mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-28 20:21:50 +01:00
## Thinking Path > - Paperclip should show live agent output without repeating presentation work for every view. > - Execution, acknowledgements and durable checkpoints must remain independent of browser interest. > - The server already owns authorization and redaction at delivery. > - A shared browser connection can declare which visible runs need full transcripts. > - Catch-up must handle subscription races, disconnects, terminal output and slow consumers. > - This PR delivers the backend and UI contract together without a database migration. ## Linked Issues or Issue Description **What existing behavior does this improve?** Visible transcript consumers receive recoverable output through one shared browser connection. **Current behavior** Independent views can create duplicate connections, presentation work and recurring history reads. A subscription race or filtered native history can lose the saved tail. **Proposed behavior** Negotiate run interests, subscribe before catch-up and retain independent canonical recovery cursors. Keep lightweight lifecycle and attention events available without full transcript delivery. PR 4 of #17097 → #17439 → #17455 → #17456. The runtime feature is independent of hot-upgrade recovery; the stack order is for review convenience. ## What Changed - Add additive WebSocket capability negotiation, replacement interests, revision acknowledgement and resynchronization notices. - Reference-count visible consumer interests on one company-scoped browser connection. Preserve older-client/server behavior. - Reuse canonical structural/current-user/registered-secret redaction for plugin run notifications through the same bounded delivery queue. Keep producer and uninterested streams free of recipient lookups. - Refresh application queries after the matching recovery acknowledgement, including one follow-up after an older in-flight read. Ordinary interest acknowledgements add no refresh. - Keep authorization and redaction at delivery. Browser interest cannot change harness execution, PRP ACKs, checkpoints, accounting or canonical logs. - Deduplicate by sequence and log identity. Catch up terminal output and saved tails without recurring reads during healthy negotiated streaming. - Bound delivery to 1,000 items and 1 MiB. Overflow requires resynchronization; persistent congestion closes the connection. - Preserve compact-history expansion from current master across paginated catch-up. Snapshot the original read window before React can defer its update. ## Verification On current source `f6710f0b3c`, Linux [job 122604880503](https://github.com/paperclipai/paperclip/actions/runs/40624101891/job/122604880503) executes all five run-read permission cases successfully (2.574 seconds), including grant and revocation on the same connection. Its shard passes all 2,430 cases. Current [server-shard job 122604880416](https://github.com/paperclipai/paperclip/actions/runs/40624101891/job/122604880416) has 1,513 passes, one failure and three skips: an unchanged nested-clone expiration/restore test exceeds its 15-second deadline. The preceding `5efc6c48bf` source has identical non-document bytes; [its corresponding job 122601359272](https://github.com/paperclipai/paperclip/actions/runs/40623017917/job/122601359272) passes all 21 nested-clone cases, including that case in 9.505 seconds. The exact timing cause is unproven. The single diagnostic [retry job 122609332597](https://github.com/paperclipai/paperclip/actions/runs/40624101891/job/122609332597) passes all 21 nested-clone cases (61.316 seconds), including the formerly timed-out case in 7.003 seconds, and all 1,514 shard cases (three skips). The failure remains recorded; no timeout or assertion was changed. After the server squash merge and qualification retarget, all 50 focused server cases and all 91 focused UI cases pass again, with both typechecks and token gates. Runner vendor preparation rebuilds current master inputs before those tests. This source needs fresh CI and reviews; prior CI and browser receipts do not qualify it by inference. Current candidate `f6710f0b3c` now targets master `6987c2f20b`, after merged #17097, #17439 and #17455. Its diff contains only transcript delivery and its documentation. It adds no database migration. Retargeting changes only the evidence document; all production and test code is byte-identical to `5efc6c48bf`. On the eighth integration, all 50 focused server delivery cases and all 91 focused UI cases pass, with both typechecks and token gates. The following 35-case receipt belongs to the earlier delivery correction. Four low-queue authorization/decoration stall variants and the late-rejection case fail before correction. They now verify the five-second read deadline, old and negotiated clients, revisions that cannot reset the deadline, unaffected sibling connections, rejected late results, and timer cleanup. The first combined toast run has four loopback EPERM failures and 31 passes; its permitted repeat passes all 35. Earlier 28-case evidence excluded the toast file. The permission correction requires the current HTTP company-scope transcript permission, plus task access, for both native events and legacy logs. Prior Linux source `49a8783e9b`, job 122549913643, executes all five run-read cases, including grant/revocation on the same connection, successfully. That source placed this file in server shard 11; later shard assignments can differ and must be checked against their actual inventories. The older `405bedd189` receipt retains a separate scheduled-retry teardown race and inherited fixture collision; neither is waived. The new head must pass again in Linux CI. The seven extracted stream-recovery tests preserve their assertions. All 39 related legacy/native cases, UI typecheck and token gates pass after restoring the initially missed fixture helper. Earlier full workspace build/typecheck and Chrome journeys at `445a76563c` cover two views, company switches, reconnect, terminal catch-up, reload and zero recurring healthy transcript reads. Those browser receipts are historical source evidence and do not qualify this new head by inference. The [qualification record](https://github.com/paperclipai/paperclip/blob/f6710f0b3c84c6fdb2021df67206261b446dfc97/doc/plans/2026-10-22-hot-upgrade-qualification.md) retains exact earlier UI/history, source-boundary and cleanup failures with their fixes and limits. The workload-cost test preserves bounds and authorization callback counts for zero interests, one viewer, multiple browsers and a slow viewer. Its socket congestion is simulated. It measures neither SQL nor network costs. Current permission checks and the final hosted active-agent/viewer matrix remain unmeasured; no production savings are claimed. Fresh exact-head CI, legacy status, completed Greptile 5/5, resolved feedback and ordinary merge eligibility remain required. The earlier recipient corrections pass all 47 registry/plugin/delivery/WebSocket/toast cases and all 174 UI provider/recovery/interest cases, both typechecks and token gates on source `b202e59a25`. A real bus/host-service test registers a synthetic run secret through the production registry and reproduces its raw notification before the fix; native/legacy/final notifications now redact it, disposal prevents late worker notification. A later P1 review reproduces lost final notifications on settings-read and secret-resolution failure. Both cases fail before correction. Any delivery failure or subscription timeout now sends one content-free stream error and removes the plugin subscription. It never changes the agent execution or run status. Later events start no new redaction reads. The final integrated six-file server lane passes all 50 cases, with server typecheck and token gates. Existing browser delivery behavior is unchanged. Storage and secret-provider seams are scripted. Two real React Query/provider regressions first miss a run during resync; both now refresh after the valid replacement ACK, including pending-read and stale-scope cases. The prerequisite qualification batch passes all 118 cases and E2E typecheck after master integration. Fresh CI, security scan and reviews remain pending on this head. The contribution-rule review correction removes 104 explanatory comments introduced by this slice and keeps the ordering, deadline and plugin-delivery explanations in the delivery document. Existing comments and functional test/lint directives remain. All edited source files have identical parsed non-comment tokens before and after the change. All 50 server delivery cases and all 91 cases in six affected UI suites pass, along with token gates. The new head requires fresh CI, security and review. ## Risks A slow or disconnected viewer must resynchronize from authorized canonical history. It may see a display gap until catch-up completes. Company changes and revoked access must remove delivery interests. This slice adds no database migration and cannot change execution or recovery authority. Full transcript delivery evaluates current company-scope permission per delivery. Active plugin recipients also perform canonical redaction reads; viewer-load database costs on this final source remain unmeasured. ## Model Used OpenAI GPT-6 through Codex, with reasoning, repository tools and code execution. The runtime does not expose a more specific model ID or context-window size. ## 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 - [ ] 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 - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
134 lines
8.7 KiB
TypeScript
134 lines
8.7 KiB
TypeScript
import { expect, test, type WebSocket } from "@playwright/test";
|
|
import { json } from "./agent-chat.shared";
|
|
|
|
test("native transcript survives two views and reload through negotiated streaming", async ({ page, context, request }, info) => {
|
|
test.setTimeout(120_000);
|
|
await page.addInitScript(() => {
|
|
const sockets = new Set<globalThis.WebSocket>();
|
|
const OriginalWebSocket = window.WebSocket;
|
|
window.WebSocket = class extends OriginalWebSocket {
|
|
constructor(url: string | URL, protocols?: string | string[]) {
|
|
super(url, protocols);
|
|
if (String(url).includes("/events/ws")) sockets.add(this);
|
|
this.addEventListener("close", () => sockets.delete(this));
|
|
}
|
|
};
|
|
Object.assign(window, { closeTranscriptTransport: () => {
|
|
for (const socket of sockets) socket.close();
|
|
} });
|
|
});
|
|
const company = await json(await request.post("/api/companies", { data: { name: "Native transcript delivery" } }));
|
|
const original = await json(await request.get("/api/instance/settings/experimental"));
|
|
const frames: Array<{ type?: string; runIds?: string[]; revision?: number }> = [];
|
|
let connections = 0;
|
|
const activeConnections = new Set<WebSocket>();
|
|
let transcriptReads = 0;
|
|
page.on("request", request => { if (/\/heartbeat-runs\/[^/]+\/(events|log)(\?|$)/.test(request.url())) transcriptReads += 1; });
|
|
page.on("websocket", socket => {
|
|
if (!socket.url().includes("/events/ws")) return;
|
|
connections += 1;
|
|
activeConnections.add(socket);
|
|
socket.on("close", () => { activeConnections.delete(socket); });
|
|
socket.on("framesent", frame => { try { frames.push(JSON.parse(String(frame.payload))); } catch {} });
|
|
socket.on("framereceived", frame => { try { frames.push(JSON.parse(String(frame.payload))); } catch {} });
|
|
});
|
|
try {
|
|
await json(await request.patch("/api/instance/settings/experimental", { data: { enableNativeRunner: true, enableWorktreeRunExecution: true } }));
|
|
await json(await request.post(`/api/companies/${company.id}/user-secret-definitions`, { data: { key: "OPENAI_API_KEY", name: "Fixture credential" } }));
|
|
await json(await request.post(`/api/companies/${company.id}/me/user-secrets`, { data: { definitionKey: "OPENAI_API_KEY", value: "not-a-real-model-key" } }));
|
|
const agent = await json(await request.post(`/api/companies/${company.id}/agents`, { data: { name: "CEO", role: "ceo", adapterType: "paperclip_runner",
|
|
adapterConfig: { provider: "codex", model: "gpt-5.1-codex-mini", env: {
|
|
OPENAI_API_KEY: { type: "user_secret_ref", key: "OPENAI_API_KEY", version: "latest", required: true },
|
|
} } } }));
|
|
await expect.poll(async () => (await json(await request.get(`/api/agents/${agent.id}`))).lifecycleState,
|
|
{ timeout: 30_000 }).toBe("ready");
|
|
await page.goto(`/${company.issuePrefix}/agents/${agent.id}/overview`);
|
|
await page.getByRole("link", { name: "Tasks", exact: true }).click();
|
|
await page.getByRole("button", { name: "New Task", exact: true }).last().click();
|
|
const dialog = page.getByRole("dialog");
|
|
await dialog.getByRole("textbox", { name: "editable markdown" }).fill("Summarize the launch decisions and include the source link");
|
|
await expect(dialog.getByRole("button", { name: "Select assignee" })).toContainText("CEO");
|
|
await dialog.getByRole("button", { name: "Create task", exact: true }).click();
|
|
await expect.poll(async () => (await json(await request.get(`/api/companies/${company.id}/issues`))).length).toBe(1);
|
|
const [issue] = await json(await request.get(`/api/companies/${company.id}/issues`));
|
|
const route = `/${company.issuePrefix}/issues/${issue.identifier}`;
|
|
activeConnections.clear();
|
|
frames.length = 0;
|
|
await page.goto(route);
|
|
let runId = "";
|
|
await expect.poll(async () => {
|
|
const runs = await json(await request.get(`/api/companies/${company.id}/heartbeat-runs`));
|
|
runId = runs[0]?.id ?? "";
|
|
return runs[0]?.status;
|
|
}).toBe("running");
|
|
const subscribed = () => {
|
|
const index = frames.findLastIndex(frame => frame.type === "live.interests");
|
|
const interest = frames[index];
|
|
return Boolean(interest?.runIds?.includes(runId)
|
|
&& frames.slice(index + 1).some(frame => frame.type === "live.subscribed" && frame.revision === interest.revision));
|
|
};
|
|
await expect.poll(subscribed).toBe(true);
|
|
await expect(page.getByText("STREAM-42: waiting for the final answer.", { exact: false }).first()).toBeVisible();
|
|
await page.waitForTimeout(2_000);
|
|
const healthyReads = transcriptReads;
|
|
await page.waitForTimeout(2_500);
|
|
const healthyPollingReads = transcriptReads - healthyReads;
|
|
expect(healthyPollingReads).toBe(0);
|
|
expect(activeConnections.size).toBe(1);
|
|
const second = await context.newPage();
|
|
await second.goto(route);
|
|
const other = await json(await request.post("/api/companies", { data: { name: "Transcript isolation" } }));
|
|
await page.goto(`/${other.issuePrefix}/dashboard`);
|
|
await expect.poll(() => frames.findLast(frame => frame.type === "live.interests")?.runIds).toEqual([]);
|
|
await page.goto(route);
|
|
await expect.poll(subscribed).toBe(true);
|
|
const beforeReconnect = connections;
|
|
await context.setOffline(true);
|
|
await page.evaluate(() => (window as unknown as { closeTranscriptTransport(): void }).closeTranscriptTransport());
|
|
await page.waitForTimeout(1_000);
|
|
await context.setOffline(false);
|
|
await expect.poll(() => connections, { timeout: 15_000 }).toBeGreaterThan(beforeReconnect);
|
|
await expect.poll(subscribed).toBe(true);
|
|
await expect.poll(async () => (await json(await request.get(`/api/companies/${company.id}/heartbeat-runs`)))[0]?.status, { timeout: 70_000 }).toBe("succeeded");
|
|
for (const view of [page, second]) {
|
|
await expect(view.getByText("STREAM-42: The launch has two stages.", { exact: false }).first()).toBeVisible();
|
|
await view.reload();
|
|
await expect(view.getByText("STREAM-42: The launch has two stages.", { exact: false }).first()).toBeVisible();
|
|
}
|
|
const runs = await json(await request.get(`/api/companies/${company.id}/heartbeat-runs`));
|
|
expect(runs).toHaveLength(1);
|
|
const comments = await json(await request.get(`/api/issues/${issue.id}/comments`));
|
|
expect(comments.filter((comment: { body: string }) => comment.body.includes("STREAM-42"))).toHaveLength(1);
|
|
await page.screenshot({ path: info.outputPath("native-transcript.png"), fullPage: true });
|
|
await page.goto(`/${company.issuePrefix}/agents/${agent.id}/runs/${runId}`);
|
|
const eventDetails = page.getByText(/^Events \(\d+\)$/).locator("..");
|
|
await expect(eventDetails.getByText("STREAM-42: The launch has two stages.", { exact: false }).first()).toBeVisible();
|
|
await page.reload();
|
|
await expect(eventDetails.getByText("STREAM-42: The launch has two stages.", { exact: false }).first()).toBeVisible();
|
|
const eventsRoute = `**/api/heartbeat-runs/${runId}/events?*`;
|
|
const logRoute = `**/api/heartbeat-runs/${runId}/log?*`;
|
|
await page.route(eventsRoute, route => route.fulfill({ status: 503, json: { error: "History temporarily unavailable" } }));
|
|
await page.route(logRoute, async route => {
|
|
const response = await route.fetch();
|
|
await route.fulfill({ json: { ...await response.json(), content: "", nextOffset: 0 } });
|
|
});
|
|
await page.reload();
|
|
await expect(page.getByText("Could not load events. Try again.", { exact: true })).toBeVisible();
|
|
await expect(page.getByText("No log events.", { exact: true })).toHaveCount(0);
|
|
await page.unroute(eventsRoute); await page.unroute(logRoute);
|
|
await page.getByRole("button", { name: "Retry events", exact: true }).click();
|
|
await expect(eventDetails.getByText("STREAM-42: The launch has two stages.", { exact: false }).first()).toBeVisible();
|
|
await expect(page.getByText("Could not load events. Try again.", { exact: true })).toHaveCount(0);
|
|
await page.screenshot({ path: info.outputPath("native-agent-events.png"), fullPage: true });
|
|
await info.attach("delivery-evidence", { body: JSON.stringify({ dependency: "deterministic Codex app-server", runId: runs[0].id,
|
|
connections, healthyPollingReads, negotiated: frames.some(frame => frame.type === "live.subscribed"),
|
|
interestRevisions: frames.filter(frame => frame.type === "live.interests") }), contentType: "application/json" });
|
|
await second.close();
|
|
} finally {
|
|
const live = await json(await request.get(`/api/companies/${company.id}/live-runs`));
|
|
for (const run of live) await json(await request.post(`/api/heartbeat-runs/${run.id}/cancel`));
|
|
await json(await request.patch("/api/instance/settings/experimental", { data: { enableNativeRunner: original.enableNativeRunner,
|
|
enableWorktreeRunExecution: original.enableWorktreeRunExecution } }));
|
|
}
|
|
});
|