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 call tools from connected apps through the Paperclip MCP gateway > - Some tool calls take a long time: exports, builds, large searches > - The MCP progress utility lets an app report how far a call is, but Paperclip ignored it > - So the task chat showed only a spinner until the call finished, with no sign of life > - This pull request reads the app's progress and shows it on the tool's row while the call runs > - The benefit is that people can see that a long call is working, how far it is, and how long it has run ## Linked Issues or Issue Description **Subsystem affected** Connected apps (MCP gateway) and the task chat. **Problem or motivation** A long tool call from a connected MCP app shows only a spinner in the task chat. Paperclip does not send a `progressToken`, and it drops `notifications/progress` from the app. **Proposed solution** Send a `progressToken` on each `tools/call` that an agent run makes. Read the app's progress notifications from the call's response stream. Show a progress bar (or an indeterminate sweep), the latest message, and elapsed time on the running tool row. Keep the latest state so that a reload mid-call shows it. **Alternatives considered** A new transport for progress. The existing company live-events socket already carries per-run events with run read checks, so this change uses it. **Additional context** Spec: https://modelcontextprotocol.io/specification/2026-07-28/basic/utilities/progress ## What Changed - `mcp-http.ts`: `mcpHttpRequestInit` can add `_meta.progressToken`. `readMcpHttpResponse` gives each notification on the response stream to an observer before the result. The observer cannot fail or delay the call. New `mcpProgressNotificationOf` matches a notification to its token. - `tool-gateway.ts`: remote HTTP and local stdio `tools/call` from an agent run send a per-call token and forward progress to a reporter. Calls without a run send no token. - New `server/src/services/tool-call-progress.ts`: checks each update (finite, increasing, plain single-line text of at most 200 characters). It publishes a `heartbeat.run.tool_progress` live event at most every 250 ms (latest wins) and saves the latest update on the invocation at most every 1 s. Nothing is awaited by the call. A final `done` event goes out when the call ends. - DB: nullable `tool_invocations.progress` jsonb column (migration `0479`, `ADD COLUMN` only). A save never writes onto a finished call. - Live delivery: the new event follows its run like transcript output. A client gets it only for runs it follows, after the run read check, in the run's company only. - New route `GET /api/issues/:issueId/tool-call-progress` (task read check) returns the latest progress of the task's running calls, for a reload mid-call. Documented in `docs/api/issues.md`. - UI: `ToolCallProgressProvider` (one per chat) keeps the latest update per call. A running tool row subscribes and shows a bar or sweep, the message, the percent and elapsed time (design tokens, reduced motion honored). Finished rows drop it and never fetch or re-render for progress. `LiveUpdatesProvider` ignores the event for query invalidation. - `packages/kv-demo-mcp-server`: new `slow_with_progress` demo tool (`steps`, `stepMs`, `withTotal`) in its own file. - Storybook: `Tasks/Tool progress` stories (running with total, running without total, done). - Docs: new `doc/connections/MCP-PROGRESS.md`; `MCP-PROTOCOL-VERSIONS.md` no longer lists progress as unsupported. ## Verification - Red/green: on the original source, 5 of the new server tests fail (token in `_meta`, SSE with interleaved progress and result, notification matching, run-interest delivery, gateway end-to-end). With this change they pass. - `server/src/__tests__/mcp-http.test.ts` (13), `tool-call-progress.test.ts` (9: throttling, latest wins, bounded text, out-of-order drop, finish, failures never throw, company/run/tool scoping), `tool-call-progress-store.test.ts` (2, embedded Postgres: company and task scoping, no write onto a finished call), `realtime/live-event-delivery.test.ts` (run interest), `tool-gateway.test.ts` end-to-end against the real SDK kv demo server over Streamable HTTP: 6 provider updates over about 1.2 s give 3 to 7 throttled events, all for the right company, run, task and tool, the last one `done`; no event reaches another company; the invocation keeps the progress; the result is unchanged. - UI: `tool-call-progress.test.tsx` (10: name matching, row states, plain-text rendering, drop on complete, restore after reload, no fetch for finished rows). All 67 task-chat test files pass. - `packages/kv-demo-mcp-server`: 13 tests, including progress over HTTP with and without a total. - Storybook: checked the three stories in a browser. The bar fills to 40%, the sweep animates, the elapsed time ticks, and the done row shows no progress. - `pnpm verify`: see the CI checks for the final revision. ## Risks - Low. The migration adds one nullable column. - An SSE response is now bounded per message, not per stream, so handled notifications (such as progress) do not use up the result's size limit. Each message is still bounded. - Progress code runs only while a run's tool call is in flight. It adds a few bytes to the request and throttled, fire-and-forget work. Agent boot and time to first token do not change. - A row finds its call by run and tool name. If one run calls the same tool twice at the same time, both rows show the newer call's progress. - Progress from a call that became an MCP Task is not shown. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Claude Code agent with tool use and code execution. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [ ] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
175 lines
7.5 KiB
TypeScript
175 lines
7.5 KiB
TypeScript
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||
import { TOOL_CALL_PROGRESS_MESSAGE_MAX_LENGTH } from "@paperclipai/shared";
|
||
import {
|
||
createToolCallProgressReporter,
|
||
TOOL_CALL_PROGRESS_PUBLISH_INTERVAL_MS,
|
||
TOOL_CALL_PROGRESS_SAVE_INTERVAL_MS,
|
||
} from "../services/tool-call-progress.js";
|
||
import { assignedToolName } from "../services/native-runtime/assigned-mcp-tools.js";
|
||
|
||
function reporter() {
|
||
const published: Array<{ companyId: string; type: string; payload: Record<string, unknown> }> = [];
|
||
const saved: unknown[] = [];
|
||
const instance = createToolCallProgressReporter({
|
||
companyId: "company-a",
|
||
runId: "run-a",
|
||
issueId: "issue-a",
|
||
agentId: "agent-a",
|
||
invocationId: "invocation-a",
|
||
toolName: "kv_demo__slow_with_progress",
|
||
startedAt: new Date("2026-11-13T10:00:00Z"),
|
||
publish: (event) => { published.push(event); },
|
||
save: async (progress) => { saved.push(progress); },
|
||
});
|
||
return { instance, published, saved };
|
||
}
|
||
|
||
describe("tool call progress reporter", () => {
|
||
beforeEach(() => { vi.useFakeTimers(); vi.setSystemTime(new Date("2026-11-13T10:00:01Z")); });
|
||
afterEach(() => { vi.useRealTimers(); });
|
||
|
||
it("publishes at most one update per interval and always the latest", () => {
|
||
const { instance, published } = reporter();
|
||
for (let step = 1; step <= 50; step++) instance.report({ progress: step, total: 50, message: `Step ${step}` });
|
||
// The first update goes out at once; the rest wait for the interval.
|
||
expect(published.map((event) => event.payload.progress)).toEqual([1]);
|
||
vi.advanceTimersByTime(TOOL_CALL_PROGRESS_PUBLISH_INTERVAL_MS);
|
||
expect(published.map((event) => event.payload.progress)).toEqual([1, 50]);
|
||
vi.advanceTimersByTime(TOOL_CALL_PROGRESS_PUBLISH_INTERVAL_MS * 4);
|
||
expect(published).toHaveLength(2);
|
||
// A steady stream for one second publishes about four times, never per update.
|
||
for (let tick = 0; tick < 100; tick++) {
|
||
instance.report({ progress: 51 + tick, total: 200 });
|
||
vi.advanceTimersByTime(10);
|
||
}
|
||
expect(published.length - 2).toBeLessThanOrEqual(1_000 / TOOL_CALL_PROGRESS_PUBLISH_INTERVAL_MS + 1);
|
||
});
|
||
|
||
it("saves on the invocation less often than it publishes", async () => {
|
||
const { instance, saved } = reporter();
|
||
for (let tick = 0; tick < 200; tick++) {
|
||
instance.report({ progress: tick, total: 200 });
|
||
await vi.advanceTimersByTimeAsync(10);
|
||
}
|
||
expect(saved.length).toBeLessThanOrEqual(2_000 / TOOL_CALL_PROGRESS_SAVE_INTERVAL_MS + 1);
|
||
expect(saved.length).toBeGreaterThanOrEqual(2);
|
||
});
|
||
|
||
it("ties every event to its company, run and tool call", () => {
|
||
const { instance, published } = reporter();
|
||
instance.report({ progress: 1, total: 4, message: "Reading" });
|
||
expect(published[0]).toEqual({
|
||
companyId: "company-a",
|
||
type: "heartbeat.run.tool_progress",
|
||
payload: {
|
||
invocationId: "invocation-a",
|
||
runId: "run-a",
|
||
issueId: "issue-a",
|
||
agentId: "agent-a",
|
||
toolName: "kv_demo__slow_with_progress",
|
||
nativeToolName: assignedToolName("kv_demo__slow_with_progress"),
|
||
startedAt: "2026-11-13T10:00:00.000Z",
|
||
updatedAt: "2026-11-13T10:00:01.000Z",
|
||
progress: 1,
|
||
total: 4,
|
||
message: "Reading",
|
||
done: false,
|
||
},
|
||
});
|
||
});
|
||
|
||
it("treats provider text as untrusted: plain, single-line and bounded", () => {
|
||
const { instance, published } = reporter();
|
||
instance.report({ progress: 1, message: `<b>bold</b>\n\u0007line${"x".repeat(1_000)}` });
|
||
const message = published[0]!.payload.message as string;
|
||
expect(message.startsWith("<b>bold</b> line ")).toBe(true);
|
||
expect(message).not.toMatch(/[\n\u0007]/);
|
||
expect(message.length).toBe(TOOL_CALL_PROGRESS_MESSAGE_MAX_LENGTH);
|
||
});
|
||
|
||
it("drops unusable and out-of-order updates", () => {
|
||
const { instance, published } = reporter();
|
||
instance.report({ progress: "1", total: 2 });
|
||
instance.report({ progress: Number.NaN });
|
||
instance.report({ progress: -1 });
|
||
expect(published).toEqual([]);
|
||
instance.report({ progress: 5, total: 2 });
|
||
expect(published[0]!.payload).toMatchObject({ progress: 5, total: null });
|
||
vi.advanceTimersByTime(TOOL_CALL_PROGRESS_PUBLISH_INTERVAL_MS);
|
||
instance.report({ progress: 3, total: 10 });
|
||
vi.advanceTimersByTime(TOOL_CALL_PROGRESS_PUBLISH_INTERVAL_MS);
|
||
expect(published).toHaveLength(1);
|
||
});
|
||
|
||
it("on finish stops pending work and tells viewers to drop the progress", () => {
|
||
const { instance, published, saved } = reporter();
|
||
instance.report({ progress: 1, total: 3 });
|
||
instance.report({ progress: 2, total: 3 });
|
||
instance.finish();
|
||
vi.advanceTimersByTime(TOOL_CALL_PROGRESS_SAVE_INTERVAL_MS * 3);
|
||
expect(published.map((event) => [event.payload.progress, event.payload.done])).toEqual([[1, false], [2, true]]);
|
||
expect(saved).toHaveLength(1);
|
||
instance.report({ progress: 3, total: 3 });
|
||
expect(published).toHaveLength(2);
|
||
});
|
||
|
||
it("a call that never reported progress finishes silently", () => {
|
||
const { instance, published } = reporter();
|
||
instance.finish();
|
||
expect(published).toEqual([]);
|
||
});
|
||
|
||
it("never throws into the call when publishing or saving fails", async () => {
|
||
const instance = createToolCallProgressReporter({
|
||
companyId: "c", runId: "r", issueId: null, agentId: null, invocationId: "i", toolName: "t",
|
||
publish: () => { throw new Error("socket gone"); },
|
||
save: async () => { throw new Error("db gone"); },
|
||
});
|
||
expect(() => instance.report({ progress: 1 })).not.toThrow();
|
||
expect(() => instance.finish()).not.toThrow();
|
||
await vi.runAllTimersAsync();
|
||
});
|
||
|
||
it("keeps one save in flight, only the newest update waits, and finish drops it", async () => {
|
||
let release!: () => void;
|
||
const saves: number[] = [];
|
||
const instance = createToolCallProgressReporter({
|
||
companyId: "c", runId: "r", issueId: null, agentId: null, invocationId: "i", toolName: "t",
|
||
publish: () => undefined,
|
||
save: (progress) => { saves.push(progress.progress); return new Promise<void>((resolve) => { release = resolve; }); },
|
||
});
|
||
instance.report({ progress: 1 });
|
||
// The database is slow: three more save intervals pass while the first write runs.
|
||
for (let step = 2; step <= 4; step++) {
|
||
vi.advanceTimersByTime(TOOL_CALL_PROGRESS_SAVE_INTERVAL_MS);
|
||
instance.report({ progress: step });
|
||
}
|
||
vi.advanceTimersByTime(TOOL_CALL_PROGRESS_SAVE_INTERVAL_MS);
|
||
expect(saves).toEqual([1]);
|
||
release();
|
||
await vi.advanceTimersByTimeAsync(0);
|
||
expect(saves).toEqual([1, 4]);
|
||
instance.report({ progress: 5 });
|
||
vi.advanceTimersByTime(TOOL_CALL_PROGRESS_SAVE_INTERVAL_MS);
|
||
instance.finish();
|
||
release();
|
||
await vi.advanceTimersByTimeAsync(TOOL_CALL_PROGRESS_SAVE_INTERVAL_MS * 3);
|
||
expect(saves).toEqual([1, 4]);
|
||
});
|
||
|
||
it("names the tool the way native runners name it, so their rows can find the call", () => {
|
||
const instance = createToolCallProgressReporter({
|
||
companyId: "c", runId: "r", issueId: null, agentId: null, invocationId: "i",
|
||
toolName: "mcp.kv-demo-1a2b3c4d:slow-with-progress",
|
||
publish: (event) => { names.push(event.payload.nativeToolName); },
|
||
});
|
||
const names: unknown[] = [];
|
||
instance.report({ progress: 1 });
|
||
expect(names).toEqual(["app_mcp_kv_demo_1a2b3c4d_slow_with_progress_889fb9a8d98e"]);
|
||
});
|
||
|
||
it("gives each call its own progress token", () => {
|
||
expect(reporter().instance.token).not.toBe(reporter().instance.token);
|
||
});
|
||
});
|