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

[Astro-Han]

Problem

Maka cannot be driven by any ACP-compatible client today. ACP (Agent Client Protocol) is the JSON-RPC 2.0 standard for editor/agent interoperability — Paseo's built-in ACP catalog lists 40+ agents (Cline, Devin, Gemini CLI, Grok, goose, Cursor, Kimi Code, Qwen Code, Hermes, GLM, ...), and Zed, JetBrains, and VS Code ship or support ACP clients. Maka's Runtime Host already owns everything ACP needs (sessions, turns, streaming, interactions, transcripts), but the only non-interactive surface is maka run, a single-turn mode that does not fit ACP's session/streaming/permission model.

Desired outcome

maka --acp — a stdio server exposing the Runtime Host through the Agent Client Protocol. Any ACP-compatible client (Zed, JetBrains, VS Code ACP clients, Paseo, and the broader ACP ecosystem) can create, drive, and resume Maka sessions, while Runtime Host remains the single execution authority. This also unblocks the Paseo integration: Paseo's ACPAgentClient base class already serves five providers, so once maka --acp exists the Paseo-side provider is a thin manifest/registry/icon addition.

Alternatives or workarounds

• Direct integration with the Runtime Host protocol (Paseo-side): a bespoke client that tracks every Runtime Host protocol change. Rejected as the primary path — ACP is a versioned, backward-compatible standard, so the coupling point stays stable as Maka (v0.1.x, actively changing) evolves.
• Custom provider via extends: "acp": requires an ACP surface, which is exactly what this proposal adds.

---

Proposal

AI-assisted: drafted with the assistance of an AI coding agent (pi). Facts verified against the Maka repository, the ACP protocol site, npm, and upstream agent implementations at drafting time; re-verify before relying on them.

Abstract

Maka will expose its agent runtime through the Agent Client Protocol via a new maka --acp stdio server. Any ACP-compatible client can create, drive, and resume Maka sessions, while Runtime Host remains the single execution authority.

Rationale

