@foldrun/core 0.3.0 → 0.5.0

package/README.md

@@ -188,19 +188,36 @@ a hand-edited template cannot ship an index that disagrees with its own files.
 ## Hosting it
 
 This package is the framework: everything needed to read a workspace and
-run it on the machine you are on. The hosted platform at
-[foldrun.io](https://foldrun.io) — a queue and its worker, one gVisor pod
-per step, a vault, metering, a team — is built on it, in a separate private
-package that plugs in through `src/platform.ts`. Nothing in this repository
-imports it, so what is here is exactly what is open. There is no
-self-hosted platform; `foldrun deploy` and `git push` move a workspace from
-your machine to the hosted one unchanged.
+run it on the machine you are on. The platform — the dashboard, a queue and
+its worker, one sandbox per step, a vault, metering, a team — is built on
+it, in a separate package that plugs in through `src/platform.ts`. Nothing
+in this repository imports it, so what is here is exactly what is open.
+
+**Run the platform yourself:** one container, one command —
+[self-hosting/](self-hosting/). Sign up at `localhost:3900`, and
+`foldrun deploy` moves a workspace from your machine to it unchanged. The
+images are the same builds that run foldrun's own installation, published
+under the same versions.
 
 ## Requirements
 
-Node 22+. Docker or Podman if your agents run scripts. Credentials come from
-`ANTHROPIC_API_KEY` or an existing Claude Code login — `foldrun check` needs
-neither.
+Node 22+. Docker or Podman if your agents run scripts. `foldrun check` needs
+no credential at all.
+
+To *run* an agent you need one of:
+
+- **`ANTHROPIC_API_KEY`** — an API key from
+  [console.anthropic.com](https://console.anthropic.com).
+- **Your own provider.** An agent that names a `provider:` needs no
+  Anthropic key: 29 endpoints are known by name, including `ollama`,
+  `lmstudio` and `vllm`, so a local model is a complete answer. Anything
+  not in that list works by spelling out `base_url:`, `format:` and
+  `auth:`. See [providers](https://docs.foldrun.io/providers).
+
+A **Claude Code or claude.ai subscription login is not one of them**, and
+the CLI will not look for one. Anthropic does not permit products built on
+its Agent SDK to run on consumer subscriptions, so using that login here
+would put you outside their terms — an API key is the supported path.
 
 ## Status
 

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./src/layout.ts";
 export * from "./src/paths.ts";
 export * from "./src/store.ts";
 export * from "./src/starter.ts";
@@ -10,6 +11,7 @@ export * from "./src/model-probe.ts";
 export * from "./src/providers.ts";
 export * from "./src/translator.ts";
 export * from "./src/arrange.ts";
+export * from "./src/flow-patterns.ts";
 export * from "./src/completions.ts";
 export * from "./src/confine.ts";
 export * from "./src/platform.ts";
@@ -28,5 +30,6 @@ export * from "./src/notify.ts";
 export * from "./src/webhook.ts";
 export * from "./src/approvals.ts";
 export * from "./src/deploy.ts";
+export * from "./src/account.ts";
 export * from "./src/tar.ts";
 export * from "./src/git.ts";

package/dist/index.js

@@ -9,6 +9,7 @@
 // its worker, metering and billing, pods on a cluster, per-account keys in a
 // database, previews, share links, tenancy — lives in its own private package
 // and plugs in through platform.ts. Nothing here imports it.
+export * from "./src/layout.js";
 export * from "./src/paths.js";
 export * from "./src/store.js";
 export * from "./src/starter.js";
@@ -21,6 +22,7 @@ export * from "./src/model-probe.js";
 export * from "./src/providers.js";
 export * from "./src/translator.js";
 export * from "./src/arrange.js";
+export * from "./src/flow-patterns.js";
 export * from "./src/completions.js";
 export * from "./src/confine.js";
 export * from "./src/platform.js";
@@ -39,5 +41,6 @@ export * from "./src/notify.js";
 export * from "./src/webhook.js";
 export * from "./src/approvals.js";
 export * from "./src/deploy.js";
+export * from "./src/account.js";
 export * from "./src/tar.js";
 export * from "./src/git.js";

package/dist/src/account.d.ts

@@ -0,0 +1,45 @@
+import { type LibraryKind } from "./library.ts";
+import { type Layout } from "./layout.ts";
+import type { DeployFile } from "./store.ts";
+export interface AccountWorkspace {
+    name: string;
+    dir: string;
+    files: DeployFile[];
+}
+export interface LibraryFile {
+    kind: LibraryKind;
+    /** Relative to the kind's directory — what the library API calls `path`. */
+    path: string;
+    content: string;
+}
+export interface AccountTree {
+    root: string;
+    /** The account-scope AGENTS.md, or null when there is none. */
+    agentsMd: string | null;
+    library: LibraryFile[];
+    workspaces: AccountWorkspace[];
+}
+/** The shared library under an account root, flattened to one list. */
+export declare function readLibraryTree(accountRoot: string): LibraryFile[];
+/**
+ * Everything an account folder would push: its AGENTS.md, its library, and
+ * every workspace under it.
+ *
+ * `only` narrows it to one workspace — `foldrun deploy <name>` — and still
+ * carries the account scope, because a workspace deployed without the library
+ * its agents name is a workspace that fails on its first run.
+ */
+export declare function readAccountTree(accountRoot: string, only?: string): AccountTree;
+/**
+ * The account tree for wherever you are standing — an account root, a
+ * workspace inside one, or a flat workspace.
+ *
+ * A flat workspace is reported as an account of one whose root is its parent,
+ * which is exactly what `accountDir` and `libraryDir` already believe about
+ * it. So the deploy path has no branch for the old layout: it pushes one
+ * workspace and whatever library sits beside it, which is what it did before.
+ */
+export declare function accountTreeFrom(from: string, only?: string): {
+    layout: Layout;
+    tree: AccountTree;
+};

package/dist/src/account.js

@@ -0,0 +1,130 @@
+// An account folder, read as the thing a deploy pushes.
+//
+// `readTree` answers the same question for one workspace: what, of the files
+// on disk, is source? This is that question one scope up — the account's own
+// AGENTS.md, the shared `library/`, and every workspace under `workspaces/` —
+// so `foldrun deploy` at an account root has one list to walk and one shape to
+// report, rather than three special cases written at the call site.
+//
+// Nothing here talks to a platform. It reads a directory and says what is in
+// it; who gets sent where is the CLI's business, because the endpoints differ
+// per part (a workspace deploys whole, a library file writes one at a time)
+// and that asymmetry belongs next to the fetch calls, not in here.
+import fs from "node:fs";
+import path from "node:path";
+import { readTree } from "./deploy.js";
+import { LIBRARY_KINDS } from "./library.js";
+import { detectLayout, listWorkspaceDirs } from "./layout.js";
+/** Anything that is bookkeeping rather than source, at either scope. */
+const NOT_SOURCE = new Set([".foldrun", ".git", "node_modules", "runs", "outputs", ".DS_Store"]);
+function walkFiles(root, rel = "") {
+    const out = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(root).sort();
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        if (NOT_SOURCE.has(entry))
+            continue;
+        const full = path.join(root, entry);
+        const next = rel ? `${rel}/${entry}` : entry;
+        try {
+            if (fs.lstatSync(full).isSymbolicLink())
+                continue;
+            if (fs.statSync(full).isDirectory())
+                out.push(...walkFiles(full, next));
+            else
+                out.push({ path: next, content: fs.readFileSync(full, "utf8") });
+        }
+        catch {
+            /* unreadable: not source */
+        }
+    }
+    return out;
+}
+/** The shared library under an account root, flattened to one list. */
+export function readLibraryTree(accountRoot) {
+    const out = [];
+    for (const kind of LIBRARY_KINDS) {
+        const dir = path.join(accountRoot, "library", kind);
+        for (const f of walkFiles(dir)) {
+            // `.gitkeep` and friends keep an empty library directory in git and are
+            // not library entries: the write endpoint refuses a path with no known
+            // extension, so shipping one would fail the deploy over a placeholder.
+            if (f.path.split("/").some((seg) => seg.startsWith(".")))
+                continue;
+            out.push({ kind, path: f.path, content: f.content });
+        }
+    }
+    return out;
+}
+/**
+ * Everything an account folder would push: its AGENTS.md, its library, and
+ * every workspace under it.
+ *
+ * `only` narrows it to one workspace — `foldrun deploy <name>` — and still
+ * carries the account scope, because a workspace deployed without the library
+ * its agents name is a workspace that fails on its first run.
+ */
+export function readAccountTree(accountRoot, only) {
+    const root = path.resolve(accountRoot);
+    const agentsMdFile = path.join(root, "AGENTS.md");
+    let agentsMd = null;
+    try {
+        agentsMd = fs.readFileSync(agentsMdFile, "utf8");
+    }
+    catch {
+        /* an account with no AGENTS.md pushes none */
+    }
+    const names = listWorkspaceDirs(root).filter((n) => (only ? n === only : true));
+    if (only && names.length === 0) {
+        throw new Error(`no workspace "${only}" in ${root} — have: ${listWorkspaceDirs(root).join(", ") || "none"}`);
+    }
+    const wsRoot = path.join(root, "workspaces");
+    const legacy = path.join(root, "projects");
+    const base = fs.existsSync(wsRoot) ? wsRoot : legacy;
+    return {
+        root,
+        agentsMd,
+        library: readLibraryTree(root),
+        workspaces: names.map((name) => {
+            const dir = path.join(base, name);
+            return { name, dir, files: readTree(dir) };
+        }),
+    };
+}
+/**
+ * The account tree for wherever you are standing — an account root, a
+ * workspace inside one, or a flat workspace.
+ *
+ * A flat workspace is reported as an account of one whose root is its parent,
+ * which is exactly what `accountDir` and `libraryDir` already believe about
+ * it. So the deploy path has no branch for the old layout: it pushes one
+ * workspace and whatever library sits beside it, which is what it did before.
+ */
+export function accountTreeFrom(from, only) {
+    const layout = detectLayout(from);
+    if (layout.kind === "flat" || layout.kind === "empty") {
+        const dir = layout.workspaceDir;
+        const name = path.basename(dir);
+        if (only && only !== name)
+            throw new Error(`${dir} is a single workspace called "${name}", not "${only}"`);
+        return {
+            layout,
+            tree: {
+                root: layout.accountRoot,
+                // A flat workspace's AGENTS.md belongs to the workspace, not the
+                // account — pushing it as account scope would apply one desk's rules
+                // to every other desk in the installation.
+                agentsMd: null,
+                library: readLibraryTree(layout.accountRoot),
+                workspaces: [{ name, dir, files: readTree(dir) }],
+            },
+        };
+    }
+    const only2 = only ?? (layout.kind === "workspace-in-account" ? layout.workspace : undefined);
+    return { layout, tree: readAccountTree(layout.accountRoot, only2) };
+}

package/dist/src/api-tools.d.ts

@@ -25,6 +25,14 @@ export interface ApiToolResult {
     server: ReturnType<typeof createSdkMcpServer> | null;
     /** Tool names to allow, e.g. mcp__foldrun_apis__call_google_ads. */
     toolNames: string[];
+    /** SDK tool name → the API it was built for, recorded as each tool is
+     *  made: `crm`'s operation `admin_list` is `crm_admin_list` beside an API
+     *  named `crm_admin`, so the name alone cannot say whose it is. */
+    owners: Record<string, string>;
+    /** SDK tool name → the HTTP method of a typed operation. A generic
+     *  call_<api> carries its method in each call's input instead. Read by the
+     *  browser-pod fallback (browser-pod.ts) to tell a GET from a write. */
+    methods: Record<string, string>;
     /** Secrets referenced but not set — surfaced as run warnings. */
     missingSecrets: string[];
     /** Human-readable lines describing each API, appended to the system prompt. */

package/dist/src/api-tools.js

@@ -258,7 +258,7 @@ export function buildApiTools(tenant, apis, workspace,
 // crossed the boundary, and there is no vault in there to ask.
 resolved) {
     if (apis.length === 0) {
-        return { server: null, toolNames: [], missingSecrets: [], promptLines: [], drainLog: () => [] };
+        return { server: null, toolNames: [], owners: {}, methods: {}, missingSecrets: [], promptLines: [], drainLog: () => [] };
     }
     const neededSecrets = [...new Set(apis.flatMap(secretsUsedByApi))];
     const { env, missing } = resolved
@@ -271,23 +271,39 @@ resolved) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the SDK types its own list this way
     const tools = [];
     const toolNames = [];
+    const owners = {};
+    const methods = {};
     const promptLines = [];
     for (const api of apis) {
         // One bucket per API per step: the limit is the vendor's, the scope is
         // this process. Two steps on two workers each get their own.
         const bucket = api.rate ? new TokenBucket(api.rate.count, api.rate.perSec) : null;
         const ops = api.resolvedOperations ?? [];
-        // An explicit `operations:` list means "only these": no escape hatch.
-        const withGeneric = !(api.operations && ops.length);
+        // An explicit `operations:` list means "only these": no escape hatch,
+        // ever. It fails closed. If the document did not load, or yielded none of
+        // the listed operations, the API gets no tools this run rather than the
+        // generic one: an allowlist that opens when a vendor renames an
+        // operation or a URL moves is not an allowlist.
+        const allowlisted = !!api.operations?.length;
+        const withGeneric = !allowlisted;
+        if (allowlisted && !ops.length) {
+            promptLines.push(`- **${api.name}** — unavailable this run: its \`operations:\` allowlist resolved no operations, ` +
+                `so no tool is exposed. Report it as blocked; do not reach this API another way.`);
+            continue;
+        }
         const typedNames = [];
         for (const op of ops) {
             tools.push(typedTool(api, op, env, bucket, log));
             typedNames.push(typedToolName(api.name, op.id));
+            methods[`mcp__foldrun_apis__${typedToolName(api.name, op.id)}`] = String(op.method ?? "").toUpperCase();
         }
         if (withGeneric)
             tools.push(genericTool(api, env, bucket, log));
         const names = [...typedNames, ...(withGeneric ? [`call_${api.name}`] : [])];
-        toolNames.push(...names.map((n) => `mcp__foldrun_apis__${n}`));
+        for (const n of names) {
+            toolNames.push(`mcp__foldrun_apis__${n}`);
+            owners[`mcp__foldrun_apis__${n}`] = api.name;
+        }
         const rateLine = api.rate ? ` Rate limit ${api.rate.count}/${Math.round(api.rate.count / api.rate.perSec)}s — over it, calls wait.` : "";
         if (ops.length) {
             const listed = ops.slice(0, PROMPT_LIST_CAP).map((op) => `  - \`${typedToolName(api.name, op.id)}\` — ${op.summary}`);
@@ -306,6 +322,8 @@ resolved) {
     return {
         server,
         toolNames,
+        owners,
+        methods,
         missingSecrets: missing,
         promptLines,
         drainLog: () => log.splice(0, log.length),

package/dist/src/approvals.d.ts

@@ -1,4 +1,4 @@
-import { type RunRecord } from "./store.ts";
+import { type FlowInfo, type RunRecord } from "./store.ts";
 export interface ApprovalDecision {
     decision: "approve" | "reject";
     /** Guidance for the step being approved — rides the record into its prompt. */
@@ -9,7 +9,97 @@ export interface ApprovalDecision {
     step?: number;
     /** Who decided, as it reads after the verb: "by a human", "via emailed link". */
     by: string;
+    /**
+     * The person behind the decision, when a session made it: their email and
+     * the role they hold. A link and an external event have neither, and are
+     * checked by their token instead — the token IS the authority there.
+     *
+     * Two rules read this. `approvers:` in the flow file names who may decide
+     * that flow's gates at all. And nobody approves a run they started
+     * themselves: a gate exists so that a second person looks, and a flow a
+     * person kicked off and then waved through is a gate that never happened.
+     */
+    actor?: {
+        email?: string | null;
+        role?: string | null;
+    } | null;
+    /**
+     * The emailed link's token, when a link is deciding. Read here rather
+     * than trusted from the route, because what a link may decide is policy:
+     * the step it was minted for, before it expires, once, and never a gate
+     * whose flow names its approvers unless the link was minted for one of
+     * them. See readApproveLink.
+     */
+    link?: string;
 }
+/** How long an emailed link decides for when the flow does not say. */
+export declare const APPROVE_LINK_DEFAULT_TTL_MS: number;
+/** What a link may decide: one step, until a moment, as somebody or as
+ *  nobody. A `run` link is the older kind — bound to the run alone, and
+ *  kept working, once, for runs that were already waiting when this
+ *  changed. */
+export type ApproveLink = {
+    kind: "step";
+    step: number;
+    expiresAt: string;
+    approver: string | null;
+} | {
+    kind: "run";
+};
+/** The link's lifetime: the flow's `approve_within:` when it has one —
+ *  after that the gate has expired on its own — else a week. */
+export declare function approveLinkTtlMs(flow: Pick<FlowInfo, "approveWithin"> | null | undefined): number;
+/**
+ * The token an emailed link carries. Bound to one step of one run and to
+ * a moment, and — when the notification went to a named approver — to
+ * that person, so the link decides as them. A link that was only bound
+ * to the run approved every later gate of that run for as long as it ran,
+ * and a forwarded one let anyone past `approvers:`.
+ *
+ * `step.expires.approver.signature`; the signature covers all of it plus
+ * the run's identity, under the install key, so rotating the key kills
+ * every link at once, the way it kills every hook.
+ */
+export declare function approveLinkToken(tenant: string, workspace: string, runId: string, link: {
+    step: number;
+    expiresAt: number;
+    approver?: string | null;
+}): string;
+/** The path an emailed link opens — absolute when the caller prefixes the
+ *  install's public origin. `decision=reject` pre-selects; a GET never
+ *  decides. */
+export declare function approveLinkPath(tenant: string, workspace: string, runId: string, link: {
+    step: number;
+    expiresAt: number;
+    approver?: string | null;
+}): string;
+/**
+ * What a presented token is, or why it is nothing. 401 for a token that
+ * was never minted for this run, 410 for one that was and has expired —
+ * the second deserves a sentence, because the person holding it did
+ * nothing wrong.
+ */
+export declare function readApproveLink(tenant: string, workspace: string, runId: string, presented: string, now?: number): {
+    link: ApproveLink;
+} | {
+    error: string;
+    status: 401 | 410;
+};
+/**
+ * Everything a link has to pass before it decides anything, answered the
+ * same way for the page that shows the gate and the POST that decides it.
+ * Returns which waiting steps the link may decide and who it decides as.
+ */
+export declare function checkApproveLink(tenant: string, workspace: string, run: RunRecord, presented: string, now?: number): {
+    ok: true;
+    link: ApproveLink;
+    steps: number[];
+    approver: string | null;
+} | {
+    ok: false;
+    status: number;
+    message: string;
+};
 /**
  * Apply a decision to every step the run is waiting on, and line the run up
  * again if a worker had parked it. Returns the record as written and which
@@ -23,6 +113,19 @@ export declare function decideApproval(tenant: string, workspace: string, runId:
     run: RunRecord;
     steps: number[];
 }>;
+/**
+ * A gate that ran out of time. `approve_within:` in the flow file stamps a
+ * deadline when the run parks; past it, the gate is rejected and the run
+ * fails, exactly as if a person had said no.
+ *
+ * Rejection, not approval, is the only safe way for a clock to answer a
+ * question a person was asked. The whole reason the step is parked is that
+ * someone wanted to look at it first.
+ *
+ * Returns whether it acted. Called from the same sweep that closes abandoned
+ * runs, so an expiry needs nothing running of its own.
+ */
+export declare function expireStaleGate(tenant: string, workspace: string, run: RunRecord, now?: number): Promise<boolean>;
 /**
  * Release a run parked on `wait: event` with what arrived. The payload is
  * stored on the step — not as an approval note, which is a person's