fix(acp): don't fail the loop when an agent lacks session/set_mode

[alistairstead]

Fixes #67

Problem

ralph run aborts on iteration 1 against any agent that doesn't implement session modes:

ERROR service=default e=message is not an Object. (evaluating '"method" in message') rejection
ERROR service=adapter-source error=Method 'session/set_mode' not found on_error
ERROR service=session-machine iteration=1 error=Method 'session/set_mode' not found iteration_error

Root cause

Two independent bugs, both reproduced in the new tests before fixing.

1. session/set_mode sent to agents that never advertised modes. The guard in AcpAdapter.run() was:

if (preferredMode && sessionResponse.modes?.currentModeId !== preferredMode)

When an agent advertises no modes, modes is undefined, so undefined !== "acceptEdits" is true and the request goes out anyway. Session modes are optional in ACP — an agent only has to accept modes it advertised in session/new — so the agent answers Method 'session/set_mode' not found, which threw out of run() and failed the iteration.

2. A bare JSON scalar on the agent's stdout kills the connection. ndJsonStream enqueues every line that parses as JSON, including scalars like "some log line". The SDK dispatcher then evaluates "method" in message, which throws a TypeError on a primitive and escapes its receive loop as an unhandled rejection — the message is not an Object line above.

Changes

Protocol robustness

• applyPreferredMode() only sends session/set_mode when the preferred mode appears in availableModes and isn't already current; a rejected call is logged as a warning instead of aborting the iteration. Mode selection is a nicety, not a requirement for the loop to run.
• New adapters/acp/message-filter.ts drops non-object messages before they reach the SDK dispatcher.

Point the Claude adapter at the maintained agent

The adapter targeted claude-code-acp, the binary from @zed-industries/claude-code-acp. That package is deprecated on npm — renamed to @agentclientprotocol/claude-agent-acp, which ships a claude-agent-acp binary, tracks ACP SDK 1.x, and was last published this month (the old package's last release was February).

• ClaudeAcpAdapter.command is now claude-agent-acp.
• AcpAdapter gained a fallbackCommands list: claude-code-acp still resolves for users who have the deprecated package installed, with a warning naming the maintained one. isAvailable() and the spawn in run() share that resolution, so a fallback install is detected rather than reported missing.
• Adapters also gained an installHint, printed by ralph run when no candidate binary is on PATH.

Docs

README and the installation guide name the maintained package and disambiguate the three similarly-named ones: @agentclientprotocol/claude-agent-acp (maintained), @zed-industries/claude-code-acp (deprecated rename, still accepted), and the unrelated third-party claude-code-acp on npm that installs cc-acp — installing that one and symlinking it is what led the reporter to an agent that doesn't implement the protocol.

Tests

packages/cli/src/adapters/acp.test.ts drives the adapter against a fake ACP agent subprocess whose behaviour is set by flags (advertises modes or not, accepts or rejects set_mode, prints a bare JSON scalar or not). Four of the five cases failed with the exact errors from the issue before the fix. Three further tests cover primary/fallback/missing command resolution.

Verification

Locally, matching CI: bun run lint, bun run test (582 pass), bun turbo typecheck, and bun run --cwd packages/cli build --single all clean.

Note on dependencies

Bumping @agentclientprotocol/sdk does not fix this. The SDK added the non-object guard in v1.0.0 (ralph pins ^0.14.1), so a bump would resolve bug 2 — but bug 1 is ralph's own guard logic, and the SDK forwards the agent's Method not found error either way. The 0.14 → 1.4 bump is a major-version jump and is left out of this fix.