@markusylisiurunen/tau 0.3.50 → 0.3.51

package/dist/core/static/tau_docs/client-tools.md

@@ -117,23 +117,222 @@ Diff-tool launcher settings are separate from command client-tool definitions. T
 
 ## Implement a command tool with Tau's helper
 
-Command client tools use Tau's version 3 bidirectional NDJSON protocol over stdin and stdout. Use the exported helper instead of implementing framing manually:
+Command client tools use Tau's version 4 bidirectional NDJSON protocol over stdin and stdout. Use the exported helper instead of implementing framing manually:
 
 ```ts
-import { runTauClientToolCommand } from "@markusylisiurunen/tau/code-mode";
+import {
+  runTauClientToolCommand,
+  truncateTauClientToolText,
+} from "@markusylisiurunen/tau/code-mode";
+
+await runTauClientToolCommand({
+  name: "notify_desktop",
+  describe(args) {
+    const input = args as { title: string; message: string };
+    return {
+      subject: truncateTauClientToolText(input.title),
+    };
+  },
+  async execute(args, context) {
+    const input = args as { title: string; message: string };
+    context.signal.throwIfAborted();
+
+    await showNotification(input.title, input.message, context.signal);
+    return {
+      content: "Notification displayed.",
+      presentation: {
+        subject: truncateTauClientToolText(input.title),
+      },
+    };
+  },
+});
+```
+
+`describe` is optional. When present, it runs before acknowledgement and may return a partial running presentation containing `subject`, `subjectWrap`, `details`, or `metadata`. The execution result may independently include the same partial shape for the terminal card. Tau supplies every omitted field, owns lifecycle actions and the operation derived from the registered tool name, and renders a complete fallback when execution ends without a result.
+
+Tau preserves every explicit presentation field up to the protocol safety limits; it does not apply display truncation or normalize client text. `truncateTauClientToolText` provides optional caller-controlled `maxLines`, `maxLineChars`, and `head` or `middle` truncation. Its defaults match Tau's concise subject policy, but callers may select larger or smaller positive limits.
+
+For a subject, use the returned string directly. For a block of detail text, split the returned string on `\n` and map each line to one `details` entry:
+
+```ts
+const details = truncateTauClientToolText(output, {
+  maxLines: 7,
+  maxLineChars: 512,
+  strategy: "middle",
+})
+  .split("\n")
+  .map((text) => ({ text }));
+```
+
+Each detail or metadata entry is a single protocol line, so use `maxLines: 1` when assigning the helper's result directly to one entry. The helper shapes text for presentation; the protocol byte and collection limits still apply. Empty detail or metadata arrays explicitly suppress that phase's defaults.
+
+`runTauClientToolCommand` reads the preparation, writes readiness and any running presentation, waits until the host accepts the call, then provides the standard execution context and writes the final result. It handles execution-environment request and cancellation framing and reacts to `SIGINT`, `SIGTERM`, and protocol input closure by aborting the handler.
+
+Reserve stdout for the helper's protocol. Write diagnostics to stderr. Return a string or `{ content, presentation? }` for success. Return `{ ok: false, error, presentation? }` for a structured tool failure. Successful content and failure text become model-visible tool results.
+
+### Version 4 frame reference
+
+The shapes below use TypeScript notation. Serialize each frame as one exact JSON object followed by a newline; unknown fields are invalid.
 
