@foldrun/core 0.5.0 → 0.7.0

package/dist/src/install-tool.js

@@ -0,0 +1,133 @@
+// The `install` tool: an agent installs what it finds it needs, mid-step,
+// without anyone having declared it. Built in and granted to every agent
+// (take it away with `disallowedTools: [install]`).
+//
+//   install(manager: "apt",  packages: ["ffmpeg"])      — Debian programs and libraries
+//   install(manager: "pip",  packages: ["manim>=0.19"]) — Python packages
+//   install(manager: "npm",  packages: ["sharp"])       — Node packages
+//
+// apt needs root, which the agent never has: it asks the root start-up's
+// install helper over a unix socket (install-helper.ts), which installs only
+// validated names through the same cache and snapshots as `runtime: system:`.
+// pip and npm need no root and run here, as the agent, into a per-step
+// directory already on PATH / PYTHONPATH / NODE_PATH (stepInstallEnv), so the
+// next command finds what this one installed. Inside a run container all of
+// it goes when the container does. Every install is logged with the line to
+// add to the agent's `runtime:` to have it before the step starts next time.
+import fs from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+import { DEB_PACKAGE, PIP_REQUIREMENT, NPM_REQUIREMENT, summarizeInstallFailure } from "./runtime.js";
+export const INSTALL_TOOL = "mcp__foldrun_install__install";
+const PATTERNS = { apt: DEB_PACKAGE, pip: PIP_REQUIREMENT, npm: NPM_REQUIREMENT };
+const RUNTIME_KEY = { apt: "system", pip: "packages", npm: "npm" };
+function findUv() {
+    for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
+        if (dir && fs.existsSync(path.join(dir, "uv")))
+            return path.join(dir, "uv");
+    }
+    return null;
+}
+/** Ask the root helper; resolves with its reply or an error. */
+export function askHelper(socket, packages, timeoutMs = 600_000) {
+    return new Promise((resolve) => {
+        const conn = net.createConnection(socket);
+        let buf = "";
+        const timer = setTimeout(() => {
+            conn.destroy();
+            resolve({ ok: false, error: `the install helper did not answer in ${Math.round(timeoutMs / 1000)}s` });
+        }, timeoutMs);
+        conn.on("connect", () => conn.write(JSON.stringify({ manager: "apt", packages }) + "\n"));
+        conn.on("data", (c) => (buf += c.toString("utf8")));
+        conn.on("end", () => {
+            clearTimeout(timer);
+            try {
+                resolve(JSON.parse(buf.trim()));
+            }
+            catch {
+                resolve({ ok: false, error: "the install helper sent no answer" });
+            }
+        });
+        conn.on("error", (err) => {
+            clearTimeout(timer);
+            resolve({ ok: false, error: `the install helper is not reachable (${err.message})` });
+        });
+    });
+}
+export function buildInstallTool(opts) {
+    const installed = [];
+    const text = (t, isError = false) => ({ content: [{ type: "text", text: t }], ...(isError ? { isError: true } : {}) });
+    const install = tool("install", "Install a program or library this step needs and does not have: Debian packages with manager \"apt\" (ffmpeg, imagemagick, tesseract-ocr, libcairo2-dev, build-essential), Python packages with \"pip\", Node packages with \"npm\". Use this instead of apt-get, pip or npm in Bash — you are not root and those would fail. What you install is usable by your next command (on PATH, importable) and lasts for this step. Name real packages only; versions as the manager writes them (\"pandas>=2\", \"sharp@^0.34\").", {
+        manager: z.enum(["apt", "pip", "npm"]).describe("apt for Debian programs and system libraries, pip for Python, npm for Node"),
+        packages: z.array(z.string()).min(1).max(30).describe("Package names, e.g. [\"ffmpeg\"] or [\"manim\", \"numpy<2\"]"),
+    }, async ({ manager, packages }) => {
+        const names = packages.map((p) => String(p).trim()).filter(Boolean);
+        const bad = names.filter((p) => !PATTERNS[manager].test(p));
+        if (bad.length)
+            return text(`Not ${manager} package names: ${bad.join(", ")}. Nothing was installed.`, true);
+        const t0 = Date.now();
+        let how = "";
+        if (manager === "apt") {
+            if (!opts.socket || !fs.existsSync(opts.socket)) {
+                return text("Debian packages can only be installed inside a run container, and this step is not running in one. Nothing was installed.", true);
+            }
+            const r = await askHelper(opts.socket, names);
+            if (!r.ok) {
+                opts.emit("error", `install: apt ${names.join(" ")} — ${String(r.error).split("\n")[0]}`);
+                return text(r.error ?? "apt failed", true);
+            }
+            how = `${r.mode ?? "apt"}, ${r.seconds ?? Math.round((Date.now() - t0) / 1000)}s`;
+        }
+        else if (manager === "pip") {
+            const target = path.join(opts.dir, "py");
+            fs.mkdirSync(target, { recursive: true });
+            const uv = findUv();
+            const res = uv
+                ? spawnSync(uv, ["pip", "install", "-q", "--python", opts.python, "--target", target, ...names], {
+                    env: { ...opts.env, UV_CACHE_DIR: path.join(opts.cacheRoot, ".uv-cache"), UV_LINK_MODE: "copy", UV_NO_PROGRESS: "1" },
+                    encoding: "utf8",
+                    timeout: 600_000,
+                })
+                : spawnSync(opts.python, ["-m", "pip", "install", "-q", "--disable-pip-version-check", "--target", target, ...names], {
+                    env: opts.env,
+                    encoding: "utf8",
+                    timeout: 600_000,
+                });
+            if (res.status !== 0) {
+                const msg = summarizeInstallFailure(uv ? "uv pip install" : "pip install", `${res.stdout ?? ""}${res.stderr ?? ""}${res.error ? res.error.message : ""}`);
+                opts.emit("error", `install: pip ${names.join(" ")} — ${msg.split("\n")[0]}`);
+                return text(msg, true);
+            }
+            how = `pip, ${Math.round((Date.now() - t0) / 1000)}s`;
+        }
+        else {
+            const prefix = path.join(opts.dir, "npm");
+            fs.mkdirSync(prefix, { recursive: true });
+            const res = spawnSync("npm", ["install", "--no-fund", "--no-audit", "--no-progress", "--prefix", prefix, ...names], {
+                env: { ...opts.env, npm_config_cache: path.join(opts.cacheRoot, ".npm-cache") },
+                encoding: "utf8",
+                timeout: 600_000,
+            });
+            if (res.status !== 0) {
+                const msg = summarizeInstallFailure("npm install", `${res.stdout ?? ""}${res.stderr ?? ""}${res.error ? res.error.message : ""}`);
+                opts.emit("error", `install: npm ${names.join(" ")} — ${msg.split("\n")[0]}`);
+                return text(msg, true);
+            }
+            how = `npm, ${Math.round((Date.now() - t0) / 1000)}s`;
+        }
+        installed.push(...names.map((n) => `${manager}:${n}`));
+        opts.emit("info", `install: ${manager} ${names.join(" ")} — ready (${how}). To have it before the step starts: runtime: ${RUNTIME_KEY[manager]}: [${names.join(", ")}]`);
+        return text(`Installed ${names.join(", ")} (${manager}). Usable now in this step — run it or import it directly.`);
+    });
+    return {
+        server: createSdkMcpServer({ name: "foldrun_install", version: "1.0.0", tools: [install] }),
+        toolName: INSTALL_TOOL,
+        /** What this step installed, `manager:name`, for the run record. */
+        installed: () => [...installed],
+        /** The handler, for tests. */
+        call: (args) => install.handler(args, {}),
+    };
+}

