Files
PaperClipAI/server/src/__tests__/environment-task-runtime.test.ts
T
Nicky LeachandClaude Opus 5.5 a78be8b601 feat(native): send launch preparation and run digests to plugin task prepare (#21717)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Environment plugins can run a native Runner as a plugin task, and a
warm session keeps that Runner between turns
> - On each warm turn Core sends the plugin a `prepare` operation with
the full launch requirements for the new run
> - The requirements' `requirementsDigest` covers the run identity, and
the run identity changes on every turn
> - So a plugin cannot tell that only the run moved, and it must redo
its whole preparation every warm turn
> - This pull request gives the plugin two digests: one that stays the
same while its preparation stays valid, and one that names the run
> - The benefit is that a plugin can transfer only the run identity when
nothing it reconciles changed

## Linked Issues or Issue Description

**What existing behavior does this improve?**
The `prepare` operation that Core sends to an environment plugin for a
plugin Runner task, on cold starts and on warm attaches.

**Subsystem affected**
Native runtime, plugin Runner tasks, the Runner launch contract, and the
plugin SDK environment task contract.

**Current behavior**
A warm attach sends the full requirements. The only digest available,
`requirementsDigest`, includes `runId`, `turnId` and `itemId`, so it
changes on every turn even when the launch is otherwise the same.

**Proposed behavior**
Core computes two digests for every `prepare`:
- `preparationDigest`: the launch requirements an environment reconciles
when it prepares a Runner:
  - the runner, lease and session identity;
  - provider, model and settings;
  - the prompt and instruction text;
- the runtime context's instruction and skill bundles, working copy and
connection instructions.

It leaves out the `runId`, `turnId` and `itemId`, and the runtime
context's MCP assignment and binding (with `aggregateDigest`, which
hashes the assignment). MCP reaches the Runner through Core's tool
authority on every run attachment, never through files the environment
publishes. Core already continues a warm session across an MCP-only
change (`nativeRuntimeContextsMatch` with tool refresh). The binding is
also named per run (`native-mcp:<runId>`). So the digest stays the same
across warm turns of one Runner, lease and session, including when the
agent's MCP access changes.
- `runDigest`: `preparationDigest` plus everything it leaves out:
`runId`, `turnId`, `itemId`, and the MCP assignment and binding. It is
unique to one run's launch.

A plugin that advertises `launchDigestVersion: 1` in its task
description gets both fields on `prepare`.

**Reason and benefit**
A plugin can compare `preparationDigest` with its saved preparation and
transfer only the run identity when they match, instead of a full
preparation.

**Breaking changes**
None. Plugins without `launchDigestVersion` get no new fields.

## What Changed

- `packages/paperclip-runner/src/live/runner-provider-launch.ts`: add
`runnerLaunchPreparationDigest` and `runnerLaunchRunDigest`. The
preparation digest drops the MCP assignment and binding; the run digest
takes the full requirements and includes them. Both use the same
canonical JSON as `runnerLaunchRequirementsDigest`, with their own
schema tags so the three digests never collide. Export them from the
package and the server's vendored runner shim.
- `packages/plugins/sdk/src/environment-tasks.ts`: add optional
`preparationDigest` and `runDigest` to the `prepare` operation, and
optional `launchDigestVersion: 1` to the task description. The
capability gates both digests.
- `server/src/services/native-runtime/plugin-runner-task.ts` and
`native-session-executor.ts`: send both digests on `prepare` when the
description advertises `launchDigestVersion: 1`.
- `server/src/services/environment-task-runtime.ts`: recompute both
digests from the requirements, and refuse a `prepare` whose digests are
missing in part or do not match.
- `tests/runner-e2e/source-sdk-public-inputs.json`: refresh the SDK
public source pin.
- Tests:
- the preparation digest is stable across runs and changes when the
runner, lease, session, instructions, model, approval policy or settings
change;
- with a runtime context, an MCP-only change (the run's binding, no
binding, a changed access set) keeps the preparation digest and changes
the run digest;
- a change to the instruction bundle, instruction entry, a skill bundle,
the skill set, the working copy or the connection instructions changes
the preparation digest;
  - the run digest changes per run;
  - Core sends the digests only when advertised;
- the runtime refuses forged or partial digests before it calls the
plugin.

## Verification

- `npx vitest run src/live/runner-launch-preparation.test.ts` in
`packages/paperclip-runner`: 26 passed.
- `npx vitest run src/services/native-runtime/plugin-runner-task.test.ts
src/__tests__/environment-task-runtime.test.ts` in `server`: 160 passed.
- `npx vitest run source-sdk-public-inputs.test.mjs
source-sdk-evidence.test.ts source-sdk-public-type.test.ts` in
`tests/runner-e2e`: 59 passed.
- `pnpm typecheck` in `server` and in `packages/paperclip-runner`:
clean.
- Not run locally: the full suite. CI covers it.

## Risks

Low risk. The digests are new optional fields behind a plugin capability
version. Core computes them and checks them again before it calls the
plugin, so a plugin can rely on them. They prove only that the launch
requirements are unchanged. A plugin that skips work on a match must
still check its own state, such as files it published into the sandbox.
If the runtime context carries values that change per run, the
preparation digest changes too, so a plugin does its full preparation.
That is safe, but the plugin saves nothing. The MCP binding is the one
such value Core sets per run today, and MCP is excluded entirely. A
plugin that does publish MCP configuration into its sandbox must not
rely on this digest for it. Values outside the requirements are not
covered at all: the account identity and credentials, the GitHub broker,
project IDs, and the plugin's own runtime revision. A plugin must keep
checking those itself. A match lets a plugin skip publishing its launch
configuration, not computing the descriptor: `prepare` must still return
a launch whose `requirementsDigest` matches the current requirements,
which carry the current MCP assignment and binding.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, code search).

## 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 Opus 5.5 <noreply@anthropic.com>
2026-11-14 20:07:54 -08:00

700 lines
56 KiB
TypeScript

