@foldrun/core 0.3.0 → 0.5.0

package/src/operator.ts

@@ -0,0 +1,300 @@
+// A person in the loop while a step runs: the agent asks, a person answers,
+// or a person says something the agent should hear.
+//
+// Until this, the only way a person reached a step was before it started —
+// `ask:`, an approval gate, `wait: event` — and the answer arrived as
+// prompt text. An agent that found, halfway through, that it needed a
+// decision had to fail or guess.
+//
+// Two things, one line out of the sandbox. A run pod has no ingress; the
+// only live door is the worker's egress proxy, reached at the per-step
+// lease address the pod already holds (FOLDRUN_EGRESS = http://<w>/e/<lease>).
+// The lease names the account and the run, so a step can only ever ask in,
+// or read the inbox of, its own run.
+//
+//   tools: [ask]   the agent gets `ask_person` — POST the question, then
+//                  long-poll for the answer; the step's sandbox is held
+//                  (and charged) while it waits, up to `ask: {timeout}`
+//   every step     after each tool call, its run's inbox is read and any
+//                  message is handed to the model as context
+//
+// Both leave a trace event with an `operator` field, which the runner turns
+// into step.questions / step.messages on the record.
+
+import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+import type { EventExtra } from "./step-exec.ts";
+import type { StepMessage, StepQuestion } from "./store.ts";
+
+/** What a trace event carries when a person was involved. */
+export type OperatorEvent =
+  | { kind: "asked"; id: string; question: string; options?: string[] }
+  | { kind: "answered"; id: string; answer: string; by?: string | null }
+  | { kind: "unanswered"; id: string }
+  | { kind: "message"; text: string; by?: string | null; at: string };
+
+export interface OperatorMessage {
+  text: string;
+  by?: string | null;
+  at: string;
+}
+
+/** The pod's side of the line. `null` when there is no proxy (the CLI, a
+ *  compose install without one): then nobody can answer or write in. */
+export interface OperatorChannel {
+  ask(question: string, options?: string[]): Promise<{ id: string }>;
+  /** Waits up to `maxMs` for this question's answer; null when none came. */
+  poll(id: string, maxMs: number): Promise<{ answer: string; by?: string | null } | null>;
+  inbox(): Promise<OperatorMessage[]>;
+  /** Nobody will read this question's answer now (the wait timed out):
+   *  stop offering it to people. Best effort; optional for fakes. */
+  close?(id: string): Promise<void>;
+}
+
+export const QUESTION_MAX = 2_000;
+export const OPTION_MAX = 200;
+export const OPTIONS_MAX = 10;
+export const ANSWER_MAX = 4_000;
+export const MESSAGE_MAX = 4_000;
+/** One long-poll round trip — under any proxy's idle cut-off. */
+export const POLL_MS = 25_000;
+export const ASK_DEFAULT_SEC = 30 * 60;
+export const ASK_MAX_SEC = 24 * 60 * 60;
+
+/** `http://w:8090/e/<lease>` → the proxy's origin and the lease token. */
+export function operatorEndpoint(egress: string | undefined | null): { base: string; token: string } | null {
+  if (!egress) return null;
+  const m = egress.match(/^(https?:\/\/[^/]+)\/e\/([A-Za-z0-9_-]{16,})\/?$/);
+  return m ? { base: m[1], token: m[2] } : null;
+}
+
+/** The channel over the egress proxy. `fetchImpl` is for tests. */
+export function httpChannel(egress: string | undefined | null, fetchImpl: typeof fetch = fetch): OperatorChannel | null {
+  const ep = operatorEndpoint(egress);
+  if (!ep) return null;
+  const json = async (res: Response) => {
+    const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+    if (!res.ok) throw new Error(String((body.error as { message?: string } | undefined)?.message ?? `proxy answered ${res.status}`));
+    return body;
+  };
+  return {
+    async ask(question, options) {
+      const body = await json(
+        await fetchImpl(`${ep.base}/ask/${ep.token}`, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ question, options }),
+          signal: AbortSignal.timeout(15_000),
+        }),
+      );
+      return { id: String(body.id) };
+    },
+    async poll(id, maxMs) {
+      const wait = Math.max(0, Math.min(maxMs, POLL_MS));
+      const body = await json(
+        await fetchImpl(`${ep.base}/ask/${ep.token}/${encodeURIComponent(id)}?wait=${wait}`, {
+          signal: AbortSignal.timeout(wait + 15_000),
+        }),
+      );
+      return typeof body.answer === "string" ? { answer: body.answer, by: (body.by as string | null) ?? null } : null;
+    },
+    async inbox() {
+      const body = await json(await fetchImpl(`${ep.base}/inbox/${ep.token}`, { signal: AbortSignal.timeout(3_000) }));
+      return Array.isArray(body.messages) ? (body.messages as OperatorMessage[]) : [];
+    },
+    async close(id) {
+      await json(
+        await fetchImpl(`${ep.base}/ask/${ep.token}/${encodeURIComponent(id)}`, {
+          method: "DELETE",
+          signal: AbortSignal.timeout(5_000),
+        }),
+      );
+    },
+  };
+}
+
+/** `ask: {timeout: 2h}` in an agent's frontmatter → seconds, clamped. */
+export function askTimeoutSec(front: Record<string, unknown>): number {
+  const raw = (front.ask as { timeout?: unknown } | undefined)?.timeout;
+  const sec = parseDuration(raw);
+  return sec === null ? ASK_DEFAULT_SEC : Math.min(Math.max(sec, 30), ASK_MAX_SEC);
+}
+
+/** "90s", "30m", "2h", "1d" or a number of seconds; null when unreadable. */
+export function parseDuration(raw: unknown): number | null {
+  if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) return raw;
+  if (typeof raw !== "string") return null;
+  const m = raw.trim().match(/^(\d+(?:\.\d+)?)\s*(s|m|h|d)?$/i);
+  if (!m) return null;
+  const mult = { s: 1, m: 60, h: 3600, d: 86400 }[(m[2] ?? "s").toLowerCase() as "s" | "m" | "h" | "d"];
+  return Math.round(Number(m[1]) * mult);
+}
+
+export const NO_ANSWER =
+  "No one answered in time. Decide for yourself if the choice is safe and say what you chose and why; if it is not, stop and reply BLOCKED with the question.";
+
+type Emit = (type: "text" | "tool" | "info" | "error", text: string, extra?: EventExtra) => void;
+
+/** The in-sandbox `ask_person` tool. With no channel (no proxy), `local`
+ *  answers instead — the CLI prompts on a terminal — or nobody does. */
+export function buildAskTool(opts: {
+  channel: OperatorChannel | null;
+  timeoutSec: number;
+  emit: Emit;
+  local?: (question: string, options?: string[]) => Promise<string | null>;
+  now?: () => number;
+}) {
+  const now = opts.now ?? Date.now;
+  const ask = tool(
+    "ask_person",
+    "Ask the person running this desk a question and wait for their answer. Use it for a decision you cannot make safely yourself — not for information you can look up. Give a short list of options when the answer is one of a few choices. Returns the answer, or says nobody answered in time.",
+    {
+      question: z.string().describe("The complete, self-contained question — the person has not read your work"),
+      options: z.array(z.string()).optional().describe("Up to 10 short choices, when the answer is one of them"),
+    },
+    async ({ question, options }) => {
+      const q = String(question).trim().slice(0, QUESTION_MAX);
+      const opts2 = (options ?? []).map((o) => String(o).trim().slice(0, OPTION_MAX)).filter(Boolean).slice(0, OPTIONS_MAX);
+      const text = (t: string) => ({ content: [{ type: "text" as const, text: t }] });
+      if (!q) return { ...text("ask_person needs a question."), isError: true };
+      if (!opts.channel) {
+        const local = opts.local ? await opts.local(q, opts2.length ? opts2 : undefined) : null;
+        const id = "local";
+        opts.emit("info", `asked a person: ${q}`, { operator: { kind: "asked", id, question: q, ...(opts2.length ? { options: opts2 } : {}) } });
+        if (local === null || local.trim() === "") {
+          opts.emit("info", "no answer — nobody can answer here", { operator: { kind: "unanswered", id } });
+          return text(NO_ANSWER);
+        }
+        opts.emit("info", `answered: ${local}`, { operator: { kind: "answered", id, answer: local, by: "terminal" } });
+        return text(`The person answered: ${local}`);
+      }
+      let id: string;
+      try {
+        ({ id } = await opts.channel.ask(q, opts2.length ? opts2 : undefined));
+      } catch (err) {
+        return { ...text(`Could not ask: ${err instanceof Error ? err.message : String(err)}. ${NO_ANSWER}`), isError: true };
+      }
+      opts.emit("info", `asked a person: ${q}`, { operator: { kind: "asked", id, question: q, ...(opts2.length ? { options: opts2 } : {}) } });
+      const deadline = now() + opts.timeoutSec * 1000;
+      while (now() < deadline) {
+        let got: { answer: string; by?: string | null } | null = null;
+        try {
+          got = await opts.channel.poll(id, deadline - now());
+        } catch {
+          // A dropped long-poll is retried; the deadline is what ends it.
+          await new Promise((r) => setTimeout(r, 2_000));
+          continue;
+        }
+        if (got) {
+          const answer = got.answer.slice(0, ANSWER_MAX);
+          opts.emit("info", `answered${got.by ? ` by ${got.by}` : ""}: ${answer}`, { operator: { kind: "answered", id, answer, by: got.by ?? null } });
+          return text(`The person answered: ${answer}`);
+        }
+      }
+      // Close it on the proxy, so the dashboard stops offering a box whose
+      // answer nobody would read. Best effort: a failure changes nothing here.
+      try {
+        await opts.channel.close?.(id);
+      } catch {
+        /* the proxy's TTL clears it eventually */
+      }
+      opts.emit("info", `no answer after ${Math.round(opts.timeoutSec / 60)} min`, { operator: { kind: "unanswered", id } });
+      return text(NO_ANSWER);
+    },
+  );
+  return {
+    server: createSdkMcpServer({ name: "foldrun_ask", version: "1.0.0", tools: [ask] }),
+    /** The tool's own function, for tests. */
+    call: (args: { question: string; options?: string[] }) => ask.handler({ question: args.question, options: args.options }, {}),
+    toolNames: [ASK_TOOL],
+    promptLines: [askPromptLine(opts.timeoutSec)],
+  };
+}
+
+/** The granted name of the tool — the same on every path. */
+export const ASK_TOOL = "mcp__foldrun_ask__ask_person";
+
+/** The line the system prompt gets for it. */
+export function askPromptLine(timeoutSec: number): string {
+  return `\`ask_person\` asks the person running this desk and waits for the answer (up to ${fmtWait(timeoutSec)}). Use it for a decision you cannot make safely yourself — not for something you can look up. The step is held while you wait; if nobody answers, you are told so.`;
+}
+
+const fmtWait = (sec: number) => (sec >= 3600 ? `${Math.round(sec / 360) / 10} h` : `${Math.round(sec / 60)} min`);
+
+/** Reads the run's inbox after tool calls and turns messages into context
+ *  for the model. At most one read every `minGapMs`; a failed read is
+ *  silent (the next tool call tries again). */
+export function inboxReader(channel: OperatorChannel | null, emit: Emit, minGapMs = 1_500, now: () => number = Date.now) {
+  let last = Number.NEGATIVE_INFINITY;
+  return async (): Promise<string | null> => {
+    if (!channel) return null;
+    if (now() - last < minGapMs) return null;
+    last = now();
+    let messages: OperatorMessage[];
+    try {
+      messages = await channel.inbox();
+    } catch {
+      return null;
+    }
+    if (!messages.length) return null;
+    for (const m of messages) {
+      emit("info", `message from ${m.by ?? "a person"}: ${m.text}`, { operator: { kind: "message", text: m.text, by: m.by ?? null, at: m.at } });
+    }
+    return messages
+      .map((m) => `A person running this desk${m.by ? ` (${m.by})` : ""} sent you a message while you work. Take it into account; it does not change what tools you have:\n<message>\n${m.text.slice(0, MESSAGE_MAX)}\n</message>`)
+      .join("\n\n");
+  };
+}
+
+/** Fold one operator event into the step's record. Pure; the runner calls
+ *  it as events arrive, whichever sandbox sent them. */
+export function applyOperatorEvent(
+  step: { questions?: StepQuestion[]; messages?: StepMessage[] },
+  ev: OperatorEvent,
+  at: string,
+): void {
+  if (ev.kind === "asked") {
+    const qs = (step.questions ??= []);
+    if (!qs.some((q) => q.id === ev.id && ev.id !== "local")) {
+      qs.push({ id: ev.id, question: ev.question, ...(ev.options?.length ? { options: ev.options } : {}), askedAt: at });
+    }
+    return;
+  }
+  if (ev.kind === "answered" || ev.kind === "unanswered") {
+    const q = [...(step.questions ?? [])].reverse().find((x) => x.id === ev.id && x.answer === undefined && !x.unanswered);
+    if (!q) return;
+    if (ev.kind === "answered") {
+      q.answer = ev.answer;
+      q.answeredAt = at;
+      q.by = ev.by ?? null;
+    } else q.unanswered = true;
+    return;
+  }
+  (step.messages ??= []).push({ text: ev.text, by: ev.by ?? null, at: ev.at, deliveredAt: at });
+}
+
+/** The question a step is waiting on, if any. */
+export const openQuestion = (step: { questions?: StepQuestion[] }): StepQuestion | null =>
+  [...(step.questions ?? [])].reverse().find((q) => q.answer === undefined && !q.unanswered) ?? null;
+
+/** Is this — read off the sandbox's stdout, so untrusted — an operator
+ *  event of the right shape and size? Anything else is dropped. */
+export function isOperatorEvent(v: unknown): v is OperatorEvent {
+  if (!v || typeof v !== "object") return false;
+  const o = v as Record<string, unknown>;
+  const str = (x: unknown, max: number) => typeof x === "string" && x.length <= max;
+  const id = str(o.id, 64);
+  switch (o.kind) {
+    case "asked":
+      return id && str(o.question, QUESTION_MAX) &&
+        (o.options === undefined || (Array.isArray(o.options) && o.options.length <= OPTIONS_MAX && o.options.every((x) => str(x, OPTION_MAX))));
+    case "answered":
+      return id && str(o.answer, ANSWER_MAX) && (o.by === undefined || o.by === null || str(o.by, 200));
+    case "unanswered":
+      return id;
+    case "message":
+      return str(o.text, MESSAGE_MAX) && str(o.at, 40) && (o.by === undefined || o.by === null || str(o.by, 200));
+    default:
+      return false;
+  }
+}

