@foldrun/core 0.3.0 → 0.5.0

package/dist/src/approvals.js

@@ -9,8 +9,125 @@
 // or a run approved from a phone would resume differently from one approved
 // at a desk. So the decision lives in core and the routes only say who made
 // it.
-import { readRun, writeRun } from "./store.js";
+import crypto from "node:crypto";
+import { readRun, writeRun, readFlow, mayApprove } from "./store.js";
 import { platform } from "./platform.js";
+import { approveToken, installKey } from "./webhook.js";
+// ----------------------------------------------------------------- links
+/** How long an emailed link decides for when the flow does not say. */
+export const APPROVE_LINK_DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/** The link's lifetime: the flow's `approve_within:` when it has one —
+ *  after that the gate has expired on its own — else a week. */
+export function approveLinkTtlMs(flow) {
+    return flow?.approveWithin ? flow.approveWithin * 1000 : APPROVE_LINK_DEFAULT_TTL_MS;
+}
+const b64 = (s) => Buffer.from(s, "utf8").toString("base64url");
+const unb64 = (s) => Buffer.from(s, "base64url").toString("utf8");
+function signLink(tenant, workspace, runId, step, expires, approver) {
+    return crypto
+        .createHmac("sha256", installKey())
+        .update(`approve-link:${tenant}/${workspace}/${runId}/${step}/${expires}/${approver}`)
+        .digest("hex")
+        .slice(0, 32);
+}
+/**
+ * The token an emailed link carries. Bound to one step of one run and to
+ * a moment, and — when the notification went to a named approver — to
+ * that person, so the link decides as them. A link that was only bound
+ * to the run approved every later gate of that run for as long as it ran,
+ * and a forwarded one let anyone past `approvers:`.
+ *
+ * `step.expires.approver.signature`; the signature covers all of it plus
+ * the run's identity, under the install key, so rotating the key kills
+ * every link at once, the way it kills every hook.
+ */
+export function approveLinkToken(tenant, workspace, runId, link) {
+    const approver = (link.approver ?? "").trim().toLowerCase();
+    const expires = Math.floor(link.expiresAt);
+    return `${link.step}.${expires}.${approver ? b64(approver) : "-"}.${signLink(tenant, workspace, runId, link.step, expires, approver)}`;
+}
+/** The path an emailed link opens — absolute when the caller prefixes the
+ *  install's public origin. `decision=reject` pre-selects; a GET never
+ *  decides. */
+export function approveLinkPath(tenant, workspace, runId, link) {
+    return `/api/approve/${tenant}/${workspace}/${runId}?token=${approveLinkToken(tenant, workspace, runId, link)}`;
+}
+const same = (a, b) => a.length === b.length && crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b));
+/**
+ * What a presented token is, or why it is nothing. 401 for a token that
+ * was never minted for this run, 410 for one that was and has expired —
+ * the second deserves a sentence, because the person holding it did
+ * nothing wrong.
+ */
+export function readApproveLink(tenant, workspace, runId, presented, now = Date.now()) {
+    const invalid = { error: "invalid token", status: 401 };
+    if (!presented)
+        return invalid;
+    const parts = presented.split(".");
+    if (parts.length === 4) {
+        const [stepText, expText, approverText, sig] = parts;
+        if (!/^\d+$/.test(stepText) || !/^\d+$/.test(expText))
+            return invalid;
+        let approver = "";
+        try {
+            approver = approverText === "-" ? "" : unb64(approverText);
+        }
+        catch {
+            return invalid;
+        }
+        const step = Number(stepText);
+        const expires = Number(expText);
+        if (!same(sig, signLink(tenant, workspace, runId, step, expires, approver)))
+            return invalid;
+        if (now >= expires)
+            return { error: "this link has expired — open the run in the dashboard to decide it", status: 410 };
+        return { link: { kind: "step", step, expiresAt: new Date(expires).toISOString(), approver: approver || null } };
+    }
+    if (same(presented, approveToken(tenant, workspace, runId)))
+        return { link: { kind: "run" } };
+    return invalid;
+}
+/** A used link is written on the run as a digest, never the token. */
+const linkDigest = (token) => crypto.createHash("sha256").update(token).digest("hex").slice(0, 24);
+/**
+ * Everything a link has to pass before it decides anything, answered the
+ * same way for the page that shows the gate and the POST that decides it.
+ * Returns which waiting steps the link may decide and who it decides as.
+ */
+export function checkApproveLink(tenant, workspace, run, presented, now = Date.now()) {
+    const read = readApproveLink(tenant, workspace, run.id, presented, now);
+    if ("error" in read)
+        return { ok: false, status: read.status, message: read.error };
+    const { link } = read;
+    if (run.approvalLinksUsed?.includes(linkDigest(presented))) {
+        return { ok: false, status: 409, message: "this link was already used — a link decides once" };
+    }
+    // The older, run-bound link: kept for runs already waiting, but not for
+    // longer than a new link would have been.
+    if (link.kind === "run") {
+        const since = Date.parse(run.parkedAt ?? run.startedAt);
+        if (Number.isFinite(since) && now - since > APPROVE_LINK_DEFAULT_TTL_MS) {
+            return { ok: false, status: 410, message: "this link has expired — open the run in the dashboard to decide it" };
+        }
+    }
+    const waiting = run.steps
+        .map((s, i) => ({ s, i }))
+        .filter(({ s, i }) => s.status === "awaiting-approval" && s.waitFor !== "event" && (link.kind === "run" || i === link.step))
+        .map(({ i }) => i);
+    const approver = link.kind === "step" ? link.approver : null;
+    // A flow that names its approvers is asking for a person; a link is a
+    // possession. Only a link minted for one of the named approvers carries
+    // enough of an identity to be checked against the list.
+    const flow = readFlow(tenant, workspace, run.flow);
+    if (flow?.approvers?.length && !approver) {
+        return {
+            ok: false,
+            status: 403,
+            message: `this flow names who may approve it (${flow.approvers.join(", ")}), and an emailed link carries no identity — sign in to the dashboard to decide it`,
+        };
+    }
+    return { ok: true, link, steps: waiting, approver };
+}
 /** An error the HTTP layer can map straight to a status — see errorResponse. */
 class ApprovalError extends Error {
     status;
@@ -32,9 +149,19 @@ export async function decideApproval(tenant, workspace, runId, d) {
     const run = readRun(tenant, workspace, runId);
     if (!run)
         throw new ApprovalError("run not found", 404);
+    // A link decides what it was minted for, as whom it was minted for.
+    let allowed = null;
+    if (d.link !== undefined) {
+        const check = checkApproveLink(tenant, workspace, run, d.link);
+        if (!check.ok)
+            throw new ApprovalError(check.message, check.status);
+        allowed = check.steps;
+        d = { ...d, actor: check.approver ? { email: check.approver, role: null } : null };
+    }
+    assertMayDecide(tenant, workspace, run, d);
     const waiting = run.steps
         .map((s, i) => ({ s, i }))
-        .filter(({ s, i }) => s.status === "awaiting-approval" && (d.step === undefined || d.step === i));
+        .filter(({ s, i }) => s.status === "awaiting-approval" && (d.step === undefined || d.step === i) && (allowed === null || allowed.includes(i)));
     if (waiting.length === 0)
         throw new ApprovalError("nothing is awaiting approval", 409);
     const note = typeof d.note === "string" ? d.note.trim() : "";
@@ -62,6 +189,17 @@ export async function decideApproval(tenant, workspace, runId, d) {
                 : `rejected ${d.by}${reason ? `: ${reason.slice(0, 200)}` : ""}`,
         });
     }
