Files
PaperClipAI/ui/src/components/task-chat/task-chat-model.ts
T
DottaandClaude Opus 5.5 8ff45c0fa9 feat(connections): render MCP Apps views in the task chat, starting with Circleback (#21119)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agents reach external apps through MCP connections. Paperclip
records each call and shows it as a tool row in the task chat.
> - MCP Apps (SEP-1865, extension `io.modelcontextprotocol/ui`, spec
2026-01-26) lets an MCP server attach an interactive `ui://` view to a
tool. Claude, Claude Code and VS Code render these views in chat.
Circleback uses them to show meeting cards.
> - Paperclip dropped the tool's `_meta.ui` at discovery and the
result's `_meta` at call time. Its gateway reported MCP App UI as
"unsupported". Circleback was reachable only through Composio, whose
toolkit has no `Display*` tools.
> - This pull request makes Paperclip an MCP Apps host. It also adds
Circleback as a native catalog connection.
> - The benefit is that a Circleback recap in a task shows the same
meeting cards as in Claude, and any other MCP server with views works
the same way.

## Linked Issues or Issue Description

**Subsystem affected**
Connections and apps (remote MCP gateway) and the task chat.

**Problem or motivation**
An agent that uses Circleback in Paperclip can only return text. The
same tools in Claude Code show interactive meeting cards
(`DisplayMeetings`). Paperclip discards the MCP Apps metadata, so it
cannot show them.

**Proposed solution**
Paperclip implements the host side of MCP Apps end to end. It keeps the
tool's view declaration and records each call that has a view. It
renders the view under the tool row in a sandboxed iframe that uses the
MCP Apps postMessage protocol. Circleback becomes a native catalog
connection, so its `Display*` tools are available.

**Alternatives considered**
Composio's `circleback_mcp` toolkit has 11 read tools and no `Display*`
tools, and its meta-tools return plain JSON, so it cannot carry views.
The spec's double-iframe sandbox proxy on a separate origin needs a
second origin that Paperclip does not have. A single opaque-origin
`srcdoc` frame with an injected CSP gives the same isolation.

**Roadmap alignment**
This extends the existing Apps catalog and MCP gateway. It adds no new
integration substrate (decision D4 in doc/connections/README.md).

**Additional context**
The standard, the design and the testing plan are in
`doc/connections/MCP-APPS.md`.

## What Changed

- **Shared:** `packages/shared/src/mcp-apps.ts` adds MCP Apps types,
`_meta.ui` and resource parsing (current and legacy keys), and a CSP
builder that keeps only well-formed `https` origins.
- **DB:** migration `0471` (`online_compatible`) adds
`tool_catalog_entries.ui_meta` and a new `tool_mcp_app_views` table.
- **Server, catalog:** discovery keeps each tool's `_meta.ui`. It is not
part of the version hash, so a view never quarantines a reviewed tool.
- **Server, gateway:**
- Paperclip advertises the MCP Apps client capability when it
initializes a session.
  - App-only tools (`visibility: ["app"]`) are hidden from agents.
- The result `_meta` is kept for the view and is not sent to the agent.
- Each successful call to a tool with a view records a view row.
Recording is best effort.
- The gateway's `initialize` now reports `paperclip/mcp-app-ui:
host_rendered`.
- The context protocol (`resources/read`) now uses the injected test
transport, like the other remote calls.
- **Server, routes:** `server/src/routes/mcp-apps.ts`
- `GET /api/issues/:issueId/mcp-app-views` lists a task's views. It
needs task read access.
- `GET /api/issues/:issueId/mcp-app-views/:viewId` returns the view
document, read live through the agent's connection.
- `POST /api/issues/:issueId/mcp-app-views/:viewId/tool-calls` runs the
view's `tools/call`. It needs `tools:use` and reaches only tools of the
same connection that allow `app`. It uses the connection test-call path,
so policy, Ask first and audit apply.
- **UI:** `ui/src/components/mcp-app/`
- The host protocol: `ui/initialize` with theme, style variables and
size limits; tool-input; tool-result; size-changed; `tools/call`;
`ui/open-link` (http and https only); teardown.
- An opaque-origin iframe (`allow-scripts`, never `allow-same-origin`)
with the CSP placed before the view's markup.
- The views of a run render with that run's reply, in the live turn and
in settled history. They are keyed by the reply's run, so history needs
no transcript.
- **Circleback:** a native catalog app (`mcp-oauth`, DCR, `user
user:write`) with:
  - the official logo;
- a reviewed risk classifier (Share* tools are writes, Delete* tools are
destructive, Display* tools are reads);
  - warnings in the sign-in step;
  - `doc/connections/CIRCLEBACK.md`.
  
Search now prefers a native app over an aggregator listing named "X
MCP".
- **Storybook:** `Tasks/MCP App views` shows the tool row with its view,
the ready state (Refresh calls a tool), loading, view unavailable, and a
tool call that needs approval.

## Verification

- `pnpm exec vitest run packages/shared/src/mcp-apps.test.ts
ui/src/components/mcp-app/`: 19 passed.
- `pnpm exec vitest run server/src/__tests__/mcp-apps.test.ts`: 3
passed, on embedded Postgres. The test connects Circleback through the
catalog with DCR OAuth against a fake Circleback MCP server. It checks:
  - `ui_meta` is stored;
  - an app-only tool is hidden from the agent;
- an agent call records one view with arguments, structured content and
`_meta`;
  - a call without a view records nothing;
  - the routes serve the view's HTML and CSP;
  - the view's tool call works and a model-only tool is refused;
  - another task, another company and an agent actor are refused.
- Circleback connector: 13 focused files, 645 tests passed. These are
the app definitions, search, aggregator fallback, connection intents,
tool policy, `AppsConnect` and `Browse`.
- Typecheck passed for `@paperclipai/shared`, `@paperclipai/server` and
`@paperclipai/ui`. `node scripts/storybook-catalog.mjs` and the
migration compatibility check also passed.
- Storybook check in the browser:
- In both themes, the view runs the handshake, renders the meeting cards
from `structuredContent`, picks up the theme variables, and resizes to
its content.
  - Refresh sends `tools/call` and re-renders the cards.
- **Live Circleback end to end** on a local instance, with a real
Circleback account:
- Connected through the catalog entry with Circleback's dynamic client
registration and OAuth.
  - Discovery stored the real view declarations:
    - `DisplayMeetings` uses `ui://circleback/meetings.v2.html`.
    - `DisplayActionItems` and `DisplayCalendarEvents` also have views.
- `ListAssigneeOptions` and `SetCalendarEventRecording` are app-only
helpers with no view. They are hidden from agents.
  - A `claude_local` agent called `DisplayMeetings` on two tasks.
- The real 3.5 MB Circleback view rendered the meeting cards with the
agent's reply.
- Clicking a card opened that meeting in Circleback through
`ui/open-link`.
- The live run found two bugs, both fixed in this PR, each with a
regression test:
    - The 1 MB tool-result limit blocked the view document.
    - Views were hidden inside the folded tool history.

## Risks

- **New migration:** a new table and a nullable column. It is
`online_compatible`.
- **Existing connections:** tools get `ui_meta` on the next catalog
refresh. Until then, no view shows and the tool row is unchanged.
- **Untrusted provider HTML:** the view runs as provider HTML in an
opaque-origin sandbox. It cannot reach Paperclip's session, DOM or API.
Its network access is limited to the origins its server declared. A
view's tool calls use the viewer's permissions and the normal policy and
Ask-first path.
- **Agent tool lists:** app-only tools are removed from them. No current
provider marks tools app-only, so no listed tool disappears.
- **Search:** the change that prefers a native app over an "X MCP"
aggregator listing affects every app.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and
subagents (one subagent authored the Circleback catalog connector).

## 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-12 13:28:05 -06:00

786 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;
/** 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;
}