@foldrun/core 0.6.0 → 1.0.0

package/src/provider-health.ts

@@ -18,6 +18,7 @@
 // It reads the same provider block a run reads, resolved the same way, so a
 // pass here means a run would reach the same place with the same key.
 
+import { accountModelBlock } from "./model-credential.ts";
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
@@ -236,6 +237,8 @@ export function providersInUse(tenant: string): ProviderInUse[] {
   };
 
   add(frontmatterOf(path.join(accountDir(tenant), "AGENTS.md")).provider, null, "account");
+  // The account's own key from Settings → Model, which needs no block.
+  add(accountModelBlock((name) => getSecret(tenant, name)?.value ?? null), null, "account (Settings → Model)");
   for (const ws of safeList(() => listWorkspaces(tenant))) {
     const dir = workspaceDir(tenant, ws.name);
     add(frontmatterOf(path.join(dir, "AGENTS.md")).provider, ws.name, ws.name);

package/src/providers.ts

@@ -591,6 +591,11 @@ export interface BrowseSettings {
   ignore_https_errors?: boolean;
   /** The NAME of a vault secret whose value encrypts state= logins at rest. */
   state_key?: string;
+  /** A saved login every call uses by default: loaded from
+   *  workspace/state/browser/<name>.json and saved back when the call ends.
+   *  Beside `cookies:` (with `state_key:`), the secret seeds it once and the
+   *  session the site keeps rotating is what later runs load. */
+  state?: string;
   /** true records every call, so the run page always has the recording to play. */
   video?: boolean;
   /** false stops the tool streaming its page to the run page while the step
@@ -685,7 +690,7 @@ export function browseEngineRefusal(engine: string, what: string): string | null
 }
 const BROWSE_SETTING_KEYS = [
   "engine", "user_agent", "device", "locale", "timezone", "cookies", "cookie_domain", "storage", "storage_origin", "identities", "headless", "version", "live",
-  "allowed_domains", "deny", "boundaries", "init", "extensions", "webgpu", "ignore_https_errors", "state_key",
+  "allowed_domains", "deny", "boundaries", "init", "extensions", "webgpu", "ignore_https_errors", "state_key", "state",
   "video", "live_view", "vendor_session",
   // Deprecated spelling of vendor_session (read, and warned about).
   "session",
@@ -964,6 +969,11 @@ export function readBrowseSettings(raw: unknown): { settings: BrowseSettings; re
       if (list.length) settings[k] = list;
       continue;
     }
+    if (k === "state") {
+      if (typeof v !== "string" || !/^[A-Za-z0-9._-]{1,64}$/.test(v)) return { settings, rest: left(rest), error: "web.browse.state is a plain name (letters, digits, dot, dash, underscore), like youtube — the login is kept in workspace/state/browser/<name>.json." };
+      settings.state = v;
+      continue;
+    }
     if (k === "state_key") {
       if (typeof v !== "string" || !/^[A-Z][A-Z0-9_]{0,63}$/.test(v)) return { settings, rest: left(rest), error: "web.browse.state_key must be the NAME of a vault secret (CAPITALS), never the key — store it with `foldrun secrets set NAME` and declare it under secrets:." };
       settings.state_key = v;
@@ -1033,6 +1043,22 @@ export function readBrowseSettings(raw: unknown): { settings: BrowseSettings; re
     };
   }
 
+  // A secret's cookies seeding a saved login: the login then sits in state/,
+  // a workspace file, so it must be encrypted with a key from the vault.
+  if (settings.state && settings.cookies && !settings.state_key) {
+    return {
+      settings,
+      rest: left(rest),
+      error:
+        `web.browse.state beside cookies needs web.browse.state_key — the secret's session would be saved ` +
+        `to state/ where any step can read it. Store a key (\`foldrun secrets set BROWSER_STATE_KEY\`), ` +
+        `write \`state_key: BROWSER_STATE_KEY\` and declare it under secrets:.`,
+    };
+  }
+  if (settings.state && settings.storage) {
+    return { settings, rest: left(rest), error: "web.browse.state cannot be combined with storage: a secret's tokens would be written to state/." };
+  }
+
   // Storage is per origin, and seeding it into the wrong one would hand a
   // site another site's signed-in state — the same mistake `cookie_domain`
   // exists to prevent, one storage area over.

package/src/run-container.ts

@@ -18,6 +18,7 @@
 // The runner image bundles @foldrun/core itself, so the driver runs the same
 // executeStep the server would — one implementation, two homes.
 
+import { isHookRecord, type HookRecord } from "./hooks.ts";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -28,7 +29,7 @@ import { isPlatformPath, type ApiSpec, type Effort } from "./store.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";
+import { safeTenantSegment, systemInstallSh, SYSTEM_FROM_INPUT_SH, INSTALL_SOCKET, type RuntimeSpec } from "./runtime.ts";
 import type { ScriptSpec } from "./script-tools.ts";
 import type { ConsultSpec } from "./agent-tools.ts";
 import type { SubagentSpec } from "./subagents.ts";
@@ -77,6 +78,9 @@ export interface ContainerStepInput {
   /** `limits:` resolved host-side, and the SDK-name → foldrun-name map the
    *  count reads (limits.ts) — enforced in the pod by the same hook. */
   limits?: Record<string, number>;
+  /** `hooks:` names, resolved inside the sandbox against its own roots. */
+  hookNames?: string[];
+  hookBase?: Record<string, unknown>;
   toolOwners?: Record<string, string>;
   /** tools: [search] — the directories to search, as paths INSIDE the
    *  container (/workspace/…, /library/…). */
@@ -172,7 +176,9 @@ const cli = () => process.env.FOLDRUN_CONTAINER_CLI ?? "docker";
 // there: everything platform-owned (store.ts#isPlatformPath — also never
 // copied in), plus knowledge/, which goes in for reading and is dropped on
 // the way out, and .git/.
-const DENY_BACK = ["knowledge/", ".git/"];
+// hooks/: a step must not rewrite the code that guards it — for this run (the
+// code is read into memory before the model starts, hooks.ts) or the next.
+const DENY_BACK = ["knowledge/", "hooks/", ".git/"];
 // A .git ANYWHERE in the tree, not just at the root. A step that clones a
 // repository into a shared area (files/site, say) was shipping the entire
 // object store back to the workspace, where the harvest then filed thousands
@@ -293,18 +299,37 @@ export function mergeAppends(was: Buffer | string | null, host: Buffer, next: Bu
   let common = 0;
   const max = Math.min(h.length, n.length);
   while (common < max && h.charCodeAt(common) === n.charCodeAt(common)) common++;
-  for (let end = common; end >= 0; end--) {
-    if (end > 0 && h[end - 1] !== "\n") continue;
-    const prefix = h.slice(0, end);
-    const matches =
-      typeof was === "string" ? sha(Buffer.from(prefix, "utf8")) === was : Buffer.from(prefix, "utf8").equals(was);
-    if (!matches) continue;
-    const hostAdded = h.slice(end);
-    const stepAdded = n.slice(end);
-    const joined = hostAdded && !hostAdded.endsWith("\n") ? hostAdded + "\n" : hostAdded;
-    return Buffer.from(prefix + joined + stepAdded, "utf8");
+  // One pass over the shared prefix. Rebuilding and hashing the prefix at
+  // every line boundary, from the longest down, was quadratic: on 6 Oct 2026
+  // a conflicted file of a few MB held the worker's event loop for minutes,
+  // the liveness probe killed it every 4.5 minutes, and every step on the box
+  // lost its model connection.
+  let end = -1;
+  if (typeof was === "string") {
+    const run = crypto.createHash("sha256");
+    if (run.copy().digest("hex") === was) end = 0;
+    let from = 0;
+    for (let nl = h.indexOf("\n"); nl !== -1 && nl < common; nl = h.indexOf("\n", nl + 1)) {
+      run.update(h.slice(from, nl + 1), "utf8");
+      from = nl + 1;
+      if (run.copy().digest("hex") === was) end = from;
+    }
+  } else {
+    // The base's bytes are known, so it can only end at their length.
+    const base = was.toString("utf8");
+    if (
+      base.length <= common &&
+      (base.length === 0 || base.endsWith("\n")) &&
+      h.startsWith(base) &&
+      Buffer.from(base, "utf8").equals(was)
+    )
+      end = base.length;
   }
-  return null;
+  if (end < 0) return null;
+  const hostAdded = h.slice(end);
+  const stepAdded = n.slice(end);
+  const joined = hostAdded && !hostAdded.endsWith("\n") ? hostAdded + "\n" : hostAdded;
+  return Buffer.from(h.slice(0, end) + joined + stepAdded, "utf8");
 }
 
 export function applyContainerChanges(
@@ -408,6 +433,13 @@ export function applyContainerChanges(
  */
 export const RUNTIME_CACHE = "/home/agent/.foldrun/runner/.runtimes";
 
+/** Starts the install helper as root, in the background, before the drop to
+ *  the agent user: the root half of the `install` tool (install-helper.ts).
+ *  The agent reaches it only through the socket; it installs only validated
+ *  Debian package names, and dies with the container. */
+export const INSTALL_HELPER_SH = `FOLDRUN_INSTALL_SOCKET=${INSTALL_SOCKET}; export FOLDRUN_INSTALL_SOCKET
+node /opt/runner/node_modules/@foldrun/core/dist/src/install-helper.js "$FOLDRUN_INSTALL_SOCKET" ${RUNTIME_CACHE} >/dev/null 2>&1 &`;
+
 /**
  * Where the platform's shared runtime layer is mounted, read-only, in a run
  * pod — and read-write, one entry at a time, in the pod that builds an entry
@@ -548,6 +580,25 @@ try {
   // meet the packages its runtime declared, not the image's bare python.
   Object.assign(env, runtime.env);
 
+  // install: what the agent finds it needs mid-step. apt goes through the
+  // root start-up's helper (install-helper.ts); pip and npm land in a
+  // directory of this container's own, on the paths from the first turn.
+  const { buildInstallTool, INSTALL_TOOL } = await import("@foldrun/core/install-tool");
+  const { stepInstallEnv, INSTALL_SOCKET } = await import("@foldrun/core/runtime");
+  const installDir = "/home/agent/.foldrun/step";
+  const installing = (input.allowed ?? []).includes(INSTALL_TOOL);
+  if (installing) Object.assign(env, stepInstallEnv(installDir, env));
+  const install = installing
+    ? buildInstallTool({
+        dir: installDir,
+        socket: env.FOLDRUN_INSTALL_SOCKET || INSTALL_SOCKET,
+        cacheRoot: "${RUNTIME_CACHE}",
+        python: env.VIRTUAL_ENV ? env.VIRTUAL_ENV + "/bin/python" : "python3",
+        env,
+        emit,
+      })
+    : { server: null };
+
   // API and script tools, rebuilt in here from their specs. Secrets were
   // substituted into API headers before the input crossed the boundary, so
   // buildApiTools gets an already-resolved environment. verify: gets the
@@ -598,6 +649,7 @@ try {
       ...(history.server ? { foldrun_history: history.server } : {}),
       ...(desks.server ? { foldrun_desks: desks.server } : {}),
       ...(ask.server ? { foldrun_ask: ask.server } : {}),
+      ...(install.server ? { foldrun_install: install.server } : {}),
       ...input.mcpServers,
     },
     ...(inbox ? { inbox } : {}),
@@ -613,6 +665,7 @@ try {
     schema: input.schema,
     maxTurns: input.maxTurns,
     ...(input.limits && Object.keys(input.limits).length ? { limits: input.limits, toolOwners: input.toolOwners ?? {} } : {}),
+    ...(input.hookNames?.length ? { hookNames: input.hookNames, hookBase: input.hookBase ?? {} } : {}),
     // Slim browsing: the platform put this step on the slim image to browse
     // 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
@@ -893,7 +946,14 @@ RUN node -e ' \\
 FROM browsers AS full
 ${CORE_INSTALL}`;
 
+// runtime: system: — apt as root, before the drop (runtime.ts systemInstallSh).
+// set -e is off around it: a failed install is reported by the driver, which
+// reads the status file and fails the step with apt's own words.
 const ENTRY = `#!/bin/sh
+set +e
+${SYSTEM_FROM_INPUT_SH}
+${systemInstallSh(RUNTIME_CACHE)}
+${INSTALL_HELPER_SH}
 set -e
 chown -R agent:agent /workspace /library /opt/runner/job
 # The runtime cache, when one is mounted. NOT recursive: a warm cache is tens
@@ -1054,7 +1114,7 @@ export function buildFailureSummary(log: string, opts: { tail?: number; maxLines
 
 export function parseDriverLine(
   line: string,
-): { e: "event"; type: "text" | "tool" | "info" | "error"; text: string; call?: string; ms?: number; err?: boolean; operator?: OperatorEvent; subagent?: string; check?: boolean } | { e: "done" } & ContainerStepOutcome | null {
+): { e: "event"; type: "text" | "tool" | "info" | "error"; text: string; call?: string; ms?: number; err?: boolean; operator?: OperatorEvent; subagent?: string; check?: boolean; hook?: HookRecord } | { e: "done" } & ContainerStepOutcome | null {
   const trimmed = line.trim();
   if (!trimmed.startsWith("{")) return null;
   try {
@@ -1070,6 +1130,7 @@ export function parseDriverLine(
         ...(isOperatorEvent(parsed.operator) ? { operator: parsed.operator } : {}),
         ...(typeof parsed.subagent === "string" && /^[a-z0-9-]{1,64}$/.test(parsed.subagent) ? { subagent: parsed.subagent } : {}),
         ...(parsed.check === true ? { check: true } : {}),
+        ...(isHookRecord(parsed.hook) ? { hook: parsed.hook } : {}),
       };
     }
     if (parsed.e === "done") {