+    // The deadline belonged to the gate that just closed. Leaving it on the
+    // record would hand a later gate in the same run a deadline that has
+    // already passed.
+    if (run.steps.every((s) => s.status !== "awaiting-approval"))
+        run.approveBy = null;
+    // A link decides once. Written as a digest on the record, so a step that
+    // parks again — a loop, a rerun from the gate — is not decided by the
+    // same forwarded mail.
+    if (d.link !== undefined) {
+        run.approvalLinksUsed = [...(run.approvalLinksUsed ?? []), linkDigest(d.link)].slice(-50);
+    }
     writeRun(tenant, workspace, run);
     // A parked run has no process polling for this decision — the worker
     // that was driving it gave its slot back at the gate. Line it up again.
@@ -72,6 +210,58 @@ export async function decideApproval(tenant, workspace, runId, d) {
     }
     return { run, steps: waiting.map(({ i }) => i) };
 }
+/**
+ * The two rules a person's decision has to pass. A token-bearing door — the
+ * emailed link, an external event — carries no actor and is not checked
+ * here: possession of a token derived from the run is its own authority,
+ * and the link was mailed to whoever the account told us to ask.
+ *
+ * Throws 403, which the routes surface verbatim: a refusal that does not say
+ * which rule refused sends someone to the wrong settings page.
+ */
+function assertMayDecide(tenant, workspace, run, d) {
+    if (!d.actor)
+        return;
+    const email = (d.actor.email ?? "").trim().toLowerCase();
+    // Rejecting your own run is always allowed: stopping something you started
+    // needs no second opinion, and the gate's whole purpose is that it does
+    // not proceed. Only approval needs someone else.
+    if (d.decision === "approve" && email && run.startedBy && run.startedBy === email) {
+        throw new ApprovalError("you started this run — an approval gate asks a second person, so someone else has to answer it", 403);
+    }
+    const flow = readFlow(tenant, workspace, run.flow);
+    if (!mayApprove(flow, d.actor)) {
+        throw new ApprovalError(`this flow's approvers: list does not include you (${flow?.approvers?.join(", ")})`, 403);
+    }
+}
+/**
+ * A gate that ran out of time. `approve_within:` in the flow file stamps a
+ * deadline when the run parks; past it, the gate is rejected and the run
+ * fails, exactly as if a person had said no.
+ *
+ * Rejection, not approval, is the only safe way for a clock to answer a
+ * question a person was asked. The whole reason the step is parked is that
+ * someone wanted to look at it first.
+ *
+ * Returns whether it acted. Called from the same sweep that closes abandoned
+ * runs, so an expiry needs nothing running of its own.
+ */
+export async function expireStaleGate(tenant, workspace, run, now = Date.now()) {
+    if (run.status !== "awaiting-approval" || !run.approveBy)
+        return false;
+    if (now < new Date(run.approveBy).getTime())
+        return false;
+    // A step waiting on `wait: event` is not waiting on a person and is not
+    // this deadline's business.
+    if (!run.steps.some((s) => s.status === "awaiting-approval" && s.waitFor !== "event"))
+        return false;
+    await decideApproval(tenant, workspace, run.id, {
+        decision: "reject",
+        by: "automatically — nobody answered in time",
+        reason: `no decision within the flow's approve_within: (due ${run.approveBy})`,
+    });
+    return true;
+}
 /**
  * Release a run parked on `wait: event` with what arrived. The payload is
  * stored on the step — not as an approval note, which is a person's

package/dist/src/browser-pod.d.ts

@@ -0,0 +1,129 @@
+/** Set by the platform on a step it put on the slim image to browse
+ *  through the pod. The web tool then never launches a browser of its own. */
+export declare const POD_ONLY_ENV = "FOLDRUN_BROWSER_POD_ONLY";
+/** Where the web tool appends one JSON line per reconnect, and the line
+ *  that says the pod is lost or the call needs the full image. */
+export declare const POD_EVENTS_ENV = "FOLDRUN_BROWSER_POD_EVENTS";
+/** The file, inside the step's sandbox. */
+export declare const POD_EVENTS_FILE = "/tmp/foldrun-browser-pod.jsonl";
+/** The note the run carries when the fallback was taken. Worded once. */
+export declare const RERAN_ON_FULL = "browser pod lost; re-ran on full";
+/**
+ * Browse actions that can change something beyond the page in front of the
+ * model: anything that types, picks, submits, signs in, uploads, runs script
+ * or pays. A click is here because a click can submit and nothing before
+ * the click can tell. The web tool's run.mjs carries a copy (it decides
+ * whether a dropped call may be repeated); the gallery test holds the two
+ * equal.
+ */
+export declare const BROWSE_WRITE_ACTIONS: readonly ["click", "dblclick", "rightclick", "tap", "swipe", "mouse", "drag", "fill", "type", "insert", "paste", "press", "keyboard", "keydown", "keyup", "clear", "select", "check", "uncheck", "upload", "dialog", "login", "eval", "webmcp", "solve"];
+export type CallKind = {
+    write: false;
+} | {
+    write: true;
+    what: string;
+};
+export interface ClassifyContext {
+    /** SDK tool name → HTTP method, for an API's typed operations (api-tools
+     *  builds the map; a generic call_<api> carries its method in the input). */
+    methods?: Record<string, string>;
+    /** Web actions a paid provider answers this step — from the env's
+     *  FOLDRUN_WEB_<ACTION>_VIA. */
+    paidWeb?: Record<string, string>;
+}
+/** The browse actions a call asked for, nested `if` branches included. */
+export declare function browseActionNames(actions: unknown): string[];
+/** What a browse call's arguments would write, or null when it only reads. */
+export declare function browseWrites(input: Record<string, unknown>): string | null;
+/**
+ * Whether one tool call can have changed anything outside the model's head,
+ * and if so, a few words saying what. Pure.
+ */
+export declare function classifyCall(tool: string, input: Record<string, unknown> | undefined, ctx?: ClassifyContext): CallKind;
+/** Paid web actions, from a step's env (FOLDRUN_WEB_<ACTION>_VIA=provider). */
+export declare function paidWebActions(env: Record<string, string | undefined>): Record<string, string>;
+/** One line of the web tool's pod log. */
+export interface PodEvent {
+    kind: "reconnect" | "lost" | "needs-full";
+    /** reconnect: which try, of how many, and whether it got through. */
+    attempt?: number;
+    of?: number;
+    ok?: boolean;
+    /** lost: whether the call ran on the pod at all before it was lost — a
+     *  call that never connected changed nothing, whatever it asked for. */
+    ran?: boolean;
+    error?: string;
+    why?: string;
+    /** When the web tool wrote the line (ISO). */
+    at?: string;
+}
+/** ", at 10:15:15Z" from a pod log line's `at`; empty when it has none. */
+export declare function podAt(at: unknown): string;
+/** Lines of the pod log from byte `offset` on, and where the next read
+ *  starts. A torn last line waits for the next read. */
+export declare function readPodEvents(text: string, offset: number): {
+    events: PodEvent[];
+    next: number;
+};
+/** What crosses back from a step that browsed through the pod. */
+export interface BrowserPodOutcome {
+    /** Reconnect tries the web tool made, and how many got through: the pod
+     *  answered and the call went on, rather than dropping again at once. */
+    reconnects: number;
+    reconnected: number;
+    /** Reconnects that reached the pod, after which the call dropped again at
+     *  once — a pod still answering while it shut down. Never "got through". */
+    closedAgain?: number;
+    /** Set when the step stopped because the pod was gone (or a call needed
+     *  a browser in the step, which slim does not have). */
+    lost?: {
+        cause: "lost" | "needs-full";
+        detail: string;
+    };
+    /** What the step had written by then, worded — empty means reads only. */
+    writes?: string[];
+}
+/** "a.md (Write), crm POST and 2 more". */
+export declare function describeWrites(writes: string[]): string;
+/** The decision, once the pod is gone: re-run on full, or fail and say why. */
+export declare function podLossDecision(pod: BrowserPodOutcome): {
+    rerun: true;
+    note: string;
+} | {
+    rerun: false;
+    message: string;
+};
+/**
+ * Why a browsing step must have a browser in its own sandbox, from what the
+ * step start can see (the agent's `web.browse` block, as env), or null when
+ * the account's pod can serve every call it could make by default. A call
+ * that picks an in-step engine itself is caught at the call (needs-full).
+ */
+export declare function slimBrowseBlocker(env: Record<string, string | undefined>): string | null;
+/** The outcome as it crosses back from the sandbox, checked field by field
+ *  (the done line is the pod's word); null when absent or not this shape. */
+export declare function parseBrowserPod(v: unknown): BrowserPodOutcome | null;
+/** One line for a person: "2 reconnects (2 got through)", "browser pod
+ *  lost; re-ran on full", or the failure. What the run page, `foldrun
+ *  report` and an attempt row say. A pod that was lost in the end is never
+ *  said to have let a reconnect through — "1 reconnect (1 got through); pod
+ *  lost" read live as a contradiction — and a reconnect that reached the pod
+ *  only for the call to drop again says that. */
+export declare function browserPodLine(p: BrowserPodOutcome & {
+    fallback?: string;
+    failure?: string;
+}): string;
+/** What podTriesLine reads of a StepAttempt (store.ts) — structural, so
+ *  this module stays free of the store's imports for the CLI and the web. */
+export interface TryRow {
+    n: number;
+    status: string;
+    image?: string;
+    costUsd: number | null;
+}
+/** A step's tries in one line when the browser pod was lost under one of
+ *  them — "slim · lost · $0.0040 → full · completed · $0.0060" — so the run
+ *  page and `foldrun report` show the slim go and the full re-run apart.
+ *  `#n` leads each try when the step had more than one attempt. Null when
+ *  no try was lost. */
+export declare function podTriesLine(tries: readonly TryRow[] | null | undefined): string | null;