package/dist/src/mail.js

@@ -125,7 +125,9 @@ export function readUnsubscribeToken(token, now = Date.now()) {
     if (!payload || !sig || extra !== undefined)
         return { error: "invalid token", status: 401 };
     const want = sign(payload);
-    if (sig.length !== want.length || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(want))) {
+    // Only base64url reaches the compare: a multibyte character would make the
+    // byte buffers differ in length, and timingSafeEqual throws on that.
+    if (!/^[A-Za-z0-9_-]+$/.test(sig) || sig.length !== want.length || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(want))) {
         return { error: "invalid token", status: 401 };
     }
     let raw;

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

@@ -0,0 +1,30 @@
+export type ModelCredentialKind = "api-key" | "auth-token" | "claude-login" | "none";
+export interface ModelCredential {
+    kind: ModelCredentialKind;
+    /** What the run record and the CLI say: which credential, by its variable. */
+    label: string;
+    /** The variables the step's Claude Code is started with. */
+    env: Record<string, string>;
+}
+export declare function resolveModelCredential(source?: Record<string, string | undefined>): ModelCredential;
+/** The line a step's trail carries, and what goes wrong when there is none. */
+export declare function credentialLine(c: ModelCredential): {
+    type: "info" | "error";
+    text: string;
+};
+/** The account vault names the account's own model key lives under. */
+export declare const ACCOUNT_MODEL_SECRETS: {
+    readonly provider: "FOLDRUN_MODEL_PROVIDER";
+    readonly key: "FOLDRUN_MODEL_API_KEY";
+    readonly baseUrl: "FOLDRUN_MODEL_BASE_URL";
+    readonly format: "FOLDRUN_MODEL_FORMAT";
+};
+/** A provider: block built from the account's own model secrets, or
+ *  undefined when it has set no key. `read` is the account-scope secret
+ *  reader (getSecret without a workspace). */
+export declare function accountModelBlock(read: (name: string) => string | null): Record<string, unknown> | undefined;
+/** A Claude login token (`claude setup-token`, sk-ant-oat…), not an API key.
+ *  Anthropic's terms do not let a third-party product run customers on
+ *  claude.ai logins, so on a hosted platform only the operator's own
+ *  accounts may; a customer's key must be an API key. */
+export declare function isClaudeLoginToken(value: string | null | undefined): boolean;

