mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 04:21:24 +01:00
## 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>
786 lines
26 KiB
TypeScript
786 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;
|
||
/** 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;
|
||
}
|