-await runTauClientToolCommand(async (args, context) => {
-  const input = args as { title: string; message: string };
-  context.signal.throwIfAborted();
+Tau starts the exchange by writing:
 
-  await showNotification(input.title, input.message, context.signal);
-  return { content: "Notification displayed." };
+- `{ version: 4, type: "prepare", sessionId, agentId, callId, toolName, arguments }` exactly once. The identity fields are non-empty strings and `arguments` is the validated model input.
+- `{ version: 4, type: "execute" }` after accepting the command's ready frame. This authorizes execution.
+
+The command writes:
+
+- `{ version: 4, type: "ready", presentation?: PresentationOverride }` exactly once after preparation.
+- `{ version: 4, type: "result", ok: true, content, presentation?: PresentationOverride }` or `{ version: 4, type: "result", ok: false, error, presentation?: PresentationOverride }` exactly once after authorization. `content` and `error` are strings.
+
+During authorized execution, the command may write `{ version: 4, type: "exec", requestId, command, options }`. The non-empty `command` string runs in the session execution environment. `options` is required and may contain `args: string[]`, `env: Record<string, string>`, base64-encoded string `stdinBase64`, string `cwd`, positive integer `timeoutMs`, and positive integer `maxCaptureBytes`.
+
+Tau answers with the same `requestId` and either:
+
+- `{ version: 4, type: "exec.result", requestId, ok: true, result: ExecResult }`
+- `{ version: 4, type: "exec.result", requestId, ok: false, error: string }`
+
+`ExecResult` contains string `output`, `stdout`, and `stderr`; nullable `exitCode` and `closeSignal`; and boolean `truncated`, `timedOut`, and `aborted`. A command may cancel one unresolved request with `{ version: 4, type: "exec.cancel", requestId }`. Request IDs must be non-empty strings and cannot be reused within a call.
+
+### Implement the protocol directly in JavaScript
+
+A JavaScript command can implement the version 4 handshake using only Node.js built-ins, without importing Tau or the code-mode package:
+
+```js
+#!/usr/bin/env node
+
+import { arch, platform, release } from "node:os";
+import { createInterface } from "node:readline";
+
+const lines = createInterface({
+  input: process.stdin,
+  crlfDelay: Number.POSITIVE_INFINITY,
 });
+const input = lines[Symbol.asyncIterator]();
+
+async function readFrame() {
+  const next = await input.next();
+  if (next.done) throw new Error("Tau closed the command protocol");
+  return JSON.parse(next.value);
+}
+
+function writeFrame(frame) {
+  process.stdout.write(`${JSON.stringify(frame)}\n`);
+}
+
+const prepare = await readFrame();
+if (
+  prepare.version !== 4 ||
+  prepare.type !== "prepare" ||
+  prepare.toolName !== "system_info"
+) {
+  throw new Error("Invalid system_info preparation");
+}
+
+writeFrame({
+  version: 4,
+  type: "ready",
+  presentation: {
+    subject: "local system",
+  },
+});
+
+const execute = await readFrame();
+if (execute.version !== 4 || execute.type !== "execute") {
+  throw new Error("Invalid system_info authorization");
+}
+
+writeFrame({
+  version: 4,
+  type: "exec",
+  requestId: "git-status",
+  command: "git status --short",
+  options: {
+    maxCaptureBytes: 256 * 1024,
+  },
+});
+
+const response = await readFrame();
+if (
+  response.version !== 4 ||
+  response.type !== "exec.result" ||
+  response.requestId !== "git-status"
+) {
+  throw new Error("Invalid execution-environment response");
+}
+if (!response.ok) throw new Error(response.error);
+
+const localSystem = `${platform()} ${release()} ${arch()}`;
+const workspaceStatus =
+  response.result.output.trim() || "Working tree is clean.";
+writeFrame({
+  version: 4,
+  type: "result",
+  ok: true,
+  content: `${localSystem}\n\n${workspaceStatus}`,
+  presentation: {
+    subject: "local system",
+  },
+});
+
+lines.close();
 ```
 
-`runTauClientToolCommand` reads the invocation, provides a standard context, handles execution-environment request and cancellation framing, and writes the final result. It also reacts to `SIGINT`, `SIGTERM`, and protocol input closure by aborting the handler.
+The `exec` frame asks Tau to run `git status --short` in the session execution environment, which may be a different machine from the JavaScript process. Tau returns the matching `exec.result` on stdin. Request IDs are single-use, and the command must check both the ID and `ok` before consuming the result.
+
+Make the file executable with `chmod +x`. Diagnostics and uncaught errors go to stderr; stdout remains reserved for protocol frames.
+
+### Implement a simple command tool in Bash
+
+A small command that needs only client-machine authority can also implement the handshake in Bash. This example depends on `jq` for safe JSON parsing and encoding:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+IFS= read -r prepare
+jq -e '
+  .version == 4 and
+  .type == "prepare" and
+  .toolName == "system_info"
+' >/dev/null <<<"$prepare"
+
+jq -cn '{
+  version: 4,
+  type: "ready",
+  presentation: {
+    subject: "local system"
+  }
+}'
+
+IFS= read -r execute
+jq -e '.version == 4 and .type == "execute"' >/dev/null <<<"$execute"
+
+content=$(uname -a)
+jq -cn --arg content "$content" '{
+  version: 4,
+  type: "result",
+  ok: true,
+  content: $content
+}'
+```
+
+Configure either executable as an argument-free command tool:
+
+```json
+{
+  "name": "system_info",
+  "defaultEnabled": true,
+  "description": "Report operating-system information from the client machine.",
+  "parameters": {
+    "type": "object",
+    "properties": {},
+    "additionalProperties": false
+  },
+  "command": "./bin/tau-system-info"
+}
+```
 
-Reserve stdout for the helper's protocol. Write diagnostics to stderr. Return either a string or `{ content: string }`; that text becomes the model-visible tool result.
+Both `ready.presentation` and `result.presentation` are optional partial objects with `subject`, `subjectWrap`, `details`, and `metadata`. The ready value applies while the call runs; the result value applies only to its terminal state. Omit either object, or any field within it, to use Tau's default for that phase. Empty `details` or `metadata` arrays suppress the corresponding default field. The script must emit `ready` before reading the authorization-bearing `execute` frame. Direct implementations can emit the same `exec` frames shown in the JavaScript example, but the TypeScript helper is preferable when the tool needs multiple target-environment requests, cancellation forwarding, or more involved protocol handling.
 
 The handler receives:
 
@@ -181,7 +380,7 @@ Tau exports two higher-level helpers for client tools that expose a bounded Java
 
 For an executable configured through `clientTools`, keep the exact parameters schema to one required `code` string with no additional properties, then call `runTauCodeModeCommand` in the executable. For SDK clients, pass the returned tool from `createTauCodeModeClientTool` in the client's `clientTools` array.
 
-Both helpers supply the invocation identities, cancellation signal, execution-environment facade, progressive `docs` value, bounded API bridge, and agent-scoped scratch files. The model-facing description remains explicit caller input. Use Tau's optional shared description builder only when its progressive-disclosure wording fits the tool; Tau does not silently rewrite a configured description.
+Both helpers supply the invocation identities, cancellation signal, execution-environment facade, progressive `docs` value, bounded API bridge, and agent-scoped scratch files. They use the submitted code, concisely truncated and character-wrapped, as the running and terminal tool-card subject. The model-facing description remains explicit caller input. Use Tau's optional shared description builder only when its progressive-disclosure wording fits the tool; Tau does not silently rewrite a configured description.
 
 The generic code-mode runtime is documented through its exported types and generated tool documentation. Do not layer another unbounded process or network channel behind it without making that authority clear in the tool description.
 
@@ -195,12 +394,13 @@ The command protocol is intentionally bounded:
 - Captured stderr is limited to 1 MiB. Exceeding it terminates the command and fails the tool.
 - Execution-environment stdin is limited to 16 MiB decoded, and capture can be requested up to 24 MiB per execution.
 - At most eight execution requests may be unresolved concurrently.
+- Each client-tool presentation override is limited to 1 MiB in total. Its subject is limited to 256 KiB; metadata values to 16 KiB each; detail values to 256 KiB each; and detail and metadata collections to 1,024 entries each. These are safety limits, not recommended UI sizes. Tau preserves explicit values within those limits. Clients may use the exported helper when they want a concise preview.
 
-The configured `executionTimeoutMs` covers the whole command invocation and defaults to 60 seconds. The host also requires the owning client to acknowledge a dispatched call promptly. Standard Tau SDK clients handle acknowledgement before invoking the tool handler.
+The configured `executionTimeoutMs` covers preparation and execution and defaults to 60 seconds. The host also requires the owning client to prepare and acknowledge a dispatched call promptly. Command executables emit readiness and any bounded running presentation before acknowledgement, then wait for Tau to authorize execution.
 
 Tau starts each configured command in a detached process group. Cancellation sends termination to the group and escalates to `SIGKILL` after a short grace period, even if the original group leader exits first. The helper aborts pending execution-environment requests and stops accepting work when stdin closes.
 
-A successful command must exit with status zero after producing one final version 3 result. Missing results, malformed framing, data after the result, reused execution request IDs, nonzero exit, timeout, cancellation, excessive output, and protocol-limit violations fail the call. Stderr is included in failure diagnostics but is not a successful result channel.
+A successful protocol exchange must emit one version 4 ready frame, wait for the execute frame, emit one final version 4 result with `ok: true` or `ok: false`, and exit with status zero. An `ok: false` frame is a communicated tool failure; process and framing failures still use stderr and a nonzero exit. Missing or duplicate readiness, execution data before authorization, missing results, malformed framing, data after the result, reused execution request IDs, timeout, cancellation, excessive output, and protocol-limit violations fail the call.
 
 ## Disconnects, reconnects, and durability
 

package/dist/core/static/tau_docs/configuration.md

@@ -185,7 +185,7 @@ Restart the host process to apply settings used to construct host-wide services,
 - `history`
 - host environment variables and Codex account forcing
 
-For `tau serve` or `tau rpc`, make the changes on the host machine and restart that server. Restarting only an attached TUI does not rebuild the host.
+For `tau serve`, make the changes on the host machine and restart the server. Restarting only an attached TUI does not rebuild the host.
 
 ### New session or runner
 

package/dist/core/static/tau_docs/credentials.md

@@ -19,10 +19,10 @@ Common cases are:
 | Nook host tool | Session host |
 | Cloudflare Sandbox bridge and Fly Sprite API | Session host startup |
 | `/listen` and `/speak` | TUI client |
-| Telegram transcription | Telegram runner |
+| Telegram transcription and voice responses | Telegram runner |
 | `tau tool pdf-unpack` | The process running that command |
 
-With local `tau`, these roles normally share one machine. With `tau attach`, setting a key only in the attached client's shell does not authenticate the remote host. Run `tau auth` on the host machine and set host-owned environment variables where `tau serve`, `tau rpc`, or the SDK host actually runs. See [ownership and scope](ownership-and-scope.md) for the full boundary.
+With local `tau`, these roles normally share one machine. With `tau attach`, setting a key only in the attached client's shell does not authenticate the remote host. Run `tau auth` on the host machine and set host-owned environment variables where `tau serve` or the SDK host actually runs. See [ownership and scope](ownership-and-scope.md) for the full boundary.
 
 ## Provider API keys
 
@@ -61,12 +61,12 @@ Several Tau features share provider credentials but intentionally prefer a fixed
 | Feature | Resolution order |
 | --- | --- |
 | Exa web search and fetch | `EXA_API_KEY`, then `apiKeys.exa` |
-| Google speech, Gemini speech-to-text, and Telegram Gemini transcription | `GEMINI_API_KEY`, then `apiKeys.google` |
+| Google speech, Gemini speech-to-text, Telegram Gemini transcription, and Telegram voice responses | `GEMINI_API_KEY`, then `apiKeys.google` |
 | Mistral speech-to-text, Telegram Mistral transcription, and PDF OCR | `MISTRAL_API_KEY`, then `apiKeys.mistral` |
 
 The Google and Mistral rows describe feature-specific helpers. Model calls follow the general model-authentication order instead, where the configured provider key wins over ambient environment authentication.
 
-`web.discover` does not require Exa. `web.search` and `web.fetch` do. `/speak` uses Google. `/listen` and Telegram audio use the configured `speechToText.provider`, which is `mistral` unless configuration selects `gemini`. PDF OCR through `tau tool pdf-unpack` uses Mistral.
+`web.discover` does not require Exa. `web.search` and `web.fetch` do. `/speak` and Telegram `/tts_on` voice responses use Google. `/listen` and incoming Telegram audio use the configured `speechToText.provider`, which is `mistral` unless configuration selects `gemini`. PDF OCR through `tau tool pdf-unpack` uses Mistral.
 
 Set these variables on the process that owns the feature. For example, a remote TUI's `/speak` reads the attached client's `GEMINI_API_KEY`, while a Google model selected by the session reads credentials at the host.
 

package/dist/core/static/tau_docs/history.md

@@ -12,7 +12,7 @@ Every Tau host opens a machine-local SQLite database at:
 ~/.config/tau/history.sqlite
 ```
 
