@foldrun/core 0.2.0

package/dist/src/library.js

@@ -0,0 +1,341 @@
+// The account library: shared skills, scripts, memory and tool definitions
+// that every workspace in the account can use.
+//
+//   data/<tenant>/library/
+//   ├── skills/<name>/SKILL.md   Agent Skills format, shared
+//   ├── scripts/<file>           shared executables
+//   ├── memory/*.md              organisation-wide knowledge
+//   └── tools/<name>.md          reusable API definitions (frontmatter = ApiSpec)
+//
+// Resolution is nearest-wins, the same rule OKF uses for knowledge: an agent's
+// own file beats its workspace's, which beats the account's. So a team can set
+// a house style once and one agent can still override it.
+import fs from "node:fs";
+import path from "node:path";
+import { dataRoot, singleWorkspace } from "./paths.js";
+import matter from "gray-matter";
+import { KINDS } from "./kinds.js";
+import { recordRevision, registerTreeReader } from "./history.js";
+import { assertSafeName, assertCanonicalCase, buildMemoryIndex, parseToolDef, readToolDir, syncBundleFor, listWorkspaces, listAgents, workspaceDir, } from "./store.js";
+// Same order as the workspace nav and asset pages — one list, one order.
+// Order matters and is asserted: it is the order every noun list in the
+// product uses. Tools then scripts, because a script is material a tool
+// points at — see the KINDS table, which is where the order is declared.
+export const LIBRARY_KINDS = ["tools", "knowledge", "memory", "skills", "scripts"];
+export function libraryDir(tenant, kind) {
+    // Alongside the workspace in single-workspace mode: ./library, so a shared
+    // library is still possible on a laptop without inventing a home directory.
+    const single = singleWorkspace();
+    if (single) {
+        const base = path.join(path.resolve(single), "..", "library");
+        return kind ? path.join(base, kind) : base;
+    }
+    assertSafeName(tenant, "tenant");
+    return kind
+        ? path.join(dataRoot(), tenant, "library", kind)
+        : path.join(dataRoot(), tenant, "library");
+}
+const TEXT_EXT = /\.(md|py|sh|[mc]?js|ts|rb|sql|txt|json|ya?ml|toml)$/i;
+function assertLibraryPath(kind, rel) {
+    const norm = path.normalize(rel);
+    assertCanonicalCase(norm);
+    if (norm.startsWith("..") || path.isAbsolute(norm))
+        throw new Error(`illegal path: ${rel}`);
+    if (!TEXT_EXT.test(norm))
+        throw new Error(`unsupported file type: ${rel}`);
+    // A flat tool is a lone .md; a folder tool is tool.md plus the code it
+    // runs, so anything is allowed one level down inside a tool's own folder.
+    if (kind === "tools" && !norm.endsWith(".md") && !norm.includes("/")) {
+        throw new Error("a tool is a .md definition, or a folder holding tool.md and its code");
+    }
+    return norm;
+}
+export function listLibrary(tenant, kind) {
+    const dir = libraryDir(tenant, kind);
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    const describe = (file, fallback) => {
+        try {
+            const { data } = matter(fs.readFileSync(file, "utf8"));
+            return { name: data.name ?? fallback, description: data.description ?? "" };
+        }
+        catch {
+            return { name: fallback, description: "" };
+        }
+    };
+    // A folder tool is one entry named by its manifest, and its code is not a
+    // separate row: listing tools/browser/run.mjs beside tools/browser/tool.md
+    // says there are two tools called browser, one of which cannot be granted.
+    if (kind === "tools") {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                const manifest = path.join(full, "tool.md");
+                if (!fs.existsSync(manifest))
+                    continue;
+                out.push({
+                    ...describe(manifest, entry.name),
+                    path: `${entry.name}/tool.md`,
+                    ...toolShape(manifest, entry.name),
+                    updatedAt: fs.statSync(manifest).mtime.toISOString(),
+                });
+            }
+            else if (entry.name.endsWith(".md")) {
+                out.push({
+                    ...describe(full, entry.name.replace(/\.md$/, "")),
+                    path: entry.name,
+                    ...toolShape(full, entry.name),
+                    updatedAt: fs.statSync(full).mtime.toISOString(),
+                });
+            }
+        }
+        return out.sort((a, b) => a.path.localeCompare(b.path));
+    }
+    if (kind === "skills") {
+        for (const entry of fs.readdirSync(dir).sort()) {
+            const full = path.join(dir, entry);
+            if (fs.statSync(full).isDirectory()) {
+                const skillMd = path.join(full, "SKILL.md");
+                if (!fs.existsSync(skillMd))
+                    continue;
+                out.push({
+                    ...describe(skillMd, entry),
+                    path: `${entry}/SKILL.md`,
+                    hasScripts: fs.existsSync(path.join(full, "scripts")),
+                    updatedAt: fs.statSync(skillMd).mtime.toISOString(),
+                });
+            }
+            else if (entry.endsWith(".md")) {
+                out.push({
+                    ...describe(full, entry.replace(/\.md$/, "")),
+                    path: entry,
+                    hasScripts: false,
+                    updatedAt: fs.statSync(full).mtime.toISOString(),
+                });
+            }
+        }
+        return out;
+    }
+    for (const entry of fs.readdirSync(dir, { recursive: true })) {
+        const rel = String(entry);
+        const full = path.join(dir, rel);
+        if (!fs.statSync(full).isFile() || !TEXT_EXT.test(rel))
+            continue;
+        // The memory index is generated, so it isn't an entry in its own list.
+        if ((kind === "memory" || kind === "knowledge") &&
+            ["index.md", "log.md"].includes(rel))
+            continue;
+        out.push({
+            ...describe(full, rel),
+            path: rel,
+            updatedAt: fs.statSync(full).mtime.toISOString(),
+        });
+    }
+    return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+/** How a tool connects, and (for a script tool) the code it runs. */
+function toolShape(file, rel) {
+    try {
+        const { data } = matter(fs.readFileSync(file, "utf8"));
+        const def = parseToolDef(data, rel.replace(/\.md$/, ""));
+        if (!def)
+            return {};
+        return {
+            transport: def.kind,
+            ...(def.kind === "script" ? { runs: def.spec.run } : {}),
+        };
+    }
+    catch {
+        return {}; // a malformed definition gets no badge, not a broken page
+    }
+}
+export function readLibraryFile(tenant, kind, rel) {
+    const p = path.join(libraryDir(tenant, kind), assertLibraryPath(kind, rel));
+    if (!fs.existsSync(p))
+        throw new Error(`not found: ${rel}`);
+    return fs.readFileSync(p, "utf8");
+}
+/** Is there already something here? For refusing to create over it. */
+export function libraryFileExists(tenant, kind, rel) {
+    try {
+        return fs.existsSync(path.join(libraryDir(tenant, kind), assertLibraryPath(kind, rel)));
+    }
+    catch {
+        return false; // an illegal path does not exist, and write will refuse it
+    }
+}
+export function writeLibraryFile(tenant, kind, rel, content, meta = {}) {
+    if (content.length > 256 * 1024)
+        throw new Error("file too large");
+    const norm = assertLibraryPath(kind, rel);
+    if (norm.endsWith(".md"))
+        matter(content); // reject broken frontmatter
+    const p = path.join(libraryDir(tenant, kind), norm);
+    const existed = fs.existsSync(p);
+    const before = existed ? fs.readFileSync(p, "utf8") : null;
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, content);
+    // Executable where code lives: the scripts shelf, a skill's bundled
+    // scripts/, and now a folder tool's own code — a tool whose run.mjs is not
+    // executable fails at the exec, which reads as "the tool is broken".
+    if (kind === "scripts" || /scripts\//.test(norm) || (kind === "tools" && !norm.endsWith(".md"))) {
+        fs.chmodSync(p, 0o755);
+    }
+    syncBundleFor(p, existed ? "Update" : "Creation");
+    // The account shelf has one history, keyed by kind/path.
+    recordRevision(tenant, "@library", [{ path: `${kind}/${norm}`, before, after: content }], meta);
+}
+export function deleteLibraryPath(tenant, kind, rel, meta = {}) {
+    const norm = path.normalize(rel);
+    if (norm.startsWith("..") || path.isAbsolute(norm))
+        throw new Error(`illegal path: ${rel}`);
+    const target = path.join(libraryDir(tenant, kind), norm);
+    const gone = [];
+    if (fs.existsSync(target)) {
+        const entries = fs.statSync(target).isFile()
+            ? [target]
+            : fs.readdirSync(target, { recursive: true }).map((e) => path.join(target, String(e)));
+        for (const e of entries) {
+            try {
+                if (fs.statSync(e).isFile()) {
+                    gone.push({ path: `${kind}/${path.relative(libraryDir(tenant, kind), e).split(path.sep).join("/")}`, before: fs.readFileSync(e, "utf8"), after: null });
+                }
+            }
+            catch {
+                // skip
+            }
+        }
+    }
+    fs.rmSync(target, { recursive: true, force: true });
+    recordRevision(tenant, "@library", gone, { message: `deleted ${kind}/${norm}`, ...meta });
+}
+// ---------- consumed by the runner ----------
+/** Library tool definitions, keyed by name — http or script, both grantable by name in `tools:`. */
+export function libraryTools(tenant) {
+    return readToolDir(libraryDir(tenant, "tools"), "account");
+}
+/** Shared memory index — derived from the files, like every other scope. */
+export function libraryMemoryIndex(tenant) {
+    // The prefix matters: without it the index names bare filenames that don't
+    // exist relative to the agent, so it guesses and gets denied.
+    return buildMemoryIndex(libraryDir(tenant, "memory"), "../../../../library/memory/");
+}
+/**
+ * Account-scope creation, expressed as a path inside `library/<kind>/`.
+ *
+ * The content comes from KINDS — an account skill and a workspace skill are
+ * the same document in a different place, and used to be two templates that
+ * drifted. `file()` returns a path from the scope root (`skills/x/SKILL.md`);
+ * here the kind directory is already the root, so the leading segment goes.
+ */
+export const LIBRARY_TEMPLATES = Object.fromEntries(LIBRARY_KINDS.map((kind) => [
+    kind,
+    (name) => ({
+        path: KINDS[kind].file(name).replace(new RegExp(`^${kind}/`), ""),
+        content: KINDS[kind].template(name),
+    }),
+]));
+/** The file a kind would occupy at a given scope root, relative to that root. */
+function localPath(kind, name) {
+    return KINDS[kind].file(name);
+}
+export function libraryUsage(tenant, kind, name) {
+    const out = [];
+    for (const ws of listWorkspaces(tenant)) {
+        const dir = workspaceDir(tenant, ws.name);
+        const agents = listAgents(tenant, ws.name);
+        // Explicit grant. Only tools have one.
+        if (kind === "tools") {
+            for (const a of agents) {
+                if (a.ownTools.includes(name))
+                    out.push({ workspace: ws.name, agent: a.name, relation: "use" });
+            }
+        }
+        // Nearest-wins: a workspace file of the same name, or an agent's own.
+        if (fs.existsSync(path.join(dir, localPath(kind, name)))) {
+            out.push({ workspace: ws.name, agent: null, relation: "shadowed" });
+        }
+        for (const a of agents) {
+            const own = path.join(dir, "agents", a.name, localPath(kind, name));
+            if (fs.existsSync(own)) {
+                out.push({ workspace: ws.name, agent: a.name, relation: "shadowed" });
+            }
+        }
+    }
+    return out;
+}
+// The account shelf as one tree, kind/path — see registerTreeReader.
+registerTreeReader((tenant, scope) => {
+    if (scope !== "@library")
+        return null;
+    const out = [];
+    for (const kind of LIBRARY_KINDS) {
+        const dir = libraryDir(tenant, kind);
+        if (!fs.existsSync(dir))
+            continue;
+        for (const entry of fs.readdirSync(dir, { recursive: true })) {
+            const rel = String(entry).split(path.sep).join("/");
+            const full = path.join(dir, rel);
+            try {
+                if (!fs.statSync(full).isFile() || !TEXT_EXT.test(rel))
+                    continue;
+                out.push({ path: `${kind}/${rel}`, before: null, after: fs.readFileSync(full, "utf8") });
+            }
+            catch {
+                // skip
+            }
+        }
+    }
+    return out;
+});
+/**
+ * Make the shelf match a tree — what a push to the library repository does.
+ * Written with plain fs and recorded as ONE revision at the end: going
+ * through writeLibraryFile per file would commit each one on top of the
+ * pushed commit, and the history would show a push as fifty edits.
+ */
+export function syncLibraryFromTree(tenant, files, meta = {}) {
+    const wanted = new Map();
+    for (const f of files) {
+        const [kind, ...rest] = f.path.split("/");
+        if (!LIBRARY_KINDS.includes(kind) || rest.length === 0)
+            continue;
+        wanted.set(f.path, f.content);
+    }
+    const changes = [];
+    for (const kind of LIBRARY_KINDS) {
+        const dir = libraryDir(tenant, kind);
+        if (!fs.existsSync(dir))
+            continue;
+        for (const entry of fs.readdirSync(dir, { recursive: true })) {
+            const rel = `${kind}/${String(entry).split(path.sep).join("/")}`;
+            const full = path.join(dir, String(entry));
+            try {
+                if (!fs.statSync(full).isFile() || !TEXT_EXT.test(rel))
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            if (!wanted.has(rel)) {
+                changes.push({ path: rel, before: fs.readFileSync(full, "utf8"), after: null });
+                fs.rmSync(full, { force: true });
+            }
+        }
+    }
+    for (const [rel, content] of wanted) {
+        const [kind, ...rest] = rel.split("/");
+        const full = path.join(libraryDir(tenant, kind), assertLibraryPath(kind, rest.join("/")));
+        const before = fs.existsSync(full) ? fs.readFileSync(full, "utf8") : null;
+        if (before === content)
+            continue;
+        fs.mkdirSync(path.dirname(full), { recursive: true });
+        fs.writeFileSync(full, content);
+        if (kind === "scripts" || /scripts\//.test(rel) || (kind === "tools" && !rel.endsWith(".md")))
+            fs.chmodSync(full, 0o755);
+        changes.push({ path: rel, before, after: content });
+    }
+    recordRevision(tenant, "@library", changes, { by: meta.by ?? "deploy", message: meta.commit ? `deployed ${meta.commit.slice(0, 7)}` : "synced from push", commit: meta.commit ?? null });
+    return changes.length;
+}

package/dist/src/linkable.d.ts

@@ -0,0 +1,20 @@
+export interface LinkableDoc {
+    /** What a person types between the brackets. */
+    name: string;
+    /** Shown beside it in the list. */
+    hint: string;
+}
+/** The directories a bare [[name]] may point at, matching the resolver. */
+export declare const LINKABLE_DIRS: string[];
+/**
+ * Everything [[ ]] resolves to in this workspace, in the order a person
+ * would want it: documents first, then the file store, then the folders.
+ *
+ * `workspaceRoot` is the workspace directory itself. `storageFiles` is the
+ * hosted store's listing when there is one; local installs pass nothing and
+ * the plain `storage/` directory on disk is walked instead — the same two
+ * sources, in the same order, that the resolver consults.
+ */
+export declare function linkableDocs(workspaceRoot: string, storageFiles?: {
+    path: string;
+}[], limit?: number): LinkableDoc[];

package/dist/src/linkable.js

@@ -0,0 +1,113 @@
+// What [[ ]] can name, as one list.
+//
+// This existed twice and the two copies disagreed. The runner's resolver
+// indexed the file store under its real directory name (`storage/`), while
+// the editor offered the same files as `files/…` — a label left over from
+// before the rename. Accepting that suggestion produced a link that matched
+// nothing, so the model received two literal brackets where a path was meant.
+// The same rename had already caused one silent failure elsewhere; this is
+// the second, and the reason the list now has one definition.
+//
+// The rule this encodes: the editor may only offer what the runner can
+// resolve. tests/doclinks-consistency.test.ts asserts the round trip on a
+// real workspace, so a future rename fails a test instead of a run.
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import { STORAGE_DIR } from "./store.js";
+/** The directories a bare [[name]] may point at, matching the resolver. */
+export const LINKABLE_DIRS = [STORAGE_DIR, "state", "knowledge", "memory", "skills", "outputs"];
+/**
+ * Everything [[ ]] resolves to in this workspace, in the order a person
+ * would want it: documents first, then the file store, then the folders.
+ *
+ * `workspaceRoot` is the workspace directory itself. `storageFiles` is the
+ * hosted store's listing when there is one; local installs pass nothing and
+ * the plain `storage/` directory on disk is walked instead — the same two
+ * sources, in the same order, that the resolver consults.
+ */
+export function linkableDocs(workspaceRoot, storageFiles = [], limit = 300) {
+    const out = [];
+    for (const kind of ["knowledge", "memory"]) {
+        const dir = path.join(workspaceRoot, kind);
+        if (!fs.existsSync(dir))
+            continue;
+        for (const entry of fs.readdirSync(dir, { recursive: true }).map(String)) {
+            if (!entry.endsWith(".md"))
+                continue;
+            // index.md and log.md are generated views of the bundle, not concepts
+            // to link at — offering them invites a link to a file that will be
+            // rewritten under it.
+            const base = path.basename(entry);
+            if (base === "index.md" || base === "log.md")
+                continue;
+            let title = "";
+            try {
+                const data = matter(fs.readFileSync(path.join(dir, entry), "utf8")).data;
+                for (const key of ["title", "name"]) {
+                    if (typeof data?.[key] === "string" && data[key]) {
+                        title = data[key];
+                        break;
+                    }
+                }
+            }
+            catch {
+                // unparseable frontmatter still links by filename
+            }
+            out.push({
+                name: entry.split(path.sep).join("/").replace(/\.md$/, ""),
+                hint: `${kind}${title ? ` — ${title}` : ""}`,
+            });
+        }
+    }
+    // state/ — what a recurring flow reads from its own past runs. Offered by
+    // path, like the file store and unlike knowledge/, because these are data
+    // files rather than documents with a title.
+    const stateDir = path.join(workspaceRoot, "state");
+    if (fs.existsSync(stateDir)) {
+        for (const entry of fs.readdirSync(stateDir, { recursive: true }).map(String)) {
+            try {
+                if (!fs.statSync(path.join(stateDir, entry)).isFile())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            out.push({ name: `state/${entry.split(path.sep).join("/")}`, hint: "state" });
+        }
+    }
+    // The file store, under the directory the resolver actually indexes.
+    const seen = new Set();
+    for (const f of storageFiles) {
+        if (seen.has(f.path))
+            continue;
+        seen.add(f.path);
+        out.push({ name: `${STORAGE_DIR}/${f.path}`, hint: "file" });
+    }
+    const filesDir = path.join(workspaceRoot, STORAGE_DIR);
+    if (fs.existsSync(filesDir)) {
+        for (const entry of fs.readdirSync(filesDir, { recursive: true }).map(String)) {
+            const fwd = entry.split(path.sep).join("/");
+            if (fwd.startsWith(".store/") || seen.has(fwd))
+                continue;
+            try {
+                if (!fs.statSync(path.join(filesDir, entry)).isFile())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            seen.add(fwd);
+            out.push({ name: `${STORAGE_DIR}/${fwd}`, hint: "file" });
+        }
+    }
+    // The folders themselves. The resolver has always accepted these — an
+    // instruction that says WHERE without naming a file is a real thing to
+    // write — and nothing offered them, so the capability was undiscoverable.
+    for (const dir of LINKABLE_DIRS) {
+        if (fs.existsSync(path.join(workspaceRoot, dir))) {
+            out.push({ name: dir, hint: "the whole folder" });
+        }
+    }
+    return out.slice(0, limit);
+}

package/dist/src/model-probe.d.ts

@@ -0,0 +1,21 @@
+import type { Effort } from "./store.ts";
+export interface ProbeReport {
+    model: string;
+    /** The model made a real tool call — the handler ran. */
+    calledTool: boolean;
+    /** The nonce came back in the reply: the loop closed end to end. */
+    echoedNonce: boolean;
+    /** calledTool && echoedNonce — what "can drive an agent" actually means. */
+    ok: boolean;
+    status: "completed" | "failed";
+    costUsd: number | null;
+    durationMs: number;
+    /** The reply itself, for the human reading a failure. */
+    reply: string | null;
+}
+/**
+ * Run the tool-loop probe against one model, through whatever endpoint the
+ * env points at — pass the same env a step would get (provider base URL,
+ * token, tier remaps) and the probe exercises the exact path a run takes.
+ */
+export declare function probeModel(model: string, env: Record<string, string | undefined>, effort?: Effort | null): Promise<ProbeReport>;

package/dist/src/model-probe.js

@@ -0,0 +1,81 @@
+// "Can this model hold a tool loop?" — answered by running one, not by
+// reading a spec sheet.
+//
+// The catalogue's `tools` flag is the gateway's claim; this is the ground
+// truth. The probe hands the model exactly one tool, whose result is a nonce
+// invented per run, and asks it to call the tool and repeat the nonce back.
+// A model that can drive an agent loop does this in two turns. A model that
+// cannot — no tool support, tool calls narrated as prose, a gateway route
+// that strips tool blocks — has no other way to learn the nonce, so the
+// verdict cannot be faked by a model that merely talks about calling tools.
+// That distinction is the entire reason the probe exists: it is the same
+// failure the run-start gate guards against, demonstrated live through
+// whatever provider env the caller passes.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+import { executeStep } from "./step-exec.js";
+const PROBE_TIMEOUT_SEC = 120;
+/**
+ * Run the tool-loop probe against one model, through whatever endpoint the
+ * env points at — pass the same env a step would get (provider base URL,
+ * token, tier remaps) and the probe exercises the exact path a run takes.
+ */
+export async function probeModel(model, env, effort = null) {
+    const nonce = `probe-${randomBytes(6).toString("hex")}`;
+    let calledTool = false;
+    const probeTool = tool("probe_fetch_token", "Returns a secret token. Call it exactly once.", {
+        // One required argument, because a loop that can't pass arguments
+        // can't run real tools either — echoing a fixed call is the easiest
+        // possible tool use, and we deliberately don't test the easiest.
+        purpose: z.string().describe("Why you are fetching the token, in a few words"),
+    }, async () => {
+        calledTool = true;
+        return { content: [{ type: "text", text: nonce }] };
+    });
+    // Homeless on purpose, like a consult: the probe reads and writes nothing,
+    // and a throwaway cwd means even a confused model call has no tree to touch.
+    const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "foldrun-probe-"));
+    const started = Date.now();
+    try {
+        const outcome = await executeStep({
+            agentDir: scratch,
+            workspaceRoot: scratch,
+            libraryRoot: scratch,
+            prompt: "Call the probe_fetch_token tool once, then reply with exactly the token it " +
+                "returns and nothing else. If you cannot call tools, reply CANNOT.",
+            model,
+            effort,
+            systemPrompt: "You are a connectivity probe. Follow the instruction literally. Do not explain.",
+            allowed: [],
+            mcpNames: ["foldrun_probe"],
+            mcpServers: {
+                foldrun_probe: createSdkMcpServer({
+                    name: "foldrun_probe",
+                    version: "1.0.0",
+                    tools: [probeTool],
+                }),
+            },
+            env,
+            timeoutSec: PROBE_TIMEOUT_SEC,
+            emit: () => { }, // the probe's transcript is the report, not a run log
+        });
+        const echoedNonce = (outcome.result ?? "").includes(nonce);
+        return {
+            model,
+            calledTool,
+            echoedNonce,
+            ok: calledTool && echoedNonce,
+            status: outcome.status,
+            costUsd: outcome.costUsd,
+            durationMs: Date.now() - started,
+            reply: outcome.result,
+        };
+    }
+    finally {
+        fs.rmSync(scratch, { recursive: true, force: true });
+    }
+}

package/dist/src/notify.d.ts

@@ -0,0 +1,61 @@
+import { type RunRecord } from "./store.ts";
+/**
+ * The platform's own mail: an invite, a low balance.
+ *
+ * These are from foldrun, about the platform, to the account's owner — so
+ * they go through the platform's Resend key and sender (FOLDRUN_RESEND_API_KEY,
+ * FOLDRUN_EMAIL_FROM), never through anything the customer configured.
+ *
+ * Without a platform key — the CLI on a laptop, a test — the account's own
+ * key and EMAIL_FROM are the fallback.
+ */
+export declare function platformMail(tenant: string): {
+    key: string;
+    from: string;
+} | null;
+/** The account's own Resend key and sender, or null when it has none. */
+export declare function accountMail(tenant: string): {
+    key: string;
+    from: string;
+} | null;
+/**
+ * A run notification is the account's mail, not the platform's: it is a
+ * desk telling its owner what it found, and the owner chose the sender —
+ * their RESEND_API_KEY and EMAIL_FROM on the account, the same connection
+ * their agents' `email` tool uses. So it comes from the address they
+ * expect, under their own domain's reputation and their own inbox rules;
+ * 2026-09-06, every notification from the platform's address was in the
+ * owner's bin. The platform's key is the fallback for an account that set
+ * none, so `notify:` works before anyone has configured mail at all.
+ */
+export declare function notifyMail(tenant: string): {
+    key: string;
+    from: string;
+} | null;
+export interface NotifyConfig {
+    url?: string;
+    email?: string;
+    events: string[];
+}
+export declare function notifyConfig(tenant: string, workspace: string): NotifyConfig | null;
+/**
+ * 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.
+ *
+ * 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): {
+    approveUrl: string;
+    rejectUrl: string;
+} | null;
+/**
+ * Fire the webhook for a run's state, if the workspace asked to hear about
+ * it. Failures are logged and swallowed — a broken Slack hook must never
+ * fail the run it is reporting on.
+ */
+/** Flows whose completion is nobody's news: eval cases and adhoc runs. */
+export declare function isQuietFlow(flow: string): boolean;
+export declare function sendRunNotification(tenant: string, workspace: string, run: RunRecord): Promise<boolean>;