@foldrun/core 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Agents are just folders. The format, the runner, the checks.",
   "license": "Apache-2.0",
   "type": "module",

package/src/browser-pod.ts

@@ -48,8 +48,9 @@ export const BROWSE_WRITE_ACTIONS = [
 ] as const;
 
 /** Call arguments of web action=browse that are writes whatever the actions:
- *  page script, a paid captcha solver, a confirmation of a credential step. */
-const BROWSE_WRITE_ARGS = ["js", "captcha", "captcha_solver", "confirm"];
+ *  page script (js=, or init= scripts run in every page), a paid captcha
+ *  solver, a confirmation of a credential step. */
+const BROWSE_WRITE_ARGS = ["js", "init", "captcha", "captcha_solver", "confirm"];
 
 /** Web actions that only read — when foldrun's own answers them. A paid
  *  provider answering one (FOLDRUN_WEB_<ACTION>_VIA) makes it a write: doing
@@ -72,24 +73,59 @@ export interface ClassifyContext {
   /** 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. */
+/**
+ * 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 function browseActionNames(actions: unknown): string[] {
+  const UNREADABLE = "(unreadable actions)";
+  const MAX_DEPTH = 32;
   let steps: unknown = actions;
   if (typeof steps === "string") {
-    try { steps = JSON.parse(steps); } catch { return ["(unreadable actions)"]; }
+    try { steps = JSON.parse(steps); } catch { return [UNREADABLE]; }
   }
   const out: string[] = [];
-  const walk = (v: unknown, depth: number) => {
-    if (depth > 8 || v === null || typeof v !== "object") return;
-    if (Array.isArray(v)) { for (const x of v) walk(x, depth + 1); return; }
+  // Unknown shapes: every key anywhere is a candidate action.
+  const walkAny = (v: unknown, depth: number) => {
+    if (v === null || typeof v !== "object") return;
+    if (depth > MAX_DEPTH) { out.push(UNREADABLE); return; }
+    if (Array.isArray(v)) { for (const x of v) walkAny(x, depth + 1); return; }
     for (const [k, x] of Object.entries(v as Record<string, unknown>)) {
       out.push(k);
-      walk(x, depth + 1);
+      walkAny(x, depth + 1);
+    }
+  };
+  const walkSteps = (v: unknown, depth: number) => {
+    if (v === null || v === undefined) return;
+    if (depth > MAX_DEPTH) { out.push(UNREADABLE); return; }
+    if (!Array.isArray(v)) { walkAny(v, depth); return; }
+    for (const step of v) {
+      if (step === null || typeof step !== "object" || Array.isArray(step)) { walkAny(step, depth + 1); continue; }
+      for (const [k, x] of Object.entries(step as Record<string, unknown>)) {
+        out.push(k);
+        if (k === "then" || k === "else") walkSteps(x, depth + 1);
+      }
     }
   };
-  walk(steps, 0);
+  walkSteps(steps, 0);
   return out;
 }
 
@@ -132,6 +168,7 @@ export function classifyCall(tool: string, input: Record<string, unknown> | unde
     if (action === "browse") {
       const w = browseWrites(args);
       if (w) return write(w);
+      if (ctx.browseInit) return write(`browse init scripts (${ctx.browseInit})`);
     }
     return { write: false };
   }

package/src/container.ts

@@ -10,6 +10,7 @@
 // development keeps working with zero configuration.
 
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { dataRoot } from "./paths.ts";
 import { spawnSync, spawn } from "node:child_process";
@@ -131,6 +132,10 @@ export interface ContainerRunOptions {
   agentDir: string;
   /** Extra read-only mounts: host path → container path. */
   readOnly?: Record<string, string>;
+  /** Workspace paths a script was handed as `workspace/…`: copied in at
+   *  `container` before it runs, and what it created or changed under them
+   *  copied back to `host` after — the host's workspace link, as a copy. */
+  staged?: { host: string; container: string }[];
   image: string;
   argv: string[]; // command inside the container
   env: Record<string, string>;