-The path belongs to the **host home**. An attached TUI and a remote execution environment do not get separate history stores merely because they participate in the session. Local `tau`, `tau serve`, `tau rpc`, and the default SDK host all use the host machine's database.
+The path belongs to the **host home**. An attached TUI and a remote execution environment do not get separate history stores merely because they participate in the session. Local `tau`, `tau serve`, and the default SDK host all use the host machine's database.
 
 For each session, history stores its immutable creation attributes and an ordered active transcript containing:
 

package/dist/core/static/tau_docs/index.md

@@ -34,7 +34,7 @@ The intrinsic `tau_docs` tool reads one exact Markdown path at a time. It does n
 
 - [Tools](tools.md) explains built-in tool availability, execution, cancellation, and code-mode tools.
 - [Sessions](sessions.md) covers creation, turns, queueing, compaction, rewind, goals, recovery, and persistence.
-- [Remote sessions](remote-sessions.md) explains `serve`, `rpc`, `attach`, remote paths, and transport authentication.
+- [Remote sessions](remote-sessions.md) explains `serve`, `attach`, remote paths, and transport authentication.
 - [History](history.md) covers local transcript history, optional remote replication, and the history tool.
 - [Nook](nook.md) explains configuration and operation of the optional static mini-app platform.
 - [Telegram](telegram.md) covers runner configuration, projects, workspaces, routing, and recovery.