package/dist/src/browser-pod.js

@@ -0,0 +1,284 @@
+// Slim browsing: a step whose only reason for the full runner image is that
+// it browses may run on the slim image and drive the account's browser pod
+// over Playwright's protocol. The pod can go away mid-step — a node drained,
+// the idle reaper, an OOM — and a slim step has no browser of its own to fall
+// back on. So:
+//
+//   1. The web tool reconnects first: a few tries, short backoff (the tool's
+//      run.mjs; each try is an event in FOLDRUN_BROWSER_POD_EVENTS).
+//   2. Still gone: the step stops, and what it has done so far decides.
+//      Only reads — re-run the whole step from the start on the full image,
+//      and say so on the run ("browser pod lost; re-ran on full").
+//   3. Anything written — fail the step: "browser pod died after the step had
+//      written <what>". Doing it again could send, post or charge twice, so
+//      retry:, on-fail: or a person decides.
+//
+// Read or write is decided from the calls the step made, as the model asked
+// for them (step-exec.ts keeps the ledger). When a call could be either it
+// counts as a write: the cost of being wrong that way is a failed step a
+// retry can redo; the other way it is a duplicate email.
+//
+// Steps that act outward (a tool marked `outward: true`) never run slim; nor
+// does anything the step start can already see needs a browser in the step
+// (lightpanda, obscura, live sessions, extensions) — slimBrowseBlocker.
+/** Set by the platform on a step it put on the slim image to browse
+ *  through the pod. The web tool then never launches a browser of its own. */
+export const POD_ONLY_ENV = "FOLDRUN_BROWSER_POD_ONLY";
+/** Where the web tool appends one JSON line per reconnect, and the line
+ *  that says the pod is lost or the call needs the full image. */
+export const POD_EVENTS_ENV = "FOLDRUN_BROWSER_POD_EVENTS";
+/** The file, inside the step's sandbox. */
+export const POD_EVENTS_FILE = "/tmp/foldrun-browser-pod.jsonl";
+/** The note the run carries when the fallback was taken. Worded once. */
+export const RERAN_ON_FULL = "browser pod lost; re-ran on full";
+/**
+ * Browse actions that can change something beyond the page in front of the
+ * model: anything that types, picks, submits, signs in, uploads, runs script
+ * or pays. A click is here because a click can submit and nothing before
+ * the click can tell. The web tool's run.mjs carries a copy (it decides
+ * whether a dropped call may be repeated); the gallery test holds the two
+ * equal.
+ */
+export const BROWSE_WRITE_ACTIONS = [
+    "click", "dblclick", "rightclick", "tap", "swipe", "mouse", "drag",
+    "fill", "type", "insert", "paste", "press", "keyboard", "keydown", "keyup", "clear",
+    "select", "check", "uncheck", "upload", "dialog", "login", "eval", "webmcp", "solve",
+];
+/** Call arguments of web action=browse that are writes whatever the actions:
+ *  page script, a paid captcha solver, a confirmation of a credential step. */
+const BROWSE_WRITE_ARGS = ["js", "captcha", "captcha_solver", "confirm"];
+/** Web actions that only read — when foldrun's own answers them. A paid
+ *  provider answering one (FOLDRUN_WEB_<ACTION>_VIA) makes it a write: doing
+ *  it twice is paying twice. `monitor` keeps state, so it always writes. */
+const WEB_READ_ACTIONS = new Set(["search", "fetch", "browse", "crawl", "map", "extract", "answer"]);
+/** Built-ins that read and change nothing. */
+const READ_BUILTINS = new Set(["Read", "Glob", "Grep", "WebSearch", "WebFetch", "TodoWrite", "LS", "NotebookRead"]);
+/** The platform's own tool groups that only read. Consults are a toolless
+ *  answer; a delegation's own calls come through on their own. */
+const READ_SERVERS = new Set(["foldrun_search", "foldrun_history", "foldrun_desks", "foldrun_agents"]);
+const DELEGATE = new Set(["Agent", "Task"]);
+/** The browse actions a call asked for, nested `if` branches included. */
+export function browseActionNames(actions) {
+    let steps = actions;
+    if (typeof steps === "string") {
+        try {
+            steps = JSON.parse(steps);
+        }
+        catch {
+            return ["(unreadable actions)"];
+        }
+    }
+    const out = [];
+    const walk = (v, depth) => {
+        if (depth > 8 || v === null || typeof v !== "object")
+            return;
+        if (Array.isArray(v)) {
+            for (const x of v)
+                walk(x, depth + 1);
+            return;
+        }
+        for (const [k, x] of Object.entries(v)) {
+            out.push(k);
+            walk(x, depth + 1);
+        }
+    };
+    walk(steps, 0);
+    return out;
+}
+/** What a browse call's arguments would write, or null when it only reads. */
+export function browseWrites(input) {
+    const names = browseActionNames(input.actions);
+    if (names.includes("(unreadable actions)"))
+        return "browse actions it could not read";
+    const writes = [...new Set(names.filter((n) => BROWSE_WRITE_ACTIONS.includes(n)))];
+    if (writes.length)
+        return `browse ${writes.join("/")}`;
+    const arg = BROWSE_WRITE_ARGS.find((a) => input[a] !== undefined && input[a] !== null && input[a] !== "" && input[a] !== false);
+    if (arg)
+        return `browse ${arg}=`;
+    return null;
+}
+/**
+ * Whether one tool call can have changed anything outside the model's head,
+ * and if so, a few words saying what. Pure.
+ */
+export function classifyCall(tool, input, ctx = {}) {
+    const args = input ?? {};
+    const write = (what) => ({ write: true, what });
+    if (READ_BUILTINS.has(tool) || DELEGATE.has(tool))
+        return { write: false };
+    if (tool === "Write" || tool === "Edit" || tool === "MultiEdit" || tool === "NotebookEdit") {
+        const raw = String(args.file_path ?? args.notebook_path ?? args.path ?? "");
+        const file = raw.startsWith("/workspace/") ? raw.slice("/workspace/".length) : raw.split("/").slice(-3).join("/");
+        return write(file ? `${file} (${tool})` : `a file (${tool})`);
+    }
+    if (tool === "Bash")
+        return write("a shell command");
+    const mcp = /^mcp__(.+?)__(.+)$/.exec(tool);
+    if (!mcp)
+        return write(tool); // unknown: a write until shown otherwise
+    const [, server, name] = mcp;
+    if (READ_SERVERS.has(server))
+        return { write: false };
+    if (server === "foldrun_ask")
+        return write("a question to a person");
+    if (server === "foldrun_scripts") {
+        if (name !== "web")
+            return write(`script ${name}`);
+        const action = String(args.action ?? "").trim().toLowerCase();
+        if (!WEB_READ_ACTIONS.has(action))
+            return write(action === "monitor" ? "web monitor state" : `web ${action || "call"}`);
+        const paid = ctx.paidWeb?.[action];
+        if (paid)
+            return write(`a paid ${paid} ${action}`);
+        if (action === "browse") {
+            const w = browseWrites(args);
+            if (w)
+                return write(w);
+        }
+        return { write: false };
+    }
+    if (server === "foldrun_apis") {
+        const method = String(name.startsWith("call_") ? (args.method ?? "GET") : (ctx.methods?.[tool] ?? "")).toUpperCase();
+        const api = name.replace(/^call_/, "");
+        if (method === "GET" || method === "HEAD")
+            return { write: false };
+        return write(`${api} ${method || "call"}`);
+    }
+    // Any other MCP server: its tools could do anything.
+    return write(`${server} ${name}`);
+}
+/** Paid web actions, from a step's env (FOLDRUN_WEB_<ACTION>_VIA=provider). */
+export function paidWebActions(env) {
+    const out = {};
+    for (const [k, v] of Object.entries(env)) {
+        const m = /^FOLDRUN_WEB_([A-Z]+)_VIA$/.exec(k);
+        if (m && v)
+            out[m[1].toLowerCase()] = v;
+    }
+    if (env.FOLDRUN_BROWSER_VENDOR)
+        out.browse = env.FOLDRUN_BROWSER_VENDOR;
+    return out;
+}
+/** ", at 10:15:15Z" from a pod log line's `at`; empty when it has none. */
+export function podAt(at) {
+    if (typeof at !== "string")
+        return "";
+    const t = Date.parse(at);
+    return Number.isNaN(t) ? "" : `, at ${new Date(t).toISOString().slice(11, 19)}Z`;
+}
+/** Lines of the pod log from byte `offset` on, and where the next read
+ *  starts. A torn last line waits for the next read. */
+export function readPodEvents(text, offset) {
+    const chunk = text.slice(offset);
+    const end = chunk.lastIndexOf("\n");
+    if (end < 0)
+        return { events: [], next: offset };
+    const events = [];
+    for (const line of chunk.slice(0, end).split("\n")) {
+        try {
+            const e = JSON.parse(line);
+            if (e && (e.kind === "reconnect" || e.kind === "lost" || e.kind === "needs-full"))
+                events.push(e);
+        }
+        catch {
+            // not ours
+        }
+    }
+    return { events, next: offset + end + 1 };
+}
+/** "a.md (Write), crm POST and 2 more". */
+export function describeWrites(writes) {
+    const uniq = [...new Set(writes)];
+    if (uniq.length > 3)
+        return `${uniq.slice(0, 3).join(", ")} and ${uniq.length - 3} more`;
+    if (uniq.length <= 1)
+        return uniq[0] ?? "something";
+    return `${uniq.slice(0, -1).join(", ")} and ${uniq.at(-1)}`;
+}
+/** The decision, once the pod is gone: re-run on full, or fail and say why. */
+export function podLossDecision(pod) {
+    const writes = pod.writes ?? [];
+    const cause = pod.lost?.cause === "needs-full" ? `a call needed a browser in the step (${pod.lost.detail})` : `browser pod lost (${pod.lost?.detail ?? "connection closed"})`;
+    if (!writes.length)
+        return { rerun: true, note: `${RERAN_ON_FULL} — ${cause}; the step had only read, so it ran again from the start on the full image` };
+    const head = pod.lost?.cause === "needs-full"
+        ? `a call needed a browser in the step after the step had written ${describeWrites(writes)}`
+        : `browser pod died after the step had written ${describeWrites(writes)}`;
+    return { rerun: false, message: `${head} — not re-run, since doing it again could repeat that; retry:, on-fail: or a person decides (${pod.lost?.detail ?? "connection closed"})` };
+}
+/**
+ * Why a browsing step must have a browser in its own sandbox, from what the
+ * step start can see (the agent's `web.browse` block, as env), or null when
+ * the account's pod can serve every call it could make by default. A call
+ * that picks an in-step engine itself is caught at the call (needs-full).
+ */
+export function slimBrowseBlocker(env) {
+    if (env.FOLDRUN_BROWSER_VENDOR)
+        return `web.browse names ${env.FOLDRUN_BROWSER_VENDOR}`;
+    if (env.FOLDRUN_BROWSER_LIVE === "1")
+        return "web.browse live: sessions run in the step";
+    const engine = (env.FOLDRUN_BROWSER_ENGINE ?? "").trim().toLowerCase();
+    if (engine === "lightpanda" || engine === "obscura")
+        return `engine ${engine} runs in the step`;
+    if (env.FOLDRUN_BROWSER_EXTENSIONS)
+        return "extensions load into a browser in the step";
+    return null;
+}
+/** The outcome as it crosses back from the sandbox, checked field by field
+ *  (the done line is the pod's word); null when absent or not this shape. */
+export function parseBrowserPod(v) {
+    if (!v || typeof v !== "object")
+        return null;
+    const o = v;
+    const n = (x) => (typeof x === "number" && Number.isFinite(x) && x >= 0 ? Math.floor(x) : 0);
+    const out = { reconnects: n(o.reconnects), reconnected: n(o.reconnected) };
+    if (n(o.closedAgain))
+        out.closedAgain = n(o.closedAgain);
+    const lost = o.lost;
+    if (lost && typeof lost === "object" && (lost.cause === "lost" || lost.cause === "needs-full")) {
+        out.lost = { cause: lost.cause, detail: String(lost.detail ?? "").slice(0, 300) };
+        out.writes = Array.isArray(o.writes) ? o.writes.slice(0, 50).map((w) => String(w).slice(0, 120)) : [];
+    }
+    return out;
+}
+/** One line for a person: "2 reconnects (2 got through)", "browser pod
+ *  lost; re-ran on full", or the failure. What the run page, `foldrun
+ *  report` and an attempt row say. A pod that was lost in the end is never
+ *  said to have let a reconnect through — "1 reconnect (1 got through); pod
+ *  lost" read live as a contradiction — and a reconnect that reached the pod
+ *  only for the call to drop again says that. */
+export function browserPodLine(p) {
+    const count = `${p.reconnects} reconnect${p.reconnects === 1 ? "" : "s"}`;
+    const tries = !p.reconnects
+        ? "no reconnects"
+        : !p.lost
+            ? `${count} (${p.reconnected} got through)`
+            : p.closedAgain
+                ? `${count}, ${p.reconnects === 1 ? "which" : "the last"} reached the pod but it closed again`
+                : count;
+    if (p.failure)
+        return `${tries}; ${p.failure}`;
+    if (p.fallback)
+        return `${tries}; ${p.fallback}${p.lost ? ` (${p.lost.detail})` : ""}`;
+    if (p.lost)
+        return `${tries}; ${p.lost.cause === "needs-full" ? "needed a browser in the step" : "pod lost"}: ${p.lost.detail}`;
+    return tries;
+}
+/** A step's tries in one line when the browser pod was lost under one of
+ *  them — "slim · lost · $0.0040 → full · completed · $0.0060" — so the run
+ *  page and `foldrun report` show the slim go and the full re-run apart.
+ *  `#n` leads each try when the step had more than one attempt. Null when
+ *  no try was lost. */
+export function podTriesLine(tries) {
+    if (!tries?.some((t) => t.status === "lost"))
+        return null;
+    const many = new Set(tries.map((t) => t.n)).size > 1;
+    return tries
+        .map((t) => [
+        `${many ? `#${t.n} ` : ""}${t.image ?? "?"}`,
+        t.status,
+        typeof t.costUsd === "number" ? `$${t.costUsd.toFixed(4)}` : null,
+    ].filter(Boolean).join(" · "))
+        .join(" → ");
+}

