The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat(runner): add bounded ACPX turn lifecycle (#12403)
Dotta57449579ca39
diff --git a/packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.test.ts b/packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.test.tsindex 9bf7faf1b2..b3e2478eb0 100644--- a/packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.test.ts+++ b/packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.test.ts@@ -248,6 +248,36 @@ describe("Codex ACPX runtime adapter", () => {});});+ it("maps prompt turns to the admitted ACPX handle", async () => {+ const runtime = fakeRuntime();+ const turn = {+ requestId: "turn-1",+ promptStarted: Promise.resolve(),+ events: { async *[Symbol.asyncIterator]() {} },+ result: Promise.resolve({ status: "completed" as const }),+ cancel: vi.fn(),+ closeStream: vi.fn(),+ };+ vi.mocked(runtime.startTurn).mockReturnValue(turn);+ const port = await openCodexAcpxRuntime(openOptions(fakeCommand()), {+ createRegistry: () => registry(),+ createStore: () => store(),+ createRuntime: () => runtime,+ });+ const signal = new AbortController().signal;++ expect(+ port.startTurn({ text: "Complete the task.", requestId: "turn-1", signal }),+ ).toBe(turn);+ expect(runtime.startTurn).toHaveBeenCalledWith({+ handle: HANDLE,+ text: "Complete the task.",+ mode: "prompt",+ requestId: "turn-1",+ signal,+ });+ });+it("fails closed and closes the session when ACPX omits recovery identity", async () => {const runtime = fakeRuntime({ ...HANDLE, agentSessionId: undefined });await expect(diff --git a/packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.ts b/packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.tsindex ade6610540..e8737a4ec4 100644--- a/packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.ts+++ b/packages/paperclip-runner/src/drivers/acpx/codex-runtime-adapter.ts@@ -585,6 +585,15 @@ function runtimePort(},}: {}),+ startTurn(input) {+ return runtime.startTurn({+ handle,+ text: input.text,+ mode: "prompt",+ requestId: input.requestId,+ ...(input.signal ? { signal: input.signal } : {}),+ });+ },async close(input) {const errors = await admissionCleanup.run(handle, input.reason);if (errors.length > 0) {diff --git a/packages/paperclip-runner/src/drivers/acpx/runtime-host.test.ts b/packages/paperclip-runner/src/drivers/acpx/runtime-host.test.tsindex e879fb2bb5..b837f5fac7 100644--- a/packages/paperclip-runner/src/drivers/acpx/runtime-host.test.ts+++ b/packages/paperclip-runner/src/drivers/acpx/runtime-host.test.ts@@ -4,6 +4,7 @@ import { join } from "node:path";import { afterEach, describe, expect, it, vi } from "vitest";+import { stageManagedCodexCredential } from "./codex-credentials.js";import type {VerifiedAcpxCommandLease,VerifiedAcpxInstallation,@@ -13,6 +14,7 @@ import {AcpxRuntimeHost,type AcpxRuntimeHostDependencies,type AcpxRuntimePort,+ type AcpxRuntimeTurn,} from "./runtime-host.js";const temporaryDirectories: string[] = [];@@ -227,7 +229,7 @@ describe("ACPX runtime host", () => {expect(fixture.commandClose).toHaveBeenCalledOnce();});- it("attempts every cleanup when runtime shutdown fails", async () => {+ it("retains credential ownership when runtime shutdown fails until retry succeeds", async () => {const fixture = await hostFixture();let failClose = true;const runtime = runtimePort({@@ -252,12 +254,263 @@ describe("ACPX runtime host", () => {await expect(host.close({ reason: "first close" })).rejects.toThrow(/cleanup failed/,);- await expect(readFile(authPath)).rejects.toMatchObject({ code: "ENOENT" });+ await expect(readFile(authPath, "utf8")).resolves.toBe("{}");+ await expect(+ stageManagedCodexCredential({+ agentHomeDirectory: join(host.runtimeRoot(), "codex-home"),+ environment: {+ PAPERCLIP_ACPX_CODEX_AUTH_JSON_SECRET: '{"owner":"contender"}',+ },+ }),+ ).rejects.toThrow("already has an active lease");expect(fixture.commandClose).toHaveBeenCalledOnce();failClose = false;await expect(host.close({ reason: "retry close" }),).resolves.toBeUndefined();+ await expect(readFile(authPath)).rejects.toMatchObject({ code: "ENOENT" });+ const contender = await stageManagedCodexCredential({+ agentHomeDirectory: join(host.runtimeRoot(), "codex-home"),+ environment: {+ PAPERCLIP_ACPX_CODEX_AUTH_JSON_SECRET: '{"owner":"contender"}',+ },+ });+ await contender.close();+ });++ it("scrubs credentials only after the exact pending runtime close resolves", async () => {+ const fixture = await hostFixture();+ let resolveRuntimeClose!: () => void;+ const runtimeClose = new Promise<void>((resolve) => {+ resolveRuntimeClose = resolve;+ });+ const runtime = runtimePort({+ onClose: vi.fn(() => runtimeClose),+ });+ const host = await AcpxRuntimeHost.open(+ {+ ...fixture.options,+ agent: "codex",+ model: "gpt-5.6-sol",+ permissionMode: "approve-all",+ environment: { PAPERCLIP_ACPX_CODEX_AUTH_JSON_SECRET: "{}" },+ },+ fixture.dependencies({ openRuntime: async () => runtime }),+ );+ const credentialHome = join(host.runtimeRoot(), "codex-home");+ const authPath = join(credentialHome, "auth.json");++ const first = host.close({ reason: "runtime close pending" });+ await vi.waitFor(() => expect(runtime.close).toHaveBeenCalledOnce());+ await vi.waitFor(() => expect(fixture.commandClose).toHaveBeenCalledOnce());+ const second = host.close({ reason: "same exact close" });+ await expect(readFile(authPath, "utf8")).resolves.toBe("{}");+ await expect(+ stageManagedCodexCredential({+ agentHomeDirectory: credentialHome,+ environment: {+ PAPERCLIP_ACPX_CODEX_AUTH_JSON_SECRET: '{"owner":"contender"}',+ },+ }),+ ).rejects.toThrow("already has an active lease");+ expect(runtime.close).toHaveBeenCalledOnce();++ resolveRuntimeClose();+ await expect(Promise.all([first, second])).resolves.toEqual([+ undefined,+ undefined,+ ]);+ await expect(readFile(authPath)).rejects.toMatchObject({ code: "ENOENT" });+ const contender = await stageManagedCodexCredential({+ agentHomeDirectory: credentialHome,+ environment: {+ PAPERCLIP_ACPX_CODEX_AUTH_JSON_SECRET: '{"owner":"contender"}',+ },+ });+ await contender.close();+ });++ it("admits one bounded turn and cancels it before shutdown", async () => {+ const fixture = await hostFixture();+ const turn = runtimeTurn();+ const startTurn = vi.fn(() => turn);+ const runtime = runtimePort({ startTurn });+ const host = await AcpxRuntimeHost.open(+ {+ ...fixture.options,+ agent: "codex",+ model: "gpt-5.6-sol",+ permissionMode: "approve-reads",+ environment: { PAPERCLIP_ACPX_CODEX_AUTH_JSON_SECRET: "{}" },+ },+ fixture.dependencies({ openRuntime: async () => runtime }),+ );++ expect(+ host.startTurn({ text: "Complete the task.", requestId: "turn-1" }),+ ).toBe(turn);+ expect(startTurn).toHaveBeenCalledWith({+ text: "Complete the task.",+ requestId: "turn-1",+ });+ expect(() =>+ host.startTurn({ text: "Concurrent", requestId: "turn-2" }),+ ).toThrow("already has an active turn");++ await host.close({ reason: "shutdown" });+ expect(turn.cancel).toHaveBeenCalledWith({ reason: "shutdown" });+ expect(runtime.close).toHaveBeenCalledOnce();+ expect(() => host.startTurn({ text: "Late", requestId: "turn-3" })).toThrow(+ "is closing",+ );+ });++ it("rejects oversized turn inputs before calling the runtime", async () => {+ const fixture = await hostFixture();+ const runtime = runtimePort();+ const host = await AcpxRuntimeHost.open(+ {+ ...fixture.options,+ agent: "codex",+ model: "gpt-5.6-sol",+ permissionMode: "approve-reads",+ environment: { PAPERCLIP_ACPX_CODEX_AUTH_JSON_SECRET: "{}" },+ },+ fixture.dependencies({ openRuntime: async () => runtime }),+ );++ expect(() => host.startTurn({ text: "ok", requestId: " " })).toThrow(+ "request id",+ );+ expect(() =>+ host.startTurn({ text: "x".repeat(1024 * 1024 + 1), requestId: "turn" }),+ ).toThrow("turn text");+ expect(runtime.startTurn).not.toHaveBeenCalled();+ await host.close({ reason: "complete" });+ });++ it("cleans runtime resources after a turn cancellation timeout", async () => {+ vi.useFakeTimers();+ try {+ const fixture = await hostFixture();+ const turn = runtimeTurn();+ turn.cancel.mockImplementation(() => new Promise(() => undefined));+ const runtime = runtimePort({ startTurn: () => turn });+ const host = await AcpxRuntimeHost.open(+ {+ ...fixture.options,+ agent: "codex",+ model: "gpt-5.6-sol",+ permissionMode: "approve-reads",+ environment: { PAPERCLIP_ACPX_CODEX_AUTH_JSON_SECRET: "{}" },+ },+ fixture.dependencies({ openRuntime: async () => runtime }),+ );+ host.startTurn({ text: "Complete the task.", requestId: "turn-1" });++ const closing = host.close({ reason: "shutdown" });+ await vi.advanceTimersByTimeAsync(2_000);+ await expect(closing).rejects.toThrow(/cleanup failed/);+ expect(turn.cancel).toHaveBeenCalledOnce();+ expect(runtime.close).toHaveBeenCalledOnce();+ expect(fixture.commandClose).toHaveBeenCalledOnce();+ await expect(+ host.close({ reason: "observe completed cleanup" }),+ ).resolves.toBeUndefined();+ expect(turn.cancel).toHaveBeenCalledOnce();+ expect(runtime.close).toHaveBeenCalledOnce();+ expect(fixture.commandClose).toHaveBeenCalledOnce();+ } finally {+ vi.useRealTimers();+ }+ });++ it("retains the cancellation handle while runtime cleanup remains retryable", async () => {+ const fixture = await hostFixture();+ const turn = runtimeTurn();+ let failRuntimeClose = true;+ const runtime = runtimePort({+ startTurn: () => turn,+ onClose: async () => {+ if (failRuntimeClose) throw new Error("runtime cleanup failed");+ },+ });+ const host = await AcpxRuntimeHost.open(+ {+ ...fixture.options,+ agent: "codex",+ model: "gpt-5.6-sol",+ permissionMode: "approve-reads",+ environment: { PAPERCLIP_ACPX_CODEX_AUTH_JSON_SECRET: "{}" },+ },+ fixture.dependencies({ openRuntime: async () => runtime }),+ );+ host.startTurn({ text: "Complete the task.", requestId: "turn-1" });+ const credentialHome = join(host.runtimeRoot(), "codex-home");+ const authPath = join(credentialHome, "auth.json");++ await expect(host.close({ reason: "first shutdown" })).rejects.toThrow(+ /cleanup failed/,+ );+ expect(turn.cancel).toHaveBeenCalledOnce();+ await expect(readFile(authPath, "utf8")).resolves.toBe("{}");+ await expect(+ stageManagedCodexCredential({+ agentHomeDirectory: credentialHome,+ environment: {+ PAPERCLIP_ACPX_CODEX_AUTH_JSON_SECRET: '{"owner":"contender"}',+ },+ }),+ ).rejects.toThrow("already has an active lease");++ failRuntimeClose = false;+ await expect(+ host.close({ reason: "retry shutdown" }),+ ).resolves.toBeUndefined();+ expect(turn.cancel).toHaveBeenCalledTimes(2);+ expect(runtime.close).toHaveBeenCalledTimes(2);+ await expect(readFile(authPath)).rejects.toMatchObject({ code: "ENOENT" });+ });++ it("retains a settled turn when shutdown cleanup must be retried", async () => {+ const fixture = await hostFixture();+ let settleTurn!: (value: { stopReason: string }) => void;+ const turn = {+ ...runtimeTurn(),+ result: new Promise<{ stopReason: string }>((resolve) => {+ settleTurn = resolve;+ }),+ };+ let failRuntimeClose = true;+ const runtime = runtimePort({+ startTurn: () => turn,+ onClose: async () => {+ if (failRuntimeClose) throw new Error("runtime cleanup failed");+ },+ });+ const host = await AcpxRuntimeHost.open(+ {+ ...fixture.options,+ agent: "codex",+ model: "gpt-5.6-sol",+ permissionMode: "approve-reads",+ environment: { PAPERCLIP_ACPX_CODEX_AUTH_JSON_SECRET: "{}" },+ },+ fixture.dependencies({ openRuntime: async () => runtime }),+ );+ host.startTurn({ text: "Complete the task.", requestId: "turn-1" });++ const firstClose = host.close({ reason: "first shutdown" });+ settleTurn({ stopReason: "end_turn" });+ await expect(firstClose).rejects.toThrow(/cleanup failed/);+ expect(turn.cancel).toHaveBeenCalledOnce();++ failRuntimeClose = false;+ await expect(+ host.close({ reason: "retry shutdown" }),+ ).resolves.toBeUndefined();+ expect(turn.cancel).toHaveBeenCalledTimes(2);+ expect(runtime.close).toHaveBeenCalledTimes(2);});it("closes a command lease that resolves after admission is aborted", async () => {@@ -412,6 +665,7 @@ function runtimePort(input: {getStatus?: AcpxRuntimePort["getStatus"];setModel?: NonNullable<AcpxRuntimePort["setModel"]>;+ startTurn?: AcpxRuntimePort["startTurn"];onClose?: AcpxRuntimePort["close"];} = {},): AcpxRuntimePort & { close: ReturnType<typeof vi.fn> } {@@ -430,10 +684,28 @@ function runtimePort(},})),...(input.setModel ? { setModel: input.setModel } : {}),+ startTurn: vi.fn(input.startTurn ?? (() => runtimeTurn())),close: vi.fn(input.onClose ?? (async () => undefined)),};}+function runtimeTurn(): AcpxRuntimeTurn & {+ cancel: ReturnType<typeof vi.fn>;+} {+ return {+ requestId: "turn-1",+ promptStarted: Promise.resolve(),+ events: {+ async *[Symbol.asyncIterator]() {+ yield { type: "text_delta" as const, text: "done" };+ },+ },+ result: new Promise(() => undefined),+ cancel: vi.fn(async () => undefined),+ closeStream: vi.fn(async () => undefined),+ };+}+async function hostFixture() {const root = await mkdtemp(join(tmpdir(), "paperclip-acpx-host-"));temporaryDirectories.push(root);diff --git a/packages/paperclip-runner/src/drivers/acpx/runtime-host.ts b/packages/paperclip-runner/src/drivers/acpx/runtime-host.tsindex c6ec72dc4f..9c8a2fa353 100644--- a/packages/paperclip-runner/src/drivers/acpx/runtime-host.ts+++ b/packages/paperclip-runner/src/drivers/acpx/runtime-host.ts@@ -1,3 +1,5 @@+import type { AcpRuntimeEvent, AcpRuntimeTurnResult } from "acpx/runtime";+import type { NativeAcpxPermissionMode } from "../../contracts/native-execution.js";import {stageManagedCodexCredential,@@ -31,17 +33,35 @@ import {} from "./runtime-sandbox.js";import type { AcpxExpectedSessionIdentity } from "./sidecar-protocol.js";+const TURN_CANCELLATION_TIMEOUT_MS = 2_000;+export interface AcpxRuntimePortIdentity {acpxRecordId: string;backendSessionId: string;agentSessionId: string;}+export interface AcpxRuntimeTurnInput {+ text: string;+ requestId: string;+ signal?: AbortSignal;+}++export interface AcpxRuntimeTurn {+ readonly requestId: string;+ readonly promptStarted: Promise<void>;+ readonly events: AsyncIterable<AcpRuntimeEvent>;+ readonly result: Promise<AcpRuntimeTurnResult>;+ cancel(input?: { reason?: string }): Promise<void>;+ closeStream(input?: { reason?: string }): Promise<void>;+}+/** Minimal third-party ACP runtime surface admitted by the host boundary. */export interface AcpxRuntimePort {identity(): Promise<AcpxRuntimePortIdentity>;getStatus(): Promise<AcpxModelStatus>;setModel?(model: string): Promise<void>;+ startTurn(input: AcpxRuntimeTurnInput): AcpxRuntimeTurn;close(input: { reason: string }): Promise<void>;}@@ -105,6 +125,9 @@ export class AcpxRuntimeHost {readonly #sandbox: AcpxRuntimeSandbox;readonly #credential: ManagedCodexCredentialLease | null;readonly #command: VerifiedAcpxCommandLease;+ #activeTurn: AcpxRuntimeTurn | null = null;+ #closingStarted = false;+ #closePromise: Promise<void> | null = null;#closed = false;private constructor(input: {@@ -281,16 +304,75 @@ export class AcpxRuntimeHost {return Object.freeze({ ...this.#sandbox.persistedEnvironment });}+ startTurn(input: AcpxRuntimeTurnInput): AcpxRuntimeTurn {+ if (this.#closed || this.#closingStarted) {+ throw new Error("ACPX runtime host is closing");+ }+ if (this.#activeTurn) {+ throw new Error("ACPX runtime host already has an active turn");+ }+ const requestId = boundedRequestId(input.requestId);+ const text = boundedTurnText(input.text);+ const turn = this.#runtime.startTurn({+ text,+ requestId,+ ...(input.signal ? { signal: input.signal } : {}),+ });+ this.#activeTurn = turn;+ void turn.result+ .finally(() => {+ // Once shutdown owns this turn, retain its cancellation handle until+ // runtime cleanup succeeds. The result may settle while cleanup is+ // failing, and a later close must still be able to retry cancellation.+ if (this.#activeTurn === turn && !this.#closingStarted) {+ this.#activeTurn = null;+ }+ })+ .catch(() => undefined);+ return turn;+ }+async close(input: { reason: string }): Promise<void> {if (this.#closed) return;- const error = await cleanupRuntimeResources(+ if (this.#closePromise) return await this.#closePromise;+ this.#closingStarted = true;+ const closePromise = this.#close(boundedReason(input.reason));+ this.#closePromise = closePromise;+ try {+ await closePromise;+ this.#closed = true;+ } finally {+ if (this.#closePromise === closePromise) this.#closePromise = null;+ }+ }++ async #close(reason: string): Promise<void> {+ const errors: unknown[] = [];+ const activeTurn = this.#activeTurn;+ if (activeTurn) {+ try {+ const cancellationError = await boundedCancellation(+ activeTurn.cancel({ reason }),+ );+ if (cancellationError !== null) errors.push(cancellationError);+ } catch (error) {+ errors.push(error);+ }+ }+ const cleanupError = await cleanupRuntimeResources(this.#runtime,this.#credential,this.#command,- boundedReason(input.reason),+ reason,);- if (error) throw error;- this.#closed = true;+ if (!cleanupError) {+ if (this.#activeTurn === activeTurn) this.#activeTurn = null;+ this.#closed = true;+ }+ if (cleanupError) errors.push(...cleanupError.errors);+ if (errors.length > 0) {+ throw new AggregateError(errors, "ACPX runtime cleanup failed");+ }}}@@ -405,25 +487,69 @@ function retainRuntimeHostCleanup(cleanup: Promise<unknown>): void {.catch(() => undefined);}+async function boundedCancellation(+ cancellation: Promise<void>,+): Promise<unknown | null> {+ let timer: ReturnType<typeof setTimeout> | undefined;+ const outcome = await Promise.race([+ cancellation.then(+ () => ({ error: null }),+ (error: unknown) => ({ error }),+ ),+ new Promise<{ error: unknown }>((resolve) => {+ timer = setTimeout(+ () =>+ resolve({+ error: new Error(+ "ACPX turn cancellation exceeded its shutdown timeout",+ ),+ }),+ TURN_CANCELLATION_TIMEOUT_MS,+ );+ }),+ ]);+ if (timer) clearTimeout(timer);+ return outcome.error;+}+async function cleanupRuntimeResources(runtime: AcpxRuntimePort | null,credential: ManagedCodexCredentialLease | null,command: VerifiedAcpxCommandLease | null,reason: string,): Promise<AggregateError | null> {- const errors: unknown[] = [];- for (const close of [- runtime ? () => runtime.close({ reason }) : null,- credential ? () => credential.close() : null,- command ? () => command.close() : null,- ]) {- if (!close) continue;+ const settle = async (+ close: () => Promise<void>,+ ): Promise<unknown | null> => {try {await close();+ return null;} catch (error) {- errors.push(error);+ return error;}- }+ };+ // The command lease owns only the already-consumed verified launch+ // snapshot, so it can be released as shutdown starts. The credential is+ // different: a provider whose exact runtime close is pending or failed may+ // still read or rewrite its home. Retain both the staged bytes and the+ // exclusive home lease until that exact close succeeds.+ const runtimeOutcome = runtime+ ? settle(() => runtime.close({ reason }))+ : Promise.resolve(null);+ const commandOutcome = command+ ? settle(() => command.close())+ : Promise.resolve(null);+ const credentialOutcome = (async (): Promise<unknown | null> => {+ const runtimeError = await runtimeOutcome;+ if (runtimeError !== null || credential === null) return null;+ return await settle(() => credential.close());+ })();+ const outcomes = await Promise.all([+ runtimeOutcome,+ commandOutcome,+ credentialOutcome,+ ]);+ const errors = outcomes.filter((error): error is unknown => error !== null);return errors.length > 0? new AggregateError(errors, "ACPX runtime cleanup failed"): null;@@ -441,3 +567,22 @@ function boundedReason(value: string): string {const reason = value.trim().slice(0, 1_000);return reason || "ACPX runtime closed";}++function boundedRequestId(value: string): string {+ const requestId = value.trim();+ if (+ requestId.length === 0 ||+ requestId !== value ||+ Buffer.byteLength(requestId) > 1_024+ ) {+ throw new Error("ACPX turn request id is outside its bounded size");+ }+ return requestId;+}++function boundedTurnText(value: string): string {+ if (Buffer.byteLength(value) > 1024 * 1024) {+ throw new Error("ACPX turn text exceeds its bounded size");+ }+ return value;+}