mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-02 08:28:48 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Its web server also owns controller admission and user commands. > - A rolling deployment starts a replacement before the old server exits. > - Shared database state alone does not preserve local agent files, browser chunks, or in-process commands. > - This pull request adds an opt-in ephemeral server contract and a local overlap test. > - The benefit is a web server that can relinquish traffic and local files without losing acknowledged work. ## Linked Issues or Issue Description Refs #18403, #18327, #18335, #18341. **Current behavior** The control-plane web server still has local agent-file authority and local command targets. A new container can miss saved bytes or send a command to the wrong process. An existing browser tab also needs chunks from its original build. **Proposed behavior** Eligible servers share only PostgreSQL, object storage and stable secrets. A replacement waits for readiness. The old server drains admitted requests, keeps owner commands available through handoff, and releases controller leases. Explicit maintenance adopts existing files before the volume is removed. **Reason and benefit** This is the application prerequisite for rolling app-only deployments. Schema migrations and permanent multi-replica operation are outside this change. ## What Changed - Store agent-file manifests in PostgreSQL and immutable bytes in S3. Treat local roots as disposable projections. Preserve existing permission checks and edit conflicts. - Add an explicit migration, eligibility and object-retention command to the production runtime bundle. - Add `/api/ready`, admitted-request drain, browser restart signaling and retained immutable UI chunks. - Carry transaction-aware work hints across controllers during handoff and active execution. Keep listeners closed when idle. - Deliver durable Stop and runtime responses to the execution owner. Recheck request lifecycle and access before response dispatch. - Reject local-only configuration in ephemeral mode. Keep the feature disabled for existing installations by default. - Add an isolated PostgreSQL/S3/proxy/browser deployment harness with independent server homes and retained failure evidence. ## Verification - All CI checks pass on `ce17b95019d3cf1cabd357d19b6d37f96782cc5c`: workspace typecheck, build, Runner checks, server/general tests and browser shards. Greptile reviewed the runtime changes at 5/5 with all findings resolved; the final commit updates maps and the plan. - Local targeted checks passed: coordinator 27; Stop/recovery 33; PostgreSQL command delivery 6; route/workspace regressions 8; bootstrap Stop 1; restart recovery 75. PostgreSQL command tests simulate the provider edge. - Local browser proof passed 91 reads and 19 saves; reconnect took 1,013ms. The tab opened Audit from S3 after deletion of A's whole home/build. This uses compiled workspace code and local-trusted auth, not released containers or live agents. - Local workspace typecheck/build passed; current server and runtime bundle passed. The earlier broad local suite was stopped after three hours and is not a passing receipt. Its retained failures and isolated reruns are documented in the plan. - Stacked #18526 adds stricter graceful-exit proof, an unready replacement control, live Runner qualification and a Stop handoff correction. Hosted enablement remains gated on those results and Cloud #1096. No hosted stack has been enabled. ## Risks - Apply migration 0422 before enabling the feature. Existing data must pass each owner's migration and eligibility checks. Do not discard a volume based on a single migration page. - Durable manifests remain authoritative after the opt-in is disabled. Rolling back to a binary that ignores them is unsupported. - Cold directory restoration and complete shutdown timing still need qualification before enabling a hosted stack. - Retained UI assets must cover the supported browser and rollback window. Cleanup is explicit; no new idle maintenance polling is introduced. - This change does not claim production zero downtime or authorize a fleet-wide enablement. ## Model Used OpenAI Codex, GPT-6 family. The exact serving model ID and context-window limit are not exposed in this session. Used reasoning, code editing, shell execution and browser automation. ## 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 - [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>
65 lines
3.8 KiB
TypeScript
65 lines
3.8 KiB
TypeScript
import assert from "node:assert/strict";
|
|
import { chromium, expect } from "@playwright/test";
|
|
import path from "node:path";
|
|
|
|
/** The actual built board UI, real APIs and ordinary browser navigation. No
|
|
* route stubs, response injection, request retries or fabricated UI state. */
|
|
export async function openRollingDeploymentBrowser(input: { origin: string; root: string; taskTitle: string; taskPath: string; omittedAssets: string[] }) {
|
|
const browser = await chromium.launch({ headless: true });
|
|
const context = await browser.newContext({ viewport: { width: 1440, height: 1000 } });
|
|
const page = await context.newPage();
|
|
const sockets: { openedAt: number; closedAt?: number; firstFrameAt?: number }[] = [];
|
|
const errors: string[] = [];
|
|
const assets: string[] = [];
|
|
const metrics: { reconnectMs?: number; oldChunkLoaded: boolean; pageErrors: number } = { oldChunkLoaded: false, pageErrors: 0 };
|
|
page.on("pageerror", error => errors.push(error.message));
|
|
page.on("response", response => { if (response.url().includes("/assets/") && response.ok()) assets.push(response.url()); });
|
|
page.on("websocket", socket => {
|
|
if (!socket.url().includes("/events/ws")) return;
|
|
const record = { openedAt: Date.now() } as typeof sockets[number]; sockets.push(record);
|
|
socket.on("framereceived", () => { record.firstFrameAt ??= Date.now(); });
|
|
socket.on("close", () => { record.closedAt = Date.now(); });
|
|
});
|
|
try {
|
|
await page.goto(`${input.origin}${input.taskPath}`);
|
|
await expect(page.getByRole("heading", { name: input.taskTitle, exact: true }).first()).toBeVisible({ timeout: 30_000 });
|
|
await expect.poll(() => sockets.some(socket => socket.firstFrameAt !== undefined), { timeout: 15_000 }).toBe(true);
|
|
assert.equal(assets.some(url => input.omittedAssets.some(asset => url.endsWith(asset))), false, "Old lazy chunk must not have loaded before deployment");
|
|
await page.screenshot({ path: path.join(input.root, "browser-before.png") });
|
|
return {
|
|
metrics,
|
|
async verifyReplacement() {
|
|
try {
|
|
await expect.poll(() => sockets.length, { timeout: 5_000 }).toBeGreaterThan(1);
|
|
await expect.poll(() => sockets.at(-1)?.firstFrameAt !== undefined, { timeout: 5_000 }).toBe(true);
|
|
const closedAt = sockets.find(socket => socket.closedAt !== undefined)?.closedAt;
|
|
assert.ok(closedAt);
|
|
const reconnected = sockets.find(socket => socket.openedAt >= closedAt && socket.firstFrameAt);
|
|
assert.ok(reconnected);
|
|
const reconnectMs = reconnected.firstFrameAt! - closedAt;
|
|
metrics.reconnectMs = reconnectMs;
|
|
assert.ok(reconnectMs <= 5_000, `Browser reconnected after ${reconnectMs}ms`);
|
|
// Use the existing tab's router so its original build requests the
|
|
// previously unopened page's chunk from B after A has been removed.
|
|
const activity = page.getByRole("link", { name: /^(Audit|Activity)$/ }).first();
|
|
await activity.click();
|
|
await expect.poll(() => assets.some(url => input.omittedAssets.some(asset => url.endsWith(asset))), { timeout: 15_000 }).toBe(true);
|
|
await expect(page.getByRole("heading", { name: /^(Audit|Activity)$/ }).first()).toBeVisible({ timeout: 15_000 });
|
|
metrics.oldChunkLoaded = true;
|
|
metrics.pageErrors = errors.length;
|
|
assert.deepEqual(errors, []);
|
|
await page.screenshot({ path: path.join(input.root, "browser-after.png") });
|
|
return metrics;
|
|
} catch (error) {
|
|
await page.screenshot({ path: path.join(input.root, "browser-failure.png") }).catch(() => undefined);
|
|
throw error;
|
|
}
|
|
},
|
|
close: () => browser.close(),
|
|
};
|
|
} catch (error) {
|
|
await page.screenshot({ path: path.join(input.root, "browser-failure.png") }).catch(() => undefined);
|
|
await browser.close(); throw error;
|
|
}
|
|
}
|