package/dist/core/static/tau_docs/node-sdk.md

@@ -1,6 +1,6 @@
 # Node SDK
 
-Tau's Node SDK provides a typed client for creating, observing, and controlling sessions without implementing the wire protocol directly. Use the in-process client when your application should own the host, the WebSocket client for a long-running `tau serve` host, or the transport adapter when another process owns the connection.
+Tau's Node SDK provides a typed client for creating, observing, and controlling sessions without implementing the wire protocol directly. Use the in-process client when your application should own the host, the WebSocket client for a long-running `tau serve` host, or the transport adapter with a custom connection implementation.
 
 The SDK uses the same public [session protocol](session-protocol.md) as the TUI. Session behavior is therefore consistent across local applications, remote integrations, and terminal clients.
 
@@ -74,23 +74,7 @@ WebSocket authentication grants full session access. Deployment and TLS guidance
 
 ### Supply a protocol transport
 
-`createTauSdkClientFromTransport(transport, options?)` builds the same client facade over any `SessionProtocolTransport`. Tau exports `StdioSessionProtocolTransport` for a spawned `tau rpc` process:
-
-```ts
-import { spawn } from "node:child_process";
-import {
-  StdioSessionProtocolTransport,
-  createTauSdkClientFromTransport,
-} from "@markusylisiurunen/tau/sdk";
-
-const child = spawn("tau", ["rpc"], {
-  stdio: ["pipe", "pipe", "pipe"],
-});
-const transport = new StdioSessionProtocolTransport(child);
-const client = await createTauSdkClientFromTransport(transport);
-```
-
-The stdio transport owns the supplied process connection and terminates it on close. Stdout must contain only protocol NDJSON; stderr is retained for bounded process diagnostics.
+`createTauSdkClientFromTransport(transport, options?)` builds the same client facade over any `SessionProtocolTransport`. This keeps the SDK facade independent of WebSocket and allows applications to supply another transport without changing session semantics.
 
 A custom transport implements:
 
