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>
This commit is contained in:
Nicky LeachandClaude Opus 5.5 authored and GitHub committed 2026-11-14 20:07:54 -08:00
1 parent b1e70ab6dd
commit a78be8b601
11 files changed
+204 -9

No files matched your search

+1 -1
View File
@@ -137,7 +137,7 @@ export { RunnerdDotDriver, type RunnerdDotDriverOptions } from "./drivers/dot/ru
export type { RunnerExecutionDriver } from "./control-plane/runner-execution-driver.js";
export { RUNNER_GITHUB_LAUNCHER_VERSION, bindRunnerLaunchResources, createRunnerProviderLaunch, runnerProviderLaunchRequirements, runnerLaunchRequirementsDigest, validatePreparedRunnerLaunch } from "./live/runner-provider-launch.js";
export { RUNNER_GITHUB_LAUNCHER_VERSION, bindRunnerLaunchResources, createRunnerProviderLaunch, runnerProviderLaunchRequirements, runnerLaunchPreparationDigest, runnerLaunchRequirementsDigest, runnerLaunchRunDigest, validatePreparedRunnerLaunch } from "./live/runner-provider-launch.js";
export type { RunnerProviderLaunchRequirements, RunnerProviderLaunchEnvironment, PreparedRunnerProviderLaunch, RunnerLaunchPreparer } from "./live/runner-provider-launch.js";
export { resolveGrokDisableWebSearch } from "./drivers/acpx/grok-web-search.js";
@@ -1,7 +1,7 @@
import { createHash } from "node:crypto";
import { canonicalNativeRuntimeContextDigest, composeNativeSystemInstructions, NATIVE_RUNTIME_ASSET_SCHEMA } from "../contracts/runtime-context.js";
import { describe, expect, it } from "vitest";
import { bindRunnerLaunchResources, createRunnerProviderLaunch, runnerLaunchRequirementsDigest, runnerProviderLaunchRequirements,
import { bindRunnerLaunchResources, createRunnerProviderLaunch, runnerLaunchPreparationDigest, runnerLaunchRequirementsDigest, runnerLaunchRunDigest, runnerProviderLaunchRequirements,
validatePreparedRunnerLaunch, type RunnerProviderLaunchRequirements } from "./runner-provider-launch.js";
const identity = { runnerInstanceId: "runner", environmentLeaseId: "lease", runId: "run",
@@ -96,3 +96,83 @@ describe("environment-owned launch contract", () => {
}
});
});
describe("launch preparation and run digests", () => {
const nextRun = { ...identity, runId: "next-run", turnId: "next-turn", itemId: "next-item" };
const withIdentity = (value: typeof identity) => ({ ...requirements(), identity: value });
it("keeps the preparation digest across runs of one Runner and changes the run digest", () => {
const first = runnerLaunchPreparationDigest(requirements());
expect(runnerLaunchPreparationDigest(withIdentity(nextRun))).toBe(first);
expect(first).toMatch(/^sha256:[a-f0-9]{64}$/);
expect(first).not.toBe(runnerLaunchRequirementsDigest(requirements()));
const run = runnerLaunchRunDigest(first, withIdentity(identity));
expect(run).toMatch(/^sha256:[a-f0-9]{64}$/);
expect(runnerLaunchRunDigest(first, withIdentity(nextRun))).not.toBe(run);
expect(runnerLaunchRunDigest(first, withIdentity({ ...identity, itemId: "other-item" }))).not.toBe(run);
expect(runnerLaunchRunDigest(first, withIdentity(identity))).toBe(run);
});
const zero = "0".repeat(64);
const one = "1".repeat(64);
type Context = NonNullable<RunnerProviderLaunchRequirements["runtimeContext"]>;
const baseContext = (): Omit<Context, "aggregateDigest"> => ({
prompt: { revision: "fixture", text: "Core policy", digest: createHash("sha256").update("Core policy").digest("hex") },
instructions: { entryPath: "AGENTS.md", bundle: { schema: NATIVE_RUNTIME_ASSET_SCHEMA,
rootPath: "/controller/instructions", digest: zero, manifestDigest: zero, fileCount: 1, totalBytes: 1 } },
skills: [{ key: "assigned", runtimeName: "assigned", versionId: "v1", bundle: {
schema: NATIVE_RUNTIME_ASSET_SCHEMA, rootPath: "/controller/skill", digest: zero, manifestDigest: zero, fileCount: 1, totalBytes: 1 } }],
mcp: { assignmentSetId: "assigned", digest: zero, bindingId: "native-mcp:run" },
});
const withContext = (value: typeof identity, change: (context: Omit<Context, "aggregateDigest">) => void = () => {}): RunnerProviderLaunchRequirements => {
const context = baseContext();
change(context);
return { ...requirements(), identity: value, runtimeContext: { ...context, aggregateDigest: canonicalNativeRuntimeContextDigest(context) } };
};
// MCP reaches the Runner through Core's tool authority on every run attachment, never through files the environment
// publishes, and Core keeps a warm session across an MCP-only change. So MCP belongs to the run digest only.
it("keeps the preparation digest across warm runs whose runtime context changes only in MCP", () => {
const first = withContext(identity);
const digest = runnerLaunchPreparationDigest(first);
const mcpChanges: Array<[string, RunnerProviderLaunchRequirements]> = [
["the run's binding", withContext(nextRun, context => { context.mcp.bindingId = "native-mcp:next-run"; })],
["no binding", withContext(nextRun, context => { context.mcp.bindingId = null; })],
["the assigned access set", withContext(nextRun, context => { context.mcp = { assignmentSetId: "other-set", digest: one, bindingId: "native-mcp:next-run" }; })],
];
for (const [label, next] of mcpChanges) {
expect(runnerLaunchPreparationDigest(next), label).toBe(digest);
expect(runnerLaunchRunDigest(digest, next), label).not.toBe(runnerLaunchRunDigest(digest, first));
}
// Within one run, an MCP change still changes the run digest.
const sameRun = withContext(identity, context => { context.mcp.assignmentSetId = "other-set"; });
expect(runnerLaunchRunDigest(digest, sameRun)).not.toBe(runnerLaunchRunDigest(digest, first));
});
it.each([
["instruction bundle", (context: Omit<Context, "aggregateDigest">) => { context.instructions.bundle.digest = one; }],
["instruction entry", (context: Omit<Context, "aggregateDigest">) => { context.instructions.entryPath = "CLAUDE.md"; }],
["skill bundle", (context: Omit<Context, "aggregateDigest">) => { context.skills[0]!.bundle.digest = one; }],
["skill set", (context: Omit<Context, "aggregateDigest">) => { context.skills = []; }],
["instruction working copy", (context: Omit<Context, "aggregateDigest">) => {
context.instructions.workingCopy = { rootPath: "/workspace/.paperclip-runtime/agent-files/agent/run", entryPath: "AGENTS.md", kind: "agent_files" }; }],
["connection instructions", (context: Omit<Context, "aggregateDigest">) => { context.connectionInstructions = { text: "Use the connector.", digest: one }; }],
])("changes the preparation digest when the %s changes", (_label, change) => {
expect(runnerLaunchPreparationDigest(withContext(identity, change))).not.toBe(runnerLaunchPreparationDigest(withContext(identity)));
});
it.each([
["runner instance", withIdentity({ ...identity, runnerInstanceId: "other-runner" })],
["environment lease", withIdentity({ ...identity, environmentLeaseId: "other-lease" })],
["session", withIdentity({ ...identity, normalizedSessionId: "other-session" })],
["instructions", { ...requirements(), instructions: "Changed instructions" }],
["model", { ...requirements(), model: "other-model" }],
["approval policy", { ...requirements(), approvalPolicy: "never" as const }],
["settings", { ...requirements(), settings: { ...requirements().settings, disableCodexWebSearch: true } }],
])("changes the preparation digest when the %s changes", (_label, changed) => {
const before = runnerLaunchPreparationDigest(requirements());
const after = runnerLaunchPreparationDigest(changed as RunnerProviderLaunchRequirements);
expect(after).not.toBe(before);
expect(runnerLaunchRunDigest(after, withIdentity(identity))).not.toBe(runnerLaunchRunDigest(before, withIdentity(identity)));
});
});
@@ -93,13 +93,51 @@ export function bindRunnerLaunchResources(
};
}
export function runnerLaunchRequirementsDigest(requirements: RunnerProviderLaunchRequirements): string {
const canonical = JSON.stringify(requirements, (_key, value: unknown) =>
value && typeof value === "object" && !Array.isArray(value)
? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) : value);
function canonicalDigest(value: unknown): string {
const canonical = JSON.stringify(value, (_key, entry: unknown) =>
entry && typeof entry === "object" && !Array.isArray(entry)
? Object.fromEntries(Object.entries(entry).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) : entry);
return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
}
export function runnerLaunchRequirementsDigest(requirements: RunnerProviderLaunchRequirements): string {
return canonicalDigest(requirements);
}
/**
* 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, and the runtime context's instruction and skill
* bundles, working copy and connection instructions. It leaves out what names one run (the run, turn and item ids) and
* the runtime context's MCP assignment and binding: MCP reaches the Runner through Core's tool authority on every run
* attachment, never through files the environment publishes, and Core already continues a warm session across an
* MCP-only change (`nativeRuntimeContextsMatch` with tool refresh). The context's `aggregateDigest` is left out with it,
* since it hashes the MCP assignment and every other field it covers is in this digest directly.
*/
export function runnerLaunchPreparationDigest(requirements: RunnerProviderLaunchRequirements): string {
const { runId: _runId, turnId: _turnId, itemId: _itemId, ...identity } = requirements.identity;
let runtimeContext: Omit<NativeRuntimeContextSnapshot, "mcp" | "aggregateDigest"> | null = null;
if (requirements.runtimeContext) {
const { mcp: _mcp, aggregateDigest: _aggregateDigest, ...prepared } = requirements.runtimeContext;
runtimeContext = prepared;
}
return canonicalDigest({ schema: "paperclip.runner.launch-preparation-digest.v1", requirements: { ...requirements, identity, runtimeContext } });
}
/**
* The preparation digest plus everything it leaves out: the run, turn and item ids, and the MCP assignment and binding.
* It is unique to one run's launch.
*/
export function runnerLaunchRunDigest(preparationDigest: string, requirements: {
identity: Pick<DurableRecoveryIdentity, "runId" | "turnId" | "itemId">;
runtimeContext: Pick<NativeRuntimeContextSnapshot, "mcp"> | null;
}): string {
const { identity } = requirements;
const mcp = requirements.runtimeContext?.mcp;
return canonicalDigest({ schema: "paperclip.runner.launch-run-digest.v1", preparationDigest,
runId: identity.runId, turnId: identity.turnId, itemId: identity.itemId,
mcp: mcp ? { assignmentSetId: mcp.assignmentSetId, digest: mcp.digest, bindingId: mcp.bindingId } : null });
}
function runnerLaunchPolicy(requirements: RunnerProviderLaunchRequirements): Record<string, unknown> {
return createRunnerProviderLaunch(requirements, {
options: { codexArgs: [] }, root: "/", cwd: "/", codexHome: "/",
@@ -95,6 +95,8 @@ export const environmentTaskOperationSchema = z.discriminatedUnion("kind", [
githubBroker: githubBroker.optional(),
recovery: preparedLaunch.optional(), resumeFrom: providerId.optional(),
priorIdentity: durableIdentity.optional(), accountIdentity: z.string().min(1).max(1024).optional(),
preparationDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/).optional(),
runDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/).optional(),
projectIds: z.array(z.string().uuid()).max(64).refine(ids => new Set(ids).size === ids.length, "Duplicate project IDs"),
}).strict(),
z.object({
@@ -206,6 +208,7 @@ export const environmentTaskResultSchema = z.discriminatedUnion("kind", [
githubCredentialBrokerVersion: z.literal(1).optional(),
configuredEnvironmentVersion: z.literal(1).optional(),
resumeLaunchInputsVersion: z.literal(1).optional(),
launchDigestVersion: z.literal(1).optional(),
}).strict(),
z.object({
kind: z.literal("status"), taskId: providerId,
@@ -5,6 +5,7 @@ import { environmentTaskErrorCodeData, environmentTaskOperationSchema, parseEnvi
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", () => ({
@@ -344,6 +345,33 @@ describe("plugin-provided Runner execution", () => {
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,
@@ -18,6 +18,7 @@ import type { PluginWorkerManager } from "./plugin-worker-manager.js";
import { NativeExecutionContext } from "./native-runtime/native-execution-context.js";
import { assertPluginTaskSourceAttachment, assertPluginTaskSourceRecovery } from "./native-runtime/plugin-task-source-recovery.js";
import { pluginAgentRuntimeIdentity } from "./plugin-agent-runtime-state.js";
import { runnerLaunchPreparationDigest, runnerLaunchRunDigest } from "../vendor/paperclip-runner/index.js";
import { assertPluginTaskOwnershipDispatch, PluginTaskOwnershipPendingError, readyPortableTaskSource, reconcilePluginTaskAdmission } from "./plugin-task-ownership.js";
export type PluginTaskDescription = Extract<PluginEnvironmentTaskResult, { kind: "description" }>;
@@ -61,6 +62,12 @@ export async function executeEnvironmentTask(db: Db, workers: Pick<PluginWorkerM
expectedTaskId?: string;
}): Promise<PluginEnvironmentTaskResult> {
const operation = environmentTaskOperationSchema.parse(input.operation);
if (operation.kind === "prepare" && (operation.preparationDigest !== undefined || operation.runDigest !== undefined)) {
const preparationDigest = runnerLaunchPreparationDigest(operation.requirements as Parameters<typeof runnerLaunchPreparationDigest>[0]);
if (operation.preparationDigest !== preparationDigest || operation.runDigest !== runnerLaunchRunDigest(preparationDigest, operation.requirements as Parameters<typeof runnerLaunchRunDigest>[1])) {
throw new Error("Plugin Runner launch digest mismatch");
}
}
const [row] = await db.select({ lease: environmentLeases, environment: environments, run: heartbeatRuns })
.from(environmentLeases)
.leftJoin(environments, eq(environments.id, environmentLeases.environmentId))
@@ -16657,6 +16657,7 @@ async function createRunnerdBackendWithinSessionClaim(
configuredEnvironment: taskConfiguredEnvironment,
releaseResumeVersion: description.releaseResumeVersion,
resumeLaunchInputsVersion: description.resumeLaunchInputsVersion,
launchDigestVersion: description.launchDigestVersion,
authorityRunId: description.releaseResumeVersion === 1 ? input.execution.binding.runId : undefined,
releasedSource: input.remoteWarmRecovery?.releasedSource,
sessionHandoff: !!input.remoteWarmRecovery?.portableSourceTaskId,
@@ -1,7 +1,7 @@
import { createHash } from "node:crypto";
import { describe, expect, it, vi } from "vitest";
import type { RunnerProviderLaunchRequirements } from "@paperclipai/paperclip-runner";
import type { RunnerProcessLaunchSpec } from "../../vendor/paperclip-runner/index.js";
import { runnerLaunchPreparationDigest, runnerLaunchRunDigest, type RunnerProcessLaunchSpec } from "../../vendor/paperclip-runner/index.js";
import { createPluginRunnerTaskOwner } from "./plugin-runner-task.js";
import { NativeExecutionContext } from "./native-execution-context.js";
@@ -831,6 +831,39 @@ it.each(["codex", "claude"])("reuses a warm %s process across run authorities wi
expect(nextTask.mock.calls.filter(([op])=>op.kind==="stop")).toHaveLength(1);
});
it.each([
["advertised", 1 as const],
["not advertised", undefined],
] as const)("launch digests are sent on prepare only when the plugin has %s them", async (_label, version) => {
const {task} = provider();
ingress.connect.mockReturnValue({ready:Promise.resolve(),close:async()=>{}});
const input = {taskId:"task",task,projectIds:[],harness:"codex",projectAuthCheckVersion:1 as const,warmTaskVersion:1 as const,
accountIdentity:"account",credentialIdentity:"revision",pollMs:1,launchDigestVersion:version};
const owner = createPluginRunnerTaskOwner(input);
await prepare(owner, launchRequirements("codex"));
const registration = await owner.registration({} as never,"run");
const spec = launchSpec(); spec.nativeRunner!.lifecyclePolicy = {mode:"warm",idleTimeoutMs:300000};
const handle = owner.launcher(spec); registration.activate(); await registration.ready();
const nextIdentity={...requirements.identity,runId:"next-run",turnId:"next-turn",itemId:"next-item"};
const nextRegistration=await owner.registration({} as never,"next-run");
await owner.driver.prepareLaunch!({...launchRequirements("codex"),identity:nextIdentity});
const prepares=task.mock.calls.map(([op])=>op).filter(op=>op.kind==="prepare");
expect(prepares).toHaveLength(2);
if (version === 1) {
const [first, next] = prepares as Array<{preparationDigest?:string;runDigest?:string}>;
expect(first.preparationDigest).toBe(runnerLaunchPreparationDigest(launchRequirements("codex")));
expect(next.preparationDigest).toBe(first.preparationDigest);
expect(first.runDigest).toBe(runnerLaunchRunDigest(first.preparationDigest!, launchRequirements("codex")));
expect(next.runDigest).toBe(runnerLaunchRunDigest(first.preparationDigest!, {...launchRequirements("codex"),identity:nextIdentity}));
expect(next.runDigest).not.toBe(first.runDigest);
} else {
for (const op of prepares) expect(op).not.toHaveProperty("preparationDigest");
for (const op of prepares) expect(op).not.toHaveProperty("runDigest");
}
await registration.release(); nextRegistration.activate(); await nextRegistration.ready();
await nextRegistration.release(); await nextRegistration.checkpoint("settled"); await handle.completion;
});
it.each([
["checked inside prepare", true, ["prepare"]],
["left to Core", false, ["prepare", "check_project_auth"]],
@@ -3,7 +3,7 @@ import { createHash } from "node:crypto";
import { setTimeout as delay } from "node:timers/promises";
import { environmentTaskOperationSchema, environmentTaskResultSchema, parseEnvironmentTaskResult, type PluginEnvironmentTaskOperation, type PluginEnvironmentTaskResult, type PluginEnvironmentTaskCredential } from "@paperclipai/plugin-sdk";
import type { RunnerIngressEndpoint } from "@paperclipai/adapter-utils/runner-connectivity";
import { RUNNER_PRP_PROTOCOL_MIN, RUNNER_PRP_PROTOCOL_MAX, type RunnerProcessHandle, type RunnerProcessLaunchSpec,
import { RUNNER_PRP_PROTOCOL_MIN, RUNNER_PRP_PROTOCOL_MAX, runnerLaunchPreparationDigest, runnerLaunchRunDigest, type RunnerProcessHandle, type RunnerProcessLaunchSpec,
type DurablePrpControlPlane, type RunnerExecutionDriver, type RunnerLaunchPreparer, type DurableRecoveryIdentity, type PrpEvent } from "../../vendor/paperclip-runner/index.js";
import { connectRunnerPrpIngress } from "../../realtime/runner-prp-outbound.js";
import type { NativeExecutionContext } from "./native-execution-context.js";
@@ -50,6 +50,7 @@ export function createPluginRunnerTaskOwner(input: {
warmTaskVersion?: 1;
releaseResumeVersion?: 1;
resumeLaunchInputsVersion?: 1;
launchDigestVersion?: 1;
releasedSource?: DurableRecoveryIdentity;
sessionHandoff?: boolean;
onResumed?: (identity: DurableRecoveryIdentity) => Promise<void>;
@@ -143,7 +144,9 @@ export function createPluginRunnerTaskOwner(input: {
if (input.githubBroker && input.githubCredentialBrokerVersion !== 1) {
throw new Error("Update the environment plugin to support the GitHub credential broker v1");
}
const preparationDigest = input.launchDigestVersion === 1 ? runnerLaunchPreparationDigest(requirements) : undefined;
const result = await call(environmentTaskOperationSchema.parse({ kind: "prepare", requirements,
...(preparationDigest ? { preparationDigest, runDigest: runnerLaunchRunDigest(preparationDigest, requirements) } : {}),
...(input.githubBroker ? { githubBroker: input.githubBroker } : {}),
projectIds: [...input.projectIds], ...(recovery ? { recovery } : {}),
...(input.resumeFrom && (!authorityRunId || !launchIdentity || launchIdentity.runId === authorityRunId || sourceRecovery)
+2
View File
@@ -107,6 +107,8 @@ export const runnerCodexDynamicToolsFit = runner.runnerCodexDynamicToolsFit;
export const admitToolInputSchema = runner.admitToolInputSchema;
export const TOOL_INPUT_SCHEMA_MAX_BYTES = runner.TOOL_INPUT_SCHEMA_MAX_BYTES;
export const canonicalToolInputSchema = runner.canonicalToolInputSchema;
export const runnerLaunchPreparationDigest = runner.runnerLaunchPreparationDigest;
export const runnerLaunchRunDigest = runner.runnerLaunchRunDigest;
export const inspectWarmRunTransition = runner.inspectWarmRunTransition;
export const inspectStagedRunAttachment = runner.inspectStagedRunAttachment;
export const inspectRetainedRunInstructions = runner.inspectRetainedRunInstructions;
@@ -13,7 +13,7 @@
"packages/plugins/sdk/src/environment-stop-error.ts": "b0e03f8aa2b2170ba095da5c7138050fced3f3cb",
"packages/plugins/sdk/src/environment-sync-error.ts": "7d6a51a95da49a7da4525aebbab6382dc5c44ae8",
"packages/plugins/sdk/src/environment-task-error.ts": "98aae8a06743b38884b68cb9a3ec44c57b34c0e4",
"packages/plugins/sdk/src/environment-tasks.ts": "e1f22476d4d73502bd4dc56afa3f863f3d1a275a",
"packages/plugins/sdk/src/environment-tasks.ts": "e1b60f9b27952079461889760b68ab79987a33a2",
"packages/plugins/sdk/src/host-client-factory.ts": "e0301c390ea13f2340b669383f07af2455e48c8a",
"packages/plugins/sdk/src/idle-drain.test.ts": "cc59f7881e7d46c89395a1d93d74f6c6b9b0a64a",
"packages/plugins/sdk/src/idle-drain.ts": "ae6e4c6be4657a3d541396922b3bc551b8db557f",