fix(runner): refresh trusted system instructions before ACPX restore

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
DottaandPaperclip committed 2026-09-29 11:09:17 -05:00
1 parent aaf67099e9
commit 1d02ab77b2
6 files changed
+138 -10

No files matched your search

@@ -29,6 +29,7 @@ export interface CodexNativeSessionBackendOptions {
startedAt: string;
}) => Promise<void>;
transportFactory?: (context?: {
baseInstructions?: string;
providerRecoveryPolicy?: PersistedNativeSession["providerRecoveryPolicy"];
persistedSession?: Pick<
PersistedHarnessSession,
@@ -142,6 +143,8 @@ function createTransportBackedNativeSessionBackend(
"Return one semantic completion result.",
];
const baseInstructions = nativeSystemInstructions(input);
const transportFactory = options.transportFactory;
return new HarnessDriverBackend(
new CodexAppServerDriver({
...(input.provider.model ? { model: input.provider.model } : {}),
@@ -154,7 +157,7 @@ function createTransportBackedNativeSessionBackend(
input.provider.kind === "codex"
? (input.provider.approvalPolicy ?? "never")
: "never",
baseInstructions: nativeSystemInstructions(input),
baseInstructions,
instructionWorkingCopyRoot: "runtimeContext" in input ? input.runtimeContext.instructions.workingCopy?.rootPath : undefined,
includeSkillInstructions: isCodex && "runtimeContext" in input,
skillInputs: isCodex
@@ -177,7 +180,9 @@ function createTransportBackedNativeSessionBackend(
runnerInstanceId:
options.runnerInstanceId ?? `paperclip-native-${input.binding.runId}`,
onSpawn: options.onSpawn,
transportFactory: options.transportFactory,
transportFactory: transportFactory
? (context) => transportFactory({ ...context, baseInstructions })
: undefined,
dynamicTools: options.dynamicTools,
dynamicToolHandler: options.dynamicToolHandler,
completionFeedback: options.completionFeedback,
@@ -5,7 +5,7 @@ import { join } from "node:path";
import { afterEach, describe, expect, it } from "vitest";
import { parseNativeExecutionInput, type NativeExecutionInput } from "../contracts/native-execution.js";
import { NATIVE_RUNTIME_ASSET_SCHEMA, PAPERCLIP_EXECUTION_PROMPT, PAPERCLIP_EXECUTION_PROMPT_REVISION, nativeRuntimePromptDigest, canonicalNativeRuntimeContextDigest } from "../contracts/runtime-context.js";
import { NATIVE_RUNTIME_ASSET_SCHEMA, PAPERCLIP_EXECUTION_PROMPT, PAPERCLIP_EXECUTION_PROMPT_REVISION, nativeRuntimePromptDigest, canonicalNativeRuntimeContextDigest, composeNativeSystemInstructions } from "../contracts/runtime-context.js";
const contextRoots: string[] = [];
afterEach(() => { for (const root of contextRoots.splice(0)) rmSync(root, { recursive: true, force: true }); });
@@ -348,6 +348,29 @@ describe("native backend factory", () => {
await session.close({ reason: "test complete" });
});
it("supplies freshly composed instructions before the transport can read a recovered thread", async () => {
const prepared = preparedExecution(execution());
if (!("runtimeContext" in prepared)) throw new Error("fixture requires runtime context");
const input = { ...acpxExecution("codex"), runtimeContext: prepared.runtimeContext };
writeFileSync(join(input.runtimeContext.instructions.bundle.rootPath, "AGENTS.md"), "Updated custom entry.");
const transport = new FakeCodexTransport();
let captured: string | undefined;
const backend = createNativeSessionBackend(input, {
codexTransportFactory: (context) => {
expect(transport.calls).toHaveLength(0);
captured = context?.baseInstructions;
return transport;
},
environment: { ...process.env, PAPERCLIP_WORKSPACE_CWD: WORKSPACE },
});
const session = await backend.openSession({
identity: { runId: "run", sessionId: "session", companyId: "company", issueId: "issue", agentId: "agent" },
workingDirectory: WORKSPACE,
});
expect(captured).toBe(composeNativeSystemInstructions(input.runtimeContext, "Updated custom entry."));
await session.close({ reason: "test complete" });
});
it("does not allow remote workspace authority without runnerd", () => {
expect(() =>
createNativeSessionBackend(execution(), {
@@ -21,6 +21,7 @@ export interface NativeBackendFactoryOptions extends Omit<
"transportFactory"
> {
codexTransportFactory?: (context?: {
baseInstructions?: string;
providerRecoveryPolicy?: PersistedNativeSession["providerRecoveryPolicy"];
persistedSession?: Pick<
PersistedHarnessSession,
@@ -46,6 +46,7 @@ import {
PAPERCLIP_EXECUTION_PROMPT,
PAPERCLIP_EXECUTION_PROMPT_REVISION,
canonicalNativeRuntimeContextDigest,
composeNativeSystemInstructions,
nativeRuntimePromptDigest,
type NativeRuntimeContextSnapshot,
} from "../contracts/runtime-context.js";
@@ -491,13 +492,14 @@ it("restores ACPX with the current registered copy after the old run copy is col
const priorRoot = join(root, "prior-run-copy");
const currentRoot = join(root, "current-run-copy");
await Promise.all([mkdir(priorRoot), mkdir(currentRoot)]);
const context = (rootPath: string) => ({
instructions: {
workingCopy: { kind: "agent_files", rootPath, entryPath: "AGENTS.md" },
},
}) as NativeRuntimeContextSnapshot;
const context = (rootPath: string) => {
const value = assignedRuntimeContext(join(root, "skills"), join(rootPath, "bundle"));
value.instructions.workingCopy = { kind: "agent_files", rootPath, entryPath: "AGENTS.md" };
return value;
};
const prior = context(priorRoot);
const current = context(currentRoot);
const customInstructions = `Keep custom instructions intact. A historical path example is ${priorRoot}.`;
const desired = {
runnerInstanceId: "runner", environmentLeaseId: "lease", runId: "new-run",
normalizedSessionId: "same-session", turnId: "new-turn", itemId: "new-item",
@@ -506,6 +508,7 @@ it("restores ACPX with the current registered copy after the old run copy is col
kind: "acpx", agent: "copilot", runId: "old-run",
normalizedSessionId: "same-session", commandDigest: "sha256:immutable",
model: "explicit-model", runtimeContext: prior,
instructions: composeNativeSystemInstructions(prior, customInstructions),
};
const state = {
runAttachTemplate: { provider, workspace: { cwd: root } },
@@ -520,7 +523,13 @@ it("restores ACPX with the current registered copy after the old run copy is col
state, desired, null, undefined, current,
);
const restoredProvider = restored.provider as typeof provider;
expect(restoredProvider).toEqual({ ...provider, runId: desired.runId, runtimeContext: current });
expect(restoredProvider).toEqual({
...provider, runId: desired.runId, runtimeContext: current,
instructions: composeNativeSystemInstructions(current, customInstructions),
});
expect(restoredProvider.instructions).toContain(customInstructions);
expect(restoredProvider.instructions).not.toContain(`(AGENT_HOME) is ${priorRoot}.`);
expect(restoredProvider.instructions).toContain(`(AGENT_HOME) is ${currentRoot}.`);
expect(bindAcpxAgentFiles(restoredProvider.runtimeContext, [])?.root).toContain("current-run-copy");
expect(restored).not.toHaveProperty("text");
expect(state.runAttachTemplate.provider.runtimeContext).toBe(prior);
@@ -536,11 +545,62 @@ it("restores ACPX with the current registered copy after the old run copy is col
state, desired, null, undefined,
);
expect((live.provider as typeof provider).runtimeContext).toEqual(prior);
expect((live.provider as typeof provider).instructions).toBe(provider.instructions);
} finally {
await rm(root, { recursive: true, force: true });
}
});
it("retargets only composed instruction framing and retains legacy custom instructions", () => {
const prior = assignedRuntimeContext("/skills", "/old-bundle");
prior.instructions.workingCopy = { kind: "agent_files", rootPath: "/old-copy", entryPath: "AGENTS.md" };
const current = assignedRuntimeContext("/skills", "/new-bundle");
current.instructions.workingCopy = { kind: "agent_files", rootPath: "/new-copy", entryPath: "AGENTS.md" };
const desired = {
runnerInstanceId: "runner", environmentLeaseId: "lease", runId: "new-run",
normalizedSessionId: "same-session", turnId: "turn", itemId: "item",
};
const restore = (
oldContext: NativeRuntimeContextSnapshot,
nextContext: NativeRuntimeContextSnapshot | null,
instructions: string,
currentInstructions?: string,
) => (runnerdRecoveryInternals.rotatedRunAttachPayload(
{ runAttachTemplate: { provider: { kind: "acpx", runtimeContext: oldContext, instructions } } },
desired, null, undefined, nextContext,
currentInstructions === undefined ? undefined : { text: currentInstructions, context: nextContext },
).provider as { instructions: string }).instructions;
// A quoted complete old asset paragraph is custom text, not a rewrite target.
const quotedOldBlock = composeNativeSystemInstructions(prior, "").slice(prior.prompt.text.length);
for (const custom of ["", `Historical example:${quotedOldBlock}\n\nKeep this exact custom ending.`]) {
expect(restore(prior, current, composeNativeSystemInstructions(prior, custom)))
.toBe(composeNativeSystemInstructions(current, custom));
expect(restore(prior, null, composeNativeSystemInstructions(prior, custom)))
.toBe([prior.prompt.text, custom].filter(Boolean).join("\n\n"));
}
const noWorkingCopy = assignedRuntimeContext("/skills", "/plain-bundle");
expect(restore(noWorkingCopy, current, composeNativeSystemInstructions(noWorkingCopy, "Custom")))
.toBe(composeNativeSystemInstructions(current, "Custom"));
expect(restore(prior, noWorkingCopy, composeNativeSystemInstructions(prior, "Custom")))
.toBe(composeNativeSystemInstructions(noWorkingCopy, "Custom"));
const opaque = "Legacy custom instructions mention /old-copy; keep every byte.";
expect(restore(prior, current, opaque)).toBe(opaque);
const fresh = composeNativeSystemInstructions(current, "Updated registered entry content");
expect(restore(prior, current, composeNativeSystemInstructions(prior, "Old content"), fresh))
.toBe(fresh);
const remote = assignedRuntimeContext("/runner/skills", "/runner/context/instructions");
remote.instructions.workingCopy = { ...current.instructions.workingCopy, rootPath: "/runner/agent-home" };
const custom = "Current instructions keep a literal example /new-copy unchanged.";
const remoteProvider = runnerdRecoveryInternals.rotatedRunAttachPayload(
{ runAttachTemplate: { provider: { kind: "acpx", runtimeContext: prior, instructions: composeNativeSystemInstructions(prior, "Old") } } },
desired, null, undefined, remote,
{ text: composeNativeSystemInstructions(current, custom), context: current },
).provider as { instructions: string; runtimeContext: NativeRuntimeContextSnapshot };
expect(remoteProvider.instructions).toBe(composeNativeSystemInstructions(remote, custom));
expect(remoteProvider.runtimeContext).toEqual(remote);
});
it("replays the durable run attachment outcome and latest provider identity", () => {
expect(
runnerdRecoveryInternals.recoveredRunAttachment({
@@ -66,7 +66,7 @@ import {
createSanitizedAwsAgentCoreEnvironment,
createSanitizedClaudeManagedEnvironment,
} from "../drivers/claude-managed/environment.js";
import type { NativeRuntimeContextSnapshot } from "../contracts/runtime-context.js";
import { composeNativeSystemInstructions, type NativeRuntimeContextSnapshot } from "../contracts/runtime-context.js";
import type {
NativeAcpxPermissionMode,
NativeOpenCodePermissionMode,
@@ -419,6 +419,7 @@ function rotatedRunAttachPayload(
completionContract:
{ revision: string; criterionIds: readonly string[] } | undefined,
runtimeContext?: NativeRuntimeContextSnapshot | null,
currentInstructions?: { text: string; context: NativeRuntimeContextSnapshot | null },
): Record<string, unknown> {
const commands = Array.isArray(state.commands)
? state.commands.map(record)
@@ -445,9 +446,31 @@ function rotatedRunAttachPayload(
authorizedTools,
completionContract,
runtimeContext,
currentInstructions,
);
}
function retargetComposedInstructions(
instructions: string,
prior: NativeRuntimeContextSnapshot,
current: NativeRuntimeContextSnapshot | null,
): string {
const priorPrefix = prior.prompt.text;
const priorSuffix = composeNativeSystemInstructions(prior, "").slice(priorPrefix.length);
// Legacy callers can supply opaque system instructions. Only the composer's
// exact framing identifies a trusted asset block; never rewrite their text.
if (!instructions.startsWith(priorPrefix) || !instructions.endsWith(priorSuffix)) {
return instructions;
}
const custom = instructions.slice(priorPrefix.length, -priorSuffix.length);
if (custom && !custom.startsWith("\n\n")) return instructions;
// Keep custom entry bytes intact, including historical path examples or an
// identical paragraph quoted inside the entry. Only replace the final block.
return (current?.prompt.text ?? priorPrefix) + custom + (current
? composeNativeSystemInstructions(current, "").slice(current.prompt.text.length)
: "");
}
function retargetRunAttachPayload(
seedPayload: Record<string, unknown>,
desired: DurableRecoveryIdentity,
@@ -455,6 +478,7 @@ function retargetRunAttachPayload(
completionContract:
{ revision: string; criterionIds: readonly string[] } | undefined,
runtimeContext?: NativeRuntimeContextSnapshot | null,
currentInstructions?: { text: string; context: NativeRuntimeContextSnapshot | null },
): Record<string, unknown> {
const payload = structuredClone(seedPayload);
const provider = record(payload.provider);
@@ -465,6 +489,17 @@ function retargetRunAttachPayload(
// Restore the durable provider identity with the current authenticated
// context, never the prior run's now-stale filesystem grant.
if (runtimeContext !== undefined) {
if (currentInstructions !== undefined) {
provider.instructions = currentInstructions.context
? retargetComposedInstructions(currentInstructions.text, currentInstructions.context, runtimeContext)
: currentInstructions.text;
} else if (typeof provider.instructions === "string" && provider.runtimeContext) {
provider.instructions = retargetComposedInstructions(
provider.instructions,
provider.runtimeContext as NativeRuntimeContextSnapshot,
runtimeContext,
);
}
provider.runtimeContext = structuredClone(runtimeContext);
}
payload.provider = provider;
@@ -5150,6 +5185,9 @@ class DurablePrpCodexTransport implements CodexAppServerTransport {
this.#authorizedTools,
this.options.resumeCompletionContract,
runtimeContext,
this.options.baseInstructions === undefined
? undefined
: { text: this.options.baseInstructions, context: sourceRuntimeContext },
);
if (provider === "codex") {
// These controller-owned, token-free paths belong to the new run.
@@ -12509,6 +12509,7 @@ async function createRunnerdBackendWithinSessionClaim(
? input.execution.runtimeContext
: null,
runnerRuntimeContext: remoteRuntimeContext,
baseInstructions: recoveryContext?.baseInstructions,
runnerFilesystemRoot: remoteRunnerFilesystemRoot ?? undefined,
resumeWorkingDirectory: runnerExecution.workspace.cwd,
externallySandboxed: remoteTarget?.transport === "sandbox",