@@ -181,15 +186,36 @@ export async function runInContainer(
   const cid = (created.stdout ?? "").trim();
 
   try {
-    // The agent's own directory becomes /workspace…
-    const copied = docker(["cp", `${opts.agentDir}/.`, `${cid}:/workspace`], 120_000);
-    if (copied.status !== 0) {
-      return { code: null, out: `copy in failed: ${(copied.stderr ?? "").slice(-300)}` };
-    }
+    // The agent's own directory becomes /workspace… — its entries staged
+    // like the workspace paths below (a scratch copy, opened up for the
+    // script's user, one tar), minus the step's `workspace` link. A step
+    // holds that link (→ ../..) so the shell can say workspace/…, and
+    // `docker cp` refuses a link that climbs out of what it copies
+    // ("invalid symlink"), so every Docker-run script failed before it
+    // started. And `docker cp` lands files as root while scripts run as
+    // `agent`, so a script could never write its own outputs/.
+    const own = fs
+      .readdirSync(opts.agentDir)
+      .filter((name) => {
+        if (name !== "workspace") return true;
+        try {
+          return !fs.lstatSync(path.join(opts.agentDir, name)).isSymbolicLink();
+        } catch {
+          return false;
+        }
+      })
+      .map((name) => ({ host: path.join(opts.agentDir, name), container: `/workspace/${name}` }));
+    const copiedIn = stageIn(CLI, cid, own, ["/workspace"]);
+    if (copiedIn) return { code: null, out: `copy in failed: ${copiedIn}` };
     // …and any shared directories land at their declared paths.
     for (const [host, mount] of Object.entries(opts.readOnly ?? {})) {
       if (fs.existsSync(host)) docker(["cp", `${host}/.`, `${cid}:${mount}`], 120_000);
     }
+    const staged = opts.staged ?? [];
+    if (staged.length) {
+      const failed = stageIn(CLI, cid, staged);
+      if (failed) return { code: null, out: `copy in failed: ${failed}` };
+    }
 
     const result = await new Promise<{ code: number | null; out: string }>((resolve) => {
       const child = spawn(CLI, ["start", "-a", cid], { timeout: opts.timeoutMs });
@@ -213,8 +239,89 @@ export async function runInContainer(
 
     // Bring deliverables back so outputs/ behaves the same either way.
     docker(["cp", `${cid}:/workspace/outputs/.`, path.join(opts.agentDir, "outputs")], 120_000);
+    for (const s of staged) stageBack(CLI, cid, s);
     return result;
   } finally {
     docker(["rm", "-f", cid], 30_000);
   }
 }
+
+/**
+ * Copy the staged workspace paths into a created container: one tar, built
+ * in a scratch directory that mirrors the container paths, extracted at /.
+ * A path that does not exist yet (an output the script is told to write)
+ * gets its parent directory, so the write has somewhere to land.
+ */
+function stageIn(cli: string, cid: string, staged: { host: string; container: string }[], dirs: string[] = []): string | null {
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "foldrun-stage-"));
+  try {
+    for (const d of dirs) fs.mkdirSync(path.join(scratch, d), { recursive: true });
+    for (const { host, container } of staged) {
+      const dest = path.join(scratch, container);
+      if (fs.existsSync(host)) {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.cpSync(host, dest, { recursive: true, dereference: false });
+      } else {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+      }
+    }
+    // `docker cp` lands files as root and scripts run as `agent`: these are
+    // scratch copies, so open them up for the script to write into.
+    openUp(scratch);
+    const top = fs.readdirSync(scratch);
+    const r = spawnSync(
+      "sh",
+      ["-c", 'dir="$1"; cli="$2"; dest="$3"; shift 3; tar --no-xattrs -C "$dir" -cf - -- "$@" | "$cli" cp - "$dest"', "sh", scratch, cli, `${cid}:/`, ...top],
+      { encoding: "utf8", timeout: 120_000, env: { ...process.env, COPYFILE_DISABLE: "1" } },
+    );
+    return r.status === 0 ? null : (r.stderr ?? "").slice(-300);
+  } finally {
+    fs.rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Copy back what the script created or changed under one staged path. Files
+ * whose bytes did not change are left alone, so an input keeps its mtime —
+ * freshness checks read it.
+ */
+function stageBack(cli: string, cid: string, s: { host: string; container: string }): void {
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), "foldrun-stage-"));
+  try {
+    const out = path.join(scratch, "x");
+    const got = spawnSync(cli, ["cp", `${cid}:${s.container}`, out], { encoding: "utf8", timeout: 120_000 });
+    if (got.status !== 0 || !fs.existsSync(out)) return;
+    syncChanged(out, s.host);
+  } finally {
+    fs.rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+/** Write `from` over `to` where the bytes differ; recurse into folders. */
+export function syncChanged(from: string, to: string): void {
+  const st = fs.lstatSync(from);
+  if (st.isSymbolicLink()) return;
+  if (st.isDirectory()) {
+    fs.mkdirSync(to, { recursive: true });
+    for (const name of fs.readdirSync(from)) syncChanged(path.join(from, name), path.join(to, name));
+    return;
+  }
+  const next = fs.readFileSync(from);
+  if (fs.existsSync(to) && fs.statSync(to).isFile() && fs.readFileSync(to).equals(next)) return;
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  fs.writeFileSync(to, next);
+}
+
+/** Directories 0777, files writable by all (exec bits kept): a scratch tree only. */
+function openUp(dir: string): void {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isSymbolicLink()) continue;
+    if (entry.isDirectory()) {
+      fs.chmodSync(p, 0o777);
+      openUp(p);
+    } else {
+      fs.chmodSync(p, fs.statSync(p).mode | 0o666);
+    }
+  }
+}

