synapse-cli-agent 0.1.30__tar.gz → 0.1.32__tar.gz

{synapse_cli_agent-0.1.30 → synapse_cli_agent-0.1.32}/.github/workflows/release.yml

@@ -63,14 +63,17 @@ jobs:
           - name: windows
             os: windows-latest
             artifact: executable-windows
+            binname: synapse-windows-x64.exe
           # macOS executables target Apple Silicon only; Intel macOS is unsupported
           # (matches the native-core-tool wheels matrix).
           - name: macos
             os: macos-latest
             artifact: executable-macos
+            binname: synapse-macos-arm64
           - name: linux
             os: ubuntu-latest
             artifact: executable-linux
+            binname: synapse-linux-x64
     steps:
       - uses: actions/checkout@v4
 
@@ -100,15 +103,24 @@ jobs:
             --collect-all texicode `
             src/synapse/entry.py
 
+      - name: Rename executable for artifact
+        shell: pwsh
+        run: |
+          $ext = if ($env:RUNNER_OS -eq 'Windows') { '.exe' } else { '' }
+          # Rename-Item refuses a destination that contains a path separator
+          # (pwsh treats it as a device path); Move-Item -LiteralPath is safe.
+          Move-Item -LiteralPath "dist/synapse$ext" -Destination "dist/${{ matrix.binname }}"
+          Write-Host "Renamed to ${{ matrix.binname }}"
+
       - name: Fix executable permission (Unix)
         if: runner.os != 'Windows'
-        run: chmod +x dist/synapse
+        run: chmod +x "dist/${{ matrix.binname }}"
 
       - name: Upload executable artifact
         uses: actions/upload-artifact@v4
         with:
           name: ${{ matrix.artifact }}
-          path: dist/synapse*
+          path: dist/${{ matrix.binname }}
           if-no-files-found: error
 
   release:

{synapse_cli_agent-0.1.30 → synapse_cli_agent-0.1.32}/.gitignore

@@ -49,3 +49,6 @@ landing/
 # OS
 Thumbs.db
 .DS_Store.tmp/
+
+# Local release executables (build artifacts, not committed)
+synapse-*.exe

synapse_cli_agent-0.1.32/.zed/settings.json

@@ -0,0 +1,5 @@
+// Folder-specific settings
+//
+// For a full list of overridable settings, and general information on folder-specific settings,
+// see the documentation: https://zed.dev/docs/configuring-zed#settings-files
+{}

{synapse_cli_agent-0.1.30 → synapse_cli_agent-0.1.32}/CHANGELOG.md

@@ -8,6 +8,41 @@ All entries are written in English.
 
 ---
 
+## v0.1.32
+
+### New Features
+
+- Added the ACP v1 adapter: a full agent collaboration protocol server exposing session lifecycle, permissions, content/prompt handling, per-session MCP servers, client services, and streaming plan/diff events. See `docs/acp-adapter/` for the capability matrix and phase documentation.
+- ACP provider management and model selection: clients can manage providers, select the active model per session, and send image prompts.
+- ACP sessions are bridged to the project-level TUI session store, so TUI and ACP clients share the same per-project recent-session history.
+- The herdr integration now reports agent lifecycle state (startup, turn, shutdown) to the herdr backend.
+
+### Bug Fixes
+
+- Fixed ACP ignoring the project's `mcp.json`: project MCP servers are now always merged with MCP servers supplied by the client.
+- Fixed placeholder-titled sessions staying invisible in the TUI recent-sessions view: listing ACP sessions now repairs sessions created before the TUI bridge existed, and Zed's global history request (without `cwd`) includes TUI sessions through the user-level project projection.
+- Fixed the transcript projection migration worker failing under the packaged Windows executable: frozen builds now route through a hidden `transcript-migration-worker` CLI subcommand instead of `python -m ... --worker`.
+
+### Engineering
+
+- Extracted the shared `run_transcript_migration_worker` worker body so source installs and frozen binaries execute identical migration logic.
+- Extended ACP bridge and migration tests to cover placeholder-title repair, global history merging, and the frozen worker command path.
+
+---
+
+## v0.1.31
+
+### New Features
+
+- The `Ctrl+O` / `Ctrl+Tab` recent-sessions switcher now lists the most recently changed sessions across every registered project (from the user-layer catalog) instead of current-project history only, and marks each row's live runtime status (`running` / `queued` / `idle` / `cold`, etc.). Sessions without an in-process runtime are shown as cold history, and the list degrades gracefully to the legacy view when the catalog is unavailable.
+
+### Bug Fixes
+
+- Fixed the standalone Windows executable exiting immediately after launch: the PyInstaller entry script only defined `main()` without invoking it, so the packaged binary ran the top-level code and quit. `synapse.entry` now has an `if __name__ == "__main__"` guard and the packaged executable runs the CLI correctly.
+- Fixed the release executable assets: the Linux and macOS binaries shared the same filename (`synapse`) and overwrote each other when merged into the release. Each platform is now uploaded under a distinct name: `synapse-windows-x64.exe`, `synapse-macos-arm64`, and `synapse-linux-x64`.
+
+---
+
 ## v0.1.30
 
 ### New Features

{synapse_cli_agent-0.1.30 → synapse_cli_agent-0.1.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: synapse-cli-agent
-Version: 0.1.30
+Version: 0.1.32
 Summary: Local coding agent built on LangChain Deep Agents (LocalShell, no sandbox)
 Project-URL: Homepage, https://github.com/alex8224/synapse-agent
 Project-URL: Repository, https://github.com/alex8224/synapse-agent
@@ -199,6 +199,7 @@ License:                                  Apache License
            limitations under the License.
 License-File: LICENSE
 Requires-Python: >=3.12
+Requires-Dist: agent-client-protocol==0.12.0
 Requires-Dist: aiosqlite==0.22.1
 Requires-Dist: deepagents==0.6.12
 Requires-Dist: httpx[socks]==0.28.1
@@ -286,11 +287,13 @@ floating project drawer: it lists every registered project, groups their
 sessions, marks live runtime status, and lets you switch sessions in place or
 jump to another project (the TUI restarts into that project).
 
-Press `Ctrl+Tab` for a lighter active-session switcher: it lists only sessions
-that are doing work right now (across projects), lets you `Tab` / `Shift+Tab`
-through them and `Enter` to switch — the old session keeps running in the
-background and is never cancelled.  Some terminals never forward `Ctrl+Tab` to
-the app; `Ctrl+O` is a drop-in alternative.
+Press `Ctrl+Tab` for a global recent-sessions switcher: it lists the most
+recently changed sessions across every registered project (from the user-layer
+catalog), marks each one's live runtime status — `running` / `queued` /
+`idle` / `cold`, etc. — lets you `Tab` / `Shift+Tab` through them and `Enter`
+to switch.  The old session keeps running in the background and is never
+cancelled.  Some terminals never forward `Ctrl+Tab` to the app; `Ctrl+O` is a
+drop-in alternative.
 
 <details>
 <summary><b>Or run from source</b></summary>
@@ -358,6 +361,46 @@ Type `/help` in the TUI for the full reference. The essentials:
 | `/safety <profile>` | Switch safety profiles |
 | `/approve` · `/reject` | Human-in-the-loop decisions |
 
+## ACP v1 adapter
+
+The package also installs the standalone `synapse-acp` stdio entry point. It
+uses the locked `agent-client-protocol==0.12.0` dependency and keeps stdout
+reserved for ACP JSON-RPC; diagnostics go to stderr.
+
+```bash
+# Run from an installed package
+synapse-acp
+
+# Run from a source checkout
+uv run synapse-acp
+```
+
+For a client such as Zed, configure the ACP agent as a subprocess whose command
+is `synapse-acp` (or the absolute path to that executable). The adapter accepts
+absolute `cwd` values and session-scoped MCP servers. MCP credentials are used
+only for the live session and are not written to the ACP catalog or transcript.
+
+The published capability set currently covers text prompts, image prompts,
+permission/HITL, session load/list/close/delete/resume, session-local
+mode/config, HTTP/SSE MCP configuration, model selection via
+`providers/list`/`providers/set`, and capability-gated Client filesystem/
+terminal tools. Thinking level maps directly to Synapse levels (`off`,
+`minimal`, `low`, `medium`, `high`, `max`). Audio, embedded-context,
+authentication/logout, elicitation, NES, and document-sync capabilities are
+not advertised until their runtime semantics and interoperability tests exist.
+
+Troubleshooting:
+
+- stdout is reserved for ACP JSON-RPC; any log line on stdout breaks the
+  protocol. Logs and startup traces go to stderr.
+- `cwd` and `additionalDirectories` must be absolute paths; relative paths are
+  rejected with an ACP error.
+- Session metadata lives in `~/.synapse/acp-sessions.sqlite`; MCP credentials
+  and headers are never persisted there.
+- If a client reports "Method not found", verify it negotiates the same ACP
+  protocol version and does not rely on `not_target` methods (auth, providers,
+  elicitation, NES, document sync).
+
 ## Pick a model
 
 Synapse works with any OpenAI-compatible endpoint. Configure profiles in `~/.synapse/models.json` (or `<workspace>/.synapse/models.json`):
@@ -390,6 +433,7 @@ For a zero-config Codex experience, use the OAuth profile — see [Models](docs/
 | [Skills](docs/skills.md) | Bundled skills and the Agent Skills format |
 | [Permissions](docs/permissions.md) | Read-only mode and approval flows |
 | [Install](docs/install.md) | All installation methods |
+| [ACP adapter](docs/acp-adapter/index.md) | ACP v1 setup, capability matrix, limitations, and verification status |
 
 ## Repository layout
 

{synapse_cli_agent-0.1.30 → synapse_cli_agent-0.1.32}/README.md

@@ -55,11 +55,13 @@ floating project drawer: it lists every registered project, groups their
 sessions, marks live runtime status, and lets you switch sessions in place or
 jump to another project (the TUI restarts into that project).
 
-Press `Ctrl+Tab` for a lighter active-session switcher: it lists only sessions
-that are doing work right now (across projects), lets you `Tab` / `Shift+Tab`
-through them and `Enter` to switch — the old session keeps running in the
-background and is never cancelled.  Some terminals never forward `Ctrl+Tab` to
-the app; `Ctrl+O` is a drop-in alternative.
+Press `Ctrl+Tab` for a global recent-sessions switcher: it lists the most
+recently changed sessions across every registered project (from the user-layer
+catalog), marks each one's live runtime status — `running` / `queued` /
+`idle` / `cold`, etc. — lets you `Tab` / `Shift+Tab` through them and `Enter`
+to switch.  The old session keeps running in the background and is never
+cancelled.  Some terminals never forward `Ctrl+Tab` to the app; `Ctrl+O` is a
+drop-in alternative.
 
 <details>
 <summary><b>Or run from source</b></summary>
@@ -127,6 +129,46 @@ Type `/help` in the TUI for the full reference. The essentials:
 | `/safety <profile>` | Switch safety profiles |
 | `/approve` · `/reject` | Human-in-the-loop decisions |
 
+## ACP v1 adapter
+
+The package also installs the standalone `synapse-acp` stdio entry point. It
+uses the locked `agent-client-protocol==0.12.0` dependency and keeps stdout
+reserved for ACP JSON-RPC; diagnostics go to stderr.
+
+```bash
+# Run from an installed package
+synapse-acp
+
+# Run from a source checkout
+uv run synapse-acp
+```
+
+For a client such as Zed, configure the ACP agent as a subprocess whose command
+is `synapse-acp` (or the absolute path to that executable). The adapter accepts
+absolute `cwd` values and session-scoped MCP servers. MCP credentials are used
+only for the live session and are not written to the ACP catalog or transcript.
+
+The published capability set currently covers text prompts, image prompts,
+permission/HITL, session load/list/close/delete/resume, session-local
+mode/config, HTTP/SSE MCP configuration, model selection via
+`providers/list`/`providers/set`, and capability-gated Client filesystem/
+terminal tools. Thinking level maps directly to Synapse levels (`off`,
+`minimal`, `low`, `medium`, `high`, `max`). Audio, embedded-context,
+authentication/logout, elicitation, NES, and document-sync capabilities are
+not advertised until their runtime semantics and interoperability tests exist.
+
+Troubleshooting:
+
+- stdout is reserved for ACP JSON-RPC; any log line on stdout breaks the
+  protocol. Logs and startup traces go to stderr.
+- `cwd` and `additionalDirectories` must be absolute paths; relative paths are
+  rejected with an ACP error.
+- Session metadata lives in `~/.synapse/acp-sessions.sqlite`; MCP credentials
+  and headers are never persisted there.
+- If a client reports "Method not found", verify it negotiates the same ACP
+  protocol version and does not rely on `not_target` methods (auth, providers,
+  elicitation, NES, document sync).
+
 ## Pick a model
 
 Synapse works with any OpenAI-compatible endpoint. Configure profiles in `~/.synapse/models.json` (or `<workspace>/.synapse/models.json`):
@@ -159,6 +201,7 @@ For a zero-config Codex experience, use the OAuth profile — see [Models](docs/
 | [Skills](docs/skills.md) | Bundled skills and the Agent Skills format |
 | [Permissions](docs/permissions.md) | Read-only mode and approval flows |
 | [Install](docs/install.md) | All installation methods |
+| [ACP adapter](docs/acp-adapter/index.md) | ACP v1 setup, capability matrix, limitations, and verification status |
 
 ## Repository layout
 

synapse_cli_agent-0.1.32/docs/acp-adapter/capability-matrix.md

@@ -0,0 +1,152 @@
+# ACP v1 能力矩阵（SDK 0.12.0）
+
+> 基线日期：2026-08-12  
+> Python 包：`agent-client-protocol==0.12.0`  
+> wire protocol：`1`  
+> 依据：本地安装包 `acp.AGENT_METHODS`、`acp.CLIENT_METHODS`、`acp.schema` 及其字段描述。  
+> 状态：P0-P7 本地可验证范围已收口，矩阵无未解释项（`planned`/`in_progress` 均已清零）；P8 真实互通与全量门禁进行中。`verified` 仅表示已有对应专项测试证据，`implemented` 不代表真实 MCP/Zed 互通已验收。
+
+## 1. 状态定义
+
+| 状态 | 含义 |
+|---|---|
+| `planned` | 已纳入完整目标，尚未实现 |
+| `in_progress` | 当前阶段正在实现 |
+| `implemented` | handler 和必要语义已实现，但尚未完成最终合规门禁 |
+| `verified` | 已通过对应协议、错误、取消和资源测试 |
+| `not_target` | 明确不属于 ACP v1 stable；仅在升级目标时重新评审 |
+
+原则：未实现能力不得在 `initialize` 中声明。SDK 暴露的方法不等于 Synapse 已实现该能力。
+
+## 2. Agent 方法矩阵
+
+| ACP method | SDK Agent API | 分类 | 目标阶段 | 当前状态 |
+|---|---|---|---|---|
+| `initialize` | `initialize` | stable required | P1 | verified |
+| `session/new` | `new_session` | stable required | P1 | verified |
+| `session/prompt` | `prompt` | stable required | P1/P2 | verified |
+| `session/cancel` | `cancel` | stable required | P1/P3 | verified |
+| `session/load` | `load_session` | stable capability | P4 | verified |
+| `session/list` | `list_sessions` | stable capability | P4 | verified |
+| `session/delete` | SDK registry `session_delete` | stable capability | P4 | verified |
+| `session/close` | `close_session` | stable capability | P4 | verified |
+| `session/resume` | `resume_session` | stable capability | P4 | verified |
+| `session/set_mode` | `set_session_mode` | compatibility/stable schema | P7 | implemented |
+| `session/set_config_option` | `set_config_option` | stable schema | P7 | implemented |
+| `authenticate` | `authenticate` | capability-gated | P7 | not_target |
+| `logout` | SDK registry `logout` | capability-gated | P7 | not_target |
+| `session/fork` | `fork_session` | unstable in SDK 0.12.0 | P4 review | implemented |
+| `mcp/message` | `ext_method`/registry | capability/transport-dependent | P5 review | not_target |
+| `providers/list` | `list_providers`（server 路由补注册） | unstable | P7 review | implemented |
+| `providers/set` | `set_provider`（server 路由补注册） | unstable | P7 review | implemented |
+| `providers/disable` | no high-level Agent method | unstable | P7 review | not_target |
+| `nes/start` | no high-level Agent method | unstable | P7 review | not_target |
+| `nes/suggest` | no high-level Agent method | unstable | P7 review | not_target |
+| `nes/accept` | no high-level Agent method | unstable | P7 review | not_target |
+| `nes/reject` | no high-level Agent method | unstable | P7 review | not_target |
+| `nes/close` | no high-level Agent method | unstable | P7 review | not_target |
+| `document/didOpen` | no high-level Agent method | unstable | P7 review | not_target |
+| `document/didChange` | no high-level Agent method | unstable | P7 review | not_target |
+| `document/didClose` | no high-level Agent method | unstable | P7 review | not_target |
+| `document/didSave` | no high-level Agent method | unstable | P7 review | not_target |
+| `document/didFocus` | no high-level Agent method | unstable | P7 review | not_target |
+
+说明：SDK 0.12.0 的 `Agent` 类仍提供 `ext_method`/`ext_notification`，但不能把未知或 unstable 方法自动视为已支持。P0 只记录事实，最终是否实现以稳定协议范围和项目能力评审为准。
+
+## 3. Agent capabilities 矩阵
+
+| Capability | schema 字段 | 目标阶段 | 当前状态 |
+|---|---|---|---|
+| 基础 Agent | `agentCapabilities` | P1 | verified |
+| Session load | `loadSession` | P4 | verified |
+| Prompt image | `promptCapabilities.image` | P2 | implemented |
+| Prompt audio | `promptCapabilities.audio` | P7 review | not_target |
+| Embedded context | `promptCapabilities.embeddedContext` | P2 | not_target |
+| MCP HTTP | `mcpCapabilities.http` | P5 | implemented |
+| MCP SSE | `mcpCapabilities.sse` | P5 review | implemented |
+| MCP ACP | `mcpCapabilities.acp` | P5 review | not_target |
+| Session list | `sessionCapabilities.list` | P4 | verified |
+| Session delete | `sessionCapabilities.delete` | P4 | verified |
+| Additional directories | `sessionCapabilities.additionalDirectories` | P4 | implemented |
+| Session fork | `sessionCapabilities.fork` | P4 review | implemented |
+| Session resume | `sessionCapabilities.resume` | P4 | verified |
+| Session close | `sessionCapabilities.close` | P4 | verified |
+| Authentication | `auth` / `authMethods` | P7 | not_target |
+| Providers | `providers` | P7 review | implemented |
+| Config options | session config option fields | P7 | implemented |
+| NES | `nes` | P7 review | not_target |
+| Position encoding | `positionEncoding` | P7 review | not_target |
+
+## 4. Client methods Agent 需要调用
+
+| ACP method | SDK Client API | 输入 capability | 目标阶段 | 当前状态 |
+|---|---|---|---|---|
+| `session/update` | `session_update` | 基础 | P2 | verified |
+| `session/request_permission` | `request_permission` | 基础 permission | P3 | verified |
+| `fs/read_text_file` | `read_text_file` | `clientCapabilities.fs.readTextFile` | P6 | implemented |
+| `fs/write_text_file` | `write_text_file` | `clientCapabilities.fs.writeTextFile` | P6 | implemented |
+| `terminal/create` | `create_terminal` | `clientCapabilities.terminal` | P6 | implemented |
+| `terminal/output` | `terminal_output` | `terminal` | P6 | implemented |
+| `terminal/wait_for_exit` | `wait_for_terminal_exit` | `terminal` | P6 | implemented |
+| `terminal/kill` | `kill_terminal` | `terminal` | P6 | implemented |
+| `terminal/release` | `release_terminal` | `terminal` | P6 | implemented |
+| `mcp/connect` | no direct high-level workflow | MCP capability | P5 review | not_target |
+| `mcp/message` | no direct high-level workflow | MCP capability | P5 review | not_target |
+| `mcp/disconnect` | no direct high-level workflow | MCP capability | P5 review | not_target |
+| `elicitation/create` | `create_elicitation` | Client elicitation capability | P7 review | not_target |
+| `elicitation/complete` | `complete_elicitation` | Client elicitation capability | P7 review | not_target |
+
+## 5. ContentBlock 矩阵
+
+| 类型 | SDK 类型 | Prompt 输入 | Agent 输出/工具内容 | 目标阶段 | 当前状态 |
+|---|---|---:|---:|---|---|
+| `text` | `TextContentBlock` | 必选 | 必选 | P1/P2 | verified |
+| `image` | `ImageContentBlock` | capability | capability | P2 | not_target |
+| `audio` | `AudioContentBlock` | capability | capability | P7 review | not_target |
+| `resource_link` | `ResourceContentBlock` | 必选基线 | tool/content | P2/P4 | verified |
+| `resource` | `EmbeddedResourceContentBlock` | `embeddedContext` | content | P2/P4 | implemented |
+| tool text | `ContentToolCallContent` | - | tool content | P2 | verified |
+| file edit | `FileEditToolCallContent` | - | tool content | P2 | verified |
+| terminal ref | `TerminalToolCallContent` | - | tool content | P6 | implemented |
+
+## 6. SessionUpdate 矩阵
+
+SDK 0.12.0 的 `SessionNotification.update` 联合类型包括：
+
+| `sessionUpdate` | SDK 类型 | 目标阶段 | 当前状态 |
+|---|---|---|---|
+| `user_message_chunk` | `UserMessageChunk` | P2/P4 | implemented |
+| `agent_message_chunk` | `AgentMessageChunk` | P1/P2 | verified |
+| `agent_thought_chunk` | `AgentThoughtChunk` | P2 | verified |
+| `tool_call` | `ToolCallStart` | P2 | verified |
+| `tool_call_update` | `ToolCallProgress` | P2 | verified |
+| `plan` | `AgentPlanUpdate` | P2 | verified |
+| `plan_content` | `AgentPlanContentUpdate` | P2 | not_target |
+| `plan_removed` | `AgentPlanRemovedUpdate` | P2 | verified |
+| `available_commands_update` | `AvailableCommandsUpdate` | P7 | verified |
+| `current_mode_update` | `CurrentModeUpdate` | P7 | verified |
+| `config_option_update` | `ConfigOptionUpdate` | P7 | verified |
+| `session_info_update` | `SessionInfoUpdate` | P4/P7 | verified |
+| `usage_update` | `UsageUpdate` | P2/P7 | verified |
+
+## 7. 非 SessionUpdate 输出模型
+
+| 模型 | 用途 | 目标阶段 | 当前状态 |
+|---|---|---|---|
+| `PromptResponse` | prompt 终态和可选 usage | P1/P2 | verified |
+| `Usage` | 累计 token usage | P2/P7 | verified |
+| `RequestPermissionResponse` | Client permission 决策 | P3 | verified |
+| `NewSessionResponse` | session ID/config/mode | P1/P7 | verified |
+| `LoadSessionResponse` | load 配置/mode | P4/P7 | verified |
+| `ResumeSessionResponse` | resume 配置/mode | P4/P7 | verified |
+| `ForkSessionResponse` | fork session ID | P4 review | implemented |
+| `ListSessionsResponse` | session page/cursor | P4 | verified |
+| `CloseSessionResponse` | close acknowledgement | P4 | verified |
+
+## 8. P0 结论
+
+- SDK 版本和 wire protocol 已锁定，满足 P0-01/P0-02。
+- Agent、Client、capability、ContentBlock、SessionUpdate 和响应类型均已登记，满足 P0-03 的事实提取要求。
+- P0-04 的“handler/test 可追溯”在后续实现阶段以本表的目标阶段和测试任务为索引继续维护。
+- `not_target` 只表示当前目标不包含 SDK 标记为 unstable、且项目当前没有对应产品语义的能力；若 ACP v1 stable 或项目需求变化，必须通过 ADR 重新评审，不得静默删除。
+- 当前声明只包含 initialize 已实现并有行为证据的能力；未声明能力必须返回协议不支持/非法参数错误，不能静默接收。

synapse_cli_agent-0.1.32/docs/acp-adapter/decisions.md

@@ -0,0 +1,117 @@
+# ACP 适配架构决策记录
+
+> 状态：持续维护。  
+> 实时实施状态见 [progress.md](progress.md)。
+
+## ADR-001：使用官方 Python SDK
+
+- 状态：Accepted
+- 决策：依赖 `agent-client-protocol`，通过 `acp.run_agent` 提供 stdio 服务。
+- 不采用：`deepagents-acp`、自研 JSON-RPC/schema。
+- 原因：协议 schema 和 transport 应由官方 SDK 维护；Synapse 只负责自身 runtime 的语义适配。
+- 约束：SDK 必须精确锁版本，升级先做 schema/API diff。
+
+## ADR-002：目标是完整 ACP v1 Agent 语义
+
+- 状态：Accepted
+- 决策：P0 从锁定 schema 建立完整矩阵，P8 逐项关闭。
+- 原因：允许阶段性交付，但不能把“最小可互通”误当最终范围。
+- 约束：稳定方法、capability、ContentBlock、SessionUpdate 和错误语义都必须进入矩阵。
+
+## ADR-003：ACP 是 runtime 的外部适配器
+
+- 状态：Accepted
+- 决策：`synapse.acp` 依赖 `synapse.runtime`，runtime 不依赖 ACP SDK。
+- 原因：TUI、CLI、Web 和 ACP 应共享同一 headless runtime，不形成多套 Agent loop。
+- 约束：ACP handler 不直接调用 Agent 原始 `astream()`。
+
+## ADR-004：独立 stdio 入口
+
+- 状态：Accepted
+- 决策：新增 `synapse-acp` console script，不复用现有交互式 CLI 启动路径。
+- 原因：ACP stdout 必须只包含有效 JSON-RPC 消息。
+- 约束：日志、trace 和诊断只能写 stderr 或文件。
+
+## ADR-005：capability 单一真源
+
+- 状态：Accepted
+- 决策：由 `CapabilityRegistry` 同时驱动 initialize 声明、handler guard 和测试参数化。
+- 原因：避免声明支持但没有实现，或实现存在但永远不声明。
+- 约束：capability 只能在对应阶段门禁通过后启用。
+
+## ADR-006：一个 ACP session 对应一个隔离的 SessionRuntime
+
+- 状态：Accepted
+- 决策：session descriptor 固定 cwd、additional directories、MCP、Client capability 和 config。
+- 原因：会话是执行、取消、权限和资源隔离域。
+- 约束：同 session prompt 排他，不同 session 在全局上限内并发。
+
+## ADR-007：Permission 在同一 ACP prompt 内闭环
+
+- 状态：Accepted
+- 决策：一个 ACP prompt 可以驱动普通 turn 和多个 LangGraph resume turn。
+- 原因：Synapse 当前 HITL 以 turn 为边界，而 ACP permission 属于一个未结束的 prompt 生命周期。
+- 约束：cancel 必须同时结束活跃 turn 和 pending permission requests。
+
+## ADR-008：语义事件优先增强 runtime
+
+- 状态：Accepted
+- 决策：缺失的 tool args、diff、plan、usage 等先加入 UI-independent `TurnEvent`，再投影 ACP。
+- 原因：禁止 ACP 层重复解析 provider/LangGraph 原始 chunk；TUI 也可复用增强语义。
+- 约束：事件版本变化必须保持兼容或显式升级。
+
+## ADR-009：线程边界使用有界事件桥
+
+- 状态：Accepted
+- 决策：broker callback 通过 `loop.call_soon_threadsafe` 投递到 ACP loop 的有界队列。
+- 原因：Agent runtime 和 ACP server 可能运行在不同 asyncio loop/线程。
+- 约束：终态和工具事件不得丢；文本可合并但不得乱序。
+
+## ADR-010：Client-provided MCP 按 session 隔离
+
+- 状态：Accepted
+- 决策：ACP 请求携带的 MCP servers 使用 session scope pool，关闭 session 即释放。
+- 原因：Client MCP 是会话资源，不是 Synapse 全局配置。
+- 约束：不得持久化 Client MCP 凭据，不得泄漏到其他 session。
+
+## ADR-011：Client 服务有能力时优先、无能力时回退
+
+- 状态：Proposed，P6 确认
+- 决策：filesystem/terminal capability 存在时优先 Client-backed backend，否则使用本地 backend。
+- 原因：Client 能提供未保存 editor buffer 和 IDE terminal；本地 backend 保持无 Client 能力时可用。
+- 待确认：同一 Agent graph 内 backend 动态路由的具体接口。
+
+## ADR-012：协议版本基线由 P0 决定
+
+- 状态：Accepted
+- 决策：总体方案只固定 ACP v1 stable，不在调查阶段猜测具体 SDK/schema patch 版本。
+- 原因：官方 SDK 变化较快，必须以实际可安装包、源码和生成 schema 为证据。
+- 约束：P0 完成前不得提交依赖或实现代码。
+
+## ADR-013：P1 先使用可注入 SessionFactory
+
+- 状态：Accepted
+- 决策：`SynapseACPAgent` 通过 `ACPSessionRegistry` 和可注入 `SessionFactory` 连接现有 `RuntimeManager`，默认 factory 只在实际 `session/new` 时构建 Agent。
+- 原因：P1 协议测试不能依赖真实模型、API 凭据或 MCP；同时为 P4/P5 的 session descriptor 和资源隔离保留边界。
+- 约束：生产默认路径复用 `build_coding_agent`，测试路径必须注入 fake factory；不得在 ACP handler 中直接调用 `astream()`。
+
+## ADR-014：P1 不静默接受未实现的 MCP
+
+- 状态：Accepted
+- 决策：P1 handler 收到非空 `mcp_servers` 时返回明确的 invalid params；P5 实现 session-scoped MCP 后再启用。
+- 原因：P1 尚未连接 Client-provided MCP，静默忽略会违反 capability/行为一致性。
+- 约束：P1 可以接受空列表或省略字段；不得把配置写入全局 MCP 配置。
+
+## ADR-015：notification 处理、batch 不适用
+
+- 状态：Accepted
+- 决策：notification（无 `id`）由官方 SDK router/dispatcher 处理，未知 notification 静默忽略、不产生响应；JSON-RPC batch 数组不纳入 ACP 适配范围。
+- 原因：ACP wire 使用 newline-delimited JSON（每行一个 message），batch 数组不是该 framing 的合法输入；官方 SDK 亦按单条 message 处理。
+- 约束：`session/cancel` 等 notification 必须保持幂等且不依赖响应；适配层不自行解析 batch，也不伪造 batch 支持声明。
+
+## 决策更新规则
+
+- 新决策追加 ADR，不覆盖历史结论。
+- 被替代决策标记 Superseded，并链接替代 ADR。
+- SDK/schema 升级、能力范围变化、状态机变化必须记录 ADR。
+- 实时任务状态不写在本文件，统一维护于 `progress.md`。