@@ -295,6 +279,11 @@ If rendering `timeline.item`, accept only the active epoch and merge by its allo
 Pass `TauSdkClientTool` entries in `clientTools` when model-facing work must run in the integration process:
 
 ```ts
+import {
+  createTauSdkClient,
+  truncateTauClientToolText,
+} from "@markusylisiurunen/tau/sdk";
+
 const client = await createTauSdkClient({
   clientTools: [
     {
@@ -303,12 +292,22 @@ const client = await createTauSdkClient({
         description: "Choose one item from the user's local workspace.",
         parameters: {
           type: "object",
-          properties: {},
+          properties: {
+            choice: { type: "string" },
+          },
+          required: ["choice"],
           additionalProperties: false,
         },
         executionTimeoutMs: 60_000,
       },
-      execute: async (_args, context) => {
+      describe: (args) => {
+        const input = args as { choice: string };
+        return {
+          subject: truncateTauClientToolText(input.choice),
+        };
+      },
+      execute: async (args, context) => {
+        const input = args as { choice: string };
         context.signal.throwIfAborted();
         const status = await context.executionEnvironment.exec(
           "git status --short",
@@ -316,7 +315,12 @@ const client = await createTauSdkClient({
             signal: context.signal,
           },
         );
-        return status.output || "Working tree is clean.";
+        return {
+          content: status.output || "Working tree is clean.",
+          presentation: {
+            subject: truncateTauClientToolText(input.choice),
+          },
+        };
       },
     },
   ],
@@ -325,7 +329,11 @@ const client = await createTauSdkClient({
 
 The handler receives `sessionId`, owning `agentId`, `callId`, an `AbortSignal`, and an execution-environment facade. The handler itself runs on the client machine. `context.executionEnvironment.exec()` crosses the session boundary and runs in the session execution environment.
 
-The SDK acknowledges delegated calls, converts a returned string or `{ content }` to the wire result, reports thrown errors, and aborts handlers on host cancellation, client close, or terminal transport failure. `client.close()` waits for active handlers to settle.
+`describe` is optional. When present, the SDK calls it with the arguments and a reduced context containing `sessionId`, `agentId`, `callId`, and `signal` before acknowledgement. This context deliberately has no execution-environment facade. It may return a partial running presentation containing `subject`, `subjectWrap`, `details`, or `metadata`. Tau owns action and operation, fills every omitted field, and acknowledges the resolved presentation before calling `execute`.
+
+The execution result may independently include the same partial shape for the terminal card. Return a string or `{ content, presentation? }` for success, or `{ ok: false, error, presentation? }` for a structured failure. Omitted presentation fields use Tau's terminal defaults; empty detail or metadata arrays suppress those defaults. If `describe` throws, the SDK reports a preparation error without calling `execute`. If the client never returns a result because of cancellation, timeout, detach, or another failure, the host produces a complete fallback presentation.
+
+Tau preserves every explicit presentation field up to the protocol safety limits; it does not apply display truncation or normalize client text. `truncateTauClientToolText` provides optional caller-controlled line, character, and head or middle truncation. Use its result directly for a subject. For a block of detail text, split the result on `\n` and map each line to one `details` entry; use `maxLines: 1` when assigning it directly to one detail or metadata entry. The helper shapes text but does not replace protocol validation. The SDK aborts handlers on host cancellation, client close, or terminal transport failure. `client.close()` waits for active handlers to settle.
 
 Tool definitions are frozen for each assistant turn and remain independent of persona tool allowlists. Names cannot collide with host tools or another observing client's tools. See [client tools](client-tools.md) for authority, limits, command-backed tools, and disconnect behavior.
 
@@ -353,7 +361,7 @@ const tickets = createTauCodeModeClientTool({
 });
 ```
 
