@foldrun/core 0.6.0 → 0.7.0

package/dist/src/storage.d.ts

@@ -128,6 +128,10 @@ export declare function uploadUrl(tenant: string, workspace: string, rel: string
  * is worth writing when a workspace actually outgrows its quota, not before.
  */
 export declare function materializeFiles(tenant: string, workspace: string): Promise<string[]>;
+/** path → sha of every stored file: what `storage/` holds once
+ *  materializeFiles has run. A run keeps it to tell its own writes from the
+ *  files it was handed. */
+export declare function storageBaseline(tenant: string, workspace: string): Record<string, string>;
 /**
  * Take what the run left in `storage/` back into the store, stamped with the
  * run that wrote it.
@@ -136,7 +140,9 @@ export declare function materializeFiles(tenant: string, workspace: string): Pro
  * derived from the index, so anything on disk that the index does not already
  * describe with the same size and hash is, by construction, new work.
  */
-export declare function harvestFiles(tenant: string, workspace: string, by: string): Promise<{
+export declare function harvestFiles(tenant: string, workspace: string, by: string, opts?: {
+    changedFrom?: Record<string, string>;
+}): Promise<{
     saved: string[];
     errors: string[];
 }>;

package/dist/src/storage.js

@@ -686,6 +686,14 @@ export async function materializeFiles(tenant, workspace) {
     fs.mkdirSync(root, { recursive: true });
     return brought;
 }
+/** path → sha of every stored file: what `storage/` holds once
+ *  materializeFiles has run. A run keeps it to tell its own writes from the
+ *  files it was handed. */
+export function storageBaseline(tenant, workspace) {
+    if (!fileStoreEnabled())
+        return {};
+    return Object.fromEntries(readIndex(tenant, workspace).files.map((f) => [f.path, f.sha]));
+}
 /**
  * Take what the run left in `storage/` back into the store, stamped with the
  * run that wrote it.
@@ -694,7 +702,7 @@ export async function materializeFiles(tenant, workspace) {
  * derived from the index, so anything on disk that the index does not already
  * describe with the same size and hash is, by construction, new work.
  */
-export async function harvestFiles(tenant, workspace, by) {
+export async function harvestFiles(tenant, workspace, by, opts = {}) {
     if (!fileStoreEnabled())
         return { saved: [], errors: [] };
     adoptLegacyFilesDir(workspaceDir(tenant, workspace));
@@ -729,6 +737,11 @@ export async function harvestFiles(tenant, workspace, by) {
                 if (sha256(fs.readFileSync(abs)) === previous.sha)
                     continue;
             }
+            // Only what the run itself changed: a file still holding the bytes it
+            // was handed is not this run's work, and the index may have moved on
+            // since (an upload while the run was going) — that must win.
+            if (opts.changedFrom && opts.changedFrom[norm] === sha256(fs.readFileSync(abs)))
+                continue;
             await putFileQuietly(tenant, workspace, norm, fs.readFileSync(abs), by);
             saved.push(norm);
         }

package/dist/src/store.d.ts

@@ -188,6 +188,15 @@ export declare function fencedCodeBlock(body: string): {
  * failure costs something that cannot be taken back. See `lintFlow`.
  */
 export declare function toolIsOutward(data: Record<string, unknown>): boolean;
+/** How much of a tool.md body rides to the model with the tool. */
+export declare const TOOL_GUIDE_MAX = 6000;
+/**
+ * The prose under a tool.md's frontmatter: how to call it, what it refuses,
+ * what its output means. Only `description:` used to reach the model, so
+ * agents invented what the body documented (5 Oct 2026). The fenced program
+ * of a single-file tool is code, not guidance, and stays out.
+ */
+export declare function toolGuide(body: string | undefined, inlineProgram?: boolean): string | undefined;
 export declare function parseToolDef(data: Record<string, unknown>, fallbackName: string, body?: string): ToolDef | null;
 /**
  * Tools in a directory, in both shapes.
@@ -234,6 +243,8 @@ export interface ApiSpec {
     name: string;
     base: string;
     description: string;
+    /** The tool.md body, for the model (see toolGuide). */
+    guide?: string;
     headers: Record<string, string>;
     query: Record<string, string>;
     methods: string[];
@@ -846,6 +857,9 @@ export declare function setWorkspaceDescription(tenant: string, workspace: strin
  * this copy still said `type: Agent` after the CLI's had moved to `kind:`,
  * so every workspace made from the dashboard was born in the old format.
  */
+/** What the dashboard's "Create workspace" makes: blank (blankWorkspaceFiles),
+ *  minus the laptop-only files, for the same reason as templateFiles. */
+export declare function blankTemplateFiles(workspace: string): DeployFile[];
 export declare function templateFiles(workspace: string): DeployFile[];
 export declare const AGENT_TEMPLATE: (name: string) => string;
 export declare const FLOW_TEMPLATE: (name: string, firstAgent: string) => string;
@@ -1341,6 +1355,12 @@ export declare function runCost(run: RunRecord): number;
  * fan-out template is a row in the trace rather than work — billing any of
  * them would charge for steps the customer can see never executed, which is
  * the fastest way to lose an argument about an invoice.
+ *
+ * Tokens count only for steps that ran on the platform's own model
+ * credential. A step on the account's own key (`credential` "provider: …" —
+ * a provider: block, or Settings → Model) was paid for at the provider, and
+ * billing it again here charged a BYOK customer twice. And a carried step's
+ * tokens were billed where it ran, like its compute.
  */
 export declare function runMeter(run: RunRecord): {
     tokenCostUsd: number;

package/dist/src/store.js

@@ -19,6 +19,7 @@
 // or an agent, and belongs in git.
 //
 // An account is a named directory (per OKF: tenancy is a hosting concern).
+import { expandPlatformVars } from "./host-env.js";
 import fs from "node:fs";
 import path from "node:path";
 import { recordRevision, registerTreeReader } from "./history.js";
@@ -50,7 +51,7 @@ import { localeProblems } from "./locale.js";
 import { readBundle, syncIndex, appendLog, provenanceMarks, syncWorkspaceBundles, } from "./okf.js";
 import { readTransport, KINDS } from "./kinds.js";
 import { providerPreset, looksOpenAiShaped, PROTECTED_PARAMS } from "./providers.js";
-import { starterFiles, accountFiles } from "./starter.js";
+import { starterFiles, accountFiles, blankWorkspaceFiles } from "./starter.js";
 import { trimSlashes, MAX_EDITABLE_FILE } from "./paths.js";
 // Where workspaces live. The hosted app keeps many under data/; the CLI runs
 // against one folder, which is what `foldrun run ./my-desk` has to mean.
@@ -288,6 +289,18 @@ export function assertCanonicalCase(rel) {
 // trigger-log.jsonl: the scheduler's record of why a flow did or did not
 // fire (trigger-log.ts). Before it was listed here every deploy erased it.
 export const PLATFORM_FILES = ["secrets.json", "hooks.json", "hook-deliveries.jsonl", ".repo.json", "trigger-log.jsonl"];
+// The agent engine's own home files. Each step's sandbox runs the Claude
+// Agent SDK — the engine, whatever model answers — with its home in the
+// agent's folder, and the engine writes its settings (.claude.json, its
+// backups), plugin caches and the full transcript of every session
+// (.claude/projects/*.jsonl) there. Nothing in foldrun reads them. Copied
+// back after every step, they had piled up to 5,274 files and 19 MB in one
+// agent's folder on the box by 6 Oct 2026, carried every past conversation
+// into every sandbox, and their clashing rewrites were the "write-back
+// conflict on .claude.json" lines (and the big merges) of that day. A
+// workspace's own .claude/agents/*.md — Claude Code subagents an author
+// writes, imported as agents — sits at the workspace root and is untouched.
+const ENGINE_HOME_RE = /^agents\/[^/]+\/\.claude([./]|$)/;
 /** True for anything the platform, not the author or the agent, writes. */
 export function isPlatformPath(rel) {
     const norm = rel.replaceAll("\\", "/");
@@ -299,6 +312,8 @@ export function isPlatformPath(rel) {
         return true;
     if (norm === "trigger-log.jsonl.tmp")
         return true;
+    if (ENGINE_HOME_RE.test(norm))
+        return true;
     return norm === "runs" || norm.startsWith("runs/") || norm === ".foldrun" || norm.startsWith(".foldrun/");
 }
 /** What a deploy keeps whatever it ships — the rule above saveWorkspace's
@@ -547,6 +562,28 @@ export function fencedCodeBlock(body) {
 export function toolIsOutward(data) {
     return data.outward === true;
 }
+/** How much of a tool.md body rides to the model with the tool. */
+export const TOOL_GUIDE_MAX = 6000;
+/**
+ * The prose under a tool.md's frontmatter: how to call it, what it refuses,
+ * what its output means. Only `description:` used to reach the model, so
+ * agents invented what the body documented (5 Oct 2026). The fenced program
+ * of a single-file tool is code, not guidance, and stays out.
+ */
+export function toolGuide(body, inlineProgram = false) {
+    if (!body)
+        return undefined;
+    let text = body.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "");
+    // Only a single-file tool's program is cut; in a `run:` tool every fenced
+    // block is an example of a call, which is exactly what the model needs.
+    const inline = inlineProgram ? fencedCodeBlock(text) : null;
+    if (inline)
+        text = text.slice(0, inline.start) + text.slice(inline.end);
+    text = text.trim();
+    if (!text)
+        return undefined;
+    return text.length > TOOL_GUIDE_MAX ? `${text.slice(0, TOOL_GUIDE_MAX)}\n\n[the rest of tool.md is cut here]` : text;
+}
 export function parseToolDef(data, fallbackName, body) {
     const name = typeof data.name === "string" ? data.name : fallbackName;
     // `transport:`, or a legacy `type: http|script|mcp` from before `type:` meant
@@ -580,18 +617,28 @@ export function parseToolDef(data, fallbackName, body) {
         };
     }
     if (kind === "script") {
+        // `guide` is the body's, never the frontmatter's: an author's `guide:`
+        // would otherwise ride to the model in place of the manual.
+        if ("guide" in data) {
+            data = { ...data };
+            delete data.guide;
+        }
         // The program is a run: path, or the file's own fenced code block — the
         // single-file form, which is what lets a script tool read and edit like
         // every other markdown document.
-        if (typeof data.run === "string")
-            return { kind: "script", name, spec: { ...data, name } };
+        if (typeof data.run === "string") {
+            const guide = toolGuide(body);
+            return { kind: "script", name, spec: { ...data, name, ...(guide ? { guide } : {}) } };
+        }
         const inline = body ? fencedCode(body) : null;
         if (!inline)
             return null;
-        return { kind: "script", name, spec: { ...data, name, code: inline.code, codeExt: inline.ext } };
+        const guide = toolGuide(body, true);
+        return { kind: "script", name, spec: { ...data, name, code: inline.code, codeExt: inline.ext, ...(guide ? { guide } : {}) } };
     }
     const [spec] = parseApis([{ ...data, name }]);
-    return spec ? { kind: "http", name, spec } : null;
+    const guide = toolGuide(body);
+    return spec ? { kind: "http", name, spec: guide ? { ...spec, guide } : spec } : null;
 }
 /**
  * Tools in a directory, in both shapes.
@@ -955,7 +1002,9 @@ export function parseApis(raw) {
         out.push({
             name: name.replace(/[^a-zA-Z0-9_]/g, "_"),
             ...(Number(e.timeout) > 0 ? { timeout: Number(e.timeout) } : {}),
-            base: trimSlashes(base),
+            // `${FOLDRUN_API_URL}` and `${FOLDRUN_PUBLIC_URL}` are the install's own
+            // addresses, filled here on the host so a desk never names one.
+            base: trimSlashes(expandPlatformVars(base)),
             description: typeof e.description === "string" ? e.description : "",
             headers: asRecordLocal(e.headers),
             query: asRecordLocal(e.query),
@@ -2430,6 +2479,11 @@ export function setWorkspaceDescription(tenant, workspace, description) {
  * this copy still said `type: Agent` after the CLI's had moved to `kind:`,
  * so every workspace made from the dashboard was born in the old format.
  */
+/** What the dashboard's "Create workspace" makes: blank (blankWorkspaceFiles),
+ *  minus the laptop-only files, for the same reason as templateFiles. */
+export function blankTemplateFiles(workspace) {
+    return blankWorkspaceFiles(workspace).filter((f) => f.path === "AGENTS.md" || IN_WORKSPACE_DIR.test(f.path));
+}
 export function templateFiles(workspace) {
     // The starter minus what only matters on a laptop's disk: .gitignore
     // guards a local clone's secrets, but the hosted store never keeps
@@ -2579,7 +2633,25 @@ export function runOutputPath(tenant, workspace, runId, agent, rel) {
 }
 export function readRun(tenant, workspace, runId) {
     const p = runFilePath(tenant, workspace, runId);
-    return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, "utf8")) : null;
+    // EFS/NFS: writeRun() replaces this file by rename, so an open()+read()
+    // here can land on the just-unlinked inode and come back ESTALE (errno
+    // -116, surfaced by Node as "Unknown system error -116", syscall read).
+    // That isn't corruption — the next open() by path sees the committed new
+    // inode — so re-read a few times on ESTALE and rethrow anything else.
+    // (On dev-aws this surfaced as a CLI `--wait` call returning HTTP 500
+    // from waitForRun's poll while the run itself completed fine.)
+    const attempts = 5;
+    for (let i = 1;; i++) {
+        try {
+            return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, "utf8")) : null;
+        }
+        catch (e) {
+            const err = e;
+            if ((err.code === "ESTALE" || err.errno === -116) && i < attempts)
+                continue;
+            throw e;
+        }
+    }
 }
 export function writeRun(tenant, workspace, run) {
     const p = runFilePath(tenant, workspace, run.id);
@@ -2825,12 +2897,19 @@ export function runCost(run) {
  * fan-out template is a row in the trace rather than work — billing any of
  * them would charge for steps the customer can see never executed, which is
  * the fastest way to lose an argument about an invoice.
+ *
+ * Tokens count only for steps that ran on the platform's own model
+ * credential. A step on the account's own key (`credential` "provider: …" —
+ * a provider: block, or Settings → Model) was paid for at the provider, and
+ * billing it again here charged a BYOK customer twice. And a carried step's
+ * tokens were billed where it ran, like its compute.
  */
 export function runMeter(run) {
     let steps = 0;
     let computeSecs = 0;
     let smallSecs = 0;
     let netBytes = 0;
+    let tokenCostUsd = 0;
     for (const s of run.steps) {
         if (s.status !== "completed" && s.status !== "failed")
             continue;
@@ -2838,13 +2917,15 @@ export function runMeter(run) {
         if (s.carriedFrom)
             continue;
         steps += 1;
+        if (!(s.credential ?? "").startsWith("provider:"))
+            tokenCostUsd += s.costUsd ?? 0;
         const secs = s.computeSecs ?? 0;
         computeSecs += secs;
         if (s.size === "small")
             smallSecs += secs;
         netBytes += (s.actual?.rxBytes ?? 0) + (s.actual?.txBytes ?? 0);
     }
-    return { tokenCostUsd: runCost(run), steps, computeSecs, smallSecs, netBytes };
+    return { tokenCostUsd, steps, computeSecs, smallSecs, netBytes };
 }
 /**
  * The compute meter for hold+work pricing: core-seconds and GiB-seconds

package/dist/src/tool-names.d.ts

@@ -12,7 +12,9 @@ export declare const RETIRED_TOOLS: Record<string, string>;
  *  and a model provider's own search (`web: {search: zai}`) is the runtime's
  *  to swap in, not the author's to name. */
 export declare const BUILTIN_TOOLS: Set<string>;
-/** The platform's own groups, served in-process rather than by the SDK. */
+/** The platform's own groups, served in-process rather than by the SDK.
+ *  `install` is granted to every agent anyway (install-tool.ts); naming it is
+ *  accepted so a file that says so is not flagged. */
 export declare const PLATFORM_GROUPS: Set<string>;
 /** Would this name resolve to something the runtime provides? Built-ins win a
  *  clash, so a tool file of the same name is shadowed rather than granted. */

package/dist/src/tool-names.js

@@ -44,8 +44,10 @@ export const BUILTIN_TOOLS = new Set([
     "Read", "Write", "Edit", "MultiEdit", "Glob", "Grep", "Bash",
     "NotebookEdit", "TodoWrite",
 ]);
-/** The platform's own groups, served in-process rather than by the SDK. */
-export const PLATFORM_GROUPS = new Set(["search", "history", "desks", "ask"]);
+/** The platform's own groups, served in-process rather than by the SDK.
+ *  `install` is granted to every agent anyway (install-tool.ts); naming it is
+ *  accepted so a file that says so is not flagged. */
+export const PLATFORM_GROUPS = new Set(["search", "history", "desks", "ask", "install"]);
 /** Would this name resolve to something the runtime provides? Built-ins win a
  *  clash, so a tool file of the same name is shadowed rather than granted. */
 export function isRuntimeTool(name) {

package/dist/src/tool-test.js

@@ -229,7 +229,14 @@ export async function testTool(tenant, workspace, def, input = {}) {
                 detail: `looked for ${file}\n\nThis is the commonest way to get a tool that silently never loads.`,
             });
         }
-        const names = Array.isArray(def.spec.secrets) ? def.spec.secrets.map(String) : [];
+        // The tool's own secrets, and the calling agent's `secrets:` — a run
+        // hands a script both. Testing gbp_read (whose agent, not the tool,
+        // declares GBP_OAUTH) said "GBP_OAUTH is not set" while every run of the
+        // same call worked (9 Oct 2026). Only an agent that grants the tool: the
+        // agents[0] stand-in above is there for its depth, not its keys.
+        const own = Array.isArray(def.spec.secrets) ? def.spec.secrets.map(String) : [];
+        const granting = caller && caller.ownTools.includes(def.name) ? caller.secrets : [];
+        const names = [...new Set([...own, ...granting])];
         const { env: stored, missing } = resolveSecrets(tenant, names, workspace);
         const live = await liveSecrets(stored, { tenant, workspace });
         if ("error" in live) {

package/dist/src/zip.d.ts

@@ -0,0 +1,17 @@
+export interface ZipEntry {
+    path: string;
+    data: Buffer;
+}
+export declare class ZipError extends Error {
+}
+export interface UnzipLimits {
+    /** Most entries the archive may hold. */
+    maxEntries?: number;
+    /** Largest one file, uncompressed. */
+    maxFileBytes?: number;
+    /** All files together, uncompressed. */
+    maxTotalBytes?: number;
+}
+export declare function crc32(buf: Buffer): number;
+export declare function zip(entries: ZipEntry[], now?: Date): Buffer;
+export declare function unzip(buf: Buffer, limits?: UnzipLimits): ZipEntry[];

package/dist/src/zip.js

@@ -0,0 +1,184 @@
+// A small zip reader and writer — enough for an export package, no dependency.
+//
+// What a person downloads from "Export" has to open with a double-click on
+// any machine, which is a zip, not a tarball. The format here is the plain
+// one: deflate or stored entries, a central directory, no zip64, no
+// encryption. The reader refuses anything outside that rather than guessing,
+// and it is written to be handed untrusted bytes: every offset is bounds
+// checked, sizes are capped before anything is inflated, and a path that
+// climbs out (`..`, absolute, a drive letter) is an error, not a skip.
+import zlib from "node:zlib";
+export class ZipError extends Error {
+}
+const CRC_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+export function crc32(buf) {
+    let c = 0xffffffff;
+    for (let i = 0; i < buf.length; i++)
+        c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+/** DOS date and time for the entry headers. */
+function dosTime(d) {
+    return {
+        time: (d.getHours() << 11) | (d.getMinutes() << 5) | Math.floor(d.getSeconds() / 2),
+        date: (Math.max(0, d.getFullYear() - 1980) << 9) | ((d.getMonth() + 1) << 5) | d.getDate(),
+    };
+}
+export function zip(entries, now = new Date()) {
+    const { time, date } = dosTime(now);
+    const locals = [];
+    const centrals = [];
+    let offset = 0;
+    const seen = new Set();
+    for (const e of entries) {
+        const name = safeEntryPath(e.path);
+        if (seen.has(name))
+            throw new ZipError(`duplicate entry: ${name}`);
+        seen.add(name);
+        const nameBuf = Buffer.from(name, "utf8");
+        const deflated = zlib.deflateRawSync(e.data);
+        const stored = deflated.length >= e.data.length;
+        const body = stored ? e.data : deflated;
+        const crc = crc32(e.data);
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(0x04034b50, 0);
+        local.writeUInt16LE(20, 4); // version needed
+        local.writeUInt16LE(0x0800, 6); // UTF-8 names
+        local.writeUInt16LE(stored ? 0 : 8, 8);
+        local.writeUInt16LE(time, 10);
+        local.writeUInt16LE(date, 12);
+        local.writeUInt32LE(crc, 14);
+        local.writeUInt32LE(body.length, 18);
+        local.writeUInt32LE(e.data.length, 22);
+        local.writeUInt16LE(nameBuf.length, 26);
+        local.writeUInt16LE(0, 28);
+        locals.push(local, nameBuf, body);
+        const central = Buffer.alloc(46);
+        central.writeUInt32LE(0x02014b50, 0);
+        central.writeUInt16LE(0x0314, 4); // made by: unix, 2.0
+        central.writeUInt16LE(20, 6);
+        central.writeUInt16LE(0x0800, 8);
+        central.writeUInt16LE(stored ? 0 : 8, 10);
+        central.writeUInt16LE(time, 12);
+        central.writeUInt16LE(date, 14);
+        central.writeUInt32LE(crc, 16);
+        central.writeUInt32LE(body.length, 20);
+        central.writeUInt32LE(e.data.length, 24);
+        central.writeUInt16LE(nameBuf.length, 28);
+        central.writeUInt32LE((0o100644 << 16) >>> 0, 38); // a regular file, rw-r--r--
+        central.writeUInt32LE(offset, 42);
+        centrals.push(central, nameBuf);
+        offset += local.length + nameBuf.length + body.length;
+    }
+    const cd = Buffer.concat(centrals);
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(0x06054b50, 0);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(cd.length, 12);
+    end.writeUInt32LE(offset, 16);
+    return Buffer.concat([...locals, cd, end]);
+}
+export function unzip(buf, limits = {}) {
+    const maxEntries = limits.maxEntries ?? 2000;
+    const maxFile = limits.maxFileBytes ?? 1024 * 1024;
+    const maxTotal = limits.maxTotalBytes ?? 50 * 1024 * 1024;
+    // The end-of-central-directory record: within the last 22 + 65535 bytes.
+    let eocd = -1;
+    for (let i = buf.length - 22; i >= Math.max(0, buf.length - 22 - 0xffff); i--) {
+        if (buf.readUInt32LE(i) === 0x06054b50) {
+            eocd = i;
+            break;
+        }
+    }
+    if (eocd < 0)
+        throw new ZipError("not a zip file");
+    const count = buf.readUInt16LE(eocd + 10);
+    const cdSize = buf.readUInt32LE(eocd + 12);
+    const cdOffset = buf.readUInt32LE(eocd + 16);
+    if (count === 0xffff || cdOffset === 0xffffffff)
+        throw new ZipError("zip64 archives are not supported");
+    if (count > maxEntries)
+        throw new ZipError(`too many files: ${count} (at most ${maxEntries})`);
+    if (cdOffset + cdSize > eocd)
+        throw new ZipError("corrupt zip: central directory out of range");
+    const out = [];
+    const seen = new Set();
+    let total = 0;
+    let p = cdOffset;
+    for (let n = 0; n < count; n++) {
+        if (p + 46 > eocd || buf.readUInt32LE(p) !== 0x02014b50)
+            throw new ZipError("corrupt zip: bad central directory entry");
+        const flags = buf.readUInt16LE(p + 8);
+        const method = buf.readUInt16LE(p + 10);
+        const crc = buf.readUInt32LE(p + 16);
+        const csize = buf.readUInt32LE(p + 20);
+        const usize = buf.readUInt32LE(p + 24);
+        const nameLen = buf.readUInt16LE(p + 28);
+        const extraLen = buf.readUInt16LE(p + 30);
+        const commentLen = buf.readUInt16LE(p + 32);
+        const localAt = buf.readUInt32LE(p + 42);
+        if (p + 46 + nameLen > eocd)
+            throw new ZipError("corrupt zip: name out of range");
+        const rawName = buf.subarray(p + 46, p + 46 + nameLen).toString("utf8");
+        p += 46 + nameLen + extraLen + commentLen;
+        if (rawName.endsWith("/"))
+            continue; // a directory entry
+        // macOS "Compress" adds these beside every file; they are not content.
+        if (/(^|\/)__MACOSX\//.test(rawName) || /(^|\/)\.DS_Store$/.test(rawName))
+            continue;
+        if (flags & 0x1)
+            throw new ZipError(`${rawName}: encrypted entries are not supported`);
+        if (method !== 0 && method !== 8)
+            throw new ZipError(`${rawName}: compression method ${method} is not supported`);
+        const name = safeEntryPath(rawName);
+        if (seen.has(name))
+            throw new ZipError(`duplicate entry: ${name}`);
+        seen.add(name);
+        if (usize > maxFile)
+            throw new ZipError(`${name} is too large (${usize} bytes, at most ${maxFile})`);
+        total += usize;
+        if (total > maxTotal)
+            throw new ZipError(`the files are too large together (more than ${maxTotal} bytes)`);
+        if (localAt + 30 > buf.length || buf.readUInt32LE(localAt) !== 0x04034b50)
+            throw new ZipError(`${name}: corrupt local header`);
+        const start = localAt + 30 + buf.readUInt16LE(localAt + 26) + buf.readUInt16LE(localAt + 28);
+        if (start + csize > buf.length)
+            throw new ZipError(`${name}: data out of range`);
+        const raw = buf.subarray(start, start + csize);
+        let data;
+        try {
+            // maxOutputLength: the header's size is the attacker's to choose, so the
+            // inflate itself is capped too — a bomb stops here, not in memory.
+            data = method === 0 ? Buffer.from(raw) : zlib.inflateRawSync(raw, { maxOutputLength: maxFile + 1 });
+        }
+        catch {
+            throw new ZipError(`${name}: could not be decompressed`);
+        }
+        if (data.length !== usize)
+            throw new ZipError(`${name}: size does not match its header`);
+        if (crc32(data) !== crc)
+            throw new ZipError(`${name}: checksum mismatch`);
+        out.push({ path: name, data });
+    }
+    return out;
+}
+/** A relative, forward-slash path that stays inside the archive's root. */
+function safeEntryPath(raw) {
+    const p = raw.replaceAll("\\", "/");
+    if (p.startsWith("/") || /^[a-zA-Z]:/.test(p) || p.includes("\0"))
+        throw new ZipError(`unsafe path: ${raw}`);
+    const parts = p.split("/").filter((s) => s !== "" && s !== ".");
+    if (parts.length === 0 || parts.some((s) => s === ".."))
+        throw new ZipError(`unsafe path: ${raw}`);
+    return parts.join("/");
+}

package/index.ts

@@ -34,6 +34,8 @@ export * from "./src/linkable.ts";
 export * from "./src/refs.ts";
 export * from "./src/tool-names.ts";
 export * from "./src/history.ts";
+export * from "./src/zip.ts";
+export * from "./src/package.ts";
 export * from "./src/gitrepo.ts";
 export * from "./src/storage.ts";
 export * from "./src/secrets.ts";
@@ -43,6 +45,7 @@ export * from "./src/notify.ts";
 export * from "./src/webhook.ts";
 export * from "./src/approvals.ts";
 export * from "./src/deploy.ts";
+export * from "./src/agent-import.ts";
 export * from "./src/account.ts";
 export * from "./src/tar.ts";
 export * from "./src/git.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Agents are just folders. The format, the runner, the checks.",
   "license": "Apache-2.0",
   "type": "module",