@markusylisiurunen/tau 0.3.82 → 0.3.83

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

@@ -1,18 +1,18 @@
 # 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 WebSocket. The important boundaries are who owns credentials and persistence and where agent-visible commands run.
+In a remote session, the terminal stays on your machine while the session host and execution environment run elsewhere. `tau attach` is the same TUI, connected over WebSocket. What changes is which machine holds credentials and saved sessions, and where the agent's commands run.
 
 ## Choose the connection shape
 
-Use the smallest shape that matches the lifecycle you need.
+Choose the simplest setup that matches how long the host should live.
 
-| Shape | Best for | Lifetime and ownership |
+| Setup | 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. |
 | 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` 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.
+Use `tau serve` for remote TUI and SDK connections. To rely on SSH for security, keep it on loopback and connect through an SSH tunnel. The [session protocol](session-protocol.md) and [Node SDK](node-sdk.md) cover the developer APIs and wire format; this page covers operation.
 
 ## Host sessions over WebSocket
 
@@ -22,7 +22,7 @@ Start a server on the host:
 tau serve
 ```
 
-The default listener is `127.0.0.1:8787`. This is suitable for local clients or a reverse proxy on the same machine. To listen on another interface, set it explicitly and require a strong token:
+By default the server listens on `127.0.0.1:8787`, which suits local clients or a reverse proxy on the same machine. To listen on another interface, set it explicitly and require a strong token:
 
 ```sh
 export TAU_WS_AUTH_TOKEN="$(openssl rand -hex 32)"
@@ -36,15 +36,15 @@ export TAU_WS_AUTH_TOKEN='the-same-token'
 tau attach ws://buildbox.example:8787
 ```
 
-`tau attach` uses `TAU_WS_AUTH_TOKEN` when `--auth-token` is absent. An explicit form is also valid:
+`tau attach` uses `TAU_WS_AUTH_TOKEN` when `--auth-token` is not given. You can also pass the token explicitly:
 
 ```sh
 tau attach --auth-token "$TAU_WS_AUTH_TOKEN" ws://buildbox.example:8787
 ```
 
-A server token authorizes full access to hosted sessions. Without `--auth-token` or `TAU_WS_AUTH_TOKEN`, the listener is unauthenticated. Tau’s server terminates plain WebSocket traffic and does not accept certificate options. On an untrusted network, put it behind a trusted TLS reverse proxy and attach with `wss://`, or keep it bound to loopback and use an SSH tunnel. Treat proxy logs and WebSocket handshake metadata as sensitive because the authentication token is carried during connection setup.
+The token gives full access to all hosted sessions. Without `--auth-token` or `TAU_WS_AUTH_TOKEN`, the server has no authentication. Tau serves plain WebSocket and has no TLS settings. On an untrusted network, put it behind a trusted TLS reverse proxy and attach with `wss://`, or keep it on loopback and use an SSH tunnel. The token is sent when the connection is set up, so treat proxy logs and WebSocket handshake data as sensitive.
 
-A typical tunnel keeps Tau bound to loopback:
+A typical tunnel, with Tau on loopback:
 
 ```sh
 ssh -N -L 8787:127.0.0.1:8787 dev@buildbox.example
@@ -64,9 +64,9 @@ Without `--session` or `--new`, `tau attach` asks the host for its session list
 tau attach ws://127.0.0.1:8787
 ```
 
-The selector shows each session id and whether it is currently idle or running. It can also create a session. If stdin or stdout is not a TTY, selection is unavailable, so specify `--session` or `--new`.
+The selector shows each session ID and whether it is idle or running, and can also create a session. It needs a terminal: if stdin or stdout is not a TTY, pass `--session` or `--new`.
 
-Attach directly when the session id is known:
+If you know the session ID, attach directly:
 
 ```sh
 tau attach \
@@ -74,7 +74,7 @@ tau attach \
   ws://127.0.0.1:8787
 ```
 
-Create a new session with an absolute cwd in the selected execution environment:
+To create a new session, give an absolute `--cwd` in the chosen execution environment:
 
 ```sh
 tau attach \
@@ -83,15 +83,15 @@ tau attach \
   ws://127.0.0.1:8787
 ```
 