-Pass `tickets` in `clientTools`. Generated code receives the declared API namespace, progressively disclosed `docs`, console output, live `Date` and `Math`, and agent-scoped scratch files when invoked as a client tool. API calls cross a bounded JSON bridge. The tool description remains explicit caller input; the builder is optional.
+Pass `tickets` in `clientTools`. Generated code receives the declared API namespace, progressively disclosed `docs`, console output, live `Date` and `Math`, and agent-scoped scratch files when invoked as a client tool. API calls cross a bounded JSON bridge. The submitted code appears, concisely truncated and character-wrapped, as the running and terminal tool-card subject. The tool description remains explicit caller input; the builder is optional.
 
 The SDK also exports `executeTauCodeMode` for standalone execution. The separate `@markusylisiurunen/tau/code-mode` entry point additionally exports file-capability types, `runTauClientToolCommand`, and `runTauCodeModeCommand` for command-backed tools. Use the helpers instead of implementing their framing manually.
 
@@ -361,7 +369,7 @@ The SDK also exports `executeTauCodeMode` for standalone execution. The separate
 
 Most turn and mutation methods do not accept an `AbortSignal`. Call `session.interrupt()` to cancel active host work. `session.exec()` is the exception: its optional signal targets only that execution.
 
-`session.unobserve()` retires one facade. `client.close()` retires the connection, rejects pending transport requests, aborts client-tool handlers, waits for them to settle, and then closes the transport. For the default in-process client it also persists sessions and shuts down the owned host. For WebSocket it leaves the remote host and sessions running. For stdio it closes the owned process connection.
+`session.unobserve()` retires one facade. `client.close()` retires the connection, rejects pending transport requests, aborts client-tool handlers, waits for them to settle, and then closes the transport. For the default in-process client it also persists sessions and shuts down the owned host. For WebSocket it leaves the remote host and sessions running.
 
 Always close clients in `finally`. Do not continue using a session facade after unobserve or any client after close.
 
@@ -371,7 +379,6 @@ All exported SDK and transport errors extend `TauSessionClientError`:
 
 - `TauSessionProtocolResponseError` means the host returned a protocol error. It exposes `code`, `message`, `requestId`, and optional `data`.
 - `TauTransportError` means connection setup, framing, version validation, timeout, closure, or another terminal transport operation failed.
-- `TauProcessError` extends `TauTransportError` for a stdio subprocess failure and includes `exitCode`, `signal`, and bounded `stderr`.
 
 Branch on a protocol error's `code`, not its message. A successful request can still return a failed, aborted, or blocked turn outcome, so inspect `result.turn.status` separately.
 
@@ -384,7 +391,7 @@ The SDK entry point exports the types needed at integration boundaries rather th
 - `TauSdkClient`, `TauSdkSession`, client option types, session summaries, and request and result aliases;
 - `TauSdkDelta`, `SessionProtocolSnapshot`, pending-message types, subagent-activity types, and ephemeral event types;
 - `TauSdkClientTool`, its execution context and environment facade, and code-mode definition and result types;
-- `SessionProtocolTransport`, listener types, WebSocket options, stdio process type, and transport errors.
+- `SessionProtocolTransport`, listener types, WebSocket options, and transport errors.
 
 It also exports `applySessionProtocolDelta`, `applySessionProtocolSubagentActivitiesMessage`, the turn-ledger helpers, and user-text projection helpers:
 

package/dist/core/static/tau_docs/ownership-and-scope.md

@@ -12,7 +12,7 @@ Client tools execute on the client machine, not wherever the agent's Bash tool r
 
 ### Host
 
-The **host** creates, observes, persists, and recovers sessions. It owns model calls, credentials, session orchestration, tool binding, history storage, and execution-environment lifecycle. Local `tau` creates an in-process host. `tau serve` and `tau rpc` are standalone host entry points.
+The **host** creates, observes, persists, and recovers sessions. It owns model calls, credentials, session orchestration, tool binding, history storage, and execution-environment lifecycle. Local `tau` creates an in-process host. `tau serve` is the standalone host entry point.
 
 The host's home owns data such as session snapshots, authentication storage, usage logs, and the local history database. Use Tau commands and session operations to manage these stores rather than editing their files directly.
 
@@ -38,10 +38,9 @@ For repository and composite projects it prepares managed workspaces. A configur
 | --- | --- | --- | --- |
 | `tau` | Local TUI process | In-process on the same machine | Local `cwd` where Tau started |
 | `tau attach … ws://…` | Machine running `tau attach` | Machine running `tau serve` | Environment selected or restored by that host |
-| `tau attach … -- <command>` | Machine running `tau attach` | Machine running the protocol command, often reached through SSH | Environment selected or restored by that host |
-| `tau rpc` or `tau serve` | A separate protocol client | The server process | Local or configured hosted environment chosen by the client |
+| `tau serve` | A separate protocol client | The server process | Local or configured hosted environment chosen by the client |
 | Default Node SDK client | SDK caller | In-process with the SDK caller | Usually a local environment supplied at session creation |
