mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 09:50:48 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents call tools from connected apps through the Paperclip MCP gateway > - Some tool calls take a long time: exports, builds, large searches > - The MCP progress utility lets an app report how far a call is, but Paperclip ignored it > - So the task chat showed only a spinner until the call finished, with no sign of life > - This pull request reads the app's progress and shows it on the tool's row while the call runs > - The benefit is that people can see that a long call is working, how far it is, and how long it has run ## Linked Issues or Issue Description **Subsystem affected** Connected apps (MCP gateway) and the task chat. **Problem or motivation** A long tool call from a connected MCP app shows only a spinner in the task chat. Paperclip does not send a `progressToken`, and it drops `notifications/progress` from the app. **Proposed solution** Send a `progressToken` on each `tools/call` that an agent run makes. Read the app's progress notifications from the call's response stream. Show a progress bar (or an indeterminate sweep), the latest message, and elapsed time on the running tool row. Keep the latest state so that a reload mid-call shows it. **Alternatives considered** A new transport for progress. The existing company live-events socket already carries per-run events with run read checks, so this change uses it. **Additional context** Spec: https://modelcontextprotocol.io/specification/2026-07-28/basic/utilities/progress ## What Changed - `mcp-http.ts`: `mcpHttpRequestInit` can add `_meta.progressToken`. `readMcpHttpResponse` gives each notification on the response stream to an observer before the result. The observer cannot fail or delay the call. New `mcpProgressNotificationOf` matches a notification to its token. - `tool-gateway.ts`: remote HTTP and local stdio `tools/call` from an agent run send a per-call token and forward progress to a reporter. Calls without a run send no token. - New `server/src/services/tool-call-progress.ts`: checks each update (finite, increasing, plain single-line text of at most 200 characters). It publishes a `heartbeat.run.tool_progress` live event at most every 250 ms (latest wins) and saves the latest update on the invocation at most every 1 s. Nothing is awaited by the call. A final `done` event goes out when the call ends. - DB: nullable `tool_invocations.progress` jsonb column (migration `0479`, `ADD COLUMN` only). A save never writes onto a finished call. - Live delivery: the new event follows its run like transcript output. A client gets it only for runs it follows, after the run read check, in the run's company only. - New route `GET /api/issues/:issueId/tool-call-progress` (task read check) returns the latest progress of the task's running calls, for a reload mid-call. Documented in `docs/api/issues.md`. - UI: `ToolCallProgressProvider` (one per chat) keeps the latest update per call. A running tool row subscribes and shows a bar or sweep, the message, the percent and elapsed time (design tokens, reduced motion honored). Finished rows drop it and never fetch or re-render for progress. `LiveUpdatesProvider` ignores the event for query invalidation. - `packages/kv-demo-mcp-server`: new `slow_with_progress` demo tool (`steps`, `stepMs`, `withTotal`) in its own file. - Storybook: `Tasks/Tool progress` stories (running with total, running without total, done). - Docs: new `doc/connections/MCP-PROGRESS.md`; `MCP-PROTOCOL-VERSIONS.md` no longer lists progress as unsupported. ## Verification - Red/green: on the original source, 5 of the new server tests fail (token in `_meta`, SSE with interleaved progress and result, notification matching, run-interest delivery, gateway end-to-end). With this change they pass. - `server/src/__tests__/mcp-http.test.ts` (13), `tool-call-progress.test.ts` (9: throttling, latest wins, bounded text, out-of-order drop, finish, failures never throw, company/run/tool scoping), `tool-call-progress-store.test.ts` (2, embedded Postgres: company and task scoping, no write onto a finished call), `realtime/live-event-delivery.test.ts` (run interest), `tool-gateway.test.ts` end-to-end against the real SDK kv demo server over Streamable HTTP: 6 provider updates over about 1.2 s give 3 to 7 throttled events, all for the right company, run, task and tool, the last one `done`; no event reaches another company; the invocation keeps the progress; the result is unchanged. - UI: `tool-call-progress.test.tsx` (10: name matching, row states, plain-text rendering, drop on complete, restore after reload, no fetch for finished rows). All 67 task-chat test files pass. - `packages/kv-demo-mcp-server`: 13 tests, including progress over HTTP with and without a total. - Storybook: checked the three stories in a browser. The bar fills to 40%, the sweep animates, the elapsed time ticks, and the done row shows no progress. - `pnpm verify`: see the CI checks for the final revision. ## Risks - Low. The migration adds one nullable column. - An SSE response is now bounded per message, not per stream, so handled notifications (such as progress) do not use up the result's size limit. Each message is still bounded. - Progress code runs only while a run's tool call is in flight. It adds a few bytes to the request and throttled, fire-and-forget work. Agent boot and time to first token do not change. - A row finds its call by run and tool name. If one run calls the same tool twice at the same time, both rows show the newer call's progress. - Progress from a call that became an MCP Task is not shown. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Claude Code agent with tool use and code execution. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [ ] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
788 lines
26 KiB
TypeScript
788 lines
26 KiB
TypeScript
/**
|
||
* Normalized presentation model for the chat-style task thread (the default
|
||
* task view; the classic legacy view sits behind enableClassicTaskInterface).
|
||
*
|
||
* This is a deliberately small, protocol-agnostic model that the new render
|
||
* layer consumes. Two producers feed it:
|
||
* 1. The dev harness, via synthetic fixtures (task-chat-fixtures.ts).
|
||
* 2. The live thread, via an adapter over the existing comment/run props.
|
||
*
|
||
* Every field traces to a real agent-protocol concept (ACP SessionUpdate /
|
||
* acpx AcpRuntimeEvent / TranscriptEntry). See DESIGN.md and the plan's state
|
||
* inventory for the mapping. No timing/motion values live here — those are
|
||
* CSS motion tokens in ui/src/index.css.
|
||
*/
|
||
import type { TaskChatMcpStartupFailure } from "./TaskChatRunHealthBanner";
|
||
import type {
|
||
Issue,
|
||
TaskBrowser,
|
||
IssueAttachment,
|
||
IssueCommentMetadata,
|
||
IssueCommentPresentation,
|
||
IssueDocument,
|
||
IssueDocumentSummary,
|
||
IssueWorkProduct,
|
||
DecisionHistoryItem,
|
||
ConversationTaskHandoff,
|
||
AttentionItem,
|
||
} from "@paperclipai/shared";
|
||
import type {
|
||
PaperclipQuestionResponse,
|
||
PaperclipQuestionSet,
|
||
} from "@paperclipai/adapter-utils";
|
||
|
||
export type { PaperclipQuestionResponse, PaperclipQuestionSet };
|
||
|
||
export type TaskChatProviderActivityFamily =
|
||
| "plan"
|
||
| "plan_proposal"
|
||
| "tool_execution"
|
||
| "research"
|
||
| "delegation"
|
||
| "model_identity"
|
||
| "context"
|
||
| "artifact"
|
||
| "review"
|
||
| "hook"
|
||
| "memory"
|
||
| "safety"
|
||
| "terminal"
|
||
| "wait"
|
||
| "verification"
|
||
| "provider_notice";
|
||
|
||
export type TaskChatProviderActivityStatus =
|
||
"running" | "completed" | "failed" | "interrupted" | "informational";
|
||
|
||
export interface TaskChatWorkspaceChangeFile {
|
||
path: string;
|
||
operation: "create" | "modify" | "delete" | "rename" | "mode_change";
|
||
previousPath: string | null;
|
||
additions: number | null;
|
||
deletions: number | null;
|
||
binary: boolean;
|
||
diff: string | null;
|
||
/** The patch was shortened by its producer; counts still cover all of it. */
|
||
diffTruncated?: boolean;
|
||
}
|
||
import type { IssueThreadInteraction } from "@/lib/issue-thread-interactions";
|
||
|
||
/** Who authored a thread row — the primary legibility signal. */
|
||
export type TaskChatAuthorKind = "human" | "agent" | "system";
|
||
|
||
/** ACP ToolCallStatus. */
|
||
export type TaskChatToolStatus =
|
||
"pending" | "in_progress" | "completed" | "failed" | "interrupted";
|
||
|
||
/** ACP PermissionOptionKind. */
|
||
export type TaskChatApprovalOptionKind =
|
||
"allow_once" | "allow_always" | "reject_once" | "reject_always";
|
||
|
||
/** ACP PlanEntryStatus. */
|
||
export type TaskChatPlanEntryStatus = "pending" | "in_progress" | "completed";
|
||
|
||
/** ACP PlanEntryPriority. */
|
||
export type TaskChatPlanEntryPriority = "high" | "medium" | "low";
|
||
|
||
export interface TaskChatApprovalOption {
|
||
id: string;
|
||
label: string;
|
||
kind: TaskChatApprovalOptionKind;
|
||
}
|
||
|
||
export interface TaskChatDiff {
|
||
path?: string;
|
||
added: number;
|
||
removed: number;
|
||
/** Optional unified-diff-ish lines for display only. */
|
||
lines?: TaskChatDiffLine[];
|
||
/** True when the producer bounded the patch and lines were omitted. */
|
||
truncated?: boolean;
|
||
/**
|
||
* Per-file counts reported by the producer for the whole patch. When present
|
||
* they are authoritative; `added`/`removed` are their sums, not line counts.
|
||
*/
|
||
files?: Array<{ path: string; additions: number; deletions: number; truncated: boolean }>;
|
||
}
|
||
|
||
export interface TaskChatDiffLine {
|
||
/** `file` starts the next file when one edit call changed several files. */
|
||
kind: "add" | "remove" | "context" | "hunk" | "file";
|
||
text: string;
|
||
}
|
||
|
||
export interface TaskChatTokenUsage {
|
||
/** ACP UsageUpdate.used — tokens in context. */
|
||
used: number;
|
||
/** ACP UsageUpdate.size — context window size. */
|
||
size: number;
|
||
inputTokens?: number;
|
||
outputTokens?: number;
|
||
costUsd?: number;
|
||
}
|
||
|
||
/** A human/agent/system message bubble. */
|
||
export interface TaskChatMessageItem {
|
||
origin?: "comment" | "fast_response";
|
||
/** Stable UI identity through optimistic acknowledgement; id remains canonical. */
|
||
renderKey?: string;
|
||
id: string;
|
||
kind: "message";
|
||
author: TaskChatAuthorKind;
|
||
authorName?: string;
|
||
/** Human identity comes from the company directory, matched by stored user ID. */
|
||
authorUserId?: string | null;
|
||
authorAvatarUrl?: string | null;
|
||
isCurrentUser?: boolean;
|
||
text: string;
|
||
/** Runner-authored output channel. Legacy adapters leave this unset. */
|
||
channel?: "progress" | "final" | "unknown";
|
||
/** Transport attribution for an inbound human comment. */
|
||
sourceChannel?: IssueCommentMetadata["sourceChannel"];
|
||
timestamp?: string;
|
||
/** Show a streaming cursor and suppress collapse while true. */
|
||
streaming?: boolean;
|
||
/** Optimistic local echo state (matches IssueChatComment.clientStatus). */
|
||
optimistic?: "pending" | "queued";
|
||
/** Live run this queued message is waiting behind. */
|
||
queueTargetRunId?: string | null;
|
||
/** Run that wrote this agent reply; its MCP Apps views show with the reply. */
|
||
sourceRunId?: string;
|
||
/** Non-blocking verification limitations attached to the run's durable reply. */
|
||
verificationCaveats?: Array<{
|
||
commandOrCheck: string;
|
||
reasonCode?: string | null;
|
||
detail?: string | null;
|
||
}>;
|
||
/** Assigned agent icon name (AgentIconName) for the avatar header. */
|
||
agentIcon?: string | null;
|
||
agent?: import("../AgentAvatar").AvatarAgent;
|
||
/**
|
||
* Responsible user's display name, set only when this agent comment is a
|
||
* cross-issue write (the author is not the assignee). Renders as a
|
||
* "for {user}" chip beside the author name (the open cross-task write design (attribution)).
|
||
*/
|
||
onBehalfOfUserName?: string;
|
||
/** A transient provider progress update, distinct from the durable final response. */
|
||
interstitial?: boolean;
|
||
/** Epoch ms of the message's first streamed chunk. */
|
||
atMs?: number;
|
||
/** Index of the latest transcript event folded into this logical block. */
|
||
transcriptIndex?: number;
|
||
/**
|
||
* The settled run turn "attached" to this bubble (round 9): when the run's
|
||
* final reply lands, the live parent row transforms into the "Worked · …"
|
||
* summary rendered on this bubble's always-visible timestamp line —
|
||
* "2:34 PM · ✓ Worked · 38s · 3 tools" — instead of a standalone row.
|
||
* Expanding still nests the tool history beneath the bubble.
|
||
*/
|
||
attachedTurn?: TaskChatTurnItem;
|
||
/**
|
||
* Structured system-notice fields (PAP-443), carried only for
|
||
* author === "system": either system attribution or an explicit
|
||
* system_notice presentation routes the comment here. The comment's
|
||
* server-authored presentation hints and metadata sections drive the
|
||
* collapsed one-line row + expandable detail.
|
||
*/
|
||
presentation?: IssueCommentPresentation | null;
|
||
metadata?: IssueCommentMetadata | null;
|
||
chatMessage?: IssueCommentMetadata["chatMessage"];
|
||
/** Agent that owns the source run, used to build run-detail links in metadata rows. */
|
||
runAgentId?: string | null;
|
||
/** Raw comment timestamp (ISO) — the collapsed system row shows relative time. */
|
||
createdAtIso?: string;
|
||
}
|
||
|
||
/** Collapsed chain-of-thought (ACP agent_thought_chunk). */
|
||
export interface TaskChatThinkingItem {
|
||
id: string;
|
||
kind: "thinking";
|
||
lines: string[];
|
||
streaming?: boolean;
|
||
/** When true, render collapsed ("Worked for N") with an expand affordance. */
|
||
collapsed?: boolean;
|
||
/** Human-readable elapsed label for the collapsed header. */
|
||
summaryLabel?: string;
|
||
/** Provider-emitted reasoning surface; never synthesized by the UI. */
|
||
channel?: "summary" | "detail" | "unknown";
|
||
/** A real provider reasoning lifecycle with no provider-authored text. */
|
||
lifecycleOnly?: boolean;
|
||
/** Index of the latest transcript event folded into this logical block. */
|
||
transcriptIndex?: number;
|
||
}
|
||
|
||
/** An automatic approval review folded onto the tool row it approved. */
|
||
export interface TaskChatAutoReview {
|
||
decision: "allowed";
|
||
riskLevel?: string;
|
||
userConsent?: string;
|
||
rationale?: string;
|
||
}
|
||
|
||
/** A tool invocation row (ACP tool_call / tool_call_update). */
|
||
export interface TaskChatToolItem {
|
||
id: string;
|
||
kind: "tool";
|
||
name: string;
|
||
/** Raw ACP tool name pre-collapse ("mcp__server__tool") for taxonomy lookup. */
|
||
rawName?: string;
|
||
/** The app tool a wrapper call runs (`paperclip_call_assigned_tool`'s `name`), for its progress. */
|
||
appToolName?: string;
|
||
/** ACP ToolKind. */
|
||
toolKind?: string;
|
||
status: TaskChatToolStatus;
|
||
/**
|
||
* Summarized primary argument (file path, command, pattern…) rendered mono
|
||
* next to the tool name — the v7 toolrow "target".
|
||
*/
|
||
target?: string;
|
||
/**
|
||
* Task the call is about, when its input named one by UUID. Rows show the
|
||
* task's identifier for it; the UUID itself is never rendered.
|
||
*/
|
||
taskRefId?: string;
|
||
detail?: string;
|
||
diff?: TaskChatDiff;
|
||
/** Resolved permission decision badge, when one applied. */
|
||
decision?: "allowed" | "rejected";
|
||
/** Automatic approval review that let this call run. */
|
||
autoReview?: TaskChatAutoReview;
|
||
/** Canonical operation (read, search, list, execute, edit) when known. */
|
||
operation?: string;
|
||
/** Provider's short description of the call, such as Claude's Bash description. */
|
||
description?: string;
|
||
/** Process exit code, when the harness reported one. */
|
||
exitCode?: number | null;
|
||
/** Wall-clock tool duration in milliseconds, when known. */
|
||
durationMs?: number | null;
|
||
/** Why the harness or a policy refused to run the tool. */
|
||
blockedReason?: string;
|
||
/** Execution id of the delegation (subagent) that made this call. */
|
||
parentToolUseId?: string;
|
||
}
|
||
|
||
/**
|
||
* A lifecycle state rendered as a status affordance — never a bubble.
|
||
* Covers both LIVE (running/working) and Tier-B (awaiting_approval,
|
||
* interrupted, refused, truncated) states.
|
||
*/
|
||
export interface TaskChatStatusItem {
|
||
id: string;
|
||
kind: "status";
|
||
status:
|
||
| "running"
|
||
| "working"
|
||
| "awaiting_approval"
|
||
| "interrupted"
|
||
| "refused"
|
||
| "truncated";
|
||
label: string;
|
||
detail?: string;
|
||
/** Raw tool name of the in-flight tail tool_call (drives the pill's icon). */
|
||
toolName?: string;
|
||
/**
|
||
* Flattened plain text of the interstitial update currently streaming
|
||
* (PAP-361, round 9): it renders in a dedicated single-line row directly
|
||
* above the status line — a slot PERMANENTLY RESERVED while the turn is
|
||
* live, so the layout above never jumps — inside a one-line viewport
|
||
* showing the streaming tail line; the gerund rotation below runs
|
||
* uninterrupted. When the message finishes the pill HOLDS the text as a
|
||
* static ellipsized line until the next update supersedes it or the turn
|
||
* ends (PAP-368) — nothing persists in the settled thread.
|
||
*/
|
||
selfTalk?: string;
|
||
elapsedMs?: number;
|
||
/** Run start epoch ms; live states tick their own elapsed from this. */
|
||
startedAtMs?: number;
|
||
tokens?: TaskChatTokenUsage;
|
||
/** Present for awaiting_approval (ACP RequestPermissionRequest). */
|
||
approval?: { toolName: string; options: TaskChatApprovalOption[] };
|
||
}
|
||
|
||
/** A lifecycle divider (session start, interruption, turn boundary). */
|
||
export interface TaskChatMarkerItem {
|
||
id: string;
|
||
kind: "marker";
|
||
variant: "session_start" | "interrupted" | "turn_boundary" | "context_compacted";
|
||
label: string;
|
||
detail?: string;
|
||
/** False when the recorded run cannot be retried, even after the chat continues. */
|
||
retryable?: boolean;
|
||
/** Renders the marker as a quiet disclosure row with detail beneath it. */
|
||
collapsible?: boolean;
|
||
/** Expected cancellation is neutral; unexpected failures remain destructive. */
|
||
tone?: "neutral" | "error";
|
||
runId?: string;
|
||
createdAtIso?: string;
|
||
runHref?: string;
|
||
planHref?: string;
|
||
/** An actionable credential denial is always expanded in the task conversation. */
|
||
credentialAccess?: {
|
||
agentName: string;
|
||
credentialName?: string;
|
||
deniedUser: string;
|
||
settingsHref: string;
|
||
};
|
||
}
|
||
|
||
/** A second-tier live token/cost readout (ACP UsageUpdate). */
|
||
export interface TaskChatUsageItem {
|
||
id: string;
|
||
kind: "usage";
|
||
usage: TaskChatTokenUsage;
|
||
/** Present when the measurement is not scoped to the current run. */
|
||
label?: string;
|
||
detail?: string;
|
||
}
|
||
|
||
export interface TaskChatActivityPhaseItem {
|
||
id: string;
|
||
kind: "activity_phase";
|
||
/** Historical assistant update that introduced this phase. */
|
||
interstitial?: TaskChatMessageItem;
|
||
/** Chronological tool/usage rows owned exclusively by this phase. */
|
||
items: Array<
|
||
| TaskChatToolItem
|
||
| TaskChatUsageItem
|
||
| TaskChatThinkingItem
|
||
| TaskChatMarkerItem
|
||
| TaskChatProtocolItem
|
||
>;
|
||
/** Deterministic, taxonomy-based summary (for example "Read 3 files, ran 1 command"). */
|
||
summary: string;
|
||
/** The tail phase of an in-flight run stays foregrounded. */
|
||
active: boolean;
|
||
}
|
||
|
||
/**
|
||
* The task description rendered as the requester's first chat bubble
|
||
* (PAP-375). A placeholder kind only — the host supplies the render
|
||
* (TaskChatThread binds TaskChatDescriptionBubble to the live issue), mirroring
|
||
* how interaction items defer to renderInteraction. Always prepended AFTER
|
||
* thread assembly, so no backbone entry or settled turn can sort above it.
|
||
*/
|
||
export interface TaskChatBriefItem {
|
||
id: string;
|
||
kind: "brief";
|
||
}
|
||
|
||
/**
|
||
* An issue-thread interaction (plan confirmation, question card, suggested
|
||
* tasks…) interleaved chronologically into the thread. The payload is the
|
||
* existing control-plane IssueThreadInteraction — the render layer wraps the
|
||
* shared IssueThreadInteractionCard rather than re-modeling the five kinds.
|
||
*/
|
||
export interface TaskChatInteractionItem {
|
||
id: string;
|
||
kind: "interaction";
|
||
interaction: IssueThreadInteraction;
|
||
}
|
||
|
||
/** A canonical, atomically saved Plan document interleaved into the thread. */
|
||
export interface TaskChatPlanDocumentItem {
|
||
id: string;
|
||
kind: "plan_document";
|
||
document: IssueDocument;
|
||
/** Distinguishes a proven semantic write boundary from lossless fallback. */
|
||
placement?: "write_boundary" | "fallback";
|
||
}
|
||
|
||
export interface TaskChatProtocolDetail {
|
||
label: string;
|
||
value: string;
|
||
mono?: boolean;
|
||
}
|
||
|
||
export interface TaskChatProtocolStep {
|
||
id: string;
|
||
label: string;
|
||
status: "pending" | "in_progress" | "completed" | "blocked" | "failed";
|
||
}
|
||
|
||
export interface TaskChatProtocolLink {
|
||
label: string;
|
||
href: string;
|
||
description?: string;
|
||
}
|
||
|
||
export interface TaskChatProtocolChild {
|
||
id: string;
|
||
title: string;
|
||
status: string;
|
||
metadata?: string;
|
||
summary?: string;
|
||
/** Subagent type the provider dispatched (`Explore`, `general-purpose`). */
|
||
role?: string;
|
||
model?: string;
|
||
/** Latest provider progress summary while the child runs. */
|
||
progress?: string;
|
||
prompt?: string;
|
||
result?: string;
|
||
}
|
||
|
||
export interface TaskChatProviderActivityItem {
|
||
id: string;
|
||
kind: "protocol";
|
||
surface: "provider_activity";
|
||
family: TaskChatProviderActivityFamily;
|
||
eventType: string;
|
||
status: TaskChatProviderActivityStatus;
|
||
title: string;
|
||
summary?: string;
|
||
details: TaskChatProtocolDetail[];
|
||
steps: TaskChatProtocolStep[];
|
||
links: TaskChatProtocolLink[];
|
||
children: TaskChatProtocolChild[];
|
||
output?: string;
|
||
outputTruncated?: boolean;
|
||
/** Index of the latest provider event coalesced into this activity. */
|
||
transcriptIndex?: number;
|
||
/** Provider activity identity, e.g. the delegation id for a subagent. */
|
||
activityId?: string;
|
||
/** Delegation (subagent) execution that made this tool call. */
|
||
parentToolUseId?: string;
|
||
/** First and latest provider event times coalesced into this activity. */
|
||
startedAtMs?: number;
|
||
updatedAtMs?: number;
|
||
/** A retry status notice the turn has moved past. */
|
||
resolved?: boolean;
|
||
/** When the provider first reported this activity (ISO timestamp). */
|
||
startedAt?: string;
|
||
/** Automatic approval review that let this tool execution run. */
|
||
autoReview?: TaskChatAutoReview;
|
||
}
|
||
|
||
export type TaskChatSubagentStatus = "running" | "completed" | "failed" | "cancelled";
|
||
|
||
/**
|
||
* A delegated subagent (Claude Agent/Task call, Codex or Cursor child) with
|
||
* the tool rows it made, nested under the parent turn.
|
||
*/
|
||
export interface TaskChatSubagent {
|
||
id: string;
|
||
/** Subagent type the provider dispatched, e.g. `Explore` or `general-purpose`. */
|
||
agentType: string;
|
||
/** Short task description the parent wrote for the child. */
|
||
description: string;
|
||
prompt?: string;
|
||
model?: string;
|
||
status: TaskChatSubagentStatus;
|
||
/** Latest provider progress summary (Claude `agentProgressSummaries`). */
|
||
progressSummary?: string;
|
||
startedAtMs?: number | null;
|
||
finishedAtMs?: number | null;
|
||
/** Child tool/thinking rows, in order. */
|
||
activity: TaskChatActivityPhaseItem["items"];
|
||
result?: string;
|
||
}
|
||
|
||
/** Subagents dispatched together; one renders as a card, several as a tree. */
|
||
export interface TaskChatSubagentGroupItem {
|
||
id: string;
|
||
kind: "subagent_group";
|
||
subagents: TaskChatSubagent[];
|
||
}
|
||
|
||
export interface TaskChatWorkspaceChangeItem {
|
||
id: string;
|
||
kind: "protocol";
|
||
surface: "workspace_change";
|
||
changeSetId: string;
|
||
revision: number;
|
||
source: "harness_reported" | "runner_verified";
|
||
complete: boolean;
|
||
files: TaskChatWorkspaceChangeFile[];
|
||
totals: { files: number; additions: number | null; deletions: number | null };
|
||
patchArtifactRef: string | null;
|
||
}
|
||
|
||
export interface TaskChatWorkspaceFileItem {
|
||
id: string;
|
||
kind: "protocol";
|
||
surface: "workspace_file";
|
||
referenceId: string;
|
||
source: "harness_reported" | "runner_verified";
|
||
path: string;
|
||
displayName: string;
|
||
mediaType: string | null;
|
||
presentation: "document" | "code" | "image" | "generic";
|
||
line: number | null;
|
||
preview: string | null;
|
||
previewTruncated: boolean;
|
||
}
|
||
|
||
export interface TaskChatRuntimeRequestItem {
|
||
id: string;
|
||
kind: "protocol";
|
||
surface: "runtime_request";
|
||
runId: string;
|
||
requestId: string;
|
||
requestKind:
|
||
| "runtime"
|
||
| "command_approval"
|
||
| "file_approval"
|
||
| "permission_approval"
|
||
| "user_input"
|
||
| "elicitation"
|
||
| null;
|
||
turnId: string | null;
|
||
requestType: "permission" | "input";
|
||
status: "pending" | "resolved" | "expired" | "cancelled";
|
||
prompt: string;
|
||
choices: Array<{ key: string; label: string }>;
|
||
fields: Array<{ name: string; label: string; placeholder: string | null }>;
|
||
questionSet?: PaperclipQuestionSet | null;
|
||
resolvedAction?: string | null;
|
||
response?: PaperclipQuestionResponse | null;
|
||
}
|
||
|
||
export type TaskChatRuntimeRequestDecision =
|
||
| { action: "accept" | "accept_for_session" | "decline" | "cancel" }
|
||
| { action: "submit"; values: Record<string, string> }
|
||
| { action: "submit"; response: PaperclipQuestionResponse };
|
||
|
||
export interface TaskChatRunResultItem {
|
||
id: string;
|
||
kind: "protocol";
|
||
surface: "run_result";
|
||
disposition: "done" | "blocked" | "needs_review" | "yielded";
|
||
summary: string;
|
||
objectiveSatisfied: boolean | null;
|
||
verification: Array<{
|
||
commandOrCheck: string;
|
||
status: "passed" | "failed" | "not_run";
|
||
detail?: string;
|
||
artifactRef?: string;
|
||
}>;
|
||
remainingWork: Array<{ description: string; blocksCompletion: boolean }>;
|
||
blocker: {
|
||
reasonCode: string;
|
||
unblockAction: string;
|
||
scope: "current_track" | "task_wide";
|
||
} | null;
|
||
artifacts: Array<{ kind: string; ref: string; title?: string }>;
|
||
/** Proven by accepted native result and same-run successful terminal events. */
|
||
acceptedResponseWake?: { runId: string; sourceEventId: string };
|
||
}
|
||
|
||
export interface TaskChatRunTerminalItem {
|
||
id: string;
|
||
kind: "protocol";
|
||
surface: "run_terminal";
|
||
turnState: "completed" | "failed" | "interrupted" | "cancelled";
|
||
runState: "succeeded" | "failed" | "cancelled";
|
||
disposition: "done" | "blocked" | "needs_review" | "yielded";
|
||
stopReason?: string;
|
||
}
|
||
|
||
export interface TaskChatMaterializedResourceItem {
|
||
id: string;
|
||
kind: "protocol";
|
||
surface: "resource";
|
||
resourceKind: "document" | "deliverable" | "attachment";
|
||
title: string;
|
||
subtitle: string;
|
||
href: string | null;
|
||
timestamp?: string;
|
||
document?: IssueDocumentSummary;
|
||
workProduct?: IssueWorkProduct;
|
||
attachment?: IssueAttachment;
|
||
imageItems?: TaskChatMaterializedResourceItem[];
|
||
}
|
||
|
||
export type TaskChatProtocolItem =
|
||
| TaskChatProviderActivityItem
|
||
| TaskChatWorkspaceChangeItem
|
||
| TaskChatWorkspaceFileItem
|
||
| TaskChatRuntimeRequestItem
|
||
| TaskChatRunResultItem
|
||
| TaskChatRunTerminalItem
|
||
| TaskChatMaterializedResourceItem;
|
||
|
||
/** Items a turn can group — everything except another turn. */
|
||
export type TaskChatTurnChildItem =
|
||
| TaskChatSubagentGroupItem
|
||
| TaskChatMessageItem
|
||
| TaskChatThinkingItem
|
||
| TaskChatToolItem
|
||
| TaskChatStatusItem
|
||
| TaskChatMarkerItem
|
||
| TaskChatUsageItem
|
||
| TaskChatActivityPhaseItem
|
||
| TaskChatPlanDocumentItem
|
||
| TaskChatProtocolItem;
|
||
|
||
/**
|
||
* One agent turn's activity (thinking/tools/diffs) grouped so a finished turn
|
||
* can fold into a one-line expandable summary ("✓ Worked · 38s · 3 tools ·
|
||
* +34 −3"). A live turn carrying `liveStatus` renders as a single expandable
|
||
* parent row headed by that status line (gerund/tool-state + elapsed +
|
||
* tokens); expanding nests the chronological activity underneath, and on
|
||
* settle the header morphs in place into the summary. The live → settled
|
||
* fold animates (~ --motion-turn-fold), while turns that load already-settled
|
||
* collapse instantly.
|
||
*/
|
||
export interface TaskChatTurnItem {
|
||
id: string;
|
||
kind: "turn";
|
||
items: TaskChatTurnChildItem[];
|
||
settled: boolean;
|
||
/** Superseded execution status is omitted; activity remains inspectable. */
|
||
historical?: boolean;
|
||
/** Agent identity retained when a live runner turn becomes durable history. */
|
||
agentName?: string;
|
||
agentIcon?: string | null;
|
||
agent?: import("../AgentAvatar").AvatarAgent;
|
||
/**
|
||
* The in-flight run's status line, hoisted to be THE turn's single visible
|
||
* row while collapsed (PAP-354 parent-row model). Absent once settled.
|
||
*/
|
||
liveStatus?: TaskChatStatusItem;
|
||
/** Animate the fold when settling (false = collapse instantly, e.g. history). */
|
||
animateFold?: boolean;
|
||
/** New-runner turns keep Worked/Stopped fixed above their ordered timeline. */
|
||
standaloneHeader?: boolean;
|
||
/** This segment resumes the same native run after a steering input. */
|
||
continuedAfterSteering?: boolean;
|
||
/** Durable response shown after the ordered Paperclip Runner timeline. */
|
||
finalResponse?: TaskChatMessageItem;
|
||
/** MCP servers the harness could not start for this run (run-health banner). */
|
||
mcpStartupFailures?: TaskChatMcpStartupFailure[];
|
||
summary: {
|
||
/** e.g. "38s" — omitted when unknown. */
|
||
durationLabel?: string;
|
||
toolCount: number;
|
||
added: number;
|
||
removed: number;
|
||
/** e.g. "12.3k tokens" — omitted when unknown. */
|
||
tokensLabel?: string;
|
||
/** Failed/interrupted turns get a ✗ affordance instead of ✓. */
|
||
failed?: boolean;
|
||
};
|
||
}
|
||
|
||
export interface TaskChatTaskCreatedItem {
|
||
id: string;
|
||
kind: "task_created";
|
||
task: Pick<Issue, "id" | "identifier" | "title" | "status" | "displayStatus" | "externalConversationState" | "blockerAttention">;
|
||
isSubtask: boolean;
|
||
timestamp: string;
|
||
}
|
||
|
||
export interface TaskChatProjectCreatedItem {
|
||
id: string;
|
||
kind: "project_created";
|
||
projectId: string;
|
||
name: string;
|
||
description?: string | null;
|
||
repositories: { id: string; name: string; url: string }[];
|
||
timestamp: string;
|
||
}
|
||
|
||
export interface TaskChatSkillCreatedItem {
|
||
id: string;
|
||
kind: "skill_created";
|
||
skillId: string;
|
||
name: string;
|
||
description?: string | null;
|
||
slug?: string | null;
|
||
versionId?: string | null;
|
||
timestamp: string;
|
||
}
|
||
|
||
export interface TaskChatBrowserItem {
|
||
id: string;
|
||
kind: "browser";
|
||
browser: TaskBrowser;
|
||
label: string;
|
||
timestamp: string;
|
||
}
|
||
|
||
export type TaskChatItem =
|
||
| { id: string; kind: "pending_question"; question: AttentionItem }
|
||
| { id: string; kind: "decision_receipt"; receipt: DecisionHistoryItem }
|
||
| { id: string; kind: "task_handoff"; handoff: ConversationTaskHandoff; animateEntry?: boolean }
|
||
| TaskChatBrowserItem
|
||
| TaskChatTaskCreatedItem
|
||
| TaskChatProjectCreatedItem
|
||
| TaskChatSkillCreatedItem
|
||
| TaskChatMessageItem
|
||
| TaskChatThinkingItem
|
||
| TaskChatToolItem
|
||
| TaskChatStatusItem
|
||
| TaskChatMarkerItem
|
||
| TaskChatUsageItem
|
||
| TaskChatActivityPhaseItem
|
||
| TaskChatInteractionItem
|
||
| TaskChatPlanDocumentItem
|
||
| TaskChatTurnItem
|
||
| TaskChatBriefItem
|
||
| TaskChatSubagentGroupItem
|
||
| TaskChatProtocolItem;
|
||
|
||
/** Latest lifecycle state wins for each request; terminal entries suppress stale pending cards. */
|
||
export function latestPendingRuntimeRequest(
|
||
items: readonly TaskChatItem[],
|
||
): TaskChatRuntimeRequestItem | null {
|
||
const seen = new Set<string>();
|
||
for (let index = items.length - 1; index >= 0; index -= 1) {
|
||
const item = items[index];
|
||
if (item.kind !== "protocol" || item.surface !== "runtime_request")
|
||
continue;
|
||
const key = `${item.runId}:${item.requestId}`;
|
||
if (seen.has(key)) continue;
|
||
seen.add(key);
|
||
if (item.status === "pending") return item;
|
||
}
|
||
return null;
|
||
}
|
||
|
||
/** A protocol denial is the explicit negative path, so a second Skip action is redundant. */
|
||
export function runtimeRequestReplacesComposerSkip(
|
||
item: TaskChatRuntimeRequestItem,
|
||
): boolean {
|
||
return item.choices.some((choice) => {
|
||
const key = choice.key.trim().toLowerCase();
|
||
const label = choice.label.trim().toLowerCase();
|
||
return (
|
||
["deny", "decline", "reject"].includes(key) ||
|
||
/^(deny|decline|reject)(\b|\s)/.test(label)
|
||
);
|
||
});
|
||
}
|
||
|
||
/** One latest lifecycle entry per request, in the order each request began. */
|
||
export function latestRuntimeRequests(
|
||
items: readonly TaskChatItem[],
|
||
): TaskChatRuntimeRequestItem[] {
|
||
const latest = new Map<
|
||
string,
|
||
{ order: number; item: TaskChatRuntimeRequestItem }
|
||
>();
|
||
for (const [order, item] of items.entries()) {
|
||
if (item.kind !== "protocol" || item.surface !== "runtime_request")
|
||
continue;
|
||
const key = `${item.runId}:${item.requestId}`;
|
||
const existing = latest.get(key);
|
||
latest.set(key, { order: existing?.order ?? order, item });
|
||
}
|
||
return [...latest.values()]
|
||
.sort((left, right) => left.order - right.order)
|
||
.map(({ item }) => item);
|
||
}
|
||
|
||
/** A structured plan entry (ACP PlanEntry) for the Plans tab. */
|
||
export interface TaskChatPlanEntry {
|
||
id: string;
|
||
content: string;
|
||
status: TaskChatPlanEntryStatus;
|
||
priority: TaskChatPlanEntryPriority;
|
||
}
|
||
|
||
export interface TaskChatPlan {
|
||
/** Revision index (1-based); higher supersedes. */
|
||
revision: number;
|
||
entries: TaskChatPlanEntry[];
|
||
updatedAt?: string;
|
||
}
|