Proposal: Agent Client Protocol (ACP) interface for Maka (maka --acp) #3132

Activity

1. Astro-Han

   added

   enhancementNew feature or requestNew feature or request

   on Aug 17, 2026
2. Sun-GLiang commented on Aug 20, 2026

   

   Sun-GLiang

   on Aug 20, 2026

   Member

   More actions

   hanks for the detailed proposal. I’d like to work on this and own the issue through the initial ACP v1 implementation.
   Given the scope, I suggest landing it incrementally:

   1. An ACP v1 vertical slice: maka --acp, stdio transport, initialize/new/prompt/cancel, ordered text/thought/tool streaming, permission handling, tests, and a real-client smoke test.
   2. Session persistence and configuration: list/load/resume/close, transcript replay, interrupted-turn recovery, modes, and configuration options.
   3. Maka-specific extensions, the capability matrix, and broader compatibility hardening. If the branch/revision/artifact/memory/goal/plan extensions are expected to be fully implemented initially, I’ll split those into focused follow-up PRs.

   I’ll keep ACP v2 and steering outside the initial scope, as described in the proposal. Are maintainers comfortable with this breakdown and assigning the issue to me?
3. shaokeyibb commented on Aug 22, 2026

   

   shaokeyibb

   on Aug 22, 2026

   Contributor

   More actions

   By the way, once the ACP integrated is implemented, could you add a new feature to support adding any ACP service in a Workspace as a subagent to facilitate the scheduling of these ACP services?

   👍React with 👍2Reacted by AstroHan and Sun-GLiang
4. Astro-Han

   assigned

   Sun-GLiang

   on Aug 23, 2026
5. Astro-Han

   added

   help wantedExtra attention is neededExtra attention is needed

   on Aug 23, 2026
6. Sun-GLiang commented on Aug 23, 2026

   

   Sun-GLiang

   on Aug 23, 2026

   Member

   More actions

   Thanks for assigning this to me. I’ll start working on the implementation.
