@foldrun/core 0.3.0 → 0.4.0

package/dist/src/notify.d.ts

@@ -36,20 +36,58 @@ export interface NotifyConfig {
     url?: string;
     email?: string;
     events: string[];
+    /** `signing_secret:` — the NAME of a vault secret, never its value. With
+     *  one, every webhook carries an HMAC of the body it delivers, so the
+     *  receiver can tell a real notification from anyone who learned the URL.
+     *  Inbound hooks have verified a signature since they existed; a delivery
+     *  going the other way is the same problem in the same shape. */
+    signingSecret?: string;
 }
 export declare function notifyConfig(tenant: string, workspace: string): NotifyConfig | null;
+/**
+ * The headers that prove a delivery came from this install.
+ *
+ * `x-foldrun-signature` is a hex SHA-256 HMAC over "<timestamp>.<body>",
+ * keyed by the named vault secret — the timestamp is inside the signed
+ * string so a captured delivery cannot be replayed later with a fresh one.
+ * `x-signature` is the plain HMAC of the body beside it, the scheme the
+ * inbound `signature: hmac` verifies.
+ *
+ * No secret named, no headers: signing is opt-in, and a receiver that does
+ * not check one is no worse off than before.
+ */
+export declare function signatureHeaders(tenant: string, workspace: string, config: NotifyConfig, body: string): Record<string, string>;
+/** One waiting step's pair of links. */
+export interface StepLinks {
+    /** Index into run.steps. */
+    step: number;
+    agent: string;
+    approveUrl: string;
+    rejectUrl: string;
+}
 /**
  * The approve/reject links for a run waiting on a person, or null when the
  * install cannot say where it lives. A notification that only says "waiting
  * for you" sends the reader to find a laptop; one that carries the decision
  * lets them make it where they read it.
  *
+ * One pair per waiting step, each bound to that step and to a moment (the
+ * flow's `approve_within:`, else a week) — see approvals.ts. A link bound
+ * to the run alone approved every later gate of the run for as long as it
+ * ran. When the notification goes to a named approver — an address in the
+ * flow's `approvers:` — the links are bound to that person too, so a
+ * forwarded mail decides as nobody. `approveUrl`/`rejectUrl` on the result
+ * are the first waiting step's pair, for receivers written against that.
+ *
  * The reject link goes to the same page with the choice pre-selected — a
  * GET must not decide anything, because inbox link-checkers follow links.
  */
