Files
PaperClipAI/server/src/services/native-runtime/native-continuation.test.ts
T
DottaandClaude Opus 5.5 8af889f612 feat(mcp-apps): view messages with consent, app context, full screen and provider tool icons (#21266)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - MCP Apps (#21119) show interactive widgets from MCP servers, such as
Circleback meeting cards, with the agent's reply in the task chat.
> - The first version deferred three parts of the MCP Apps spec. A
widget could not propose a chat message (`ui/message`). It could not
give the agent context (`ui/update-model-context`). It could not go full
screen.
> - Paperclip also ignored the `icons` that MCP servers declare on tools
(SEP-973).
> - The security review of #21119 showed what these features need from
day one: explicit consent, untrusted-data labels and strict icon
sanitizing.
> - This pull request adds the three host features and provider tool
icons, with those protections built in.
> - The benefit is that widgets can now work with the person and the
agent, not only display data.

## Linked Issues or Issue Description

Refs #21119

**Subsystem affected**
MCP Apps host (task chat widgets), tool catalog, run wake prompt.

**Problem or motivation**
The MCP Apps host refused `ui/message` (-32601), dropped
`ui/update-model-context` and kept every view inline. MCP tool `icons`
were not parsed or shown. So widgets could not ask the agent a
follow-up, the agent could not see what the person selected in a widget,
large widgets were cramped, and tool rows used only generic icons.

**Proposed solution**
Add consent-gated view messages, per-view app context delivered to the
task's next run as untrusted data, a full-screen dialog, and sanitized
provider icons. Details are under "What Changed".

**Alternatives considered**
- Send view messages with a new server route that creates the comment
itself. Rejected: comment creation has many rules (agent chat ownership,
paused conversations, queued delivery, wakeups, receipts). The widget's
Send button uses the same send path as the composer. A small route then
records which view the comment came from.
- Keep the iframe in place for full screen with CSS. Rejected: chat
containers can create containing blocks that break `position: fixed`. A
moved iframe always reloads, so the dialog hosts a new frame instead.

**Roadmap alignment**
Continues the MCP feature work after #21119, #21140 and #21219. It does
not touch the MCP Tasks work (gateway `tools/call` polling and
elicitation).

## What Changed

- **`ui/message`.** The host shows "<App> wants to send: …" with
**Send** and **Dismiss** under the widget (and inside the full-screen
dialog). Nothing is sent before the click. Send posts the text as the
viewer's own comment through the chat's normal send path
(`handleThreadAdd`). `POST
/api/issues/:issueId/mcp-app-views/:viewId/messages` then logs
`issue.mcp_app_message_sent`. It accepts only the caller's own comment
on the same task, matched by `clientRequestId`, from the last 10
minutes. One proposal per view can wait at a time. The view gets `{}`
after the send, or -32000 "Message sending denied" after Dismiss. Only
`user` text up to 8,000 characters is accepted.
- **`ui/update-model-context`.** `PUT
/api/issues/:issueId/mcp-app-views/:viewId/model-context` stores the
latest context per view in `tool_mcp_app_views.model_context` (text
blocks and `structuredContent`, 16 KB at most). Updates are applied in
order and deduped in the browser and on the server. A change logs
`issue.mcp_app_context_updated`, and an empty update clears the context.
The task's next run gets the three most recently updated contexts as an
`## App context (untrusted)` wake-prompt section. The section quotes the
data as JSON and says it is third-party data, not instructions. The read
runs in parallel with the other run preparation and never fails the run.
CLI adapters and the native runner render it through the same
`renderPaperclipWakePrompt`.
- **Who may do this.** Messages and context need a signed-in person with
`issue:comment` on the task. Agents and API keys get 403. Other tasks
and companies get 404. `message` and `updateModelContext` are advertised
in `hostCapabilities` only where the viewer can send messages.
- **Full screen.** The host advertises `availableDisplayModes:
["inline","fullscreen"]` and handles `ui/request-display-mode`. It
honors the view's declared modes and answers with the resulting mode. It
sends `host-context-changed` with `displayMode` and the container (fixed
`height`/`width` in full screen), and again when that container resizes.
A new **Open full screen** control sits next to "Widget from …". Full
screen is a Paperclip dialog that closes with Exit, Escape or the view's
own request.
- **Provider tool icons.** `icons` on MCP tool descriptors are sanitized
into the new `tool_catalog_entries.icons` column, outside the version
hash, so a new icon never quarantines a reviewed tool. Only `https:`
URLs and `data:image/*` URIs are kept, and SVG only as `data:`. A
`data:` icon is at most 32 KB, a URL at most 2,048 characters, with at
most 4 icons per tool. `GET /api/companies/:companyId/tool-icons` lists
them keyed by gateway tool name, in one cached request per chat. Task
chat tool rows and the app's actions list show them through
`ProviderToolIcon`. It renders `<img referrerPolicy="no-referrer">` at a
fixed size and never inlines markup. It checks the source again before
rendering and falls back to the taxonomy icon.
- **Schema.** Migration `0477` adds `tool_catalog_entries.icons`,
`tool_mcp_app_views.model_context` and `model_context_updated_at`, all
nullable.
- **Docs and stories.** `doc/connections/MCP-APPS.md` documents the new
behavior, and the finished items are removed from "Limits and
follow-ups". `Tasks/MCP App views` has new stories: "View asks to send a
message", "Full screen" and "Tool rows with provider icons". The fixture
view now uses `ui/message`, `ui/request-display-mode` and
`ui/update-model-context`.

## Verification

- `pnpm exec vitest run server/src/__tests__/mcp-apps.test.ts
server/src/__tests__/tool-catalog-publication.test.ts
server/src/__tests__/openapi-routes.test.ts
packages/shared/src/mcp-icons.test.ts
packages/shared/src/mcp-apps.test.ts`: pass (embedded Postgres). These
tests cover:
- Context: stored, deduped, logged once, 413 when too large, cleared,
scoped to the task and company, refused for agents (403), and rendered
into the wake prompt as untrusted data.
- Messages: attributed only to the viewer's own recent comment on the
same task. A teammate's comment, an unknown request id or an old comment
gets 404. An agent gets 403.
- Icons: stored sanitized, and the version hash and status do not
change. Another company sees nothing.
- `cd ui && pnpm exec vitest run src/components/mcp-app/
src/components/ProviderToolIcon.test.tsx src/pages/apps/app-detail/`: 69
pass. These tests cover:
- The host protocol for each new method: capabilities, consent wait, one
proposal at a time, invalid input, ordered and deduped context, the size
limit, and the display-mode rules.
  - The consent card (nothing sent without Send).
  - The full-screen dialog (one frame at a time).
  - Icon rendering (no-referrer `img`, no inline SVG, fallback).
- `cd ui && pnpm typecheck` (including Storybook) and `tsc --noEmit` for
the server: clean.
- Red/green: the new route and host tests fail on `master`, where the
routes do not exist and the host answers -32601 or drops updates. The
icon descriptor test failed when the publication write was removed.
- Not run locally: the full suite, and
`packages/adapter-utils/src/server-utils.test.ts › runChildProcess ›
does not crash when the child closes stdin before a delayed write`. That
test times out on this Mac with or without this change, so it is a local
platform issue. CI covers both.

## Risks

- Migration risk is low: three nullable columns, no backfill.
- Every run on a task now does one extra indexed read, in parallel with
the other preparation. Errors are logged and the run continues without
app context.
- If the attribution request fails after the comment is sent, the
comment stays without the `mcp_app_message_sent` activity row. This is
documented.
- Switching between inline and full screen restarts the view, so state
inside the widget resets. This is documented as a limit.
- Icon names shortened with a hash by the gateway (very long names) do
not match, and those rows keep the taxonomy icon.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and
code execution. One subagent (the same model) built the provider-icon
part.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 07:32:48 -06:00

146 lines
8.8 KiB
TypeScript

import { describe, expect, it } from "vitest";
import { buildNativeContinuationPrompt } from "./native-continuation.js";
const issue = { title: "Original task", description: "Retain my long task brief." };
const message = { id: "new", body: "Yes, please proceed.", authorType: "user", authorId: "board", sourceTrust: "user", createdByRunId: null };
const wake = {
reason: "issue_commented",
executionContinuation: {
version: 1,
objective: message.body,
messages: [{ ...message, id: "old", body: "OLD_HISTORY" }, message],
resumeDelta: { baseRunId: "prior", messages: [message] },
completedWork: { summary: "OLD_SUMMARY" },
humanResponses: [{ id: "old-question", result: { answer: "OLD_ANSWER" } }],
},
comments: [message], continuationSummary: { markdown: "OLD_SUMMARY" },
};
const build = (value: unknown = wake, previousIssue = issue) => buildNativeContinuationPrompt({ wakePayload: value, previousRunId: "prior", issue, previousIssue });
describe("native continuation event projection", () => {
it("sends a new comment once without the unchanged brief, objective, history or summary", () => {
const text = build()!;
expect(text.split(message.body)).toHaveLength(2);
for (const old of [issue.description, issue.title, "OLD_HISTORY", "OLD_SUMMARY", "OLD_ANSWER"]) expect(text).not.toContain(old);
expect(JSON.parse(text).messages[0]).toMatchObject({ authorType: "user", body: message.body });
expect(text.length).toBeLessThan(600);
});
it("tells a resumed turn which delivered comments an earlier turn already read", () => {
const comment = { id: "new", body: message.body, author: { type: "user", id: "board" } };
const marked = JSON.parse(build({ ...wake, comments: [{ ...comment, readByEarlierTurn: true }] })!);
expect(marked.readByEarlierTurn).toEqual({ messageIds: ["new"], note: expect.stringContaining("may have applied it") });
expect(JSON.parse(build({ ...wake, comments: [comment] })!).readByEarlierTurn).toBeUndefined();
});
it("keeps the task widgets' app context on a resumed turn", () => {
const appContext = "## App context (untrusted)\n\n```json\n{\"app\":\"Circleback\",\"text\":\"Selected m2\"}\n```";
const events = JSON.parse(build({ ...wake, mcpAppContext: appContext })!);
expect(events.appContext).toBe(appContext);
expect(events.messages[0]).toMatchObject({ body: message.body });
expect(JSON.parse(build()!).appContext).toBeUndefined();
});
it("only uses a delta whose base matches the actual previous run", () => {
expect(build({ ...wake, executionContinuation: { ...wake.executionContinuation, resumeDelta: { baseRunId: "different", messages: [message] } } })).toBeNull();
expect(build({ ...wake, executionContinuation: null })).toBeNull();
});
it("delivers the current authenticated answer once, not all prior answers", () => {
const text = build({ ...wake, interactionId: "new-question", executionContinuation: { ...wake.executionContinuation, resumeDelta: { baseRunId: "prior", messages: [] }, humanResponses: [...wake.executionContinuation.humanResponses, { id: "new-question", kind: "ask_user_questions", status: "answered", resolvedByUserId: "board", result: { answer: "NEW_ANSWER" } }] } })!;
expect(text.split("NEW_ANSWER")).toHaveLength(2);
expect(text).not.toContain("OLD_ANSWER");
expect(JSON.parse(text).humanResponses[0].resolvedByUserId).toBe("board");
});
it("includes external child completion and actual brief edits", () => {
const text = build({ ...wake, reason: "issue_children_completed", childIssueSummaries: [{ id: "child", status: "done", summary: "CHILD_RESULT" }] }, { ...issue, description: "old brief" })!;
expect(JSON.parse(text).taskChanges).toEqual({ description: issue.description });
expect(text).toContain("CHILD_RESULT");
});
it.each([{ fallbackFetchNeeded: true }, { recovery: { cause: "interrupted" } }, { externalChatExecutionBound: true }, { reason: "issue_assigned" }])("retains bootstrap framing for special wakes: %j", (extra) => {
expect(build({ ...wake, ...extra })).toBeNull();
});
});
describe("plain-text external chat continuation projection", () => {
const slackComment = { ...message, author: { type: "user", id: "board" } };
const slackWake = {
...wake,
reason: "External chat message received",
issue: { id: "task", title: "OLD_EXACT_REPLY", description: "Started from Slack", workMode: "standard" },
externalChatProvider: "slack", checkedOutByHarness: true,
comments: [slackComment],
commentIds: [message.id], latestCommentId: message.id,
commentWindow: { requestedCount: 1, includedCount: 1, missingCount: 0 },
attachmentOmissions: [],
};
const buildChat = (value: unknown = slackWake) => buildNativeContinuationPrompt({
wakePayload: value, previousRunId: "prior", issue: slackWake.issue,
previousIssue: slackWake.issue,
allowExternalChat: true,
});
it.each(["slack", "github"])("sends the new %s message once without prior titles, history or instructions", (externalChatProvider) => {
const text = buildChat({ ...slackWake, externalChatProvider })!;
expect(text).not.toBeNull();
expect(JSON.parse(text)).toEqual({ messages: [message] });
expect(text).not.toContain("OLD_EXACT_REPLY");
expect(text).not.toContain("OLD_HISTORY");
expect(text.length).toBeLessThan(600);
});
it("excludes edited history and prior agent output outside the current Slack delivery", () => {
const text = buildChat({ ...slackWake, executionContinuation: {
...wake.executionContinuation,
resumeDelta: { baseRunId: "prior", messages: [
{ ...message, id: "old-edited", body: "STALE_DIRECTION" },
{ ...message, id: "old-reply", authorType: "agent", body: "OLD_AGENT_REPLY" },
message,
] },
} });
expect(JSON.parse(text!).messages).toEqual([message]);
expect(text).not.toContain("STALE_DIRECTION");
expect(text).not.toContain("OLD_AGENT_REPLY");
});
it("preserves an actual task brief edit beside the current message", () => {
const text = buildNativeContinuationPrompt({
wakePayload: slackWake, previousRunId: "prior", allowExternalChat: true,
issue: { ...slackWake.issue, description: "Updated scope" }, previousIssue: slackWake.issue,
});
expect(JSON.parse(text!).taskChanges).toEqual({ description: "Updated scope" });
});
it("delivers changed GitHub configuration while retaining unchanged configuration in the provider session", () => {
const config = { key: "a".repeat(64), instructions: "CURRENT_REVIEW_POLICY" };
const args = { wakePayload: { ...slackWake, externalChatProvider: "github", githubReviewConfigurations: [config] },
previousRunId: "prior", issue: slackWake.issue, previousIssue: slackWake.issue, allowExternalChat: true };
const changed = buildNativeContinuationPrompt(args)!;
expect(JSON.parse(changed).reviewConfigurations).toEqual([config]);
const unchanged = buildNativeContinuationPrompt({ ...args, previousGitHubReviewConfigurationKeys: [config.key] })!;
expect(unchanged).not.toContain(config.instructions);
expect(JSON.parse(unchanged).messages).toEqual([message]);
expect(buildNativeContinuationPrompt({ ...args, previousRunId: "wrong" })).toBeNull();
});
it("accepts the verified non-assignee chat binding", () => {
expect(buildChat({ ...slackWake, checkedOutByHarness: false, externalChatExecutionBound: true })).not.toBeNull();
});
it.each([
{ comments: [{ ...slackComment, attachments: [{ id: "file" }] }] },
{ comments: [{ ...slackComment, attachments: "malformed" }] },
{ comments: [{ ...slackComment, body: "EDITED_SINCE_DELTA" }] },
{ comments: [{ ...slackComment, author: { type: "user", id: "different-user" } }] },
{ attachmentOmissions: [{ commentId: message.id, notice: "Unavailable input" }] },
{ externalChatProvider: "discord" },
{ checkedOutByHarness: false },
{ truncated: true },
{ fallbackFetchNeeded: true },
{ comments: [{ ...slackComment, bodyTruncated: true }] },
{ interactionId: "approval", interactionKind: "request_confirmation" },
{ recovery: { cause: "interrupted" } },
{ executionContinuation: { ...wake.executionContinuation, resumeDelta: { baseRunId: "wrong", messages: [message] } } },
{ executionContinuation: { ...wake.executionContinuation, resumeDelta: { baseRunId: "prior", messages: [] } } },
{ commentIds: [message.id, "missing"], latestCommentId: "missing" },
{ commentIds: [message.id, message.id], latestCommentId: message.id },
{ executionContinuation: { ...wake.executionContinuation, resumeDelta: { baseRunId: "prior", messages: [message, message] } } },
])("keeps specialized or incomplete input on the full path: %j", (extra) => {
expect(buildChat({ ...slackWake, ...extra })).toBeNull();
});
it("requires the constructor to explicitly opt into chat continuation", () => {
expect(build(slackWake)).toBeNull();
});
});