mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 11:59:26 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Paperclip Runner runs Claude Code through the ACPX sidecar. > - Claude can start a shell command in the background and end its turn. When the command finishes, Claude Code starts a cycle of its own to continue. Today the Runner stops Claude at the end of the turn, so the command stops and the run fails with `native_finalization_missing`. > - A stack of pull requests lets the Runner accept that cycle as a new turn of the same run, when a controller asks for it. > - The Runner, its sidecar and the controller speak two protocols with schemas: PRP between the controller and the Runner, and the sidecar protocol between `paperclip-runnerd` and the ACPX sidecar. > - A turn that the provider starts needs new fields and one new command in those protocols. > - This pull request declares them and generates the readers again. It changes no behavior. > - The benefit is that the next two pull requests show behavior only, with the contract already in review. ## Linked Issues or Issue Description No public issue exists. The issue is described here. This pull request is one part of a change that was first opened as one large pull request (#21316). The parts, in stack order after #21311: 1. #21419: sidecar preparation (a refactor). 2. #21420: converter for raw ACP session updates. 3. #21421: cycle stream at the adapter. 4. #21422: contract for provider-started turns. 5. #21423: `paperclip-runnerd` waits for a provider-started turn. 6. #21316: the sidecar adopts a cycle. This is part 4. Its base branch is `feat/claude-provider-cycle-stream`. After each part, a production run does the same as today, because no controller sends the opt-in. Refs #19912 (design). **What existing behavior does this improve?** Nothing in production. The protocol schemas. **Subsystem affected** Paperclip Runner: `protocol/` and the generated TypeScript and Rust contract code. **Current behavior** - PRP has no way to say that a turn was started by the provider, or that the Runner waits for such a turn. - The sidecar protocol has no command to arm the sidecar and no event for a turn that the provider starts. **Proposed behavior** - PRP (`schemas/provider-turn.schema.json`, new): `providerStartedTurns` (boolean) in the payload of `turn.start`, `origin: "provider"` on `turn.started`, and `awaitingProviderTurn: true` on `turn.completed`. `command-v3` and `event-v3` refer to it. - Sidecar protocol (`provider-schemas/acpx-sidecar.schema.json`): the command `session.provider_turn` with `{ turnId, armed }`, the event `runtime.turn_started` with `{ origin: "provider" }`, and the payload of the diagnostic for a lost provider. The schema enforces that payload for a `runtime.diagnostic` with the code `ACPX_PROVIDER_PROCESS_LOST`. Diagnostics with other codes keep their open payload. - `paperclip-runnerd` decodes `runtime.turn_started` and refuses it. No sidecar sends it yet. The Runner of today refuses an unknown event too. - No controller, Runner or sidecar uses the new fields in this pull request. **Reason and benefit** The repository rule for Runner contracts says that new fields must be in the schema with generated readers. A separate pull request lets a reviewer read the contract alone. ## What Changed - `protocol/schemas/provider-turn.schema.json` (new), `command-v3.schema.json`, `event-v3.schema.json`, `protocol/provider-schemas/acpx-sidecar.schema.json`, `protocol/manifest.json`. - `scripts/generate-acpx-sidecar-contract.mjs` and `scripts/generate-protocol-schema-module.mjs`. - Generated: `src/drivers/acpx/generated-sidecar-contract.ts`, `src/protocol/generated/schema-bundle.ts`, `src/protocol/generated/standalone-validators.ts`, `runner/crates/runner-core/src/generated_acpx_sidecar_contract.rs`. - `runner/crates/runner-core/src/acpx_event_payload.rs` (3 lines): the Rust `match` on the event type must name the new event to compile. - `test/protocol-contract.test.mjs`. - The contract digests of the pack change (`prp.acpx-sidecar`, `prp.command-v3`, `prp.event-v3`, `rust`, and the new `prp.provider-turn`). No stored file refers to these digests. No provider `commandDigest` and no profile version changes. ## Verification At the head of this branch, from `packages/paperclip-runner`: - `npx tsc --noEmit -p tsconfig.json`, `npx tsc --noEmit -p tsconfig.test.json`, `pnpm run typecheck:typescript`, `pnpm run build:typescript`, `node --test test/acpx-sidecar-contract.test.mjs test/protocol-contract.test.mjs`, the server check `node scripts/verify-runner-vendor-dependencies.mjs`, `node --test scripts/__tests__/runner-release-crate-cache.test.mjs`, `cargo fmt --check` and `cargo build -p paperclip-runner-core --bins` (no new warning): all passed. The contract tests: 32 passed. - The sidecar suite and the tracker tests: 141 passed. Not run: the full suite. CI supplies that coverage. ## Risks - **The pack contract digest changes.** Older image packs are not used again. - **The opt-in field is accepted by the schema but has no effect yet.** A controller that sends it before part 5 gets the behavior of today. - **State saved by the previous release:** this pull request changes no persisted shape. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Fable 5.2 (`claude-fable-5-2`) in Claude Code planned the change and the split, reviewed the diff, and ran a part of the verification again. - Claude Opus 5.5 (`claude-opus-5-5`), as a Claude Code subagent with tool use (shell, file edits, local test runs), wrote the change and the tests and cut this slice from the full change. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
123 lines
5.0 KiB
JavaScript
123 lines
5.0 KiB
JavaScript
import { readFile, writeFile } from "node:fs/promises";
|
|
import { dirname, resolve } from "node:path";
|
|
import { fileURLToPath } from "node:url";
|
|
|
|
import Ajv2020 from "ajv/dist/2020.js";
|
|
import standaloneCode from "ajv/dist/standalone/index.js";
|
|
|
|
const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
|
|
const schemaDirectory = resolve(packageRoot, "protocol/schemas");
|
|
const outputPath = resolve(packageRoot, "src/protocol/generated/schema-bundle.ts");
|
|
const validatorsOutputPath = resolve(
|
|
packageRoot,
|
|
"src/protocol/generated/standalone-validators.ts",
|
|
);
|
|
const schemaNames = [
|
|
"auth-credentials",
|
|
"identity",
|
|
"capabilities",
|
|
"capabilities-v2",
|
|
"capabilities-v3",
|
|
"command",
|
|
"command-v2",
|
|
"command-v3",
|
|
"provider-descriptor",
|
|
"provider-event",
|
|
"workspace-diff",
|
|
"workspace-file-reference",
|
|
"semantic-tool",
|
|
"usage",
|
|
"stop-reason",
|
|
"terminal",
|
|
"question-set",
|
|
"question-response",
|
|
"question-adapter-fixture",
|
|
"request",
|
|
"result",
|
|
"event",
|
|
"event-v2",
|
|
"event-v3",
|
|
"session-goal",
|
|
"provider-turn",
|
|
"fixture",
|
|
];
|
|
|
|
const schemas = await Promise.all(
|
|
schemaNames.map(async (name) => ({
|
|
name,
|
|
value: JSON.parse(await readFile(resolve(schemaDirectory, `${name}.schema.json`), "utf8")),
|
|
})),
|
|
);
|
|
|
|
const identifier = (name) => name.replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase());
|
|
const declarations = schemas
|
|
.map(({ name, value }) => `export const ${identifier(name)}Schema = ${JSON.stringify(value, null, 2)} as const;`)
|
|
.join("\n\n");
|
|
const bundle = schemaNames.map((name) => ` ${JSON.stringify(name)}: ${identifier(name)}Schema,`).join("\n");
|
|
const generated = `// Generated by scripts/generate-protocol-schema-module.mjs. Do not edit.\n\n${declarations}\n\nexport const prpSchemaBundle = {\n${bundle}\n} as const;\n`;
|
|
|
|
const schemaByName = Object.fromEntries(schemas.map(({ name, value }) => [name, value]));
|
|
const ajv = new Ajv2020({
|
|
allErrors: true,
|
|
strict: true,
|
|
strictRequired: false,
|
|
code: { esm: true, source: true },
|
|
formats: {
|
|
"date-time": /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/,
|
|
},
|
|
});
|
|
for (const { value } of schemas) ajv.addSchema(value);
|
|
const standaloneValidators = standaloneCode(ajv, {
|
|
authCredentialsValidator: schemaByName["auth-credentials"].$id,
|
|
fixtureValidator: schemaByName.fixture.$id,
|
|
eventValidator: schemaByName.event.$id,
|
|
eventV2Validator: schemaByName["event-v2"].$id,
|
|
eventV3Validator: schemaByName["event-v3"].$id,
|
|
resultValidator: schemaByName.result.$id,
|
|
});
|
|
const ucs2RuntimePattern = /const (func\d+) = require\("ajv\/dist\/runtime\/ucs2length"\)\.default;/;
|
|
if (!ucs2RuntimePattern.test(standaloneValidators)) {
|
|
throw new Error("Ajv standalone output no longer has the expected ucs2length runtime binding");
|
|
}
|
|
const equalRuntimePattern = /const (func\d+) = require\("ajv\/dist\/runtime\/equal"\)\.default;/;
|
|
if (!equalRuntimePattern.test(standaloneValidators)) {
|
|
throw new Error("Ajv standalone output no longer has the expected equal runtime binding");
|
|
}
|
|
const validatorsWithRuntimeImports = standaloneValidators.replace(
|
|
ucs2RuntimePattern,
|
|
"const $1 = typeof ucs2LengthModule === \"function\" ? ucs2LengthModule : ucs2LengthModule.default;",
|
|
).replace(
|
|
equalRuntimePattern,
|
|
"const $1 = typeof equalModule === \"function\" ? equalModule : equalModule.default;",
|
|
);
|
|
const validatorExportPattern = /export const (authCredentialsValidator|fixtureValidator|eventValidator|resultValidator) =/g;
|
|
const validatorExports = [...validatorsWithRuntimeImports.matchAll(validatorExportPattern)];
|
|
if (validatorExports.length !== 4) {
|
|
throw new Error("Ajv standalone output no longer has the expected validator exports");
|
|
}
|
|
// Ajv's generated functions are intentionally unchecked runtime JavaScript.
|
|
// Bound their exported types so TypeScript does not infer the full generated
|
|
// implementation graph. replay-contract.ts applies the checked public types.
|
|
const validators = validatorsWithRuntimeImports.replace(
|
|
validatorExportPattern,
|
|
"export const $1: unknown =",
|
|
);
|
|
const generatedValidators = `// Generated by scripts/generate-protocol-schema-module.mjs. Do not edit.\n// @ts-nocheck -- Ajv standalone output is JavaScript compiled from the checked-in schemas.\n\nimport equalModule from "ajv/dist/runtime/equal.js";\nimport ucs2LengthModule from "ajv/dist/runtime/ucs2length.js";\n\n${validators}\n`;
|
|
|
|
if (process.argv.includes("--check")) {
|
|
const current = await readFile(outputPath, "utf8").catch(() => "");
|
|
const currentValidators = await readFile(validatorsOutputPath, "utf8").catch(() => "");
|
|
if (current !== generated || currentValidators !== generatedValidators) {
|
|
process.stderr.write("Generated PRP schema modules are stale. Run pnpm generate:protocol-types.\n");
|
|
process.exitCode = 1;
|
|
} else {
|
|
process.stdout.write("Generated PRP schema modules match the JSON Schema sources.\n");
|
|
}
|
|
} else {
|
|
await Promise.all([
|
|
writeFile(outputPath, generated),
|
|
writeFile(validatorsOutputPath, generatedValidators),
|
|
]);
|
|
process.stdout.write("Generated PRP schema and standalone validator modules.\n");
|
|
}
|