Files
PaperClipAI/server/src/__tests__/tool-call-progress.test.ts
T
DottaandClaude Opus 5.5 a726dce4f0 feat(mcp): show live progress for long connected-app tool calls in the task chat (#21449)
## 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>
2026-11-13 20:14:22 -06:00

175 lines
7.5 KiB
TypeScript
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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);
});
});