@inflexa-ai/harness 0.47.0 → 0.48.0

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

@@ -0,0 +1,34 @@
+/**
+ * The entries of a compressed file, for the read tools of a script: a zip, a tar, a gzip-compressed tar, or one
+ * gzip-compressed file.
+ *
+ * Each read runs on the host and holds the bytes in memory, thus each one has a cap. A zip names the size of each
+ * entry in its index, thus a list reads no entry and a read decompresses one entry. A tar has no index, thus a list
+ * and a read of a `.tar.gz` decompress the whole stream, up to {@link ARCHIVE_SCAN_CAP_BYTES}.
+ */
+import { type Result } from "neverthrow";
+export type ArchiveKind = "zip" | "tar" | "tar-gzip" | "gzip";
+/** The cap of the decompressed stream of a gzip-compressed tar or file that a list or a read decompresses. */
+export declare const ARCHIVE_SCAN_CAP_BYTES: number;
+export type ArchiveEntry = {
+    readonly name: string;
+    readonly bytes: number;
+};
+/** Why an entry did not read. `too_large` carries the size of the entry, when the archive names it. */
+export type EntryRefusal = {
+    readonly kind: "not_found";
+} | {
+    readonly kind: "too_large";
+    readonly bytes: number | undefined;
+} | {
+    readonly kind: "unparsable";
+    readonly detail: string;
+};
+/** The kind of a compressed file by its name, or `undefined` for a file that is not one. */
+export declare function archiveKindOf(path: string): ArchiveKind | undefined;
+/** The one entry of a gzip-compressed file: its name with no `.gz`. */
+export declare function gzipEntryName(path: string): string;
+/** Each file of a compressed file, with its decompressed size. */
+export declare function listArchive(kind: ArchiveKind, path: string, content: Buffer): Result<ArchiveEntry[], EntryRefusal>;
+/** The decompressed bytes of one entry, up to `cap`. */
+export declare function readArchiveEntry(kind: ArchiveKind, path: string, content: Buffer, entry: string, cap: number): Result<Buffer, EntryRefusal>;

package/dist/tools/script/archive.js

