Files
PaperClipAI/ui/src/components/task-chat/task-chat-model.ts
T
DottaandClaude Opus 5.5 a726dce4f0 feat(mcp): show live progress for long connected-app tool calls in the task chat (#21449)
## 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>
2026-11-13 20:14:22 -06:00

788 lines
26 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* 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;
}