thincoder 0.12.10 → 0.12.12

package/README.md

@@ -20,7 +20,7 @@ Design philosophy (the entire meaning of the name): if the Node standard library
 - **Memory system**: three layers (personal/project/team), FTS5 + vector RRF hybrid retrieval, git-friendly markdown format
 - **Two-phase tool scheduling**: permission prompts serialized, read-only tools parallelized, side-effect tools serialized
 - **Session persistence** ⭐0.5.0: up to 5 archive slots, `/session` to switch anytime, tool results visible after restore. Process-level isolation — multiple instances in the same directory each get their own session slot
-- **Concurrent subagents**: three roles — `explore`/`plan`/`coder` — dispatched in parallel, streaming output visible, reports land in the conversation
+- **Concurrent subagents**: three roles — `explore`/`plan`/`coder` — dispatched in parallel, streaming output visible, reports land in the conversation; per-subagent model override (`subagent` tool `model` arg or `agent.subagentModel` config — e.g. discuss with `glm-5.2`, let `deepseek-v4-flash` implement)
 - **Plan Mode**: read-only exploration + design, implement after user approval
 - **AUTO mode**: `/auto` full authorization, no confirmations on long tasks
 - **Task tracking**: `task` tool breaks down multi-step work, status bar ✓n/m live progress, auto-filters completed items
@@ -43,6 +43,14 @@ Three layers, all "query if present, skip if absent", unified hybrid retrieval:
 - **Dual-track accumulation**: conventions written manually (`memory_put`), experience extracted from sessions via `/extract` — **the LLM proposes candidates, a human confirms each y/n** before anything is stored; never fully automatic
 - **Retrieval isolation**: the Project layer is isolated by project path — project A's memories never leak into project B
 
