@inflexa-ai/harness 0.46.2 → 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/codemode-worker.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The entry of the worker thread of `run_script`. An embedder that bundles the harness, for example a Bun single-file
+ * binary, adds this module as an entry of its build, and gives its embedded path as `ScriptRuntime.workerUrl`.
+ */
+import "@earendil-works/pi-codemode/worker";

package/dist/tools/script/codemode-worker.js

@@ -0,0 +1,5 @@
+/**
+ * The entry of the worker thread of `run_script`. An embedder that bundles the harness, for example a Bun single-file
+ * binary, adds this module as an entry of its build, and gives its embedded path as `ScriptRuntime.workerUrl`.
+ */
+import "@earendil-works/pi-codemode/worker";

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

@@ -0,0 +1,106 @@
+/**
+ * The file tools of a script: `read_table`, `read_pdf`, `write_derived`, `render_chart`, and `export_pdf`.
+ *
+ * The VM of `run_script` has no file system. These tools are its only reach into the workspace, thus each one is
+ * the boundary. `read_table` reads through the read seam of the workspace, which confines a path to the analysis
+ * of the call and refuses a symbolic link. `write_derived` and `render_chart` write only into the `derived/`
+ * 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. `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.
+ */
+import { type Result } from "neverthrow";
+import { z } from "zod";
+import type { AgentSession } from "../../auth/types.js";
+import { type Row } from "../../report-model/production-resolver.js";
+import type { WorkspaceReadLineage } from "../../provenance/workspace-reads.js";
+import type { WorkspaceFilesystem } from "../../workspace/filesystem.js";
+import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
+import { type Tool, type WithToolCallRecord } from "../define-tool.js";
+import type { ScratchFile, ScriptRead, ScriptScratch } from "./scratch.js";
+/** The cap of one table read. It matches the cap of the report path, which reads with the same parsers. */
+export declare const TABLE_READ_CAP_BYTES: number;
+/** What one call of a file tool did to files. `run_script` reads it from the call record of a nested call. */
+export type ScriptFileEffect = {
+    readonly reads?: readonly ScriptRead[];
+    readonly writes?: readonly ScratchFile[];
+};
+export declare const ScriptFileEffectSchema: z.ZodObject<{
+    reads: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        hash: z.ZodString;
+    }, z.core.$strip>>>;
+    writes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        hash: z.ZodString;
+        size: z.ZodNumber;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ScriptFileToolsDeps = {
+    readonly workspaceFs: WorkspaceFilesystem;
+    readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    readonly scratch: ScriptScratch;
+};
+/**
+ * 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 source: Buffer;
+    readonly columns: string[];
+    readonly rows: Row[];
+};
+/**
+ * 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 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>>;
+export declare const ReadTableOutputSchema: z.ZodObject<{
+    path: z.ZodString;
+    columns: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    rowCount: z.ZodNumber;
+    rows: z.ZodReadonly<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>>;
+}, 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>;
+declare const ReadPdfOutputSchema: z.ZodObject<{
+    path: z.ZodString;
+    totalPages: z.ZodNumber;
+    pages: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        page: z.ZodNumber;
+        text: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+type ReadPdfOutput = WithToolCallRecord<z.infer<typeof ReadPdfOutputSchema>, ScriptFileEffect>;
+/** `lineage` records each read in the lineage of a step. */
+export declare function createReadPdfTool(deps: Pick<ScriptFileToolsDeps, "workspaceFs" | "resolveWorkspaceRoot"> & {
+    readonly lineage?: WorkspaceReadLineage;
+}): Tool<z.infer<typeof readPdfInput>, ReadPdfOutput>;
+export type Cell = string | number | boolean | null;
+/** The text of `rows` in the format that the extension of `name` names, or `undefined` for another extension. */
+export declare function rowsText(name: string, rows: readonly Record<string, Cell>[]): string | undefined;
+/** What the document tools of a script need. `imageScope` limits the images of a PDF to one directory of a session. */
+export type DocumentToolsDeps = ScriptFileToolsDeps & {
+    readonly imageScope?: (session: AgentSession) => string | undefined;
+};
+export declare function createScriptFileTools(deps: ScriptFileToolsDeps): Tool[];
+/** 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[];
+export {};