Files
PaperClipAI/ui/src/components/task-chat/TaskChatRunnerTurn.tsx
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

329 lines
13 KiB
TypeScript

import { groupImageResources } from "./image-resources";
import { McpAppTurnViews, mcpAppRunRefreshKey } from "@/components/mcp-app/McpAppTurnViews";
import { useRef, type ReactNode } from "react";
import type { ExecutionProjection } from "@paperclipai/shared";
import { useSecondTick } from "@/hooks/useSecondTick";
import { cn } from "@/lib/utils";
import type {
TaskChatItem,
TaskChatMessageItem,
TaskChatRuntimeRequestDecision,
TaskChatRuntimeRequestItem,
} from "./task-chat-model";
import { TaskChatAgentIdentity, TaskChatBubble } from "./TaskChatBubble";
import { TaskChatBubbleActions } from "./TaskChatBubbleActions";
import { formatTaskChatTimestamp } from "./task-chat-adapter";
import { TaskChatRunnerActivityGroup } from "./TaskChatRunnerActivityGroup";
import { TaskChatSubagentTree } from "./TaskChatSubagentCard";
import { TaskChatRunHealthBanner, partitionRunHealthItems } from "./TaskChatRunHealthBanner";
import { TaskChatProtocolCard } from "./TaskChatProtocolCard";
import { TaskChatPlanPreviewCard } from "./TaskChatPlanPreviewCard";
import { TaskChatMarker } from "./TaskChatMarker";
import { TaskChatShimmerScope, useTaskChatShimmer } from "./TaskChatShimmer";
import {
buildTurnTimelineRows,
isTerminalRunStatus,
omitProgressRepeatedByResponse,
paperclipRunnerFinalResponse,
paperclipRunnerTimelineItems,
} from "./transcript-adapter";
function currentActivityStatusItems(
items: readonly TaskChatItem[],
): readonly TaskChatItem[] {
let boundaryIndex = -1;
for (let index = items.length - 1; index >= 0; index -= 1) {
const item = items[index];
if (
item.kind === "message" ||
item.kind === "plan_document" ||
(item.kind === "protocol" &&
(item.surface === "runtime_request" ||
item.surface === "run_result" ||
item.surface === "run_terminal"))
) {
boundaryIndex = index;
break;
}
}
return items.slice(boundaryIndex + 1);
}
function formatCompactDuration(ms: number | null): string | null {
if (ms == null || !Number.isFinite(ms)) return null;
const totalSeconds = Math.max(0, Math.floor(ms / 1000));
if (totalSeconds < 60) return `${totalSeconds}s`;
const minutes = Math.floor(totalSeconds / 60);
const seconds = totalSeconds % 60;
return seconds === 0 ? `${minutes}m` : `${minutes}m ${seconds}s`;
}
function terminalStatusFailed(status: string): boolean {
return (
status === "failed" ||
status === "cancelled" ||
status === "timed_out" ||
status === "interrupted"
);
}
function RunnerTurnStatus({
status,
startedAtMs,
finishedAtMs,
continuedAfterSteering = false,
waitingLabel,
}: {
status: string;
startedAtMs: number | null;
finishedAtMs?: number | null;
continuedAfterSteering?: boolean;
waitingLabel?: string | null;
}) {
const terminal = isTerminalRunStatus(status);
useSecondTick(!terminal && startedAtMs != null);
const elapsedMs =
startedAtMs == null
? null
: Math.max(
0,
(terminal ? (finishedAtMs ?? Date.now()) : Date.now()) - startedAtMs,
);
const elapsed = formatCompactDuration(elapsedMs);
const failed = terminalStatusFailed(status);
const label = terminal ? (failed ? "Stopped" : "Worked") : waitingLabel ?? "Working";
const suffix = terminal
? elapsed ? ` ${failed ? "after" : "for"} ${elapsed}` : ""
: elapsed ? `${waitingLabel ? " · " : " for "}${elapsed}` : "";
return (
<span
className="min-w-0 truncate text-sm font-normal text-muted-foreground"
data-testid="task-chat-turn-status-header"
data-turn-position="identity"
aria-live="polite"
aria-atomic="true"
>
{continuedAfterSteering ? <span data-conversation-meta="">Continued after steering · </span> : null}
{label}<span data-conversation-meta="">{suffix}</span>
</span>
);
}
function RunnerCurrentActivityTail({ status, waitingLabel }: { status: string; waitingLabel?: string | null }) {
const shimmer = useTaskChatShimmer("working");
if (isTerminalRunStatus(status)) return null;
return <div className="mt-2 flex min-h-8 min-w-0 items-center gap-2 px-1 py-1 text-xs text-muted-foreground" data-testid="task-chat-current-activity" data-turn-position="tail">
<span className={cn(!waitingLabel && shimmer && "shimmer-text shimmer-text-muted")} aria-live="polite" data-testid="task-chat-current-activity-label">{waitingLabel ?? "Thinking"}</span>
</div>;
}
interface RunnerHeaderProps {
runId?: string | null;
agentName?: string | null;
agentIcon?: string | null;
agent?: import("../AgentAvatar").AvatarAgent;
status: string;
execution?: ExecutionProjection | null;
preparationLabel?: string;
startedAtMs: number | null;
finishedAtMs?: number | null;
continuedAfterSteering?: boolean;
}
function runnerWaitingLabel({ runId, status, execution, preparationLabel }: RunnerHeaderProps) {
if (isTerminalRunStatus(status)) return null;
if (execution?.phase === "waiting_for_provider") return execution.label;
if (!runId && preparationLabel) return preparationLabel;
return status === "queued" && execution?.cause ? execution.label : null;
}
/** One identity stays mounted while admission discovers the run's renderer. */
export function TaskChatRunnerHeader({ statusContent, ...props }: RunnerHeaderProps & { statusContent?: ReactNode }) {
return <div className="flex min-h-8 min-w-0 items-center gap-2 pb-1 pt-2" data-testid="task-chat-runner-identity-row">
{props.agentName ? <TaskChatAgentIdentity agentName={props.agentName} agentIcon={props.agentIcon} agent={props.agent} /> : null}
{statusContent ?? <RunnerTurnStatus status={props.status} startedAtMs={props.startedAtMs} finishedAtMs={props.finishedAtMs}
continuedAfterSteering={props.continuedAfterSteering} waitingLabel={runnerWaitingLabel(props)} />}
</div>;
}
export function TaskChatRunnerTurn({
runId,
agentName,
agentIcon,
agent,
items,
status,
execution,
preparationLabel,
startedAtMs,
finishedAtMs,
activityUnavailable = false,
allowSummaryFallback = true,
awaitingContinuation = false,
waitSummary = null,
continuedAfterSteering = false,
showHeader = true,
onRuntimeRequestDecision,
}: {
/** Stable identity used to clear replay-latched final text for the next turn. */
runId?: string | null;
agentName?: string | null;
agentIcon?: string | null;
agent?: import("../AgentAvatar").AvatarAgent;
items: readonly TaskChatItem[];
status: string;
execution?: ExecutionProjection | null;
/** Presentation only while Send/Retry admission has no run yet. */
preparationLabel?: string;
startedAtMs: number | null;
finishedAtMs?: number | null;
activityUnavailable?: boolean;
allowSummaryFallback?: boolean;
/**
* Accepted wait/interaction authority: the turn is waiting, so an early
* provider final that only restates the wait is not presented as a reply.
* Prose the agent wrote for the user stays visible.
*/
awaitingContinuation?: boolean;
/** The accepted yielded result's wait summary, when known. */
waitSummary?: string | null;
/** The visible tail resumes the same native run after an accepted steer. */
continuedAfterSteering?: boolean;
/** The task thread keeps a shared header across native and legacy discovery. */
showHeader?: boolean;
onRuntimeRequestDecision?: (
item: TaskChatRuntimeRequestItem,
decision: TaskChatRuntimeRequestDecision,
) => void | Promise<void>;
}) {
const { failures: mcpStartupFailures, rest: turnItems } = partitionRunHealthItems(items);
const terminal = isTerminalRunStatus(status);
const waitingLabel = runnerWaitingLabel({ runId, status, execution, preparationLabel, startedAtMs });
const yielded = turnItems.some(
(item) =>
item.kind === "protocol" &&
item.surface === "run_result" &&
item.disposition === "yielded",
);
const observedFinal = paperclipRunnerFinalResponse(turnItems, awaitingContinuation
? { allowFallback: false, yielded: true, waitSummary }
: { allowFallback: terminal && allowSummaryFallback });
const observedProviderText = Boolean(
observedFinal &&
turnItems.some(
(item) =>
item.kind === "message" &&
item.id === observedFinal.id &&
item.channel !== "progress",
),
);
// A reconnect/replay can briefly rebuild the transcript without the final
// item (or with an earlier, shorter prefix). Provider-authored final text
// always replaces a structured summary fallback, even when it is shorter;
// within either class, displayed answer text remains monotonic.
const finalRef = useRef<{
runId?: string | null;
item?: TaskChatMessageItem;
providerText?: boolean;
}>({ runId });
if (finalRef.current.runId !== runId) finalRef.current = { runId };
// A provider final can arrive before the accepted yielded result. Clear any
// replay latch once the control plane establishes that this turn is waiting
// for continuation; only an authored (non-wait) final is re-latched below.
if (yielded || awaitingContinuation) finalRef.current = { runId };
if (
observedFinal &&
(!finalRef.current.item ||
(observedProviderText && !finalRef.current.providerText) ||
(observedProviderText === Boolean(finalRef.current.providerText) &&
observedFinal.text.length >= finalRef.current.item.text.length))
) {
finalRef.current.item = observedFinal;
finalRef.current.providerText = observedProviderText;
}
const final = finalRef.current.item;
const timelineItems = paperclipRunnerTimelineItems(turnItems);
const currentActivityItems = currentActivityStatusItems(timelineItems);
const timelineRows = groupImageResources(buildTurnTimelineRows(
omitProgressRepeatedByResponse(timelineItems, final?.text),
!terminal,
));
return (
<TaskChatShimmerScope items={items}><div
className="flex min-w-0 flex-col"
data-testid="task-chat-runner-turn"
data-phase={status === "queued" ? "startup" : undefined}
>
{showHeader ? <TaskChatRunnerHeader runId={runId} agentName={agentName} agentIcon={agentIcon} agent={agent}
status={status} execution={execution} preparationLabel={preparationLabel} startedAtMs={startedAtMs}
finishedAtMs={finishedAtMs} continuedAfterSteering={continuedAfterSteering} /> : null}
<TaskChatRunHealthBanner failures={mcpStartupFailures} />
{activityUnavailable ? (
<div
className="px-1 py-1 text-xs text-muted-foreground"
role="status"
data-testid="task-chat-activity-unavailable"
>
Live runner activity is temporarily unavailable. Retrying…
</div>
) : null}
{timelineRows.length > 0 ? (
<div
className="flex min-w-0 flex-col gap-2 py-1"
data-testid="task-chat-turn-timeline"
>
{timelineRows.map((row) => (
<div
className="min-w-0"
key={`${runId ?? "run"}:${row.id}`}
data-testid="task-chat-turn-timeline-row"
data-timeline-row-id={row.id}
data-thread-anchor={row.id}
>
{row.kind === "activity_phase" ? (
<TaskChatRunnerActivityGroup item={row} />
) : row.kind === "plan_document" ? (
<TaskChatPlanPreviewCard
source={{ kind: "saved", document: row.document }}
testId={
row.placement === "fallback"
? "task-chat-plan-preview-fallback"
: "task-chat-plan-preview"
}
/>
) : row.kind === "marker" ? (
<TaskChatMarker item={row} />
) : row.kind === "subagent_group" ? (
<TaskChatSubagentTree subagents={row.subagents} />
) : row.kind === "protocol" ? (
<TaskChatProtocolCard
item={row}
onRuntimeRequestDecision={onRuntimeRequestDecision}
/>
) : null}
</div>
))}
</div>
) : null}
<McpAppTurnViews runId={runId} refreshKey={mcpAppRunRefreshKey(turnItems, status)} />
{final ? (
<div
className="w-full"
data-testid="task-chat-final-response"
>
<TaskChatBubble
item={{ ...final, authorName: agentName ?? undefined, agentIcon, agent, timestamp: final.timestamp ?? formatTaskChatTimestamp(final.atMs) }}
animateEntry={false}
hideAgentIdentity={!continuedAfterSteering}
actions={<TaskChatBubbleActions copyText={final.text} />}
/>
</div>
) : null}
{!final && currentActivityItems.length === 0 ? <RunnerCurrentActivityTail status={status} waitingLabel={waitingLabel} /> : null}
</div></TaskChatShimmerScope>
);
}