@markusylisiurunen/tau 0.3.47 → 0.3.49

package/README.md

@@ -147,7 +147,7 @@ Session attach renders the authoritative session snapshot, streams recoverable `
 
 The host owns the active transcript as one ordered timeline of messages, tool calls, notices, and maintenance operations. Durable items retain their exact position across reattach; ephemeral transcript notices use the same ordering while attached but are not recovered. Successful compaction starts a new numeric timeline epoch containing the summary and future activity, while rewind removes every item after its selected boundary.
 
-The TUI advertises client tools for diff review, input prefill, and the effective command-backed tools selected from global definitions. `prefill_input` fills only an empty editor and leaves existing draft text unchanged. Pass `--no-client-tools` to `tau` or `tau attach` to advertise no TUI client tools, for example when another TUI attached to the same session already owns them.
+The TUI advertises client tools for diff review, input prefill, and the effective command-backed tools selected from global definitions. The Telegram runner advertises the effective command-backed tools for each session workspace without exposing TUI-only tools. `prefill_input` fills only an empty editor and leaves existing draft text unchanged. Pass `--no-client-tools` to `tau` or `tau attach` to advertise no TUI client tools, for example when another TUI attached to the same session already owns them.
 
 Model `bash` tool calls, `!`/`!!`, `session.exec`, and Tau-controlled command helpers each run in a fresh, non-interactive login Bash belonging to the session execution environment. Tau sets `HOME` to the execution environment home, so Bash reads `/etc/profile` and then the first available user login file (`~/.bash_profile`, `~/.bash_login`, or `~/.profile`). Bash also reads inherited `BASH_ENV` when set; otherwise `.bashrc` is loaded only when the login configuration sources it. Login startup files must be automation-safe: they must not write to stdout or stderr, read stdin, require a TTY, or terminate the shell unexpectedly. Tau does not filter or frame startup output. Commands start from the backend's target-side environment and apply explicit execution-environment overrides; the local backend filters sensitive variables inherited from the Tau host. Node, Git, and other helper executables resolve from the same login-configured `PATH` as model commands. Shell state such as `cd`, exports, aliases, functions, and `nvm use` does not persist between calls.
 
@@ -174,7 +174,7 @@ The runner keeps tool and lifecycle progress quiet: Telegram receives command ac
 
 Telegram DM input supports plain text, voice/audio transcription with the transcript echoed back for verification, and attachment queueing (`image/*`, PDF, `.txt`, `.md`, `.json`, `.csv`, `.yaml`, `.yml`). allowed groups are opt-in via `allowedChatIds`; non-triggering group text/captions, attachments, audio transcripts, and processing errors are buffered as sender-attributed context and the most recent 50 messages since the previous bot-triggering turn are included when a bot mention triggers a turn. group commands accept explicit bot mentions on or around the command, such as `/status@botusername`, `/status @botusername`, or `@botusername /status`.
 
-Telegram config defines `bots`, `projects`, `workspaceRoot`, optional `systemMessage`, and optional `maxSessions`. Projects may describe one repository or compose several repository projects under a generated multi-repo root. Repositories use persistent bare caches at `<workspaceRoot>-repo-cache/<projectId>.git`; active and failed session records and per-chat project preferences are persisted, workspaces survive runner restarts, and unreferenced workspace entries are removed on startup. Tau reconnects preserved active sessions to their corresponding snapshots and reconciles unresolved Telegram requests through the durable turn ledger. Accepted running turns remain interruptible after a lost response, while failed, blocked, or confirmed-unaccepted request notifications remain persisted until Telegram delivery succeeds. Terminal failed records retain the initiating submission diagnostic until the session is closed. When creating or reconstructing a workspace, Telegram starts an optional executable `.tau/scripts/provision` repository hook through the Tau session without blocking chat access; failures are reported while the session remains available. Preserved workspaces skip provisioning on restart. for config details, see [docs/telegram.md](docs/telegram.md).
+Telegram config defines `bots`, `projects`, `workspaceRoot`, optional `systemMessage`, and optional `maxSessions`. Projects may describe one repository, reuse one existing persistent directory across sessions, or compose several repository projects under a generated multi-repo root. Persistent directories must already exist and are never created, provisioned, or removed by Tau. Repositories use persistent bare caches at `<workspaceRoot>-repo-cache/<projectId>.git`; active and failed session records and per-chat project preferences are persisted, workspaces survive runner restarts, and unreferenced managed workspace entries are removed on startup. Tau reconnects preserved active sessions to their corresponding snapshots and reconciles unresolved Telegram requests through the durable turn ledger. Accepted running turns remain interruptible after a lost response, while failed, blocked, or confirmed-unaccepted request notifications remain persisted until Telegram delivery succeeds. Terminal failed records retain the initiating submission diagnostic until the session is closed. When creating or reconstructing a repository workspace, Telegram starts an optional executable `.tau/scripts/provision` hook through the Tau session without blocking chat access; failures are reported while the session remains available. Preserved workspaces skip provisioning on restart. for config details, see [docs/telegram.md](docs/telegram.md).
 
 ## built-in tool commands
 
@@ -559,7 +559,7 @@ model definitions can be extended and overridden through `~/.config/tau/models.j
     {
       "name": "notify",
       "defaultEnabled": true,
-      "description": "Show a desktop notification on the TUI machine.",
+      "description": "Show a desktop notification on the owning client machine.",
       "parameters": {
         "type": "object",
         "properties": { "message": { "type": "string" } },
@@ -635,7 +635,7 @@ tau ships a built-in browser diff review tool as `tau diff-tool`. `/diff` launch
 
 supported built-in diff tool code themes are: `andromeeda`, `aurora-x`, `ayu-dark`, `ayu-mirage`, `catppuccin-frappe`, `catppuccin-macchiato`, `catppuccin-mocha`, `dark-plus`, `dracula`, `dracula-soft`, `everforest-dark`, `github-dark`, `github-dark-default`, `github-dark-dimmed`, `github-dark-high-contrast`, `gruvbox-dark-hard`, `gruvbox-dark-medium`, `gruvbox-dark-soft`, `horizon`, `horizon-bright`, `houston`, `kanagawa-dragon`, `kanagawa-wave`, `laserwave`, `material-theme`, `material-theme-darker`, `material-theme-ocean`, `material-theme-palenight`, `min-dark`, `monokai`, `night-owl`, `nord`, `one-dark-pro`, `plastic`, `poimandres`, `red`, `rose-pine`, `rose-pine-moon`, `slack-dark`, `solarized-dark`, `synthwave-84`, `tokyo-night`, `vesper`, `vitesse-black`, `vitesse-dark`.
 
-`clientTools` defines command-backed model tools that execute on the TUI machine. Because these tools execute local commands when selected by the model, they are accepted only in `~/.config/tau/config.json`; project `.tau/config.json` files cannot define them. Each entry requires `name`, `defaultEnabled`, `description`, an object JSON Schema in `parameters`, and `command`, with optional `args` and positive `executionTimeoutMs`. Relative command paths resolve from home. When no project config selects tools, entries with `defaultEnabled: true` are advertised. A project `.tau/config.json` can set `enabledClientTools` to an exact allowlist of globally defined names; unknown names are ignored, an empty list disables all configured tools, and the most specific project value wins. Configured tools are available in both local `tau` and `tau attach`, and `--no-client-tools` disables them together with the built-in TUI client tools.
+`clientTools` defines command-backed model tools that execute on the owning client machine. Because these tools execute local commands when selected by the model, they are accepted only in `~/.config/tau/config.json`; project `.tau/config.json` files cannot define them. Each entry requires `name`, `defaultEnabled`, `description`, an object JSON Schema in `parameters`, and `command`, with optional `args` and positive `executionTimeoutMs`. Relative command paths resolve from home. When no project config selects tools, entries with `defaultEnabled: true` are advertised. A project `.tau/config.json` can set `enabledClientTools` to an exact allowlist of globally defined names; unknown names are ignored, an empty list disables all configured tools, and the most specific project value wins. Configured tools are available in local `tau`, `tau attach`, and Telegram sessions. `--no-client-tools` disables configured and built-in client tools for TUI clients; Telegram workspaces can disable configured tools with `enabledClientTools: []`.
 
 the `subagents.defaultLaunchModels` field configures allowed `spawn_agent` launch overrides for the built-in `default` sub-agent. values must use `<provider>/<model>:<effort>`.
 
@@ -657,7 +657,7 @@ see [docs/telegram.md](docs/telegram.md) for the config schema, project selectio
 
 ### command client tools
 
-Command client tools extend the standard TUI without modifying Tau. Define them only in `~/.config/tau/config.json`; Tau requires each parameter schema to be an object with root `type: "object"`, trusts the remaining schema contents, advertises the effective tools to the session host, and runs their commands on the machine where `tau` or `tau attach` is running. Every definition must set `defaultEnabled`. Without a workspace selection, only default-enabled tools are advertised.
+Command client tools extend Tau clients without modifying the session host. Define them only in `~/.config/tau/config.json`; Tau requires each parameter schema to be an object with root `type: "object"`, trusts the remaining schema contents, advertises the effective tools to the session host, and runs their commands on the owning TUI or Telegram runner machine. Every definition must set `defaultEnabled`. Without a workspace selection, only default-enabled tools are advertised.
 
 A project or nested directory can select a different exact set without defining executable behavior:
 
@@ -669,13 +669,14 @@ A project or nested directory can select a different exact set without defining
 
 The most specific `.tau/config.json` selection wins. Unknown names are skipped, and `enabledClientTools: []` disables every configured command client tool for that workspace.
 
-For every call, Tau validates the arguments against the configured schema, starts the command directly without a shell, and speaks a version 2 newline-delimited JSON protocol over stdin and stdout. The initial stdin frame contains the invocation:
+For every call, Tau validates the arguments against the configured schema, starts the command directly without a shell, and speaks a version 3 newline-delimited JSON protocol over stdin and stdout. The initial stdin frame contains the invocation:
 
 ```json
 {
-  "version": 2,
+  "version": 3,
   "type": "invoke",
   "sessionId": "session-id",
+  "agentId": "agent-id",
   "callId": "call-id",
   "arguments": { "message": "Build finished" }
 }
@@ -684,12 +685,12 @@ For every call, Tau validates the arguments against the configured schema, start
 Commands may send `exec` frames to run commands in the session execution environment. Tau returns the ordinary `session.exec` result in a matching `exec.result` stdin frame. The command finishes with one stdout result frame:
 
 ```json
-{ "version": 2, "type": "result", "content": "Notification shown." }
+{ "version": 3, "type": "result", "content": "Notification shown." }
 ```
 
-Use `runTauClientToolCommand()` from `@markusylisiurunen/tau/sdk` or `@markusylisiurunen/tau/code-mode` to handle this framing and receive the same `{ sessionId, callId, signal, executionEnvironment }` context as an in-process SDK client tool. The command itself still runs on the TUI machine; only `context.executionEnvironment.exec()` runs through `session.exec` in the session execution environment.
+Use `runTauClientToolCommand()` from `@markusylisiurunen/tau/sdk` or `@markusylisiurunen/tau/code-mode` to handle this framing and receive the same `{ sessionId, agentId, callId, signal, executionEnvironment }` context as an in-process SDK client tool. The command itself runs on the owning TUI or Telegram runner machine; only `context.executionEnvironment.exec()` runs through `session.exec` in the session execution environment.
 
-The result `content` becomes model-visible. A nonzero exit fails the tool using stderr, falling back to stdout when stderr is empty. Tau runs the command from the TUI's current working directory with the TUI process environment unchanged, limits each command-to-TUI protocol frame and total stdout and stderr to 1 MiB, allows at most eight execution requests to remain active while their responses are delivered with stdin backpressure, and terminates the command's process group on cancellation, terminal transport failure, timeout, or excess output. Closing protocol stdin aborts the command helper and its pending execution requests. Process-group termination escalates to `SIGKILL` after two seconds even if the command leader exits first. `executionTimeoutMs` defaults to 60 seconds.
+The result `content` becomes model-visible. A nonzero exit fails the tool using stderr. Tau runs the command from the owning client's current working directory with that client's process environment unchanged. Command stdout is decoded as a bounded NDJSON protocol stream with at most 512 frames and 192 MiB total per invocation; each frame is capped at 24 MiB, `exec` stdin retains the session protocol's 16 MiB decoded limit, and final result content plus stderr are each capped at 1 MiB. Tau allows at most eight execution requests to remain active while their responses are delivered with stdin backpressure, and terminates the command's process group on cancellation, terminal transport failure, timeout, or excess output. Closing protocol stdin aborts the command helper and its pending execution requests. Process-group termination escalates to `SIGKILL` after two seconds even if the command leader exits first. `executionTimeoutMs` defaults to 60 seconds.
 
 ```ts
 #!/usr/bin/env node
@@ -718,7 +719,7 @@ Tau's `@markusylisiurunen/tau/code-mode` export implements this command framing
 }
 ```
 
-The executable owns authenticated clients and explicitly exposes trusted handlers. Handler arguments and results cross a JSON boundary; generated code receives only the declared namespace plus `docs`, `console`, `Date`, and `Math`:
+The executable owns authenticated clients and explicitly exposes trusted handlers. Handler arguments and results cross a JSON boundary; generated code receives the declared namespace, agent-scoped `files`, `docs`, `console`, `Date`, and `Math`:
 
 ```ts
 #!/usr/bin/env node
@@ -736,9 +737,9 @@ await runTauCodeModeCommand({
 });
 ```
 
-Trusted code-mode API handlers receive the command's execution-environment facade in their context and may intentionally expose narrower workspace operations through the declared API. Generated code does not receive an undeclared shell namespace. Tau prepends canonical runtime guidance to the executable's API documentation. The installed runtime therefore documents its actual capabilities, 60-second default timeout, 8,192-token output projection, 128-call total limit, and eight-call concurrency limit without duplicating those details in `config.json`. The optional `buildTauCodeModeToolDescription()` helper produces the recommended progressive-disclosure description, but descriptions are otherwise passed through unchanged.
+Trusted code-mode API handlers receive the command's execution-environment facade in their context and may intentionally expose narrower workspace operations through the declared API. Generated code does not receive an undeclared shell namespace. Its `files.read()`, `files.write()`, `files.list()`, and `files.remove()` methods operate on UTF-8 files in an agent-scoped execution-environment temporary directory. The files are shared across code-mode tools and later calls for that agent, and returned absolute paths are usable by Bash. Names are basenames rather than paths; `files.write()` rejects changes above 128 regular files or 64 MiB total, while Bash-created over-limit contents remain visible and removable. The execution environment's temporary filesystem controls the lifetime, and no scratch metadata enters the session snapshot. Tau prepends canonical runtime guidance to the executable's API documentation. The installed runtime therefore documents its actual capabilities, 60-second default timeout, 8,192-token output projection, 128-call total limit, and eight-call concurrency limit without duplicating those details in `config.json`. The optional `buildTauCodeModeToolDescription()` helper produces the recommended progressive-disclosure description, but descriptions are otherwise passed through unchanged.
 
-Configured names must be unique and cannot replace built-in TUI or host tools. Only one observing client may advertise a given name for a session. `--no-client-tools` disables command client tools together with `diff_review` and `prefill_input`.
+Configured names must be unique and cannot replace host tools or built-ins advertised by the same client. Only one observing client may advertise a given name for a session. `--no-client-tools` disables command client tools together with `diff_review` and `prefill_input` for TUI clients; Telegram workspaces use `enabledClientTools: []` to disable configured tools.
 
 ### diff review tool
 

package/dist/code_mode/command.js

@@ -1,5 +1,5 @@
 import { runTauClientToolCommand } from "../sdk/client_tool_command.js";
-import { executeTauCodeMode, validateTauCodeModeDefinition, } from "./runtime.js";
+import { createTauCodeModeExecutionEnvironmentFiles, executeTauCodeMode, validateTauCodeModeDefinition, } from "./runtime.js";
 export async function runTauCodeModeCommand(definition) {
     validateTauCodeModeDefinition(definition);
     await runTauClientToolCommand(async (args, context) => {
@@ -10,9 +10,11 @@ export async function runTauCodeModeCommand(definition) {
             signal: context.signal,
             invocation: {
                 sessionId: context.sessionId,
+                agentId: context.agentId,
                 callId: context.callId,
             },
             executionEnvironment: context.executionEnvironment,
+            files: createTauCodeModeExecutionEnvironmentFiles(context.agentId, context.executionEnvironment),
         });
     });
 }

package/dist/code_mode/command.js.map

@@ -1 +1 @@
-{"version":3,"file":"command.js","sourceRoot":"","sources":["../../src/code_mode/command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,EACL,kBAAkB,EAElB,6BAA6B,GAC9B,MAAM,cAAc,CAAC;AAEtB,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,UAAiC;IAC3E,6BAA6B,CAAC,UAAU,CAAC,CAAC;IAC1C,MAAM,uBAAuB,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;QACpD,MAAM,IAAI,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;QACtC,OAAO,MAAM,kBAAkB,CAAC;YAC9B,GAAG,UAAU;YACb,IAAI;YACJ,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,UAAU,EAAE;gBACV,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;aACvB;YACD,oBAAoB,EAAE,OAAO,CAAC,oBAAoB;SACnD,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAc;IACxC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IACnE,CAAC;IACD,MAAM,IAAI,GAAG,KAAgC,CAAC;IAC9C,IACE,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;QAC7B,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;QACjB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,MAAM,CAAC,EAC/C,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,8EAA8E,CAAC,CAAC;IAClG,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC;AACnB,CAAC"}
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../../src/code_mode/command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AACxE,OAAO,EACL,0CAA0C,EAC1C,kBAAkB,EAElB,6BAA6B,GAC9B,MAAM,cAAc,CAAC;AAEtB,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,UAAiC;IAC3E,6BAA6B,CAAC,UAAU,CAAC,CAAC;IAC1C,MAAM,uBAAuB,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;QACpD,MAAM,IAAI,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;QACtC,OAAO,MAAM,kBAAkB,CAAC;YAC9B,GAAG,UAAU;YACb,IAAI;YACJ,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,UAAU,EAAE;gBACV,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,MAAM,EAAE,OAAO,CAAC,MAAM;aACvB;YACD,oBAAoB,EAAE,OAAO,CAAC,oBAAoB;YAClD,KAAK,EAAE,0CAA0C,CAC/C,OAAO,CAAC,OAAO,EACf,OAAO,CAAC,oBAAoB,CAC7B;SACF,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAc;IACxC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IACnE,CAAC;IACD,MAAM,IAAI,GAAG,KAAgC,CAAC;IAC9C,IACE,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;QAC7B,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;QACjB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,MAAM,CAAC,EAC/C,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,8EAA8E,CAAC,CAAC;IAClG,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC;AACnB,CAAC"}

package/dist/code_mode/files.d.ts

@@ -0,0 +1,47 @@
+export declare const TAU_CODE_MODE_MAX_FILES = 128;
+export declare const TAU_CODE_MODE_MAX_TOTAL_FILE_BYTES: number;
+export type TauCodeModeFileAdapterResult = {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+};
+export type TauCodeModeFileAdapter = {
+    runNodeScript(script: string, options: {
+        input: string;
+        signal: AbortSignal;
+        maxCaptureBytes: number;
+    }): Promise<TauCodeModeFileAdapterResult>;
+};
+export type TauCodeModeFilesOptions = {
+    agentId: string;
+    adapter: TauCodeModeFileAdapter;
+};
+export type TauCodeModeFileMetadata = {
+    name: string;
+    path: string;
+    bytes: number;
+};
+export type TauCodeModeFileList = {
+    files: TauCodeModeFileMetadata[];
+    totalFiles: number;
+    totalBytes: number;
+};
+export declare function createTauCodeModeFilesApi(options: TauCodeModeFilesOptions): {
+    read: (args: unknown[], context: {
+        signal: AbortSignal;
+    }) => Promise<string>;
+    write: (args: unknown[], context: {
+        signal: AbortSignal;
+    }) => Promise<{
+        path: string;
+        bytes: number;
+    }>;
+    list: (args: unknown[], context: {
+        signal: AbortSignal;
+    }) => Promise<TauCodeModeFileList>;
+    remove: (args: unknown[], context: {
+        signal: AbortSignal;
+    }) => Promise<{
+        path: string;
+    }>;
+};

package/dist/code_mode/files.js

@@ -0,0 +1,296 @@
+import { CODE_MODE_MAX_BRIDGE_PAYLOAD_BYTES } from "../core/tools/code_mode_worker.js";
+export const TAU_CODE_MODE_MAX_FILES = 128;
+export const TAU_CODE_MODE_MAX_TOTAL_FILE_BYTES = 64 * 1024 * 1024;
+const FILE_COMMAND_MAX_CAPTURE_BYTES = 8 * 1024 * 1024;
+export function createTauCodeModeFilesApi(options) {
+    if (!options.agentId)
+        throw new Error("code-mode files agentId must not be empty");
+    let operationQueue = Promise.resolve();
+    const execute = (request, signal) => {
+        const operation = operationQueue.then(() => executeScratchFileRequest(options.adapter, request, signal));
+        operationQueue = operation.then(() => undefined, () => undefined);
+        return operation;
+    };
+    return {
+        read: async (args, context) => {
+            const [name] = parseArguments(args, ["string"], "files.read");
+            return await execute({ operation: "read", agentId: options.agentId, name }, context.signal);
+        },
+        write: async (args, context) => {
+            const [name, content] = parseArguments(args, ["string", "string"], "files.write");
+            return await execute({
+                operation: "write",
+                agentId: options.agentId,
+                name,
+                content,
+            }, context.signal);
+        },
+        list: async (args, context) => {
+            parseArguments(args, [], "files.list");
+            return await execute({ operation: "list", agentId: options.agentId }, context.signal);
+        },
+        remove: async (args, context) => {
+            const [name] = parseArguments(args, ["string"], "files.remove");
+            return await execute({
+                operation: "remove",
+                agentId: options.agentId,
+                name,
+            }, context.signal);
+        },
+    };
+}
+function parseArguments(args, types, method) {
+    if (args.length !== types.length || args.some((value) => typeof value !== "string")) {
+        const signature = types.map((type, index) => `${index === 0 ? "name" : "content"}: ${type}`);
+        throw new TypeError(`${method} expects (${signature.join(", ")})`);
+    }
+    return args;
+}
+async function executeScratchFileRequest(adapter, request, signal) {
+    const result = await adapter.runNodeScript(SCRATCH_FILE_SCRIPT, {
+        input: JSON.stringify(request),
+        signal,
+        maxCaptureBytes: FILE_COMMAND_MAX_CAPTURE_BYTES,
+    });
+    if (result.exitCode !== 0) {
+        throw new Error(result.stderr.trim() || "code-mode scratch file operation failed");
+    }
+    let response;
+    try {
+        response = JSON.parse(result.stdout);
+    }
+    catch {
+        throw new Error("code-mode scratch file operation returned invalid JSON");
+    }
+    if (!isScratchFileResponse(response)) {
+        throw new Error("code-mode scratch file operation returned an invalid response");
+    }
+    if (!response.ok) {
+        const error = new Error(response.error.message);
+        error.name = response.error.name;
+        throw error;
+    }
+    return response.value;
+}
+function isScratchFileResponse(value) {
+    if (typeof value !== "object" || value === null || !("ok" in value))
+        return false;
+    const response = value;
+    if (response.ok === true)
+        return "value" in response;
+    if (response.ok !== false || typeof response.error !== "object" || response.error === null) {
+        return false;
+    }
+    const error = response.error;
+    return typeof error.name === "string" && typeof error.message === "string";
+}
+const SCRATCH_FILE_SCRIPT = String.raw `
+const {
+  closeSync,
+  constants,
+  fstatSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} = require("node:fs");
+const { createHash, randomUUID } = require("node:crypto");
+const { tmpdir } = require("node:os");
+const { join } = require("node:path");
+const { TextDecoder } = require("node:util");
+
+const MAX_NAME_BYTES = 255;
+const MAX_OPERATION_BYTES = ${CODE_MODE_MAX_BRIDGE_PAYLOAD_BYTES};
+const MAX_FILES = ${TAU_CODE_MODE_MAX_FILES};
+const MAX_TOTAL_BYTES = ${TAU_CODE_MODE_MAX_TOTAL_FILE_BYTES};
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function validateName(name) {
+  const bytes = Buffer.byteLength(name, "utf8");
+  if (
+    bytes === 0 ||
+    bytes > MAX_NAME_BYTES ||
+    name === "." ||
+    name === ".." ||
+    name.includes("/") ||
+    name.includes("\\") ||
+    name.includes("\0")
+  ) {
+    fail("scratch file name must be a UTF-8 basename between 1 and 255 bytes");
+  }
+}
+
+function ensureOwnedDirectory(path, label) {
+  try {
+    mkdirSync(path, { mode: 0o700 });
+  } catch (error) {
+    if (error?.code !== "EEXIST") throw error;
+  }
+  const stats = lstatSync(path);
+  if (stats.isSymbolicLink() || !stats.isDirectory()) {
+    fail(label + " path is not a directory");
+  }
+  if (typeof process.getuid !== "function" || stats.uid !== process.getuid()) {
+    fail(label + " directory is not owned by the current user");
+  }
+  if ((stats.mode & 0o077) !== 0) {
+    fail(label + " directory permissions must not allow group or other access");
+  }
+  return path;
+}
+
+function getRoot(agentId) {
+  if (typeof agentId !== "string" || agentId.length === 0) fail("agentId must not be empty");
+  const scope = createHash("sha256").update(agentId).digest("hex").slice(0, 32);
+  return ensureOwnedDirectory(join(tmpdir(), "tau-code-mode-files-" + scope), "code-mode scratch");
+}
+
+function getStagingRoot(root) {
+  return ensureOwnedDirectory(root + "-staging", "code-mode scratch staging");
+}
+
+function getFilePath(root, name) {
+  validateName(name);
+  return join(root, name);
+}
+
+function getExistingFile(path) {
+  let stats;
+  try {
+    stats = lstatSync(path);
+  } catch (error) {
+    if (error?.code === "ENOENT") return undefined;
+    throw error;
+  }
+  if (stats.isSymbolicLink() || !stats.isFile()) fail("scratch path is not a regular file");
+  return stats;
+}
+
+function listFiles(root) {
+  const files = [];
+  for (const name of readdirSync(root)) {
+    const path = join(root, name);
+    const stats = lstatSync(path);
+    if (stats.isSymbolicLink() || !stats.isFile()) continue;
+    files.push({ name, path, bytes: stats.size });
+  }
+  files.sort((left, right) => left.name.localeCompare(right.name));
+  return files;
+}
+
+function read(root, name) {
+  const path = getFilePath(root, name);
+  const descriptor = openSync(
+    path,
+    constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
+  );
+  try {
+    const stats = fstatSync(descriptor);
+    if (!stats.isFile()) fail("scratch path is not a regular file");
+    if (stats.size > MAX_OPERATION_BYTES) {
+      fail("scratch file exceeds the 1 MiB read limit");
+    }
+    const content = readFileSync(descriptor);
+    return new TextDecoder("utf-8", { fatal: true }).decode(content);
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+function write(root, name, content) {
+  if (typeof content !== "string") fail("scratch file content must be a string");
+  const bytes = Buffer.byteLength(content, "utf8");
+  if (bytes > MAX_OPERATION_BYTES) fail("scratch file exceeds the 1 MiB write limit");
+
+  const path = getFilePath(root, name);
+  const existing = getExistingFile(path);
+  const files = listFiles(root);
+  const totalBytes = files.reduce((total, file) => total + file.bytes, 0);
+  const resultingFiles = files.length + (existing ? 0 : 1);
+  const resultingBytes = totalBytes - (existing?.size ?? 0) + bytes;
+  if (resultingFiles > MAX_FILES) fail("scratch directory exceeds the 128-file limit");
+  if (resultingBytes > MAX_TOTAL_BYTES) fail("scratch directory exceeds the 64 MiB total limit");
+
+  const temporaryPath = join(getStagingRoot(root), ".tau-write-" + randomUUID());
+  let descriptor;
+  try {
+    descriptor = openSync(
+      temporaryPath,
+      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
+      0o600,
+    );
+    writeFileSync(descriptor, content, "utf8");
+    fsyncSync(descriptor);
+    closeSync(descriptor);
+    descriptor = undefined;
+    renameSync(temporaryPath, path);
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+    try {
+      unlinkSync(temporaryPath);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+  }
+  return { path, bytes };
+}
+
+function list(root) {
+  const allFiles = listFiles(root);
+  return {
+    files: allFiles,
+    totalFiles: allFiles.length,
+    totalBytes: allFiles.reduce((total, file) => total + file.bytes, 0),
+  };
+}
+
+function remove(root, name) {
+  const path = getFilePath(root, name);
+  if (!getExistingFile(path)) fail("scratch file does not exist");
+  unlinkSync(path);
+  return { path };
+}
+
+function execute(request) {
+  if (typeof request !== "object" || request === null || typeof request.operation !== "string") {
+    fail("invalid scratch file request");
+  }
+  const root = getRoot(request.agentId);
+  switch (request.operation) {
+    case "read":
+      return read(root, request.name);
+    case "write":
+      return write(root, request.name, request.content);
+    case "list":
+      return list(root);
+    case "remove":
+      return remove(root, request.name);
+    default:
+      fail("unsupported scratch file operation");
+  }
+}
+
+try {
+  const request = JSON.parse(readFileSync(0, "utf8"));
+  process.stdout.write(JSON.stringify({ ok: true, value: execute(request) }));
+} catch (error) {
+  process.stdout.write(
+    JSON.stringify({
+      ok: false,
+      error: {
+        name: error instanceof Error ? error.name : "Error",
+        message: error instanceof Error ? error.message : String(error),
+      },
+    }),
+  );
+}
+`;
+//# sourceMappingURL=files.js.map

package/dist/code_mode/files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../../src/code_mode/files.ts"],"names":[],"mappings":"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"}

package/dist/code_mode/index.d.ts

@@ -1,4 +1,6 @@
 export { runTauClientToolCommand, TAU_CLIENT_TOOL_COMMAND_PROTOCOL_VERSION, type TauClientToolCommandHandler, } from "../sdk/client_tool_command.js";
 export { runTauCodeModeCommand } from "./command.js";
+export type { TauCodeModeFileAdapter, TauCodeModeFileAdapterResult, TauCodeModeFileList, TauCodeModeFileMetadata, TauCodeModeFilesOptions, } from "./files.js";
+export { TAU_CODE_MODE_MAX_FILES, TAU_CODE_MODE_MAX_TOTAL_FILE_BYTES, } from "./files.js";
 export type { BuildTauCodeModeToolDescriptionOptions, ExecuteTauCodeModeOptions, TauCodeModeApi, TauCodeModeDefinition, TauCodeModeExecutionStatus, TauCodeModeHandler, TauCodeModeHandlerContext, TauCodeModeInvocation, TauCodeModeJsonValue, TauCodeModePersistOutput, TauCodeModeResult, } from "./runtime.js";
 export { buildTauCodeModeToolDescription, executeTauCodeMode, TAU_CODE_MODE_DEFAULT_TIMEOUT_MS, TAU_CODE_MODE_MAX_OUTPUT_TOKENS, } from "./runtime.js";

package/dist/code_mode/index.js

@@ -1,4 +1,5 @@
 export { runTauClientToolCommand, TAU_CLIENT_TOOL_COMMAND_PROTOCOL_VERSION, } from "../sdk/client_tool_command.js";
 export { runTauCodeModeCommand } from "./command.js";
+export { TAU_CODE_MODE_MAX_FILES, TAU_CODE_MODE_MAX_TOTAL_FILE_BYTES, } from "./files.js";
 export { buildTauCodeModeToolDescription, executeTauCodeMode, TAU_CODE_MODE_DEFAULT_TIMEOUT_MS, TAU_CODE_MODE_MAX_OUTPUT_TOKENS, } from "./runtime.js";
 //# sourceMappingURL=index.js.map

package/dist/code_mode/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/code_mode/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,wCAAwC,GAEzC,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAcrD,OAAO,EACL,+BAA+B,EAC/B,kBAAkB,EAClB,gCAAgC,EAChC,+BAA+B,GAChC,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/code_mode/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,wCAAwC,GAEzC,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAQrD,OAAO,EACL,uBAAuB,EACvB,kCAAkC,GACnC,MAAM,YAAY,CAAC;AAcpB,OAAO,EACL,+BAA+B,EAC/B,kBAAkB,EAClB,gCAAgC,EAChC,+BAA+B,GAChC,MAAM,cAAc,CAAC"}

package/dist/code_mode/runtime.d.ts

@@ -1,4 +1,5 @@
 import type { TauSdkClientToolExecutionEnvironment } from "../sdk/types.js";
+import { type TauCodeModeFilesOptions } from "./files.js";
 export declare const TAU_CODE_MODE_DEFAULT_TIMEOUT_MS = 60000;
 export declare const TAU_CODE_MODE_MAX_OUTPUT_TOKENS = 8192;
 export type TauCodeModeJsonValue = null | boolean | number | string | TauCodeModeJsonValue[] | {
@@ -6,6 +7,7 @@ export type TauCodeModeJsonValue = null | boolean | number | string | TauCodeMod
 };
 export type TauCodeModeInvocation = {
     sessionId: string;
+    agentId: string;
     callId: string;
 };
 export type TauCodeModeHandlerContext = {
@@ -59,6 +61,7 @@ export type ExecuteTauCodeModeOptions = TauCodeModeDefinition & {
     signal?: AbortSignal;
     invocation?: TauCodeModeInvocation | null;
     executionEnvironment?: TauSdkClientToolExecutionEnvironment | null;
+    files?: TauCodeModeFilesOptions;
 };
 export type TauCodeModeResult = {
     content: string;
@@ -67,6 +70,7 @@ export type BuildTauCodeModeToolDescriptionOptions = {
     name: string;
     description: string;
 };
+export declare function createTauCodeModeExecutionEnvironmentFiles(agentId: string, executionEnvironment: TauSdkClientToolExecutionEnvironment): TauCodeModeFilesOptions;
 export type TauCodeModeRuntimeResult = {
     result: TauCodeModeResult;
     status: TauCodeModeExecutionStatus;