1. ACP is the de facto integration standard. 40+ agents in Paseo's catalog, Zed/JetBrains/VS Code support. Implementing the protocol once reaches the entire ACP ecosystem.
2. Runtime Host already covers every capability ACP needs. Sessions, turns, streaming (assistant deltas, tool events), interactions, and transcript paging all exist. ACP is a translation layer — the marginal cost is the mapping, not the machinery.
3. A stable coupling point. ACP is versioned and backward-compatible; external clients keep working as the Runtime Host protocol evolves.
4. Enables the Paseo integration (see Desired outcome).
5. Openness without publishing packages. @maka/* packages are private; ACP is the standard way for external clients to drive Maka without internal dependencies.

Initial Goals

1. maka --acp stdio server on the official @agentclientprotocol/sdk (Apache-2.0), following the minimal skeleton used by upstream agents: ndJsonStream + AgentSideConnection + an Agent implementation class.
2. Session lifecycle: initialize; session/new → session.create (adapter generates sessionId); session/prompt → turn.start; session/cancel → turn.stop; session/list → session.catalog.query; session/close → subscription.close.
3. Streaming: subscription.session_delta (text/thinking) → agent_message/agent_thought chunks; subscription.session_event (tool_start/tool_result/tool_output_delta) → tool_call/tool_call_update; turn terminal states → end_turn.
4. Permissions: InteractionRequest kinds → permission_request; interaction.answer → permission_response. Maka's question interactions have no standard ACP equivalent yet (elicitation is still an RFD); initially ride the _maka/ extension namespace.
5. Session restore: session/load/session/resume → subscription.open + transcript paging; interrupted turns via turn.resume.query/turn.resume.start.
6. Configuration: mode/permissionMode/thinkingLevel/collaborationMode/orchestrationMode → session config options (ACP v2 direction), with session/set_mode as the v1-compatible path.
7. _maka/… extension namespace (the ACP-reserved single-underscore prefix, as used by Qwen's _qwen/…) for deeper Maka capabilities ACP cannot express: branch, revision, artifact, memory, goal, plan.
8. Capability-matrix doc in the style of Kimi's @moonshot-ai/acp-adapter README.

Current Status

Maka is actively developed (Apache-2.0, v0.1.x) with four shipping surfaces — Desktop, TUI, CLI, Eval. The proposal targets ACP v1 (what Paseo and the mainstream ecosystem speaks). ACP v2 is a draft consolidation release (session modes removed in favor of config options, unified capability naming, whole-message upserts, permission title/subject, session/resume replay cursors) and is not yet SDK-ready; v1 remains supported after v2 ships. The mapping is designed with v2's migration direction in mind.

Known Risks

• Maintenance commitment: the adapter is a translation layer but must track protocol/SDK/client evolution. Keep it thin, mirror event mapping in a dedicated module with tests (as Mistral Vibe does with session_updates.py).
• Protocol maturity: ACP v2 is a draft; no standard system prompt (RFD refactor(runtime): split context-budget into domain leaves #1237 merged but not in SDK 1.3.0 — workspace instructions need a workaround); no standard elicitation (question interactions); no standard usage/context tracking (usage pricing via _maka/ extension); no steering (v1 and v2 both lack mid-turn input injection — out of scope initially).
• Implementation: message ordering (session/update vs end_turn — Maka's subscription frames are sequence-numbered, preserve order through the mapping); new ClientSurface value 'acp' needed; SDK trails protocol RFDs.

Reference implementations consulted

• Amp (amp-acp) — minimal skeleton
• Cline (apps/cli/src/acp/) — AgentSideConnection + event subscription
• Gemini CLI (packages/cli/src/acp/) — modular dispatcher/session/auth
• Kimi (@moonshot-ai/acp-adapter) — harness abstraction + runAcpServer
• Qwen Code — _qwen/… extension namespace, ACP-over-HTTP transport
• OpenClaw (acpx) — ACP backend over a platform-owned runtime
• Mistral Vibe — session_updates.py event-mapping module

External Dependencies

@agentclientprotocol/sdk — Apache-2.0, license-compatible with Maka (Apache-2.0). Current version 1.3.0. Internal deps (@maka/runtime-host, @maka/core) already in-repo.

---

中文对照 (Chinese Translation)

本提案由 AI 辅助起草（pi），事实性内容已按起草时的 Maka 仓库、ACP 协议官网、npm 与上游 agent 实现核实，使用前请复核。

问题。 目前任何 ACP 兼容客户端都无法驱动 Maka。ACP（Agent Client Protocol）是编辑器与 agent 互操作的 JSON-RPC 2.0 标准——Paseo 内置 ACP catalog 收录 40+ 个 agent（Cline、Devin、Gemini CLI、Grok、goose、Cursor、Kimi Code、Qwen Code、Hermes、GLM 等），Zed、JetBrains、VS Code 均支持 ACP 客户端。Maka 的 Runtime Host 已拥有 ACP 所需的全部能力（会话、turn、流式、交互、transcript），但唯一的非交互入口是 maka run——单轮模式，不符合 ACP 的会话/流式/权限模型。

期望结果。 新增 maka --acp——通过 Agent Client Protocol 暴露 Runtime Host 的 stdio 服务。任何 ACP 兼容客户端（Zed、JetBrains、VS Code ACP 客户端、Paseo 及更广泛 ACP 生态）都能创建、驱动、续接 Maka 会话，Runtime Host 保持唯一执行权威。这也为 Paseo 集成铺路：Paseo 的 ACPAgentClient 基类已服务 5 个 provider，maka --acp 就绪后 Paseo 侧只是薄追加。

备选方案。

• Paseo 侧直接对接 Runtime Host 协议：定制客户端需跟随每次协议变更。不选为主路径——ACP 是有版本、向后兼容的标准，Maka（v0.1.x 活跃演进）变化时耦合点保持稳定。
• extends: "acp" 自定义 provider：需要 ACP 接口，正是本提案要加的。

提案摘要。 Maka 通过新增 maka --acp stdio 服务以 ACP 暴露其 agent 运行时，任何 ACP 兼容客户端可创建、驱动、续接 Maka 会话，Runtime Host 保持唯一执行权威。

理由。 ① ACP 是事实标准（Paseo 40+ agent catalog、Zed/JetBrains/VS Code 支持），一次实现触达整个生态；② Runtime Host 已覆盖 ACP 所需全部能力，ACP 只是翻译层，边际成本在映射而非机制；③ 耦合点选在稳定协议上；④ 为 Paseo 集成铺路；⑤ 不发布内部包也能开放。

初始目标。 ① 基于官方 @agentclientprotocol/sdk（Apache-2.0）的 maka --acp stdio 服务（ndJsonStream + AgentSideConnection + Agent 实现类）；② 会话生命周期映射（session/new → session.create 等）；③ 流式映射（session_delta → agent_message/agent_thought，session_event → tool_call/tool_call_update，终止态 → end_turn）；④ 权限映射（InteractionRequest → permission_request，question 交互初期走 _maka/ 扩展）；⑤ 会话恢复（session/load/resume → subscription.open + transcript）；⑥ 配置映射（config options 为 v2 方向，v1 用 set_mode）；⑦ _maka/… 扩展命名空间承载 branch/revision/artifact/memory/goal/plan；⑧ 能力矩阵文档。

现状。 Maka 活跃开发（Apache-2.0、v0.1.x），有 Desktop/TUI/CLI/Eval 四个界面。提案瞄准 ACP v1（Paseo 与主流生态当前版本）；ACP v2 是 draft 整合发布（移除 session modes、统一能力命名、whole-message upsert、权限 title/subject、resume replay 游标），SDK 未就绪，v2 发布后 v1 仍受支持，映射按 v2 迁移方向设计。

已知风险。 维护承诺（适配器轻薄、事件映射独立成模块配测试）；协议成熟度（v2 draft、无标准 system prompt——SDK 1.3.0 尚未实现、无标准 elicitation、无标准用量追踪、无 steering）；实现（消息排序——Maka 订阅帧带 sequence 需保持顺序、新增 ClientSurface 值 'acp'、SDK 滞后于 RFD）。

参考实现。 Amp（最小骨架）、Cline（AgentSideConnection + 事件订阅）、Gemini CLI（模块化 dispatcher/session/auth）、Kimi（@moonshot-ai/acp-adapter harness 抽象）、Qwen Code（_qwen/… 扩展命名空间、ACP-over-HTTP）、OpenClaw（acpx 平台拥有运行时之上的 ACP 后端）、Mistral Vibe（session_updates.py 事件映射模块）。

外部依赖。 @agentclientprotocol/sdk — Apache-2.0，与 Maka license 兼容。当前版本 1.3.0。内部依赖（@maka/runtime-host、@maka/core）已在仓库内。

[Sun-GLiang]

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?

[shaokeyibb]

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?

[Sun-GLiang]

Thanks for assigning this to me. I’ll start working on the implementation.

[Sun-GLiang]

ACP v1 implementation tracker

English

Current-code baseline

• Revalidated against main@bfba25361 on 2026-08-26 after PR 1 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 1 deliberately keeps startup and initialize transport-only and Runtime Host-independent; PR 2 owns the deferred lazy Runtime Host bootstrap at the first Host-backed Session method.
• 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.
• Revalidate these facts against the latest main before each PR starts.

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.
• 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

PR 1 → PR 2 → PR 3 → PR 4
                         ├→ PR 5 ────────┐
                         ├→ PR 6 → PR 8 ─┤
                         │       └→ PR 9 ┤
                         └→ PR 7 ────────┤
                                        └→ PR 10

---

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 the basic ACP session lifecycle

  • Extend PR 1's transport-only startup by taking ownership of the deliberately deferred Host bootstrap: lazily create one existing CLI Runtime Host context through connectRuntimeHostCli when the first Host-backed ACP method is called; share it across the ACP connection and close it exactly once on EOF, protocol failure, or process shutdown.
  • 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 ACP session registry for durable-session creation, subscription ownership, latest-snapshot tracking, failure recording, and idempotent connection-level shutdown.
  • Start consuming every subscription immediately so bounded client queues cannot stall; PR 2 records projections and failures but defers ACP event projection/streaming to the same consumption path in PR 4.
  • Map session/list through a reusable single-page Runtime Host catalog reader and a size-bounded, versioned opaque ACP cursor bound to the normalized cwd filter; surface revision changes as stale-cursor parameter errors and skip unmappable legacy records.
  • Do not implement or advertise session/close in PR 2; it continues to return -32601. It is currently deferred to PR 4 and must be revalidated before PR 4 starts against cancel-active-turn → close-subscription → remove-adapter-state semantics.
  • Never delete or archive a durable Runtime Host session during adapter cleanup. If creation succeeds but subscription opening fails, return the generated sessionId, durableSessionCreated: true, and a stable Runtime Host error classification without retrying or rolling back creation.
  • Test bounded catalog pagination, cwd filtering and stale cursors, multiple-session isolation, continuous subscription consumption, shutdown races, unsupported inputs, and stable Runtime Host error translation with the official SDK client and a real Runtime Host process.
  • Acceptance: an ACP client can create multiple independent sessions and list them with bounded pagination while each subscription is continuously consumed; Runtime Host is connected only when Host-backed session work begins, the lazily created CLI context and all adapter resources are closed exactly once on connection/process shutdown, durable sessions remain owned by Runtime Host, and session/close remains unadvertised.
  • Depends on: PR 1
  • Status: Open and ready for review; rebased onto merged PR 1
  • PR: #3744

• PR 3 — Expose Maka session configuration through ACP v1

  • Return exactly four ordered ACP select configOptions from the committed Runtime Host SessionCatalogProjection in every successful session/new response.
  • Map permission_mode to permissionMode (explore, ask, bypass), thinking_level to thinkingLevel (default maps to Host null; also off, minimal, low, medium, high, xhigh, max), collaboration_mode to collaborationMode (agent, plan), and orchestration_mode to orchestrationMode (default, swarm, graph).
  • Route ACP v1 session/set_config_option only for sessions owned by the current ACP connection; 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 the complete SessionConfiguration, 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.
  • Return the complete four-option projection from the committed Host result; translate validation, missing/legacy projection, interruption, busy-session, and uncertain-commit failures into stable ACP errors.
  • 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 the pure option vocabulary, complete-configuration CAS and conflict retry behavior, error/lifecycle boundaries, official SDK routing, stdio responses, and a real Runtime Host create → configure flow.
  • Acceptance: session/new returns the four Host-backed configuration options, 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: Draft open; implementation and verification complete, awaiting PR 2
  • PR: #4051

• PR 4 — Map prompts, cancellation, and ordered core streaming

  • Map session/prompt to turn.start, generating the required turnId and converting supported ACP prompt content to Maka MessageContent.
  • 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 current subscription rejects sequence gaps and the projector already handles startOffset, reset, completion, and reconnect recovery.
  • Keep ACP event translation in a dedicated module with focused tests.
  • Acceptance: a client can drive and cancel a complete turn; offsets, resets, reconnects, and terminal states produce one ordered ACP stream and exactly one end_turn.
  • Depends on: PR 3
  • Status: planned
  • PR: pending

---

Phase 2 — ACP v1 runtime capabilities

• PR 5 — Map the current Maka tool event model

  • Map tool_start to tool_call.
  • Map tool_output_delta and tool_result to tool_call_update.
  • Define explicit ACP update behavior for the current additional tool_progress and tool_result_preview events instead of dropping them silently.
  • Preserve toolUseId/tool-call identity, output sequence, stream, redaction, result status, and duration where ACP can represent them.
  • Reuse projected SessionEvent values rather than decoding Runtime Host frames a second time.
  • Acceptance: single, concurrent, previewing, and streaming tool calls remain correlated and ordered, with end_turn emitted only after the terminal tool/turn state.
  • Depends on: PR 4
  • Status: planned
  • PR: pending

• PR 6 — Bridge all current Interaction request kinds

  • Handle the current InteractionRequest union: permission, sandbox_boundary, and question.
  • Map permission and representable sandbox_boundary requests to ACP permission_request.
  • Map ACP permission responses to the existing typed interaction.answer operation.
  • Expose question requests and answers through _maka/ because ACP v1 has no standard elicitation equivalent.
  • Reuse pending Interaction snapshots from SessionContinuitySnapshot.interactions and the existing projector callbacks.
  • Handle resolved/closed interactions, including turn_stopped, turn_terminal, timed_out, and host_restarted closures.
  • Establish shared _maka/ dispatch, validation, correlation, and error conventions for later extensions.
  • Acceptance: permission, sandbox-boundary, and question interactions complete or close through Runtime Host without a second decision authority.
  • Depends on: PR 4
  • Status: planned
  • PR: pending

• PR 7 — Load and resume existing sessions

  • Resolve existing sessions with the paged catalog/get contract and open them through the existing session subscription path.
  • Reuse the subscription.open snapshot, activeAssistantStreams, and transcript bootstrap instead of adding a separate restore protocol.
  • Reuse ClientSessionSubscription/session-channel transcript assembly for durable and overlay pages, watermarks, cursors, and reconnect recovery.
  • Reattach to an already live root turn directly from the subscription snapshot.
  • For an interrupted turn, call turn.resume.query; call turn.resume.start only for a ready plan using its source run and RuntimeEvent high-water identities.
  • Surface parked resume reasons without starting a duplicate turn.
  • Acceptance: an ACP client can load a multi-page transcript, reattach to a live turn, or safely resume/park an interrupted turn without replay gaps, duplicates, or identity changes.
  • Depends on: PR 4
  • Status: planned
  • PR: pending

---

Phase 3 — Maka extension namespace

• PR 8 — Expose branch, revision, and artifact operations

  • Define stable _maka/ request/response names around the existing typed Runtime Host operations.
  • Map branch/revision to session.branch.create, session.revision.create, and session.revision.abandon.
  • Preserve source/target session identity and expectedSourceRevision conflict semantics.
  • Map artifact access to the existing artifact.query, artifact.ingest, and artifact.delete contracts, including multipart ingest identities and offsets.
  • Reuse the PR 6 extension validation and error conventions; do not add branch, revision, or artifact state to the adapter.
  • Acceptance: ACP clients can use the existing Runtime Host branch, revision, and artifact authorities through tested _maka/ contracts.
  • Depends on: PR 6
  • Status: planned
  • PR: pending

• PR 9 — Expose memory, goal, and plan operations

  • Define stable _maka/ request/response names around the existing typed Runtime Host operations.
  • Map memory to memory.query and memory.mutate.
  • Map goal to goal.query, goal.arm, and goal.control.
  • Map plan to plan.query, plan.control, and plan.turn.start.
  • Preserve the existing revision/control results and Runtime Host error contracts.
  • Keep all memory, goal, and plan state in Runtime Host.
  • Acceptance: ACP clients can use the existing Runtime Host memory, goal, and plan authorities through tested _maka/ contracts.
  • Depends on: PR 6
  • Status: planned
  • PR: pending

---

Phase 4 — Documentation and interoperability

• PR 10 — Add the capability matrix and final conformance coverage
  • Document directly supported ACP v1 methods, _maka/ extensions, current Runtime Host mappings, unsupported behavior, and the ACP v2 migration boundary.
  • Clarify that Runtime Host already supports current-turn message submission, while ACP v1 has no standard steering method; the limitation belongs to the adapter protocol surface, not Maka Runtime Host.
  • Document handling for questions, sandbox-boundary requests, tool progress/previews, workspace instructions, and usage/context information.
  • Add cross-PR child-process tests for create → configure → prompt → stream → interact → cancel/complete → close.
  • Add load → transcript bootstrap/page → live reattach or interrupted-turn resume coverage.
  • Add end-to-end _maka/ extension coverage without deferring feature-level tests from earlier PRs.
  • Run an ACP-compatible client smoke test and the repository/CLI third-party notice checks.
  • Acceptance: every documented supported capability has test evidence, and an ACP-compatible client can create, drive, interact with, cancel, load, resume, and close Maka sessions.
  • Depends on: PR 5, PR 7, PR 8, and PR 9
  • Status: planned
  • PR: pending

---

Explicitly deferred

• ACP v2 draft-only behavior.
• ACP mid-turn steering/input injection until the ACP protocol defines a compatible method; existing Runtime Host steering remains unchanged.
• Standard ACP elicitation before the protocol defines it; Maka questions use _maka/ initially.
• Direct client integration with the private Runtime Host protocol.
• Paseo-side provider, registry, manifest, or icon changes.

Issue completion criteria

• maka --acp provides a working ACP v1 stdio server over the existing Runtime Host client stack.
• An ACP-compatible client can create, configure, drive, interact with, cancel, list, load, resume, and close Maka sessions.
• Text, thinking, tool, and terminal updates preserve Runtime Host correlation and ordering.
• All three current Interaction request kinds complete or close through Runtime Host.
• Branch, revision, artifact, memory, goal, and plan are available through _maka/ using existing Runtime Host authorities.
• Every PR has focused tests and leaves the full repository test suite green.
• The capability matrix accurately describes standard, extended, unsupported, and deferred behavior.

Progress-update convention

• When a Draft PR opens, link it and record the implemented boundary and verification evidence, but keep the tracker checkbox open.
• When a PR merges, mark it complete and post a short update covering what landed, what was verified, and which dependent PRs are now unblocked.

简体中文

当前代码基线

• PR 1 合入后，已按 2026-08-26 的 main@bfba25361 重新核对。
• PR 1（#3658）已落地 maka --acp stdio server、官方 @agentclientprotocol/sdk@1.4.0 依赖、纯协议 stdout、未支持方法的明确错误，以及可复用的官方 SDK 子进程测试工具。
• PR 1 有意保持启动和 initialize 仅建立 transport、不依赖 Runtime Host；首个 Host-backed Session 方法触发的惰性 Runtime Host bootstrap 已明确由 PR 2 承接。
• 当前 Runtime Host ClientHello 已不再包含 ClientSurface；私有的 surface: 'desktop' 只用于兼容旧 Host。ACP 不应新增 ClientSurface 值。
• 应复用现有 RuntimeHostConnection、ClientSessionSubscription、RuntimeHostSessionProjector、transcript 分页及重连/恢复逻辑，不建立第二套 Runtime Host client stack。
• 每个 PR 开始前重新按最新 main 核对这些事实。

跟踪规则

• PR 只有合并后才能勾选完成。
• 每个 PR 必须能够独立审查和测试。
• 每个 PR 只能依赖已经合并的前置 PR。
• 新行为的测试必须随对应 PR 一起提交。
• Runtime Host 保持唯一执行和状态权威。
• 尚未实现的 ACP 方法必须返回明确的协议错误。
• 现有 Desktop、TUI、CLI 和 Eval 行为不得受影响。

依赖关系

PR 1 → PR 2 → PR 3 → PR 4
                         ├→ PR 5 ────────┐
                         ├→ PR 6 → PR 8 ─┤
                         │       └→ PR 9 ┤
                         └→ PR 7 ────────┤
                                        └→ PR 10

---

阶段一 — 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 方法到来时，通过 connectRuntimeHostCli 惰性创建一个现有 CLI Runtime Host context；同一 ACP connection 共享该 context，并在 EOF、协议失败或进程关闭时确保只关闭一次。
  • 将 session/new 映射到 session.create，由 adapter 生成 sessionId，把 cwd 映射为 host_path workspace，并固定使用 Host 默认 modelTarget。
  • 允许空的 mcpServers 和 additionalDirectories，明确拒绝非空值；忽略 ACP _meta，不定义私有 Project ID 契约。
  • 建立唯一的 ACP session registry，负责 durable session 创建、subscription 所有权、最新 snapshot 跟踪、失败记录和幂等的连接级关闭。
  • 每个 subscription 打开后立即持续消费，避免有界 client queue 阻塞；PR 2 只记录 projection 和失败，PR 4 在同一消费入口加入 ACP event projection/streaming。
  • session/list 使用可复用的 Runtime Host 单页 catalog reader，以及绑定规范化 cwd 过滤条件、带大小限制和版本号的 opaque ACP cursor；revision 变化映射为 stale-cursor 参数错误，并跳过无法映射的 legacy record。
  • PR 2 不实现也不声明 session/close，调用继续返回 -32601；当前暂移 PR 4，PR 4 开发前必须按“取消 active turn → 关闭 subscription → 移除 adapter state”语义重新核验。
  • adapter 清理绝不删除或归档 Runtime Host durable session。创建成功但 subscription 打开失败时不重试、不回滚，错误返回已生成的 sessionId、durableSessionCreated: true 和稳定的 Runtime Host 错误分类。
  • 使用官方 SDK client 和真实 Runtime Host 进程测试有界 catalog 分页、cwd 过滤与 stale cursor、多 session 隔离、subscription 持续消费、关闭竞态、不支持输入和稳定的 Runtime Host 错误转换。
  • 验收： ACP 客户端可创建多个独立 session 并通过有界分页列出；每个 subscription 都被持续消费；仅在 Host-backed session 工作开始时连接 Runtime Host，连接/进程关闭时惰性创建的 CLI context 与全部 adapter 资源都只关闭一次；durable session 继续由 Runtime Host 管理，且 session/close 不被声明。
  • 依赖： PR 1
  • 状态： PR 已开放审查；已基于合入后的 PR 1 完成 rebase
  • PR： #3744

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

  • 每次 session/new 成功后，根据 Runtime Host 已提交的 SessionCatalogProjection 返回顺序固定、恰好四项的 ACP select configOptions。
  • 将 permission_mode 映射到 permissionMode（explore、ask、bypass）；将 thinking_level 映射到 thinkingLevel（default 对应 Host null，另含 off、minimal、low、medium、high、xhigh、max）；将 collaboration_mode 映射到 collaborationMode（agent、plan）；将 orchestration_mode 映射到 orchestrationMode（default、swarm、graph）。
  • 仅允许当前 ACP connection 所拥有的 session 调用 ACP v1 session/set_config_option；未知 option ID、错误 value 类型和不支持的值必须在 Host I/O 前拒绝。
  • 每次在线修改都先读取当前 catalog projection，再携带 expectedRevision 和完整 SessionConfiguration 调用 session.configuration.update，保留 modelTarget 与全部未变字段。
  • 遇到 revision_conflict 时重新读取 projection 并重试完整更新，最多严格执行三次。
  • 根据 Host 已提交结果返回完整四项 option projection；将校验错误、缺失/legacy projection、中断、session busy 和提交结果不确定等失败转换为稳定的 ACP 错误。
  • session/set_mode 保持不支持且不声明。ACP session/new 没有配置或 mode 输入，因此 PR 3 不表示创建期 SessionStartMode，也不把它伪装成可变配置。
  • Workspace instructions 继续由 Runtime Host 组合，不建立 ACP 侧 system-prompt 权威。
  • 测试纯 option 词汇、完整配置 CAS 与冲突重试、错误与生命周期边界、官方 SDK 路由、stdio 响应，以及真实 Runtime Host 的 create → configure 流程。
  • 验收： session/new 返回四项 Host-backed 配置，session/set_config_option 通过 Runtime Host CAS 只修改一个受支持值，不覆盖模型选择或无关配置；连续三次冲突后确定性终止，同时 session/set_mode 继续明确返回不支持。
  • 依赖： PR 2
  • 状态： Draft 已创建；实现与验证已完成，等待 PR 2
  • PR： #4051

• PR 4 — 映射 Prompt、取消与有序基础流式输出

  • session/prompt 映射到 turn.start，生成必需的 turnId，并将支持的 ACP prompt 内容转换成 Maka MessageContent。
  • 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 侧排序器：当前 subscription 会拒绝 sequence gap，projector 已处理 startOffset、reset、complete 和重连恢复。
  • ACP 事件映射保持为独立模块，并增加聚焦测试。
  • 验收： 客户端可以运行和取消完整 turn；offset、reset、重连和终止状态形成单一有序 ACP 流，并且只产生一次 end_turn。
  • 依赖： PR 3
  • 状态： 计划中
  • PR： 待创建

---

阶段二 — ACP v1 Runtime 能力

• PR 5 — 映射当前 Maka Tool 事件模型

  • tool_start → tool_call
  • tool_output_delta、tool_result → tool_call_update
  • 为当前额外存在的 tool_progress 和 tool_result_preview 定义明确的 ACP update 行为，不得静默丢弃。
  • 在 ACP 能表达的范围内保持 toolUseId/tool-call identity、output sequence、stream、redaction、result status 和 duration。
  • 复用投影后的 SessionEvent，不二次解析 Runtime Host frame。
  • 验收： 单个、并发、preview 和流式 tool call 都保持关联和顺序，end_turn 只在 terminal tool/turn 状态后产生。
  • 依赖： PR 4
  • 状态： 计划中
  • PR： 待创建

• PR 6 — 桥接当前全部 Interaction Request 类型

  • 处理当前 InteractionRequest union：permission、sandbox_boundary 和 question。
  • 将 permission 和 ACP 可表达的 sandbox_boundary 映射为 permission_request。
  • 将 ACP permission response 映射到现有 typed interaction.answer operation。
  • 因 ACP v1 没有标准 elicitation，通过 _maka/ 暴露 question request/answer。
  • 复用 SessionContinuitySnapshot.interactions 中的 pending snapshot 和现有 projector callback。
  • 处理已解决或关闭的 interaction，包括 turn_stopped、turn_terminal、timed_out 和 host_restarted。
  • 为后续扩展建立共享 _maka/ dispatch、validation、correlation 和 error 约定。
  • 验收： Permission、sandbox boundary 和 question 均通过 Runtime Host 完成或关闭，不产生第二个决策权威。
  • 依赖： PR 4
  • 状态： 计划中
  • PR： 待创建

• PR 7 — 加载和恢复现有 Session

  • 使用分页 catalog/get 契约解析现有 session，并通过当前 session subscription 路径打开。
  • 复用 subscription.open 返回的 snapshot、activeAssistantStreams 和 transcript bootstrap，不增加另一套 restore 协议。
  • 复用 ClientSessionSubscription/session-channel 对 durable/overlay 页面、watermark、cursor 和重连恢复的处理。
  • 已存在 live root turn 时直接根据 subscription snapshot 重新附着。
  • 中断 turn 先调用 turn.resume.query；只有结果为 ready 时才使用 source run 和 RuntimeEvent high-water identity 调用 turn.resume.start。
  • Parked resume reason 直接反馈，不启动重复 turn。
  • 验收： ACP 客户端可以加载多页 transcript、重新附着 live turn，或安全恢复/park 中断 turn，不产生 replay 缺口、重复或 identity 变化。
  • 依赖： PR 4
  • 状态： 计划中
  • PR： 待创建

---

阶段三 — Maka 扩展命名空间

• PR 8 — 暴露 Branch、Revision 和 Artifact Operation

  • 基于现有 typed Runtime Host operation 定义稳定的 _maka/ request/response 名称。
  • Branch/revision 映射到 session.branch.create、session.revision.create 和 session.revision.abandon。
  • 保持 source/target session identity 和 expectedSourceRevision 冲突语义。
  • Artifact 映射到现有 artifact.query、artifact.ingest 和 artifact.delete，包括 multipart ingest identity 和 offset。
  • 复用 PR 6 的扩展校验和错误约定；adapter 不保存 branch、revision 或 artifact 状态。
  • 验收： ACP 客户端可通过经过测试的 _maka/ 契约使用现有 Runtime Host branch、revision 和 artifact 权威。
  • 依赖： PR 6
  • 状态： 计划中
  • PR： 待创建

• PR 9 — 暴露 Memory、Goal 和 Plan Operation

  • 基于现有 typed Runtime Host operation 定义稳定的 _maka/ request/response 名称。
  • Memory 映射到 memory.query 和 memory.mutate。
  • Goal 映射到 goal.query、goal.arm 和 goal.control。
  • Plan 映射到 plan.query、plan.control 和 plan.turn.start。
  • 保持现有 revision/control result 和 Runtime Host error contract。
  • 所有 memory、goal 和 plan 状态继续保存在 Runtime Host。
  • 验收： ACP 客户端可通过经过测试的 _maka/ 契约使用现有 Runtime Host memory、goal 和 plan 权威。
  • 依赖： PR 6
  • 状态： 计划中
  • PR： 待创建

---

阶段四 — 文档与兼容性

• PR 10 — 增加能力矩阵和最终一致性覆盖
  • 记录直接支持的 ACP v1 方法、_maka/ 扩展、对应 Runtime Host operation、不支持行为和 ACP v2 迁移边界。
  • 明确 Runtime Host 当前已支持 current-turn message submission；ACP v1 缺少标准 steering 方法，因此限制属于 adapter 协议面，而不是 Maka Runtime Host。
  • 记录 question、sandbox boundary、tool progress/preview、workspace instructions 和 usage/context 信息的处理方式。
  • 增加跨 PR 子进程测试：create → configure → prompt → stream → interact → cancel/complete → close。
  • 增加 load → transcript bootstrap/page → live reattach 或 interrupted-turn resume 覆盖。
  • 增加端到端 _maka/ 扩展覆盖，但不把前面各 PR 的功能测试延期到本 PR。
  • 使用 ACP 兼容客户端执行 smoke test，并运行仓库测试和 CLI 第三方依赖声明检查。
  • 验收： 每个已记录为支持的能力都有测试证据，ACP 兼容客户端可以创建、驱动、交互、取消、加载、恢复和关闭 Maka session。
  • 依赖： PR 5、PR 7、PR 8、PR 9
  • 状态： 计划中
  • PR： 待创建

---

明确延期

• ACP v2 draft-only 行为。
• 在 ACP 定义兼容方法前，延期 ACP mid-turn steering/input injection；现有 Runtime Host steering 保持不变。
• 协议定义标准 elicitation 前不实现标准 ACP elicitation；Maka question 初期使用 _maka/。
• 直接集成私有 Runtime Host 协议。
• Paseo 侧 provider、registry、manifest 或 icon 修改。

Issue 完成条件

• maka --acp 基于现有 Runtime Host client stack 提供可用 ACP v1 stdio server。
• ACP 兼容客户端可以创建、配置、驱动、交互、取消、列出、加载、恢复和关闭 Maka session。
• Text、thinking、tool 和 terminal update 保持 Runtime Host correlation 和顺序。
• 当前三类 Interaction request 都通过 Runtime Host 完成或关闭。
• Branch、revision、artifact、memory、goal 和 plan 通过 _maka/ 使用现有 Runtime Host 权威。
• 每个 PR 都有聚焦测试，并保持完整仓库测试通过。
• 能力矩阵准确描述标准、扩展、不支持和延期行为。

进度更新约定

• Draft PR 创建时加入链接，并记录实现边界和验证证据，但保持 tracker checkbox 未勾选。
• PR 合并后勾选完成，并发布简短更新，说明已合并内容、验证证据及新解锁的依赖 PR。

[Sun-GLiang]

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.