mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-06 05:56:19 +01:00
## Thinking Path > - Paperclip coordinates AI agents and retains their work across failures. > - A retry can require a new workspace while preserving the failed attempt. > - Core rejects this recovery strategy for provider-owned storage. > - Providers should implement the required outcome using their own storage design. > - This pull request adds a semantic fresh-preparation contract and delegates recovery preparation. > - The benefit is that a supported provider can run a fresh retry without losing prior work. ## Linked Issues or Issue Description **What happened?** A retry that selects `fresh_isolated_workspace` fails with `fresh_workspace_storage_unsupported` for provider-owned storage. **Expected behavior** Core asks a capable provider to prepare new storage and attach verified recovery files. The failed workspace remains intact. **Steps to reproduce** Run a task in a task-capable plugin environment. Let the task fail without a verified workspace preservation receipt. Retry the task so Core selects a fresh attempt. **Paperclip version or commit**6204239cf(rebased on current master). **Deployment mode** Self-hosted server with a plugin task environment and managed workspace provider. Search found no duplicate implementation. This branch includes the default-provider changes from #17247 and preserves their source selection behavior. ## What Changed - Define an opt-in fresh-preparation contract with a stable attempt identity and verified recovery file descriptors. - Describe retained-storage and recovery-attachment guarantees without requiring a Git storage layout. - Reserve replacement task bindings with revision checks and keep the failed workspace intact. Projectless and project-backed task environments both replay their stable attempt reservation. - Reconcile an interrupted preparation against its reserved workspace and stable operation identity. - Stage verified recovery archives at stable transfer paths. Delegate attachment materialization to the provider. - Preserve projectless attempt directory identities through later turns and pin the intent into each execution lease. - Protect fresh intent and projectless ownership from caller metadata replacement or injection. ## Verification - SDK workspace-provider tests: 4 passed. - Targeted reservation and task-dispatch tests: 31 passed. - Recovery transfer staging and lifecycle focus: 7 passed. The separate cache-cleanup failure reconciliation case also passed. - After rebasing on current master, 7 focused preparation and ownership cases passed. These cover inherited provider defaults, fresh preparation, stable projectless identity, and authorization denial. - The focused metadata authority regression passed, including forged intent, replacement, and null metadata patches. - Three assembled interrupted task-reservation cases passed: projectless, project with a saved source, and project with a newly selected default source. - Targeted tests use worktree SDK sources. No full local build or typecheck ran. - Local checks remain targeted as requested. Latest-head GitHub CI passed: 54 successful checks, including typecheck, build, server suites, Runner validation, and E2E shards; 2 unrelated Storybook checks were skipped. - Greptile reviewed commit73595b0c61at 5/5 with zero unresolved threads. - Live VM E2E has not run. ## Risks - Existing providers retain their existing behavior. Fresh attempts require explicit version support. - The companion provider implementation must materialize recovery snapshots safely and preserve the old workspace. - Fresh retries require the companion provider implementation. Providers without the version marker fail closed. ## Model Used - OpenAI GPT-6.1 (`gpt-6.1-sol`), reasoning and coding tools. The runtime does not expose the context-window limit. ## 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>
42 lines
3.2 KiB
TypeScript
42 lines
3.2 KiB
TypeScript
import { createHash, randomUUID } from "node:crypto";
|
|
import { Readable } from "node:stream";
|
|
import { chmod, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
|
|
import { tmpdir } from "node:os";
|
|
import path from "node:path";
|
|
import { afterEach, describe, expect, it, vi } from "vitest";
|
|
import type { Db } from "@paperclipai/db";
|
|
import { releaseProviderRecoveryTransfers, stageProviderFreshWorkspace } from "./provider-fresh-workspace.js";
|
|
const state = vi.hoisted(() => ({ getObject: vi.fn() }));
|
|
vi.mock("../storage/index.js", () => ({ getStorageService: () => ({ getObject: state.getObject }) }));
|
|
let home: string | undefined;
|
|
afterEach(async () => { vi.unstubAllEnvs(); state.getObject.mockReset(); if (home) await rm(home, { recursive: true, force: true }); });
|
|
describe("fresh provider recovery transfer staging", () => {
|
|
it("verifies immutable transfer files and reuses stable descriptors after interruption", async () => {
|
|
home = await mkdtemp(path.join(tmpdir(), "provider-recovery-")); vi.stubEnv("PAPERCLIP_HOME", home);
|
|
const companyId = randomUUID(), sourceRunId = randomUUID(), leaseId = randomUUID(), operationId = randomUUID();
|
|
const archive = Buffer.from("verified archive"), manifest = Buffer.from("verified manifest");
|
|
const stored = (bytes: Buffer, extension: string) => { const sha256 = createHash("sha256").update(bytes).digest("hex");
|
|
return { objectKey: `${companyId}/workspace-recovery/${sourceRunId}/${leaseId}/${sha256}.${extension}`, sha256, byteSize: bytes.length }; };
|
|
const metadata = { schema: "paperclip.workspace-recovery-snapshot.v1", recoveryActionId: randomUUID(), leaseId,
|
|
providerLeaseId: "retained-task", archive: stored(archive, "tar"), manifest: stored(manifest, "jsonl") };
|
|
const db = { execute: async () => [{ id: sourceRunId }], select: () => ({ from: () => ({ where: async () => [{ id: operationId, metadata }] }) }) } as unknown as Db;
|
|
state.getObject.mockImplementation(async (_companyId, key) => ({ stream: Readable.from([key.endsWith(".tar") ? archive : manifest]) }));
|
|
const input = { db, companyId, issueId: randomUUID(), sourceRunId, attemptId: randomUUID(), previousWorkspaceId: randomUUID() };
|
|
const first = await stageProviderFreshWorkspace(input);
|
|
expect(first.recoverySnapshots).toHaveLength(1);
|
|
expect(await readFile(first.recoverySnapshots[0].archive.path)).toEqual(archive);
|
|
expect(await stageProviderFreshWorkspace({ ...input, existing: first })).toEqual(first);
|
|
await rm(first.recoverySnapshots[0].archive.path);
|
|
expect(await stageProviderFreshWorkspace({ ...input, existing: first })).toEqual(first);
|
|
expect(state.getObject).toHaveBeenCalledTimes(3);
|
|
await releaseProviderRecoveryTransfers(companyId, first);
|
|
await expect(readFile(first.recoverySnapshots[0].archive.path)).rejects.toThrow();
|
|
expect(await stageProviderFreshWorkspace({ ...input, existing: first })).toEqual(first);
|
|
expect(state.getObject).toHaveBeenCalledTimes(5);
|
|
await chmod(first.recoverySnapshots[0].archive.path, 0o600);
|
|
await writeFile(first.recoverySnapshots[0].archive.path, "corrupt");
|
|
await expect(stageProviderFreshWorkspace(input)).rejects.toThrow();
|
|
expect(state.getObject).toHaveBeenCalledTimes(5);
|
|
});
|
|
});
|