@foldrun/core 0.4.0 → 0.6.0

package/README.md

@@ -208,16 +208,19 @@ To *run* an agent you need one of:
 
 - **`ANTHROPIC_API_KEY`** — an API key from
   [console.anthropic.com](https://console.anthropic.com).
+- **`CLAUDE_CODE_OAUTH_TOKEN`** — a Claude login token, from
+  `claude setup-token`. Used when no API key is set.
 - **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.
+The first one set is used, and every step records which. The login Claude
+Code keeps on the machine is never picked up by itself. Anthropic does not
+allow products built on its Agent SDK to offer claude.ai login unless
+Anthropic has approved them, so check that the terms cover your use before
+you rely on a login token.
 
 ## Status
 

package/dist/index.d.ts

@@ -1,5 +1,7 @@
+export * from "./src/layout.ts";
 export * from "./src/paths.ts";
 export * from "./src/store.ts";
+export * from "./src/model-credential.ts";
 export * from "./src/starter.ts";
 export * from "./src/runner.ts";
 export * from "./src/okf.ts";
@@ -10,6 +12,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 +31,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,8 +9,10 @@
 // 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/model-credential.js";
 export * from "./src/starter.js";
 export * from "./src/runner.js";
 export * from "./src/okf.js";
@@ -21,6 +23,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 +42,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/browser-pod.d.ts

@@ -0,0 +1,148 @@
+/** Set by the platform on a step it put on the slim image to browse
+ *  through the pod. The web tool then never launches a browser of its own. */
+export declare const POD_ONLY_ENV = "FOLDRUN_BROWSER_POD_ONLY";
+/** Where the web tool appends one JSON line per reconnect, and the line
+ *  that says the pod is lost or the call needs the full image. */
+export declare const POD_EVENTS_ENV = "FOLDRUN_BROWSER_POD_EVENTS";
+/** The file, inside the step's sandbox. */
+export declare const POD_EVENTS_FILE = "/tmp/foldrun-browser-pod.jsonl";
+/** The note the run carries when the fallback was taken. Worded once. */
+export declare const RERAN_ON_FULL = "browser pod lost; re-ran on full";
+/**
+ * Browse actions that can change something beyond the page in front of the
+ * model: anything that types, picks, submits, signs in, uploads, runs script
+ * or pays. A click is here because a click can submit and nothing before
+ * the click can tell. The web tool's run.mjs carries a copy (it decides
+ * whether a dropped call may be repeated); the gallery test holds the two
+ * equal.
+ */
+export declare const BROWSE_WRITE_ACTIONS: readonly ["click", "dblclick", "rightclick", "tap", "swipe", "mouse", "drag", "fill", "type", "insert", "paste", "press", "keyboard", "keydown", "keyup", "clear", "select", "check", "uncheck", "upload", "dialog", "login", "eval", "webmcp", "solve"];
+export type CallKind = {
+    write: false;
+} | {
+    write: true;
+    what: string;
+};
+export interface ClassifyContext {
+    /** SDK tool name → HTTP method, for an API's typed operations (api-tools
+     *  builds the map; a generic call_<api> carries its method in the input). */
+    methods?: Record<string, string>;
+    /** Web actions a paid provider answers this step — from the env's
+     *  FOLDRUN_WEB_<ACTION>_VIA. */
+    paidWeb?: Record<string, string>;
+    /** Page scripts the agent's web.browse block runs in every page — the
+     *  env's FOLDRUN_BROWSER_INIT. They make every browse call a write. */
+    browseInit?: string;
+}
+/**
+ * The browse actions a call asked for, nested `if` branches included.
+ *
+ * Read the way the web tool reads them (platform gallery.ts, browse.mjs
+ * checkSteps): `actions` is an array of steps, a step's action is one of its
+ * OWN keys (the first the tool knows), and the only steps inside a step are
+ * an `if`'s `then` and `else`. Every own key of a step is returned — the
+ * caller keeps the ones it cares about, and a step holding a write key beside
+ * a read key counts as the write. What sits inside an option's value — an
+ * extract's `fields` (column names), a mock's `json` body, a webmcp `input` —
+ * is data, not an action: `{"fields": {"type": "td.kind"}}` is no typing.
+ *
+ * A shape the tool would refuse (an object where the array belongs, a step
+ * that is not an object, `then` that is not a list) is walked key by key at
+ * every depth, as before; nesting past MAX_DEPTH is unreadable, so a write
+ * buried deep is never taken for a read.
+ */
+export declare function browseActionNames(actions: unknown): string[];
+/** What a browse call's arguments would write, or null when it only reads. */
+export declare function browseWrites(input: Record<string, unknown>): string | null;
+/**
+ * Whether one tool call can have changed anything outside the model's head,
+ * and if so, a few words saying what. Pure.
+ */
+export declare function classifyCall(tool: string, input: Record<string, unknown> | undefined, ctx?: ClassifyContext): CallKind;
+/** Paid web actions, from a step's env (FOLDRUN_WEB_<ACTION>_VIA=provider). */
+export declare function paidWebActions(env: Record<string, string | undefined>): Record<string, string>;
+/** One line of the web tool's pod log. */
+export interface PodEvent {
+    kind: "reconnect" | "lost" | "needs-full";
+    /** reconnect: which try, of how many, and whether it got through. */
+    attempt?: number;
+    of?: number;
+    ok?: boolean;
+    /** lost: whether the call ran on the pod at all before it was lost — a
+     *  call that never connected changed nothing, whatever it asked for. */
+    ran?: boolean;
+    error?: string;
+    why?: string;
+    /** When the web tool wrote the line (ISO). */
+    at?: string;
+}
+/** ", at 10:15:15Z" from a pod log line's `at`; empty when it has none. */
+export declare function podAt(at: unknown): string;
+/** Lines of the pod log from byte `offset` on, and where the next read
+ *  starts. A torn last line waits for the next read. */
+export declare function readPodEvents(text: string, offset: number): {
+    events: PodEvent[];
+    next: number;
+};
+/** What crosses back from a step that browsed through the pod. */
+export interface BrowserPodOutcome {
+    /** Reconnect tries the web tool made, and how many got through: the pod
+     *  answered and the call went on, rather than dropping again at once. */
+    reconnects: number;
+    reconnected: number;
+    /** Reconnects that reached the pod, after which the call dropped again at
+     *  once — a pod still answering while it shut down. Never "got through". */
+    closedAgain?: number;
+    /** Set when the step stopped because the pod was gone (or a call needed
+     *  a browser in the step, which slim does not have). */
+    lost?: {
+        cause: "lost" | "needs-full";
+        detail: string;
+    };
+    /** What the step had written by then, worded — empty means reads only. */
+    writes?: string[];
+}
+/** "a.md (Write), crm POST and 2 more". */
+export declare function describeWrites(writes: string[]): string;
+/** The decision, once the pod is gone: re-run on full, or fail and say why. */
+export declare function podLossDecision(pod: BrowserPodOutcome): {
+    rerun: true;
+    note: string;
+} | {
+    rerun: false;
+    message: string;
+};
+/**
+ * Why a browsing step must have a browser in its own sandbox, from what the
+ * step start can see (the agent's `web.browse` block, as env), or null when
+ * the account's pod can serve every call it could make by default. A call
+ * that picks an in-step engine itself is caught at the call (needs-full).
+ */
+export declare function slimBrowseBlocker(env: Record<string, string | undefined>): string | null;
+/** The outcome as it crosses back from the sandbox, checked field by field
+ *  (the done line is the pod's word); null when absent or not this shape. */
+export declare function parseBrowserPod(v: unknown): BrowserPodOutcome | null;
+/** One line for a person: "2 reconnects (2 got through)", "browser pod
+ *  lost; re-ran on full", or the failure. What the run page, `foldrun
+ *  report` and an attempt row say. A pod that was lost in the end is never
+ *  said to have let a reconnect through — "1 reconnect (1 got through); pod
+ *  lost" read live as a contradiction — and a reconnect that reached the pod
+ *  only for the call to drop again says that. */
+export declare function browserPodLine(p: BrowserPodOutcome & {
+    fallback?: string;
+    failure?: string;
+}): string;
+/** What podTriesLine reads of a StepAttempt (store.ts) — structural, so
+ *  this module stays free of the store's imports for the CLI and the web. */
+export interface TryRow {
+    n: number;
+    status: string;
+    image?: string;
+    costUsd: number | null;
+}
+/** A step's tries in one line when the browser pod was lost under one of
+ *  them — "slim · lost · $0.0040 → full · completed · $0.0060" — so the run
+ *  page and `foldrun report` show the slim go and the full re-run apart.
+ *  `#n` leads each try when the step had more than one attempt. Null when
+ *  no try was lost. */
+export declare function podTriesLine(tries: readonly TryRow[] | null | undefined): string | null;