-| SDK over WebSocket or stdio | SDK caller | Remote server or command process | Environment selected or restored by that host |
+| SDK over WebSocket | SDK caller | Remote server | Environment selected or restored by that host |
 | `tau telegram` | Telegram runner | In-process on the runner machine | Prepared project workspace or persistent directory |
 
 A Cloudflare Sandbox or Fly Sprite can place the execution environment on another target while the host stays on its own machine. The host keeps provider credentials and orchestration authority; the target owns its paths and commands.

package/dist/core/static/tau_docs/prompts-and-project-context.md

@@ -139,7 +139,7 @@ tau --no-agent-context-files
 
 This disables ancestor `AGENTS.md` injection, configured `agentContextFiles`, and the descendant paths-only scan. It does not disable personas, prompt templates, or [skills](skills.md).
 
-The option applies to local TUI sessions and to hosts started with `tau rpc` or `tau serve`. For the Node SDK, `noAgentContextFiles: true` provides the same host-level behavior. An attached client cannot retroactively change how an existing remote host session was created.
+The option applies to local TUI sessions and to hosts started with `tau serve`. For the Node SDK, `noAgentContextFiles: true` provides the same host-level behavior. An attached client cannot retroactively change how an existing remote host session was created.
 
 ## Alternate subagent working directories
 
@@ -176,6 +176,6 @@ For a new local TUI session, debug mode prints discovered content, loaded contex
 tau --debug --persona release-coder
 ```
 
-Add `--no-agent-context-files` to verify the context-free variant. Debug mode is TUI startup functionality and is not available with `tau rpc` or `tau serve`.
+Add `--no-agent-context-files` to verify the context-free variant. Debug mode is TUI startup functionality and is not available with `tau serve`.
 
 If expected context is missing, verify the execution-environment `cwd` and `home`, not just the attached client's current directory. Then check exact filenames, canonical path eligibility, configuration-level path bases, scan exclusions, and reload warnings. See [troubleshooting](troubleshooting.md) for broader diagnostics.

package/dist/core/static/tau_docs/remote-sessions.md

@@ -1,6 +1,6 @@
 # Remote sessions
 
-Remote sessions let the terminal stay close to the user while the session host and execution environment run elsewhere. Tau does not turn remote work into a second product mode: `tau attach` uses the same TUI over a WebSocket or stdio transport. The important choice is which process should stay alive, who owns credentials and persistence, and where agent-visible commands run.
+Remote sessions let the terminal stay close to the user while the session host and execution environment run elsewhere. Tau does not turn remote work into a second product mode: `tau attach` uses the same TUI over WebSocket. The important boundaries are who owns credentials and persistence and where agent-visible commands run.
 
 ## Choose the connection shape
 
@@ -9,12 +9,10 @@ Use the smallest shape that matches the lifecycle you need.
 | Shape | Best for | Lifetime and ownership |
 | --- | --- | --- |
 | `tau serve` plus WebSocket attach | Long-running hosts, reconnects, and multiple observers | The server owns the host independently of any one TUI. |
-| `tau attach -- ssh … tau rpc` | Ad hoc access through SSH without exposing a listener | The attachment owns one remote RPC process. Closing it shuts that host down. |
-| `tau rpc` directly | Editors, automation, and custom protocol clients over NDJSON | The parent process owns the RPC host and its stdin/stdout. |
 | Node SDK with its default client | Applications that want an in-process host | The SDK client owns the host and closes it with the client. |
 | Node SDK over WebSocket | Applications sharing a long-running `tau serve` host | The server owns sessions; the SDK observes them remotely. |
 
-Use `tau serve` when a turn should continue after a laptop disconnects. Use stdio/SSH when SSH is already the desired security and process boundary and it is acceptable for closing the TUI to stop remote work. The [session protocol](session-protocol.md) and [Node SDK](node-sdk.md) cover developer APIs and wire details; this page stays at the operational level.
+Use `tau serve` for remote TUI and SDK connections. Keep it bound to loopback behind an SSH tunnel when SSH is the desired security boundary. The [session protocol](session-protocol.md) and [Node SDK](node-sdk.md) cover developer APIs and wire details; this page stays at the operational level.
 
 ## Host sessions over WebSocket
 
@@ -58,24 +56,6 @@ Then attach locally:
 tau attach ws://127.0.0.1:8787
 ```
 