package/src/context-tools.ts

@@ -32,7 +32,7 @@ import type { RunRecord } from "./store.ts";
 // ------------------------------------------------------------------ search
 
 export interface SearchRoot {
-  /** How the agent should name the place: "knowledge/", "../../memory/". */
+  /** How the agent should name the place: "knowledge/", "workspace/memory/". */
   label: string;
   /** The directory, absolute. */
   dir: string;

package/src/evals.ts

@@ -31,6 +31,7 @@
 // they pass — no point paying a model to grade output already known to be
 // wrong.
 
+import { sdkEnv } from "./step-exec.ts";
 import fs from "node:fs";
 import path from "node:path";
 import { deployedCommit } from "./deploy.ts";
@@ -491,6 +492,8 @@ async function judge(
       tools: [],
       allowedTools: [],
       settingSources: [],
+      strictMcpConfig: true,
+      env: sdkEnv(undefined),
       maxTurns: 1,
     },
   });

package/src/host-env.ts

@@ -20,6 +20,11 @@
 const EXACT = new Set([
   "PATH", "HOME", "TMPDIR", "TMP", "TEMP", "LANG", "LANGUAGE",
   "TZ", "TERM", "SHELL", "USER", "LOGNAME",
+  // Where Claude Code / the Agent SDK keeps its config and session
+  // transcripts — the same kind of thing as HOME (a path, not a secret), and
+  // without it an operator cannot keep them out of the host user's
+  // ~/.claude: the box's deploy tests set it to the job's temp (2026-10-02).
+  "CLAUDE_CONFIG_DIR",
   // The host's way to the network is the child's way to the network.
   "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "no_proxy",
   "SSL_CERT_FILE", "SSL_CERT_DIR",

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,71 @@
+// 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`",
+  };
+}

package/src/run-container.ts

@@ -25,7 +25,7 @@ import crypto from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
 import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
 import { isPlatformPath, type ApiSpec, type Effort } from "./store.ts";
-import { divertedSummary, isDivertedPath } from "./test-mode.ts";
+import { divertedSummary, isDivertedPath, overlayTestWrites } from "./test-mode.ts";
 import type { EventExtra } from "./step-exec.ts";
 import { isFileValue, fileContent } from "./secrets.ts";
 import { safeTenantSegment, type RuntimeSpec } from "./runtime.ts";
