@foldrun/core 0.6.0 → 1.0.0

package/dist/src/runtime.js

@@ -43,9 +43,14 @@ import { spawnSync } from "node:child_process";
  */
 const PIP_NAME = String.raw `[A-Za-z0-9][A-Za-z0-9._-]*(\[[A-Za-z0-9._,-]+\])?`;
 const PIP_SPECIFIER = String.raw `(==|!=|<=|>=|~=|<|>)[A-Za-z0-9._*+!-]+`;
-const PIP_REQUIREMENT = new RegExp(`^${PIP_NAME}(${PIP_SPECIFIER}(,${PIP_SPECIFIER})*)?$`);
+export const PIP_REQUIREMENT = new RegExp(`^${PIP_NAME}(${PIP_SPECIFIER}(,${PIP_SPECIFIER})*)?$`);
 /** npm's own shape: an optional @scope, then a name, then an optional @range. */
-const NPM_REQUIREMENT = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(@[A-Za-z0-9._^~*>=< |-]+)?$/;
+export const NPM_REQUIREMENT = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(@[A-Za-z0-9._^~*>=< |-]+)?$/;
+/** A Debian package name as policy defines it: lowercase letters, digits,
+ *  `+`, `-` and `.`, starting with a letter or digit, two or more characters.
+ *  Like the two above, a guard first: it can never begin with a dash, so it
+ *  can never become an apt option, and it holds no shell characters. */
+export const DEB_PACKAGE = /^[a-z0-9][a-z0-9+.-]{1,62}$/;
 export function parseRuntime(raw) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw))
         return null;
@@ -67,11 +72,14 @@ export function parseRuntime(raw) {
         node: typeof e.node === "string" || typeof e.node === "boolean" ? e.node : undefined,
         npm: list(e.npm, NPM_REQUIREMENT),
     };
+    const system = list(e.system ?? e.apt, DEB_PACKAGE);
+    if (system.length)
+        spec.system = system;
     if (rejected.length)
         spec.rejected = rejected;
     if (Array.isArray(e.ignored) && e.ignored.length)
         spec.ignored = e.ignored.map(String);
