@foldrun/core 0.4.0 → 0.5.0

package/dist/src/refusal.d.ts

@@ -0,0 +1,83 @@
+/** The family of headers that carries the answer. */
+export declare const UNIFIED_PREFIX = "anthropic-ratelimit-unified";
+/** The only headers that are ever copied out of an upstream response.
+ *  An allow-list rather than a prefix match, so a header we have not
+ *  thought about cannot reach a trace by being named plausibly. */
+export declare const REFUSAL_HEADERS: readonly string[];
+/** The marker a refusal line carries through the egress log, the
+ *  translator log and the run trace, so the runner can find the sentence
+ *  again among lines it did not write. */
+export declare const REFUSAL_MARK = "provider refusal:";
+/** Anything with a `get(name)` — a `Headers`, or a plain object wrapped by
+ *  `headersFrom` below. */
+export interface HeaderBag {
+    get(name: string): string | null | undefined;
+}
+/** Read a plain record as a header bag, case-insensitively. */
+export declare function headersFrom(record: Record<string, string | string[] | undefined>): HeaderBag;
+/**
+ * The allow-listed headers, and nothing else, as a small record. This is
+ * the whole of what any part of foldrun keeps from an upstream response's
+ * headers — the proxy calls it at the boundary and passes the result on.
+ */
+export declare function captureRefusalHeaders(headers: HeaderBag): Record<string, string>;
+export interface RefusalContext {
+    /** The upstream status. */
+    status: number;
+    /** What `captureRefusalHeaders` kept. Empty is meaningful: it is how a
+     *  dead credential is told from a spent window. */
+    headers?: Record<string, string>;
+    /** The step's own zone, from the clock cascade. */
+    timezone?: string;
+    /** Where the step stands on a second supply. Said out loud on every
+     *  refusal, because "no fallback" is becoming the normal state and must
+     *  read as a decision rather than as something that went missing. Left
+     *  out by a caller that cannot know — the egress proxy sees a response,
+     *  not a flow — and added by the runner, which can. */
+    supply?: SupplyState;
+    /** How the endpoint is named in the trace: `api.anthropic.com`. */
+    provider?: string;
+    /** For tests, and for a reset that has already passed. */
+    now?: Date;
+}
+/** The short name a person uses for a zone: `Australia/Sydney` → Sydney,
+ *  `UTC` → UTC, `+10:00` → UTC+10:00. */
+export declare function zoneWord(timezone: string): string;
+/**
+ * A unix-second reset as a person in that zone reads it: `14:00 Sydney`,
+ * with the date when it is not today there. Null for a stamp that is not
+ * one, so a garbled header costs a clause rather than the sentence.
+ */
+export declare function resetWhen(raw: string | undefined, timezone: string, now?: Date): string | null;
+/** Where a step stands on a second supply: none configured, one about to
+ *  be tried, or one that has been tried and refused as well. */
+export type SupplyState = "none" | "trying" | "exhausted";
+/** The clause that says whether there is anywhere else to go. Always on a
+ *  refusal the runner finalises: the absence of a fallback is a state to
+ *  state, not a silence to notice. */
+export declare function supplyNote(state: SupplyState | undefined): string;
+/**
+ * The sentence. One line, this project's voice, safe to put in a trace and
+ * on a failure line.
+ *
+ * Three shapes, in the order they are told apart:
+ *
+ *   1. rate-limit headers present → a supply problem. Which window, how
+ *      used, whether overage could have covered it and why it did not, and
+ *      when it clears in the step's own zone.
+ *   2. no rate-limit headers and a 401/403 → a credential problem. Said
+ *      explicitly, including that this is NOT quota, because assuming the
+ *      opposite is what cost an hour.
+ *   3. anything else → the status, plainly, plus whatever the provider
+ *      asked us to wait.
+ */
+export declare function explainRefusal(ctx: RefusalContext): string;
+/** The same sentence, marked, for a log line the runner reads back. */
+export declare function refusalLine(ctx: RefusalContext): string;
+/** Is this status one we explain? The set the runner already treats as a
+ *  provider refusal, plus 402 which is what started all this. */
+export declare function isRefusalStatus(status: number): boolean;
+/** Pull the sentence back out of a trace line that carries the mark,
+ *  wherever in the line it sits — the translator's lines are prefixed on
+ *  their way into the record, and the egress proxy's are not. */
+export declare function refusalFromLine(text: string): string | null;

package/dist/src/refusal.js

