@foldrun/core 0.7.0 → 1.1.0

package/src/network.ts

@@ -0,0 +1,390 @@
+// Network: which sites a step's sandbox may reach.
+//
+//   network: trusted                 # the trusted list, plus what the step declares
+//   network: open                    # any public site
+//   network: none                    # only what the step declares
+//   network: [api.example.com, "*.example.org"]          # add sites; the level stays
+//   network: { level: trusted, allow: [api.example.com], defaults: false }
+//
+// Written on an agent, a workspace's AGENTS.md or the account's. The level
+// and `defaults` are nearest-wins (agent, then workspace, then account);
+// `allow` adds up across all three, so an account can name a site every
+// agent may reach without each agent repeating it.
+//
+// Unset, an agent that reads the open web — `web` with fetch or browse — is
+// `open`, because a search result can name any site and an allowlist would
+// break it. Every other agent is `trusted`: package registries, source
+// hosts and cloud SDKs, the list Anthropic's own cloud sandboxes start from
+// (TRUSTED_SITES below), plus the hosts the step itself declares — its
+// `apis:`, its remote MCP servers, its web providers, the sites its secrets
+// are bound to. That is the default the cloud sandboxes this platform is
+// measured against use: least access, widened on purpose.
+//
+// The rule is enforced at the egress proxy, which every request from a
+// sandbox goes through (HTTPS_PROXY in the pod), and, on the Kubernetes
+// tier, by the pod's network policy: a `trusted` or `none` pod reaches the
+// proxy and DNS and nothing else, so a program that ignores the proxy
+// variables fails instead of going round. This file is the vocabulary; the
+// proxy (foldrun-platform egress-proxy.ts) holds the rule per request.
+
+/** How wide a step's network is. */
+export type NetworkLevel = "open" | "trusted" | "none";
+
+export const NETWORK_LEVELS: readonly NetworkLevel[] = ["open", "trusted", "none"];
+
+/** One level's `network:` line, read. Absent fields inherit. */
+export interface NetworkSetting {
+  level?: NetworkLevel;
+  /** Sites added at this level. */
+  allow: string[];
+  /** false drops the trusted list, leaving only `allow` and what the step declares. */
+  defaults?: boolean;
+}
+
+/** What one step may reach, resolved. Plain JSON: it crosses into the egress
+ *  grant and the run record. */
+export interface NetworkPolicy {
+  level: NetworkLevel;
+  /** Every site allowed beyond what `open` would allow — the trusted list
+   *  (unless dropped), the `allow` lists, and the hosts the step declares.
+   *  Empty for `open`, which needs no list. */
+  hosts: string[];
+  /** Where the level came from, for the trace: "agent", "workspace",
+   *  "account", or "default" with the reason. */
+  from: string;
+  /** Whether the trusted list is part of `hosts`. */
+  defaults: boolean;
+  /** The sites the files added (`allow`, every level), apart from the
+   *  trusted list — what the trace and the dashboard show as "added". */
+  added: string[];
+  /** Hosts the step declares (apis, MCP servers, providers, bound secrets). */
+  implied: string[];
+}
+
+/**
+ * The trusted list: the domains Anthropic's Claude Code cloud environments
+ * allow at their default "Trusted" level, as published on
+ * code.claude.com/docs/en/cloud-environments#default-allowed-domains
+ * (read 14 Oct 2026), plus the Debian mirrors the runner image installs
+ * `runtime: system:` packages from. `*.` matches the subdomains and the
+ * bare domain.
+ */
+export const TRUSTED_SITES: readonly string[] = [
+  // Anthropic services
+  "api.anthropic.com", "docs.claude.com", "platform.claude.com", "code.claude.com", "claude.ai", "claude.com",
+  "support.claude.com", "anthropic.com", "www.anthropic.com",
+  // Version control
+  "github.com", "www.github.com", "api.github.com", "npm.pkg.github.com", "raw.githubusercontent.com",
+  "pkg-npm.githubusercontent.com", "objects.githubusercontent.com", "release-assets.githubusercontent.com",
+  "codeload.github.com", "avatars.githubusercontent.com", "camo.githubusercontent.com", "gist.github.com",
+  "gitlab.com", "www.gitlab.com", "registry.gitlab.com", "bitbucket.org", "www.bitbucket.org", "api.bitbucket.org",
+  // Container registries
+  "registry-1.docker.io", "auth.docker.io", "index.docker.io", "hub.docker.com", "www.docker.com",
+  "production.cloudflare.docker.com", "production.cloudfront.docker.com", "download.docker.com", "gcr.io",
+  "*.gcr.io", "ghcr.io", "mcr.microsoft.com", "*.data.mcr.microsoft.com", "public.ecr.aws",
+  // Cloud platforms
+  "cloud.google.com", "accounts.google.com", "gcloud.google.com", "*.googleapis.com", "storage.googleapis.com",
+  "compute.googleapis.com", "container.googleapis.com", "azure.com", "portal.azure.com", "microsoft.com",
+  "www.microsoft.com", "*.microsoftonline.com", "packages.microsoft.com", "dotnet.microsoft.com", "dot.net",
+  "visualstudio.com", "dev.azure.com", "*.amazonaws.com", "*.api.aws", "oracle.com", "www.oracle.com", "java.com",
+  "www.java.com", "java.net", "www.java.net", "download.oracle.com", "yum.oracle.com", "*.r2.cloudflarestorage.com",
+  // JavaScript and Node
+  "registry.npmjs.org", "www.npmjs.com", "www.npmjs.org", "npmjs.com", "npmjs.org", "yarnpkg.com",
+  "registry.yarnpkg.com", "jsr.io", "npm.jsr.io",
+  // Python
+  "pypi.org", "www.pypi.org", "files.pythonhosted.org", "pythonhosted.org", "test.pypi.org", "pypi.python.org",
+  "pypa.io", "www.pypa.io",
+  // Ruby
+  "rubygems.org", "www.rubygems.org", "api.rubygems.org", "index.rubygems.org", "ruby-lang.org",
+  "www.ruby-lang.org", "rubyforge.org", "www.rubyforge.org", "rubyonrails.org", "www.rubyonrails.org", "rvm.io",
+  "get.rvm.io",
+  // Rust
+  "crates.io", "www.crates.io", "index.crates.io", "static.crates.io", "rustup.rs", "static.rust-lang.org",
+  "www.rust-lang.org",
+  // Go
+  "proxy.golang.org", "sum.golang.org", "index.golang.org", "golang.org", "www.golang.org", "goproxy.io", "pkg.go.dev",
+  // JVM
+  "maven.org", "repo.maven.org", "central.maven.org", "repo1.maven.org", "repo.maven.apache.org",
+  "maven.google.com", "jcenter.bintray.com", "gradle.org", "www.gradle.org", "services.gradle.org",
+  "plugins.gradle.org", "plugins-artifacts.gradle.org", "kotlinlang.org", "www.kotlinlang.org", "spring.io",
+  "repo.spring.io",
+  // Other package managers
+  "packagist.org", "www.packagist.org", "repo.packagist.org", "nuget.org", "www.nuget.org", "api.nuget.org",
+  "pub.dev", "api.pub.dev", "hex.pm", "www.hex.pm", "cpan.org", "www.cpan.org", "metacpan.org", "www.metacpan.org",
+  "api.metacpan.org", "cocoapods.org", "www.cocoapods.org", "cdn.cocoapods.org", "haskell.org", "www.haskell.org",
+  "hackage.haskell.org", "swift.org", "www.swift.org",
+  // Linux distributions — Anthropic's list, then Debian's (the runner image is Debian)
+  "archive.ubuntu.com", "security.ubuntu.com", "ubuntu.com", "www.ubuntu.com", "*.ubuntu.com",
+  "ppa.launchpad.net", "launchpad.net", "www.launchpad.net", "*.nixos.org",
+  "deb.debian.org", "security.debian.org", "snapshot.debian.org",
+  // Development tools and platforms
+  "dl.k8s.io", "pkgs.k8s.io", "k8s.io", "www.k8s.io", "releases.hashicorp.com", "apt.releases.hashicorp.com",
+  "rpm.releases.hashicorp.com", "archive.releases.hashicorp.com", "hashicorp.com", "www.hashicorp.com",
+  "repo.anaconda.com", "conda.anaconda.org", "anaconda.org", "www.anaconda.com", "anaconda.com", "continuum.io",
+  "apache.org", "www.apache.org", "archive.apache.org", "downloads.apache.org", "eclipse.org", "www.eclipse.org",
+  "download.eclipse.org", "nodejs.org", "www.nodejs.org", "developer.apple.com", "developer.android.com",
+  "pkg.stainless.com", "binaries.prisma.sh",
+  // Cloud services and monitoring
+  "http-intake.logs.datadoghq.com", "*.datadoghq.com", "*.datadoghq.eu", "api.honeycomb.io",
+  // Content delivery and mirrors
+  "sourceforge.net", "*.sourceforge.net", "packagecloud.io", "*.packagecloud.io", "fonts.googleapis.com",
+  "fonts.gstatic.com",
+  // Schema and configuration
+  "json-schema.org", "www.json-schema.org", "json.schemastore.org", "www.schemastore.org",
+  // Model Context Protocol
+  "*.modelcontextprotocol.io",
+];
+
+/** A site as `network:` takes it: a domain or `*.domain` — no scheme, no
+ *  path, no port. The same shape `web.browse.allowed_domains` takes. */
+export const SITE = /^(\*\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;
+
+/** A host as it arrives — `API.Example.com:443.` — as the lists hold it. */
+export function normalHost(host: string): string {
+  let h = host.trim().toLowerCase();
+  if (h.startsWith("[")) return h.replace(/^\[|\](:\d+)?$/g, ""); // an IPv6 literal
+  h = h.replace(/:\d+$/, "");
+  return h.replace(/\.$/, "");
+}
+
+/** Does `site` (a domain or `*.domain`) cover `host`? `*.example.com`
+ *  covers `a.example.com`, `a.b.example.com` and `example.com` itself. */
+export function siteCovers(site: string, host: string): boolean {
+  const h = normalHost(host);
+  const s = site.toLowerCase();
+  if (s.startsWith("*.")) {
+    const base = s.slice(2);
+    return h === base || h.endsWith(`.${base}`);
+  }
+  return h === s;
+}
+
+/** May a step under `policy` reach `host`? `open` reaches any public host —
+ *  the caller still refuses private addresses, which no level opens. */
+export function networkAllows(policy: Pick<NetworkPolicy, "level" | "hosts">, host: string): boolean {
+  if (policy.level === "open") return true;
+  return policy.hosts.some((s) => siteCovers(s, host));
+}
+
+/** A list of sites from YAML's list or one comma-separated line. */
+function siteList(v: unknown): string[] | null {
+  if (typeof v === "string") return v.split(",").map((x) => x.trim()).filter(Boolean);
+  if (Array.isArray(v) && v.every((x) => typeof x === "string")) return v.map((x) => x.trim()).filter(Boolean);
+  return null;
+}
+
+/**
+ * One `network:` value, read. Never throws: what cannot be read is a
+ * problem `check` and deploy report, and the run treats that level as
+ * saying nothing — the next level up, or the default, decides.
+ */
+export function readNetwork(raw: unknown, where = "network"): { setting: NetworkSetting | null; problems: string[] } {
+  if (raw === undefined || raw === null) return { setting: null, problems: [] };
+  const problems: string[] = [];
+  const sites = (v: unknown, key: string): string[] => {
+    const list = siteList(v);
+    if (!list) {
+      problems.push(`${key} is a list of sites, like [api.example.com, "*.example.org"].`);
+      return [];
+    }
+    const out: string[] = [];
+    for (const s of list.map((x) => x.toLowerCase())) {
+      if (/^https?:\/\//.test(s) || s.includes("/")) problems.push(`${key}: ${s} — a site is a domain, no scheme or path: ${s.replace(/^https?:\/\//, "").split("/")[0]}`);
+      else if (/:\d+$/.test(s)) problems.push(`${key}: ${s} — a site has no port; every port of the host is covered`);
+      else if (!SITE.test(s)) problems.push(`${key}: ${s} is not a domain or *.domain`);
+      else out.push(s);
+    }
+    return out;
+  };
+  const level = (v: unknown, key: string): NetworkLevel | undefined => {
+    if (typeof v === "string" && (NETWORK_LEVELS as readonly string[]).includes(v.trim().toLowerCase())) {
+      return v.trim().toLowerCase() as NetworkLevel;
+    }
+    problems.push(`${key} is ${NETWORK_LEVELS.join(", ")} — not ${JSON.stringify(v)}.`);
+    return undefined;
+  };
+  if (typeof raw === "string" && (NETWORK_LEVELS as readonly string[]).includes(raw.trim().toLowerCase())) {
+    return { setting: { level: raw.trim().toLowerCase() as NetworkLevel, allow: [] }, problems };
+  }
+  if (typeof raw === "string" || Array.isArray(raw)) {
+    // A bare word that is not a level reads as a site only when it looks
+    // like one — `network: closed` is a typo, not a domain called "closed".
+    if (typeof raw === "string" && !raw.includes(".") && !raw.includes(",")) {
+      return { setting: null, problems: [`${where} is ${NETWORK_LEVELS.join(", ")}, a list of sites, or {level, allow, defaults} — not "${raw}".`] };
+    }
+    const allow = sites(raw, where);
+    return { setting: problems.length && !allow.length ? null : { allow }, problems };
+  }
+  if (typeof raw === "object") {
+    const o = raw as Record<string, unknown>;
+    for (const k of Object.keys(o)) {
+      if (!["level", "allow", "defaults"].includes(k)) problems.push(`${where}.${k} is not a key — level, allow, defaults.`);
+    }
+    const setting: NetworkSetting = { allow: [] };
+    if (o.level !== undefined) setting.level = level(o.level, `${where}.level`);
+    if (o.allow !== undefined) setting.allow = sites(o.allow, `${where}.allow`);
+    if (o.defaults !== undefined) {
+      if (o.defaults === true || o.defaults === false) setting.defaults = o.defaults;
+      else problems.push(`${where}.defaults is true or false — false drops the trusted list.`);
+    }
+    return { setting, problems };
+  }
+  return { setting: null, problems: [`${where} is ${NETWORK_LEVELS.join(", ")}, a list of sites, or {level, allow, defaults}.`] };
+}
+
+/** `check`'s and deploy's view: the problems only. */
+export function networkProblems(raw: unknown): string[] {
+  return readNetwork(raw).problems;
+}
+
+/**
+ * The step's network, from its three levels and what it declares.
+ *
+ * `readsWeb` — the step may fetch or browse the open web (the `web` tool
+ * with fetch or browse). It decides the default level only; a `network:`
+ * written anywhere beats it.
+ */
+export function resolveNetwork(args: {
+  account?: unknown;
+  workspace?: unknown;
+  agent?: unknown;
+  readsWeb: boolean;
+  implied?: Iterable<string>;
+}): NetworkPolicy {
+  const levels: [string, NetworkSetting | null][] = [
+    ["agent", readNetwork(args.agent).setting],
+    ["workspace", readNetwork(args.workspace).setting],
+    ["account", readNetwork(args.account).setting],
+  ];
+  const levelHit = levels.find(([, s]) => s?.level);
+  const level: NetworkLevel = levelHit ? levelHit[1]!.level! : args.readsWeb ? "open" : "trusted";
+  const from = levelHit ? levelHit[0] : args.readsWeb ? "default — the agent reads the web" : "default";
+  const defaultsHit = levels.find(([, s]) => s?.defaults !== undefined);
+  const defaults = level === "trusted" && (defaultsHit ? defaultsHit[1]!.defaults! : true);
+  const added = [...new Set(levels.flatMap(([, s]) => s?.allow ?? []))];
+  const implied = [...new Set([...(args.implied ?? [])].map(normalHost).filter((h) => h && SITE.test(h)))];
+  const hosts = level === "open" ? [] : [...new Set([...(defaults ? TRUSTED_SITES : []), ...added, ...implied])];
+  return { level, hosts, from, defaults, added, implied };
+}
+
+/** One line for the run's trace. */
+export function networkLine(policy: NetworkPolicy, enforced: boolean | null): string {
+  const how =
+    enforced === null
+      ? " — not enforced here (no sandbox network)"
+      : enforced
+        ? ""
+        : " — report only on this install: a site off the list is allowed and named in the trace";
+  if (policy.level === "open") return `network: open (${policy.from}) — any public site${how}`;
+  const parts: string[] = [];
+  if (policy.defaults) parts.push(`the trusted list (${TRUSTED_SITES.length} sites)`);
+  if (policy.added.length) parts.push(`added: ${policy.added.join(", ")}`);
+  if (policy.implied.length) parts.push(`declared by the step: ${policy.implied.join(", ")}`);
+  const what = parts.length ? parts.join("; ") : "nothing but the platform's own services";
+  return `network: ${policy.level} (${policy.from}) — ${what}${how}`;
+}
+
+/** What the proxy says when it refuses a site. */
+export function refusalText(policy: Pick<NetworkPolicy, "level">, host: string): string {
+  return `network: ${host} is not a site this step may reach (network: ${policy.level}). Add it to the agent's network: list — network: [${normalHost(host)}] — or set network: open.`;
+}
+
+/** The proxy variables a sandbox's programs read, for a forward-proxy URL
+ *  (`http://foldrun:<token>@host:port`). Both spellings: curl reads only the
+ *  lower-case http_proxy, much else only the upper-case. NO_PROXY keeps the
+ *  cluster's own names — the egress address itself, the account's pods —
+ *  off the proxy. NODE_USE_ENV_PROXY turns the variables on for Node's own
+ *  fetch and http (Node 22.21 and later). */
+export function proxyEnv(proxyUrl: string, extraNoProxy: string[] = []): Record<string, string> {
+  let egressHost = "";
+  try {
+    egressHost = new URL(proxyUrl).hostname;
+  } catch {
+    // a malformed URL is still exported as given; the client says why it fails
+  }
+  const noProxy = [...new Set(["localhost", "127.0.0.1", "::1", ".svc", ".cluster.local", egressHost, ...extraNoProxy].filter(Boolean))].join(",");
+  return {
+    HTTP_PROXY: proxyUrl,
+    HTTPS_PROXY: proxyUrl,
+    http_proxy: proxyUrl,
+    https_proxy: proxyUrl,
+    NO_PROXY: noProxy,
+    no_proxy: noProxy,
+    NODE_USE_ENV_PROXY: "1",
+    // Node 22 warns "EnvHttpProxyAgent is experimental" on the first request
+    // of every process; a script tool's stderr then reads as an error to the
+    // model. That one warning, and no other.
+    NODE_OPTIONS: "--disable-warning=UNDICI-EHPA",
+  };
+}
+
+/** The env var the egress CA travels in — its PEM, base64'd so it survives
+ *  every env channel (docker's env file has no multi-line values). The
+ *  pod's start writes it to a file and points every TLS client at a bundle
+ *  that includes it. */
+export const EGRESS_CA_ENV = "FOLDRUN_EGRESS_CA";
+
+/**
+ * The shell the sandbox's start runs before anything else: when the step
+ * carries the egress CA, write it, build a bundle of the system's CAs plus
+ * it, and point every TLS client the image has at that bundle. The CA only
+ * ever signs for hosts a secret is bound to — every other connection is a
+ * tunnel the proxy cannot read — but those clients must trust it there.
+ * Sourced after the env file, before system packages install (apt goes
+ * through the proxy too). `dir` is a directory the start may write.
+ */
+export function egressCaSh(dir: string, systemBundle = "/etc/ssl/certs/ca-certificates.crt"): string {
+  // Without the system's bundle to add to, a bundle of the egress CA alone
+  // would make every other site untrusted — so only Node, which ADDS the
+  // file to its own roots, is told; nothing else changes.
+  return `if [ -n "\${${EGRESS_CA_ENV}:-}" ] && printf '%s' "\$${EGRESS_CA_ENV}" | base64 -d > ${dir}/egress-ca.pem 2>/dev/null; then
+  if [ -s ${systemBundle} ] && cat ${systemBundle} ${dir}/egress-ca.pem > ${dir}/ca-bundle.pem; then
+    export SSL_CERT_FILE=${dir}/ca-bundle.pem REQUESTS_CA_BUNDLE=${dir}/ca-bundle.pem CURL_CA_BUNDLE=${dir}/ca-bundle.pem PIP_CERT=${dir}/ca-bundle.pem GIT_SSL_CAINFO=${dir}/ca-bundle.pem
+  fi
+  export NODE_EXTRA_CA_CERTS=${dir}/egress-ca.pem
+fi`;
+}
+
+/** A site as a YAML flow item: `*.x` would read as an alias, so it is quoted. */
+const siteItem = (site: string) => (/^[a-z0-9]/.test(site) ? site : JSON.stringify(site));
+
+/** `network:` as one line of YAML, the shortest of the three shapes that
+ *  says it; null when there is nothing to say. */
+export function networkYaml(setting: { level?: NetworkLevel; allow?: string[]; defaults?: boolean } | null): string | null {
+  if (!setting) return null;
+  const allow = [...new Set((setting.allow ?? []).map((s) => s.trim().toLowerCase()).filter(Boolean))];
+  const list = `[${allow.map(siteItem).join(", ")}]`;
+  if (setting.defaults === false) {
+    return `{ ${[setting.level ? `level: ${setting.level}` : "", allow.length ? `allow: ${list}` : "", "defaults: false"].filter(Boolean).join(", ")} }`;
+  }
+  if (setting.level && allow.length) return `{ level: ${setting.level}, allow: ${list} }`;
+  if (setting.level) return setting.level;
+  if (allow.length) return list;
+  return null;
+}
+
+/**
+ * The text of an agent.md (or AGENTS.md) with its `network:` replaced by
+ * `setting` — or removed, for null — and every other byte as it was. The
+ * old value's indented lines go with it, whatever shape it was written in.
+ * Pure string work, so the dashboard runs it in the browser and the CLI on
+ * a file, and both write exactly the same line.
+ */
+export function setNetworkSetting(raw: string, setting: { level?: NetworkLevel; allow?: string[]; defaults?: boolean } | null): string {
+  const eol = raw.includes("\r\n") ? "\r\n" : "\n";
+  const lines = raw.split(eol);
+  const value = networkYaml(setting);
+  const line = value ? `network: ${value}` : null;
+  if (lines[0]?.trim() !== "---") return line ? ["---", line, "---", ...lines].join(eol) : raw;
+  const close = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
+  if (close < 0) return raw;
+  const at = lines.findIndex((l, i) => i > 0 && i < close && /^network\s*:/.test(l));
+  if (at < 0) {
+    if (line) lines.splice(close, 0, line);
+    return lines.join(eol);
+  }
+  let end = at + 1;
+  while (end < close && (/^\s+\S/.test(lines[end]) || /^\s*-\s/.test(lines[end]))) end++;
+  lines.splice(at, end - at, ...(line ? [line] : []));
+  return lines.join(eol);
+}

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),

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";
@@ -29,6 +30,7 @@ import { divertedSummary, isDivertedPath, overlayTestWrites } from "./test-mode.
 import type { EventExtra } from "./step-exec.ts";
 import { isFileValue, fileContent } from "./secrets.ts";
 import { safeTenantSegment, systemInstallSh, SYSTEM_FROM_INPUT_SH, INSTALL_SOCKET, type RuntimeSpec } from "./runtime.ts";
+import { egressCaSh, type NetworkLevel } from "./network.ts";
 import type { ScriptSpec } from "./script-tools.ts";
 import type { ConsultSpec } from "./agent-tools.ts";
 import type { SubagentSpec } from "./subagents.ts";
@@ -77,6 +79,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 +177,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
@@ -659,6 +666,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
@@ -944,6 +952,7 @@ ${CORE_INSTALL}`;
 // reads the status file and fails the step with apt's own words.
 const ENTRY = `#!/bin/sh
 set +e
+${egressCaSh("/opt/runner/job")}
 ${SYSTEM_FROM_INPUT_SH}
 ${systemInstallSh(RUNTIME_CACHE)}
 ${INSTALL_HELPER_SH}
@@ -1107,7 +1116,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 {
@@ -1123,6 +1132,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") {
@@ -1193,6 +1203,10 @@ export interface RunInContainerArgs {
   input: ContainerStepInput;
   /** Secret + provider env — crosses as an env file, never argv. */
   env: Record<string, string>;
+  /** The step's network (network.ts), for an executor that can wall the
+   *  sandbox in itself: the k8s tier labels a filtered pod so its policy
+   *  admits the proxy and DNS alone. `enforced` false is report-only. */
+  network?: { level: NetworkLevel; enforced: boolean };
   emit: (type: "text" | "tool" | "info" | "error", text: string, extra?: EventExtra) => void;
   /** The run this step belongs to. Stamped on the sandbox as a label so a
    *  person stopping the run can reach the thing actually burning money —