@@ -0,0 +1,182 @@
+/**
+ * The entries of a compressed file, for the read tools of a script: a zip, a tar, a gzip-compressed tar, or one
+ * gzip-compressed file.
+ *
+ * Each read runs on the host and holds the bytes in memory, thus each one has a cap. A zip names the size of each
+ * entry in its index, thus a list reads no entry and a read decompresses one entry. A tar has no index, thus a list
+ * and a read of a `.tar.gz` decompress the whole stream, up to {@link ARCHIVE_SCAN_CAP_BYTES}.
+ */
+import { basename } from "node:path";
+import { gunzipSync } from "node:zlib";
+import { unzipSync } from "fflate";
+import { err, ok } from "neverthrow";
+/** The cap of the decompressed stream of a gzip-compressed tar or file that a list or a read decompresses. */
+export const ARCHIVE_SCAN_CAP_BYTES = 64 * 1024 * 1024;
+/** The kind of a compressed file by its name, or `undefined` for a file that is not one. */
+export function archiveKindOf(path) {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".zip"))
+        return "zip";
+    if (lower.endsWith(".tar"))
+        return "tar";
+    if (lower.endsWith(".tar.gz") || lower.endsWith(".tgz"))
+        return "tar-gzip";
+    if (lower.endsWith(".gz"))
+        return "gzip";
+    return undefined;
+}
+/** The one entry of a gzip-compressed file: its name with no `.gz`. */
+export function gzipEntryName(path) {
+    return basename(path).slice(0, -".gz".length);
+}
+/** The decompressed bytes of a gzip stream, or `too_large` past `cap`. */
+function gunzip(content, cap) {
+    try {
+        return ok(gunzipSync(content, { maxOutputLength: cap }));
+    }
+    catch (cause) {
+        if (cause instanceof RangeError)
+            return err({ kind: "too_large", bytes: undefined });
+        return err({ kind: "unparsable", detail: "the gzip stream is damaged" });
+    }
+}
+const TAR_BLOCK = 512;
+/** One text field of a tar header: the bytes up to the first NUL. */
+function tarText(block, start, length) {
+    const field = block.subarray(start, start + length);
+    const end = field.indexOf(0);
+    return field.subarray(0, end === -1 ? field.length : end).toString("utf8");
+}
+/** The `path` record of a pax extended header, which names an entry longer than the header field holds. */
+function paxPath(data) {
+    for (const line of data.toString("utf8").split("\n")) {
+        const record = line.slice(line.indexOf(" ") + 1);
+        if (record.startsWith("path="))
+            return record.slice("path=".length);
+    }
+    return undefined;
+}
+/**
+ * Each regular file of a tar, with its data. A GNU long name and a pax `path` record rename the entry that follows
+ * them. A directory, a link, and each other special entry is no file, thus it is skipped.
+ */
+function tarFiles(tar) {
+    const files = [];
+    let offset = 0;
+    let longName;
+    while (offset + TAR_BLOCK <= tar.length) {
+        const header = tar.subarray(offset, offset + TAR_BLOCK);
+        if (header.every((byte) => byte === 0))
+            break;
+        const size = Number.parseInt(tarText(header, 124, 12).trim() || "0", 8);
+        if (!Number.isSafeInteger(size) || size < 0)
+            return err({ kind: "unparsable", detail: "a tar header has no valid size" });
+        const dataStart = offset + TAR_BLOCK;
+        if (dataStart + size > tar.length)
+            return err({ kind: "unparsable", detail: "the tar ends inside an entry" });
+        const data = tar.subarray(dataStart, dataStart + size);
+        const type = String.fromCharCode(header[156] ?? 0);
+        const prefix = tarText(header, 257, 6) === "ustar" ? tarText(header, 345, 155) : "";
+        const name = longName ?? (prefix === "" ? tarText(header, 0, 100) : `${prefix}/${tarText(header, 0, 100)}`);
+        if (type === "L")
+            longName = tarText(data, 0, data.length);
+        else if (type === "x")
+            longName = paxPath(data) ?? longName;
+        else {
+            longName = undefined;
+            if (type === "0" || type === "\0")
+                files.push({ name, data });
+        }
+        offset = dataStart + Math.ceil(size / TAR_BLOCK) * TAR_BLOCK;
+    }
+    return ok(files);
+}
+/** The tar inside a tar archive: the bytes themselves, or the decompressed stream of a `.tar.gz`. */
+function tarOf(kind, content) {
+    return kind === "tar" ? ok(content) : gunzip(content, ARCHIVE_SCAN_CAP_BYTES);
+}
+/** The files of a zip, as its index names them. A directory entry is no file. */
+function zipIndex(content) {
+    const entries = [];
+    try {
+        unzipSync(content, {
+            filter: (file) => {
+                if (!file.name.endsWith("/"))
+                    entries.push({ name: file.name, bytes: file.originalSize });
+                return false;
+            },
+        });
+    }
+    catch {
+        return err({ kind: "unparsable", detail: "the zip is damaged" });
+    }
+    return ok(entries);
+}
+/** Each file of a compressed file, with its decompressed size. */
+export function listArchive(kind, path, content) {
+    switch (kind) {
+        case "zip":
+            return zipIndex(content);
+        case "gzip": {
+            // The last 4 bytes of a gzip stream hold the decompressed size, modulo 2^32.
+            const bytes = content.length >= 4 ? content.readUInt32LE(content.length - 4) : 0;
+            return ok([{ name: gzipEntryName(path), bytes }]);
+        }
+        case "tar":
+        case "tar-gzip":
+            return tarOf(kind, content)
+                .andThen(tarFiles)
+                .map((files) => files.map((file) => ({ name: file.name, bytes: file.data.length })));
+        default: {
+            const unhandled = kind;
+            throw new Error(`unhandled archive kind: ${String(unhandled)}`);
+        }
+    }
+}
+/** The decompressed bytes of one entry, up to `cap`. */
+export function readArchiveEntry(kind, path, content, entry, cap) {
+    switch (kind) {
+        case "zip": {
+            const index = zipIndex(content);
+            if (index.isErr())
+                return err(index.error);
+            const found = index.value.find((file) => file.name === entry);
+            if (found === undefined)
+                return err({ kind: "not_found" });
+            if (found.bytes > cap)
+                return err({ kind: "too_large", bytes: found.bytes });
+            try {
+                const data = unzipSync(content, { filter: (file) => file.name === entry })[entry];
+                if (data === undefined)
+                    return err({ kind: "not_found" });
+                // The index can lie about the size, thus the cap holds on the bytes too.
+                if (data.length > cap)
+                    return err({ kind: "too_large", bytes: data.length });
+                return ok(Buffer.from(data.buffer, data.byteOffset, data.length));
+            }
+            catch {
+                return err({ kind: "unparsable", detail: `the entry ${entry} did not decompress` });
+            }
+        }
+        case "gzip":
+            if (entry !== gzipEntryName(path))
+                return err({ kind: "not_found" });
+            return gunzip(content, cap);
+        case "tar":
+        case "tar-gzip": {
+            const files = tarOf(kind, content).andThen(tarFiles);
+            if (files.isErr())
+                return err(files.error);
+            const found = files.value.find((file) => file.name === entry);
+            if (found === undefined)
+                return err({ kind: "not_found" });
+            if (found.data.length > cap)
+                return err({ kind: "too_large", bytes: found.data.length });
+            return ok(found.data);
+        }
+        default: {
+            const unhandled = kind;
+            throw new Error(`unhandled archive kind: ${String(unhandled)}`);
+        }
+    }
+}

