@foldrun/core 0.4.0 → 0.6.0

package/dist/src/operator.d.ts

@@ -0,0 +1,201 @@
+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 declare const QUESTION_MAX = 2000;
+export declare const OPTION_MAX = 200;
+export declare const OPTIONS_MAX = 10;
+export declare const ANSWER_MAX = 4000;
+export declare const MESSAGE_MAX = 4000;
+/** One long-poll round trip — under any proxy's idle cut-off. */
+export declare const POLL_MS = 25000;
+export declare const ASK_DEFAULT_SEC: number;
+export declare const ASK_MAX_SEC: number;
+/** `http://w:8090/e/<lease>` → the proxy's origin and the lease token. */
+export declare function operatorEndpoint(egress: string | undefined | null): {
+    base: string;
+    token: string;
+} | null;
+/** The channel over the egress proxy. `fetchImpl` is for tests. */
+export declare function httpChannel(egress: string | undefined | null, fetchImpl?: typeof fetch): OperatorChannel | null;
+/** `ask: {timeout: 2h}` in an agent's frontmatter → seconds, clamped. */
+export declare function askTimeoutSec(front: Record<string, unknown>): number;
+/** "90s", "30m", "2h", "1d" or a number of seconds; null when unreadable. */
+export declare function parseDuration(raw: unknown): number | null;
+export declare 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 declare function buildAskTool(opts: {
+    channel: OperatorChannel | null;
+    timeoutSec: number;
+    emit: Emit;
+    local?: (question: string, options?: string[]) => Promise<string | null>;
+    now?: () => number;
+}): {
+    server: import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;
+    /** The tool's own function, for tests. */
+    call: (args: {
+        question: string;
+        options?: string[];
+    }) => Promise<{
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        content: ({
+            type: "text";
+            text: string;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            type: "image";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            type: "audio";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | {
+            uri: string;
+            description?: string | undefined;
+            mimeType?: string | undefined;
+            size?: number | undefined;
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "dark" | "light" | undefined;
+            }[] | undefined;
+            name: string;
+            title?: string | undefined;
+            type: "resource_link";
+        } | {
+            type: "resource";
+            resource: {
+                uri: string;
+                mimeType?: string | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+                text: string;
+            } | {
+                uri: string;
+                mimeType?: string | undefined;
+                _meta?: {
+                    [x: string]: unknown;
+                } | undefined;
+                blob: string;
+            };
+            annotations?: {
+                audience?: ("assistant" | "user")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        })[];
+        structuredContent?: {
+            [x: string]: unknown;
+        } | undefined;
+        isError?: boolean | undefined;
+    }>;
+    toolNames: string[];
+    promptLines: string[];
+};
+/** The granted name of the tool — the same on every path. */
+export declare const ASK_TOOL = "mcp__foldrun_ask__ask_person";
+/** The line the system prompt gets for it. */
+export declare function askPromptLine(timeoutSec: number): string;
+/** 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 declare function inboxReader(channel: OperatorChannel | null, emit: Emit, minGapMs?: number, now?: () => number): () => Promise<string | null>;
+/** Fold one operator event into the step's record. Pure; the runner calls
+ *  it as events arrive, whichever sandbox sent them. */
+export declare function applyOperatorEvent(step: {
+    questions?: StepQuestion[];
+    messages?: StepMessage[];
+}, ev: OperatorEvent, at: string): void;
+/** The question a step is waiting on, if any. */
+export declare const openQuestion: (step: {
+    questions?: StepQuestion[];
+}) => StepQuestion | 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 declare function isOperatorEvent(v: unknown): v is OperatorEvent;
+export {};

package/dist/src/operator.js

@@ -0,0 +1,251 @@
+// 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";
+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) {
+    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, fetchImpl = fetch) {
+    const ep = operatorEndpoint(egress);
+    if (!ep)
+        return null;
+    const json = async (res) => {
+        const body = (await res.json().catch(() => ({})));
+        if (!res.ok)
+            throw new Error(String(body.error?.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 ?? 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 : [];
+        },
+        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) {
+    const raw = front.ask?.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) {
+    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()];
+    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.";
+/** 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) {
+    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) => ({ content: [{ type: "text", 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;
+        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 = 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) => 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) {
+    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) => (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, emit, minGapMs = 1_500, now = Date.now) {
+    let last = Number.NEGATIVE_INFINITY;
+    return async () => {
+        if (!channel)
+            return null;
+        if (now() - last < minGapMs)
+            return null;
+        last = now();
+        let messages;
+        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, ev, at) {
+    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) => [...(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) {
+    if (!v || typeof v !== "object")
+        return false;
+    const o = v;
+    const str = (x, max) => 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/dist/src/paths.d.ts

@@ -31,8 +31,36 @@ export declare function dataRoot(): string;
  * no account and no tenant there, so the wrapper directories collapse away.
  */
 export declare function singleWorkspace(): string | 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 declare function singleAccountRoot(): 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;
+/** 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 declare const MAX_EDITABLE_FILE: number;
+/**
+ * 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 declare function entriesNoFollow(dir: string): string[];

package/dist/src/paths.js

@@ -21,6 +21,7 @@
 // caches: the whole point is that the answer can change between calls.
 import fs from "node:fs";
 import path from "node:path";
+import { accountRootFor } from "./layout.js";
 /**
  * The nearest enclosing project root, found by walking up from `from` looking
  * for a `.git` directory. Null when there is none — an installed package in
@@ -76,6 +77,28 @@ export function dataRoot() {
 export function singleWorkspace() {
     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() {
+    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
@@ -108,3 +131,35 @@ export function trimChars(s, chars) {
         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) {
+    const out = [];
+    const walk = (abs, rel) => {
+        let entries;
+        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/dist/src/platform.d.ts

@@ -14,7 +14,7 @@ export type TriggerAdmission = {
     admit: true;
 } | {
     admit: false;
-    reason: "duplicate" | "throttled" | "quarantined" | "debounced";
+    reason: "duplicate" | "throttled" | "quarantined" | "paused" | "debounced";
     detail: string;
     firesAt?: number;
 };
@@ -87,9 +87,9 @@ export interface PlatformHooks {
     /** 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): {
+    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. */
@@ -126,6 +126,46 @@ export interface PlatformHooks {
         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;
 }
 export declare const platform: PlatformHooks;
 /** Install the platform's implementations. Partial: what is not given keeps its local default. */

package/dist/src/platform.js

@@ -24,7 +24,7 @@ const local = {
     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 },
@@ -32,6 +32,14 @@ const local = {
     sandboxResumable: () => false,
     galleryDir: () => null,
     noteOAuthRefresh: async () => undefined,
+    fetchUntrusted: (url, init) => fetch(url, init),
+    async deliverWebhook(tenant, workspace, delivery) {
+        const { attemptWebhook, newDeliveryId } = await import("./notify.js");
+        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
 // the boot file and each route handler separately (Next does) gives every

package/dist/src/provider-health.js

@@ -23,6 +23,7 @@ import matter from "gray-matter";
 import { getSecret } from "./secrets.js";
 import { noteSecretUse, healthKey } from "./secret-health.js";
 import { accountDir, workspaceDir, listWorkspaces, listAgents, parseProvider } from "./store.js";
+import { fetchUntrusted } from "./untrusted-fetch.js";
 /** How long to wait. A provider slower than this is not one a step should
  *  be waiting on either, and the check must never hold a tick. */
 const TIMEOUT_MS = 15_000;
@@ -115,12 +116,12 @@ export async function checkProvider(tenant, workspace, spec, model) {
     for (const [k, v] of Object.entries(spec.headers ?? {}))
         headers[k.toLowerCase()] = resolve(tenant, workspace, v);
     try {
-        const res = await fetch(url, {
+        const res = await fetchUntrusted(url, {
             method: "POST",
             headers,
             body: JSON.stringify(body),
             signal: AbortSignal.timeout(TIMEOUT_MS),
-        });
+        }, { sameOrigin: true });
         const { verdict, detail } = verdictFor(res.status);
         // The check is itself a use of the credential, and the most informative
         // one there is: it was made for exactly this purpose.