@@ -617,7 +617,7 @@ try {
     // through the account's pod, and named the file the web tool logs its
     // reconnects to. A lost pod stops the step; what it wrote decides what
     // the runner does next (browser-pod.ts).
-    ...(env.FOLDRUN_BROWSER_POD_EVENTS ? { browserPod: { events: env.FOLDRUN_BROWSER_POD_EVENTS, methods: api.methods ?? {}, paidWeb: paidWebActions(env) } } : {}),
+    ...(env.FOLDRUN_BROWSER_POD_EVENTS ? { browserPod: { events: env.FOLDRUN_BROWSER_POD_EVENTS, methods: api.methods ?? {}, paidWeb: paidWebActions(env), ...(env.FOLDRUN_BROWSER_INIT ? { browseInit: env.FOLDRUN_BROWSER_INIT } : {}) } } : {}),
     // The container is the boundary; the SDK's own bash sandbox here would
     // only block declared network use (SSH, curl) for no added safety.
     sandboxBash: false,
@@ -647,17 +647,30 @@ try {
 }
 `;
 
+// Core itself is installed in a stage of its own (CORE_STAGE) and only the
+// result is copied in: the tarball and the package README — which explains
+// foldrun to a person reading the repo, and which no step reads — stay in
+// that stage and never become a layer of the image. Owner rule, 2026-10-02:
+// foldrun's own docs live in git, not in containers.
+const CORE_STAGE = `FROM base AS core
+WORKDIR /opt/runner
+COPY foldrun-core.tgz ./
+RUN npm init -y >/dev/null && npm install ./foldrun-core.tgz --omit=dev \\
+ && npm cache clean --force >/dev/null 2>&1 \\
+ && rm -f foldrun-core.tgz node_modules/@foldrun/core/README.md
+`;
+
 // docker cp writes root-owned files, so the entrypoint starts as root for
 // exactly two commands — chown the copied-in trees, drop to the agent user —
 // and the run flags grant only the three capabilities those two commands
 // need. By the time any model-directed code executes, the process is uid
 // 10001 with no capabilities at all.
 const CORE_INSTALL = `WORKDIR /opt/runner
-COPY foldrun-core.tgz driver.mjs entry.sh ./
-RUN npm init -y >/dev/null && npm install ./foldrun-core.tgz --omit=dev \\
- && npm cache clean --force >/dev/null 2>&1 \\
- && mkdir -p /workspace /library /opt/runner/job ${RUNTIME_CACHE} ${SHARED_RUNTIMES} \\
- && chown -R agent:agent /workspace /library /opt/runner /home/agent/.foldrun /opt/foldrun-runtimes \\
+COPY --from=core --chown=agent:agent /opt/runner/ ./
+COPY --chown=agent:agent driver.mjs entry.sh ./
+RUN mkdir -p /workspace /library /opt/runner/job ${RUNTIME_CACHE} ${SHARED_RUNTIMES} \\
+ && chown agent:agent /opt/runner \\
+ && chown -R agent:agent /workspace /library /opt/runner/job /home/agent/.foldrun /opt/foldrun-runtimes \\
  && chmod +x /opt/runner/entry.sh
 ENTRYPOINT ["/opt/runner/entry.sh"]
 `;
@@ -724,6 +737,7 @@ RUN apt-get update \\
 COPY --from=ghcr.io/astral-sh/uv:${UV_VERSION} /uv /uvx /usr/local/bin/
 ENV PLAYWRIGHT_BROWSERS_PATH=/opt/browser NODE_PATH=/usr/local/lib/node_modules
 
+${CORE_STAGE}
 FROM base AS slim
 # Fonts, because a step that draws text without a browser still needs them:
 # the full image gets 51 from Playwright's --with-deps, slim had none, so from
@@ -1299,6 +1313,12 @@ export async function runStepInContainer(args: RunInContainerArgs): Promise<Cont
       preserveTimestamps: true,
       filter: (src) => !isPlatformPath(path.relative(args.workspaceRoot, src)),
     });
+    // A test run: what its earlier steps wrote, over the real files (the
+    // copy is the baseline too, so only this step's own writes come back).
+    if (args.divert) {
+      const laid = overlayTestWrites(wsIn, args.divert.to);
+      if (laid.length) args.emit("info", `test: this step sees ${laid.length} file${laid.length === 1 ? "" : "s"} earlier steps of this run wrote`);
+    }
     const libIn = path.join(staging, "library");
     if (args.galleryRoot && fs.existsSync(args.galleryRoot)) fs.cpSync(args.galleryRoot, libIn, { recursive: true });
     if (fs.existsSync(args.libraryRoot)) fs.cpSync(args.libraryRoot, libIn, { recursive: true });