package/dist/tools/script/file-tools.d.ts

@@ -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.
@@ -44,9 +45,12 @@ export type ScriptFileToolsDeps = {
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
     readonly scratch: ScriptScratch;
 };
-/** The rows of one table, the bytes that they came from, and the columns that they keep. */
+/**
+ * The rows of one table, the columns that they keep, and the bytes of the file on disk that held them. A read of an
+ * entry names the compressed file, thus its hash is the hash of that file.
+ */
 export type TableRows = {
-    readonly content: Buffer;
+    readonly source: Buffer;
     readonly columns: string[];
     readonly rows: Row[];
 };
@@ -58,6 +62,7 @@ export declare function readTableRows(args: {
     readonly workspaceFs: WorkspaceFilesystem;
     readonly session: AgentSession;
     readonly path: string;
+    readonly entry?: string;
     readonly columns: readonly string[] | undefined;
     readonly tooLarge: string;
 }): Promise<Result<TableRows, string>>;
@@ -69,6 +74,7 @@ export declare const ReadTableOutputSchema: z.ZodObject<{
 }, z.core.$strip>;
 declare const readPdfInput: z.ZodObject<{
     path: z.ZodString;
+    entry: z.ZodOptional<z.ZodString>;
     firstPage: z.ZodOptional<z.ZodNumber>;
     lastPage: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
@@ -93,7 +99,7 @@ export type DocumentToolsDeps = ScriptFileToolsDeps & {
     readonly imageScope?: (session: AgentSession) => string | undefined;
 };
 export declare function createScriptFileTools(deps: ScriptFileToolsDeps): Tool[];
-/** 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 declare function createReadScriptTools(deps: Pick<ScriptFileToolsDeps, "workspaceFs" | "resolveWorkspaceRoot">): Tool[];
 /** The tools that make a document in a script: a chart as an SVG file, and a PDF from markdown. */
 export declare function createDocumentTools(deps: DocumentToolsDeps): Tool[];

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;
+}