-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.
+With the default `local` execution kind, this path is on the host machine, not the attaching machine. The directory must already exist and contain the repository or workspace you want. Tau creates only 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).
+A remote `--new` sets the creation attribute `source: "tui"`. It does not look at the remote directory to fill in repository information. Clients that need it should create sessions through the SDK or protocol and send complete attributes. See [sessions](sessions.md).
 
-`tau attach` does not accept the normal local startup persona flags. Select the server’s default at host startup, for example `tau serve --persona opus-5.5-coder`, or switch the newly created session with `/persona:<id>` after attaching.
+`tau attach` does not accept the persona flags of local startup. Set the server's default when starting the host, for example `tau serve --persona opus-5.5-coder`, or switch the new session with `/persona:<id>` after attaching.
 
 ## Select an execution environment
 
-A session can use a local host directory or an already-provisioned Fly Sprite. In all cases, the execution cwd is an absolute path inside that environment.
+A session can use a directory on the host or an existing Fly Sprite. Either way, the working directory is an absolute path inside that environment.
 
 ### Host-local directory
 
@@ -101,11 +101,11 @@ A session can use a local host directory or an already-provisioned Fly Sprite. I
 tau attach --new --cwd /srv/workspaces/tau ws://host.example:8787
 ```
 
-The host process executes agent-visible filesystem and command operations on its own machine. Tau does not clone, pull, or provision a repository.
+The agent's file operations and commands run on the host machine. Tau does not clone, pull, or set up a repository.
 
 ### Fly Sprite
 
-The host must already have a connection configured in `flySprites`, and the Sprite must already exist:
+The host must have a `flySprites` connection configured, and the Sprite must already exist:
 
 ```sh
 tau attach \
@@ -118,18 +118,18 @@ tau attach \
 
 `--fly-sprite` names an existing Sprite. Tau does not provision it or prepare its repository.
 
-Bridge URLs, API targets, home paths, and credential environment variables are host-owned [configuration](configuration.md). Session creation resolves Tau project configuration and content from the execution cwd through the selected environment. The execution environment itself remains a generic filesystem and process target; it does not own Tau’s configuration precedence or session policy.
+The Sprite API URL, home path, and token are host [configuration](configuration.md). When the session is created, Tau reads project configuration and content from the working directory inside the Sprite.
 
 ## Keep the ownership boundaries clear
 
-An attached session spans three logical machines even when two happen to share one operating system.
+An attached session involves three separate parts, even when two of them run on the same machine.
 
 ### The attaching client owns
 
 - terminal rendering, editor drafts, clipboard operations, and local notifications
 - loaded themes and `defaultTheme`
 - `/listen`, `/speak`, and their local credentials and OS commands
-- the built-in or configured diff-tool process
+- the built-in diff tool process
 - configured command-backed client-tool processes
 - the client’s Tau binary and TUI behavior
 
@@ -138,7 +138,7 @@ An attached session spans three logical machines even when two happen to share o
 - session orchestration, persistence, and recovery
 - provider credential resolution and model execution
 - WebSocket authentication and listener lifetime
-- execution-environment resolver definitions and credentials
+- hosted execution environment settings and credentials
 - pending input while the session remains live
 - the host’s Tau binary and built-in agent documentation
 
@@ -149,66 +149,66 @@ An attached session spans three logical machines even when two happen to share o
 - command execution, platform, PATH, and runtime dependencies
 - automatic-compaction archives and other target-side temporary files
 
-This is why changing a host’s theme selection does not affect a remote TUI, why `!git status` runs against the execution environment, and why the built-in diff review tool opens on the attaching machine. [Ownership and scope](ownership-and-scope.md) applies the same model across Tau.
+That is why a host's theme setting does not affect a remote TUI, why `!git status` runs in the execution environment, and why the built-in diff review tool opens on the attaching machine. [Ownership and scope](ownership-and-scope.md) applies the same model across Tau.
 
 ## Reload or restart the correct process
 
-Different changes have different owners:
+Each kind of change belongs to a different process:
 
 | Change | Action |
 | --- | --- |
 | Project config, personas, prompts, skills, or AGENTS.md in the execution environment | Wait for idle, then run `/reload`. |
 | Global model `apiKeys` on the host | Restart the host. |
-| Managed Codex auth changed with `tau auth` | No host restart; auth storage is read again on later credential resolutions. |
+| Codex auth changed with `tau auth` | No restart needed; every new request reads auth storage again. |
 | Attaching themes, speech config, or configured client tools | Restart `tau attach`. |
