mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 09:50:48 +01:00
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - An agent can have app connections. Paperclip gives the agent the
tools of those apps through an MCP gateway, with its approval and audit
rules.
> - Native harnesses reach the gateway in two ways today. In the relay,
the server keeps the gateway token and offers the tools over the
authenticated Runner channel. In the direct way, the server gives the
gateway URL and a bearer token to the harness.
> - Which way a harness uses comes from a list of special cases that
grew one harness at a time. Local Codex and all ACPX agents use the
direct way. The others use the relay.
> - The direct way puts a run-scoped token in a provider process. A
process that the agent starts can read it. A provider process that
serves more than one run can hold a revoked token.
> - This pull request replaces the list with one rule. Each native
harness gets its assigned gateway tools through the relay.
> - The benefit is one behavior for all native harnesses, and no gateway
token in a provider process.
## Linked Issues or Issue Description
No public issue exists. The issue is described here.
Refs #13942 (the relay), #17149 (ACPX accepts relayed tools) and #19912
(the design for turn-scoped ACPX MCP authority).
**What existing behavior does this improve?**
How a native harness reaches the tools of its assigned MCP gateway.
**Subsystem affected**
Native runtime in the server (`native-session-executor.ts`,
`native-session-resume.ts`). One Runner test file. One Rust test.
**Current behavior**
- `relayAssignedMcp` is true for plugin tasks, Cursor Cloud, OpenCode,
Codex on a remote target, and Dot.
- For local Codex and for each ACPX agent (Claude, Codex, Cursor, Pi,
Kimi, Grok, Copilot, Antigravity), Core puts
`PAPERCLIP_NATIVE_MCP_NAME`, `PAPERCLIP_NATIVE_MCP_URL` and
`PAPERCLIP_NATIVE_MCP_TOKEN` in the Runner environment. The ACPX host
gives them to the provider as an HTTP MCP server. The local Codex home
gets them in `config.toml`.
- The token is run-scoped. Core revokes it when the run ends.
**Proposed behavior**
- A native run that has an assigned gateway uses the relay. The
condition names no provider.
- Core builds the gateway tools on the control plane, offers them with
the other Runner tools, dispatches each call over PRP, and authorizes
each call again through the gateway.
- Core removes the three `PAPERCLIP_NATIVE_MCP_*` variables from each
Runner environment.
- The tool contract fingerprint has the relay marker for each target,
not only for remote targets.
**Reason and benefit**
- All native harnesses have the same behavior.
- No provider process holds a gateway token.
- A sandbox does not need to reach the gateway URL of the host.
## What Changed
- `server/src/services/native-runtime/native-session-executor.ts`
- The list of special cases is gone. Core validates the binding and
builds the relayed tools when a binding is present.
- Core does not list the gateway for a review run, Grok Bot or Muse. The
tool authority never offered app tools to those. A gateway error can
therefore not fail those runs.
- OpenCode keeps its `on_demand` catalog. That option depends on the
provider, not on the relay.
- Core removes the three variables from each Runner environment.
- `server/src/services/native-runtime/native-session-resume.ts`: the
relay marker in the tool contract fingerprint is unconditional.
- `doc/execution-semantics.md`: the text about the tool contract
fingerprint now states the rule, the tool names and the cutover.
- App tool schemas. New module
`packages/paperclip-runner/src/drivers/tool-input-schema.ts` compiles
each schema by itself, in its declared dialect (draft-07, 2019-09 or
2020-12), with no shared `$id` registry. Core uses it when it builds the
relayed tools (`assigned-mcp-tools.ts`). Core does not offer a tool
whose schema has an unsupported dialect or does not compile, and writes
a log entry with the tool name and the reason. The run does not fail.
The ACPX tool bridge and the OpenCode MCP bridge use the same function.
The tools of Paperclip itself stay strict.
- Large arguments. The ACPX sidecar sends the arguments of a tool call
to runnerd with no display limit. The limit is the tool-call admission
limit of runnerd, 256 KiB. A larger call fails with a tool error that
gives the limit. The sidecar does not dispatch it.
- Tests in `native-session-executor.test.ts`,
`native-session-resume.test.ts`, `runtime-context-materializer.test.ts`
and `acpx_provider_backend.rs`.
Not changed in this pull request: the direct code path. It is still in
the Runner, but it receives no binding. #21311 deletes it.
## Behavior that each harness sees
| Harness | Before | After |
|---|---|---|
| Codex on a remote target, OpenCode, Cursor Cloud, Dot, plugin tasks |
Relay | No change |
| Local Codex | Direct: a `paperclip-assigned` server in `config.toml` |
Relay. App tools are dynamic tools named `app_<name>_<digest>` |
| ACPX agents | Direct: a second HTTP MCP server | Relay. App tools are
on the `paperclip` bridge as `mcp__paperclip__app_<name>_<digest>` |
| ACPX with a preconfigured home | No gateway | No change |
| Grok Bot, Muse | Got the variables and ignored them | Do not get the
variables |
- A relayed tool name has a maximum of 64 characters. With the
`mcp__paperclip__` prefix it has a maximum of 80.
- Permission behavior keeps the same intent. For Claude in the
`approve-reads` and `approve-paperclip` modes, app tools ask for
approval, as before. For the other ACPX agents the permission decision
does not use the server name.
- In a planning run or an ask run, the relay offers only tools with read
risk. The direct gateway offered all tools. This is stricter.
- When the catalog is too large, each harness gets the two compact tools
`paperclip_search_assigned_tools` and `paperclip_call_assigned_tool`.
- The four helper tools for resources and prompts
(`paperclip_list_resources`, `paperclip_read_resource`,
`paperclip_list_prompts`, `paperclip_get_prompt`) are not in the relay.
No harness loses them: a run token permits only `tools/list` and
`tools/call` (`run-preparation.ts`), so these four tools already fail
with `gateway_token_action_denied` on the direct path.
## State saved by the previous release
- **Local sessions of each provider start again one time.** The tool
contract fingerprint changes for local targets. The next run sees a
different fingerprint, starts a new provider session with the full task
context in the same workspace, and keeps the old saved state. This is
the existing rotation for a tool contract change. Codex needs it,
because Codex cannot add tools to a thread that it resumes. For the
local providers that already used the relay, the restart is not
necessary. It is accepted so that the rule names no provider.
- **Remote sessions continue.** Their fingerprint does not change. For
ACPX, the attach of the next run replaces the saved tool set.
- **A kept Codex home.** Paperclip writes `config.toml` again at each
start and recovery. The old gateway server and its token are removed.
- **A deploy lands during a run, and the Runner survives.** The
controller attaches to the same Runner for the same run. The old
provider keeps its direct gateway connection. The controller detach
keeps the gateway token of that run, and Paperclip revokes it when the
run ends.
- **A deploy lands during a run, and the Runner is dead.** The Runner
starts again for the same run with its saved tool set and no direct
gateway. The assigned app tools are not available for the remainder of
that one run. The next run gets them through the relay. This applies to
each harness that moves to the relay. It has no test.
- Paperclip refuses no saved state and discards none.
## Verification
- `cd server && npx vitest run
src/services/native-runtime/native-session-executor.test.ts
src/services/native-runtime/native-session-resume.test.ts`: `1508 passed
| 7 skipped`, 1 failed. The failed test is "archives a damaged prior
epoch before completing guarded same-task replacement with real runnerd"
(`ENOENT … authority-epochs`). It fails in the same way on `master` at
53608bd1d6 and with the product change removed, on macOS.
- `cd server && npx tsc --noEmit -p tsconfig.json`: no errors.
- `cd packages/paperclip-runner && npx vitest run
src/drivers/runtime-context-materializer.test.ts`: `18 passed`. `npx tsc
--noEmit -p tsconfig.test.json`: no errors.
- `cargo fmt --manifest-path runner/Cargo.toml --all -- --check`: no
changes. `cargo test -p paperclip-runner-core --lib
acpx_provider_backend`: `50 passed`.
- `npx vitest run src/drivers/tool-input-schema.test.ts
src/drivers/runner-tool-bridge.schemas.test.ts
src/drivers/runner-tool-bridge.test.ts
src/cli/acpx-runtime-sidecar.test.ts src/drivers/opencode` in
`packages/paperclip-runner`: `21 passed (21)` files, `377 passed` tests.
`pnpm run typecheck:typescript`: no errors.
- `cargo test -p paperclip-runner-core --test acpx_event_payload --test
tool_input_schema_fixtures`: 10 and 3 passed.
- Schema tests use one shared fixture
(`tool-input-schema-fixtures.json`) for the TypeScript compiler, the
tool bridge and the Rust `begin_call`: a draft-07 schema, a second
schema with the same `$id`, 2019-09, 2020-12, draft-04, an unknown
dialect, a `$ref` with no target, and an invalid keyword. Before the fix
the bridge failed with `no schema with key or ref
"http://json-schema.org/draft-07/schema#"`.
- A tool schema whose `$id` is the URI of a meta-schema cannot damage
the shared compiler. Before this fix, `removeSchema` deleted that
meta-schema, and later schemas failed to compile for each run in the
process. A test with 7 reserved ids failed before the fix and passes
now.
- Core limits the compile work of each run start. A schema over 512 KiB
is not compiled, and one listing compiles a maximum of 768 KiB of
schemas. These are the limits of the Runner. A tool over a limit is
served only through the search and call tools. Core keeps the outcome
for each schema digest (1,024 entries) and yields to the event loop
before each compile. Four tests failed before this change.
- A sidecar test sends a tool call with 200 KiB of arguments and
receives them byte for byte, refuses a call with 300 KiB with the named
error, and keeps the replacement of a lone surrogate.
Tests, each seen to fail without the product change:
- "keeps assigned MCP credentials on the control plane for %s" now runs
for remote Codex, local Codex, OpenCode and ACPX Claude, Pi, Kimi,
Copilot and Cursor. It checks that Core builds the relay, offers the
tool, dispatches a call, and gives no `PAPERCLIP_NATIVE_MCP_*` variable
to the Runner. Without the change, the five new harness cases fail.
- "relays the assigned gateway when a deploy lands mid-run…" runs for
Claude and Pi.
- The fingerprint tests keep the old local fingerprint as a retained
value and check that the new one is different. The remote fingerprints
for Codex and OpenCode do not change.
- "drops a retained direct gateway server when the relayed launch has no
binding": a Codex home with the old `config.toml` entry loses that entry
at the next start and at a recovery of the same run.
-
`next_run_attach_offers_relayed_gateway_tools_to_a_direct_gateway_checkpoint`
runs for Claude and Pi.
Not run: a live run with a real provider and a real app connection for
each harness. Not run: `pnpm verify` and the full suite. CI supplies
that coverage.
## Risks
- **An ACPX app call has a limit of 256 KiB for its arguments.** The
direct gateway accepted a request body of 10 MB. Codex and OpenCode
permit 480 KiB. To get nearer to 10 MB, runnerd needs a larger admission
limit for tool calls or a protocol that sends arguments in parts. That
is not in this pull request.
- **A tool with a draft-04 or draft-06 schema is not offered.** Ajv 8
does not support draft-04, and the TypeScript and Rust validators must
agree. On the direct path the provider got such a tool.
- **Core compiles app schemas on its event loop.** Before this pull
request Core did not compile them. With the limits above, one valid
schema near 512 KiB can hold the loop for about 0.65 s, and one listing
for about 1.2 s in total (measured on a developer machine). An app that
changes its schemas at each listing gets no help from the cache. A
worker thread with a timeout would remove this; it is not in this pull
request.
- **Tool names change for local Codex and all ACPX agents.** A saved
agent instruction that names a gateway tool directly does not match the
new name.
- **Each local native session starts again one time after the deploy.**
The provider conversation of that session does not continue. The task
context and the workspace stay.
- **A run that is in flight at deploy, with a dead Runner, has no app
tools until it ends.**
- **Names of 80 characters are not tested live** with Kimi, Copilot,
Grok, Antigravity and Codex through ACPX. Pi already shortens a name
longer than 64 characters.
- **Managed Claude and AWS AgentCore now receive relayed app tools.**
This is not tested live.
- **A gateway token expires after 1 hour.** The relay keeps the token on
the controller for the whole run, as OpenCode and remote Codex do today.
A longer run loses its app tools on both paths. This pull request does
not change that.
- **The gateway URL must have the path `/mcp/gateways/<id>`.** With a
path prefix in the API base URL, a run with an assigned gateway fails
with `assigned native MCP gateway path is invalid`. This was true for
the relayed harnesses before. It is now true for all.
- No test covers the rule that Core does not list the gateway for Grok
Bot and Muse.
## Follow-up
The direct path is now unreachable. #21311 deletes it. That pull request
is in the same stack, above the pull requests that change the same ACPX
host files.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
- Claude Fable 5.2 (`claude-fable-5-2`) in Claude Code planned the
change, reviewed the diff and ran the verification again.
- Claude Opus 5.5 (`claude-opus-5-5`), as a Claude Code subagent with
tool use (shell, file edits, local test runs), investigated each harness
and wrote the change and the tests.
## 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
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2782 lines
105 KiB
TypeScript
2782 lines
105 KiB
TypeScript
import { createHash, randomUUID } from "node:crypto";
|
|
import { existsSync, readFileSync } from "node:fs";
|
|
import {
|
|
chmod,
|
|
mkdir,
|
|
mkdtemp,
|
|
readFile,
|
|
readdir,
|
|
rm,
|
|
writeFile,
|
|
} from "node:fs/promises";
|
|
import { createServer } from "node:http";
|
|
import { tmpdir } from "node:os";
|
|
import { join, resolve } from "node:path";
|
|
import { eq, sql } from "drizzle-orm";
|
|
import {
|
|
agents,
|
|
companies,
|
|
completionContracts,
|
|
createDb,
|
|
heartbeatRunEvents,
|
|
heartbeatRuns,
|
|
issues,
|
|
nativeHarnessBackups,
|
|
nativeRunFinalizations,
|
|
nativeRunResults,
|
|
} from "@paperclipai/db";
|
|
import { describe, expect, it, vi } from "vitest";
|
|
import {
|
|
CodexAppServerDriver,
|
|
HarnessDriverBackend,
|
|
createCodexTaskEnvelope,
|
|
createRunnerdCodexTransport as createCapabilityRunnerdCodexTransport,
|
|
} from "@paperclipai/paperclip-runner";
|
|
import {
|
|
getEmbeddedPostgresTestSupport,
|
|
startEmbeddedPostgresTestDatabase as startEmbeddedDatabase,
|
|
} from "../../__tests__/helpers/embedded-postgres.js";
|
|
import {
|
|
canonicalNativeRuntimeContextDigest,
|
|
buildNativeModelEnvelope,
|
|
defaultCapabilityRunnerdBinary,
|
|
executeNativeSession,
|
|
parseNativeExecutionInput,
|
|
type NativeExecutionInput,
|
|
type NativeSession,
|
|
} from "../../vendor/paperclip-runner/index.js";
|
|
import {
|
|
runnerPrpWebSocketInternals,
|
|
setupRunnerPrpWebSocketServer,
|
|
} from "../../realtime/runner-prp-ws.js";
|
|
import {
|
|
appendRetainedNativeCleanupEvent,
|
|
createRunnerdBackend,
|
|
retainedNativeCleanupJournalMatches,
|
|
} from "./native-session-executor.js";
|
|
import * as publicationSignals from "../chat-publication-reconciliation.js";
|
|
import { PaperclipControlPlanePort } from "./paperclip-control-plane-port.js";
|
|
import {
|
|
LIST_CHAT_ATTACHMENTS_TOOL_DEFINITION,
|
|
REUSE_CHAT_ATTACHMENT_TOOL_DEFINITION,
|
|
} from "./chat-attachment-reuse.js";
|
|
import { buildNativeExecutionInput } from "./native-execution-input.js";
|
|
import { clearRunProviderStateUnsaved, markAcceptedRunProviderStateUnsaved } from "./native-provider-state-unsaved.js";
|
|
import {
|
|
buildNativeExecutionWithCheckpoint,
|
|
findNativeSessionResumeRun,
|
|
NATIVE_PROVIDER_SIDE_EFFECT_PENDING,
|
|
NATIVE_PROVIDER_STATE_INCOMPATIBLE,
|
|
NATIVE_PROVIDER_STATE_UNSAVED_KEY,
|
|
NATIVE_TOOL_CONTRACT_FINGERPRINT,
|
|
isUnusedLegacyNativeRetryReplacement,
|
|
nativeToolContractFingerprintForTarget,
|
|
nativeSessionIdForBootstrapPersistence,
|
|
nativeSessionProviderEvidence,
|
|
prepareNativeSessionBootstrapPersistence,
|
|
rebindNativeSessionCheckpoint,
|
|
selectNativeSessionResumeRun,
|
|
} from "./native-session-resume.js";
|
|
import { nativeRuntimeContextFixture } from "./runtime-context.test-fixture.js";
|
|
import { resolveExternalTestDatabaseUrl } from "../../__tests__/helpers/external-test-database.js";
|
|
|
|
const externalTestDatabaseUrl = resolveExternalTestDatabaseUrl("PAPERCLIP_TEST_DATABASE_URL");
|
|
|
|
async function startEmbeddedPostgresTestDatabase(prefix: string) {
|
|
const externalUrl = externalTestDatabaseUrl;
|
|
if (!externalUrl) return startEmbeddedDatabase(prefix);
|
|
const { closeRegisteredClients } = await import("@paperclipai/db");
|
|
return { connectionString: externalUrl, cleanup: async () => {
|
|
const db = createDb(externalUrl);
|
|
try { await db.execute(sql`TRUNCATE TABLE companies CASCADE`); }
|
|
finally { await closeRegisteredClients(externalUrl); }
|
|
} };
|
|
}
|
|
|
|
const companyId = "10000000-0000-4000-8000-000000000001";
|
|
const issueId = "20000000-0000-4000-8000-000000000002";
|
|
const agentId = "30000000-0000-4000-8000-000000000003";
|
|
const previousRunId = "40000000-0000-4000-8000-000000000004";
|
|
const currentRunId = "50000000-0000-4000-8000-000000000005";
|
|
const normalizedSessionId = "60000000-0000-4000-8000-000000000006";
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
function execution(
|
|
runId: string,
|
|
cwd = "/workspace",
|
|
workMode = "standard",
|
|
workspace: {
|
|
id?: string;
|
|
repoUrl?: string | null;
|
|
repoRef?: string | null;
|
|
branchName?: string | null;
|
|
} = {},
|
|
) {
|
|
return buildNativeExecutionInput({
|
|
companyId,
|
|
runId,
|
|
issue: {
|
|
id: issueId,
|
|
identifier: "DOT-2",
|
|
title: "Test",
|
|
description: null,
|
|
workMode,
|
|
},
|
|
taskPrompt: "Only the current turn",
|
|
agentId,
|
|
workspace: {
|
|
id: workspace.id ?? runId,
|
|
cwd,
|
|
repoUrl: workspace.repoUrl ?? null,
|
|
repoRef: workspace.repoRef ?? null,
|
|
branchName: workspace.branchName ?? null,
|
|
},
|
|
normalizedSessionId,
|
|
provider: "codex",
|
|
completionContract: {
|
|
id: "70000000-0000-4000-8000-000000000007",
|
|
sha256: `sha256:${"a".repeat(64)}`,
|
|
schemaVersion: "paperclip.run-result.v1",
|
|
contract: {
|
|
revision: "1",
|
|
objective: "Test session resumption",
|
|
criteria: [{ id: "objective", requirement: "Answer the current turn" }],
|
|
},
|
|
},
|
|
runtimeContext: nativeRuntimeContextFixture(),
|
|
});
|
|
}
|
|
|
|
function planningExecution(runId: string, revisionId: string) {
|
|
return buildNativeExecutionInput({
|
|
companyId,
|
|
runId,
|
|
issue: {
|
|
id: issueId,
|
|
identifier: "DOT-2",
|
|
title: "Test",
|
|
description: null,
|
|
workMode: "planning",
|
|
},
|
|
taskPrompt: "Revise the plan",
|
|
agentId,
|
|
workspace: {
|
|
id: runId,
|
|
cwd: "/workspace",
|
|
repoUrl: null,
|
|
repoRef: null,
|
|
branchName: null,
|
|
},
|
|
normalizedSessionId,
|
|
provider: "codex",
|
|
executionMode: "plan",
|
|
planningContext: {
|
|
documentId: "80000000-0000-4000-8000-000000000008",
|
|
baseRevisionId: revisionId,
|
|
baseRevisionNumber: revisionId.endsWith("9") ? 9 : 8,
|
|
markdown: `Plan at ${revisionId}`,
|
|
sha256: `sha256:${"b".repeat(64)}`,
|
|
reviewContext: {},
|
|
},
|
|
completionContract: execution(runId).completionContract,
|
|
runtimeContext: nativeRuntimeContextFixture(),
|
|
});
|
|
}
|
|
|
|
function previousRun(overrides: Record<string, unknown> = {}) {
|
|
return {
|
|
id: previousRunId,
|
|
companyId,
|
|
agentId,
|
|
nativeSessionId: normalizedSessionId,
|
|
runnerProfileJson: {
|
|
nativeToolContractFingerprint: NATIVE_TOOL_CONTRACT_FINGERPRINT,
|
|
nativeExecutionInput: execution(previousRunId),
|
|
sessionCheckpoint: {
|
|
backendKind: "runner",
|
|
driverKind: "codex_app_server",
|
|
sessionId: "provider-thread-123",
|
|
providerSessionId: "provider-thread-123",
|
|
cursor: "42",
|
|
identity: {
|
|
runId: previousRunId,
|
|
sessionId: normalizedSessionId,
|
|
companyId,
|
|
issueId,
|
|
agentId,
|
|
},
|
|
semanticResult: {
|
|
schema: "paperclip.run-result.v1",
|
|
reportedWorkDisposition: "done",
|
|
summary: "old",
|
|
},
|
|
terminal: {
|
|
schema: "paperclip.prp.terminal.v1",
|
|
turnTerminalState: "completed",
|
|
runTerminalState: "succeeded",
|
|
reportedWorkDisposition: "done",
|
|
},
|
|
activeTurnId: "old-turn",
|
|
terminalTurns: [{ turnId: "old-turn", state: "completed" }],
|
|
pendingRuntimeRequests: [{ requestId: "old-request" }],
|
|
lineage: [{ threadId: "provider-thread-123" }],
|
|
},
|
|
...overrides,
|
|
},
|
|
};
|
|
}
|
|
|
|
describe("capability-gated connection tool refresh", () => {
|
|
it("retains the exact provider session for an MCP-only change when the harness supports it", () => {
|
|
const current = execution(currentRunId);
|
|
current.runtimeContext.mcp.digest = "b".repeat(64);
|
|
current.runtimeContext.aggregateDigest = canonicalNativeRuntimeContextDigest(current.runtimeContext);
|
|
const rebound = rebindNativeSessionCheckpoint({ previousRun: previousRun(), currentExecution: current, toolRefreshOnResume: true, refreshTools: true });
|
|
expect(rebound).toMatchObject({ sessionId: "provider-thread-123", providerSessionId: "provider-thread-123", identity: { runId: currentRunId }, providerRecoveryPolicy: "allow_replacement_after_resume_failure" });
|
|
expect(rebindNativeSessionCheckpoint({ previousRun: previousRun(), currentExecution: current })).toBeNull();
|
|
expect(rebindNativeSessionCheckpoint({ previousRun: previousRun(), currentExecution: current, refreshTools: true, toolRefreshOnResume: false })).toBeNull();
|
|
});
|
|
|
|
it.each(["add", "edit", "remove"])("replaces sessions when connection instructions %s, even with live tool refresh", (change) => {
|
|
const block = (text: string) => ({ text, digest: createHash("sha256").update(text).digest("hex") });
|
|
const previous = execution(previousRunId);
|
|
const current = execution(currentRunId);
|
|
if (change !== "add") previous.runtimeContext.connectionInstructions = block("Prior connection instructions.");
|
|
if (change !== "remove") current.runtimeContext.connectionInstructions = block("Current connection instructions.");
|
|
previous.runtimeContext.aggregateDigest = canonicalNativeRuntimeContextDigest(previous.runtimeContext);
|
|
current.runtimeContext.aggregateDigest = canonicalNativeRuntimeContextDigest(current.runtimeContext);
|
|
const prior = previousRun({ nativeExecutionInput: previous });
|
|
expect(rebindNativeSessionCheckpoint({ previousRun: prior, currentExecution: current, toolRefreshOnResume: true, refreshTools: true })).toBeNull();
|
|
current.runtimeContext = previous.runtimeContext;
|
|
expect(rebindNativeSessionCheckpoint({ previousRun: prior, currentExecution: current })).not.toBeNull();
|
|
});
|
|
|
|
it("preserves instruction and identity fences even during a supported refresh", () => {
|
|
const current = execution(currentRunId);
|
|
current.runtimeContext.instructions.bundle.digest = "b".repeat(64);
|
|
current.runtimeContext.aggregateDigest = canonicalNativeRuntimeContextDigest(current.runtimeContext);
|
|
expect(rebindNativeSessionCheckpoint({ previousRun: previousRun(), currentExecution: current, toolRefreshOnResume: true, refreshTools: true })).toBeNull();
|
|
current.runtimeContext = nativeRuntimeContextFixture();
|
|
expect(rebindNativeSessionCheckpoint({ previousRun: previousRun(), currentExecution: current, toolRefreshOnResume: true, refreshTools: true })).not.toBeNull();
|
|
current.binding.agentId = randomUUID();
|
|
expect(rebindNativeSessionCheckpoint({ previousRun: previousRun(), currentExecution: current, toolRefreshOnResume: true, refreshTools: true })).toBeNull();
|
|
});
|
|
|
|
it("rebuilds the bootstrap when refresh requires a fresh session", () => {
|
|
const buildExecution = vi.fn(({ normalizedSessionId: sessionId, resumedSession }) => {
|
|
const built = execution(currentRunId);
|
|
built.session.normalizedSessionId = sessionId;
|
|
built.task.prompt = resumedSession ? "wake delta" : "original goal and complete handoff";
|
|
return built;
|
|
});
|
|
const result = buildNativeExecutionWithCheckpoint({ previousRun: previousRun(), normalizedSessionId, refreshTools: true, toolRefreshOnResume: false, buildExecution });
|
|
expect(result.checkpoint).toBeNull();
|
|
expect(result.normalizedSessionId).not.toBe(normalizedSessionId);
|
|
expect(result.execution.task.prompt).toContain("complete handoff");
|
|
expect(buildExecution).toHaveBeenLastCalledWith({ normalizedSessionId: result.normalizedSessionId, resumedSession: false });
|
|
});
|
|
});
|
|
|
|
describe("a source stopped with a pending side-effecting call", () => {
|
|
it("does not rebind the saved session that still refuses attachment", () => {
|
|
const current = execution(currentRunId);
|
|
const source = { ...previousRun(), errorCode: NATIVE_PROVIDER_SIDE_EFFECT_PENDING };
|
|
expect(rebindNativeSessionCheckpoint({ previousRun: source, currentExecution: current })).toBeNull();
|
|
});
|
|
});
|
|
|
|
describe("a source whose saved provider session the runner proved incompatible", () => {
|
|
it("continues the task in a fresh provider session with the same workspace", () => {
|
|
const current = execution(currentRunId);
|
|
expect(rebindNativeSessionCheckpoint({ previousRun: { ...previousRun(), errorCode: "native_session_interrupted" },
|
|
currentExecution: current })).not.toBeNull();
|
|
const source = { ...previousRun(), errorCode: NATIVE_PROVIDER_STATE_INCOMPATIBLE };
|
|
expect(rebindNativeSessionCheckpoint({ previousRun: source, currentExecution: current })).toBeNull();
|
|
const buildExecution = vi.fn(({ normalizedSessionId: sessionId, resumedSession }) => {
|
|
const built = execution(currentRunId);
|
|
built.session.normalizedSessionId = sessionId;
|
|
built.task.prompt = resumedSession ? "wake delta" : "original goal and complete handoff";
|
|
return built;
|
|
});
|
|
const result = buildNativeExecutionWithCheckpoint({ previousRun: source, normalizedSessionId, buildExecution });
|
|
expect(result.checkpoint).toBeNull();
|
|
expect(result.normalizedSessionId).not.toBe(normalizedSessionId);
|
|
expect(result.execution.task.prompt).toContain("complete handoff");
|
|
expect(result.execution.binding.executionWorkspaceId).toBe(current.binding.executionWorkspaceId);
|
|
expect(result.execution.workspace).toEqual(current.workspace);
|
|
});
|
|
});
|
|
|
|
describe("a source whose provider state was not saved after its result was accepted", () => {
|
|
const unsaved = { [NATIVE_PROVIDER_STATE_UNSAVED_KEY]: { code: NATIVE_PROVIDER_STATE_INCOMPATIBLE,
|
|
reason: "harness_backup_not_saved", recordedAt: "2026-11-11T00:00:00.000Z" } };
|
|
const withPolicy = (policy: "resume_failure" | "governed_wait" | "same_session", overrides: Record<string, unknown> = {}) => {
|
|
const source = previousRun(overrides);
|
|
const checkpoint = (source.runnerProfileJson as Record<string, unknown>).sessionCheckpoint as Record<string, unknown>;
|
|
if (policy === "governed_wait") checkpoint.semanticResult = { schema: "paperclip.run_result.v1", reportedWorkDisposition: "yielded",
|
|
summary: "Waiting for a response.", continuation: { kind: "response_wake", idempotencyKey: "interaction-response:one" } };
|
|
if (policy === "same_session") checkpoint.goal = { status: "paused", objective: "Keep working" };
|
|
return source;
|
|
};
|
|
|
|
it.each(["resume_failure", "governed_wait", "same_session"] as const)(
|
|
"starts the next run in a fresh provider session directly (%s policy)", (policy) => {
|
|
const current = execution(currentRunId);
|
|
expect(rebindNativeSessionCheckpoint({ previousRun: withPolicy(policy, unsaved), currentExecution: current })).toBeNull();
|
|
const buildExecution = vi.fn(({ normalizedSessionId: sessionId, resumedSession }) => {
|
|
const built = execution(currentRunId);
|
|
built.session.normalizedSessionId = sessionId;
|
|
built.task.prompt = resumedSession ? "wake delta" : "original goal and complete handoff";
|
|
return built;
|
|
});
|
|
const result = buildNativeExecutionWithCheckpoint({ previousRun: withPolicy(policy, unsaved), normalizedSessionId, buildExecution });
|
|
expect(result.checkpoint).toBeNull();
|
|
expect(result.normalizedSessionId).not.toBe(normalizedSessionId);
|
|
expect(result.execution.task.prompt).toContain("complete handoff");
|
|
expect(result.execution.workspace).toEqual(current.workspace);
|
|
});
|
|
|
|
it.each(["resume_failure", "governed_wait", "same_session"] as const)(
|
|
"keeps the resume path for a record without the mark (%s policy)", (policy) => {
|
|
const expected = { resume_failure: "allow_replacement_after_resume_failure",
|
|
governed_wait: "allow_replacement_after_governed_wait", same_session: "same_session_only" }[policy];
|
|
// Records written before the mark existed, and runs whose backup saved.
|
|
for (const overrides of [{}, { [NATIVE_PROVIDER_STATE_UNSAVED_KEY]: null },
|
|
{ [NATIVE_PROVIDER_STATE_UNSAVED_KEY]: { code: "some_other_code" } }]) {
|
|
expect(rebindNativeSessionCheckpoint({ previousRun: withPolicy(policy, overrides), currentExecution: execution(currentRunId) }))
|
|
.toMatchObject({ providerRecoveryPolicy: expected, identity: { runId: currentRunId } });
|
|
}
|
|
});
|
|
});
|
|
|
|
it("wires exact-session recovery and guarded selected identity into heartbeat persistence", () => {
|
|
const source = readFileSync(
|
|
new URL("../heartbeat/runtime-selection.ts", import.meta.url),
|
|
"utf8",
|
|
);
|
|
expect(source).toContain("findNativeSessionResumeRun(db,");
|
|
expect(source).toContain(
|
|
"prepareNativeSessionBootstrapPersistence(tx,",
|
|
);
|
|
expect(source).toContain("nativeSessionId: persistedNativeSessionId,");
|
|
expect(source).toContain("lockedProfile.sessionCheckpoint != null");
|
|
const build = source.slice(
|
|
source.indexOf("const nativeExecutionWithCheckpoint ="),
|
|
source.indexOf("const nativeSandboxLifecycle ="),
|
|
);
|
|
expect(build).toContain("previousRun: previousNativeRun,");
|
|
});
|
|
|
|
const embeddedSupport = await getEmbeddedPostgresTestSupport();
|
|
const databaseSupported = Boolean(externalTestDatabaseUrl) || embeddedSupport.supported;
|
|
const recoveryFakeCodex = resolve(
|
|
import.meta.dirname,
|
|
"../../../../packages/paperclip-runner/test/fixtures/fake-final-burst-codex-app-server.mjs",
|
|
);
|
|
|
|
(databaseSupported && existsSync(defaultCapabilityRunnerdBinary())
|
|
? it
|
|
: it.skip)(
|
|
"keeps actual normalized driver events separate from raw maintenance receipts",
|
|
async () => {
|
|
const database = await startEmbeddedPostgresTestDatabase(
|
|
"native-cleanup-topology-",
|
|
);
|
|
const db = createDb(database.connectionString);
|
|
const scratch = await mkdtemp(join(tmpdir(), "native-cleanup-topology-"));
|
|
const root = join(scratch, "state");
|
|
const home = join(scratch, "home");
|
|
const workspace = join(scratch, "workspace");
|
|
const companyId = randomUUID(),
|
|
agentId = randomUUID(),
|
|
issueId = randomUUID(),
|
|
runId = randomUUID();
|
|
const runnerInstanceId = randomUUID(),
|
|
normalizedSessionId = randomUUID();
|
|
let session: NativeSession | undefined;
|
|
const signal = vi.spyOn(
|
|
publicationSignals,
|
|
"publishChatPublicationCommitSignal",
|
|
);
|
|
let bundle:
|
|
ReturnType<typeof createCapabilityRunnerdCodexTransport> | undefined;
|
|
try {
|
|
await mkdir(home);
|
|
await mkdir(workspace);
|
|
await db
|
|
.insert(companies)
|
|
.values({
|
|
id: companyId,
|
|
name: "Cleanup topology",
|
|
issuePrefix: "NCT",
|
|
});
|
|
await db
|
|
.insert(agents)
|
|
.values({
|
|
id: agentId,
|
|
companyId,
|
|
name: "Fixture",
|
|
status: "active",
|
|
adapterType: "paperclip_runner",
|
|
});
|
|
await db
|
|
.insert(issues)
|
|
.values({
|
|
id: issueId,
|
|
companyId,
|
|
title: "Exact topology",
|
|
assigneeAgentId: agentId,
|
|
status: "in_progress",
|
|
});
|
|
await db
|
|
.insert(heartbeatRuns)
|
|
.values({
|
|
id: runId,
|
|
companyId,
|
|
agentId,
|
|
status: "running",
|
|
runtimeMode: "native",
|
|
nativeIssueId: issueId,
|
|
nativeSessionId: normalizedSessionId,
|
|
runnerInstanceId,
|
|
});
|
|
bundle = createCapabilityRunnerdCodexTransport({
|
|
stateDirectory: root,
|
|
sourceCodexHome: home,
|
|
// The packaged runnerd does not imply local Rust test binaries exist.
|
|
// Reuse the credential-free provider fixture available in every checkout.
|
|
codexCommand: process.execPath,
|
|
codexArgs: [recoveryFakeCodex, join(scratch, "fake.json"), "16"],
|
|
prpIdentity: {
|
|
runId,
|
|
runnerInstanceId,
|
|
normalizedSessionId,
|
|
environmentLeaseId: runId,
|
|
turnId: `turn-${runId}`,
|
|
itemId: `item-${runId}`,
|
|
},
|
|
});
|
|
const backend = new HarnessDriverBackend(
|
|
new CodexAppServerDriver({
|
|
runnerInstanceId,
|
|
approvalPolicy: "never",
|
|
taskEnvelope: createCodexTaskEnvelope({
|
|
objective: "Open only the fixture session",
|
|
}),
|
|
transportFactory: () => bundle!.transport,
|
|
environment: { HOME: home, CODEX_HOME: home },
|
|
requireProviderSessionIdentity: true,
|
|
}),
|
|
);
|
|
session = await backend.openSession({
|
|
identity: {
|
|
companyId,
|
|
issueId,
|
|
agentId,
|
|
runId,
|
|
sessionId: normalizedSessionId,
|
|
},
|
|
workingDirectory: workspace,
|
|
});
|
|
const stream = session.events()[Symbol.asyncIterator]();
|
|
const normalized = (await stream.next()).value;
|
|
expect(normalized).toMatchObject({
|
|
sourceInstanceId: runnerInstanceId,
|
|
sourceSeq: 1,
|
|
});
|
|
expect(normalized.sourceEventId).toBe(`${runnerInstanceId}:${runId}:1`);
|
|
expect(normalized.payload).not.toHaveProperty("processId");
|
|
const port = new PaperclipControlPlanePort(db, {
|
|
companyId,
|
|
issueId,
|
|
agentId,
|
|
runId,
|
|
sessionId: normalizedSessionId,
|
|
sourceInstanceId: runnerInstanceId,
|
|
controlPlaneSourceInstanceId: `${runnerInstanceId}:control`,
|
|
completionContractId: randomUUID(),
|
|
completionContractSha256: "fixture-contract",
|
|
});
|
|
await port.appendEvent(normalized);
|
|
const original = await db
|
|
.select()
|
|
.from(heartbeatRunEvents)
|
|
.where(eq(heartbeatRunEvents.runId, runId));
|
|
expect(original).toHaveLength(1);
|
|
const control = JSON.parse(
|
|
await readFile(
|
|
join(root, "control-plane/control-plane-state.json"),
|
|
"utf8",
|
|
),
|
|
);
|
|
const raw = control.committedEvents
|
|
.map(
|
|
(entry: { envelope: { payload: Record<string, unknown> } }) =>
|
|
entry.envelope.payload,
|
|
)
|
|
.find((event: Record<string, unknown>) =>
|
|
["session.started", "session.resumed"].includes(
|
|
String(event.eventType),
|
|
),
|
|
);
|
|
expect(raw).toMatchObject({
|
|
sourceInstanceId: runnerInstanceId,
|
|
sourceSeq: 1,
|
|
payload: {
|
|
providerSessionId: normalized.payload.driverSessionId,
|
|
providerAccountSessionId: normalized.payload.providerSessionId,
|
|
},
|
|
});
|
|
expect(raw.payload.processId).toBeGreaterThan(0);
|
|
expect(raw.sourceEventId).not.toBe(normalized.sourceEventId);
|
|
// The original normalized seq=1 is already durable. Reusing that
|
|
// namespace for the raw wire seq=1 must remain an integrity violation.
|
|
await expect(port.appendEvent(raw)).rejects.toMatchObject({
|
|
code: "native_event_replay_conflict",
|
|
});
|
|
signal.mockClear();
|
|
const input = {
|
|
companyId,
|
|
agentId,
|
|
runId,
|
|
nativeSessionId: normalizedSessionId,
|
|
runnerInstanceId,
|
|
requestId: `fixture:${randomUUID()}`,
|
|
event: raw,
|
|
};
|
|
await appendRetainedNativeCleanupEvent(db, input);
|
|
await appendRetainedNativeCleanupEvent(db, input);
|
|
const rows = await db
|
|
.select()
|
|
.from(heartbeatRunEvents)
|
|
.where(eq(heartbeatRunEvents.runId, runId));
|
|
expect(rows).toHaveLength(2);
|
|
expect(rows.find((row) => row.id === original[0]!.id)).toEqual(
|
|
original[0],
|
|
);
|
|
const receipt = rows.find(
|
|
(row) => row.eventType === "native.cleanup.event",
|
|
)!;
|
|
expect(receipt.sourceSeq).toBe(1);
|
|
expect(receipt.sourceInstanceId).not.toBe(runnerInstanceId);
|
|
expect(receipt.payload).not.toHaveProperty("prpEvent");
|
|
expect(
|
|
Object.keys(
|
|
receipt.payload!.nativeCleanupEvent as Record<string, unknown>,
|
|
).sort(),
|
|
).toEqual([
|
|
"rawCanonicalSha256",
|
|
"rawEventType",
|
|
"rawSourceEventId",
|
|
"rawSourceInstanceId",
|
|
"rawSourceSeq",
|
|
"requestId",
|
|
"schema",
|
|
]);
|
|
await expect(
|
|
appendRetainedNativeCleanupEvent(db, {
|
|
...input,
|
|
event: {
|
|
...raw,
|
|
payload: {
|
|
...raw.payload,
|
|
privateData: "MUST_NOT_REACH_MAINTENANCE_RECEIPTS",
|
|
},
|
|
},
|
|
}),
|
|
).rejects.toMatchObject({ code: "native_event_replay_conflict" });
|
|
expect(
|
|
await db
|
|
.select()
|
|
.from(heartbeatRunEvents)
|
|
.where(eq(heartbeatRunEvents.runId, runId)),
|
|
).toHaveLength(2);
|
|
expect(JSON.stringify(receipt.payload)).not.toContain("MUST_NOT_REACH");
|
|
expect(signal).not.toHaveBeenCalled();
|
|
} finally {
|
|
signal.mockRestore();
|
|
await session
|
|
?.close({ reason: "Dispose exact test session" })
|
|
.catch(() => undefined);
|
|
await bundle?.transport.close().catch(() => undefined);
|
|
await database.cleanup();
|
|
await rm(scratch, { recursive: true, force: true });
|
|
}
|
|
},
|
|
30_000,
|
|
);
|
|
|
|
(databaseSupported &&
|
|
existsSync(defaultCapabilityRunnerdBinary()) &&
|
|
existsSync(recoveryFakeCodex)
|
|
? it
|
|
: it.skip)(
|
|
"archives a damaged prior epoch before completing guarded same-task replacement with real runnerd",
|
|
async () => {
|
|
const database = await startEmbeddedPostgresTestDatabase(
|
|
"native-damaged-resume-",
|
|
);
|
|
const db = createDb(database.connectionString);
|
|
const scratch = await mkdtemp(join(tmpdir(), "native-damaged-resume-"));
|
|
const stateBase = join(scratch, "sessions");
|
|
const bin = join(scratch, "bin");
|
|
const workspace = join(scratch, "workspace");
|
|
const sourceHome = join(scratch, "source-home");
|
|
const previousStateBase = process.env.PAPERCLIP_RUNNER_STATE_DIR;
|
|
const server = createServer();
|
|
let firstSession: NativeSession | undefined;
|
|
const ownedSessions = new Set<NativeSession>();
|
|
const ownedSpawns: Array<{ pid: number; processGroupId: number | null; startedAt: string }> = [];
|
|
const onSpawn = async (meta: typeof ownedSpawns[number]) => { ownedSpawns.push(meta); };
|
|
let executionCloseCompleted = false;
|
|
const runnerDiagnostics: string[] = [];
|
|
const onRunnerLog = async (_stream: "stdout" | "stderr", chunk: string) => {
|
|
runnerDiagnostics.push(chunk.slice(-4_096));
|
|
if (runnerDiagnostics.length > 32) runnerDiagnostics.shift();
|
|
};
|
|
// The production resolver prefers installed Codex over PATH. Explicitly
|
|
// bind this disposable fixture so it can never invoke a real provider.
|
|
const codexCommandResolver = await vi.importActual<{ resolveCodexCommand: () => string }>(
|
|
"../../../../packages/paperclip-runner/src/drivers/codex/codex-command.js",
|
|
);
|
|
const resolveFixtureCodex = vi.spyOn(codexCommandResolver, "resolveCodexCommand")
|
|
.mockReturnValue(join(bin, "codex"));
|
|
process.env.PAPERCLIP_RUNNER_STATE_DIR = stateBase;
|
|
try {
|
|
await Promise.all(
|
|
[bin, workspace, sourceHome].map((path) =>
|
|
mkdir(path, { recursive: true }),
|
|
),
|
|
);
|
|
// Only the provider boundary is synthetic; driver, runnerd, authority
|
|
// rotation, prior-owner DB checks and archive/replacement are real.
|
|
const quote = (value: string) => `'${value.replaceAll("'", "'\\''")}'`;
|
|
const command = join(bin, "codex");
|
|
await writeFile(
|
|
command,
|
|
`#!/bin/sh\nexec ${quote(process.execPath)} ${quote(recoveryFakeCodex)} "$CODEX_HOME/fake-state.json" 16\n`,
|
|
);
|
|
await chmod(command, 0o700);
|
|
await new Promise<void>((done) => server.listen(0, "127.0.0.1", done));
|
|
const address = server.address();
|
|
if (!address || typeof address === "string")
|
|
throw new Error("Missing test listener");
|
|
setupRunnerPrpWebSocketServer(server, {
|
|
apiUrl: `http://127.0.0.1:${address.port}`,
|
|
});
|
|
const makeExecution = (runId: string): NativeExecutionInput => {
|
|
const { runtimeContext: _runtimeContext, ...value } = execution(
|
|
runId,
|
|
workspace,
|
|
);
|
|
return {
|
|
...value,
|
|
schema: "paperclip.native-execution-input.v2",
|
|
provider: { kind: "codex", model: "gpt-5.6-luna" },
|
|
completionContract: {
|
|
...value.completionContract,
|
|
contract: {
|
|
revision: "burst-v1",
|
|
objective: "Complete a fresh response after guarded recovery",
|
|
criteria: [
|
|
{ id: "burst", requirement: "Complete the new response" },
|
|
],
|
|
},
|
|
},
|
|
};
|
|
};
|
|
const firstExecution = makeExecution(previousRunId);
|
|
const currentExecution = makeExecution(currentRunId);
|
|
expect(() => parseNativeExecutionInput(firstExecution)).not.toThrow();
|
|
const runnerInstanceId = randomUUID();
|
|
const environment = {
|
|
PATH: `${bin}:${process.env.PATH ?? "/usr/bin:/bin"}`,
|
|
HOME: sourceHome,
|
|
CODEX_HOME: sourceHome,
|
|
};
|
|
await db.insert(companies).values({
|
|
id: companyId,
|
|
name: "Damaged recovery",
|
|
issuePrefix: "DNR",
|
|
});
|
|
await db.insert(agents).values({
|
|
id: agentId,
|
|
companyId,
|
|
name: "Recovery runner",
|
|
status: "active",
|
|
adapterType: "paperclip_runner",
|
|
});
|
|
await db.insert(issues).values({
|
|
id: issueId,
|
|
companyId,
|
|
title: "Preserve the same task",
|
|
assigneeAgentId: agentId,
|
|
status: "in_progress",
|
|
});
|
|
await db.insert(completionContracts).values({
|
|
id: currentExecution.completionContract.id,
|
|
companyId,
|
|
issueId,
|
|
revision: 1,
|
|
schemaVersion: "paperclip.completion-contract.v1",
|
|
policyVersion: "damaged-recovery-v1",
|
|
risk: "standard",
|
|
completionAuthority: "server_arbiter",
|
|
incompleteCriteriaPolicy: "preserve_non_terminal",
|
|
contractJson: { ...currentExecution.completionContract.contract },
|
|
canonicalSha256: currentExecution.completionContract.sha256,
|
|
createdByActorType: "system",
|
|
createdByActorId: "test",
|
|
});
|
|
await db.insert(heartbeatRuns).values([
|
|
{
|
|
id: previousRunId,
|
|
companyId,
|
|
agentId,
|
|
status: "running",
|
|
runtimeMode: "native",
|
|
nativeIssueId: issueId,
|
|
nativeSessionId: normalizedSessionId,
|
|
runnerInstanceId,
|
|
completionContractId: firstExecution.completionContract.id,
|
|
completionContractSha256: firstExecution.completionContract.sha256,
|
|
runnerProfileJson: { nativeExecutionInput: firstExecution },
|
|
},
|
|
{
|
|
id: currentRunId,
|
|
companyId,
|
|
agentId,
|
|
status: "running",
|
|
runtimeMode: "native",
|
|
nativeIssueId: issueId,
|
|
nativeSessionId: normalizedSessionId,
|
|
runnerInstanceId,
|
|
completionContractId: currentExecution.completionContract.id,
|
|
completionContractSha256: currentExecution.completionContract.sha256,
|
|
runnerProfileJson: { nativeExecutionInput: currentExecution },
|
|
},
|
|
]);
|
|
const firstBackend = await createRunnerdBackend({
|
|
db,
|
|
execution: firstExecution,
|
|
runnerInstanceId,
|
|
runnerEnvironment: environment,
|
|
onLog: onRunnerLog,
|
|
onSpawn,
|
|
});
|
|
firstSession = await firstBackend.openSession({
|
|
identity: {
|
|
companyId,
|
|
issueId,
|
|
agentId,
|
|
runId: previousRunId,
|
|
sessionId: normalizedSessionId,
|
|
},
|
|
workingDirectory: workspace,
|
|
});
|
|
ownedSessions.add(firstSession);
|
|
const checkpoint = await firstSession.snapshot();
|
|
expect(checkpoint.identity).toEqual({
|
|
companyId,
|
|
issueId,
|
|
agentId,
|
|
runId: previousRunId,
|
|
sessionId: normalizedSessionId,
|
|
});
|
|
await firstSession.close({
|
|
reason: "Establish a suspended test-only historical root",
|
|
});
|
|
firstSession = undefined;
|
|
const [stateKey] = (await readdir(stateBase)).filter((name) =>
|
|
/^[a-f0-9]{64}$/.test(name),
|
|
);
|
|
expect(stateKey).toBeDefined();
|
|
const root = join(stateBase, stateKey!);
|
|
const runnerPath = join(root, "runner", "runner-state.json");
|
|
const providerPath = join(root, "runner", "codex-provider-state.json");
|
|
const runner = JSON.parse(await readFile(runnerPath, "utf8"));
|
|
const provider = JSON.parse(await readFile(providerPath, "utf8"));
|
|
expect(runner.lifecycle).toBe("suspended");
|
|
|
|
// Reproduce only in a generated disposable root the historical failure:
|
|
// an unacknowledged input whose digest predates bounded sanitization.
|
|
const badPayload = {
|
|
semantic_tool: {
|
|
schema: "paperclip.prp.semantic_tool.v1",
|
|
schemaVersion: 1,
|
|
phase: "input",
|
|
input: { summary: "bounded historical answer" },
|
|
content: { digest: `sha256:${"0".repeat(64)}` },
|
|
},
|
|
};
|
|
const envelope = {
|
|
protocol: "paperclip.runner",
|
|
version: 1,
|
|
kind: "event",
|
|
runnerInstanceId: runner.runnerInstanceId,
|
|
environmentLeaseId: runner.environmentLeaseId,
|
|
runId: previousRunId,
|
|
normalizedSessionId,
|
|
turnId: runner.turnId,
|
|
itemId: runner.itemId,
|
|
payload: {
|
|
schema: "paperclip.prp.event.v1",
|
|
sourceEventId: "historical-bad-input-44",
|
|
sourceSeq: 44,
|
|
sourceInstanceId: runner.runnerInstanceId,
|
|
sourceKind: "runner",
|
|
runId: previousRunId,
|
|
normalizedSessionId,
|
|
turnId: runner.turnId,
|
|
itemId: runner.itemId,
|
|
eventType: "semantic_tool.input",
|
|
schemaVersion: 1,
|
|
priority: 0,
|
|
emittedAt: "2026-09-08T00:00:00.000Z",
|
|
payload: badPayload,
|
|
},
|
|
};
|
|
runner.ackedSourceSeq = 43;
|
|
runner.nextSourceSeq = 45;
|
|
runner.outbox = [
|
|
{
|
|
sourceSeq: 44,
|
|
priority: 0,
|
|
eventType: "semantic_tool.input",
|
|
envelope,
|
|
byteSize: Buffer.byteLength(JSON.stringify(envelope)),
|
|
},
|
|
];
|
|
provider.pendingEvents = [
|
|
{
|
|
executorEventId: "codex_provider_0000000000000044",
|
|
eventType: "semantic_tool.input",
|
|
priority: "p0",
|
|
payload: badPayload,
|
|
},
|
|
];
|
|
provider.nextProviderEventSeq = 45;
|
|
await writeFile(runnerPath, JSON.stringify(runner));
|
|
await writeFile(providerPath, JSON.stringify(provider));
|
|
const damagedRunnerBytes = await readFile(runnerPath);
|
|
const damagedProviderBytes = await readFile(providerPath);
|
|
await expect(
|
|
createRunnerdBackend({
|
|
db,
|
|
execution: currentExecution,
|
|
runnerInstanceId,
|
|
runnerEnvironment: environment,
|
|
}),
|
|
).rejects.toThrow("runner_state_identity_mismatch");
|
|
expect(await readFile(runnerPath, "utf8")).toBe(
|
|
damagedRunnerBytes.toString(),
|
|
);
|
|
expect(await readdir(root)).not.toContain("authority-epochs");
|
|
const source = previousRun({
|
|
nativeExecutionInput: firstExecution,
|
|
sessionCheckpoint: checkpoint,
|
|
});
|
|
await db
|
|
.update(heartbeatRuns)
|
|
.set({ status: "failed", runnerProfileJson: source.runnerProfileJson })
|
|
.where(eq(heartbeatRuns.id, previousRunId));
|
|
const selected = await findNativeSessionResumeRun(db, {
|
|
companyId,
|
|
agentId,
|
|
issueId,
|
|
normalizedSessionId,
|
|
currentRunId,
|
|
beforeCreatedAt: new Date(),
|
|
});
|
|
expect(selected?.id).toBe(previousRunId);
|
|
const rebound = rebindNativeSessionCheckpoint({
|
|
previousRun: selected!,
|
|
currentExecution,
|
|
});
|
|
expect(rebound).toMatchObject({
|
|
cursor: null,
|
|
semanticResult: null,
|
|
activeTurnId: null,
|
|
providerRecoveryPolicy: "allow_replacement_after_resume_failure",
|
|
});
|
|
expect(rebound?.identity).toEqual({
|
|
companyId,
|
|
issueId,
|
|
agentId,
|
|
runId: currentRunId,
|
|
sessionId: normalizedSessionId,
|
|
});
|
|
|
|
const backend = await createRunnerdBackend({
|
|
db,
|
|
execution: currentExecution,
|
|
runnerInstanceId,
|
|
runnerEnvironment: environment,
|
|
onLog: onRunnerLog,
|
|
onSpawn,
|
|
});
|
|
let continuity: Record<string, unknown> | undefined;
|
|
const controlPlaneInstanceId = randomUUID();
|
|
const port = new PaperclipControlPlanePort(db, {
|
|
companyId,
|
|
issueId,
|
|
runId: currentRunId,
|
|
agentId,
|
|
sessionId: normalizedSessionId,
|
|
completionContractId: currentExecution.completionContract.id,
|
|
completionContractSha256: currentExecution.completionContract.sha256,
|
|
sourceInstanceId: runnerInstanceId,
|
|
controlPlaneSourceInstanceId: controlPlaneInstanceId,
|
|
});
|
|
await expect(
|
|
executeNativeSession({
|
|
input: currentExecution,
|
|
backend,
|
|
persistedSession: rebound!,
|
|
runnerInstanceId,
|
|
controlPlaneInstanceId,
|
|
timeoutMs: 20_000,
|
|
// This disposable real-daemon fixture must join full retirement before
|
|
// removing its controller routes and durable state. The production
|
|
// default deliberately permits asynchronous cleanup after a result.
|
|
requireSessionCloseBeforeReturn: true,
|
|
onSession(value) { if (value) ownedSessions.add(value); },
|
|
async onSessionClosed() { executionCloseCompleted = true; },
|
|
controlPlane: port,
|
|
async onContinuityBreak(value) {
|
|
continuity = value;
|
|
},
|
|
}).then((result) => {
|
|
if (result.terminal.runTerminalState !== "succeeded") {
|
|
throw new Error(`Disposable recovery fixture failed: ${JSON.stringify(result)}`);
|
|
}
|
|
return result;
|
|
}).catch(async (error: unknown) => {
|
|
const eventRows = await db
|
|
.select({
|
|
eventType: heartbeatRunEvents.eventType,
|
|
payload: heartbeatRunEvents.payload,
|
|
})
|
|
.from(heartbeatRunEvents)
|
|
.where(eq(heartbeatRunEvents.runId, currentRunId));
|
|
const eventCodes = eventRows.slice(-32).map((event) => ({
|
|
eventType: event.eventType,
|
|
code: event.payload?.code ?? null,
|
|
}));
|
|
const fakeProvider = await readFile(
|
|
join(root, "codex-home", "fake-state.json"),
|
|
"utf8",
|
|
).then(JSON.parse, () => null);
|
|
throw new Error(
|
|
`${error instanceof Error ? error.message : String(error)}\nDisposable recovery fixture runner diagnostics:\n${runnerDiagnostics.join("").slice(-12_000)}\nPersisted event codes: ${JSON.stringify(eventCodes)}\nFake provider state: ${JSON.stringify(fakeProvider)}`,
|
|
{ cause: error },
|
|
);
|
|
}),
|
|
).resolves.toMatchObject({
|
|
result: {
|
|
summary: "Fixture complete.",
|
|
reportedWorkDisposition: "done",
|
|
},
|
|
terminal: { runTerminalState: "succeeded" },
|
|
normalizedSessionId,
|
|
});
|
|
expect(executionCloseCompleted).toBe(true);
|
|
expect(ownedSpawns.length).toBeGreaterThanOrEqual(2);
|
|
for (const { pid } of ownedSpawns) {
|
|
expect(() => process.kill(pid, 0)).toThrow(expect.objectContaining({ code: "ESRCH" }));
|
|
}
|
|
console.info("Recovery fixture retired owned daemons", ownedSpawns);
|
|
expect(continuity).toMatchObject({
|
|
// The daemon can reject the damaged retained input during startup,
|
|
// before attach gets a chance to reject the unsettled provider session.
|
|
// Both refusal paths must preserve the exact archived evidence below.
|
|
reason: expect.stringMatching(
|
|
/run\.attach requires a settled Codex provider session|semantic tool input content digest does not match its transmitted input/,
|
|
),
|
|
previousDriverSessionId: checkpoint.sessionId,
|
|
});
|
|
const [epoch] = await readdir(join(root, "authority-epochs"));
|
|
const digest = (value: Buffer) =>
|
|
createHash("sha256").update(value).digest("hex");
|
|
expect(
|
|
digest(
|
|
await readFile(
|
|
join(root, "authority-epochs", epoch!, "runner-state.json"),
|
|
),
|
|
),
|
|
).toBe(digest(damagedRunnerBytes));
|
|
const [continuityArchive] = await readdir(
|
|
join(root, "continuity-breaks"),
|
|
);
|
|
const archivedProvider = JSON.parse(
|
|
await readFile(
|
|
join(
|
|
root,
|
|
"continuity-breaks",
|
|
continuityArchive!,
|
|
"runner",
|
|
"codex-provider-state.json",
|
|
),
|
|
"utf8",
|
|
),
|
|
);
|
|
// Restoration may append a lifecycle notice, but must neither consume
|
|
// nor rewrite the old semantic input to make attachment succeed.
|
|
expect(
|
|
archivedProvider.pendingEvents.filter(
|
|
(event: { eventType: string }) =>
|
|
event.eventType === "semantic_tool.input",
|
|
),
|
|
).toEqual(JSON.parse(damagedProviderBytes.toString()).pendingEvents);
|
|
const completedProvider = JSON.parse(
|
|
await readFile(join(root, "codex-home", "fake-state.json"), "utf8"),
|
|
);
|
|
expect(completedProvider.nextTurn).toBe(1);
|
|
expect(completedProvider.turns["final-burst-turn-1"]).toMatchObject({
|
|
status: "completed",
|
|
deltaCount: 16,
|
|
});
|
|
const priorProvider = JSON.parse(
|
|
await readFile(
|
|
join(
|
|
root,
|
|
"continuity-breaks",
|
|
continuityArchive!,
|
|
"codex-home",
|
|
"fake-state.json",
|
|
),
|
|
"utf8",
|
|
),
|
|
);
|
|
expect(priorProvider.nextTurn).toBe(0);
|
|
const results = await db
|
|
.select()
|
|
.from(nativeRunResults)
|
|
.where(eq(nativeRunResults.runId, currentRunId));
|
|
expect(results).toHaveLength(1);
|
|
// Prove the maintenance anchor against an actual completed composition:
|
|
// the DB owns normalized driver events and the accepted result, whereas
|
|
// the retained controller owns distinct raw provider/tool event IDs.
|
|
const [completedRun] = await db
|
|
.select()
|
|
.from(heartbeatRuns)
|
|
.where(eq(heartbeatRuns.id, currentRunId));
|
|
const anchorEvents = await db
|
|
.select()
|
|
.from(heartbeatRunEvents)
|
|
.where(eq(heartbeatRunEvents.runId, currentRunId));
|
|
const control = JSON.parse(
|
|
await readFile(
|
|
join(root, "control-plane", "control-plane-state.json"),
|
|
"utf8",
|
|
),
|
|
);
|
|
const rawIdentity = control.committedEvents
|
|
.map(
|
|
(entry: { envelope: { payload: Record<string, unknown> } }) =>
|
|
entry.envelope.payload,
|
|
)
|
|
.find((event: Record<string, unknown>) =>
|
|
["session.started", "session.resumed"].includes(
|
|
String(event.eventType),
|
|
),
|
|
);
|
|
expect(rawIdentity).toBeDefined();
|
|
expect(
|
|
retainedNativeCleanupJournalMatches({
|
|
run: completedRun!,
|
|
execution: currentExecution,
|
|
accepted: results[0]!,
|
|
control,
|
|
providerSessionId: rawIdentity.payload.providerSessionId,
|
|
providerAccountSessionId:
|
|
rawIdentity.payload.providerAccountSessionId,
|
|
persistedEvents: anchorEvents,
|
|
}),
|
|
).toBe(true);
|
|
expect(results[0]).toMatchObject({
|
|
companyId,
|
|
issueId,
|
|
runId: currentRunId,
|
|
schemaStatus: "accepted",
|
|
resultJson: {
|
|
result: { summary: "Fixture complete." },
|
|
terminal: { runTerminalState: "succeeded" },
|
|
},
|
|
});
|
|
const sourceResults = await db
|
|
.select({ id: nativeRunResults.id })
|
|
.from(nativeRunResults)
|
|
.where(eq(nativeRunResults.runId, previousRunId));
|
|
expect(sourceResults).toHaveLength(0);
|
|
const persistedEvents = await db
|
|
.select({ sourceEventId: heartbeatRunEvents.sourceEventId })
|
|
.from(heartbeatRunEvents)
|
|
.where(eq(heartbeatRunEvents.runId, currentRunId));
|
|
expect(persistedEvents.length).toBeGreaterThan(0);
|
|
expect(persistedEvents.map((event) => event.sourceEventId)).not.toContain(
|
|
"historical-bad-input-44",
|
|
);
|
|
const [task] = await db
|
|
.select({ id: issues.id, assigneeAgentId: issues.assigneeAgentId })
|
|
.from(issues)
|
|
.where(eq(issues.id, issueId));
|
|
expect(task).toEqual({ id: issueId, assigneeAgentId: agentId });
|
|
} finally {
|
|
// onSession(null) quarantines the runtime owner before close finishes;
|
|
// keep every published handle so an assertion/error cannot lose cleanup.
|
|
if (firstSession) ownedSessions.add(firstSession);
|
|
const closed = await Promise.allSettled([...ownedSessions].map((session) =>
|
|
Promise.resolve().then(() => session.close({ reason: "Recovery fixture cleanup" })),
|
|
));
|
|
const closeFailures = closed.filter((result) => result.status === "rejected");
|
|
resolveFixtureCodex.mockRestore();
|
|
runnerPrpWebSocketInternals.resetForTests();
|
|
server.closeAllConnections();
|
|
await new Promise<void>((done) => server.close(() => done()));
|
|
if (previousStateBase === undefined)
|
|
delete process.env.PAPERCLIP_RUNNER_STATE_DIR;
|
|
else process.env.PAPERCLIP_RUNNER_STATE_DIR = previousStateBase;
|
|
await database.cleanup();
|
|
if (closeFailures.length) {
|
|
// Retain exact fixture state if owned retirement cannot be proven.
|
|
throw new AggregateError(closeFailures.map((result) => result.reason), "Recovery fixture session cleanup failed");
|
|
}
|
|
await rm(scratch, { recursive: true, force: true });
|
|
}
|
|
},
|
|
60_000,
|
|
);
|
|
|
|
(databaseSupported ? describe : describe.skip)(
|
|
"native session recovery database orchestration",
|
|
() => {
|
|
it.each(["accepted", "no_result", "rejected", "backup_current"] as const)(
|
|
"marks the checkpoint not resumable only after an accepted result (%s)", async (outcome) => {
|
|
const database = await startEmbeddedPostgresTestDatabase("paperclip-native-unsaved-state-");
|
|
const db = createDb(database.connectionString);
|
|
try {
|
|
await db.insert(companies).values({ id: companyId, name: "Unsaved provider state", issuePrefix: "NPS" });
|
|
await db.insert(agents).values({ id: agentId, companyId, name: "Native runner" });
|
|
await db.insert(issues).values({ id: issueId, companyId, title: "Keep the task" });
|
|
const source = previousRun();
|
|
const sourceExecution = source.runnerProfileJson.nativeExecutionInput;
|
|
await db.insert(completionContracts).values({ id: sourceExecution.completionContract.id, companyId, issueId,
|
|
revision: 1, schemaVersion: "paperclip.completion-contract.v1", policyVersion: "unsaved-state-v1", risk: "standard",
|
|
completionAuthority: "server_arbiter", incompleteCriteriaPolicy: "preserve_non_terminal",
|
|
contractJson: { ...sourceExecution.completionContract.contract }, canonicalSha256: sourceExecution.completionContract.sha256,
|
|
createdByActorType: "system", createdByActorId: "test" });
|
|
const resultJson = { result: { summary: "Done." }, terminal: { runTerminalState: "succeeded" } };
|
|
await db.insert(heartbeatRuns).values({ id: previousRunId, companyId, agentId, status: "succeeded",
|
|
runtimeMode: "native", nativeIssueId: issueId, nativeSessionId: normalizedSessionId, runnerInstanceId: randomUUID(),
|
|
completionContractId: sourceExecution.completionContract.id, completionContractSha256: sourceExecution.completionContract.sha256,
|
|
createdAt: new Date(Date.UTC(2026, 10, 11, 0, 0, 0)), resultJson, runnerProfileJson: source.runnerProfileJson });
|
|
const resultId = randomUUID();
|
|
if (outcome !== "no_result") await db.insert(nativeRunResults).values({ id: resultId, companyId, issueId, runId: previousRunId,
|
|
completionContractId: sourceExecution.completionContract.id, serverFingerprint: "test",
|
|
schemaStatus: outcome === "rejected" ? "rejected" : "accepted", resultJson, canonicalSha256: "a".repeat(64) });
|
|
await db.insert(nativeRunFinalizations).values({ runId: previousRunId, companyId, issueId,
|
|
phase: outcome === "accepted" || outcome === "backup_current" ? "committed" : "observed",
|
|
resultId: outcome === "no_result" ? null : resultId });
|
|
// The durable backup became current before a later step failed.
|
|
if (outcome === "backup_current") await db.insert(nativeHarnessBackups).values({ companyId, issueId, runId: previousRunId,
|
|
scopeDigest: "b".repeat(64), manifestSha256: `sha256:${"c".repeat(64)}`, status: "current", reference: {} });
|
|
const binding = { companyId, issueId, runId: previousRunId };
|
|
const selection = { companyId, agentId, issueId, normalizedSessionId, currentRunId,
|
|
beforeCreatedAt: new Date(Date.UTC(2026, 10, 11, 0, 1, 0)) };
|
|
const [before] = await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.id, previousRunId));
|
|
|
|
expect(await markAcceptedRunProviderStateUnsaved(db, binding)).toBe(outcome === "accepted");
|
|
const [after] = await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.id, previousRunId));
|
|
// The accepted result and the run outcome are untouched.
|
|
expect({ ...after, runnerProfileJson: null }).toEqual({ ...before, runnerProfileJson: null });
|
|
const selected = await findNativeSessionResumeRun(db, selection);
|
|
expect(selected?.id).toBe(previousRunId);
|
|
const rebound = rebindNativeSessionCheckpoint({ previousRun: selected!, currentExecution: execution(currentRunId) });
|
|
if (outcome === "accepted") {
|
|
expect(after.runnerProfileJson).toMatchObject({ ...source.runnerProfileJson,
|
|
[NATIVE_PROVIDER_STATE_UNSAVED_KEY]: { code: NATIVE_PROVIDER_STATE_INCOMPATIBLE, reason: "harness_backup_not_saved" } });
|
|
expect(rebound).toBeNull();
|
|
// A later save of the same run's state restores the resume path.
|
|
await clearRunProviderStateUnsaved(db, binding);
|
|
const restored = await findNativeSessionResumeRun(db, selection);
|
|
expect(rebindNativeSessionCheckpoint({ previousRun: restored!, currentExecution: execution(currentRunId) }))
|
|
.toMatchObject({ providerRecoveryPolicy: "allow_replacement_after_resume_failure" });
|
|
} else {
|
|
// A failure before acceptance, or after the backup became current, keeps today's path.
|
|
expect(after.runnerProfileJson).toEqual(before.runnerProfileJson);
|
|
expect(rebound).toMatchObject({ providerRecoveryPolicy: "allow_replacement_after_resume_failure" });
|
|
}
|
|
} finally {
|
|
await database.cleanup();
|
|
}
|
|
}, 60_000);
|
|
|
|
it("uses scoped latest checkpoints, preserves progress barriers, and guards bootstrap persistence after the row lock", async () => {
|
|
const database = await startEmbeddedPostgresTestDatabase(
|
|
"paperclip-native-resume-selection-",
|
|
);
|
|
const db = createDb(database.connectionString);
|
|
try {
|
|
const otherCompany = randomUUID(),
|
|
otherAgent = randomUUID(),
|
|
otherIssue = randomUUID();
|
|
await db.insert(companies).values([
|
|
{ id: companyId, name: "Session recovery", issuePrefix: "NRS" },
|
|
{ id: otherCompany, name: "Other company", issuePrefix: "OTHER" },
|
|
]);
|
|
await db.insert(agents).values([
|
|
{ id: agentId, companyId, name: "Native runner" },
|
|
{ id: otherAgent, companyId: otherCompany, name: "Other agent" },
|
|
]);
|
|
await db.insert(issues).values([
|
|
{ id: issueId, companyId, title: "Retain this task" },
|
|
{ id: otherIssue, companyId, title: "Other task" },
|
|
]);
|
|
const at = (second: number) =>
|
|
new Date(Date.UTC(2026, 8, 8, 0, 0, second));
|
|
const source = {
|
|
...previousRun(),
|
|
runtimeMode: "native",
|
|
nativeIssueId: issueId,
|
|
status: "failed",
|
|
createdAt: at(0),
|
|
runnerInstanceId: randomUUID(),
|
|
};
|
|
const unused = {
|
|
companyId,
|
|
agentId,
|
|
runtimeMode: "native",
|
|
nativeIssueId: issueId,
|
|
nativeSessionId: normalizedSessionId,
|
|
status: "failed",
|
|
runnerProfileJson: {},
|
|
};
|
|
const bootstrapId = randomUUID();
|
|
const futureId = randomUUID();
|
|
await db.insert(heartbeatRuns).values([
|
|
source,
|
|
{ ...unused, id: bootstrapId, createdAt: at(2) },
|
|
{
|
|
...unused,
|
|
id: currentRunId,
|
|
status: "running",
|
|
createdAt: at(10),
|
|
},
|
|
{
|
|
...unused,
|
|
id: randomUUID(),
|
|
companyId: otherCompany,
|
|
createdAt: at(3),
|
|
status: "running",
|
|
},
|
|
{
|
|
...unused,
|
|
id: randomUUID(),
|
|
agentId: otherAgent,
|
|
createdAt: at(4),
|
|
status: "running",
|
|
},
|
|
{
|
|
...unused,
|
|
id: randomUUID(),
|
|
nativeIssueId: otherIssue,
|
|
createdAt: at(5),
|
|
status: "running",
|
|
},
|
|
{
|
|
...unused,
|
|
id: randomUUID(),
|
|
nativeSessionId: randomUUID(),
|
|
createdAt: at(6),
|
|
status: "running",
|
|
},
|
|
{
|
|
...unused,
|
|
id: futureId,
|
|
createdAt: at(11),
|
|
},
|
|
]);
|
|
const selection = {
|
|
companyId,
|
|
agentId,
|
|
issueId,
|
|
normalizedSessionId,
|
|
currentRunId,
|
|
beforeCreatedAt: at(10),
|
|
};
|
|
expect((await findNativeSessionResumeRun(db, selection))?.id).toBe(
|
|
previousRunId,
|
|
);
|
|
await db
|
|
.update(heartbeatRuns)
|
|
.set({ runnerProfileJson: source.runnerProfileJson })
|
|
.where(eq(heartbeatRuns.id, futureId));
|
|
expect(await findNativeSessionResumeRun(db, selection)).toBeNull();
|
|
await db
|
|
.update(heartbeatRuns)
|
|
.set({ runnerProfileJson: {}, status: "running" })
|
|
.where(eq(heartbeatRuns.id, futureId));
|
|
expect(await findNativeSessionResumeRun(db, selection)).toBeNull();
|
|
await db
|
|
.update(heartbeatRuns)
|
|
.set({ status: "failed" })
|
|
.where(eq(heartbeatRuns.id, futureId));
|
|
expect((await findNativeSessionResumeRun(db, selection))?.id).toBe(
|
|
previousRunId,
|
|
);
|
|
await db.insert(heartbeatRunEvents).values({
|
|
companyId,
|
|
agentId,
|
|
runId: bootstrapId,
|
|
seq: 1,
|
|
eventType: "session.started",
|
|
});
|
|
expect(await findNativeSessionResumeRun(db, selection)).toBeNull();
|
|
const incompatibleId = randomUUID();
|
|
await db.insert(heartbeatRuns).values({
|
|
...unused,
|
|
id: incompatibleId,
|
|
createdAt: at(7),
|
|
runnerProfileJson: {
|
|
...source.runnerProfileJson,
|
|
nativeToolContractFingerprint: "stale",
|
|
},
|
|
});
|
|
const incompatible = await findNativeSessionResumeRun(db, selection);
|
|
expect(incompatible?.id).toBe(incompatibleId);
|
|
expect(
|
|
rebindNativeSessionCheckpoint({
|
|
previousRun: incompatible!,
|
|
currentExecution: execution(currentRunId),
|
|
}),
|
|
).toBeNull();
|
|
// A run whose saved provider session the runner proved unrestorable
|
|
// stays the barrier, and its checkpoint is not resumed.
|
|
const unrestorableId = randomUUID();
|
|
const sourceCheckpoint = source.runnerProfileJson.sessionCheckpoint;
|
|
await db.insert(heartbeatRuns).values({
|
|
...unused,
|
|
id: unrestorableId,
|
|
createdAt: at(8),
|
|
errorCode: NATIVE_PROVIDER_STATE_INCOMPATIBLE,
|
|
runnerProfileJson: {
|
|
...source.runnerProfileJson,
|
|
nativeExecutionInput: execution(unrestorableId),
|
|
sessionCheckpoint: {
|
|
...sourceCheckpoint,
|
|
identity: { ...sourceCheckpoint.identity, runId: unrestorableId },
|
|
},
|
|
},
|
|
});
|
|
const unrestorable = await findNativeSessionResumeRun(db, selection);
|
|
expect(unrestorable).toMatchObject({
|
|
id: unrestorableId,
|
|
errorCode: NATIVE_PROVIDER_STATE_INCOMPATIBLE,
|
|
});
|
|
expect(
|
|
rebindNativeSessionCheckpoint({
|
|
previousRun: { ...unrestorable!, errorCode: null },
|
|
currentExecution: execution(currentRunId),
|
|
}),
|
|
).not.toBeNull();
|
|
expect(
|
|
rebindNativeSessionCheckpoint({
|
|
previousRun: unrestorable!,
|
|
currentExecution: execution(currentRunId),
|
|
}),
|
|
).toBeNull();
|
|
|
|
const fresh = buildNativeExecutionWithCheckpoint({
|
|
previousRun: null,
|
|
normalizedSessionId,
|
|
buildExecution: ({ normalizedSessionId: selected }) => {
|
|
const current = execution(currentRunId);
|
|
return {
|
|
...current,
|
|
session: { ...current.session, normalizedSessionId: selected },
|
|
};
|
|
},
|
|
});
|
|
await db.transaction(async (tx) => {
|
|
const [locked] = await tx
|
|
.select()
|
|
.from(heartbeatRuns)
|
|
.where(eq(heartbeatRuns.id, currentRunId))
|
|
.for("update");
|
|
const selected = await prepareNativeSessionBootstrapPersistence(tx, {
|
|
run: locked,
|
|
selectedSessionId: fresh.normalizedSessionId,
|
|
execution: fresh.execution,
|
|
restoringCheckpoint: false,
|
|
});
|
|
await tx
|
|
.update(heartbeatRuns)
|
|
.set({
|
|
nativeSessionId: selected,
|
|
runnerProfileJson: { nativeExecutionInput: fresh.execution },
|
|
})
|
|
.where(eq(heartbeatRuns.id, locked.id));
|
|
});
|
|
const [persisted] = await db
|
|
.select()
|
|
.from(heartbeatRuns)
|
|
.where(eq(heartbeatRuns.id, currentRunId));
|
|
expect(persisted.nativeSessionId).toBe(fresh.normalizedSessionId);
|
|
expect(persisted.nativeSessionId).not.toBe(normalizedSessionId);
|
|
await expect(
|
|
db.transaction(async (tx) => {
|
|
const [locked] = await tx
|
|
.select()
|
|
.from(heartbeatRuns)
|
|
.where(eq(heartbeatRuns.id, currentRunId))
|
|
.for("update");
|
|
return prepareNativeSessionBootstrapPersistence(tx, {
|
|
run: locked,
|
|
selectedSessionId: fresh.normalizedSessionId,
|
|
execution: fresh.execution,
|
|
restoringCheckpoint: false,
|
|
});
|
|
}),
|
|
).resolves.toBe(fresh.normalizedSessionId);
|
|
await expect(
|
|
db.transaction(async (tx) => {
|
|
const [locked] = await tx
|
|
.select()
|
|
.from(heartbeatRuns)
|
|
.where(eq(heartbeatRuns.id, currentRunId))
|
|
.for("update");
|
|
const changedExecution = structuredClone(fresh.execution);
|
|
changedExecution.task.prompt = "Changed admission";
|
|
return prepareNativeSessionBootstrapPersistence(tx, {
|
|
run: locked,
|
|
selectedSessionId: fresh.normalizedSessionId,
|
|
execution: changedExecution,
|
|
restoringCheckpoint: false,
|
|
});
|
|
}),
|
|
).rejects.toThrow("native_execution_input_persisted_binding_mismatch");
|
|
const [preserved] = await db
|
|
.select()
|
|
.from(heartbeatRuns)
|
|
.where(eq(heartbeatRuns.id, previousRunId));
|
|
expect(preserved.runnerProfileJson).toEqual(source.runnerProfileJson);
|
|
|
|
const lateId = randomUUID();
|
|
await db
|
|
.insert(heartbeatRuns)
|
|
.values({ ...unused, id: lateId, createdAt: at(11) });
|
|
expect((await nativeSessionProviderEvidence(db, [lateId])).size).toBe(
|
|
0,
|
|
);
|
|
let unlock!: () => void;
|
|
let locked!: () => void;
|
|
const lockAcquired = new Promise<void>((resolve) => {
|
|
locked = resolve;
|
|
});
|
|
const release = new Promise<void>((resolve) => {
|
|
unlock = resolve;
|
|
});
|
|
const writer = db.transaction(async (tx) => {
|
|
await tx
|
|
.select()
|
|
.from(heartbeatRuns)
|
|
.where(eq(heartbeatRuns.id, lateId))
|
|
.for("update");
|
|
locked();
|
|
await release;
|
|
await tx.insert(heartbeatRunEvents).values({
|
|
companyId,
|
|
agentId,
|
|
runId: lateId,
|
|
seq: 1,
|
|
eventType: "session.started",
|
|
});
|
|
});
|
|
let attempt: Promise<unknown> | undefined;
|
|
try {
|
|
await lockAcquired;
|
|
const applicationName = `native-resume-lock-${randomUUID()}`;
|
|
attempt = db
|
|
.transaction(async (tx) => {
|
|
await tx.execute(
|
|
sql`select set_config('application_name', ${applicationName}, true)`,
|
|
);
|
|
const [row] = await tx
|
|
.select()
|
|
.from(heartbeatRuns)
|
|
.where(eq(heartbeatRuns.id, lateId))
|
|
.for("update");
|
|
return prepareNativeSessionBootstrapPersistence(tx, {
|
|
run: row,
|
|
selectedSessionId: randomUUID(),
|
|
execution: execution(lateId),
|
|
restoringCheckpoint: false,
|
|
});
|
|
})
|
|
.then(
|
|
() => null,
|
|
(error: unknown) => error,
|
|
);
|
|
await expect
|
|
.poll(async () => {
|
|
const rows = await db.execute<{ blocked: boolean }>(sql`
|
|
select exists (
|
|
select 1 from pg_stat_activity
|
|
where application_name = ${applicationName}
|
|
and wait_event_type = 'Lock'
|
|
and cardinality(pg_blocking_pids(pid)) > 0
|
|
) as blocked
|
|
`);
|
|
return rows[0]?.blocked;
|
|
})
|
|
.toBe(true);
|
|
unlock();
|
|
await writer;
|
|
expect(await attempt).toMatchObject({
|
|
message: "native_session_bootstrap_identity_conflict",
|
|
});
|
|
const [unchanged] = await db
|
|
.select()
|
|
.from(heartbeatRuns)
|
|
.where(eq(heartbeatRuns.id, lateId));
|
|
expect(unchanged.nativeSessionId).toBe(normalizedSessionId);
|
|
} finally {
|
|
unlock();
|
|
await Promise.all([writer, attempt]);
|
|
}
|
|
} finally {
|
|
await database.cleanup();
|
|
}
|
|
}, 60_000);
|
|
},
|
|
);
|
|
|
|
describe("rebindNativeSessionCheckpoint", () => {
|
|
it("rotates a carried session id when no checkpoint source exists", () => {
|
|
const calls: boolean[] = [];
|
|
const result = buildNativeExecutionWithCheckpoint({
|
|
previousRun: null,
|
|
normalizedSessionId,
|
|
buildExecution: (options) => {
|
|
calls.push(options.resumedSession);
|
|
const current = execution(currentRunId);
|
|
return {
|
|
...current,
|
|
session: {
|
|
...current.session,
|
|
normalizedSessionId: options.normalizedSessionId,
|
|
},
|
|
task: {
|
|
...current.task,
|
|
prompt: options.resumedSession
|
|
? "Compact delta"
|
|
: "Full task context",
|
|
},
|
|
};
|
|
},
|
|
});
|
|
expect(calls.every((resumed) => !resumed)).toBe(true);
|
|
expect(result.checkpoint).toBeNull();
|
|
expect(result.normalizedSessionId).not.toBe(normalizedSessionId);
|
|
expect(result.execution.session.normalizedSessionId).toBe(
|
|
result.normalizedSessionId,
|
|
);
|
|
expect(result.execution.task.prompt).toBe("Full task context");
|
|
expect(
|
|
nativeSessionIdForBootstrapPersistence({
|
|
run: {
|
|
nativeSessionId: normalizedSessionId,
|
|
processPid: null,
|
|
processGroupId: null,
|
|
processStartedAt: null,
|
|
runnerProfileJson: {},
|
|
},
|
|
selectedSessionId: result.normalizedSessionId,
|
|
hasProviderEvents: false,
|
|
}),
|
|
).toBe(result.normalizedSessionId);
|
|
});
|
|
|
|
it("does not rotate an admitted or authority-bearing session id", () => {
|
|
const unused = {
|
|
nativeSessionId: normalizedSessionId,
|
|
processPid: null,
|
|
processGroupId: null,
|
|
processStartedAt: null,
|
|
runnerProfileJson: {},
|
|
};
|
|
for (const run of [
|
|
{
|
|
...unused,
|
|
runnerProfileJson: { nativeExecutionInput: execution(currentRunId) },
|
|
},
|
|
{ ...unused, runnerProfileJson: { sessionCheckpoint: {} } },
|
|
{ ...unused, processPid: 123 },
|
|
{ ...unused, processGroupId: 123 },
|
|
{ ...unused, processStartedAt: new Date() },
|
|
]) {
|
|
expect(() =>
|
|
nativeSessionIdForBootstrapPersistence({
|
|
run,
|
|
selectedSessionId: previousRunId,
|
|
hasProviderEvents: false,
|
|
}),
|
|
).toThrow("native_session_bootstrap_identity_conflict");
|
|
}
|
|
expect(() =>
|
|
nativeSessionIdForBootstrapPersistence({
|
|
run: unused,
|
|
selectedSessionId: previousRunId,
|
|
hasProviderEvents: true,
|
|
}),
|
|
).toThrow("native_session_bootstrap_identity_conflict");
|
|
expect(
|
|
nativeSessionIdForBootstrapPersistence({
|
|
run: {
|
|
...unused,
|
|
runnerProfileJson: { nativeExecutionInput: execution(currentRunId) },
|
|
},
|
|
selectedSessionId: normalizedSessionId,
|
|
hasProviderEvents: true,
|
|
}),
|
|
).toBe(normalizedSessionId);
|
|
});
|
|
|
|
it("recovers the latest exact checkpoint past only unused bootstrap failures", () => {
|
|
const source = {
|
|
...previousRun(),
|
|
nativeIssueId: issueId,
|
|
runtimeMode: "native",
|
|
status: "failed",
|
|
createdAt: new Date(0),
|
|
processPid: null,
|
|
processGroupId: null,
|
|
processStartedAt: null,
|
|
};
|
|
const unusedFailure = {
|
|
...source,
|
|
id: "failed-bootstrap",
|
|
runnerProfileJson: {
|
|
nativeExecutionInput: execution("failed-bootstrap"),
|
|
},
|
|
};
|
|
const original = structuredClone(source);
|
|
const selected = selectNativeSessionResumeRun({
|
|
runs: [unusedFailure, source],
|
|
companyId,
|
|
agentId,
|
|
issueId,
|
|
normalizedSessionId,
|
|
currentRunId,
|
|
beforeCreatedAt: new Date(100),
|
|
providerEvidenceRunIds: new Set(),
|
|
});
|
|
expect(selected).toBe(source);
|
|
expect(
|
|
rebindNativeSessionCheckpoint({
|
|
previousRun: selected!,
|
|
currentExecution: execution(currentRunId),
|
|
}),
|
|
).toMatchObject({
|
|
sessionId: "provider-thread-123",
|
|
identity: { runId: currentRunId, sessionId: normalizedSessionId },
|
|
});
|
|
expect(source).toEqual(original);
|
|
});
|
|
|
|
it("never skips a newer provider authority or incompatible checkpoint", () => {
|
|
const source = {
|
|
...previousRun(),
|
|
nativeIssueId: issueId,
|
|
runtimeMode: "native",
|
|
status: "succeeded",
|
|
createdAt: new Date(0),
|
|
processPid: null as number | null,
|
|
processGroupId: null,
|
|
processStartedAt: null,
|
|
};
|
|
const newer = { ...source, id: "newer", runnerProfileJson: {} };
|
|
const select = (
|
|
candidate: typeof source | typeof newer,
|
|
hasEvents = false,
|
|
) =>
|
|
selectNativeSessionResumeRun({
|
|
runs: [candidate, source],
|
|
companyId,
|
|
agentId,
|
|
issueId,
|
|
normalizedSessionId,
|
|
currentRunId,
|
|
beforeCreatedAt: new Date(100),
|
|
providerEvidenceRunIds: new Set(hasEvents ? [candidate.id] : []),
|
|
});
|
|
expect(select(newer, true)).toBeNull();
|
|
expect(select({ ...newer, processPid: 123 })).toBeNull();
|
|
expect(select({ ...newer, status: "running" })).toBeNull();
|
|
const incompatible = {
|
|
...source,
|
|
id: "newer",
|
|
runnerProfileJson: {
|
|
...source.runnerProfileJson,
|
|
nativeToolContractFingerprint: "stale",
|
|
},
|
|
};
|
|
expect(select(incompatible)).toBe(incompatible);
|
|
expect(
|
|
rebindNativeSessionCheckpoint({
|
|
previousRun: select(incompatible)!,
|
|
currentExecution: execution(currentRunId),
|
|
}),
|
|
).toBeNull();
|
|
});
|
|
|
|
it("does not borrow checkpoints across company, agent, issue, or normalized session", () => {
|
|
const source = {
|
|
...previousRun(),
|
|
nativeIssueId: issueId,
|
|
runtimeMode: "native",
|
|
status: "succeeded",
|
|
createdAt: new Date(0),
|
|
processPid: null,
|
|
processGroupId: null,
|
|
processStartedAt: null,
|
|
};
|
|
for (const changed of [
|
|
{ companyId: currentRunId },
|
|
{ agentId: currentRunId },
|
|
{ nativeIssueId: currentRunId },
|
|
{ nativeSessionId: currentRunId },
|
|
{ id: currentRunId },
|
|
]) {
|
|
expect(
|
|
selectNativeSessionResumeRun({
|
|
runs: [{ ...source, ...changed }],
|
|
companyId,
|
|
agentId,
|
|
issueId,
|
|
normalizedSessionId,
|
|
currentRunId,
|
|
beforeCreatedAt: new Date(100),
|
|
providerEvidenceRunIds: new Set(),
|
|
}),
|
|
).toBeNull();
|
|
}
|
|
});
|
|
|
|
it("does not resume across a work-mode tool-surface change", () => {
|
|
expect(
|
|
rebindNativeSessionCheckpoint({
|
|
previousRun: previousRun(),
|
|
currentExecution: execution(currentRunId, "/workspace", "ask"),
|
|
}),
|
|
).toBeNull();
|
|
});
|
|
it.each(["External chat message received", "issue_comment_added"])(
|
|
"rebuilds full task context when a %s checkpoint is corrupt",
|
|
(reason) => {
|
|
const calls: boolean[] = [];
|
|
const result = buildNativeExecutionWithCheckpoint({
|
|
previousRun: previousRun({ sessionCheckpoint: {} }),
|
|
normalizedSessionId,
|
|
buildExecution: (options) => {
|
|
calls.push(options.resumedSession);
|
|
return buildNativeExecutionInput({
|
|
companyId,
|
|
runId: currentRunId,
|
|
issue: {
|
|
id: issueId,
|
|
identifier: "DOT-2",
|
|
title: "Current task",
|
|
description: "Full task instructions",
|
|
workMode: "standard",
|
|
},
|
|
taskPrompt: options.resumedSession
|
|
? "Compact context"
|
|
: "Full task instructions",
|
|
wakePayload: {
|
|
reason,
|
|
issue: {
|
|
id: issueId,
|
|
title: "Current task",
|
|
workMode: "standard",
|
|
},
|
|
},
|
|
resumedSession: options.resumedSession,
|
|
agentId,
|
|
workspace: {
|
|
id: currentRunId,
|
|
cwd: "/workspace",
|
|
repoUrl: null,
|
|
repoRef: null,
|
|
branchName: null,
|
|
},
|
|
normalizedSessionId: options.normalizedSessionId,
|
|
provider: "codex",
|
|
completionContract: execution(currentRunId).completionContract,
|
|
runtimeContext: nativeRuntimeContextFixture(),
|
|
});
|
|
},
|
|
});
|
|
expect(calls).toEqual([true, false]);
|
|
expect(result.checkpoint).toBeNull();
|
|
expect(result.execution.session.normalizedSessionId).not.toBe(
|
|
normalizedSessionId,
|
|
);
|
|
expect(result.execution.task.prompt).toContain("Full task instructions");
|
|
expect(result.execution.task.prompt).not.toContain(
|
|
"Paperclip Resume Delta",
|
|
);
|
|
expect(result.execution.task.prompt).not.toContain("Compact context");
|
|
},
|
|
);
|
|
|
|
it.each([
|
|
["paperclip.native-execution-input.v4", "paperclip.native-execution-input.v5"],
|
|
["paperclip.native-execution-input.v5", "paperclip.native-execution-input.v4"],
|
|
] as const)("retains a recoverable %s session when the constructor defaults to %s", (priorSchema, currentSchema) => {
|
|
const prior = previousRun();
|
|
const profile = prior.runnerProfileJson as Record<string, unknown>;
|
|
profile.nativeExecutionInput = { ...execution(previousRunId), schema: priorSchema };
|
|
const checkpoint = profile.sessionCheckpoint as Record<string, unknown>;
|
|
checkpoint.goal = { status: "paused", objective: "Preserve the existing durable work" };
|
|
const before = structuredClone(prior);
|
|
const result = buildNativeExecutionWithCheckpoint({
|
|
previousRun: prior,
|
|
normalizedSessionId,
|
|
buildExecution: ({ normalizedSessionId: sessionId, resumedSession }) => parseNativeExecutionInput({
|
|
...execution(currentRunId), schema: currentSchema,
|
|
session: { ...execution(currentRunId).session, normalizedSessionId: sessionId },
|
|
continuationPrompt: resumedSession ? "New direction only; do not replay completed actions" : null,
|
|
}),
|
|
});
|
|
expect(result.execution.schema).toBe(priorSchema);
|
|
expect(result.normalizedSessionId).toBe(normalizedSessionId);
|
|
expect(result.checkpoint).toMatchObject({
|
|
providerSessionId: "provider-thread-123",
|
|
providerRecoveryPolicy: "same_session_only",
|
|
goal: { status: "paused", objective: "Preserve the existing durable work" },
|
|
});
|
|
expect(prior).toEqual(before);
|
|
});
|
|
|
|
it("keeps a valid checkpoint and does not rebuild the resumed task", () => {
|
|
const calls: boolean[] = [];
|
|
const result = buildNativeExecutionWithCheckpoint({
|
|
previousRun: previousRun(),
|
|
normalizedSessionId,
|
|
buildExecution: (options) => {
|
|
calls.push(options.resumedSession);
|
|
return execution(currentRunId);
|
|
},
|
|
});
|
|
expect(calls).toEqual([true]);
|
|
expect(result.checkpoint?.sessionId).toBe("provider-thread-123");
|
|
expect(result.execution.session.normalizedSessionId).toBe(
|
|
normalizedSessionId,
|
|
);
|
|
});
|
|
|
|
it("rebuilds full context when the persisted provider tool contract is stale", () => {
|
|
const calls: boolean[] = [];
|
|
const result = buildNativeExecutionWithCheckpoint({
|
|
previousRun: previousRun({
|
|
nativeToolContractFingerprint: "sha256:stale",
|
|
}),
|
|
normalizedSessionId,
|
|
buildExecution: (options) => {
|
|
calls.push(options.resumedSession);
|
|
const current = execution(currentRunId);
|
|
return {
|
|
...current,
|
|
session: {
|
|
...current.session,
|
|
normalizedSessionId: options.normalizedSessionId,
|
|
},
|
|
task: {
|
|
...current.task,
|
|
prompt: options.resumedSession
|
|
? "Paperclip Resume Delta"
|
|
: "Full task instructions",
|
|
},
|
|
};
|
|
},
|
|
});
|
|
|
|
expect(calls).toEqual([true, false]);
|
|
expect(result.checkpoint).toBeNull();
|
|
expect(result.execution.task.prompt).toBe("Full task instructions");
|
|
expect(result.normalizedSessionId).not.toBe(normalizedSessionId);
|
|
});
|
|
|
|
it.each([
|
|
{ contract: "conditional current-wake reader", retainedFingerprint: "sha256:fe7a2e17ca825228ea2f51f23acdc82db65c91da5ec6add330fefa39b65e1c85" },
|
|
{ contract: "same-conversation attachment reuse", retainedFingerprint: "sha256:2b84f2105c2cea10e0e5f37cf4a6ba9bf7fec90d8c8c19c655a0e21d3a8dab5f" },
|
|
{ contract: "historical file inspection", retainedFingerprint: "sha256:9b558a575dfa4e3dfaf97b7139b47d1676ab3e0307953ec85f2af0b3f443567c" },
|
|
{ contract: "structured human questions", retainedFingerprint: "sha256:1c3cd7e3223f6ed28e1c44a0ba3c961dd4c0c52e52c9c1100a4e41a83384259c" },
|
|
{ contract: "response-wake completion yield", retainedFingerprint: "sha256:09887bbf1f6a3674fcf529d872fe2853cc1d6554376019dd1a9b8d607d7eb7fb" },
|
|
{ contract: "explicit chat-attachment invocation guidance", retainedFingerprint: "sha256:d797c8bc1baef8407a8c80f2c4b28da63b2a4258a47cf52ee9b1fca45535f5e7" },
|
|
{
|
|
contract: "completion descriptions",
|
|
// Deployed v8 / finish_response_wake_concrete_object.v2 local catalog.
|
|
retainedFingerprint:
|
|
"sha256:5b7b302db36f7ed6686f9ea1ba70bbf79ebd7fabf86953b548d966a2bc38b648",
|
|
},
|
|
{
|
|
contract: "native completion tool guidance",
|
|
// Deployed v13 local catalog before canonical finish/block descriptions.
|
|
retainedFingerprint:
|
|
"sha256:68a51d34e091c55ee5d0d2b563153454dd727d72db16e6a27c358d342ae489c9",
|
|
},
|
|
{
|
|
contract: "GitHub working-comment tools",
|
|
// Deployed v14 threads retain the catalog without update_comment.
|
|
retainedFingerprint:
|
|
"sha256:134a7dbd526179aff57f91c261bb653e83db51c20492efab5c26a5ce618792c8",
|
|
},
|
|
{
|
|
contract: "GitHub instruction skill selection",
|
|
// Deployed v15 remote threads omitted configured skills from native turns.
|
|
retainedFingerprint:
|
|
"sha256:f12fe3b1bf5d63b7954d8ab16f57764874806ab49acff7c6582c4de007f4ed4d",
|
|
},
|
|
{
|
|
contract: "regressed conditional run-scoped readers",
|
|
// Deployed v17 threads were opened without read_current_wake_comments
|
|
// and read_chat_attachment on ordinary turns; resume cannot add them.
|
|
retainedFingerprint:
|
|
"sha256:dc495475fb6a4bd034c6dbb2bbe0cf52e7ffc1635838889dc5f7d7251273f119",
|
|
},
|
|
{
|
|
contract: "task-bound human-input description",
|
|
// Deployed v9 still advertises the generic mock-task question description.
|
|
retainedFingerprint:
|
|
"sha256:b64efcd063a575925aa95dbd2a20953386eaa760f05b0e0e73b4ae04a97679b0",
|
|
},
|
|
{
|
|
contract: "direct assigned gateway",
|
|
retainedFingerprint:
|
|
"sha256:c46f05862e87525db392ebf3157d50c424d6e7010e5640680d0ec5075723d7f5",
|
|
},
|
|
])(
|
|
"refreshes retained $contract without changing the Paperclip task or prior history",
|
|
({ contract, retainedFingerprint }) => {
|
|
if (contract === "explicit chat-attachment invocation guidance") {
|
|
expect(LIST_CHAT_ATTACHMENTS_TOOL_DEFINITION.description).toContain("Call with {}");
|
|
expect(LIST_CHAT_ATTACHMENTS_TOOL_DEFINITION.description).toContain("1 through 50");
|
|
expect(REUSE_CHAT_ATTACHMENT_TOOL_DEFINITION.description).toContain("All four arguments are required");
|
|
expect(REUSE_CHAT_ATTACHMENT_TOOL_DEFINITION.description).toContain("same key unchanged on every retry");
|
|
}
|
|
expect(NATIVE_TOOL_CONTRACT_FINGERPRINT).not.toBe(retainedFingerprint);
|
|
const prior = previousRun({
|
|
nativeToolContractFingerprint: retainedFingerprint,
|
|
});
|
|
const priorSnapshot = structuredClone(prior);
|
|
const modes: boolean[] = [];
|
|
const result = buildNativeExecutionWithCheckpoint({
|
|
previousRun: prior,
|
|
normalizedSessionId,
|
|
buildExecution: (options) => {
|
|
modes.push(options.resumedSession);
|
|
const current = execution(currentRunId);
|
|
return {
|
|
...current,
|
|
session: {
|
|
...current.session,
|
|
normalizedSessionId: options.normalizedSessionId,
|
|
},
|
|
task: {
|
|
...current.task,
|
|
prompt: options.resumedSession
|
|
? "Paperclip Resume Delta"
|
|
: "Full context for the same Paperclip task",
|
|
},
|
|
};
|
|
},
|
|
});
|
|
expect(modes).toEqual([true, false]);
|
|
expect(result.checkpoint).toBeNull();
|
|
expect(result.normalizedSessionId).not.toBe(normalizedSessionId);
|
|
expect(result.execution.binding).toMatchObject({
|
|
companyId,
|
|
issueId,
|
|
agentId,
|
|
runId: currentRunId,
|
|
});
|
|
expect(result.execution.workspace).toEqual(
|
|
execution(currentRunId).workspace,
|
|
);
|
|
expect(result.execution.task.prompt).toBe(
|
|
"Full context for the same Paperclip task",
|
|
);
|
|
// No deletion/reset of the existing provider checkpoint or Paperclip history.
|
|
expect(prior).toEqual(priorSnapshot);
|
|
expect(prior.runnerProfileJson.sessionCheckpoint.sessionId).toBe(
|
|
"provider-thread-123",
|
|
);
|
|
},
|
|
);
|
|
|
|
|
|
|
|
it.each(["local", "remote"] as const)("refreshes only OpenCode's former direct MCP catalog on %s", target => {
|
|
const legacy = nativeToolContractFingerprintForTarget(target);
|
|
expect(nativeToolContractFingerprintForTarget(target, "codex")).toBe(legacy);
|
|
expect(nativeToolContractFingerprintForTarget(target, "acpx")).toBe(legacy);
|
|
const current = nativeToolContractFingerprintForTarget(target, "opencode");
|
|
expect(current).not.toBe(legacy);
|
|
const shortenedCatalog = target === "local"
|
|
? "sha256:2ae35faccbb63cfe009d94170ef1ef13f0d57e120af6160540598a3ec72001d7"
|
|
: "sha256:ee5285ca5118b8468c0afd1df4ef9c05d85b0934e882bccd0b193dc8722dbb7a";
|
|
expect(current).not.toBe(shortenedCatalog);
|
|
const currentExecution = { ...execution(currentRunId), provider: { kind: "opencode", model: "openrouter/deepseek/deepseek-v4.1-flash-1017", permissionMode: "allow" }, session: { ...execution(currentRunId).session, driverKind: "opencode_server" } } as NativeExecutionInput;
|
|
const previousExecution = { ...execution(previousRunId), provider: currentExecution.provider, session: currentExecution.session };
|
|
expect(rebindNativeSessionCheckpoint({ previousRun: previousRun({ nativeToolContractFingerprint: shortenedCatalog, nativeExecutionInput: previousExecution }), currentExecution, executionTargetKind: target })).toBeNull();
|
|
expect(rebindNativeSessionCheckpoint({ previousRun: previousRun({ nativeToolContractFingerprint: legacy, nativeExecutionInput: previousExecution }), currentExecution, executionTargetKind: target })).toBeNull();
|
|
expect(rebindNativeSessionCheckpoint({ previousRun: previousRun({ nativeToolContractFingerprint: current, nativeExecutionInput: previousExecution }), currentExecution, executionTargetKind: target })).not.toBeNull();
|
|
});
|
|
|
|
it.each([
|
|
["codex", "sha256:07b116cd7f04b0c9a53b87818a910be32682d5df6181c2019cb1ba8e0077be99"],
|
|
["opencode", "sha256:310dd0367d7157669e9fbf4c41698372a9977ef94183330317167fe07a8987cb"],
|
|
] as const)("keeps a remote %s checkpoint that already relayed its assigned gateway", (providerKind, retainedFingerprint) => {
|
|
expect(nativeToolContractFingerprintForTarget("remote", providerKind)).toBe(retainedFingerprint);
|
|
expect(nativeToolContractFingerprintForTarget("local", providerKind)).not.toBe(retainedFingerprint);
|
|
});
|
|
|
|
it("binds the provider tool catalog to the local or remote execution target", () => {
|
|
const remoteFingerprint = nativeToolContractFingerprintForTarget("remote");
|
|
expect(remoteFingerprint).not.toBe(NATIVE_TOOL_CONTRACT_FINGERPRINT);
|
|
expect(
|
|
rebindNativeSessionCheckpoint({
|
|
previousRun: previousRun(),
|
|
currentExecution: execution(currentRunId),
|
|
executionTargetKind: "remote",
|
|
}),
|
|
).toBeNull();
|
|
expect(
|
|
rebindNativeSessionCheckpoint({
|
|
previousRun: previousRun({
|
|
nativeToolContractFingerprint: remoteFingerprint,
|
|
}),
|
|
currentExecution: execution(currentRunId),
|
|
executionTargetKind: "remote",
|
|
}),
|
|
).not.toBeNull();
|
|
// Deployed v17 remote threads were opened without the run-scoped readers.
|
|
expect(
|
|
rebindNativeSessionCheckpoint({
|
|
previousRun: previousRun({
|
|
nativeToolContractFingerprint:
|
|
"sha256:96dde421aab01f847468d1a8f12863d32dfdb3038a9aca61e1e6bdc81022d5a1",
|
|
}),
|
|
currentExecution: execution(currentRunId),
|
|
executionTargetKind: "remote",
|
|
}),
|
|
).toBeNull();
|
|
});
|
|
|
|
|
|
|
|
|
|
|
|
|
|
it("permits legacy retry rebinding only before the replacement acquired authority", () => {
|
|
const source = {
|
|
runtimeMode: "native",
|
|
status: "interrupted",
|
|
nativeSessionId: normalizedSessionId,
|
|
};
|
|
const replacement = {
|
|
processPid: null,
|
|
processGroupId: null,
|
|
processStartedAt: null,
|
|
runnerProfileJson: {},
|
|
};
|
|
expect(
|
|
isUnusedLegacyNativeRetryReplacement({
|
|
source,
|
|
replacement,
|
|
hasProviderEvents: false,
|
|
}),
|
|
).toBe(true);
|
|
expect(
|
|
isUnusedLegacyNativeRetryReplacement({
|
|
source,
|
|
replacement: { ...replacement, processPid: 123 },
|
|
hasProviderEvents: false,
|
|
}),
|
|
).toBe(false);
|
|
expect(
|
|
isUnusedLegacyNativeRetryReplacement({
|
|
source,
|
|
replacement,
|
|
hasProviderEvents: true,
|
|
}),
|
|
).toBe(false);
|
|
expect(
|
|
isUnusedLegacyNativeRetryReplacement({
|
|
source,
|
|
replacement: {
|
|
...replacement,
|
|
runnerProfileJson: {
|
|
sessionCheckpoint: { providerSessionId: "claimed" },
|
|
},
|
|
},
|
|
hasProviderEvents: false,
|
|
}),
|
|
).toBe(false);
|
|
});
|
|
|
|
it("retains provider identity but clears prior turn and event state", () => {
|
|
const prior = previousRun();
|
|
const profile = prior.runnerProfileJson as Record<string, unknown>;
|
|
const checkpoint = profile.sessionCheckpoint as Record<string, unknown>;
|
|
checkpoint.governedWait = { sourceEvent: { runId: previousRunId, turnId: "old-turn" }, result: { reportedWorkDisposition: "yielded" } };
|
|
checkpoint.dispositionOnlyRecoveryConsumed = true;
|
|
checkpoint.dispositionOnlyRecoveryTurnId = "old-restart-continuation";
|
|
const before = structuredClone(prior);
|
|
const rebound = rebindNativeSessionCheckpoint({
|
|
previousRun: prior,
|
|
currentExecution: execution(currentRunId),
|
|
});
|
|
expect(rebound?.governedWait).toBeUndefined();
|
|
expect(prior).toEqual(before);
|
|
expect(rebound).toMatchObject({
|
|
sessionId: "provider-thread-123",
|
|
providerSessionId: "provider-thread-123",
|
|
driverKind: "codex_app_server",
|
|
cursor: null,
|
|
semanticResult: null,
|
|
terminal: null,
|
|
activeTurnId: null,
|
|
terminalTurns: [],
|
|
pendingRuntimeRequests: [],
|
|
dispositionOnlyRecoveryConsumed: false,
|
|
dispositionOnlyRecoveryTurnId: null,
|
|
providerRecoveryPolicy: "allow_replacement_after_resume_failure",
|
|
identity: {
|
|
runId: currentRunId,
|
|
sessionId: normalizedSessionId,
|
|
companyId,
|
|
issueId,
|
|
agentId,
|
|
},
|
|
});
|
|
});
|
|
|
|
it("allows a provider replacement only after a durable response wake", () => {
|
|
const source = previousRun();
|
|
const profile = source.runnerProfileJson as Record<string, unknown>;
|
|
const checkpoint = profile.sessionCheckpoint as Record<string, unknown>;
|
|
checkpoint.semanticResult = {
|
|
schema: "paperclip.run_result.v1",
|
|
reportedWorkDisposition: "yielded",
|
|
summary: "Waiting for a response.",
|
|
continuation: {
|
|
kind: "response_wake",
|
|
idempotencyKey: "interaction-response:one",
|
|
},
|
|
};
|
|
|
|
expect(
|
|
rebindNativeSessionCheckpoint({
|
|
previousRun: source,
|
|
currentExecution: execution(currentRunId),
|
|
}),
|
|
).toMatchObject({
|
|
providerRecoveryPolicy: "allow_replacement_after_governed_wait",
|
|
semanticResult: null,
|
|
activeTurnId: null,
|
|
});
|
|
});
|
|
|
|
it("requires exact provider continuity for an unfinished session goal", () => {
|
|
const source = previousRun();
|
|
const profile = source.runnerProfileJson as Record<string, unknown>;
|
|
const checkpoint = profile.sessionCheckpoint as Record<string, unknown>;
|
|
checkpoint.goal = {
|
|
threadId: "provider-thread-123",
|
|
objective: "Keep this paused goal on its original provider session.",
|
|
status: "paused",
|
|
tokenBudget: null,
|
|
tokensUsed: 321,
|
|
timeUsedSeconds: 12,
|
|
};
|
|
checkpoint.semanticResult = {
|
|
schema: "paperclip.run_result.v1",
|
|
reportedWorkDisposition: "yielded",
|
|
summary: "Paused at a quiescent boundary.",
|
|
continuation: {
|
|
kind: "same_agent",
|
|
idempotencyKey: "goal:paused:one",
|
|
},
|
|
};
|
|
|
|
expect(
|
|
rebindNativeSessionCheckpoint({
|
|
previousRun: source,
|
|
currentExecution: execution(currentRunId),
|
|
}),
|
|
).toMatchObject({
|
|
providerRecoveryPolicy: "same_session_only",
|
|
semanticResult: null,
|
|
activeTurnId: null,
|
|
goal: {
|
|
objective: "Keep this paused goal on its original provider session.",
|
|
status: "paused",
|
|
},
|
|
});
|
|
});
|
|
|
|
it("refuses to resume when the workspace changes", () => {
|
|
expect(
|
|
rebindNativeSessionCheckpoint({
|
|
previousRun: previousRun(),
|
|
currentExecution: execution(currentRunId, "/different-workspace"),
|
|
}),
|
|
).toBeNull();
|
|
});
|
|
|
|
it("requires the exact managed execution-workspace identity", () => {
|
|
const managedWorkspaceId = "90000000-0000-4000-8000-000000000009";
|
|
const source = previousRun({
|
|
nativeExecutionInput: execution(
|
|
previousRunId,
|
|
"/shared-workspace",
|
|
"standard",
|
|
{ id: managedWorkspaceId },
|
|
),
|
|
});
|
|
expect(
|
|
rebindNativeSessionCheckpoint({
|
|
previousRun: source,
|
|
currentExecution: execution(
|
|
currentRunId,
|
|
"/shared-workspace",
|
|
"standard",
|
|
{ id: managedWorkspaceId },
|
|
),
|
|
}),
|
|
).not.toBeNull();
|
|
expect(
|
|
rebindNativeSessionCheckpoint({
|
|
previousRun: source,
|
|
currentExecution: execution(
|
|
currentRunId,
|
|
"/shared-workspace",
|
|
"standard",
|
|
{ id: "a0000000-0000-4000-8000-00000000000a" },
|
|
),
|
|
}),
|
|
).toBeNull();
|
|
});
|
|
|
|
it("permits per-run projectless placeholders only for an identical workspace descriptor", () => {
|
|
const source = previousRun({
|
|
nativeExecutionInput: execution(
|
|
previousRunId,
|
|
"/projectless",
|
|
"standard",
|
|
{
|
|
repoUrl: "https://example.test/repo.git",
|
|
repoRef: "refs/heads/main",
|
|
branchName: "main",
|
|
},
|
|
),
|
|
});
|
|
const matching = execution(currentRunId, "/projectless", "standard", {
|
|
repoUrl: "https://example.test/repo.git",
|
|
repoRef: "refs/heads/main",
|
|
branchName: "main",
|
|
});
|
|
expect(
|
|
rebindNativeSessionCheckpoint({
|
|
previousRun: source,
|
|
currentExecution: matching,
|
|
}),
|
|
).not.toBeNull();
|
|
expect(
|
|
rebindNativeSessionCheckpoint({
|
|
previousRun: source,
|
|
currentExecution: {
|
|
...matching,
|
|
workspace: { ...matching.workspace, repoRef: "refs/heads/next" },
|
|
},
|
|
}),
|
|
).toBeNull();
|
|
expect(
|
|
rebindNativeSessionCheckpoint({
|
|
previousRun: source,
|
|
currentExecution: execution(currentRunId, "/projectless", "standard", {
|
|
id: "b0000000-0000-4000-8000-00000000000b",
|
|
repoUrl: "https://example.test/repo.git",
|
|
repoRef: "refs/heads/main",
|
|
branchName: "main",
|
|
}),
|
|
}),
|
|
).toBeNull();
|
|
});
|
|
|
|
it("rotates when assigned context changes but permits a fresh run-scoped MCP binding", () => {
|
|
const reboundCredential = execution(currentRunId);
|
|
reboundCredential.runtimeContext.mcp.bindingId = "native-mcp:fresh-run";
|
|
expect(
|
|
rebindNativeSessionCheckpoint({
|
|
previousRun: previousRun(),
|
|
currentExecution: reboundCredential,
|
|
}),
|
|
).not.toBeNull();
|
|
|
|
const changedAssignment = execution(currentRunId);
|
|
const withoutAggregate = {
|
|
prompt: changedAssignment.runtimeContext.prompt,
|
|
instructions: changedAssignment.runtimeContext.instructions,
|
|
skills: changedAssignment.runtimeContext.skills,
|
|
mcp: {
|
|
assignmentSetId: `sha256:${"1".repeat(64)}`,
|
|
digest: "1".repeat(64),
|
|
bindingId: "native-mcp:fresh-run",
|
|
},
|
|
};
|
|
changedAssignment.runtimeContext = {
|
|
...withoutAggregate,
|
|
aggregateDigest: canonicalNativeRuntimeContextDigest(withoutAggregate),
|
|
};
|
|
expect(
|
|
rebindNativeSessionCheckpoint({
|
|
previousRun: previousRun(),
|
|
currentExecution: changedAssignment,
|
|
}),
|
|
).toBeNull();
|
|
});
|
|
|
|
it("refuses a checkpoint whose prior-run binding was rewritten", () => {
|
|
const source = previousRun();
|
|
const profile = source.runnerProfileJson as Record<string, unknown>;
|
|
const checkpoint = profile.sessionCheckpoint as Record<string, unknown>;
|
|
checkpoint.identity = {
|
|
...(checkpoint.identity as Record<string, unknown>),
|
|
runId: currentRunId,
|
|
};
|
|
expect(
|
|
rebindNativeSessionCheckpoint({
|
|
previousRun: source,
|
|
currentExecution: execution(currentRunId),
|
|
}),
|
|
).toBeNull();
|
|
});
|
|
|
|
it("reuses plan mode across canonical revisions but never across a mode change", () => {
|
|
const source = previousRun({
|
|
nativeExecutionInput: planningExecution(previousRunId, "revision-8"),
|
|
});
|
|
expect(
|
|
rebindNativeSessionCheckpoint({
|
|
previousRun: source,
|
|
currentExecution: planningExecution(currentRunId, "revision-9"),
|
|
}),
|
|
).not.toBeNull();
|
|
expect(
|
|
rebindNativeSessionCheckpoint({
|
|
previousRun: source,
|
|
currentExecution: execution(currentRunId),
|
|
}),
|
|
).toBeNull();
|
|
});
|
|
});
|
|
|
|
describe("buildNativeExecutionInput wake projection", () => {
|
|
it.each(["slack", "github"])("uses compact %s input only after provider resume, preserving fresh bootstrap fallback", (externalChatProvider) => {
|
|
const base = execution(currentRunId);
|
|
const issue = { id: issueId, identifier: "DOT-2", title: "Old greeting", description: null, workMode: "standard" };
|
|
const message = { id: "wake", body: "NEW_SLACK_MESSAGE", authorType: "user", authorId: "board", sourceTrust: "user", createdByRunId: null };
|
|
const input = buildNativeExecutionInput({
|
|
companyId, runId: currentRunId, agentId, issue,
|
|
taskPrompt: "FULL_BOOTSTRAP_WITH_FILE_AND_AUTHORIZATION_INSTRUCTIONS",
|
|
resumedSession: true,
|
|
previousTurn: { runId: previousRunId, task: issue },
|
|
wakePayload: {
|
|
reason: "External chat message received", issue,
|
|
externalChatProvider, checkedOutByHarness: true,
|
|
comments: [{ ...message, author: { type: "user", id: "board" } }], commentIds: [message.id], latestCommentId: message.id,
|
|
commentWindow: { requestedCount: 1, includedCount: 1, missingCount: 0 },
|
|
executionContinuation: { version: 1, objective: message.body, messages: [message], resumeDelta: { baseRunId: previousRunId, messages: [message] } },
|
|
},
|
|
workspace: { id: currentRunId, ...base.workspace }, normalizedSessionId,
|
|
provider: "codex", completionContract: base.completionContract,
|
|
runtimeContext: nativeRuntimeContextFixture(),
|
|
});
|
|
expect(input.continuationPrompt).toContain(message.body);
|
|
expect(input.continuationPrompt).not.toContain("FULL_BOOTSTRAP");
|
|
expect(input.task.prompt).toContain("FULL_BOOTSTRAP");
|
|
expect(input.task.prompt).toContain(message.body);
|
|
});
|
|
|
|
it.each(["github", null])("restores GitHub configuration on fresh fallback and sends changes on %s resume", (externalChatProvider) => {
|
|
const base = execution(currentRunId);
|
|
const issue = { id: issueId, identifier: "REVIEW-1", title: "PR #1", description: null, workMode: "standard" };
|
|
const config = { key: "a".repeat(64), instructions: "STABLE_REVIEW_POLICY" };
|
|
const message = { id: "new-push", body: "Review new head abc123", authorType: "user", authorId: "board", createdByRunId: null };
|
|
const args = {
|
|
companyId, runId: currentRunId, agentId, issue, taskPrompt: "Canonical task",
|
|
resumedSession: true, previousTurn: { runId: previousRunId, task: issue, githubReviewConfigurationKeys: [config.key] },
|
|
wakePayload: { reason: externalChatProvider ? "External chat message received" : "issue_commented", issue, externalChatProvider, checkedOutByHarness: true,
|
|
githubReviewConfigurations: [config],
|
|
comments: [{ ...message, author: { type: "user", id: "board" } }], commentIds: [message.id], latestCommentId: message.id,
|
|
commentWindow: { requestedCount: 1, includedCount: 1, missingCount: 0 },
|
|
executionContinuation: { version: 1, objective: message.body, messages: [{ ...message, id: "old", body: "OLD_REQUEST" }, message],
|
|
resumeDelta: { baseRunId: previousRunId, messages: [message] } },
|
|
},
|
|
workspace: { id: currentRunId, ...base.workspace }, normalizedSessionId,
|
|
provider: "codex" as const, completionContract: base.completionContract, runtimeContext: nativeRuntimeContextFixture(),
|
|
};
|
|
const prepared = buildNativeExecutionInput(args);
|
|
const resumed = JSON.stringify(buildNativeModelEnvelope(prepared, { resumedSession: true }));
|
|
expect(resumed).toContain("paperclip.native-continuation.v1");
|
|
expect(resumed).toContain(message.body);
|
|
expect(resumed).not.toContain(config.instructions);
|
|
expect(resumed).not.toContain("OLD_REQUEST");
|
|
const fresh = JSON.stringify(buildNativeModelEnvelope(prepared));
|
|
expect(fresh.split(config.instructions)).toHaveLength(2);
|
|
expect(fresh).toContain("OLD_REQUEST");
|
|
const changed = buildNativeExecutionInput({ ...args, previousTurn: { ...args.previousTurn, githubReviewConfigurationKeys: [] } });
|
|
expect(JSON.stringify(buildNativeModelEnvelope(changed, { resumedSession: true })).split(config.instructions)).toHaveLength(2);
|
|
const reset = buildNativeExecutionInput({ ...args, resumedSession: false });
|
|
expect(reset.continuationPrompt).toBeUndefined();
|
|
expect(JSON.stringify(buildNativeModelEnvelope(reset))).toContain(config.instructions);
|
|
});
|
|
|
|
it("uses a neutral turn title for authenticated external-chat follow-ups", () => {
|
|
const staleRootTitle = "Reply with exactly STALE-ROOT-MARKER";
|
|
const input = buildNativeExecutionInput({
|
|
companyId,
|
|
runId: currentRunId,
|
|
issue: {
|
|
id: issueId,
|
|
identifier: "CHAT-4",
|
|
title: staleRootTitle,
|
|
description: "Started from Telegram.",
|
|
workMode: "standard",
|
|
},
|
|
taskPrompt: [
|
|
"Paperclip task context:",
|
|
`- Title: ${JSON.stringify(staleRootTitle)}`,
|
|
"Latest wake comment:",
|
|
"```text",
|
|
"Quick question: what is 55 + 8?",
|
|
"```",
|
|
].join("\n"),
|
|
wakePayload: {
|
|
reason: "External chat message received",
|
|
externalChatProvider: "telegram",
|
|
checkedOutByHarness: true,
|
|
issue: {
|
|
id: issueId,
|
|
identifier: "CHAT-4",
|
|
title: staleRootTitle,
|
|
description: "Started from Telegram.",
|
|
descriptionTruncated: false,
|
|
status: "in_progress",
|
|
workMode: "standard",
|
|
},
|
|
commentWindow: {
|
|
requestedCount: 1,
|
|
includedCount: 1,
|
|
missingCount: 0,
|
|
},
|
|
commentIds: ["comment-current"],
|
|
latestCommentId: "comment-current",
|
|
comments: [
|
|
{
|
|
id: "comment-current",
|
|
issueId,
|
|
body: "Quick question: what is 55 + 8?",
|
|
bodyTruncated: false,
|
|
authorType: "user",
|
|
},
|
|
],
|
|
fallbackFetchNeeded: false,
|
|
},
|
|
agentId,
|
|
workspace: {
|
|
id: currentRunId,
|
|
cwd: "/workspace",
|
|
repoUrl: null,
|
|
repoRef: null,
|
|
branchName: null,
|
|
},
|
|
normalizedSessionId,
|
|
provider: "codex",
|
|
completionContract: {
|
|
id: "70000000-0000-4000-8000-000000000007",
|
|
sha256: `sha256:${"a".repeat(64)}`,
|
|
schemaVersion: "paperclip.run-result.v1",
|
|
contract: {
|
|
revision: "2",
|
|
objective: "Respond to the latest comment",
|
|
criteria: [
|
|
{
|
|
id: "objective",
|
|
requirement: "Quick question: what is 55 + 8?",
|
|
},
|
|
],
|
|
},
|
|
},
|
|
runtimeContext: nativeRuntimeContextFixture(),
|
|
});
|
|
|
|
expect(input.task.title).toBe("External chat follow-up");
|
|
expect(input.task.description).toBeNull();
|
|
expect(input.task.prompt).toContain(staleRootTitle);
|
|
expect(input.task.prompt).toContain("Quick question: what is 55 + 8?");
|
|
expect(input.completionContract.contract).toMatchObject({
|
|
objective: "Respond to the latest comment",
|
|
criteria: [
|
|
{
|
|
id: "objective",
|
|
requirement: "Quick question: what is 55 + 8?",
|
|
},
|
|
],
|
|
});
|
|
});
|
|
|
|
it("preserves the canonical task title outside the authenticated chat shortcut", () => {
|
|
const input = execution(currentRunId);
|
|
|
|
expect(input.task.title).toBe("Test");
|
|
});
|
|
|
|
it("writes native v4 and pins every provider's complete effective configuration", () => {
|
|
const common = {
|
|
companyId,
|
|
runId: currentRunId,
|
|
issue: {
|
|
id: issueId,
|
|
identifier: "DOT-4",
|
|
title: "Permissions",
|
|
description: null,
|
|
workMode: "standard",
|
|
},
|
|
taskPrompt: "Verify permissions",
|
|
agentId,
|
|
workspace: {
|
|
id: currentRunId,
|
|
cwd: "/workspace",
|
|
repoUrl: null,
|
|
repoRef: null,
|
|
branchName: null,
|
|
},
|
|
normalizedSessionId,
|
|
completionContract: execution(currentRunId).completionContract,
|
|
runtimeContext: nativeRuntimeContextFixture(),
|
|
} as const;
|
|
const codex = buildNativeExecutionInput({
|
|
...common,
|
|
provider: "codex",
|
|
codexApprovalPolicy: "on-request",
|
|
});
|
|
const opencode = buildNativeExecutionInput({
|
|
...common,
|
|
provider: "opencode",
|
|
model: "openrouter/z-ai/glm-5.2",
|
|
opencodePermissionMode: "ask",
|
|
});
|
|
const acpx = buildNativeExecutionInput({
|
|
...common,
|
|
provider: "acpx",
|
|
acpxAgent: "claude",
|
|
model: "claude-sonnet-5",
|
|
acpxPermissionMode: "deny-all",
|
|
});
|
|
const claudeManaged = buildNativeExecutionInput({
|
|
...common,
|
|
provider: "claude_managed",
|
|
model: "claude-sonnet-5",
|
|
managedProfile: {
|
|
profileId: "managed-profile",
|
|
anthropicAgentId: "agent-remote",
|
|
agentVersion: "7",
|
|
environmentId: "environment-remote",
|
|
betaVersion: "managed-agents-2026-04-01",
|
|
},
|
|
maxSessionListCostUsd: 0.75,
|
|
});
|
|
const agentCore = buildNativeExecutionInput({
|
|
...common,
|
|
provider: "aws_agentcore",
|
|
model: "global.anthropic.claude-sonnet-4-6",
|
|
agentCoreProfile: {
|
|
profileId: "agentcore-profile",
|
|
region: "us-east-1",
|
|
accountId: "123456789012",
|
|
harnessArn:
|
|
"arn:aws:bedrock-agentcore:us-east-1:123456789012:harness/h-1",
|
|
harnessVersion: "3",
|
|
endpointArn:
|
|
"arn:aws:bedrock-agentcore:us-east-1:123456789012:endpoint/e-1",
|
|
endpointQualifier: "prod",
|
|
agentRuntimeArn:
|
|
"arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/r-1",
|
|
memoryArn:
|
|
"arn:aws:bedrock-agentcore:us-east-1:123456789012:memory/m-1",
|
|
memoryId: "m-1",
|
|
invocationRoleArn: "arn:aws:iam::123456789012:role/invoke",
|
|
contextBucket: "paperclip-context",
|
|
contextPrefix: "runner/",
|
|
contextKmsKeyArn: "arn:aws:kms:us-east-1:123456789012:key/key-1",
|
|
qualificationRevision: "aws-agentcore-harness-context-v2",
|
|
eventExpiryDays: 90,
|
|
},
|
|
maxEstimatedSessionCostUsd: 1.25,
|
|
invocationLimits: {
|
|
maxIterations: 8,
|
|
maxOutputTokens: 4_096,
|
|
timeoutSeconds: 300,
|
|
},
|
|
});
|
|
const defaultOpenCode = buildNativeExecutionInput({
|
|
...common,
|
|
provider: "opencode",
|
|
model: "openrouter/z-ai/glm-5.2",
|
|
});
|
|
const defaultAcpx = buildNativeExecutionInput({
|
|
...common,
|
|
provider: "acpx",
|
|
model: "gpt-5.6-sol",
|
|
});
|
|
|
|
expect(codex).toMatchObject({
|
|
schema: "paperclip.native-execution-input.v5",
|
|
provider: { kind: "codex", approvalPolicy: "on-request" },
|
|
});
|
|
expect(opencode).toMatchObject({
|
|
schema: "paperclip.native-execution-input.v5",
|
|
provider: { kind: "opencode", permissionMode: "ask" },
|
|
});
|
|
expect(acpx).toMatchObject({
|
|
schema: "paperclip.native-execution-input.v5",
|
|
provider: { kind: "acpx", permissionMode: "deny-all" },
|
|
});
|
|
expect(claudeManaged).toMatchObject({
|
|
session: { driverKind: "claude_managed_agents_api" },
|
|
provider: {
|
|
kind: "claude_managed",
|
|
managedProfile: { profileId: "managed-profile" },
|
|
maxSessionListCostUsd: 0.75,
|
|
},
|
|
});
|
|
expect(agentCore).toMatchObject({
|
|
session: { driverKind: "aws_agentcore_harness_api" },
|
|
provider: {
|
|
kind: "aws_agentcore",
|
|
agentCoreProfile: {
|
|
profileId: "agentcore-profile",
|
|
eventExpiryDays: 90,
|
|
},
|
|
maxEstimatedSessionCostUsd: 1.25,
|
|
},
|
|
});
|
|
expect(defaultOpenCode).toMatchObject({
|
|
provider: { kind: "opencode", permissionMode: "allow" },
|
|
});
|
|
expect(defaultAcpx).toMatchObject({
|
|
provider: {
|
|
kind: "acpx",
|
|
agent: "codex",
|
|
permissionMode: "approve-all",
|
|
},
|
|
});
|
|
expect(
|
|
JSON.stringify([codex, opencode, claudeManaged, agentCore, acpx]),
|
|
).not.toMatch(
|
|
/OPENAI_API_KEY|ANTHROPIC_API_KEY|AWS_SECRET_ACCESS_KEY|PAPERCLIP_API_KEY/,
|
|
);
|
|
});
|
|
|
|
it.each([false, true])("projects wake context with the appropriate execution contract (conversation=%s)", (conversationMode) => {
|
|
const input = buildNativeExecutionInput({
|
|
companyId,
|
|
runId: currentRunId,
|
|
issue: {
|
|
id: issueId,
|
|
identifier: "DOT-146",
|
|
title: "Finish after child handoff",
|
|
description: "Use the child result.",
|
|
workMode: "standard",
|
|
},
|
|
taskPrompt: "Paperclip task context:\n- Issue: DOT-146",
|
|
wakePayload: {
|
|
reason: "issue_children_completed",
|
|
issue: {
|
|
id: issueId,
|
|
identifier: "DOT-146",
|
|
title: "Finish after child handoff",
|
|
description: "Use the child result.",
|
|
status: "in_progress",
|
|
priority: "medium",
|
|
workMode: "standard",
|
|
},
|
|
childIssueSummaries: [
|
|
{
|
|
id: "child-147",
|
|
identifier: "DOT-147",
|
|
title: "Build utility",
|
|
status: "done",
|
|
summary: "Created three files and passed 7/7 tests.",
|
|
},
|
|
],
|
|
childIssueSummaryTruncated: false,
|
|
checkedOutByHarness: true,
|
|
},
|
|
resumedSession: true,
|
|
conversationMode,
|
|
agentId,
|
|
workspace: {
|
|
id: currentRunId,
|
|
cwd: "/workspace",
|
|
repoUrl: null,
|
|
repoRef: null,
|
|
branchName: null,
|
|
},
|
|
normalizedSessionId,
|
|
provider: "opencode",
|
|
model: "openrouter/z-ai/glm-5.2",
|
|
completionContract: {
|
|
id: "70000000-0000-4000-8000-000000000007",
|
|
sha256: `sha256:${"a".repeat(64)}`,
|
|
schemaVersion: "paperclip.run-result.v1",
|
|
contract: {
|
|
revision: "1",
|
|
objective: "Finish after the child",
|
|
criteria: [
|
|
{ id: "objective", requirement: "Report the child result" },
|
|
],
|
|
},
|
|
},
|
|
runtimeContext: nativeRuntimeContextFixture(),
|
|
});
|
|
|
|
expect(input.task.prompt).not.toContain("Execution contract:");
|
|
expect(input.task.prompt).not.toContain("Use child issues");
|
|
// Full bootstrap stays available if provider recovery fails after admission.
|
|
expect(input.task.prompt).toContain("## Paperclip Wake Payload");
|
|
expect(input.task.prompt).toContain("reason: issue_children_completed");
|
|
expect(input.task.prompt).toContain("DOT-147 Build utility (done)");
|
|
expect(input.task.prompt).toContain(
|
|
"Created three files and passed 7/7 tests.",
|
|
);
|
|
expect(input.task.prompt).toContain(
|
|
"Paperclip task context:\n- Issue: DOT-146",
|
|
);
|
|
expect(input.task.prompt).not.toContain("Use the child result.");
|
|
});
|
|
});
|