@markusylisiurunen/tau 0.3.49 → 0.3.50

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

@@ -0,0 +1,198 @@
+# Models
+
+A model definition tells Tau how to call a provider model and how to reason about its capabilities, limits, and cost. A persona selects one provider and model, while credentials authorize the resulting request. Keeping those layers separate makes it possible to update model metadata without rewriting persona behavior.
+
+Tau ships a versioned catalog and lets the execution environment overlay it with `models.json`. The effective catalog for a session therefore depends on both the installed Tau version and the session working directory.
+
+## Providers, models, and personas
+
+A **provider** owns authentication and one or more request APIs. A **model** is addressed by a provider ID and an exact model ID, such as `openai/gpt-5.6-sol`. A [persona](personas.md) binds that pair to a system prompt, settings, tools, skills, and subagents.
+
+The bundled catalog comes from Tau's model runtime and Tau-owned extensions. It supplies known provider IDs, bundled model IDs, request API names, endpoints, capability flags, token limits, and pricing. Bundled does not mean currently usable: a provider may still lack credentials, an account may not expose a model, or a configured endpoint may reject it. See [credentials](credentials.md).
+
+Tau applies `models.json` overlays before resolving built-in or custom personas. A bundled persona therefore uses overridden metadata when its provider and model are patched.
+
+## Where `models.json` is loaded
+
+Tau uses the same level discovery as runtime configuration:
+
+- `~/.config/tau/models.json` is the global overlay when the session `cwd` is inside the execution environment's home.
+- Every ancestor `.tau/models.json` is a project overlay.
+- When `cwd` is inside home, project discovery stops at home. Otherwise it continues to the filesystem root.
+
+Merge order is bundled catalog, global overlay, then project overlays from the farthest parent to the nearest. The nearest value wins for the same field.
+
+These paths belong to the execution environment. In an attached session, edit `models.json` on the session target, not on the TUI machine. The general path rules and reload boundary are covered in [configuration](configuration.md).
+
+## File shape
+
+A `models.json` file has one required `providers` object. Provider keys are normalized to lowercase and must already be known to the bundled catalog.
+
+```json
+{
+  "providers": {
+    "openai": {
+      "baseUrl": "https://models.internal.example/v1",
+      "headers": {
+        "x-tenant": "payments"
+      },
+      "models": [
+        {
+          "id": "gpt-5.6-sol",
+          "contextWindow": 300000,
+          "maxTokens": 48000
+        },
+        {
+          "id": "gpt-5.7-preview",
+          "name": "GPT-5.7 preview",
+          "reasoning": true,
+          "input": ["text", "image"],
+          "contextWindow": 200000,
+          "maxTokens": 32000,
+          "cost": {
+            "input": 3,
+            "output": 18,
+            "cacheRead": 0.3,
+            "cacheWrite": 3.75
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+Unknown object fields are discarded. A malformed JSON document or invalid schema rejects that whole file and produces a configuration warning. An unknown provider produces a warning for that provider entry; Tau can still process valid entries from the same file.
+
+## Provider fields
+
+A provider entry accepts these optional defaults:
+
+| Field | Contract |
+| --- | --- |
+| `api` | Non-empty request API name. It must correspond to an API implementation available in the installed model runtime. |
+| `baseUrl` | Non-empty endpoint URL string used for provider models unless a model overrides it. |
+| `headers` | String-to-string map merged into model request headers. |
+| `compat` | Provider-specific compatibility value. Objects shallow-merge; another JSON value replaces the prior value. |
+| `models` | Array of model patches or definitions. |
+
+Provider defaults apply to every effective model for that provider. Across levels, `headers` merge by key and `compat` objects merge one level deep. Other provider fields use the nearest defined value.
+
+Headers are literal strings, not environment references. Prefer the mechanisms in [credentials](credentials.md) for secrets. If a proxy requires a routing header, keep the containing file private and remember that a project overlay may be committed.
+
+## Model fields
+
+Each model entry requires `id`. Its value is trimmed but otherwise exact and case-sensitive. All remaining fields are optional patches:
+
+| Field | Contract |
+| --- | --- |
+| `id` | Required non-empty model ID. It forms the key with the normalized provider ID. |
+| `name` | Non-empty display name. |
+| `api` | Non-empty request API name, overriding the provider or bundled value. |
+| `baseUrl` | Non-empty endpoint string, overriding the provider or bundled value. |
+| `headers` | String-to-string map. Model headers merge over provider headers by key. |
+| `reasoning` | Boolean indicating whether the model supports reasoning controls. |
+| `input` | Array containing `text`, `image`, or both. The array replaces the prior value. |
+| `contextWindow` | Positive integer context-window size in tokens. Tau uses it for context pressure and compaction decisions. |
+| `maxTokens` | Positive integer maximum output-token setting. |
+| `cost` | Partial rates object described below. Fields merge into prior cost metadata. |
+| `compat` | Provider-adapter compatibility value. Objects shallow-merge; another JSON value replaces the prior value. |
+
+A model-level value always overrides the effective provider-level value, even when the model patch came from a broader configuration level. Among model patches for the same provider and ID, the nearest level wins field by field. `headers`, object `compat`, and individual `cost` fields merge; `input` and `cost.tiers` replace their previous arrays.
+
+`compat` is intentionally adapter-specific and is not structurally validated by Tau. Use only keys understood by the selected API implementation. An accepted but unsupported `api` or `compat` value can still fail when a request is made.
+
+## Cost and tiered pricing
+
+Base cost rates are US dollars per million tokens:
+
+```json
+{
+  "cost": {
+    "input": 2,
+    "output": 12,
+    "cacheRead": 0.2,
+    "cacheWrite": 2.5
+  }
+}
+```
+
+Each base field is optional in a patch because omitted values inherit. For a newly synthesized model, inherited provider defaults remain unless replaced.
+
+`cost.tiers` is an array of complete request-wide rates. Every tier requires all five fields:
+
+```json
+{
+  "cost": {
+    "tiers": [
+      {
+        "inputTokensAbove": 272000,
+        "input": 4,
+        "output": 18,
+        "cacheRead": 0.4,
+        "cacheWrite": 5
+      }
+    ]
+  }
+}
+```
+
+Tau totals input, cache-read, and cache-write usage for the request. When that total is greater than a tier's `inputTokensAbove`, the entire request uses that tier's rates. If several thresholds match, the highest threshold wins. The threshold comparison is strict, so a total exactly equal to the threshold stays on the lower rate.
+
+Keep pricing metadata accurate. Tau uses it for displayed and recorded cost, not only documentation.
+
+## Unbundled model IDs
+
+Custom personas and subagent launch allowlists may name an unbundled model ID when the provider is known. Tau handles it in one of two ways:
+
+1. If merged `models.json` contains the provider and ID, Tau derives a model from that provider's bundled template and applies provider and model patches.
+2. Otherwise, general model resolution synthesizes the requested ID from that provider's bundled template and applies provider-level patches.
+
+This supports newly released IDs before Tau bundles them. It does not discover capabilities or prices from the provider. The synthesized definition inherits the first bundled template for that provider, so explicitly define any differing `api`, endpoint, inputs, reasoning support, token limits, compatibility settings, and cost.
+
+A completely new provider cannot be introduced through `models.json`; provider keys must be known to the installed runtime. Also note that `modelSystemNotices` requires a **configured** model. An unbundled ID used only through synthesis must first be listed in `models.json` before a notice can target it.
+
+## Model system notices
+
+`modelSystemNotices` belongs in `config.json`, but its keys are validated against the merged configured model catalog, so it is closely tied to model configuration:
+
+```json
+{
+  "modelSystemNotices": {
+    "openai/gpt-5.7-preview": "Use the preview endpoint only for non-production analysis."
+  }
+}
+```
+
+Keys use exact `<provider>/<model>` form. Provider IDs must be known. Model IDs are case-sensitive and must be bundled or listed in layered `models.json`. Values must be non-empty strings. The map merges by key across configuration levels, with the nearest notice winning.
+
+When Tau commits input for a main agent or subagent using that model, it prepends the notice as a hidden model-facing system block. The block is persisted with the user message and later compaction sees it as source history. Tau does not add a fresh current notice to maintenance prompts or synthetic compaction messages. Ephemeral agents do not receive model system notices.
+
+Use notices for model-specific operational guidance, not credentials or transient secrets. The notice becomes durable session content.
+
+## Applying and verifying changes
+
+Run `/reload` in an idle TUI session after changing `models.json` or `modelSystemNotices`. Reload resolves runtime content again, reapplies the active persona when its ID still exists, and reports model or configuration warnings. The TUI refuses to reload during an active turn.
+
+For a new local session, this command verifies that the intended persona resolves to the expected provider and model ID without starting the TUI:
+
+```sh
+tau --debug --persona release-coder
+```
+
+Debug output shows effective persona IDs and selected model IDs, not every model metadata field. It also prints the full effective system prompt and project context, so treat its output accordingly. A small real request is the final check for endpoint, API compatibility, model availability, and credentials.
+
+Common warnings and failures include:
+
+- invalid JSON or a missing `providers` object;
+- an unknown provider;
+- an empty model ID, API, endpoint, or name;
+- non-string headers;
+- unsupported values in `input`;
+- non-positive or non-integer token limits;
+- negative cost rates or an incomplete tier;
+- a persona that references a provider with no bundled template;
+- a notice targeting a model that was never bundled or configured; and
+- a syntactically accepted API or compatibility setting that the runtime adapter cannot use.
+
+Warnings identify the exact `models.json` or `config.json` path. In a remote session, that path is in the execution environment. See [troubleshooting](troubleshooting.md) when the edited file and the warning path do not match.

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

@@ -0,0 +1,399 @@
+# 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.
+
+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.
+
+## Install and import
+
+Tau requires Node.js 24 or later.
+
+```sh
+npm install @markusylisiurunen/tau
+```
+
+Import the SDK from its package entry point:
+
+```ts
+import { createTauSdkClient } from "@markusylisiurunen/tau/sdk";
+```
+
+Tau is an ES module package.
+
+## Choose a client
+
+### Own an in-process host
+
+`createTauSdkClient()` creates a local host and connects through an in-process transport:
+
+```ts
+const client = await createTauSdkClient({
+  persona: "gpt-5.6-sol-coder:high",
+});
+```
+
+The host uses the current host user's Tau session store and history database. `cwd` in the client options controls startup configuration for host-wide services and defaults to `process.cwd()`. Each session separately resolves runtime configuration and content from the execution environment and `cwd` passed to `client.sessions.create()`.
+
+The in-process options are:
+
+```ts
+type TauSdkClientOptions = {
+  cwd?: string;
+  persona?: string;
+  reasoning?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+  noAgentContextFiles?: boolean;
+  connectTimeoutMs?: number;
+  initialize?: { client: { name: string; version: string } };
+  clientTools?: TauSdkClientTool[];
+};
+```
+
+`persona`, `reasoning`, and `noAgentContextFiles` configure sessions created by this owned host. `connectTimeoutMs` defaults to 5,000 ms. Default initialization metadata is `{ client: { name: "tau-sdk", version: "1" } }`.
+
+Closing this client also shuts down its host after persisting live sessions.
+
+### Connect to `tau serve`
+
+`createTauSdkWebSocketClient()` connects to a long-running WebSocket host:
+
+```ts
+import { createTauSdkWebSocketClient } from "@markusylisiurunen/tau/sdk";
+
+const client = await createTauSdkWebSocketClient({
+  url: "wss://tau.example.com",
+  authToken: process.env.TAU_WS_AUTH_TOKEN,
+  initialize: {
+    client: { name: "acme-automation", version: "1.0.0" },
+  },
+});
+```
+
+Options include `url`, optional `authToken`, `connectTimeoutMs`, `initialize`, `clientTools`, and an optional `webSocketFactory` for runtimes that need a custom WebSocket implementation. Closing the SDK client closes only its connection. Sessions remain with the server.
+
+WebSocket authentication grants full session access. Deployment and TLS guidance belongs to [remote sessions](remote-sessions.md), and the trust model belongs to [security](security.md).
+
+### 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.
+
+A custom transport implements:
+
+```ts
+type SessionProtocolTransport = {
+  readonly ready: SessionProtocolReadyMessage;
+  connect(initializeParams, timeoutMs): Promise<void>;
+  request(method, params): Promise<unknown>;
+  onDelta(listener): () => void;
+  onEphemeral(listener): () => void;
+  onPendingUserMessages(listener): () => void;
+  onSubagentActivities(listener): () => void;
+  onClientTool(listener): () => void;
+  onFailure(listener): () => void;
+  close(): Promise<void>;
+};
+```
+
+A terminal transport failure must call `onFailure` listeners so the SDK can abort delegated client tools and reject outstanding work.
+
+## Create and run a session
+
+A typical integration creates and automatically observes a session, listens for state, submits work, and closes cleanly:
+
+```ts
+import {
+  TauSessionProtocolResponseError,
+  TauTransportError,
+  createTauSdkClient,
+} from "@markusylisiurunen/tau/sdk";
+
+const client = await createTauSdkClient();
+const session = await client.sessions.create({
+  executionEnvironment: {
+    kind: "local",
+    cwd: process.cwd(),
+  },
+  attributes: {
+    source: "sdk",
+    repository: "github.com/example/atlas",
+  },
+});
+
+const unsubscribe = session.onDelta((delta) => {
+  console.log(delta.sessionId, delta.fromRevision, delta.toRevision);
+});
+
+try {
+  const result = await session.submit("Summarize the current changes.");
+  const snapshot = await session.snapshot();
+  console.log(result.userHistoryEntryId, result.turn.status, snapshot.revision);
+} catch (error) {
+  if (error instanceof TauSessionProtocolResponseError) {
+    console.error(error.code, error.message);
+  } else if (error instanceof TauTransportError) {
+    console.error(error.message);
+  } else {
+    throw error;
+  }
+} finally {
+  unsubscribe();
+  await session.unobserve();
+  await client.close();
+}
+```
+
+`client.sessions.create(input)` sends `session.create`, then observes the new session before resolving. `client.sessions.observe(sessionId)` does the same observation handshake for an existing session. `client.sessions.list()` returns `{ sessionId, lifecycle }` summaries.
+
+Creation requires complete execution-environment input and immutable attributes. The execution `cwd` must be absolute and belongs to the selected environment, not necessarily the SDK process. Cloudflare Sandbox and Fly Sprite sessions refer to already-provisioned targets configured on the host. See [sessions](sessions.md) for creation attributes and [ownership and scope](ownership-and-scope.md) for path ownership.
+
+`session.unobserve()` stops observation and makes that `TauSdkSession` facade terminal. It does not delete the hosted session. `client.close()` is idempotent and closes the whole client.
+
+The connected `TauSdkClient` exposes:
+
+| Member | Purpose |
+| --- | --- |
+| `ready` | The validated server `ready` message and advertised methods. |
+| `sessions.create(input)` | Create, observe, and return a session facade. |
+| `sessions.list()` | List hosted session summaries. |
+| `sessions.observe(sessionId)` | Observe an existing session and return a facade. |
+| `subscribe(listener)` | Receive deltas for every observed session on this connection. |
+| `subscribePendingUserMessages(listener)` | Receive pending-state replacements across observed sessions. |
+| `subscribeSubagentActivities(listener)` | Receive subagent-activity changes across observed sessions. |
+| `subscribeEphemeral(listener)` | Receive best-effort ephemeral events across observed sessions. |
+| `close()` | Close the client and its owned resources. |
+
+Each subscription returns an unsubscribe function.
+
+## Use the session facade
+
+`TauSdkSession.id` is the bound session id. Its methods map directly to protocol operations; the [method reference](session-protocol-methods.md) defines exact results, turn outcomes, busy rules, and mutation behavior.
+
+| SDK method | Purpose |
+| --- | --- |
+| `record(text, options?)` | Append user text without running a turn. |
+| `submit(text, options?)` | Append user text and run an idle session turn. |
+| `queue(text, options?)` | Run now or wait behind active session work. |
+| `steer(text)` | Redirect active model work at a safe boundary. |
+| `cancelPendingMessages()` | Cancel all queued and unapplied steering input. |
+| `retry()` | Run from current history without appending user text. |
+| `exec(command, options?)` | Run an independent login-Bash command in the execution environment. |
+| `sample({ context, options })` | Run isolated inference without mutating the session. |
+| `interrupt()` | Request cancellation of active session work. |
+| `snapshot()` | Read the complete authoritative snapshot. |
+| `startGoal(objective)` | Create and run a persistent autonomous goal. |
+| `resumeGoal()` | Continue a blocked goal. |
+| `clearGoal()` | Clear the current goal and return the updated snapshot. |
+| `setReasoning(reasoning)` | Set reasoning for the next independently started turn. |
+| `setPersona(personaId)` | Change persona and return the updated snapshot. |
+| `resolvePrompt(promptId)` | Load a current prompt body from the execution environment. |
+| `autocompletePaths({ query, limit })` | Request bounded execution-environment path suggestions. |
+| `reload()` | Reload session-owned configuration and content. |
+| `compact(mode, options?)` | Manually compact model context. |
+| `rewindToHistoryEntryId(id)` | Rewind from one user history entry while idle. |
+| `interruptSubagent(subagentId)` | Interrupt one live subagent run. |
+| `createEphemeralContext(options)` | Create a non-persisted host-owned agent context. |
+| `submitEphemeralThread(options)` | Run or continue one ephemeral thread. |
+| `closeEphemeralContext(contextId)` | Close an ephemeral context and its threads. |
+| `unobserve()` | Stop observation and retire this facade. |
+
+`submit`, `queue`, and `record` accept `{ historyEntryId?: string }`. When omitted, Tau generates the user history id. Use `getTauSdkSessionTurnRecord(snapshot, id)` to distinguish unknown, running, and settled accepted turns, or `getTauSdkSessionTurnOutcome(snapshot, id)` when only a settled outcome matters.
+
+### Execute a command
+
+`exec` generates a unique wire-level execution id and supports exact positional arguments, environment overrides other than `HOME`, binary stdin, a command `cwd`, timeout, capture limit, and cancellation signal:
+
+```ts
+const controller = new AbortController();
+const result = await session.exec('exec "$0" "$@"', {
+  args: ["git", "status", "--short"],
+  cwd: "/srv/workspaces/atlas",
+  timeoutMs: 10_000,
+  maxCaptureBytes: 256 * 1024,
+  signal: controller.signal,
+});
+
+console.log(result.exitCode, result.output);
+```
+
+Aborting the signal sends targeted `session.cancelExec` and rejects the SDK call. It does not interrupt turns or other executions. The operation does not enter conversation history.
+
+### Sample a model
+
+`sample` uses the session's active resolved model target and credentials but only the supplied provider-neutral context:
+
+```ts
+const sampled = await session.sample({
+  context: {
+    systemPrompt: "Classify the request in one word.",
+    messages: [
+      {
+        role: "user",
+        content: [{ type: "text", text: "I cannot log in." }],
+        timestamp: Date.now(),
+      },
+    ],
+  },
+  options: { reasoning: "low", maxTokens: 100 },
+});
+
+console.log(sampled.message.content);
+```
+
+The returned complete assistant message can be reused in a later sampling context. Optional tool schemas can produce tool-call content, but Tau does not execute those calls. Sampling does not emit deltas, change snapshot revision or cost, or write conversation history.
+
+## Consume streamed state
+
+The SDK exposes connection-wide subscriptions on `TauSdkClient` and session-filtered subscriptions on `TauSdkSession`. Prefer the session facade unless one component deliberately multiplexes several sessions.
+
+### Snapshot deltas
+
+`session.onDelta(listener)` receives only that session's `TauSdkDelta` messages. The facade buffers deltas received before its first local delta listener and replays them when that listener is attached. Use `applySessionProtocolDelta` against an installed snapshot. On any revision gap or invalid transition, refresh with `session.snapshot()`.
+
+A method that returns an authoritative snapshot, such as reload, compact, rewind, persona change, or goal clearing, lets the facade discard buffered deltas through that revision. Do not also replay stale presentation transitions from those discarded deltas.
+
+### Pending input
+
+`session.pendingUserMessages()` returns a clone of the current full pending-message state. `session.onPendingUserMessages(listener)` immediately emits the current baseline, then newer full replacements. Its revision is independent of the snapshot.
+
+```ts
+const stopPending = session.onPendingUserMessages(({ state }) => {
+  console.log(state.messages.map((message) => [message.mode, message.text]));
+});
+```
+
+Pending input is shared among clients observing the live hosted session and starts empty after recovery.
+
+### Subagent activity
+
+`session.subagentActivities()` returns the current transient activity state. `session.onSubagentActivities(listener)` immediately emits the current agents as `agent.set` changes, then later per-agent replacements and removals.
+
+For a custom accumulator, use `applySessionProtocolSubagentActivitiesMessage`. This channel has its own revision and does not replace durable `snapshot.agents`.
+
+### Ephemeral events
+
+`session.onEphemeral(listener)` receives best-effort footer notices, ephemeral thread progress, and non-recoverable timeline notices. These events are not replayed or included in `session.snapshot()`.
+
+If rendering `timeline.item`, accept only the active epoch and merge by its allocated sequence. Compaction and rewind causes determine which client-local ephemeral items remain valid. The [session protocol](session-protocol.md) gives the application rules.
+
+## Provide client tools
+
+Pass `TauSdkClientTool` entries in `clientTools` when model-facing work must run in the integration process:
+
+```ts
+const client = await createTauSdkClient({
+  clientTools: [
+    {
+      schema: {
+        name: "local_picker",
+        description: "Choose one item from the user's local workspace.",
+        parameters: {
+          type: "object",
+          properties: {},
+          additionalProperties: false,
+        },
+        executionTimeoutMs: 60_000,
+      },
+      execute: async (_args, context) => {
+        context.signal.throwIfAborted();
+        const status = await context.executionEnvironment.exec(
+          "git status --short",
+          {
+            signal: context.signal,
+          },
+        );
+        return status.output || "Working tree is clean.";
+      },
+    },
+  ],
+});
+```
+
+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.
+
+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.
+
+### Build a code-mode tool
+
+`createTauCodeModeClientTool()` wraps a bounded one-shot JavaScript API as an SDK client tool:
+
+```ts
+import {
+  buildTauCodeModeToolDescription,
+  createTauCodeModeClientTool,
+} from "@markusylisiurunen/tau/sdk";
+
+const name = "tickets";
+const tickets = createTauCodeModeClientTool({
+  name,
+  description: buildTauCodeModeToolDescription({
+    name,
+    description: "Read support tickets.",
+  }),
+  documentation: "# Tickets API\n\nUse `tickets.get(id)` to read one ticket.",
+  api: {
+    get: async ([id], { signal }) => ticketClient.get(String(id), { signal }),
+  },
+});
+```
+
+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.
+
+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.
+
+## Cancel and close deliberately
+
+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.
+
+Always close clients in `finally`. Do not continue using a session facade after unobserve or any client after close.
+
+## Handle errors
+
+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.
+
+Listener exceptions are isolated from SDK event delivery. Handle failures inside listeners and keep state application deterministic.
+
+## Use the public types and helpers
+
+The SDK entry point exports the types needed at integration boundaries rather than requiring imports from internal modules:
+
+- `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.
+
+It also exports `applySessionProtocolDelta`, `applySessionProtocolSubagentActivitiesMessage`, the turn-ledger helpers, and user-text projection helpers:
+
+```ts
+import {
+  getTauUserDisplayText,
+  getTauUserModelText,
+  projectTauUserText,
+} from "@markusylisiurunen/tau/sdk";
+```
+
+Use `getTauUserDisplayText` before rendering raw snapshot user text. It removes Tau metadata and leading exact hidden system blocks. `getTauUserModelText` removes Tau metadata while preserving model-facing hidden instructions. `projectTauUserText` returns both views together. These helpers apply only to user messages.