package/dist/src/model-credential.js

@@ -0,0 +1,98 @@
+// Which Anthropic credential a step runs on, decided once and said on the
+// record — never whatever happens to be signed in on the machine.
+//
+// In order: an API key (ANTHROPIC_API_KEY), a bearer for a gateway
+// (ANTHROPIC_AUTH_TOKEN), then a Claude login token (CLAUDE_CODE_OAUTH_TOKEN,
+// made by `claude setup-token`). Before this, an in-process step was handed
+// none of them — the host allowlist drops credentials — so Claude Code fell
+// back to the machine's own claude.ai login whatever key was set: a key the
+// CLI insisted on was checked and then ignored.
+//
+// Note on terms: Anthropic does not allow third-party products built on the
+// Agent SDK to offer claude.ai login unless Anthropic has approved it. The
+// login token is accepted here because the account owner chose to support
+// it; offering it to customers needs that approval.
+//
+// What an agent's own shell sees: Claude Code keeps CLAUDE_CODE_OAUTH_TOKEN
+// out of its Bash by itself; an API key is visible there, as it is when you
+// run Claude Code with one in your shell. Its scrub switch
+// (CLAUDE_CODE_SUBPROCESS_ENV_SCRUB) is not used: it also strips the agent's
+// own declared secrets (RESEND_API_KEY, DATAFORSEO_PASSWORD) from Bash, and on
+// Linux it refuses to start without bubblewrap. Script tools and shell
+// `verify:` never see any of these: they start from the host allowlist.
+const set = (v) => typeof v === "string" && v.trim() !== "";
+export function resolveModelCredential(source = process.env) {
+    const base = set(source.ANTHROPIC_BASE_URL) ? { ANTHROPIC_BASE_URL: source.ANTHROPIC_BASE_URL } : {};
+    if (set(source.ANTHROPIC_API_KEY)) {
+        return {
+            kind: "api-key",
+            label: "API key (ANTHROPIC_API_KEY)",
+            env: { ...base, ANTHROPIC_API_KEY: source.ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN: "" },
+        };
+    }
+    if (set(source.ANTHROPIC_AUTH_TOKEN)) {
+        return {
+            kind: "auth-token",
+            label: `bearer token (ANTHROPIC_AUTH_TOKEN)${base.ANTHROPIC_BASE_URL ? ` to ${base.ANTHROPIC_BASE_URL}` : ""}`,
+            env: { ...base, ANTHROPIC_AUTH_TOKEN: source.ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY: "", CLAUDE_CODE_OAUTH_TOKEN: "" },
+        };
+    }
+    if (set(source.CLAUDE_CODE_OAUTH_TOKEN)) {
+        return {
+            kind: "claude-login",
+            label: "Claude login token (CLAUDE_CODE_OAUTH_TOKEN)",
+            env: { ...base, CLAUDE_CODE_OAUTH_TOKEN: source.CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY: "" },
+        };
+    }
+    return { kind: "none", label: "none set", env: {} };
+}
+/** The line a step's trail carries, and what goes wrong when there is none. */
+export function credentialLine(c) {
+    if (c.kind !== "none")
+        return { type: "info", text: `model credential: ${c.label}` };
+    return {
+        type: "error",
+        text: "model credential: none set — Claude Code will fall back to whatever login this machine has, if any. " +
+            "Set ANTHROPIC_API_KEY, or CLAUDE_CODE_OAUTH_TOKEN from `claude setup-token`",
+    };
+}
+// ---------------------------------------------------------------- the account's own key
+//
+// An account brings its own model key without writing a provider: block:
+// three secrets in the ACCOUNT vault (set from Settings → Model, the API's
+// /api/account/model, or `foldrun model set`). A provider: block at any
+// level still wins; this is what a step falls to when none names one, before
+// the platform's own credential.
+/** The account vault names the account's own model key lives under. */
+export const ACCOUNT_MODEL_SECRETS = {
+    provider: "FOLDRUN_MODEL_PROVIDER",
+    key: "FOLDRUN_MODEL_API_KEY",
+    baseUrl: "FOLDRUN_MODEL_BASE_URL",
+    format: "FOLDRUN_MODEL_FORMAT",
+};
+/** A provider: block built from the account's own model secrets, or
+ *  undefined when it has set no key. `read` is the account-scope secret
+ *  reader (getSecret without a workspace). */
+export function accountModelBlock(read) {
+    const key = read(ACCOUNT_MODEL_SECRETS.key);
+    if (!key)
+        return undefined;
+    const block = { token: `\${${ACCOUNT_MODEL_SECRETS.key}}` };
+    const name = read(ACCOUNT_MODEL_SECRETS.provider);
+    const baseUrl = read(ACCOUNT_MODEL_SECRETS.baseUrl);
+    const format = read(ACCOUNT_MODEL_SECRETS.format);
+    if (name)
+        block.name = name;
+    if (baseUrl)
+        block.base_url = baseUrl;
+    if (format)
+        block.format = format;
+    return block;
+}
+/** A Claude login token (`claude setup-token`, sk-ant-oat…), not an API key.
+ *  Anthropic's terms do not let a third-party product run customers on
+ *  claude.ai logins, so on a hosted platform only the operator's own
+ *  accounts may; a customer's key must be an API key. */
+export function isClaudeLoginToken(value) {
+    return typeof value === "string" && /^sk-ant-oat\d*-/.test(value.trim());
+}

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