+- **Agent Client Protocol** ⭐: `thincoder acp` exposes the agent over [ACP](https://agentclientprotocol.com/) v1 on stdio — one terminal login drives sessions from **Zed**, **JetBrains** AI chat, or **Paseo**:
+  - Streaming replies + thinking chunks; tool approval dialogs in the IDE
+  - IDE-native diffs — `write`/`edit` route through the editor buffer
+  - Persisted sessions: list / load (history replay) / resume / delete
+  - Per-session config: model / thinking / mode
+  - Setup: [docs/guides/ides.md](docs/guides/ides.md)
+
+
 ## Requirements
 
 - Node.js >= 24
@@ -85,7 +93,7 @@ thincoder upgrade
 
 Running from source: replace `thincoder` above with `node bin/thincoder.mjs`.
 
-Slash commands in the TUI: `/help`, `/model` (two-level picker: first select provider, then model; `/model <provider>:<name>` switches directly), `/provider` (add/remove providers, set keys, custom endpoints), `/think` (thinking mode toggle and reasoning effort), `/config` (view config, `/config embedkey` for the embedding key, `/config set` for parameters), `/session` (list/switch archived sessions), `/reindex` (rebuild the index), `/extract` (extract knowledge from the current session), `/restore` (restore checkpoint), `/clear`, `/exit`. High-frequency commands support abbreviations: `/h` `/x` `/m` `/p` `/t` `/c` `/n`. Typing `/` shows live matching hints in the status bar. Model picker supports search/filter — type to narrow down results.
+Slash commands in the TUI: `/help`, `/model` (two-level picker: first select provider, then model; `/model <provider>:<name>` switches directly), `/submodel` (subagent models per type — picker over global + explore/plan/coder/eng-coder slots, or `/submodel <type> <provider:model>` directly), `/shell` (platform-aware picker of available shells — e.g. `/shell` → pick Git Bash/pwsh, or `/shell "C:\Program Files\Git\bin\bash.exe"`, `/shell reset`; fixes win11 cmd encoding/command issues), `/provider` (add/remove providers, set keys, custom endpoints), `/think` (thinking mode toggle and reasoning effort), `/config` (view config, `/config embedkey` for the embedding key, `/config set` for parameters), `/session` (list/switch archived sessions), `/reindex` (rebuild the index), `/extract` (extract knowledge from the current session), `/restore` (restore checkpoint), `/clear`, `/exit`. High-frequency commands support abbreviations: `/h` `/x` `/m` `/p` `/t` `/c` `/n`. Typing `/` shows live matching hints in the status bar. Model picker supports search/filter — type to narrow down results.
 
 Environment variables: `THINCODER_API_KEY` (or `DEEPSEEK_API_KEY` / `OPENAI_API_KEY`), `THINCODER_BASE_URL`, `THINCODER_MODEL`, `SILICONFLOW_API_KEY`.
 
@@ -112,6 +120,7 @@ Environment variables: `THINCODER_API_KEY` (or `DEEPSEEK_API_KEY` / `OPENAI_API_
     },
   ],
   "activeProvider": "deepseek", // currently active provider name
+  "shell": null, // bash tool shell (win11: e.g. "C:\\Program Files\\Git\\bin\\bash.exe" or "pwsh"); null = system default — cmd on Windows (UTF-8 forced per command), /bin/sh elsewhere. TUI: /shell
   "embedding": {
     // optional: without it, retrieval is pure FTS
     "baseURL": "https://api.siliconflow.cn/v1",
@@ -120,6 +129,8 @@ Environment variables: `THINCODER_API_KEY` (or `DEEPSEEK_API_KEY` / `OPENAI_API_
   },
   "agent": {
     "maxTurns": 100, // tool-loop cap
+    "subagentModel": null, // default subagent provider/model override: "provider:model" | provider name | model name; null = inherit parent provider. Per-call: subagent tool `model` arg
+    "subagentModels": {}, // per-type override: { "explore": "...", "plan": "...", "coder": "...", "eng-coder": "..." }; priority: tool model arg > this > subagentModel > parent provider
     "compactThreshold": 100000, // context compaction threshold (approx. tokens)
   },
   "memory": {
@@ -209,6 +220,12 @@ Code conventions: pure `.mjs`, no semicolons, no npm dependencies allowed (inclu
 
 ## Changelog
 
+### 0.12.11 (2026-08)
+- **Subagent model per type** — `subagent` tool `model` arg, `config.agent.subagentModels` (per explore/plan/coder/eng-coder) and `config.agent.subagentModel` (global fallback); priority: tool arg > type > global > parent provider. `/submodel` TUI command: picker over 5 slots (global + 4 roles) with provider→model selection, or direct args (`/submodel coder deepseek:deepseek-v4-flash`).
+- **Configurable bash shell** — `config.shell` or `/shell` TUI command: platform-aware picker (Windows: pwsh/Git Bash/WSL bash; POSIX: bash/zsh/fish — availability-detected, custom path supported). Windows default cmd now forces UTF-8 per command (`chcp 65001`) — fixes garbled Chinese output on win11.
+- **Markdown table alignment fix** — `stringWidth` strips ANSI (zero display width) and rendered table rows are padded back to the computed width; inline markers (`` `code` ``, `**bold**`) no longer shift the borders.
+- **sliceByWidth keeps ANSI sequences whole** — never slices mid-escape-sequence.
+
 ### 0.12.10 (2026-08)
 - **Code-quality pass (advisor subsystem):**
   - **Drop 11 unused exports** — internal-use symbols no longer leak through the module API (advisor table headers/constants, plan reminders, token-UUID helper, shrinkOversized).

package/bin/thincoder.mjs

@@ -7,6 +7,7 @@
  *   thincoder memory <sub>    Memory management: list / search / put / remove
  *   thincoder upgrade         Update to the latest version from npm
  *   thincoder completion <sh> Shell completion: bash / zsh / fish
+ *   thincoder acp             Agent Client Protocol server (stdio, for Zed/JetBrains/Paseo)
  *   thincoder -v              Print version
  *   thincoder --help          Print help
  */
@@ -40,6 +41,7 @@ const USAGE = `thincoder - thin coding agent
 Usage:
   thincoder                 Launch the interactive TUI
   thincoder chat [--auto] <prompt>   One-shot agent run (tools enabled), streams reply to stdout; --auto approves all tool calls
+  thincoder acp             Agent Client Protocol server (stdio — Zed/JetBrains/Paseo drive sessions)
   thincoder memory list [--type=<t>]           List memory entries
   thincoder memory search <query>              Search memory
   thincoder memory put --type=<t> --title=<t> --content=<c> [--tags=<t>]
@@ -278,7 +280,7 @@ switch (command) {
     distill) COMPREPLY=( \\$(compgen -W "--yes --scope=" -- "\\$cur") ) ;;
     completion) COMPREPLY=( \\$(compgen -W "bash zsh fish" -- "\\$cur") ) ;;
     *)
-      COMPREPLY=( \\$(compgen -W "chat memory sync reindex distill upgrade completion -v --version -h --help" -- "\\$cur") ) ;;
+      COMPREPLY=( \\$(compgen -W "chat acp memory sync reindex distill upgrade completion -v --version -h --help" -- "\\$cur") ) ;;
   esac
 }
 complete -F _thincoder thincoder
@@ -297,6 +299,7 @@ _thincoder() {
     cmd)
       _values 'command' \\
         'chat[One-shot agent run with tools]' \\
+        'acp[Agent Client Protocol server for IDEs]' \\
         'memory[Manage long-term memory]' \\
         'sync[Sync team memory repo]' \\
         'reindex[Rebuild local index from markdown]' \\
@@ -331,6 +334,7 @@ complete -c thincoder -a reindex  -d 'Rebuild local index from markdown'
 complete -c thincoder -a distill  -d 'Extract knowledge from session'
 complete -c thincoder -a upgrade  -d 'Update to latest version'
 complete -c thincoder -a completion -d 'Shell completion'
+complete -c thincoder -a acp -d 'Agent Client Protocol server for IDEs'
 
 # Flags
 complete -c thincoder -s v -l version -d 'Print version'
@@ -388,6 +392,12 @@ complete -c thincoder -n '__fish_seen_subcommand_from completion' -a fish -d 'Fi
     break
   }
 
+  case "acp": {
+    const { runAcpServer } = await import("../src/acp.mjs")
+    await runAcpServer()
+    break
+  }
+
   case "--help":
   case "-h": {
     process.stdout.write(USAGE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thincoder",
-  "version": "0.12.10",
+  "version": "0.12.12",
   "description": "Thin coding agent - zero dependencies, no build step, Node.js native. Sharp code, zero bloat.",
   "keywords": [
     "ai",

package/src/acp/bridge.mjs

@@ -0,0 +1,229 @@
+/**
+ * bridge.mjs — map runAgent callbacks to ACP session/update notifications
+ * and reverse-RPC (M2: tools, permissions, fs routing).
+ *
+ * Wire shapes verified against the ACP schema v1 + kimi acp-adapter:
+ * - agent text   → `agent_message_chunk`  { content: { type: "text", text } }
+ * - thinking     → `agent_thought_chunk`  (same content shape)
+ * - tool start   → `tool_call`  { toolCallId, title, kind, status: "in_progress", rawInput, content }
+ * - tool result  → `tool_call_update`  { toolCallId, status: "completed"|"failed", content } (REPLACE semantics)
+ * - usage        → `usage_update` { usage }
+ * - permission   → reverse-RPC request `session/request_permission`
+ *                  { sessionId, options, toolCall } → client responds with
+ *                  { outcome: { outcome: "selected", optionId } | { outcome: "cancelled" } }
+ * - fs routing   → reverse-RPC `fs/read_text_file` / `fs/write_text_file`
+ *
+ * toolCallId is generated per session (t1, t2, …) — thincoder's model-level
+ * tool ids are not guaranteed unique across turns, ACP ids must be.
+ *
+ * End-of-turn is NOT a notification: `session/prompt` resolves with
+ * `{ stopReason: "end_turn" }` (kimi session.ts parity).
+ */
+import { join } from "node:path"
+
+/** ACP ToolKind inference (schema v1 enum) — best-effort, clients render by kind. */
+function inferToolKind(name) {
+  const base = name.includes("/") ? name.split("/").pop() : name
+  if (["write", "edit", "apply_patch", "insert_after", "hashline_edit"].includes(base)) return "edit"
+  if (base === "delete") return "delete"
+  if (base === "bash") return "execute"
+  if (["read", "glob", "grep", "ls", "code_search", "doc_search", "repo_outline"].includes(base)) return "read"
+  if (base === "fetch" || base === "websearch") return "fetch"
+  return "other"
+}
+
+/** Permission options surfaced to the client (kimi canonical ids, order load-bearing). */
+const PERMISSION_OPTIONS = [
+  { optionId: "approve_once", name: "Approve once", kind: "allow_once" },
+  { optionId: "approve_always", name: "Approve for this session", kind: "allow_always" },
+  { optionId: "reject", name: "Reject", kind: "reject_once" },
+]
+
+/** Map a client permission response to a boolean (unknown → reject, safety-first). */
+function permissionToBoolean(response) {
+  const outcome = response?.outcome
+  if (!outcome || outcome.outcome === "cancelled") return false
+  if (outcome.optionId === "approve_once" || outcome.optionId === "approve" || outcome.optionId === "approve_always" || outcome.optionId === "approve_for_session") return true
+  return false
+}
+
+/**
+ * Build the runAgent callbacks for an ACP session.
+ * @param {{ sessionId: string, notify: (m, p) => void, request: (m, p, o?) => Promise<any>, log?: (s) => void }} deps
+ */
+export function buildAcpCallbacks({ sessionId, notify, request, log = () => {} }) {
+  const update = (sessionUpdate, extra = {}) =>
+    notify("session/update", { sessionId, update: { sessionUpdate, ...extra } })
+  let toolSeq = 0
+  const toolIds = new Map() // active tool name → current ACP toolCallId (defined before the literal — no expando)
+
+  const toolCallId = () => `t${++toolSeq}`
+  const contentBlock = (text) => ({ type: "content", content: { type: "text", text } })
+  const pathOf = (args) => {
+    const p = args?.path ?? args?.filePath
+    return typeof p === "string" && p ? p : null
+  }
+
+  const callbacks = {
+    onToken: (text) => update("agent_message_chunk", { content: { type: "text", text } }),
+    onReasoning: (text) => update("agent_thought_chunk", { content: { type: "text", text } }),
+    onUsage: (usage) => update("usage_update", { usage }),
+    onWait: ({ phase, seconds }) => log(`[rate-limit] ${phase} waiting ~${seconds}s`),
+    onCompress: () => log("[context] auto-compacted"),
+
+    onToolCall: (name, args) => {
+      const id = toolCallId()
+      toolIds.set(name, id)
+      update("tool_call", {
+        toolCallId: id,
+        title: name,
+        kind: inferToolKind(name),
+        status: "in_progress",
+        rawInput: args ?? {},
+        content: [contentBlock(JSON.stringify(args ?? {}))],
+      })
+    },
+
+    onToolResult: (name, result) => {
+      const id = toolIds.get(name) ?? toolCallId()
+      toolIds.delete(name)
+      update("tool_call_update", {
+        toolCallId: id,
+        status: "completed",
+        content: [contentBlock(String(result ?? ""))],
+      })
+    },
+
+    /**
+     * Permission gate (dispatch.mjs onPermissionRequest): reverse-RPC to the
+     * client. Any transport failure → reject (safety-first, kimi parity).
+     */
+    onPermissionRequest: async (name, args) => {
+      const toolCall = {
+        toolCallId: toolIds.get(name) ?? toolCallId(),
+        title: name,
+        content: [contentBlock(`Requesting approval to run ${name}`), contentBlock(JSON.stringify(args ?? {}))],
+      }
+      try {
+        const response = await request("session/request_permission", {
+          sessionId,
+          options: PERMISSION_OPTIONS,
+          toolCall,
+        }, { timeoutMs: 300000 }) // user deliberation can take a while; 5 min
+        return permissionToBoolean(response)
+      } catch (e) {
+        log(`[acp] request_permission failed; rejecting: ${e.message}`)
+        return false
+      }
+    },
+
+    /**
+     * fs reverse-RPC router (dispatch.mjs toolRouter, M2):
+     * - write            → fs/write_text_file (full content, no read-back)
+     * - edit              → fs/read_text_file → local single-replacement → fs/write_text_file
+     * - apply_patch       → local (unified-diff application is not routed in M2)
+     * - delete, reads     → local
+     */
+    toolRouter: async (name, args) => {
+      const base = name.includes("/") ? name.split("/").pop() : name
+      const path = pathOf(args)
+      if (base === "write" && path) {
+        if (typeof args?.content !== "string") {
+          return { handled: true, result: `Error: write content must be a string (got ${typeof args?.content})` }
+        }
+        const content = args.content
+        try {
+          await request("fs/write_text_file", { sessionId, path, content }, { timeoutMs: 30000 })
+          return { handled: true, result: `OK: wrote ${path} via IDE` }
+        } catch (e) {
+          return { handled: true, result: `Error: fs/write_text_file failed: ${e.message}` }
+        }
+      }
+      if (base === "edit" && path && typeof args?.old_string === "string" && typeof args?.new_string === "string") {
+        try {
+          const read = await request("fs/read_text_file", { sessionId, path }, { timeoutMs: 30000 })
+          const current = read?.text ?? read?.content ?? ""
+          const idx = current.indexOf(args.old_string)
+          if (idx === -1) {
+            return { handled: true, result: `Error: old_string not found in ${path} (read via IDE buffer)` }
+          }
+          const next = current.slice(0, idx) + args.new_string + current.slice(idx + args.old_string.length)
+          await request("fs/write_text_file", { sessionId, path, content: next }, { timeoutMs: 30000 })
+          return { handled: true, result: `OK: edited ${path} via IDE (1 replacement)` }
+        } catch (e) {
+          return { handled: true, result: `Error: edit via IDE failed: ${e.message}` }
+        }
+      }
+      return { handled: false } // read-only tools, delete, apply_patch stay local
+    },
+  }
+  return callbacks
+}
+
+
+/**
+ * Replay a stored human-line history as session/update notifications (session/load).
+ * role → event mapping (design §4.5):
+ *   user      → user_message_chunk
+ *   assistant → agent_message_chunk (no tool_calls) | tool_call cards (with tool_calls)
+ *   tool      → tool_call_update following its assistant message
+ * Machine-only lines ([System reminder:/[User interrupt:, transient) are never stored
+ * in the human line (saveSession filters them), so nothing to skip here.
+ */
+export function replayHistory({ sessionId, notify, history, log = () => {} }) {
+  const update = (sessionUpdate, extra = {}) =>
+    notify("session/update", { sessionId, update: { sessionUpdate, ...extra } })
+  // Shared content extraction: string → single text block; array → text blocks
+  // (images skipped with a log). textOf derives from the same source.
+  const contentBlocks = (m) => {
+    const items = []
+    if (typeof m?.content === "string") items.push({ type: "text", text: m.content })
+    else if (Array.isArray(m?.content)) {
+      for (const b of m.content) {
+        if (typeof b === "string") items.push({ type: "text", text: b })
+        else if (b?.type === "text") items.push({ type: "text", text: b.text })
+        else if (b?.type === "image") log(`[acp] replay: image block skipped (${sessionId})`)
+      }
+    }
+    return items
+  }
+  const textOf = (m) => contentBlocks(m).map((b) => b.text).join("\n")
+
+  let pendingToolCalls = [] // { id, title, kind } of the current assistant tool_calls batch
+  let toolSeq = 0
+  for (const m of history ?? []) {
+    if (m?.role === "user") {
+      pendingToolCalls = []
+      for (const b of contentBlocks(m)) update("user_message_chunk", { content: b })
+    } else if (m?.role === "assistant") {
+      const calls = Array.isArray(m.tool_calls) && m.tool_calls.length > 0 ? m.tool_calls : null
+      if (calls) {
+        // One tool_call notification PER tool in the batch — clients correlate
+        // later tool_call_updates by toolCallId; an orphan update would be ignored.
+        pendingToolCalls = calls.map((tc, i) => {
+          const id = `t${++toolSeq}`
+          const title = tc?.name ?? "tool"
+          update("tool_call", {
+            toolCallId: id,
+            title,
+            kind: inferToolKind(title),
+            status: "in_progress",
+            content: contentBlocks(m).map((b) => ({ type: "content", content: b })),
+          })
+          return { id, title }
+        })
+      } else {
+        const items = contentBlocks(m)
+        for (const b of items) update("agent_message_chunk", { content: b })
+        pendingToolCalls = []
+      }
+    } else if (m?.role === "tool" && pendingToolCalls.length > 0) {
+      const call = pendingToolCalls.shift()
+      update("tool_call_update", {
+        toolCallId: call.id,
+        status: "completed",
+        content: [{ type: "content", content: { type: "text", text: textOf(m).slice(0, 2000) } }],
+      })
+    }
+  }
+}

package/src/acp/session.mjs

@@ -0,0 +1,46 @@
+/**
+ * session.mjs — one ACP session = one thincoder agent instance.
+ *
+ * - `run(input)` serializes prompts through a per-session FIFO promise chain
+ *   (concurrent prompts queue; each runs after the previous turn's end_turn).
+ * - `cancel()` aborts the in-flight turn via a REAL AbortController — the
+ *   provider layer composes `AbortSignal.any([signal, timeout])` (core.mjs:280,
+ *   anthropic.mjs:67, google.mjs:98), which requires a real AbortSignal; a
+ *   plain object would throw TypeError on every LLM call.
+ * - The controller is rebuilt after every turn, so one cancel only affects the
+ *   in-flight turn; the next queued prompt starts with a clean signal.
+ * - `run` is injectable for tests (defaults to the real runAgent).
+ */
+import { runAgent } from "../agent.mjs"
+import { buildAcpCallbacks } from "./bridge.mjs"
+
+export function createAcpSession({ id, agent, notify, request = async () => { throw new Error("no request channel") }, log = () => {}, run = runAgent }) {
+  let controller = new AbortController()
+  const callbacks = buildAcpCallbacks({ sessionId: id, notify, request, log })
+  let queue = Promise.resolve()
+  let busy = false
+
+  return {
+    id,
+    agent,
+    get busy() { return busy },
+    run(input) {
+      const task = queue.then(async () => {
+        busy = true
+        try {
+          return await run(agent, input, callbacks, { signal: controller.signal })
+        } finally {
+          busy = false
+          // Fresh controller per turn: cancel() only affects the in-flight turn.
+          controller = new AbortController()
+        }
+      })
+      // Keep the chain alive even when a turn rejects (the next prompt still runs).
+      queue = task.then(() => {}, () => {})
+      return task
+    },
+    cancel() {
+      controller.abort({ interrupt: true, message: "cancelled by client" })
+    },
+  }
+}

package/src/acp/transport.mjs

@@ -0,0 +1,155 @@
+/**
+ * transport.mjs — ACP NDJSON JSON-RPC 2.0 layer over stdio (zero dependencies).
+ *
+ * Wire format: one JSON object per line on stdin/stdout. stdout carries ONLY
+ * protocol JSON (logs go to stderr — kimi log-guard parity). Error codes follow
+ * JSON-RPC 2.0: -32600 parse, -32601 method not found, -32602 invalid params,
+ * -32603 internal, -32000 authRequired (ACP extension).
+ *
+ * `write` is injectable for tests (defaults to process.stdout.write). `start()`
+ * wires stdin + graceful shutdown (SIGINT/SIGTERM drain in-flight requests).
+ */
+import { createInterface } from "node:readline"
+
+export const ACP_ERRORS = {
+  PARSE: { code: -32600, message: "Parse error" },
+  METHOD_NOT_FOUND: { code: -32601, message: "Method not found" },
+  INVALID_PARAMS: { code: -32602, message: "Invalid params" },
+  INTERNAL: { code: -32603, message: "Internal error" },
+  AUTH_REQUIRED: { code: -32000, message: "authRequired" },
+}
+
+/**
+ * Create an ACP server.
+ * @param {Record<string, (params, ctx) => Promise<any>|any>} handlers — method → handler.
+ *   Handler return value becomes `result`; `{ error: ACP_ERRORS.X }` becomes an error response;
+ *   a thrown error becomes -32603.
+ * @param {{ write?: (s: string) => void, log?: (s: string) => void }} [opts]
+ */
+export function createAcpServer(handlers, { write = (s) => process.stdout.write(s), log = () => {} } = {}) {
+  const state = { closed: false, inputClosed: false, inflight: new Set() }
+  const pending = new Map() // agent-initiated requests awaiting a client response (request_permission, fs/*)
+  let nextReqId = 1
+  const send = (obj) => { if (!state.closed) write(JSON.stringify(obj) + "\n") }
+  const notify = (method, params) => send({ jsonrpc: "2.0", method, params })
+
+  /**
+   * Agent-initiated JSON-RPC request: send with an id and await the client's
+   * response. Used for `session/request_permission` and `fs/read_text_file` /
+   * `fs/write_text_file` (reverse-RPC). Times out defensively — a silent
+   * client must never hang the agent loop.
+   */
+  function request(method, params, { timeoutMs = 60000 } = {}) {
+    return new Promise((resolve, reject) => {
+      const id = `rpc-${nextReqId++}`
+      const timer = setTimeout(() => {
+        pending.delete(id)
+        reject(new Error(`ACP client did not respond to ${method} within ${timeoutMs}ms`))
+      }, timeoutMs)
+      pending.set(id, { resolve, reject, timer })
+      send({ jsonrpc: "2.0", id, method, params })
+    })
+  }
+
+  // stdin EOF only means "no more requests" — in-flight handlers must still
+  // deliver their responses (e.g. session/new building an agent). Closed only
+  // after the last handler settles.
+  const drainIfDone = () => { if (state.inputClosed && state.inflight.size === 0) state.closed = true }
+
+  // Inbound requests are serialized (FIFO): ACP sessions have ordering
+  // dependencies (prompt must follow new), and a naive client may fire lines
+  // back-to-back without awaiting responses. Each line's handler is awaited
+  // before the next line is processed — ordering is guaranteed end-to-end.
+  // EXCEPTION: responses to agent-initiated requests (request_permission /
+  // fs/*) resolve the pending waiter IMMEDIATELY, outside the queue — the
+  // prompt handler awaiting them blocks the queue, so queuing them would
+  // deadlock (client response waits for queue, queue waits for handler).
+  let inbound = Promise.resolve()
+  function handleLine(line) {
+    let msg
+    try { msg = JSON.parse(line) } catch {
+      // Malformed line. If it LOOKS like a response to an agent-initiated
+      // request (has an "rpc-" id), reject the waiter NOW — the prompt handler
+      // awaiting it would otherwise hang until the timeout.
+      const m = /"id"\s*:\s*"?(rpc-\d+)"?/.exec(line)
+      if (m && pending.has(m[1])) {
+        const waiter = pending.get(m[1])
+        pending.delete(m[1])
+        clearTimeout(waiter.timer)
+        waiter.reject(new Error("ACP client sent a malformed response"))
+        return
+      }
+      // Otherwise → queued path emits the parse error in order.
+    }
+    if (msg && typeof msg === "object" && msg.method === undefined && msg.id !== undefined) {
+      resolveClientResponse(msg)
+      return
+    }
+    const task = inbound.then(() => processLine(line)).catch(() => {})
+    inbound = task
+    state.inflight.add(task)
+    task.finally(() => { state.inflight.delete(task); drainIfDone() }).catch(() => {})
+    return task
+  }
+
+  function resolveClientResponse(msg) {
+    const waiter = pending.get(String(msg.id))
+    if (!waiter) return
+    pending.delete(String(msg.id))
+    clearTimeout(waiter.timer)
+    if (msg.error) waiter.reject(Object.assign(new Error(msg.error.message ?? "ACP client error"), { code: msg.error.code }))
+    else waiter.resolve(msg.result ?? {})
+  }
+
+  async function processLine(line) {
+    let msg
+    try {
+      msg = JSON.parse(line)
+    } catch {
+      send({ jsonrpc: "2.0", id: null, error: ACP_ERRORS.PARSE })
+      return
+    }
+    if (!msg || typeof msg !== "object") return
+    // Responses were already handled out-of-band in handleLine; anything left
+    // here with no method is a stray notification — ignore silently.
+    if (msg.method === undefined) return
+    const handler = handlers[msg.method]
+    if (!handler) {
+      if (msg.id !== undefined) send({ jsonrpc: "2.0", id: msg.id, error: ACP_ERRORS.METHOD_NOT_FOUND })
+      return
+    }
+    try {
+      const result = await handler(msg.params ?? {}, { notify, send, log })
+      if (msg.id !== undefined) {
+        if (result && typeof result === "object" && result.error) {
+          send({ jsonrpc: "2.0", id: msg.id, error: result.error })
+        } else {
+          send({ jsonrpc: "2.0", id: msg.id, result })
+        }
+      }
+    } catch (e) {
+      log(`[acp] handler error: ${e?.message ?? e}`)
+      if (msg.id !== undefined) {
+        send({ jsonrpc: "2.0", id: msg.id, error: { ...ACP_ERRORS.INTERNAL, message: e?.message ?? String(e) } })
+      }
+    }
+  }
+
+  /** Wire stdin + shutdown handlers. Returns the notify fn for out-of-band pushes. */
+  function start() {
+    const rl = createInterface({ input: process.stdin, crlfDelay: Infinity })
+    rl.on("line", (l) => { if (l.trim()) handleLine(l) })
+    rl.on("close", () => { state.inputClosed = true; drainIfDone() })
+    const shutdown = () => {
+      log("[acp] shutting down — draining in-flight requests")
+      Promise.all([...state.inflight]).then(() => { state.closed = true; process.exit(0) })
+      setTimeout(() => process.exit(0), 2000).unref()
+    }
+    process.on("SIGINT", shutdown)
+    process.on("SIGTERM", shutdown)
+    return { notify, shutdown }
+  }
+
+  // handleLine/_state exposed for tests (drive without a real stdin).
+  return { start, notify, request, handleLine, _state: state }
+}