-export declare function approvalLinks(tenant: string, workspace: string, runId: string): {
+export declare function approvalLinks(tenant: string, workspace: string, run: RunRecord, 
+/** Who the notification is going to, when it is going to one address. */
+recipient?: string | null): {
     approveUrl: string;
     rejectUrl: string;
+    links: StepLinks[];
 } | null;
 /**
  * Fire the webhook for a run's state, if the workspace asked to hear about
@@ -58,4 +96,44 @@ export declare function approvalLinks(tenant: string, workspace: string, runId:
  */
 /** Flows whose completion is nobody's news: eval cases and adhoc runs. */
 export declare function isQuietFlow(flow: string): boolean;
+/**
+ * A notification that is not about one run finishing.
+ *
+ * Three things need to say something to the same destination a run
+ * notification goes to, and none of them has a RunRecord to hand: a flow
+ * that has been quarantined, a run that has outlived its `sla:`, and a
+ * budget that is nearly spent. They are the messages a person most needs
+ * and least expects, because each one is about something NOT happening —
+ * the failure mode that never sends mail is the one that costs a week.
+ *
+ * The event name is matched against `events:` exactly like a run status,
+ * so a workspace that wants none of this writes its own list and gets none
+ * of it. They are on by default: an alert nobody opted into is the point.
+ */
+export declare function sendPlainNotification(tenant: string, workspace: string, msg: {
+    event: string;
+    headline: string;
+    detail: string;
+    flow?: string;
+    runId?: string;
+}): Promise<boolean>;
+/**
+ * Prove the notification path works, now, while someone is looking.
+ *
+ * Every run notification is sent when nobody is watching, to a destination
+ * nobody has tested, through a mail domain nobody has verified. On
+ * 2026-09-06 every one of them had been going to a bin for weeks and the
+ * only symptom was silence — which is indistinguishable from nothing having
+ * gone wrong. An alert that has never been proven to arrive is not an alert.
+ *
+ * Unlike every other send here, this one reports its failure in full: the
+ * provider's own words, which are what actually name the problem ("domain
+ * not verified", "you can only send to your own address"). Swallowing them
+ * is right for a run notification and useless for a test.
+ */
+export declare function sendTestNotification(tenant: string, workspace: string): Promise<{
+    ok: boolean;
+    destination: string;
+    detail: string;
+}>;
 export declare function sendRunNotification(tenant: string, workspace: string, run: RunRecord): Promise<boolean>;

package/dist/src/notify.js

@@ -30,10 +30,13 @@
 // Defaults: failed and awaiting-approval. Completed is opt-in — a schedule
 // that works is the quiet kind of good news, and a channel that pings on
 // every success gets muted, which un-pings the failures too.
+import crypto from "node:crypto";
 import { readAgentsMd } from "./runner.js";
-import { accountDir, workspaceDir, runCost } from "./store.js";
+import { accountDir, workspaceDir, runCost, readFlow } from "./store.js";
 import { getSecret } from "./secrets.js";
-import { approveToken, publicUrl } from "./webhook.js";
+import { publicUrl } from "./webhook.js";
+import { approveLinkPath, approveLinkTtlMs } from "./approvals.js";
+import { noteSecretUse, healthKey } from "./secret-health.js";
 /**
  * The platform's own mail: an invite, a low balance.
  *
@@ -71,6 +74,14 @@ export function accountMail(tenant) {
 export function notifyMail(tenant) {
     return accountMail(tenant) ?? platformMail(tenant);
 }
+/** Was the mail sent on the account's own key? Only then is a refusal from
+ *  Resend a fact about a secret the account holds. Recording a platform-key
+ *  failure against a RESEND_API_KEY the account does not have would send
+ *  them to rotate a key that does not exist. */
+function noteMailUse(tenant, status) {
+    if (accountMail(tenant))
+        noteSecretUse(tenant, healthKey("RESEND_API_KEY", "account"), { host: "api.resend.com", status });
+}
 const DEFAULT_EVENTS = ["failed", "awaiting-approval"];
 export function notifyConfig(tenant, workspace) {
     const raw = readAgentsMd(workspaceDir(tenant, workspace))?.data.notify ??
@@ -93,6 +104,7 @@ export function notifyConfig(tenant, workspace) {
             url,
             email,
             events: Array.isArray(o.events) && o.events.length ? o.events.map(String) : DEFAULT_EVENTS,
+            signingSecret: typeof o.signing_secret === "string" ? o.signing_secret.trim().replace(/^\$\{|\}$/g, "") || undefined : undefined,
         };
     }
     return null;
@@ -100,16 +112,56 @@ export function notifyConfig(tenant, workspace) {
 // Said once per process, not once per run: the fix is one env edit, and a
 // line per parked run would bury the failures around it.
 let warnedNoPublicUrl = false;
+/**
+ * The headers that prove a delivery came from this install.
+ *
+ * `x-foldrun-signature` is a hex SHA-256 HMAC over "<timestamp>.<body>",
+ * keyed by the named vault secret — the timestamp is inside the signed
+ * string so a captured delivery cannot be replayed later with a fresh one.
+ * `x-signature` is the plain HMAC of the body beside it, the scheme the
+ * inbound `signature: hmac` verifies.
+ *
+ * No secret named, no headers: signing is opt-in, and a receiver that does
+ * not check one is no worse off than before.
+ */
+export function signatureHeaders(tenant, workspace, config, body) {
+    if (!config.signingSecret)
+        return {};
+    const secret = getSecret(tenant, config.signingSecret, workspace);
+    if (!secret) {
+        console.error(`[foldrun] notify: signing_secret names ${config.signingSecret}, which is not in the vault for ${tenant}/${workspace} — sending unsigned`);
+        return {};
+    }
+    const timestamp = Math.floor(Date.now() / 1000).toString();
+    const mac = crypto.createHmac("sha256", secret.value).update(`${timestamp}.${body}`).digest("hex");
+    // Two headers. `x-foldrun-signature` is the timestamped one, and what a
+    // receiver should check. `x-signature` is the plain HMAC of the body,
+    // which is what the inbound `signature: hmac` verifies — so a foldrun
+    // notification pointed at another foldrun webhook flow is accepted, and
+    // any receiver written against the plain scheme keeps working.
+    const plain = crypto.createHmac("sha256", secret.value).update(body).digest("hex");
+    return { "x-foldrun-timestamp": timestamp, "x-foldrun-signature": `sha256=${mac}`, "x-signature": plain };
+}
 /**
  * The approve/reject links for a run waiting on a person, or null when the
  * install cannot say where it lives. A notification that only says "waiting
  * for you" sends the reader to find a laptop; one that carries the decision
  * lets them make it where they read it.
  *
+ * One pair per waiting step, each bound to that step and to a moment (the
+ * flow's `approve_within:`, else a week) — see approvals.ts. A link bound
+ * to the run alone approved every later gate of the run for as long as it
+ * ran. When the notification goes to a named approver — an address in the
+ * flow's `approvers:` — the links are bound to that person too, so a
+ * forwarded mail decides as nobody. `approveUrl`/`rejectUrl` on the result
+ * are the first waiting step's pair, for receivers written against that.
+ *
  * The reject link goes to the same page with the choice pre-selected — a
  * GET must not decide anything, because inbox link-checkers follow links.
  */
-export function approvalLinks(tenant, workspace, runId) {
+export function approvalLinks(tenant, workspace, run, 
+/** Who the notification is going to, when it is going to one address. */
+recipient = null) {
     const base = publicUrl();
     if (!base) {
         if (!warnedNoPublicUrl) {
@@ -118,8 +170,20 @@ export function approvalLinks(tenant, workspace, runId) {
         }
         return null;
     }
-    const approveUrl = `${base}/api/approve/${tenant}/${workspace}/${runId}?token=${approveToken(tenant, workspace, runId)}`;
-    return { approveUrl, rejectUrl: `${approveUrl}&decision=reject` };
+    const flow = readFlow(tenant, workspace, run.flow);
+    const to = (recipient ?? "").trim().toLowerCase();
+    const approver = to && flow?.approvers?.includes(to) ? to : null;
+    const expiresAt = Date.now() + approveLinkTtlMs(flow);
+    const links = [];
+    run.steps.forEach((s, i) => {
+        if (s.status !== "awaiting-approval" || s.waitFor === "event")
+            return;
+        const approveUrl = `${base}${approveLinkPath(tenant, workspace, run.id, { step: i, expiresAt, approver })}`;
+        links.push({ step: i, agent: s.agent, approveUrl, rejectUrl: `${approveUrl}&decision=reject` });
+    });
+    if (links.length === 0)
+        return null;
+    return { approveUrl: links[0].approveUrl, rejectUrl: links[0].rejectUrl, links };
 }
 /**
  * Fire the webhook for a run's state, if the workspace asked to hear about
@@ -130,6 +194,162 @@ export function approvalLinks(tenant, workspace, runId) {
 export function isQuietFlow(flow) {
     return /^(eval|adhoc):/.test(flow);
 }
+/**
+ * A notification that is not about one run finishing.
+ *
+ * Three things need to say something to the same destination a run
+ * notification goes to, and none of them has a RunRecord to hand: a flow
+ * that has been quarantined, a run that has outlived its `sla:`, and a
+ * budget that is nearly spent. They are the messages a person most needs
+ * and least expects, because each one is about something NOT happening —
+ * the failure mode that never sends mail is the one that costs a week.
+ *
+ * The event name is matched against `events:` exactly like a run status,
+ * so a workspace that wants none of this writes its own list and gets none
+ * of it. They are on by default: an alert nobody opted into is the point.
+ */
+export async function sendPlainNotification(tenant, workspace, msg) {
+    const config = notifyConfig(tenant, workspace);
+    if (!config)
+        return false;
+    // These follow `failed`. Each one IS a failure — a flow that stopped
+    // running, a run that has stalled, a budget about to refuse work — that
+    // happens to produce no failed run for the normal path to report. A
+    // destination hearing about failures hears about these; naming one
+    // explicitly also turns it on; leaving `failed` out silences them.
+    if (!config.events.includes(msg.event) && !config.events.includes("failed"))
+        return false;
+    const body = {
+        text: `${msg.headline} — ${msg.detail} · ${workspace}`,
+        workspace,
+        status: msg.event,
+        summary: msg.detail,
+        ...(msg.flow ? { flow: msg.flow } : {}),
+        ...(msg.runId ? { runId: msg.runId } : {}),
+    };
+    try {
+        if (config.email) {
+            const mail = notifyMail(tenant);
+            if (!mail)
+                return false;
+            const res = await fetch("https://api.resend.com/emails", {
+                method: "POST",
+                headers: { authorization: `Bearer ${mail.key}`, "content-type": "application/json" },
+                body: JSON.stringify({
+                    from: mail.from,
+                    to: config.email,
+                    subject: `${msg.headline}`.slice(0, 160),
+                    text: `${msg.headline}\n\n${msg.detail}\n\nworkspace: ${workspace}\n${msg.flow ? `flow: ${msg.flow}\n` : ""}${msg.runId ? `run: ${msg.runId}\n` : ""}`,
+                }),
+                signal: AbortSignal.timeout(8000),
+            });
+            return res.ok;
+        }
+        const url = (config.url ?? "").replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (whole, name) => {
+            const hit = getSecret(tenant, name, workspace);
+            return hit ? hit.value : whole;
+        });
+        if (!url || url.includes("${"))
+            return false;
+        const payload = JSON.stringify(body);
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...signatureHeaders(tenant, workspace, config, payload) },
+            body: payload,
+            signal: AbortSignal.timeout(5000),
+        });
+        return res.ok;
+    }
+    catch (err) {
+        console.error(`[foldrun] notify (${msg.event}): ${tenant}/${workspace} →`, err instanceof Error ? err.message : err);
+        return false;
+    }
+}
+/**
+ * Prove the notification path works, now, while someone is looking.
+ *
+ * Every run notification is sent when nobody is watching, to a destination
+ * nobody has tested, through a mail domain nobody has verified. On
+ * 2026-09-06 every one of them had been going to a bin for weeks and the
+ * only symptom was silence — which is indistinguishable from nothing having
+ * gone wrong. An alert that has never been proven to arrive is not an alert.
+ *
+ * Unlike every other send here, this one reports its failure in full: the
+ * provider's own words, which are what actually name the problem ("domain
+ * not verified", "you can only send to your own address"). Swallowing them
+ * is right for a run notification and useless for a test.
+ */
+export async function sendTestNotification(tenant, workspace) {
+    const config = notifyConfig(tenant, workspace);
+    if (!config) {
+        return {
+            ok: false,
+            destination: "none",
+            detail: "no notify: in this workspace's AGENTS.md or the account's — nothing would be sent for a failure or a gate either",
+        };
+    }
+    const sent = new Date().toISOString();
+    const headline = "\u2713 foldrun test notification";
+    const detail = `Sent from ${workspace} at ${sent}. If you are reading this, failures and approval gates will reach you here too.`;
+    if (config.email) {
+        const mail = notifyMail(tenant);
+        if (!mail) {
+            return {
+                ok: false,
+                destination: config.email,
+                detail: "email is configured but there is no mail credential — set RESEND_API_KEY (and EMAIL_FROM) on the account, or FOLDRUN_RESEND_API_KEY on the platform",
+            };
+        }
+        try {
+            const res = await fetch("https://api.resend.com/emails", {
+                method: "POST",
+                headers: { authorization: `Bearer ${mail.key}`, "content-type": "application/json" },
+                body: JSON.stringify({ from: mail.from, to: config.email, subject: headline, text: `${headline}\n\n${detail}\n` }),
+                signal: AbortSignal.timeout(8000),
+            });
+            noteMailUse(tenant, res.status);
+            const body = (await res.text().catch(() => "")).replace(/\s+/g, " ").slice(0, 400);
+            return res.ok
+                ? { ok: true, destination: `${config.email} (from ${mail.from})`, detail: "accepted by Resend for delivery" }
+                : { ok: false, destination: config.email, detail: `HTTP ${res.status} from Resend — ${body}` };
+        }
+        catch (err) {
+            return { ok: false, destination: config.email, detail: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    const raw = config.url ?? "";
+    const url = raw.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (whole, name) => {
+        const hit = getSecret(tenant, name, workspace);
+        return hit ? hit.value : whole;
+    });
+    // The destination is echoed back with the secret still unresolved: a
+    // Slack webhook URL is itself a credential, and a page that prints it is
+    // a page that leaks it into a screenshot.
+    const shown = raw.includes("${") ? raw : `${url.slice(0, 40)}…`;
+    if (!url || url.includes("${")) {
+        return { ok: false, destination: shown, detail: `the secret named in notify.url is not in this account's vault` };
+    }
+    try {
+        const payload = JSON.stringify({ text: `${headline} — ${detail}`, workspace, status: "test", summary: detail });
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...signatureHeaders(tenant, workspace, config, payload) },
+            body: payload,
+            signal: AbortSignal.timeout(8000),
+        });
+        const body = (await res.text().catch(() => "")).replace(/\s+/g, " ").slice(0, 400);
+        return res.ok
+            ? {
+                ok: true,
+                destination: shown,
+                detail: config.signingSecret ? "accepted, signed with " + config.signingSecret : "accepted",
+            }
+            : { ok: false, destination: shown, detail: `HTTP ${res.status} — ${body}` };
+    }
+    catch (err) {
+        return { ok: false, destination: shown, detail: err instanceof Error ? err.message : String(err) };
+    }
+}
 export async function sendRunNotification(tenant, workspace, run) {
     const config = notifyConfig(tenant, workspace);
     if (!config || !config.events.includes(run.status))
@@ -141,6 +361,12 @@ export async function sendRunNotification(tenant, workspace, run) {
     // real reports with them. Failures and gates still send: a person asked.
     if (run.status === "completed" && isQuietFlow(run.flow))
         return false;
+    // A test run sent nothing outward and this must not be the exception: it
+    // reports only a failure, which is the one thing the person testing it
+    // needs told about without watching. Its gate mail would ask a real
+    // decision about a pretend send.
+    if (run.test && run.status !== "failed")
+        return false;
     const failed = run.steps.filter((s) => s.status === "failed").map((s) => s.agent);
     const waitingSteps = run.steps.filter((s) => s.status === "awaiting-approval");
     const waiting = waitingSteps.map((s) => s.agent);
@@ -160,7 +386,9 @@ export async function sendRunNotification(tenant, workspace, run) {
     // what it cost, and nothing at all about what it found. A scheduled desk
     // reporting only its own existence is a desk nobody reads by week three.
     const summary = run.summary?.trim() || null;
-    const links = run.status === "awaiting-approval" ? approvalLinks(tenant, workspace, run.id) : null;
+    // An emailed link is minted for its reader: a named approver's mail
+    // carries links that decide as them. A webhook has no reader.
+    const links = run.status === "awaiting-approval" ? approvalLinks(tenant, workspace, run, config.email ?? null) : null;
     // At a gate the reader is being asked something; the question goes in the
     // mail, and so does what the run has concluded so far — the last finished
     // step's first line, which is the proposal's own summary ("… ·
@@ -209,10 +437,15 @@ export async function sendRunNotification(tenant, workspace, run) {
                         (asks.length ? `\n${asks.map((a) => `Question: ${a}`).join("\n")}\n` : "") +
                         `\nworkspace: ${workspace}\nrun: ${run.id}\nflow: ${run.flow}\n` +
                         `cost: $${runCost(run).toFixed(4)}\nstarted: ${run.startedAt}\nfinished: ${run.finishedAt ?? "-"}\n` +
-                        (links ? `\nApprove: ${links.approveUrl}\nReject: ${links.rejectUrl}\n` : ""),
+                        (links
+                            ? links.links.length === 1
+                                ? `\nApprove: ${links.approveUrl}\nReject: ${links.rejectUrl}\n`
+                                : links.links.map((l) => `\nStep ${l.step + 1} (${l.agent})\nApprove: ${l.approveUrl}\nReject: ${l.rejectUrl}\n`).join("")
+                            : ""),
                 }),
                 signal: AbortSignal.timeout(8000),
             });
