@inflexa-ai/harness 0.47.0 → 0.48.1

package/dist/tools/script/file-tools.js

@@ -7,7 +7,8 @@
  * directory of the scratch of the session.
  *
  * A table read holds at most 16 MiB, and the parse runs on the host. A larger table, or a format with no parser
- * here, is work for an analysis run, and the refusal says so.
+ * here, is work for an analysis run, and the refusal says so. `list_archive` lists the files of a compressed file, and
+ * a read names one of them as its `entry`. A gzip-compressed table reads with no entry.
  *
  * Each tool gives the files that it read or wrote as its call record. `run_script` collects the records of the
  * calls of one script, thus the provenance of the script chains each derived file to the tables that it read.
@@ -24,6 +25,7 @@ import { parseUnknownRecord, UnknownArraySchema } from "../../lib/unknown-contai
 import { resolveWorkspacePath } from "../../workspace/paths.js";
 import { defineTool, withToolCallRecord } from "../define-tool.js";
 import { normalizeEchartSpec } from "../display/normalize-echart-spec.js";
+import { ARCHIVE_SCAN_CAP_BYTES, archiveKindOf, gzipEntryName, listArchive, readArchiveEntry } from "./archive.js";
 import { recordReadBytes, recordReadRefusal } from "./metrics.js";
 /** The cap of one table read. It matches the cap of the report path, which reads with the same parsers. */
 export const TABLE_READ_CAP_BYTES = 16 * 1024 * 1024;
@@ -51,18 +53,25 @@ function numericCell(text) {
         return text;
     return value;
 }
+/** The cap of the compressed file that a read of an entry reads. */
+const ARCHIVE_READ_CAP_BYTES = 64 * 1024 * 1024;
+const entryInput = z
+    .string()
+    .min(1)
+    .optional()
+    .describe("The file inside a compressed file at `path` (zip, tar, tar.gz), as `list_archive` names it. Absent: `path` itself.");
 /**
- * Read one table through the read seam, parse it on the host, and keep the named columns. A refusal is the line
- * that the script reads. `tooLarge` names where a table over the cap goes instead.
+ * Read one file of the workspace through the read seam, or one entry of a compressed file. A gzip-compressed file
+ * with no entry reads as its one entry. A refusal is the line that the script reads.
  */