@@ -0,0 +1,17 @@
+/** Refused for want of a usable key; `status` is what an HTTP layer answers. */
+export declare class ModelKeyError extends Error {
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+export declare const NO_MODEL_KEY: string;
+/**
+ * `platform` is a function: the caller's own way to build the platform's env
+ * (a step's, or the SDK's host env), called only when this account may use
+ * it. `format` says what the endpoint speaks — a caller with no translator
+ * refuses anything but anthropic.
+ */
+export declare function accountModelEnv(tenant: string, workspace: string, platformEnv: () => Record<string, string | undefined>): {
+    env: Record<string, string | undefined>;
+    supply: "provider" | "platform";
+    format: string;
+};

package/dist/src/model-env.js

@@ -0,0 +1,57 @@
+// The model environment for work an ACCOUNT asks for outside a step: an eval's
+// judge, the dashboard's "draft a flow with AI". Resolved the way a step
+// resolves it — the workspace's provider: block, else the account's, else the
+// account's own key from Settings → Model — and only then the platform's own
+// credential, which a hosted platform keeps for its operator's accounts
+// (platform.platformKeyAllowed). Every other account brings an API key;
+// asking for the platform's here is refused, not quietly billed to it.
+import { accountDir, workspaceDir, parseProvider, providerEnvFor } from "./store.js";
+import { readAgentsMd } from "./runner.js";
+import { getSecret } from "./secrets.js";
+import { platform } from "./platform.js";
+import { accountModelBlock, isClaudeLoginToken } from "./model-credential.js";
+/** Refused for want of a usable key; `status` is what an HTTP layer answers. */
+export class ModelKeyError extends Error {
+    status;
+    constructor(message, status = 402) {
+        super(message);
+        this.status = status;
+    }
+}
+export const NO_MODEL_KEY = "no model key: this account runs on its own API key, and none is set — add one in Settings → Model " +
+    "(or `foldrun model set <provider> --key …`), or write a provider: block in AGENTS.md";
+/**
+ * `platform` is a function: the caller's own way to build the platform's env
+ * (a step's, or the SDK's host env), called only when this account may use
+ * it. `format` says what the endpoint speaks — a caller with no translator
+ * refuses anything but anthropic.
+ */
+export function accountModelEnv(tenant, workspace, platformEnv) {
+    const raw = readAgentsMd(workspaceDir(tenant, workspace))?.data?.provider ??
+        readAgentsMd(accountDir(tenant))?.data?.provider ??
+        accountModelBlock((name) => getSecret(tenant, name)?.value ?? null);
+    const spec = parseProvider(raw);
+    if (!spec?.baseUrl) {
+        if (!platform.platformKeyAllowed(tenant))
+            throw new ModelKeyError(NO_MODEL_KEY);
+        return { env: platformEnv(), supply: "platform", format: "anthropic" };
+    }
+    const sub = (text) => text.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (whole, name) => getSecret(tenant, name, workspace)?.value ?? whole);
+    const token = sub(spec.token);
+    if (token.includes("${"))
+        throw new ModelKeyError("the provider's token secret is not set — `foldrun secrets` sets it", 422);
+    if (!platform.platformKeyAllowed(tenant) && isClaudeLoginToken(token)) {
+        throw new ModelKeyError("model key: a Claude login token (sk-ant-oat…) cannot be used here — use an API key from your provider", 422);
+    }
+    return {
+        env: providerEnvFor({
+            baseUrl: spec.baseUrl,
+            token,
+            auth: spec.auth,
+            models: spec.models,
+            headers: Object.fromEntries(Object.entries(spec.headers).map(([k, v]) => [k, sub(v)])),
+        }),
+        supply: "provider",
+        format: spec.format,
+    };
+}

