@markusylisiurunen/tau 0.3.81 → 0.3.83

package/dist/core/static/tau_docs/session-protocol.md

@@ -1,8 +1,8 @@
 # Session protocol
 
-Tau's session protocol is the public wire contract for clients that create, observe, and control hosted sessions through `tau serve`. Node applications can usually use the typed [Node SDK](node-sdk.md) instead.
+Tau's session protocol is the wire format for clients that create, observe, and control sessions hosted by `tau serve`. Node applications can usually use the typed [Node SDK](node-sdk.md) instead.
 
-The protocol is transport-neutral and request and response based, with separate server messages for observed state, pending input, subagent activity, ephemeral feedback, and delegated client tools. Tau currently exposes it over WebSocket. The complete method surface is in the [session protocol method reference](session-protocol-methods.md).
+The protocol is based on requests and responses, plus server messages for session state, pending input, subagent activity, short-lived feedback, and client tool calls. It does not depend on a particular transport; Tau serves it over WebSocket. The complete method surface is in the [session protocol method reference](session-protocol-methods.md).
 
 ## Connect over WebSocket
 
@@ -10,7 +10,7 @@ The protocol is transport-neutral and request and response based, with separate
 
 The server exposes one host. Starting it does not create or select a session. A client lists, creates, or observes sessions explicitly.
 
-The client, host, and execution environment remain separate logical machines even when they share a process or filesystem. Session paths and commands belong to the execution environment. Persistence, credentials, model work, and protocol coordination belong to the host. Client tools and local UI belong to the connected client. See [ownership and scope](ownership-and-scope.md) before passing paths or credentials across this boundary.
+The client, host, and execution environment are separate, even when they share a process or filesystem. Session paths and commands are on the execution environment. Saving, credentials, model calls, and protocol handling are on the host. Client tools and local UI are on the connected client. See [ownership and scope](ownership-and-scope.md) before passing paths or credentials across this boundary.
 
 ## Connect and initialize
 
@@ -18,19 +18,19 @@ The server sends `ready` as its first message:
 
 ```json
 {
-  "version": 16,
+  "version": 17,
   "type": "ready",
   "methods": ["initialize", "session.create", "session.list"]
 }
 ```
 
-The actual `methods` array contains the complete supported method set, not only the shortened example above. Protocol versioning is exact rather than negotiated. A client and host that disagree on `version` must use compatible Tau releases.
+The real `methods` array lists every supported method; the example above is shortened. Versions must match exactly and are not negotiated. If client and host disagree on `version`, use matching Tau releases.
 
 After `ready`, send `initialize` with non-empty client metadata:
 
 ```json
 {
-  "version": 16,
+  "version": 17,
   "type": "request",
   "id": "init-1",
   "method": "initialize",
@@ -40,9 +40,9 @@ After `ready`, send `initialize` with non-empty client metadata:
 }
 ```
 
-A successful result returns `protocolVersion`, the complete `methods` array, and `alreadyInitialized`. Repeating `initialize` is allowed and reports `alreadyInitialized: true`. Initialization is a handshake signal, not a session operation, but clients should complete it before other requests.
+A successful result returns `protocolVersion`, the full `methods` array, and `alreadyInitialized`. Calling `initialize` again is allowed and returns `alreadyInitialized: true`. It does not act on any session, but clients should complete it before other requests.
 
-An initializing client may advertise in-process client tools through `client.tools`. Tool calls are then delegated over this connection. The [client tools](client-tools.md) page owns tool behavior, authority, and command-backed helpers; this page describes the wire messages required by a raw protocol client.
+A client can offer its own tools in `client.tools` when initializing. Calls to those tools are then sent to it over this connection. [Client tools](client-tools.md) covers tool behavior, permissions, and command helpers; this page covers only the wire messages a raw protocol client needs.
 
 ## Send requests and match responses
 
@@ -50,7 +50,7 @@ Every request has the same envelope:
 
 ```json
 {
-  "version": 16,
+  "version": 17,
   "type": "request",
   "id": "req-42",
   "method": "session.snapshot",
@@ -58,13 +58,13 @@ Every request has the same envelope:
 }
 ```
 
