@selesai/code 0.13.39 → 0.14.0

package/docs/rpc.md

@@ -78,9 +78,11 @@ With `queueWhileCompacting: true` the prompt is accepted into a buffer (`success
 
 Response:
 ```json
-{"id": "req-1", "type": "response", "command": "prompt", "success": true}
+{"id": "req-1", "type": "response", "command": "prompt", "success": true, "data": {"disposition": "started"}}
 ```
 
+`data.disposition` is `"started"`, `"queued"`, or `"handled"` for this input, not the session's streaming state. Extension commands or input hooks can handle a prompt without starting an agent run. A compaction-buffered prompt returns `"queued"`. `RpcClient.prompt()` returns this disposition; its legacy boolean third argument still controls compaction buffering. `promptAndWait()` returns promptly for handled inputs and waits for `agent_settled` otherwise.
+
 `success: true` means the prompt was accepted, queued, or handled immediately. `success: false` means the prompt was rejected before acceptance. Failures after acceptance are reported through the normal event and message stream, not as a second `response` for the same request id.
 
 The `images` field is optional. Each image uses `ImageContent` format: `{"type": "image", "data": "base64-encoded-data", "mimeType": "image/png"}`.
@@ -102,7 +104,7 @@ The `images` field is optional. Each image uses `ImageContent` format (same as `
 
 Response:
 ```json
-{"type": "response", "command": "steer", "success": true}
+{"type": "response", "command": "steer", "success": true, "data": {"disposition": "queued"}}
 ```
 
 See [set_steering_mode](#set_steering_mode) for controlling how steering messages are processed.
@@ -124,7 +126,7 @@ The `images` field is optional. Each image uses `ImageContent` format (same as `
 
 Response:
 ```json
-{"type": "response", "command": "follow_up", "success": true}
+{"type": "response", "command": "follow_up", "success": true, "data": {"disposition": "queued"}}
 ```
 
 See [set_follow_up_mode](#set_follow_up_mode) for controlling how follow-up messages are processed.
@@ -186,6 +188,7 @@ Response:
     "thinkingLevel": "medium",
     "isStreaming": false,
     "isCompacting": false,
+    "isRetrying": false,
     "steeringMode": "all",
     "followUpMode": "one-at-a-time",
     "sessionFile": "/path/to/session.jsonl",
@@ -198,7 +201,7 @@ Response:
 }
 ```
 
-The `model` field is a full [Model](#model) object or `null`. The `sessionName` field is the display name set via `set_session_name`, or omitted if not set.
+The `model` field is a full [Model](#model) object or `null`. `isRetrying` is true while an auto-retry is in flight, including the backoff sleep between attempts (`isStreaming` can be false then). The `sessionName` field is the display name set via `set_session_name`, or omitted if not set.
 
 #### get_messages
 
@@ -857,6 +860,214 @@ Optional `themeName` selects the export theme:
 
 Response: `{"command": "share_gist", "success": true, "data": {"url": "https://github.com/user/...", "gistUrl": "https://gist.github.com/..."}}`
 
+### Subagent observability (Desktop / headless clients)
+
+`subagent_status` is a dedicated **read-only** command. It does not invoke an LLM, the `subagent` tool, a slash command, or the generic internal RPC/event bus. It reads the loaded extension's current native foreground controls/history and tracker-fed async/fleet state. No arbitrary user paths are scanned. Spawn/manage/steer/stop/resume are **not** exposed by this stdio contract.
+
+```json
+{"type":"subagent_status","id":"status-1","version":1}
+{"type":"response","id":"status-1","command":"subagent_status","success":true,"data":{"version":1,"available":true,"capabilities":{"snapshot":true,"events":true},"sessionId":"host-session-id","epoch":"bind-uuid","revision":2,"fleet":{"version":1,"entries":[{"key":"fleet-1","agent":"worker","startedAt":1733234500000,"tokens":{"input":12,"output":3,"total":15}}],"totalActive":1,"topLevelAsyncCapacity":{"used":1,"limit":3},"omitted":0},"runs":[{"key":"node-opaque","runId":"run-1","status":"running","startedAt":1733234500000,"children":[{"key":"node-child-opaque","agent":"worker","status":"running","currentTool":"read","tokens":{"input":12,"output":3,"total":15},"children":[],"omittedChildren":0}],"omittedChildren":0}],"omitted":{"runs":0,"children":0}}}
+```
+
+The exact machine-readable JSON Schema for commands, success responses, events, snapshots, fleet and recursive nodes is [rpc-subagent.schema.json](rpc-subagent.schema.json); TypeScript definitions are in [`src/core/subagent-rpc.ts`](../src/core/subagent-rpc.ts). `version:1` is required; missing/unknown versions, extra command fields, non-string/overlong IDs and malformed backend projections fail with normal `success:false` responses. Optional `id` is at most 128 characters without CR/LF. Unknown future wire fields should be ignored by clients.
+
+Missing extension (also after disposal) is explicit, **not** an empty healthy fleet:
+
+```json
+{"type":"response","command":"subagent_status","success":true,"data":{"version":1,"available":false,"capabilities":{"snapshot":true,"events":false},"sessionId":"host-session-id","epoch":"bind-uuid","revision":1,"fleet":{"version":1,"entries":[],"totalActive":0,"topLevelAsyncCapacity":{"used":0,"limit":0},"omitted":0},"runs":[],"omitted":{"runs":0,"children":0}}}
+{"type":"response","command":"subagent_status","success":false,"error":"Unsupported subagent_status version; expected 1"}
+```
+
+An initial `subagent_event` is emitted after extension binding, including when unavailable, and again for every session switch/rebind/reload. Each event is a **full replacement snapshot**, identical to the authoritative status projection at its revision, not a patch:
+
+```json
+{"type":"subagent_event","version":1,"sessionId":"host-session-id","epoch":"bind-uuid","revision":1,"snapshot":{"version":1,"available":true,"capabilities":{"snapshot":true,"events":true},"sessionId":"host-session-id","epoch":"bind-uuid","revision":1,"fleet":{"version":1,"entries":[],"totalActive":0,"topLevelAsyncCapacity":{"used":0,"limit":0},"omitted":0},"runs":[],"omitted":{"runs":0,"children":0}}}
+```
+
+Scope and recovery:
+- `sessionId` is the **bare host parent SDK session ID**, never an artifact path or broker endpoint. Internally, native run ownership can use a session-file path; the adapter filters on that native identity without exposing it as a node identity.
+- `epoch` is a fresh host-binding UUID shared with Intercom's nested `scope`. Rebinding the same session/reloading rotates it. Revision starts at 1 after binding and increases monotonically on projection changes; querying unchanged status does not advance it. A status query may publish a fresh changed snapshot immediately. Native progress changes are sampled/coalesced at 250 ms while subscribed; identical snapshots emit nothing.
+- Desktop should retain the current `(sessionId, epoch)` from the current binding/status, reject obsolete scopes and revisions, and replace the whole projection. Reconnect by requesting status; events are not a durable log. Late callbacks from disposed bindings are ignored and subscriptions/timers are released. Parent `agent_end` is **not** child completion: async work remains active until its own runtime lifecycle changes.
+- `available:true` means the native observation backend is loaded, not that any child, model, or task is healthy. `capabilities.snapshot` is always true; `events` is true only with the backend. Unavailable snapshots contain zero counters as unavailable placeholders, not evidence of an idle fleet.
+
+Node semantics and bounds:
+- `runs` holds bounded native foreground controls, retained foreground child rows, and current/recent async records. It is a runtime display window, **not a durable run ledger**. Foreground retained child rows have the parent `runId`; async records use their native async run ID. A `workflowId` is only present when native workflow ownership is known. `key` is opaque; reconcile keys only inside the current epoch, never parse them or use paths as IDs. Fleet keys are a separate active-child display namespace; do not join fleet keys to run keys.
+- `status` is the native lifecycle: `queued|pending|running|complete|completed|failed|partial|paused|stopped|rejected|detached`. Optional `activity` is separate: `waiting_supervisor` comes only from an actual registered pending native supervisor request; `needs_attention` comes only from native control activity. Clearing a pending request removes the wait hint. Do not infer activity from parent streaming, elapsed time, output text or tool names.
+- Optional numeric `startedAt`, `updatedAt`, `endedAt` are native millisecond timestamps. `progress` is a bounded latest-output/description projection (256 characters), `currentTool` is at most 96 characters, `agent` 96, `error` 256, `reason` 128. No arguments, transcripts, arbitrary artifacts, or paths-as-identity are included; display strings can naturally mention paths and are not a secret-redaction API.
+- `tokens`, when genuinely present, is `{input,output,total,window?,windowPeak?}` with nonnegative safe integers. Do not invent missing counters. Fleet retains the existing DTO's zero-counter fallback for absent usage; run/node tokens are omitted if unknown.
+- Optional `outcome:{status,success?,exitCode?}` is only copied from an explicit native `execution` projection. A lifecycle `complete`/`completed`, terminal timestamp, exit code in other metadata, or output presence does **not** establish task success. `processTerminal:{state,observedAt?,reason?}` independently copies native runner proof (`pending|observed|unknown|not-started`); never infer it from task outcome or lifecycle. Both may be absent, and a failed task may have observed process closure.
+- Fleet has at most 16 entries and 256 candidate records. `totalActive` counts native active children before the display bound; `omitted = totalActive - entries.length`, including malformed display rows. `topLevelAsyncCapacity.limit:0` means that native opt-in cap is disabled.
+- At most 32 run roots, 64 total run/child nodes, 16 immediate children per node, and child depth 4 are emitted. The serialized projection reserves 1 KiB inside a 64 KiB budget for wire scope/envelope. Overflow/malformed records are omitted. `omitted.runs` counts excluded root candidates; every emitted node has `omittedChildren`, counting excluded **immediate child candidates** (not recursively enumerating hidden descendants). `omitted.children` is the sum of these counts over emitted nodes. Entire roots can be removed to meet the byte budget. These counts describe this projection window only, not expired native history or undiscovered artifacts.
+
+TypeScript: `RpcClient.subagentStatus(): Promise<SubagentRpcSnapshot>` and `RpcEvent`/`SubagentRpcEvent` are exported with `SubagentRpcCommand`, `SubagentRpcResponse`, `SubagentRpcNode`, `SubagentRpcFleet`, `SubagentRpcTokens`, `SubagentRpcLifecycle`, and `RpcObservationScope` from `@selesai/code`. The dedicated internal source bridge is not an external extension-bus RPC invocation API.
+
+### Release readiness (Desktop / headless clients)
+
+`release_readiness` answers one question authoritatively: **is it safe to stop this process right now, and if not, why?** A host that spawns one `--mode rpc` child per session uses it to decide when an idle child may be released (gracefully stopped) without losing background subagent runs, intercom asks, armed session-only schedules, queued prompts, open extension dialogs or retrying turns. It is read-only and never invokes a model. Call it from events (navigate away, turn end, background result delivered), not on a timer.
+
+```json
+{"type":"release_readiness","id":"r-1","version":1}
+{"type":"response","id":"r-1","command":"release_readiness","success":true,"data":{"version":1,"sessionId":"host-session-id","epoch":"bind-uuid","safe":false,"contributors":["subagents","intercom","scheduler"],"blockers":[{"source":"subagents","kind":"async_run","id":"run-1","detail":"Async single running: worker","since":1733234500000}]}}
+{"type":"response","command":"release_readiness","success":false,"error":"Unsupported release_readiness version; expected 1"}
+```
+
+- `version` must be `1`; unknown keys and an `id` longer than 128 characters or containing line breaks are rejected with a failure response. After a session switch/reload the previous binding answers `"Release readiness session ended"`.
+- `safe` is `true` **only** when `blockers` is empty. Treat any failure response as "not safe".
+- `sessionId` and `epoch` are the same scope as `subagent_status`/Intercom events. Drop answers whose `(sessionId, epoch)` is obsolete; the epoch rotates on `new_session`, `switch_session`, fork/clone, import and reload.
+- `contributors` lists the extension contributors that answered (`subagents`, `intercom`, `scheduler`). **`safe: true` with an empty `contributors` list means no extension reported**, e.g. the extensions are not loaded. Core blockers are always evaluated. A host that requires extension coverage should check the list.
+- **Fail closed.** A contributor that throws, returns malformed blockers, or fails while reconciling a run yields a `contributor_error` blocker instead of silently answering safe. Over-long contributions are truncated with a `contributor_error` marker (64 blockers per contributor, 256 total).
+- A dead background runner is **not** a blocker: it is repaired into a failed result first and then reported as `undelivered_result` until that result is delivered to the session.
+
+Blocker fields: `source` (`core`, `subagents`, `intercom`, `scheduler`, or another extension name), `kind` (stable token), optional `id`, human-readable `detail`, optional `since` (epoch ms; for `armed_schedule` it is the next run time).
+
+| source | kind | Reported when |
+|---|---|---|
+| core | `streaming` | an agent run (or its post-run continuation) is active |
+| core | `compacting` | compaction or branch summarization is running |
+| core | `retrying` | an auto-retry is in flight (also `isRetrying` in `get_state`) |
+| core | `queued_messages` | steering/follow-up messages are queued |
+| core | `pending_tool_calls` | tool calls are in flight |
+| core | `pending_bash` | a `bash` command is running or its output awaits flushing |
+| core | `extension_dialog` | an extension UI request awaits an `extension_ui_response` |
+| core | `compaction_prompt_queue` | prompts are buffered until compaction ends |
+| core | `prompt_in_flight` | a `prompt` command has not finished processing |
+| core | `session_transition` | a session switch/new/fork/reload/rebind is in progress |
+| core | `releasing` | a `release` command has been committed and the process is shutting down (see [`release`](#release-atomic-release-if-safe)) |
+| subagents | `async_run` | a background run is queued/running, has live nested descendants, or a retained nested route may still be live (`id` = run id, `since` = start) |
+| subagents | `foreground_run` | a foreground subagent run is in progress |
+| subagents | `undelivered_result` | a repaired/finished run's result, a queued completion notification, or a persisted result owned by this process has not been delivered |
+| intercom | `inbound_ask` | an ask is awaiting our reply (`id` = message id) |
+| intercom | `outbound_ask` | our blocking ask awaits a reply |
+| intercom | `outbound_message` | an outbox send from another extension has not settled |
+| scheduler | `armed_schedule` | a **session-only** schedule holds an armed timer in this process (it would be lost on exit). Project schedules persist on disk and never block. An armed schedule whose record cannot be read is reported too (fail closed) |
+| scheduler | `scheduled_run_pending` | a scheduled run (of any schedule kind) is still awaiting completion |
+| any | `contributor_error` | a contributor failed (fail closed) |
+
+Extension contract (internal, not an external RPC API): the host emits `release:readiness:v1` on the session event bus with `{version:1, sessionId, contribute(name, blockers)}`. Listeners call `contribute` synchronously, many contributors are accepted, and listeners must ignore requests whose `sessionId` is not the session they host (`answerReleaseReadiness` from `@selesai/code` implements the gate and the fail-closed try/catch).
+
+TypeScript: `RpcClient.releaseReadiness(): Promise<ReleaseReadiness>`; `ReleaseReadinessCommand`, `ReleaseReadinessResponse`, `ReleaseReadiness` and `ReleaseBlocker` are exported types.
+
+#### `release`: atomic release-if-safe
+
+Asking `release_readiness` and then closing stdin is racy: stdin EOF shuts the process down immediately, so work that starts between the "safe" answer and the EOF (a schedule timer fires, an intercom message triggers a turn, a background result arrives) is lost. `release` closes that window by making the check and the commitment one step inside the process.
+
+```json
+{"type":"release","id":"r-2","version":1}
+{"type":"response","id":"r-2","command":"release","success":true,"data":{"released":true,"readiness":{"version":1,"sessionId":"host-session-id","epoch":"bind-uuid","safe":true,"contributors":["subagents","intercom","scheduler"],"blockers":[]}}}
+{"type":"response","id":"r-3","command":"release","success":true,"data":{"released":false,"readiness":{"version":1,"sessionId":"host-session-id","epoch":"bind-uuid","safe":false,"contributors":["subagents","intercom","scheduler"],"blockers":[{"source":"core","kind":"pending_bash","detail":"Bash command running"}]}}}
+```
+
+- Request fields and validation are identical to `release_readiness` (`version` must be `1`, no unknown keys, `id` at most 128 characters without line breaks); a malformed request gets a failure response and nothing is committed.
+- The process computes readiness exactly as `release_readiness` does (core blockers plus every extension contributor) and, in the same synchronous step, decides:
+  - **Releasable** = `safe` **and** at least one contributor answered. The response is `released: true`. The process then rejects every later command with `success:false, error:"Session is releasing"` and, once the response is flushed, takes the normal graceful shutdown path: extensions receive `session_shutdown`, **nothing is aborted**, and the exit code is `0`. Because releasable implies idle, there is no in-flight turn to lose. Stdin EOF after a committed release is harmless.
+  - **Not releasable**: `released: false` with the full `readiness` (the blockers). The process keeps running normally and nothing changed.
+- **Nobody answered is not released.** `safe: true` with an empty `contributors` list (extensions not loaded) yields `released: false`, because the process cannot prove that no background work exists. The `readiness` in the response shows `safe: true, contributors: []`; hosts that want to stop such a process anyway must do so themselves.
+- After a committed release: `release` is answered idempotently with `released: true` (and the committed `readiness`); `release_readiness` answers `safe: false` with a core `releasing` blocker; every other command fails with `Session is releasing`. `extension_ui_response` lines are still routed.
+- Residual window: work that bypasses the RPC command loop (extension timers such as session-only schedules, intercom-triggered turns, background results) is not refused by the flag; between the commit and the process exit (the stdout flush plus extension disposal, typically milliseconds) such work would be cut off by the shutdown. This is the same disposal that stdin EOF triggers, but without the unbounded gap between the readiness answer and the EOF.
+- Prefer `release` over `release_readiness` + closing stdin. For CLIs that predate it (the `release` command fails with `Unknown command: release`), fall back to `release_readiness` and, only when `safe` with a non-empty `contributors`, close stdin.
+
+TypeScript: `RpcClient.release(): Promise<ReleaseResult>`; `ReleaseCommand`, `ReleaseResponse` and `ReleaseResult` are exported types.
+
+#### `stop_all_background`: kill switch for "Quit anyway"
+
+`release` and `release_readiness` never stop work. `stop_all_background` is the opposite: **one destructive command that leaves nothing of this session running or armed.** It is intended only for an explicit user decision such as a "Quit anyway" button after a quit warning built from `release_readiness` blockers; never call it from automatic release, idle, cap or navigation logic. Afterwards the host exits the child gently (close stdin) or kills it.
+
+```json
+{"type":"stop_all_background","id":"k-1","version":1}
+{"type":"response","id":"k-1","command":"stop_all_background","success":true,"data":{"version":1,"sessionId":"host-session-id","epoch":"bind-uuid","stopped":[{"source":"core","kind":"turn","detail":"Aborted in-flight agent turn","ok":true},{"source":"scheduler","kind":"schedule","id":"nightly","detail":"Paused session-only schedule nightly and cleared its timer (schedule.resume re-arms it)","ok":true},{"source":"subagents","kind":"async_run","id":"run-1","detail":"Stopped Async single (worker) run-1","ok":true},{"source":"intercom","kind":"inbound_ask","id":"m-7","detail":"cannot cancel inbound: ask from planner is awaiting our reply and keeps waiting","ok":false,"error":"cannot cancel inbound"}],"remaining":{"version":1,"sessionId":"host-session-id","epoch":"bind-uuid","safe":false,"contributors":["subagents","intercom","scheduler"],"blockers":[{"source":"intercom","kind":"inbound_ask","id":"m-7","detail":"Ask from planner is awaiting our reply"}]}}}
+{"type":"response","command":"stop_all_background","success":false,"error":"Unsupported stop_all_background version; expected 1"}
+```
+
+- Request fields and validation are identical to `release_readiness` and `release` (`version` must be `1`, no unknown keys, `id` at most 128 characters without line breaks). `success:false` is returned **only** for a malformed request, while the session is releasing (`error:"Session is releasing"`, like every other command after a committed `release`), or when the binding was replaced during the stop. Individual failures never fail the command: they are `ok:false` items.
+- `stopped` lists everything that was running, armed or pending when the command arrived, one item per thing: `{source, kind, id?, detail, ok, error?}`. `ok:true` means it is no longer running/armed/pending; `ok:false` carries a short `error` (`timeout`, `cannot cancel inbound`, `foreign_session`, or the failure text). An idle session yields `stopped: []`. Items are ordered by contributor: `core`, then extensions in registration order.
+- `remaining` is the same `ReleaseReadiness` that `release_readiness` returns, computed **after** the stop: show it to explain what could not be stopped. Note that a run which was just stopped usually still appears as `undelivered_result` (its `stopped` result has not been delivered to the parent); that is not running work.
+- **Idempotent.** A second call finds nothing left to stop: `stopped` only repeats things that cannot be stopped (inbound asks, runs of another session), usually `[]`.
+- **Bounded.** The core abort and every extension's stop start together (synchronously inside the call) and are awaited under ONE total budget of about 5 seconds. A part that has not finished by then is reported `ok:false, error:"timeout"` and the response is sent anyway; its stop request stays in effect.
+
+What is stopped:
+
+| Source | What | How |
+| --- | --- | --- |
+| core | the in-flight agent turn, auto-retry, compaction and branch summarization | the same path as the `abort` command (`abortBranchSummary`, `abortCompaction`, `session.abort()`), plus: a running `bash` command is killed, and queued steer/follow-up messages and prompts buffered until compaction ends are dropped first so nothing restarts the turn after the abort |
+| core / subagents | **foreground** subagent runs | they belong to the turn: the abort signal kills their child processes. The subagents handler only waits (within the budget) for them to leave and reports each as `foreground_run` |
+| subagents | every live **async / detached** run of this session (`async_run`), runs a scheduled run is still awaiting (`scheduled_run`, the `scheduled_run_pending` blockers) and live nested descendants (`nested_run`) | the same machinery as the subagents RPC `stop` method: a stop request file is written to the run's control inbox (`<run dir>/control/stop-requests/`). The detached runner consumes it by itself, ends with status `stopped`, and exits; nothing depends on the CLI process staying alive, and the request is written before the call's first asynchronous step, so exiting right after the response is safe. Each item is `ok:true` once the runner's status is terminal |
+| scheduler | **session-only** schedules armed in this process | **paused** (persisted) and their timers cleared, so they neither fire now nor on the next launch (`catchUp: "latest"` cannot revive a paused schedule). Pause rather than delete: it is reversible with `schedule.resume`, keeps the history and works while a run is active (delete refuses then) |
+| intercom | this session's blocking **outbound ask** | broker `cancel_ask` (drops the ask edge and its pending-ask record), the blocked tool call/RPC ask returns `Cancelled: session background work was stopped`, and the recipient is asked to drop the message (`cancel_message`, best-effort; the detail says whether it was reached) |
+
+What is **not** stopped:
+
+- **Project schedules** (decision D11): they live on the project and re-arm on any launch. An armed timer whose record cannot be read is left alone and reported `ok:false` (it might be a project schedule).
+- **Inbound intercom asks** waiting on this session: the receiver cannot cancel the asker's ask. They are reported `ok:false, error:"cannot cancel inbound"` and stay in `remaining`. Outbound messages from other extensions that have not settled (`outbound_message`) and pending extension dialogs are also left alone.
+- **Runs of another session** that happen to be listed in this process are never touched (`ok:false, error:"foreign_session"`).
+- **Undelivered results** of stopped runs: they are delivered when the session is resumed (ownership takeover).
+- A wedged detached runner that never consumes its stop file: the control channel is file based on purpose (no PID signalling, a PID cannot be proven to belong to the runner), so it is reported `timeout` and stays in `remaining`; the host may still kill the process tree it knows about.
+- New work started during the stop window (for example a new prompt sent by the host in parallel) is not prevented; send the command, wait for the response, then exit.
+
+TypeScript: `RpcClient.stopAllBackground(): Promise<StopAllBackgroundResult>`; `StopAllBackgroundCommand`, `StopAllBackgroundResponse`, `StopAllBackgroundResult` and `StopAllBackgroundItem` are exported types. Extension contract (internal): the host emits `release:stop-all:v1` with `{version:1, sessionId, deadline, contribute(name, items | Promise<items>)}`; extensions register a handler next to their `release:readiness:v1` contributor (`answerStopAllBackground` from `@selesai/code` implements the session gate and the fail-closed try/catch), start the stop synchronously and settle by `deadline`.
+
+### Intercom (Desktop / headless clients)
+
+These dedicated commands use the loaded `pi-intercom` extension's existing local broker connection. They do not invoke a model, run `/intercom` (a TUI overlay), or expose arbitrary extension events/tools. They work while the agent is idle or busy. `list_sessions` lists saved transcripts; `intercom_list` lists **live broker-connected endpoints**, including self, within the current routing scope.
+
+| Command | Fields | Successful `data` |
+| --- | --- | --- |
+| `intercom_status` | none | `{enabled, connected, sessionId, name?, scope:{version:1,sessionId,epoch}}` (snapshot; does not initiate a connection) |
+| `intercom_list` | none | `{sessionId, sessions: SessionInfo[]}` |
+| `intercom_pending` | none | `{asks: [{from, message, receivedAt}]}` (unresolved inbound asks) |
+| `intercom_send` | `to`, `message`, `attachments?`, `replyTo?` | Delivery object below |
+| `intercom_ask` | `to`, `message`, `attachments?`, `replyTo?`, `timeoutMs?` | Delivery object plus `reply: Message` |
+| `intercom_reply` | `message`, `to?`, `replyTo?`, `attachments?` | Delivery object with exact `replyTo` |
+
+Targets use existing name/full-ID/unique-ID-prefix resolution; ambiguous and self targets fail. Prefer full IDs from a fresh live list. Text and targets must be non-empty strings; attachments use `{type: "file"|"snippet"|"context", name, content, language?}`. `reply` uses the current turn's inbound message or single pending ask; specify `replyTo` when there are multiple asks. Ordinary `send` infers the sole pending ask from its target, with the same active-turn misdirection guard as the model tool.
+
+```json
+{"id":"status-1","type":"intercom_status"}
+{"id":"peers-1","type":"intercom_list"}
+{"id":"send-1","type":"intercom_send","to":"peer-full-id","message":"Build finished."}
+{"id":"send-1","type":"response","command":"intercom_send","success":true,"data":{"messageId":"msg-1","to":"peer-full-id","delivered":true,"delivery":"socket_delivered","retryable":false,"outcomeKnown":true}}
+{"id":"ask-1","type":"intercom_ask","to":"peer-full-id","message":"Approve the change?","timeoutMs":60000}
+{"id":"ask-1","type":"response","command":"intercom_ask","success":true,"data":{"messageId":"question-1","to":"peer-full-id","delivered":true,"delivery":"socket_delivered","retryable":false,"outcomeKnown":true,"reply":{"id":"answer-1","timestamp":1733234567890,"replyTo":"question-1","content":{"text":"Approved."}}}}
+{"id":"pending-1","type":"intercom_pending"}
+{"id":"reply-1","type":"intercom_reply","replyTo":"question-2","message":"Proceed."}
+```
+
+RPC `id` correlates the terminal command response, not the Intercom message. `data.messageId` correlates delivery/receipts and `reply.replyTo`; `data.to` is the resolved target. Delivery is `socket_delivered` or `queued`; it does **not** mean the recipient model processed the message. Delivery failures return `success:false` and an error (diagnostic delivery events can include `code`, `reason`, `retryable`, `outcomeKnown`).
+
+`ask` waits without an LLM turn and requires a live recipient. Its `timeoutMs` is an integer from 1 to 600000, default 600000; only one shared ask waiter (RPC or model tool) is allowed per session. Concurrent asks fail rather than replacing it. A timeout is **not cancellation** of already delivered work. Other bridge operations are bounded to 30 seconds (with a one-second host cleanup margin). Replacement, reload, shutdown, and disconnect settle pending operations; stale session events/results are discarded.
+
+The extension's confirmation policy is unchanged: with `confirmSend:true`, ordinary and inferred sends emit `extension_ui_request` with `method:"confirm"`; respond with a matching `extension_ui_response`. Refusal, missing UI, or a 30-second confirmation timeout fails closed. Explicit `replyTo`, `reply`, and `ask` skip confirmation, as in the existing Intercom tool. A missing extension fails promptly with `Intercom extension unavailable`; a disabled extension reports `enabled:false` in status and rejects other operations.
+
+#### Structured Intercom events
+
+These stream even without an active prompt and while the agent is busy:
+
+Every Intercom event and `intercom_status.data` includes **`scope: {version:1, sessionId: string|null, epoch: string}`**. `scope.sessionId` is the host parent SDK session ID (as in `get_state`), never a session-file path or broker endpoint ID. Existing top-level `sessionId` is unchanged: self broker endpoint in status/connection, departing peer endpoint in `intercom_session_left`. `from.id`, `session.id`, and list IDs also remain broker endpoints. `scope.epoch` is the host binding UUID shared with subagent snapshots; it rotates on every rebind/reload, including rebinding the same session. Reject events from an obsolete `(scope.sessionId, scope.epoch)` pair. Broker reconnects within the same binding do not rotate the epoch; connection events report reconnect state. Status does not initiate a broker connection.
+
+```json
+{"id":"status-1","type":"response","command":"intercom_status","success":true,"data":{"enabled":true,"connected":true,"sessionId":"broker-self-id","scope":{"version":1,"sessionId":"host-session-id","epoch":"bind-uuid"}}}
+```
+
+| Event | Payload |
+| --- | --- |
+| `intercom_connection` | `enabled`, `connected`, `sessionId`, `reason?` |
+| `intercom_session_joined` | `session: SessionInfo` |
+| `intercom_session_left` | `sessionId` |
+| `intercom_presence` | `session: SessionInfo` (name, cwd, model, lifecycle status, optional context usage) |
+| `intercom_message` | `from: SessionInfo`, `message: Message` (including attachments and threading) |
+| `intercom_delivery` | `result: {type:"delivered"|"delivery_failed", messageId, delivery, retryable, outcomeKnown, code?, reason?}` |
+| `intercom_receipt` | `from: SessionInfo`, `receipt: {messageId, status, timestamp, detail?}` |
+
+```json
+{"type":"intercom_connection","enabled":true,"connected":true,"sessionId":"self-id","scope":{"version":1,"sessionId":"host-session-id","epoch":"bind-uuid"}}
+{"type":"intercom_session_left","sessionId":"peer-full-id","scope":{"version":1,"sessionId":"host-session-id","epoch":"bind-uuid"}}
+{"type":"intercom_message","from":{"id":"peer-full-id","name":"reviewer","cwd":"/project","model":"model-id","pid":123,"startedAt":1733234500000,"lastActivity":1733234567890},"message":{"id":"question-2","timestamp":1733234567890,"expectsReply":true,"content":{"text":"Can I proceed?"}},"scope":{"version":1,"sessionId":"host-session-id","epoch":"bind-uuid"}}
+{"type":"intercom_receipt","from":{"id":"peer-full-id","cwd":"/project","model":"model-id","pid":123,"startedAt":1733234500000,"lastActivity":1733234567890},"receipt":{"messageId":"msg-1","status":"injected","timestamp":1733234567890},"scope":{"version":1,"sessionId":"host-session-id","epoch":"bind-uuid"}}
+```
+
+Incoming events are deduplicated per sender/message ID and include replies consumed by an ask waiter. They do not replace the normal custom-message/transcript stream; avoid rendering both as separate copies. Inbound triggering remains governed by `inboundTrigger`: idle recipients may start a turn and busy RPC recipients receive steering at the next safe boundary. Receipt statuses include `receiver_received`, `acknowledged`, `injected`, `queued`, `expired`, `cancelled`, `superseded`, and `cancellation_requested`.
+
+TypeScript: `RpcClient` provides `intercomStatus`, `intercomList`, `intercomSend`, `intercomAsk`, `intercomReply`, `intercomPending`; `onEvent` accepts the exported `RpcEvent` union, including `IntercomRpcEvent` and extension UI requests. The `IntercomRpcCommand`, `IntercomRpcDataMap`, delivery/status/message option types are exported from `@selesai/code`.
+
 ### Commands
 
 #### get_commands
@@ -1002,17 +1213,16 @@ Emitted when a message begins and completes. The `message` field contains an `Ag
 
 ### message_update (Streaming)
 
-Emitted during streaming of assistant messages. Contains both the partial message and a streaming delta event.
+Emitted during streaming of assistant messages. Wire records contain cumulative `usage` and a streaming delta event, not cumulative message snapshots. `message` and `assistantMessageEvent.partial` are omitted to keep stream size linear. SDK events still contain those snapshots; `message_end.message` is the authoritative final message.
 
 ```json
 {
   "type": "message_update",
-  "message": {...},
+  "usage": {"input": 100, "output": 1, "cacheRead": 0, "cacheWrite": 0, "totalTokens": 101, "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0, "total": 0}},
   "assistantMessageEvent": {
     "type": "text_delta",
     "contentIndex": 0,
-    "delta": "Hello ",
-    "partial": {...}
+    "delta": "Hello "
   }
 }
 ```
@@ -1028,7 +1238,7 @@ The `assistantMessageEvent` field contains one of these delta types:
 | `thinking_start` | Thinking block started |
 | `thinking_delta` | Thinking content chunk |
 | `thinking_end` | Thinking block ended |
-| `toolcall_start` | Tool call started |
+| `toolcall_start` | Tool call started (includes `id` and `toolName`) |
 | `toolcall_delta` | Tool call arguments chunk |
 | `toolcall_end` | Tool call ended (includes full `toolCall` object) |
 | `done` | Message complete (reason: `"stop"`, `"length"`, `"toolUse"`) |
@@ -1036,10 +1246,10 @@ The `assistantMessageEvent` field contains one of these delta types:
 
 Example streaming a text response:
 ```json
-{"type":"message_update","message":{...},"assistantMessageEvent":{"type":"text_start","contentIndex":0,"partial":{...}}}
-{"type":"message_update","message":{...},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello","partial":{...}}}
-{"type":"message_update","message":{...},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":" world","partial":{...}}}
-{"type":"message_update","message":{...},"assistantMessageEvent":{"type":"text_end","contentIndex":0,"content":"Hello world","partial":{...}}}
+{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_start","contentIndex":0}}
+{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello"}}
+{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":" world"}}
+{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_end","contentIndex":0,"content":"Hello world"}}
 ```
 
 ### bash_execution_update

package/docs/sdk.md

@@ -16,7 +16,7 @@ See [examples/sdk/](../examples/sdk/) for working examples from minimal to full
 ## Quick Start
 
 ```typescript
-import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "@earendil-works/pi-coding-agent";
+import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "@selesai/code";
 
 // Set up credential storage and model registry
 const authStorage = AuthStorage.create();
@@ -40,7 +40,7 @@ await session.prompt("What files are in the current directory?");
 ## Installation
 
 ```bash
-npm install @earendil-works/pi-coding-agent
+npm install @selesai/code
 ```
 
 The SDK is included in the main package. No separate installation needed.
@@ -54,7 +54,7 @@ The main factory function for a single `AgentSession`.
 `createAgentSession()` uses a `ResourceLoader` to supply extensions, skills, prompt templates, themes, and context files. If you do not provide one, it uses `DefaultResourceLoader` with standard discovery.
 
 ```typescript
-import { createAgentSession, SessionManager } from "@earendil-works/pi-coding-agent";
+import { createAgentSession, SessionManager } from "@selesai/code";
 
 // Minimal: defaults with DefaultResourceLoader
 const { session } = await createAgentSession();
@@ -132,7 +132,7 @@ import {
   createAgentSessionServices,
   getAgentDir,
   SessionManager,
-} from "@earendil-works/pi-coding-agent";
+} from "@selesai/code";
 
 const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
   const services = await createAgentSessionServices({ cwd });
@@ -338,23 +338,23 @@ const { session } = await createAgentSession({
   cwd: process.cwd(), // default
   
   // Global config directory
-  agentDir: "~/.pi/agent", // default (expands ~)
+  agentDir: "~/.selesai/agent", // default (expands ~)
 });
 ```
 
 `cwd` is used by `DefaultResourceLoader` for:
-- Project extensions (`.pi/extensions/`)
+- Project extensions (`.selesai/extensions/`)
 - Project skills:
-  - `.pi/skills/`
+  - `.selesai/skills/`
   - `.agents/skills/` in `cwd` and ancestor directories (up to git repo root, or filesystem root when not in a repo)
-- Project prompts (`.pi/prompts/`)
+- Project prompts (`.selesai/prompts/`)
 - Context files (`AGENTS.md` walking up from cwd)
 - Session directory naming
 
 `agentDir` is used by `DefaultResourceLoader` for:
 - Global extensions (`extensions/`)
 - Global skills:
-  - `skills/` under `agentDir` (for example `~/.pi/agent/skills/`)
+  - `skills/` under `agentDir` (for example `~/.selesai/agent/skills/`)
   - `~/.agents/skills/`
 - Global prompts (`prompts/`)
 - Global context file (`AGENTS.md`)
@@ -369,7 +369,7 @@ When you pass a custom `ResourceLoader`, `cwd` and `agentDir` no longer control
 
 ```typescript
 import { getModel } from "@earendil-works/pi-ai";
-import { AuthStorage, ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { AuthStorage, ModelRegistry } from "@selesai/code";
 
 const authStorage = AuthStorage.create();
 const modelRegistry = ModelRegistry.create(authStorage);
@@ -416,9 +416,9 @@ API key resolution priority (handled by AuthStorage):
 4. Fallback resolver (for custom provider keys from `models.json`)
 
 ```typescript
-import { AuthStorage, ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { AuthStorage, ModelRegistry } from "@selesai/code";
 
-// Default: uses ~/.pi/agent/auth.json and ~/.pi/agent/models.json
+// Default: uses ~/.selesai/agent/auth.json and ~/.selesai/agent/models.json
 const authStorage = AuthStorage.create();
 const modelRegistry = ModelRegistry.create(authStorage);
 
@@ -452,7 +452,7 @@ const simpleRegistry = ModelRegistry.inMemory(authStorage);
 Use a `ResourceLoader` to override the system prompt:
 
 ```typescript
-import { createAgentSession, DefaultResourceLoader } from "@earendil-works/pi-coding-agent";
+import { createAgentSession, DefaultResourceLoader } from "@selesai/code";
 
 const loader = new DefaultResourceLoader({
   systemPromptOverride: () => "You are a helpful assistant.",
@@ -469,16 +469,16 @@ const { session } = await createAgentSession({ resourceLoader: loader });
 Specify which built-in tools to enable:
 
 - Built-in tool names: `read`, `bash`, `powershell`, `edit`, `write`, `grep`, `find`, `ls`
-- Default built-ins: `read`, `bash`, `edit`, `write`
+- Default built-ins: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`
 - `noTools: "all"` disables all tools
-- Extension and custom tools are inactive by default; include their names in `tools` to enable them
+- Extension and custom tools use their declared `exposure` and `defaultActive`; an explicit `tools` allowlist must include each tool you want enabled
 - `noTools: "builtin"` disables default built-ins and enables extension and custom tools
 - `excludeTools` disables specific built-in, extension, or custom tool names after any `tools` allowlist is applied
 
 The `edit` tool returns `details.diff` for Pi's TUI display and `details.patch` as a standard unified patch for SDK consumers.
 
 ```typescript
-import { createAgentSession } from "@earendil-works/pi-coding-agent";
+import { createAgentSession } from "@selesai/code";
 
 // Read-only mode
 const { session } = await createAgentSession({
@@ -501,7 +501,7 @@ const { session } = await createAgentSession({
 When you pass a custom `cwd`, `createAgentSession()` builds selected built-in tools for that cwd.
 
 ```typescript
-import { createAgentSession, SessionManager } from "@earendil-works/pi-coding-agent";
+import { createAgentSession, SessionManager } from "@selesai/code";
 
 const cwd = "/path/to/project";
 
@@ -525,7 +525,7 @@ const { session } = await createAgentSession({
 
 ```typescript
 import { Type } from "typebox";
-import { createAgentSession, defineTool } from "@earendil-works/pi-coding-agent";
+import { createAgentSession, defineTool } from "@selesai/code";
 
 // Inline custom tool
 const myTool = defineTool({
@@ -557,10 +557,10 @@ If you pass `tools`, include each custom or extension tool name you want enabled
 
 ### Extensions
 
-Extensions are loaded by the `ResourceLoader`. `DefaultResourceLoader` discovers extensions from `~/.pi/agent/extensions/`, `.pi/extensions/`, and settings.json extension sources.
+Extensions are loaded by the `ResourceLoader`. `DefaultResourceLoader` discovers extensions from `~/.selesai/agent/extensions/`, `.selesai/extensions/`, and settings.json extension sources.
 
 ```typescript
-import { createAgentSession, DefaultResourceLoader } from "@earendil-works/pi-coding-agent";
+import { createAgentSession, DefaultResourceLoader } from "@selesai/code";
 
 const loader = new DefaultResourceLoader({
   additionalExtensionPaths: ["/path/to/my-extension.ts"],
@@ -582,7 +582,7 @@ Extensions can register tools, subscribe to events, add commands, and more. See
 **Event Bus:** Extensions can communicate via `pi.events`. Pass a shared `eventBus` to `DefaultResourceLoader` if you need to emit or listen from outside:
 
 ```typescript
-import { createEventBus, DefaultResourceLoader } from "@earendil-works/pi-coding-agent";
+import { createEventBus, DefaultResourceLoader } from "@selesai/code";
 
 const eventBus = createEventBus();
 const loader = new DefaultResourceLoader({
@@ -602,7 +602,7 @@ import {
   createAgentSession,
   DefaultResourceLoader,
   type Skill,
-} from "@earendil-works/pi-coding-agent";
+} from "@selesai/code";
 
 const customSkill: Skill = {
   name: "my-skill",
@@ -628,7 +628,7 @@ const { session } = await createAgentSession({ resourceLoader: loader });
 ### Context Files
 
 ```typescript
-import { createAgentSession, DefaultResourceLoader } from "@earendil-works/pi-coding-agent";
+import { createAgentSession, DefaultResourceLoader } from "@selesai/code";
 
 const loader = new DefaultResourceLoader({
   agentsFilesOverride: (current) => ({
@@ -652,7 +652,7 @@ import {
   createAgentSession,
   DefaultResourceLoader,
   type PromptTemplate,
-} from "@earendil-works/pi-coding-agent";
+} from "@selesai/code";
 
 const customCommand: PromptTemplate = {
   name: "deploy",
@@ -687,7 +687,7 @@ import {
   createAgentSessionServices,
   getAgentDir,
   SessionManager,
-} from "@earendil-works/pi-coding-agent";
+} from "@selesai/code";
 
 // In-memory (no persistence)
 const { session } = await createAgentSession({
@@ -781,7 +781,7 @@ sm.createBranchedSession(leafId);       // Extract path to new file
 ### Settings Management
 
 ```typescript
-import { createAgentSession, SettingsManager, SessionManager } from "@earendil-works/pi-coding-agent";
+import { createAgentSession, SettingsManager, SessionManager } from "@selesai/code";
 
 // Default: loads from files (global + project merged)
 const { session } = await createAgentSession({
@@ -815,8 +815,8 @@ const { session } = await createAgentSession({
 **Project-specific settings:**
 
 Settings load from two locations and merge:
-1. Global: `~/.pi/agent/settings.json`
-2. Project: `<cwd>/.pi/settings.json`
+1. Global: `~/.selesai/agent/settings.json`
+2. Project: `<cwd>/.selesai/settings.json`
 
 Project overrides global. Nested objects merge keys. Setters modify global settings by default.
 
@@ -837,7 +837,7 @@ Use `DefaultResourceLoader` to discover extensions, skills, prompts, themes, and
 import {
   DefaultResourceLoader,
   getAgentDir,
-} from "@earendil-works/pi-coding-agent";
+} from "@selesai/code";
 
 const loader = new DefaultResourceLoader({
   cwd,
@@ -888,7 +888,7 @@ import {
   ModelRegistry,
   SessionManager,
   SettingsManager,
-} from "@earendil-works/pi-coding-agent";
+} from "@selesai/code";
 
 // Set up auth storage (custom location)
 const authStorage = AuthStorage.create("/custom/agent/auth.json");
@@ -973,7 +973,7 @@ import {
   getAgentDir,
   InteractiveMode,
   SessionManager,
-} from "@earendil-works/pi-coding-agent";
+} from "@selesai/code";
 
 const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
   const services = await createAgentSessionServices({ cwd });
@@ -1013,7 +1013,7 @@ import {
   getAgentDir,
   runPrintMode,
   SessionManager,
-} from "@earendil-works/pi-coding-agent";
+} from "@selesai/code";
 
 const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
   const services = await createAgentSessionServices({ cwd });
@@ -1050,7 +1050,7 @@ import {
   getAgentDir,
   runRpcMode,
   SessionManager,
-} from "@earendil-works/pi-coding-agent";
+} from "@selesai/code";
 
 const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
   const services = await createAgentSessionServices({ cwd });
@@ -1142,3 +1142,11 @@ type Tool
 ```
 
 For extension types, see [extensions.md](extensions.md) for the full API.
+
+## Codemode and MCP
+
+SDK sessions do not automatically load the CLI's built-in extensions. Add `createCodemodeExtension()`, `createToolSearchExtension()`, and `createMcpExtension()` through `DefaultResourceLoader.extensionFactories`, reload the loader, and pass it to `createAgentSession()`.
+
+Keep SDK base defaults (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`) by using additive settings such as `defaultTools: ["+codemode", "+tool_search"]`. A plain `tools` allowlist replaces the selection. Calling `session.bindExtensions({})` emits `session_start` and starts configured MCP connections. Before disposal, await `session.extensionRunner.emit({ type: "session_shutdown", reason: "quit" })` so handlers close MCP processes and other long-lived resources. `dispose()` invalidates the runtime and disconnects listeners; it does not await shutdown handlers. Always dispose in a `finally` block even if shutdown fails.
+
+See [examples/sdk/14-codemode-mcp.ts](../examples/sdk/14-codemode-mcp.ts) for a complete example, [MCP](mcp.md) for exposure/authentication, and [Codemode](codemode.md) for tool discovery, classifiers, and image generation. Factory CLI `+codemode` settings do not change the SDK's seven-tool default contract.