-| Host process environment variables, history target, WebSocket listener, Fly API target, or host startup flags | Restart `tau serve`. |
+| Host environment variables, history target, WebSocket listener, Fly Sprite connection, 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. |
 
-`/reload` is a session operation. It asks the host to resolve session-owned content, from the execution environment and does not reload either process’s executable code or environment. Managed Codex auth storage is separate and is read again on later credential resolutions. For a long-running WebSocket host, restarting only the client cannot update the model-facing built-in docs or host tools. For an old client against a new host, restarting only the host cannot update local TUI behavior. See [credentials](credentials.md) for complete precedence and apply boundaries.
+`/reload` acts on the session. The host reads session content again from the execution environment. It does not reload either process's code or environment. For a long-running WebSocket host, restarting only the client does not update the host's tools or the documentation its agent reads. For an old client attached to a new host, restarting only the host does not update the TUI. See [credentials](credentials.md) for complete precedence and apply boundaries.
 
 ## Reconnect and observe safely
 
-A WebSocket connection observes a hosted session; it does not own or delete its durable state. After the last observer disconnects, the host unloads an idle live runtime while retaining its persisted snapshot. If a client disconnects while work runs, the host keeps working and unloads the runtime only after that work settles. Reattach with the same session id to recover the current persisted state and continue receiving updates.
+A WebSocket connection observes a hosted session. It does not own the saved session and cannot delete it. After the last client disconnects, the host unloads an idle session from memory and keeps it saved. If a client disconnects while work is running, the host keeps working and unloads the session only after the work finishes. Reattach with the same session ID to get the current state and continue receiving updates.
 
-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, and discards live subagents.
+A clean `tau serve` shutdown interrupts running work, saves live sessions, and closes clients. After a restart, the host lists the sessions whose execution environments it can reconnect. Recovered sessions come back idle, without queued or steering messages, and without subagents.
 
 ## 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.
+Several WebSocket clients can observe the same live session and receive the same updates and pending messages. Every one of them can also submit, queue, steer, interrupt, or change the session. None is read-only, so agree on who, or which automation, is in charge.
 
-Each ordinary TUI advertises client-owned `diff_review` and `prefill_input` tools plus enabled configured client tools. Only one observing client may advertise a given client-tool name for a session. Start additional observers with:
+Each TUI offers its `diff_review` and `prefill_input` tools plus its enabled configured client tools. Only one client may offer a given tool name in a session. Start additional clients with:
 
 ```sh
 tau attach --no-client-tools --session 0195d6e4-4cf9-7f44-a2d8-f8f7f49ee9d3 ws://host.example:8787
 ```
 
-The host captures the available client-tool set when a turn starts. If the owning client detaches before a delegated call, that tool becomes unavailable; an active delegated call is cancelled. Client tools are not recovered after host restart until a client advertising them attaches again. See [client tools](client-tools.md).
+A turn keeps the client tools that were available when it started. If the owning client detaches, its tools become unavailable and its running calls are cancelled. After a host restart, client tools return only when a client that offers them attaches again. See [client tools](client-tools.md).
 
 ## Troubleshoot connection and recovery
 
 ### The client reports an unsupported protocol version
 
-Tau’s current session protocol uses an exact version, not a compatibility negotiation. Upgrade the host and attaching client to the same Tau release, restart both processes, and reconnect. The host-facing agent uses tools and documentation from the host installation, while TUI behavior comes from the client installation.
+Client and host must use exactly the same protocol version; there is no negotiation. Upgrade both to the same Tau release, restart both, and reconnect. The agent's tools and documentation come from the host's installation, and TUI behavior comes from the client's.
 
-Avoid downgrading a host that has already written sessions with a newer storage format. Newer Tau versions migrate supported older session documents during normal recovery; older versions are not expected to understand newer documents.
+Do not downgrade a host that has already saved sessions in a newer format. Newer Tau versions upgrade supported older sessions when recovering them, but older versions cannot read newer sessions.
 
 ### A session is missing from the selector
 
-The host lists only stored sessions whose execution-environment kind it can currently restore. Confirm that:
+The host lists only saved sessions whose execution environment it can reconnect. Confirm that:
 
 - the connection uses the same host user and home directory as the original process
