Skip to content

The open-source app everyone uses to manage agents at work

feat(runner): add qualified OpenCode runtime (#12588)

Dotta2e5a24e17769
diff --git a/packages/adapters/codex-local/src/ui/build-config.test.ts b/packages/adapters/codex-local/src/ui/build-config.test.ts
index 54e86b4479..97201f40f0 100644
--- a/packages/adapters/codex-local/src/ui/build-config.test.ts
+++ b/packages/adapters/codex-local/src/ui/build-config.test.ts
@@ -106,4 +106,44 @@ describe("buildPaperclipRunnerConfig", () => {
expect(config).not.toHaveProperty(unsupportedKey);
}
});
+
+ it("builds a bounded OpenCode runner profile from schema values", () => {
+ const config = buildPaperclipRunnerConfig(makeValues({
+ adapterType: "paperclip_runner",
+ model: "",
+ codexEngine: "acp",
+ dangerouslyBypassSandbox: true,
+ adapterSchemaValues: {
+ provider: "opencode",
+ opencodePermissionMode: "ask",
+ lifecycleMode: "warm",
+ idleTimeoutMs: 45_000,
+ },
+ }));
+
+ expect(config).toMatchObject({
+ provider: "opencode",
+ model: "openrouter/deepseek/deepseek-v4-flash-0731",
+ opencodePermissionMode: "ask",
+ lifecycleMode: "warm",
+ idleTimeoutMs: 45_000,
+ });
+ expect(config).not.toHaveProperty("engine");
+ expect(config).not.toHaveProperty("dangerouslyBypassApprovalsAndSandbox");
+ });
+
+ it("falls back to safe OpenCode defaults for invalid schema values", () => {
+ expect(buildPaperclipRunnerConfig(makeValues({
+ adapterSchemaValues: {
+ provider: "opencode",
+ opencodePermissionMode: "unrestricted",
+ lifecycleMode: "forever",
+ idleTimeoutMs: -1,
+ },
+ }))).toMatchObject({
+ provider: "opencode",
+ opencodePermissionMode: "allow",
+ lifecycleMode: "per_turn",
+ });
+ });
});
diff --git a/packages/adapters/codex-local/src/ui/build-config.ts b/packages/adapters/codex-local/src/ui/build-config.ts
index af647cb1f0..f5090d136d 100644
--- a/packages/adapters/codex-local/src/ui/build-config.ts
+++ b/packages/adapters/codex-local/src/ui/build-config.ts
@@ -61,7 +61,15 @@ export function buildCodexLocalConfig(v: CreateConfigValues): Record<string, unk
return ac;
}
-/** Build the Codex-only profile accepted by the experimental Rust runner. */
+function paperclipRunnerProvider(value: unknown): "codex" | "opencode" {
+ return value === "opencode" ? "opencode" : "codex";
+}
+
+function openCodePermissionMode(value: unknown): "allow" | "ask" | "deny" {
+ return value === "ask" || value === "deny" ? value : "allow";
+}
+
+/** Build a provider profile accepted by the experimental Rust runner. */
export function buildPaperclipRunnerConfig(v: CreateConfigValues): Record<string, unknown> {
const config = buildCodexLocalConfig(v);
for (const unsupportedKey of [
@@ -82,5 +90,27 @@ export function buildPaperclipRunnerConfig(v: CreateConfigValues): Record<string
]) {
delete config[unsupportedKey];
}
- return { ...config, provider: "codex" };
+ const schemaValues = v.adapterSchemaValues ?? {};
+ const provider = paperclipRunnerProvider(schemaValues.provider);
+ if (provider === "codex") {
+ return { ...config, provider };
+ }
+
+ const lifecycleMode = schemaValues.lifecycleMode === "warm" ? "warm" : "per_turn";
+ const configuredIdleTimeoutMs = schemaValues.idleTimeoutMs;
+ const idleTimeoutMs = typeof configuredIdleTimeoutMs === "number"
+ && Number.isSafeInteger(configuredIdleTimeoutMs)
+ && configuredIdleTimeoutMs > 0
+ ? configuredIdleTimeoutMs
+ : 300_000;
+ return {
+ ...config,
+ provider,
+ model: v.model || "openrouter/deepseek/deepseek-v4-flash-0731",
+ opencodePermissionMode: openCodePermissionMode(
+ schemaValues.opencodePermissionMode,
+ ),
+ lifecycleMode,
+ ...(lifecycleMode === "warm" ? { idleTimeoutMs } : {}),
+ };
}
diff --git a/packages/paperclip-runner/README.md b/packages/paperclip-runner/README.md
index 01a443d8dd..0d8fb43da6 100644
--- a/packages/paperclip-runner/README.md
+++ b/packages/paperclip-runner/README.md
@@ -20,7 +20,10 @@ The package also publishes the canonical semantic action declarations and
their input and output schemas. Its package-local dispatcher projects only
bound, run-authorized actions and emits redacted semantic receipts.
-The first and only installed provider is Codex. Dynamic semantic tools remain
+The production-selected provider remains Codex. The package also contains the
+qualified OpenCode 1.18.17 driver, authenticated loopback MCP bridge, and
+runnerd-compatible proxy, but this slice does not authorize the server to
+select OpenCode for a fresh native run. Dynamic semantic tools remain
undiscoverable unless the hidden server coordinator projects one of the five
same-task read bindings for an already persisted native Codex run. Catalog
membership alone does not grant authority. The server can now create and start
@@ -36,8 +39,8 @@ The package has two initial public surfaces:
- `@paperclipai/paperclip-runner/testing` adds Node-only fixture loading and a
provider-neutral semantic conformance kit for deterministic test adapters.
-No SDK, browser, React, eval, live-console, lab, or provider-experiment entry
-point is exported. The package remains private in this wave. The server route
+No SDK, browser, React, eval, live-console, or lab entry point is exported. The
+package remains private in this wave. The server route
at `/api/runner/v1/connect/:runId` has no authority until the hidden coordinator
registers an exact existing run binding. Fresh native starts are rejected
unless the instance `enableNativeRunner` flag is enabled. Existing direct
@@ -49,6 +52,13 @@ an installed server does not depend on a separate system Rust installation or
a manually copied binary. `pnpm-lock.yaml` remains under the repository's
existing lockfile process.
+The `paperclip-runner-opencode-proxy` binary adapts the pinned OpenCode server
+protocol to the normalized harness contract. It admits only a bounded provider
+environment, uses an authenticated loopback MCP endpoint, validates dynamic
+tool inputs, keeps terminal completion tools private to the runner boundary,
+and preserves exact provider session identity for recovery. The backend factory
+requires an explicit runtime directory before constructing this provider.
+
The package also builds `paperclip-runner-acpx-sidecar`. This bounded v2
stdin/stdout bridge admits the qualified Codex ACPX profile only. It validates
the exact model, session identity, tool catalog, structured input, and terminal
diff --git a/packages/paperclip-runner/package.json b/packages/paperclip-runner/package.json
index 6dfc54abee..d844a3976e 100644
--- a/packages/paperclip-runner/package.json
+++ b/packages/paperclip-runner/package.json
@@ -8,6 +8,7 @@
},
"type": "module",
"bin": {
+ "paperclip-runner-opencode-proxy": "./dist/cli/opencode-app-server-proxy.js",
"paperclip-runner-acpx-sidecar": "./dist/cli/acpx-runtime-sidecar.js"
},
"exports": {
@@ -58,7 +59,8 @@
"@agentclientprotocol/codex-acp": "1.6.2",
"acpx": "0.13.1",
"ajv": "^8.20.0",
- "json-schema-to-ts": "^3.1.1"
+ "json-schema-to-ts": "^3.1.1",
+ "opencode-ai": "1.18.17"
},
"devDependencies": {
"@types/node": "^24.0.0",
diff --git a/packages/paperclip-runner/protocol/fixtures/questions/opencode.json b/packages/paperclip-runner/protocol/fixtures/questions/opencode.json
new file mode 100644
index 0000000000..e450b722aa
--- /dev/null
+++ b/packages/paperclip-runner/protocol/fixtures/questions/opencode.json
@@ -0,0 +1,43 @@
+{
+ "schema": "paperclip.question_adapter_fixture.v1",
+ "adapter": "opencode",
+ "nativeRequest": {
+ "type": "question.asked",
+ "properties": {
+ "id": "request-1",
+ "sessionID": "session-1",
+ "title": "Deployment input",
+ "questions": [{
+ "question": "Where should we deploy?",
+ "header": "Environment",
+ "required": true,
+ "options": [
+ { "label": "Staging", "description": "Deploy to staging first." },
+ { "label": "Production", "description": "Deploy directly to production." }
+ ],
+ "multiple": false
+ }]
+ }
+ },
+ "canonicalQuestionSet": {
+ "schema": "paperclip.question_set.v1",
+ "title": "Deployment input",
+ "submitLabel": "Submit answers",
+ "questions": [{
+ "id": "environment",
+ "header": "Environment",
+ "prompt": "Where should we deploy?",
+ "required": true,
+ "answerMode": "single_select",
+ "options": [
+ { "id": "option-1", "label": "Staging", "description": "Deploy to staging first." },
+ { "id": "option-2", "label": "Production", "description": "Deploy directly to production." }
+ ]
+ }]
+ },
+ "canonicalResponse": {
+ "schema": "paperclip.question_response.v1",
+ "answers": { "environment": { "selectedOptionIds": ["option-1"] } }
+ },
+ "nativeResponse": { "answers": [["Staging"]] }
+}
diff --git a/packages/paperclip-runner/protocol/manifest.json b/packages/paperclip-runner/protocol/manifest.json
index aded16edae..a0a0dffce4 100644
--- a/packages/paperclip-runner/protocol/manifest.json
+++ b/packages/paperclip-runner/protocol/manifest.json
@@ -187,6 +187,12 @@
"expectation": "accept",
"compatibilityCase": "codex-structured-input"
},
+ {
+ "path": "fixtures/questions/opencode.json",
+ "sha256": "7e5f753d04321f78a38a4362b2a4c7aeacbb4736d4db72a699f23c245884da72",
+ "expectation": "accept",
+ "compatibilityCase": "opencode-structured-input"
+ },
{
"path": "fixtures/replay/duplicate-event.json",
"sha256": "779c146966d2825ffcde88bfff8b1fb238c162d40c578980ad3bd1a7def405d7",
diff --git a/packages/paperclip-runner/src/backends/native-backend-factory.test.ts b/packages/paperclip-runner/src/backends/native-backend-factory.test.ts
index 01914acf9c..79c0e4db6a 100644
--- a/packages/paperclip-runner/src/backends/native-backend-factory.test.ts
+++ b/packages/paperclip-runner/src/backends/native-backend-factory.test.ts
@@ -93,6 +93,23 @@ function acpxExecution(agent: "codex" | "pi" = "codex"): NativeExecutionInput {
};
}
+function opencodeExecution(): NativeExecutionInput {
+ return {
+ ...execution(),
+ session: {
+ normalizedSessionId: "session",
+ driverKind: "opencode_server",
+ protocolVersion: 1,
+ lifecyclePolicy: { mode: "per_turn", idleTimeoutMs: null },
+ },
+ provider: {
+ kind: "opencode",
+ model: "openrouter/model",
+ permissionMode: "allow",
+ },
+ };
+}
+
describe("native backend factory", () => {
it("constructs the Codex backend without starting its transport", async () => {
const backend = createNativeSessionBackend(execution(), {
@@ -111,17 +128,27 @@ describe("native backend factory", () => {
});
});
- it("fails closed when a deferred provider reaches the factory", () => {
+ it("requires an explicit runtime root for OpenCode", () => {
expect(() =>
- createNativeSessionBackend(
- execution({
- kind: "opencode",
- model: "openrouter/model",
- }),
- ),
- ).toThrow(
- "Native backend for opencode is not included in the Codex-first runner",
- );
+ createNativeSessionBackend(opencodeExecution()),
+ ).toThrow("OpenCode native backend requires an instance runtime directory");
+ });
+
+ it("constructs the OpenCode backend without starting its process", async () => {
+ const backend = createNativeSessionBackend(opencodeExecution(), {
+ opencodeRuntimeDirectory: "/runtime",
+ });
+
+ await expect(backend.descriptor()).resolves.toMatchObject({
+ kind: "runner",
+ name: "opencode_server",
+ version: "1.18.17",
+ capabilities: {
+ resume: true,
+ interruption: true,
+ dynamicTools: true,
+ },
+ });
});
it("constructs the qualified Codex ACPX backend without starting ACPX", async () => {
diff --git a/packages/paperclip-runner/src/backends/native-backend-factory.ts b/packages/paperclip-runner/src/backends/native-backend-factory.ts
index 8148034ade..76003ef48d 100644
--- a/packages/paperclip-runner/src/backends/native-backend-factory.ts
+++ b/packages/paperclip-runner/src/backends/native-backend-factory.ts
@@ -12,6 +12,7 @@ import {
createCodexAcpxNativeSessionBackend,
type CodexAcpxNativeSessionBackendOptions,
} from "./codex-acpx-native-backend.js";
+import { createOpenCodeNativeSessionBackend } from "./opencode-native-backend.js";
export interface NativeBackendFactoryOptions extends Omit<
CodexNativeSessionBackendOptions,
@@ -24,6 +25,9 @@ export interface NativeBackendFactoryOptions extends Omit<
acpxEnvironment?: NodeJS.ProcessEnv;
acpxManagedCodexCredentialSourcePath?: string;
acpxDynamicToolHandler?: CodexAcpxNativeSessionBackendOptions["dynamicToolHandler"];
+ opencodeRuntimeDirectory?: string;
+ opencodeEnvironment?: NodeJS.ProcessEnv;
+ opencodeCommand?: string;
}
/**
@@ -35,6 +39,22 @@ export function createNativeSessionBackend(
input: NativeExecutionInput,
options: NativeBackendFactoryOptions = {},
): NativeSessionBackend {
+ if (input.provider.kind === "opencode") {
+ if (!options.opencodeRuntimeDirectory?.trim()) {
+ throw new Error(
+ "OpenCode native backend requires an instance runtime directory",
+ );
+ }
+ return createOpenCodeNativeSessionBackend(input, {
+ runtimeDirectory: options.opencodeRuntimeDirectory,
+ environment: options.opencodeEnvironment,
+ command: options.opencodeCommand,
+ runnerInstanceId: options.runnerInstanceId,
+ onSpawn: options.onSpawn,
+ dynamicTools: options.dynamicTools,
+ dynamicToolHandler: options.dynamicToolHandler,
+ });
+ }
if (input.provider.kind === "acpx") {
if (input.provider.agent !== "codex") {
throw new Error(
diff --git a/packages/paperclip-runner/src/backends/opencode-native-backend.ts b/packages/paperclip-runner/src/backends/opencode-native-backend.ts
new file mode 100644
index 0000000000..4023ed06da
--- /dev/null
+++ b/packages/paperclip-runner/src/backends/opencode-native-backend.ts
@@ -0,0 +1,32 @@
+import { createCodexTaskEnvelope } from "../contracts/codex.js";
+import type { NativeExecutionInput } from "../contracts/native-execution.js";
+import type { NativeSessionBackend } from "../contracts/native-session-backend.js";
+import { OpenCodeServerDriver, type OpenCodeServerDriverOptions } from "../drivers/opencode/opencode-server-driver.js";
+import { HarnessDriverBackend } from "./harness-driver-backend.js";
+import { nativeSystemInstructions, nativeTaskConstraints } from "./runtime-context.js";
+
+export function createOpenCodeNativeSessionBackend(
+ input: NativeExecutionInput,
+ options: Omit<OpenCodeServerDriverOptions, "model" | "taskEnvelope">,
+): NativeSessionBackend {
+ if (input.provider.kind !== "opencode" || !input.provider.model) {
+ throw new Error("OpenCode native backend requires a persisted OpenCode provider/model selection");
+ }
+ return new HarnessDriverBackend(new OpenCodeServerDriver({
+ ...options,
+ systemInstructions: nativeSystemInstructions(input),
+ runtimeContext: "runtimeContext" in input ? input.runtimeContext : null,
+ model: input.provider.model,
+ permissionMode: input.provider.permissionMode ?? "allow",
+ taskEnvelope: createCodexTaskEnvelope({
+ objective: input.completionContract.contract.objective,
+ contractRevision: input.completionContract.contract.revision,
+ criteria: input.completionContract.contract.criteria,
+ constraints: [
+ "Work only inside the supplied working directory.",
+ ...nativeTaskConstraints(input),
+ "Return one semantic completion result through paperclip_finish or paperclip_block.",
+ ],
+ }),
+ }));
+}
diff --git a/packages/paperclip-runner/src/cli/opencode-app-server-proxy.test.ts b/packages/paperclip-runner/src/cli/opencode-app-server-proxy.test.ts
new file mode 100644
index 0000000000..2a5f028cd4
--- /dev/null
+++ b/packages/paperclip-runner/src/cli/opencode-app-server-proxy.test.ts
@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+
+import { openCodeProxyTaskEnvelope } from "./opencode-proxy-task-envelope.js";
+
+describe("OpenCode runnerd proxy task envelope", () => {
+ it("uses the durable completion-contract binding instead of a demo revision", () => {
+ expect(openCodeProxyTaskEnvelope({
+ baseInstructions: "Complete only this task.",
+ completionContract: {
+ revision: "17",
+ criterionIds: ["objective", "verification"],
+ },
+ })).toMatchObject({
+ completionContract: {
+ revision: "17",
+ criteria: [
+ { id: "objective" },
+ { id: "verification" },
+ ],
+ },
+ });
+ });
+});
diff --git a/packages/paperclip-runner/src/cli/opencode-app-server-proxy.ts b/packages/paperclip-runner/src/cli/opencode-app-server-proxy.ts
new file mode 100644
index 0000000000..8aad11eb2c
--- /dev/null
+++ b/packages/paperclip-runner/src/cli/opencode-app-server-proxy.ts
@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+import { createInterface } from "node:readline";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+
+import type { HarnessRuntimeRequestResolution, HarnessSession, PersistedHarnessSession } from "../contracts/harness-driver.js";
+import { OpenCodeServerDriver } from "../drivers/opencode/opencode-server-driver.js";
+import { parseNativeRuntimeContext } from "../contracts/runtime-context.js";
+import { openCodeProxyTaskEnvelope } from "./opencode-proxy-task-envelope.js";
+import {
+ shouldAnnounceOpenCodeProxyTurn,
+ shouldForwardOpenCodeProxyItem,
+} from "./opencode-proxy-events.js";
+import { enqueueOpenCodeProxyInput } from "./opencode-proxy-input.js";
+import {
+ assertOpenCodeProxyCollaborationMode,
+ openCodeProxyCollaborationModes,
+} from "./opencode-proxy-collaboration-mode.js";
+
+type RpcMessage = { id?: string | number; method?: string; params?: unknown; result?: unknown; error?: unknown };
+
+const input = createInterface({ input: process.stdin, crlfDelay: Infinity });
+const pending = new Map<string, { resolve(value: unknown): void; reject(error: Error): void }>();
+let nextServerRequestId = 1;
+let driver: OpenCodeServerDriver | null = null;
+let session: HarnessSession | null = null;
+let eventPump: Promise<void> | null = null;
+let cwd = "";
+let activeModel = "";
+let activeTurnId: string | null = null;
+const announcedTurnIds = new Set<string>();
+
+function openCodeCommand(): string {
+ const configured = process.env.PAPERCLIP_OPENCODE_COMMAND?.trim();
+ if (configured && configured !== "opencode") return configured;
+ try {
+ return createRequire(import.meta.url).resolve("opencode-ai/bin/opencode.exe");
+ } catch {
+ return configured || "opencode";
+ }
+}
+
+function send(value: unknown): void {
+ process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+
+function requestController(method: string, params: unknown): Promise<unknown> {
+ const id = `opencode-${nextServerRequestId++}`;
+ send({ id, method, params });
+ return new Promise((resolveValue, reject) => pending.set(id, { resolve: resolveValue, reject }));
+}
+
+function record(value: unknown): Record<string, unknown> {
+ return typeof value === "object" && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+function text(value: unknown, fallback = ""): string {
+ return typeof value === "string" ? value : fallback;
+}
+
+function runtimeDirectory(): string {
+ const configured = process.env.PAPERCLIP_OPENCODE_RUNTIME_DIR?.trim();
+ if (!configured) throw new Error("PAPERCLIP_OPENCODE_RUNTIME_DIR is required");
+ return resolve(configured);
+}
+
+async function open(params: Record<string, unknown>, resume: boolean): Promise<Record<string, unknown>> {
+ if (session) return threadResponse(session.ids().providerSessionId ?? session.ids().driverSessionId);
+ cwd = resolve(text(params.cwd, process.cwd()));
+ const model = text(params.model);
+ if (!model.includes("/")) throw new Error("OpenCode proxy requires model in provider/model form");
+ activeModel = model;
+ const dynamicTools = Array.isArray(params.dynamicTools) ? params.dynamicTools.map(record) : [];
+ const runtimeContextPath = process.env.PAPERCLIP_NATIVE_RUNTIME_CONTEXT_PATH?.trim();
+ const runtimeContext = runtimeContextPath
+ ? parseNativeRuntimeContext(JSON.parse(readFileSync(runtimeContextPath, "utf8")))
+ : null;
+ driver = new OpenCodeServerDriver({
+ model,
+ command: openCodeCommand(),
+ runtimeDirectory: runtimeDirectory(),
+ environment: process.env,
+ runnerInstanceId: process.env.PAPERCLIP_RUNNER_INSTANCE_ID ?? "paperclip-runnerd-opencode",
+ taskEnvelope: openCodeProxyTaskEnvelope(params),
+ systemInstructions: text(params.baseInstructions, "Complete only the supplied task."),
+ runtimeContext,
+ dynamicTools,
+ dynamicToolHandler: async (call) => requestController("item/tool/call", {
+ threadId: session?.ids().driverSessionId ?? "opening",
+ turnId: call.turnId,
+ callId: call.callId,
+ tool: call.tool,
+ arguments: call.arguments,
+ }),
+ onDiagnostic: (message) => process.stderr.write(`[opencode] ${message}\n`),
+ // runnerd gives this proxy its own process group. Keep `opencode serve` in
+ // that same group so runnerd's TERM/KILL fallback cannot orphan it.
+ isolateProcessGroup: false,
+ });
+ if (resume) {
+ const threadId = text(params.threadId);
+ const snapshot: PersistedHarnessSession = {
+ driverKind: "opencode_server",
+ driverSessionId: threadId,
+ providerSessionId: threadId,
+ runId: process.env.PAPERCLIP_RUN_ID ?? "runnerd-run",
+ normalizedSessionId: process.env.PAPERCLIP_NORMALIZED_SESSION_ID ?? threadId,
+ activeTurnId: null,
+ lastSourceSequence: 0,
+ };
+ const recovered = await driver.recoverSession(snapshot);
+ if (!recovered.recovered || !recovered.session) throw new Error(recovered.reason ?? "OpenCode recovery failed");
+ session = recovered.session;
+ } else {
+ session = await driver.openSession({
+ runId: process.env.PAPERCLIP_RUN_ID ?? "runnerd-run",
+ normalizedSessionId: process.env.PAPERCLIP_NORMALIZED_SESSION_ID ?? `runnerd-${Date.now()}`,
+ workingDirectory: cwd,
+ });
+ }
+ eventPump = pumpEvents(session);
+ void eventPump.catch((error) => failProxy(error));
+ return threadResponse(session.ids().providerSessionId ?? session.ids().driverSessionId);
+}
+
+function threadResponse(id: string): Record<string, unknown> {
+ return { thread: { id, sessionId: id, cwd }, model: activeModel };
+}
+
+function announceTurnStarted(opened: HarnessSession, turnId: string): void {
+ if (!shouldAnnounceOpenCodeProxyTurn(announcedTurnIds, turnId)) return;
+ send({
+ method: "turn/started",
+ params: {
+ threadId: opened.ids().driverSessionId,
+ turnId,
+ turn: { id: turnId, status: "inProgress" },
+ },
+ });
+}
+
+async function pumpEvents(opened: HarnessSession): Promise<void> {
+ for await (const event of opened.events()) {
+ const payload = record(event.payload);
+ if (event.eventType === "turn.started") {
+ if (typeof event.turnId === "string") announceTurnStarted(opened, event.turnId);
+ } else if (event.eventType === "item.started" || event.eventType === "item.delta" || event.eventType === "item.completed") {
+ // The inner OpenCode driver publishes session-scoped model metadata as
+ // an item before any turn exists. The outer Codex protocol facade emits
+ // its own model item, so forwarding this unbound duplicate would quite
+ // correctly trip the facade's strict turn-binding validator.
+ if (!shouldForwardOpenCodeProxyItem({ turnId: event.turnId, kind: payload.kind })) continue;
+ const assistantText = payload.kind === "text" && typeof payload.text === "string"
+ ? payload.text
+ : null;
+ const method = event.eventType === "item.delta" && assistantText !== null
+ ? "item/agentMessage/delta"
+ : event.eventType.replace(".", "/");
+ const providerItem = record(payload.item);
+ const item = assistantText === null
+ ? payload.item ?? { id: event.itemId, type: payload.kind, text: payload.text }
+ : { ...providerItem, id: event.itemId, type: "agentMessage", text: assistantText };
+ send({
+ method,
+ params: {
+ threadId: opened.ids().driverSessionId,
+ turnId: event.turnId,
+ itemId: event.itemId,
+ ...payload,
+ item,
+ ...(method === "item/agentMessage/delta" ? { delta: assistantText } : {}),
+ },
+ });
+ if (payload.kind === "usage") {
+ const usage = record(payload.usage);
+ const cache = record(usage.cache);
+ send({ method: "thread/tokenUsage/updated", params: {
+ threadId: opened.ids().driverSessionId,
+ turnId: event.turnId,
+ tokenUsage: { total: {
+ inputTokens: usage.inputTokens ?? usage.input ?? 0,
+ outputTokens: usage.outputTokens ?? usage.output ?? 0,
+ cachedInputTokens: usage.cachedInputTokens ?? cache.read ?? 0,
+ reasoningTokens: usage.reasoningTokens ?? usage.reasoning ?? 0,
+ costUsd: usage.costUsd ?? usage.cost ?? null,
+ } },
+ } });
+ }
+ } else if (event.eventType === "run.result.proposed") {
+ send({
+ method: "paperclip/runResult",
+ params: {
+ threadId: opened.ids().driverSessionId,
+ turnId: event.turnId,
+ itemId: event.itemId ?? "semantic-result",
+ result: payload,
+ },
+ });
+ } else if (event.eventType === "runtime_request.created") {
+ const request = record(payload.request);
+ const requestId = text(request.requestId);
+ const turnId = text(request.turnId, text(event.turnId, activeTurnId ?? ""));
+ if (!requestId || !turnId || !opened.resolveRuntimeRequest) {
+ throw new Error("OpenCode runtime request is not resolvable");
+ }
+ // Keep consuming OpenCode SSE while the controller waits for the user.
+ // If the underlying provider disappears, the stream can then fail the
+ // proxy and runnerd will expire the still-pending canonical request.
+ void (async () => {
+ const controllerResponse = record(await requestController("paperclip/runtimeRequest", {
+ request,
+ }));
+ await opened.resolveRuntimeRequest!({
+ requestId,
+ turnId,
+ resolution: record(controllerResponse.resolution) as HarnessRuntimeRequestResolution,
+ });
+ })().catch((error) => failProxy(error));
+ } else if (["turn.completed", "turn.failed", "turn.interrupted", "turn.cancelled"].includes(event.eventType)) {
+ const status = event.eventType.slice("turn.".length);
+ send({ method: "turn/completed", params: { threadId: opened.ids().driverSessionId, turnId: event.turnId, turn: { id: event.turnId, status } } });
+ activeTurnId = null;
+ } else if (event.eventType === "harness.diagnostic") {
+ send({ method: "warning", params: { threadId: opened.ids().driverSessionId, message: payload.message ?? payload.code } });
+ }
+ }
+}
+
+async function handle(message: RpcMessage): Promise<void> {
+ if (message.method === undefined && message.id !== undefined) {
+ const waiter = pending.get(String(message.id));
+ if (!waiter) return;
+ pending.delete(String(message.id));
+ if (message.error !== undefined) waiter.reject(new Error(JSON.stringify(message.error)));
+ else {
+ const contentItems = record(message.result).contentItems;
+ waiter.resolve(Array.isArray(contentItems) ? contentItems[0] ?? message.result : message.result);
+ }
+ return;
+ }
+ if (!message.method || message.id === undefined) return;
+ const params = record(message.params);
+ let result: unknown;
+ switch (message.method) {
+ case "initialize":
+ result = { user: { sessionId: "opencode" }, serverInfo: { name: "opencode", version: "1.18.17" } };
+ break;
+ case "thread/start": result = await open(params, false); break;
+ case "thread/resume": result = await open(params, true); break;
+ case "collaborationMode/list":
+ result = openCodeProxyCollaborationModes(activeModel);
+ break;
+ case "turn/start": {
+ if (!session) throw new Error("OpenCode thread is not open");
+ assertOpenCodeProxyCollaborationMode(params);
+ const inputItems = Array.isArray(params.input) ? params.input.map(record) : [];
+ const messageText = inputItems.map((entry) => text(entry.text)).filter(Boolean).join("\n");
+ const turn = await session.startTurn({ message: { role: "user", text: messageText } });
+ activeTurnId = turn.turnId;
+ // OpenCode normally publishes session/turn startup over SSE, but a fast
+ // completion can make the synchronous prompt response the only place the
+ // authoritative turn id is observed. Emit the normalized notification
+ // after this request's JSON-RPC response when SSE did not already announce
+ // it. runnerd buffers notifications received while awaiting a response,
+ // so replaying an earlier SSE announcement would violate strict turn
+ // binding at the outer driver.
+ queueMicrotask(() => {
+ announceTurnStarted(session!, turn.turnId);
+ });
+ result = { turn: { id: turn.turnId, status: "inProgress" } };
+ break;
+ }
+ case "turn/interrupt":
+ if (!session?.interrupt) throw new Error("OpenCode interruption is unavailable");
+ await session.interrupt({ turnId: text(params.turnId, activeTurnId ?? "") });
+ result = true;
+ break;
+ case "thread/read":
+ if (!session) throw new Error("OpenCode thread is not open");
+ result = { thread: { id: session.ids().driverSessionId, cwd, turns: activeTurnId ? [{ id: activeTurnId, status: "inProgress" }] : [] }, transcript: await session.read?.() };
+ break;
+ default: throw new Error(`Unsupported OpenCode proxy method ${message.method}`);
+ }
+ send({ id: message.id, result });
+}
+
+let pendingInput = Promise.resolve();
+let bootstrapFailure: Error | null = null;
+input.on("line", (line) => {
+ if (!line.trim()) return;
+ let message: RpcMessage;
+ try { message = JSON.parse(line) as RpcMessage; }
+ catch (error) { process.stderr.write(`Invalid JSON-RPC input: ${String(error)}\n`); return; }
+ pendingInput = enqueueOpenCodeProxyInput(
+ pendingInput,
+ async () => {
+ if (bootstrapFailure) {
+ throw new Error(
+ `OpenCode provider bootstrap failed before ${message.method ?? "the dependent command"}: ${bootstrapFailure.message}`,
+ );
+ }
+ await handle(message);
+ },
+ (error) => {
+ const normalized = error instanceof Error ? error : new Error(String(error));
+ if (
+ message.method === "initialize"
+ || message.method === "thread/start"
+ || message.method === "thread/resume"
+ ) {
+ bootstrapFailure ??= normalized;
+ }
+ send({
+ id: message.id,
+ error: { code: -32000, message: normalized.message },
+ });
+ },
+ );
+});
+
+let shutdownPromise: Promise<void> | null = null;
+function failProxy(error: unknown): void {
+ process.stderr.write(`[opencode] fatal proxy error: ${error instanceof Error ? error.message : String(error)}\n`);
+ void shutdown(1);
+}
+
+function shutdown(exitCode = 0): Promise<void> {
+ shutdownPromise ??= (async () => {
+ for (const waiter of pending.values()) waiter.reject(new Error("OpenCode proxy is shutting down"));
+ pending.clear();
+ await session?.close({ reason: "proxy_shutdown", force: true }).catch(() => {});
+ await eventPump?.catch(() => {});
+ })().finally(() => process.exit(exitCode));
+ return shutdownPromise;
+}
+
+input.on("close", () => { void pendingInput.then(() => shutdown()); });
+process.on("SIGTERM", () => { void shutdown(); });
+process.on("SIGINT", () => { void shutdown(); });
diff --git a/packages/paperclip-runner/src/cli/opencode-proxy-collaboration-mode.test.ts b/packages/paperclip-runner/src/cli/opencode-proxy-collaboration-mode.test.ts
new file mode 100644
index 0000000000..a065eb02ef
--- /dev/null
+++ b/packages/paperclip-runner/src/cli/opencode-proxy-collaboration-mode.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ assertOpenCodeProxyCollaborationMode,
+ openCodeProxyCollaborationModes,
+} from "./opencode-proxy-collaboration-mode.js";
+
+describe("OpenCode runnerd proxy collaboration mode", () => {
+ it("advertises proxy-owned planning against the resolved model", () => {
+ expect(
+ openCodeProxyCollaborationModes(
+ "openrouter/deepseek/deepseek-v4-flash-0731",
+ ),
+ ).toEqual({
+ data: [
+ {
+ name: "Plan",
+ mode: "plan",
+ model: "openrouter/deepseek/deepseek-v4-flash-0731",
+ reasoning_effort: null,
+ },
+ ],
+ });
+ });
+
+ it("accepts the negotiated plan payload on turn/start", () => {
+ expect(() =>
+ assertOpenCodeProxyCollaborationMode({
+ collaborationMode: {
+ mode: "plan",
+ settings: { model: "openrouter/example" },
+ },
+ }),
+ ).not.toThrow();
+ });
+
+ it("rejects collaboration modes the proxy does not implement", () => {
+ expect(() =>
+ assertOpenCodeProxyCollaborationMode({
+ collaborationMode: { mode: "pair-programming" },
+ }),
+ ).toThrow("Unsupported OpenCode proxy collaboration mode pair-programming");
+ });
+});
diff --git a/packages/paperclip-runner/src/cli/opencode-proxy-collaboration-mode.ts b/packages/paperclip-runner/src/cli/opencode-proxy-collaboration-mode.ts
new file mode 100644
index 0000000000..0118baf55f
--- /dev/null
+++ b/packages/paperclip-runner/src/cli/opencode-proxy-collaboration-mode.ts
@@ -0,0 +1,41 @@
+function record(value: unknown): Record<string, unknown> {
+ return typeof value === "object" && value !== null && !Array.isArray(value)
+ ? (value as Record<string, unknown>)
+ : {};
+}
+
+/**
+ * OpenCode does not expose Codex app-server collaboration presets itself, but
+ * the Paperclip proxy implements planning semantics through its task envelope,
+ * read-only permission profile, and Paperclip runtime tools. Advertise that
+ * proxy-owned capability so runnerd can negotiate planning mode without
+ * pretending OpenCode supplied a native Codex preset.
+ */
+export function openCodeProxyCollaborationModes(model: string) {
+ const resolvedModel = model.trim();
+ if (!resolvedModel) {
+ throw new Error(
+ "OpenCode collaboration modes are unavailable before thread/start resolves a model",
+ );
+ }
+ return {
+ data: [
+ {
+ name: "Plan",
+ mode: "plan",
+ model: resolvedModel,
+ reasoning_effort: null,
+ },
+ ],
+ };
+}
+
+export function assertOpenCodeProxyCollaborationMode(params: unknown): void {
+ const collaborationMode = record(record(params).collaborationMode);
+ if (Object.keys(collaborationMode).length === 0) return;
+ if (collaborationMode.mode !== "plan") {
+ throw new Error(
+ `Unsupported OpenCode proxy collaboration mode ${String(collaborationMode.mode)}`,
+ );
+ }
+}
diff --git a/packages/paperclip-runner/src/cli/opencode-proxy-events.test.ts b/packages/paperclip-runner/src/cli/opencode-proxy-events.test.ts
new file mode 100644
index 0000000000..4a0953869b
--- /dev/null
+++ b/packages/paperclip-runner/src/cli/opencode-proxy-events.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ shouldAnnounceOpenCodeProxyTurn,
+ shouldForwardOpenCodeProxyItem,
+} from "./opencode-proxy-events.js";
+
+describe("OpenCode runnerd proxy event boundary", () => {
+ it("drops only the duplicate session-scoped model item", () => {
+ expect(
+ shouldForwardOpenCodeProxyItem({ kind: "model" }),
+ ).toBe(false);
+ expect(
+ shouldForwardOpenCodeProxyItem({
+ turnId: "turn-1",
+ kind: "model",
+ }),
+ ).toBe(true);
+ expect(
+ shouldForwardOpenCodeProxyItem({ kind: "agentMessage" }),
+ ).toBe(true);
+ });
+
+ it("announces one outer turn when SSE wins the response race", () => {
+ const announced = new Set<string>();
+ expect(shouldAnnounceOpenCodeProxyTurn(announced, "turn-1")).toBe(true);
+ expect(shouldAnnounceOpenCodeProxyTurn(announced, "turn-1")).toBe(false);
+ expect([...announced]).toEqual(["turn-1"]);
+ });
+});
diff --git a/packages/paperclip-runner/src/cli/opencode-proxy-events.ts b/packages/paperclip-runner/src/cli/opencode-proxy-events.ts
new file mode 100644
index 0000000000..ef1426cdac
--- /dev/null
+++ b/packages/paperclip-runner/src/cli/opencode-proxy-events.ts
@@ -0,0 +1,15 @@
+export function shouldForwardOpenCodeProxyItem(input: {
+ turnId?: string;
+ kind?: unknown;
+}): boolean {
+ return !(input.turnId === undefined && input.kind === "model");
+}
+
+export function shouldAnnounceOpenCodeProxyTurn(
+ announcedTurnIds: Set<string>,
+ turnId: string,
+): boolean {
+ if (announcedTurnIds.has(turnId)) return false;
+ announcedTurnIds.add(turnId);
+ return true;
+}
diff --git a/packages/paperclip-runner/src/cli/opencode-proxy-input.test.ts b/packages/paperclip-runner/src/cli/opencode-proxy-input.test.ts
new file mode 100644
index 0000000000..76a6036257
--- /dev/null
+++ b/packages/paperclip-runner/src/cli/opencode-proxy-input.test.ts
@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+
+import { enqueueOpenCodeProxyInput } from "./opencode-proxy-input.js";
+
+describe("OpenCode proxy input sequencing", () => {
+ it("drains requests in order before EOF shutdown", async () => {
+ let releaseFirst!: () => void;
+ const firstBlocked = new Promise<void>((resolve) => {
+ releaseFirst = resolve;
+ });
+ const events: string[] = [];
+ let pending = Promise.resolve();
+ pending = enqueueOpenCodeProxyInput(
+ pending,
+ async () => {
+ events.push("initialize:start");
+ await firstBlocked;
+ events.push("initialize:complete");
+ },
+ () => events.push("initialize:error"),
+ );
+ pending = enqueueOpenCodeProxyInput(
+ pending,
+ async () => {
+ events.push("thread:start");
+ },
+ () => events.push("thread:error"),
+ );
+ const shutdown = pending.then(() => {
+ events.push("shutdown");
+ });
+
+ await Promise.resolve();
+ expect(events).toEqual(["initialize:start"]);
+ releaseFirst();
+ await shutdown;
+ expect(events).toEqual([
+ "initialize:start",
+ "initialize:complete",
+ "thread:start",
+ "shutdown",
+ ]);
+ });
+
+ it("reports a failed queued request without rejecting the drain", async () => {
+ const events: string[] = [];
+ let pending = Promise.resolve();
+ pending = enqueueOpenCodeProxyInput(
+ pending,
+ async () => {
+ throw new Error("initialize failed");
+ },
+ (error) => events.push((error as Error).message),
+ );
+
+ await pending;
+ expect(events).toEqual(["initialize failed"]);
+ });
+});
diff --git a/packages/paperclip-runner/src/cli/opencode-proxy-input.ts b/packages/paperclip-runner/src/cli/opencode-proxy-input.ts
new file mode 100644
index 0000000000..2099c381aa
--- /dev/null
+++ b/packages/paperclip-runner/src/cli/opencode-proxy-input.ts
@@ -0,0 +1 @@
+export { enqueueSerialInput as enqueueOpenCodeProxyInput } from "./serial-input-queue.js";
diff --git a/packages/paperclip-runner/src/cli/opencode-proxy-task-envelope.ts b/packages/paperclip-runner/src/cli/opencode-proxy-task-envelope.ts
new file mode 100644
index 0000000000..0b76023408
--- /dev/null
+++ b/packages/paperclip-runner/src/cli/opencode-proxy-task-envelope.ts
@@ -0,0 +1,38 @@
+import { createCodexTaskEnvelope } from "../contracts/codex.js";
+
+function record(value: unknown): Record<string, unknown> {
+ return typeof value === "object" && value !== null && !Array.isArray(value)
+ ? value as Record<string, unknown>
+ : {};
+}
+
+function text(value: unknown, fallback = ""): string {
+ return typeof value === "string" ? value : fallback;
+}
+
+export function openCodeProxyTaskEnvelope(params: Record<string, unknown>) {
+ const completionContract = record(params.completionContract);
+ const revision = text(completionContract.revision).trim();
+ const criterionIds = Array.isArray(completionContract.criterionIds)
+ ? completionContract.criterionIds
+ .filter((value): value is string => typeof value === "string" && value.trim().length > 0)
+ .map((value) => value.trim())
+ : [];
+ return createCodexTaskEnvelope({
+ objective: "Complete the provider turn supplied by Paperclip Runner.",
+ ...(revision && criterionIds.length > 0
+ ? {
+ contractRevision: revision,
+ criteria: criterionIds.map((id) => ({
+ id,
+ requirement: `Satisfy the Paperclip completion criterion ${id}.`,
+ })),
+ }
+ : {}),
+ constraints: [
+ text(params.baseInstructions, "Complete only the supplied task."),
+ "Work only inside the supplied working directory.",
+ "Use Paperclip MCP tools for semantic operations.",
+ ],
+ });
+}
diff --git a/packages/paperclip-runner/src/cli/serial-input-queue.ts b/packages/paperclip-runner/src/cli/serial-input-queue.ts
index b927b8ece0..576445a6ae 100644
--- a/packages/paperclip-runner/src/cli/serial-input-queue.ts
+++ b/packages/paperclip-runner/src/cli/serial-input-queue.ts
@@ -17,5 +17,10 @@ export function enqueueSerialInput(
// Diagnostics must not poison the queue or skip later input frames.
}
};
- return pending.catch(reportError).then(operation).catch(reportError);
+ return pending
+ .then(operation, (error) => {
+ reportError(error);
+ return operation();
+ })
+ .catch(reportError);
}
diff --git a/packages/paperclip-runner/src/contracts/provider-trace-file-sink.test.ts b/packages/paperclip-runner/src/contracts/provider-trace-file-sink.test.ts
new file mode 100644
index 0000000000..405a28edd7
--- /dev/null
+++ b/packages/paperclip-runner/src/contracts/provider-trace-file-sink.test.ts
@@ -0,0 +1,62 @@
+import { chmod, mkdtemp, readFile, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { createProviderTraceFileSink } from "./provider-trace-file-sink.js";
+
+const roots: string[] = [];
+
+afterEach(async () => {
+ const { rm } = await import("node:fs/promises");
+ await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("ProviderTraceFileSink", () => {
+ it("hardens an existing file before it appends provider frames", async () => {
+ const root = await mkdtemp(join(tmpdir(), "paperclip-provider-trace-mode-"));
+ roots.push(root);
+ const tracePath = join(root, "provider.ndjson");
+ await writeFile(tracePath, "", { mode: 0o644 });
+ await chmod(tracePath, 0o644);
+
+ const sink = await createProviderTraceFileSink({
+ path: tracePath,
+ provider: "opencode",
+ channel: "test",
+ });
+
+ expect(statMode(await stat(tracePath))).toBe(0o600);
+ await sink?.finish();
+ });
+
+ it("redacts registered credentials before raw frames reach disk", async () => {
+ const root = await mkdtemp(join(tmpdir(), "paperclip-provider-trace-secret-"));
+ roots.push(root);
+ const tracePath = join(root, "provider.ndjson");
+ const sink = await createProviderTraceFileSink({
+ path: tracePath,
+ provider: "opencode",
+ channel: "test",
+ });
+ sink?.addSensitiveValues(["provider-secret", "bridge-secret"]);
+ sink?.frame({
+ direction: "provider_stderr",
+ raw: "credential=provider-secret authorization=bridge-secret",
+ transport: "process_stderr",
+ });
+ await sink?.finish();
+
+ const trace = await readFile(tracePath, "utf8");
+ expect(trace).not.toContain("provider-secret");
+ expect(trace).not.toContain("bridge-secret");
+ const frame = JSON.parse(trace.trim().split("\n")[0]!) as Record<string, unknown>;
+ expect(Buffer.from(String(frame.rawBase64), "base64").toString("utf8"))
+ .toBe("credential=[REDACTED] authorization=[REDACTED]");
+ });
+});
+
+function statMode(value: Awaited<ReturnType<typeof stat>>): number {
+ return value.mode & 0o777;
+}
diff --git a/packages/paperclip-runner/src/contracts/provider-trace-file-sink.ts b/packages/paperclip-runner/src/contracts/provider-trace-file-sink.ts
new file mode 100644
index 0000000000..aff5932900
--- /dev/null
+++ b/packages/paperclip-runner/src/contracts/provider-trace-file-sink.ts
@@ -0,0 +1,248 @@
+import { createHash } from "node:crypto";
+import { open, type FileHandle } from "node:fs/promises";
+
+const DEFAULT_MAX_BYTES = 64 * 1024 * 1024;
+const MAX_PENDING_RECORDS = 1_024;
+
+type TraceRecord = Record<string, unknown>;
+type ProviderTraceDirection =
+ | "client_to_provider"
+ | "provider_to_client"
+ | "provider_stderr";
+type ProviderTraceDisposition =
+ | "mapped"
+ | "generic"
+ | "ignored"
+ | "rejected"
+ | "operator_only";
+type ProviderTraceFieldMapping = {
+ inputPath?: string;
+ outputPath?: string;
+ action: "copied" | "renamed" | "normalized" | "derived" | "dropped" | "redacted";
+ reason?: string;
+};
+
+/**
+ * A bounded, fire-and-forget file spool for native providers implemented in
+ * TypeScript. Provider execution never awaits writes on its hot path; a slow
+ * or failed sidecar becomes an incomplete trace instead of run backpressure.
+ */
+export class ProviderTraceFileSink {
+ readonly #file: FileHandle;
+ readonly #provider: string;
+ readonly #channel: string;
+ readonly #maxBytes: number;
+ readonly #sensitiveValues = new Set<string>();
+ readonly #queue: string[] = [];
+ #nextFrameId: number;
+ #nextDebugSequence: number;
+ #capturedBytes: number;
+ #draining: Promise<void> | null = null;
+ #closed = false;
+ #truncated = false;
+ #incompleteReason: string | null = null;
+
+ constructor(input: {
+ file: FileHandle;
+ provider: string;
+ channel: string;
+ maxBytes?: number;
+ nextFrameId?: number;
+ nextDebugSequence?: number;
+ capturedBytes?: number;
+ }) {
+ this.#file = input.file;
+ this.#provider = input.provider;
+ this.#channel = input.channel;
+ this.#maxBytes = input.maxBytes ?? DEFAULT_MAX_BYTES;
+ this.#nextFrameId = input.nextFrameId ?? 1;
+ this.#nextDebugSequence = input.nextDebugSequence ?? 1;
+ this.#capturedBytes = input.capturedBytes ?? 0;
+ }
+
+ addSensitiveValues(values: readonly (string | undefined)[]): void {
+ for (const value of values) {
+ if (value) this.#sensitiveValues.add(value);
+ }
+ }
+
+ frame(input: {
+ direction: ProviderTraceDirection;
+ raw: Uint8Array | string;
+ transport: string;
+ nativeMethod?: string;
+ }): number | null {
+ if (this.#closed) return null;
+ const raw = this.#redact(
+ typeof input.raw === "string" ? Buffer.from(input.raw) : Buffer.from(input.raw),
+ );
+ if (this.#capturedBytes + raw.byteLength > this.#maxBytes) {
+ this.#truncated = true;
+ return null;
+ }
+ const frameId = this.#nextFrameId++;
+ this.#capturedBytes += raw.byteLength;
+ this.#append({
+ kind: "frame",
+ schema: "paperclip.provider_trace_frame.v1",
+ frameId,
+ timestamp: new Date().toISOString(),
+ direction: input.direction,
+ transport: input.transport,
+ provider: this.#provider,
+ ...(input.nativeMethod ? { nativeMethod: input.nativeMethod } : {}),
+ byteLength: raw.byteLength,
+ digest: `sha256:${createHash("sha256").update(raw).digest("hex")}`,
+ rawBase64: raw.toString("base64"),
+ });
+ return frameId;
+ }
+
+ interpretation(input: {
+ frameId: number;
+ stage: string;
+ ruleId: string;
+ disposition: ProviderTraceDisposition;
+ emittedEventIds?: string[];
+ droppedFields?: string[];
+ fieldMappings?: ProviderTraceFieldMapping[];
+ reason: string;
+ }): void {
+ if (this.#closed) return;
+ this.#append({
+ kind: "interpretation",
+ schema: "paperclip.provider_trace_interpretation.v1",
+ frameId: input.frameId,
+ stage: input.stage,
+ ruleId: input.ruleId,
+ disposition: input.disposition,
+ emittedEventIds: input.emittedEventIds ?? [],
+ droppedFields: input.droppedFields ?? [],
+ fieldMappings: input.fieldMappings ?? [],
+ reason: input.reason,
+ });
+ }
+
+ async finish(input: { reason?: string | null } = {}): Promise<void> {
+ if (this.#closed) {
+ await this.#draining;
+ return;
+ }
+ const reason = input.reason ?? this.#incompleteReason;
+ const status = reason
+ ? "incomplete"
+ : this.#truncated
+ ? "truncated"
+ : "complete";
+ const acknowledgedDebugSequence = this.#nextDebugSequence - 1;
+ this.#append({
+ kind: "trace_status",
+ status,
+ acknowledgedDebugSequence,
+ reason: reason ?? (this.#truncated ? "provider_trace_max_bytes_exceeded" : null),
+ });
+ this.#closed = true;
+ await this.#draining;
+ await this.#file.close().catch(() => undefined);
+ }
+
+ #append(value: TraceRecord): void {
+ const record = {
+ ...value,
+ debugChannel: this.#channel,
+ debugSequence: this.#nextDebugSequence++,
+ };
+ if (this.#queue.length >= MAX_PENDING_RECORDS) {
+ this.#incompleteReason ??= "trace_sidecar_spool_full";
+ return;
+ }
+ this.#queue.push(`${JSON.stringify(record)}\n`);
+ if (this.#draining === null) this.#scheduleDrain();
+ }
+
+ #scheduleDrain(): void {
+ this.#draining = this.#drain().finally(() => {
+ this.#draining = null;
+ if (this.#queue.length > 0) this.#scheduleDrain();
+ });
+ }
+
+ async #drain(): Promise<void> {
+ while (this.#queue.length > 0) {
+ const line = this.#queue.shift()!;
+ try {
+ await this.#file.appendFile(line, { encoding: "utf8" });
+ } catch {
+ this.#incompleteReason ??= "trace_sidecar_write_failed";
+ this.#queue.length = 0;
+ return;
+ }
+ }
+ }
+
+ #redact(raw: Buffer): Buffer {
+ if (this.#sensitiveValues.size === 0) return raw;
+ let value = raw.toString("utf8");
+ for (const sensitive of [...this.#sensitiveValues].sort(
+ (left, right) => right.length - left.length,
+ )) {
+ value = value.split(sensitive).join("[REDACTED]");
+ }
+ return Buffer.from(value, "utf8");
+ }
+}
+
+export async function createProviderTraceFileSink(input: {
+ path?: string;
+ provider: string;
+ channel: string;
+ maxBytes?: string | number;
+}): Promise<ProviderTraceFileSink | null> {
+ if (!input.path) return null;
+ const maxBytes = typeof input.maxBytes === "number"
+ ? input.maxBytes
+ : Number.parseInt(input.maxBytes ?? "", 10);
+ // Keep one descriptor for the sink lifetime. This prevents a path swap
+ // between permission hardening, replay inspection, and later appends.
+ const file = await open(input.path, "a+", 0o600);
+ let existing: string;
+ try {
+ // Opening an existing file preserves its prior mode. Tighten it before
+ // reading or appending so no provider frame has a readable exposure window.
+ await file.chmod(0o600);
+ existing = await file.readFile({ encoding: "utf8" });
+ } catch (error) {
+ await file.close().catch(() => undefined);
+ throw error;
+ }
+ let nextFrameId = 1;
+ let nextDebugSequence = 1;
+ let capturedBytes = 0;
+ for (const line of existing.split("\n")) {
+ if (!line.trim()) continue;
+ try {
+ const entry = JSON.parse(line) as Record<string, unknown>;
+ if (entry.kind === "frame") {
+ nextFrameId = Math.max(nextFrameId, Number(entry.frameId) + 1 || 1);
+ capturedBytes += Number(entry.byteLength) || 0;
+ }
+ if (entry.debugChannel === input.channel) {
+ nextDebugSequence = Math.max(
+ nextDebugSequence,
+ Number(entry.debugSequence) + 1 || 1,
+ );
+ }
+ } catch {
+ // The server-side integrity pass will classify a malformed prior record.
+ }
+ }
+ return new ProviderTraceFileSink({
+ file,
+ provider: input.provider,
+ channel: input.channel,
+ maxBytes: Number.isSafeInteger(maxBytes) && maxBytes > 0 ? maxBytes : DEFAULT_MAX_BYTES,
+ nextFrameId,
+ nextDebugSequence,
+ capturedBytes,
+ });
+}
diff --git a/packages/paperclip-runner/src/drivers/opencode/mcp-bridge.test.ts b/packages/paperclip-runner/src/drivers/opencode/mcp-bridge.test.ts
new file mode 100644
index 0000000000..6539a14b52
--- /dev/null
+++ b/packages/paperclip-runner/src/drivers/opencode/mcp-bridge.test.ts
@@ -0,0 +1,182 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { canonicalOpenCodeMcpToolName, startOpenCodeMcpBridge, type OpenCodeMcpBridge } from "./mcp-bridge.js";
+
+const bridges: OpenCodeMcpBridge[] = [];
+
+afterEach(async () => {
+ await Promise.all(bridges.splice(0).map((bridge) => bridge.close()));
+});
+
+async function rpc(
+ bridge: OpenCodeMcpBridge,
+ body: Record<string, unknown>,
+ secret = bridge.secret,
+) {
+ return fetch(bridge.url, {
+ method: "POST",
+ headers: {
+ Authorization: `Bearer ${secret}`,
+ "Content-Type": "application/json",
+ Accept: "application/json, text/event-stream",
+ },
+ body: JSON.stringify({ jsonrpc: "2.0", ...body }),
+ });
+}
+
+describe("OpenCode MCP bridge", () => {
+ it("binds to loopback, requires authentication, and exposes only its closed catalog", async () => {
+ const bridge = await startOpenCodeMcpBridge({
+ secret: "session-secret",
+ tools: [{ name: "documents.read", description: "Read", inputSchema: { type: "object" } }],
+ handler: async () => ({ ok: true }),
+ });
+ bridges.push(bridge);
+ expect(new URL(bridge.url).hostname).toBe("127.0.0.1");
+ expect((await rpc(bridge, { id: 1, method: "tools/list" }, "wrong")).status).toBe(401);
+ const listed = await rpc(bridge, { id: 2, method: "tools/list" });
+ expect(await listed.json()).toMatchObject({
+ result: { tools: [
+ { name: "documents.read" },
+ { name: "paperclip_finish" },
+ { name: "paperclip_block" },
+ ] },
+ });
+ });
+
+ it("admits runner-private extension operations without advertising them to the model", async () => {
+ const handler = vi.fn(async ({ tool }) => ({ decision: tool === "__paperclip_permission" ? "accept" : "decline" }));
+ const bridge = await startOpenCodeMcpBridge({
+ tools: [{ name: "documents.read", inputSchema: { type: "object" } }],
+ privateTools: [{ name: "__paperclip_permission", inputSchema: { type: "object" } }],
+ handler,
+ });
+ bridges.push(bridge);
+ const listed = await (await rpc(bridge, { id: 1, method: "tools/list" })).json() as { result: { tools: Array<{ name: string }> } };
+ expect(listed.result.tools.map((tool) => tool.name)).not.toContain("__paperclip_permission");
+ expect(await (await rpc(bridge, {
+ id: "permission-1",
+ method: "tools/call",
+ params: { name: "__paperclip_permission", arguments: {} },
+ })).json()).toMatchObject({ result: { content: [{ text: "{\"decision\":\"accept\"}" }] } });
+ expect(handler).toHaveBeenCalledWith(expect.objectContaining({ tool: "__paperclip_permission" }));
+ });
+
+ it("maps prefixed names and replays identical duplicate calls exactly once", async () => {
+ const handler = vi.fn(async () => ({ value: 7 }));
+ const bridge = await startOpenCodeMcpBridge({
+ tools: [{ name: "documents.read", inputSchema: { type: "object" } }],
+ handler,
+ });
+ bridges.push(bridge);
+ const request = { id: "call-1", method: "tools/call", params: { name: "paperclip_documents.read", arguments: { id: "doc" } } };
+ expect(await (await rpc(bridge, request)).json()).toMatchObject({ result: { content: [{ text: "{\"value\":7}" }] } });
+ expect(await (await rpc(bridge, request)).json()).toMatchObject({ result: { content: [{ text: "{\"value\":7}" }] } });
+ expect(handler).toHaveBeenCalledTimes(1);
+ expect(handler).toHaveBeenCalledWith(expect.objectContaining({ tool: "documents.read", callId: "call-1", arguments: { id: "doc" } }));
+ });
+
+ it("fails conflicting duplicate identities and handler errors closed", async () => {
+ const bridge = await startOpenCodeMcpBridge({
+ tools: [{ name: "documents.read", inputSchema: { type: "object" } }],
+ handler: async () => { throw new Error("denied"); },
+ });
+ bridges.push(bridge);
+ const failed = await rpc(bridge, { id: "call-2", method: "tools/call", params: { name: "documents.read", arguments: { id: "a" } } });
+ expect(await failed.json()).toMatchObject({ result: { isError: true, content: [{ text: "denied" }] } });
+ const conflict = await rpc(bridge, { id: "call-2", method: "tools/call", params: { name: "documents.read", arguments: { id: "b" } } });
+ expect(await conflict.json()).toMatchObject({ result: { isError: true, content: [{ text: "Duplicate call identity conflict." }] } });
+ });
+
+ it("normalizes all supported OpenCode MCP prefixes", () => {
+ expect(canonicalOpenCodeMcpToolName("paperclip_documents.read")).toBe("documents.read");
+ expect(canonicalOpenCodeMcpToolName("paperclip__documents.read")).toBe("documents.read");
+ expect(canonicalOpenCodeMcpToolName("paperclip.documents.read")).toBe("documents.read");
+ expect(canonicalOpenCodeMcpToolName("paperclip_paperclip_finish")).toBe("paperclip_finish");
+ });
+
+ it("validates inputs before dispatch", async () => {
+ const handler = vi.fn(async () => ({ ok: true }));
+ const bridge = await startOpenCodeMcpBridge({
+ tools: [{
+ name: "documents.read",
+ inputSchema: { type: "object", required: ["id"], properties: { id: { type: "string" } }, additionalProperties: false },
+ }],
+ handler,
+ });
+ bridges.push(bridge);
+ const response = await rpc(bridge, {
+ id: "invalid",
+ method: "tools/call",
+ params: { name: "documents.read", arguments: { id: 9 } },
+ });
+ expect(await response.json()).toMatchObject({ result: { isError: true } });
+ expect(handler).not.toHaveBeenCalled();
+ });
+
+ it("times out and cancels in-flight calls", async () => {
+ const observed = vi.fn();
+ const bridge = await startOpenCodeMcpBridge({
+ tools: [{ name: "documents.read", inputSchema: { type: "object" } }],
+ timeoutMs: 20,
+ handler: ({ signal }) => new Promise((_resolve, reject) => {
+ signal.addEventListener("abort", () => { observed(); reject(new Error("aborted")); }, { once: true });
+ }),
+ });
+ bridges.push(bridge);
+ const response = await rpc(bridge, {
+ id: "slow-call",
+ method: "tools/call",
+ params: { name: "documents.read", arguments: {} },
+ });
+ expect(await response.json()).toMatchObject({ result: { isError: true, content: [{ text: "Paperclip tool call timed out" }] } });
+ expect(observed).toHaveBeenCalledOnce();
+ });
+
+ it("allows human-gated private calls to outlive ordinary tool timeouts", async () => {
+ const bridge = await startOpenCodeMcpBridge({
+ tools: [{ name: "documents.read", inputSchema: { type: "object" } }],
+ privateTools: [{ name: "__paperclip_runtime_input", inputSchema: { type: "object" } }],
+ timeoutMs: 20,
+ privateToolTimeoutMs: 200,
+ handler: async ({ tool }) => {
+ await new Promise((resolve) => setTimeout(resolve, 50));
+ return { tool, resolved: true };
+ },
+ });
+ bridges.push(bridge);
+ const response = await rpc(bridge, {
+ id: "human-input",
+ method: "tools/call",
+ params: { name: "__paperclip_runtime_input", arguments: {} },
+ });
+ expect(await response.json()).toMatchObject({
+ result: { content: [{ text: expect.stringContaining("\"resolved\":true") }] },
+ });
+ });
+
+ it("honors MCP cancellation notifications", async () => {
+ const started = vi.fn();
+ const bridge = await startOpenCodeMcpBridge({
+ tools: [{ name: "documents.read", inputSchema: { type: "object" } }],
+ handler: ({ signal }) => new Promise((_resolve, reject) => {
+ started();
+ signal.addEventListener("abort", () => reject(new Error("handler aborted")), { once: true });
+ }),
+ });
+ bridges.push(bridge);
+ const pending = rpc(bridge, {
+ id: "cancel-me",
+ method: "tools/call",
+ params: { name: "documents.read", arguments: {} },
+ });
+ await vi.waitFor(() => expect(started).toHaveBeenCalledOnce());
+ expect((await rpc(bridge, {
+ method: "notifications/cancelled",
+ params: { requestId: "cancel-me", reason: "turn stopped" },
+ })).status).toBe(202);
+ expect(await (await pending).json()).toMatchObject({
+ result: { isError: true, content: [{ text: "Paperclip tool call cancelled" }] },
+ });
+ });
+});
diff --git a/packages/paperclip-runner/src/drivers/opencode/mcp-bridge.ts b/packages/paperclip-runner/src/drivers/opencode/mcp-bridge.ts
new file mode 100644
index 0000000000..79ce677037
--- /dev/null
+++ b/packages/paperclip-runner/src/drivers/opencode/mcp-bridge.ts
@@ -0,0 +1,356 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { Ajv2020, type ValidateFunction } from "ajv/dist/2020.js";
+
+import {
+ PRP_BLOCK_RESULT_PROVIDER_INPUT_SCHEMA,
+ PRP_BLOCK_TOOL_NAME,
+ PRP_COMPLETION_RESULT_PROVIDER_INPUT_SCHEMA,
+ PRP_COMPLETION_TOOL_NAME,
+} from "../../contracts/completion-result.js";
+
+export interface OpenCodeMcpToolDefinition {
+ name: string;
+ description?: string;
+ inputSchema: Record<string, unknown>;
+}
+
+export interface OpenCodeMcpCall {
+ tool: string;
+ callId: string;
+ arguments: unknown;
+ signal: AbortSignal;
+}
+
+export interface OpenCodeMcpBridgeOptions {
+ tools?: readonly Readonly<Record<string, unknown>>[];
+ /** Runner-owned operations callable only by a trusted harness extension and never advertised to the model. */
+ privateTools?: readonly Readonly<Record<string, unknown>>[];
+ handler: (call: OpenCodeMcpCall) => Promise<unknown>;
+ timeoutMs?: number;
+ /** Human-gated private operations may remain pending much longer than model tool calls. */
+ privateToolTimeoutMs?: number;
+ maxBodyBytes?: number;
+ secret?: string;
+}
+
+export interface OpenCodeMcpBridge {
+ url: string;
+ secret: string;
+ close(): Promise<void>;
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_BODY_BYTES = 1_048_576;
+
+export function canonicalOpenCodeMcpToolName(name: string): string {
+ const trimmed = name.trim();
+ if (trimmed === PRP_COMPLETION_TOOL_NAME || trimmed === PRP_BLOCK_TOOL_NAME) return trimmed;
+ for (const prefix of ["paperclip__", "paperclip_", "paperclip."]) {
+ if (trimmed.startsWith(prefix)) return trimmed.slice(prefix.length);
+ }
+ return trimmed;
+}
+
+export async function startOpenCodeMcpBridge(
+ options: OpenCodeMcpBridgeOptions,
+): Promise<OpenCodeMcpBridge> {
+ const secret = options.secret ?? randomBytes(32).toString("base64url");
+ const tools = normalizeTools(options.tools ?? []);
+ const privateTools = normalizeTools(options.privateTools ?? [], false);
+ const admittedTools = [...tools, ...privateTools.filter((candidate) => !tools.some((tool) => tool.name === candidate.name))];
+ const validators = compileValidators(admittedTools);
+ const calls = new Map<string, { fingerprint: string; promise: Promise<unknown> }>();
+ const controllers = new Map<string, AbortController>();
+ const server = createServer((request, response) => {
+ void handleRequest(request, response, {
+ secret,
+ tools,
+ admittedTools,
+ validators,
+ calls,
+ controllers,
+ handler: options.handler,
+ timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+ privateToolTimeoutMs: options.privateToolTimeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+ privateToolNames: new Set(privateTools.map((tool) => tool.name)),
+ maxBodyBytes: options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES,
+ });
+ });
+ await new Promise<void>((resolve, reject) => {
+ server.once("error", reject);
+ server.listen(0, "127.0.0.1", () => {
+ server.off("error", reject);
+ resolve();
+ });
+ });
+ const address = server.address();
+ if (address === null || typeof address === "string") {
+ await closeServer(server);
+ throw new Error("OpenCode MCP bridge failed to bind a loopback port");
+ }
+ return {
+ url: `http://127.0.0.1:${address.port}/mcp`,
+ secret,
+ close: async () => {
+ for (const controller of controllers.values()) controller.abort();
+ await closeServer(server);
+ },
+ };
+}
+
+function normalizeTools(
+ input: readonly Readonly<Record<string, unknown>>[],
+ includeTerminalTools = true,
+): OpenCodeMcpToolDefinition[] {
+ const tools: OpenCodeMcpToolDefinition[] = [];
+ const seen = new Set<string>();
+ for (const raw of input) {
+ const name = typeof raw.name === "string" ? canonicalOpenCodeMcpToolName(raw.name) : "";
+ if (!name || seen.has(name)) continue;
+ const inputSchema = isRecord(raw.inputSchema) ? structuredClone(raw.inputSchema) : { type: "object" };
+ tools.push({
+ name,
+ ...(typeof raw.description === "string" ? { description: raw.description } : {}),
+ inputSchema,
+ });
+ seen.add(name);
+ }
+ if (includeTerminalTools) for (const terminal of [
+ { name: PRP_COMPLETION_TOOL_NAME, description: "Return the semantic completion result.", inputSchema: PRP_COMPLETION_RESULT_PROVIDER_INPUT_SCHEMA },
+ { name: PRP_BLOCK_TOOL_NAME, description: "Return the semantic blocked result.", inputSchema: PRP_BLOCK_RESULT_PROVIDER_INPUT_SCHEMA },
+ ]) {
+ if (!seen.has(terminal.name)) tools.push(terminal);
+ }
+ return tools;
+}
+
+function compileValidators(tools: readonly OpenCodeMcpToolDefinition[]): Map<string, ValidateFunction> {
+ const ajv = new Ajv2020({ allErrors: true, strict: false });
+ return new Map(tools.map((tool) => [tool.name, ajv.compile(tool.inputSchema)]));
+}
+
+async function handleRequest(
+ request: IncomingMessage,
+ response: ServerResponse,
+ context: {
+ secret: string;
+ tools: OpenCodeMcpToolDefinition[];
+ admittedTools: OpenCodeMcpToolDefinition[];
+ validators: Map<string, ValidateFunction>;
+ calls: Map<string, { fingerprint: string; promise: Promise<unknown> }>;
+ controllers: Map<string, AbortController>;
+ handler: OpenCodeMcpBridgeOptions["handler"];
+ timeoutMs: number;
+ privateToolTimeoutMs: number;
+ privateToolNames: ReadonlySet<string>;
+ maxBodyBytes: number;
+ },
+): Promise<void> {
+ setSecurityHeaders(response);
+ if (!authorized(request.headers.authorization, context.secret)) {
+ response.statusCode = 401;
+ response.end();
+ return;
+ }
+ if (request.method === "GET") {
+ response.statusCode = 405;
+ response.setHeader("Allow", "POST, DELETE");
+ response.end();
+ return;
+ }
+ if (request.method === "DELETE") {
+ response.statusCode = 204;
+ response.end();
+ return;
+ }
+ if (request.method !== "POST" || request.url !== "/mcp") {
+ response.statusCode = 404;
+ response.end();
+ return;
+ }
+ let message: Record<string, unknown>;
+ try {
+ message = parseMessage(await readBody(request, context.maxBodyBytes));
+ } catch (error) {
+ writeRpc(response, null, undefined, rpcError(-32700, safeError(error)));
+ return;
+ }
+ const id = message.id ?? null;
+ const method = typeof message.method === "string" ? message.method : "";
+ if (method === "notifications/cancelled") {
+ const params = isRecord(message.params) ? message.params : {};
+ const requestId = params.requestId;
+ if (typeof requestId === "string" || typeof requestId === "number") {
+ context.controllers.get(String(requestId))?.abort();
+ }
+ response.statusCode = 202;
+ response.end();
+ return;
+ }
+ if (method === "notifications/initialized") {
+ response.statusCode = 202;
+ response.end();
+ return;
+ }
+ if (method === "initialize") {
+ response.setHeader("Mcp-Session-Id", randomBytes(16).toString("hex"));
+ writeRpc(response, id, {
+ protocolVersion: "2025-03-26",
+ capabilities: { tools: { listChanged: false } },
+ serverInfo: { name: "paperclip-runner", version: "1" },
+ });
+ return;
+ }
+ if (method === "ping") {
+ writeRpc(response, id, {});
+ return;
+ }
+ if (method === "tools/list") {
+ writeRpc(response, id, { tools: context.tools });
+ return;
+ }
+ if (method !== "tools/call") {
+ writeRpc(response, id, undefined, rpcError(-32601, "Method not found"));
+ return;
+ }
+ const params = isRecord(message.params) ? message.params : {};
+ const rawName = typeof params.name === "string" ? params.name : "";
+ const tool = canonicalOpenCodeMcpToolName(rawName);
+ if (!context.admittedTools.some((entry) => entry.name === tool)) {
+ writeRpc(response, id, { isError: true, content: [{ type: "text", text: "Unsupported tool." }] });
+ return;
+ }
+ const callId = typeof id === "string" || typeof id === "number" ? String(id) : randomBytes(12).toString("hex");
+ const args = params.arguments ?? {};
+ const validator = context.validators.get(tool);
+ if (validator === undefined || !validator(args)) {
+ const detail = validator?.errors?.map((error) => `${error.instancePath || "/"} ${error.message ?? "is invalid"}`).join("; ");
+ writeRpc(response, id, {
+ isError: true,
+ content: [{ type: "text", text: `Invalid tool input${detail ? `: ${detail}` : "."}` }],
+ });
+ return;
+ }
+ const fingerprint = canonicalJson({ tool, args });
+ const existing = context.calls.get(callId);
+ if (existing && existing.fingerprint !== fingerprint) {
+ writeRpc(response, id, { isError: true, content: [{ type: "text", text: "Duplicate call identity conflict." }] });
+ return;
+ }
+ const controller = existing === undefined ? new AbortController() : undefined;
+ const execution = existing?.promise ?? withCancellationAndTimeout(
+ context.handler({ tool, callId, arguments: structuredClone(args), signal: controller!.signal }),
+ controller!,
+ context.privateToolNames.has(tool) ? context.privateToolTimeoutMs : context.timeoutMs,
+ );
+ if (!existing) {
+ if (context.calls.size >= 2_048) context.calls.delete(context.calls.keys().next().value!);
+ context.calls.set(callId, { fingerprint, promise: execution });
+ context.controllers.set(callId, controller!);
+ void execution.finally(() => context.controllers.delete(callId)).catch(() => undefined);
+ }
+ try {
+ const result = await execution;
+ writeRpc(response, id, { content: [{ type: "text", text: safeJson(result) }] });
+ } catch (error) {
+ writeRpc(response, id, { isError: true, content: [{ type: "text", text: safeError(error) }] });
+ }
+}
+
+function authorized(value: string | undefined, secret: string): boolean {
+ if (!value?.startsWith("Bearer ")) return false;
+ const supplied = Buffer.from(value.slice(7));
+ const expected = Buffer.from(secret);
+ return supplied.length === expected.length && timingSafeEqual(supplied, expected);
+}
+
+function readBody(request: IncomingMessage, maxBytes: number): Promise<string> {
+ return new Promise((resolve, reject) => {
+ const chunks: Buffer[] = [];
+ let size = 0;
+ request.on("data", (chunk: Buffer) => {
+ size += chunk.length;
+ if (size > maxBytes) {
+ reject(new Error("MCP request exceeded the retained payload limit"));
+ request.destroy();
+ return;
+ }
+ chunks.push(chunk);
+ });
+ request.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+ request.on("error", reject);
+ });
+}
+
+function parseMessage(body: string): Record<string, unknown> {
+ const parsed: unknown = JSON.parse(body);
+ if (!isRecord(parsed) || parsed.jsonrpc !== "2.0") throw new Error("Invalid JSON-RPC request");
+ return parsed;
+}
+
+function writeRpc(response: ServerResponse, id: unknown, result?: unknown, error?: unknown): void {
+ response.statusCode = 200;
+ response.setHeader("Content-Type", "application/json");
+ response.end(JSON.stringify({ jsonrpc: "2.0", id, ...(error === undefined ? { result } : { error }) }));
+}
+
+function rpcError(code: number, message: string) {
+ return { code, message };
+}
+
+function setSecurityHeaders(response: ServerResponse): void {
+ response.setHeader("Cache-Control", "no-store");
+ response.setHeader("X-Content-Type-Options", "nosniff");
+}
+
+function closeServer(server: Server): Promise<void> {
+ return new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+}
+
+function withCancellationAndTimeout<T>(
+ promise: Promise<T>,
+ controller: AbortController,
+ timeoutMs: number,
+): Promise<T> {
+ return new Promise((resolve, reject) => {
+ let settled = false;
+ const finish = (callback: () => void) => {
+ if (settled) return;
+ settled = true;
+ clearTimeout(timer);
+ controller.signal.removeEventListener("abort", onAbort);
+ callback();
+ };
+ const onAbort = () => finish(() => reject(new Error("Paperclip tool call cancelled")));
+ const timer = setTimeout(() => {
+ finish(() => reject(new Error("Paperclip tool call timed out")));
+ controller.abort();
+ }, timeoutMs);
+ timer.unref?.();
+ controller.signal.addEventListener("abort", onAbort, { once: true });
+ promise.then(
+ (value) => finish(() => resolve(value)),
+ (error) => finish(() => reject(error)),
+ );
+ });
+}
+
+function safeError(error: unknown): string {
+ return (error instanceof Error ? error.message : String(error)).slice(0, 2_000);
+}
+
+function safeJson(value: unknown): string {
+ const serialized = JSON.stringify(value);
+ return (serialized ?? "null").slice(0, 64 * 1024);
+}
+
+function canonicalJson(value: unknown): string {
+ if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+ if (isRecord(value)) return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+ return JSON.stringify(value) ?? "undefined";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
diff --git a/packages/paperclip-runner/src/drivers/opencode/opencode-server-driver.test.ts b/packages/paperclip-runner/src/drivers/opencode/opencode-server-driver.test.ts
new file mode 100644
index 0000000000..b5abaa4fb2
--- /dev/null
+++ b/packages/paperclip-runner/src/drivers/opencode/opencode-server-driver.test.ts
@@ -0,0 +1,920 @@
+import { chmod, lstat, mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+ NATIVE_RUNTIME_ASSET_SCHEMA,
+ PAPERCLIP_EXECUTION_PROMPT,
+ PAPERCLIP_EXECUTION_PROMPT_REVISION,
+ canonicalNativeRuntimeContextDigest,
+ nativeRuntimePromptDigest,
+ type NativeRuntimeContextSnapshot,
+} from "../../contracts/runtime-context.js";
+import { OpenCodeServerDriver, openCodeServerDriverInternals } from "./opencode-server-driver.js";
+
+const roots: string[] = [];
+const fixture = resolve("test/fixtures/fake-opencode-server.mjs");
+
+function runtimeContext(skillRoot: string, instructionRoot: string): NativeRuntimeContextSnapshot {
+ const digest = "0".repeat(64);
+ const value = {
+ prompt: {
+ revision: PAPERCLIP_EXECUTION_PROMPT_REVISION,
+ text: PAPERCLIP_EXECUTION_PROMPT,
+ digest: nativeRuntimePromptDigest(),
+ },
+ instructions: {
+ entryPath: "AGENTS.md",
+ bundle: {
+ schema: NATIVE_RUNTIME_ASSET_SCHEMA,
+ digest,
+ manifestDigest: digest,
+ rootPath: instructionRoot,
+ fileCount: 2,
+ totalBytes: 2,
+ },
+ },
+ skills: [{
+ key: "company/assigned",
+ runtimeName: "assigned",
+ versionId: "version-1",
+ bundle: {
+ schema: NATIVE_RUNTIME_ASSET_SCHEMA,
+ digest,
+ manifestDigest: digest,
+ rootPath: skillRoot,
+ fileCount: 2,
+ totalBytes: 2,
+ },
+ }],
+ mcp: { assignmentSetId: "assigned", digest, bindingId: "binding" },
+ } satisfies Omit<NativeRuntimeContextSnapshot, "aggregateDigest">;
+ return { ...value, aggregateDigest: canonicalNativeRuntimeContextDigest(value) };
+}
+
+async function makeWritable(root: string): Promise<void> {
+ const info = await lstat(root).catch(() => null);
+ if (!info) return;
+ if (info.isDirectory()) {
+ await chmod(root, 0o700);
+ for (const entry of await readdir(root)) await makeWritable(join(root, entry));
+ } else {
+ await chmod(root, 0o600);
+ }
+}
+
+afterEach(async () => {
+ await Promise.all(roots.splice(0).map(async (root) => {
+ await makeWritable(root);
+ await rm(root, { recursive: true, force: true });
+ }));
+});
+
+describe("OpenCodeServerDriver", () => {
+ it("advertises within-turn plans as unsupported", async () => {
+ const driver = new OpenCodeServerDriver({
+ model: "openrouter/deepseek/deepseek-v4-flash-0731",
+ runtimeDirectory: "/tmp/paperclip-opencode-capabilities",
+ command: fixture,
+ });
+ const descriptor = await driver.descriptor();
+ expect(descriptor.capabilities.typedEventFamilies
+ .find((family) => family.family === "plan"))
+ .toMatchObject({ availability: "unsupported" });
+ });
+
+ it("starts an authenticated isolated server, creates a session, streams usage, aborts, and cleans up", async () => {
+ await chmod(fixture, 0o755);
+ const root = await mkdtemp(join(tmpdir(), "paperclip-opencode-driver-"));
+ const workspace = await mkdtemp(join(tmpdir(), "paperclip-opencode-workspace-"));
+ roots.push(root, workspace);
+ const tracePath = join(root, "provider-trace.ndjson");
+ const spawns: Array<{ pid: number; processGroupId: number | null }> = [];
+ const diagnostics: string[] = [];
+ const driver = new OpenCodeServerDriver({
+ model: "openrouter/deepseek/deepseek-v4-flash-0731",
+ runtimeDirectory: root,
+ command: fixture,
+ environment: {
+ PATH: process.env.PATH,
+ OPENROUTER_API_KEY: "test-openrouter-key",
+ PAPERCLIP_API_KEY: "must-not-leak",
+ UNRELATED_SECRET: "must-not-leak",
+ PAPERCLIP_PROVIDER_TRACE_PATH: tracePath,
+ PAPERCLIP_PROVIDER_TRACE_MAX_BYTES: String(64 * 1024 * 1024),
+ },
+ onSpawn: async (meta) => { spawns.push(meta); },
+ onDiagnostic: (message) => diagnostics.push(message),
+ });
+ const session = await driver.openSession({ runId: "run-1", normalizedSessionId: "normalized/1", workingDirectory: workspace });
+ expect(session.ids()).toMatchObject({ providerSessionId: "ses_fake_1" });
+ expect(spawns).toHaveLength(1);
+ const turn = await session.startTurn({ message: { role: "user", text: "finish" } });
+ const events = [];
+ for await (const event of session.events()) events.push(event);
+ expect(events.map((event) => event.eventType)).toContain("turn.completed");
+ expect(events).toContainEqual(expect.objectContaining({ eventType: "run.result.proposed" }));
+ expect(events.filter((event) => event.eventType === "item.delta")).toHaveLength(1);
+ expect(events.find((event) => event.eventType === "item.delta")?.payload.text).toBe("done [guide](guide.md)");
+ expect(events.find(
+ (event) => event.eventType === "item.completed" && event.payload.kind === "agentMessage",
+ )?.payload).toMatchObject({
+ channel: "final",
+ providerPhase: "final_answer",
+ text: "done [guide](guide.md)",
+ });
+ expect(events.filter(
+ (event) => event.eventType === "item.completed" && event.payload.kind === "usage",
+ )).toHaveLength(1);
+ expect(events.find((event) => event.eventType === "workspace.change.updated")?.payload)
+ .toMatchObject({ schema: "paperclip.workspace.diff.v1", source: "harness_reported", totals: { files: 1 } });
+ expect(events.find((event) => event.eventType === "workspace.diff.recorded")?.payload)
+ .toMatchObject({ schema: "paperclip.workspace.diff.v1", complete: true });
+ expect(events.find((event) => event.eventType === "workspace.file.referenced")?.payload)
+ .toMatchObject({ schema: "paperclip.workspace.file_reference.v1", path: "guide.md" });
+ expect(JSON.stringify(events)).not.toContain("submitted prompt must not become assistant text");
+ expect(await session.usage()).toMatchObject({
+ input: 3,
+ output: 2,
+ costUsd: 0.001,
+ provider: "openrouter",
+ driverVersion: "1.18.17",
+ });
+ await session.interrupt?.({ turnId: turn.turnId });
+ const snapshot = await session.snapshot();
+ expect(snapshot.driverKind).toBe("opencode_server");
+ const sessionRoot = join(root, "normalized_1");
+ expect((await stat(sessionRoot)).mode & 0o777).toBe(0o700);
+ expect((await stat(join(sessionRoot, "config", "opencode", "opencode.json"))).mode & 0o777).toBe(0o600);
+ const config = await readFile(join(sessionRoot, "config", "opencode", "opencode.json"), "utf8");
+ await session.close({ reason: "test" });
+ const recovered = await driver.recoverSession?.(snapshot);
+ expect(recovered).toMatchObject({ recovered: true });
+ await expect(recovered?.session?.read?.()).resolves.toMatchObject({ sessionId: "ses_fake_1", messages: [] });
+ await recovered?.session?.close({ reason: "recovery-test" });
+
+ const traceEntries = (await readFile(tracePath, "utf8"))
+ .trim()
+ .split("\n")
+ .map((line) => JSON.parse(line) as Record<string, unknown>);
+ const traceFrames = traceEntries.filter((entry) => entry.kind === "frame");
+ expect(traceFrames.map((entry) => entry.direction)).toEqual(
+ expect.arrayContaining(["client_to_provider", "provider_to_client", "provider_stderr"]),
+ );
+ expect(traceFrames.some((entry) => entry.nativeMethod === "SSE /event")).toBe(true);
+ expect(traceEntries.some(
+ (entry) => entry.stage === "typescript_opencode_driver_normalization"
+ && Array.isArray(entry.emittedEventIds)
+ && entry.emittedEventIds.length > 0,
+ )).toBe(true);
+ expect(traceEntries.at(-1)).toMatchObject({
+ kind: "trace_status",
+ debugChannel: "typescript_opencode_native",
+ status: "complete",
+ });
+
+ const environment = JSON.parse(await readFile(join(sessionRoot, "data", "fake-environment.json"), "utf8"));
+ const mcpEvidence = JSON.parse(await readFile(join(sessionRoot, "data", "fake-mcp-evidence.json"), "utf8"));
+ expect(environment.keys).toContain("OPENROUTER_API_KEY");
+ expect(environment.keys).not.toContain("PAPERCLIP_API_KEY");
+ expect(environment.keys).not.toContain("UNRELATED_SECRET");
+ expect(environment.keys).not.toContain("PAPERCLIP_PROVIDER_TRACE_PATH");
+ expect(environment.projectConfigDisabled).toBe("true");
+ expect(mcpEvidence.tools).toEqual(expect.arrayContaining(["paperclip_finish", "paperclip_block"]));
+ expect(config).toContain("openrouter/deepseek/deepseek-v4-flash-0731");
+ expect(config).toContain('"*": "allow"');
+ expect(config).toContain('"external_directory": "deny"');
+ expect(events.some((event) => event.eventType === "runtime_request.created")).toBe(false);
+ expect(config).not.toContain("test-openrouter-key");
+ expect(diagnostics.join("\n")).not.toContain("test-openrouter-key");
+ expect(diagnostics.join("\n")).toContain("[REDACTED]");
+ });
+
+ it("maps OpenCode's normal abort error to cancellation without a false provider failure notice", async () => {
+ await chmod(fixture, 0o755);
+ const root = await mkdtemp(join(tmpdir(), "paperclip-opencode-abort-"));
+ const workspace = await mkdtemp(join(tmpdir(), "paperclip-opencode-abort-workspace-"));
+ roots.push(root, workspace);
+ const driver = new OpenCodeServerDriver({
+ model: "openrouter/deepseek/deepseek-v4-flash-0731",
+ runtimeDirectory: root,
+ command: fixture,
+ environment: { PATH: process.env.PATH, OPENROUTER_API_KEY: "fixture-key" },
+ });
+ const session = await driver.openSession({
+ runId: "run-aborted",
+ normalizedSessionId: "aborted",
+ workingDirectory: workspace,
+ });
+ await session.startTurn({ message: { role: "user", text: "session-aborted" } });
+ const events = [];
+ for await (const event of session.events()) events.push(event);
+ expect(events.map((event) => event.eventType)).toContain("turn.cancelled");
+ expect(events.map((event) => event.eventType)).not.toContain("turn.failed");
+ expect(events.map((event) => event.eventType)).not.toContain("provider.notice.recorded");
+ await session.close({ reason: "test" });
+ });
+
+ it("keeps OpenCode in an outer supervisor process group when requested", async () => {
+ await chmod(fixture, 0o755);
+ const root = await mkdtemp(join(tmpdir(), "paperclip-opencode-driver-"));
+ const workspace = await mkdtemp(join(tmpdir(), "paperclip-opencode-workspace-"));
+ roots.push(root, workspace);
+ let processGroupId: number | null | undefined;
+ const driver = new OpenCodeServerDriver({
+ model: "openrouter/deepseek/deepseek-v4-flash-0731",
+ runtimeDirectory: root,
+ command: fixture,
+ environment: { PATH: process.env.PATH, OPENROUTER_API_KEY: "fixture-key" },
+ isolateProcessGroup: false,
+ onSpawn: async (meta) => { processGroupId = meta.processGroupId; },
+ });
+ const session = await driver.openSession({ runId: "run-supervised", normalizedSessionId: "supervised", workingDirectory: workspace });
+ expect(processGroupId).toBeNull();
+ await session.close({ reason: "test" });
+ });
+
+ it("uses the native system channel, selected skill tree, instruction root, and assigned MCP gateway", async () => {
+ await chmod(fixture, 0o755);
+ const root = await mkdtemp(join(tmpdir(), "paperclip-opencode-context-"));
+ const workspace = await mkdtemp(join(tmpdir(), "paperclip-opencode-context-workspace-"));
+ const skillRoot = join(root, "skill-source");
+ const instructionRoot = join(root, "instruction-source");
+ roots.push(root, workspace);
+ await Promise.all([
+ mkdir(join(skillRoot, "references"), { recursive: true }),
+ mkdir(instructionRoot, { recursive: true }),
+ ]);
+ await Promise.all([
+ writeFile(join(skillRoot, "SKILL.md"), "# Assigned\nRead references/support.md\n"),
+ writeFile(join(skillRoot, "references", "support.md"), "skill support\n"),
+ writeFile(join(instructionRoot, "AGENTS.md"), "Read sibling.md\n"),
+ writeFile(join(instructionRoot, "sibling.md"), "instruction sibling\n"),
+ ]);
+ const systemInstructions = `${PAPERCLIP_EXECUTION_PROMPT}\n\nRead sibling.md\n\nRead-only instruction sibling root: ${instructionRoot}`;
+ let submittedPrompt: Record<string, unknown> | null = null;
+ const driver = new OpenCodeServerDriver({
+ model: "openrouter/deepseek/deepseek-v4-flash-0731",
+ runtimeDirectory: root,
+ command: fixture,
+ systemInstructions,
+ runtimeContext: runtimeContext(skillRoot, instructionRoot),
+ environment: {
+ PATH: process.env.PATH,
+ OPENROUTER_API_KEY: "fixture-key",
+ PAPERCLIP_NATIVE_MCP_NAME: "paperclip-assigned",
+ PAPERCLIP_NATIVE_MCP_URL: "https://paperclip.example/mcp",
+ PAPERCLIP_NATIVE_MCP_TOKEN: "x".repeat(40),
+ },
+ fetch: async (input, init) => {
+ if (String(input).endsWith("/prompt_async")) submittedPrompt = JSON.parse(String(init?.body));
+ return fetch(input, init);
+ },
+ });
+ const session = await driver.openSession({
+ runId: "run-context",
+ normalizedSessionId: "context",
+ workingDirectory: workspace,
+ });
+ await session.startTurn({ message: { role: "user", text: "finish" } });
+ for await (const event of session.events()) {
+ if (event.eventType === "turn.completed") break;
+ }
+ expect(submittedPrompt).toMatchObject({
+ system: systemInstructions,
+ tools: { question: true },
+ });
+ expect(JSON.stringify(submittedPrompt?.parts ?? null)).not.toContain(PAPERCLIP_EXECUTION_PROMPT);
+ const sessionRoot = join(root, "context");
+ const isolatedHomes = (await readdir(sessionRoot)).filter((entry) => entry.startsWith("home-"));
+ expect(isolatedHomes).toHaveLength(1);
+ await expect(readFile(join(sessionRoot, isolatedHomes[0]!, ".claude", "skills", "assigned", "references", "support.md"), "utf8"))
+ .resolves.toBe("skill support\n");
+ const config = JSON.parse(await readFile(join(sessionRoot, "config", "opencode", "opencode.json"), "utf8"));
+ expect(config).toMatchObject({
+ instructions: [],
+ plugin: [],
+ tools: { question: true },
+ permission: { external_directory: { "*": "deny", [`${instructionRoot}/**`]: "allow" } },
+ mcp: {
+ paperclip: { enabled: true },
+ "paperclip-assigned": { url: "https://paperclip.example/mcp", enabled: true },
+ },
+ });
+ await expect(readFile(join(instructionRoot, "sibling.md"), "utf8")).resolves.toBe("instruction sibling\n");
+ await session.close({ reason: "test" });
+ });
+
+ it("sends only the authoritative wake envelope when resuming an existing provider session", async () => {
+ await chmod(fixture, 0o755);
+ const root = await mkdtemp(join(tmpdir(), "paperclip-opencode-resume-context-"));
+ const workspace = await mkdtemp(join(tmpdir(), "paperclip-opencode-resume-workspace-"));
+ roots.push(root, workspace);
+ let submittedPrompt: Record<string, unknown> | null = null;
+ const driver = new OpenCodeServerDriver({
+ model: "openrouter/deepseek/deepseek-v4-flash-0731",
+ runtimeDirectory: root,
+ command: fixture,
+ systemInstructions: "large original system context",
+ environment: { PATH: process.env.PATH, OPENROUTER_API_KEY: "fixture-key" },
+ fetch: async (input, init) => {
+ if (String(input).endsWith("/prompt_async")) submittedPrompt = JSON.parse(String(init?.body));
+ return fetch(input, init);
+ },
+ });
+ const seed = await driver.openSession({
+ runId: "run-seed",
+ normalizedSessionId: "resume-context",
+ workingDirectory: workspace,
+ });
+ const snapshot = await seed.snapshot();
+ await seed.close({ reason: "seed complete" });
+
+ const recovered = await driver.recoverSession?.(snapshot);
+ expect(recovered).toMatchObject({ recovered: true });
+ await recovered!.session!.startTurn({
+ message: { role: "user", text: "{\"interactionResponses\":[{\"answer\":\"friendly\"}]}" },
+ });
+ for await (const event of recovered!.session!.events()) {
+ if (event.eventType === "turn.completed") break;
+ }
+
+ expect(submittedPrompt).toMatchObject({
+ providerID: "openrouter",
+ modelID: "deepseek/deepseek-v4-flash-0731",
+ tools: { question: true },
+ parts: [{ type: "text", text: "{\"interactionResponses\":[{\"answer\":\"friendly\"}]}" }],
+ });
+ expect(submittedPrompt).not.toHaveProperty("system");
+ await recovered!.session!.close({ reason: "recovery-test" });
+ });
+
+ it("normalizes native question.asked events and replies with ordered OpenCode answer arrays", async () => {
+ await chmod(fixture, 0o755);
+ const root = await mkdtemp(join(tmpdir(), "paperclip-opencode-question-"));
+ const workspace = await mkdtemp(join(tmpdir(), "paperclip-opencode-question-workspace-"));
+ roots.push(root, workspace);
+ const driver = new OpenCodeServerDriver({
+ model: "openrouter/deepseek/deepseek-v4-flash-0731",
+ runtimeDirectory: root,
+ command: fixture,
+ environment: { PATH: process.env.PATH, OPENROUTER_API_KEY: "fixture-key" },
+ });
+ const session = await driver.openSession({
+ runId: "run-native-question",
+ normalizedSessionId: "native-question",
+ workingDirectory: workspace,
+ });
+ const { turnId } = await session.startTurn({ message: { role: "user", text: "native-question" } });
+ const iterator = session.events()[Symbol.asyncIterator]();
+ let requestEvent: Awaited<ReturnType<typeof iterator.next>>["value"] | null = null;
+ for (let count = 0; count < 30; count += 1) {
+ const event = await iterator.next();
+ if (event.done) break;
+ if (event.value.eventType === "runtime_request.created") {
+ requestEvent = event.value;
+ break;
+ }
+ }
+ expect(requestEvent?.payload).toMatchObject({
+ request: {
+ schema: "paperclip.runtime_request.v2",
+ requestKind: "runtime",
+ type: "input",
+ input: {
+ schema: "paperclip.question_set.v1",
+ questions: [
+ { id: "environment", answerMode: "single_select", required: false, customAnswer: { enabled: true } },
+ { id: "regions", answerMode: "multi_select", required: false },
+ ],
+ },
+ },
+ });
+ await new Promise((resolveDelay) => setTimeout(resolveDelay, 20));
+ expect(session.pendingRuntimeRequests?.()).toHaveLength(1);
+ await session.resolveRuntimeRequest?.({
+ requestId: "question-native-1",
+ turnId,
+ resolution: {
+ action: "submit",
+ response: {
+ schema: "paperclip.question_response.v1",
+ answers: {
+ environment: { customText: "Canary" },
+ regions: { selectedOptionIds: ["option-1", "option-2"] },
+ },
+ },
+ },
+ });
+ const reply = JSON.parse(await readFile(join(root, "native-question", "data", "fake-question-reply.json"), "utf8"));
+ expect(reply).toEqual({
+ url: expect.stringContaining(`directory=${encodeURIComponent(workspace)}`),
+ body: { answers: [["Canary"], ["US", "EU"]] },
+ });
+ const terminalQuestionEvents = (await session.transcript?.())?.events.filter((event) =>
+ event.payload.requestId === "question-native-1"
+ && ["runtime_request.resolved", "runtime_request.cancelled"].includes(event.eventType)
+ ) ?? [];
+ expect(terminalQuestionEvents).toHaveLength(1);
+ expect(terminalQuestionEvents[0]?.payload).toMatchObject({
+ action: "submit",
+ response: {
+ schema: "paperclip.question_response.v1",
+ answers: {
+ environment: { customText: "Canary" },
+ regions: { selectedOptionIds: ["option-1", "option-2"] },
+ },
+ },
+ });
+ await session.close({ reason: "test" });
+ });
+
+ it("hands a native question to the durable interaction path without touching permissions", async () => {
+ await chmod(fixture, 0o755);
+ const root = await mkdtemp(join(tmpdir(), "paperclip-opencode-question-handoff-"));
+ const workspace = await mkdtemp(join(tmpdir(), "paperclip-opencode-question-handoff-workspace-"));
+ roots.push(root, workspace);
+ const driver = new OpenCodeServerDriver({
+ model: "openrouter/deepseek/deepseek-v4-flash-0731",
+ runtimeDirectory: root,
+ command: fixture,
+ environment: { PATH: process.env.PATH, OPENROUTER_API_KEY: "fixture-key" },
+ });
+ const session = await driver.openSession({
+ runId: "run-native-question-handoff",
+ normalizedSessionId: "native-question-handoff",
+ workingDirectory: workspace,
+ });
+ const { turnId } = await session.startTurn({ message: { role: "user", text: "native-question" } });
+ const iterator = session.events()[Symbol.asyncIterator]();
+ let created: Awaited<ReturnType<typeof iterator.next>>["value"] | null = null;
+ for (let count = 0; count < 30; count += 1) {
+ const next = await iterator.next();
+ if (next.done) break;
+ if (next.value.eventType === "runtime_request.created") {
+ created = next.value;
+ break;
+ }
+ }
+ expect(created).toMatchObject({
+ payload: { request: { requestId: "question-native-1", type: "input" } },
+ });
+
+ const firstHandoff = session.handoffRuntimeRequest?.({
+ requestId: "question-native-1",
+ turnId,
+ reason: "durable_handoff",
+ signal: new AbortController().signal,
+ });
+ expect(firstHandoff?.result).toBe("handed_off");
+ await firstHandoff?.cleanup;
+ const repeatedHandoff = session.handoffRuntimeRequest?.({
+ requestId: "question-native-1",
+ turnId,
+ reason: "durable_handoff",
+ signal: new AbortController().signal,
+ });
+ expect(repeatedHandoff?.result).toBe("already_settled");
+ await repeatedHandoff?.cleanup;
+
+ let expired: Awaited<ReturnType<typeof iterator.next>>["value"] | null = null;
+ for (let count = 0; count < 20; count += 1) {
+ const next = await iterator.next();
+ if (next.done) break;
+ if (next.value.eventType === "runtime_request.expired") {
+ expired = next.value;
+ break;
+ }
+ }
+ expect(expired).toMatchObject({
+ payload: {
+ requestId: "question-native-1",
+ reason: "durable_handoff",
+ replayAllowed: false,
+ requestType: "input",
+ request: {
+ schema: "paperclip.runtime_request.v2",
+ requestId: "question-native-1",
+ type: "input",
+ },
+ },
+ });
+ expect(session.pendingRuntimeRequests?.()).toEqual([]);
+ const terminal = (await session.transcript?.())?.events.filter((event) =>
+ event.payload.requestId === "question-native-1"
+ && ["runtime_request.resolved", "runtime_request.cancelled", "runtime_request.expired"].includes(event.eventType)
+ );
+ expect(terminal).toHaveLength(1);
+ await session.close({ reason: "handoff test complete" });
+ });
+
+ it("recovers a missed pending question from the list endpoint and rejects it", async () => {
+ await chmod(fixture, 0o755);
+ const root = await mkdtemp(join(tmpdir(), "paperclip-opencode-question-recovery-"));
+ const workspace = await mkdtemp(join(tmpdir(), "paperclip-opencode-question-recovery-workspace-"));
+ roots.push(root, workspace);
+ const normalizedSessionId = "question-recovery";
+ const driver = new OpenCodeServerDriver({
+ model: "openrouter/deepseek/deepseek-v4-flash-0731",
+ runtimeDirectory: root,
+ command: fixture,
+ environment: { PATH: process.env.PATH, OPENROUTER_API_KEY: "fixture-key" },
+ });
+ const seed = await driver.openSession({
+ runId: "run-question-recovery",
+ normalizedSessionId,
+ workingDirectory: workspace,
+ });
+ const snapshot = await seed.snapshot();
+ await seed.close({ reason: "simulate reconnect" });
+ const dataRoot = join(root, normalizedSessionId, "data");
+ await mkdir(dataRoot, { recursive: true });
+ await writeFile(join(dataRoot, "fake-pending-question.json"), JSON.stringify({
+ id: "question-native-1",
+ sessionID: "ses_fake_1",
+ questions: [{
+ id: "environment",
+ header: "Environment",
+ question: "Where should we deploy?",
+ options: [{ label: "Staging" }, { label: "Production" }],
+ custom: true,
+ }],
+ }));
+
+ const recovered = await driver.recoverSession?.({
+ ...snapshot,
+ activeTurnId: "turn-recovered-question",
+ });
+ expect(recovered).toMatchObject({ recovered: true });
+ const session = recovered!.session!;
+ const iterator = session.events()[Symbol.asyncIterator]();
+ let created: Awaited<ReturnType<typeof iterator.next>>["value"] | null = null;
+ for (let count = 0; count < 20; count += 1) {
+ const next = await iterator.next();
+ if (next.done) break;
+ if (next.value.eventType === "runtime_request.created") {
+ created = next.value;
+ break;
+ }
+ }
+ expect(created).toMatchObject({
+ payload: { request: { requestId: "question-native-1", type: "input" } },
+ });
+ await session.resolveRuntimeRequest?.({
+ requestId: "question-native-1",
+ turnId: "turn-recovered-question",
+ resolution: { action: "decline" },
+ });
+ expect(session.pendingRuntimeRequests?.()).toEqual([]);
+ await session.close({ reason: "recovery test complete" });
+ });
+
+ it.each([
+ { style: "legacy", action: "accept" as const, reply: "once" },
+ { style: "v2", action: "accept_for_session" as const, reply: "always" },
+ { style: "v2", action: "decline" as const, reply: "reject" },
+ ])("normalizes $style permission events and maps $action to $reply", async ({ style, action, reply }) => {
+ await chmod(fixture, 0o755);
+ const root = await mkdtemp(join(tmpdir(), `paperclip-opencode-permission-${style}-`));
+ const workspace = await mkdtemp(join(tmpdir(), `paperclip-opencode-permission-${style}-workspace-`));
+ roots.push(root, workspace);
+ const driver = new OpenCodeServerDriver({
+ model: "openrouter/deepseek/deepseek-v4-flash-0731",
+ permissionMode: "ask",
+ runtimeDirectory: root,
+ command: fixture,
+ environment: { PATH: process.env.PATH, OPENROUTER_API_KEY: "fixture-key" },
+ });
+ const normalizedSessionId = `native-permission-${style}-${action}`;
+ const session = await driver.openSession({
+ runId: `run-${normalizedSessionId}`,
+ normalizedSessionId,
+ workingDirectory: workspace,
+ });
+ const { turnId } = await session.startTurn({
+ message: { role: "user", text: `native-permission-${style}` },
+ });
+ const iterator = session.events()[Symbol.asyncIterator]();
+ let created: Awaited<ReturnType<typeof iterator.next>>["value"] | null = null;
+ for (let count = 0; count < 30; count += 1) {
+ const next = await iterator.next();
+ if (next.done) break;
+ if (next.value.eventType === "runtime_request.created") {
+ created = next.value;
+ break;
+ }
+ }
+ expect(created).toMatchObject({
+ payload: {
+ request: {
+ requestId: "permission-native-1",
+ type: "permission",
+ actions: ["accept", "accept_for_session", "decline", "cancel"],
+ },
+ },
+ });
+ await session.resolveRuntimeRequest?.({
+ requestId: "permission-native-1",
+ turnId,
+ resolution: { action },
+ });
+ const persisted = JSON.parse(
+ await readFile(join(root, normalizedSessionId, "data", "fake-permission-reply.json"), "utf8"),
+ );
+ expect(persisted).toEqual({
+ url: expect.stringContaining(`directory=${encodeURIComponent(workspace)}`),
+ body: { reply },
+ });
+ expect(session.pendingRuntimeRequests?.()).toEqual([]);
+ await session.close({ reason: "permission test complete" });
+ });
+
+ it.each(["allow", "ask", "deny"] as const)("pins the %s permission mode while retaining external-directory denial", async (permissionMode) => {
+ await chmod(fixture, 0o755);
+ const root = await mkdtemp(join(tmpdir(), `paperclip-opencode-mode-${permissionMode}-`));
+ const workspace = await mkdtemp(join(tmpdir(), `paperclip-opencode-mode-${permissionMode}-workspace-`));
+ roots.push(root, workspace);
+ const driver = new OpenCodeServerDriver({
+ model: "openrouter/deepseek/deepseek-v4-flash-0731",
+ permissionMode,
+ runtimeDirectory: root,
+ command: fixture,
+ environment: { PATH: process.env.PATH, OPENROUTER_API_KEY: "fixture-key" },
+ });
+ const session = await driver.openSession({ runId: `run-${permissionMode}`, normalizedSessionId: permissionMode, workingDirectory: workspace });
+ const config = JSON.parse(await readFile(join(root, permissionMode, "config", "opencode", "opencode.json"), "utf8"));
+ expect(config.permission).toMatchObject({ "*": permissionMode, external_directory: "deny" });
+ expect(config.permission.paperclip_finish).toBeUndefined();
+ expect(config.permission["paperclip_*"]).toBe("allow");
+ await session.close({ reason: "permission mode test complete" });
+ });
+
+ it("clears a stale active turn that already has a persisted terminal fingerprint", async () => {
+ await chmod(fixture, 0o755);
+ const root = await mkdtemp(join(tmpdir(), "paperclip-opencode-stale-turn-"));
+ const workspace = await mkdtemp(join(tmpdir(), "paperclip-opencode-stale-workspace-"));
+ roots.push(root, workspace);
+ const driver = new OpenCodeServerDriver({
+ model: "openrouter/deepseek/deepseek-v4-flash-0731",
+ runtimeDirectory: root,
+ command: fixture,
+ environment: { PATH: process.env.PATH, OPENROUTER_API_KEY: "fixture-key" },
+ });
+ const seed = await driver.openSession({
+ runId: "run-stale-turn",
+ normalizedSessionId: "stale-turn",
+ workingDirectory: workspace,
+ });
+ const snapshot = await seed.snapshot();
+ await seed.close({ reason: "seed complete" });
+
+ const recoveryDriver = new OpenCodeServerDriver({
+ model: "openrouter/deepseek/deepseek-v4-flash-0731",
+ runtimeDirectory: root,
+ command: fixture,
+ environment: { PATH: process.env.PATH, OPENROUTER_API_KEY: "fixture-key" },
+ });
+ const recovery = await recoveryDriver.recoverSession?.({
+ ...snapshot,
+ activeTurnId: "turn-already-terminal",
+ terminalTurns: [{ turnId: "turn-already-terminal", fingerprint: "terminal-fingerprint" }],
+ });
+ expect(recovery).toMatchObject({ recovered: true });
+ await expect(recovery!.session!.snapshot()).resolves.toMatchObject({ activeTurnId: null });
+ await recovery!.session!.close({ reason: "recovery-test" });
+ });
+
+ it("validates provider/model form", async () => {
+ const root = await mkdtemp(join(tmpdir(), "paperclip-opencode-driver-"));
+ roots.push(root);
+ const driver = new OpenCodeServerDriver({ model: "bad", runtimeDirectory: root });
+ await expect(driver.validateConfig?.({ model: "bad" })).resolves.toMatchObject({ ok: false });
+ await expect(driver.validateConfig?.({ model: "openrouter/model" })).resolves.toMatchObject({ ok: true });
+ });
+
+ it("normalizes a structured block result", async () => {
+ await chmod(fixture, 0o755);
+ const root = await mkdtemp(join(tmpdir(), "paperclip-opencode-driver-"));
+ const workspace = await mkdtemp(join(tmpdir(), "paperclip-opencode-workspace-"));
+ roots.push(root, workspace);
+ const driver = new OpenCodeServerDriver({
+ model: "openrouter/deepseek/deepseek-v4-flash-0731",
+ runtimeDirectory: root,
+ command: fixture,
+ environment: { PATH: process.env.PATH, OPENROUTER_API_KEY: "fixture-key" },
+ });
+ const session = await driver.openSession({ runId: "run-block", normalizedSessionId: "block", workingDirectory: workspace });
+ await session.startTurn({ message: { role: "user", text: "block-result" } });
+ const events = [];
+ for await (const event of session.events()) events.push(event);
+ expect(events.find((event) => event.eventType === "run.result.proposed")?.payload)
+ .toMatchObject({ reportedWorkDisposition: "blocked", blocker: { reasonCode: "test_dependency" } });
+ await session.close({ reason: "test" });
+ });
+
+ it("designates the substantive pre-finish response instead of a trailing acknowledgement", async () => {
+ await chmod(fixture, 0o755);
+ const root = await mkdtemp(join(tmpdir(), "paperclip-opencode-driver-"));
+ const workspace = await mkdtemp(join(tmpdir(), "paperclip-opencode-workspace-"));
+ roots.push(root, workspace);
+ const driver = new OpenCodeServerDriver({
+ model: "openrouter/deepseek/deepseek-v4-flash-0731",
+ runtimeDirectory: root,
+ command: fixture,
+ environment: { PATH: process.env.PATH, OPENROUTER_API_KEY: "fixture-key" },
+ });
+ const session = await driver.openSession({
+ runId: "run-final-selection",
+ normalizedSessionId: "final-selection",
+ workingDirectory: workspace,
+ });
+ await session.startTurn({ message: { role: "user", text: "text-before-finish" } });
+ const events = [];
+ for await (const event of session.events()) events.push(event);
+ const finalMessages = events.filter(
+ (event) => event.eventType === "item.completed"
+ && event.payload.kind === "agentMessage"
+ && event.payload.channel === "final",
+ );
+ expect(finalMessages).toHaveLength(1);
+ expect(finalMessages[0]?.payload.text).toBe("Substantive answer before finish.");
+ expect(events.filter((event) => event.eventType === "item.delta").map((event) => event.payload.text))
+ .toEqual(expect.arrayContaining(["Substantive answer before finish.", "Done."]));
+ await session.close({ reason: "test" });
+ });
+
+ it("does not promote opening commentary to the final response when work follows it", async () => {
+ await chmod(fixture, 0o755);
+ const root = await mkdtemp(join(tmpdir(), "paperclip-opencode-driver-"));
+ const workspace = await mkdtemp(join(tmpdir(), "paperclip-opencode-workspace-"));
+ roots.push(root, workspace);
+ const driver = new OpenCodeServerDriver({
+ model: "openrouter/deepseek/deepseek-v4-flash-0731",
+ runtimeDirectory: root,
+ command: fixture,
+ environment: { PATH: process.env.PATH, OPENROUTER_API_KEY: "fixture-key" },
+ });
+ const session = await driver.openSession({
+ runId: "run-commentary-only",
+ normalizedSessionId: "commentary-only",
+ workingDirectory: workspace,
+ });
+ await session.startTurn({ message: { role: "user", text: "commentary-only-before-work" } });
+ const events = [];
+ for await (const event of session.events()) events.push(event);
+ expect(events.filter(
+ (event) => event.eventType === "item.completed"
+ && event.payload.kind === "agentMessage"
+ && event.payload.channel === "final",
+ )).toHaveLength(0);
+ expect(events.filter((event) => event.eventType === "item.delta").map((event) => event.payload.text))
+ .toContain("I will inspect the workspace first.");
+ expect(events).toContainEqual(expect.objectContaining({ eventType: "run.result.proposed" }));
+ await session.close({ reason: "test" });
+ });
+
+ it("correlates the final response to the native message containing the semantic tool", async () => {
+ await chmod(fixture, 0o755);
+ const root = await mkdtemp(join(tmpdir(), "paperclip-opencode-driver-"));
+ const workspace = await mkdtemp(join(tmpdir(), "paperclip-opencode-workspace-"));
+ roots.push(root, workspace);
+ const driver = new OpenCodeServerDriver({
+ model: "openrouter/deepseek/deepseek-v4-flash-0731",
+ runtimeDirectory: root,
+ command: fixture,
+ environment: { PATH: process.env.PATH, OPENROUTER_API_KEY: "fixture-key" },
+ });
+ const session = await driver.openSession({
+ runId: "run-correlated-final-selection",
+ normalizedSessionId: "correlated-final-selection",
+ workingDirectory: workspace,
+ });
+ await session.startTurn({ message: { role: "user", text: "correlated-final-message" } });
+ const events = [];
+ for await (const event of session.events()) events.push(event);
+ const finalMessages = events.filter(
+ (event) => event.eventType === "item.completed"
+ && event.payload.kind === "agentMessage"
+ && event.payload.channel === "final",
+ );
+ expect(finalMessages).toHaveLength(1);
+ expect(finalMessages[0]?.payload.text).toBe("Correlated substantive final answer.");
+ expect(events.filter((event) => event.eventType === "item.delta").map((event) => event.payload.text))
+ .toEqual(expect.arrayContaining([
+ "I will write the result now.",
+ "Correlated substantive final answer.",
+ "Done.",
+ ]));
+ await session.close({ reason: "test" });
+ });
+
+ it("prefers a substantive post-tool answer over schema commentary in the tool message", async () => {
+ await chmod(fixture, 0o755);
+ const root = await mkdtemp(join(tmpdir(), "paperclip-opencode-driver-"));
+ const workspace = await mkdtemp(join(tmpdir(), "paperclip-opencode-workspace-"));
+ roots.push(root, workspace);
+ const driver = new OpenCodeServerDriver({
+ model: "openrouter/deepseek/deepseek-v4-flash-0731",
+ runtimeDirectory: root,
+ command: fixture,
+ environment: { PATH: process.env.PATH, OPENROUTER_API_KEY: "fixture-key" },
+ });
+ const session = await driver.openSession({
+ runId: "run-post-tool-final-selection",
+ normalizedSessionId: "post-tool-final-selection",
+ workingDirectory: workspace,
+ });
+ await session.startTurn({ message: { role: "user", text: "final-after-tool-commentary" } });
+ const events = [];
+ for await (const event of session.events()) events.push(event);
+ const finalMessages = events.filter(
+ (event) => event.eventType === "item.completed"
+ && event.payload.kind === "agentMessage"
+ && event.payload.channel === "final",
+ );
+ expect(finalMessages).toHaveLength(1);
+ expect(finalMessages[0]?.payload.text)
+ .toBe("This is the complete substantive answer emitted after the accepted completion tool call.");
+ await session.close({ reason: "test" });
+ });
+
+ it("rejects malformed and oversized SSE frames", async () => {
+ const stream = (value: string) => new ReadableStream<Uint8Array>({
+ start(controller) {
+ controller.enqueue(new TextEncoder().encode(value));
+ controller.close();
+ },
+ });
+ const consume = async (value: string) => {
+ for await (const _event of openCodeServerDriverInternals.parseSse(stream(value))) {
+ // Consume the complete stream so parse failures are observed.
+ }
+ };
+ await expect(consume("data: {bad json}\n\n")).rejects.toThrow();
+ await expect(consume(`data: ${"x".repeat(1_048_577)}`)).rejects.toThrow("payload limit");
+ });
+
+ it("restarts OpenCode when session startup fails transiently", async () => {
+ await chmod(fixture, 0o755);
+ const root = await mkdtemp(join(tmpdir(), "paperclip-opencode-driver-"));
+ const workspace = await mkdtemp(join(tmpdir(), "paperclip-opencode-workspace-"));
+ roots.push(root, workspace);
+ let failSessionCreate = true;
+ const spawns: number[] = [];
+ const driver = new OpenCodeServerDriver({
+ model: "openrouter/deepseek/deepseek-v4-flash-0731",
+ runtimeDirectory: root,
+ command: fixture,
+ environment: { PATH: process.env.PATH, OPENROUTER_API_KEY: "fixture-key" },
+ fetch: async (input, init) => {
+ if (failSessionCreate && String(input).endsWith("/session") && init?.method === "POST") {
+ failSessionCreate = false;
+ throw new Error("transient session initialization failure");
+ }
+ return fetch(input, init);
+ },
+ onSpawn: async ({ pid }) => { spawns.push(pid); },
+ });
+ const session = await driver.openSession({ runId: "run-retry", normalizedSessionId: "retry", workingDirectory: workspace });
+ expect(session.ids().providerSessionId).toBe("ses_fake_1");
+ expect(spawns).toHaveLength(2);
+ await session.close({ reason: "test" });
+ });
+
+ it("reports startup exit details with stderr captured after spawn and redacted", async () => {
+ await chmod(fixture, 0o755);
+ const root = await mkdtemp(join(tmpdir(), "paperclip-opencode-driver-"));
+ const workspace = await mkdtemp(join(tmpdir(), "paperclip-opencode-workspace-"));
+ roots.push(root, workspace);
+ const exitingFixture = join(root, "exit-before-health.mjs");
+ await writeFile(
+ exitingFixture,
+ "#!/usr/bin/env node\nprocess.stderr.write(`credential=${process.env.OPENROUTER_API_KEY}\\nauthorization=super-secret-opencode-token\\n`);\nprocess.exit(17);\n",
+ { mode: 0o755 },
+ );
+ const driver = new OpenCodeServerDriver({
+ model: "openrouter/deepseek/deepseek-v4-flash-0731",
+ runtimeDirectory: root,
+ command: exitingFixture,
+ environment: {
+ PATH: process.env.PATH,
+ OPENROUTER_API_KEY: "fixture-key",
+ },
+ });
+ const error = await driver.openSession({
+ runId: "run-startup-exit",
+ normalizedSessionId: "startup-exit",
+ workingDirectory: workspace,
+ }).then(
+ () => "provider unexpectedly started",
+ (cause: unknown) => String(cause),
+ );
+ expect(error).toContain("provider_process_exited");
+ expect(error).toContain("provider=opencode");
+ expect(error).toContain("stage=health");
+ expect(error).toContain("[REDACTED]");
+ expect(error).not.toContain("fixture-key");
+ expect(error).not.toContain("super-secret-opencode-token");
+ });
+});
diff --git a/packages/paperclip-runner/src/drivers/opencode/opencode-server-driver.ts b/packages/paperclip-runner/src/drivers/opencode/opencode-server-driver.ts
new file mode 100644
index 0000000000..c23dfc13c1
--- /dev/null
+++ b/packages/paperclip-runner/src/drivers/opencode/opencode-server-driver.ts
@@ -0,0 +1,1855 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { createServer } from "node:net";
+import { dirname, join, resolve } from "node:path";
+
+import {
+ CODEX_SKILLLESS_BASE_INSTRUCTIONS,
+ createCodexTaskEnvelope,
+ type CodexTaskEnvelope,
+} from "../../contracts/codex.js";
+import {
+ PRP_BLOCK_TOOL_NAME,
+ PRP_COMPLETION_TOOL_NAME,
+} from "../../contracts/completion-result.js";
+import type {
+ HarnessDriver,
+ HarnessDriverConfigValidation,
+ HarnessDriverDescriptor,
+ HarnessSession,
+ HarnessSessionRecoveryResult,
+ HarnessTranscriptSnapshot,
+ OpenHarnessSessionInput,
+ PersistedHarnessSession,
+ HarnessRuntimeRequest,
+ HarnessRuntimeRequestHandoff,
+ HarnessRuntimeRequestResolution,
+ PaperclipQuestion,
+ PaperclipQuestionResponse,
+ PaperclipQuestionSet,
+} from "../../contracts/harness-driver.js";
+import {
+ PAPERCLIP_QUESTION_SET_SCHEMA,
+ PAPERCLIP_RUNTIME_REQUEST_SCHEMA_V2,
+ harnessRuntimeInputExpiredOutcome,
+ harnessRuntimeRequestOutcome,
+ parseHarnessRuntimeRequestResolution,
+ parsePaperclipQuestionSet,
+} from "../../contracts/harness-driver.js";
+import type { NativeSessionCapabilities, NativeUserMessage } from "../../contracts/types.js";
+import type { NativeRuntimeContextSnapshot } from "../../contracts/runtime-context.js";
+import {
+ createProviderTraceFileSink,
+ type ProviderTraceFileSink,
+} from "../../contracts/provider-trace-file-sink.js";
+import type { PrpEvent, PrpStructuredRunResult } from "../../protocol/replay-contract.js";
+import { validatePrpStructuredRunResult } from "../../protocol/replay-contract.js";
+import { paperclipWorkspaceFileReferencesFromText } from "../../live/workspace-file-reference.js";
+import {
+ canonicalOpenCodeDisplayToolName,
+ canonicalProviderEventsFromOpenCodePart,
+ providerFamilyCapabilities,
+} from "../../provider-events.js";
+import { canonicalOpenCodeMcpToolName, startOpenCodeMcpBridge, type OpenCodeMcpBridge } from "./mcp-bridge.js";
+import { nativeMcpLaunchBinding } from "../native-mcp.js";
+import { materializeNativeRuntimeSkills } from "../runtime-context-materializer.js";
+
+export const OPENCODE_SERVER_DRIVER_KIND = "opencode_server" as const;
+export const QUALIFIED_OPENCODE_VERSION = "1.18.17" as const;
+export const QUALIFIED_OPENCODE_MODEL = "openrouter/deepseek/deepseek-v4-flash-0731" as const;
+
+type DynamicToolHandler = (call: {
+ tool: string;
+ callId: string;
+ threadId: string;
+ turnId: string;
+ arguments: unknown;
+}) => Promise<unknown>;
+
+export interface OpenCodeServerDriverOptions {
+ model: string;
+ permissionMode?: "allow" | "ask" | "deny";
+ taskEnvelope?: CodexTaskEnvelope;
+ runnerInstanceId?: string;
+ command?: string;
+ runtimeDirectory: string;
+ systemInstructions?: string;
+ runtimeContext?: NativeRuntimeContextSnapshot | null;
+ environment?: NodeJS.ProcessEnv;
+ dynamicTools?: readonly Readonly<Record<string, unknown>>[];
+ dynamicToolHandler?: DynamicToolHandler;
+ onSpawn?: (meta: { pid: number; processGroupId: number | null; startedAt: string }) => Promise<void>;
+ /** Keep false when an outer supervisor already owns the process group. */
+ isolateProcessGroup?: boolean;
+ onDiagnostic?: (message: string) => void;
+ fetch?: typeof globalThis.fetch;
+ now?: () => Date;
+}
+
+interface OpenCodeRuntime {
+ baseUrl: string;
+ authHeader: string;
+ version: string;
+ permissionMode: "allow" | "ask" | "deny";
+ process: ChildProcess;
+ bridge: OpenCodeMcpBridge;
+ trace: ProviderTraceFileSink | null;
+ sensitiveValues: readonly string[];
+ close(input?: { finalizeTrace?: boolean; reason?: string | null }): Promise<void>;
+}
+
+const CAPABILITIES: NativeSessionCapabilities = {
+ resume: true,
+ typedEvents: true,
+ typedEventFamilies: providerFamilyCapabilities({
+ tool_execution: "available",
+ research: "available",
+ delegation: "available",
+ context: "available",
+ artifact: "policy_disabled",
+ provider_notice: "available",
+ }),
+ steering: false,
+ interruption: true,
+ structuredResult: true,
+ read: true,
+ reconciliation: true,
+ usage: true,
+ dynamicTools: true,
+ runtimeRequestResolution: true,
+ runtimeRequestHandoff: true,
+ goals: false,
+ threadLineage: false,
+ unsupported: ["steering", "goals", "threadLineage"],
+};
+
+export class OpenCodeServerDriver implements HarnessDriver {
+ readonly #options: OpenCodeServerDriverOptions;
+
+ constructor(options: OpenCodeServerDriverOptions) {
+ this.#options = options;
+ }
+
+ async descriptor(): Promise<HarnessDriverDescriptor> {
+ return {
+ kind: OPENCODE_SERVER_DRIVER_KIND,
+ displayName: "OpenCode server",
+ version: QUALIFIED_OPENCODE_VERSION,
+ protocolVersion: "http+sse/v1",
+ runtimeContextCapabilities: { instructions: "native", skills: "native", mcp: "native" },
+ capabilities: structuredClone(CAPABILITIES),
+ };
+ }
+
+ async validateConfig(config: unknown): Promise<HarnessDriverConfigValidation> {
+ const candidate = isRecord(config) ? config : {};
+ const issues = [];
+ const model = typeof candidate.model === "string" ? candidate.model.trim() : "";
+ if (!validModel(model)) issues.push({ path: "model", code: "invalid_model", message: "OpenCode model must use provider/model form." });
+ const command = typeof candidate.command === "string" ? candidate.command.trim() : "opencode";
+ if (!command) issues.push({ path: "command", code: "invalid_command", message: "OpenCode command cannot be empty." });
+ const permissionMode = candidate.permissionMode ?? "allow";
+ if (permissionMode !== "allow" && permissionMode !== "ask" && permissionMode !== "deny") {
+ issues.push({ path: "permissionMode", code: "invalid_permission_mode", message: "OpenCode permission mode must be allow, ask, or deny." });
+ }
+ return issues.length === 0
+ ? { ok: true, config: { model, command, permissionMode }, issues: [] }
+ : { ok: false, config: null, issues };
+ }
+
+ async openSession(input: OpenHarnessSessionInput): Promise<HarnessSession> {
+ return this.#open(input, null);
+ }
+
+ async recoverSession(snapshot: PersistedHarnessSession): Promise<HarnessSessionRecoveryResult> {
+ if (
+ snapshot.driverKind !== OPENCODE_SERVER_DRIVER_KIND
+ || !snapshot.runId
+ || !snapshot.normalizedSessionId
+ || !snapshot.driverSessionId
+ ) return { recovered: false, reason: "persisted OpenCode session identity is incomplete" };
+ try {
+ const session = await this.#open({
+ runId: snapshot.runId,
+ normalizedSessionId: snapshot.normalizedSessionId,
+ workingDirectory: await this.#readWorkspace(snapshot.normalizedSessionId),
+ }, snapshot);
+ return { recovered: true, session };
+ } catch (error) {
+ return { recovered: false, reason: redact(String(error), [this.#options.environment?.OPENROUTER_API_KEY]) };
+ }
+ }
+
+ async #readWorkspace(normalizedSessionId: string): Promise<string> {
+ const raw = await readFile(join(sessionRoot(this.#options.runtimeDirectory, normalizedSessionId), "workspace"), "utf8");
+ return raw.trim();
+ }
+
+ async #open(input: OpenHarnessSessionInput, snapshot: PersistedHarnessSession | null): Promise<HarnessSession> {
+ const cwd = validateWorkspace(input.workingDirectory);
+ const root = sessionRoot(this.#options.runtimeDirectory, input.normalizedSessionId);
+ await mkdir(root, { recursive: true, mode: 0o700 });
+ await writeFile(join(root, "workspace"), `${cwd}\n`, { mode: 0o600 });
+ const trace = await createProviderTraceFileSink({
+ path: this.#options.environment?.PAPERCLIP_PROVIDER_TRACE_PATH,
+ provider: "opencode",
+ channel: "typescript_opencode_native",
+ maxBytes: this.#options.environment?.PAPERCLIP_PROVIDER_TRACE_MAX_BYTES,
+ });
+ let lastError: unknown = null;
+ for (let attempt = 1; attempt <= 3; attempt += 1) {
+ let session: OpenCodeHarnessSession | null = null;
+ let runtime: OpenCodeRuntime | null = null;
+ try {
+ runtime = await startRuntime({
+ options: this.#options,
+ root,
+ cwd,
+ trace,
+ dispatch: (call) => {
+ if (session === null) throw new Error("OpenCode session is not ready for tool calls");
+ return session.dispatchTool(call);
+ },
+ });
+ const fetcher = this.#options.fetch ?? globalThis.fetch;
+ let providerSessionId = snapshot?.providerSessionId ?? snapshot?.driverSessionId ?? null;
+ if (providerSessionId !== null) {
+ const existing = await api(fetcher, runtime, `/session/${encodeURIComponent(providerSessionId)}`);
+ if (!isRecord(existing) || text(existing.id) !== providerSessionId) throw new Error("OpenCode resumed a different session");
+ } else {
+ const created = await api(fetcher, runtime, "/session", {
+ method: "POST",
+ body: JSON.stringify({ title: `Paperclip ${input.runId}` }),
+ });
+ providerSessionId = text(record(created).id);
+ if (!providerSessionId) throw new Error("OpenCode session creation omitted its id");
+ }
+ session = new OpenCodeHarnessSession({
+ runtime,
+ fetcher,
+ runId: input.runId,
+ normalizedSessionId: input.normalizedSessionId,
+ providerSessionId,
+ workingDirectory: cwd,
+ runnerInstanceId: this.#options.runnerInstanceId ?? `paperclip-opencode-${input.runId}`,
+ model: this.#options.model,
+ taskEnvelope: this.#options.taskEnvelope ?? createCodexTaskEnvelope({ objective: "Complete the supplied task." }),
+ systemInstructions: this.#options.systemInstructions ?? CODEX_SKILLLESS_BASE_INSTRUCTIONS,
+ dynamicToolHandler: this.#options.dynamicToolHandler,
+ snapshot,
+ now: this.#options.now ?? (() => new Date()),
+ });
+ session.startEventPump();
+ return session;
+ } catch (error) {
+ lastError = error;
+ await runtime?.close({ finalizeTrace: false });
+ if (attempt === 3 || !retryableOpenCodeStartupError(error)) {
+ await trace?.finish({ reason: "opencode_session_start_failed" });
+ throw error;
+ }
+ this.#options.onDiagnostic?.(`OpenCode session startup attempt ${attempt} failed; retrying.`);
+ await new Promise((resolveDelay) => setTimeout(resolveDelay, 100 * attempt));
+ }
+ }
+ throw lastError;
+ }
+}
+
+class OpenCodeHarnessSession implements HarnessSession {
+ readonly #runtime: OpenCodeRuntime;
+ readonly #fetch: typeof globalThis.fetch;
+ #runId: string;
+ readonly #normalizedSessionId: string;
+ readonly #providerSessionId: string;
+ readonly #workingDirectory: string;
+ readonly #runnerInstanceId: string;
+ readonly #model: string;
+ readonly #taskEnvelope: CodexTaskEnvelope;
+ readonly #systemInstructions: string;
+ readonly #dynamicToolHandler?: DynamicToolHandler;
+ readonly #now: () => Date;
+ readonly #events = new AsyncQueue<PrpEvent>();
+ readonly #transcript: PrpEvent[] = [];
+ readonly #terminalTurns = new Map<string, string>();
+ readonly #seenProviderEvents = new Set<string>();
+ readonly #messageRoles = new Map<string, string>();
+ readonly #pendingMessageParts = new Map<string, Array<Record<string, unknown>>>();
+ readonly #partText = new Map<string, string>();
+ readonly #completedTextPartIds = new Set<string>();
+ readonly #completedTextParts: Array<{
+ partId: string;
+ messageId: string | null;
+ text: string;
+ item: Record<string, unknown>;
+ observedSourceSeq: number;
+ }> = [];
+ readonly #messageUsageFingerprints = new Map<string, string>();
+ readonly #workspaceChangesByTurn = new Map<string, Record<string, unknown>>();
+ readonly #emittedFileReferences = new Set<string>();
+ readonly #pendingRuntimeRequests = new Map<string, {
+ request: HarnessRuntimeRequest;
+ nativeQuestions: Record<string, unknown>[];
+ submittedResponse?: PaperclipQuestionResponse;
+ submittedAction?: "accept" | "accept_for_session" | "decline" | "cancel";
+ settling?: boolean;
+ }>();
+ #activeTraceFrameId: number | null = null;
+ #activeTraceEmittedEventIds: string[] = [];
+ #sourceSequence: number;
+ #activeTurnId: string | null;
+ #result: PrpStructuredRunResult | null;
+ #resultFingerprint: string | null;
+ #resultCallId: string | null;
+ #resultTurnId: string | null;
+ #semanticResultTextBoundary: number | null = null;
+ #semanticResultProviderMessageId: string | null = null;
+ #lastNonTerminalToolSourceSeq = 0;
+ #usage: Record<string, unknown> | null = null;
+ #sendFullContext: boolean;
+ #closed = false;
+ #abort = new AbortController();
+
+ constructor(input: {
+ runtime: OpenCodeRuntime;
+ fetcher: typeof globalThis.fetch;
+ runId: string;
+ normalizedSessionId: string;
+ providerSessionId: string;
+ workingDirectory: string;
+ runnerInstanceId: string;
+ model: string;
+ taskEnvelope: CodexTaskEnvelope;
+ systemInstructions: string;
+ dynamicToolHandler?: DynamicToolHandler;
+ snapshot: PersistedHarnessSession | null;
+ now: () => Date;
+ }) {
+ this.#runtime = input.runtime;
+ this.#fetch = input.fetcher;
+ this.#runId = input.runId;
+ this.#sourceSequence = 0;
+ this.#normalizedSessionId = input.normalizedSessionId;
+ this.#providerSessionId = input.providerSessionId;
+ this.#workingDirectory = input.workingDirectory;
+ this.#runnerInstanceId = input.runnerInstanceId;
+ this.#model = input.model;
+ this.#taskEnvelope = input.taskEnvelope;
+ this.#systemInstructions = input.systemInstructions;
+ this.#dynamicToolHandler = input.dynamicToolHandler;
+ this.#now = input.now;
+ this.#sendFullContext = input.snapshot === null;
+ this.#sourceSequence = input.snapshot?.lastSourceSequence ?? 0;
+ this.#activeTurnId = input.snapshot?.activeTurnId ?? null;
+ const restored = input.snapshot?.semanticResult ?? null;
+ this.#result = restored?.result ?? null;
+ this.#resultFingerprint = restored?.fingerprint ?? null;
+ this.#resultCallId = restored?.callId ?? null;
+ this.#resultTurnId = restored?.turnId ?? null;
+ for (const terminal of input.snapshot?.terminalTurns ?? []) this.#terminalTurns.set(terminal.turnId, terminal.fingerprint);
+ if (this.#activeTurnId && this.#terminalTurns.has(this.#activeTurnId)) {
+ this.#activeTurnId = null;
+ }
+ this.#emit(input.snapshot ? "session.resumed" : "session.started", {
+ driverSessionId: input.providerSessionId,
+ providerSessionId: input.providerSessionId,
+ context: {
+ protocolVersion: "http+sse/v1",
+ opencodeVersion: input.runtime.version,
+ model: input.model,
+ modelProvider: input.model.split("/", 1)[0],
+ workingDirectory: input.workingDirectory,
+ environmentKeys: sanitizedEnvironmentKeys(),
+ permissionMode: input.runtime.permissionMode,
+ },
+ });
+ this.#emit("item.completed", {
+ kind: "model",
+ text: `${input.model} (OpenCode ${input.runtime.version})`,
+ model: { name: input.model, provider: input.model.split("/", 1)[0], opencodeVersion: input.runtime.version },
+ }, { itemId: `${input.providerSessionId}:model` });
+ }
+
+ ids() {
+ return { driverSessionId: this.#providerSessionId, providerSessionId: this.#providerSessionId, displayId: this.#providerSessionId };
+ }
+
+ attachRun(input: { runId: string }): void {
+ if (this.#activeTurnId !== null) throw new Error("opencode_run_attach_busy");
+ if (!input.runId) throw new Error("opencode_run_attach_invalid");
+ this.#runId = input.runId;
+ this.#result = null;
+ this.#resultFingerprint = null;
+ this.#resultCallId = null;
+ this.#resultTurnId = null;
+ this.#semanticResultTextBoundary = null;
+ this.#semanticResultProviderMessageId = null;
+ this.#lastNonTerminalToolSourceSeq = 0;
+ this.#completedTextPartIds.clear();
+ this.#completedTextParts.length = 0;
+ this.#terminalTurns.clear();
+ this.#sendFullContext = false;
+ this.#emit("run.attached", { runId: input.runId, sameSession: true });
+ }
+
+ events(): AsyncIterable<PrpEvent> { return this.#events; }
+
+ startEventPump(): void {
+ void this.#recoverPendingRuntimeRequests()
+ .catch((error) => this.#emit("harness.diagnostic", {
+ code: "opencode_runtime_request_recovery_failed",
+ message: redact(String(error), this.#runtime.sensitiveValues),
+ }))
+ .finally(() => this.#pumpEvents());
+ }
+
+ async startTurn(input: { message: NativeUserMessage }): Promise<{ turnId: string }> {
+ if (this.#activeTurnId !== null) throw new Error("OpenCode session already has an active turn");
+ const turnId = `turn-${randomBytes(12).toString("hex")}`;
+ this.#activeTurnId = turnId;
+ this.#emit("turn.submitted", { envelopeSchema: this.#taskEnvelope.schema, text: input.message.text });
+ this.#emit("turn.accepted", { turnId }, { turnId });
+ this.#emit("turn.started", { status: "inProgress" }, { turnId });
+ const [providerID, ...modelParts] = this.#model.split("/");
+ const modelID = modelParts.join("/");
+ // A resumed OpenCode provider session already retains the original system
+ // instructions and task envelope in its conversation. Repeating both on
+ // every Paperclip continuation can overflow smaller context windows and
+ // OpenCode then completes with `finish: unknown` and zero tokens. The
+ // native model envelope still carries the authoritative wake delta,
+ // interaction responses, completion contract, and current issue context.
+ const prompt = this.#sendFullContext
+ ? JSON.stringify({ task: this.#taskEnvelope, message: input.message.text })
+ : input.message.text;
+ await api(this.#fetch, this.#runtime, `/session/${encodeURIComponent(this.#providerSessionId)}/prompt_async`, {
+ method: "POST",
+ body: JSON.stringify({
+ // OpenCode 1.18's PromptPayload carries the provider and model at the
+ // top level. Older examples used a nested `model` object; 1.18
+ // silently ignores that shape and falls back to the configured model,
+ // which can turn `openrouter/deepseek/...` into a duplicated provider
+ // lookup. Keep Paperclip's persisted provider/model form, but adapt it
+ // at this HTTP boundary.
+ providerID,
+ modelID,
+ // This exact OpenCode version passed the native-question conformance
+ // suite. question.asked is adapted into PRP v2 and its reply/reject API
+ // remains private to this driver.
+ tools: { question: true },
+ ...(this.#sendFullContext ? { system: this.#systemInstructions } : {}),
+ parts: [{ type: "text", text: prompt }],
+ }),
+ });
+ this.#sendFullContext = false;
+ return { turnId };
+ }
+
+ async interrupt(input: { turnId?: string; reason?: string }): Promise<void> {
+ if (input.turnId && this.#activeTurnId && input.turnId !== this.#activeTurnId) throw new Error("stale OpenCode turn");
+ await api(this.#fetch, this.#runtime, `/session/${encodeURIComponent(this.#providerSessionId)}/abort`, { method: "POST" });
+ }
+
+ pendingRuntimeRequests(): HarnessRuntimeRequest[] {
+ return [...this.#pendingRuntimeRequests.values()].map(({ request }) => structuredClone(request));
+ }
+
+ async resolveRuntimeRequest(input: {
+ requestId: string;
+ turnId: string;
+ resolution: HarnessRuntimeRequestResolution;
+ }): Promise<void> {
+ const pending = this.#pendingRuntimeRequests.get(input.requestId);
+ if (!pending) throw new Error(`OpenCode request ${input.requestId} is no longer pending`);
+ if (pending.request.turnId !== input.turnId || this.#activeTurnId !== input.turnId) {
+ throw new Error(`OpenCode request ${input.requestId} belongs to a stale turn`);
+ }
+ const resolution = parseHarnessRuntimeRequestResolution(
+ pending.request.requestKind,
+ input.resolution,
+ pending.request.input,
+ );
+ if (pending.settling) throw new Error(`OpenCode request ${input.requestId} is already settling`);
+ pending.settling = true;
+ const submit = async (operation: Promise<unknown>) => {
+ try {
+ await operation;
+ } catch (error) {
+ if (this.#pendingRuntimeRequests.get(input.requestId) === pending) pending.settling = false;
+ throw error;
+ }
+ };
+ const workspace = `directory=${encodeURIComponent(this.#workingDirectory)}`;
+ if (pending.request.requestKind === "permission_approval") {
+ const action = resolution.action === "accept" || resolution.action === "accept_for_session"
+ ? resolution.action
+ : resolution.action === "decline" || resolution.action === "cancel"
+ ? resolution.action
+ : "decline";
+ pending.submittedAction = action;
+ await submit(api(
+ this.#fetch,
+ this.#runtime,
+ `/permission/${encodeURIComponent(input.requestId)}/reply?${workspace}`,
+ {
+ method: "POST",
+ body: JSON.stringify({
+ reply: action === "accept" ? "once" : action === "accept_for_session" ? "always" : "reject",
+ }),
+ },
+ ));
+ if (!this.#pendingRuntimeRequests.delete(input.requestId)) return;
+ this.#emit("runtime_request.resolved", harnessRuntimeRequestOutcome(pending.request, { action }), {
+ turnId: input.turnId,
+ itemId: pending.request.itemId,
+ });
+ return;
+ }
+ const base = `/question/${encodeURIComponent(input.requestId)}`;
+ if (resolution.action === "submit" && "response" in resolution) {
+ // OpenCode can broadcast question.replied before the reply HTTP request
+ // returns. Retain the canonical response before crossing that boundary
+ // so the racing terminal event carries the same durable answer record.
+ pending.submittedResponse = structuredClone(resolution.response);
+ await submit(api(this.#fetch, this.#runtime, `${base}/reply?${workspace}`, {
+ method: "POST",
+ body: JSON.stringify({ answers: openCodeAnswers(pending, resolution.response) }),
+ }));
+ } else if (resolution.action === "submit" && "answers" in resolution) {
+ await submit(api(this.#fetch, this.#runtime, `${base}/reply?${workspace}`, {
+ method: "POST",
+ body: JSON.stringify({ answers: pending.nativeQuestions.map((question, index) =>
+ resolution.answers[openCodeQuestionId(question, index)]?.answers ?? [],
+ ) }),
+ }));
+ } else {
+ await submit(api(this.#fetch, this.#runtime, `${base}/reject?${workspace}`, { method: "POST" }));
+ }
+ // question.replied/question.rejected can race the HTTP response on the SSE
+ // stream. The first terminal fact wins; the echo must not emit a duplicate.
+ if (!this.#pendingRuntimeRequests.delete(input.requestId)) return;
+ this.#emit("runtime_request.resolved", harnessRuntimeRequestOutcome(pending.request, {
+ action: resolution.action,
+ ...(resolution.action === "submit" && "response" in resolution
+ ? { response: resolution.response }
+ : {}),
+ }), { turnId: input.turnId, itemId: pending.request.itemId });
+ }
+
+ handoffRuntimeRequest(input: {
+ requestId: string;
+ turnId: string;
+ reason: "durable_handoff";
+ signal: AbortSignal;
+ }): HarnessRuntimeRequestHandoff {
+ if (input.signal.aborted) {
+ return { result: "already_settled", cleanup: Promise.resolve() };
+ }
+ const pending = this.#pendingRuntimeRequests.get(input.requestId);
+ if (
+ !pending
+ || pending.request.input === undefined
+ || pending.request.turnId !== input.turnId
+ || this.#activeTurnId !== input.turnId
+ || pending.settling
+ || pending.submittedResponse !== undefined
+ || pending.submittedAction !== undefined
+ ) return { result: "already_settled", cleanup: Promise.resolve() };
+ if (!this.#pendingRuntimeRequests.delete(input.requestId)) {
+ return { result: "already_settled", cleanup: Promise.resolve() };
+ }
+ this.#emit(
+ "runtime_request.expired",
+ harnessRuntimeInputExpiredOutcome(pending.request, input.reason),
+ { turnId: input.turnId, itemId: pending.request.itemId },
+ );
+ const workspace = `directory=${encodeURIComponent(this.#workingDirectory)}`;
+ const cleanup = Promise.allSettled([
+ api(
+ this.#fetch,
+ this.#runtime,
+ `/question/${encodeURIComponent(input.requestId)}/reject?${workspace}`,
+ { method: "POST" },
+ ),
+ api(
+ this.#fetch,
+ this.#runtime,
+ `/session/${encodeURIComponent(this.#providerSessionId)}/abort`,
+ { method: "POST" },
+ ),
+ ]).then(() => undefined);
+ return { result: "handed_off", cleanup };
+ }
+
+ async read(): Promise<Record<string, unknown>> {
+ const messages = await api(this.#fetch, this.#runtime, `/session/${encodeURIComponent(this.#providerSessionId)}/message`);
+ return { sessionId: this.#providerSessionId, messages };
+ }
+
+ async reconcile(): Promise<Record<string, unknown>> {
+ const status = await api(this.#fetch, this.#runtime, "/session/status");
+ return { sessionId: this.#providerSessionId, status: record(status)[this.#providerSessionId] ?? null };
+ }
+
+ async usage(): Promise<Record<string, unknown> | null> { return this.#usage === null ? null : structuredClone(this.#usage); }
+
+ async transcript(): Promise<HarnessTranscriptSnapshot> {
+ return {
+ schema: "paperclip-runner/harness-transcript/v1",
+ complete: true,
+ eventCount: this.#transcript.length,
+ events: structuredClone(this.#transcript),
+ omissionReason: null,
+ };
+ }
+
+ async snapshot(): Promise<PersistedHarnessSession> {
+ return {
+ driverKind: OPENCODE_SERVER_DRIVER_KIND,
+ driverSessionId: this.#providerSessionId,
+ providerSessionId: this.#providerSessionId,
+ runId: this.#runId,
+ normalizedSessionId: this.#normalizedSessionId,
+ activeTurnId: this.#activeTurnId,
+ semanticResult: this.#result && this.#resultFingerprint && this.#resultTurnId
+ ? { result: structuredClone(this.#result), fingerprint: this.#resultFingerprint, callId: this.#resultCallId, turnId: this.#resultTurnId }
+ : null,
+ terminalTurns: [...this.#terminalTurns].map(([turnId, fingerprint]) => ({ turnId, fingerprint })),
+ pendingRuntimeRequests: this.pendingRuntimeRequests(),
+ lastSourceSequence: this.#sourceSequence,
+ };
+ }
+
+ async close(): Promise<void> {
+ if (this.#closed) return;
+ this.#closed = true;
+ this.#abort.abort();
+ for (const { request } of this.#pendingRuntimeRequests.values()) {
+ this.#emit(
+ request.input === undefined ? "runtime_request.cancelled" : "runtime_request.expired",
+ request.input === undefined
+ ? harnessRuntimeRequestOutcome(request, { reason: "session_closed" })
+ : harnessRuntimeInputExpiredOutcome(request, "provider_process_lost"),
+ { turnId: request.turnId, itemId: request.itemId },
+ );
+ }
+ this.#pendingRuntimeRequests.clear();
+ this.#events.close();
+ await this.#runtime.close();
+ }
+
+ async dispatchTool(call: { tool: string; callId: string; arguments: unknown }): Promise<unknown> {
+ const tool = canonicalOpenCodeMcpToolName(call.tool);
+ const turnId = this.#activeTurnId;
+ if (turnId === null) throw new Error("OpenCode tool call is not bound to an active turn");
+ this.#emit("item.started", {
+ kind: "dynamicToolCall",
+ item: { type: "tool_call", id: call.callId, name: tool, arguments: call.arguments },
+ }, { turnId, itemId: call.callId });
+ if (tool === PRP_COMPLETION_TOOL_NAME || tool === PRP_BLOCK_TOOL_NAME) {
+ const validation = validatePrpStructuredRunResult(call.arguments);
+ if (!validation.ok) throw new Error("Invalid semantic result");
+ if (
+ (tool === PRP_BLOCK_TOOL_NAME && validation.result.reportedWorkDisposition !== "blocked")
+ || (tool === PRP_COMPLETION_TOOL_NAME && validation.result.reportedWorkDisposition === "blocked")
+ ) throw new Error("Semantic result disposition does not match the terminal tool");
+ if (validation.result.completionClaim.contractRevision !== this.#taskEnvelope.completionContract.revision) {
+ throw new Error("Semantic result completion contract revision does not match");
+ }
+ const fingerprint = canonicalJson(validation.result);
+ if (this.#resultFingerprint && this.#resultFingerprint !== fingerprint) throw new Error("A different semantic result was already committed");
+ if (!this.#resultFingerprint) {
+ this.#result = structuredClone(validation.result);
+ this.#resultFingerprint = fingerprint;
+ this.#resultCallId = call.callId;
+ this.#resultTurnId = turnId;
+ this.#semanticResultTextBoundary = this.#completedTextParts.length;
+ this.#emit("run.result.proposed", validation.result, { turnId, itemId: call.callId });
+ }
+ this.#emit("item.completed", {
+ kind: "dynamicToolCall",
+ item: { type: "tool_result", id: call.callId, tool_use_id: call.callId, result: "Semantic completion accepted." },
+ }, { turnId, itemId: call.callId });
+ return { accepted: true };
+ }
+ if (!this.#dynamicToolHandler) throw new Error("Unsupported Paperclip operation");
+ try {
+ const result = await this.#dynamicToolHandler({
+ tool,
+ callId: call.callId,
+ threadId: this.#providerSessionId,
+ turnId,
+ arguments: call.arguments,
+ });
+ this.#emit("item.completed", {
+ kind: "dynamicToolCall",
+ item: { type: "tool_result", id: call.callId, tool_use_id: call.callId, result },
+ }, { turnId, itemId: call.callId });
+ return result;
+ } catch (error) {
+ this.#emit("item.completed", {
+ kind: "dynamicToolCall",
+ item: { type: "tool_result", id: call.callId, tool_use_id: call.callId, error: redact(String(error)), is_error: true },
+ }, { turnId, itemId: call.callId });
+ throw error;
+ }
+ }
+
+ async #recoverPendingRuntimeRequests(): Promise<void> {
+ await this.#recoverPendingQuestions();
+ const value = await api(
+ this.#fetch,
+ this.#runtime,
+ `/permission?directory=${encodeURIComponent(this.#workingDirectory)}`,
+ );
+ const pending = Array.isArray(value)
+ ? value
+ : Array.isArray(record(value).permissions)
+ ? record(value).permissions as unknown[]
+ : [];
+ for (const entry of pending) this.#acceptPermission(record(entry), "permission.recovered");
+ }
+
+ async #recoverPendingQuestions(): Promise<void> {
+ const value = await api(
+ this.#fetch,
+ this.#runtime,
+ `/question?directory=${encodeURIComponent(this.#workingDirectory)}`,
+ );
+ const pending = Array.isArray(value) ? value : Array.isArray(record(value).questions) ? record(value).questions as unknown[] : [];
+ for (const entry of pending) {
+ const question = record(entry);
+ const sessionId = text(question.sessionID, text(question.sessionId));
+ if (sessionId && sessionId !== this.#providerSessionId) continue;
+ this.#acceptQuestion(question);
+ }
+ }
+
+ #acceptQuestion(properties: Record<string, unknown>): void {
+ const turnId = this.#activeTurnId;
+ if (!turnId) return;
+ const requestId = text(properties.id, text(properties.requestID, text(properties.requestId)));
+ const nativeQuestions = Array.isArray(properties.questions) ? properties.questions.map(record).slice(0, 64) : [];
+ if (!requestId || nativeQuestions.length === 0) {
+ this.#emit("harness.diagnostic", {
+ code: "runtime_input_rejected",
+ adapter: "opencode-server",
+ reason: "OpenCode emitted a question event without a request id or supported questions.",
+ }, { turnId, ...(requestId ? { itemId: requestId } : {}) });
+ return;
+ }
+ if (this.#pendingRuntimeRequests.has(requestId)) return;
+ let input: PaperclipQuestionSet;
+ try {
+ input = normalizeOpenCodeQuestionSet(nativeQuestions, properties);
+ } catch {
+ this.#emit("harness.diagnostic", {
+ code: "runtime_input_rejected",
+ adapter: "opencode-server",
+ reason: "OpenCode emitted a malformed or ambiguous question set.",
+ }, { turnId, itemId: requestId });
+ return;
+ }
+ const request: HarnessRuntimeRequest = {
+ requestId,
+ requestKind: "user_input",
+ method: "question.asked",
+ turnId,
+ itemId: requestId,
+ status: "pending",
+ prompt: "OpenCode requests user input.",
+ details: {},
+ input,
+ origin: { adapter: "opencode-server", provider: "opencode", method: "question.asked" },
+ };
+ this.#pendingRuntimeRequests.set(requestId, { request, nativeQuestions });
+ this.#emit("runtime_request.created", {
+ request: {
+ schema: PAPERCLIP_RUNTIME_REQUEST_SCHEMA_V2,
+ requestKind: "runtime",
+ requestId,
+ type: "input",
+ status: "pending",
+ prompt: request.prompt,
+ input,
+ origin: request.origin,
+ turnId,
+ itemId: request.itemId,
+ },
+ }, { turnId, itemId: request.itemId });
+ }
+
+ #acceptPermission(properties: Record<string, unknown>, method: string): void {
+ const turnId = this.#activeTurnId;
+ if (!turnId) return;
+ const permission = isRecord(properties.permission)
+ ? properties.permission
+ : isRecord(properties.request)
+ ? properties.request
+ : properties;
+ const requestId = text(
+ permission.id,
+ text(permission.requestID, text(permission.requestId, text(permission.permissionID))),
+ );
+ if (!requestId || this.#pendingRuntimeRequests.has(requestId)) return;
+ const title = text(permission.title, text(permission.permission, text(permission.tool, "requested operation")));
+ const request: HarnessRuntimeRequest = {
+ requestId,
+ requestKind: "permission_approval",
+ method,
+ turnId,
+ itemId: requestId,
+ status: "pending",
+ prompt: `OpenCode requests permission for ${title}.`.slice(0, 4000),
+ details: bounded(permission),
+ origin: { adapter: "opencode-server", provider: "opencode", method },
+ };
+ this.#pendingRuntimeRequests.set(requestId, { request, nativeQuestions: [] });
+ this.#emit("runtime_request.created", {
+ request: {
+ schema: PAPERCLIP_RUNTIME_REQUEST_SCHEMA_V2,
+ requestKind: "runtime",
+ requestId,
+ type: "permission",
+ status: "pending",
+ prompt: request.prompt,
+ actions: ["accept", "accept_for_session", "decline", "cancel"],
+ details: request.details,
+ origin: request.origin,
+ turnId,
+ itemId: request.itemId,
+ },
+ }, { turnId, itemId: request.itemId });
+ }
+
+ async #pumpEvents(): Promise<void> {
+ let attempts = 0;
+ while (!this.#closed && !this.#abort.signal.aborted) {
+ try {
+ const response = await this.#fetch(`${this.#runtime.baseUrl}/event`, {
+ headers: { Authorization: this.#runtime.authHeader, Accept: "text/event-stream" },
+ signal: this.#abort.signal,
+ });
+ if (!response.ok || !response.body) throw new Error(`OpenCode event stream returned HTTP ${response.status}`);
+ const outboundFrameId = this.#runtime.trace?.frame({
+ direction: "client_to_provider",
+ raw: "",
+ transport: "http_sse",
+ nativeMethod: "GET /event",
+ });
+ if (outboundFrameId) {
+ this.#runtime.trace?.interpretation({
+ frameId: outboundFrameId,
+ stage: "typescript_opencode_http_transport",
+ ruleId: "opencode.http.GET_event",
+ disposition: "operator_only",
+ reason: "Opened the OpenCode server-sent event stream",
+ });
+ }
+ for await (const frame of parseSseFrames(response.body)) {
+ if (this.#closed) return;
+ const frameId = this.#runtime.trace?.frame({
+ direction: "provider_to_client",
+ raw: frame.raw,
+ transport: "http_sse",
+ nativeMethod: "SSE /event",
+ }) ?? null;
+ let event: unknown;
+ try {
+ event = JSON.parse(frame.data);
+ if (frameId) {
+ this.#runtime.trace?.interpretation({
+ frameId,
+ stage: "typescript_opencode_sse_parse",
+ ruleId: "opencode.sse.json",
+ disposition: "mapped",
+ fieldMappings: [{
+ inputPath: "$raw.data",
+ outputPath: "$providerEvent",
+ action: "normalized",
+ reason: "Decoded the exact SSE data payload as an OpenCode event",
+ }],
+ reason: "OpenCode SSE frame parsed as JSON",
+ });
+ }
+ } catch (error) {
+ if (frameId) {
+ this.#runtime.trace?.interpretation({
+ frameId,
+ stage: "typescript_opencode_sse_parse",
+ ruleId: "opencode.sse.invalid_json",
+ disposition: "rejected",
+ reason: `OpenCode SSE data was not valid JSON: ${String(error).slice(0, 400)}`,
+ });
+ }
+ throw error;
+ }
+ this.#mapProviderEvent(event, frameId);
+ }
+ throw new Error("OpenCode event stream closed before the session became terminal");
+ } catch (error) {
+ if (this.#closed || this.#abort.signal.aborted) return;
+ attempts += 1;
+ if (attempts > 3) {
+ this.#emit("harness.diagnostic", { code: "opencode_sse_failed", message: redact(String(error), this.#runtime.sensitiveValues) });
+ this.#events.fail(error);
+ return;
+ }
+ await new Promise((resolve) => setTimeout(resolve, 50 * attempts));
+ }
+ }
+ }
+
+ #mapProviderEvent(value: unknown, traceFrameId: number | null = null): void {
+ this.#activeTraceFrameId = traceFrameId;
+ this.#activeTraceEmittedEventIds = [];
+ let rejected: unknown = null;
+ try {
+ this.#mapProviderEventValue(value);
+ } catch (error) {
+ rejected = error;
+ throw error;
+ } finally {
+ if (traceFrameId) {
+ const providerType = text(record(value).type, "unknown");
+ this.#runtime.trace?.interpretation({
+ frameId: traceFrameId,
+ stage: "typescript_opencode_driver_normalization",
+ ruleId: `opencode.normalize.${providerType.replace(/[^A-Za-z0-9_.-]/g, "_")}`,
+ disposition: rejected
+ ? "rejected"
+ : this.#activeTraceEmittedEventIds.length > 0
+ ? "mapped"
+ : "ignored",
+ emittedEventIds: [...this.#activeTraceEmittedEventIds],
+ fieldMappings: this.#activeTraceEmittedEventIds.length > 0
+ ? [{
+ inputPath: "properties",
+ outputPath: "prpEvent.payload",
+ action: "normalized",
+ reason: "Mapped OpenCode event fields into canonical PRP payloads",
+ }]
+ : [],
+ reason: rejected
+ ? `OpenCode event normalization failed: ${String(rejected).slice(0, 400)}`
+ : this.#activeTraceEmittedEventIds.length > 0
+ ? "OpenCode event emitted one or more canonical PRP events"
+ : "OpenCode event was observed but produced no canonical PRP event",
+ });
+ }
+ this.#activeTraceFrameId = null;
+ this.#activeTraceEmittedEventIds = [];
+ }
+ }
+
+ #mapProviderEventValue(value: unknown): void {
+ const event = record(value);
+ const properties = record(event.properties);
+ const type = text(event.type);
+ const eventId = text(event.id, canonicalJson(value));
+ if (this.#seenProviderEvents.has(eventId)) return;
+ this.#seenProviderEvents.add(eventId);
+ if (this.#seenProviderEvents.size > 10_000) this.#seenProviderEvents.delete(this.#seenProviderEvents.values().next().value!);
+ const sessionId = text(properties.sessionID, text(record(properties.info).sessionID));
+ if (sessionId && sessionId !== this.#providerSessionId) return;
+ const turnId = this.#activeTurnId;
+ if (type === "question.asked" && turnId) {
+ this.#acceptQuestion(properties);
+ return;
+ }
+ if ((type === "permission.updated" || type === "permission.asked" || type === "permission.v2.asked") && turnId) {
+ this.#acceptPermission(properties, type);
+ return;
+ }
+ if ((type === "permission.replied" || type === "permission.v2.replied") && turnId) {
+ const permission = isRecord(properties.permission)
+ ? properties.permission
+ : isRecord(properties.request)
+ ? properties.request
+ : properties;
+ const requestId = text(
+ permission.id,
+ text(permission.requestID, text(permission.requestId, text(permission.permissionID))),
+ );
+ const pending = this.#pendingRuntimeRequests.get(requestId);
+ if (!pending || pending.request.requestKind !== "permission_approval") return;
+ this.#pendingRuntimeRequests.delete(requestId);
+ const nativeReply = text(
+ properties.reply,
+ text(properties.response, text(permission.reply, text(permission.response))),
+ );
+ const action = pending.submittedAction
+ ?? (nativeReply === "always" || nativeReply === "always_allow"
+ ? "accept_for_session"
+ : nativeReply === "once" || nativeReply === "allow"
+ ? "accept"
+ : "decline");
+ this.#emit("runtime_request.resolved", harnessRuntimeRequestOutcome(pending.request, { action }), {
+ turnId,
+ itemId: pending.request.itemId,
+ });
+ return;
+ }
+ if ((type === "question.replied" || type === "question.rejected") && turnId) {
+ const requestId = text(properties.id, text(properties.requestID, text(properties.requestId)));
+ const pending = this.#pendingRuntimeRequests.get(requestId);
+ if (!pending) return;
+ this.#pendingRuntimeRequests.delete(requestId);
+ this.#emit(
+ type === "question.replied" ? "runtime_request.resolved" : "runtime_request.cancelled",
+ harnessRuntimeRequestOutcome(
+ pending.request,
+ type === "question.replied"
+ ? { action: "submit", response: pending.submittedResponse }
+ : { reason: "provider_rejected" },
+ ),
+ { turnId, itemId: pending.request.itemId },
+ );
+ return;
+ }
+ if (type === "message.part.updated" && turnId) {
+ const part = record(properties.part);
+ const messageId = text(part.messageID, text(part.messageId));
+ if (!messageId) return;
+ const role = this.#messageRoles.get(messageId);
+ if (role === "assistant") this.#emitAssistantPart(part, turnId);
+ else if (role === undefined) {
+ const pending = this.#pendingMessageParts.get(messageId) ?? [];
+ if (pending.length < 100) pending.push(part);
+ this.#pendingMessageParts.set(messageId, pending);
+ }
+ return;
+ }
+ if (type === "message.updated" && turnId) {
+ const info = record(properties.info);
+ const messageId = text(info.id, text(info.messageID, text(info.messageId)));
+ const role = text(info.role);
+ if (messageId && role) {
+ this.#messageRoles.set(messageId, role);
+ const pending = this.#pendingMessageParts.get(messageId) ?? [];
+ this.#pendingMessageParts.delete(messageId);
+ if (role === "assistant") for (const part of pending) this.#emitAssistantPart(part, turnId);
+ }
+ const tokens = record(info.tokens);
+ if (role === "assistant" && (Object.keys(tokens).length > 0 || typeof info.cost === "number")) {
+ this.#usage = bounded({
+ ...tokens,
+ costUsd: info.cost ?? null,
+ model: this.#model,
+ provider: this.#model.split("/", 1)[0],
+ driverVersion: this.#runtime.version,
+ });
+ const usageFingerprint = canonicalJson(this.#usage);
+ const hasMeaningfulUsage = hasPositiveNumber(tokens)
+ || (typeof info.cost === "number" && info.cost > 0);
+ if (
+ hasMeaningfulUsage
+ && this.#messageUsageFingerprints.get(messageId) !== usageFingerprint
+ ) {
+ this.#messageUsageFingerprints.set(messageId, usageFingerprint);
+ this.#emit("item.completed", { kind: "usage", usage: this.#usage }, { turnId, itemId: `${turnId}:usage` });
+ }
+ }
+ return;
+ }
+ if ((type === "session.idle" || (type === "session.status" && text(record(properties.status).type) === "idle")) && turnId) {
+ const fingerprint = canonicalJson({ status: "completed", semanticResult: this.#resultFingerprint });
+ this.#terminalTurns.set(turnId, fingerprint);
+ this.#emitSettledFinalAgentMessage(turnId);
+ const workspace = this.#workspaceChangesByTurn.get(turnId);
+ if (workspace !== undefined) this.#emit("workspace.diff.recorded", { ...workspace, complete: true }, { turnId, itemId: `${turnId}:workspace` });
+ this.#activeTurnId = null;
+ this.#emit("turn.completed", { status: "completed" }, { turnId });
+ this.#events.close();
+ return;
+ }
+ if (type === "session.error" && turnId) {
+ const providerError = record(properties.error);
+ const providerErrorData = record(providerError.data);
+ if (
+ text(providerError.name) === "MessageAbortedError"
+ && text(providerErrorData.message, text(providerError.message)) === "Aborted"
+ ) {
+ // OpenCode reports its normal /abort control path as session.error. That
+ // endpoint is also how Paperclip parks a provider turn after a durable
+ // governed interaction is created, so presenting it as a provider
+ // failure produces a false red error immediately above a healthy wait
+ // card. Preserve the provider fact as a cancelled terminal event; the
+ // native session loop independently commits the authoritative yielded
+ // result when this abort followed a governed wait.
+ this.#activeTurnId = null;
+ this.#emit("turn.cancelled", {
+ status: "cancelled",
+ error: bounded(properties.error ?? properties),
+ }, { turnId });
+ this.#terminalTurns.set(turnId, canonicalJson({ status: "cancelled" }));
+ this.#events.close();
+ return;
+ }
+ this.#emit("provider.notice.recorded", {
+ schema: "paperclip.provider.notice.v1",
+ noticeId: `${turnId}:session-error`,
+ severity: "error",
+ category: "session_error",
+ scope: "turn",
+ recoverable: false,
+ userActionable: true,
+ summary: redact(text(record(properties.error).message, "OpenCode session failed."), this.#runtime.sensitiveValues).slice(0, 4000),
+ }, { turnId, itemId: `${turnId}:session-error` });
+ this.#activeTurnId = null;
+ this.#emit("turn.failed", { status: "failed", error: bounded(properties.error ?? properties) }, { turnId });
+ this.#terminalTurns.set(turnId, canonicalJson({ status: "failed" }));
+ this.#events.close();
+ }
+ }
+
+ #emitAssistantPart(part: Record<string, unknown>, turnId: string): void {
+ const partId = text(part.id, `${turnId}:part`);
+ const partType = text(part.type, "unknown");
+ const messageId = text(part.messageID, text(part.messageId)) || null;
+ const canonicalToolName = canonicalOpenCodeMcpToolName(
+ canonicalOpenCodeDisplayToolName(
+ text(part.tool, text(part.name)),
+ text(part.callID, text(part.callId)),
+ ),
+ );
+ if (
+ ["tool", "tool-call", "tool_call"].includes(partType)
+ && [PRP_COMPLETION_TOOL_NAME, PRP_BLOCK_TOOL_NAME].includes(
+ canonicalToolName as typeof PRP_COMPLETION_TOOL_NAME,
+ )
+ && messageId
+ ) {
+ // OpenCode may report the terminal MCP call before it marks the text
+ // part from the same assistant message complete. Correlating by native
+ // message identity selects that response while excluding both earlier
+ // commentary messages and later acknowledgement-only messages.
+ this.#semanticResultProviderMessageId = messageId;
+ }
+ for (const canonical of canonicalProviderEventsFromOpenCodePart(part)) {
+ this.#emit(canonical.eventType, canonical.payload, { turnId, itemId: canonical.itemId });
+ }
+ if (
+ ["tool", "tool-call", "tool_call"].includes(partType)
+ && ![PRP_COMPLETION_TOOL_NAME, PRP_BLOCK_TOOL_NAME].includes(
+ canonicalToolName as typeof PRP_COMPLETION_TOOL_NAME,
+ )
+ ) {
+ this.#lastNonTerminalToolSourceSeq = this.#sourceSequence;
+ }
+ if (partType === "patch") {
+ const paths = Array.isArray(part.files) ? part.files : [];
+ const files = paths.slice(0, 2_000).flatMap((value): Record<string, unknown>[] => {
+ const path = text(value).replaceAll("\\", "/");
+ if (!path || path.startsWith("/") || path.split("/").includes("..")) return [];
+ return [{ path, operation: "modify", previousPath: null, additions: null, deletions: null, binary: false, diff: null }];
+ });
+ if (files.length > 0) {
+ const previous = this.#workspaceChangesByTurn.get(turnId);
+ const payload = {
+ schema: "paperclip.workspace.diff.v1",
+ changeSetId: `${turnId}:workspace`,
+ revision: Number(record(previous).revision ?? 0) + 1,
+ source: "harness_reported",
+ complete: false,
+ files,
+ totals: { files: files.length, additions: null, deletions: null },
+ patchArtifactRef: null,
+ };
+ this.#workspaceChangesByTurn.set(turnId, payload);
+ this.#emit("workspace.change.updated", payload, { turnId, itemId: `${turnId}:workspace` });
+ }
+ }
+ const content = text(part.text, text(part.output));
+ const previous = this.#partText.get(partId) ?? "";
+ this.#partText.set(partId, content);
+ if (partType === "text" && content.length > 0) {
+ for (const reference of paperclipWorkspaceFileReferencesFromText(
+ this.#workingDirectory,
+ content,
+ turnId,
+ )) {
+ if (this.#emittedFileReferences.has(reference.referenceId)) continue;
+ this.#emittedFileReferences.add(reference.referenceId);
+ this.#emit("workspace.file.referenced", { ...reference }, { turnId, itemId: reference.referenceId });
+ }
+ }
+ const delta = content.startsWith(previous) ? content.slice(previous.length) : content;
+ if (delta) {
+ this.#emit("item.delta", { kind: partType, text: delta, item: bounded(part) }, { turnId, itemId: partId });
+ }
+ const completedAt = record(part.time).end;
+ if (
+ partType === "text"
+ && content.trim().length > 0
+ && Number.isFinite(completedAt)
+ && !this.#completedTextPartIds.has(partId)
+ ) {
+ this.#completedTextPartIds.add(partId);
+ this.#completedTextParts.push({
+ partId,
+ messageId,
+ text: content,
+ item: bounded({ ...part, type: "agentMessage", phase: "final_answer", text: content }),
+ observedSourceSeq: this.#sourceSequence,
+ });
+ }
+ }
+
+ #emitSettledFinalAgentMessage(turnId: string): void {
+ // OpenCode labels every assistant text part as plain `text`; unlike Codex,
+ // it does not provide commentary/final-answer channels. A single native
+ // assistant message can therefore contain an opening progress note, many
+ // work tools, and the terminal MCP call. Do not promote that opening note
+ // into the settled response merely because it shares the terminal call's
+ // message id. Only text observed after the last non-terminal work tool can
+ // be a final response. When no such text exists, emit no final agentMessage
+ // and let the accepted semantic summary resolve the durable reply.
+ const afterLastWorkTool = (part: { observedSourceSeq: number }) =>
+ part.observedSourceSeq > this.#lastNonTerminalToolSourceSeq;
+ const eligibleText = this.#completedTextParts.filter(afterLastWorkTool);
+ // OpenCode can place terminal-tool troubleshooting text in the same
+ // native message as paperclip_finish, then emit the actual answer in a
+ // later message. It can also append a terse acknowledgement after a real
+ // answer. With no native commentary/final channel, prefer the most
+ // substantive eligible text and use structural correlation/order only as
+ // tie breakers. This does not cap, truncate, or regex-filter model prose.
+ const selected = eligibleText.reduce<(typeof eligibleText)[number] | null>((best, candidate) => {
+ if (best === null) return candidate;
+ const candidateLength = candidate.text.trim().length;
+ const bestLength = best.text.trim().length;
+ if (candidateLength !== bestLength) return candidateLength > bestLength ? candidate : best;
+ const candidateCorrelated = candidate.messageId === this.#semanticResultProviderMessageId;
+ const bestCorrelated = best.messageId === this.#semanticResultProviderMessageId;
+ if (candidateCorrelated !== bestCorrelated) return candidateCorrelated ? candidate : best;
+ const candidateBeforeResult = this.#semanticResultTextBoundary !== null
+ && this.#completedTextParts.indexOf(candidate) < this.#semanticResultTextBoundary;
+ const bestBeforeResult = this.#semanticResultTextBoundary !== null
+ && this.#completedTextParts.indexOf(best) < this.#semanticResultTextBoundary;
+ if (candidateBeforeResult !== bestBeforeResult) return candidateBeforeResult ? candidate : best;
+ return candidate.observedSourceSeq >= best.observedSourceSeq ? candidate : best;
+ }, null);
+ if (!selected) return;
+ this.#emit("item.completed", {
+ kind: "agentMessage",
+ channel: "final",
+ providerPhase: "final_answer",
+ text: selected.text,
+ item: selected.item,
+ }, { turnId, itemId: selected.partId });
+ }
+
+ #emit(eventType: PrpEvent["eventType"], payload: Record<string, unknown>, refs: { turnId?: string; itemId?: string } = {}): void {
+ const sourceSeq = ++this.#sourceSequence;
+ const event: PrpEvent = {
+ schema: "paperclip.prp.event.v1",
+ sourceEventId: `${this.#runnerInstanceId}:${this.#runId}:${sourceSeq}`,
+ sourceSeq,
+ sourceInstanceId: this.#runnerInstanceId,
+ sourceKind: "runner",
+ runId: this.#runId,
+ normalizedSessionId: this.#normalizedSessionId,
+ ...(refs.turnId ? { turnId: refs.turnId } : {}),
+ ...(refs.itemId ? { itemId: refs.itemId } : {}),
+ eventType,
+ schemaVersion: 1,
+ priority: eventType === "run.result.proposed" ? 0 : 1,
+ emittedAt: this.#now().toISOString(),
+ payload,
+ };
+ if (this.#activeTraceFrameId !== null) {
+ this.#activeTraceEmittedEventIds.push(event.sourceEventId);
+ }
+ this.#transcript.push(structuredClone(event));
+ this.#events.push(event);
+ }
+}
+
+async function startRuntime(input: {
+ options: OpenCodeServerDriverOptions;
+ root: string;
+ cwd: string;
+ trace: ProviderTraceFileSink | null;
+ dispatch: (call: { tool: string; callId: string; arguments: unknown }) => Promise<unknown>;
+}): Promise<OpenCodeRuntime> {
+ const port = await reservePort();
+ const password = randomBytes(32).toString("base64url");
+ const username = "paperclip";
+ const authHeader = `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`;
+ const configHome = join(input.root, "config");
+ const dataHome = join(input.root, "data");
+ const cacheHome = join(input.root, "cache");
+ await Promise.all([
+ mkdir(join(configHome, "opencode"), { recursive: true, mode: 0o700 }),
+ mkdir(dataHome, { recursive: true, mode: 0o700 }),
+ mkdir(cacheHome, { recursive: true, mode: 0o700 }),
+ ]);
+ // HOME contains a read-only skill snapshot, whose destination must be fresh.
+ // Keep OpenCode's XDG data stable for provider-session recovery while giving
+ // every launch (including retries and recovery) a new isolated HOME.
+ const isolatedHome = await mkdtemp(join(input.root, "home-"));
+ await chmod(isolatedHome, 0o700);
+ try {
+ await materializeNativeRuntimeSkills(input.options.runtimeContext ?? null, join(isolatedHome, ".claude", "skills"));
+ } catch (error) {
+ await rm(isolatedHome, { recursive: true, force: true }).catch(() => undefined);
+ throw error;
+ }
+ const bridge = await startOpenCodeMcpBridge({
+ tools: input.options.dynamicTools,
+ handler: input.dispatch,
+ }).catch(async (error) => {
+ await rm(isolatedHome, { recursive: true, force: true }).catch(() => undefined);
+ throw error;
+ });
+ const assignedMcp = nativeMcpLaunchBinding(input.options.environment ?? process.env);
+ input.trace?.addSensitiveValues([
+ password,
+ authHeader,
+ bridge.secret,
+ assignedMcp?.token,
+ input.options.environment?.OPENROUTER_API_KEY,
+ ]);
+ const instructionRoot = input.options.runtimeContext?.instructions.bundle.rootPath;
+ const config = {
+ $schema: "https://opencode.ai/config.json",
+ model: input.options.model,
+ small_model: input.options.model,
+ share: "disabled",
+ // The configured entry is already composed exactly once into the session
+ // system prompt; siblings remain available through the read-only root.
+ instructions: [],
+ plugin: [],
+ tools: {
+ question: true,
+ },
+ permission: {
+ "*": input.options.permissionMode ?? "allow",
+ question: "allow",
+ "paperclip_*": "allow",
+ "mcp__paperclip__*": "allow",
+ external_directory: instructionRoot
+ ? { "*": "deny", [`${instructionRoot}/**`]: "allow" }
+ : "deny",
+ },
+ mcp: {
+ paperclip: {
+ type: "remote",
+ url: bridge.url,
+ enabled: true,
+ oauth: false,
+ headers: { Authorization: `Bearer ${bridge.secret}` },
+ timeout: 30_000,
+ },
+ ...(assignedMcp ? {
+ [assignedMcp.name]: {
+ type: "remote",
+ url: assignedMcp.url,
+ enabled: true,
+ oauth: false,
+ headers: { Authorization: `Bearer ${assignedMcp.token}` },
+ timeout: 30_000,
+ },
+ } : {}),
+ },
+ };
+ await writeFile(join(configHome, "opencode", "opencode.json"), `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+ const environment = sanitizedEnvironment(input.options.environment ?? process.env, {
+ HOME: isolatedHome,
+ XDG_CONFIG_HOME: configHome,
+ XDG_DATA_HOME: dataHome,
+ XDG_CACHE_HOME: cacheHome,
+ OPENCODE_DISABLE_PROJECT_CONFIG: "true",
+ OPENCODE_SERVER_USERNAME: username,
+ OPENCODE_SERVER_PASSWORD: password,
+ });
+ const isolateProcessGroup = input.options.isolateProcessGroup ?? true;
+ const child = spawn(input.options.command ?? "opencode", ["serve", "--hostname", "127.0.0.1", "--port", String(port)], {
+ cwd: input.cwd,
+ env: environment,
+ stdio: ["ignore", "ignore", "pipe"],
+ detached: globalThis.process.platform !== "win32" && isolateProcessGroup,
+ });
+ let diagnostics = "";
+ child.stderr?.on("data", (chunk) => {
+ const raw = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+ const redactedDiagnostic = redact(raw.toString("utf8"), [
+ password,
+ input.options.environment?.OPENROUTER_API_KEY,
+ ]);
+ diagnostics = `${diagnostics}${redactedDiagnostic}`.slice(-8_192);
+ const frameId = input.trace?.frame({
+ direction: "provider_stderr",
+ raw,
+ transport: "process_stderr",
+ nativeMethod: "opencode serve stderr",
+ });
+ if (frameId) {
+ input.trace?.interpretation({
+ frameId,
+ stage: "typescript_opencode_process_transport",
+ ruleId: "opencode.stderr",
+ disposition: "operator_only",
+ reason: "OpenCode stderr is retained only in the restricted trace sidecar",
+ });
+ }
+ input.options.onDiagnostic?.(redactedDiagnostic);
+ });
+ try {
+ await new Promise<void>((resolve, reject) => {
+ child.once("spawn", resolve);
+ child.once("error", reject);
+ });
+ if (child.pid) await input.options.onSpawn?.({
+ pid: child.pid,
+ processGroupId: globalThis.process.platform === "win32" || !isolateProcessGroup ? null : child.pid,
+ startedAt: new Date().toISOString(),
+ });
+ const baseUrl = `http://127.0.0.1:${port}`;
+ const health = await waitForHealth(
+ baseUrl,
+ authHeader,
+ input.options.fetch ?? globalThis.fetch,
+ child,
+ () => diagnostics,
+ input.trace,
+ );
+ const version = text(record(health).version);
+ if (!/^\d+\.\d+\.\d+$/.test(version)) throw new Error("OpenCode health response omitted a semantic version");
+ const qualifiedComparison = compareVersion(version, QUALIFIED_OPENCODE_VERSION);
+ if (qualifiedComparison !== 0) {
+ throw new Error(
+ `OpenCode ${version} is not the question-conformance-qualified ${QUALIFIED_OPENCODE_VERSION}`,
+ );
+ }
+ return {
+ baseUrl,
+ authHeader,
+ version,
+ permissionMode: input.options.permissionMode ?? "allow",
+ process: child,
+ bridge,
+ trace: input.trace,
+ sensitiveValues: [password, input.options.environment?.OPENROUTER_API_KEY].filter((value): value is string => Boolean(value)),
+ close: async (closeInput = {}) => {
+ await bridge.close().catch(() => {});
+ if (child.exitCode === null && child.signalCode === null && child.pid) {
+ try {
+ if (globalThis.process.platform === "win32" || !isolateProcessGroup) child.kill("SIGTERM");
+ else globalThis.process.kill(-child.pid, "SIGTERM");
+ } catch { child.kill("SIGTERM"); }
+ }
+ await waitForExit(child, 2_000);
+ if (child.exitCode === null && child.signalCode === null && child.pid) {
+ try {
+ if (globalThis.process.platform === "win32" || !isolateProcessGroup) child.kill("SIGKILL");
+ else globalThis.process.kill(-child.pid, "SIGKILL");
+ } catch { child.kill("SIGKILL"); }
+ }
+ await rm(join(configHome, "opencode", "opencode.json"), { force: true }).catch(() => undefined);
+ await rm(isolatedHome, { recursive: true, force: true }).catch(() => undefined);
+ if (closeInput.finalizeTrace !== false) {
+ await input.trace?.finish({ reason: closeInput.reason ?? null });
+ }
+ },
+ };
+ } catch (error) {
+ await bridge.close().catch(() => {});
+ child.kill("SIGKILL");
+ await rm(join(configHome, "opencode", "opencode.json"), { force: true }).catch(() => undefined);
+ await rm(isolatedHome, { recursive: true, force: true }).catch(() => undefined);
+ throw error;
+ }
+}
+
+export function normalizeOpenCodeQuestionSet(
+ nativeQuestions: Record<string, unknown>[],
+ metadata: Record<string, unknown> = {},
+): PaperclipQuestionSet {
+ const questions = nativeQuestions.map((question, index): PaperclipQuestion => {
+ const options = (Array.isArray(question.options) ? question.options : []).map(record).slice(0, 128).map((option, optionIndex) => ({
+ id: text(option.id, `option-${optionIndex + 1}`).slice(0, 160),
+ label: text(option.label, text(option.value, `Option ${optionIndex + 1}`)).slice(0, 1_000),
+ ...(text(option.description) ? { description: text(option.description).slice(0, 4_000) } : {}),
+ }));
+ return {
+ id: openCodeQuestionId(question, index),
+ ...(text(question.header) ? { header: text(question.header).slice(0, 1_000) } : {}),
+ prompt: text(question.question, text(question.prompt, `Question ${index + 1}`)).slice(0, 4_000),
+ ...(text(question.description) ? { helpText: text(question.description).slice(0, 4_000) } : {}),
+ required: question.required === true,
+ answerMode: options.length === 0 ? "text" : question.multiple === true ? "multi_select" : "single_select",
+ ...(options.length > 0 ? { options } : {}),
+ ...(question.custom === true || question.allowCustom === true
+ ? { customAnswer: { enabled: true, label: "Other", placeholder: "Enter another answer" } }
+ : {}),
+ };
+ });
+ return parsePaperclipQuestionSet({
+ schema: PAPERCLIP_QUESTION_SET_SCHEMA,
+ title: text(metadata.title, "OpenCode needs your input").slice(0, 1_000),
+ ...(text(metadata.description) ? { description: text(metadata.description).slice(0, 4_000) } : {}),
+ submitLabel: text(metadata.submitLabel, "Submit answers").slice(0, 200),
+ questions,
+ });
+}
+
+function openCodeAnswers(
+ pending: { request: HarnessRuntimeRequest; nativeQuestions: Record<string, unknown>[] },
+ response: PaperclipQuestionResponse,
+): string[][] {
+ return pending.nativeQuestions.map((nativeQuestion, index) => {
+ const questionId = openCodeQuestionId(nativeQuestion, index);
+ const question = pending.request.input?.questions.find((candidate) => candidate.id === questionId);
+ const answer = response.answers[questionId];
+ if (!question || !answer) return [];
+ const values = (answer.selectedOptionIds ?? []).map((optionId) =>
+ question.options?.find((option) => option.id === optionId)?.label,
+ ).filter((value): value is string => typeof value === "string");
+ if (answer.text !== undefined) values.push(answer.text);
+ if (answer.customText !== undefined) values.push(answer.customText);
+ return values;
+ });
+}
+
+function openCodeQuestionId(question: Record<string, unknown>, index: number): string {
+ const nativeId = text(question.id).trim();
+ if (nativeId) return nativeId.slice(0, 160);
+ const header = text(question.header).trim().toLowerCase()
+ .replace(/[^a-z0-9._:-]+/g, "-")
+ .replace(/^-+|-+$/g, "")
+ .slice(0, 160);
+ return header || `question-${index + 1}`;
+}
+
+async function api(fetcher: typeof globalThis.fetch, runtime: OpenCodeRuntime, path: string, init: RequestInit = {}): Promise<unknown> {
+ const timeout = AbortSignal.timeout(20_000);
+ const signal = init.signal ? AbortSignal.any([init.signal, timeout]) : timeout;
+ const method = String(init.method ?? "GET").toUpperCase();
+ const requestRaw = typeof init.body === "string"
+ ? init.body
+ : init.body instanceof Uint8Array
+ ? init.body
+ : "";
+ const requestFrameId = runtime.trace?.frame({
+ direction: "client_to_provider",
+ raw: requestRaw,
+ transport: "http_json",
+ nativeMethod: `${method} ${path}`,
+ });
+ if (requestFrameId) {
+ runtime.trace?.interpretation({
+ frameId: requestFrameId,
+ stage: "typescript_opencode_http_transport",
+ ruleId: `opencode.http.${method}.${safeTraceRulePath(path)}`,
+ disposition: "operator_only",
+ reason: "Sent an exact HTTP request body to the OpenCode app server",
+ });
+ }
+ let response: Response;
+ try {
+ response = await fetcher(`${runtime.baseUrl}${path}`, {
+ ...init,
+ signal,
+ headers: { Authorization: runtime.authHeader, "Content-Type": "application/json", ...init.headers },
+ });
+ } catch (error) {
+ throw new Error(`OpenCode API ${path} request failed: ${redact(String(error), runtime.sensitiveValues)}`);
+ }
+ const responseRaw = await response.text();
+ const responseFrameId = runtime.trace?.frame({
+ direction: "provider_to_client",
+ raw: responseRaw,
+ transport: "http_json",
+ nativeMethod: `${method} ${path} ${response.status}`,
+ });
+ if (!response.ok) {
+ if (responseFrameId) {
+ runtime.trace?.interpretation({
+ frameId: responseFrameId,
+ stage: "typescript_opencode_http_parse",
+ ruleId: `opencode.http.error.${response.status}`,
+ disposition: "rejected",
+ reason: `OpenCode API returned HTTP ${response.status}`,
+ });
+ }
+ throw new Error(`OpenCode API ${path} returned HTTP ${response.status}: ${redact(responseRaw, runtime.sensitiveValues)}`);
+ }
+ if (response.status === 204 || !responseRaw) {
+ if (responseFrameId) {
+ runtime.trace?.interpretation({
+ frameId: responseFrameId,
+ stage: "typescript_opencode_http_parse",
+ ruleId: "opencode.http.empty_success",
+ disposition: "operator_only",
+ reason: "OpenCode API returned a successful empty response",
+ });
+ }
+ return null;
+ }
+ try {
+ const parsed = JSON.parse(responseRaw) as unknown;
+ if (responseFrameId) {
+ runtime.trace?.interpretation({
+ frameId: responseFrameId,
+ stage: "typescript_opencode_http_parse",
+ ruleId: "opencode.http.json_success",
+ disposition: "operator_only",
+ fieldMappings: [{
+ inputPath: "$raw",
+ outputPath: "$response",
+ action: "normalized",
+ reason: "Decoded the exact OpenCode HTTP response body as JSON",
+ }],
+ reason: "OpenCode HTTP response parsed as JSON",
+ });
+ }
+ return parsed;
+ } catch (error) {
+ if (responseFrameId) {
+ runtime.trace?.interpretation({
+ frameId: responseFrameId,
+ stage: "typescript_opencode_http_parse",
+ ruleId: "opencode.http.invalid_json",
+ disposition: "rejected",
+ reason: `OpenCode response was not valid JSON: ${String(error).slice(0, 400)}`,
+ });
+ }
+ throw error;
+ }
+}
+
+function retryableOpenCodeStartupError(error: unknown): boolean {
+ const message = String(error);
+ return message.includes("request failed")
+ || message.includes("did not become healthy")
+ || message.includes("exited during startup")
+ || message.includes("provider_initialize_timeout")
+ || message.includes("provider_process_exited")
+ || message.includes("HTTP 408")
+ || message.includes("HTTP 425")
+ || message.includes("HTTP 429")
+ || /HTTP 5\d\d/.test(message);
+}
+
+async function waitForHealth(
+ baseUrl: string,
+ authHeader: string,
+ fetcher: typeof globalThis.fetch,
+ process: ChildProcess,
+ diagnostics: () => string,
+ trace: ProviderTraceFileSink | null,
+): Promise<unknown> {
+ const deadline = Date.now() + 10_000;
+ while (Date.now() < deadline) {
+ if (process.exitCode !== null || process.signalCode !== null) {
+ const detail = redact(diagnostics());
+ throw new Error(
+ `provider_process_exited: provider=opencode stage=health exitCode=${process.exitCode ?? "null"} signal=${process.signalCode ?? "null"}${detail ? ` stderrTail=${detail}` : ""}`,
+ );
+ }
+ try {
+ const requestFrameId = trace?.frame({
+ direction: "client_to_provider",
+ raw: "",
+ transport: "http_json",
+ nativeMethod: "GET /global/health",
+ });
+ if (requestFrameId) {
+ trace?.interpretation({
+ frameId: requestFrameId,
+ stage: "typescript_opencode_http_transport",
+ ruleId: "opencode.http.GET_global_health",
+ disposition: "operator_only",
+ reason: "Probed the local OpenCode app-server health endpoint",
+ });
+ }
+ const response = await fetcher(`${baseUrl}/global/health`, {
+ headers: { Authorization: authHeader },
+ signal: AbortSignal.timeout(1_000),
+ });
+ const raw = await response.text();
+ const responseFrameId = trace?.frame({
+ direction: "provider_to_client",
+ raw,
+ transport: "http_json",
+ nativeMethod: `GET /global/health ${response.status}`,
+ });
+ if (response.ok) {
+ const parsed = JSON.parse(raw) as unknown;
+ if (responseFrameId) {
+ trace?.interpretation({
+ frameId: responseFrameId,
+ stage: "typescript_opencode_http_parse",
+ ruleId: "opencode.http.health_success",
+ disposition: "operator_only",
+ reason: "OpenCode health response parsed successfully",
+ });
+ }
+ return parsed;
+ }
+ } catch { /* server is still starting */ }
+ await new Promise((resolve) => setTimeout(resolve, 50));
+ }
+ const detail = redact(diagnostics());
+ throw new Error(
+ `provider_initialize_timeout: provider=opencode stage=health${detail ? ` stderrTail=${detail}` : ""}`,
+ );
+}
+
+async function reservePort(): Promise<number> {
+ const server = createServer();
+ await new Promise<void>((resolve, reject) => {
+ server.once("error", reject);
+ server.listen(0, "127.0.0.1", () => resolve());
+ });
+ const address = server.address();
+ if (!address || typeof address === "string") throw new Error("Unable to reserve OpenCode port");
+ const port = address.port;
+ await new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+ return port;
+}
+
+async function* parseSseFrames(
+ stream: ReadableStream<Uint8Array>,
+): AsyncIterable<{ raw: string; data: string }> {
+ const decoder = new TextDecoder();
+ let buffer = "";
+ for await (const chunk of stream as unknown as AsyncIterable<Uint8Array>) {
+ buffer += decoder.decode(chunk, { stream: true });
+ if (buffer.length > 1_048_576) throw new Error("OpenCode SSE event exceeded the retained payload limit");
+ let boundary: RegExpExecArray | null;
+ while ((boundary = /\r?\n\r?\n/.exec(buffer)) !== null) {
+ const rawFrame = buffer.slice(0, boundary.index);
+ const raw = buffer.slice(0, boundary.index + boundary[0].length);
+ const frame = rawFrame.replaceAll("\r", "");
+ buffer = buffer.slice(boundary.index + boundary[0].length);
+ const data = frame.split("\n").filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trimStart()).join("\n");
+ if (!data || data === "[DONE]") continue;
+ yield { raw, data };
+ }
+ }
+}
+
+async function* parseSse(stream: ReadableStream<Uint8Array>): AsyncIterable<unknown> {
+ for await (const frame of parseSseFrames(stream)) yield JSON.parse(frame.data);
+}
+
+function sanitizedEnvironment(source: NodeJS.ProcessEnv, overrides: Record<string, string>): NodeJS.ProcessEnv {
+ const allowed = ["PATH", "LANG", "LC_ALL", "LC_CTYPE", "TZ", "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "ALL_PROXY", "SSL_CERT_FILE", "SSL_CERT_DIR", "OPENROUTER_API_KEY"];
+ const result: NodeJS.ProcessEnv = {};
+ for (const key of allowed) if (source[key] !== undefined) result[key] = source[key];
+ return { ...result, ...overrides };
+}
+
+function sanitizedEnvironmentKeys(): string[] {
+ return ["PATH", "LANG", "LC_ALL", "LC_CTYPE", "TZ", "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "ALL_PROXY", "SSL_CERT_FILE", "SSL_CERT_DIR", "OPENROUTER_API_KEY"];
+}
+
+function sessionRoot(runtimeDirectory: string, normalizedSessionId: string): string {
+ const safe = normalizedSessionId.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 120);
+ if (!safe || safe === "." || safe === "..") throw new Error("Invalid normalized OpenCode session id");
+ return join(resolve(runtimeDirectory), safe);
+}
+
+function validateWorkspace(value: string): string {
+ const cwd = resolve(value);
+ if (!value.trim() || cwd === dirname(cwd)) throw new Error("OpenCode working directory must not be a filesystem root");
+ return cwd;
+}
+
+function validModel(value: string): boolean {
+ const slash = value.indexOf("/");
+ return slash > 0 && slash < value.length - 1;
+}
+
+function compareVersion(left: string, right: string): number {
+ const a = left.split(".").map(Number);
+ const b = right.split(".").map(Number);
+ for (let index = 0; index < 3; index += 1) {
+ if (a[index] !== b[index]) return (a[index] ?? 0) - (b[index] ?? 0);
+ }
+ return 0;
+}
+
+function bounded(value: unknown): Record<string, unknown> {
+ const serialized = JSON.stringify(value);
+ if (!serialized || serialized.length > 64 * 1024) return { omitted: true, reason: "payload_limit" };
+ const parsed = JSON.parse(serialized) as unknown;
+ return isRecord(parsed) ? parsed : { value: parsed };
+}
+
+function record(value: unknown): Record<string, unknown> { return isRecord(value) ? value : {}; }
+function isRecord(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }
+function text(value: unknown, fallback = ""): string { return typeof value === "string" ? value : fallback; }
+function hasPositiveNumber(value: unknown): boolean {
+ if (typeof value === "number") return Number.isFinite(value) && value > 0;
+ if (Array.isArray(value)) return value.some(hasPositiveNumber);
+ if (isRecord(value)) return Object.values(value).some(hasPositiveNumber);
+ return false;
+}
+function safeTraceRulePath(value: string): string {
+ return value
+ .replace(/\/[A-Za-z0-9_-]{12,}/g, "/:id")
+ .replace(/[^A-Za-z0-9_.:/-]/g, "_")
+ .replaceAll("/", "_")
+ .slice(0, 120);
+}
+function redact(value: string, sensitiveValues: readonly (string | undefined)[] = []): string {
+ let redacted = value;
+ for (const sensitive of sensitiveValues) {
+ if (sensitive && sensitive.length >= 4) redacted = redacted.split(sensitive).join("[REDACTED]");
+ }
+ return redacted.replace(/(OPENROUTER_API_KEY|authorization|password|token|secret)\s*[:=]\s*[^\s,}\]]+/gi, "$1=[REDACTED]").slice(0, 8_192);
+}
+function canonicalJson(value: unknown): string {
+ if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+ if (isRecord(value)) return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+ return JSON.stringify(value) ?? "undefined";
+}
+
+async function waitForExit(process: ChildProcess, timeoutMs: number): Promise<void> {
+ if (process.exitCode !== null || process.signalCode !== null) return;
+ await new Promise<void>((resolve) => {
+ const timer = setTimeout(resolve, timeoutMs);
+ timer.unref?.();
+ process.once("exit", () => { clearTimeout(timer); resolve(); });
+ });
+}
+
+export const openCodeServerDriverInternals = { parseSse };
+
+class AsyncQueue<T> implements AsyncIterable<T> {
+ #items: T[] = [];
+ #waiters: Array<{ resolve: (result: IteratorResult<T>) => void; reject: (error: unknown) => void }> = [];
+ #closed = false;
+ #error: unknown = null;
+ push(item: T): void {
+ if (this.#closed) return;
+ const waiter = this.#waiters.shift();
+ if (waiter) waiter.resolve({ done: false, value: item });
+ else this.#items.push(item);
+ }
+ close(): void {
+ if (this.#closed) return;
+ this.#closed = true;
+ for (const waiter of this.#waiters.splice(0)) waiter.resolve({ done: true, value: undefined });
+ }
+ fail(error: unknown): void {
+ if (this.#closed) return;
+ this.#closed = true;
+ this.#error = error;
+ for (const waiter of this.#waiters.splice(0)) waiter.reject(error);
+ }
+ [Symbol.asyncIterator](): AsyncIterator<T> {
+ return {
+ next: () => {
+ const item = this.#items.shift();
+ if (item !== undefined) return Promise.resolve({ done: false, value: item });
+ if (this.#error !== null) return Promise.reject(this.#error);
+ if (this.#closed) return Promise.resolve({ done: true, value: undefined });
+ return new Promise((resolve, reject) => this.#waiters.push({ resolve, reject }));
+ },
+ };
+ }
+}
diff --git a/packages/paperclip-runner/src/index.ts b/packages/paperclip-runner/src/index.ts
index c7c9d706e3..61de133458 100644
--- a/packages/paperclip-runner/src/index.ts
+++ b/packages/paperclip-runner/src/index.ts
@@ -11,10 +11,15 @@ export * from "./contracts/question-set.js";
export * from "./contracts/runtime-context.js";
export * from "./contracts/types.js";
export * from "./backends/harness-driver-backend.js";
+export { createOpenCodeNativeSessionBackend } from "./backends/opencode-native-backend.js";
export {
createNativeSessionBackend,
type NativeBackendFactoryOptions,
} from "./backends/native-backend-factory.js";
+export {
+ OpenCodeServerDriver,
+ type OpenCodeServerDriverOptions,
+} from "./drivers/opencode/opencode-server-driver.js";
export * from "./native-session-runtime.js";
export {
DurablePrpControlPlane,
diff --git a/packages/paperclip-runner/test/acpx-codex-package-contract.test.mjs b/packages/paperclip-runner/test/acpx-codex-package-contract.test.mjs
index 114185371f..9dbcf8f5b0 100644
--- a/packages/paperclip-runner/test/acpx-codex-package-contract.test.mjs
+++ b/packages/paperclip-runner/test/acpx-codex-package-contract.test.mjs
@@ -37,9 +37,11 @@ test("the runner pins only the Codex ACPX production dependencies", () => {
);
});
-test("the package exposes only the reviewed Codex ACPX sidecar binary", () => {
+test("the package exposes only the reviewed provider transport binaries", () => {
assert.deepEqual(runnerPackage.bin, {
"paperclip-runner-acpx-sidecar": "./dist/cli/acpx-runtime-sidecar.js",
+ "paperclip-runner-opencode-proxy":
+ "./dist/cli/opencode-app-server-proxy.js",
});
});
diff --git a/packages/paperclip-runner/test/fixtures/fake-opencode-server.mjs b/packages/paperclip-runner/test/fixtures/fake-opencode-server.mjs
new file mode 100644
index 0000000000..e54c662817
--- /dev/null
+++ b/packages/paperclip-runner/test/fixtures/fake-opencode-server.mjs
@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+import { createServer } from "node:http";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const args = process.argv.slice(2);
+if (process.env.OPENROUTER_API_KEY) process.stderr.write(`fixture credential=${process.env.OPENROUTER_API_KEY}\n`);
+const port = Number(args[args.indexOf("--port") + 1]);
+const username = process.env.OPENCODE_SERVER_USERNAME ?? "opencode";
+const password = process.env.OPENCODE_SERVER_PASSWORD ?? "";
+const expectedAuth = `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`;
+const session = { id: "ses_fake_1", title: "Paperclip fake" };
+const clients = new Set();
+let eventConnections = 0;
+const runtimeConfig = JSON.parse(await readFile(join(process.env.XDG_CONFIG_HOME, "opencode", "opencode.json"), "utf8"));
+const mcp = runtimeConfig.mcp?.paperclip;
+let mcpRequestId = 1;
+const mcpEvidence = { tools: [], calls: [] };
+
+function nativeQuestion() {
+ return {
+ id: "question-native-1",
+ sessionID: session.id,
+ questions: [
+ {
+ id: "environment",
+ header: "Environment",
+ question: "Where should we deploy?",
+ options: [
+ { label: "Staging", description: "Deploy to staging first." },
+ { label: "Production", description: "Deploy directly to production." }
+ ],
+ custom: true
+ },
+ {
+ id: "regions",
+ header: "Regions",
+ question: "Which regions?",
+ options: [{ label: "US" }, { label: "EU" }],
+ multiple: true
+ }
+ ]
+ };
+}
+
+function nativePermission(style) {
+ return style === "legacy"
+ ? {
+ id: "permission-native-1",
+ type: "tool",
+ pattern: "echo OK",
+ sessionID: session.id,
+ messageID: "message-permission",
+ callID: "call-permission",
+ title: "Run validation command",
+ metadata: {},
+ time: { created: Date.now() },
+ }
+ : {
+ id: "permission-native-1",
+ sessionID: session.id,
+ permission: "bash",
+ patterns: ["echo OK"],
+ always: ["echo *"],
+ metadata: {},
+ tool: { messageID: "message-permission", callID: "call-permission" },
+ };
+}
+
+let pendingQuestion = await readFile(join(process.env.XDG_DATA_HOME, "fake-pending-question.json"), "utf8")
+ .then((value) => JSON.parse(value))
+ .catch(() => null);
+let pendingPermission = await readFile(join(process.env.XDG_DATA_HOME, "fake-pending-permission.json"), "utf8")
+ .then((value) => JSON.parse(value))
+ .catch(() => null);
+let permissionStyle = "v2";
+
+await mkdir(process.env.XDG_DATA_HOME, { recursive: true });
+await writeFile(join(process.env.XDG_DATA_HOME, "fake-environment.json"), JSON.stringify({
+ keys: Object.keys(process.env).sort(),
+ home: process.env.HOME,
+ configHome: process.env.XDG_CONFIG_HOME,
+ projectConfigDisabled: process.env.OPENCODE_DISABLE_PROJECT_CONFIG,
+}));
+
+function json(response, status, value) {
+ response.statusCode = status;
+ response.setHeader("Content-Type", "application/json");
+ response.end(JSON.stringify(value));
+}
+
+function emit(value) {
+ const frame = `data: ${JSON.stringify(value)}\n\n`;
+ for (const response of clients) response.write(frame);
+}
+
+async function mcpRequest(method, params) {
+ const response = await fetch(mcp.url, {
+ method: "POST",
+ headers: { ...mcp.headers, "Content-Type": "application/json", Accept: "application/json, text/event-stream" },
+ body: JSON.stringify({ jsonrpc: "2.0", id: mcpRequestId++, method, ...(params ? { params } : {}) }),
+ });
+ return response.json();
+}
+
+async function callFirstPaperclipTool() {
+ if (!mcp?.url) return;
+ await mcpRequest("initialize", { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "fake-opencode", version: "1" } });
+ const listed = await mcpRequest("tools/list");
+ mcpEvidence.tools = (listed.result?.tools ?? []).map((entry) => entry.name);
+ const tool = listed.result?.tools?.find((entry) =>
+ !["paperclip_finish", "paperclip_block"].includes(entry.name)
+ && (entry.inputSchema?.required?.length ?? 0) === 0
+ );
+ if (tool) mcpEvidence.calls.push(await mcpRequest("tools/call", { name: `paperclip_${tool.name}`, arguments: {} }));
+ await writeFile(join(process.env.XDG_DATA_HOME, "fake-mcp-evidence.json"), JSON.stringify(mcpEvidence));
+}
+
+async function callTerminalTool(promptBody) {
+ const prompt = JSON.parse(promptBody.parts?.[0]?.text ?? "{}");
+ const blocked = String(prompt.message ?? "").includes("block-result");
+ const result = {
+ schema: "paperclip.run_result.v1",
+ reportedWorkDisposition: blocked ? "blocked" : "done",
+ summary: blocked ? "Fake provider is blocked." : "Fake provider completed the task.",
+ completionClaim: {
+ contractRevision: prompt.task?.completionContract?.revision ?? "codex-demo-v1",
+ objectiveSatisfied: !blocked,
+ criteria: (prompt.task?.completionContract?.criteria ?? []).map((criterion) => ({
+ criterionId: criterion.id,
+ status: blocked ? "unknown" : "satisfied",
+ evidenceRefs: [],
+ })),
+ remainingWork: blocked ? [{ description: "Waiting on a test dependency.", blocksCompletion: true }] : [],
+ },
+ evidence: [],
+ verification: [],
+ attentionRequests: blocked ? [{ kind: "blocker", summary: "Waiting on a test dependency." }] : [],
+ artifacts: [],
+ ...(blocked ? { blocker: {
+ reasonCode: "test_dependency",
+ owner: { kind: "external", name: "fixture" },
+ unblockAction: "Release the fixture dependency.",
+ scope: "current_track",
+ } } : {}),
+ };
+ return mcpRequest("tools/call", {
+ name: blocked ? "paperclip_block" : "paperclip_finish",
+ arguments: result,
+ });
+}
+
+const server = createServer(async (request, response) => {
+ if (request.headers.authorization !== expectedAuth) return json(response, 401, { error: "unauthorized" });
+ if (request.url === "/global/health") return json(response, 200, { healthy: true, version: "1.18.17" });
+ if (request.url === "/event") {
+ eventConnections += 1;
+ response.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-cache" });
+ response.write(`data: ${JSON.stringify({ type: "server.connected", properties: {} })}\n\n`);
+ if (eventConnections === 1) {
+ response.end();
+ return;
+ }
+ clients.add(response);
+ request.on("close", () => clients.delete(response));
+ return;
+ }
+ if (request.method === "POST" && request.url === "/session") return json(response, 200, session);
+ if (request.method === "GET" && request.url === `/session/${session.id}`) return json(response, 200, session);
+ if (request.method === "GET" && request.url === `/session/${session.id}/message`) return json(response, 200, []);
+ if (request.method === "GET" && request.url === "/session/status") return json(response, 200, { [session.id]: { type: "idle" } });
+ if (request.method === "GET" && request.url?.startsWith("/question?")) return json(response, 200, pendingQuestion ? [pendingQuestion] : []);
+ if (request.method === "GET" && request.url?.startsWith("/permission?")) return json(response, 200, pendingPermission ? [pendingPermission] : []);
+ if (request.method === "POST" && request.url?.startsWith("/question/question-native-1/reply?")) {
+ const chunks = [];
+ request.on("data", (chunk) => chunks.push(chunk));
+ request.on("end", async () => {
+ const body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+ await writeFile(join(process.env.XDG_DATA_HOME, "fake-question-reply.json"), JSON.stringify({ url: request.url, body }));
+ const repliedQuestion = pendingQuestion;
+ pendingQuestion = null;
+ emit({ type: "question.replied", id: "event-question-replied", properties: repliedQuestion });
+ setTimeout(() => {
+ json(response, 200, true);
+ emit({ type: "session.idle", id: "event-question-idle", properties: { sessionID: session.id } });
+ }, 10);
+ });
+ return;
+ }
+ if (request.method === "POST" && request.url?.startsWith("/question/question-native-1/reject?")) {
+ const rejectedQuestion = pendingQuestion;
+ pendingQuestion = null;
+ emit({ type: "question.rejected", id: "event-question-rejected", properties: rejectedQuestion });
+ setTimeout(() => {
+ json(response, 200, true);
+ emit({ type: "session.idle", id: "event-question-rejected-idle", properties: { sessionID: session.id } });
+ }, 10);
+ return;
+ }
+ if (request.method === "POST" && request.url?.startsWith("/permission/permission-native-1/reply?")) {
+ const chunks = [];
+ request.on("data", (chunk) => chunks.push(chunk));
+ request.on("end", async () => {
+ const body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+ await writeFile(join(process.env.XDG_DATA_HOME, "fake-permission-reply.json"), JSON.stringify({ url: request.url, body }));
+ pendingPermission = null;
+ emit({
+ type: permissionStyle === "legacy" ? "permission.replied" : "permission.v2.replied",
+ id: "event-permission-replied",
+ properties: permissionStyle === "legacy"
+ ? { sessionID: session.id, permissionID: "permission-native-1", response: body.reply }
+ : { sessionID: session.id, requestID: "permission-native-1", reply: body.reply },
+ });
+ setTimeout(() => {
+ json(response, 200, true);
+ emit({ type: "session.idle", id: "event-permission-idle", properties: { sessionID: session.id } });
+ }, 10);
+ });
+ return;
+ }
+ if (request.method === "POST" && request.url === `/session/${session.id}/abort`) return json(response, 200, true);
+ if (request.method === "POST" && request.url === `/session/${session.id}/prompt_async`) {
+ const chunks = [];
+ request.on("data", (chunk) => chunks.push(chunk));
+ request.on("end", () => {
+ const promptPayload = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+ if (promptPayload.providerID !== "openrouter" || promptPayload.modelID !== "deepseek/deepseek-v4-flash-0731" || "model" in promptPayload) {
+ return json(response, 400, { error: "OpenCode 1.18 prompt model fields must be top-level" });
+ }
+ json(response, 204, null);
+ setTimeout(async () => {
+ await callFirstPaperclipTool();
+ const parsedPrompt = JSON.parse(promptPayload.parts?.[0]?.text ?? "{}");
+ if (String(parsedPrompt.message ?? "").includes("native-question")) {
+ pendingQuestion = nativeQuestion();
+ emit({ type: "question.asked", id: "event-question-native-1", properties: pendingQuestion });
+ emit({ type: "question.asked", id: "event-question-native-1", properties: pendingQuestion });
+ return;
+ }
+ if (String(parsedPrompt.message ?? "").includes("native-permission")) {
+ permissionStyle = String(parsedPrompt.message ?? "").includes("legacy") ? "legacy" : "v2";
+ pendingPermission = nativePermission(permissionStyle);
+ emit({
+ type: permissionStyle === "legacy" ? "permission.updated" : "permission.v2.asked",
+ id: `event-permission-${permissionStyle}`,
+ properties: pendingPermission,
+ });
+ return;
+ }
+ if (String(parsedPrompt.message ?? "").includes("session-aborted")) {
+ emit({
+ type: "session.error",
+ id: "event-session-aborted",
+ properties: {
+ sessionID: session.id,
+ error: { name: "MessageAbortedError", data: { message: "Aborted" } },
+ },
+ });
+ return;
+ }
+ const textBeforeFinish = String(parsedPrompt.message ?? "").includes("text-before-finish");
+ const correlatedFinal = String(parsedPrompt.message ?? "").includes("correlated-final-message");
+ const finalAfterToolCommentary = String(parsedPrompt.message ?? "").includes("final-after-tool-commentary");
+ const commentaryOnlyBeforeWork = String(parsedPrompt.message ?? "").includes("commentary-only-before-work");
+ emit({ type: "message.updated", id: "event-user", properties: { sessionID: session.id, info: { id: "message-user", sessionID: session.id, role: "user" } } });
+ emit({ type: "message.part.updated", id: "event-user-part", properties: { sessionID: session.id, part: { id: "part-user", messageID: "message-user", type: "text", text: "submitted prompt must not become assistant text" } } });
+ emit({ type: "message.updated", id: "event-assistant", properties: { sessionID: session.id, info: { id: "message-assistant", sessionID: session.id, role: "assistant" } } });
+ emit({ type: "message.part.updated", id: "event-patch", properties: { sessionID: session.id, part: { id: "part-patch", messageID: "message-assistant", type: "patch", files: ["src/index.ts"] } } });
+ if (commentaryOnlyBeforeWork) {
+ emit({ type: "message.part.updated", id: "event-opening-commentary", properties: { sessionID: session.id, part: { id: "part-opening-commentary", messageID: "message-assistant", type: "text", text: "I will inspect the workspace first.", time: { start: 1, end: 2 } } } });
+ emit({ type: "message.part.updated", id: "event-work-tool", properties: { sessionID: session.id, part: { id: "part-work-tool", messageID: "message-assistant", type: "tool", tool: "bash", state: { status: "completed", input: { command: "pwd" }, output: "/workspace" } } } });
+ await callTerminalTool(promptPayload);
+ } else if (finalAfterToolCommentary) {
+ emit({ type: "message.part.updated", id: "event-tool-commentary", properties: { sessionID: session.id, part: { id: "part-tool-commentary", messageID: "message-assistant", type: "text", text: "The schema might need another value; I will try again.", time: { start: 1, end: 2 } } } });
+ await callTerminalTool(promptPayload);
+ emit({ type: "message.part.updated", id: "event-tool-part", properties: { sessionID: session.id, part: { id: "part-tool", messageID: "message-assistant", type: "tool", tool: "paperclip_paperclip_finish", state: { status: "completed", output: "accepted" } } } });
+ emit({ type: "message.updated", id: "event-post-tool-final-message", properties: { sessionID: session.id, info: { id: "message-post-tool-final", sessionID: session.id, role: "assistant" } } });
+ emit({ type: "message.part.updated", id: "event-post-tool-final", properties: { sessionID: session.id, part: { id: "part-post-tool-final", messageID: "message-post-tool-final", type: "text", text: "This is the complete substantive answer emitted after the accepted completion tool call.", time: { start: 3, end: 4 } } } });
+ } else if (correlatedFinal) {
+ emit({ type: "message.part.updated", id: "event-commentary", properties: { sessionID: session.id, part: { id: "part-commentary", messageID: "message-assistant", type: "text", text: "I will write the result now.", time: { start: 1, end: 2 } } } });
+ await callTerminalTool(promptPayload);
+ emit({ type: "message.updated", id: "event-final-message", properties: { sessionID: session.id, info: { id: "message-final", sessionID: session.id, role: "assistant" } } });
+ emit({ type: "message.part.updated", id: "event-finish-part", properties: { sessionID: session.id, part: { id: "part-finish", messageID: "message-final", type: "tool", tool: "paperclip_paperclip_finish", state: { status: "completed", output: "accepted" } } } });
+ emit({ type: "message.part.updated", id: "event-correlated-answer", properties: { sessionID: session.id, part: { id: "part-correlated-answer", messageID: "message-final", type: "text", text: "Correlated substantive final answer.", time: { start: 3, end: 4 } } } });
+ emit({ type: "message.part.updated", id: "event-duplicate-finish", properties: { sessionID: session.id, part: { id: "part-duplicate-finish", messageID: "message-final", type: "tool", tool: "unknown", callID: "functions.paperclip_paperclip_finish:24", state: { status: "error", error: "Tool execution aborted", metadata: { interrupted: true } } } } });
+ emit({ type: "message.updated", id: "event-trailing-message", properties: { sessionID: session.id, info: { id: "message-trailing", sessionID: session.id, role: "assistant" } } });
+ emit({ type: "message.part.updated", id: "event-trailing-ack", properties: { sessionID: session.id, part: { id: "part-trailing-ack", messageID: "message-trailing", type: "text", text: "Done.", time: { start: 5, end: 6 } } } });
+ } else if (textBeforeFinish) {
+ emit({ type: "message.part.updated", id: "event-answer", properties: { sessionID: session.id, part: { id: "part-answer", messageID: "message-assistant", type: "text", text: "Substantive answer before finish.", time: { start: 1, end: 2 } } } });
+ await callTerminalTool(promptPayload);
+ emit({ type: "message.part.updated", id: "event-ack", properties: { sessionID: session.id, part: { id: "part-ack", messageID: "message-assistant", type: "text", text: "Done.", time: { start: 3, end: 4 } } } });
+ } else {
+ await callTerminalTool(promptPayload);
+ emit({ type: "message.part.updated", id: "event-1", properties: { sessionID: session.id, part: { id: "part-1", messageID: "message-assistant", type: "text", text: "done [guide](guide.md)", time: { start: 1, end: 2 } } } });
+ emit({ type: "message.part.updated", id: "event-1", properties: { sessionID: session.id, part: { id: "part-1", messageID: "message-assistant", type: "text", text: "done" } } });
+ }
+ emit({ type: "message.updated", id: "event-2", properties: { info: { id: "message-assistant", sessionID: session.id, role: "assistant", tokens: { input: 3, output: 2 }, cost: 0.001 } } });
+ emit({ type: "session.idle", id: "event-3", properties: { sessionID: session.id } });
+ }, 100);
+ });
+ return;
+ }
+ json(response, 404, { error: "not found" });
+});
+
+server.listen(port, "127.0.0.1");
+for (const signal of ["SIGTERM", "SIGINT"]) process.on(signal, () => server.close(() => process.exit(0)));
diff --git a/server/src/__tests__/heartbeat-stale-queue-invalidation.test.ts b/server/src/__tests__/heartbeat-stale-queue-invalidation.test.ts
index 177678074f..7896cd4fd3 100644
--- a/server/src/__tests__/heartbeat-stale-queue-invalidation.test.ts
+++ b/server/src/__tests__/heartbeat-stale-queue-invalidation.test.ts
@@ -488,12 +488,17 @@ describeEmbeddedPostgres("heartbeat stale queued-run invalidation", () => {
await heartbeat.resumeQueuedRuns();
await waitForCondition(async () => {
- const run = await db
- .select({ status: heartbeatRuns.status })
- .from(heartbeatRuns)
- .where(eq(heartbeatRuns.id, runId))
- .then((rows) => rows[0] ?? null);
- return run?.status === "cancelled";
+ const [run, wakeup] = await Promise.all([
+ db.select({ status: heartbeatRuns.status })
+ .from(heartbeatRuns)
+ .where(eq(heartbeatRuns.id, runId))
+ .then((rows) => rows[0] ?? null),
+ db.select({ status: agentWakeupRequests.status })
+ .from(agentWakeupRequests)
+ .where(eq(agentWakeupRequests.id, wakeupRequestId))
+ .then((rows) => rows[0] ?? null),
+ ]);
+ return run?.status === "cancelled" && wakeup?.status === "skipped";
});
const [run, wakeup, issue] = await Promise.all([
@@ -580,12 +585,17 @@ describeEmbeddedPostgres("heartbeat stale queued-run invalidation", () => {
await heartbeat.resumeQueuedRuns();
await waitForCondition(async () => {
- const run = await db
- .select({ status: heartbeatRuns.status })
- .from(heartbeatRuns)
- .where(eq(heartbeatRuns.id, runId))
- .then((rows) => rows[0] ?? null);
- return run?.status === "cancelled";
+ const [run, wakeup] = await Promise.all([
+ db.select({ status: heartbeatRuns.status })
+ .from(heartbeatRuns)
+ .where(eq(heartbeatRuns.id, runId))
+ .then((rows) => rows[0] ?? null),
+ db.select({ status: agentWakeupRequests.status })
+ .from(agentWakeupRequests)
+ .where(eq(agentWakeupRequests.id, wakeupRequestId))
+ .then((rows) => rows[0] ?? null),
+ ]);
+ return run?.status === "cancelled" && wakeup?.status === "skipped";
});
const [run, wakeup, issue] = await Promise.all([