package/dist/src/budget.d.ts

@@ -0,0 +1,32 @@
+export type BudgetPeriod = "run" | "day" | "week" | "month";
+export interface Budget {
+    usd: number;
+    period: BudgetPeriod;
+}
+/**
+ * The budget a frontmatter value declares, or null for "no cap".
+ *
+ * Lenient on purpose: a value nobody can read is treated as no cap rather
+ * than as a cap of zero, because refusing every run over a typo is the worse
+ * failure. `budgetProblem` is the strict reading, for lint and the editor.
+ */
+export declare function parseBudget(raw: unknown, defaultPeriod: BudgetPeriod): Budget | null;
+/**
+ * What is wrong with a `budget:` value, in a sentence, or null when it is
+ * fine. `allowed` names the periods this file may use — an agent's or a
+ * flow's budget is per run and nothing else; a workspace's or the account's
+ * is over time and never per run.
+ */
+export declare function budgetProblem(raw: unknown, allowed: BudgetPeriod[]): string | null;
+/** "$60/day", "$500/month", "$6/run". */
+export declare function formatBudget(b: Budget): string;
+/** "today", "this week", "this month" — the window a spend is measured in. */
+export declare function windowName(period: BudgetPeriod): string;
+/** What to wait for when the cap is reached. */
+export declare function windowTurnsHint(period: BudgetPeriod): string;
+/**
+ * When the current window began, as a UTC instant — the moment spend is
+ * summed from. Today's midnight, Monday's midnight, or the first of the
+ * month, all in the given calendar. A per-run budget has no window.
+ */
+export declare function windowStartMs(period: BudgetPeriod, timeZone: string, now?: Date): number | null;