+            noteMailUse(tenant, res.status);
             if (!res.ok) {
                 // Resend's body says WHY — "domain not verified", "can only send to
                 // your own address" — and a status alone sent someone to the wrong
@@ -233,10 +466,11 @@ export async function sendRunNotification(tenant, workspace, run) {
             console.error(`[foldrun] notify: secret in URL not set for ${tenant}/${workspace}`);
             return false;
         }
+        const payload = JSON.stringify(body);
         const res = await fetch(url, {
             method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify(body),
+            headers: { "content-type": "application/json", ...signatureHeaders(tenant, workspace, config, payload) },
+            body: payload,
             signal: AbortSignal.timeout(5000),
         });
         if (!res.ok) {

package/dist/src/paths.d.ts

@@ -31,3 +31,8 @@ export declare function dataRoot(): string;
  * no account and no tenant there, so the wrapper directories collapse away.
  */
 export declare function singleWorkspace(): string | null;
+/** Without leading and/or trailing slashes. */
+export declare function trimSlashes(s: string, where?: "start" | "end" | "both"): string;
+/** Without any of `chars` at the ends — the linear form of
+ *  `.replace(/^[chars]+/, "").replace(/[chars]+$/, "")`. */
+export declare function trimChars(s: string, chars: string): string;

package/dist/src/paths.js

@@ -76,3 +76,35 @@ export function dataRoot() {
 export function singleWorkspace() {
     return process.env.FOLDRUN_WORKSPACE ?? null;
 }
+// ------------------------------------------------------- linear trimming
+//
+// `s.replace(/\/+$/, "")` is the obvious way to drop trailing slashes and
+// it is quadratic: the engine tries `\/+` from every position and fails at
+// `$` each time, so a string of ten thousand slashes is fifty million
+// steps. Several of these strings come from a customer's own files — a
+// base_url, a tool's base, a storage prefix — which is exactly the input
+// that must not be able to stall a worker. A loop is linear and reads the
+// same.
+/** Without leading and/or trailing slashes. */
+export function trimSlashes(s, where = "end") {
+    let a = 0;
+    let b = s.length;
+    if (where !== "end")
+        while (a < b && s[a] === "/")
+            a++;
+    if (where !== "start")
+        while (b > a && s[b - 1] === "/")
+            b--;
+    return s.slice(a, b);
+}
+/** Without any of `chars` at the ends — the linear form of
+ *  `.replace(/^[chars]+/, "").replace(/[chars]+$/, "")`. */
+export function trimChars(s, chars) {
+    let a = 0;
+    let b = s.length;
+    while (a < b && chars.includes(s[a]))
+        a++;
+    while (b > a && chars.includes(s[b - 1]))
+        b--;
+    return s.slice(a, b);
+}

package/dist/src/platform.d.ts

@@ -1,13 +1,86 @@
-import type { FlowStep, RunRecord } from "./store.ts";
+import type { FlowInfo, FlowStep, RunRecord } from "./store.ts";
 import type { RunInContainerArgs, ContainerStepOutcome } from "./run-container.ts";
 import type { EgressHooks } from "./egress.ts";
 export type IsolatedStepRunner = (args: RunInContainerArgs) => Promise<ContainerStepOutcome>;
+/** Who this install is for. `hosted` means someone is paying the operator
+ *  for it — a wallet, a plan, a bill. `self-hosted` is everything else: a
+ *  laptop, a company's own box, the open-source download. */
+export type Edition = "self-hosted" | "hosted";
+/** What a trigger gate decided. `admit: false` is never an error: the
+ *  trigger was received and understood, and the flow's own file says this
+ *  one does not become a run. `detail` is what the sender and the log are
+ *  told, because a silent drop reads exactly like a broken hook. */
+export type TriggerAdmission = {
+    admit: true;
+} | {
+    admit: false;
+    reason: "duplicate" | "throttled" | "quarantined" | "debounced";
+    detail: string;
+    firesAt?: number;
+};
 export interface PlatformHooks {
+    /** Is this a hosted install? The ONE question every commercial surface —
+     *  the wallet, top-ups, plan limits, whatever is added next that assumes
+     *  a customer — asks before it renders or answers. Default: self-hosted,
+     *  which is what a process that never registered a platform is, and what
+     *  the open-source image is unless its operator configures billing. One
+     *  predicate, one place, so "does the community build show X" is a test
+     *  and not an audit. */
+    edition(): Edition;
     /** Put a flow run where a worker will pick it up. Default: start it here, now. */
-    enqueueFlowRun(tenant: string, workspace: string, steps: FlowStep[], flowName: string, modelOverride?: string | null, tags?: string[]): Promise<RunRecord>;
+    enqueueFlowRun(tenant: string, workspace: string, steps: FlowStep[], flowName: string, modelOverride?: string | null, tags?: string[], 
+    /** The person who asked, when one did — their email. A schedule, a
+     *  webhook and a chained flow leave it unset, which is what makes
+     *  "nobody approves their own run" a rule the record can enforce. */
+    startedBy?: string | null, 
+    /** `test: true` marks the run a test run (see test-mode.ts). Unset
+     *  lets the platform decide — a preview workspace's runs are tests
+     *  unless the flow says `live: true`. */
+    opts?: {
+        test?: boolean;
+    }): Promise<RunRecord>;
     /** A parked run was approved and has no driver; line it up. Default: nothing —
      *  locally the starter that parked it is still polling the record. */
     enqueueResume(tenant: string, workspace: string, runId: string): Promise<void>;
+    /**
+     * What a run has spent so far, in the money the customer is actually
+     * billed — tokens AND the sandbox seconds behind them.
+     *
+     * `budget:` says "the most one run may spend", and for a long time it
+     * only ever compared token cost. A step that called no model — a script
+     * looping on a page that never loads, a browser waiting on a selector
+     * that never appears — spent nothing by that reading and was capped by
+     * nothing, while the sandbox billed by the second. The platform has no
+     * clock of its own by design, so the cap is the only backstop there is,
+     * and it has to count the whole bill for that to be true.
+     *
+     * Default: token cost, which is the entire bill on an install that
+     * prices no compute.
+     */
+    runSpend(run: RunRecord): number;
+    /**
+     * Should a trigger become a run? The flow file's `idempotency:`,
+     * `throttle:`, `debounce:` and `disable_after:` are all answered here,
+     * because all four need state that outlives one delivery — what has been
+     * seen, when the last run started, what is still being waited out.
+     *
+     * Default: yes, always. A laptop has no fleet to protect and no duplicate
+     * deliveries to remember; the local runner is the one asking, and it asked
+     * because a person did.
+     */
+    admitTrigger(tenant: string, workspace: string, flow: FlowInfo, opts?: {
+        deliveryKey?: string | null;
+        body?: string;
+        tag?: string;
+    }): Promise<TriggerAdmission>;
+    /** An admitted trigger whose start then threw. Undoes what admitTrigger
+     *  recorded — the delivery as seen, the throttle window — so the sender's
+     *  retry is a fresh event rather than a "duplicate" of a run that never
+     *  existed. Default: nothing, because the default gate records nothing. */
+    rollbackTrigger(tenant: string, workspace: string, flow: FlowInfo, opts?: {
+        deliveryKey?: string | null;
+        reason?: string;
+    }): Promise<void>;
     /** Step executors by FOLDRUN_RUN_ISOLATION value, beyond the `container`
      *  one core ships. The platform adds `k8s`. */
     isolation: Record<string, IsolatedStepRunner>;
@@ -34,9 +107,36 @@ export interface PlatformHooks {
      *  on its record is resumed rather than destroyed and run again. Default:
      *  nothing is. */
     sandboxResumable(kind: string): boolean;
+    /**
+     * Where the platform's built-in tools sit on disk, materialised at boot —
+     * a shelf every account reads, beneath its own library. A name found in
+     * the workspace wins, then the account's copy, then this. Default: none,
+     * which is what a laptop has; there the gallery is a dashboard feature and
+     * not a directory, and an agent grants only what it or its account owns.
+     */
+    galleryDir(): string | null;
+    /**
+     * An oauth2 secret was just refreshed — `error` null when it worked, the
+     * provider's reason when it did not. The platform keeps each connection's
+     * health, emails once when a grant is dead, and answers with the one-click
+     * reconnect address, which the failing step's error then quotes. Default:
+     * nothing to say, which is a laptop.
+     */
+    noteOAuthRefresh(ctx: {
+        tenant: string;
+        workspace?: string;
+    }, name: string, error: string | null): Promise<string | undefined>;
 }
 export declare const platform: PlatformHooks;
 /** Install the platform's implementations. Partial: what is not given keeps its local default. */
 export declare function registerPlatform(hooks: Partial<PlatformHooks>): void;
+/**
+ * Does a platform own the queue? True once something registered its own
+ * enqueueFlowRun — whatever process asks. An eval used to decide this from
+ * FOLDRUN_ROLE === "web", so on a worker it started the run in-process and
+ * walked around the queue the platform was counting on (the account cap,
+ * the lanes, the per-pod lease). The seam is the fact; the role is a guess.
+ */
+export declare function platformQueues(): boolean;
 /** Back to the local defaults — for tests that register and must not leak. */
 export declare function resetPlatform(): void;

package/dist/src/platform.js

@@ -12,12 +12,16 @@
 // and calls registerPlatform() once at boot. A process that forgets to is a
 // local install — which is exactly the failure that is safe.
 const local = {
-    async enqueueFlowRun(tenant, workspace, steps, flowName, modelOverride, tags = []) {
+    edition: () => "self-hosted",
+    async enqueueFlowRun(tenant, workspace, steps, flowName, modelOverride, tags = [], startedBy = null, opts = {}) {
         // Imported here, not at the top: runner.ts imports this file.
         const { startFlowRun } = await import("./runner.js");
-        return startFlowRun(tenant, workspace, steps, flowName, modelOverride ?? null, tags);
+        return startFlowRun(tenant, workspace, steps, flowName, modelOverride ?? null, tags, null, startedBy, opts);
     },
     async enqueueResume() { },
+    admitTrigger: async () => ({ admit: true }),
+    async rollbackTrigger() { },
+    runSpend: (run) => run.steps.reduce((sum, s) => sum + (s.costUsd ?? 0), 0),
     isolation: {},
     killRunSandboxes() { },
     syncPublicShares: () => ({ added: [] }),
@@ -26,6 +30,8 @@ const local = {
     egress: { lease: async () => null },
     workspaceChanged() { },
     sandboxResumable: () => false,
+    galleryDir: () => null,
+    noteOAuthRefresh: async () => undefined,
 };
 // One object per PROCESS, not per module instance. A bundler that compiles
 // the boot file and each route handler separately (Next does) gives every
@@ -44,6 +50,16 @@ export function registerPlatform(hooks) {
         isolation: { ...platform.isolation, ...(hooks.isolation ?? {}) },
     });
 }
+/**
+ * Does a platform own the queue? True once something registered its own
+ * enqueueFlowRun — whatever process asks. An eval used to decide this from
+ * FOLDRUN_ROLE === "web", so on a worker it started the run in-process and
+ * walked around the queue the platform was counting on (the account cap,
+ * the lanes, the per-pod lease). The seam is the fact; the role is a guess.
+ */
+export function platformQueues() {
+    return platform.enqueueFlowRun !== local.enqueueFlowRun;
+}
 /** Back to the local defaults — for tests that register and must not leak. */
 export function resetPlatform() {
     Object.assign(platform, local, { isolation: {} });