@@ -0,0 +1,281 @@
+// Why the model supply said no.
+//
+// A step whose model call is refused used to leave two facts in the record:
+// a status code, and a sentence written by the SDK. In the incident this
+// file exists for, that was:
+//
+//   egress: POST api.anthropic.com/v1/messages → 401 × 4 [FOLDRUN_MODEL_KEY]
+//   API Error: 402 This request would exceed your available credits
+//
+// Both are true and neither is the reason. The reason was that the
+// subscription behind the key had its five-hour window part used and
+// overage switched off for lack of credits — a state that clears by itself
+// at a known minute — and the fallback provider had no balance. Working
+// that out took an hour on the box, most of it spent assuming the key had
+// been revoked. The key was fine.
+//
+// Anthropic says all of it in response headers on the very response that
+// carried the refusal:
+//
+//   anthropic-ratelimit-unified-status: allowed | rejected
+//   anthropic-ratelimit-unified-5h-status / -7d-status
+//   anthropic-ratelimit-unified-5h-utilization: 0.35
+//   anthropic-ratelimit-unified-overage-status: rejected
+//   anthropic-ratelimit-unified-overage-disabled-reason: out_of_credits
+//   anthropic-ratelimit-unified-reset / -5h-reset / -7d-reset (unix seconds)
+//   retry-after (on 429)
+//
+// We logged none of it. This file turns that header set into one sentence
+// in the step's own trace and on the step's failure line, in the step's own
+// timezone, and — the distinction that cost the hour — tells a spent window
+// apart from a dead credential. A refusal carrying no rate-limit headers at
+// all is a credential problem; a refusal carrying them is a supply problem
+// and usually a clock.
+//
+// Two rules hold everywhere below. Never log a credential: nothing here
+// reads a request header, and the only response headers it will look at are
+// the allow-listed ones named above. Never log the whole header set: a
+// provider is free to put anything in one, and a trace is read by people
+// who are not thinking about that.
+import { localDate } from "./clock.js";
+/** The family of headers that carries the answer. */
+export const UNIFIED_PREFIX = "anthropic-ratelimit-unified";
+/** The only headers that are ever copied out of an upstream response.
+ *  An allow-list rather than a prefix match, so a header we have not
+ *  thought about cannot reach a trace by being named plausibly. */
+export const REFUSAL_HEADERS = [
+    `${UNIFIED_PREFIX}-status`,
+    `${UNIFIED_PREFIX}-reset`,
+    `${UNIFIED_PREFIX}-5h-status`,
+    `${UNIFIED_PREFIX}-5h-utilization`,
+    `${UNIFIED_PREFIX}-5h-reset`,
+    `${UNIFIED_PREFIX}-7d-status`,
+    `${UNIFIED_PREFIX}-7d-utilization`,
+    `${UNIFIED_PREFIX}-7d-reset`,
+    `${UNIFIED_PREFIX}-overage-status`,
+    `${UNIFIED_PREFIX}-overage-disabled-reason`,
+    "retry-after",
+];
+/** The marker a refusal line carries through the egress log, the
+ *  translator log and the run trace, so the runner can find the sentence
+ *  again among lines it did not write. */
+export const REFUSAL_MARK = "provider refusal:";
+/** Read a plain record as a header bag, case-insensitively. */
+export function headersFrom(record) {
+    const lower = new Map();
+    for (const [k, v] of Object.entries(record)) {
+        if (v === undefined)
+            continue;
+        lower.set(k.toLowerCase(), Array.isArray(v) ? v.join(", ") : v);
+    }
+    return { get: (name) => lower.get(name.toLowerCase()) ?? null };
+}
+/**
+ * The allow-listed headers, and nothing else, as a small record. This is
+ * the whole of what any part of foldrun keeps from an upstream response's
+ * headers — the proxy calls it at the boundary and passes the result on.
+ */
+export function captureRefusalHeaders(headers) {
+    const out = {};
+    for (const name of REFUSAL_HEADERS) {
+        const value = headers.get(name);
+        if (typeof value === "string" && value.trim())
+            out[name] = value.trim().slice(0, 120);
+    }
+    return out;
+}
+/** Which of the two windows refused, when either did. */
+function rejectedWindow(h) {
+    for (const w of ["5h", "7d"]) {
+        if ((h[`${UNIFIED_PREFIX}-${w}-status`] ?? "").toLowerCase() === "rejected")
+            return w;
+    }
+    return null;
+}
+/** The busiest window we were told about, when none of them said
+ *  "rejected" outright but the request was refused anyway. */
+function busiestWindow(h) {
+    let best = null;
+    let high = -1;
+    for (const w of ["5h", "7d"]) {
+        const raw = h[`${UNIFIED_PREFIX}-${w}-utilization`];
+        const n = raw === undefined ? NaN : Number(raw);
+        if (Number.isFinite(n) && n > high) {
+            high = n;
+            best = w;
+        }
+    }
+    return best;
+}
+const WINDOW_WORD = { "5h": "5-hour", "7d": "7-day" };
+/** `0.35` → `35%`. Null for anything that is not a number we can show. */
+function percent(raw) {
+    const n = raw === undefined ? NaN : Number(raw);
+    if (!Number.isFinite(n) || n < 0)
+        return null;
+    // Providers have sent both a fraction and a percentage. Over 1 can only
+    // be the latter; a run should not be told it is 3500% through a window.
+    const fraction = n > 1 ? n / 100 : n;
+    return `${Math.round(fraction * 100)}%`;
+}
+/** The short name a person uses for a zone: `Australia/Sydney` → Sydney,
+ *  `UTC` → UTC, `+10:00` → UTC+10:00. */
+export function zoneWord(timezone) {
+    if (!timezone)
+        return "UTC";
+    if (/^[+-]/.test(timezone))
+        return `UTC${timezone}`;
+    const last = timezone.split("/").pop() ?? timezone;
+    return last.replace(/_/g, " ");
+}
+/**
+ * A unix-second reset as a person in that zone reads it: `14:00 Sydney`,
+ * with the date when it is not today there. Null for a stamp that is not
+ * one, so a garbled header costs a clause rather than the sentence.
+ */
+export function resetWhen(raw, timezone, now = new Date()) {
+    const secs = raw === undefined ? NaN : Number(raw);
+    if (!Number.isFinite(secs) || secs <= 0)
+        return null;
+    // Seconds, or milliseconds from a provider that forgot which it promised.
+    const at = new Date(secs > 1e11 ? secs : secs * 1000);
+    if (Number.isNaN(at.getTime()))
+        return null;
+    let time;
+    try {
+        time = new Intl.DateTimeFormat("en-GB", {
+            timeZone: timezone,
+            hour: "2-digit",
+            minute: "2-digit",
+            hour12: false,
+        }).format(at);
+    }
+    catch {
+        return null;
+    }
+    const sameDay = localDate(timezone, at) === localDate(timezone, now);
+    if (sameDay)
+        return `${time} ${zoneWord(timezone)}`;
+    const day = new Intl.DateTimeFormat("en-GB", {
+        timeZone: timezone,
+        weekday: "short",
+        day: "numeric",
+        month: "short",
+    }).format(at);
+    return `${time} ${zoneWord(timezone)} on ${day}`;
+}
+/** `retry-after: 90` → `90s`; `180` → `3m`. */
+function waitWord(raw) {
+    const n = raw === undefined ? NaN : Number(raw);
+    if (!Number.isFinite(n) || n < 0) {
+        // A provider may send an HTTP date instead of a delta.
+        const at = raw ? Date.parse(raw) : NaN;
+        if (!Number.isFinite(at))
+            return null;
+        const secs = Math.round((at - Date.now()) / 1000);
+        return secs > 0 ? waitWord(String(secs)) : null;
+    }
+    if (n < 90)
+        return `${Math.round(n)}s`;
+    if (n < 5400)
+        return `${Math.round(n / 60)}m`;
+    return `${(n / 3600).toFixed(1).replace(/\.0$/, "")}h`;
+}
+/** What the provider said it is out of. `out_of_credits` reads as prose. */
+function reasonWord(raw) {
+    if (!raw)
+        return null;
+    return raw.replace(/[_-]+/g, " ").trim().toLowerCase() || null;
+}
+/** The clause that says whether there is anywhere else to go. Always on a
+ *  refusal the runner finalises: the absence of a fallback is a state to
+ *  state, not a silence to notice. */
+export function supplyNote(state) {
+    if (state === "none")
+        return " — no second supply is configured";
+    if (state === "trying")
+        return " — trying the second supply";
+    if (state === "exhausted")
+        return " — the second supply refused it too";
+    return "";
+}
+/**
+ * The sentence. One line, this project's voice, safe to put in a trace and
+ * on a failure line.
+ *
+ * Three shapes, in the order they are told apart:
+ *
+ *   1. rate-limit headers present → a supply problem. Which window, how
+ *      used, whether overage could have covered it and why it did not, and
+ *      when it clears in the step's own zone.
+ *   2. no rate-limit headers and a 401/403 → a credential problem. Said
+ *      explicitly, including that this is NOT quota, because assuming the
+ *      opposite is what cost an hour.
+ *   3. anything else → the status, plainly, plus whatever the provider
+ *      asked us to wait.
+ */
+export function explainRefusal(ctx) {
+    const h = ctx.headers ?? {};
+    const zone = ctx.timezone || "UTC";
+    const now = ctx.now ?? new Date();
+    const where = ctx.provider ? ` at ${ctx.provider}` : "";
+    const supply = supplyNote(ctx.supply);
+    const hasLimits = Object.keys(h).some((k) => k.startsWith(UNIFIED_PREFIX));
+    if (hasLimits) {
+        const window = rejectedWindow(h) ?? busiestWindow(h);
+        const used = window ? percent(h[`${UNIFIED_PREFIX}-${window}-utilization`]) : null;
+        const reset = resetWhen(window ? h[`${UNIFIED_PREFIX}-${window}-reset`] : undefined, zone, now) ??
+            resetWhen(h[`${UNIFIED_PREFIX}-reset`], zone, now);
+        const overage = (h[`${UNIFIED_PREFIX}-overage-status`] ?? "").toLowerCase();
+        const why = reasonWord(h[`${UNIFIED_PREFIX}-overage-disabled-reason`]);
+        const parts = [];
+        if (window) {
+            parts.push(used ? `the ${WINDOW_WORD[window]} window is ${used} used` : `the ${WINDOW_WORD[window]} window is spent`);
+        }
+        if (overage === "rejected" || overage === "disabled" || why) {
+            parts.push(why ? `overage is off (${why})` : "overage is off");
+        }
+        else if (overage === "allowed") {
+            parts.push("overage is on but did not cover it");
+        }
+        // "used BUT overage is off" — the two clauses are in tension, and that
+        // tension is the finding: there was room left and no way to buy it.
+        const wait = waitWord(h["retry-after"]);
+        const tail = reset ? `it resets at ${reset}` : wait ? `it asked us to wait ${wait}` : "";
+        const body = parts.length ? parts.join(" but ") : `HTTP ${ctx.status}`;
+        return `the subscription${where} refused this burst — ${body}${tail ? `; ${tail}` : ""}${supply}`;
+    }
+    if (ctx.status === 401 || ctx.status === 403) {
+        return (`the credential${where} was refused (HTTP ${ctx.status}) and the response carried no rate-limit headers, ` +
+            `so this is the key itself — invalid, revoked, or wrong for this endpoint — not a spent window${supply}`);
+    }
+    if (ctx.status === 429) {
+        const wait = waitWord(h["retry-after"]);
+        return wait
+            ? `the provider${where} is rate limiting this step (HTTP 429) and asked us to wait ${wait}${supply}`
+            : `the provider${where} is rate limiting this step (HTTP 429) and named no wait${supply}`;
+    }
+    if (ctx.status === 402) {
+        return `the account${where} is out of credit (HTTP 402) and the response said nothing about windows${supply}`;
+    }
+    return `the model supply${where} refused this step (HTTP ${ctx.status})${supply}`;
+}
+/** The same sentence, marked, for a log line the runner reads back. */
+export function refusalLine(ctx) {
+    return `${REFUSAL_MARK} ${explainRefusal(ctx)}`;
+}
+/** Is this status one we explain? The set the runner already treats as a
+ *  provider refusal, plus 402 which is what started all this. */
+export function isRefusalStatus(status) {
+    return status === 401 || status === 402 || status === 403 || status === 429;
+}
+/** Pull the sentence back out of a trace line that carries the mark,
+ *  wherever in the line it sits — the translator's lines are prefixed on
+ *  their way into the record, and the egress proxy's are not. */
+export function refusalFromLine(text) {
+    const at = text.indexOf(REFUSAL_MARK);
+    if (at < 0)
+        return null;
+    const said = text.slice(at + REFUSAL_MARK.length).trim();
+    return said || null;
+}

