Skip to content

Latest commit

 

History

History
18 lines (16 loc) · 13.1 KB

phase-4.md

File metadata and controls

18 lines (16 loc) · 13.1 KB

Phase 4: ACP (L2) and approvals

Exit criteria (roadmap): Claude Code, Codex and WrongStack in structured mode (ACP or adapter) with approvals answered from the window. Items that need real agent accounts are marked and skipped, never faked.

Task State Notes
P4-01 ACP client done (against a fake ACP agent) agora-adapters::acp: agora acp-bridge -- <agent argv> is the ACP client towards the agent and an adapter towards the node; manifests say [structured] acp = { argv = [...] }; kinds report level L2; tested end to end with agora-fake-agent --acp (bridge unit and integration tests, and a real node through the CLI). Mapping in docs/specs/adapter-protocol.md. Gaps found with opencode 1.1.59 (#401): failed, stopped and empty turns carry reason codes, an agent's exit (also before initialize) is reported with stage, exit code and a redacted stderr tail, and usage_update cost becomes usage/report (adapter-protocol.md "Turn and exit reasons"). ADR-0058 (accepted) stage 1 done: notices in the conversation (CHAT_KIND_NOTICE), a failed start answers adapter.agent_exited / adapter.agent_refused instead of internal, session/options + AgentSessionOptions, session/set_option behind agent.set_mode / agent.set_model (node and hub capabilities), context level and size and the agent's own cost in AgentUsageReported and the snapshot; tested with the fake ACP agent through the bridge and a real node. Stage 2 done: the web conversation renders notices from notice-* locale ids and has a session bar (mode and model pickers, a confirmation before a mode that skips permissions, context fill, the agent's own cost); the terminal client shows notices and the session line and switches with /mode and /model. Not done: a run against a real ACP agent (opencode) to check the mode list and the permission marking in practice
P4-02 structured chat view done the node keeps each chat agent's transcript and streams it (chat.subscribe, ADR-0038); the console shows the conversation with a prompt box; plans, tool calls and diffs have their own rendering: a tool call reads as one line (the agent's title, or what it did when it gave none, and its command, file, search or address) with its full input folded underneath, steps in a row form one list that shows its last three, a diff shows the file, +N −M and coloured lines, only the latest plan stays open, and agent text draws its code blocks, inline code, lists and headings (as text, never HTML); an ACP approval's detail names the command or file when its input reads as JSON (apps/web/src/net/tool.ts, net/markdown.ts; docs/screenshots/chat/)
P4-03 approvals queue across clients done the console lists waiting approvals from every machine and answers them with this browser's device key; hidden-tab notifications; stale approvals are cleared when a node restarts
P4-04 node-local policy and user-signed approvals done (ADR-0020, ADR-0028) trusted-devices file reloaded when it changes
P4-05 real agents in structured mode Claude Code and Codex manifests done, WrongStack open manifests/agents/claude-code.toml with screens captured from Claude Code 2.1.319 on the maintainer machine with its signed-in account (no tool run; one one-word prompt, about $0.05; a dedicated account would still be cleaner) (trust prompt → blocked, working with esc to interrupt, idle prompt box; fixtures/claude-code/, checked by tests/shipped_manifests.rs); launch, --mcp-config mesh injection and --resume use flags checked against that version's --help. manifests/agents/codex.toml likewise from codex-cli 0.167.0 (idle › prompt box, Working (… esc to interrupt)), same machine and account, one one-word prompt; codex resume checked against --help. Tool-permission prompts of both are captured too (a touch probe.txt request in a scratch directory, cancelled with Esc, nothing ran; permission.screen → blocked). manifests/agents/wrongstack.toml from WrongStack 1.5.3 (Z.AI coding plan on the maintainer machine, one one-word prompt on the cheapest model; --skip --tui launch so no menu or startup question waits for a key; idle, working (⠙ bamboozling… in the input box title), approval prompt (touch probe.txt, never approved; the process was killed) and answered screens in fixtures/wrongstack/; --mcp-config and --resume sess_… checked against --help and a real resume of a saved session; a live session did use the mesh tools: asked to call task_create on the agora-mesh server, WrongStack found mcp_use, called it and got {"task_id":"t-1"}; the same run found that agora agent prompt sent the text and Enter in one write, which WrongStack took for a paste, so the prompt sat unsent in its input box: the node now writes the Enter 150 ms after the text; WrongStack's prompt refiner holds a prompt for about 3 seconds after Enter unless another key is pressed, which the manifest does not handle). manifests/agents/wrongstack-acp.toml is the L2 entry point (wstack acp serve): agora acp-bridge initialised it and got a session and an IDLE state with no model call (a turn was run later through a real node: agora agent start wrongstack-acp, then agora agent prompt with a one-word request on the cheapest model; WrongStack answered "ok" and kept the conversation in its own acp-sessions file; the run found that agent list kept showing unknown because the bridge named its states IDLE instead of AGENT_STATE_IDLE, fixed in the bridge). ACP entry points of the other two (checked with --help on 2026-11-09): Claude Code 2.1.319 has none and Codex 0.167.0 has only app-server, an experimental server with its own protocol (not ACP), so neither gets an L2 manifest until they ship one or an adapter is written (L3). Usage sources are done for all three (ADR-0042, accepted: [usage.file] in the manifests, read by agora-node::usage_files, tested against scrubbed lines of the real shapes and through a real node, WrongStack's llm_response lines included). An agent that exits is read one last time, so its last second is kept (test usage_files_last). Not done: hooks ([hooks]: installing a reporter into the agent's settings, its own decision). Codex mesh injection is done: cli_flag without a path plus {socket_toml}/{mcp_command_toml} placeholders pass the server as -c mcp_servers.agora-mesh… overrides (the override form was checked with codex mcp list; a live Codex session using the mesh tools was tried and stopped at Codex's own "hook needs review" dialog, which waits for the user's trust decision on a lifecycle hook in their config; the manifest now reports that screen as blocked (hook_review, fixture hook_review.screen) and the mesh call itself is still untried on Codex)
P4-ADR57 agents start agents (ADR-0057) done except another machine schema (stage 1). Node and mesh: agent_start, agent_wait and agent_output (capability mesh.spawn, agora-node::spawn), the signed agent.start decision over a hash of the request, the helper grant (listed and revoked with the grant commands, ends with its agent), the folder ceiling, depth/helper/pending/prompt limits and the rate, parent_agent_id on every AgentStarted, AgentStop.stop_helpers, hub audit rows; tested with the fake agent in crates/agora-node/tests/agent_spawn.rs. Clients: the web window shows helpers under their parent ("started by …" in the tree, the tile and the pane), an approval card for agent.start with the folder (marked when outside), the whole prompt and the grant choice ("up to 3 like this while it runs", "its helpers may ask too"), signed over the request as shown, and an agent's live helper permissions with Revoke (docs/screenshots/agent-start-*.png); the TUI lists helpers under their parent, shows a start request with its whole prompt (control characters dropped), answers it with the start signature (one start, no grant), and x on an agent with running helpers asks whether they stop too (yes unless n). A helper grant ends for good when the device that signed it is no longer trusted (untrusted, ran out or narrowed to other projects; audit F270 #649 and F290 #656). Not done: starting a helper on another machine; the web window has no stop button, so its "stop the helpers too?" question exists only in the TUI
P4-ADR60 session ledger and Resume (ADR-0060) in progress Stage 1 done: schema (AgentInterrupted event 38, AgentResume command 87, AgentSnapshot 40-43, error codes agent.not_interrupted, agent.session_missing, agent.folder_changed, agent.parent_not_running, golden fixtures), the hub keeps interrupted agents with the closed ones, and the node's owner-only ledger (agora-node::ledger, learns from the events it records; ids never reused). Stage 2 done: the node reports interrupted agents after it starts and in every resync (AgentInterrupted), agent.resume (capability agent.resume, signed like agent.launch on the routed path, Resume or Start again, folder identity check, helpers only under a running parent without their grants), `resume = ask
P4-ADR59 launch options (ADR-0059) in progress Stage 1 done: schema (AgentStart/AgentLaunch.launch_options, AgentKind.launch_options of LaunchOption, AgentStarted/AgentSnapshot fields 30-31), error code agent.option_forbidden, manifest [[launch.option]] (engine 2) with the flags checked on real versions (Claude Code 2.1.323, codex-cli 0.167.1, WrongStack 1.6.0; agy 1.5.6 as seen on Windows). Stage 2 done: node policy skip_permissions (default allow, typo forbids), enforcement before anything starts (confined_only needs active confinement), arguments on the command line / ACP server command for the agent's life, directory-action-v3 signature over the ids and the confirmed ids (length-prefixed lists, shared vectors), routed AgentStart with options refused, helpers never get one, hub capability check, snapshot fields and audit rows; tested with the fake agent (tests/launch_options.rs, agent_spawn.rs). Stage 3 done: the web start window's "How it acts" choice with the ADR-0058-style confirmation (Keep asking primary), the signed choice (directory-action-v3), the "Does not ask" badge in the tree, tile and pane header (docs/screenshots/adr59-*.png, both themes), and the TUI start flow and badges; en+tr. Not done: per-kind defaults (ADR-0059 point 6, a later decision); choosing an ACP mode that skips permissions at start (open question); the one-time acceptance screen a skip flag may show (Claude Code "Bypass Permissions mode") still needs a captured fixture and a blocked rule (macOS task)
P4-ADR66 start with model, effort and mode (ADR-0066) in progress PR 1 done (#605, in 0.3.14): [[launch.setting]] in manifests (engine 3), AgentStart/AgentLaunch.settings, AgentKind.settings, the node's checks before anything starts, agora agent start --setting model=... --setting effort=.... PR 2 done (#653): a launch with settings through the hub is signed (directory-action-v4), an agent's agent_start with settings over agora-approval-start-v2, capability agent.launch_settings, the web approval card lists the settings. Not done: the start window's and the terminal client's pickers, the terminal client's card, remembering the last choice
P4-ADR69 a missing agent kind says why (ADR-0069) done PR 1 done (#598): AgentKind.program, NodeOnline.binary, NodeSnapshot.binary, capability kinds.program. PR 2 done (#599): the web start window names the program a machine cannot find, and the trust command runs agora from its folder when it is off the PATH. PR 3 done (#606): the terminal client names a missing agent's program and where agora is.
P4-ADR80 the file browser does not show secret files (ADR-0080) node side done #636: a node marks files secret by name (FileEntry.secret), files.read refuses with files.secret, git.diff names a changed secret file with its line counts and no hunk; the owner's policy files.show_secret = true switches it off and agora doctor warns when it is on. Not done: the marker in the web window and the terminal client (client markers are separate work)