package/src/paths.ts

@@ -22,6 +22,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { accountRootFor } from "./layout.ts";
 
 /**
  * The nearest enclosing project root, found by walking up from `from` looking
@@ -77,3 +78,85 @@ export function dataRoot(): string {
 export function singleWorkspace(): string | null {
   return process.env.FOLDRUN_WORKSPACE ?? null;
 }
+
+/**
+ * The account scope in single-workspace mode: where `AGENTS.md` and
+ * `library/` live for the workspace this process is pinned to. Null in the
+ * multi-tenant layout, where the account is a tenant directory under the data
+ * root and nothing has to be inferred.
+ *
+ * It used to be, everywhere, `path.resolve(single, "..")`. That is right for a
+ * flat workspace and wrong for one inside an account folder, where the parent
+ * is `workspaces/` — a directory with no AGENTS.md and no library in it. Every
+ * `skills:`, `tools:` and `scripts:` that named something shared then resolved
+ * against an empty directory and came back missing. `accountRootFor` knows the
+ * difference; `FOLDRUN_ACCOUNT` overrides both, for an embedder that has
+ * already decided.
+ */
+export function singleAccountRoot(): string | null {
+  const single = singleWorkspace();
+  if (!single) return null;
+  if (process.env.FOLDRUN_ACCOUNT) return path.resolve(process.env.FOLDRUN_ACCOUNT);
+  return accountRootFor(path.resolve(single));
+}
+
+// ------------------------------------------------------- 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: string, where: "start" | "end" | "both" = "end"): string {
+  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: string, chars: string): string {
+  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);
+}
+
+/** The largest file a person (or the gallery) writes into a workspace or the
+ *  library through the store: 512 KB. A folder tool's program is one file,
+ *  and the gallery browser's passed 256 KB on 2026-09-29. */
+export const MAX_EDITABLE_FILE = 512 * 1024;
+
+/**
+ * Every entry under `dir`, relative, like `fs.readdirSync(dir, { recursive:
+ * true })` — except that a link to a directory is listed and NOT entered.
+ * Node's recursive readdir follows directory links, so a link back up the
+ * tree (the `workspace` link a step holds in its agent folder, confine.ts)
+ * is walked about forty levels deep before the kernel stops it, each level
+ * a full copy of the workspace.
+ */
+export function entriesNoFollow(dir: string): string[] {
+  const out: string[] = [];
+  const walk = (abs: string, rel: string) => {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(abs, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const r = rel ? path.join(rel, e.name) : e.name;
+      out.push(r);
+      if (e.isDirectory()) walk(path.join(abs, e.name), r);
+    }
+  };
+  walk(dir, "");
+  return out;
+}