package/dist/src/run-container.d.ts

@@ -4,8 +4,11 @@ import type { EventExtra } from "./step-exec.ts";
 import { type RuntimeSpec } from "./runtime.ts";
 import type { ScriptSpec } from "./script-tools.ts";
 import type { ConsultSpec } from "./agent-tools.ts";
+import type { SubagentSpec } from "./subagents.ts";
+import { type OperatorEvent } from "./operator.ts";
 import type { SearchRoot, RunDigest } from "./context-tools.ts";
 import type { TranslatorSpec } from "./translator.ts";
+import { type BrowserPodOutcome } from "./browser-pod.ts";
 /** What crosses the boundary. Everything in here is values — pre-resolved
  *  secrets in headers, assembled prompt, serializable MCP configs. */
 export interface ContainerStepInput {
@@ -29,6 +32,8 @@ export interface ContainerStepInput {
      *  their agent.md files host-side. The driver rebuilds the consult tools
      *  in here; the callees run toolless, so nothing else need cross. */
     consults: ConsultSpec[];
+    /** `subagents:` — built host-side (runner.ts), plain JSON. */
+    subagents?: SubagentSpec[];
     timeoutSec?: number;
     /** The step's spend ceiling and the model's per-token price — see
      *  step-exec.ts. Values, so the driver can enforce them in the pod. */
@@ -44,6 +49,10 @@ export interface ContainerStepInput {
     /** `schema:` and `max_turns:`, resolved host-side — see ExecOptions. */
     schema?: Record<string, unknown> | boolean;
     maxTurns?: number;
+    /** `limits:` resolved host-side, and the SDK-name → foldrun-name map the
+     *  count reads (limits.ts) — enforced in the pod by the same hook. */
+    limits?: Record<string, number>;
+    toolOwners?: Record<string, string>;
     /** tools: [search] — the directories to search, as paths INSIDE the
      *  container (/workspace/…, /library/…). */
     search?: SearchRoot[];
@@ -51,10 +60,21 @@ export interface ContainerStepInput {
     history?: RunDigest[];
     /** tools: [desks] — the account's other workspaces' runs, gathered host-side. */
     desks?: RunDigest[];
+    /** tools: [ask] — ask_person, and how long it may wait for an answer. */
+    ask?: {
+        timeoutSec: number;
+    };
     /** A Chat-Completions provider: the driver starts the runtime's translator
      *  on loopback and points the SDK at it. Null or absent: the env's
      *  ANTHROPIC_BASE_URL is spoken to directly. */
     translator?: TranslatorSpec | null;
+    /** A granted tool acts outward (`outward: true`): an executor that could
+     *  put a browsing step on the slim image keeps this one on the full image,
+     *  where a browser in the step is always there (browser-pod.ts). */
+    outward?: boolean;
+    /** "full" — this attempt must have the full image: the re-run after the
+     *  browser pod was lost. Absent lets the executor choose. */
+    image?: "full";
 }
 /**
  * How long the sandbox actually existed, measured host-side — the driver
@@ -96,11 +116,25 @@ export interface ContainerStepOutcome {
         inputTokens: number;
         outputTokens: number;
     } | null;
+    /** Every turn priced at its own model, when sub-agents ran on others —
+     *  see ExecOutcome.turnsCostUsd. */
+    turnsCostUsd?: number;
     /** What the sandbox actually touched — see the driver's readActuals. */
     res?: StepActuals | null;
     /** Set by the isolated executors only — an in-process step rents no
      *  sandbox, so it has no compute seconds to bill. */
     timing?: StepTiming | null;
+    /** Which runner image the sandbox ran, as the executor chose it: `pod`
+     *  when a browsing step ran on slim and browsed through the account's
+     *  browser pod. Absent from an executor with one image. */
+    image?: {
+        variant: "full" | "slim";
+        why?: string;
+        pod?: boolean;
+    } | null;
+    /** The pod's reconnects and, when it was lost, what the step had written —
+     *  see ExecOutcome.browserPod. */
+    browserPod?: BrowserPodOutcome;
 }
 /**
  * The one place the timing line is worded, so the docker and k8s traces
@@ -135,6 +169,17 @@ export declare function allowedBack(rel: string): boolean;
  * step changed without the staging copy the first driver held in /tmp.
  */
 export declare function hashTree(dir: string): Record<string, string>;
+/**
+ * Every file's mtime under `dir`, relative path to milliseconds — so a copy
+ * that cannot carry times can have them put back. `kubectl cp` unpacks with
+ * `tar -m`, which stamps every file with the moment it landed; on 2026-09-24
+ * gbp-desk's reply-sheet check ("pending-replies.json written in the last
+ * hour") passed on a file last written on 2026-09-13, and the poster sent
+ * nothing. Every freshness check in every flow was answering "yes".
+ */
+export declare function mtimeManifest(dir: string): Record<string, number>;
+/** The in-pod half of mtimeManifest: a node one-liner, run as root before `go`. */
+export declare const APPLY_MTIMES_JS: string;
 /**
  * Both sides changed a file the step was handed. When each is the handed-in
  * content with lines added on the end — a ledger, history.md, a .jsonl — the
@@ -157,22 +202,79 @@ export declare function applyContainerChanges(hostWs: string, containerWs: strin
  */
 export declare const RUNTIME_CACHE = "/home/agent/.foldrun/runner/.runtimes";
 /**
- * The per-tenant directory backing that mount, or null when there is none.
+ * Where the platform's shared runtime layer is mounted, read-only, in a run
+ * pod — and read-write, one entry at a time, in the pod that builds an entry
+ * for it (foldrun-platform runtime-warm.ts). A fixed path for the same reason
+ * as RUNTIME_CACHE: a venv hard-codes its own location. Laid out as
+ * <FOLDRUN_DATA>/shared/.runtimes so the builder's prepareRuntime("shared", …)
+ * lands exactly here with FOLDRUN_DATA=/opt/foldrun-runtimes.
+ */
+export declare const SHARED_RUNTIMES = "/opt/foldrun-runtimes/shared/.runtimes";
+/**
+ * The per-tenant runtime cache mount — a Docker NAMED volume and the fixed
+ * path it mounts at — or null when there is none.
+ *
+ * A named volume, not a host path. The run's `docker create` is issued to the
+ * host daemon over the mounted socket, and that daemon cannot resolve a path
+ * under the platform's own FOLDRUN_DATA — which under compose is itself a named
+ * volume, or a directory Docker Desktop has not shared — so `-v <hostpath>:…`
+ * failed with "mounts denied". A named volume is resolved by the daemon, needs
+ * no host sharing, and on first use is seeded from the image's mount point,
+ * which the runner image creates owned by the agent user (the DOCKERFILE below,
+ * `${RUNTIME_CACHE}`) — so the fresh cache is writable without a host-side chown.
  *
- * Per-tenant, not shared. A shared cache would store one copy of pandas
- * instead of one per account, but it would also be mutable state that one
- * tenant's step writes and another tenant's step then *executes* — a poisoned
- * venv arriving as a trusted local file, which is precisely the path gVisor,
- * the capability drop and the egress policy all exist to close. Disk is the
- * cheaper thing to spend. If the duplication ever stops being cheap, the fix
- * is a read-only mount filled by a trusted builder, not a writable shared one.
+ * Per-tenant, not shared. A shared cache would store one copy of pandas instead
+ * of one per account, but it would also be mutable state that one tenant's step
+ * writes and another tenant's step then *executes* — a poisoned venv arriving
+ * as a trusted local file, which is precisely the path gVisor, the capability
+ * drop and the egress policy all exist to close. Disk is the cheaper thing to
+ * spend. One volume per tenant keeps that boundary; each carries a
+ * `foldrun.io/tenant` label so it can be found and pruned (self-hosting/README.md).
  *
- * Deliberately NOT under `<tenant>/.runtimes`, which is the *host* cache: the
- * venvs there carry host absolute paths and would be unusable inside a runner.
- * Two roots, so a hit is always a real hit.
+ * The venvs inside carry the runner's own absolute paths, distinct from the
+ * host's `<tenant>/.runtimes` cache — two roots, so a hit is always a real hit.
  */
-export declare function runtimeCacheDir(tenant: string | undefined): string | null;
-export declare function runnerImageTag(): string;
+export declare function runtimeCacheMount(tenant: string | undefined): {
+    source: string;
+    target: string;
+} | null;
+/** The uv release copied into the image. Pinned: a floating uv is a floating
+ *  resolver, and the runtime cache is keyed on the declaration, not on it. */
+export declare const UV_VERSION = "0.11.25";
+/** How many times a best-effort engine download is tried before the build
+ *  gives up on it, and the wait before the second and third (15s, then 30s).
+ *  A GitHub release or Google's apt mirror that blinks for a minute used to
+ *  cost the engine outright; on x86_64 that now fails the build, so a
+ *  transient blip would fail a deploy. */
+export declare const ENGINE_DOWNLOAD_ATTEMPTS = 3;
+/** `retry <engine> <command…>`: one shell function, defined at the top of each
+ *  RUN that downloads an engine (a RUN is its own shell). Its lines start
+ *  "runner image:" like every engine line, and go to stderr so a quiet
+ *  install (>/dev/null) still shows them — the deploy greps them into the
+ *  step summary (buildFailureSummary). */
+export declare const RETRY_SH = "retry() { what=$1; shift; n=1; until \"$@\"; do if [ \"$n\" -ge 3 ]; then echo \"runner image: $what - download failed $n times, giving up\" >&2; return 1; fi; echo \"runner image: $what - download failed (attempt $n of 3), retrying in $((n * 15))s\" >&2; sleep $((n * 15)); n=$((n + 1)); done; }";
+/** The base both targets start from, pinned by digest. The tag alone floats:
+ *  `node:22-slim` is re-pushed for every Node patch and Debian point release,
+ *  and will change Debian release when the Node image decides to, so the
+ *  same runner tag — a hash of this text — could hold different bytes on two
+ *  rebuilds. With the digest in the text, new base bytes mean a new tag.
+ *
+ *  Debian 13 (trixie), not the 12 that `node:22-slim` still names: its glibc
+ *  (2.41) runs Lightpanda past 0.3.6, which wants 2.38; Debian 12 has 2.36.
+ *  Python is 3.13 here (3.11 on 12): runtime.ts checkEntry rebuilds a cached
+ *  venv whose interpreter moved, once per declaration.
+ *
+ *  Raise it on purpose (foldrun-infra/README.md, "Runner images"): read the
+ *  current digest of the tag, put it here, build both targets on both arches
+ *  and make one browse call per engine on the full image:
+ *    docker buildx imagetools inspect node:22-trixie-slim --format '{{json .Manifest}}' | jq -r .digest
+ *  The digest names the multi-arch index, so the one pin serves amd64 and
+ *  arm64 alike. */
+export declare const NODE_BASE = "node:22-trixie-slim@sha256:b26b04c123d9ff8ab646ceb18b9d75a1173acf64b9a401094b906d27b29338d4";
+export declare const DOCKERFILE = "FROM node:22-trixie-slim@sha256:b26b04c123d9ff8ab646ceb18b9d75a1173acf64b9a401094b906d27b29338d4 AS base\nRUN apt-get update \\\n && apt-get install -y --no-install-recommends python3 python3-venv ca-certificates bash util-linux tar openssh-client sshpass git curl \\\n && rm -rf /var/lib/apt/lists/* \\\n && useradd -m -u 10001 agent\n# uv builds the declared python environments (runtime.ts): a fraction of\n# pip's time, and it can fetch a pinned python the image does not carry.\nCOPY --from=ghcr.io/astral-sh/uv:0.11.25 /uv /uvx /usr/local/bin/\nENV PLAYWRIGHT_BROWSERS_PATH=/opt/browser NODE_PATH=/usr/local/lib/node_modules\n\nFROM base AS slim\n# Fonts, because a step that draws text without a browser still needs them:\n# the full image gets 51 from Playwright's --with-deps, slim had none, so from\n# 2026-09-29 (when non-browsing steps moved to slim) every resvg/sharp diagram\n# rendered its labels as empty boxes \u2014 expert-witness-desk's validator failed\n# four passes on a post image that was \"three empty boxes\". DejaVu covers\n# Latin, Greek and Cyrillic in a few MB; fontconfig is how renderers find it.\n# DejaVu alone still drew emoji, Chinese, Japanese, Korean, Devanagari and\n# Thai as empty boxes (reproduced 2026-10-01 with resvg-js 2.6 and sharp\n# 0.34), so four more, the smallest set that drew all of them \u2014 8 MB:\n#   Symbola     emoji and symbols, as outlines. NOT Noto Color Emoji (10 MB):\n#               resvg draws nothing from its bitmap glyphs, so a resvg\n#               diagram kept its empty boxes.\n#   WenQuanYi Micro Hei   Chinese, Japanese kana and Korean Hangul, one file.\n#   Lohit Devanagari, Loma   Hindi and Thai.\n# Here, not in base, so the full image's browser layers stay cached.\nRUN apt-get update \\\n && apt-get install -y --no-install-recommends fonts-dejavu-core fontconfig fonts-symbola fonts-wqy-microhei fonts-lohit-deva fonts-tlwg-loma-otf \\\n && rm -rf /var/lib/apt/lists/* \\\n && fc-cache -f >/dev/null\n# The Playwright client only, the same pinned version as the browser pod's\n# server (the wire protocol is version-locked), so a tool that imports it\n# still loads; there is nothing here for it to launch.\n# npm's download cache is dropped in the same layer: it was 190 MB of every\n# image, read by nothing after the build.\nRUN npm install -g playwright@1.63.0 axe-core@4.13.0 >/dev/null && npm cache clean --force >/dev/null 2>&1\nWORKDIR /opt/runner\nCOPY foldrun-core.tgz driver.mjs entry.sh ./\nRUN npm init -y >/dev/null && npm install ./foldrun-core.tgz --omit=dev \\\n && npm cache clean --force >/dev/null 2>&1 \\\n && mkdir -p /workspace /library /opt/runner/job /home/agent/.foldrun/runner/.runtimes /opt/foldrun-runtimes/shared/.runtimes \\\n && chown -R agent:agent /workspace /library /opt/runner /home/agent/.foldrun /opt/foldrun-runtimes \\\n && chmod +x /opt/runner/entry.sh\nENTRYPOINT [\"/opt/runner/entry.sh\"]\n\nFROM base AS browsers\n# Real browsers, because directories and portals increasingly render with\n# JavaScript and a plain fetch sees only the empty shell. Chromium is the one the\n# browser tool drives by default; Firefox and WebKit (Safari's engine) are\n# there for an agent asked to see a page the way those render it. Installed\n# to a fixed path the agent user can read (the default cache would be\n# root's HOME). The browsers' own sandboxes are disabled at launch time \u2014 in\n# this platform the container/gVisor IS the sandbox, and the two fight.\n# Pinned exactly, not @1: web browse's numbered elements use ariaSnapshot's\n# \"ai\" mode (1.59+), and the per-account browser pod runs this same image, so\n# a floating version would move both under a working tool on any rebuild.\n# Raise it on purpose, with the gallery tests and one real call.\n# axe-core beside it is web browse's mode=a11y: one file the tool injects\n# into the page; without it the mode falls back to its own shorter checks.\n# Xvfb by name: the browser pod starts it at boot and web browse starts one\n# per call for headless: false. It used to arrive only as one of Playwright's\n# --with-deps packages, so a Playwright bump that dropped it would have\n# broken every windowed browser without a word. No xauth: nothing here runs\n# xvfb-run, and Xvfb started without -auth takes the local client as it is.\nRUN apt-get update \\\n && apt-get install -y --no-install-recommends xvfb \\\n && rm -rf /var/lib/apt/lists/*\n# Google Chrome and Chrome beta come from Google's apt repository, which\n# Playwright adds; each is tried ENGINE_DOWNLOAD_ATTEMPTS times. Only on\n# x86_64: Google ships no Linux Chrome for arm64, so there it is not tried.\nRUN npm install -g playwright@1.63.0 axe-core@4.13.0 >/dev/null \\\n && playwright install --with-deps chromium firefox webkit >/dev/null \\\n && retry() { what=$1; shift; n=1; until \"$@\"; do if [ \"$n\" -ge 3 ]; then echo \"runner image: $what - download failed $n times, giving up\" >&2; return 1; fi; echo \"runner image: $what - download failed (attempt $n of 3), retrying in $((n * 15))s\" >&2; sleep $((n * 15)); n=$((n + 1)); done; } \\\n && if [ \"$(uname -m)\" = x86_64 ]; then \\\n      retry chrome playwright install --with-deps chrome >/dev/null || echo \"runner image: chrome not installed - engine: chrome would fall back to chromium\" >&2; \\\n      retry chrome-beta playwright install --with-deps chrome-beta >/dev/null || echo \"runner image: chrome-beta not installed\" >&2; \\\n    else echo \"runner image: no Google Chrome for $(uname -m) - engine: chrome falls back to chromium\"; fi \\\n && chmod -R a+rX /opt/browser \\\n && npm cache clean --force >/dev/null 2>&1\n# Lightpanda (engine: lightpanda): a browser that runs the JavaScript and\n# never draws \u2014 a fraction of Chromium's memory for reading and filling\n# pages. Its own program, which web browse starts beside a call and drives\n# over the DevTools protocol; shipped unmodified (AGPL-3.0). Pinned by\n# checksum (GitHub's own asset digests, checked again here). 0.4.1 since the\n# move to Debian 13: 0.3.7 on wants glibc 2.38, and Debian 12's 2.36 held it\n# at 0.3.6. An arch without a build leaves the engine out, and the tool says\n# so when asked for it. Each download (with its checksum) is tried\n# ENGINE_DOWNLOAD_ATTEMPTS times before the engine is left out.\n# Raise it on purpose: the new release's two sha256s, then one\n# engine=lightpanda call on each arch.\nRUN arch=$(uname -m) \\\n && case \"$arch\" in \\\n      x86_64) sum=1d40801e72c0bc61b2cbd3f3562bcfc46de7b79e0568f33f686b64f2e587610a ;; \\\n      aarch64) sum=664775c7f5ab69cc3189954c7f9345e25c167cb4dace016173e629f9a5e82c42 ;; \\\n      *) sum= ;; \\\n    esac \\\n && mkdir -p /opt/browser/lightpanda \\\n && retry() { what=$1; shift; n=1; until \"$@\"; do if [ \"$n\" -ge 3 ]; then echo \"runner image: $what - download failed $n times, giving up\" >&2; return 1; fi; echo \"runner image: $what - download failed (attempt $n of 3), retrying in $((n * 15))s\" >&2; sleep $((n * 15)); n=$((n + 1)); done; } \\\n && fetch() { curl -fsSL -o /opt/browser/lightpanda/lightpanda \"https://github.com/lightpanda-io/browser/releases/download/0.4.1/lightpanda-$arch-linux\" \\\n      && echo \"$sum  /opt/browser/lightpanda/lightpanda\" | sha256sum -c - >/dev/null; } \\\n && if [ -n \"$sum\" ] && retry lightpanda fetch; then \\\n      chmod a+rx /opt/browser/lightpanda/lightpanda && /opt/browser/lightpanda/lightpanda version; \\\n    else rm -f /opt/browser/lightpanda/lightpanda; echo \"runner image: lightpanda not installed for $arch - engine: lightpanda says so when asked\" >&2; fi\n# Obscura (engine: obscura): a headless browser in Rust around V8 that does\n# draw \u2014 screenshots, a raster PDF, a screencast \u2014 light like Lightpanda.\n# Apache-2.0. The plain build, not -stealth: this platform does not help a\n# page not see automation. Two binaries, obscura and obscura-worker, which\n# must sit side by side. Pinned by checksum; glibc 2.35 is its floor, so\n# Debian 13 (2.41) runs it. As above, a download is tried\n# ENGINE_DOWNLOAD_ATTEMPTS times, then a failed one leaves the engine out.\nRUN arch=$(uname -m) \\\n && case \"$arch\" in \\\n      x86_64) sum=1534d1e6ddaf3d080ec4091eb41d0a4d8cc042a48b607d3c410fc13b482a9eec ;; \\\n      aarch64) sum=5ecf980bca3060236a7a86ec7ed83d943e6598ee87caa46d20325d90bc75f979 ;; \\\n      *) sum= ;; \\\n    esac \\\n && mkdir -p /opt/browser/obscura \\\n && retry() { what=$1; shift; n=1; until \"$@\"; do if [ \"$n\" -ge 3 ]; then echo \"runner image: $what - download failed $n times, giving up\" >&2; return 1; fi; echo \"runner image: $what - download failed (attempt $n of 3), retrying in $((n * 15))s\" >&2; sleep $((n * 15)); n=$((n + 1)); done; } \\\n && fetch() { curl -fsSL -o /tmp/obscura.tgz \"https://github.com/h4ckf0r0day/obscura/releases/download/v0.2.3/obscura-$arch-linux.tar.gz\" \\\n      && echo \"$sum  /tmp/obscura.tgz\" | sha256sum -c - >/dev/null; } \\\n && if [ -n \"$sum\" ] && retry obscura fetch \\\n      && tar -xzf /tmp/obscura.tgz -C /opt/browser/obscura obscura obscura-worker; then \\\n      chmod a+rx /opt/browser/obscura/obscura /opt/browser/obscura/obscura-worker && /opt/browser/obscura/obscura --version; \\\n    else rm -rf /opt/browser/obscura/*; echo \"runner image: obscura not installed for $arch - engine: obscura says so when asked\" >&2; fi \\\n && rm -f /tmp/obscura.tgz\n# What this image actually has, written down: /opt/browser/engines.json, one\n# entry per engine (its path and version, or null when the install above\n# left it out) plus Xvfb. Chromium's version is its own --version (dotted,\n# so FOLDRUN_RUNNER_ENGINES carries it: a pinned user_agent on engine\n# chromium is compared with it, not with Google Chrome's) then the build.\n# web browse reads it for its \"built without\" answer, and the deploy reads\n# it to report the engines beside the version.\n# On x86_64 a missing engine FAILS the build: every engine ships for that\n# arch, so a gap there is a failed download, and an image that quietly lacks\n# the Chrome or Lightpanda a desk names would fail those runs instead. A\n# failed build leaves the previous image running and says why. Elsewhere\n# (arm64 has no Google Chrome) the gap is recorded and the image ships.\nRUN node -e ' \\\n  const fs = require(\"fs\"), cp = require(\"child_process\"), pw = require(\"playwright\"); \\\n  const at = (p) => (p && fs.existsSync(p) ? p : null); \\\n  const ver = (bin, args) => { try { return cp.execFileSync(bin, args, { timeout: 30000, stdio: [\"ignore\", \"pipe\", \"ignore\"] }).toString().trim().split(\"\\n\")[0] || null; } catch { return null; } }; \\\n  const one = (p, v) => (p ? { path: p, version: v } : null); \\\n  const pwBuild = (p) => (p ? (p.match(/(chromium|firefox|webkit)-(\\d+)/) || [])[0] || null : null); \\\n  const lp = at(\"/opt/browser/lightpanda/lightpanda\"); \\\n  const cr = at(pw.chromium.executablePath()); \\\n  const ob = at(\"/opt/browser/obscura/obscura-worker\") && at(\"/opt/browser/obscura/obscura\"); \\\n  const engines = { \\\n    chromium: one(cr, cr && [ver(cr, [\"--version\"]), pwBuild(cr)].filter(Boolean).join(\" \")), \\\n    chrome: one(at(\"/opt/google/chrome/chrome\"), ver(\"/opt/google/chrome/chrome\", [\"--version\"])), \\\n    \"chrome-beta\": one(at(\"/opt/google/chrome-beta/chrome\"), ver(\"/opt/google/chrome-beta/chrome\", [\"--version\"])), \\\n    firefox: one(at(pw.firefox.executablePath()), pwBuild(pw.firefox.executablePath())), \\\n    webkit: one(at(pw.webkit.executablePath()), pwBuild(pw.webkit.executablePath())), \\\n    lightpanda: one(lp, lp && ver(lp, [\"version\"])), \\\n    obscura: one(ob, ob && ver(ob, [\"--version\"])), \\\n  }; \\\n  const xvfb = ver(\"sh\", [\"-c\", \"command -v Xvfb\"]); \\\n  const arch = cp.execFileSync(\"uname\", [\"-m\"]).toString().trim(); \\\n  const manifest = { arch, playwright: require(\"playwright/package.json\").version, engines, xvfb }; \\\n  fs.writeFileSync(\"/opt/browser/engines.json\", JSON.stringify(manifest, null, 2) + \"\\n\"); \\\n  console.log(JSON.stringify(manifest)); \\\n  const missing = [\"chromium\", \"chrome\", \"firefox\", \"webkit\", \"lightpanda\", \"obscura\"].filter((e) => !engines[e]).concat(xvfb ? [] : [\"Xvfb\"]); \\\n  if (missing.length && arch === \"x86_64\") { \\\n    console.error(\"runner image: MISSING ENGINES on x86_64: \" + missing.join(\", \")); \\\n    console.error(\"runner image: every engine ships for x86_64, so a missing one is a failed download (the retry lines above say which) - failing the build\"); \\\n    process.exit(1); \\\n  } \\\n  if (missing.length) console.error(\"runner image: built without \" + missing.join(\", \") + \" on \" + arch); \\\n ' \\\n && chmod a+r /opt/browser/engines.json\n\nFROM browsers AS full\nWORKDIR /opt/runner\nCOPY foldrun-core.tgz driver.mjs entry.sh ./\nRUN npm init -y >/dev/null && npm install ./foldrun-core.tgz --omit=dev \\\n && npm cache clean --force >/dev/null 2>&1 \\\n && mkdir -p /workspace /library /opt/runner/job /home/agent/.foldrun/runner/.runtimes /opt/foldrun-runtimes/shared/.runtimes \\\n && chown -R agent:agent /workspace /library /opt/runner /home/agent/.foldrun /opt/foldrun-runtimes \\\n && chmod +x /opt/runner/entry.sh\nENTRYPOINT [\"/opt/runner/entry.sh\"]\n";
+/** Which build target of the runner image (see DOCKERFILE). */
+export type RunnerVariant = "full" | "slim";
+export declare function runnerImageTag(variant?: RunnerVariant): string;
 /**
  * Build the runner image if this exact (core version, driver, dockerfile)
  * has not been built before. `npm pack` of the installed core, so the image
@@ -186,12 +288,43 @@ export declare function runnerImageTag(): string;
  * (tonistiigi/binfmt); the publisher does that itself, every time, because
  * the registration does not survive a reboot.
  */
+/**
+ * Which image a step runs in: an explicit FOLDRUN_RUNNER_IMAGE when one is
+ * set, otherwise the content-hash tag core builds itself. `explicit` is what
+ * ensureRunnerImage checks to skip the build — an empty string is *not* an
+ * image name (it is `docker build -t ""` → "repository name must have at
+ * least one component"), so it falls through to the content-hash tag exactly
+ * as an unset value does. Pure, so the resolution is testable without docker.
+ */
+export declare function runnerImageRef(opts?: {
+    platform?: string;
+    variant?: RunnerVariant;
+}): {
+    tag: string;
+    explicit: boolean;
+};
 export declare function ensureRunnerImage(opts?: {
     platform?: string;
+    variant?: RunnerVariant;
 }): {
     tag: string;
     log: string[];
 };
+/**
+ * What a failed runner build's error says: the lines that name the failure,
+ * then the end of the log. Only the last 2000 characters used to survive,
+ * and BuildKit ends a failed RUN by echoing the instruction — the engines
+ * probe is a long one — so "chrome missing" scrolled out of the very error
+ * that existed to say it. Every engine line the DOCKERFILE prints starts
+ * "runner image:" (the retries, the giving up, the MISSING ENGINES line);
+ * those are kept, from anywhere in the log, with BuildKit's "#12 3.456 "
+ * prefix taken off, and so are BuildKit's own ERROR lines (each cut short:
+ * they quote the whole instruction). Pure, so it is tested on fixtures.
+ */
+export declare function buildFailureSummary(log: string, opts?: {
+    tail?: number;
+    maxLines?: number;
+}): string;
 export declare function parseDriverLine(line: string): {
     e: "event";
     type: "text" | "tool" | "info" | "error";
@@ -199,6 +332,9 @@ export declare function parseDriverLine(line: string): {
     call?: string;
     ms?: number;
     err?: boolean;
+    operator?: OperatorEvent;
+    subagent?: string;
+    check?: boolean;
 } | ({
     e: "done";
 } & ContainerStepOutcome) | null;