7. Sun-GLiang commented on Aug 23, 2026

   

   Sun-GLiang

   on Aug 23, 2026

   Last edited by Sun-GLiang

   Member

   More actions

   ACP v1 implementation tracker

   English

   Progress snapshot (2026-09-27)

   • All eight planned PR checklist items have merged: 10 delivered PRs in total because PR 5 was split into three. The original combined #5222 was closed without merging; its scope was delivered by #5384, #5385, and #5386.
   • This issue remains open with three issue-level acceptance checkboxes below: one combined branch/revision-target → Artifact/Memory path, final integrated validation (including the Desktop Electron E2E and Windows/Linux runs not repeated on the PR 8 head), and reconciliation of the capability matrix and client/SDK evidence with the final integration results. Passing per-PR build and test evidence is recorded below.

   Current-code baseline

   • Status checked against main@86c61d420 on 2026-09-26 after PR 7 and PR 8 merged.
   • PR 1 (#3658) landed the maka --acp stdio server, official @agentclientprotocol/sdk@1.4.0 dependency, protocol-only stdout, explicit unsupported-method errors, and the reusable official-SDK child-process harness.
   • PR 2 (#3744) landed lazy Runtime Host bootstrap plus durable Session creation and bounded listing without subscription attachment.
   • PR 3 (#4051) landed Host-backed ACP configuration projection and CAS updates. PR 4 subsequently addressed post-create Session reachability and subscription-driven option refresh.
   • PR 4 (#4862) merged on 2026-09-13. PR 5 and PR 6 subsequently merged; PR 7 (#5685) and PR 8 (#5734) both merged on 2026-09-26.
   • Current Runtime Host ClientHello no longer has a ClientSurface; the private surface: 'desktop' field is only a legacy compatibility shim. ACP must not add a new ClientSurface value.
   • Reuse the existing RuntimeHostConnection, ClientSessionSubscription, RuntimeHostSessionProjector, transcript paging, and reconnect/recovery behavior instead of creating a second Runtime Host client stack.
   • This baseline records the merged PR work; revalidate it against the latest main for any follow-up work.

   Tracking rules

   • A PR checkbox is marked complete only after the PR is merged.
   • Every PR must be independently reviewable and testable.
   • Each PR may depend only on already merged prerequisites.
   • Tests for behavior introduced by a PR must land in that PR.
   • New interfaces and modules must be consumed by a production ACP route or execution flow in the same PR, verified through the official SDK and real ACP/Host path.
   • Reuse existing registry, configuration, attachment, projection and Host operation seams. Extract shared logic with its actual callers; introduce extension routing with the first concrete method that consumes it.
   • Update documentation and capability declarations with each feature. Use third-party ACP clients for standard interoperability and SDK production-route tests for extensions.
   • Runtime Host remains the single execution and state authority.
   • Unimplemented ACP methods return explicit protocol errors.
   • Existing Desktop, TUI, CLI, and Eval behavior must remain unaffected.

   Dependency graph

   flowchart LR
       PR1["PR 1"] --> PR2["PR 2"]
       PR2 --> PR3["PR 3"]
       PR3 --> PR4["PR 4"]
       PR4 --> PR5["PR 5"]
       PR5 --> PR6["PR 6"]
       PR5 --> PR7["PR 7"]
       PR6 --> PR8["PR 8"]
   

   Loading

   ---

   Phase 1 — ACP foundation

   • PR 1 — Add the maka --acp stdio server foundation

     • Add the official @agentclientprotocol/sdk dependency, lockfile changes, and regenerated CLI third-party notices.
     • Add an acp command kind before the current generic TUI --flag parsing path, and update CLI help and parser tests.
     • Wire stdio through ndJsonStream and agent(...).connect(...) with the Maka ACP Agent implementation.
     • Keep startup and initialize transport-only; do not connect to Runtime Host until an ACP method requires Host-backed session or runtime state.
     • Implement ACP initialize without adding a ClientSurface field or value.
     • Keep stdout protocol-only and diagnostics on stderr.
     • Return explicit errors for ACP methods not implemented yet.
     • Add a reusable child-process stdio/ACP test harness.
     • Acceptance: maka --acp starts an ACP v1 stdio transport, completes initialize without requiring Runtime Host, rejects an unsupported method explicitly, and shuts down cleanly without changing existing CLI commands.
     • Depends on: none
     • Status: merged on 2026-08-26
     • PR: #3658

   • PR 2 — Map ACP session creation and listing

     • Extend PR 1's transport-only startup by taking ownership of the deliberately deferred Host bootstrap: lazily create one connection-only CLI Runtime Host context through connectRuntimeHostCliConnection when the first Host-backed ACP method is called; share it across the ACP connection and close it exactly once when the ACP stdio connection terminates or Runtime Host bootstrap is aborted. Do not make ACP Session operations depend on the unrelated model connection catalog.
     • Map session/new to session.create, generating sessionId in the adapter, mapping cwd to a host_path workspace, and always using the Host default modelTarget.
     • Accept empty mcpServers and additionalDirectories, reject non-empty values explicitly, and ignore ACP _meta without defining a private Project ID contract.
     • Establish one focused ACP session registry for durable-session creation, listing, and idempotent connection-level shutdown. PR 2 retains no per-session adapter state: it does not track ownership and does not open, retain, or consume a Runtime Host subscription. PR 3 introduces current-connection ownership when configuration routing becomes its first production consumer; subscription attachment moves to PR 4's first session/prompt.
     • Map session/list through a reusable single-page Runtime Host catalog reader and a size-bounded, strict opaque ACP cursor bound to the normalized cwd filter; surface revision changes as stale-cursor parameter errors and skip unmappable legacy records. Require canonical base64url and exactly the current revision, cursor, and cwd fields. Defer cursor versioning until a concrete compatibility need exists.
     • Make the full-catalog reader normalize RuntimeHostSessionCatalogRevisionChangedError on both the first-page and continuation paths instead of exposing a narrower implementation detail to callers.
     • Do not implement or advertise session/close in PR 2; it continues to return -32601, and PR 4 explicitly owns cancel-active-turn → close-subscription → remove-adapter-state semantics.
     • Never delete or archive a durable Runtime Host session during adapter cleanup. Adapter EOF only closes the owned Host connection; PR 2 has no connection-local per-session state to clear.
     • Update maka --help so it no longer describes the ACP surface as initialize-only and states the methods available at this stage.
     • Test bounded catalog pagination, cwd filtering and stale cursors, first-page revision-change normalization, multiple-session isolation, more than 16 creates on one ACP connection without subscription attachment, shutdown races, unsupported inputs, and stable Runtime Host error translation with the official SDK client and a real Runtime Host process. Assert that session/new and session/list never call subscription.open.
     • Acceptance: an ACP client can create more than 16 independent durable sessions and list them with bounded pagination without opening a subscription; Runtime Host is connected only when Host-backed Session work begins, the lazily created connection-only CLI context is closed exactly once when the ACP stdio connection terminates or Runtime Host bootstrap is aborted, durable sessions remain owned by Runtime Host, and session/close remains unadvertised.
     • Depends on: PR 1
     • Status: Merged on 2026-09-02
     • PR: #3744

   • PR 3 — Expose Maka session configuration through ACP v1

     • Return ordered ACP select configOptions from the committed Runtime Host SessionCatalogProjection in every successful session/new response: permission, collaboration, and orchestration are always present; thinking is present only when the selected model declares supported thinking levels.
     • Derive selectable values from the canonical core lists. Map permission_mode to permissionMode with selectable ask and bypass; a pre-existing explore Session may report it as the current value but ACP cannot select it. Map collaboration_mode to collaborationMode (agent, plan) and orchestration_mode to orchestrationMode (default, swarm, graph).
     • Resolve thinking_level from the selected model in the Runtime Host connection catalog. Non-reasoning models omit the option; reasoning models advertise default (Host null) plus exactly the model's declared thinking levels.
     • Introduce a lightweight current-connection ownership set from successful session/new results, and route ACP v1 session/set_config_option only for session IDs in that set; do not use a live subscription as proof of ownership. Reject unknown option IDs, wrong value types, and unsupported values before Host I/O.
     • For every live change, read the current catalog projection and call session.configuration.update with expectedRevision and a one-field SessionConfigurationPatch. Runtime Host merges the patch into the current configuration and commits the complete result, preserving modelTarget and all unchanged fields.
     • On revision_conflict, re-read the projection and retry the complete update, with a hard maximum of three attempts. Share neutral Session lookup/projection and bounded CAS retry with the CLI/TUI session driver while keeping ACP lifecycle checks and structured error mapping at the ACP boundary.
     • Return the complete advertised option projection from the committed Host result. Preserve Runtime Host state/conflict codes such as session_busy and operation_conflict in error.data.code without classifying them as malformed JSON-RPC parameters.
     • Keep session/set_mode unsupported and unadvertised. ACP session/new has no configuration/mode input, so PR 3 does not represent create-time SessionStartMode and does not pretend it is mutable.
     • Keep workspace-instruction composition in Runtime Host instead of inventing an ACP-side system-prompt authority.
     • Test canonical and model-specific option projection, CAS and conflict retry behavior, ownership and shutdown boundaries, official SDK routing, stdio responses, and real child-process + Runtime Host create → configure flows for reasoning and non-reasoning models. Configuration must not require or open a subscription.
     • Acceptance: session/new returns the model-appropriate Host-backed configuration options without attaching a subscription; explore is not selectable; and session/set_config_option changes exactly one supported value through Runtime Host CAS without overwriting model selection or unrelated configuration. Three consecutive conflicts terminate deterministically, while session/set_mode remains explicitly unsupported.
     • Depends on: PR 2
     • Status: Merged on 2026-09-07 as b67778abd; required CI passed.
     • PR: #4051

   • PR 4 — Attach live sessions and map prompts, cancellation, close, and ordered core streaming

     • Keep durable-session ownership separate from live attachment state. For a session owned by the current ACP connection, make the first session/prompt single-flight attach one Runtime Host subscription and start consuming it before turn.start, so no early frame can be missed; later prompts reuse the live attachment.
     • Harden the existing AcpSessionRegistry.#create lifecycle boundary before attachment: after Runtime Host creation succeeds, prefer returning the created sessionId while omitting optional configOptions if option projection fails; do not grant mutation ownership before ACP returns that id. If rollback is chosen instead, define durable-Session deletion and cleanup-failure semantics first.
     • When an attached Session's model or configuration changes outside ACP, consume the authoritative subscription update and emit ACP config_option_update with the full refreshed option projection, including addition or removal of thinking_level; define ordering against session/set_config_option responses and suppress updates after close.
     • Keep the one-shot open operation only on the reconnecting Runtime Host connection, where it guarantees that attachment never silently lands on a replacement Host epoch; do not add a duplicate alias to the concrete base connection interface.
     • Map session/prompt to turn.start only after attachment succeeds, generating the required turnId and converting supported ACP prompt content to Maka MessageContent. An attachment failure must not start a turn or modify the durable Session.
     • Map session/cancel to turn.stop using the authoritative sessionId, turnId, and runId from the current subscription snapshot.
     • Reuse RuntimeHostSessionProjector/session-channel behavior for sequence validation, delta folding, active-stream recovery, and terminal-turn detection.
     • Map projected text/thinking events to agent_message/agent_thought chunks and terminal complete/abort/error events to end_turn.
     • Do not add an ACP-side event sorter: the PR 4-owned subscription rejects sequence gaps and the projector already handles startOffset, reset, completion, and reconnect recovery.
     • Implement and advertise session/close. If a turn is active, cancel it first; then close the subscription and remove all adapter-owned attachment and ownership state. Closing an unattached Session only removes adapter-owned state. Never delete or archive the durable Runtime Host Session.
     • Retain a successful attachment until session/close or ACP connection shutdown. Rely on the Host's per-connection subscription admission instead of mirroring it with client-side counters; report capacity failure before turn.start, and make capacity reusable after close.
     • Do not export the Host subscription limit or add a protocol compatibility declaration solely for ACP-side capacity accounting.
     • Do not reintroduce a test-only inspect() API; attachment state must be consumed directly by prompt, cancel, streaming, and close behavior.
     • On subscription EOF or failure, terminate any affected prompt deterministically, release attachment resources, and allow a later prompt to perform a fresh one-shot attachment when the protocol state permits.
     • Before declaring prompt interoperability, run one real-client session/new/prompt smoke test (Zed if available), record the actual required mcpServers payload, and resolve whether non-empty client-provided servers remain explicitly unsupported or need a supported mapping.
     • Keep ACP event translation in a dedicated module with focused tests.
     • Test post-create catalog/projection failure and Session reachability, concurrent first prompts, attach-before-start ordering, attachment/cancel/close/shutdown races, subscription EOF and failure, Host replacement during one-shot open, external model changes that add or remove reasoning options, update ordering, more than 16 created-but-unattached Sessions, Host capacity rejection without turn creation, and slot reuse after session/close.
     • Acceptance: after Runtime Host creates a Session, ACP returns a usable sessionId or completes a defined rollback, so option projection cannot leave an unreachable durable Session; a client can then attach on first prompt, drive and cancel a complete turn, and close adapter-owned Session state without deleting the durable Session; offsets, resets, reconnects, and terminal states produce one ordered ACP stream and exactly one end_turn; externally observed model changes publish ordered config_option_update notifications with refreshed choices; more than 16 Sessions may be created without attachment, and subscription capacity is released by close.
     • Depends on: PR 3
     • Status: merged on 2026-09-13 as 6ce9c72c3; required CI passed.
     • PR: #4862

   ---

   Phase 2 — ACP v1 runtime capabilities

   • PR 5 — Complete tool execution, interactions and stdio MCP integration

     • Extend the existing prompt path: map tool_start to tool_call, and output/progress/preview/result events to explicit tool_call_update behavior. Preserve tool identity, sequence, stream, redaction, status and duration where representable, with bounded presentation state and explicit truncation.
     • Respect ACP tool-content replacement semantics. Reconcile cumulative live output with authoritative StoredMessage tool records; contentOmitted is not an empty result and argsPreview is not full input. Handle missing starts, duplicate sequences, late previews/results and slow-consumer recovery without duplicate cards or reopening terminal tools.
     • Connect transcript settlement/replacement to the mapper. Current-prompt result completion and recovery belong here, not in PR 6. Reuse existing paging, watermarks and fragment decoding; first verify the smallest necessary extension to the subscription/channel seam. Cached initial loadTranscript() is not refresh; do not blindly copy the TUI helper that opens an extra subscription and fails at full capacity.
     • Await necessary result reconciliation and notification delivery before normal prompt completion. Preserve PR 4's distinction between authoritative end_turn, explicit cancellation (cancelled) and projection/transport failures. Tool completion alone cannot terminate a turn; cancellation, failure and close must not wait forever for missing tool results.
     • Cover all five current InteractionRequest kinds: permission, question, form, sandbox_boundary, client_capability. Reuse pending/resolved snapshots, channel callbacks, core validation and typed interaction.answer; handle external answers, replay, late replies and Host closure reasons.
     • Use standard session/request_permission and capability-negotiated elicitation/create where they faithfully represent the request. Preserve grant target/scope, turn-limited permission, typed form values and decline/cancel semantics. Any required private representation must have its concrete route and SDK end-to-end consumer in this PR. Unsupported clients receive a defined failure/closure instead of an indefinitely pending interaction; no broader authorization is invented.
     • Support client-provided stdio mcpServers during session/new, replacing PR 2–4's temporary nonempty-list rejection. Validate names/command/args/env, map to existing in-memory MCP config with Session cwd, and reuse McpClientManager, createMcpCapabilityProvider and Host capability invocation/cancellation. Do not persist request commands/env into user MCP settings or add HTTP/SSE/OAuth management.
     • Prove Session isolation before choosing the smallest Host capability-seam extension: current connection-wide publication and affinity: session do not target a specific Session. Two Sessions on one ACP connection may supply different same-named servers. Registration/replacement/removal must affect only the target; scoped tools must not enter unrelated provider fallback. Preserve existing Desktop/TUI behavior and required protocol compatibility checks. Do not work around this by adding a Host connection per Session.
     • Complete MCP discovery/publication before admitting dependent turns. Define preparation failure, dynamic tool-list publication, cancellation, Host reconnect/republication and EOF cleanup. Prepare before durable creation where possible; any post-create failure must preserve a reachable Session ID under an explicit error/result contract. Close releases only adapter-owned registrations/processes after stopping execution, never the durable Session.
     • Verify create → prompt → MCP/tool invocation → permission/form answer → result → complete/cancel/close through production ACP routes.
     • Test official-SDK child process + real Host; single/concurrent/streaming tools; five interaction kinds and answer races; full subscription capacity; MCP discovery/call/cancel/exit; same-name cross-Session isolation; replacement and close isolation; reconnect and EOF; existing TUI/Desktop capability regressions.
     • Acceptance: an ACP client drives a complete tool-enabled turn, answers supported interactions and receives authoritative results; failure paths settle deterministically and release resources. Every new seam is exercised by this workflow.
     • Depends on: PR 4
     • Status: completed; all three split PRs merged by 2026-09-22. α merged on 2026-09-17 (672d82731), β on 2026-09-19 (852a9748d), and γ on 2026-09-22 (420c22186).
     • Delivered: ordered tool-card projection and authoritative result reconciliation; all five Host interaction kinds through ACP permission/elicitation; Session-isolated stdio MCP discovery, publication, invocation and lifecycle cleanup. PR 6 and PR 7 have since merged.
     • PRs: α #5384, β #5385, γ #5386. Split from the original combined #5222, which was closed without merging.

   • PR 6 — Load, reattach, resume execution, branch and revise Sessions

     • Implement and advertise session/load (replay history before responding) and session/resume (reattach without historical replay). Neither implicitly restarts an interrupted turn. Validate cwd and lifecycle inputs, return current configuration, and integrate successful attachment with the existing connection ownership set.
     • Reuse catalog lookup, subscription snapshot, active assistant streams, durable/overlay paging, cursors, watermarks and canonical recovery. Replay user/assistant/thinking/tool history through PR 5's projection where applicable; establish a nonduplicating handoff to live output. Partial failure releases attachment resources without deleting the Session.
     • Connect existing onTurnStarted and interaction callbacks so an already-live turn is observable without a new prompt. Maintain one event consumer per turn; a prompt response waits on that same observation rather than opening a second reader. Introduce non-prompt execution status representation with its actual load/resume consumer here, not prospectively in PR 5.
     • Add an explicit _maka/turn/resume workflow for interrupted execution. Query Host first, start only from a ready plan with source run/high-water identity, and surface parked reasons. Reuse/extract the neutral part of existing TUI resume logic only when both callers consume it; keep lifecycle control in their respective adapters.
     • Apply the caller's complete MCP list on load/resume through PR 5's Session-scoped integration. Do not recover commands/env from durable history or replay past tool calls. Host binding rules decide whether replacement is safe; active conflicts and incompatible interrupted contracts must not silently substitute a provider. Repeated equivalent attachment must not duplicate MCP processes.
     • Add concrete _maka/ routes for session.branch.create, session.revision.create and session.revision.abandon. Preserve source/target identity and expected source revision; grant a successfully returned target ownership so it can immediately be configured/prompted or loaded. Preserve reachability after Host commit if later projection fails.
     • Branching does not clone live MCP processes or credentials. Handle target attachment/execution before abandon and preserve Host abandoned versus retained; normal close is not deletion. Do not import TUI-specific local-storage cleanup authority.
     • Verify loading and continuing live/persisted Sessions, explicit interrupted execution recovery, branch/revision creation followed by a target prompt, and abandonment through production routes.
     • Test multi-page history, live/replay ordering, restored pending interactions, ownership/configuration, double load/resume, close/failure races, provider changes, parked recovery, branch continuation, revision conflicts and retained targets.
     • Acceptance: clients load, reattach, explicitly resume or branch/revise without replay gaps, duplicate execution, unreachable targets or resource leaks.
     • Depends on: PR 5
     • Status: merged on 2026-09-25 as 87217d370; PR 8 is unblocked.
     • Delivered/evidence: #5621 adds load/resume, historical and live Turn recovery without duplicate replay, Session MCP reconfiguration with cross-connection conflict fencing, explicit interrupted-Turn resume, and branch/revision routes. At head 745430a3c, the full CLI suite passed 1256 tests (3 skipped), the full Runtime Host suite passed 2127 tests (12 skipped), and the GitHub test check passed. Windows was not rerun at this head; see the PR verification and validation record for earlier Desktop E2E and Zed evidence limits.
     • PR: #5621

   ---

   Phase 3 — Maka extension namespace

   • PR 7 — Complete artifact and memory access

     • Add concrete _maka/ request/response routes for artifact.query, artifact.ingest, artifact.delete, memory.query and memory.mutate, with existing ownership/error checks and Host typed validation.
     • Consume artifact list/get/text/binary/chunk operations and multipart begin/chunk/finalization/cleanup variants supported by the current Host contract. Preserve revision/cursor, upload identity, offsets, limits and integrity checks. Tool-result artifact references must be readable/exportable through ACP, not merely returned as opaque IDs or inaccessible Host paths.
     • Exercise memory mutation through authoritative query and the next applicable turn's real context. Preserve Host scope/conflict semantics and document when changes take effect; do not promise mutation of already-running model input.
     • Keep persistence, authorization and conflict authority in Host. Add only the bounded client-side transfer orchestration actually consumed here; no generic CRUD layer, upload store or ACP-specific memory injection.
     • Register only these concrete methods. Reuse already-landed extension helpers if suitable.
     • Verify ACP upload → read/export → delete and memory mutate → query → subsequent turn through production routes, checking returned data and execution effects.
     • Test pagination/revision changes, chunked round trips and integrity, interrupted transfer, missing/deleted artifacts, mutation conflicts, reconnect and subsequent-turn memory consumption.
     • Acceptance: artifact and memory operations produce usable, verifiable results over ACP, with no dependency on later goal/plan features.
     • Depends on: PR 5
     • Status: merged on 2026-09-26 as 835112108; the PR 6 prerequisite was already merged.
     • Delivered/evidence: five private routes for Artifact transfer/read/delete and Memory query/mutation, including readable tool-result references and Memory in a later model request. SDK/real-Host tests cover bytes, pagination, recovery and Memory; full CLI test:dist passed 1278 tests (3 skipped), and GitHub test passed. No third-party private-extension UI smoke.
     • PR: #5685

   • PR 8 — Observable and controllable goal/plan execution

     • Add concrete _maka/ routes for goal.query, goal.arm, goal.control, plan.query, plan.control and plan.turn.start, preserving goal/proposal/execution identity, revisions, store versions, budgets and Host outcomes.
     • Reuse PR 6's already-consumed attachment/turn observation. Observe before starting execution; return admission from the initiating extension request and deliver subsequent execution status without inventing an unrelated prompt response.
     • Connect existing goal/domain-change callbacks and authoritative query refresh as needed. Text, tools and interactions from goal/plan execution must be consumable immediately, without a follow-up prompt. Do not add a scheduler, plan state machine or extra subscription solely for refresh.
     • Distinguish pause/resume/clear of a goal, stopping the current turn and closing adapter attachment. Handle stale approval, repeated requests, external control, reconnect and EOF without duplicate execution or rewriting Host authority. Do not apply configuration CAS retries indiscriminately to execution commands.
     • Verify goal arm → execution/state observation → control and plan query → approve/start → output/interaction → cancel/resume/terminal state through production ACP routes.
     • Test real execution, revision conflicts, duplicate approval/start attempts, background turns, pending interactions, reconnect, cancellation and resource cleanup.
     • Acceptance: clients can drive and observe goal/plan work end to end. With PR 7 also merged, the Phase 3 routes are delivered; remaining issue-wide integration checks are tracked below.
     • Depends on: PR 6
     • Status: merged on 2026-09-26 as 86c61d420 after integrating PR 7's mainline changes.
     • Delivered/evidence: six private routes, opt-in Goal/Plan hints and one retained attachment/Turn observer. SDK/real-Host tests cover continuation, execution/resume, conflicts, external changes and cleanup. Full CLI and Runtime Host suites passed on the implementation head; root build, focused ACP tests, full CLI and GitHub test passed after merging PR 7. Full Host, Zed and Desktop E2E were not rerun on that merge head.
     • PR: #5734

   ---

   Phase 4 — Documentation and interoperability

   • Each PR updates supported ACP methods/capabilities, _maka/ names, Host mappings, lifecycle/error behavior and its verification evidence. Workspace instructions remain Host-owned; usage/context handling is documented without a new dashboard or protocol. PR 1–8 documentation and validation records are delivered.
   • Verify create → configure → stdio MCP/tool → interaction → complete/cancel → close through the actual ACP/Host process path. PR 3–5 official-SDK and real-Host tests cover these flows.
   • Verify history load → live handoff/pending interaction → explicit interrupted execution recovery, including incompatible/parked cases. PR 6 covers these paths with real ACP/Host and focused regressions.
   • Verify branch/revision → target continuation → artifact access and memory consumption; verify goal/plan start → output/interactions → control/recovery. PR 6 proved branch/revision target continuation, PR 7 proved Artifact/Memory flows, and PR 8 proved Goal/Plan flows. A single cross-feature branch/revision-target → Artifact/Memory integration path has not been evidenced.
   • Run a real third-party ACP client smoke test for standard supported workflows (prefer Zed when available); use official-SDK production-route tests for Maka extensions. Zed smoke covered standard tool/permission and load/prompt flows in PR 5–6; official-SDK/real-Host child-process tests cover PR 7–8 private routes. No third-party private-extension UI smoke is claimed.
   • Complete final integrated verification on the merged head: repository tests and relevant build/typecheck/lint/format, CLI third-party notices and protocol compatibility checks. Shared-seam changes retain Desktop/TUI/CLI/Eval regressions. Do not defer feature tests or necessary consumers to this final gate. PR 7–8 recorded builds, focused tests, full CLI suites, lint/format and passing GitHub test; PR 8 also recorded a full Runtime Host suite. Desktop Electron E2E and Windows/Linux platform runs were not repeated on the final PR 8 head.

   Scope boundaries

   • Keep ACP v2 draft-only behavior, mid-turn steering/input injection and Paseo provider/registry/icon changes outside this issue; merged PR 1–8 did not add Host steering.
   • External clients use the ACP surface; Runtime Host remains the internal execution and state authority in the merged PR 1–8 flows.
   • The current ACP capability matrix states the supported ACP v1 inputs and methods, Maka extensions, and unsupported behavior. PR 5–6 cover client-provided stdio MCP; PR 7–8 add Artifact/Memory and Goal/Plan routes and describe their contracts in packages/cli/src/acp/README.md, alongside workspace instructions and usage/context handling.
   • Supported clients can complete standard elicitation through explicit capability negotiation; PR 5 exercises the required interaction and failure paths through its production workflow.

   Issue completion criteria

   • maka --acp exposes create/configure/list/prompt/cancel/load/resume/close over the existing Host client stack; interrupted execution resumes only through an explicit safe workflow (PR 1–6).
   • Text/thinking/tool/terminal output preserves correlation and ordering; all five current Interaction kinds complete or close through Host (PR 4–6).
   • Client-provided stdio MCP works with Session isolation, lifecycle cleanup and load/resume handling (PR 5–6).
   • Branch/revision/artifact/memory/goal/plan are usable through tested _maka/ routes while Host remains the single execution/state authority. PR 6 delivered branch/revision, PR 7 Artifact/Memory, and PR 8 Goal/Plan.
   • Every new design has a real same-PR production consumer and end-to-end evidence; PR 5–8 do not depend on a future PR to establish their validity.
   • The capability matrix and real-client/SDK evidence match the delivered standard, extended and excluded behaviors, and all issue-level integration scenarios pass. Standard Zed and private-route SDK evidence exists; the combined branch/revision-target → Artifact/Memory scenario above remains to be verified.

   Progress-update convention

   • Link each draft PR and its scope/evidence without checking it complete. Mark it complete only after merge, with a short update of delivered behavior and newly unblocked dependencies.

   简体中文

   进度概览（2026-09-27）

   • 计划中的 8 个 PR checklist 项均已合入；PR 5 拆分为三个 PR，因此实际合入共 10 个 PR。原合并版 #5222 已关闭、未合入，其范围由 #5384、#5385、#5386 交付。
   • 本 issue 仍为 Open，下方有 3 个 issue 级验收项未勾选：单条 branch/revision 目标 → Artifact/Memory 整合路径、最终整合验证（包括 PR 8 最终版本未重跑的 Desktop Electron E2E 与 Windows/Linux 检查），以及按最终整合结果核对能力矩阵和客户端/SDK 证据。各 PR 已通过的构建与测试证据见下文。

   当前代码基线

   • PR 7、PR 8 合入后，已按 2026-09-26 的 main@86c61d420 核对进度。
   • PR 1（#3658）已落地 maka --acp stdio server、官方 @agentclientprotocol/sdk@1.4.0 依赖、纯协议 stdout、未支持方法的明确错误，以及可复用的官方 SDK 子进程测试工具。
   • PR 2（#3744）已落地惰性 Runtime Host bootstrap，以及不 attach subscription 的 durable Session 创建和有界分页列出。
   • PR 3（#4051）已落地 Host-backed ACP configuration projection 和 CAS update；PR 4 随后处理了创建后 Session 可达性和 subscription 驱动的 option 刷新。
   • PR 4（#4862）已于 2026-09-13 合入，PR 5 和 PR 6 随后合入；PR 7（#5685）与 PR 8（#5734）均于 2026-09-26 合入。
   • 当前 Runtime Host ClientHello 已不再包含 ClientSurface；私有的 surface: 'desktop' 只用于兼容旧 Host。ACP 不应新增 ClientSurface 值。
   • 应复用现有 RuntimeHostConnection、ClientSessionSubscription、RuntimeHostSessionProjector、transcript 分页及重连/恢复逻辑，不建立第二套 Runtime Host client stack。
   • 上述基线记录已合入 PR 的进度；后续工作开始前仍需按最新 main 复核。

   跟踪规则

   • PR 只有合并后才能勾选完成。
   • 每个 PR 必须能够独立审查和测试。
   • 每个 PR 只能依赖已经合并的前置 PR。
   • 新行为的测试必须随对应 PR 一起提交。
   • 新增接口和模块必须在同一 PR 被生产 ACP 路由或执行流程消费，并通过官方 SDK 和真实 ACP/Host 链路验证。
   • 复用已有 registry、配置、attachment、投影及 Host operation seam；共享逻辑随实际调用方提取，扩展路由随首个具体消费方法引入。
   • 文档与能力声明随功能同步更新；标准互操作用第三方 ACP 客户端验证，扩展通过 SDK 调用生产路由验证。
   • Runtime Host 保持唯一执行和状态权威。
   • 尚未实现的 ACP 方法必须返回明确的协议错误。
   • 现有 Desktop、TUI、CLI 和 Eval 行为不得受影响。

   依赖关系

   flowchart LR
       PR1["PR 1"] --> PR2["PR 2"]
       PR2 --> PR3["PR 3"]
       PR3 --> PR4["PR 4"]
       PR4 --> PR5["PR 5"]
       PR5 --> PR6["PR 6"]
       PR5 --> PR7["PR 7"]
       PR6 --> PR8["PR 8"]
   

   Loading

   ---

   阶段一 — ACP 基础

   • PR 1 — 增加 maka --acp stdio 服务基础

     • 引入官方 @agentclientprotocol/sdk，更新 lockfile，并重新生成 CLI 第三方依赖声明。
     • 在当前通用 TUI --flag 解析前增加 acp command kind，并更新 CLI help 和解析测试。
     • 使用 ndJsonStream 和 agent(...).connect(...) 将 stdio 接入 Maka ACP Agent 实现。
     • 启动和 initialize 阶段只建立 transport；在 ACP 方法实际需要 session 或 runtime 状态前不连接 Runtime Host。
     • 实现 ACP initialize，不增加 ClientSurface 字段或值。
     • 保证 stdout 只包含协议消息，诊断信息输出到 stderr。
     • 尚未实现的 ACP 方法返回明确错误。
     • 增加可复用的子进程 stdio/ACP 测试工具。
     • 验收： maka --acp 可启动 ACP v1 stdio transport，在不依赖 Runtime Host 的情况下完成 initialize，明确拒绝未支持方法并正常退出，且不改变现有 CLI 命令。
     • 依赖： 无
     • 状态： 已于 2026-08-26 合入
     • PR： #3658

   • PR 2 — 映射 ACP Session 创建与列出

     • 承接 PR 1 有意延期的 Runtime Host bootstrap：在首个需要 Host 的 ACP 方法到来时，通过 connectRuntimeHostCliConnection 惰性创建一个仅含连接的 CLI Runtime Host context；同一 ACP connection 共享该 context，并在 ACP stdio connection 结束或 Runtime Host bootstrap 被中止时确保只关闭一次。ACP Session 操作不得依赖无关的模型连接 catalog。
     • 将 session/new 映射到 session.create，由 adapter 生成 sessionId，把 cwd 映射为 host_path workspace，并固定使用 Host 默认 modelTarget。
     • 允许空的 mcpServers 和 additionalDirectories，明确拒绝非空值；忽略 ACP _meta，不定义私有 Project ID 契约。
     • 建立一个聚焦的 ACP session registry，负责 durable session 创建、列出和幂等的连接级关闭。PR 2 不保留任何 per-session adapter state：不跟踪 ownership，也不打开、保留或消费 Runtime Host subscription。PR 3 在配置路由成为首个生产消费者时引入 current-connection ownership；subscription attach 延至 PR 4 的首次 session/prompt。
     • session/list 使用可复用的 Runtime Host 单页 catalog reader，以及绑定规范化 cwd 过滤条件、带大小限制且严格的 opaque ACP cursor；revision 变化映射为 stale-cursor 参数错误，并跳过无法映射的 legacy record。cursor 必须使用 canonical base64url，且只允许当前的 revision、cursor、cwd 三个字段；在出现明确兼容需求前不提前引入 cursor 版本号。
     • 完整 catalog reader 在首页和后续页路径都应规范化 RuntimeHostSessionCatalogRevisionChangedError，避免向调用方泄漏更窄的实现细节。
     • PR 2 不实现也不声明 session/close，调用继续返回 -32601；PR 4 明确负责“取消 active turn → 关闭 subscription → 移除 adapter state”语义。
     • adapter 清理绝不删除或归档 Runtime Host durable session。adapter EOF 只关闭其拥有的 Host connection；PR 2 没有需要清理的 connection-local per-session state。
     • 更新 maka --help，不再把 ACP surface 描述成仅支持 initialize，并写明此阶段已支持的方法。
     • 使用官方 SDK client 和真实 Runtime Host 进程测试有界 catalog 分页、cwd 过滤与 stale cursor、首页 revision-change 规范化、多 session 隔离、单个 ACP connection 创建超过 16 个但不 attach subscription、关闭竞态、不支持输入和稳定的 Runtime Host 错误转换。明确断言 session/new 和 session/list 不调用 subscription.open。
     • 验收： ACP 客户端可创建超过 16 个相互独立的 durable session，并在不打开 subscription 的情况下通过有界分页列出；仅在 Host-backed Session 工作开始时连接 Runtime Host，ACP stdio connection 结束或 Runtime Host bootstrap 被中止时，惰性创建的 connection-only CLI context 只关闭一次；durable session 继续由 Runtime Host 管理，且 session/close 不被声明。
     • 依赖： PR 1
     • 状态： 已于 2026-09-02 合入
     • PR： #3744

   • PR 3 — 通过 ACP v1 暴露 Maka Session 配置

     • 每次 session/new 成功后，根据 Runtime Host 已提交的 SessionCatalogProjection 返回顺序固定的 ACP select configOptions：permission、collaboration 和 orchestration 始终存在；只有当前模型声明了 thinking levels 时才返回 thinking。
     • 可选值来自 core 的规范列表。permission_mode 映射到 permissionMode，仅可选择 ask 和 bypass；已有 Session 可以把 explore 报告为当前值，但 ACP 不允许选择它。collaboration_mode 映射到 collaborationMode（agent、plan），orchestration_mode 映射到 orchestrationMode（default、swarm、graph）。
     • thinking_level 根据 Runtime Host connection catalog 中当前选定模型生成。非推理模型不返回该选项；推理模型返回 default（对应 Host null）以及该模型准确声明的 thinking levels。
     • 根据成功的 session/new 结果引入轻量 current-connection ownership set，并仅允许该集合中的 session ID 调用 ACP v1 session/set_config_option；不得以 live subscription 作为所有权证明。未知 option ID、错误 value 类型和不支持的值必须在 Host I/O 前拒绝。
     • 每次在线修改都先读取当前 catalog projection，再携带 expectedRevision 和单字段 SessionConfigurationPatch 调用 session.configuration.update。Runtime Host 将 patch 合并到当前配置并提交完整结果，保留 modelTarget 与全部未变字段。
     • 遇到 revision_conflict 时重新读取 projection 并重试完整更新，最多严格执行三次。与 CLI/TUI session driver 共享中立的 Session 读取、projection 和有限 CAS 重试，同时把 ACP 生命周期检查与结构化错误映射保留在 ACP 边界。
     • 根据 Host 已提交结果返回完整的已声明 option projection。session_busy、operation_conflict 等 Host 状态/冲突码保留在 error.data.code，不把它们误分类为 JSON-RPC 参数非法。
     • session/set_mode 保持不支持且不声明。ACP session/new 没有配置或 mode 输入，因此 PR 3 不表示创建期 SessionStartMode，也不把它伪装成可变配置。
     • Workspace instructions 继续由 Runtime Host 组合，不建立 ACP 侧 system-prompt 权威。
     • 测试规范值和模型相关 option projection、CAS 与冲突重试、所有权与关闭边界、官方 SDK 路由、stdio 响应，以及推理/非推理模型的真实 ACP 子进程 + Runtime Host create → configure 流程。配置操作不得要求或打开 subscription。
     • 验收： session/new 在不 attach subscription 的情况下返回适合当前模型的 Host-backed 配置；explore 不可选择；session/set_config_option 通过 Runtime Host CAS 只修改一个受支持值，不覆盖模型选择或无关配置。连续三次冲突后确定性终止，同时 session/set_mode 继续明确返回不支持。
     • 依赖： PR 2
     • 状态： 已于 2026-09-07 以 b67778abd 合入；required CI 已通过。
     • PR： #4051

   • PR 4 — Attach live Session，并映射 Prompt、取消、关闭与有序基础流式输出

     • 将 durable-session ownership 与 live attachment state 分离。对当前 ACP connection 所拥有的 session，首次 session/prompt 以 single-flight 方式打开一个 Runtime Host subscription，并在 turn.start 前开始消费，确保不遗漏早期 frame；后续 prompt 复用 live attachment。
     • 在 attach 前加固现有 AcpSessionRegistry.#create 生命周期边界：Runtime Host 创建成功后，如果 option projection 失败，优先返回已创建的 sessionId 并省略可选的 configOptions；ACP 返回该 id 前不授予 mutation ownership。如果改选 rollback，必须先定义 durable Session 删除和 cleanup failure 语义。
     • 已 attach Session 的模型或配置被 ACP 之外的客户端修改时，消费权威 subscription update，并发送包含完整最新 option projection 的 ACP config_option_update，包括增加或移除 thinking_level；定义它与 session/set_config_option response 的顺序，并禁止 close 后继续发送。
     • one-shot open operation 只保留在 reconnecting Runtime Host connection 上，用于保证 attach 不会静默落到 replacement Host epoch；不要在 concrete base connection interface 增加重复别名。
     • 仅在 attach 成功后才将 session/prompt 映射到 turn.start，生成必需的 turnId，并将支持的 ACP prompt 内容转换成 Maka MessageContent。attach 失败不得启动 turn，也不得修改 durable Session。
     • session/cancel 使用当前 subscription snapshot 中权威的 sessionId、turnId 和 runId 调用 turn.stop。
     • 复用 RuntimeHostSessionProjector/session-channel 的 sequence 校验、delta folding、active stream 恢复和 terminal turn 判断。
     • 将投影后的 text/thinking 事件映射成 agent_message/agent_thought，将 terminal complete/abort/error 映射成 end_turn。
     • 不增加 ACP 侧排序器：PR 4 所拥有的 subscription 会拒绝 sequence gap，projector 已处理 startOffset、reset、complete 和重连恢复。
     • 实现并声明 session/close。若存在 active turn，先取消；随后关闭 subscription，并移除全部 adapter-owned attachment 与 ownership state。关闭尚未 attach 的 Session 时只移除 adapter-owned state。绝不删除或归档 Runtime Host durable Session。
     • 成功 attach 后保持到 session/close 或 ACP connection shutdown。依赖 Host 的 per-connection subscription admission，不在客户端复制计数器；容量不足必须在 turn.start 前返回，并在 close 后可复用容量。
     • 不要仅为 ACP 侧容量计算导出 Host subscription limit，也不要为此新增 protocol compatibility declaration。
     • 不要重新引入仅供测试使用的 inspect() API；attachment state 必须由 prompt、cancel、streaming 和 close 行为直接消费。
     • subscription EOF 或消费失败时，确定性结束受影响的 prompt、释放 attachment resource，并在协议状态允许时让后续 prompt 执行新的 one-shot attach。
     • 在声明 prompt 互操作前，用一个真实 ACP client 完成 session/new/prompt smoke test（可用时优先 Zed），记录实际必填的 mcpServers payload，并决定非空 client-provided server 是继续明确不支持，还是提供受支持映射。
     • ACP 事件映射保持为独立模块，并增加聚焦测试。
     • 测试 Host 创建后的 catalog/projection 失败与 Session 可达性、并发首次 prompt、attach-before-start 顺序、attach/cancel/close/shutdown 竞态、subscription EOF 与失败、one-shot open 期间 Host replacement、外部模型变化导致 reasoning option 增加或移除、update 顺序、创建超过 16 个但未 attach 的 Session、Host 容量拒绝且不创建 turn，以及 session/close 后槽位复用。
     • 验收： Runtime Host 创建 Session 后，ACP 返回可用的 sessionId 或完成定义明确的 rollback，option projection 不得遗留不可达 durable Session；随后客户端可在首次 prompt 时 attach，运行并取消完整 turn，并在不删除 durable Session 的情况下关闭 adapter-owned Session state；offset、reset、重连和终止状态形成单一有序 ACP 流且只产生一次 end_turn；外部模型变化会按序发送包含最新选项的 config_option_update；可创建超过 16 个未 attach 的 Session，且 close 会释放 subscription capacity。
     • 依赖： PR 3
     • 状态： 已于 2026-09-13 合入（6ce9c72c3）；required CI 已通过。
     • PR： #4862

   ---

   阶段二 — ACP v1 Runtime 能力

   • PR 5 — 完整工具执行、交互与 stdio MCP 接入

     • 扩展现有 prompt 路径：tool_start → tool_call；output/progress/preview/result 均有明确的 tool_call_update 行为。在可表达范围内保留工具 identity、sequence、stream、redaction、status 和 duration，展示状态有界且截断可见。
     • 遵守 ACP 工具 content 的替换语义，以权威 StoredMessage 工具记录校准累计输出。contentOmitted 不代表空结果，argsPreview 不代表完整参数。处理缺失 start、重复 seq、迟到 preview/result、慢消费者恢复，不重复建卡或把终态恢复成运行态。
     • 接通 transcript settlement/replacement 与 mapper。当前 prompt 的结果补全及恢复归本 PR，不推迟到 PR 6。复用分页、watermark 和 fragment decoding，并先验证 subscription/channel seam 的最小必要扩展。缓存的初始 loadTranscript() 不是刷新；不得直接复制会额外打开 subscription、可能在满容量时失败的 TUI helper。
     • 正常完成前等待必要结果校准及通知发送；保留 PR 4 实现中权威 end_turn、显式取消 cancelled、投影/传输失败的区别。工具终态不能代替 turn 终态，取消、失败和 close 不得无限等待缺失结果。
     • 覆盖当前五类 InteractionRequest：permission、question、form、sandbox_boundary、client_capability。复用 pending/resolved snapshot、channel callback、core 校验和 typed interaction.answer，处理外部已回答、重放、迟到回答和 Host closure reason。
     • 对能忠实表达的交互使用标准 session/request_permission 和能力协商后的 elicitation/create。保留 grant target/scope、turn 内授权有效期、表单类型及 decline/cancel 语义。确有必要的私有表达必须在本 PR 同时落地具体路由与 SDK 端到端消费。不支持的客户端得到明确失败/关闭路径，不永久 pending，也不扩大授权。
     • 在 session/new 支持客户端提供的 stdio mcpServers，替换 PR 2–4 对非空列表的临时拒绝。校验名称、command/args/env，使用 Session cwd 转换为已有内存 MCP config；复用 McpClientManager、createMcpCapabilityProvider 和 Host capability 调用/取消链。不把请求中的 command/env 写入用户 MCP 设置，不增加 HTTP/SSE/OAuth 管理。
     • 先用真实双 Session 调用验证隔离，再选择 Host capability seam 的最小扩展：当前 connection-wide publication 和 affinity: session 不能指定目标 Session。同一 ACP connection 的两个 Session 可以提供同名不同实现的服务器；注册、替换、撤销只能影响目标，scoped 工具不能进入无关 provider fallback。保留 Desktop/TUI 行为及必要协议兼容检查，不用每 Session 新增 Host connection 绕过问题。
     • 依赖 MCP 的 turn 准入前必须完成发现和发布。定义准备失败、工具列表动态更新、取消、Host 重连重发及 EOF 清理。尽量在 durable 创建前准备；Host 创建后的失败必须通过明确 error/result 契约保留可达 Session ID。close 先停止执行，再释放 adapter-owned 注册和进程，不删除 durable Session。
     • 通过生产 ACP 路由验证 create → prompt → MCP/tool 调用 → 权限/表单回答 → 结果 → complete/cancel/close。
     • 测试官方 SDK 子进程 + 真实 Host；单个/并发/流式工具；五类交互及回答竞态；满 subscription 容量；MCP 发现/调用/取消/退出；同名服务器跨 Session 隔离；替换/关闭隔离；重连/EOF；原 TUI/Desktop capability 回归。
     • 验收： ACP 客户端可运行完整工具 turn、回答支持的交互并收到权威结果；失败路径确定性结束并释放资源，每个新增 seam 均被此流程使用。
     • 依赖： PR 4
     • 状态： 已完成；三个拆分 PR 已于 2026-09-22 前全部合并。α 于 2026-09-17 合并（672d82731），β 于 2026-09-19 合并（852a9748d），γ 于 2026-09-22 合并（420c22186）。
     • 已交付： 有序工具卡片投影与权威结果校准；经 ACP permission/elicitation 处理全部五类 Host 交互；Session 隔离的 stdio MCP 发现、发布、调用与生命周期清理。PR 6 和 PR 7 随后均已合入。
     • PR： α #5384、β #5385、γ #5386。由原合并版 #5222 拆分交付；feat(cli): add ACP tools, interactions and session-scoped MCP #5222 已关闭、未合入。

   • PR 6 — 加载、重新附着、恢复执行、分支与修订

     • 实现并声明 session/load（历史回放后响应）与 session/resume（不回放历史的接管），二者均不隐式重启中断 turn。校验 cwd 和生命周期输入、返回当前配置，并将成功接管接入已有 connection ownership。
     • 复用 catalog 查询、subscription snapshot、active assistant streams、durable/overlay 分页、cursor、watermark 和 canonical recovery。适用时复用 PR 5 投影，回放 user/assistant/thinking/tool 历史并无重复切换至实时输出；部分失败释放 attachment，不删除 Session。
     • 接通已有 onTurnStarted 和交互 callback，使已存在 live turn 在没有新 prompt 时仍可观察。同一 turn 只设一个事件消费者，prompt response 等待同一观察结果，不另开第二个 reader。非 prompt 执行的状态表达由本 PR 实际 load/resume 流程消费，不在 PR 5 预建。
     • 提供显式 _maka/turn/resume 中断执行流程：先 query，仅 ready 时携带 source run/high-water identity start；直接反馈 parked 原因。只有 TUI 与 ACP 都实际使用时才提取现有 TUI resume 的中立逻辑，各自保留生命周期控制。
     • load/resume 经 PR 5 的 Session-scoped 集成应用本次请求的完整 MCP 列表。不从 durable 历史恢复 command/env，不重放历史工具调用。由 Host binding 契约判断安全替换，活跃冲突或中断契约不兼容不得静默更换 provider；重复等价接管不重复启动进程。
     • 为 session.branch.create、session.revision.create、session.revision.abandon 增加具体 _maka/ 路由。保留 source/target identity 和 expected source revision；成功返回的目标获得 ownership，可立即 configure/prompt 或 load。Host 已提交后发生投影失败仍保留目标可达性。
     • 分支不复制活跃 MCP 进程或凭据。abandon 处理目标 attachment/执行状态并保留 Host 的 abandoned/retained 区别，普通 close 不删除 Session，不引入 TUI 特有的本地 storage cleanup authority。
     • 通过生产路由验证已有/活跃 Session 加载并继续、显式恢复中断执行、创建分支/修订后 prompt 目标，以及 abandon。
     • 测试多页历史、live/replay 顺序、pending interaction 恢复、ownership/configuration、重复 load/resume、close/failure 竞态、provider 变化、parked、分支继续执行、revision 冲突及 retained。
     • 验收： 客户端可加载、接管、显式恢复或分支/修订，不产生历史缺口、重复执行、不可达目标或资源泄漏。
     • 依赖： PR 5
     • 状态： 已于 2026-09-25 合入（87217d370）；PR 8 的前置依赖已解锁。
     • 交付与证据： #5621 交付 load/resume、无重复回放的历史与实时 Turn 恢复、带跨连接冲突保护的 Session MCP 重配、显式中断 Turn 恢复及分支/修订路由。提交 745430a3c 的完整 CLI 测试通过 1256 个（跳过 3 个）、完整 Runtime Host 测试通过 2127 个（跳过 12 个），GitHub test 检查通过。该提交未在 Windows 重跑；此前 Desktop E2E 与 Zed 的证据边界见 PR 验证摘要和验证记录。
     • PR： #5621

   ---

   阶段三 — Maka 扩展命名空间

   • PR 7 — 完整 Artifact 与 Memory 访问

     • 为 artifact.query、artifact.ingest、artifact.delete、memory.query、memory.mutate 增加具体 _maka/ request/response 路由，沿用 ownership/error 检查和 Host typed 校验。
     • 消费 artifact 的 list/get/text/binary/chunk 及当前 Host multipart begin/chunk/完成/清理契约，保留 revision/cursor、upload identity、offset、限制和完整性校验。工具结果中的 artifact 引用必须经 ACP 可读取/导出，不能只返回 ID 或不可访问 Host 路径。
     • Memory mutation 通过权威 query 和后续适用 turn 的真实上下文验证，保留作用域/冲突语义并说明生效时间，不承诺改写已运行的模型输入。
     • 持久化、授权和冲突权威留在 Host。仅增加本 PR 实际消费的有界传输编排，不增加通用 CRUD、upload store 或 ACP 专属 memory 注入路径。
     • 仅注册本 PR 的具体方法；已有适用扩展 helper 可直接复用。
     • 通过生产路由验证 ACP 上传 → 读取/导出 → 删除，以及 memory mutate → query → 后续 turn，核对返回数据和执行效果。
     • 测试分页/revision 变化、分块往返与完整性、中断传输、缺失/删除产物、mutation 冲突、重连及后续 turn 的 memory 消费。
     • 验收： Artifact 和 Memory 经 ACP 返回可使用、可验证的结果，不依赖后续 goal/plan 功能。
     • 依赖： PR 5
     • 状态： 已于 2026-09-26 合入（835112108）；前置 PR 6 已先行合入。
     • 交付与证据： 五个私有路由覆盖 Artifact 传输/读取/删除及 Memory 查询/变更，工具结果引用可读取，Memory 在后续模型请求中生效。SDK/真实 Host 测试覆盖字节、分页、恢复和 Memory；完整 CLI test:dist 通过 1278 个（跳过 3 个），GitHub test 通过。未验证第三方私有扩展 UI。
     • PR： #5685

   • PR 8 — 可观察、可控制的 Goal/Plan 执行

     • 为 goal.query、goal.arm、goal.control、plan.query、plan.control、plan.turn.start 增加具体 _maka/ 路由，保留 goal/proposal/execution identity、revision、store version、预算及 Host outcome。
     • 复用 PR 6 已有消费者验证的 attachment/turn observation，先建立观察再启动执行。启动扩展返回 admission，后续发送执行状态，不伪造无关 prompt response。
     • 按需消费已有 goal/domain-change callback 和权威 query refresh。Goal/Plan 产生的文本、工具、交互立即可消费，不依赖用户再发普通 prompt；不增加调度器、计划状态机或仅用于刷新的额外 subscription。
     • 区分 goal pause/resume/clear、停止当前 turn、关闭 adapter attachment。处理过期审批、重复请求、外部控制、重连/EOF，不重复执行或改写 Host 权威；不得把配置 CAS 重试泛化到执行命令。
     • 通过生产 ACP 路由验证 goal arm → 执行/状态观察 → control，以及 plan query → approve/start → 输出/交互 → cancel/resume/terminal。
     • 测试实际执行、revision 冲突、重复审批/start、后台 turn、pending interaction、重连、取消及资源清理。
     • 验收： 客户端可以完整驱动并观察 Goal/Plan。PR 7 也已合入，阶段三的路由已交付；剩余 issue 级整合检查见下文。
     • 依赖： PR 6
     • 状态： 已于 2026-09-26 合入（86c61d420），并已整合 PR 7 的 mainline 改动。
     • 交付与证据： 六个私有路由、可选 Goal/Plan 提示、单个 retained attachment/Turn observer。SDK/真实 Host 测试覆盖续跑、执行/恢复、冲突、外部变化和清理。实现提交通过完整 CLI 与 Runtime Host 测试；整合 PR 7 后通过 root build、ACP 定向测试、完整 CLI 和 GitHub test。合并提交未重跑完整 Host、Zed 和 Desktop E2E。
     • PR： #5734

   ---

   阶段四 — 文档与兼容性

   • 各 PR 同步更新 ACP 方法/能力、_maka/ 名称、Host 映射、生命周期/错误语义与验证证据。workspace instructions 仍由 Host 组合；usage/context 处理方式已记录，未新增仪表盘或协议。PR 1–8 的文档与验证记录均已交付。
   • 经实际 ACP/Host 进程验证 create → configure → stdio MCP/tool → interaction → complete/cancel → close。PR 3–5 的官方 SDK 与真实 Host 测试覆盖这些流程。
   • 验证 history load → live 切换/pending interaction → 显式中断执行恢复，包含不兼容/parked。PR 6 已用真实 ACP/Host 链路和聚焦回归覆盖。
   • 验证 branch/revision → 目标继续执行 → artifact 访问及 memory 消费；验证 goal/plan start → 输出/交互 → 控制/恢复。PR 6 已验证分支/修订目标继续执行，PR 7 已验证 Artifact/Memory，PR 8 已验证 Goal/Plan；尚无单条 branch/revision 目标 → Artifact/Memory 跨功能整合路径的证据。
   • 用真实第三方 ACP 客户端进行标准流程 smoke（可用时优先 Zed），用官方 SDK 的生产路由测试验证 Maka 扩展。PR 5–6 的 Zed smoke 覆盖标准工具/权限和 load/prompt；PR 7–8 的官方 SDK/真实 Host 子进程测试覆盖私有路由。不宣称已验证第三方私有扩展 UI。
   • 在合入后的版本完成最终整合验证：仓库测试及相关 build/typecheck/lint/format、CLI 第三方声明、协议兼容检查。共享 seam 保留 Desktop/TUI/CLI/Eval 回归；不得把功能测试或必要消费者留到最终门槛。PR 7–8 已记录构建、定向测试、完整 CLI 测试、lint/format 和通过的 GitHub test；PR 8 还记录了完整 Runtime Host 测试。PR 8 最终提交未重跑 Desktop Electron E2E 或 Windows/Linux 平台检查。

   范围边界

   • ACP v2 draft-only、mid-turn steering/input injection、Paseo provider/registry/icon 修改不在本 issue；已合并的 PR 1–8 未新增 Host steering。
   • 已合并的 PR 1–8 由外部客户端通过 ACP 访问，Runtime Host 保持内部执行与状态权威。
   • 当前 ACP 能力矩阵准确列出支持的 ACP v1 输入/方法、Maka 扩展及不支持行为。PR 5–6 已完成客户端 stdio MCP；PR 7–8 加入 Artifact/Memory、Goal/Plan 路由，并在 packages/cli/src/acp/README.md 记录其契约，以及 workspace instructions 和 usage/context 的处理方式。
   • 支持的客户端可通过明确能力协商完成标准 elicitation；PR 5 已通过生产流程验证所需交互和失败路径。

   Issue 完成条件

   • maka --acp 基于已有 Host client stack 提供 create/configure/list/prompt/cancel/load/resume/close；中断执行仅通过显式安全流程恢复（PR 1–6）。
   • Text/thinking/tool/terminal 输出保持关联和顺序；当前五类 Interaction 均经 Host 完成或关闭（PR 4–6）。
   • 客户端 stdio MCP 支持 Session 隔离、生命周期清理及 load/resume（PR 5–6）。
   • Branch/revision/artifact/memory/goal/plan 经已验证的 _maka/ 路由可用，Host 保持唯一执行/状态权威。PR 6 交付 branch/revision，PR 7 交付 Artifact/Memory，PR 8 交付 Goal/Plan。
   • 每项新增设计都有当期实际生产消费者及端到端证据，PR 5–8 不依赖未来 PR 才证明有效性。
   • 能力矩阵及第三方客户端/SDK 证据与最终标准、扩展、范围边界一致，全部 issue 级整合场景通过。已有标准流程 Zed 和私有路由 SDK 证据；上文所述 branch/revision 目标 → Artifact/Memory 联合场景仍待验证。

   进度更新约定

   • Draft PR 创建时记录链接、范围和证据但不勾选；合并后才勾选，并简述交付内容及解锁的依赖。
8. Sun-GLiang commented on Aug 24, 2026

   

   Sun-GLiang

   on Aug 24, 2026

   Member

   More actions

   By the way, once the ACP integrated is implemented, could you add a new feature to support adding any ACP service in a Workspace as a subagent to facilitate the scheduling of these ACP services?

   Thanks for the suggestion! I’ll work on this as a follow-up after completing the current ACP server integration.
9. Astro-Han

   removed

   help wantedExtra attention is neededExtra attention is needed

   on Aug 29, 2026
10. Astro-Han

    added the

    Feature

    issue type on Aug 29, 2026
11. Astro-Han

    added 2 commits that reference this issue on Sep 2, 2026

    feat(cli): add ACP session creation and listing (#3744)

    ...

    dcddeaf

    feat(cli): expose ACP session configuration

    ...

    b67778a
12. Astro-Han commented on Sep 9, 2026

    

    Astro-Han

    on Sep 9, 2026

    ContributorAuthor

    More actions

    I’d like to track a concrete use case for the follow-up ACP client support here: running Google’s Antigravity agent inside Maka.

    A user requested this on X: https://x.com/FuurinFuu/status/2097500015812104528. T3 Code implements it by launching Google’s official Antigravity ACP agent, with Google sign-in and session/event adaptation.

    This fits the follow-up discussed above for driving external ACP agents. I suggest using Antigravity as a concrete integration and acceptance case for that work, keeping the current ACP server scope unchanged.
13. Sun-GLiang commented on Sep 9, 2026

    

    Sun-GLiang

    on Sep 9, 2026

    Member

    More actions

    Thanks! I’ll open a separate tracking issue with a design proposal for ACP client support, using Antigravity as the first integration and acceptance case. The interfaces will target ACP-compatible agents generally, with agent-specific launch and authentication handled by adapters. I’ll link it here so we can discuss the design in parallel while keeping the current ACP server scope and implementation plan unchanged.
14. Sun-GLiang

    added 6 commits that reference this issue on Sep 13, 2026

    feat(cli): add ACP tools, interactions and session-scoped MCP

    ...

    9a58631

    feat(cli): add ACP tools, interactions and session-scoped MCP

    ...

    9fe25e8

    feat(cli): add ACP tools, interactions and session-scoped MCP

    ...

    ea42a67

    feat(cli): add ACP tools, interactions and session-scoped MCP

    ...

    e8c019f

    feat(cli): add ACP tools, interactions and session-scoped MCP

    ...

    1b2e5d1

    feat(cli): add ACP tools, interactions and session-scoped MCP

    ...

    2946832
15. Sun-GLiang

    added a commit that references this issue on Sep 26, 2026

    feat(acp): expose Artifact and Memory Host operations (#5685)

    ...

    8351121
16. Astro-Han

    added a commit that references this issue on Sep 27, 2026

    test(acp): cover copied-session Artifact and Memory flow (#5756)

    ...

    afe2027