@markusylisiurunen/tau 0.3.47 → 0.3.48

package/README.md

@@ -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
 
@@ -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 still runs on the TUI 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 TUI's current working directory with the TUI 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,7 +737,7 @@ 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`.
 

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;

package/dist/code_mode/runtime.js

@@ -2,12 +2,26 @@ import stripAnsi from "strip-ansi";
 import { CODE_MODE_MAX_BRIDGE_PAYLOAD_BYTES, CODE_MODE_MAX_BRIDGE_REQUESTS, CODE_MODE_MAX_CONCURRENT_BRIDGE_REQUESTS, executeCodeModeWorker, } from "../core/tools/code_mode_worker.js";
 import { bytesToTokens } from "../core/utils/token.js";
 import { formatBytes, truncateForTokens } from "../core/utils/truncate.js";
+import { createTauCodeModeFilesApi, TAU_CODE_MODE_MAX_FILES, TAU_CODE_MODE_MAX_TOTAL_FILE_BYTES, } from "./files.js";
 export const TAU_CODE_MODE_DEFAULT_TIMEOUT_MS = 60_000;
 export const TAU_CODE_MODE_MAX_OUTPUT_TOKENS = 8_192;
 const sandboxRunnerUrl = new URL("../core/static/code_mode/sandbox_runner.mjs", import.meta.url);
 const javascriptIdentifierPattern = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
-const reservedNames = new Set([...Object.getOwnPropertyNames(globalThis), "docs"]);
+const reservedNames = new Set([...Object.getOwnPropertyNames(globalThis), "docs", "files"]);
 const unsafeApiKeys = new Set(["__proto__", "constructor", "prototype"]);
+export function createTauCodeModeExecutionEnvironmentFiles(agentId, executionEnvironment) {
+    return {
+        agentId,
+        adapter: {
+            runNodeScript: async (script, options) => await executionEnvironment.exec('exec "$0" "$@"', {
+                args: ["node", "-e", script],
+                stdin: Buffer.from(options.input),
+                signal: options.signal,
+                maxCaptureBytes: options.maxCaptureBytes,
+            }),
+        },
+    };
+}
 export function buildTauCodeModeToolDescription({ name, description, }) {
     validateName(name);
     const trimmedDescription = description.trim();
@@ -26,7 +40,7 @@ export function validateTauCodeModeDefinition(definition) {
         throw new Error("code-mode documentation must not be empty");
     }
     validateTimeout(definition.timeoutMs);
-    registerMethods(definition.api);
+    registerMethods(definition.api, definition.name);
 }
 export async function executeTauCodeMode(options) {
     const runtime = await runTauCodeMode(options);
@@ -43,12 +57,20 @@ export async function runTauCodeMode(options) {
         throw new Error("code-mode documentation must not be empty");
     }
     validateTimeout(options.timeoutMs);
-    const methods = registerMethods(options.api);
+    const apiMethods = registerMethods(options.api, options.name);
+    const filesMethods = options.files
+        ? registerMethods(createTauCodeModeFilesApi(options.files), "files", apiMethods.length)
+        : [];
+    const apis = [
+        { name: options.name, methods: apiMethods },
+        ...(filesMethods.length > 0 ? [{ name: "files", methods: filesMethods }] : []),
+    ];
+    const methods = apis.flatMap((api) => api.methods);
     const timeoutMs = options.timeoutMs ?? TAU_CODE_MODE_DEFAULT_TIMEOUT_MS;
     const invocation = options.invocation ?? null;
     const executionEnvironment = options.executionEnvironment ?? null;
     const signal = options.signal ?? new AbortController().signal;
-    const docs = buildRuntimeDocumentation(options.name, options.documentation, timeoutMs);
+    const docs = buildRuntimeDocumentation(options.name, options.documentation, timeoutMs, filesMethods.length > 0);
     const startedAt = Date.now();
     let execution;
     try {
@@ -57,22 +79,24 @@ export async function runTauCodeMode(options) {
             workerData: {
                 code: options.code,
                 docs,
-                name: options.name,
-                methods: methods.map(({ id, path }) => ({ id, path })),
+                apis: apis.map((api) => ({
+                    name: api.name,
+                    methods: api.methods.map(({ id, path }) => ({ id, path })),
+                })),
             },
             signal,
             timeoutMs,
             handleRequest: async (request, requestSignal) => {
                 const method = methods[request.methodId];
                 if (!method)
-                    throw new Error(`unsupported ${options.name} API method`);
-                const args = parseBridgeArguments(request.argsJson, options.name, method.path);
+                    throw new Error("unsupported code-mode API method");
+                const args = parseBridgeArguments(request.argsJson, method.apiName, method.path);
                 const value = await method.handler(args, {
                     signal: requestSignal,
                     invocation,
                     executionEnvironment,
                 });
-                return serializeBridgeResult(value, options.name, method.path);
+                return serializeBridgeResult(value, method.apiName, method.path);
             },
         });
     }