-- the Fly API id still exists in host configuration
+- the Fly Sprite connection is still configured on the host
 - host credentials are available to the restarted process
 - the target Sprite or local directory still exists
 - the session was created on this host rather than another machine with a different store
 
-Do not edit the session JSON to change environment identity. Restore the owning configuration or target instead.
+Do not edit the session files to change the environment. Restore the configuration or the target instead.
 
 ### WebSocket attachment is unauthorized
 
-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.
+Check that server and client use the same token, and that any reverse proxy passes through the WebSocket request path and query string. `TAU_WS_AUTH_TOKEN` can supply the token on either side without you noticing, so check the environment as well as the flags. Do not print the token into shared logs.
 
 ### A reconnect shows an interrupted turn
 
-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 intentionally. [Sessions](sessions.md) explains recovery and safe verification.
+A client disconnecting does not stop a turn on a WebSocket host, but a server shutdown does. Look at the last assistant message and tool results, check the execution environment with `!!pwd` and `!!git status --short`, then retry if you mean to. [Sessions](sessions.md) explains recovery and how to check a recovered session.

package/dist/core/static/tau_docs/sdk-diff-review.md

@@ -1,6 +1,6 @@
 # SDK browser diff review
 
-`startTauSdkDiffReview()` starts Tau's built-in browser review UI for an observed SDK session without requiring the TUI or opening a browser. It captures the selected diff through the session execution environment, creates the same review-scoped ephemeral agent context used by `/diff`, eagerly prepares shared review context and the reviewer guide, and binds an HTTP server on loopback by default.
+`startTauSdkDiffReview()` starts Tau's built-in browser review UI for an observed SDK session, without the TUI and without opening a browser. It takes the diff in the session's execution environment, creates the same review agent context that `/diff` uses, starts preparing the review context and reviewer guide right away, and starts an HTTP server, on loopback by default.
 
 ```ts
 import { startTauSdkDiffReview } from "@markusylisiurunen/tau/sdk";
@@ -23,15 +23,19 @@ try {
 }
 ```
 
-The source may instead be `{ kind: "patch_files", patchFiles, scopeLabel }`. Paths and Git arguments belong to the session execution environment. Captured snapshot patches are limited to 16 MiB; narrow the Git arguments or patch-file selection when a larger scope is rejected. A plain working-tree snapshot includes non-binary untracked files up to 4 MiB each within that aggregate limit. Optional `host`, `port`, and `signal` fields control the client-owned HTTP process and startup cancellation.
+The source can instead be `{ kind: "patch_files", patchFiles, scopeLabel }`. Paths and Git arguments refer to the session's execution environment. A snapshot's patch can be at most 16 MiB; narrow the Git arguments or patch files if a larger diff is rejected. A plain working-tree snapshot includes non-binary untracked files of up to 4 MiB each, within that total. The optional `host`, `port`, and `signal` fields set where the HTTP server listens and let you cancel startup.
 
 ## Routing and lifecycle
 
-The returned `url` is local to the SDK client machine and ends with a trailing slash. An embedding service may expose it through an authenticated or capability-protected reverse proxy. The browser app uses paths relative to its document URL, so it can be mounted below a route prefix; the external route URL must also end with a trailing slash. The embedding service owns public authentication, routing, retention, and recovery.
+The returned `url` is on the SDK client's machine and ends with a slash. Your service can expose it through a reverse proxy that handles authentication or access links. The browser app uses relative paths, so it works under a path prefix, as long as the public URL also ends with a slash. Your service is responsible for public authentication, routing, retention, and recovery.
 
-The HTTP server does not provide authentication. The default loopback listener is suitable for a same-machine proxy. An explicitly configured non-loopback `host` is safe only within a trusted network boundary; otherwise, keep the listener on loopback and expose it through a protected proxy.
+The HTTP server has no authentication. The default loopback address suits a proxy on the same machine. Set a non-loopback `host` only inside a trusted network; otherwise keep it on loopback behind a protected proxy.
 