import { beforeEach, describe, expect, it, vi } from "vitest";
import { PgDialect } from "drizzle-orm/pg-core";
import { executionWorkspaces, environmentLeases, type Db } from "@paperclipai/db";
import { environmentTaskErrorCodeData, environmentTaskOperationSchema, parseEnvironmentTaskResult, JsonRpcCallError, PluginEnvironmentTaskError,
readEnvironmentTaskErrorCode, readEnvironmentTaskErrorDiagnostic } from "@paperclipai/plugin-sdk";
import { executeEnvironmentTask, isSettledReadyRunnerState, settleDispatchedEnvironmentTask } from "../services/environment-task-runtime.js";
import { NativeExecutionContext } from "../services/native-runtime/native-execution-context.js";
import { runnerLaunchPreparationDigest, runnerLaunchRunDigest } from "../vendor/paperclip-runner/index.js";
const state = vi.hoisted(() => ({ plugin: {} as any, release: vi.fn(), identity: vi.fn(), config: vi.fn() }));
vi.mock("../services/provider-fresh-workspace.js", () => ({
stageProviderFreshWorkspace: async (input: { existing: unknown }) => input.existing,
releaseProviderRecoveryTransfers: state.release,
}));
vi.mock("../services/plugin-registry.js", () => ({ pluginRegistryService: () => ({ getById: vi.fn(async () => state.plugin), getConfig: state.config }) }));
vi.mock("../services/plugin-agent-runtime-state.js", () => ({ pluginAgentRuntimeIdentity: state.identity }));
const leaseId = "10000000-0000-4000-8000-000000000001";
const projectId = "10000000-0000-4000-8000-000000000002";
const secondProjectId = "10000000-0000-4000-8000-000000000003";
const row = () => ({
lease: { id: leaseId, companyId: "company", environmentId: "environment", providerLeaseId: "attempt-1", heartbeatRunId: "run", issueId: "issue", status: "active", expiresAt: null as Date | null,
metadata: { driver: "plugin", pluginId: "original", driverKey: "tasks", runnerTaskProjectAuthValidation: { configurationId: "configuration", provider: "openai", projectIds: [projectId] } } },
environment: { id: "environment", config: { pluginKey: "test.provider", driverKey: "tasks", driverConfig: {} } } as { id: string; config: Record<string, unknown> } | null,
run: { id: "run", agentId: "agent", status: "running" } as { id: string; agentId: string; status: string } | null,
});
function database(value: ReturnType<typeof row> | null = row(), projectRows = [{ id: projectId }], workspaceRows: unknown[] = [], ownerRows: unknown[] = []) {
let selectedRows: unknown[] = projectRows;
const results = [value ? [value] : [], [{ id: "issue" }], value ? [value] : []];
const query: any = { from: (table: unknown) => { selectedRows = table === executionWorkspaces ? workspaceRows : table === environmentLeases ? ownerRows : projectRows; return query; }, leftJoin: () => query, where: vi.fn(() => query), limit: () => Promise.resolve(results.shift()), then: (resolve: (rows: typeof projectRows) => unknown) => Promise.resolve(selectedRows).then(resolve as (rows: unknown[]) => unknown) };
const sets: Record<string, unknown>[] = [];
const update: any = { set: (value: Record<string, unknown>) => { sets.push(value); return update; }, where: () => update,
returning: async () => [{ id: leaseId, metadata: value?.lease.metadata, heartbeatRunId: value?.lease.heartbeatRunId }], then: (resolve: (value: unknown) => unknown) => Promise.resolve([]).then(resolve) };
const db = { select: () => query, update: () => update,
transaction: vi.fn(async (write: (tx: Db) => Promise<unknown>) => write(db as unknown as Db)) };
return { db: db as unknown as Db, query, sets, transaction: db.transaction };
}
function worker(result: unknown = { kind: "accepted", taskId: "attempt-1" }) {
return { getWorker: vi.fn(() => ({ supportedMethods: ["environmentTask"] })), call: vi.fn(async () => result) };
}
const submit = { kind: "submit" as const, preparedLaunchId: "configuration", projectIds: [projectId], runner: { protocolMin: 1, protocolMax: 2, harness: "codex", runnerId: "runner", leaseId, runId: "run", sessionId: "session", turnId: "turn", itemId: "item" }, bootstrapTicket: "transient-test-ticket" };
beforeEach(() => {
state.release.mockReset();
state.identity.mockReset().mockResolvedValue({ instanceSecrets: { launcher: "synthetic-transient-binding" } });
state.config.mockReset().mockResolvedValue({ configJson: { endpoint: "synthetic" } });
state.plugin = { id: "original", pluginKey: "test.provider", status: "ready", manifestJson: { capabilities: ["environment.drivers.register"], environmentDrivers: [{ driverKey: "tasks", supportsTasks: true }] } };
});
describe("stopped Runner checkpoint settlement", () => {
const idle = () => ({ schema: "paperclip.runner.durable.state.v1", lifecycle: "ready", lastControllerCommandSeq: 7,
ackedSourceSeq: 11, nextSourceSeq: 12, outbox: [] as unknown[], processedCommands: { done: { status: "completed" } } as Record<string, unknown>,
pendingTerminalDelivery: null, pendingProviderCleanup: null, warmTransition: null } as Record<string, unknown>);
it("treats only a ready journal at a fully settled cut as suspended", () => {
expect(isSettledReadyRunnerState(idle())).toBe(true);
for (const change of [
{ lifecycle: "suspended" }, { lifecycle: "recoverable_failure" }, { lifecycle: "backpressure" }, { schema: "unknown" },
{ outbox: [{ sourceSeq: 12 }] }, { outbox: undefined }, { ackedSourceSeq: 10 }, { nextSourceSeq: 0 }, { nextSourceSeq: undefined },
{ processedCommands: { turn: { status: "pending" } } }, { processedCommands: { turn: { status: "indeterminate" } } },
{ processedCommands: { turn: {} } }, { processedCommands: undefined }, { processedCommands: [] },
{ pendingTerminalDelivery: { commandId: "c" } }, { pendingProviderCleanup: { commandId: "c" } }, { warmTransition: { id: "t" } },
]) expect(isSettledReadyRunnerState({ ...idle(), ...change }), JSON.stringify(change)).toBe(false);
});
});
describe("plugin-provided Runner execution", () => {
it("records a confirmed admission refusal so lease cleanup never looks for a Runner", async () => {
const value = row();
const fixture = database(value);
const refusal = { kind: "admission_rejected", taskId: "attempt-1", reason: "session_state_unavailable" };
const workers = worker(refusal);
await expect(executeEnvironmentTask(fixture.db, workers as never, {
companyId: "company", leaseId, operation: submit,
})).resolves.toEqual(refusal);
const update = new PgDialect().sqlToQuery(fixture.sets.at(-1)!.metadata as never);
expect(update.sql).toContain("- 'runnerTaskIdentity'");
const durable = JSON.parse(String(update.params[0]));
expect(durable).toEqual({
runnerTaskAdmissionRejection: { taskId: "attempt-1", reason: "session_state_unavailable" },
runnerTaskDispatched: false, runnerTaskExecutionStopped: true, runnerTaskSessionRetained: false,
});
Object.assign(value.lease.metadata, durable);
await expect(settleDispatchedEnvironmentTask(database(value).db, workers as never, {
companyId: "company", id: leaseId,
})).resolves.toBe("stopped");
expect(workers.call.mock.calls).toHaveLength(1);
});
it.each([false, true])("retires an undispatched warm task only with required preparation proof (%s)", async preparationStopped => {
const value = row();
Object.assign(value.lease.metadata, { runnerTaskDispatched: false,
runnerTaskStartupCleanup: { contextId: "startup", requiresPreparationStop: true } });
const fixture = database(value), workers = worker();
fixture.db.select = ((...args: unknown[]) => (database(value).db.select as (...values: unknown[]) => unknown)(...args)) as Db["select"];
let release!: () => void;
const drain = new Promise<void>(resolve => { release = resolve; });
const drainStartup = vi.fn(() => drain);
Object.assign(workers, { drainStartup });
const operations: string[] = [];
workers.call.mockImplementation(async (...args: any[]) => {
const operation = args[2].operation.kind; operations.push(operation);
return operation === "status" ? { kind: "status", taskId: "attempt-1", phase: "cancelled", executionStopped: true, preparationStopped }
: { kind: "accepted", taskId: "attempt-1" };
});
const retiring = settleDispatchedEnvironmentTask(fixture.db, workers as never, { companyId: "company", id: leaseId });
const checked = retiring.then(value => ({ value, error: null }), error => ({ value: false, error }));
await vi.waitFor(() => expect(operations).toContain("stop"));
await vi.waitFor(() => expect(operations).toContain("status"));
expect(drainStartup).toHaveBeenCalledWith("startup");
expect(operations).not.toContain("complete");
release();
const result = await checked;
if (preparationStopped) { expect(result).toEqual({ value: "completed", error: null }); expect(operations).toEqual(["stop", "status", "complete"]); }
else { expect(result.error?.message).toContain("termination is unconfirmed"); expect(fixture.sets).toContainEqual(expect.objectContaining({ status: "pending_cleanup", cleanupStatus: "failed" })); }
});
it.each([true, false])("checks startup preparation proof after resume observed the stop (%s)", async preparationStopped => {
const value = row();
Object.assign(value.lease.metadata, { runnerTaskDispatched: false,
runnerTaskStartupCleanup: { contextId: "startup", requiresPreparationStop: true } });
const fixture = database(value), workers = worker();
fixture.db.select = ((...args: unknown[]) => (database(value).db.select as (...values: unknown[]) => unknown)(...args)) as Db["select"];
Object.assign(workers, { drainStartup: vi.fn(async () => undefined) });
const operations: string[] = [];
let stopped = false;
workers.call.mockImplementation(async (...args: any[]) => {
const operation = args[2].operation.kind; operations.push(operation);
if (operation === "stop") stopped = true;
return operation === "status" ? { kind: "status", taskId: "attempt-1", phase: "cancelled", executionStopped: true, preparationStopped: preparationStopped || stopped }
: { kind: "accepted", taskId: "attempt-1" };
});
await expect(settleDispatchedEnvironmentTask(fixture.db, workers as never, { companyId: "company", id: leaseId }, { executionStopObserved: true })).resolves.toBe("completed");
expect(operations).toEqual(preparationStopped ? ["status", "complete"] : ["status", "stop", "status", "complete"]);
});
it("negotiates the transient context without reading transport for an older plugin", async () => {
const context = new NativeExecutionContext({ binding: { companyId: "company", agentId: "agent", runId: "run" } } as never, 1_000);
const workers = worker();
workers.call.mockImplementation(async (...args: any[]) => { args[5]?.(); return { kind: "description", taskId: "attempt-1", runner: { version: "fixture", digest: `sha256:${"a".repeat(64)}` } }; });
try {
await executeEnvironmentTask(database().db, workers as never, { companyId: "company", leaseId, operation: { kind: "describe" }, executionContext: context });
const sent = workers.call.mock.calls[0] as unknown as any[];
expect(sent[2]).toMatchObject({ executionContextSupported: 1 });
expect(sent[2].executionContext).toBeUndefined();
expect(state.identity).not.toHaveBeenCalled();
expect(state.config).not.toHaveBeenCalled();
expect(context.pending).toBe(false);
} finally { context.finish(); }
});
it("shares one transport lookup across the supported startup operations", async () => {
const context = new NativeExecutionContext({ binding: { companyId: "company", agentId: "agent", runId: "run" } } as never, 1_000);
context.pluginSupported = true;
const workers = worker();
workers.call.mockImplementation(async (...args: any[]) => {
args[5]?.();
return { kind: "description", taskId: "attempt-1", executionContextVersion: 1, runner: { version: "fixture", digest: `sha256:${"a".repeat(64)}` } };
});
try {
for (const kind of ["describe", "describe"] as const) await executeEnvironmentTask(database().db, workers as never,
{ companyId: "company", leaseId, operation: { kind }, executionContext: context });
expect(state.identity).toHaveBeenCalledOnce();
expect(state.config).toHaveBeenCalledOnce();
for (const call of workers.call.mock.calls as unknown as any[][]) expect(call[2].executionContext).toMatchObject({
id: context.id, deadlineAtMs: context.deadlineAtMs, transport: { instanceSecrets: { launcher: "synthetic-transient-binding" } },
});
} finally { context.finish(); }
});
it.each(["json", "wrong-run"])("rejects a %s context before the worker", async mode => {
const context = new NativeExecutionContext({ binding: { companyId: "company", agentId: "agent", runId: mode === "wrong-run" ? "other" : "run" } } as never, 1_000);
const workers = worker();
try {
await expect(executeEnvironmentTask(database().db, workers as never, { companyId: "company", leaseId, operation: { kind: "describe" },
executionContext: mode === "json" ? JSON.parse(JSON.stringify(context)) : context })).rejects.toThrow("native_execution_context");
expect(workers.call).not.toHaveBeenCalled();
} finally { context.finish(); }
});
it("removes transport material from worker error reporting", async () => {
const context = new NativeExecutionContext({ binding: { companyId: "company", agentId: "agent", runId: "run" } } as never, 1_000);
context.pluginSupported = true;
const workers = worker();
workers.call.mockImplementation(async (...args: any[]) => { args[5]?.(); throw new Error(JSON.stringify(args[2])); });
try {
await expect(executeEnvironmentTask(database().db, workers as never, { companyId: "company", leaseId, operation: { kind: "describe" }, executionContext: context }))
.rejects.toThrow("Plugin-provided Runner execution operation unavailable; reconcile the same task before retrying");
} finally { context.finish(); }
});
it("forwards a retained fresh directory intent on later launch calls and checks provider support", async () => {
const value = row();
value.lease.metadata.runnerTaskProjectAuthValidation.projectIds = [];
const fresh = { attemptId: leaseId, sourceRunId: secondProjectId, previousWorkspaceId: null, recoverySnapshots: [] };
Object.assign(value.lease.metadata, { freshWorkspace: fresh });
Object.assign(state.plugin.manifestJson.environmentDrivers[0], { freshWorkspaceVersion: 1 });
const workers = worker();
await executeEnvironmentTask(database(value, []).db, workers as never, { companyId: "company", leaseId, operation: { ...submit, projectIds: [] } });
expect(workers.call).toHaveBeenCalledWith("original", "environmentTask", expect.objectContaining({ fresh }), 15_000);
delete state.plugin.manifestJson.environmentDrivers[0].freshWorkspaceVersion;
const denied = worker();
await expect(executeEnvironmentTask(database(value, []).db, denied as never, { companyId: "company", leaseId,
operation: { ...submit, projectIds: [] } })).rejects.toThrow("fresh workspace preparation unavailable");
expect(denied.call).not.toHaveBeenCalled();
});
it("commits prior retained task-owner retirement through the environment cleanup boundary", async () => {
const value = row();
Object.assign(value.lease, { leasePolicy: "reuse_by_environment", provider: "sandbox" });
Object.assign(value.lease.metadata, { runnerTaskExecutionStopped: true });
const owner = { id: "previous-lease", companyId: "company", heartbeatRunId: "previous-run", provider: "sandbox",
providerLeaseId: "attempt-1", status: "retained", leasePolicy: "retain_on_failure", cleanupStatus: "failed" };
const fixture = database(value, [], [], [owner]);
await executeEnvironmentTask(fixture.db, worker() as never, { companyId: "company", leaseId, operation: { kind: "complete" } });
expect(fixture.transaction).toHaveBeenCalledOnce();
expect(fixture.sets).toEqual(expect.arrayContaining([expect.objectContaining({ status: "released", cleanupStatus: "success",
releasedAt: expect.any(Date), metadata: expect.anything() })]));
});
it("releases fresh transfer copies only after confirmed task completion", async () => {
const value = row();
const fresh = { attemptId: leaseId, sourceRunId: secondProjectId, previousWorkspaceId: null, recoverySnapshots: [] };
Object.assign(value.lease.metadata, { freshWorkspace: fresh });
const workers = worker();
await executeEnvironmentTask(database(value).db, workers as never, { companyId: "company", leaseId, operation: { kind: "complete" } });
expect(state.release).not.toHaveBeenCalled();
Object.assign(value.lease.metadata, { runnerTaskExecutionStopped: true });
await executeEnvironmentTask(database(value).db, workers as never, { companyId: "company", leaseId, operation: { kind: "complete" } });
expect(state.release).toHaveBeenCalledWith("company", fresh);
});
it("passes only the workspace binding pinned to this lease and provider", async () => {
const value = row(); value.lease.metadata.runnerTaskProjectAuthValidation.projectIds = [];
const binding = { pluginId: leaseId, projectId, executionWorkspaceId: secondProjectId, projectWorkspaceId: projectId,
sourceRevision: "revision", workspaceRef: "provider:checkout" };
state.plugin.id = binding.pluginId;
Object.assign(value.lease, { executionWorkspaceId: binding.executionWorkspaceId });
Object.assign(value.lease.metadata, { pluginId: binding.pluginId, workspaceProvider: binding });
const workspace = { id: binding.executionWorkspaceId, companyId: "company", providerType: "plugin", providerRef: binding.workspaceRef,
status: "active", metadata: { workspaceProvider: binding } };
const workers = worker();
await executeEnvironmentTask(database(value, [], [workspace]).db, workers as never, { companyId: "company", leaseId, operation: { ...submit, projectIds: [] } });
expect(workers.call).toHaveBeenCalledWith(binding.pluginId, "environmentTask", expect.objectContaining({ workspace: binding }), 15_000);
const denied = worker(); workspace.providerRef = "foreign";
await expect(executeEnvironmentTask(database(value, [], [workspace]).db, denied as never, { companyId: "company", leaseId, operation: { ...submit, projectIds: [] } })).rejects.toThrow("binding changed");
expect(denied.call).not.toHaveBeenCalled();
});
it("accepts artifact identity without arbitrary filesystem or execution settings", () => {
const operation = environmentTaskOperationSchema.parse({ kind: "describe" });
const description = { kind: "description", taskId: "attempt-1", runner: { version: "fixture", digest: `sha256:${"a".repeat(64)}` } };
expect(parseEnvironmentTaskResult(operation, "attempt-1", description)).toEqual(description);
for (const field of ["resources", "environment", "connection", "codexCommand"]) {
expect(() => parseEnvironmentTaskResult(operation, "attempt-1", { ...description, [field]: {} })).toThrow();
}
for (const kind of ["checkpoint", "read_file"]) {
expect(environmentTaskOperationSchema.safeParse({ kind }).success).toBe(false);
}
});
it("bounds file reads to the active task identity and validated project scope", async () => {
const value=row();
const identity={runnerInstanceId:"runner",environmentLeaseId:leaseId,runId:"run",normalizedSessionId:"session",turnId:"turn",itemId:"item"};
Object.assign(value.lease.metadata,{runnerTaskIdentity:{...submit.runner}});
const operation={kind:"read_file" as const,identity,projectIds:[projectId],path:"proof.txt",maxBytes:1024};
const result={kind:"file",taskId:"attempt-1",base64:"",byteSize:0,sha256:"a".repeat(64)};
const workers=worker(result);
await expect(executeEnvironmentTask(database(value).db,workers as never,{companyId:"company",leaseId,operation})).resolves.toEqual(result);
workers.call.mockClear();
for(const invalid of [{...operation,projectIds:[]},{...operation,identity:{...identity,itemId:"foreign"}}]) {
await expect(executeEnvironmentTask(database(value).db,workers as never,{companyId:"company",leaseId,operation:invalid})).rejects.toThrow();
}
value.lease.expiresAt=new Date(0);
await expect(executeEnvironmentTask(database(value).db,workers as never,{companyId:"company",leaseId,operation})).rejects.toThrow("not active");
expect(workers.call).not.toHaveBeenCalled();
value.lease.expiresAt=null;
workers.call.mockImplementation(async()=>{value.run!.status="cancelled";return result;});
await expect(executeEnvironmentTask(database(value).db,workers as never,{companyId:"company",leaseId,operation})).rejects.toThrow("operation unavailable");
for(const path of ["//etc/passwd","../escape","a/../b","a\\b","https://example.test/file"]) expect(environmentTaskOperationSchema.safeParse({...operation,path}).success).toBe(false);
expect(environmentTaskOperationSchema.safeParse({...operation,maxBytes:11*1024*1024}).success).toBe(false);
expect(()=>parseEnvironmentTaskResult(operation,"attempt-1",{...result,taskId:"other"})).toThrow();
});
it("reads only the current task's saved identity and rejects inactive checkpoint operations", async () => {
const value = row();
const identity = { runnerInstanceId: "runner", environmentLeaseId: "logical-lease", runId: "run",
normalizedSessionId: "session", turnId: "turn", itemId: "item" };
Object.assign(value.lease.metadata, { runnerTaskIdentity: { ...submit.runner, leaseId: identity.environmentLeaseId } });
const operation = { kind: "read_state" as const, identity };
const result = { kind: "state", taskId: "attempt-1", state: { schema: "paperclip.runner.durable.state.v1", ...identity, lifecycle: "suspended" } };
const workers = worker(result);
await expect(executeEnvironmentTask(database(value).db, workers as never, { companyId: "company", leaseId, operation })).resolves.toEqual(result);
expect(workers.call).toHaveBeenCalledOnce(); workers.call.mockClear();
await expect(executeEnvironmentTask(database(value).db, workers as never, { companyId: "company", leaseId,
operation: { ...operation, identity: { ...identity, itemId: "different" } } })).rejects.toThrow("identity mismatch");
value.lease.status = "released";
await expect(executeEnvironmentTask(database(value).db, workers as never, { companyId: "company", leaseId, operation })).rejects.toThrow("not active");
await expect(executeEnvironmentTask(database(value).db, workers as never, { companyId: "company", leaseId,
operation: { kind: "archive_state", priorIdentity: identity, archiveKey: "a".repeat(24), resumeFrom: "prior" } })).rejects.toThrow("not active");
expect(workers.call).not.toHaveBeenCalled();
expect(() => parseEnvironmentTaskResult(operation, "attempt-1", { ...result, taskId: "other" })).toThrow();
expect(environmentTaskOperationSchema.safeParse({ ...operation, path: "/arbitrary" }).success).toBe(false);
expect(environmentTaskOperationSchema.safeParse({ kind: "archive_state", priorIdentity: identity, archiveKey: "../escape", resumeFrom: "prior" }).success).toBe(false);
});
it.each(["retained", "expired"])("reads the exact successful warm owner's state during %s cleanup", async status => {
const value = row();
value.lease.status = status;
value.run!.status = "succeeded";
Object.assign(value.lease, {leasePolicy:"reuse_by_environment"});
Object.assign(value.lease.metadata, {runnerTaskDispatched:true,runnerTaskLifecyclePolicy:{mode:"warm",idleTimeoutMs:120000},runnerTaskIdentity:{...submit.runner}});
const identity = {runnerInstanceId:"runner",environmentLeaseId:leaseId,runId:"run",normalizedSessionId:"session",turnId:"turn",itemId:"item"};
const operation = {kind:"read_state" as const,identity};
const result = {kind:"state",taskId:"attempt-1",state:{schema:"paperclip.runner.durable.state.v1",...identity,lifecycle:"suspended"}};
const workers = worker(result);
await expect(executeEnvironmentTask(database(value).db,workers as never,{companyId:"company",leaseId,operation})).resolves.toEqual(result);
expect(workers.call).toHaveBeenCalledOnce();
for (const change of ["identity","policy","dispatch","lease","run"] as const) {
const changed = structuredClone(value);
if (change === "policy") Object.assign(changed.lease.metadata,{runnerTaskLifecyclePolicy:{mode:"per_turn",idleTimeoutMs:null}});
if (change === "dispatch") Object.assign(changed.lease.metadata,{runnerTaskDispatched:false});
if (change === "lease") changed.lease.status="released";
if (change === "run") changed.run!.status="cancelled";
const denied=worker(result);
await expect(executeEnvironmentTask(database(changed).db,denied as never,{companyId:"company",leaseId,
operation:change === "identity" ? {...operation,identity:{...identity,itemId:"other"}} : operation})).rejects.toThrow();
expect(denied.call).not.toHaveBeenCalled();
}
});
it("requires project validation for the exact configuration, provider, and projects before credential dispatch", async () => {
const operation = { ...submit, preparedLaunchId: "configuration", accountIdentity: "account",
credential: { type: "codex-auth-json" as const, authJson: '{"OPENAI_API_KEY":"never-leak"}' } };
const proof = { configurationId: "configuration", provider: "openai", projectIds: [projectId] };
for (const invalid of [undefined, { ...proof, configurationId: "other" }, { ...proof, provider: "anthropic" }, { ...proof, projectIds: [] }]) {
const value = row(); Object.assign(value.lease.metadata, { runnerTaskProjectAuthValidation: invalid });
const workers = worker();
await expect(executeEnvironmentTask(database(value).db, workers as never, { companyId: "company", leaseId, operation })).rejects.toThrow("validation unavailable");
expect(workers.call).not.toHaveBeenCalled();
}
const value = row(); Object.assign(value.lease.metadata, { runnerTaskProjectAuthValidation: proof });
await expect(executeEnvironmentTask(database(value).db, worker() as never, { companyId: "company", leaseId, operation })).resolves.toMatchObject({ kind: "accepted" });
await expect(executeEnvironmentTask(database(value).db, worker() as never, { companyId: "company", leaseId,
operation: { ...operation, credential: { type: "claude-env", environment: { ANTHROPIC_API_KEY: "never-leak" } } } })).rejects.toThrow("validation unavailable");
});
it.each(["allowed", "denied", "wrong-configuration", "wrong-provider", "timeout"])("records only a matching successful project validation (%s)", async mode => {
const operation = { kind: "check_project_auth" as const, configurationId: "configuration", provider: "openai" as const, projectIds: [projectId] };
const result = { kind: "project_auth", taskId: "attempt-1", configurationId: mode === "wrong-configuration" ? "other" : "configuration",
provider: mode === "wrong-provider" ? "anthropic" : "openai", allowed: mode !== "denied" };
const workers = worker(result); if (mode === "timeout") workers.call.mockRejectedValueOnce(new Error("timeout with private credential"));
const { db, sets } = database();
const checked = executeEnvironmentTask(db, workers as never, { companyId: "company", leaseId, operation });
if (["allowed", "denied"].includes(mode)) await expect(checked).resolves.toEqual(result);
else await expect(checked).rejects.toThrow("operation unavailable");
expect(sets).toHaveLength(mode === "allowed" ? 2 : 1);
expect(new PgDialect().sqlToQuery(sets[0].metadata as any).sql).toContain("- 'runnerTaskProjectAuthValidation'");
if (mode === "allowed") expect(JSON.parse(new PgDialect().sqlToQuery(sets[1].metadata as any).params[0] as string))
.toEqual({ runnerTaskProjectAuthValidation: { configurationId: "configuration", provider: "openai", projectIds: [projectId] } });
const denied = worker(result);
await expect(executeEnvironmentTask(database(row(), []).db, denied as never, { companyId: "company", leaseId, operation })).rejects.toThrow("project unavailable");
expect(denied.call).not.toHaveBeenCalled();
});
it("accepts prepare launch digests only when they match the requirements", async () => {
const operation = { kind: "prepare" as const, projectIds: [projectId], requirements: {
schema: "paperclip.runner.launch-requirements.v1" as const,
identity: { runnerInstanceId: "runner", environmentLeaseId: leaseId, runId: "run",
normalizedSessionId: "session", turnId: "turn", itemId: "item" },
provider: "codex" as const, model: "selected", instructions: "Core instructions", runtimeContext: null,
settings: {}, approvalPolicy: "on-request" as const, readOnly: false,
preparedConversation: false, includeCollaborationModeInstructions: true,
} };
const preparationDigest = runnerLaunchPreparationDigest(operation.requirements);
const runDigest = runnerLaunchRunDigest(preparationDigest, operation.requirements);
const result = { kind: "prepared", taskId: "attempt-1", launch: { configurationId: "configuration-1",
requirementsDigest: `sha256:${"a".repeat(64)}`, provider: { kind: "codex" } } };
const accepted = worker(result);
await expect(executeEnvironmentTask(database().db, accepted as never, { companyId: "company", leaseId,
operation: { ...operation, preparationDigest, runDigest } })).resolves.toEqual(result);
expect(accepted.call).toHaveBeenCalledWith("original", "environmentTask", expect.objectContaining({
operation: expect.objectContaining({ preparationDigest, runDigest }) }), 15_000);
const forged = `sha256:${"b".repeat(64)}`;
for (const digests of [{ preparationDigest: forged, runDigest }, { preparationDigest, runDigest: forged },
{ preparationDigest }, { runDigest }]) {
const refused = worker(result);
await expect(executeEnvironmentTask(database().db, refused as never, { companyId: "company", leaseId,
operation: { ...operation, ...digests } })).rejects.toThrow("launch digest mismatch");
expect(refused.call).not.toHaveBeenCalled();
}
});
it.each([[false, false], [true, false], [false, true], [true, true]])("prepares scoped configuration with submit-time auth %s and in-prepare auth %s", async (atSubmit, checked) => {
const operation = { kind: "prepare" as const, projectIds: [projectId], requirements: {
schema: "paperclip.runner.launch-requirements.v1" as const,
identity: { runnerInstanceId: "runner", environmentLeaseId: leaseId, runId: "run",
normalizedSessionId: "session", turnId: "turn", itemId: "item" },
provider: "codex" as const, model: "selected", instructions: "Core instructions", runtimeContext: null,
settings: {}, approvalPolicy: "on-request" as const, readOnly: false,
preparedConversation: false, includeCollaborationModeInstructions: true,
} };
const result = { kind: "prepared", taskId: "attempt-1", ...(atSubmit ? {projectAuthCheckAtSubmit: true} : {}),
...(checked ? {projectAuthChecked: true} : {}), launch: { configurationId: "configuration-1",
requirementsDigest: `sha256:${"a".repeat(64)}`, provider: { kind: "codex" } } };
const workers = worker(result), store = database();
await expect(executeEnvironmentTask(store.db, workers as never, { companyId: "company", leaseId, operation }))
.resolves.toEqual(result);
expect(workers.call).toHaveBeenCalledWith("original", "environmentTask", expect.objectContaining({
companyId: "company", runId: "run", agentId: "agent", projectIds: [projectId], operation,
}), 15_000);
expect(store.sets).toHaveLength(atSubmit || checked ? 2 : 1);
if (atSubmit || checked) expect(new PgDialect().sqlToQuery(store.sets[1].metadata as never).params).toContain(JSON.stringify({
runnerTaskProjectAuthValidation: { configurationId: "configuration-1", provider: "openai", projectIds: [projectId],
...(checked ? {} : { atSubmit: true }) },
}));
const denied = worker(result);
const inactive = row(); inactive.lease.status = "released";
for (const value of [null, inactive]) {
await expect(executeEnvironmentTask(database(value).db, denied as never, { companyId: "company", leaseId, operation })).rejects.toThrow();
}
await expect(executeEnvironmentTask(database().db, denied as never, { companyId: "company", leaseId,
operation: { ...operation, requirements: { ...operation.requirements, identity: { ...operation.requirements.identity, runId: "other" } } } }))
.rejects.toThrow("identity mismatch");
await expect(executeEnvironmentTask(database(row(), []).db, denied as never, { companyId: "company", leaseId, operation }))
.rejects.toThrow("project unavailable");
expect(denied.call).not.toHaveBeenCalled();
expect(() => parseEnvironmentTaskResult(operation, "attempt-1", { ...result, taskId: "other" })).toThrow();
expect(environmentTaskOperationSchema.safeParse({ ...operation, command: "sh" }).success).toBe(false);
});
it("allows only the private, unexpired setup identity on an ad-hoc lease", async () => {
const value = row();
Object.assign(value.lease, { heartbeatRunId: null, issueId: null }); value.run = null;
value.lease.metadata.runnerTaskProjectAuthValidation.projectIds = [];
Object.assign(value.lease.metadata, { runnerTaskProbe: { runId: "probe-run", sessionId: "probe-session", expiresAtMs: Date.now() + 60_000 } });
const operation = { ...submit, projectIds: [], runner: { ...submit.runner, runId: "probe-run", sessionId: "probe-session" },
launch: { runnerVersion: "fixture", runnerDigest: `sha256:${"a".repeat(64)}`,
maxOutboxBytes: 262144, p0ReserveBytes: 65536, maxRuntimeMs: 0, maxLifetimeMs: 0,
lifecyclePolicy: { mode: "per_turn" as const, idleTimeoutMs: null },
} };
const workers = worker();
await expect(executeEnvironmentTask(database(value).db, workers as never, { companyId: "company", leaseId, operation })).resolves.toMatchObject({ kind: "accepted" });
expect(workers.call).toHaveBeenCalledWith("original", "environmentTask", expect.objectContaining({ runId: "probe-run", projectIds: [] }), 15_000);
const lifetime = (workers.call.mock.calls[0] as unknown as [string, string, { operation: typeof operation }])[2].operation.launch.maxRuntimeMs;
expect(lifetime).toBeGreaterThan(0); expect(lifetime).toBeLessThanOrEqual(60_000);
expect((workers.call.mock.calls[0] as unknown as [string, string, { operation: typeof operation }])[2].operation.launch).not.toHaveProperty("maxLifetimeMs");
for (const invalid of [{ ...operation, projectIds: [projectId] }, { ...operation, runner: { ...operation.runner, sessionId: "other" } }, submit]) {
await expect(executeEnvironmentTask(database(value).db, workers as never, { companyId: "company", leaseId, operation: invalid })).rejects.toThrow("identity mismatch");
}
const metadataOperation = { kind: "copilot_metadata" as const, token: "never-persist-token", model: "selected" };
const receipt = { kind: "copilot_metadata", taskId: "attempt-1", metadata: {}, executionStopped: true };
const metadataDatabase = database(value);
await expect(executeEnvironmentTask(metadataDatabase.db, worker(receipt) as never, { companyId: "company", leaseId, operation: metadataOperation })).resolves.toEqual(receipt);
const savedParams = JSON.stringify(metadataDatabase.sets.flatMap(set => new PgDialect().sqlToQuery((set as any).metadata).params));
expect(savedParams).toContain("runnerTaskDispatched");
expect(savedParams).not.toContain("never-persist-token");
await expect(executeEnvironmentTask(database().db, worker(receipt) as never, { companyId: "company", leaseId, operation: metadataOperation })).rejects.toThrow("private setup lease");
expect(() => parseEnvironmentTaskResult(metadataOperation, "attempt-1", { ...receipt, executionStopped: false })).toThrow();
Object.assign(value.lease.metadata, { runnerTaskProbe: { runId: "probe-run", sessionId: "probe-session", expiresAtMs: Date.now() - 1 } });
await expect(executeEnvironmentTask(database(value).db, workers as never, { companyId: "company", leaseId, operation })).rejects.toThrow("not active");
await expect(executeEnvironmentTask(database(value).db, workers as never, { companyId: "company", leaseId, operation: metadataOperation })).rejects.toThrow("not active");
await expect(executeEnvironmentTask(database(value).db, workers as never, { companyId: "company", leaseId, operation: { kind: "stop" } })).resolves.toMatchObject({ kind: "accepted" });
});
it("dispatches with host-derived scope and a persisted attempt identity", async () => {
const { db, query } = database(); const workers = worker();
await expect(executeEnvironmentTask(db, workers as never, { companyId: "company", leaseId, operation: submit })).resolves.toEqual({ kind: "accepted", taskId: "attempt-1" });
const scope = new PgDialect().sqlToQuery(query.where.mock.calls[0][0]);
expect(scope.sql).toContain('"environment_leases"."company_id" =');
expect(scope.sql).toContain('"environment_leases"."id" =');
expect(scope.params).toEqual([leaseId, "company"]);
expect(workers.call).toHaveBeenCalledWith("original", "environmentTask", expect.objectContaining({
taskId: "attempt-1", companyId: "company", agentId: "agent", projectIds: [projectId], runId: "run", operation: submit,
}), 15_000);
});
it("validates every requested project in the task company before dispatch", async () => {
const operation = { ...submit, projectIds: [projectId, secondProjectId] };
const value = row(); value.lease.metadata.runnerTaskProjectAuthValidation.projectIds = operation.projectIds;
const { db, query } = database(value, [{ id: projectId }, { id: secondProjectId }]);
const workers = worker();
await executeEnvironmentTask(db, workers as never, { companyId: "company", leaseId, operation });
expect(workers.call).toHaveBeenCalledWith("original", "environmentTask", expect.objectContaining({ projectIds: operation.projectIds }), 15_000);
const scope = new PgDialect().sqlToQuery(query.where.mock.calls[2][0]);
expect(scope.sql).toContain('"projects"."company_id" =');
expect(scope.params).toEqual(["company", projectId, secondProjectId]);
const rejected = worker();
await expect(executeEnvironmentTask(database(row(), [{ id: projectId }]).db, rejected as never, { companyId: "company", leaseId, operation })).rejects.toThrow("project unavailable");
expect(rejected.call).not.toHaveBeenCalled();
});
it("validates unique project IDs and allows tasks with no project mounts", async () => {
for (const projectIds of [[projectId, projectId], ["invalid"], Array(65).fill(projectId)]) {
expect(environmentTaskOperationSchema.safeParse({ ...submit, projectIds }).success).toBe(false);
}
const workers = worker();
const value = row(); value.lease.metadata.runnerTaskProjectAuthValidation.projectIds = [];
await executeEnvironmentTask(database(value).db, workers as never, { companyId: "company", leaseId, operation: { ...submit, projectIds: [] } });
expect(workers.call).toHaveBeenCalledWith("original", "environmentTask", expect.objectContaining({ projectIds: [] }), 15_000);
});
it.each(["release", "resume"] as const)("sends the prepared project and fresh scope with a retained %s", async kind => {
const identity = { runnerInstanceId: "runner", environmentLeaseId: leaseId, runId: "run", normalizedSessionId: "session", turnId: "turn", itemId: "item" };
const operation = kind === "release" ? { kind, identity } : { kind, identity, bootstrapTicket: "transient-test-ticket" };
const result = kind === "release" ? { kind: "released", taskId: "attempt-1" } : { kind: "resume", taskId: "attempt-1", outcome: "resumed" };
const fresh = { attemptId: leaseId, sourceRunId: secondProjectId, previousWorkspaceId: null, recoverySnapshots: [] };
const value = row(); value.lease.status = "retained"; value.run!.status = "succeeded";
Object.assign(value.lease.metadata, { runnerTaskProjectIds: [projectId, secondProjectId], freshWorkspace: fresh });
const { db, query } = database(value, [{ id: projectId }, { id: secondProjectId }]);
const workers = worker(result);
await expect(executeEnvironmentTask(db, workers as never, { companyId: "company", leaseId, operation })).resolves.toEqual(result);
expect(workers.call).toHaveBeenCalledWith("original", "environmentTask", expect.objectContaining({
projectIds: [projectId, secondProjectId], fresh, operation }), 15_000);
const scope = new PgDialect().sqlToQuery(query.where.mock.calls[1][0]);
expect(scope.sql).toContain('"projects"."company_id" =');
expect(scope.params).toEqual(["company", projectId, secondProjectId]);
const unscoped = row(); unscoped.lease.status = "retained";
const plain = worker(result);
await executeEnvironmentTask(database(unscoped, []).db, plain as never, { companyId: "company", leaseId, operation });
const sent = (plain.call.mock.calls[0] as unknown as any[])[2];
expect(sent.projectIds).toEqual([]);
expect(sent).not.toHaveProperty("fresh");
const rejected = worker(result);
await expect(executeEnvironmentTask(database(value, [{ id: projectId }]).db, rejected as never, { companyId: "company", leaseId, operation }))
.rejects.toThrow("project unavailable");
expect(rejected.call).not.toHaveBeenCalled();
});
it("rejects an absent or cross-company lease before calling a worker", async () => {
const workers = worker();
await expect(executeEnvironmentTask(database(null).db, workers as never, { companyId: "other", leaseId, operation: submit })).rejects.toThrow("lease unavailable");
expect(workers.call).not.toHaveBeenCalled();
});
it("rejects mismatched Runner binding and inactive submission", async () => {
const workers = worker();
await expect(executeEnvironmentTask(database().db, workers as never, { companyId: "company", leaseId, operation: { ...submit, runner: { ...submit.runner, runId: "other" } } })).rejects.toThrow("identity mismatch");
const value = row(); value.lease.status = "released";
await expect(executeEnvironmentTask(database(value).db, workers as never, { companyId: "company", leaseId, operation: submit })).rejects.toThrow("not active");
expect(workers.call).not.toHaveBeenCalled();
});
it("uses the pinned provider for cleanup after environment edits", async () => {
const value = row(); value.lease.status = "released"; value.environment!.config.pluginKey = "replacement";
const workers = worker();
await executeEnvironmentTask(database(value).db, workers as never, { companyId: "company", leaseId, operation: { kind: "stop" } });
expect(workers.call).toHaveBeenCalledWith("original", "environmentTask", expect.objectContaining({ config: {}, operation: { kind: "stop" } }), 15_000);
});
it("keeps cleanup available after environment, run, and issue deletion", async () => {
const value = row(); value.environment = null; value.run = null;
for (const kind of ["stop", "complete", "status"] as const) {
const workers = worker(kind === "status" ? { kind: "status", taskId: "attempt-1", phase: "cancelled" } : undefined);
await executeEnvironmentTask(database(value).db, workers as never, { companyId: "company", leaseId, operation: { kind } });
expect(workers.call).toHaveBeenCalledWith("original", "environmentTask", expect.objectContaining({
config: {}, environmentId: null, runId: null, agentId: null, projectIds: [],
}), 15_000);
}
await expect(executeEnvironmentTask(database(value).db, worker() as never, { companyId: "company", leaseId, operation: submit })).rejects.toThrow("not active");
});
it("preserves opaque provider IDs in requests and receipts", async () => {
const value = row(); value.lease.providerLeaseId = `provider:attempt.${"x".repeat(120)}`;
const workers = worker({ kind: "accepted", taskId: value.lease.providerLeaseId });
await expect(executeEnvironmentTask(database(value).db, workers as never, { companyId: "company", leaseId, operation: { kind: "stop" } })).resolves.toMatchObject({ taskId: value.lease.providerLeaseId });
});
it("reconnects a successful retained warm task without granting new execution", async () => {
const value = row();
value.lease.status = "retained";
value.run!.status = "succeeded";
Object.assign(value.lease, { leasePolicy: "reuse_by_environment" });
Object.assign(value.lease.metadata, { runnerTaskDispatched: true,
runnerTaskExecutionStopped: false, runnerTaskIdentity: { ...submit.runner },
runnerTaskLifecyclePolicy: { mode: "warm", idleTimeoutMs: 120_000 } });
const connection = { kind: "connection", taskId: "attempt-1", endpoint: {
kind: "authenticated_websocket", websocketUrl: "wss://runner.example.test/connect", generation: "attempt-1",
secretHeaders: [{ name: "Authorization", value: "Bearer fixture" }],
} };
const workers = worker(connection);
await expect(executeEnvironmentTask(database(value).db, workers as never, {
companyId: "company", leaseId, operation: { kind: "connection" },
})).resolves.toEqual(connection);
expect(workers.call).toHaveBeenCalledOnce();
for (const operation of [submit, { kind: "describe" as const }]) {
const denied = worker();
await expect(executeEnvironmentTask(database(value).db, denied as never, {
companyId: "company", leaseId, operation,
})).rejects.toThrow("not active");
expect(denied.call).not.toHaveBeenCalled();
}
for (const change of ["retiring", "stopped", "undispatched", "per_turn", "expired", "superseded", "failed", "cancelled", "missing_identity", "foreign_identity", "deleted"] as const) {
const changed = structuredClone(value);
if (change === "retiring") Object.assign(changed.lease.metadata, { runnerTaskRetiring: true });
if (change === "stopped") Object.assign(changed.lease.metadata, { runnerTaskExecutionStopped: true });
if (change === "undispatched") Object.assign(changed.lease.metadata, { runnerTaskDispatched: false });
if (change === "per_turn") Object.assign(changed.lease.metadata, { runnerTaskLifecyclePolicy: { mode: "per_turn", idleTimeoutMs: null } });
if (change === "expired") changed.lease.expiresAt = new Date(0);
if (change === "superseded") changed.lease.status = "expired";
if (change === "failed" || change === "cancelled") changed.run!.status = change;
if (change === "missing_identity") Object.assign(changed.lease.metadata, { runnerTaskIdentity: undefined });
if (change === "foreign_identity") Object.assign(changed.lease.metadata, { runnerTaskIdentity: { ...submit.runner, runId: "other" } });
if (change === "deleted") changed.environment = null;
const denied = worker(connection);
await expect(executeEnvironmentTask(database(changed).db, denied as never, {
companyId: "company", leaseId, operation: { kind: "connection" },
}), change).rejects.toThrow("not active");
expect(denied.call).not.toHaveBeenCalled();
}
});
it("returns a validated connection for active execution", async () => {
const connection = { kind: "connection", taskId: "attempt-1", endpoint: {
kind: "authenticated_websocket", websocketUrl: "wss://runner.example.test/connect", generation: "attempt-1",
secretHeaders: [{ name: "Authorization", value: "Bearer fixture" }],
} };
const input = { companyId: "company", leaseId, operation: { kind: "connection" as const } };
await expect(executeEnvironmentTask(database().db, worker(connection) as never, input)).resolves.toEqual(connection);
for (const state of ["expired", "finished", "deleted"] as const) {
const value = row();
if (state === "expired") value.lease.expiresAt = new Date(0);
if (state === "finished") value.run!.status = "succeeded";
if (state === "deleted") value.environment = null;
const workers = worker(connection);
await expect(executeEnvironmentTask(database(value).db, workers as never, input)).rejects.toThrow("not active");
expect(workers.call).not.toHaveBeenCalled();
}
for (const endpoint of [
{ ...connection.endpoint, websocketUrl: "ws://runner.example.test/connect" },
{ ...connection.endpoint, websocketUrl: "wss://runner.example.test/connect?token=fixture" },
{ ...connection.endpoint, secretHeaders: [{ name: "Authorization", value: "fixture\r\nInjected: true" }] },
{ ...connection.endpoint, secretHeaders: [{ name: "Invalid Header", value: "fixture" }] },
]) {
await expect(executeEnvironmentTask(database().db, worker({ ...connection, endpoint }) as never, input)).rejects.toThrow("reconcile the same task");
}
});
it.each(["manifest", "worker"])("requires live %s support", async kind => {
const workers = worker();
if (kind === "manifest") state.plugin.manifestJson.environmentDrivers[0].supportsTasks = false;
else workers.getWorker.mockReturnValue({ supportedMethods: [] });
await expect(executeEnvironmentTask(database().db, workers as never, { companyId: "company", leaseId, operation: submit })).rejects.toThrow("provider unavailable");
expect(workers.call).not.toHaveBeenCalled();
});
it("forwards resume launch inputs without persisting them or exposing them in worker errors", async () => {
const identity = { runnerInstanceId: "runner", environmentLeaseId: leaseId, runId: "run", normalizedSessionId: "session", turnId: "turn", itemId: "item" };
const operation = { kind: "resume" as const, identity, bootstrapTicket: "transient-test-ticket",
credential: { type: "claude-env" as const, environment: { CLAUDE_CODE_OAUTH_TOKEN: "never-leak-token" } },
configuredEnvironment: { STRIPE_SECRET_KEY: "never-leak-variable" } };
const result = { kind: "resume", taskId: "attempt-1", outcome: "resumed" };
const retained = () => { const value = row(); value.lease.status = "retained"; value.run!.status = "succeeded"; return value; };
const store = database(retained());
const workers = worker(result);
await expect(executeEnvironmentTask(store.db, workers as never, { companyId: "company", leaseId, operation })).resolves.toEqual(result);
expect(workers.call).toHaveBeenCalledWith("original", "environmentTask", expect.objectContaining({ operation }), 15_000);
const persisted = JSON.stringify(store.sets.map(set => new PgDialect().sqlToQuery(set.metadata as never).params));
expect(persisted).not.toContain("never-leak-token");
expect(persisted).not.toContain("never-leak-variable");
const failing = worker();
failing.call.mockRejectedValue(Object.assign(new Error("resume failed for never-leak-token and never-leak-variable"), { data: operation }));
const error = await executeEnvironmentTask(database(retained()).db, failing as never, { companyId: "company", leaseId, operation }).catch(caught => caught);
expect(error.message).toBe("Plugin-provided Runner execution operation unavailable; reconcile the same task before retrying");
expect(JSON.stringify({ ...error, message: error.message })).not.toContain("never-leak-token");
expect(JSON.stringify({ ...error, message: error.message })).not.toContain("never-leak-variable");
expect(error.cause).toBeUndefined();
});
it("rejects wrong task receipts and sanitizes worker errors", async () => {
await expect(executeEnvironmentTask(database().db, worker({ kind: "accepted", taskId: "other" }) as never, { companyId: "company", leaseId, operation: submit })).rejects.toThrow("reconcile the same task");
const workers = worker(); workers.call.mockRejectedValue(new Error("private-credential"));
await expect(executeEnvironmentTask(database().db, workers as never, { companyId: "company", leaseId, operation: submit })).rejects.toThrow(/^Plugin-provided Runner execution operation unavailable; reconcile the same task before retrying$/);
});
it.each([submit, { kind: "status" } as const])("redacts even a valid source envelope outside a source submit (%j)", async operation => {
const workers = worker();
workers.call.mockRejectedValue(new JsonRpcCallError({ code: -32000, message: "synthetic-private-text", data: {
schema: "paperclip/environment-task-error/v1", diagnostic: { httpStatus: 409, errorCode: "SESSION_STATE_UNAVAILABLE", reason: "unresolved_operation" },
} }));
const error = await executeEnvironmentTask(database().db, workers as never, { companyId: "company", leaseId, operation }).catch(error => error);
expect(error.message).toBe("Plugin-provided Runner execution operation unavailable; reconcile the same task before retrying");
expect(readEnvironmentTaskErrorDiagnostic(error)).toBeNull();
});
it("keeps only the plugin's stable task error code through worker error sanitization", async () => {
const workers = worker();
workers.call.mockRejectedValue(Object.assign(new JsonRpcCallError({ code: -32002, message: "private-credential",
data: environmentTaskErrorCodeData(new PluginEnvironmentTaskError("runner_revision_mismatch")) }), { extra: "private-credential" }));
const error = await executeEnvironmentTask(database().db, workers as never, { companyId: "company", leaseId, operation: submit }).catch(caught => caught);
expect(error.message).toBe("Plugin-provided Runner execution operation unavailable; reconcile the same task before retrying");
expect(readEnvironmentTaskErrorCode(error)).toBe("runner_revision_mismatch");
expect(JSON.stringify({ ...error, message: error.message })).not.toContain("private-credential");
expect(error.cause).toBeUndefined();
workers.call.mockRejectedValue(new Error("The installed Runner does not match the expected revision"));
expect(readEnvironmentTaskErrorCode(await executeEnvironmentTask(database().db, workers as never, { companyId: "company", leaseId, operation: submit }).catch(caught => caught))).toBeNull();
});
it("accepts PRP identity characters and length limits", () => {
for (const field of ["runnerId", "leaseId", "runId", "sessionId", "turnId", "itemId"]) {
for (const value of ["session:part.1", "a".repeat(160)]) {
expect(environmentTaskOperationSchema.safeParse({ ...submit, runner: { ...submit.runner, [field]: value } }).success).toBe(true);
}
for (const value of ["a".repeat(161), "../escape", "a/b", ""]) {
expect(environmentTaskOperationSchema.safeParse({ ...submit, runner: { ...submit.runner, [field]: value } }).success).toBe(false);
}
}
});
it("validates the client's inclusive PRP version range", () => {
for (const range of [{ protocolMin: 1, protocolMax: 1 }, { protocolMin: 1, protocolMax: 2 }, { protocolMin: 3, protocolMax: 5 }]) {
expect(environmentTaskOperationSchema.safeParse({ ...submit, runner: { ...submit.runner, ...range } }).success).toBe(true);
}
for (const range of [
{ protocolMin: 0, protocolMax: 2 }, { protocolMin: 2, protocolMax: 1 },
{ protocolMin: 1.5, protocolMax: 2 }, { protocolMin: 1, protocolMax: 2.5 },
{ protocolMin: 1, protocolMax: Number.MAX_SAFE_INTEGER + 1 },
{ protocolMin: undefined, protocolMax: 2 }, { protocolMin: 1, protocolMax: undefined },
]) {
expect(environmentTaskOperationSchema.safeParse({ ...submit, runner: { ...submit.runner, ...range } }).success).toBe(false);
}
});
it("validates operation and result shape without making acceptance mean readiness", () => {
expect(environmentTaskOperationSchema.safeParse({ ...submit, surprise: true }).success).toBe(false);
expect(environmentTaskOperationSchema.safeParse({ ...submit, runner: { ...submit.runner, unknownField: true } }).success).toBe(false);
expect(() => parseEnvironmentTaskResult({ kind: "status" }, "attempt-1", { kind: "accepted", taskId: "attempt-1" })).toThrow();
expect(parseEnvironmentTaskResult(submit, "attempt-1", { kind: "accepted", taskId: "attempt-1" }).kind).toBe("accepted");
const rejected = { kind: "admission_rejected", taskId: "attempt-1", reason: "account_binding_mismatch" };
expect(parseEnvironmentTaskResult(submit, "attempt-1", rejected)).toEqual(rejected);
expect(() => parseEnvironmentTaskResult(submit, "attempt-2", rejected)).toThrow();
expect(() => parseEnvironmentTaskResult(submit, "attempt-1", { ...rejected, reason: "unknown" })).toThrow();
expect(() => parseEnvironmentTaskResult({ kind: "stop" }, "attempt-1", rejected)).toThrow();
});
});