@@ -142,7 +166,7 @@ function validateTimeout(timeoutMs) {
         throw new Error("code-mode timeoutMs must be a positive integer");
     }
 }
-function registerMethods(api) {
+function registerMethods(api, apiName, firstId = 0) {
     const methods = [];
     const visit = (value, path) => {
         if (!isPlainObject(value)) {
@@ -158,7 +182,7 @@ function registerMethods(api) {
                 throw new Error(`code-mode API key '${formatPath(childPath)}' is not allowed`);
             }
             if (typeof child === "function") {
-                methods.push({ id: methods.length, path: childPath, handler: child });
+                methods.push({ id: firstId + methods.length, apiName, path: childPath, handler: child });
             }
             else {
                 visit(child, childPath);
@@ -220,26 +244,46 @@ function serializeBridgeResult(value, name, path) {
     }
     return json;
 }
-function buildRuntimeDocumentation(name, documentation, timeoutMs) {
+function buildRuntimeDocumentation(name, documentation, timeoutMs, hasFiles) {
     return [
         "# Code-mode runtime",
         "",
         "## Available globals",
         "",
         `- \`${name}\`: the explicitly exposed API documented below.`,
+        ...(hasFiles
+            ? ["- `files`: shared UTF-8 scratch files for this agent, documented below."]
+            : []),
         "- `docs`: this document.",
         "- `console`: program output through `debug`, `error`, `info`, `log`, and `warn`.",
         "- `Date`: standard date handling with live current-time access.",
         "- `Math`: standard math operations, including `Math.random()`.",
         "",
         "Top-level `await` is supported. The program return value is ignored; only console output is returned.",
-        "Generated code has no direct filesystem, process, environment, network, credential, import, timer, or `fetch` access.",
+        hasFiles
+            ? "Generated code has no direct process, environment, network, credential, import, timer, or `fetch` access. Filesystem access is limited to the `files` scratch API."
+            : "Generated code has no direct filesystem, process, environment, network, credential, import, timer, or `fetch` access.",
         "",
         "## API boundary",
         "",
-        `Arguments passed to \`${name}\` methods and their results cross a JSON serialization boundary with a ${formatBytes(CODE_MODE_MAX_BRIDGE_PAYLOAD_BYTES)} limit per request or response.`,
+        `Arguments and results cross a JSON serialization boundary with a ${formatBytes(CODE_MODE_MAX_BRIDGE_PAYLOAD_BYTES)} limit per request or response.`,
         `A program may make at most ${CODE_MODE_MAX_BRIDGE_REQUESTS} API calls, with at most ${CODE_MODE_MAX_CONCURRENT_BRIDGE_REQUESTS} unresolved calls concurrently. Exceeding any bridge limit fails the program.`,
         `The program must finish within ${formatDuration(timeoutMs)}.`,
+        ...(hasFiles
+            ? [
+                "",
+                "## Scratch files",
+                "",
+                "Scratch files are real files in an execution-environment temporary directory shared by every code-mode tool for this agent. Returned absolute paths can be used by Bash and other tools. The execution environment controls their lifetime; they are not stored in the session snapshot.",
+                "",
+                "- `await files.write(name, content)` atomically writes UTF-8 text and returns `{ path, bytes }`.",
+                "- `await files.read(name)` reads the current file as UTF-8 text.",
+                "- `await files.list()` returns `{ files, totalFiles, totalBytes }`; each file has `{ name, path, bytes }`.",
+                "- `await files.remove(name)` removes a file and returns `{ path }`.",
+                "",
+                `Names must be single UTF-8 basenames of at most 255 bytes. \`files.write()\` rejects changes above ${TAU_CODE_MODE_MAX_FILES} regular files or ${TAU_CODE_MODE_MAX_TOTAL_FILE_BYTES / (1024 * 1024)} MiB total; Bash-created over-limit contents remain visible and removable.`,
+            ]
+            : []),
         "",
         "## Output",
         "",