@foldrun/core 0.6.0 → 1.0.0

package/dist/src/package.js

@@ -0,0 +1,594 @@
+// Export a workspace, a flow or an agent as one .zip, and import one.
+//
+// Agent import (agent-import.ts) copies between workspaces of ONE account;
+// `foldrun pull` then `foldrun deploy` moves a whole workspace, but only from
+// a terminal. Neither gets a desk from one account or installation to
+// another from the dashboard, and nothing exported a single flow. A package
+// is the unit for that: the authored source a thing needs to run, as a zip
+// with a small manifest, which any account can preview and take in.
+//
+// What is IN a package is what an author wrote — never what runs made
+// (memory/, state/, outputs/, storage), never the vault (secret names are
+// listed so the importer can set them; values never leave), never the
+// engine's .claude session files.
+//
+//   workspace  the whole authored tree
+//   flow       the flow, every flow it runs as a step, every agent those
+//              steps and their colleagues name, and the workspace tools,
+//              skills and scripts those agents grant
+//   agent      the agent's folder (what agent import copies), and the
+//              workspace tools, skills and scripts it grants
+//
+// What a package needs and does not carry — secrets, the account library,
+// an agent it consults — is worked out at IMPORT, from the files and the
+// target, not taken on trust from the manifest: a manifest is the sender's
+// claim, the files are what will run.
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import { assertSafeName, isEditablePath, listWorkspaceFiles, listWorkspaces, listFlows, parseFlow, readWorkspaceFile, saveWorkspace, blankTemplateFiles, syncBundleFor, notifyWorkspaceChanged, workspaceDir, } from "./store.js";
+import { recordRevision } from "./history.js";
+import { libraryDir, libraryTools } from "./library.js";
+import { discoverSkills } from "./runner.js";
+import { listSecrets } from "./secrets.js";
+import { isRuntimeTool } from "./tool-names.js";
+import { refNames } from "./refs.js";
+import { zip, unzip, ZipError } from "./zip.js";
+/** An error the API layer turns into a status rather than a 500. */
+export class PackageError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+export const MANIFEST_FILE = "foldrun-package.json";
+const MAX_FILES = 500;
+/** The authored source of a workspace: AGENTS.md and these folders. A
+ *  path anywhere else is never written by an import — isEditablePath alone
+ *  accepts a scripts/ folder at any depth, which let a zip write
+ *  runs/scripts/… and storage/scripts/… into a desk (audit, 7 Oct). */
+const AUTHORED_TOP = new Set(["agents", "flows", "evals", "skills", "knowledge", "tools", "scripts"]);
+/** Inside those, what runs or the engine made, and .env files — never in a
+ *  package. A package carries secret NAMES; a value in a tool's .env would
+ *  leave with it. */
+const NOT_PACKAGED = /^agents\/[^/]+\/(memory|outputs|state|workspace|\.claude)(\/|$)|^agents\/[^/]+\/\.claude[^/]*$|(^|\/)\.claude(\/|$)|(^|\/)(\.env(\.[^/]*)?|[^/]+\.env)$/;
+export function isPackagedPath(rel) {
+    if (rel === "AGENTS.md" || rel === "project.md")
+        return true;
+    if (!AUTHORED_TOP.has(rel.split("/")[0]))
+        return false;
+    return !NOT_PACKAGED.test(rel) && isEditablePath(rel);
+}
+/** Largest one file in a package — what a deploy carries, not the 512 KB a
+ *  person edits: a deployed 800 KB CSV exported and then could not come back. */
+const MAX_PACKAGE_FILE = 10 * 1024 * 1024;
+// ---------------------------------------------------------------- export
+export function packageOf(tenant, workspace, kind, name) {
+    assertSafeName(workspace, "workspace");
+    if (!listWorkspaces(tenant).some((w) => w.name === workspace)) {
+        throw new PackageError(`no workspace called "${workspace}" in this account`, 404);
+    }
+    const all = listWorkspaceFiles(tenant, workspace).filter(isPackagedPath);
+    const read = (p) => readWorkspaceFile(tenant, workspace, p);
+    let paths;
+    let label;
+    if (kind === "workspace") {
+        paths = all;
+        label = workspace;
+    }
+    else {
+        if (!name)
+            throw new PackageError(`name the ${kind} to export`, 400);
+        assertSafeName(name, kind);
+        label = name;
+        paths = kind === "flow" ? flowClosure(tenant, workspace, name, all, read) : agentClosure([name], all, read, false);
+    }
+    const files = paths.sort().map((p) => ({ path: p, content: read(p) }));
+    return {
+        manifest: {
+            format: "foldrun-package",
+            version: 1,
+            kind,
+            name: label,
+            workspace,
+            exportedAt: new Date().toISOString(),
+            files: files.map((f) => f.path),
+        },
+        files,
+    };
+}
+export function packageZip(pkg) {
+    return zip([
+        { path: MANIFEST_FILE, data: Buffer.from(`${JSON.stringify(pkg.manifest, null, 2)}\n`) },
+        ...pkg.files.map((f) => ({ path: f.path, data: Buffer.from(f.content, "utf8") })),
+    ]);
+}
+/** What the download is called: `<workspace>.zip`, `<workspace>-flow-<name>.zip`. */
+export function packageFilename(m) {
+    return m.kind === "workspace" ? `${m.workspace}.zip` : `${m.workspace}-${m.kind}-${m.name}.zip`;
+}
+function flowClosure(tenant, workspace, flow, all, read) {
+    // By name, the way a step addresses a flow — the file may be called
+    // something else (flows/publish-v2.md with name: publish was left out).
+    const byName = new Map(listFlows(tenant, workspace).map((f) => [f.name, f]));
+    const flows = new Set();
+    const files = new Set();
+    const agents = new Set();
+    const visit = (name) => {
+        if (flows.has(name))
+            return;
+        const info = byName.get(name);
+        if (!info) {
+            if (flows.size === 0)
+                throw new PackageError(`no flow called "${name}" in ${workspace}`, 404);
+            return; // a missing subflow — import reports it, export carries what exists
+        }
+        flows.add(name);
+        files.add(`flows/${info.file}`);
+        for (const s of info.steps) {
+            if (s.subflow)
+                visit(s.subflow);
+            else if (s.agent)
+                agents.add(s.agent);
+            if (s.onFail)
+                agents.add(s.onFail);
+            for (const d of s.delegate ?? [])
+                agents.add(d);
+        }
+    };
+    visit(flow);
+    const flowFiles = all.filter((p) => files.has(p));
+    return [...new Set([...flowFiles, ...agentClosure([...agents], all, read, true)])];
+}
+/** The agents' own folders and the workspace-level tools, skills and scripts
+ *  they grant. With `colleagues`, every agent they consult or delegate to as
+ *  well — a flow does not run without them; a single agent's export names
+ *  them instead, and import says which are missing. */
+function agentClosure(names, all, read, colleagues) {
+    const out = new Set();
+    const seen = new Set();
+    const tools = toolFiles(all, read);
+    const skills = skillFiles(all, read);
+    const queue = [...names];
+    while (queue.length) {
+        const agent = queue.shift();
+        if (seen.has(agent))
+            continue;
+        seen.add(agent);
+        const own = all.filter((p) => p.startsWith(`agents/${agent}/`));
+        if (!own.includes(`agents/${agent}/agent.md`)) {
+            if (seen.size === 1 && !colleagues)
+                throw new PackageError(`no agent called "${agent}"`, 404);
+            continue;
+        }
+        own.forEach((p) => out.add(p));
+        const front = frontOf(read(`agents/${agent}/agent.md`));
+        for (const t of front.tools) {
+            for (const p of tools.get(t) ?? []) {
+                out.add(p);
+                // A single-file tool's program lives elsewhere in the workspace
+                // (`run: workspace/scripts/x.mjs`); without it the tool has nothing
+                // to run. onpage-desk's apply-onpage was exported without its script.
+                const prog = /^tools\/[^/]+\.md$/.test(p) ? toolProgram(read(p)) : null;
+                if (prog && all.includes(prog))
+                    out.add(prog);
+            }
+        }
+        // No `skills:` line: the runtime gives the agent every skill in scope, so
+        // the package carries every workspace skill.
+        for (const s of front.skills ?? [...skills.keys()])
+            for (const p of skills.get(s) ?? [])
+                out.add(p);
+        for (const s of front.scripts)
+            if (all.includes(`scripts/${s}`))
+                out.add(`scripts/${s}`);
+        if (colleagues)
+            queue.push(...front.agents);
+    }
+    return [...out];
+}
+// ---------------------------------------------------------------- import
+export function readPackage(buf) {
+    let entries;
+    try {
+        entries = unzip(buf, { maxEntries: 5000, maxFileBytes: MAX_PACKAGE_FILE, maxTotalBytes: 50 * 1024 * 1024 });
+    }
+    catch (err) {
+        if (err instanceof ZipError)
+            throw new PackageError(err.message, 400);
+        throw err;
+    }
+    // A folder zipped by hand ("Compress" on a Mac) puts everything under one
+    // top directory. Look through it when that is all there is.
+    const tops = new Set(entries.map((e) => e.path.split("/")[0]));
+    const top1 = [...tops][0];
+    if (tops.size === 1 && entries.every((e) => e.path.includes("/")) && !AUTHORED_TOP.has(top1) && !["memory", "state"].includes(top1)) {
+        const top = `${[...tops][0]}/`;
+        entries = entries.map((e) => ({ ...e, path: e.path.slice(top.length) }));
+    }
+    let manifest = {};
+    const files = [];
+    // Not authored source: memory, state, a .gitignore or CLAUDE.md beside a
+    // hand-zipped folder, runs/… — never written, and listed, so the person
+    // sees what was left out rather than the whole zip being refused for it.
+    const skipped = [];
+    for (const e of entries) {
+        if (e.path === MANIFEST_FILE) {
+            try {
+                manifest = JSON.parse(e.data.toString("utf8"));
+            }
+            catch {
+                throw new PackageError(`${MANIFEST_FILE} is not valid JSON`, 400);
+            }
+            continue;
+        }
+        if (!isPackagedPath(e.path)) {
+            skipped.push(e.path);
+            continue;
+        }
+        const content = e.data.toString("utf8");
+        if (!Buffer.from(content, "utf8").equals(e.data))
+            throw new PackageError(`${e.path} is not UTF-8 text`, 400);
+        try {
+            matter(content);
+        }
+        catch {
+            throw new PackageError(`${e.path}: its frontmatter does not parse`, 400);
+        }
+        files.push({ path: e.path, content });
+    }
+    if (files.length === 0) {
+        throw new PackageError(`the package has no files to import${skipped.length ? ` — only what an import never writes (${skipped.slice(0, 5).join(", ")}${skipped.length > 5 ? " …" : ""})` : ""}. A package carries AGENTS.md, agents, flows, evals, knowledge, skills, tools and scripts`, 400);
+    }
+    if (files.length > MAX_FILES)
+        throw new PackageError(`too many files: ${files.length} (at most ${MAX_FILES})`, 400);
+    // No manifest: a workspace folder zipped by hand is still importable.
+    const kind = manifest.kind === "flow" || manifest.kind === "agent" || manifest.kind === "workspace"
+        ? manifest.kind
+        : files.some((f) => f.path === "AGENTS.md")
+            ? "workspace"
+            : "flow";
+    if (manifest.format !== undefined && manifest.format !== "foldrun-package") {
+        throw new PackageError(`${MANIFEST_FILE} is not a foldrun package manifest`, 400);
+    }
+    if (manifest.version !== undefined && manifest.version !== 1) {
+        throw new PackageError(`package version ${manifest.version} is newer than this installation reads — update foldrun`, 400);
+    }
+    return {
+        manifest: {
+            format: "foldrun-package",
+            version: 1,
+            kind,
+            name: typeof manifest.name === "string" ? manifest.name : "",
+            workspace: typeof manifest.workspace === "string" ? manifest.workspace : "",
+            exportedAt: typeof manifest.exportedAt === "string" ? manifest.exportedAt : "",
+            files: files.map((f) => f.path),
+        },
+        files: files.sort((a, b) => a.path.localeCompare(b.path)),
+        skipped: skipped.sort(),
+    };
+}
+export function planImport(tenant, workspace, pkg) {
+    assertSafeName(workspace, "workspace");
+    const exists = listWorkspaces(tenant).some((w) => w.name === workspace);
+    if (!exists && pkg.manifest.kind !== "workspace") {
+        throw new PackageError(`no workspace called "${workspace}" — a ${pkg.manifest.kind} imports into one that exists`, 404);
+    }
+    const dir = workspaceDir(tenant, workspace);
+    const added = [];
+    const overwritten = [];
+    const unchanged = [];
+    const blocked = [];
+    for (const f of pkg.files) {
+        const abs = path.join(dir, f.path);
+        const why = exists ? targetProblem(dir, f.path) : null;
+        if (why) {
+            blocked.push(`${f.path}: ${why}`);
+            continue;
+        }
+        if (!exists || !fs.existsSync(abs))
+            added.push(f.path);
+        else if (sameText(fs.readFileSync(abs, "utf8"), f.content))
+            unchanged.push(f.path);
+        else
+            overwritten.push(f.path);
+    }
+    // Checked before anything is written, so an import is all or nothing: a
+    // zip naming knowledge/x.md/y.md where knowledge/x.md is a file failed
+    // half-way and left what it had written outside History (audit, 7 Oct).
+    if (blocked.length) {
+        throw new PackageError(`the package cannot be written into ${workspace}: ${blocked.slice(0, 5).join("; ")}${blocked.length > 5 ? " …" : ""}`, 409);
+    }
+    // A workspace with no AGENTS.md exports fine (sched-lab had none) but a new
+    // workspace needs one: it gets the blank one "Create workspace" makes.
+    if (!exists && !pkg.files.some((f) => f.path === "AGENTS.md"))
+        added.push("AGENTS.md");
+    return {
+        kind: pkg.manifest.kind,
+        name: pkg.manifest.name,
+        from: pkg.manifest.workspace,
+        workspace,
+        creates: !exists,
+        added,
+        overwritten,
+        unchanged,
+        skipped: pkg.skipped ?? [],
+        needs: needsOf(tenant, workspace, exists, pkg.files),
+    };
+}
+export function applyImport(tenant, workspace, pkg, opts = {}) {
+    const plan = planImport(tenant, workspace, pkg);
+    // The caller checked permissions for one of these; if the workspace came
+    // or went since, refuse rather than skip the check that applied.
+    if (opts.expect && (opts.expect === "create") !== plan.creates) {
+        throw new PackageError(`${workspace} ${plan.creates ? "no longer exists" : "was created meanwhile"} — preview the import again`, 409);
+    }
+    if (plan.overwritten.length && !opts.overwrite) {
+        throw new PackageError(`${plan.overwritten.length} file${plan.overwritten.length === 1 ? "" : "s"} in ${workspace} would be overwritten: ${plan.overwritten.slice(0, 8).join(", ")}${plan.overwritten.length > 8 ? " …" : ""} — import with overwrite to replace them`, 409);
+    }
+    const what = plan.kind === "workspace" ? "workspace" : `${plan.kind} ${plan.name}`;
+    const message = `import ${what}${plan.from ? ` from ${plan.from}` : ""}`.trim();
+    const meta = { ...(opts.by ? { by: opts.by } : {}), message };
+    if (plan.creates) {
+        const files = pkg.files.some((f) => f.path === "AGENTS.md") ? pkg.files : [...pkg.files, ...blankTemplateFiles(workspace)];
+        saveWorkspace(tenant, workspace, files, meta);
+        for (const f of files)
+            if (isCode(f.path))
+                fs.chmodSync(path.join(workspaceDir(tenant, workspace), f.path), 0o755);
+        return { ...plan, written: files.map((f) => f.path), revision: null };
+    }
+    // One revision for the whole import, so History and restore treat it as
+    // the single change it is. Never deletes: a file the package lacks stays.
+    const dir = workspaceDir(tenant, workspace);
+    const write = new Set([...plan.added, ...plan.overwritten]);
+    const changes = [];
+    try {
+        for (const f of pkg.files) {
+            if (!write.has(f.path))
+                continue;
+            const abs = path.join(dir, f.path);
+            const before = fs.existsSync(abs) ? fs.readFileSync(abs, "utf8") : null;
+            fs.mkdirSync(path.dirname(abs), { recursive: true });
+            fs.writeFileSync(abs, normalized(f.content));
+            changes.push({ path: f.path, before, after: null });
+            // Same rule as writeWorkspaceFile: code is executable wherever it lives.
+            if (isCode(f.path))
+                fs.chmodSync(abs, 0o755);
+        }
+    }
+    catch (err) {
+        // Put back what this import wrote; nothing reaches History.
+        for (const c of changes.reverse()) {
+            const abs = path.join(dir, c.path);
+            try {
+                if (c.before === null)
+                    fs.rmSync(abs, { force: true });
+                else
+                    fs.writeFileSync(abs, c.before);
+            }
+            catch {
+                // best effort — the error below is the one to report
+            }
+        }
+        throw new PackageError(`the import could not be written, and nothing was kept: ${err instanceof Error ? err.message : String(err)}`, 500);
+    }
+    for (const c of changes) {
+        const abs = path.join(dir, c.path);
+        syncBundleFor(abs, c.before === null ? "Creation" : "Update");
+        c.after = fs.readFileSync(abs, "utf8");
+    }
+    const rev = recordRevision(tenant, workspace, changes, meta);
+    if (changes.length)
+        notifyWorkspaceChanged(tenant, workspace, "write");
+    return { ...plan, written: changes.map((c) => c.path), revision: rev?.id ?? null };
+}
+/** Code is executable wherever it lives — writeWorkspaceFile's rule. */
+const isCode = (rel) => /(^|\/)scripts\//.test(rel) || (/^tools\//.test(rel) && !rel.endsWith(".md"));
+/** Why a file cannot be written at `rel` in `dir`, or null: a parent that is
+ *  a file, a target that is a directory, or a symlink on the way. */
+function targetProblem(dir, rel) {
+    const parts = rel.split("/");
+    let cur = dir;
+    for (let i = 0; i < parts.length; i++) {
+        cur = path.join(cur, parts[i]);
+        let st;
+        try {
+            st = fs.lstatSync(cur);
+        }
+        catch {
+            return null; // the rest does not exist yet — it will be made
+        }
+        if (st.isSymbolicLink())
+            return `${parts.slice(0, i + 1).join("/")} is a link`;
+        const last = i === parts.length - 1;
+        if (!last && !st.isDirectory())
+            return `${parts.slice(0, i + 1).join("/")} is a file`;
+        if (last && st.isDirectory())
+            return "a folder is there";
+    }
+    return null;
+}
+/** As writeWorkspaceFile stores it: one trailing newline. */
+const normalized = (s) => `${s.trimEnd()}\n`;
+/** The same text, whatever the line endings and trailing whitespace. A file
+ *  a deploy stored without a final newline, or a CSV with CRLF endings, is
+ *  byte-different from what an import would write and identical to read —
+ *  comparing bytes listed six such files of a live desk as "would replace"
+ *  when the desk was re-imported into itself. */
+const sameText = (a, b) => a.replace(/\r\n/g, "\n").trimEnd() === b.replace(/\r\n/g, "\n").trimEnd();
+function needsOf(tenant, workspace, exists, files) {
+    const inPkg = new Map(files.map((f) => [f.path, f.content]));
+    const there = exists ? listWorkspaceFiles(tenant, workspace) : [];
+    const readThere = (p) => readWorkspaceFile(tenant, workspace, p);
+    // Everything the target will have once the package is in.
+    const paths = [...new Set([...there, ...inPkg.keys()])];
+    const read = (p) => inPkg.get(p) ?? readThere(p);
+    const tools = new Set([...toolFiles(paths, read).keys(), ...Object.keys(libraryTools(tenant))]);
+    const skills = new Set([...skillFiles(paths, read).keys(), ...discoverSkills(libraryDir(tenant), "skills").map((s) => s.name)]);
+    const agents = new Set(paths.map((p) => /^agents\/([^/]+)\/agent\.md$/.exec(p)?.[1]).filter((x) => Boolean(x)));
+    // Flow names as steps address them: the frontmatter name, else the file name.
+    const flows = new Set(paths
+        .filter((p) => /^flows\/.+\.md$/.test(p))
+        .map((p) => {
+        try {
+            return parseFlow(p.slice("flows/".length), read(p)).name;
+        }
+        catch {
+            return p.slice("flows/".length, -3);
+        }
+    }));
+    const need = { secrets: new Set(), tools: new Set(), skills: new Set(), scripts: new Set(), agents: new Set(), flows: new Set() };
+    for (const f of files) {
+        const agent = /^agents\/([^/]+)\/agent\.md$/.exec(f.path)?.[1];
+        if (agent) {
+            const front = frontOf(f.content);
+            for (const t of front.tools)
+                if (!isRuntimeTool(t) && !tools.has(t) && !front.inline.has(t))
+                    need.tools.add(t);
+            for (const s of front.skills ?? [])
+                if (!skills.has(s) && !agentSkill(paths, read, agent, s))
+                    need.skills.add(s);
+            for (const s of front.scripts) {
+                if (![`agents/${agent}/scripts/${s}`, `scripts/${s}`].some((p) => paths.includes(p)) && !fs.existsSync(path.join(libraryDir(tenant), "scripts", s)))
+                    need.scripts.add(s);
+            }
+            for (const a of front.agents)
+                if (!agents.has(a))
+                    need.agents.add(a);
+            front.secrets.forEach((s) => need.secrets.add(s));
+        }
+        if (/^tools\//.test(f.path) && f.path.endsWith(".md")) {
+            const data = safeFront(f.content);
+            list(data.secrets).forEach((s) => need.secrets.add(s));
+            const prog = /^tools\/[^/]+\.md$/.test(f.path) ? toolProgram(f.content) : null;
+            if (prog && !paths.includes(prog))
+                need.scripts.add(prog);
+        }
+        // ${NAME} placeholders in the frontmatter (an API's headers, an MCP
+        // server's env) — not the prose, where ${PATH} is a shell variable.
+        if (/^(agents\/[^/]+\/agent\.md|tools\/.+\.md)$/.test(f.path)) {
+            const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(f.content)?.[1] ?? "";
+            for (const m of fm.matchAll(/\$\{([A-Z][A-Z0-9_]*)\}/g))
+                need.secrets.add(m[1]);
+        }
+        if (/^flows\/.+\.md$/.test(f.path)) {
+            let steps = [];
+            try {
+                steps = parseFlow(f.path, f.content).steps;
+            }
+            catch {
+                // an unparseable flow is check's to report, not import's
+            }
+            for (const s of steps) {
+                if (s.subflow) {
+                    if (!flows.has(s.subflow))
+                        need.flows.add(s.subflow);
+                    continue;
+                }
+                for (const a of [s.agent, s.onFail, ...(s.delegate ?? [])])
+                    if (a && !agents.has(a))
+                        need.agents.add(a);
+            }
+        }
+    }
+    let have;
+    try {
+        have = new Set(listSecrets(tenant, exists ? workspace : undefined).map((s) => s.name));
+    }
+    catch {
+        have = new Set();
+    }
+    const sorted = (s) => [...s].sort();
+    return {
+        secrets: sorted(new Set([...need.secrets].filter((s) => !have.has(s)))),
+        tools: sorted(need.tools),
+        skills: sorted(need.skills),
+        scripts: sorted(need.scripts),
+        agents: sorted(need.agents),
+        flows: sorted(need.flows),
+    };
+}
+// ---------------------------------------------------------------- shared
+/** A frontmatter list as the runtime reads it — arrays, comma strings, map
+ *  entries (refs.ts). */
+const list = (v) => refNames(v).map((s) => s.trim()).filter(Boolean);
+function safeFront(content) {
+    try {
+        return matter(content).data;
+    }
+    catch {
+        return {};
+    }
+}
+function frontOf(content) {
+    const d = safeFront(content);
+    const apis = Array.isArray(d.apis) ? d.apis.map((a) => (a && typeof a === "object" ? String(a.name ?? "") : "")) : [];
+    const mcp = d.mcpServers && typeof d.mcpServers === "object" ? Object.keys(d.mcpServers) : [];
+    const scripts = list(d.scripts);
+    return {
+        tools: list(d.tools),
+        skills: d.skills === undefined || d.skills === null ? null : list(d.skills),
+        scripts,
+        secrets: list(d.secrets),
+        agents: [...list(d.agents), ...list(d.subagents)],
+        inline: new Set([...apis, ...mcp, ...scripts, ...scripts.map((s) => s.replace(/\.[^.]+$/, ""))].filter(Boolean)),
+    };
+}
+/** The workspace file a single-file tool's `run:` names, as a workspace
+ *  path (`scripts/x.mjs`), or null when it names none or a place outside
+ *  the workspace (the account library, the gallery). */
+function toolProgram(content) {
+    const run = safeFront(content).run;
+    if (typeof run !== "string")
+        return null;
+    const rel = run.trim().replace(/^\.\//, "").replace(/^workspace\//, "").replace(/^(\.\.\/)+/, "");
+    if (/^(account|library|shared)\//.test(run.trim()) || rel.includes("..") || rel.startsWith("/"))
+        return null;
+    return rel || null;
+}
+/** Workspace tool name → its files: `tools/<x>.md`, or a folder tool's whole folder. */
+function toolFiles(paths, read) {
+    const out = new Map();
+    for (const p of paths) {
+        let m = /^tools\/([^/]+)\.md$/.exec(p);
+        if (m) {
+            const name = String(safeFront(read(p)).name ?? m[1]);
+            out.set(name, [p]);
+            continue;
+        }
+        m = /^tools\/([^/]+)\/tool\.md$/.exec(p);
+        if (m) {
+            const name = String(safeFront(read(p)).name ?? m[1]);
+            out.set(name, paths.filter((q) => q.startsWith(`tools/${m[1]}/`)));
+        }
+    }
+    return out;
+}
+/** Workspace skill name → its files: a skill folder (`skills/x/SKILL.md`
+ *  and what is beside it) or a single file (`skills/x.md`), as discoverSkills
+ *  finds them. */
+function skillFiles(paths, read) {
+    const out = new Map();
+    for (const p of paths) {
+        const folder = /^skills\/([^/]+)\/SKILL\.md$/.exec(p);
+        if (folder) {
+            out.set(String(safeFront(read(p)).name ?? folder[1]), paths.filter((q) => q.startsWith(`skills/${folder[1]}/`)));
+            continue;
+        }
+        const single = /^skills\/([^/]+)\.md$/.exec(p);
+        if (single)
+            out.set(String(safeFront(read(p)).name ?? single[1]), [p]);
+    }
+    return out;
+}
+function agentSkill(paths, read, agent, skill) {
+    const prefix = `agents/${agent}/skills/`;
+    return paths.some((p) => {
+        if (!p.startsWith(prefix))
+            return false;
+        const rest = p.slice(prefix.length);
+        const m = /^([^/]+)\/SKILL\.md$/.exec(rest) ?? /^([^/]+)\.md$/.exec(rest);
+        return Boolean(m) && (m[1] === skill || safeFront(read(p)).name === skill);
+    });
+}

package/dist/src/platform.d.ts

@@ -107,6 +107,11 @@ export interface PlatformHooks {
      *  on its record is resumed rather than destroyed and run again. Default:
      *  nothing is. */
     sandboxResumable(kind: string): boolean;
+    /** May this account's steps run on the platform's own model credential
+     *  (the host's key or Claude login)? A hosted platform lets only its
+     *  operator's accounts do so; every customer brings their own API key.
+     *  Default: yes — a laptop or a self-hosted install is its own operator. */
+    platformKeyAllowed(tenant: 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

package/dist/src/platform.js

@@ -30,6 +30,7 @@ const local = {
     egress: { lease: async () => null },
     workspaceChanged() { },
     sandboxResumable: () => false,
+    platformKeyAllowed: () => true,
     galleryDir: () => null,
     noteOAuthRefresh: async () => undefined,
     fetchUntrusted: (url, init) => fetch(url, init),

package/dist/src/provider-health.js

@@ -17,6 +17,7 @@
 //
 // It reads the same provider block a run reads, resolved the same way, so a
 // pass here means a run would reach the same place with the same key.
+import { accountModelBlock } from "./model-credential.js";
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
@@ -199,6 +200,8 @@ export function providersInUse(tenant) {
         out.push({ spec, workspace, declaredIn, model: cheapestModel(spec) });
     };
     add(frontmatterOf(path.join(accountDir(tenant), "AGENTS.md")).provider, null, "account");
+    // The account's own key from Settings → Model, which needs no block.
+    add(accountModelBlock((name) => getSecret(tenant, name)?.value ?? null), null, "account (Settings → Model)");
     for (const ws of safeList(() => listWorkspaces(tenant))) {
         const dir = workspaceDir(tenant, ws.name);
         add(frontmatterOf(path.join(dir, "AGENTS.md")).provider, ws.name, ws.name);

package/dist/src/providers.d.ts

@@ -346,6 +346,11 @@ export interface BrowseSettings {
     ignore_https_errors?: boolean;
     /** The NAME of a vault secret whose value encrypts state= logins at rest. */
     state_key?: string;
+    /** A saved login every call uses by default: loaded from
+     *  workspace/state/browser/<name>.json and saved back when the call ends.
+     *  Beside `cookies:` (with `state_key:`), the secret seeds it once and the
+     *  session the site keeps rotating is what later runs load. */
+    state?: string;
     /** true records every call, so the run page always has the recording to play. */
     video?: boolean;
     /** false stops the tool streaming its page to the run page while the step