-    return wantsPython(spec) || wantsNode(spec) ? spec : null;
+    return wantsPython(spec) || wantsNode(spec) || wantsSystem(spec) ? spec : null;
 }
 /**
  * Several declarations, one environment.
@@ -103,6 +111,9 @@ export function mergeRuntimes(...specs) {
         node: pick("node"),
         npm: uniq(present.flatMap((s) => s.npm)),
     };
+    const system = uniq(present.flatMap((s) => s.system ?? []));
+    if (system.length)
+        merged.system = system;
     const rejected = uniq(present.flatMap((s) => s.rejected ?? []));
     if (rejected.length)
         merged.rejected = rejected;
@@ -117,6 +128,11 @@ export function fingerprint(spec) {
         packages: [...spec.packages].sort(),
         node: spec.node ?? null,
         npm: [...spec.npm].sort(),
+        // Only when declared: adding the key unconditionally would give every
+        // environment already cached a new fingerprint and rebuild them all.
+        // Part of it when declared, because a venv whose packages compiled
+        // against these libraries is not the venv built without them.
+        ...(spec.system?.length ? { system: [...spec.system].sort() } : {}),
     });
     return crypto.createHash("sha256").update(canonical).digest("hex").slice(0, 16);
 }
@@ -210,6 +226,7 @@ function wire(root, spec, note) {
 }
 // `python: false` says "not this one" — it used to read as a declaration
 // because it was not undefined, and built a venv nobody asked for.
+const wantsSystem = (s) => (s.system?.length ?? 0) > 0;
 const wantsPython = (s) => (s.python !== undefined && s.python !== false) || s.packages.length > 0;
 const wantsNode = (s) => (s.node !== undefined && s.node !== false) || s.npm.length > 0;
 /** How long a build may hold the claim, and therefore how long another step
@@ -524,9 +541,197 @@ function findUv() {
     return uvKnown;
 }
 // Build (or reuse) the environment for one runtime declaration.
+/**
+ * An installer's failure, said so that the first line is the cause.
+ *
+ * Until 11 Oct 2026 a failure was the installer's last 500 characters, and
+ * the run log shows a message's first line: a pycairo build that died for
+ * want of a C compiler read, in full, `uv pip install failed: files.` — the
+ * tail end of a setuptools deprecation notice. The cause was on the last
+ * line of 4 KB nobody saw. So: find the cause and the package it hit, say
+ * the fix when it is one we know, then the last lines of the log for the rest.
+ */
+export function summarizeInstallFailure(what, out) {
+    const text = out ?? "";
+    const lines = text.split(/\r?\n/).map((l) => l.replace(/\s+$/, "")).filter(Boolean);
+    const pkg = /Failed to build `([^`]+)`/.exec(text)?.[1] ??
+        /Failed building wheel for ([\w.-]+)/.exec(text)?.[1] ??
+        /Building wheel for ([\w.-]+) \(.*\) did not run successfully/.exec(text)?.[1] ??
+        /Failed to (?:download|prepare|fetch) `([^`]+)`/.exec(text)?.[1] ??
+        null;
+    const subject = pkg ? `\`${pkg}\`` : "a package";
+    let cause = null;
+    let hint = "";
+    const header = /fatal error: ([\w./+-]+\.h): No such file/.exec(text);
+    const pc = /Package '?([\w.+-]+)'?,? (?:required by [^,]+, )?(?:was )?not found|Dependency "([\w.+-]+)" not found/.exec(text);
+    if (/No such file or directory: '[^']*gcc'|unable to execute '[^']*gcc'|\bgcc: (?:command )?not found|command '[^']*gcc' failed|error: command '[^']*\b(?:cc|gcc|c\+\+|g\+\+)' failed|C compiler cannot create executables|no acceptable C compiler/i.test(text)) {
+        cause = `${subject} has to be compiled and this runner has no C compiler`;
+        hint = " — add `system: [build-essential]` (and the -dev package of any library it builds against) to the runtime, or pin a version that ships a prebuilt wheel";
+    }
+    else if (/pkg-config(?:: command)? not found|Did not find pkg-config|pkg-config.*No such file/i.test(text)) {
+        cause = `${subject} looks for its libraries with pkg-config, which this runner lacks`;
+        hint = " — add `system: [pkg-config]` and the library's -dev package to the runtime";
+    }
+    else if (header && /^Python\.h$/.test(header[1])) {
+        cause = `${subject} builds against Python's own C headers, which this runner lacks`;
+        hint = " — add `system: [python3-dev, build-essential]` to the runtime";
+    }
+    else if (pc || header) {
+        const lib = pc?.[1] ?? pc?.[2] ?? header[1];
+        cause = `${subject} needs the system library ${lib} (its headers) to build`;
+        hint = ` — add its Debian -dev package to \`runtime: system:\`${pc ? ` (for ${lib}, usually \`lib${lib.replace(/^lib/, "")}-dev\`)` : ""}, plus build-essential and pkg-config`;
+    }
+    else if (/E: Unable to locate package (\S+)/.test(text)) {
+        cause = `apt has no package \`${/E: Unable to locate package (\S+)/.exec(text)[1]}\``;
+        hint = " — check the name on packages.debian.org for trixie";
+    }
+    else if (/No solution found when resolving dependencies/.test(text)) {
+        const i = lines.findIndex((l) => /No solution found/.test(l));
+        cause = `the requirements cannot all be satisfied: ${lines.slice(i + 1, i + 3).map((l) => l.replace(/^[\s╰─▶×]+/, "")).join(" ")}`.trim();
+    }
+    else if (/No matching distribution found for (\S+)|Could not find a version that satisfies the requirement (\S+)|Because (\S+) was not found in the package registry/.test(text)) {
+        const m = /No matching distribution found for (\S+)|Could not find a version that satisfies the requirement (\S+)|Because (\S+) was not found in the package registry/.exec(text);
+        cause = `no published version of \`${m[1] ?? m[2] ?? m[3]}\` matches`;
+    }
+    else if (/npm (?:ERR!|error) code (\S+)/.test(text)) {
+        const code = /npm (?:ERR!|error) code (\S+)/.exec(text)[1];
+        const detail = lines.find((l) => /npm (?:ERR!|error) (?:404|notarget|E\w+)\b/.test(l) && !/ code /.test(l));
+        cause = `npm ${code}${detail ? `: ${detail.replace(/^npm (?:ERR!|error)\s*/, "")}` : ""}`;
+    }
+    if (!cause) {
+        const last = [...lines].reverse().find((l) => /error/i.test(l)) ?? lines[lines.length - 1] ?? "no output";
+        cause = (pkg ? `${subject}: ` : "") + last.replace(/^\s*(?:error:|ERROR:|×)\s*/, "");
+    }
+    const excerpt = lines.slice(-25).join("\n");
+    return `${what} failed — ${cause}${hint}\n${excerpt.length > 2000 ? excerpt.slice(-2000) : excerpt}`;
+}
+/** Sets $FOLDRUN_SYSTEM_PACKAGES from the step's input.json (its merged
+ *  runtime spec) — the run pod's and the docker entry's first line. */
+export const SYSTEM_FROM_INPUT_SH = `FOLDRUN_SYSTEM_PACKAGES="$(node -e 'try{const r=JSON.parse(require("fs").readFileSync("/opt/runner/job/input.json","utf8")).runtime;process.stdout.write(((r&&r.system)||[]).join(" "))}catch(e){}')"`;
+/** Where a run container's root start-up records the system install. */
+export const SYSTEM_STATUS_FILE = "/opt/runner/job/system-install.json";
+export const SYSTEM_LOG_FILE = "/opt/runner/job/system-install.log";
+/**
+ * The root start-up's half of `runtime: system:` — one shell snippet, used by
+ * the k8s run pod, the docker entry and the deploy-time warm pod alike.
+ * Reads the package names from $FOLDRUN_SYSTEM_PACKAGES (space-separated,
+ * each re-checked against DEB_PACKAGE's shape here too, so nothing else can
+ * ride in), installs them with apt as root BEFORE the drop to the agent user,
+ * and writes SYSTEM_STATUS_FILE for prepareRuntime to read.
+ *
+ * The first step to need a package set installs it with apt (the .debs kept
+ * in `<cache>/.apt/archives`) and then saves the files those packages added,
+ * with their dpkg records, as a snapshot: `<cache>/.apt/snapshots/<key>.tar`.
+ * Every later step restores the snapshot instead — measured 11 Oct 2026 in a
+ * gVisor run pod on the NFS cache: build-essential, pkg-config, python3-dev,
+ * libcairo2-dev and libpango1.0-dev (154 packages, 432 MB) took 23-30 s
+ * through apt and 0.76 s from the snapshot, gcc and pkg-config working after.
+ * The key is the package set AND a checksum of the image's own dpkg status,
+ * so a new runner image never restores files built against the old one. A
+ * snapshot is written under a temporary name and renamed, so two pods
+ * building it at once cannot leave a torn one; a restore that fails falls
+ * back to apt, and prepareRuntime verifies the result either way. Unused for
+ * 30 days, one is pruned. Package lists stay per pod: two pods updating one
+ * lists directory on a shared volume would corrupt it.
+ */
+export function systemInstallSh(cacheDir, logDir = "/opt/runner/job") {
+    return `if [ -n "$FOLDRUN_SYSTEM_PACKAGES" ]; then
+  SYS=""; for p in $FOLDRUN_SYSTEM_PACKAGES; do case "$p" in -*|*[!a-z0-9+.-]*) ;; *) SYS="$SYS $p";; esac; done
+  D=\${FOLDRUN_DPKG_DIR:-/var/lib/dpkg}; R=\${FOLDRUN_SYS_ROOT:-/}
+  C=${cacheDir}/.apt; A=$C/archives; S=$C/snapshots
+  mkdir -p "$A/partial" "$S" 2>/dev/null || { A=/var/cache/apt/archives; S=""; }
+  KEY=v3-$( { printf '%s\\n' $SYS | sort -u; cksum < "$D/status"; } | cksum | tr ' ' '-')
+  T0=$(date +%s); MODE=apt; RC=1
+  if [ -n "$S" ] && [ -f "$S/$KEY.tar" ] && tar -xf "$S/$KEY.tar" -C "$R" > ${logDir}/system-install.log 2>&1; then
+    MODE=snapshot; RC=0; touch "$S/$KEY.tar" 2>/dev/null
+    # apt runs ldconfig through dpkg's trigger; a restore must too, or a
+    # library the snapshot brought is missing from /etc/ld.so.cache.
+    [ "$R" = / ] && ldconfig 2>/dev/null
+  else
+    ls "$D"/info/*.list 2>/dev/null | sort > /tmp/.sys-before
+    touch /tmp/.sys-mark; sleep 1
+    { apt-get -o Acquire::Retries=3 -qq update && DEBIAN_FRONTEND=noninteractive apt-get -o Dir::Cache::Archives="$A" -o Acquire::Retries=3 -o Dpkg::Use-Pty=0 install -y -qq --no-install-recommends $SYS; } > ${logDir}/system-install.log 2>&1
+    RC=$?
+    if [ $RC -eq 0 ] && [ -n "$S" ]; then
+      ls "$D"/info/*.list 2>/dev/null | sort > /tmp/.sys-after
+      comm -13 /tmp/.sys-before /tmp/.sys-after > /tmp/.sys-new
+      if [ -s /tmp/.sys-new ]; then
+        { cat $(cat /tmp/.sys-new) | sort -u | while read -r f; do if [ -f "$f" ] || [ -L "$f" ]; then echo "$f"; fi; done
+          for l in $(cat /tmp/.sys-new); do ls "\${l%.list}".* 2>/dev/null; done
+          echo "$D/status"
+          # What the packages' install scripts made, which dpkg's lists do not
+          # name: update-alternatives links (libblas.so.3 → /etc/alternatives),
+          # generated caches and configs. By ctime, not mtime: those links carry
+          # the package's own (2025) mtime, and only ctime cannot be backdated.
+          find \${FOLDRUN_SYS_SCAN:-/etc /usr /var/lib} -xdev \\( -path /var/lib/apt -o -path /var/lib/dpkg/info \\) -prune -o \\( -type f -o -type l \\) -cnewer /tmp/.sys-mark -print 2>/dev/null
+        } | sort -u > /tmp/.sys-files
+        tar -cf "$S/.$KEY.$$.tar" -T /tmp/.sys-files 2>/dev/null && mv -f "$S/.$KEY.$$.tar" "$S/$KEY.tar" 2>/dev/null
+        rm -f "$S/.$KEY.$$.tar" 2>/dev/null
+      fi
+      find "$S" -name '*.tar' -mtime +30 -delete 2>/dev/null
+    fi
+  fi
+  printf '{"ok": %s, "exit": %s, "seconds": %s, "mode": "%s", "packages": "%s"}\\n' "$([ $RC -eq 0 ] && echo true || echo false)" "$RC" "$(( $(date +%s) - T0 ))" "$MODE" "$SYS" > ${logDir}/system-install.json
+  rm -rf /var/lib/apt/lists/* 2>/dev/null || true
+fi`;
+}
+/**
+ * Are the declared system packages on this machine? The install happened in
+ * the container's root start-up (systemInstallSh); this only reads the
+ * result. Without dpkg (a laptop, macOS) there is nothing to check against
+ * and nothing this process could install: say so and carry on.
+ */
+export function checkSystemPackages(pkgs) {
+    if (!pkgs.length)
+        return { log: [], error: null };
+    const statusFile = process.env.FOLDRUN_SYSTEM_STATUS ?? SYSTEM_STATUS_FILE;
+    const logFile = process.env.FOLDRUN_SYSTEM_LOG ?? SYSTEM_LOG_FILE;
+    let status = null;
+    try {
+        status = JSON.parse(fs.readFileSync(statusFile, "utf8"));
+    }
+    catch {
+        status = null;
+    }
+    const q = spawnSync("dpkg-query", ["-W", "-f=${Package} ${db:Status-Status}\n", ...pkgs], { encoding: "utf8" });
+    if (q.error) {
+        return { log: [`system packages ${pkgs.join(", ")} install only in a run container; on this machine they are assumed present`], error: null };
+    }
+    const installed = new Set((q.stdout ?? "")
+        .split("\n")
+        .map((l) => l.trim().split(/\s+/))
+        .filter((f) => f[1] === "installed")
+        .map((f) => f[0].replace(/:.*$/, "")));
+    const missing = pkgs.filter((p) => !installed.has(p));
+    if (!missing.length) {
+        return { log: [`system packages ready: ${pkgs.join(", ")}${status?.seconds !== undefined ? ` (${status.mode === "snapshot" ? "snapshot" : "apt"}, ${status.seconds}s)` : ""}`], error: null };
+    }
+    let aptOut = "";
+    try {
+        aptOut = fs.readFileSync(logFile, "utf8");
+    }
+    catch {
+        aptOut = "";
+    }
+    const reason = !status
+        ? "this runner did not install them — system packages are installed by a run container's start-up (k8s or docker isolation), not on a bare host"
+        : status.ok
+            ? "apt reported success, yet they are not installed"
+            : summarizeInstallFailure("apt-get install", aptOut).replace(/^apt-get install failed — /, "apt: ");
+    return { log: [], error: `system packages not installed: ${missing.join(", ")} — ${reason}` };
+}
 export function prepareRuntime(tenant, spec) {
     if (!spec)
         return EMPTY;
+    const system = checkSystemPackages(spec.system ?? []);
+    if (system.error)
+        return { ...EMPTY, log: system.log, error: system.error };
+    if (!wantsPython(spec) && !wantsNode(spec))
+        return { ...EMPTY, log: system.log };
+    const built = prepareLanguageRuntime(tenant, spec);
+    return system.log.length ? { ...built, log: [...system.log, ...built.log] } : built;
+}
+function prepareLanguageRuntime(tenant, spec) {
     const fp = fingerprint(spec);
     const cacheRoot = path.join(dataRoot(), tenant, ".runtimes");
     const shared = path.join(cacheRoot, fp);
@@ -695,7 +900,7 @@ export function prepareRuntime(tenant, spec) {
                     ? install(uv, ["pip", "install", "-q", "--python", venvPython, ...spec.packages], root, 300_000, uvEnv)
                     : install(path.join(root, "venv", "bin", "pip"), ["install", "--disable-pip-version-check", "-q", ...spec.packages], root);
                 if (!installed.ok) {
-                    return fail(`${uv ? "uv pip" : "pip"} install failed: ${installed.out.slice(-500)}`);
+                    return fail(summarizeInstallFailure(`${uv ? "uv pip" : "pip"} install`, installed.out));
                 }
                 built.packages = spec.packages;
                 log.push(`runtime ${fp}: installed ${spec.packages.join(", ")}`);
@@ -718,7 +923,7 @@ export function prepareRuntime(tenant, spec) {
                     npm_config_cache: path.join(root, ".npm-cache"),
                 });
                 if (!installed.ok) {
-                    return fail(`npm install failed: ${installed.out.slice(-500)}`);
+                    return fail(summarizeInstallFailure("npm install", installed.out));
                 }
                 built.npm = spec.npm;
                 log.push(`runtime ${fp}: installed ${spec.npm.join(", ")}`);
@@ -790,3 +995,23 @@ function touch(file) {
         // read-only or gone; neither is a reason to fail the step
     }
 }
+// ---------- installing mid-step ----------
+/** Where the root start-up's install helper listens, inside a run container. */
+export const INSTALL_SOCKET = "/opt/runner/job/install.sock";
+/**
+ * What a step installs for itself mid-run (the `install` tool) lands under
+ * one per-step directory: pip packages in `<dir>/py` (`uv pip install
+ * --target`), npm packages in `<dir>/npm` (`npm install --prefix`). Both are
+ * on the step's paths from its first turn, so a tool installed by one call is
+ * found by the next — `ffmpeg`, `import manim`, `require("sharp")`. Inside a
+ * run container the directory is the container's own filesystem and goes
+ * when the container does.
+ */
+export function stepInstallEnv(dir, base) {
+    return {
+        // After whatever is already there: a declared environment keeps winning.
+        PATH: [base.PATH ?? "", path.join(dir, "py", "bin"), path.join(dir, "npm", "node_modules", ".bin")].filter(Boolean).join(path.delimiter),
+        PYTHONPATH: [base.PYTHONPATH ?? "", path.join(dir, "py")].filter(Boolean).join(path.delimiter),
+        NODE_PATH: [base.NODE_PATH ?? "", path.join(dir, "npm", "node_modules")].filter(Boolean).join(path.delimiter),
+    };
+}

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

@@ -6,6 +6,8 @@ export interface ScriptSpec {
      *  script inline. Exactly one of the two is the program. */
     run: string;
     description: string;
+    /** The tool.md body, for the model: how to call it and what it means. */
+    guide?: string;
     args: Record<string, string>;
     interpreter?: string;
     /** Seconds this script may run — for the crawl that legitimately takes

package/dist/src/script-tools.js

@@ -55,6 +55,7 @@ export function parseScripts(raw) {
             run: run ?? "",
             ...(code ? { code, codeExt: typeof e.codeExt === "string" ? e.codeExt : ".mjs" } : {}),
             description: typeof e.description === "string" ? e.description : "",
+            ...(typeof e.guide === "string" && e.guide.trim() ? { guide: e.guide } : {}),
             args,
             interpreter: typeof e.interpreter === "string" ? e.interpreter : undefined,
             secrets: e.secrets === "proxied" ? "proxied" : undefined,
@@ -346,7 +347,8 @@ export function buildScriptTools(agentDir, scripts, env, libraryScripts = "", in
     const tools = scripts.map((spec) => {
         const shape = scriptArgShape(spec.args);
         return tool(spec.name, `${spec.description || `Run ${spec.run}.`} Runs the workspace script ${spec.run}; returns its output. ` +
-            `Credentials it needs are already in its environment.`, shape, async (args) => {
+            `Credentials it needs are already in its environment.` +
+            (spec.guide ? `\n\nHow to use it (from its tool.md):\n${spec.guide}` : ""), shape, async (args) => {
             const started = Date.now();
             const values = Object.fromEntries(Object.entries(args ?? {}).map(([k, v]) => [k, v === undefined ? "" : String(v)]));
             const { code, out } = await runScript(agentDir, spec, values, env, libraryScripts, interpreters, exec);

package/dist/src/secrets.d.ts

@@ -123,6 +123,11 @@ export interface OAuth2Config {
     /** Extra form fields some providers want (audience, scope, …). */
     extra?: Record<string, string>;
 }
+/** Tries at a token endpoint before a refresh is called failed: the first,
+ *  and two more after a short wait, for a network error, a 5xx or a 429. */
+export declare const OAUTH_REFRESH_TRIES = 3;
+/** Wait before try n (1-based retry): 1s, 3s — FOLDRUN_OAUTH_RETRY_MS scales it for tests. */
+export declare function oauthRetryDelayMs(n: number): number;
 export declare function setOAuth2Secret(tenant: string, name: string, config: OAuth2Config, workspace?: string): void;
 export declare function isOAuth2Value(value: string): boolean;
 /**

package/dist/src/secrets.js

@@ -402,6 +402,14 @@ export function rotateMasterKey(tenant, from, to) {
     return { rewritten, unreadable };
 }
 const OAUTH2_PREFIX = "@oauth2 ";
+/** Tries at a token endpoint before a refresh is called failed: the first,
+ *  and two more after a short wait, for a network error, a 5xx or a 429. */
+export const OAUTH_REFRESH_TRIES = 3;
+/** Wait before try n (1-based retry): 1s, 3s — FOLDRUN_OAUTH_RETRY_MS scales it for tests. */
+export function oauthRetryDelayMs(n) {
+    const base = Number(process.env.FOLDRUN_OAUTH_RETRY_MS ?? 1000);
+    return base * (n === 1 ? 1 : 3);
+}
 export function setOAuth2Secret(tenant, name, config, workspace) {
     for (const field of ["token_url", "client_id", "client_secret"]) {
         if (!config[field]?.trim())
@@ -440,12 +448,35 @@ async function exchange(config, cacheKey) {
             client_secret: config.client_secret,
             ...(config.extra ?? {}),
         });
-        const res = await fetchUntrusted(config.token_url, {
-            method: "POST",
-            headers: { "content-type": "application/x-www-form-urlencoded" },
-            body: body.toString(),
-            signal: AbortSignal.timeout(15_000),
-        }, { sameOrigin: true });
+        // A network blip is retried; a provider's answer is not. "fetch failed"
+        // (a reset, a DNS hiccup, a timeout) failed whole steps on the first try
+        // — gbp-desk's Thursday posts, 7 Oct 2026. A 4xx (revoked, wrong client)
+        // will say the same thing again, so it goes straight to the error below
+        // and the reconnect mail; a 5xx or 429 is the provider busy, retried.
+        let res;
+        let lastNetwork;
+        for (let attempt = 0; attempt < OAUTH_REFRESH_TRIES; attempt++) {
+            if (attempt)
+                await new Promise((r) => setTimeout(r, oauthRetryDelayMs(attempt)));
+            try {
+                res = await fetchUntrusted(config.token_url, {
+                    method: "POST",
+                    headers: { "content-type": "application/x-www-form-urlencoded" },
+                    body: body.toString(),
+                    signal: AbortSignal.timeout(15_000),
+                }, { sameOrigin: true });
+            }
+            catch (err) {
+                lastNetwork = err;
+                res = undefined;
+                continue;
+            }
+            if (res.status === 429 || res.status >= 500)
+                continue;
+            break;
+        }
+        if (!res)
+            throw lastNetwork instanceof Error ? lastNetwork : new Error(String(lastNetwork));
         const payload = (await res.json().catch(() => ({})));
         if (!res.ok || !payload.access_token) {
             throw new Error(`token refresh failed (${res.status}): ${payload.error_description ?? payload.error ?? "no access_token in the reply"}`);

package/dist/src/starter.d.ts

@@ -28,3 +28,15 @@ export declare function accountFiles(account: string): StarterFile[];
  */
 export declare function accountGitignore(): StarterFile;
 export declare function starterFiles(workspace: string): StarterFile[];
+/**
+ * A new workspace with nothing in it to delete: its AGENTS.md, the
+ * .gitignore that keeps its secret key out of git, and the CLAUDE.md a coding
+ * tool reads. No example agents or flow.
+ *
+ * The starter's researcher and writer were a demo, and a person making a
+ * workspace for real work met them as clutter — "why does a new workspace
+ * have agents?" (owner, 2026-10-05). The agents worth having are usually ones
+ * already written in another workspace, which `agents/import` copies in; the
+ * example is still one flag away (`foldrun new <name> --starter`).
+ */
+export declare function blankWorkspaceFiles(workspace: string): StarterFile[];

package/dist/src/starter.js

@@ -40,6 +40,10 @@ foldrun_version: "0.1"
 # that declares the same key replaces it *whole* — base_url and token never
 # merge across scopes, so a provider block belongs entirely at one level.
 #
+# Your own model key needs no block: Settings → Model provider, or
+# \`foldrun account model set anthropic --key …\` (an API key, not a login).
+# A provider: block here or lower wins over it.
+#
 # provider:
 #   base_url: https://openrouter.ai/api
 #   token: \${OPENROUTER_API_KEY}
@@ -259,6 +263,7 @@ only when they asked for exactly that deletion.
 | \`memory/\` | what past runs learned — agents write here themselves |
 | \`evals/\` | tests for agents, same idea as unit tests |
 | \`skills/\` | a procedure an agent can follow, named in \`skills:\` |
+| \`hooks/\` | your code at every tool call, step start or step end (\`hook.md\` + \`run.mjs\`), turned on with \`hooks:\` — refuse, rewrite, add context; same on every model |
 | \`tools/\` | a folder tool: its definition and its code together |
 | \`scripts/\` | code the agents call, referenced by \`scripts:\` |
 | \`state/\` | what runs accumulate. Yours to read, never deployed over |
@@ -326,13 +331,14 @@ All of it, \`/api/workspaces/<workspace>\` unless noted:
 | \`/runs/<id>/message\` | POST | tell a running step something; \`step\` picks one of a parallel group |
 | \`/flows\` · \`/flows/<f>\` | GET POST · POST DELETE PATCH | list, create, edit |
 | \`/flows/<f>/run\` | POST | start a flow |
-| \`/agents\` · \`/agents/<a>/run\` | GET POST · POST | list agents, run one |
+| \`/agents\` · \`/agents/<a>/run\` · \`/agents/import\` | GET POST · POST · GET POST | list agents, run one, copy one in from another workspace |
 | \`/evals\` · \`/evals/<e>/run\` | GET POST · POST | list evals, run one |
 | \`/tools/<t>/test\` | POST | exercise one tool alone |
 | \`/storage\` · \`/storage/download\` · \`/storage/upload-url\` · \`/storage/preview\` | GET POST PUT DELETE · GET · POST · GET | workspace files, any type; \`preview\` returns one parsed for reading |
 | \`/assets\` | POST | upload an asset |
 | \`/hooks/<f>/rotate\` | POST | new webhook token for a flow |
 | \`/notify/deliveries\` · \`/notify/deliveries/<id>/redeliver\` | GET · POST | every notify: webhook sent and each attempt; send one again |
+| \`/export\` · \`/import\` | GET · POST | the workspace, a flow (\`?kind=flow&name=\`) or an agent as a .zip; take one in (\`?dryRun=1\` first, \`?overwrite=1\` to replace) |
 | \`/restore\` | POST | the workspace's source back to a point in its history — \`dryRun\` first, then \`confirm\` |
 | \`/vocabulary\` | GET | what this workspace's documents may say |
 
@@ -434,6 +440,7 @@ size: large                 # small | large | heavy — the sandbox it rents
 tools: [web, read, ask, my-folder-tool]  # built-ins and your own tools/, one list; \`ask\` lets it ask you mid-step
 disallowedTools: [Bash]     # subtract from what it would otherwise have
 skills: [house-style]       # from skills/
+hooks: [no-force-push]      # from hooks/ or the library: code at every tool call
 scripts: [summarise.py]     # from scripts/, each becomes a callable tool
 apis: [{ name: crm }]       # an HTTP API, as a tool
 mcpServers: {}              # an MCP server, as a tool
@@ -442,10 +449,11 @@ subagents: [researcher]     # colleagues it may delegate a job to (own context,
 secrets: [CRM_TOKEN]        # keys the agent uses itself; a tool's own come with the tool
 limits: {web.search: 40, crm: 20, calls: 300}  # per step; a call past a limit is refused, never run
 timezone: Australia/Sydney  # the calendar it works to — IANA name or UTC+10
-provider: {}                # BYOK: your own model credential
+provider: {}                # BYOK for this agent; account-wide: \`foldrun account model set\`
 permissionMode: plan        # plan first, act once approved
 runtime:                    # only if scripts need packages
   packages: [requests]
+  system: [ffmpeg]          # Debian packages, apt-installed before the step
 ---
 
 You research a topic and report what you found...
@@ -459,8 +467,12 @@ flow's, else the workspace's AGENTS.md, else the account's, else UTC. It sets
 \`TZ\` and the date the agent is told, so a Sydney desk stamps the Sydney date.
 
 \`runtime:\` installs pip/npm packages in the sandbox each agent runs in. Pin
-versions the normal way (\`pandas>=2\`, \`lodash@^4\`). Python and Node are
-supported; anything else should ship as a committed binary.
+versions the normal way (\`pandas>=2\`, \`lodash@^4\`). \`system:\` adds Debian
+packages \u{2014} a program (\`ffmpeg\`), a library's headers for a pip package that
+compiles (\`libcairo2-dev\`, \`python3-dev\`), \`build-essential\` \u{2014} installed with
+apt before the step starts and cached, so later runs only unpack them. An agent that
+finds it needs something mid-run installs it itself with the \`install\` tool
+(apt, pip or npm), which every agent has; declaring is only a speed-up.
 
 Link documents to each other with \`[[wikilinks]]\` — the name, not the path.
 `,
@@ -482,3 +494,25 @@ expect:
         },
     ];
 }