package/src/platform.ts

@@ -12,13 +12,34 @@
 // and calls registerPlatform() once at boot. A process that forgets to is a
 // local install — which is exactly the failure that is safe.
 
-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" | "paused" | "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,
@@ -27,17 +48,67 @@ export interface PlatformHooks {
     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>;
   /** Destroy whatever sandboxes a stopped run still has. Default: nothing to destroy. */
   killRunSandboxes(runId: string): void;
   /** Publish storage/public/ as share links after a run. Default: no links. */
-  syncPublicShares(tenant: string, workspace: string): { added: string[] };
+  syncPublicShares(tenant: string, workspace: string): Promise<{ added: string[] }>;
   /** The workspace a preview was branched from, for inherited secrets. Default: none. */
   previewSourceOf(tenant: string, workspace: string): string | null;
   /** This account's own data key, or null to use the install key. */
@@ -55,23 +126,94 @@ 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>;
+  /**
+   * fetch() for a URL a tenant chose — a webhook, an OAuth token endpoint,
+   * a provider base URL, an OpenAPI source. On a platform these run on the
+   * worker or web tier, which can reach what a sandbox cannot, so the
+   * platform refuses private and cluster addresses. Default: plain fetch,
+   * which is a laptop calling its own LAN on purpose. Core calls this only
+   * through untrusted-fetch.ts, once per hop with `redirect: "manual"`, so
+   * every redirect target is checked here like the first URL was.
+   */
+  fetchUntrusted(url: string, init?: RequestInit): Promise<Response>;
+  /**
+   * Hand a notify: webhook to whatever delivers it. The platform records
+   * the delivery, makes the first attempt now and retries on a backoff from
+   * the worker (`retry: true`); `retry: false` is one attempt, recorded —
+   * the test button. Default: one attempt now, recorded nowhere, which is a
+   * laptop: there is no worker to retry from and nobody to read the log.
+   */
+  deliverWebhook(
+    tenant: string,
+    workspace: string,
+    delivery: { event: string; body: string; retry: boolean },
+  ): Promise<WebhookDeliveryOutcome>;
+  /**
+   * Does this person take this optional category of mail — for this
+   * workspace, when the category is per workspace? Asked by mail.ts at send
+   * time, never for required mail. Default: yes; a laptop keeps no
+   * preferences and sends what it always sent.
+   */
+  mailPreference(tenant: string, email: string, category: string, workspace: string | null): Promise<boolean>;
+}
+
+/** What handing a webhook over came to: the delivery's id (the
+ *  X-Foldrun-Delivery header) and its first attempt, when one was made. */
+export interface WebhookDeliveryOutcome {
+  ok: boolean;
+  deliveryId: string;
+  statusCode: number | null;
+  /** The receiver's words or the error, trimmed — what the test reports. */
+  detail: string;
+  /** True when a failed first attempt has later ones scheduled. */
+  retrying?: boolean;
 }
 
 const local: PlatformHooks = {
-  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.ts");
-    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: [] }),
+  syncPublicShares: async () => ({ added: [] }),
   previewSourceOf: () => null,
   tenantKey: () => null,
   egress: { lease: async () => null },
   workspaceChanged() {},
   sandboxResumable: () => false,
+  galleryDir: () => null,
+  noteOAuthRefresh: async () => undefined,
+  fetchUntrusted: (url, init) => fetch(url, init),
+  async deliverWebhook(tenant, workspace, delivery) {
+    const { attemptWebhook, newDeliveryId } = await import("./notify.ts");
+    const deliveryId = newDeliveryId();
+    const a = await attemptWebhook(tenant, workspace, { id: deliveryId, event: delivery.event, body: delivery.body, attempt: 1 });
+    return { ok: a.ok, deliveryId, statusCode: a.statusCode, detail: a.error ?? a.response ?? "" };
+  },
+  mailPreference: async () => true,
 };
 
 // One object per PROCESS, not per module instance. A bundler that compiles
@@ -93,6 +235,17 @@ export 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 function platformQueues(): boolean {
+  return platform.enqueueFlowRun !== local.enqueueFlowRun;
+}
+
 /** Back to the local defaults — for tests that register and must not leak. */
 export function resetPlatform(): void {
   Object.assign(platform, local, { isolation: {} });