package/dist/src/package.d.ts

@@ -0,0 +1,67 @@
+import { type DeployFile } from "./store.ts";
+export type PackageKind = "workspace" | "flow" | "agent";
+export interface PackageManifest {
+    format: "foldrun-package";
+    version: 1;
+    kind: PackageKind;
+    /** The workspace's, flow's or agent's name. */
+    name: string;
+    /** The workspace it was exported from. */
+    workspace: string;
+    exportedAt: string;
+    files: string[];
+}
+export interface Package {
+    manifest: PackageManifest;
+    files: DeployFile[];
+    /** Entries in the zip that are not authored source, left out (readPackage). */
+    skipped?: string[];
+}
+/** An error the API layer turns into a status rather than a 500. */
+export declare class PackageError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export declare const MANIFEST_FILE = "foldrun-package.json";
+export declare function isPackagedPath(rel: string): boolean;
+export declare function packageOf(tenant: string, workspace: string, kind: PackageKind, name?: string): Package;
+export declare function packageZip(pkg: Package): Buffer;
+/** What the download is called: `<workspace>.zip`, `<workspace>-flow-<name>.zip`. */
+export declare function packageFilename(m: PackageManifest): string;
+export declare function readPackage(buf: Buffer): Package;
+export interface ImportPlan {
+    kind: PackageKind;
+    name: string;
+    /** Where it came from, as the package says. */
+    from: string;
+    workspace: string;
+    /** True when the workspace does not exist yet and the import makes it. */
+    creates: boolean;
+    added: string[];
+    /** Files that exist with different text — written only with `overwrite`. */
+    overwritten: string[];
+    unchanged: string[];
+    /** In the zip, not written: memory, state, .gitignore, anything outside
+     *  the authored folders. */
+    skipped: string[];
+    /** What the imported files name that the target cannot provide. The import
+     *  still happens — a missing secret is set in a minute. */
+    needs: {
+        secrets: string[];
+        tools: string[];
+        skills: string[];
+        scripts: string[];
+        agents: string[];
+        flows: string[];
+    };
+}
+export interface ImportResult extends ImportPlan {
+    written: string[];
+    revision: string | null;
+}
+export declare function planImport(tenant: string, workspace: string, pkg: Package): ImportPlan;
+export declare function applyImport(tenant: string, workspace: string, pkg: Package, opts?: {
+    overwrite?: boolean;
+    by?: string;
+    expect?: "create" | "merge";
+}): ImportResult;