Tracking: ACP client support in Maka Desktop, with Antigravity as the first integration (follow-up to #3132)

English

## Problem

This is a **follow-up tracking issue for #3132**, specifically the [ACP client / Antigravity use case](https://github.com/apache/maka/issues/3132#issuecomment-5594973082).

The two directions are distinct:

- #3132 exposes Maka as an ACP **agent/server** through `maka --acp`.
- This issue makes Maka an ACP **client**, allowing users to run an external agent inside Maka Desktop. Google Antigravity is the first concrete integration and acceptance case.

Users need to select an external execution agent, authenticate it, and use it through Maka's existing conversation interface. Adding each agent as a bespoke chat integration would duplicate session, interaction, history, and UI logic. Treating a complete external agent as an AI SDK model provider would also conflate agent-owned execution with Maka-owned model/tool execution.

This work does not expand the server scope of #3132 or restore the retired `gemini-cli` / Antigravity account-provider preview from #3054. The new integration uses Google's official ACP agent as a separate execution backend.

## Desired outcome

### User-visible result

A user can configure a locally installed official Antigravity ACP executable, sign in with Google, select Antigravity and a model in the Maka Desktop composer, and complete a coding task through Maka. The existing conversation surface shows streamed replies, tool activity, output, file diffs, permission choices, and agent questions. The user can stop execution and, after restarting, resume the same external session.

The Antigravity process runs behind Maka; this does not embed the Antigravity IDE.

### Desktop design: a unified executor and model picker

Follow the interaction structure of T3 Code's [ProviderModelPicker](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/components/chat/ProviderModelPicker.tsx) and [ModelPickerSidebar](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/components/chat/ModelPickerSidebar.tsx), using Maka's existing UI primitives and styling.

Extend the existing composer model entry instead of adding a separate “Maka vs. external agent” toggle. The trigger shows the selected executor icon and model. Its popover has an executor rail on the left and that executor's model choices on the right:

```text
[Executor icon · Model name v] [Supported mode v]

+--------------------+--------------------------------+
| Execution agent | Search models |
| | |
| * Maka | Models for this executor |
| Antigravity | Model A |
| | * Model B |
| | Model C |
| | |
| Manage agents | Connection state / setup |
+--------------------+--------------------------------+
```

- Selecting the left rail browses an executor; selecting a model commits the complete executor/model choice and closes the popover.
- The Maka branch retains its existing connection groups and model choices. The Antigravity branch uses models returned by its account/session configuration, without inventing an LLM connection.
- An unconfigured or unauthenticated Antigravity entry can show setup/login actions, but cannot be committed as an executable selection.
- Initially, Maka does not override the model or mode: use the current values returned when the ACP agent creates a session. Show the concrete values when available and an honest “Agent default” label otherwise. This does not promise to inherit the user's Antigravity IDE model selection. Verify that omission is supported; if the agent requires explicit configuration, include the necessary selection and application in PR 2 rather than deferring them to PR 4.
- New drafts retain Maka's existing defaults. Do not add new global remembered-selection or project-precedence rules in this scope.
- Switching executors preserves draft text and attachments. Unsupported attachments remain visible with an actionable validation message; they are not silently removed or sent.
- Once a task exists, its executor is fixed. Model changes are allowed only while idle and when supported. Other executors explain that switching requires a new task.
- Do not copy T3's favorites, multi-account management, or entire advanced-settings surface.

| Desktop surface | Change |
| --- | --- |
| Settings | Add **External Agents** for official installation or existing-program selection, connection checks, Google sign-in, and diagnostics. |
| Composer | Extend the existing model entry with the unified picker; show only supported mode controls. |
| Conversation | Reuse existing message, tool-output, and diff presentation. |
| Interaction area | Reuse forms for external permission options and agent questions. |
| Task/history surface | Identify the executor and show interrupted, restoring, and restore-failed states. |

Task Entry continues to supply the Host/project target. Executor selection and submission belong to the existing composer/task-creation flow, not a new responsibility inside Task Entry.

### Architecture: reuse existing seams

```mermaid
flowchart TD
UI[Maka Desktop] --> Host[Runtime Host]
Host --> Backend[AgentBackend]
Backend --> Native[AiSdkBackend]
Native --> SDK[AI SDK / models]
Backend --> ACP[AcpAgentBackend]
ACP --> Client[ACP SDK connection and session handling]
Client --> Profile[Antigravity adaptation]
Profile --> Agent[Official Antigravity ACP process]
```

`AcpAgentBackend` is a sibling of `AiSdkBackend`, not an AI SDK provider or a layer inside it. Maka owns task/run identity, admission, persistence, subscriptions, and interactions. Antigravity owns its reasoning loop, tools, and execution context.

| Existing seam | Reuse |
| --- | --- |
| `AgentBackend`, `BackendRegistry`, `PreparedBackendFactory` | Register the ACP implementation and use prepare/build/send/stop/dispose. |
| SessionManager and Host execution coordination | Keep task creation, turn admission, stop, and retirement in the existing authority. |
| `SessionEvent` to `RuntimeEvent` mapping, stores, and subscriptions | Convert ACP updates into the existing event pipeline; do not add an ACP transcript store. |
| `HostedInteractionBridge` and InteractionCoordinator | Reuse admission, answers, closure, and settlement. |
| Settings request and presentation infrastructure | Reuse loading, write guards, action guards, browser opening, errors, and status presentation. |
| Existing tool and `file_diff` presentation | Adapt data rather than create an Antigravity-specific renderer. |
| History pagination and reading-position control | Continue consuming the canonical Maka transcript. |

Start with an internal ACP module in Runtime Host, not a new workspace package. Use the official ACP SDK rather than reimplement JSON-RPC. Separate shared connection/session handling from Antigravity-specific launch, authentication, and compatibility logic, but introduce extension hooks only when used. Settings checks and task execution are real consumers of the shared connection code.

Future standard ACP agents should reuse this implementation through configuration and, where necessary, small agent-specific adaptations. A future non-ACP agent can implement its own sibling backend. Do not prebuild an unused plugin/capability framework.

Existing OAuth and model UI contracts contain LLM-provider assumptions. Reuse their lower-level presentation and lifecycle primitives, but do not fabricate provider identities to force ACP authentication or model selection through them.

### Protocol, interaction, and lifecycle rules

- Use a local stdio connection and one external process per active task, owned by the Host. In PR 2, an active task includes a live session waiting for its next turn: retain its process while idle. Closing the UI does not implicitly stop a task. Retirement and Host shutdown clean up owned processes, including owned helpers. PR 2 must handle crashes, cancellation races, and cleanup itself; process loss leaves readable history with continuation explicitly unavailable until restoration is delivered.
- Convert text, tool activity, output, diffs, and completion into existing backend events. Merge partial updates by tool-call ID and preserve arrival order. Add shared event fields only with a same-PR producer and consumer.
- External tool notifications are observations, not instructions for Maka to execute the same tool. Do not fabricate Maka tool-dispatch journal entries.
- Use `HostedInteractionBridge.admitFormRequest` for external option-based interactions. Map the ACP option ID to the form's `single_select.value` and its display text to `label`; return the original ID through the existing settlement path.
- Clearly identify external permission requests and preserve the agent's allow/deny choices. Do not reinterpret them as Maka sandbox grants or route them through legacy permission events. Antigravity-specific question detection stays in its adaptation code.
- Implement the verified, necessary ACP text-file callbacks with workspace/path/symlink checks. Do not advertise terminal capability. Do not claim that agent-owned tools run inside Maka's built-in sandbox.
- Cancellation settles outstanding interactions, sends ACP cancel, and continues consuming updates until the prompt finishes. A bounded timeout terminates the owned process and records interruption rather than false successful cancellation. Preserve the actual stop reason.
- Maka stores visible history; the external agent owns its execution context. A crash does not automatically resend a prompt.
- Restore through negotiated resume/load support. Load replay is handled as restoration, not appended as a new turn. Define replay deduplication and reconciliation when the agent has progressed beyond Maka's last durable event; do not blindly discard or append all replay. If history cannot be reliably aligned, show an explicit history-gap/restoration status instead of claiming intact history. Failure keeps history readable and offers retry/new task without silently replacing the external session or resending a prompt.
- Use a Maka-managed or user-installed [official Antigravity ACP distribution](https://github.com/agentclientprotocol/registry/blob/main/antigravity-acp/agent.json), including its matching helper. The official process owns credentials. Do not assume IDE login is reusable.

PR1 setup behavior has now been exercised with official ACP 1.1.1 on macOS arm64; see #5164. Task execution, model/mode and restoration behavior are not established by these setup checks. Record and verify the actual version/platform, authentication, event shapes, cancellation, and restoration before relying on them. T3's [Antigravity adapter](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/provider/acp/AntigravityAcpSupport.ts) is an implementation reference, not a substitute for real-agent acceptance.

### Pre-implementation verification

Verify the official binary before implementing the behavior that depends on it; record the actual version/platform and sanitized evidence. Reference code and negotiated protocol support do not replace real-agent checks.

- **Before PR 1 authentication:** verify official server/helper layout, initialization, authentication methods, authorization-link output, authentication completion and process exit. Connection checks must not log in, create a session or send a prompt. PR1 setup evidence is recorded in #5164.
- **Before PR 2 execution:** verify session creation, omitted model/mode initialization, required file callbacks, text/tool/diff/permission/question events, multi-turn prompting and cancellation. Probe cross-process resume/load feasibility here as well, so the task binding does not assume unverified restoration behavior.
- **Before PR 3 restoration:** verify restoration of the same session across process restarts, replay shape, deduplication and crash-window reconciliation before implementing persistence/restoration behavior.
- **Before PR 4 configuration:** verify actual model/mode discovery, selection/application and failure behavior. Configuration required to execute belongs in PR2 and must be verified there.

If required behavior is unavailable, revise that PR's scope and acceptance criteria before implementation. Do not record credentials or private project content. Completing PR1 setup checks does not mark task, model or restoration behavior as verified.

### Incremental PR plan

The implementation order is now **settings/authentication → execution plus usable model selection → restoration → modes and catalog reconciliation**. PR 2 had to include real model discovery and first-prompt application because Antigravity is not usable from the Composer with an unresolved “Agent default”. PR 3 remains responsible only for restoring the same external session. PR 4 must extend the configuration seam rather than rebuilding model discovery.

Each PR must remain independently deliverable and verifiable. Every new production interface, field, or capability must have a real producer and consumer in the same PR, including protocol, storage, Host, and Desktop changes. Update protocol decoders and the compatibility epoch whenever required.

- [x] **PR 1 — Install, configure, connect, and authenticate from Settings** — merged in #5164.
- [x] Install the pinned official Antigravity ACP distribution or choose an existing program; verify and persist the executable through RuntimePolicy.
- [x] Check connectivity and complete Google authentication without creating a task or sending a prompt.
- [x] Reuse the shared ACP connection lifecycle and clean up temporary server/helper processes across success, failure, cancellation, and disconnect.
- [x] Cover integrity, persistence, stale-result protection, localization, diagnostics, and real macOS arm64 setup evidence.
- **Boundary:** no task execution, external session restoration, automatic discovery/upgrades, or multi-account support.

- [ ] **PR 2 — External-agent execution and usable model selection** — implemented in draft PR #5224; check the parent item only after merge.
- [x] Keep executor selection separate from the model menu. Maka and external Agents reuse the same boxed model-menu interaction and visual structure from upstream/main. This accepted UI supersedes the earlier two-column picker sketch.
- [x] Preserve draft text, attachments, and the retained Maka model while browsing executors. Commit executor plus model atomically at task creation; never route an external task through a Maka LLM connection.
- [x] Connect unconfigured, unauthenticated, and unavailable Antigravity states to the PR 1 setup/login flow. Authenticate before creating the first Maka Session so a failed preflight does not leave an empty task.
- [x] Register AcpAgentBackend as a sibling of AiSdkBackend and implement session creation, live multi-turn prompting, text/tool/output/diff projection, form-based permissions/questions, stop, failure states, and owned process/helper cleanup.
- [x] Implement required file callbacks and reject unsupported attachments and native-only operations without deleting draft content.
- [x] Discover Antigravity models through a provider-owned catalog, persist the last successful catalog in Runtime Host, keep a renderer hot cache, and prewarm on executor selection so later drafts and concurrent tasks do not each wait for a new probe.
- [x] Apply the selected model to a newly created external session before its first prompt. Existing external tasks use their live session configuration and may change model only while idle.
- [x] Preserve the selected concrete model label while live session configuration initializes; do not temporarily present it as “Agent default”.
- [x] Keep an active external process while the task is idle. After Host restart or process loss, retain readable history and explicitly reject continuation until PR 3 restoration exists.
- [x] Cover protocol, Host, Core, Desktop, UI, CLI compatibility, model isolation, first-send, cancellation, cleanup, cached-catalog, and shared-menu regressions. Latest #5224 CI is green.
- [ ] Complete final review and merge #5224.
- **Producer → consumer:** provider catalog and executor/model choice → task creation → backend/session configuration → canonical events → existing conversation/forms → answer, follow-up, model change, or stop.
- **Acceptance:** Maka model sending remains functional; selecting Antigravity immediately exposes the cached/prewarmed model list; the chosen model is applied before a real first prompt; two new Antigravity tasks reuse catalog data but own independent sessions; real follow-up, tools/diffs, interactions, cancellation, restart-to-history-only, and task isolation work.
- **Deferred:** cross-process continuation belongs to PR 3. Supported modes, provider-specific catalog scope, and account/catalog invalidation reconciliation belong to PR 4.

- [ ] **PR 3 — Restore the same external session and reconstruct its process**
- [ ] Verify cross-process resume/load, replay shape, and failure behavior against the supported official Antigravity version before relying on them.
- [ ] Persist the external session identity and required restoration metadata when the external session is created, and consume them through backend preparation in this same PR.
- [ ] Split ACP backend initialization into explicit create and restore paths. initialModel applies only to a newly created session; restoration must not call session/new as a fallback.
- [ ] Replace the PR 2 history-only restart guard only after a verified restore path exists. Tasks created without restoration metadata remain readable and unavailable for continuation; never silently create a replacement external session.
- [ ] Restore lazily when the user continues a task. Loading history or the task list must not launch every external Agent.
- [ ] Reconcile resume/load replay with canonical Maka history, deduplicate events, handle the crash window, and expose an explicit history-gap state when reliable alignment is impossible. Never automatically resend an interrupted prompt.
- [ ] Reuse existing task readiness, history, and Composer surfaces for restoring, retry, restore failure, and new-task actions.
- [ ] Complete restoration, limitation, and troubleshooting documentation plus controlled-process and real-agent verification.
- **Producer → consumer:** durable restoration metadata → backend prepare → explicit restore path → Host admission → Composer/history readiness.
- **Acceptance:** restart and continue the same real external session with intact context and no duplicate history; failure leaves history readable and never resends a prompt, switches backend, or starts a replacement session.

- [ ] **PR 4 — Supported modes and model-catalog lifecycle**
- [ ] Reuse the provider catalog/configuration module delivered by PR 2; do not add another discovery path or an Agent-specific Desktop picker.
- [ ] Discover supported modes and project them through the existing configuration area. Apply a new task's selected mode before the first prompt and allow live changes only while the task is idle and the Agent supports them.
- [ ] Define catalog scope inside each external-Agent provider adapter. Explicitly decide which of Agent, account/profile, Host, and workspace affect catalog identity; do not bake Antigravity assumptions into shared UI or Host callers.
- [ ] Revalidate the selected model/mode at actual session creation and after account or catalog changes. If a choice becomes unavailable, retain the user's prior value, block sending with an actionable state, and require an explicit replacement; never silently substitute another model.
- [ ] Update displayed configuration only after the Agent confirms a change. On failure retain the previous confirmed value and expose retry/reselection.
- [ ] Existing tasks read their own live session configuration. Draft catalog refreshes must not overwrite live-session values or change an existing task's executor.
- **Producer → consumer:** provider-scoped catalog and configuration → shared model/mode controls → ACP configuration → confirmed session value and execution.
- **Acceptance:** selected model/mode affects execution; unavailable choices cannot send and are not silently replaced; cached catalogs appear immediately; refresh is scoped correctly; keyboard navigation, focus return, narrow windows, and localization work.

### Final acceptance criteria

- [ ] With a recorded official Antigravity version, complete the Desktop path: **configure → Google sign-in → select Antigravity/model → create task → edit and test → inspect tools/diffs → answer interactions → follow up → cancel → restart and continue the same external session**.
- [ ] Maka and every external Agent provide candidates through provider-owned catalog/configuration logic and render them through the same upstream/main-style model menu; adding another provider does not duplicate Composer or Host orchestration.
- [ ] Selecting an external Agent exposes cached candidates immediately. Concurrent or subsequent new tasks reuse catalog data while keeping independent external sessions and selected configurations.
- [ ] Existing tasks cannot switch executor. Model/mode changes are idle-only, Agent-confirmed, and never silently substituted after account/catalog changes.
- [ ] Unsupported attachments and operations remain visible with actionable validation and never lose draft content.
- [ ] Controlled ACP-process tests cover event ordering, partial updates, option identity, first-prompt configuration, cancellation races, crashes, cleanup, catalog caching/invalidation, and restoration.
- [ ] Real-agent checks cover authentication, actual tools/session behavior, model/mode application, and cross-process restoration; fixtures contain no tokens or private project content.
- [ ] Existing Maka execution remains functional, and shared ACP dependency changes preserve the maka --acp server path.
- [ ] Every new production interface, field, or capability has a real same-PR consumer; shared behavior stays behind the provider/backend seams instead of spreading into Agent-specific UI branches.

### Initial scope

Local Maka Desktop on macOS arm64, local Runtime Host, and an official Antigravity ACP process installed through an explicit Install action or selected by the user. Out of scope: automatic discovery/upgrades, remote execution/OAuth forwarding, multi-account management, external subagent orchestration, steering, rewind, and cross-agent continuation. TUI product work is deferred while the Host implementation remains reusable.

## Alternatives or workarounds

- **Use Antigravity separately:** possible today, but does not provide the unified Maka task/history/interaction experience.
- **Wrap Antigravity as an AI SDK model provider:** rejected because a complete agent owns session state and tools, unlike a model call. Use a sibling `AgentBackend` implementation instead.
- **Build a separate external-agent chat stack:** rejected because Maka already has execution, interaction, persistence, and presentation seams.
- **Embed the IDE or wrap the ordinary CLI:** unnecessary for this scope because an official ACP distribution exists.
- **Implement infrastructure-only PRs before wiring UI consumers:** rejected; the PRs above deliver vertical production slices.

---

This proposal was prepared with AI assistance from the design discussion. Real-binary verification remains an explicit implementation and acceptance requirement.

中文

## 问题

这是 **#3132 的后续追踪 issue**，对应其中提出的 [ACP client / Antigravity 使用案例](https://github.com/apache/maka/issues/3132#issuecomment-5594973082)。

两个方向需要区分：

- #3132 通过 `maka --acp` 将 Maka 暴露为 ACP **Agent / 服务端**。
- 本 issue 让 Maka 成为 ACP **客户端**，使用户能够在 Maka Desktop 中运行外部 Agent，以 Google Antigravity 作为首个集成与验收案例。

用户需要选择外部执行者、完成认证，并通过 Maka 现有聊天界面使用它。如果每接入一个 Agent 都单独实现聊天集成，就会重复建设会话、交互、历史和 UI。如果将完整外部 Agent 当作 AI SDK 模型 provider，则会混淆外部 Agent 自己管理的执行循环与 Maka 管理的模型调用和工具执行。

本方案不扩大 #3132 的服务端范围，也不恢复 #3054 已退役的 `gemini-cli` / Antigravity 账户 provider 预览。新的接入方式是将 Google 官方 ACP Agent 作为独立执行 backend。

## 期望结果

### 用户最终看到的效果

用户配置本地安装的官方 Antigravity ACP 程序，完成 Google 登录，在 Maka Desktop 输入框中选择 Antigravity 和模型，然后通过 Maka 完成编码任务。现有聊天界面展示流式回复、工具活动、输出、文件 diff、权限选项和 Agent 提问。用户可以停止执行，并在重启后恢复同一个外部会话。

Antigravity 进程在 Maka 后台运行，不嵌入 Antigravity IDE。

### Desktop 设计：统一的执行者与模型选择器

参考 T3 Code 的 [ProviderModelPicker](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/components/chat/ProviderModelPicker.tsx) 与 [ModelPickerSidebar](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/components/chat/ModelPickerSidebar.tsx) 的交互结构，使用 Maka 已有 UI 基础组件与样式实现。

扩展现有 Composer 模型入口，不增加独立的“Maka / 外部 Agent”开关。按钮显示当前执行者图标和模型，展开后左侧切换执行者，右侧显示其模型：

```text
[执行者图标 · 模型名称 ▾] [支持的模式 ▾]

┌──────────────────┬────────────────────────────┐
│ 执行者 │ 搜索模型 │
│ │ │
│ ● Maka │ 当前执行者的模型列表 │
│ Antigravity │ ○ 模型 A │
│ │ ● 模型 B │
│ │ ○ 模型 C │
│ │ │
│ 管理外部 Agents │ 连接状态 / 设置入口 │
└──────────────────┴────────────────────────────┘
```

- 点击左侧只切换浏览的执行者；选择模型才提交完整的“执行者 + 模型”选择并关闭浮层。
- Maka 分支保留现有连接分组和模型选择。Antigravity 分支使用其账户或会话配置返回的模型，不伪造 LLM connection。
- 未配置或未登录的 Antigravity 可以展示设置、登录入口，但不能提交为可执行选择。
- 首版不主动覆盖模型或模式，使用 ACP Agent 新建会话时返回的当前值；返回具体值时展示实际值，否则准确显示“Agent 默认”。不承诺继承用户本地 Antigravity IDE 的模型选择。必须验证是否允许省略配置；若 Agent 要求显式配置，必要的选择与应用必须纳入 PR 2，不能推迟到 PR 4。
- 新草稿继续使用 Maka 现有默认配置，首期不新增全局选择记忆或项目优先级规则。
- 切换执行者保留草稿文本和附件。不支持的附件继续显示，并提供可操作的校验提示，不静默删除或发送。
- 任务创建后执行者固定。仅在空闲且支持时允许修改模型；选择其他执行者时提示需要新建任务。
- 不复制 T3 的收藏、多账户管理或完整高级设置界面。

| Desktop 界面 | 改动 |
| --- | --- |
| 设置 | 新增「外部 Agents」，安装官方程序或选择已有程序、检查连接、Google 登录与诊断。 |
| Composer | 扩展现有模型入口为统一选择器，仅展示支持的模式控制。 |
| 聊天 | 复用现有消息、工具输出和 diff 展示。 |
| 交互区域 | 复用表单展示外部权限选项和 Agent 提问。 |
| 任务与历史 | 标识执行者，展示中断、恢复中和恢复失败状态。 |

Task Entry 继续提供 Host 与项目目标。执行者选择及提交属于现有 Composer / 任务创建流程，不向 Task Entry 加入新的会话创建职责。

### 架构：复用已有 seam

```mermaid
flowchart TD
UI[Maka Desktop] --> Host[Runtime Host]
Host --> Backend[AgentBackend]
Backend --> Native[AiSdkBackend]
Native --> SDK[AI SDK / 模型]
Backend --> ACP[AcpAgentBackend]
ACP --> Client[ACP SDK 连接与会话处理]
Client --> Profile[Antigravity 适配]
Profile --> Agent[官方 Antigravity ACP 进程]
```

`AcpAgentBackend` 与 `AiSdkBackend` 并列，不是 AI SDK provider，也不位于 `AiSdkBackend` 内部。Maka 管理任务和 run 身份、执行准入、持久化、订阅与交互；Antigravity 管理自身推理循环、工具和执行上下文。

| 已有 seam | 复用方式 |
| --- | --- |
| `AgentBackend`、`BackendRegistry`、`PreparedBackendFactory` | 注册 ACP 实现，沿用 prepare/build/send/stop/dispose。 |
| SessionManager 与 Host 执行协调 | 任务创建、turn 准入、停止和退休继续由既有执行管理负责。 |
| `SessionEvent` 到 `RuntimeEvent` 的映射、存储与订阅 | 将 ACP 更新转入现有事件链路，不另建 ACP transcript store。 |
| `HostedInteractionBridge` 与 InteractionCoordinator | 复用交互受理、回答、关闭和结算。 |
| 设置请求与展示基础设施 | 复用加载、写入保护、操作保护、浏览器打开、错误与状态展示。 |
| 已有工具与 `file_diff` 展示 | 转换数据，不新增 Antigravity 专属渲染器。 |
| 历史分页与阅读位置控制 | 继续消费 Maka 的权威 transcript。 |

首期在 Runtime Host 内增加内部 ACP 模块，不提前新建 workspace package。使用官方 ACP SDK，不重新实现 JSON-RPC。共享连接和会话处理与 Antigravity 启动、认证、兼容逻辑分开，但仅在实际使用时增加扩展点。设置检查与任务执行是共享连接代码的真实消费者。

未来标准 ACP Agent 优先通过配置复用，必要时增加小范围厂商适配；非 ACP Agent 可以实现并列的 backend。不提前建设无人使用的插件或能力框架。

已有 OAuth 和模型 UI 契约包含 LLM provider 假设。复用底层展示与生命周期基础能力，但不通过伪造 provider 身份强行接入 ACP 认证或模型选择。

### 协议、交互与生命周期规则

- 使用本地 stdio，每个活动任务独占一个由 Host 管理的外部进程。PR 2 中活动任务包括等待下一轮输入的存活会话，空闲时保留进程。关闭 UI 不隐式停止任务；任务退休及 Host 退出时清理所属进程及其 helper。PR 2 自己完成崩溃、取消竞态和清理处理；恢复能力交付前，进程丢失后保留可读历史并明确禁止继续。
- 文本、工具活动、输出、diff 和完成状态转为现有 backend 事件。按 tool-call ID 合并局部更新，保留接收顺序。新增公共事件字段时，生产者和消费者必须同 PR 交付。
- 外部工具通知表示发生的活动，不要求 Maka 再执行同一工具。不伪造 Maka 工具调度日志。
- 外部选项交互使用 `HostedInteractionBridge.admitFormRequest`。ACP option ID 映射为表单 `single_select.value`，显示文本映射为 `label`，通过现有结算路径回传原始 ID。
- 外部权限请求明确标识来源，保留 Agent 的允许、拒绝选项。不将其解释为 Maka sandbox 授权，不经过旧 permission 事件。Antigravity 特有提问识别留在厂商适配中。
- 实现验证过且必需的 ACP 文本文件回调，检查工作目录、路径与符号链接。不声明 terminal 能力，也不宣称 Agent 自己执行的工具受 Maka 内置 sandbox 管理。
- 取消时结算待处理交互，发送 ACP cancel，继续消费更新直至 prompt 结束。超过有限等待时间则结束所属进程并记录中断，不能错误显示正常取消。保留实际 stop reason。
- Maka 保存可见历史，外部 Agent 管理执行上下文。进程崩溃不自动重发 prompt。
- 依据协商能力使用 resume/load 恢复。load 历史重放作为恢复处理，不追加为新 turn。明确重放去重与历史对齐策略，覆盖 Agent 已推进、Maka 最后事件尚未持久化的崩溃窗口，不能简单全部丢弃或追加 replay。无法可靠对齐时明确展示历史缺口或恢复状态，不宣称历史完整。失败时保留可读历史，提供重试或新建任务，不能静默替换外部会话或重发 prompt。
- 使用 Maka 托管安装或用户自行安装的[官方 Antigravity ACP 发行包](https://github.com/agentclientprotocol/registry/blob/main/antigravity-acp/agent.json)及匹配 helper。官方进程管理凭据，不假定可以复用 IDE 登录。

PR1 设置流程已使用 macOS arm64 官方 ACP 1.1.1 实测，见 #5164；这些设置验证不代表任务执行、模型/模式及恢复行为已验证。实施时必须记录并验证实际版本、平台、认证、事件结构、取消和恢复行为。T3 的 [Antigravity 适配](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/provider/acp/AntigravityAcpSupport.ts)是实现参考，不能替代真实 Agent 验收。

### 实施前真实能力验证

在实现依赖某项能力的功能前验证官方程序，记录实际版本、平台和脱敏证据。参考代码及协议能力声明不能代替真实 Agent 验证。

- **PR1 认证实施前：** 验证官方 server/helper 布局、初始化、认证方法、授权链接输出、认证完成响应与进程退出。连接检查不触发登录、不创建 session、不发送 prompt。PR1 设置流程证据见 #5164。
- **PR2 执行实施前：** 验证会话创建、省略模型/模式时的初始化、必需文件回调、文本/工具/diff/权限/问答事件、多轮 prompt 与取消；同时探测跨进程 resume/load 可行性，避免任务绑定依赖未经验证的恢复假设。
- **PR3 恢复实施前：** 验证进程重启后恢复同一会话、历史重放结构、去重与崩溃窗口对齐，再实现持久化及恢复行为。
- **PR4 配置实施前：** 验证实际模型/模式发现、选择应用及失败行为；执行必需的配置属于 PR2，必须在 PR2 验证。

必要能力不可用时，先修改对应 PR 的范围和验收标准再实施。记录中不得包含凭据或私有项目内容。PR1 设置检查完成不代表任务、模型或恢复能力已验证。

### PR 拆分实施计划

实施顺序调整为：**设置与认证 → 执行闭环与可用模型选择 → 会话恢复 → 模式与模型目录协调**。Antigravity 若只显示无法解析的“Agent 默认”就不能从 Composer 正常使用，因此真实模型发现和首条消息前应用模型已前移到 PR 2。PR 3 只负责恢复同一个外部会话；PR 4 扩展已有配置 seam，不重复建设模型发现。

每个 PR 必须可独立交付和验收。每个新增生产接口、字段或能力的生产者与真实消费者必须在同一 PR 出现，同时交付所需协议、存储、Host 与 Desktop 改动。涉及协议变更时同步更新解码器及兼容性 epoch。

- [x] **PR 1 — 在设置中安装、配置、连接与认证** — 已通过 #5164 合并。
- [x] 安装固定版本的官方 Antigravity ACP，或选择已有程序；校验后通过 RuntimePolicy 持久化程序路径。
- [x] 检查连接并完成 Google 认证；设置流程不创建任务、不发送 prompt。
- [x] 复用共享 ACP 连接生命周期，在成功、失败、取消和断开时清理临时 server/helper。
- [x] 覆盖完整性、持久化、迟到结果保护、本地化、诊断及 macOS arm64 真实设置证据。
- **边界：** 不包含任务执行、外部会话恢复、自动发现/升级或多账号。

- [ ] **PR 2 — 外部 Agent 执行闭环与可用模型选择** — 已在 Draft PR #5224 实现，合并后再勾选父项。
- [x] 执行者选择与模型菜单分开。Maka 和外部 Agent 复用 upstream/main 的同一盒式模型菜单交互及视觉结构；该已确认 UI 取代原先的双栏 picker 草图。
- [x] 浏览执行者时保留草稿文本、附件和 Maka 模型；创建任务时原子提交“执行者 + 模型”，外部任务不经过 Maka LLM connection。
- [x] 将 Antigravity 未配置、未认证和不可用状态连接到 PR 1 设置/登录流程；首个 Maka Session 创建前完成认证，预检失败不留下空任务。
- [x] 将 AcpAgentBackend 注册为 AiSdkBackend 的并列 backend，实现 session 创建、存活会话多轮 prompt、文本/工具/输出/diff 投影、表单权限/问答、停止、故障状态及所属进程/helper 清理。
- [x] 实现必需文件回调；不支持的附件和原生专属操作明确拒绝，不删除草稿内容。
- [x] 通过 provider 自己的目录发现 Antigravity 模型，在 Runtime Host 持久化最近一次成功目录，在 Renderer 保留热缓存，并在选择执行者时预热，避免后续草稿及并发任务各自等待新探测。
- [x] 新建外部 session 后、首条 prompt 前应用所选模型；已有外部任务读取实时 session 配置，仅在空闲时允许改模型。
- [x] 实时 session 配置初始化期间保留已选具体模型名称，不临时显示为“Agent 默认”。
- [x] 任务空闲时保留外部进程。Host 重启或进程丢失后历史可读，在 PR 3 提供恢复前明确拒绝继续。
- [x] 覆盖协议、Host、Core、Desktop、UI、CLI 兼容、模型隔离、首发、取消、清理、目录缓存及共享菜单回归；#5224 最新 CI 已通过。
- [ ] 完成 #5224 最终 review 并合并。
- **生产者 → 消费者：** provider 模型目录与执行者/模型选择 → 任务创建 → backend/session 配置 → 权威事件 → 现有聊天与表单 → 回答、追问、改模型或停止。
- **验收：** Maka 模型发送保持正常；选择 Antigravity 后立即展示缓存/预热的模型列表；首条真实 prompt 前应用所选模型；两个新 Antigravity 任务复用目录数据但各自拥有独立 session；真实追问、工具/diff、交互、取消、重启后只读历史及任务隔离工作正常。
- **后置：** 跨进程续接属于 PR 3；支持的模式、provider 特定目录作用域及账号/目录失效协调属于 PR 4。

- [ ] **PR 3 — 恢复同一个外部会话并重建进程**
- [ ] 实施前使用受支持的官方 Antigravity 版本验证跨进程 resume/load、重放结构及失败行为。
- [ ] 创建外部 session 时持久化 external session identity 和必要恢复元数据，并在同一 PR 的 backend prepare 中消费。
- [ ] 将 ACP backend 初始化拆成明确的 create 与 restore 路径。initialModel 只用于新建 session；恢复失败不能回退到 session/new。
- [ ] 只有验证后的恢复路径就绪后，才替换 PR 2 的重启后 history-only 保护。没有恢复元数据的旧任务保持历史可读、不可续接，不静默新建替代 session。
- [ ] 用户继续任务时惰性恢复；仅加载任务列表或历史不得启动全部外部 Agent。
- [ ] 将 resume/load 重放与 Maka 权威历史对齐，完成去重与崩溃窗口协调；无法可靠对齐时展示明确的历史缺口状态。绝不自动重发中断的 prompt。
- [ ] 复用任务就绪、历史和 Composer 界面展示恢复中、重试、恢复失败及新建任务操作。
- [ ] 补齐恢复、限制和排障文档，以及受控进程测试与真实 Agent 验证。
- **生产者 → 消费者：** 持久恢复元数据 → backend prepare → 明确 restore 路径 → Host 准入 → Composer/历史就绪状态。
- **验收：** 重启后继续同一个真实外部 session，上下文完整且历史不重复；失败时历史仍可读，不重发 prompt、不切换 backend、不新建替代 session。

- [ ] **PR 4 — 支持的模式与模型目录生命周期**
- [ ] 复用 PR 2 已交付的 provider 目录/配置模块，不增加第二套发现路径或 Agent 专属 Desktop picker。
- [ ] 发现支持的模式并投影到现有配置区域；新任务首条 prompt 前应用所选模式，已有任务仅在空闲且 Agent 支持时修改。
- [ ] 在每个外部 Agent provider adapter 内定义目录作用域，明确 Agent、账号/profile、Host、workspace 中哪些因素参与目录身份；不把 Antigravity 假设写进共享 UI 或 Host 调用方。
- [ ] 创建 session 时及账号/目录变化后重新校验所选模型/模式。选项失效时保留用户原值，阻止发送并给出可操作状态，要求用户显式改选；不得静默替换模型。
- [ ] 只有 Agent 确认修改成功后才更新显示；失败时保留之前已确认值，并提供重试/重新选择。
- [ ] 已有任务读取自己的实时 session 配置；草稿目录刷新不得覆盖实时 session 值，也不得改变已有任务的执行者。
- **生产者 → 消费者：** provider 作用域目录与配置 → 共享模型/模式控件 → ACP 配置 → 已确认 session 值与执行。
- **验收：** 所选模型/模式确实影响执行；不可用选项不能发送且不会被静默替换；缓存目录立即展示；刷新作用域正确；键盘导航、焦点返回、窄窗口和本地化状态正常。

### 最终验收标准

- [ ] 使用已记录版本的官方 Antigravity 完成完整 Desktop 流程：**配置 → Google 登录 → 选择 Antigravity/模型 → 创建任务 → 修改与测试 → 查看工具/diff → 回答交互 → 追问 → 取消 → 重启并继续同一个外部 session**。
- [ ] Maka 与每个外部 Agent 都通过 provider 自己的目录/配置逻辑提供候选项，并交给 upstream/main 风格的同一个模型菜单展示；新增 provider 不复制 Composer 或 Host 编排。
- [ ] 选择外部 Agent 后立即展示缓存候选项；并发或后续新任务复用目录数据，但保持独立外部 session 和选择配置。
- [ ] 已有任务不能切换执行者；模型/模式只在空闲时修改，由 Agent 确认，账号/目录变化后不得静默替换。
- [ ] 不支持的附件和操作保持可见并给出可操作校验，不丢失草稿内容。
- [ ] 受控 ACP 进程测试覆盖事件顺序、局部更新、选项身份、首条 prompt 配置、取消竞态、崩溃、清理、目录缓存/失效及恢复。
- [ ] 真实 Agent 检查覆盖认证、实际工具/session 行为、模型/模式应用和跨进程恢复；fixtures 不包含 token 或私有项目内容。
- [ ] Maka 现有执行保持正常，共享 ACP 依赖修改不破坏 maka --acp 服务端路径。
- [ ] 每个新增生产接口、字段或能力在同一 PR 内都有真实消费者；共享行为保留在 provider/backend seam 后面，不扩散为 Agent 专属 UI 分支。

### 首期范围

本地 macOS arm64 Maka Desktop、本地 Runtime Host，以及用户点击安装或手动选择的官方 Antigravity ACP 进程。不包含自动发现或自动升级、远程执行/OAuth 转发、多账户管理、外部子 Agent 编排、steering、会话回退或跨 Agent 续接。TUI 产品入口后续再做，Host 实现保持可复用。

## 备选方案或临时做法

- **单独使用 Antigravity：** 当前可以使用，但无法获得统一的 Maka 任务、历史与交互体验。
- **将 Antigravity 包装为 AI SDK 模型 provider：** 不采用。完整 Agent 管理会话和工具，与模型调用不同，应实现并列的 `AgentBackend`。
- **单独建设外部 Agent 聊天系统：** 不采用。Maka 已有执行、交互、持久化和展示 seam。
- **嵌入 IDE 或包装普通 CLI：** 首期无需这样做，官方已提供 ACP 发行包。
- **先提交纯基础设施 PR，再接 UI 消费者：** 不采用。上述 PR 按真实生产功能纵向交付。

---

本提案依据设计讨论，由 AI 辅助整理。官方二进制实测仍是明确的实施与验收要求。