zcode-acp-server 0.1.0 → 0.3.0

package/docs/PROTOCOL.md

@@ -12,11 +12,11 @@ resembles JSON-RPC, but **does not include the `jsonrpc` field**.
 
 Messages are classified by the presence of `id` and `method`:
 
-| Combination | Type | Direction |
-|------|------|------|
-| `id` + no `method` | Response | zcode -> bridge |
-| `id` + `method` | Request | bridge -> zcode or zcode -> bridge |
-| `method` + no `id` | Notification | bidirectional |
+| Combination        | Type         | Direction                          |
+| ------------------ | ------------ | ---------------------------------- |
+| `id` + no `method` | Response     | zcode -> bridge                    |
+| `id` + `method`    | Request      | bridge -> zcode or zcode -> bridge |
+| `method` + no `id` | Notification | bidirectional                      |
 
 ### Request format
 
@@ -78,9 +78,13 @@ Messages are classified by the presence of `id` and `method`:
 
 ### `session/create`
 
-Create a new session.
+Create a new session. Note: the bridge defers this call until a session's
+first use — ACP `session/new` returns a local placeholder id and materializes
+the backend session (this RPC) on the first prompt / config change / extension
+method, so an editor startup that never sends a message leaves no session.
 
 **Request:**
+
 ```json
 {
   "id": 1,
@@ -96,6 +100,7 @@ Create a new session.
 ```
 
 **Response:**