-`id` is a non-empty client-chosen string and must identify the outstanding request on that connection. `params` is always required, including `{}` for `session.list`. The host validates required fields, field types, discriminators, method names, and the exact protocol version. Unknown object fields are accepted and stripped, except system messages and their metadata, which reject unsupported fields.
+`id` is a non-empty string chosen by the client, unique among its open requests on the connection. `params` is always required, even if empty, as in `{}` for `session.list`. The host validates required fields, types, discriminators, method names, and the exact protocol version. Unknown fields are accepted and removed, except in system messages and their metadata, where they are rejected.
 
 Successful responses echo the request id:
 
 ```json
 {
-  "version": 16,
+  "version": 17,
   "type": "response",
   "id": "req-42",
   "ok": true,
@@ -76,7 +76,7 @@ A request can remain open while the host emits state messages or handles later r
 
 ## Observe before consuming session state
 
-`session.create` creates a hosted session but does not observe it. `session.observe` establishes observation on this connection and returns three authoritative baselines together:
+`session.create` creates a session but does not observe it. `session.observe` starts observing on this connection and returns three complete starting states together:
 
 ```json
 {
@@ -86,13 +86,13 @@ A request can remain open while the host emits state messages or handles later r
 }
 ```
 
-Install all three baselines before processing later messages for that session. The host buffers updates while preparing the observe response and sends only updates newer than the returned revisions afterward.
+Install all three before processing later messages for that session. The host holds back updates while preparing the response, and afterward sends only updates newer than the returned revisions.
 
-Observation controls delivery, not session ownership. `session.unobserve` stops this connection's updates without deleting the session or interrupting work. Several connections may observe the same session, and every observer can mutate it. Client-tool names must remain unique across observing clients.
+Observing controls which updates you receive; it does not make you the owner. `session.unobserve` stops this connection's updates without deleting the session or interrupting work. Several connections can observe one session, and each can change it. Client tool names must be unique among observing clients.
 
-## Treat the snapshot as authoritative
+## Treat the snapshot as the source of truth
 
-`SessionProtocolSnapshot` is the recoverable public state for one session. Its major fields are:
+`SessionProtocolSnapshot` is the saved, recoverable state of one session. Its main fields are:
 
 | Field | Meaning |
 | --- | --- |
@@ -100,31 +100,31 @@ Observation controls delivery, not session ownership. `session.unobserve` stops
 | `revision` | Monotonic protocol snapshot revision. |
 | `lifecycle` | `idle` or `running`. |
 | `agentState` | Independent agent revision, model context key, and optional usage checkpoint. |
-| `goal`, `settings`, `costTotal` | Current goal, persona and reasoning settings, and accumulated session cost. |
+| `settings`, `costTotal` | Persona and reasoning settings, and accumulated session cost. |
 | `bootstrap`, `catalog` | Selected model and prompt metadata plus available personas, prompt metadata, skills, and enabled host-configured MCP server names. |
 | `executionEnvironment` | The environment kind, identity, `cwd`, and home used for agent-visible work. |
-| `messages`, `turns` | Synchronized model-facing records and durable logical-turn receipts. |
+| `messages`, `turns` | Messages sent to the model, and a saved record for each accepted turn. |
 | `timeline` | Ordered active transcript placement. |
-| `tools`, `operations`, `agents` | Mutable semantic state referenced by timeline items or client views. |
+| `tools`, `operations`, `agents` | Changing state that timeline items or client views refer to. |
 | `facets` | Versioned client-facing metadata. Unknown facet kinds and versions should be ignored. |
 
-`catalog.mcpServers` lists enabled MCP server names from the host configuration. It does not indicate live connections; servers connect lazily when used. Only names are exposed, not connection settings or credentials.
+`catalog.mcpServers` lists the enabled MCP servers in the host configuration, by name only. It does not mean they are connected; servers connect on first use. Connection settings and credentials are never included.
 
-`bootstrap.prompt.subagentSystemPrompt` is present when subagent launches are enabled. Each catalog persona has a `subagentLaunchModels` allowlist. Subagent records have task titles and IDs, not worker-type names.
+`bootstrap.prompt.subagentSystemPrompt` is present when subagents can be started. Each catalog persona has a `subagentLaunchModels` allowlist. Subagent records have task titles and IDs; there are no worker types.
 
 Render active transcript order from `timeline.items`, not by sorting or filtering `messages`. A timeline item either contains a notice or references a message, tool, or operation in the corresponding snapshot collection. Some model-visible messages intentionally have no timeline item.
 
 The timeline has an `epoch`, a per-epoch sequence high-water mark, and ordered items. Successful compaction replaces the active recoverable timeline and advances the epoch. Rewind stays in the same epoch, removes later items, and preserves the sequence high-water mark so sequence numbers are not reused.
 
-User message text is raw recoverable session text. User-facing renderers should remove Tau metadata and leading exact `<system>...</system>\n` blocks. The Node SDK exports projection helpers for this purpose. Do not apply user-text projection to assistant, tool-result, or protocol system messages.
+User message text is stored raw. Before showing it, remove Tau metadata and any leading `<system>...</system>\n` blocks; the Node SDK exports helpers for this. Apply this only to user messages, never to assistant, tool-result, or system messages.
 
-The initial system message is the separate persona/base prompt. Intermediate system messages are ordered history records with plain-text `content`, a `timestamp`, and required structured `metadata`: `{ type: "instruction" | "auto-compaction-continuation", version: 1 }`. They remain model-visible and recoverable. The normal TUI hides them, while searchable conversation history includes them as system entries. Tau metadata is removed before provider dispatch. Text-block arrays, named sections, and tool additions or removals are not supported in system messages.
+The first system message is the persona's base prompt. Later system messages are history records, in order, with plain-text `content`, a `timestamp`, and required `metadata`: `{ type: "instruction" | "auto-compaction-continuation", version: 1 }`. The model sees them and they are recoverable. The TUI hides them, and searchable history includes them as system entries. Tau metadata is removed before sending to the provider. System messages cannot contain text-block arrays, named sections, or tool changes.
 
-Intermediate instructions are committed without a user turn receipt. Their durable append uses the `system-message` delta cause and does not require a timeline item. The initial prompt has no intermediate-message metadata; recovery restores subsequent instructions without duplicating that base prompt. There is no public insertion method or automatic conversion of user-authored `<system>` text.
+These later system messages are added without a turn record. Adding one uses the `system-message` delta cause and needs no timeline item. The base prompt has no such metadata, and recovery restores later instructions without duplicating it. Clients cannot insert system messages, and a user's `<system>` text is never turned into one.
 
-Turn requests return a terminal outcome, and accepted user turns are also keyed by `userHistoryEntryId` in `snapshot.turns`. Use that ledger to distinguish an unknown request from accepted running work and settled work. Do not infer request outcomes from notice titles, message counts, or timing.
+Turn requests return a final outcome, and each accepted user turn is also recorded in `snapshot.turns`, keyed by `userHistoryEntryId`. Use this record to tell an unknown request apart from accepted work that is running or finished. Never infer outcomes from notice titles, message counts, or timing.
 
-User-facing behavior such as goals, retry, compaction, rewind, and recovery is described in [sessions](sessions.md).
+User-facing behavior such as retry, compaction, rewind, and recovery is described in [sessions](sessions.md).
 
 ## Apply snapshot deltas in order
 
@@ -132,7 +132,7 @@ Observed snapshot changes arrive as `session.delta`:
 
 ```json
 {
-  "version": 16,
+  "version": 17,
   "type": "session.delta",
   "sessionId": "0195d6e4-4cf9-7f44-a2d8-f8f7f49ee9d3",
   "fromRevision": 8,
@@ -152,17 +152,17 @@ Observed snapshot changes arrive as `session.delta`:
 }
 ```
 
-For a patch, `fromRevision` must equal the installed snapshot revision and `toRevision` becomes the new revision. Apply every `changes` entry atomically and in order. Changes can set scalar state, append or replace messages, append streamed content, update the timeline, or set and remove keyed tools, operations, agents, turns, and facets.
+For a patch, `fromRevision` must equal your current snapshot revision, and `toRevision` becomes the new one. Apply all `changes` in order, as one unit. Changes can set scalar state, append or replace messages, append streamed content, update the timeline, or set and remove keyed tools, operations, agents, turns, and facets.
 
-`snapshot.reset` carries a complete replacement snapshot. Reset causes identify `compaction`, `rewind`, or `resync`; compaction and rewind include the timeline data needed to validate the transition. Use the structured cause rather than inferring destructive transitions from content.
+`snapshot.reset` carries a complete new snapshot. Its cause is `compaction`, `rewind`, or `resync`, and compaction and rewind include the timeline data needed to validate the change. Use the cause; never guess at a destructive change from the content.
 
-If a patch has an unexpected `fromRevision`, or applying any change would produce invalid references or ordering, stop applying deltas and call `session.snapshot`. Deltas whose `toRevision` is already installed are stale and must not replay client presentation transitions.
+If a patch has an unexpected `fromRevision`, or a change would leave invalid references or ordering, stop applying deltas and call `session.snapshot`. A delta whose `toRevision` you already have is stale; do not replay its effects in the UI.
 
 Node clients can use `applySessionProtocolDelta`, which validates session identity, revision continuity, timeline rules, references, and the resulting snapshot.
 
 ## Maintain the independent live-state channels
 
-Not all observed state belongs in the recoverable snapshot. Each live channel has its own revision or delivery semantics.
+Some live state is not part of the snapshot. Each of these channels has its own revision or delivery rules.
 
 ### Pending user messages
 
@@ -170,7 +170,7 @@ Not all observed state belongs in the recoverable snapshot. Each live channel ha
 
 ```json
 {
-  "version": 16,
+  "version": 17,
   "type": "session.pendingUserMessages",
   "sessionId": "...",
   "state": {
@@ -183,23 +183,23 @@ Not all observed state belongs in the recoverable snapshot. Each live channel ha
 }
 ```
 
-Replace the complete pending list only when its revision is newer. Pending revisions are independent of snapshot revisions. This state is shared by observers while the hosted session remains in memory, but it starts empty after recovery.
+Replace the whole list, but only when the revision is newer. These revisions are separate from snapshot revisions. All observers share this state while the session is loaded on the host. It is empty after recovery.
 
 ### Subagent activities
 
 `session.subagentActivities` carries an independent `revision` and a list of changes. `agent.set` replaces that agent's complete current-run activity list; `agent.remove` deletes it. Apply changes only when the message revision is newer than the installed activity revision. The observe result provides the complete baseline.
 
-Activity lists contain bounded assistant text, settled tool presentations, and notices. They are transient supervision state, not a substitute for `snapshot.agents`, and they start empty after recovery.
+Activity lists contain limited assistant text, finished tool cards, and notices. They are live progress information, do not replace `snapshot.agents`, and are empty after recovery.
 
 ### Ephemeral events
 
-`session.ephemeral` carries best-effort live events with no channel revision:
+`session.ephemeral` carries live events that are not guaranteed and have no revision:
 
-- `feedback.notice` is temporary footer feedback.
-- `ephemeral-agent.thread-update` reports live progress for an ephemeral context and thread.
-- `timeline.item` is a non-recoverable notice with an active timeline epoch and allocated sequence.
+- `feedback.notice` is short-lived footer feedback.
+- `ephemeral-agent.thread-update` reports progress of an ephemeral context and thread.
+- `timeline.item` is a notice that is not saved, with a timeline epoch and sequence number.
 
-A `timeline.item` can be merged into current presentation only when its epoch matches the installed snapshot. Discard old-epoch items after compaction and post-cutoff items after rewind. Missing ephemeral events do not require resynchronization.
+Show a `timeline.item` only if its epoch matches your snapshot. After compaction, drop items from the old epoch; after rewind, drop items past the rewind point. Missing ephemeral events never require a resync.
 
 ## Delegate client tools
 
@@ -207,7 +207,7 @@ An initialized client that advertised a tool can receive:
 
 ```json
 {
-  "version": 16,
+  "version": 17,
   "type": "session.clientTool.call",
   "sessionId": "...",
   "agentId": "main",
@@ -219,11 +219,11 @@ An initialized client that advertised a tool can receive:
 }
 ```
 
-Acknowledge promptly with `session.clientTool.ack`, optionally including a bounded partial running presentation. Begin execution only after the acknowledgement returns `{ accepted: true }`, then send exactly one `session.clientTool.result` with either `{ ok: true, content }` or `{ ok: false, error }` and an optional independent terminal presentation. Successful `content` is an ordered array of text/image blocks. Both presentation objects may contain `subject`, `subjectWrap`, `details`, and `metadata`; the host owns action and operation and supplies every omitted field. Explicit fields are preserved unchanged after protocol safety validation, while generated defaults use Tau's canonical display truncation. Empty detail or metadata arrays suppress those defaults.
+Acknowledge promptly with `session.clientTool.ack`, optionally with a partial presentation for the running tool card. Start work only after the acknowledgement returns `{ accepted: true }`. Then send exactly one `session.clientTool.result` with `{ ok: true, content }` or `{ ok: false, error }`, optionally with a separate presentation for the finished card. `content` is an ordered array of text and image blocks. Both presentations may contain `subject`, `subjectWrap`, `details`, and `metadata`. The host sets the action and operation and fills in omitted fields. Fields you set are kept unchanged once they pass validation, while defaults are truncated the way Tau truncates its own cards. An empty `details` or `metadata` array hides that default.
 
-A successful result is rejected until acknowledgement has completed. If preparation itself fails, send an error result before acknowledgement; the host records it as a preparation failure without authorizing execution. If no result arrives because of timeout, cancellation, detach, or another failure, the host renders a complete fallback terminal presentation. The result method returns `{ accepted: boolean }`; `false` means the message is invalid for the call's current state or the call is no longer waiting for it.
+A successful result is rejected until the acknowledgement has completed. If preparation fails, send an error result before acknowledging; the host records a preparation failure and the tool never runs. If no result arrives, because of a timeout, cancellation, detach, or other failure, the host shows a complete default card. The result method returns `{ accepted: boolean }`; `false` means the result does not fit the call's current state or the call no longer expects it.
 
-`session.clientTool.cancel` names the session and call with reason `aborted`, `timeout`, `client-detached`, or `host-failed`. Abort local work and do not send a late result. The SDK implements this lifecycle automatically. Tool execution authority and the execution-environment facade are covered in [client tools](client-tools.md).
+`session.clientTool.cancel` names the session and call, with reason `aborted`, `timeout`, `client-detached`, or `host-failed`. Stop local work and do not send a result. The SDK handles all of this for you. Permissions and execution-environment access for client tools are covered in [client tools](client-tools.md).
 
 ## Handle errors and terminal transport failure
 
@@ -231,7 +231,7 @@ Error responses use `ok: false`:
 
 ```json
 {
-  "version": 16,
+  "version": 17,
   "type": "response",
   "id": "req-42",
   "ok": false,
@@ -255,19 +255,19 @@ The supported codes are:
 | `cancelled` | Pending input, execution, or sampling was cancelled. |
 | `internal_error` | The host could not complete the operation. |
 
-When no valid request id can be recovered, an error response uses `id: null`. Error `message` and optional `data` are diagnostic. Branch on `code`, not message text.
+When the request ID cannot be read, the error response uses `id: null`. The error `message` and optional `data` are for diagnostics. Branch on `code`, never on message text.
 
-A WebSocket close, malformed server payload, unsupported version, or other terminal transport failure rejects all outstanding requests. Stop sending, cancel client-local delegated tools, and reconnect or create a new transport deliberately. A WebSocket disconnect detaches from the long-running host.
+A WebSocket close, a malformed server message, an unsupported version, or another fatal transport failure rejects all open requests. Stop sending, cancel running client tools, and reconnect or create a new transport on purpose. A WebSocket disconnect only detaches from the long-running host.
 
 ## Coordinate concurrent work
 
-The server can accept several requests before earlier requests settle, so responses and streamed messages may interleave.
+The server accepts new requests before earlier ones finish, so responses and streamed messages can interleave.
 
-- Only one ordinary main-session turn or goal turn runs at a time. `session.submit`, `session.retry`, `session.startGoal`, and `session.resumeGoal` return `busy` on conflict.
-- `session.queue` waits for idle work. `session.steer` requests the next safe turn boundary. Each request receives its own eventual response.
-- Session mutations are serialized in arrival order across clients. Mutations that replace context can interrupt active work and reject pending input. `session.rewind` instead requires the session to be idle with no pending input.
-- `session.setReasoning` is serialized but does not interrupt the active turn. The new setting applies to the next independently started turn.
-- `session.exec` and `session.sample` are side channels. They can overlap turns, mutations, each other, and ephemeral agents. Clients own workspace coordination.
-- Ephemeral contexts run outside the main mutation queue. Two submissions to the same ephemeral thread conflict, while different threads can run independently.
+- Only one main-session turn runs at a time. `session.submit` and `session.retry` return `busy` on conflict.
+- `session.queue` waits until the session is idle. `session.steer` joins the running turn at its next safe point. Each request gets its own response when done.
+- Session changes run one at a time, in arrival order across all clients. Changes that replace the context can interrupt running work and reject pending input. `session.rewind` instead requires an idle session with no pending input.
+- `session.setReasoning` waits its turn but does not interrupt the running turn. The new setting applies from the next turn.
+- `session.exec` and `session.sample` run alongside everything else: turns, other changes, each other, and ephemeral agents. Clients must coordinate their own use of the workspace.
+- Ephemeral contexts are not part of that one-at-a-time ordering. Two submissions to the same ephemeral thread conflict, while different threads can run at once.
 
-Do not assume a success response arrives before the deltas caused by that request. Maintain state from the observed streams, correlate completion by request id, and use `session.snapshot` when continuity is uncertain.
+A success response may arrive before or after the deltas the request caused. Keep state from the observed streams, match completion by request ID, and call `session.snapshot` when unsure whether you missed something.