-## Attach through stdio and SSH
-
-Anything after `--` is launched as a local child process and must speak Tau’s session protocol over stdin and stdout. SSH makes that child a remote `tau rpc` process:
-
-```sh
-tau attach -- ssh dev@buildbox.example tau rpc
-```
-
-A login shell or project-specific host configuration can be selected in the remote command:
-
-```sh
-tau attach -- ssh dev@buildbox.example 'cd /srv/tau-host && tau rpc'
-```
-
-The remote process’s stdin and stdout are protocol traffic. Shell startup files and wrapper scripts must not print banners to stdout. Put diagnostics on stderr.
-
-This is a one-shot host. When the TUI exits or the transport fails, the local child is terminated, `tau rpc` shuts down its host, active work is interrupted, and durable state is recovered on the next process. Do not use this shape when work must continue through client disconnects; run `tau serve` instead.
-
 ## List, select, create, or attach
 
 Without `--session` or `--new`, `tau attach` asks the host for its session list and opens an interactive selector:
@@ -94,14 +74,6 @@ tau attach \
   ws://127.0.0.1:8787
 ```
 
-The equivalent SSH form is:
-
-```sh
-tau attach \
-  --session 0195d6e4-4cf9-7f44-a2d8-f8f7f49ee9d3 \
-  -- ssh dev@buildbox.example tau rpc
-```
-
 Create a new session with an absolute cwd in the selected execution environment:
 
 ```sh
@@ -111,15 +83,6 @@ tau attach \
   ws://127.0.0.1:8787
 ```
 
-For stdio/SSH:
-
-```sh
-tau attach \
-  --new \
-  --cwd /srv/workspaces/tau \
-  -- ssh dev@buildbox.example tau rpc
-```
-
 For the default `local` execution kind, this path is on the host machine, not the attaching machine. It must already be a usable directory with the desired repository or workspace. Tau creates the session, not the directory or repository.
 
 Remote `--new` supplies the conventional creation attribute `source: "tui"`. It does not infer repository metadata by inspecting the remote cwd. Clients that need repository provenance should create through the SDK or protocol and provide complete immutable attributes. See [sessions](sessions.md).
@@ -215,7 +178,7 @@ Different changes have different owners:
 | Effective model `apiKeys` in execution-environment or session configuration | Wait for idle, then run `/reload`; new sessions also resolve the current values. |
 | Managed Codex auth changed with `tau auth` | No host restart; auth storage is read again on later credential resolutions. |
 | Attaching themes, diff launcher, speech config, or configured client tools | Restart `tau attach`. |
-| Host process environment variables, history target, WebSocket listener, Cloudflare bridge, Fly API target, or host startup flags | Restart `tau serve` or the `tau rpc` process. |
+| Host process environment variables, history target, WebSocket listener, Cloudflare bridge, Fly API target, or host startup flags | Restart `tau serve`. |
 | Host Tau package, built-in tools, protocol, session recovery code, or built-in documentation | Upgrade and restart the host. |
 | TUI package, keybindings, rendering, local speech, or client-tool implementation | Upgrade and restart the attaching client. |
 
@@ -227,8 +190,6 @@ A WebSocket connection observes a hosted session; it does not own or delete it.
 
 A clean `tau serve` shutdown interrupts active work, persists live sessions, and closes clients. On restart, the host lists sessions whose execution environments it can restore. Recovery returns sessions idle, drops pending queued and steering messages, discards live subagents, and changes an active persistent goal to blocked. Use `/goal resume` only after checking why the host stopped.
 
-A stdio/SSH connection is different because its RPC process is the host. Closing the connection ends that process. The session remains stored under the remote host user’s `~/.config/tau/sessions` and can be observed by a later `tau rpc` process using the same home and compatible resolver configuration.
-
 ## Use multiple observers carefully
 
 Multiple WebSocket clients can observe the same live session and receive the same committed updates and pending-message state. They can also submit, queue, steer, interrupt, or mutate that session, so coordinate human or automation ownership rather than treating observers as read-only.
@@ -265,10 +226,6 @@ Do not edit the session JSON to change environment identity. Restore the owning
 
 Verify that server and client use the same token and that a reverse proxy preserves the WebSocket request path and query string. `TAU_WS_AUTH_TOKEN` can silently supply either side, so inspect the environment as well as command-line flags. Do not print the token in shared logs.
 
-### SSH attachment fails before the TUI opens
-
-Run the remote command directly and confirm that `tau rpc` is installed and can start. Protocol stdout must contain only NDJSON. Login banners, shell startup output, or wrapper diagnostics on stdout corrupt the transport; redirect them to stderr or remove them.
-
 ### A reconnect shows an interrupted turn
 
-A client disconnect alone does not stop a WebSocket-hosted turn, but server shutdown does. Stdio/SSH attachment shutdown also ends its host. Review the last assistant and tool states, verify the execution environment with `!!pwd` and `!!git status --short`, then retry or resume a blocked goal intentionally. [Sessions](sessions.md) explains recovery and safe verification.
+A client disconnect alone does not stop a WebSocket-hosted turn, but server shutdown does. Review the last assistant and tool states, verify the execution environment with `!!pwd` and `!!git status --short`, then retry or resume a blocked goal intentionally. [Sessions](sessions.md) explains recovery and safe verification.