@foldrun/core 0.6.0 → 1.0.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/kinds.ts

@@ -44,6 +44,7 @@ export type Kind =
   | "flows"
   | "evals"
   | "tools"
+  | "hooks"
   | "skills"
   | "memory"
   | "knowledge"
@@ -192,6 +193,33 @@ Notes for whoever maintains this. Agents opt in with:
 \`\`\`yaml
 tools: [${name}]
 \`\`\`
+`,
+  },
+
+  hooks: {
+    kind: "hooks",
+    one: "hook",
+    docType: null,
+    docKey: null,
+    // Turned on per agent (`hooks:`), or for every agent from an AGENTS.md;
+    // shared ones live in the account library.
+    scopes: ["account", "workspace"],
+    placeholder: "no-force-push",
+    hint: "Your code at every tool call, step start or step end — on every model. Folder: hook.md and run.mjs.",
+    file: (name) => `hooks/${name}/hook.md`,
+    template: (name) => `---
+name: ${name}
+on: tool.call
+tool: Bash
+description: What this hook guards, in one line.
+---
+
+# ${name}
+
+What it refuses or rewrites, and why. The code is run.mjs beside this file:
+it reads the event as JSON on stdin and prints one JSON answer —
+{"decision": "deny", "reason": "..."} to refuse, {"input": {...}} to rewrite,
+{} to let the call through. A hook that fails refuses the call.
 `,
   },
   // Last, and not navigable: a folder tool holds its own code, so scripts

package/src/library.ts

@@ -32,12 +32,12 @@ import {
 } from "./store.ts";
 
 
-export type LibraryKind = "skills" | "scripts" | "memory" | "knowledge" | "tools";
+export type LibraryKind = "skills" | "scripts" | "memory" | "knowledge" | "tools" | "hooks";
 // Same order as the workspace nav and asset pages — one list, one order.
 // Order matters and is asserted: it is the order every noun list in the
 // product uses. Tools then scripts, because a script is material a tool
 // points at — see the KINDS table, which is where the order is declared.
-export const LIBRARY_KINDS: LibraryKind[] = ["tools", "knowledge", "memory", "skills", "scripts"];
+export const LIBRARY_KINDS: LibraryKind[] = ["tools", "hooks", "knowledge", "memory", "skills", "scripts"];
 
 export function libraryDir(tenant: string, kind?: LibraryKind) {
   // Alongside the workspace in single-workspace mode: ./library, so a shared
@@ -159,6 +159,22 @@ export function listLibrary(tenant: string, kind: LibraryKind): LibraryEntry[] {
     return out.sort((a, b) => a.path.localeCompare(b.path));
   }
 
+  // A hook is a folder: hook.md says when it runs, run.mjs is the code.
+  if (kind === "hooks") {
+    for (const entry of fs.readdirSync(dir).sort()) {
+      const full = path.join(dir, entry);
+      const hookMd = path.join(full, "hook.md");
+      if (!fs.statSync(full).isDirectory() || !fs.existsSync(hookMd)) continue;
+      out.push({
+        ...describe(hookMd, entry),
+        path: `${entry}/hook.md`,
+        files: folderFiles(full, entry),
+        updatedAt: fs.statSync(hookMd).mtime.toISOString(),
+      });
+    }
+    return out;
+  }
+
   if (kind === "skills") {
     for (const entry of fs.readdirSync(dir).sort()) {
       const full = path.join(dir, entry);

package/src/mail.ts

@@ -81,7 +81,7 @@ export const MAIL_CATEGORIES: readonly MailCategoryInfo[] = [
     label: "Account notices",
     required: true,
     perWorkspace: false,
-    description: "Something about the account stopped working on its own — a notification webhook switched off after days of failures, a close request.",
+    description: "Something about the account stopped working on its own, or is about to — a notification webhook switched off after days of failures, a close request, an API route it still calls being switched off.",
     why: "each one is the only message saying a thing you rely on has stopped",
   },
   {

package/src/model-credential.ts

@@ -69,3 +69,44 @@ export function credentialLine(c: ModelCredential): { type: "info" | "error"; te
       "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,
+  };
+}

package/src/notify.ts

@@ -137,6 +137,15 @@ export function notifyConfig(tenant: string, workspace: string): NotifyConfig |
 // line per parked run would bury the failures around it.
 let warnedNoPublicUrl = false;
 
+/**
+ * The version of the webhook body's shape, sent on every delivery as
+ * `x-foldrun-webhook-version` (and in the user agent). Within a version the
+ * body only gains fields — a receiver must ignore the ones it does not know.
+ * A field removed, renamed or retyped is a new version, announced in What's
+ * new at least six months before the old shape stops being sent.
+ */
+export const WEBHOOK_PAYLOAD_VERSION = 1;
+
 /**
  * The headers that prove a delivery came from this install.
  *
@@ -252,7 +261,8 @@ export async function attemptWebhook(
       method: "POST",
       headers: {
         "content-type": "application/json",
-        "user-agent": "foldrun-webhooks/1",
+        "user-agent": `foldrun-webhooks/${WEBHOOK_PAYLOAD_VERSION}`,
+        "x-foldrun-webhook-version": String(WEBHOOK_PAYLOAD_VERSION),
         "x-foldrun-delivery": d.id,
         "x-foldrun-event": d.event,
         "x-foldrun-attempt": String(d.attempt),