+/**
+ * A new workspace with nothing in it to delete: its AGENTS.md, the
+ * .gitignore that keeps its secret key out of git, and the CLAUDE.md a coding
+ * tool reads. No example agents or flow.
+ *
+ * The starter's researcher and writer were a demo, and a person making a
+ * workspace for real work met them as clutter — "why does a new workspace
+ * have agents?" (owner, 2026-10-05). The agents worth having are usually ones
+ * already written in another workspace, which `agents/import` copies in; the
+ * example is still one flag away (`foldrun new <name> --starter`).
+ */
+export function blankWorkspaceFiles(workspace) {
+    const keep = new Set(["AGENTS.md", ".gitignore", "CLAUDE.md"]);
+    return starterFiles(workspace)
+        .filter((f) => keep.has(f.path))
+        .map((f) => f.path === "AGENTS.md"
+        ? {
+            ...f,
+            content: f.content.replace("description: A starter workspace — edit the agents, then run the flow.", "description: A new workspace — add an agent or import one from another workspace, then write a flow."),
+        }
+        : f);
+}

package/dist/src/step-exec.d.ts

@@ -1,3 +1,4 @@
+import { type HookDef, type HookRecord } from "./hooks.ts";
 import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
 import type { Effort } from "./store.ts";
 import type { TestEffect } from "./test-mode.ts";
