The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat(runner): define ACPX sidecar contract (#12386)
Dottae13856eb3722
diff --git a/packages/paperclip-runner/package.json b/packages/paperclip-runner/package.jsonindex 06f1c93342..d732e2e42f 100644--- a/packages/paperclip-runner/package.json+++ b/packages/paperclip-runner/package.json@@ -29,17 +29,17 @@"build:rust": "cargo build --manifest-path runner/Cargo.toml --locked --workspace --bins","build:binary": "cargo build --release --manifest-path runner/Cargo.toml --locked -p paperclip-runner-core --bin paperclip-runnerd && node scripts/stage-runner-binary.mjs","typecheck": "pnpm run typecheck:typescript && pnpm run typecheck:rust",- "typecheck:typescript": "node --check scripts/protocol-contract.mjs && node --check scripts/generate-protocol-manifest.mjs && node --check scripts/generate-protocol-schema-module.mjs && node --check scripts/generate-replay-goldens.mjs && node --check scripts/generate-semantic-action-catalog.mjs && pnpm run check:protocol-types && tsc -p tsconfig.json --noEmit",+ "typecheck:typescript": "node --check scripts/protocol-contract.mjs && node --check scripts/generate-protocol-manifest.mjs && node --check scripts/generate-protocol-schema-module.mjs && node --check scripts/generate-acpx-sidecar-contract.mjs && node --check scripts/generate-replay-goldens.mjs && node --check scripts/generate-semantic-action-catalog.mjs && pnpm run check:protocol-types && tsc -p tsconfig.json --noEmit","typecheck:rust": "cargo fmt --manifest-path runner/Cargo.toml --all -- --check && cargo check --manifest-path runner/Cargo.toml --locked --workspace","test": "pnpm run test:typescript && pnpm run test:rust",- "test:typescript": "node --test test/protocol-contract.test.mjs && vitest run",+ "test:typescript": "node --test test/protocol-contract.test.mjs test/acpx-sidecar-contract.test.mjs && vitest run","test:rust": "cargo test --release --manifest-path runner/Cargo.toml --locked --workspace","test:codex": "cargo test --manifest-path runner/Cargo.toml --locked -p paperclip-runner-core --test codex_provider","test:durable": "cargo test --manifest-path runner/Cargo.toml --locked -p paperclip-runner-core durable::","generate:protocol-manifest": "node scripts/generate-protocol-manifest.mjs","check:protocol-manifest": "node scripts/generate-protocol-manifest.mjs --check",- "generate:protocol-types": "node scripts/generate-protocol-schema-module.mjs",- "check:protocol-types": "node scripts/generate-protocol-schema-module.mjs --check",+ "generate:protocol-types": "node scripts/generate-protocol-schema-module.mjs && node scripts/generate-acpx-sidecar-contract.mjs",+ "check:protocol-types": "node scripts/generate-protocol-schema-module.mjs --check && node scripts/generate-acpx-sidecar-contract.mjs --check","generate:replay-goldens": "pnpm run build:typescript && node scripts/generate-replay-goldens.mjs","check:replay-goldens": "pnpm run build:typescript && node scripts/generate-replay-goldens.mjs --check","generate:semantic-action-catalog": "pnpm run build:typescript && node scripts/generate-semantic-action-catalog.mjs",diff --git a/packages/paperclip-runner/protocol/provider-schemas/acpx-sidecar.schema.json b/packages/paperclip-runner/protocol/provider-schemas/acpx-sidecar.schema.jsonnew file mode 100644index 0000000000..dbbbb53a12--- /dev/null+++ b/packages/paperclip-runner/protocol/provider-schemas/acpx-sidecar.schema.json@@ -0,0 +1,110 @@+{+ "$schema": "https://json-schema.org/draft/2020-12/schema",+ "$id": "https://paperclip.dev/schemas/acpx-sidecar/v2/message.schema.json",+ "title": "Paperclip ACPX sidecar message",+ "oneOf": [+ { "$ref": "#/$defs/request" },+ { "$ref": "#/$defs/response" },+ { "$ref": "#/$defs/event" }+ ],+ "$defs": {+ "protocolVersion": { "const": 2 },+ "command": {+ "enum": [+ "initialize",+ "session.open",+ "run.attach",+ "turn.start",+ "turn.cancel",+ "permission.resolve",+ "input.resolve",+ "tool.resolve",+ "session.read",+ "session.snapshot",+ "session.suspend",+ "session.close"+ ]+ },+ "eventType": {+ "enum": [+ "runtime.event",+ "runtime.permission_requested",+ "runtime.input_requested",+ "runtime.tool_called",+ "runtime.turn_terminal",+ "runtime.process",+ "runtime.diagnostic"+ ]+ },+ "request": {+ "type": "object",+ "required": ["protocolVersion", "id", "command", "params"],+ "properties": {+ "protocolVersion": { "$ref": "#/$defs/protocolVersion" },+ "id": { "type": "integer", "minimum": 1 },+ "command": { "$ref": "#/$defs/command" },+ "params": { "type": "object" }+ },+ "additionalProperties": false+ },+ "response": {+ "type": "object",+ "required": ["protocolVersion", "id", "ok"],+ "oneOf": [+ {+ "properties": {+ "ok": { "const": true },+ "result": { "type": "object" },+ "error": false+ },+ "required": ["result"]+ },+ {+ "properties": {+ "ok": { "const": false },+ "result": false,+ "error": { "type": "object" }+ },+ "required": ["error"]+ }+ ],+ "properties": {+ "protocolVersion": { "$ref": "#/$defs/protocolVersion" },+ "id": { "type": "integer", "minimum": 1 },+ "ok": { "type": "boolean" },+ "result": { "type": "object" },+ "error": {+ "type": "object",+ "required": ["code", "message", "retryable"],+ "properties": {+ "code": { "type": "string", "minLength": 1, "maxLength": 160 },+ "message": { "type": "string", "maxLength": 8192 },+ "retryable": { "type": "boolean" }+ },+ "additionalProperties": false+ }+ },+ "additionalProperties": false+ },+ "event": {+ "type": "object",+ "required": [+ "protocolVersion",+ "sequence",+ "eventType",+ "runId",+ "turnId",+ "payload"+ ],+ "properties": {+ "protocolVersion": { "$ref": "#/$defs/protocolVersion" },+ "sequence": { "type": "integer", "minimum": 1 },+ "eventType": { "$ref": "#/$defs/eventType" },+ "runId": { "type": ["string", "null"], "maxLength": 160 },+ "turnId": { "type": ["string", "null"], "maxLength": 160 },+ "payload": { "type": "object" }+ },+ "additionalProperties": false+ }+ }+}diff --git a/packages/paperclip-runner/runner/crates/runner-core/src/generated_acpx_sidecar_contract.rs b/packages/paperclip-runner/runner/crates/runner-core/src/generated_acpx_sidecar_contract.rsnew file mode 100644index 0000000000..46f8fc0b18--- /dev/null+++ b/packages/paperclip-runner/runner/crates/runner-core/src/generated_acpx_sidecar_contract.rs@@ -0,0 +1,56 @@+// Generated by scripts/generate-acpx-sidecar-contract.mjs. Do not edit.++pub const GENERATED_ACPX_SIDECAR_PROTOCOL_VERSION: u64 = 2;++#[derive(Clone, Copy, Debug, PartialEq, Eq)]+pub enum GeneratedAcpxSidecarCommand {+ Initialize,+ SessionOpen,+ RunAttach,+ TurnStart,+ TurnCancel,+ PermissionResolve,+ InputResolve,+ ToolResolve,+ SessionRead,+ SessionSnapshot,+ SessionSuspend,+ SessionClose,+}++impl GeneratedAcpxSidecarCommand {+ pub const fn as_str(self) -> &'static str {+ match self {+ Self::Initialize => "initialize",+ Self::SessionOpen => "session.open",+ Self::RunAttach => "run.attach",+ Self::TurnStart => "turn.start",+ Self::TurnCancel => "turn.cancel",+ Self::PermissionResolve => "permission.resolve",+ Self::InputResolve => "input.resolve",+ Self::ToolResolve => "tool.resolve",+ Self::SessionRead => "session.read",+ Self::SessionSnapshot => "session.snapshot",+ Self::SessionSuspend => "session.suspend",+ Self::SessionClose => "session.close",+ }+ }+}++#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Deserialize)]+pub enum GeneratedAcpxSidecarEventType {+ #[serde(rename = "runtime.event")]+ RuntimeEvent,+ #[serde(rename = "runtime.permission_requested")]+ RuntimePermissionRequested,+ #[serde(rename = "runtime.input_requested")]+ RuntimeInputRequested,+ #[serde(rename = "runtime.tool_called")]+ RuntimeToolCalled,+ #[serde(rename = "runtime.turn_terminal")]+ RuntimeTurnTerminal,+ #[serde(rename = "runtime.process")]+ RuntimeProcess,+ #[serde(rename = "runtime.diagnostic")]+ RuntimeDiagnostic,+}diff --git a/packages/paperclip-runner/scripts/acpx-sidecar-contract.mjs b/packages/paperclip-runner/scripts/acpx-sidecar-contract.mjsnew file mode 100644index 0000000000..34388c95f3--- /dev/null+++ b/packages/paperclip-runner/scripts/acpx-sidecar-contract.mjs@@ -0,0 +1,33 @@+const SCHEMA_ID_PATTERN =+ /^https:\/\/paperclip\.dev\/schemas\/acpx-sidecar\/v([1-9]\d*)\/message\.schema\.json$/;+const PROTOCOL_VERSION_REF = "#/$defs/protocolVersion";++export function readAcpxSidecarProtocolVersion(schema) {+ const schemaIdMatch = SCHEMA_ID_PATTERN.exec(schema?.$id ?? "");+ const protocolVersion = Number(schemaIdMatch?.[1]);+ if (!Number.isSafeInteger(protocolVersion)) {+ throw new Error(+ "ACPX sidecar schema $id must declare a positive safe-integer protocol version",+ );+ }++ if (schema?.$defs?.protocolVersion?.const !== protocolVersion) {+ throw new Error(+ "ACPX sidecar protocol version must match its authoritative schema $id",+ );+ }++ for (const family of ["request", "response", "event"]) {+ const versionSchema = schema?.$defs?.[family]?.properties?.protocolVersion;+ if (+ Object.keys(versionSchema ?? {}).length !== 1 ||+ versionSchema?.$ref !== PROTOCOL_VERSION_REF+ ) {+ throw new Error(+ `ACPX ${family} schema must use the shared protocol version`,+ );+ }+ }++ return protocolVersion;+}diff --git a/packages/paperclip-runner/scripts/generate-acpx-sidecar-contract.mjs b/packages/paperclip-runner/scripts/generate-acpx-sidecar-contract.mjsnew file mode 100644index 0000000000..9f3141df9c--- /dev/null+++ b/packages/paperclip-runner/scripts/generate-acpx-sidecar-contract.mjs@@ -0,0 +1,54 @@+import { readFile, writeFile } from "node:fs/promises";+import { dirname, resolve } from "node:path";+import { fileURLToPath } from "node:url";++import { readAcpxSidecarProtocolVersion } from "./acpx-sidecar-contract.mjs";++const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");+const schema = JSON.parse(+ await readFile(+ resolve(root, "protocol/provider-schemas/acpx-sidecar.schema.json"),+ "utf8",+ ),+);+const commands = schema.$defs.command.enum;+const events = schema.$defs.eventType.enum;+const protocolVersion = readAcpxSidecarProtocolVersion(schema);+const quote = (value) => JSON.stringify(value);+const rustVariant = (value) =>+ value+ .split(/[._-]/)+ .map((part) => part[0].toUpperCase() + part.slice(1))+ .join("");++const typescript = `// Generated by scripts/generate-acpx-sidecar-contract.mjs. Do not edit.\n\nexport const GENERATED_ACPX_SIDECAR_PROTOCOL_VERSION = ${protocolVersion} as const;\nexport const GENERATED_ACPX_SIDECAR_COMMANDS = [\n${commands.map((value) => ` ${quote(value)},`).join("\n")}\n] as const;\nexport type GeneratedAcpxSidecarCommand =\n (typeof GENERATED_ACPX_SIDECAR_COMMANDS)[number];\n\nexport const GENERATED_ACPX_SIDECAR_EVENT_TYPES = [\n${events.map((value) => ` ${quote(value)},`).join("\n")}\n] as const;\nexport type GeneratedAcpxSidecarEventType =\n (typeof GENERATED_ACPX_SIDECAR_EVENT_TYPES)[number];\n`;+const rust = `// Generated by scripts/generate-acpx-sidecar-contract.mjs. Do not edit.\n\npub const GENERATED_ACPX_SIDECAR_PROTOCOL_VERSION: u64 = ${protocolVersion};\n\n#[derive(Clone, Copy, Debug, PartialEq, Eq)]\npub enum GeneratedAcpxSidecarCommand {\n${commands.map((value) => ` ${rustVariant(value)},`).join("\n")}\n}\n\nimpl GeneratedAcpxSidecarCommand {\n pub const fn as_str(self) -> &'static str {\n match self {\n${commands.map((value) => ` Self::${rustVariant(value)} => ${quote(value)},`).join("\n")}\n }\n }\n}\n\n#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Deserialize)]\npub enum GeneratedAcpxSidecarEventType {\n${events.map((value) => ` #[serde(rename = ${quote(value)})]\n ${rustVariant(value)},`).join("\n")}\n}\n`;++const outputs = [+ [resolve(root, "src/drivers/acpx/generated-sidecar-contract.ts"), typescript],+ [+ resolve(+ root,+ "runner/crates/runner-core/src/generated_acpx_sidecar_contract.rs",+ ),+ rust,+ ],+];+if (process.argv.includes("--check")) {+ const stale = [];+ for (const [path, content] of outputs)+ if ((await readFile(path, "utf8").catch(() => "")) !== content)+ stale.push(path);+ if (stale.length > 0) {+ process.stderr.write(+ `Generated ACPX sidecar contracts are stale: ${stale.join(", ")}\n`,+ );+ process.exitCode = 1;+ } else+ process.stdout.write(+ "Generated TypeScript/Rust ACPX sidecar contracts match the schema.\n",+ );+} else {+ await Promise.all(outputs.map(([path, content]) => writeFile(path, content)));+ process.stdout.write("Generated TypeScript/Rust ACPX sidecar contracts.\n");+}diff --git a/packages/paperclip-runner/src/drivers/acpx/generated-sidecar-contract.ts b/packages/paperclip-runner/src/drivers/acpx/generated-sidecar-contract.tsnew file mode 100644index 0000000000..eed7190584--- /dev/null+++ b/packages/paperclip-runner/src/drivers/acpx/generated-sidecar-contract.ts@@ -0,0 +1,31 @@+// Generated by scripts/generate-acpx-sidecar-contract.mjs. Do not edit.++export const GENERATED_ACPX_SIDECAR_PROTOCOL_VERSION = 2 as const;+export const GENERATED_ACPX_SIDECAR_COMMANDS = [+ "initialize",+ "session.open",+ "run.attach",+ "turn.start",+ "turn.cancel",+ "permission.resolve",+ "input.resolve",+ "tool.resolve",+ "session.read",+ "session.snapshot",+ "session.suspend",+ "session.close",+] as const;+export type GeneratedAcpxSidecarCommand =+ (typeof GENERATED_ACPX_SIDECAR_COMMANDS)[number];++export const GENERATED_ACPX_SIDECAR_EVENT_TYPES = [+ "runtime.event",+ "runtime.permission_requested",+ "runtime.input_requested",+ "runtime.tool_called",+ "runtime.turn_terminal",+ "runtime.process",+ "runtime.diagnostic",+] as const;+export type GeneratedAcpxSidecarEventType =+ (typeof GENERATED_ACPX_SIDECAR_EVENT_TYPES)[number];diff --git a/packages/paperclip-runner/test/acpx-sidecar-contract.test.mjs b/packages/paperclip-runner/test/acpx-sidecar-contract.test.mjsnew file mode 100644index 0000000000..10695fc9a6--- /dev/null+++ b/packages/paperclip-runner/test/acpx-sidecar-contract.test.mjs@@ -0,0 +1,95 @@+import assert from "node:assert/strict";+import { readFile } from "node:fs/promises";+import test from "node:test";++import Ajv2020 from "ajv/dist/2020.js";++import { readAcpxSidecarProtocolVersion } from "../scripts/acpx-sidecar-contract.mjs";++const schema = JSON.parse(+ await readFile(+ new URL(+ "../protocol/provider-schemas/acpx-sidecar.schema.json",+ import.meta.url,+ ),+ "utf8",+ ),+);+const validate = new Ajv2020({ allErrors: true, strict: true }).compile(schema);+const protocolVersion = readAcpxSidecarProtocolVersion(schema);++const messages = [+ {+ protocolVersion,+ id: 1,+ command: "initialize",+ params: {},+ },+ {+ protocolVersion,+ id: 1,+ ok: true,+ result: {},+ },+ {+ protocolVersion,+ sequence: 1,+ eventType: "runtime.event",+ runId: "run-1",+ turnId: "turn-1",+ payload: {},+ },+];++test("the ACPX sidecar schema accepts each versioned message family", () => {+ for (const message of messages) {+ assert.equal(validate(message), true, JSON.stringify(validate.errors));+ }+});++test("the ACPX sidecar schema fails closed on drift", () => {+ for (const message of [+ { ...messages[0], protocolVersion: protocolVersion + 1 },+ { ...messages[0], command: "session.destroy" },+ { protocolVersion, id: 1, ok: true, result: {}, error: error() },+ { protocolVersion, id: 1, ok: true },+ { protocolVersion, id: 1, ok: false },+ { protocolVersion, id: 1, ok: false, result: {}, error: error() },+ { ...messages[2], unexpected: true },+ ]) {+ assert.equal(validate(message), false);+ }+});++test("every ACPX sidecar message family uses the shared version", () => {+ for (const family of ["request", "response", "event"]) {+ assert.deepEqual(schema.$defs[family].properties.protocolVersion, {+ $ref: "#/$defs/protocolVersion",+ });+ }+});++test("the ACPX sidecar schema id carries the declared protocol version", () => {+ assert.equal(+ schema.$id,+ `https://paperclip.dev/schemas/acpx-sidecar/v${protocolVersion}/message.schema.json`,+ );+});++test("a coordinated family-version upgrade cannot outpace the schema id", () => {+ const driftedSchema = structuredClone(schema);+ driftedSchema.$defs.protocolVersion.const = protocolVersion + 1;++ assert.throws(+ () => readAcpxSidecarProtocolVersion(driftedSchema),+ /must match its authoritative schema \$id/,+ );+});++function error() {+ return {+ code: "runtime_failed",+ message: "The runtime failed.",+ retryable: false,+ };+}