From 6e6ef5e8abfe571754b3fddba5d1e3431832841e Mon Sep 17 00:00:00 2001 From: lucasyarza Date: Fri, 21 Aug 2026 20:43:24 +0200 Subject: [PATCH 1/5] chore(agents): bump built-in Claude and Pi adapter ranges Advance the source-owned npm ranges for the Claude and Pi built-in adapters to their current npm releases: - `@agentclientprotocol/claude-agent-acp` `^0.60.0` -> `^0.70.0` - `pi-acp` `^0.0.31` -> `^0.0.33` The Codex (`^1.1.5`) and Mux (`^0.28.0`) ranges already float to the latest published releases (1.6.2 and 0.28.2), so they are left unchanged. Claude 0.61.0 through 0.70.0 and Pi 0.0.32 through 0.0.33 publish no breaking changes; the release notes contain features and fixes only. Built-in names, command routing, installed-package-first resolution, package-exec fallback, queueing, persistence, cancellation, and reconnect behavior are unchanged. No ACPX dependency, manifest, or lockfile changes. Co-Authored-By: Claude --- CHANGELOG.md | 1 + src/agent-registry.ts | 4 ++-- test/agent-registry.test.ts | 6 +++--- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 85e15d3b..ab4c5714 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,7 @@ Repo: https://github.com/openclaw/acpx ### Changes - Dependencies: update the ACP SDK, TypeScript runner, replay-viewer dependencies, and validation tooling, and refresh transitive dependency overrides. +- Agents/built-ins: bump the default Claude ACP adapter range to `@agentclientprotocol/claude-agent-acp@^0.70.0` and the Pi adapter range to `pi-acp@^0.0.33`, so fresh built-in launches pick up the latest adapter releases. ### Breaking diff --git a/src/agent-registry.ts b/src/agent-registry.ts index 6fc0337d..dccbf72e 100644 --- a/src/agent-registry.ts +++ b/src/agent-registry.ts @@ -3,9 +3,9 @@ import path from "node:path"; import { fileURLToPath } from "node:url"; const ACP_ADAPTER_PACKAGE_RANGES = { - pi: "^0.0.31", + pi: "^0.0.33", codex: "^1.1.5", - claude: "^0.60.0", + claude: "^0.70.0", mux: "^0.28.0", } as const; diff --git a/test/agent-registry.test.ts b/test/agent-registry.test.ts index d4531400..9df7f4bd 100644 --- a/test/agent-registry.test.ts +++ b/test/agent-registry.test.ts @@ -121,14 +121,14 @@ test("default agent is codex", () => { }); test("claude built-in uses the current ACP adapter package range", () => { - assert.equal(BUILT_IN_AGENT_PACKAGES.claude.packageRange, "^0.60.0"); - assert.equal(AGENT_REGISTRY.claude, "npx -y @agentclientprotocol/claude-agent-acp@^0.60.0"); + assert.equal(BUILT_IN_AGENT_PACKAGES.claude.packageRange, "^0.70.0"); + assert.equal(AGENT_REGISTRY.claude, "npx -y @agentclientprotocol/claude-agent-acp@^0.70.0"); }); test("npm-backed built-ins use current adapter package ranges", () => { assert.equal(BUILT_IN_AGENT_PACKAGES.codex.packageRange, "^1.1.5"); assert.equal(AGENT_REGISTRY.codex, "npx -y @agentclientprotocol/codex-acp@^1.1.5"); - assert.equal(AGENT_REGISTRY.pi, "npx pi-acp@^0.0.31"); + assert.equal(AGENT_REGISTRY.pi, "npx pi-acp@^0.0.33"); }); test("resolveInstalledBuiltInAgentLaunch uses a locally installed adapter when available", (t) => { From 1af7a98143b00116e75cd98dce395415728761b5 Mon Sep 17 00:00:00 2001 From: lucasyarza Date: Fri, 21 Aug 2026 21:21:16 +0200 Subject: [PATCH 2/5] fix(agents): migrate superseded Claude and Pi built-in commands Registering the new ranges alone left the outgoing launch commands unmapped, so persisted sessions recorded under them reconstructed no argv and kept launching the retired adapter line. Add the superseded forms to `LEGACY_AGENT_COMMANDS`: - `npx pi-acp@^0.0.31` - `npx -y @agentclientprotocol/claude-agent-acp@^0.60.0` - `npm exec @agentclientprotocol/claude-agent-acp@^0.60.0` Cover all three in the historical built-in command table in `test/session-persistence.test.ts`. Synchronize the harness documentation the range change requires: mark the Pi built-in as ACPX-range-owned in `skills/acpx/SKILL.md`, document the persisted command mapping there and in `agents/Claude.md`, add the missing `agents/Pi.md`, and link it first in `agents/README.md` per the mandatory example ordering. Drop the adapter version specifiers from the changelog entry, which the documentation policy forbids. Co-Authored-By: Claude --- CHANGELOG.md | 2 +- agents/Claude.md | 1 + agents/Pi.md | 25 +++++++++++++++++++++++++ agents/README.md | 1 + skills/acpx/SKILL.md | 4 +++- src/acp/builtin-command-migration.ts | 4 +++- test/session-persistence.test.ts | 3 +++ 7 files changed, 37 insertions(+), 3 deletions(-) create mode 100644 agents/Pi.md diff --git a/CHANGELOG.md b/CHANGELOG.md index ab4c5714..0189e230 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,7 +17,7 @@ Repo: https://github.com/openclaw/acpx ### Changes - Dependencies: update the ACP SDK, TypeScript runner, replay-viewer dependencies, and validation tooling, and refresh transitive dependency overrides. -- Agents/built-ins: bump the default Claude ACP adapter range to `@agentclientprotocol/claude-agent-acp@^0.70.0` and the Pi adapter range to `pi-acp@^0.0.33`, so fresh built-in launches pick up the latest adapter releases. +- Agents/built-ins: refresh the default Claude and Pi adapter ranges so fresh built-in launches pick up the current adapter releases, and keep sessions persisted under the superseded launch commands on the current built-in launch path. ### Breaking diff --git a/agents/Claude.md b/agents/Claude.md index 7ea3ead5..4e465772 100644 --- a/agents/Claude.md +++ b/agents/Claude.md @@ -4,6 +4,7 @@ - Default command: `npx -y @agentclientprotocol/claude-agent-acp` - Upstream: https://github.com/agentclientprotocol/claude-agent-acp - ACPX pins the built-in package range so fresh installs pick up Claude model and ACP adapter fixes without depending on a global adapter binary. +- When that range advances, sessions persisted under the superseded built-in command are mapped back to the current built-in launch argv on reuse, so older records do not keep launching the retired adapter line. - Model switches can change the available effort controls. ACPX updates existing saved effort selections from the accepted response and removes selections whose controls disappear. - Saved model and config selections are restored after reconnect, without replacing the conversation. diff --git a/agents/Pi.md b/agents/Pi.md new file mode 100644 index 00000000..db31755e --- /dev/null +++ b/agents/Pi.md @@ -0,0 +1,25 @@ +# Pi + +- Built-in name: `pi` +- Default command: `npx pi-acp` +- Upstream: [mariozechner/pi](https://github.com/mariozechner/pi) +- Adapter: [svkozak/pi-acp](https://github.com/svkozak/pi-acp) +- ACPX owns the built-in package range so fresh launches use the repository-selected adapter line without depending on a globally installed adapter binary. +- When that range advances, sessions persisted under the superseded built-in command are mapped back to the current built-in launch argv on reuse, so older records do not keep launching the retired adapter line. + +`acpx pi` starts the Pi coding agent through the `pi-acp` ACP adapter. The adapter +drives an installed Pi CLI, so install and authenticate Pi first; the adapter README +states the minimum supported Pi version. + +If the adapter needs a different resolution path or extra startup arguments, override +the built-in argv in `~/.acpx/config.json`: + +```json +{ + "agents": { + "pi": { + "argv": ["npx", "pi-acp"] + } + } +} +``` diff --git a/agents/README.md b/agents/README.md index 520676a1..6b42af45 100644 --- a/agents/README.md +++ b/agents/README.md @@ -26,6 +26,7 @@ Built-in agents: Harness-specific docs in this directory: +- [Pi](Pi.md): built-in `pi -> npx pi-acp` via an ACPX-owned npm range - [Codex](Codex.md): built-in `codex -> npx -y @agentclientprotocol/codex-acp` - [Claude](Claude.md): built-in `claude -> npx -y @agentclientprotocol/claude-agent-acp` - [Gemini](Gemini.md): built-in `gemini -> gemini --acp` diff --git a/skills/acpx/SKILL.md b/skills/acpx/SKILL.md index bccefb61..261b639f 100644 --- a/skills/acpx/SKILL.md +++ b/skills/acpx/SKILL.md @@ -81,7 +81,7 @@ If prompt text is omitted and stdin is piped, `acpx` reads prompt text from stdi Friendly agent names resolve to commands: -- `pi` -> `npx pi-acp` +- `pi` -> `npx pi-acp` (ACPX-owned package range) - `openclaw` -> `openclaw acp` - `codex` -> `npx -y @agentclientprotocol/codex-acp` (ACPX-owned package range) - `claude` -> `npx -y @agentclientprotocol/claude-agent-acp` (ACPX-owned package range) @@ -110,6 +110,8 @@ Rules: - Unknown positional agent tokens are treated as raw agent commands. - `--agent ` explicitly sets a raw ACP adapter command. - Do not combine a positional agent and `--agent` in the same command. +- When ACPX advances an ACPX-owned package range, sessions persisted under the superseded + built-in command are mapped back to the current built-in launch argv on reuse. ## Commands diff --git a/src/acp/builtin-command-migration.ts b/src/acp/builtin-command-migration.ts index 8675b6b9..8d0b034b 100644 --- a/src/acp/builtin-command-migration.ts +++ b/src/acp/builtin-command-migration.ts @@ -1,7 +1,7 @@ import { AGENT_ARGV_REGISTRY, AGENT_REGISTRY, BUILT_IN_AGENT_PACKAGES } from "../agent-registry.js"; const LEGACY_AGENT_COMMANDS: Record = { - pi: ["npx pi-acp", "npx pi-acp@^0.0.22", "npx pi-acp@^0.0.26"], + pi: ["npx pi-acp", "npx pi-acp@^0.0.22", "npx pi-acp@^0.0.26", "npx pi-acp@^0.0.31"], codex: [ "npx @zed-industries/codex-acp", "npx @zed-industries/codex-acp@^0.9.5", @@ -21,8 +21,10 @@ const LEGACY_AGENT_COMMANDS: Record = { "npx -y @zed-industries/claude-agent-acp@^0.31.0", "npx -y @agentclientprotocol/claude-agent-acp@^0.36.1", "npx -y @agentclientprotocol/claude-agent-acp@^0.37.0", + "npx -y @agentclientprotocol/claude-agent-acp@^0.60.0", "npm exec @agentclientprotocol/claude-agent-acp@^0.36.1", "npm exec @agentclientprotocol/claude-agent-acp@^0.37.0", + "npm exec @agentclientprotocol/claude-agent-acp@^0.60.0", ], gemini: ["gemini", "gemini --experimental-acp"], kiro: ["kiro-cli acp"], diff --git a/test/session-persistence.test.ts b/test/session-persistence.test.ts index ca97030a..e251cc01 100644 --- a/test/session-persistence.test.ts +++ b/test/session-persistence.test.ts @@ -72,6 +72,9 @@ test("parseSessionRecord backfills argv for historical built-in commands", () => for (const [agentCommand, expectedArgv] of [ ["npx @zed-industries/codex-acp@^0.12.0", AGENT_ARGV_REGISTRY.codex], ["npm exec @agentclientprotocol/claude-agent-acp@^0.37.0", AGENT_ARGV_REGISTRY.claude], + ["npx -y @agentclientprotocol/claude-agent-acp@^0.60.0", AGENT_ARGV_REGISTRY.claude], + ["npm exec @agentclientprotocol/claude-agent-acp@^0.60.0", AGENT_ARGV_REGISTRY.claude], + ["npx pi-acp@^0.0.31", AGENT_ARGV_REGISTRY.pi], ["npx -y mux@^0.27.0 acp", AGENT_ARGV_REGISTRY.mux], ["gemini --experimental-acp", AGENT_ARGV_REGISTRY.gemini], ["kiro-cli acp", AGENT_ARGV_REGISTRY.kiro], From b6d24dbb7810852b1c3e317ea3d08649f27f395c Mon Sep 17 00:00:00 2001 From: lucasyarza Date: Fri, 21 Aug 2026 21:33:28 +0200 Subject: [PATCH 3/5] docs(agents): qualify the persisted-session migration guarantee A usable stored `agent_argv` is resolved before the historical-command map, so a record saved under a retired command only picks up the current argv when it has no usable stored argv. The previous wording promised the migration for every such record. Qualify the claim in `agents/Claude.md`, `agents/Pi.md`, `skills/acpx/SKILL.md`, and the changelog entry, and lock the precedence with a regression test that a retired command plus usable stored argv keeps the stored launcher. Co-Authored-By: Claude --- CHANGELOG.md | 2 +- agents/Claude.md | 2 +- agents/Pi.md | 2 +- skills/acpx/SKILL.md | 5 +++-- test/session-persistence.test.ts | 19 +++++++++++++++++++ 5 files changed, 25 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0189e230..d1b70789 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,7 +17,7 @@ Repo: https://github.com/openclaw/acpx ### Changes - Dependencies: update the ACP SDK, TypeScript runner, replay-viewer dependencies, and validation tooling, and refresh transitive dependency overrides. -- Agents/built-ins: refresh the default Claude and Pi adapter ranges so fresh built-in launches pick up the current adapter releases, and keep sessions persisted under the superseded launch commands on the current built-in launch path. +- Agents/built-ins: refresh the default Claude and Pi adapter ranges so fresh built-in launches pick up the current adapter releases, and keep sessions saved under the superseded launch commands on the current built-in launch path when their record carries no usable stored argv. ### Breaking diff --git a/agents/Claude.md b/agents/Claude.md index 4e465772..fb125b45 100644 --- a/agents/Claude.md +++ b/agents/Claude.md @@ -4,7 +4,7 @@ - Default command: `npx -y @agentclientprotocol/claude-agent-acp` - Upstream: https://github.com/agentclientprotocol/claude-agent-acp - ACPX pins the built-in package range so fresh installs pick up Claude model and ACP adapter fixes without depending on a global adapter binary. -- When that range advances, sessions persisted under the superseded built-in command are mapped back to the current built-in launch argv on reuse, so older records do not keep launching the retired adapter line. +- When that range advances, a session persisted under the superseded built-in command is mapped back to the current built-in launch argv on reuse, but only when the record carries no usable stored `agent_argv`. A record with usable stored argv intentionally keeps that launcher. - Model switches can change the available effort controls. ACPX updates existing saved effort selections from the accepted response and removes selections whose controls disappear. - Saved model and config selections are restored after reconnect, without replacing the conversation. diff --git a/agents/Pi.md b/agents/Pi.md index db31755e..019ebe72 100644 --- a/agents/Pi.md +++ b/agents/Pi.md @@ -5,7 +5,7 @@ - Upstream: [mariozechner/pi](https://github.com/mariozechner/pi) - Adapter: [svkozak/pi-acp](https://github.com/svkozak/pi-acp) - ACPX owns the built-in package range so fresh launches use the repository-selected adapter line without depending on a globally installed adapter binary. -- When that range advances, sessions persisted under the superseded built-in command are mapped back to the current built-in launch argv on reuse, so older records do not keep launching the retired adapter line. +- When that range advances, a session persisted under the superseded built-in command is mapped back to the current built-in launch argv on reuse, but only when the record carries no usable stored `agent_argv`. A record with usable stored argv intentionally keeps that launcher. `acpx pi` starts the Pi coding agent through the `pi-acp` ACP adapter. The adapter drives an installed Pi CLI, so install and authenticate Pi first; the adapter README diff --git a/skills/acpx/SKILL.md b/skills/acpx/SKILL.md index 261b639f..376c1034 100644 --- a/skills/acpx/SKILL.md +++ b/skills/acpx/SKILL.md @@ -110,8 +110,9 @@ Rules: - Unknown positional agent tokens are treated as raw agent commands. - `--agent ` explicitly sets a raw ACP adapter command. - Do not combine a positional agent and `--agent` in the same command. -- When ACPX advances an ACPX-owned package range, sessions persisted under the superseded - built-in command are mapped back to the current built-in launch argv on reuse. +- When ACPX advances an ACPX-owned package range, a session persisted under the superseded + built-in command is mapped back to the current built-in launch argv on reuse only when the + record carries no usable stored `agent_argv`. A usable stored argv always wins. ## Commands diff --git a/test/session-persistence.test.ts b/test/session-persistence.test.ts index e251cc01..b2417b0f 100644 --- a/test/session-persistence.test.ts +++ b/test/session-persistence.test.ts @@ -97,6 +97,25 @@ test("parseSessionRecord backfills argv for historical built-in commands", () => } }); +test("parseSessionRecord keeps usable stored argv over historical command migration", () => { + const storedArgv = ["npx", "-y", "@agentclientprotocol/claude-agent-acp@^0.60.0"]; + const serialized = serializeSessionRecordForDisk( + makeSessionRecord({ + acpxRecordId: "stored-argv-wins", + acpSessionId: "stored-argv-wins", + agentCommand: "npx -y @agentclientprotocol/claude-agent-acp@^0.60.0", + cwd: "/tmp/stored-argv-wins", + }), + ); + serialized.agent_argv = storedArgv; + + const parsed = parseSessionRecord(serialized); + + assert.ok(parsed); + assert.deepEqual(parsed.agentArgv, storedArgv); + assert.notDeepEqual(parsed.agentArgv, AGENT_ARGV_REGISTRY.claude); +}); + test("parseSessionRecord preserves persisted session env", () => { const serialized = serializeSessionRecordForDisk( makeSessionRecord({ From 469c586e8151edc965e752a8e5602953c82a4bc6 Mon Sep 17 00:00:00 2001 From: lucasyarza Date: Fri, 21 Aug 2026 21:44:35 +0200 Subject: [PATCH 4/5] fix(agents): keep built-in launch resolution for retired Claude commands Backfilling argv was not enough. The client resolves built-in launch behavior from the unchanged persisted `agent_command`, and `findBuiltInAgentPackage` matches only `fallbackCommand` and `legacyFallbackCommands`. Neither retired `^0.60.0` form appeared there, so a saved Claude session without stored argv took a raw npx launcher and bypassed the installed-package-first and package-exec paths that recognized Claude commands use. Register both retired forms in the Claude spec's `legacyFallbackCommands`, which `resolveAgentArgvForCommand` already consults before `LEGACY_AGENT_COMMANDS`, and drop the now-duplicate entries from that map so each retired form has one home. Cover the launch path: package-exec resolution must recognize both retired commands and bridge them at the current package range. Co-Authored-By: Claude --- src/acp/builtin-command-migration.ts | 2 -- src/agent-registry.ts | 2 ++ test/agent-registry.test.ts | 18 ++++++++++++++++++ 3 files changed, 20 insertions(+), 2 deletions(-) diff --git a/src/acp/builtin-command-migration.ts b/src/acp/builtin-command-migration.ts index 8d0b034b..2a4cc699 100644 --- a/src/acp/builtin-command-migration.ts +++ b/src/acp/builtin-command-migration.ts @@ -21,10 +21,8 @@ const LEGACY_AGENT_COMMANDS: Record = { "npx -y @zed-industries/claude-agent-acp@^0.31.0", "npx -y @agentclientprotocol/claude-agent-acp@^0.36.1", "npx -y @agentclientprotocol/claude-agent-acp@^0.37.0", - "npx -y @agentclientprotocol/claude-agent-acp@^0.60.0", "npm exec @agentclientprotocol/claude-agent-acp@^0.36.1", "npm exec @agentclientprotocol/claude-agent-acp@^0.37.0", - "npm exec @agentclientprotocol/claude-agent-acp@^0.60.0", ], gemini: ["gemini", "gemini --experimental-acp"], kiro: ["kiro-cli acp"], diff --git a/src/agent-registry.ts b/src/agent-registry.ts index dccbf72e..cc1c02ac 100644 --- a/src/agent-registry.ts +++ b/src/agent-registry.ts @@ -103,6 +103,8 @@ export const BUILT_IN_AGENT_PACKAGES = { fallbackCommand: AGENT_REGISTRY.claude, legacyFallbackCommands: [ `npm exec @agentclientprotocol/claude-agent-acp@${ACP_ADAPTER_PACKAGE_RANGES.claude}`, + "npx -y @agentclientprotocol/claude-agent-acp@^0.60.0", + "npm exec @agentclientprotocol/claude-agent-acp@^0.60.0", ], }, } as const satisfies Record; diff --git a/test/agent-registry.test.ts b/test/agent-registry.test.ts index 9df7f4bd..46b91072 100644 --- a/test/agent-registry.test.ts +++ b/test/agent-registry.test.ts @@ -177,6 +177,24 @@ test("resolveInstalledBuiltInAgentLaunch ignores non-built-in commands", () => { assert.equal(resolveInstalledBuiltInAgentLaunch("custom-acp-server --stdio"), undefined); }); +test("package-exec resolution recognizes the retired Claude built-in commands", () => { + const npmCliPath = path.join(os.tmpdir(), "acpx-test-npm-cli.js"); + for (const retiredCommand of [ + "npx -y @agentclientprotocol/claude-agent-acp@^0.60.0", + "npm exec @agentclientprotocol/claude-agent-acp@^0.60.0", + ]) { + const launch = resolvePackageExecBuiltInAgentLaunch(retiredCommand, { + execPath: "/tmp/node", + existsSync: (candidate) => candidate === npmCliPath, + resolveNpmCliPath: () => npmCliPath, + }); + + assert.equal(launch?.source, "package-exec"); + assert.equal(launch?.packageName, BUILT_IN_AGENT_PACKAGES.claude.packageName); + assert.equal(launch?.packageRange, BUILT_IN_AGENT_PACKAGES.claude.packageRange); + } +}); + test("resolvePackageExecBuiltInAgentLaunch bridges built-ins through the current Node npm CLI", () => { const npmCliPath = path.join(os.tmpdir(), "acpx-test-npm-cli.js"); const launch = resolvePackageExecBuiltInAgentLaunch(AGENT_REGISTRY.codex, { From 5e6fa7b443ea26f35f0f93fbd5f65f17c4831fb5 Mon Sep 17 00:00:00 2001 From: lucasyarza Date: Mon, 31 Aug 2026 09:31:38 +0200 Subject: [PATCH 5/5] docs(changelog): keep the adapter entry under Unreleased The 0.13.2 release rolled the previous `Unreleased` block into a dated section, and rebasing carried this branch's entry into it. Move the entry back under `Unreleased`, where it belongs until it actually ships. Co-Authored-By: Claude --- CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d1b70789..9760a934 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,8 @@ Repo: https://github.com/openclaw/acpx ### Changes +- Agents/built-ins: refresh the default Claude and Pi adapter ranges so fresh built-in launches pick up the current adapter releases, and keep sessions saved under the superseded launch commands on the current built-in launch path when their record carries no usable stored argv. + ### Breaking ### Fixes @@ -17,7 +19,6 @@ Repo: https://github.com/openclaw/acpx ### Changes - Dependencies: update the ACP SDK, TypeScript runner, replay-viewer dependencies, and validation tooling, and refresh transitive dependency overrides. -- Agents/built-ins: refresh the default Claude and Pi adapter ranges so fresh built-in launches pick up the current adapter releases, and keep sessions saved under the superseded launch commands on the current built-in launch path when their record carries no usable stored argv. ### Breaking