* feat(pi): add native RPC transport and compatibility contracts * feat(pi): implement native harness and event normalization * feat(pi): resume native and legacy ACP sessions * feat(pi): support native steering and reliable cancellation * feat(pi): expose native models commands and skills * feat(pi): bridge extension dialogs to desktop and mobile input * feat(pi): preserve Zeron MCP delegation in native sessions * feat(pi): activate native RPC driver and CLI discovery * refactor(pi): retire ACP adapter and verify native lifecycle parity * fix(pi): preserve switched sessions empty resumes and composer drafts * docs(pi): translate RPC migration research into English * style(ios): trim whitespace in updated question bindings * test(acp): wait for scenario progress before steering * test(pi): compare canonical session paths on Windows * fix(pi): deliver steering bursts in the same model step * fix(ios): preserve generated Swift binding whitespace * fix(pi): scrub nested-agent env and keep dropped-resolver semantics Pi's native launch skipped owned::configure, so CLAUDECODE and the other nested-agent variables the ACP launch removed leaked into pi. The engine's new input-cancellation task also turned a dropped resolver into an empty answer; keep it an error for harnesses (opencode rejects on error). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * ci: run the native Pi RPC driver tests pi_rpc needs the native-fixture feature and pi_resume is an engine test; neither ran in any workflow. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(pi): never overwrite a configured Pi steering mode set_steering_mode persists to Pi's global settings.json. Selecting `all` on every session start silently rewrote the user's standalone Pi preference and undid any `/steering` choice on the next run. Select `all` only while neither the global nor the project settings configure a mode. PiHarness::with_agent_dir lets tests (and callers) pin PI_CODING_AGENT_DIR for both the child and Zeron's own reads, so fixture tests never consult the developer's real Pi settings. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(ios): don't trap on duplicate question ids when prefilling answers Dictionary(uniqueKeysWithValues:) crashes on a repeated key; question ids come from agents and synced docs, so keep the first instead. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * style(pi): rustfmt the steering-mode guard and its tests Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(pi): start fresh with a notice when a session can't be restored The native driver hard-failed a resume whose Pi session file was missing. The engine injects the chat's stored session id on every dispatch, so one unwritten or deleted session file left the chat failing every message for good. The ACP adapter and the Codex driver start a new session and announce the lost context instead; do the same. Proven-empty sessions still keep their UUID via --session-id. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(pi): never fail a turn over an attachment Pi can't inline Composer uploads include SVG, HEIC, BMP, TIFF and AVIF. The native driver errored the whole run on any of those (or an unreadable path), while the Claude driver skips them and the retired adapter ignored attachments: the path refs already ride the prompt text. Load images best-effort instead. Also give native startup the 120s budget the ACP handshake gave Pi, since extensions can start cold. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * style(pi): rustfmt the lost-session live test Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Wing <contact@winglee.io> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
14 KiB
ACP integration: shared harness + Grok Build (2026-08)
Decision
-
Add an ACP harness (
crates/harness/src/acp/) speaking Agent Client Protocol v1 — JSON-RPC 2.0 newline-framed over stdio, same wire shape as the codex app-server — over the sharedcrates/harness/src/jsonrpc.rsclient (promoted fromcodex/rpc.rs). Wire types are hand-rolled tolerant serde against rawValues (house style, verified againstagent-client-protocol-schema1.3.0), NOT the official SDK crates: zeron keeps its own child-lifecycle hardening (StderrTail, SIGTERM→SIGKILL, PATH composition) and shell-script test fixtures, and drives raw updates the SDK'sActiveSessionabstraction hides. -
First registered agent: Grok Build (
grok agent stdio), xAI's native ACP agent (npm@xai-official/grok, ACP registry idgrok-build). Auth: browser OAuth orXAI_API_KEY; zeron passes env through.GROK_EXECUTABLEoverrides resolution (tests point it attests/fixtures/fake-acp.sh). -
claude/codex converted to ACP too (2026-08-08, wing's call: "keep things clean"):
AcpHarness::claude()via@agentclientprotocol/claude-agent-acp(pinned 0.66.0) andAcpHarness::codex()via@agentclientprotocol/codex-acp(pinned 1.1.14), resolved from PATH or via the managed install (below). The bespoke stream-json/app-server adapters (~4,300 lines) are deleted; the catalogs (models, effort clamping, Ultrathink prefix) survive as spec inputs. Accepted deltas: Claude steering is now priority-nowpre-emption (adapter semantics) instead of step-boundary stdin; sandbox policy control is adapter-owned; zeron-specific settings ride config options where advertised (mode → bypassPermissions, model via family-alias matching — the claude adapter advertises SDK aliases likeopus[1m]/sonnet/haiku— fastMode/thinking as booleans) and are silently skipped elsewhere (ultracode has no adapter surface today). AskUserQuestion arrives as a question-shapedsession/request_permission(options without allow/reject kinds) and bridges to the input panel; allow/reject-shaped requests auto-accept. Per-turn usage comes from the settled prompt response. -
Hermes + Pi registered (2026-08-08):
AcpHarness::hermes()runs Nous Research's native ACP server (hermes acp; Python install viacurl -fsSL https://hermes-agent.nousresearch.com/install.sh | bashplus the.[acp]extra — no npm fallback, so resolution is PATH/~/.local/bin/~/.hermes/binonly,HERMES_EXECUTABLEoverrides). No_session/steeringextension and no effort config advertised (Hermes 4's hybrid reasoning is model-internal) → turn-boundary steering, empty ladder; the model list is discovered over ACP (below), with the Nous flagships as the static fallback. Pi migrated to native RPC on 2026-09-29; see Pi integration. Its former ACP adapter is no longer installed or launched. -
Devin registered (2026-08-15):
AcpHarness::devin()runs Cognition's native ACP server (devin acp; install viacurl -fsSL https://cli.devin.ai/install.sh | bashorbrew install --cask devin-cli— no npm fallback, so resolution is PATH/~/.local/bin/homebrew bins only,DEVIN_EXECUTABLEoverrides; the agent is also in the official ACP registry, iddevin). No_session/steeringextension → turn-boundary steering. Nothought_levelconfig option — effort is baked into the advertised model ids (claude-5-fable-high), so the descriptor ladder stays empty; the model list is discovered over ACP (below) with two flagship rows as the static fallback. Unattended parity rides the mode select'sbypassvalue (added to the generic no-prompts preference list). CLI 3000.6.14 also exposes subagent lifecycle and child transcript updates when the client advertisescognition.ai/subagentSupport; Zeron correlates the child agent id back to the parent'srun_subagenttool-call id and routes the tagged messages, thoughts and tools into a nested transcript. The separatecognition.ai/subagentControlextension stays disabled until Zeron has a foreground/background control surface. Resume quirks verified live (3000.6.14):session/loadreplays the full history (dropped, the doc has it) and then continues normally; a turn that was cancelled leaves its user message in Devin's history with no reply, so the next prompt after a resume may answer BOTH the new prompt and the stale one (SWE-1.7 did exactly that).session/loadalso refuses with-32015 "already open in another process"while a previousdevin acpstill holds the session — the shared driver's fresh-session fallback covers that, at the cost of Devin-side context. -
ACP is the source of truth for model lists (2026-08-08; preference order inverted 2026-08-09):
models()runs a short-lived probe (initialize →session/new, thediscover_commandspattern) and reads themodelconfig option's choices FIRST, falling back to the legacy first-classmodelsstate (SessionModelState) only when no model config option is advertised. The original order (legacy state first) put one row per model × effort in the picker: codex-acp enumeratesgpt-5.6-sol[low]…[ultra]on the deprecated surface while itsconfigOptionscarry base ids with effort as a separatethought_levelselect — the same reason Zed deleted its model-API support outright (zed@c413552859). 1M-context variants (opus[1m]display form,claude-…-1mSDK form) collapse into the base row's Context Window trait when the bare id is also advertised, and stand alone otherwise. Traits come off the wire too: every select/boolean config option outside mode/model/thought_level becomes aModelOption(codexfast-mode— its service tier — andcollaboration_mode;currentValuedoubles as the default choice), so the static catalogs' option sets now only apply on the legacy-fallback and probe-failure paths. The catalog still enriches matched ids (label/description/curated per-model ladders); discovered models otherwise inherit the probe session'sthought_levelladder plus the spec'sladder_extras(Claude Ultrathink — a prompt-prefix mode the wire can't advertise). Revisit a Kimi-style per-model walk if an agent genuinely varies ladders per model.
Protocol surface used (v1)
initialize(protocolVersion 1; fs/terminal client capabilities declined) →session/new/session/load(fresh-session fallback; replay drained, the doc already holds history) →session/promptper turn; the prompt RESPONSE carries thestopReason(cancelled→ Interrupted,refusal→ Errored, else Completed).session/cancelis the interrupt; SIGTERM/SIGKILL escalate.session/updatenotifications →AgentEvent: message/thought chunks → Text/ReasoningDelta;tool_call/tool_call_update→ typed ToolCall (kind + rawInput + locations + diff content) + ToolResult carrying capped output text and inline diffs (16KB/64KB harness caps; 4KB/16KB doc caps inparts.rs— the session-load-size discipline);plan→ToolCall::Todo(stable idacp-plan);available_commands_update→AgentEvent::AvailableCommands.usage_updateis a context gauge, not per-turn tokens — deliberately unmapped.session/request_permission→ auto-accept the preferred allow option (allow_always>allow_once> first) — parity with claude bypassPermissions / codex approvalPolicy never. Question-shaped means some option lacks an allow/reject kind — kinds legitimately repeat (codex sends TWOallow_alwaysoptions on every exec approval: "Allow for Session" + a prefix-rule amendment; treating duplicates as questions re-prompted the user for every command, 2026-08-09). The forced no-prompts mode matches per-adapter naming: claudebypassPermissions, codexagent-full-access.- Session config options: ACP has no per-prompt model field; the run's
model + reasoning apply through
session/set_config_optionagainst the session response's advertisedconfigOptions(categorymodel/thought_level, matched to advertised value ids, skipped when current, never fatal). Grok's effort ladder in the picker is Low/Medium/High →low/medium/high; other zeron levels degrade down a preference ladder (config_option_sets). - Steering:
_session/steeringextension wheninitialize._meta.steering.supported(org adapters); request carries_meta.steering.idleBehavior: "promptRequired"so a turn-end race hands the text back instead of firing an untracked turn. Without the extension (Grok): queue and deliver as the nextsession/prompt—SteeringMode::TurnBoundary. Session parks between turns while the steering mailbox lives (codex pattern). - Ordering hazard fixed twice: responses resolve via the pending map while
notifications ride the incoming channel, so (a)
request_drainingflushes the channel aftersession/loadresolves, (b) the turn arm drains queued updates before emitting Done, (c) EOF right after a final response reads as a clean finish (50ms turn-future grace), not a crash.
New shared surface
Harness::commands()(default empty) +ListCommandsRPC (mirrors ListModels, relay-forwardable) → composer/popup (mirrors the file-mention popup; localfilter_indicesranking, no per-keystroke RPC).AgentEvent::ToolResult{output?, diff?}→MessagePart::Tool{output?, diff?}→ doc columns (output,diff— additive, TS mirror updated in render-parts.ts/control-types.ts) → expandable transcript chips (tool_detail_lines:similarline diff, context collapsed to⋯, 12-line cap, analytic heights).
Managed adapter installs (2026-08-15)
- The
npx -y <pinned>fallback put every user's npm state in the chat hot path and was the root of the "harness protocol error … exit code 254" class of report (zeronsh/comet#95): npm encodes fatal fs errors as256 - errnoexits (254 = ENOENT, 243 = EACCES — npm/cli#4838), often with no stderr, and a coldnpxcould also stall a first chat for minutes while it downloaded the adapter's dependency tree (claude-agent-acp's is ~570MB). - Replaced by
adapter_install: pinned packages install ONCE into~/.zeron/adapters/<pkg>/<version>($ZERON_ADAPTERS_DIRoverrides) with a zeron-owned npm cache beside them, atomically (tmp dir + bin-entry verification +.zeron-install-okmarker + rename), then every launch isnode <entry>directly. Discovery probes never block on npm (background install + static-catalog fallback);run()blocks, and install failures carry npm's full output plus the decoded errno. The engine prewarms adapters for present CLIs at boot. Handshake additionally bounded at 120s (a hung agent used to spin "Working" forever).
Citations
agentclientprotocol.com (v1 spec + schema), agentclientprotocol org repos
(claude-agent-acp v0.66.0, codex-acp v1.1.14 — steering wire shape),
agent-client-protocol-schema 1.3.0 (serde tags), ACP registry entry
grok-build, live grok agent stdio initialize handshake (2026-08-07).
Pending prompts and silence (#296, 2026-09-09)
A completed tool result, partial assistant message, or usage update can precede
another model request. None proves that session/prompt has finished. The old
30-second blanket quiet settlement discarded the outstanding response future,
then allowed another prompt into an agent that was still busy. The next request
could fail with Invalid request and its specific error.data was discarded.
The ACP quiet timer and ZERON_ACP_QUIET_SETTLE_MS override are retired. Pending
prompts retain their response futures; boundary steers remain queued. Explicit
completion extensions and noRunningTurn recovery retain their existing roles.
Cancellation still sends session/cancel, awaits completion, and escalates to
process termination if needed. The engine also exempts authoritative pending
prompts from its quiet watchdog, including when a diagnostic window is set;
unowned self-continued activity retains its fallback. RPC errors include their
code and non-null data, preserving the agent's explanation in the terminal event.
Regression checks:
cargo test -p zeron-harness
cargo test -p zeron-engine --test acp_lifecycle
The stateful Python peer rejects overlapping prompts. Coverage includes quiet periods after four completed reads, partial text, reasoning, usage, open tools, multiple queued follow-ups, EOF without a response, cancellation, an unresponsive agent, and structured error details. The engine test checks Working status and transcript boundaries with a 100ms watchdog, then verifies autonomous activity still settles.
For real-model testing, configure an isolated authenticated Pi agent directory,
select a model in its settings, and load
crates/harness/tests/fixtures/pi-slow-model.ts (for example, symlink it into that
agent directory's extensions/ directory). The extension waits 35 seconds before
sending the next model request after a completed tool. It does not delay tool
results or synthesize an ACP completion. Then run:
PI_CODING_AGENT_DIR=/path/to/isolated/pi-agent \
PI_EXECUTABLE=/path/to/pi \
ACP_TEST_RUNS=3 \
cargo test -p zeron-harness --test real_acp_lifecycle -- --ignored --nocapture
These tests require successful real calls; missing authentication or an unloaded
delay extension fails rather than skips. Historical ACP verification used pi-acp 0.0.33,
Pi 0.85.1, and gpt-5.6-luna: three sessions each completed the original turn and
two queued follow-ups after 36.6–36.8-second post-tool gaps; cancellation during a
32-second post-tool gap also completed as Interrupted.