-Always call `close()` when the review is no longer available. This cancels the review if needed, closes the ephemeral agent context, and stops the HTTP server. Submit in the built-in UI first opens the exact return-text preview, where included feedback can be excluded and the full review can be copied. Approve returns immediately when no feedback remains; if feedback appears while approval is being checked, the preview opens instead. Returned review Markdown is self-contained: it identifies the reviewed scope, presents change-level comments with their relevant context, and explains the participants and roles in unresolved review discussions. `result` resolves once with the returned outcome or cancellation reason. Returned results distinguish an approval from submitted comments without sentinel review text:
+Always call `close()` when the review should no longer be available. It cancels the review if needed, closes the review agent context, and stops the HTTP server.
+
+In the UI, **Submit** first opens a preview of the exact text to be returned, where the reviewer can exclude feedback and copy the full review. **Approve** returns right away when no feedback remains; if feedback appears while approval is being checked, the preview opens instead. The returned Markdown stands on its own: it names the reviewed scope, gives change-level comments their context, and explains who took part in each unresolved discussion and in what role.
+
+`result` resolves once, with the outcome or the reason for cancellation. An approval and a review with comments are separate outcomes, so you never need to check for placeholder text:
 
 ```ts
 const result = await review.result;
@@ -44,7 +48,7 @@ if (result.status === "returned" && result.outcome === "approved") {
 
 ## Durable review state
 
-Review annotations, transcripts, guide content and comments, and UI preferences are in memory by default. Supply a client-owned `storage` adapter to preserve them:
+By default, review annotations, transcripts, guide content and comments, and UI preferences are kept only in memory. Pass a `storage` adapter to save them:
 
 ```ts
 const review = await startTauSdkDiffReview({
@@ -57,15 +61,15 @@ const review = await startTauSdkDiffReview({
 });
 ```
 
-The stored document is an opaque, size-bounded, versioned Tau value. The embedding application should store it without inspecting or modifying it. Tau persists durable mutations before returning HTTP success and rolls a mutation back if storage fails.
+The stored document is a versioned Tau value of limited size. Store it as is, without reading or changing it. Tau saves each change before the HTTP request succeeds, and undoes the change if saving fails.
 
-Restoration requires the stored document to be valid, supported by the running Tau version, and bound to the same captured diff. The binding includes the patch, file metadata, diff command and arguments, repository root, and working directory. Invalid, unsupported, or mismatched state causes `startTauSdkDiffReview()` to reject instead of silently starting with empty state. The embedding application must decide whether to retain the failed document or discard or replace it before retrying startup.
+To restore, the stored document must be valid, supported by the running Tau version, and made for the same diff. "The same diff" covers the patch, file metadata, diff command and arguments, repository root, and working directory. If the state is invalid, unsupported, or for a different diff, `startTauSdkDiffReview()` rejects, instead of quietly starting empty. Your application then decides whether to keep, discard, or replace the document before trying again.
 
-Durable review state excludes loading indicators and ephemeral agent thread identifiers. After restoration, the first follow-up recreates an agent thread from a fresh bootstrap and supplies the stored conversation transcript.
+Saved state does not include loading indicators or review agent thread IDs. After a restore, the first follow-up question starts a new agent thread and gives it the saved conversation transcript.
 
 ## Durable submission
 
-Use `onSubmit` when review acceptance must be durable before the browser sees success:
+Use `onSubmit` when the submitted review must be saved before the browser is told it succeeded:
 
 ```ts
 const review = await startTauSdkDiffReview({
@@ -83,6 +87,6 @@ const review = await startTauSdkDiffReview({
 
 An approved submission has `outcome: "approved"` and no `review` field. A commented submission has `outcome: "commented"` and a required `review` field. Both include `diffCommand` and `reviewedFiles`.
 
-Tau permits only one in-flight or successful submission per running diff-review server. It awaits `onSubmit` before returning HTTP success and closing the review. If the callback fails, the submission remains available for retry.
+Each running review server allows only one submission at a time, and none after one succeeds. Tau waits for `onSubmit` to finish before reporting success and closing the review. If the callback fails, the reviewer can submit again.
 
-The embedding application remains responsible for a durable exactly-once transition, deciding whether a submitted review may be reconstructed, and retaining or removing stored state. A typical acceptance callback atomically marks its own review record submitted and enqueues downstream work.
+Your application is responsible for recording the submission exactly once, for deciding whether a submitted review may be opened again, and for keeping or deleting stored state. A typical callback marks its own review record as submitted and queues follow-up work in one transaction.