@foldrun/core 0.5.0 → 0.7.0

package/src/install-tool.ts

@@ -0,0 +1,154 @@
+// 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.ts";
+
+type Emit = (type: "text" | "tool" | "info" | "error", text: string) => void;
+
+export const INSTALL_TOOL = "mcp__foldrun_install__install";
+
+const PATTERNS = { apt: DEB_PACKAGE, pip: PIP_REQUIREMENT, npm: NPM_REQUIREMENT } as const;
+const RUNTIME_KEY = { apt: "system", pip: "packages", npm: "npm" } as const;
+
+function findUv(): string | null {
+  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: string, packages: string[], timeoutMs = 600_000): Promise<{ ok: boolean; mode?: string; seconds?: number; error?: string }> {
+  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: {
+  /** The per-step directory pip and npm install into (stepInstallEnv's). */
+  dir: string;
+  /** The root helper's socket; null where there is none (a laptop). */
+  socket: string | null;
+  /** The account's runtime cache, for uv's and npm's download caches. */
+  cacheRoot: string;
+  /** The interpreter pip installs for: the declared venv's, else python3. */
+  python: string;
+  env: Record<string, string | undefined>;
+  emit: Emit;
+}) {
+  const installed: string[] = [];
+  const text = (t: string, isError = false) => ({ content: [{ type: "text" as const, 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" } as unknown as NodeJS.ProcessEnv,
+              encoding: "utf8",
+              timeout: 600_000,
+            })
+          : spawnSync(opts.python, ["-m", "pip", "install", "-q", "--disable-pip-version-check", "--target", target, ...names], {
+              env: opts.env as unknown as NodeJS.ProcessEnv,
+              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") } as unknown as NodeJS.ProcessEnv,
+          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: { manager: "apt" | "pip" | "npm"; packages: string[] }) => install.handler(args, {}),
+  };
+}

package/src/mail.ts

@@ -168,7 +168,9 @@ export function readUnsubscribeToken(
   const [payload, sig, extra] = token.split(".");
   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: { t?: unknown; e?: unknown; c?: unknown; w?: unknown; x?: unknown };

package/src/model-credential.ts

@@ -0,0 +1,112 @@
+// 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.
+
+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>;
+}
+
+const set = (v: string | undefined) => typeof v === "string" && v.trim() !== "";
+
+export function resolveModelCredential(source: Record<string, string | undefined> = process.env): ModelCredential {
+  const base: Record<string, string> = 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: ModelCredential): { type: "info" | "error"; text: string } {
+  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",
+} as const;
+
+/** 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: (name: string) => string | null): Record<string, unknown> | undefined {
+  const key = read(ACCOUNT_MODEL_SECRETS.key);
+  if (!key) return undefined;
+  const block: Record<string, unknown> = { 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: string | null | undefined): boolean {
+  return typeof value === "string" && /^sk-ant-oat\d*-/.test(value.trim());
+}

package/src/model-env.ts

@@ -0,0 +1,66 @@
+// 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.ts";
+import { readAgentsMd } from "./runner.ts";
+import { getSecret } from "./secrets.ts";
+import { platform } from "./platform.ts";
+import { accountModelBlock, isClaudeLoginToken } from "./model-credential.ts";
+
+/** Refused for want of a usable key; `status` is what an HTTP layer answers. */
+export class ModelKeyError extends Error {
+  readonly status: number;
+  constructor(message: string, 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: string,
+  workspace: string,
+  platformEnv: () => Record<string, string | undefined>,
+): { env: Record<string, string | undefined>; supply: "provider" | "platform"; format: string } {
+  const raw =
+    (readAgentsMd(workspaceDir(tenant, workspace))?.data?.provider as Record<string, unknown> | undefined) ??
+    (readAgentsMd(accountDir(tenant))?.data?.provider as Record<string, unknown> | undefined) ??
+    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: string) =>
+    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,
+  };
+}