@@ -40,6 +41,14 @@ export interface ExecOutcome {
     browserPod?: BrowserPodOutcome;
 }
 export interface ExecOptions {
+    /** `hooks:` resolved host-side (hooks.ts): run at this step's own dispatch,
+     *  inside its sandbox. `hookBase` is what every hook event carries. */
+    hooks?: HookDef[];
+    /** Or the names (`hooks:` from the account, workspace and agent), resolved
+     *  here against this step's own roots — in a sandbox those are not the
+     *  host's paths. A name that resolves to nothing refuses the step. */
+    hookNames?: string[];
+    hookBase?: Record<string, unknown>;
     agentDir: string;
     workspaceRoot: string;
     libraryRoot: string;
@@ -151,6 +160,7 @@ export type EventExtra = {
     operator?: OperatorEvent;
     subagent?: string;
     check?: boolean;
+    hook?: HookRecord;
 };
 /** Conservative per-token rates for a model nothing else can price — an
  *  unknown id on a gateway with no catalogue. Opus-class, so a ceiling
@@ -238,8 +248,8 @@ export declare function checkVerify(agentDir: string, verify: string, ctx: {
      *  and `matches:` test this, because it is also what the run's headline
      *  is read from: a reporter that narrated between tool calls ("Now let
      *  me write the report…") failed `matches: ^BAD\b` with a correct
-     *  headline while the check read every turn joined. `judge:` still grades
-     *  the whole result. */
+     *  headline while the check read every turn joined. `judge:` grades this
+     *  too, as "the reply", with the whole result beside it as the work. */
     conclusion?: string | null;
     data?: unknown;
     /** The step's own model environment, for `judge:` — it grades on the
@@ -249,6 +259,12 @@ export declare function checkVerify(agentDir: string, verify: string, ctx: {
      *  person asked the run to stop. */
     signal?: AbortSignal;
 }): Promise<VerifyVerdict>;
+/**
+ * A toolless, fast-tier grading call: does the reply satisfy the sentence?
+ * Same shape as the eval judge, and answered with one word first so the
+ * verdict is a prefix test rather than a reading.
+ */
+export declare function judgePrompt(rubric: string, reply: string, work: string): string;
 /**
  * The environment an Agent SDK session starts with: the step's, minus the
  * connectors of whoever is signed in to claude.ai on this machine. Claude
@@ -260,3 +276,6 @@ export declare function checkVerify(agentDir: string, verify: string, ctx: {
  * the rest of the on-disk MCP configuration out; this keeps the account's.
  */
 export declare function sdkEnv(base: Record<string, string | undefined> | undefined, extra?: Record<string, string>): Record<string, string | undefined>;
+/** The text of a tool result, whichever shape it came in: a string, or a
+ *  list of content blocks of which only the text ones say anything. */
+export declare function toolResultText(content: unknown): string;