-export async function readTableRows(args) {
-    const { path, columns } = args;
-    const format = detectFormat(path);
-    if (format === undefined) {
-        recordReadRefusal("unsupported_format");
-        return err(`${path} has no table format that a script reads (csv, tsv, json, parquet); an analysis run reads it`);
-    }
-    const read = await args.workspaceFs.readFile({ session: args.session, path, maxBytes: TABLE_READ_CAP_BYTES });
+async function readScriptFile(args) {
+    const { path, maxBytes } = args;
+    const kind = archiveKindOf(path);
+    const entry = args.entry ?? (kind === "gzip" ? gzipEntryName(path) : undefined);
+    if (entry !== undefined && kind === undefined)
+        return err(`${path} is not a compressed file that a script opens (zip, tar, tar.gz, gz)`);
+    const cap = kind === undefined ? maxBytes : ARCHIVE_READ_CAP_BYTES;
+    const read = await args.workspaceFs.readFile({ session: args.session, path, maxBytes: cap });
     if (read.isErr())
         return err(`${path} could not be read`);
     const file = read.value;
@@ -72,14 +81,53 @@ export async function readTableRows(args) {
         return err(`${path} is outside this analysis`);
     if (file.kind === "truncated") {
         recordReadRefusal("too_large");
-        return err(`${path} is ${String(file.totalSize)} bytes, over the 16 MiB cap of a script read; ${args.tooLarge}`);
+        return err(`${path} is ${String(file.totalSize)} bytes, over the ${String(cap / (1024 * 1024))} MiB cap of a script read; ${args.tooLarge}`);
+    }
+    if (kind === undefined || entry === undefined)
+        return ok({ content: file.content, source: file.content });
+    const opened = readArchiveEntry(kind, path, file.content, entry, maxBytes);
+    if (opened.isOk())
+        return ok({ content: opened.value, source: file.content });
+    switch (opened.error.kind) {
+        case "not_found":
+            return err(`${path} holds no file ${entry}; list_archive gives its files`);
+        case "too_large":
+            recordReadRefusal("too_large");
+            return err(`${entry} in ${path} is over the ${String(maxBytes / (1024 * 1024))} MiB cap of a script read, or its archive decompresses past ${String(ARCHIVE_SCAN_CAP_BYTES / (1024 * 1024))} MiB; ${args.tooLarge}`);
+        case "unparsable":
+            recordReadRefusal("unparsable");
+            return err(`${path} did not open: ${opened.error.detail}`);
+        default: {
+            const unhandled = opened.error;
+            throw new Error(`unhandled entry refusal: ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+/**
+ * Read one table through the read seam, parse it on the host, and keep the named columns. A refusal is the line
+ * that the script reads. `tooLarge` names where a table over the cap goes instead.
+ */
+export async function readTableRows(args) {
+    const { path, columns } = args;
+    const kind = archiveKindOf(path);
+    const name = args.entry ?? (kind === "gzip" ? gzipEntryName(path) : path);
+    const format = detectFormat(name);
+    if (format === undefined) {
+        recordReadRefusal("unsupported_format");
+        if (kind !== undefined && kind !== "gzip" && args.entry === undefined)
+            return err(`${path} is a compressed file; list_archive gives its files, and an entry names one`);
+        return err(`${name} has no table format that a script reads (csv, tsv, json, parquet); an analysis run reads it`);
     }
-    const parsed = await parseTable(format, file.content);
+    const read = await readScriptFile({ ...args, entry: args.entry, maxBytes: TABLE_READ_CAP_BYTES });
+    if (read.isErr())
+        return err(read.error);
+    const { content, source } = read.value;
+    const parsed = await parseTable(format, content);
     if (parsed === undefined) {
         recordReadRefusal("unparsable");
-        return err(`${path} did not parse as ${format}: a ragged row, a repeated header, or a nested JSON value`);
+        return err(`${name} did not parse as ${format}: a ragged row, a repeated header, or a nested JSON value`);
     }
-    recordReadBytes(file.content.length);
+    recordReadBytes(content.length);
     const header = [...new Set(parsed.flatMap((row) => Object.keys(row)))];
     const missing = (columns ?? []).filter((column) => !header.includes(column));
     if (missing.length > 0)
@@ -94,10 +142,11 @@ export async function readTableRows(args) {
         }
         return out;
     });
-    return ok({ content: file.content, columns: kept, rows });
+    return ok({ source, columns: kept, rows });
 }
 const readTableInput = z.object({
     path: z.string().min(1).describe("Analysis-rooted path of the table, for example 'runs/<runId>/<stepId>/output/de_results.csv'."),
+    entry: entryInput,
     columns: z.array(z.string()).min(1).optional().describe("Keep only these columns. Absent: each column."),
 });
 export const ReadTableOutputSchema = z.object({
@@ -112,29 +161,88 @@ function createReadTableTool(deps) {
         id: "read_table",
         description: "Read one table of the workspace as rows: CSV, TSV, JSON (an array of flat objects), or parquet, up to 16 MiB. " +
             "Each row is an object keyed by column, and a cell that holds a plain number reads as a number. " +
+            "A gzip-compressed table reads as it is, and `entry` reads one table inside a zip or a tar. " +
             "A larger table, or another format such as h5ad, is work for an analysis run.",
         inputSchema: readTableInput,
         outputSchema: ReadTableOutputSchema,
-        describeCall: ({ path }) => path,
+        describeCall: ({ path, entry }) => (entry === undefined ? path : `${path} : ${entry}`),
         describeResult: (_input, result) => `${String(result.rowCount)} rows`,
-        execute: async ({ path, columns }, ctx) => {
-            const table = await readTableRows({ workspaceFs: deps.workspaceFs, session: ctx.session, path, columns, tooLarge: "an analysis run reads it" });
+        execute: async ({ path, entry, columns }, ctx) => {
+            const table = await readTableRows({
+                workspaceFs: deps.workspaceFs,
+                session: ctx.session,
+                path,
+                entry,
+                columns,
+                tooLarge: "an analysis run reads it",
+            });
             if (table.isErr())
                 return refused(table.error);
-            const { content, rows } = table.value;
+            const { source, rows } = table.value;
             const { analysisId } = ctx.session.scope;
             const resolved = resolveWorkspacePath({ workspaceRoot: await deps.resolveWorkspaceRoot(analysisId), analysisId, path });
             const relative = resolved.kind === "ok" ? resolved.relative.split("\\").join("/") : path;
-            const effect = { reads: [{ path: relative, hash: computeSha256(content) }] };
+            const effect = { reads: [{ path: relative, hash: computeSha256(source) }] };
             return ok(withToolCallRecord({ path: relative, columns: table.value.columns, rowCount: rows.length, rows }, effect));
         },
     });
 }
+const listArchiveInput = z.object({
+    path: z.string().min(1).describe("Analysis-rooted path of a compressed file: .zip, .tar, .tar.gz, .tgz, or .gz."),
+});
+const ListArchiveOutputSchema = z.object({
+    path: z.string(),
+    entries: z.array(z.object({ name: z.string(), bytes: z.number() })).readonly(),
+});
+function createListArchiveTool(deps) {
+    return defineTool({
+        id: "list_archive",
+        description: "List the files inside a compressed file of the workspace (zip, tar, tar.gz, gz), each with its decompressed size. " +
+            "`read_table` and `read_pdf` then read one of them as their `entry`.",
+        inputSchema: listArchiveInput,
+        outputSchema: ListArchiveOutputSchema,
+        describeCall: ({ path }) => path,
+        describeResult: (_input, result) => `${String(result.entries.length)} files`,
+        execute: async ({ path }, ctx) => {
+            const kind = archiveKindOf(path);
+            if (kind === undefined) {
+                recordReadRefusal("unsupported_format");
+                return refused(`${path} is not a compressed file that a script opens (zip, tar, tar.gz, gz)`);
+            }
+            const read = await readScriptFile({
+                workspaceFs: deps.workspaceFs,
+                session: ctx.session,
+                path,
+                entry: undefined,
+                maxBytes: ARCHIVE_READ_CAP_BYTES,
+                tooLarge: "an analysis run opens it",
+            });
+            if (read.isErr())
+                return refused(read.error);
+            const { source } = read.value;
+            const listed = listArchive(kind, path, source);
+            if (listed.isErr()) {
+                if (listed.error.kind === "too_large") {
+                    recordReadRefusal("too_large");
+                    return refused(`${path} decompresses past ${String(ARCHIVE_SCAN_CAP_BYTES / (1024 * 1024))} MiB; an analysis run opens it`);
+                }
+                recordReadRefusal("unparsable");
+                return refused(`${path} did not open${listed.error.kind === "unparsable" ? `: ${listed.error.detail}` : ""}`);
+            }
+            const { analysisId } = ctx.session.scope;
+            const resolved = resolveWorkspacePath({ workspaceRoot: await deps.resolveWorkspaceRoot(analysisId), analysisId, path });
+            const relative = resolved.kind === "ok" ? resolved.relative.split("\\").join("/") : path;
+            const effect = { reads: [{ path: relative, hash: computeSha256(source) }] };
+            return ok(withToolCallRecord({ path: relative, entries: listed.value }, effect));
+        },
+    });
+}
 /** The cap of one PDF read, and the pages that one call reads. */
 const PDF_READ_CAP_BYTES = 64 * 1024 * 1024;
 const PDF_PAGES_PER_READ = 50;
 const readPdfInput = z.object({
     path: z.string().min(1).describe("Analysis-rooted path of the PDF, for example 'data/inputs/<fileId>/paper.pdf'."),
+    entry: entryInput,
     firstPage: z.number().int().min(1).optional().describe("The first page to read, 1-based. Absent: 1."),
     lastPage: z
         .number()
@@ -158,42 +266,48 @@ export function createReadPdfTool(deps) {
             "A scanned page with no text layer reads as an empty text.",
         inputSchema: readPdfInput,
         outputSchema: ReadPdfOutputSchema,
-        describeCall: ({ path, firstPage, lastPage }) => firstPage === undefined && lastPage === undefined ? path : `${path}, pages ${String(firstPage ?? 1)}-${String(lastPage ?? "")}`,
+        describeCall: ({ path, entry, firstPage, lastPage }) => {
+            const file = entry === undefined ? path : `${path} : ${entry}`;
+            return firstPage === undefined && lastPage === undefined ? file : `${file}, pages ${String(firstPage ?? 1)}-${String(lastPage ?? "")}`;
+        },
         describeResult: (_input, result) => `${String(result.pages.length)} of ${String(result.totalPages)} pages`,
         // `run_script` folds the record of a nested call only into a tool that folds records.
         foldCallRecord: lineage === undefined ? undefined : (effect) => lineage.track(effect.reads ?? []),
-        execute: async ({ path, firstPage, lastPage }, ctx) => {
-            if (!path.toLowerCase().endsWith(".pdf")) {
+        execute: async ({ path, entry, firstPage, lastPage }, ctx) => {
+            const kind = archiveKindOf(path);
+            const name = entry ?? (kind === "gzip" ? gzipEntryName(path) : path);
+            if (!name.toLowerCase().endsWith(".pdf")) {
                 recordReadRefusal("unsupported_format");
-                return refused(`${path} is not a PDF; read_table reads a table, and read_file reads text`);
+                if (kind !== undefined && kind !== "gzip" && entry === undefined)
+                    return refused(`${path} is a compressed file; list_archive gives its files, and an entry names one`);
+                return refused(`${name} is not a PDF; read_table reads a table, and read_file reads text`);
             }
-            const read = await deps.workspaceFs.readFile({ session: ctx.session, path, maxBytes: PDF_READ_CAP_BYTES });
+            const read = await readScriptFile({
+                workspaceFs: deps.workspaceFs,
+                session: ctx.session,
+                path,
+                entry,
+                maxBytes: PDF_READ_CAP_BYTES,
+                tooLarge: "an analysis run reads it",
+            });
             if (read.isErr())
-                return refused(`${path} could not be read`);
-            const file = read.value;
-            if (file.kind === "not_found")
-                return refused(`${path} does not exist; find the path with workspace_search or list_files`);
-            if (file.kind === "out_of_scope")
-                return refused(`${path} is outside this analysis`);
-            if (file.kind === "truncated") {
-                recordReadRefusal("too_large");
-                return refused(`${path} is ${String(file.totalSize)} bytes, over the 64 MiB cap of a PDF read`);
-            }
+                return refused(read.error);
+            const { content, source } = read.value;
             const first = firstPage ?? 1;
             const last = Math.min(lastPage ?? first + PDF_PAGES_PER_READ - 1, first + PDF_PAGES_PER_READ - 1);
             let text;
             try {
-                text = await readPdfText(file.content, { first, last });
+                text = await readPdfText(content, { first, last });
             }
             catch {
                 recordReadRefusal("unparsable");
                 return refused(`${path} did not open as a PDF: a damaged file, or a file with a password`);
             }
-            recordReadBytes(file.content.length);
+            recordReadBytes(content.length);
             const { analysisId } = ctx.session.scope;
             const resolved = resolveWorkspacePath({ workspaceRoot: await deps.resolveWorkspaceRoot(analysisId), analysisId, path });
             const relative = resolved.kind === "ok" ? resolved.relative.split("\\").join("/") : path;
-            const effect = { reads: [{ path: relative, hash: computeSha256(file.content) }] };
+            const effect = { reads: [{ path: relative, hash: computeSha256(source) }] };
             return ok(withToolCallRecord({ path: relative, totalPages: text.totalPages, pages: text.pages }, effect));
         },
     });
@@ -365,11 +479,11 @@ function createExportPdfTool(deps) {
     });
 }
 export function createScriptFileTools(deps) {
-    return [createReadTableTool(deps), createReadPdfTool(deps), createWriteDerivedTool(deps), ...createDocumentTools(deps)];
+    return [createReadTableTool(deps), createReadPdfTool(deps), createListArchiveTool(deps), createWriteDerivedTool(deps), ...createDocumentTools(deps)];
 }
-/** The script tools that read a table and a PDF of the workspace, and write nothing. */
+/** The script tools that read a table, a PDF, and the files of a compressed file of the workspace, and write nothing. */
 export function createReadScriptTools(deps) {
-    return [createReadTableTool(deps), createReadPdfTool(deps)];
+    return [createReadTableTool(deps), createReadPdfTool(deps), createListArchiveTool(deps)];
 }
 /** The tools that make a document in a script: a chart as an SVG file, and a PDF from markdown. */
 export function createDocumentTools(deps) {

package/dist/tools/script/metrics.d.ts

@@ -9,13 +9,22 @@
  *   - cortex.harness.script.read_refusals — counter, one for each table read that a script tool refused, with
  *     `reason` (`too_large`, `unsupported_format`, or `unparsable`). A rise of `too_large` and `unsupported_format`
  *     says that the work wants the tables that only a sandbox reads.
- *   - cortex.harness.script.read_bytes — histogram of the bytes of each table that a script read.
+ *   - cortex.harness.script.read_bytes — histogram of the bytes of each table or PDF that a script read, in buckets
+ *     from 1 KiB up to the PDF read cap.
  *
  * A recovery replays the cached result of a script and runs no body, thus a replay never counts again. The
  * instruments are made on the first use, thus they bind to whatever provider the host registers.
  */
 export type ScriptFailure = "none" | "script" | "memory" | "timeout" | "aborted" | "sandbox";
 export type ReadRefusal = "too_large" | "unsupported_format" | "unparsable";
+/**
+ * Bucket bounds for the bytes of one read: 1 KiB to 64 MiB, a factor of 4 apart. The top bound is the PDF read cap,
+ * thus the overflow bucket stays empty. Without them the default bounds stop at 10000, and each larger read lands in
+ * the overflow bucket.
+ */
+export declare const SCRIPT_READ_BOUNDS_BYTES: readonly number[];
 export declare function recordScriptRun(agentId: string, failure: ScriptFailure): void;
 export declare function recordReadRefusal(reason: ReadRefusal): void;
 export declare function recordReadBytes(bytes: number): void;
+/** Drop the instruments, thus the next record binds to the provider that a test registered. */
+export declare function __resetScriptMetricsForTest(): void;

package/dist/tools/script/metrics.js

@@ -9,12 +9,19 @@
  *   - cortex.harness.script.read_refusals — counter, one for each table read that a script tool refused, with
  *     `reason` (`too_large`, `unsupported_format`, or `unparsable`). A rise of `too_large` and `unsupported_format`
  *     says that the work wants the tables that only a sandbox reads.
- *   - cortex.harness.script.read_bytes — histogram of the bytes of each table that a script read.
+ *   - cortex.harness.script.read_bytes — histogram of the bytes of each table or PDF that a script read, in buckets
+ *     from 1 KiB up to the PDF read cap.
  *
  * A recovery replays the cached result of a script and runs no body, thus a replay never counts again. The
  * instruments are made on the first use, thus they bind to whatever provider the host registers.
  */
 import { metrics } from "@opentelemetry/api";
+/**
+ * Bucket bounds for the bytes of one read: 1 KiB to 64 MiB, a factor of 4 apart. The top bound is the PDF read cap,
+ * thus the overflow bucket stays empty. Without them the default bounds stop at 10000, and each larger read lands in
+ * the overflow bucket.
+ */
+export const SCRIPT_READ_BOUNDS_BYTES = [1_024, 4_096, 16_384, 65_536, 262_144, 1_048_576, 4_194_304, 16_777_216, 67_108_864];
 let instruments;
 function getInstruments() {
     if (instruments === undefined) {
@@ -22,7 +29,11 @@ function getInstruments() {
         instruments = {
             runs: meter.createCounter("cortex.harness.script.runs", { description: "Scripts that run_script ran" }),
             readRefusals: meter.createCounter("cortex.harness.script.read_refusals", { description: "Table reads of a script that a script tool refused" }),
-            readBytes: meter.createHistogram("cortex.harness.script.read_bytes", { description: "Bytes of each table that a script read", unit: "By" }),
+            readBytes: meter.createHistogram("cortex.harness.script.read_bytes", {
+                description: "Bytes of each table or PDF that a script read",
+                unit: "By",
+                advice: { explicitBucketBoundaries: [...SCRIPT_READ_BOUNDS_BYTES] },
+            }),
         };
     }
     return instruments;
@@ -36,3 +47,7 @@ export function recordReadRefusal(reason) {
 export function recordReadBytes(bytes) {
     getInstruments().readBytes.record(bytes);
 }
+/** Drop the instruments, thus the next record binds to the provider that a test registered. */
+export function __resetScriptMetricsForTest() {
+    instruments = undefined;
+}

package/dist/tools/script/run-script.js

@@ -33,6 +33,8 @@ const SCRIPT_TIMEOUT_MS = 180_000;
 const SCRIPT_MEMORY_BYTES = 256 * 1024 * 1024;
 /** The text of a result that reaches the model. A longer output keeps its head and its tail. */
 const MAX_RESULT_CHARS = 24_000;
+/** The least time between two live copies of the nested calls of a script. */
+const LIVE_ACTIVITY_INTERVAL_MS = 500;
 const inputSchema = z.object({
     description: z.string().max(200).optional().describe("One short line that tells the user what the script does, for example 'Top 20 genes by padj'."),
     code: z
@@ -57,11 +59,59 @@ function plainJson(value) {
     return value === undefined ? null : parseJsonAs(JSON.stringify(value), z.json());
 }
 function describeTool(tool) {
-    return renderToolSample({ name: tool.id, description: tool.description, inputSchema: tool.jsonSchema, outputSchema: tool.outputJsonSchema });
+    return renderToolSample({ name: tool.id, description: tool.description, inputSchema: inputSchemaOf(tool), outputSchema: tool.outputJsonSchema });
 }
 function issuesOf(error) {
     return error.issues.map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`).join("; ");
 }
+/**
+ * The live copies of the activity part of one script, so a reader sees each nested call while the script runs. A copy
+ * is transient, and the part that the call emits at its end is the one that a stored display keeps. Each copy holds
+ * each entry so far, thus at most one copy goes in each interval. A copy that the interval holds back goes at the end
+ * of the interval, thus a long nested call shows before it ends.
+ */
+function createLiveActivity(emit, log, intervalMs) {
+    let latest = null;
+    let lastSentMs = Number.NEGATIVE_INFINITY;
+    let timer;
+    let closed = false;
+    const inFlight = new Set();
+    const send = () => {
+        timer = undefined;
+        if (closed || latest === null)
+            return;
+        lastSentMs = Date.now();
+        const part = latest;
+        const sent = (async () => {
+            try {
+                await emit({ type: part.type, data: part, transient: true });
+            }
+            catch (err) {
+                log.warn("a live copy of the nested calls did not reach the stream", log.errorFields(err));
+            }
+        })();
+        inFlight.add(sent);
+        void sent.finally(() => inFlight.delete(sent));
+    };
+    return {
+        update(part) {
+            latest = part;
+            if (closed || timer !== undefined)
+                return;
+            const wait = lastSentMs + intervalMs - Date.now();
+            if (wait <= 0)
+                send();
+            // oxlint-disable-next-line eslint-js/no-restricted-syntax -- `close` clears it, and the call runs `close` in its `finally`, thus it ends with the call.
+            else
+                timer = setTimeout(send, wait);
+        },
+        async close() {
+            closed = true;
+            clearTimeout(timer);
+            await Promise.all(inFlight);
+        },
+    };
+}
 /** Keep the files of the call record of one nested call. A record of another shape carries no file. */
 function collectEffect(state, value) {
     const effect = ScriptFileEffectSchema.safeParse(readToolCallRecord(value));
@@ -82,7 +132,7 @@ function scriptToolOf(tool, ctx, state, log, inCallContext) {
     return {
         name: tool.id,
         description: tool.description,
-        inputSchema: tool.jsonSchema,
+        inputSchema: inputSchemaOf(tool),
         outputSchema: tool.outputJsonSchema,
         execute: (args, options) => inCallContext(() => runNestedCall(tool, ctx, state, log, args, options.signal)),
     };
@@ -148,6 +198,36 @@ function withoutProse(schema) {
         .filter(([key]) => key !== "description" && key !== "examples")
         .map(([key, value]) => [key, withoutProse(value)]));
 }
+/**
+ * A JSON schema as a script reads it. A tool can union its real shape with the empty schema to keep its runtime parse
+ * permissive (`add_block` does, thus a malformed block reaches its typed refusal). The type of such a union is
+ * `unknown`, which hides the real shape, thus the empty member goes. The VM only renders the schema and validates
+ * nothing, and the tool still parses each input with its own schema.
+ */
+function printableSchema(schema) {
+    const array = UnknownArraySchema.safeParse(schema);
+    if (array.success)
+        return array.data.map(printableSchema);
+    const record = parseUnknownRecord(schema);
+    if (record === undefined)
+        return schema;
+    let out = Object.fromEntries(Object.entries(record).map(([key, value]) => [key, printableSchema(value)]));
+    for (const key of ["anyOf", "oneOf"]) {
+        const members = UnknownArraySchema.safeParse(out[key]);
+        if (!members.success)
+            continue;
+        const shaped = members.data.filter((member) => Object.keys(parseUnknownRecord(member) ?? {}).length > 0);
+        if (shaped.length === 0 || shaped.length === members.data.length)
+            continue;
+        const rest = Object.fromEntries(Object.entries(out).filter(([name]) => name !== key));
+        out = shaped.length > 1 ? { ...rest, [key]: shaped } : { ...rest, ...parseUnknownRecord(shaped[0]) };
+    }
+    return out;
+}
+/** The input schema of a tool as a script reads it. See {@link printableSchema}. */
+function inputSchemaOf(tool) {
+    return parseUnknownRecord(printableSchema(tool.jsonSchema)) ?? tool.jsonSchema;
+}
 /** The longest result type that the catalog shows. A longer type shows as `unknown`, and `describe()` gives it whole. */
 const MAX_CATALOG_RESULT_TYPE_CHARS = 800;
 /** One catalog entry: the first sentence of the description, then the signature with no prose. */
@@ -155,7 +235,7 @@ function catalogEntry(tool) {
     const output = tool.outputJsonSchema === undefined ? undefined : parseUnknownRecord(withoutProse(tool.outputJsonSchema));
     const resultType = output === undefined ? "unknown" : schemaToType(output, { maxChars: MAX_CATALOG_RESULT_TYPE_CHARS });
     // pi renders a signature with no result schema as `...: Promise<unknown>;`, thus the catalog puts its capped type there.
-    const untyped = renderToolSignature({ name: tool.id, inputSchema: parseUnknownRecord(withoutProse(tool.jsonSchema)) ?? {} });
+    const untyped = renderToolSignature({ name: tool.id, inputSchema: parseUnknownRecord(withoutProse(inputSchemaOf(tool))) ?? {} });
     const signature = `${untyped.slice(0, -"unknown>;".length)}${resultType}>;`;
     return `/** ${firstSentence(tool.description)} */\n${signature}`;
 }
@@ -234,6 +314,7 @@ export function createRunScriptTool(scriptTools, runtime = {}, options = {}) {
                 source: { agentId: caller.agentId, callPath: [...caller.callPath] },
             }, Date.now());
             const tracked = { part: null };
+            const live = createLiveActivity(ctx.emit, log, LIVE_ACTIVITY_INTERVAL_MS);
             let started = 0;
             const state = {
                 code,
@@ -244,7 +325,11 @@ export function createRunScriptTool(scriptTools, runtime = {}, options = {}) {
                 nextInvocationId: () => `${ctx.invocationId}:${++started}`,
                 source: { agentId: RUN_SCRIPT_TOOL_ID, callPath: [...caller.callPath, RUN_SCRIPT_TOOL_ID], invocationId: ctx.invocationId },
                 observe: (frame) => {
-                    tracked.part = tracker.track(frame, Date.now()) ?? tracked.part;
+                    const part = tracker.track(frame, Date.now());
+                    if (part === null)
+                        return;
+                    tracked.part = part;
+                    live.update(part);
                 },
             };
             // The VM calls a tool from a message event of its worker, and such an event runs outside the async context
@@ -286,6 +371,7 @@ export function createRunScriptTool(scriptTools, runtime = {}, options = {}) {
                     reads: state.reads.length,
                     writes: state.writes.length,
                 });
+                await live.close();
                 if (tracked.part !== null)
                     await ctx.emit({ type: tracked.part.type, data: tracked.part });
                 if (state.writes.length > 0) {
@@ -319,6 +405,7 @@ export function createRunScriptTool(scriptTools, runtime = {}, options = {}) {
                 return ok(record.run === undefined && record.nested.length === 0 ? outcome : withToolCallRecord(outcome, record));
             }
             finally {
+                await live.close();
                 await sandbox.close();
             }
         },

package/dist/tools/script/scratch.d.ts

@@ -13,6 +13,7 @@ import type { AgentSession } from "../../auth/types.js";
 import type { Logger } from "../../lib/logger.js";
 import { type ProvenanceSeam } from "../../provenance/seam.js";
 import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
+import { type SyncSessionFile } from "../../workspace/session-files.js";
 /** The cap of one derived file. It matches the cap of a table read, thus a script can read back what it wrote. */
 export declare const DERIVED_FILE_CAP_BYTES: number;
 /** The cap of the derived files of one session together. */
@@ -76,6 +77,8 @@ export type ScriptScratchDeps = {
     readonly sessionDir: (threadId: string) => string;
     /** The provenance seam. An unbound session emit records nothing, and the scripts run the same. */
     readonly provenance?: ProvenanceSeam;
+    /** The host copy of each file that lands, owned by the thread of the session. */
+    readonly syncSessionFile?: SyncSessionFile;
     readonly logger?: Logger;
 };
 export declare function createScriptScratch(deps: ScriptScratchDeps): ScriptScratch;

package/dist/tools/script/scratch.js

@@ -17,6 +17,7 @@ import { tryFs } from "../../lib/fs-result.js";
 import { unwrapOrThrow } from "../../lib/result.js";
 import { bindSessionEmit } from "../../provenance/seam.js";
 import { isSafeId } from "../../workspace/paths.js";
+import { syncWrittenFile } from "../../workspace/session-files.js";
 import { confinedWrite } from "../workspace/mutator.js";
 /** The cap of one derived file. It matches the cap of a table read, thus a script can read back what it wrote. */
 export const DERIVED_FILE_CAP_BYTES = 16 * 1024 * 1024;
@@ -55,7 +56,7 @@ async function directoryBytes(absolute) {
 export function createScriptScratch(deps) {
     const logger = (deps.logger ?? createNoopLogger()).named("script-scratch");
     const observe = bindSessionEmit(deps.provenance, logger);
-    async function land(session, dir, name, content, invocationId) {
+    async function land(session, threadId, dir, name, content, invocationId) {
         const { analysisId } = session.scope;
         const workspaceRoot = await deps.resolveWorkspaceRoot(analysisId);
         const landed = await confinedWrite({
@@ -70,14 +71,16 @@ export function createScriptScratch(deps) {
         });
         if (landed.status !== "ok")
             return { refused: `the write of ${dir}/${name} was refused (${landed.status})` };
-        return { path: landed.relative, hash: computeSha256(landed.bytes), size: landed.bytes.length };
+        const file = { path: landed.relative, hash: computeSha256(landed.bytes), size: landed.bytes.length };
+        await syncWrittenFile(deps.syncSessionFile, logger, { session, owner: { kind: "thread", threadId }, ...file, content: landed.bytes });
+        return file;
     }
     return {
         async saveScript({ session, invocationId, code }) {
             const { threadId } = session.scope;
             if (threadId === undefined)
                 return undefined;
-            const saved = await land(session, `${deps.sessionDir(threadId)}/scripts`, scriptFileName(invocationId), code, invocationId);
+            const saved = await land(session, threadId, `${deps.sessionDir(threadId)}/scripts`, scriptFileName(invocationId), code, invocationId);
             if ("refused" in saved)
                 throw new Error(saved.refused);
             return saved;
@@ -115,7 +118,7 @@ export function createScriptScratch(deps) {
             if (used + bytes > DERIVED_SESSION_CAP_BYTES) {
                 return { status: "refused", reason: `the derived files of this session would pass the cap of ${String(DERIVED_SESSION_CAP_BYTES)} bytes` };
             }
-            const landed = await land(session, dir, name, content, invocationId);
+            const landed = await land(session, threadId, dir, name, content, invocationId);
             if ("refused" in landed)
                 return { status: "refused", reason: landed.refused };
             return { status: "written", file: landed };

package/dist/tools/workspace/mutator.d.ts

@@ -38,6 +38,7 @@ import type { AgentSession } from "../../auth/types.js";
 import type { Logger } from "../../lib/logger.js";
 import type { ProvenanceCollector } from "../../provenance/collector.js";
 import { type ProvenanceSeam } from "../../provenance/seam.js";
+import { type SyncSessionFile } from "../../workspace/session-files.js";
 import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
 /** Outcome of a confined write. Expected outcomes are data variants — never throws on them. */
 export type WriteFileResult = {
@@ -191,6 +192,8 @@ export type SessionWorkspaceMutatorDeps = {
      * proceeds unchanged.
      */
     readonly provenance?: ProvenanceSeam;
+    /** The host copy of each file that lands, owned by the analysis: the path is anywhere in its tree. */
+    readonly syncSessionFile?: SyncSessionFile;
     readonly logger?: Logger;
 };
 /**

package/dist/tools/workspace/mutator.js

@@ -43,6 +43,7 @@ import { computeSha256 } from "../../lib/fs-helpers.js";
 import { tryFs, tryFsWrite } from "../../lib/fs-result.js";
 import { unwrapOrThrow } from "../../lib/result.js";
 import { bindSessionEmit } from "../../provenance/seam.js";
+import { syncWrittenFile } from "../../workspace/session-files.js";
 import { resolveForWrite, STAGED_INPUT_ROOT } from "../../workspace/paths.js";
 /**
  * Agent-visible name of the tool driving a confined write. Rides the write args
@@ -305,7 +306,16 @@ export function createSessionWorkspaceMutator(deps) {
             });
             if (landed.status !== "ok")
                 return { ...landed, path };
-            return landedWrite(landed);
+            const write = landedWrite(landed);
+            await syncWrittenFile(deps.syncSessionFile, logger, {
+                session,
+                owner: { kind: "analysis" },
+                path: write.record.path,
+                hash: write.record.hash,
+                size: write.record.size,
+                content: landed.bytes,
+            });
+            return write;
         },
         recordWrite(record) {
             const event = {