+
 ```json
 {
   "id": 1,
@@ -114,6 +119,7 @@ Create a new session.
 List all sessions.
 
 **Request:**
+
 ```json
 {
   "id": 2,
@@ -131,7 +137,15 @@ List all sessions.
 
 Resume an existing session.
 
+The sessionId may be a lazy `session/new` placeholder (the editor persists it
+and resumes it after a bridge restart). The bridge resolves it before the
+backend call: an in-memory or persisted (`acp-lazy-sessions.json`) mapping is
+followed to the real backend session — resuming it, or materializing a fresh
+empty one if the placeholder was never used. Real ids from `session/list` pass
+through unchanged.
+
 **Request:**
+
 ```json
 {
   "id": 3,
@@ -151,6 +165,7 @@ Resume an existing session.
 Send a prompt.
 
 **Request:**
+
 ```json
 {
   "id": 4,
@@ -163,6 +178,7 @@ Send a prompt.
 ```
 
 **Response:**
+
 ```json
 {
   "id": 4,
@@ -190,6 +206,7 @@ Stop the current turn (fire-and-forget).
 Read the session state and projection.
 
 **Request:**
+
 ```json
 {
   "id": 5,
@@ -201,6 +218,7 @@ Read the session state and projection.
 ```
 
 **Response:**
+
 ```json
 {
   "id": 5,
@@ -216,9 +234,7 @@ Read the session state and projection.
       "model": { "current": { "modelId": "GLM-5.2" } },
       "thoughtLevel": { "current": "high" }
     },
-    "todos": [
-      { "content": "Implement login", "status": "pending", "priority": "high" }
-    ]
+    "todos": [{ "content": "Implement login", "status": "pending", "priority": "high" }]
   }
 }
 ```
@@ -228,6 +244,7 @@ Read the session state and projection.
 Fetch the session's historical messages.
 
 **Request:**
+
 ```json
 {
   "id": 6,
@@ -245,6 +262,7 @@ Fetch the session's historical messages.
 Subscribe to a session's event push.
 
 **Request:**
+
 ```json
 {
   "id": 7,
@@ -259,6 +277,7 @@ Subscribe to a session's event push.
 ```
 
 **Response:**
+
 ```json
 {
   "id": 7,
@@ -312,6 +331,7 @@ Model streaming output.
 ```
 
 `kind` can be:
+
 - `text_delta`: text delta
 - `reasoning_delta`: reasoning text delta
 - `tool_call`: tool call declaration (caches toolName and input)
@@ -338,6 +358,7 @@ Tool status update.
 ```
 
 `kind` can be:
+
 - `scheduled`: tool scheduled
 - `started`: tool started executing
 - `progress`: progress update (stdoutTail / stderrTail)
@@ -408,6 +429,53 @@ Session state update (usage, etc.).
 }
 ```
 
+### Steer lifecycle events
+
+When `session/steer` appends instructions to a running turn, the backend emits
+a pair of lifecycle events (available in app-server 0.15.2+). The bridge does
+not currently translate these — they are tracked as a future enhancement (see
+[`BACKLOG.md`](./BACKLOG.md)).
+
+```json
+{
+  "type": "turn.steerQueued",
+  "payload": {}
+}
+```
+
+```json
+{
+  "type": "turn.steerDrained",
+  "payload": {}
+}
+```
+
+### `turn.terminal`
+
+Terminal turn lifecycle event (app-server 0.15.2+). Carries a status plus
+usage. The bridge currently relies on `turn.completed`/`turn.failed` instead;
+documented here for completeness.
+
+```json
+{
+  "method": "session/event",
+  "params": {
+    "sessionId": "sess_abc123",
+    "seq": 49,
+    "type": "turn.terminal",
+    "payload": {
+      "kind": "turn.terminal",
+      "status": "success",
+      "resultType": "end_turn",
+      "durationMs": 12345,
+      "inputTokens": 1234,
+      "outputTokens": 567,
+      "totalTokens": 1801
+    }
+  }
+}
+```
+
 ## Interaction Protocol (Server -> Client)
 
 Requests that zcode actively sends to the bridge.
@@ -440,6 +508,7 @@ Tool permission request.
 User input request (ExitPlanMode / AskUserQuestion).
 
 **ExitPlanMode:**
+
 ```json
 {
   "id": 101,
@@ -455,6 +524,7 @@ User input request (ExitPlanMode / AskUserQuestion).
 ```
 
 **AskUserQuestion:**
+
 ```json
 {
   "id": 102,
@@ -482,17 +552,18 @@ User input request (ExitPlanMode / AskUserQuestion).
 ZCode `interaction/*` requests are routed to different ACP interaction
 mechanisms based on client capabilities:
 
-| Request type | Client supports elicitation.form | Client does not |
-|---------|:------------------------:|:----------:|
-| Tool auth (`interaction/requestPermission`) | `session/request_permission` | `session/request_permission` |
-| ExitPlanMode (`interaction/requestUserInput` + plan_approval) | `elicitation/create` (approve/reject form) | `session/request_permission` |
-| AskUserQuestion (`interaction/requestUserInput`) | `elicitation/create` (single form) | per-question `session/request_permission` |
+| Request type                                                  |      Client supports elicitation.form      |              Client does not              |
+| ------------------------------------------------------------- | :----------------------------------------: | :---------------------------------------: |
+| Tool auth (`interaction/requestPermission`)                   |        `session/request_permission`        |       `session/request_permission`        |
+| ExitPlanMode (`interaction/requestUserInput` + plan_approval) | `elicitation/create` (approve/reject form) |       `session/request_permission`        |
+| AskUserQuestion (`interaction/requestUserInput`)              |     `elicitation/create` (single form)     | per-question `session/request_permission` |
 
 **Capability detection**: at `initialize` time the client declares support via
 `clientCapabilities.elicitation.form`. The server detects it with
 `server.supportsElicitationForm()`.
 
 **elicitation form example** (AskUserQuestion):
+
 ```json
 {
   "method": "elicitation/create",
@@ -505,17 +576,36 @@ mechanisms based on client capabilities:
       "properties": {
         "q_0": {
           "type": "string",
-          "enum": ["auth.test.ts", "user.test.ts"],
-          "title": "Select the files to test"
+          "title": "Select the files to test",
+          "oneOf": [
+            { "const": "auth.test.ts", "title": "auth.test.ts" },
+            { "const": "user.test.ts", "title": "user.test.ts" },
+            { "const": "__skip__", "title": "Skip this question" }
+          ]
+        },
+        "q_0_other": {
+          "type": "string",
+          "title": "↳    or type a custom value (overrides the selection)"
         }
       },
-      "required": ["q_0"]
+      "required": []
     }
   }
 }
 ```
 
+ACP/MCP elicitation string fields are EITHER an enum (restricted dropdown) OR
+free text — the spec forbids a single field that is both. So each question is
+rendered as TWO fields: `q_<i>` (a `oneOf`/`anyOf` enum dropdown of the model's
+suggested answers, with a trailing "Skip this question" option whose `const` is
+the `__skip__` sentinel and whose `title` is the readable label) and
+`q_<i>_other` (a free-text companion). On submit, a non-empty `q_<i>_other`
+overrides the dropdown (single-select) or is appended to the picked values
+(multi-select); selecting "Skip this question" or leaving both blank skips just
+that question without cancelling the form.
+
 **elicitation response** (accept/decline/cancel):
+
 ```json
 {
   "action": "accept",
@@ -523,6 +613,35 @@ mechanisms based on client capabilities:
 }
 ```
 
+**ExitPlanMode elicitation form** — single `feedback` text field; no
+approve/reject dropdown. The client's own submit button is the approve action;
+typing into the field is the reject action. Submitting with the field empty
+approves the plan; submitting with text rejects it and returns the text to
+zcode as the decline `reason` (so the agent sees the redirection when it
+re-plans). The cancel/decline button is a plain reject with no reason.
+
+```json
+{
+  "method": "elicitation/create",
+  "params": {
+    "mode": "form",
+    "sessionId": "sess_abc123",
+    "message": "Ready to code?\n\n1. Implement login\n2. Implement signup\n\nLeave the box empty and submit to approve; type feedback to reject and redirect.",
+    "requestedSchema": {
+      "type": "object",
+      "properties": {
+        "feedback": {
+          "type": "string",
+          "title": "Feedback",
+          "description": "Empty = approve the plan. Anything typed = reject and use this text as the redirection."
+        }
+      },
+      "required": []
+    }
+  }
+}
+```
+
 ## Extension Methods (0.14.8+)
 
 ### `session/fork`
@@ -530,6 +649,7 @@ mechanisms based on client capabilities:
 Fork a new session from a checkpoint.
 
 **Request:**
+
 ```json
 {
   "id": 8,
@@ -546,6 +666,7 @@ Fork a new session from a checkpoint.
 Rewind to a checkpoint.
 
 **Request:**
+
 ```json
 {
   "id": 9,
@@ -563,6 +684,7 @@ Rewind to a checkpoint.
 Read / set / replace / clear the goal.
 
 **Request:**
+
 ```json
 {
   "id": 10,
@@ -582,6 +704,7 @@ Read / set / replace / clear the goal.
 Compact the conversation history.
 
 **Request:**
+
 ```json
 {
   "id": 11,
@@ -597,6 +720,7 @@ Compact the conversation history.
 Append instructions to a running turn.
 
 **Request:**
+
 ```json
 {
   "id": 12,
@@ -613,6 +737,7 @@ Append instructions to a running turn.
 Switch the session mode.
 
 **Request:**
+
 ```json
 {
   "id": 13,
@@ -629,6 +754,7 @@ Switch the session mode.
 Set the thought level.
 
 **Request:**
+
 ```json
 {
   "id": 14,
@@ -640,10 +766,189 @@ Set the thought level.
 }
 ```
 
-## Version Compatibility
+## Background Tasks & Sub-Agents
+
+When the model dispatches a sub-agent via the `Agent` (or `Task`) tool, the
+backend keeps producing events on the **same session stream** — both while the
+sub-agent runs and after the main turn ends. The bridge forwards a curated
+subset to the ACP client:
+
+### Synchronous sub-agent (blocking)
+
+The `Agent` tool blocks until the sub-agent finishes. Its internal tool calls
+(`Read`, `Bash`, …) arrive as ordinary `tool.updated` events on the main stream
+and are forwarded as regular `tool_call` cards. The `Agent` card itself carries
+structured metadata in `_meta.subagent` (parsed from the result content):
+
+```json
+{
+  "sessionUpdate": "tool_call_update",
+  "toolCallId": "call_xxx",
+  "status": "completed",
+  "_meta": {
+    "claudeCode": { "toolName": "Agent" },
+    "subagent": {
+      "agentId": "agent_73c7c63d-...",
+      "tokens": 40904,
+      "toolUses": 1,
+      "durationMs": 10559
+    }
+  }
+}
+```
+
+### Background sub-agent (`run_in_background: true`)
+
+The `Agent` tool returns immediately with a launch acknowledgement (result
+content contains `agentId` + `output_file` + "working in the background"). The
+main turn then completes, but the backend continues to push the task's
+lifecycle on the same stream:
+
+**1. Status changes** — `session.updated` carries a `taskId` and `status`:
+
+```json
+{
+  "method": "session/event",
+  "params": {
+    "sessionId": "sess_abc123",
+    "seq": 16,
+    "type": "session.updated",
+    "payload": {
+      "taskId": "agent_88a44529-...",
+      "toolCallId": "call_orig",
+      "toolName": "Agent",
+      "status": "running",
+      "description": "Read README first heading",
+      "outputPath": "/.../output.txt",
+      "terminalId": "agent_88a44529-...",
+      "startedAt": "2026-07-18T09:06:45.929Z"
+    }
+  }
+}
+```
+
+The bridge's session-scoped `BackgroundTaskListener` turns these into a
+dedicated ACP tool card (`[background] <description>`) plus status updates:
+
+| Backend event                              | ACP notification                                               |
+| ------------------------------------------ | -------------------------------------------------------------- |
+| first `session.updated` (status `running`) | `tool_call` (new card, `kind:"other"`, `status:"in_progress"`) |
+| `session.updated` (status `completed`)     | `tool_call_update` (`status:"completed"`)                      |
+
+`session.updated` events WITHOUT a `taskId` (e.g. usage updates) are ignored by
+the background listener — they remain owned by the turn loop.
+
+**2. Completion notification turn** — when the background task finishes, the
+backend auto-triggers a new turn whose `turn.started` carries
+`inputSource:"background_task"`:
+
+```json
+{
+  "type": "turn.started",
+  "payload": {
+    "inputSource": "background_task",
+    "inputVisibility": "model-only",
+    "input": "<task-notification>\n  <task-id>agent_...</task-id>\n  <status>completed</status-status>\n  ...\n</task-notification>",
+    "turnId": "turn_95197b25-..."
+  }
+}
+```
+
+The background listener forwards that turn's `model.streaming text_delta` as
+`agent_message_chunk` so the user sees the background result. The per-prompt
+turn loop **defers** this entire turn (drops its events) to avoid double-
+forwarding and to keep it from prematurely ending the user's real turn.
+
+### Background Bash (`run_in_background: true`)
+
+The `Bash` tool launched with `run_in_background: true` returns immediately
+with a launch acknowledgement (result content: "Command running in background
+with ID: exec_…"). Like the Agent sub-agent, the backend keeps pushing the
+task's lifecycle on the same stream via `session.updated` events that carry
+the originating `toolCallId`:
 
-| ZCode CLI version | session/subscribe | Extension methods | Notes |
-|---------------|-------------------|----------|------|
-| >= 0.15.0 | Supported | All supported | Full functionality |
-| >= 0.14.8 | Supported | Partially supported | workspace/* unavailable |
-| 0.14.5 ~ 0.14.7 | Not supported | Not supported | Incompatible with this project |
+```json
+{
+  "type": "session.updated",
+  "payload": {
+    "taskId": "exec_ac3a5053-...",
+    "toolCallId": "call_e282b4ec...",
+    "toolName": "Bash",
+    "status": "running",
+    "pid": 22410,
+    "outputPath": "/.../call_...-stdout.log",
+    "outputTail": "done\n"
+  }
+}
+```
+
+**Card reuse, not duplication.** Unlike an Agent sub-agent (which mints a fresh
+`bg_*` card), a background Bash task **reuses the launch card** — the very
+terminal card the dispatcher created when `Bash` was scheduled. This keeps the
+lifecycle on a single card instead of producing a duplicate `[background]` card
+that the editor would show alongside the closed launch card.
+
+The mechanism:
+
+1. **Launch turn** — the dispatcher tags the `ToolCallNew`/`ToolCallUpdate`
+   with `background: true` (threaded from the cached `input.run_in_background`
+   flag) and, on the launch `result`, **skips `terminal_exit`** so the launch
+   card stays `in_progress`. It seeds an empty marker in `terminalSentData`
+   for the `toolCallId` — this is the signal the background listener uses to
+   recognise "this is a tracked launch card".
+2. **Lifecycle (`session.updated`)** — the `BackgroundTaskListener` resolves
+   the `toolCallId`, sees it in `terminalSentData`, and routes status updates
+   back to the launch card. On `status:"completed"`, it emits the final
+   `outputTail` via `terminal_output` (iff launch text wasn't already streamed)
+   and closes the terminal UI with `terminal_exit` (exit code 0, or 1 on
+   `failed`), then clears the `terminalSentData` entry.
+3. **Fallback** — if the `session.updated` lacks a `toolCallId`, or the
+   `toolCallId` is unknown to `terminalSentData` (sub-agent case), the listener
+   falls back to minting a fresh `bg_*` card — the Agent sub-agent path above.
+
+| Backend event                                             | ACP notification (background Bash)                                                                                         |
+| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| first `session.updated` (status `running`)                | `tool_call_update` on the launch card (`status:"in_progress"`)                                                             |
+| `session.updated` (status `completed`, with `outputTail`) | `terminal_output` (final output, if not already streamed) + `tool_call_update` with `terminal_exit` (`status:"completed"`) |
+| `session.updated` (status `failed`)                       | `tool_call_update` with `terminal_exit` (`status:"failed"`, exit_code 1)                                                   |
+
+`session/cancelBackgroundTask` for a background Bash task additionally emits
+`terminal_exit` with `_meta.backgroundTask.cancelled = true` so the terminal
+UI closes on cancellation.
+
+### `session/cancelBackgroundTask`
+
+Cancels a background task. The bridge additionally marks the corresponding ACP
+tool card as `failed` with `_meta.backgroundTask.cancelled = true`.
+
+| ZCode CLI version | session/subscribe | Extension methods   | Notes                          |
+| ----------------- | ----------------- | ------------------- | ------------------------------ |
+| >= 0.15.0         | Supported         | All supported       | Full functionality             |
+| >= 0.14.8         | Supported         | Partially supported | workspace/* unavailable        |
+| 0.14.5 ~ 0.14.7   | Not supported     | Not supported       | Incompatible with this project |
+
+## Additional backend methods (not wired into the bridge)
+
+The backend exposes more RPC methods than the bridge uses (sub-agent listing,
+event pull, session usage/close, automation, workspace config, MCP/plugins).
+These have no ACP-side counterpart yet. See [`BACKLOG.md`](./BACKLOG.md) for
+the full list and which are candidates for future support.
+
+## Multi-client semantics (remote access)
+
+When `ZCODE_ACP_REMOTE=1` is enabled, the bridge accepts additional ACP clients
+over WebSocket (via the machine-level hub) alongside the stdio editor. All
+clients share the same backend sessions; the rules below define how one agent
+serves many clients.
+
+| Aspect                                             | Behaviour                                                                                                                                                                                |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `session/update` notifications                     | Broadcast to every connected client. A client that never saw a session (e.g. an editor receiving a phone-created session) simply ignores the update.                                     |
+| `session/request_permission`, `elicitation/create` | Sent to every client; the **first response wins**. Losing requests are aborted, which emits `$/cancel_request` so the losing client dismisses its dialog and replies `RequestCancelled`. |
+| Capabilities                                       | OR-merged across clients at each `initialize` (booleans union, `_meta` shallow-merged). A capability any client declares is enabled for interaction routing.                             |
+| Concurrent `session/prompt` on one session         | Serialized by the per-session preempt lock — identical to the single-client case; a second client's prompt preempts or queues the same way.                                              |
+| `session/cancel`                                   | Affects the shared turn regardless of which client sent it.                                                                                                                              |
+| Process lifetime                                   | Follows the stdio client: when the editor disconnects, the bridge (and every remote attachment) exits. Remote clients never extend the lifetime.                                         |
+
+Transport details (hub discovery API, token auth, tunnel notes) live in the
+[Remote Access](../README.md#remote-access) section of the README.