@foldrun/core 2.6.0 → 2.7.0

package/dist/src/capture.js

@@ -6,7 +6,7 @@
 // secret on the cap's edge is never kept half. Recording never fails the step.
 import { redactText } from "./scan.js";
 import { writeCapturedCall, CAPTURE_CAP } from "./store.js";
-import { isFileValue, fileContent } from "./secrets.js";
+import { isFileValue, fileContent, isApiValue, apiConfigOf, isClientCertValue, clientCertOf } from "./secrets.js";
 /** How much past the cap a step sends, so masking sees a secret whole
  *  before the cut (a value longer than this is a file secret, which is also
  *  masked line by line). */
@@ -29,6 +29,44 @@ export function redactionsFor(secrets) {
     for (const [name, raw] of Object.entries(secrets)) {
         if (typeof raw !== "string")
             continue;
+        // An API connection's header values are each a secret in their own right
+        // (a token, Basic credentials) — and a Basic header's password too.
+        // An exported client certificate's passphrase and private key reach the
+        // sandbox as files: each is masked, whole and line by line.
+        if (isClientCertValue(raw)) {
+            const c = clientCertOf(raw);
+            for (const v of [c.passphrase, c.key]) {
+                if (!v)
+                    continue;
+                add(v, name);
+                add(v.trim(), name);
+                const escaped = JSON.stringify(v).slice(1, -1);
+                if (escaped !== v)
+                    add(escaped, name);
+                for (const line of v.split(/\r?\n/))
+                    if (line.trim().length >= 16)
+                        add(line.trim(), name);
+            }
+        }
+        if (isApiValue(raw)) {
+            // Each as written and as JSON would escape it, like every value here.
+            const both = (v) => {
+                add(v, name);
+                const escaped = JSON.stringify(v).slice(1, -1);
+                if (escaped !== v)
+                    add(escaped, name);
+            };
+            for (const v of Object.values(apiConfigOf(raw).headers ?? {})) {
+                both(v);
+                const basic = /^Basic\s+([A-Za-z0-9+/=]+)$/i.exec(v.trim());
+                if (basic) {
+                    both(basic[1]);
+                    const decoded = Buffer.from(basic[1], "base64").toString("utf8");
+                    if (decoded.includes(":"))
+                        both(decoded.slice(decoded.indexOf(":") + 1));
+                }
+            }
+        }
         for (const v of isFileValue(raw) ? [raw, fileContent(raw)] : [raw]) {
             add(v, name);
             add(v.trim(), name);

package/dist/src/egress.d.ts

@@ -27,6 +27,13 @@ export declare function hostOf(url: string): string | null;
  * from the step's declared secrets and the hosts its tools and provider
  * name; the proxy enforces it per request.
  */
+/** Which workload a lease is for — the runner's word, never the pod's: what
+ *  an identity token's subject is built from (oidc-issuer.ts). */
+export interface LeaseWho {
+    workspace: string;
+    agent: string;
+    flow?: string;
+}
 export interface EgressGrant {
     /** Secret name → the hosts that secret may be substituted for. */
     secrets: Record<string, {
@@ -53,6 +60,11 @@ export interface EgressGrant {
     /** Refuse a site off the list (true), or allow it and name it in the
      *  trace (false: report only). Set by the platform when it leases. */
     enforce?: boolean;
+    /** Identity name → the audience its tokens are for: the only identities
+     *  this step may ask the proxy's /identity door to mint (oidc-issuer.ts). */
+    identities?: Record<string, {
+        audience: string;
+    }>;
 }
 export interface EgressLease {
     /** The base the pod sends through: `http://…/e/<token>`. */
@@ -105,7 +117,11 @@ export interface EgressHooks {
         step?: number;
         agent?: string;
         peers?: PeerInfo[];
+        who?: LeaseWho;
     }): Promise<EgressLease | null>;
+    /** The run is still being driven: renew its leases' heartbeat. Optional —
+     *  an install without leases has nothing to renew. */
+    renew?(runId: string): Promise<number>;
     /** The step is over — every attempt, however it ended (tools: [peers]).
      *  A lease comes and goes per attempt, so it cannot say this: a sibling
      *  between retries, or waiting for a slot, holds none and is not done.

package/dist/src/run-container.d.ts

@@ -289,7 +289,7 @@ export declare function runtimeCacheMount(tenant: string | undefined): {
     target: string;
 } | null;
 /** The runner container's entrypoint, as JS text: written into the image as driver.mjs, so it must be plain JS — a TypeScript cast here broke every step on v2026.10.21.5 (tests/run-container.test.ts checks it). */
-export declare const DRIVER = "// The runner container's entrypoint. Reads one step, executes it with the\n// same core the server uses, speaks JSONL on stdout, exits.\nimport fs from \"node:fs\";\nconst input = JSON.parse(fs.readFileSync(\"/opt/runner/job/input.json\", \"utf8\"));\n// Start-up marks (run-container.ts#STARTUP_PHASES): which phase just ended,\n// on the sandbox's clock. A worker that does not know a mark skips the line.\nconst mark = (name) => process.stdout.write(JSON.stringify({ e: \"mark\", name, at: Date.now() }) + \"\\n\");\nmark(\"driver\");\nlet modelSpoke = false;\nconst emit = (type, text, extra) => {\n  // The model's first text or tool call is where start-up ends and the\n  // step's own work begins \u2014 runtime and tool lines before it are set-up.\n  if (!modelSpoke && (type === \"text\" || type === \"tool\")) { modelSpoke = true; mark(\"model\"); }\n  process.stdout.write(JSON.stringify({ e: \"event\", type, text, ...extra }) + \"\\n\");\n};\n// What this sandbox actually touched, read at the last moment from the\n// kernel's own books: cgroup v2 for CPU busy-time and peak memory,\n// /proc/net/dev for bytes on the wire. Every read is best-effort \u2014 gVisor\n// exposes some of these files and not others depending on version, and a\n// metric we cannot read is null, never guessed. Reservation is what is\n// billed; these exist so the reservation can be right-sized.\nfunction readActuals() {\n  // fs from the module's own import \u2014 the driver is ESM, and a require()\n  // here threw on every call, silently nulling every metric it guarded.\n  const read = (p) => { try { return fs.readFileSync(p, \"utf8\"); } catch { return null; } };\n  // Two cgroup dialects: v2 (cpu.stat, microseconds; memory.peak) on a\n  // plain runtime, v1-style controllers under gVisor (cpuacct.usage,\n  // NANOseconds; memory.max_usage_in_bytes) \u2014 probed on the real cluster,\n  // not assumed. Whichever answers wins; both silent means null.\n  const cpuStat = read(\"/sys/fs/cgroup/cpu.stat\");\n  const usage = cpuStat?.match(/^usage_usec (\\d+)/m);\n  const cpuacctNs = usage ? NaN : Number(read(\"/sys/fs/cgroup/cpuacct/cpuacct.usage\")?.trim());\n  const peak =\n    read(\"/sys/fs/cgroup/memory.peak\") ??\n    read(\"/sys/fs/cgroup/memory/memory.max_usage_in_bytes\") ??\n    read(\"/sys/fs/cgroup/memory/memory.usage_in_bytes\");\n  let rx = 0, tx = 0, sawNet = false;\n  const net = read(\"/proc/net/dev\");\n  if (net) {\n    for (const line of net.split(\"\\n\").slice(2)) {\n      const m = line.trim().match(/^(\\S+):\\s+(\\d+)(?:\\s+\\d+){7}\\s+(\\d+)/);\n      if (m && m[1] !== \"lo\") { rx += Number(m[2]); tx += Number(m[3]); sawNet = true; }\n    }\n  }\n  return {\n    busyCpuSecs: usage\n      ? Number(usage[1]) / 1e6\n      : Number.isFinite(cpuacctNs) && cpuacctNs > 0\n        ? cpuacctNs / 1e9\n        : null,\n    peakMemBytes: peak ? Number(peak.trim()) || null : null,\n    rxBytes: sawNet ? rx : null,\n    txBytes: sawNet ? tx : null,\n  };\n}\n\ntry {\n  // Runtime state (venvs, npm prefixes) lands in the agent user's real home\n  // \u2014 writable, inside the container, gone with it.\n  process.env.FOLDRUN_DATA = \"/home/agent/.foldrun\";\n  const { executeStep } = await import(\"@foldrun/core/step-exec\");\n  const { buildApiTools } = await import(\"@foldrun/core/api-tools\");\n  const { buildScriptTools } = await import(\"@foldrun/core/script-tools\");\n  const { buildConsultTools } = await import(\"@foldrun/core/agent-tools\");\n  const { buildSearchTools, buildHistoryTools, buildDeskTools } = await import(\"@foldrun/core/context-tools\");\n  const { httpChannel, buildAskTool, buildPeerTools, inboxReader } = await import(\"@foldrun/core/operator\");\n  const { startTranslator } = await import(\"@foldrun/core/translator\");\n  const { prepareRuntime } = await import(\"@foldrun/core/runtime\");\n  const { materializeFileSecrets } = await import(\"@foldrun/core/secret-files\");\n  const { paidWebActions } = await import(\"@foldrun/core/browser-pod\");\n  mark(\"imports\");\n\n  const agentDir = \"/workspace/\" + input.agentRel;\n  // HOME is where a bare relative path lands when anything resolves one\n  // outside cwd \u2014 and root's /root is outside the workspace, so such a read\n  // was refused by confinement with a path the agent never typed. Its own\n  // directory is both the truthful answer and the safe one.\n  // @file secrets crossed as content; materialise them to 0600 paths inside\n  // the container (a host path from the other side would not exist here).\n  const env = materializeFileSecrets(agentDir, { ...process.env, HOME: agentDir }).env;\n  // Caches go to the sandbox user's own home, not to HOME: the Claude CLI's\n  // logs, fontconfig, Mesa and gstreamer all follow XDG_CACHE_HOME, and under\n  // agents/<name>/.cache they were copied back after every step \u2014 3,855 files\n  // across 179 agent folders on the box by 17 Oct 2026, read by nothing.\n  env.XDG_CACHE_HOME = \"/home/agent/.cache\";\n\n  // The declared runtime, built in here \u2014 pip and npm have the network, which\n  // the host side may not. It lands in .foldrun/runner/.runtimes, which the\n  // executors mount from a per-tenant directory (run-container.ts#RUNTIME_CACHE):\n  // the first step for a given fingerprint installs, every later one finds\n  // .ready and skips. With no mount it still works, just fresh every time \u2014\n  // which is what this used to be unconditionally. The log says which happened.\n  const runtime = input.runtime\n    ? prepareRuntime(\"runner\", input.runtime)\n    : { interpreters: {}, env: {}, log: [], error: null };\n  for (const line of runtime.log) emit(\"info\", \"runtime: \" + line);\n  if (runtime.error) emit(\"error\", \"runtime: \" + runtime.error);\n  // The step's own environment gets it too, not only the script tools: an\n  // agent that runs \"python3 x.py\" or a shebang script through Bash should\n  // meet the packages its runtime declared, not the image's bare python.\n  Object.assign(env, runtime.env);\n\n  // install: what the agent finds it needs mid-step. apt goes through the\n  // root start-up's helper (install-helper.ts); pip and npm land in a\n  // directory of this container's own, on the paths from the first turn.\n  const { buildInstallTool, INSTALL_TOOL } = await import(\"@foldrun/core/install-tool\");\n  const { stepInstallEnv, INSTALL_SOCKET } = await import(\"@foldrun/core/runtime\");\n  const installDir = \"/home/agent/.foldrun/step\";\n  const installing = (input.allowed ?? []).includes(INSTALL_TOOL);\n  if (installing) Object.assign(env, stepInstallEnv(installDir, env));\n  const install = installing\n    ? buildInstallTool({\n        dir: installDir,\n        socket: env.FOLDRUN_INSTALL_SOCKET || INSTALL_SOCKET,\n        cacheRoot: \"/home/agent/.foldrun/runner/.runtimes\",\n        python: env.VIRTUAL_ENV ? env.VIRTUAL_ENV + \"/bin/python\" : \"python3\",\n        env,\n        emit,\n      })\n    : { server: null };\n\n  // API and script tools, rebuilt in here from their specs. Secrets were\n  // substituted into API headers before the input crossed the boundary, so\n  // buildApiTools gets an already-resolved environment. verify: gets the\n  // container's own environment, whole: it is the boundary, assembled on\n  // the host from an allowlist, and the declared secrets are in it.\n  // A long result is kept in a file only when the agent can read it back.\n  // (tool-output.ts canReadBack, inlined: the driver imports core by subpath.)\n  const keepIn = { dir: agentDir, readable: () => (input.allowed ?? []).some((t) => t === \"Read\" || t === \"Grep\") };\n  // A declared secret named like a model variable crosses as\n  // FOLDRUN_DECLARED_<NAME> (runner.ts, FOL-19): the model keeps its own\n  // settings, and the agent's API and script tools and verify: get the value\n  // back under the name it declared. Built here, after the runtime and any\n  // mid-step install have added their paths to env.\n  const toolEnv = { ...env };\n  for (const [k, v] of Object.entries(env)) if (k.startsWith(\"FOLDRUN_DECLARED_\")) toolEnv[k.slice(\"FOLDRUN_DECLARED_\".length)] = v;\n  const api = buildApiTools(\"\", input.apis, undefined, { env: toolEnv, missing: [] }, keepIn);\n  const script = buildScriptTools(\n    agentDir,\n    input.scripts,\n    toolEnv,\n    \"/library/scripts\",\n    runtime.interpreters,\n    null,\n    keepIn.readable,\n  );\n  // The translator, when the provider speaks Chat Completions: a loopback\n  // server for the length of this step. Its env replaces the endpoint the\n  // host assembled; the provider's real URL and key stay inside it.\n  const translator = input.translator ? await startTranslator(input.translator) : null;\n  if (translator) {\n    Object.assign(env, translator.env);\n    emit(\"info\", \"translator: listening on \" + translator.baseUrl + \" for \" + (input.translator.label ?? input.translator.upstreamBase));\n  }\n  const consult = buildConsultTools(input.consults ?? [], env, emit);\n  // The platform's own two groups, rebuilt from values like everything else.\n  const search = buildSearchTools(input.search ?? []);\n  const history = input.history?.length ? buildHistoryTools(input.history) : { server: null };\n  const desks = input.desks?.length ? buildDeskTools(input.desks) : { server: null };\n  // A person in the loop, over the proxy this step's lease already names:\n  // ask_person when tools: [ask], and the run's inbox after every tool call.\n  const channel = httpChannel(env.FOLDRUN_EGRESS);\n  const ask = input.ask ? buildAskTool({ channel, timeoutSec: input.ask.timeoutSec, emit }) : { server: null };\n  const peers = input.peers ? buildPeerTools({ channel, self: input.peers.self, siblings: input.peers.siblings, emit }) : { server: null };\n  const inbox = channel ? inboxReader(channel, emit) : undefined;\n\n  mark(\"tools\");\n  const outcome = await executeStep({\n    agentDir,\n    workspaceRoot: \"/workspace\",\n    libraryRoot: \"/library\",\n    prompt: input.prompt,\n    model: input.model,\n    effort: input.effort ?? null,\n    systemPrompt: input.systemPrompt,\n    allowed: input.allowed,\n    mcpNames: input.mcpNames,\n    mcpServers: {\n      ...(api.server ? { foldrun_apis: api.server } : {}),\n      ...(script.server ? { foldrun_scripts: script.server } : {}),\n      ...(consult.server ? { foldrun_agents: consult.server } : {}),\n      ...(search.server ? { foldrun_search: search.server } : {}),\n      ...(history.server ? { foldrun_history: history.server } : {}),\n      ...(desks.server ? { foldrun_desks: desks.server } : {}),\n      ...(ask.server ? { foldrun_ask: ask.server } : {}),\n      ...(peers.server ? { foldrun_peers: peers.server } : {}),\n      ...(install.server ? { foldrun_install: install.server } : {}),\n      ...input.mcpServers,\n    },\n    ...(inbox ? { inbox } : {}),\n    ...(input.subagents?.length ? { subagents: input.subagents } : {}),\n    env,\n    timeoutSec: input.timeoutSec,\n    budgetUsd: input.budgetUsd,\n    budgetNote: input.budgetNote,\n    price: input.price,\n    verify: input.verify,\n    verifyEnv: toolEnv,\n    ...(typeof input.judgeModel === \"string\" ? { judgeModel: input.judgeModel } : {}),\n    ...(typeof input.judgeEffort === \"string\" ? { judgeEffort: input.judgeEffort } : {}),\n    output: input.output,\n    schema: input.schema,\n    maxTurns: input.maxTurns,\n    ...(input.capture === \"metadata\" || input.capture === \"full\" ? { capture: input.capture } : {}),\n    ...(input.limits && Object.keys(input.limits).length ? { limits: input.limits, toolOwners: input.toolOwners ?? {} } : {}),\n    ...(input.hookNames?.length ? { hookNames: input.hookNames, hookBase: input.hookBase ?? {} } : {}),\n    // Slim browsing: the platform put this step on the slim image to browse\n    // through the account's pod, and named the file the web tool logs its\n    // reconnects to. A lost pod stops the step; what it wrote decides what\n    // the runner does next (browser-pod.ts).\n    ...(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 } : {}) } } : {}),\n    // The container is the boundary; the SDK's own bash sandbox here would\n    // only block declared network use (SSH, curl) for no added safety.\n    sandboxBash: false,\n    emit,\n  });\n  for (const line of api.drainLog()) emit(\"info\", \"api: \" + line);\n  for (const line of script.drainLog()) emit(\"info\", \"script: \" + line);\n  if (translator) {\n    for (const line of translator.drainLog()) emit(\"info\", line.startsWith(\"translator\") ? line : \"translator: \" + line);\n    await translator.close();\n  }\n  // A consult's spend belongs to the step that asked.\n  const consultCost = consult.drainCost();\n  if (consultCost > 0) outcome.costUsd = (outcome.costUsd ?? 0) + consultCost;\n  if (consultCost > 0 && typeof outcome.turnsCostUsd === \"number\") outcome.turnsCostUsd += consultCost;\n  process.stdout.write(JSON.stringify({ e: \"done\", ...outcome, res: readActuals() }) + \"\\n\");\n  process.exit(0);\n} catch (err) {\n  emit(\"error\", err instanceof Error ? err.message : String(err));\n  // The failure path reports actuals too \u2014 a step that died eleven minutes\n  // in still held its slice for eleven minutes, and the failed runs are\n  // exactly the ones whose resource story gets read.\n  let res = null;\n  try { res = readActuals(); } catch { /* the reading must never mask the error */ }\n  process.stdout.write(JSON.stringify({ e: \"done\", status: \"failed\", result: null, costUsd: null, res }) + \"\\n\");\n  process.exit(0);\n}\n";
+export declare const DRIVER = "// The runner container's entrypoint. Reads one step, executes it with the\n// same core the server uses, speaks JSONL on stdout, exits.\nimport fs from \"node:fs\";\nconst input = JSON.parse(fs.readFileSync(\"/opt/runner/job/input.json\", \"utf8\"));\n// Start-up marks (run-container.ts#STARTUP_PHASES): which phase just ended,\n// on the sandbox's clock. A worker that does not know a mark skips the line.\nconst mark = (name) => process.stdout.write(JSON.stringify({ e: \"mark\", name, at: Date.now() }) + \"\\n\");\nmark(\"driver\");\nlet modelSpoke = false;\nconst emit = (type, text, extra) => {\n  // The model's first text or tool call is where start-up ends and the\n  // step's own work begins \u2014 runtime and tool lines before it are set-up.\n  if (!modelSpoke && (type === \"text\" || type === \"tool\")) { modelSpoke = true; mark(\"model\"); }\n  process.stdout.write(JSON.stringify({ e: \"event\", type, text, ...extra }) + \"\\n\");\n};\n// What this sandbox actually touched, read at the last moment from the\n// kernel's own books: cgroup v2 for CPU busy-time and peak memory,\n// /proc/net/dev for bytes on the wire. Every read is best-effort \u2014 gVisor\n// exposes some of these files and not others depending on version, and a\n// metric we cannot read is null, never guessed. Reservation is what is\n// billed; these exist so the reservation can be right-sized.\nfunction readActuals() {\n  // fs from the module's own import \u2014 the driver is ESM, and a require()\n  // here threw on every call, silently nulling every metric it guarded.\n  const read = (p) => { try { return fs.readFileSync(p, \"utf8\"); } catch { return null; } };\n  // Two cgroup dialects: v2 (cpu.stat, microseconds; memory.peak) on a\n  // plain runtime, v1-style controllers under gVisor (cpuacct.usage,\n  // NANOseconds; memory.max_usage_in_bytes) \u2014 probed on the real cluster,\n  // not assumed. Whichever answers wins; both silent means null.\n  const cpuStat = read(\"/sys/fs/cgroup/cpu.stat\");\n  const usage = cpuStat?.match(/^usage_usec (\\d+)/m);\n  const cpuacctNs = usage ? NaN : Number(read(\"/sys/fs/cgroup/cpuacct/cpuacct.usage\")?.trim());\n  const peak =\n    read(\"/sys/fs/cgroup/memory.peak\") ??\n    read(\"/sys/fs/cgroup/memory/memory.max_usage_in_bytes\") ??\n    read(\"/sys/fs/cgroup/memory/memory.usage_in_bytes\");\n  let rx = 0, tx = 0, sawNet = false;\n  const net = read(\"/proc/net/dev\");\n  if (net) {\n    for (const line of net.split(\"\\n\").slice(2)) {\n      const m = line.trim().match(/^(\\S+):\\s+(\\d+)(?:\\s+\\d+){7}\\s+(\\d+)/);\n      if (m && m[1] !== \"lo\") { rx += Number(m[2]); tx += Number(m[3]); sawNet = true; }\n    }\n  }\n  return {\n    busyCpuSecs: usage\n      ? Number(usage[1]) / 1e6\n      : Number.isFinite(cpuacctNs) && cpuacctNs > 0\n        ? cpuacctNs / 1e9\n        : null,\n    peakMemBytes: peak ? Number(peak.trim()) || null : null,\n    rxBytes: sawNet ? rx : null,\n    txBytes: sawNet ? tx : null,\n  };\n}\n\ntry {\n  // Runtime state (venvs, npm prefixes) lands in the agent user's real home\n  // \u2014 writable, inside the container, gone with it.\n  process.env.FOLDRUN_DATA = \"/home/agent/.foldrun\";\n  const { executeStep } = await import(\"@foldrun/core/step-exec\");\n  const { buildApiTools } = await import(\"@foldrun/core/api-tools\");\n  const { buildScriptTools } = await import(\"@foldrun/core/script-tools\");\n  const { buildConsultTools } = await import(\"@foldrun/core/agent-tools\");\n  const { buildSearchTools, buildHistoryTools, buildDeskTools } = await import(\"@foldrun/core/context-tools\");\n  const { httpChannel, buildAskTool, buildPeerTools, inboxReader } = await import(\"@foldrun/core/operator\");\n  const { startTranslator } = await import(\"@foldrun/core/translator\");\n  const { prepareRuntime } = await import(\"@foldrun/core/runtime\");\n  const { materializeFileSecrets } = await import(\"@foldrun/core/secret-files\");\n  const { paidWebActions } = await import(\"@foldrun/core/browser-pod\");\n  mark(\"imports\");\n\n  const agentDir = \"/workspace/\" + input.agentRel;\n  // HOME is where a bare relative path lands when anything resolves one\n  // outside cwd \u2014 and root's /root is outside the workspace, so such a read\n  // was refused by confinement with a path the agent never typed. Its own\n  // directory is both the truthful answer and the safe one.\n  // @file secrets crossed as content; materialise them to 0600 paths inside\n  // the container (a host path from the other side would not exist here).\n  const env = materializeFileSecrets(agentDir, { ...process.env, HOME: agentDir }).env;\n  // Caches go to the sandbox user's own home, not to HOME: the Claude CLI's\n  // logs, fontconfig, Mesa and gstreamer all follow XDG_CACHE_HOME, and under\n  // agents/<name>/.cache they were copied back after every step \u2014 3,855 files\n  // across 179 agent folders on the box by 17 Oct 2026, read by nothing.\n  env.XDG_CACHE_HOME = \"/home/agent/.cache\";\n\n  // The declared runtime, built in here \u2014 pip and npm have the network, which\n  // the host side may not. It lands in .foldrun/runner/.runtimes, which the\n  // executors mount from a per-tenant directory (run-container.ts#RUNTIME_CACHE):\n  // the first step for a given fingerprint installs, every later one finds\n  // .ready and skips. With no mount it still works, just fresh every time \u2014\n  // which is what this used to be unconditionally. The log says which happened.\n  const runtime = input.runtime\n    ? prepareRuntime(\"runner\", input.runtime)\n    : { interpreters: {}, env: {}, log: [], error: null };\n  for (const line of runtime.log) emit(\"info\", \"runtime: \" + line);\n  if (runtime.error) emit(\"error\", \"runtime: \" + runtime.error);\n  // The step's own environment gets it too, not only the script tools: an\n  // agent that runs \"python3 x.py\" or a shebang script through Bash should\n  // meet the packages its runtime declared, not the image's bare python.\n  Object.assign(env, runtime.env);\n\n  // install: what the agent finds it needs mid-step. apt goes through the\n  // root start-up's helper (install-helper.ts); pip and npm land in a\n  // directory of this container's own, on the paths from the first turn.\n  const { buildInstallTool, INSTALL_TOOL } = await import(\"@foldrun/core/install-tool\");\n  const { stepInstallEnv, INSTALL_SOCKET } = await import(\"@foldrun/core/runtime\");\n  const installDir = \"/home/agent/.foldrun/step\";\n  const installing = (input.allowed ?? []).includes(INSTALL_TOOL);\n  if (installing) Object.assign(env, stepInstallEnv(installDir, env));\n  const install = installing\n    ? buildInstallTool({\n        dir: installDir,\n        socket: env.FOLDRUN_INSTALL_SOCKET || INSTALL_SOCKET,\n        cacheRoot: \"/home/agent/.foldrun/runner/.runtimes\",\n        python: env.VIRTUAL_ENV ? env.VIRTUAL_ENV + \"/bin/python\" : \"python3\",\n        env,\n        emit,\n      })\n    : { server: null };\n\n  // API and script tools, rebuilt in here from their specs. Secrets were\n  // substituted into API headers before the input crossed the boundary, so\n  // buildApiTools gets an already-resolved environment. verify: gets the\n  // container's own environment, whole: it is the boundary, assembled on\n  // the host from an allowlist, and the declared secrets are in it.\n  // A long result is kept in a file only when the agent can read it back.\n  // (tool-output.ts canReadBack, inlined: the driver imports core by subpath.)\n  const keepIn = { dir: agentDir, readable: () => (input.allowed ?? []).some((t) => t === \"Read\" || t === \"Grep\") };\n  // A declared secret named like a model variable crosses as\n  // FOLDRUN_DECLARED_<NAME> (runner.ts, FOL-19): the model keeps its own\n  // settings, and the agent's API and script tools and verify: get the value\n  // back under the name it declared. Built here, after the runtime and any\n  // mid-step install have added their paths to env.\n  const toolEnv = { ...env };\n  for (const [k, v] of Object.entries(env)) if (k.startsWith(\"FOLDRUN_DECLARED_\")) toolEnv[k.slice(\"FOLDRUN_DECLARED_\".length)] = v;\n  const api = buildApiTools(\"\", input.apis, undefined, { env: toolEnv, missing: [] }, keepIn);\n  const script = buildScriptTools(\n    agentDir,\n    input.scripts,\n    toolEnv,\n    \"/library/scripts\",\n    runtime.interpreters,\n    null,\n    keepIn.readable,\n  );\n  // The translator, when the provider speaks Chat Completions: a loopback\n  // server for the length of this step. Its env replaces the endpoint the\n  // host assembled; the provider's real URL and key stay inside it.\n  const translator = input.translator ? await startTranslator(input.translator) : null;\n  if (translator) {\n    Object.assign(env, translator.env);\n    emit(\"info\", \"translator: listening on \" + translator.baseUrl + \" for \" + (input.translator.label ?? input.translator.upstreamBase));\n  }\n  const consult = buildConsultTools(input.consults ?? [], env, emit);\n  // The platform's own two groups, rebuilt from values like everything else.\n  const search = buildSearchTools(input.search ?? []);\n  const history = input.history?.length ? buildHistoryTools(input.history) : { server: null };\n  const desks = input.desks?.length ? buildDeskTools(input.desks) : { server: null };\n  // A person in the loop, over the proxy this step's lease already names:\n  // ask_person when tools: [ask], and the run's inbox after every tool call.\n  const channel = httpChannel(env.FOLDRUN_EGRESS);\n  const ask = input.ask ? buildAskTool({ channel, timeoutSec: input.ask.timeoutSec, emit }) : { server: null };\n  const peers = input.peers ? buildPeerTools({ channel, self: input.peers.self, siblings: input.peers.siblings, emit }) : { server: null };\n  const inbox = channel ? inboxReader(channel, emit) : undefined;\n\n  // Keyless cloud identities (FOLDRUN_IDENTITIES): each token file kept\n  // fresh through the proxy's /identity door, which mints only what this\n  // step's lease was granted. Fetched before the step starts, renewed five\n  // minutes before it expires (with jitter); a failure is said and retried.\n  // Plain JS: this text is the driver, not TypeScript.\n  const identityNames = (env.FOLDRUN_IDENTITIES || \"\").split(\",\").filter(Boolean);\n  if (identityNames.length) {\n    // No backslashes: this sits inside a template literal, which eats them.\n    const ep = new RegExp(\"^(https?://[^/]+)/e/([A-Za-z0-9_-]{16,})/?$\").exec(env.FOLDRUN_EGRESS || \"\");\n    const dir = env.FOLDRUN_IDENTITY_DIR || \"/tmp/foldrun-identity\";\n    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });\n    const keepFresh = async (name) => {\n      let wait = 30000;\n      try {\n        if (!ep) throw new Error(\"no egress proxy to ask\");\n        const res = await fetch(ep[1] + \"/identity/\" + ep[2] + \"/\" + name, { signal: AbortSignal.timeout(15000) });\n        const body = await res.json().catch(() => ({}));\n        if (!res.ok || !body.token) throw new Error((body.error && body.error.message) || (\"proxy answered \" + res.status));\n        const file = dir + \"/\" + name.toLowerCase() + \".jwt\";\n        fs.writeFileSync(file + \".tmp\", body.token, { mode: 0o600 });\n        fs.renameSync(file + \".tmp\", file);\n        wait = Math.max(30000, body.expiresAt - Date.now() - 300000 + Math.floor(Math.random() * 60000) - 30000);\n      } catch (err) {\n        emit(\"error\", \"identity \" + name + \": \" + (err && err.message ? err.message : String(err)) + \" \u2014 trying again in 30s\");\n      }\n      setTimeout(() => { void keepFresh(name); }, wait).unref();\n    };\n    await Promise.all(identityNames.map(keepFresh));\n  }\n\n  mark(\"tools\");\n  const outcome = await executeStep({\n    agentDir,\n    workspaceRoot: \"/workspace\",\n    libraryRoot: \"/library\",\n    prompt: input.prompt,\n    model: input.model,\n    effort: input.effort ?? null,\n    systemPrompt: input.systemPrompt,\n    allowed: input.allowed,\n    mcpNames: input.mcpNames,\n    mcpServers: {\n      ...(api.server ? { foldrun_apis: api.server } : {}),\n      ...(script.server ? { foldrun_scripts: script.server } : {}),\n      ...(consult.server ? { foldrun_agents: consult.server } : {}),\n      ...(search.server ? { foldrun_search: search.server } : {}),\n      ...(history.server ? { foldrun_history: history.server } : {}),\n      ...(desks.server ? { foldrun_desks: desks.server } : {}),\n      ...(ask.server ? { foldrun_ask: ask.server } : {}),\n      ...(peers.server ? { foldrun_peers: peers.server } : {}),\n      ...(install.server ? { foldrun_install: install.server } : {}),\n      ...input.mcpServers,\n    },\n    ...(inbox ? { inbox } : {}),\n    ...(input.subagents?.length ? { subagents: input.subagents } : {}),\n    env,\n    timeoutSec: input.timeoutSec,\n    budgetUsd: input.budgetUsd,\n    budgetNote: input.budgetNote,\n    price: input.price,\n    verify: input.verify,\n    verifyEnv: toolEnv,\n    ...(typeof input.judgeModel === \"string\" ? { judgeModel: input.judgeModel } : {}),\n    ...(typeof input.judgeEffort === \"string\" ? { judgeEffort: input.judgeEffort } : {}),\n    output: input.output,\n    schema: input.schema,\n    maxTurns: input.maxTurns,\n    ...(input.capture === \"metadata\" || input.capture === \"full\" ? { capture: input.capture } : {}),\n    ...(input.limits && Object.keys(input.limits).length ? { limits: input.limits, toolOwners: input.toolOwners ?? {} } : {}),\n    ...(input.hookNames?.length ? { hookNames: input.hookNames, hookBase: input.hookBase ?? {} } : {}),\n    // Slim browsing: the platform put this step on the slim image to browse\n    // through the account's pod, and named the file the web tool logs its\n    // reconnects to. A lost pod stops the step; what it wrote decides what\n    // the runner does next (browser-pod.ts).\n    ...(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 } : {}) } } : {}),\n    // The container is the boundary; the SDK's own bash sandbox here would\n    // only block declared network use (SSH, curl) for no added safety.\n    sandboxBash: false,\n    emit,\n  });\n  for (const line of api.drainLog()) emit(\"info\", \"api: \" + line);\n  for (const line of script.drainLog()) emit(\"info\", \"script: \" + line);\n  if (translator) {\n    for (const line of translator.drainLog()) emit(\"info\", line.startsWith(\"translator\") ? line : \"translator: \" + line);\n    await translator.close();\n  }\n  // A consult's spend belongs to the step that asked.\n  const consultCost = consult.drainCost();\n  if (consultCost > 0) outcome.costUsd = (outcome.costUsd ?? 0) + consultCost;\n  if (consultCost > 0 && typeof outcome.turnsCostUsd === \"number\") outcome.turnsCostUsd += consultCost;\n  process.stdout.write(JSON.stringify({ e: \"done\", ...outcome, res: readActuals() }) + \"\\n\");\n  process.exit(0);\n} catch (err) {\n  emit(\"error\", err instanceof Error ? err.message : String(err));\n  // The failure path reports actuals too \u2014 a step that died eleven minutes\n  // in still held its slice for eleven minutes, and the failed runs are\n  // exactly the ones whose resource story gets read.\n  let res = null;\n  try { res = readActuals(); } catch { /* the reading must never mask the error */ }\n  process.stdout.write(JSON.stringify({ e: \"done\", status: \"failed\", result: null, costUsd: null, res }) + \"\\n\");\n  process.exit(0);\n}\n";
 /** The uv release copied into the image. Pinned: a floating uv is a floating
  *  resolver, and the runtime cache is keyed on the declaration, not on it. */
 export declare const UV_VERSION = "0.11.25";

package/dist/src/run-container.js

@@ -577,6 +577,36 @@ try {
   const peers = input.peers ? buildPeerTools({ channel, self: input.peers.self, siblings: input.peers.siblings, emit }) : { server: null };
   const inbox = channel ? inboxReader(channel, emit) : undefined;
 
+  // Keyless cloud identities (FOLDRUN_IDENTITIES): each token file kept
+  // fresh through the proxy's /identity door, which mints only what this
+  // step's lease was granted. Fetched before the step starts, renewed five
+  // minutes before it expires (with jitter); a failure is said and retried.
+  // Plain JS: this text is the driver, not TypeScript.
+  const identityNames = (env.FOLDRUN_IDENTITIES || "").split(",").filter(Boolean);
+  if (identityNames.length) {
+    // No backslashes: this sits inside a template literal, which eats them.
+    const ep = new RegExp("^(https?://[^/]+)/e/([A-Za-z0-9_-]{16,})/?$").exec(env.FOLDRUN_EGRESS || "");
+    const dir = env.FOLDRUN_IDENTITY_DIR || "/tmp/foldrun-identity";
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const keepFresh = async (name) => {
+      let wait = 30000;
+      try {
+        if (!ep) throw new Error("no egress proxy to ask");
+        const res = await fetch(ep[1] + "/identity/" + ep[2] + "/" + name, { signal: AbortSignal.timeout(15000) });
+        const body = await res.json().catch(() => ({}));
+        if (!res.ok || !body.token) throw new Error((body.error && body.error.message) || ("proxy answered " + res.status));
+        const file = dir + "/" + name.toLowerCase() + ".jwt";
+        fs.writeFileSync(file + ".tmp", body.token, { mode: 0o600 });
+        fs.renameSync(file + ".tmp", file);
+        wait = Math.max(30000, body.expiresAt - Date.now() - 300000 + Math.floor(Math.random() * 60000) - 30000);
+      } catch (err) {
+        emit("error", "identity " + name + ": " + (err && err.message ? err.message : String(err)) + " — trying again in 30s");
+      }
+      setTimeout(() => { void keepFresh(name); }, wait).unref();
+    };
+    await Promise.all(identityNames.map(keepFresh));
+  }
+
   mark("tools");
   const outcome = await executeStep({
     agentDir,

package/dist/src/runner.js

@@ -41,7 +41,7 @@ import { accountDir, workspaceDir, buildMemoryIndex, workspaceMemoryIndex, knowl
 import { canReadBack } from "./tool-output.js";
 import { PromptLayers, promptCacheKey } from "./prompt-layers.js";
 import { loadCatalog, checkModel, clampEffort, catalogCost, findModel, tokenPriceOf } from "./catalog.js";
-import { resolveSecrets, getSecret, materializeSecrets, secretSites } from "./secrets.js";
+import { resolveSecrets, getSecret, materializeSecrets, secretSites, isClientCertValue, clientCertOf, withoutHeldCerts, isIdentityValue, identityOf } from "./secrets.js";
 import { resolveNetwork, networkLine, networkEnforceWanted, proxyEnv, EGRESS_CA_ENV } from "./network.js";
 import { materializeFileSecrets, cleanupFileSecrets } from "./secret-files.js";
 import { buildApiTools, secretsUsedByApi } from "./api-tools.js";
@@ -1348,7 +1348,8 @@ grantsOnly = false) {
     // the agent, and the date the platform believes it is.
     {
         ...runtime.env,
-        ...secretEnv,
+        // An unexported client certificate is the proxy's, never a script's.
+        ...withoutHeldCerts(secretEnv),
         ...(identity.runId ? { FOLDRUN_RUN_ID: identity.runId } : {}),
         ...(identity.agent ? { FOLDRUN_AGENT: identity.agent } : {}),
         // And the workspace: a commit or a record made by a shared library
@@ -1618,6 +1619,9 @@ grantsOnly = false) {
         // asked for by name fails inside the container with "cannot find" while
         // the host path, which uses this same merged spec, works fine.
         runtime: { log: runtimeLog, error: runtimeError, executor, spec: runtimeSpec, dispose: runtime.dispose },
+        // Whole: a bound client certificate goes from here into the egress
+        // grant (runStep), which is where it is presented. Programs get theirs
+        // filtered (withoutHeldCerts) where their environments are built.
         secretEnv: { ...runtime.env, ...secretEnv },
         formatWarning: checkFormatVersion(workspaceFrontmatter(agentDir, tenant).foldrun_version).warning,
         providerEnv,
@@ -2490,11 +2494,26 @@ peerBus) {
             // to refuse; the proxy adds the install's own switch and has the last
             // word (egress-proxy.ts), so false here never loosens anything.
             grant.enforce = networkEnforceWanted(readAgentsMd(accountDir(tenant))?.data?.network_enforce, readAgentsMd(workspaceRootOf(agentDir))?.data?.network_enforce);
+            // Keyless cloud identities the step declared: the proxy may mint tokens
+            // for these audiences only, for this workload (oidc-issuer.ts).
+            // A test run withholds them as it withholds every credential
+            // (test-mode.ts): a token is a credential, however it is delivered.
+            const declaredIdentities = Object.entries(liveSecrets).filter(([, v]) => typeof v === "string" && isIdentityValue(v));
+            const identitiesHeld = testRun
+                ? withholdSecrets(Object.fromEntries(declaredIdentities), {
+                    outward: scriptSpecs.some((sc) => sc.outward),
+                    allow: scriptSpecs.some((sc) => sc.testMode === "allow"),
+                }).withheld
+                : [];
+            const identities = Object.fromEntries(declaredIdentities.filter(([name]) => !identitiesHeld.includes(name)).map(([name, v]) => [name, { audience: identityOf(v).audience }]));
+            if (Object.keys(identities).length)
+                grant.identities = identities;
             const lease = await platform.egress.lease({
                 tenant,
                 runId: runId ?? "adhoc",
                 grant,
                 test: testRun,
+                who: { workspace: workspaceName, agent: step.agent },
                 ...(stepIndex !== undefined && stepIndex >= 0 ? { step: stepIndex } : {}),
                 // tools: [peers] — the roster the proxy serves, and the inboxes a
                 // colleague's message may be addressed to. Only when granted: a
@@ -2565,6 +2584,38 @@ peerBus) {
                     push("info", `test: ${name} withheld from the sandbox — TEST_MODE_WITHHELD`, { effect: { kind: "withheld", summary: `${name} withheld from the sandbox` } });
                 }
             }
+            // A keyless identity holds nothing to hand over: the sandbox gets the
+            // path of a token file the driver keeps fresh through the proxy's
+            // /identity door. Without a lease there is no door, and so no token.
+            const identityDeclared = declared.filter((name) => typeof liveSecrets[name] === "string" && isIdentityValue(liveSecrets[name]));
+            for (const name of identityDeclared)
+                delete sandboxSecrets[name];
+            for (const name of identitiesHeld) {
+                push("info", `test: ${name} withheld — no identity token on a test run`, { effect: { kind: "withheld", summary: `${name} withheld from the sandbox` } });
+            }
+            const identityNames = identityDeclared.filter((name) => !identitiesHeld.includes(name));
+            if (identityNames.length) {
+                if (lease) {
+                    const dir = "/tmp/foldrun-identity";
+                    sandboxSecrets.FOLDRUN_IDENTITIES = identityNames.join(",");
+                    sandboxSecrets.FOLDRUN_IDENTITY_DIR = dir;
+                    for (const name of identityNames)
+                        sandboxSecrets[`${name}_FILE`] = `${dir}/${name.toLowerCase()}.jwt`;
+                    push("info", `identity: ${identityNames.join(", ")} — a short-lived token in $NAME_FILE, renewed by the platform while the step runs`);
+                }
+                else {
+                    push("error", `identity: ${identityNames.join(", ")} needs a sandboxed step on the platform — no token here`);
+                }
+            }
+            // A client certificate is the proxy's to present, to the exact sites it
+            // is bound to; never the sandbox's, unless it was saved with `export`.
+            for (const name of declared) {
+                const v = liveSecrets[name];
+                if (typeof v !== "string" || !isClientCertValue(v) || bound.includes(name) || clientCertOf(v).export)
+                    continue;
+                delete sandboxSecrets[name];
+                push("info", `secrets: ${name} is a client certificate — the egress proxy presents it to the sites it is bound to (\`foldrun secrets sites ${name} <host>\`); unbound, it stays out of the sandbox`);
+            }
             // On a test run the http tools always go through the proxy as
             // placeholders, even when a script made the step materialise: the
             // proxy is where the outward-write policy lives, and a header
@@ -2966,7 +3017,19 @@ peerBus) {
             for (const name of held.withheld) {
                 push("info", `test: ${name} withheld from scripts — TEST_MODE_WITHHELD`, { effect: { kind: "withheld", summary: `${name} withheld from scripts` } });
             }
-            const stepSecrets = held.env;
+            // A client certificate not saved with `export` has no proxy here to
+            // present it: it stays out of everything this step runs — tools,
+            // consults, verify commands — not only out of the files.
+            const stepSecrets = Object.fromEntries(Object.entries(held.env).filter(([name, v]) => {
+                if (typeof v === "string" && isIdentityValue(v)) {
+                    push("error", `identity: ${name} needs a sandboxed step on the platform — no token here`);
+                    return false;
+                }
+                if (typeof v !== "string" || !isClientCertValue(v) || clientCertOf(v).export)
+                    return true;
+                push("info", `secrets: ${name} is a client certificate — no egress proxy here to present it; save it with export to use it as files`);
+                return false;
+            }));
             // The model credential for this machine's Claude Code — the agent's
             // own provider when it names one. The host allowlist drops it, so
             // without this every in-process step ran on the machine's login.
@@ -3804,7 +3867,15 @@ async function harvestQuietly(tenant, workspace, run) {
 export const drivingRuns = new Set();
 export function driveRun(tenant, workspace, run, modelOverride, tags = [], opts = {}) {
     drivingRuns.add(run.id);
+    // The run's egress leases are renewed while it is driven, by whichever
+    // door drove it — the queue, or a reconcile that picked it back up — so an
+    // identity token is renewed for a live step however it was started.
+    const renew = platform.egress.renew;
+    const beat = renew ? setInterval(() => void renew(run.id).catch(() => undefined), 5 * 60_000) : null;
+    beat?.unref?.();
     return driveRunInner(tenant, workspace, run, modelOverride, tags, opts).finally(() => {
+        if (beat)
+            clearInterval(beat);
         drivingRuns.delete(run.id);
     });
 }

package/dist/src/secret-files.js

@@ -17,7 +17,7 @@
 // deleted the keys the other was still using.
 import fs from "node:fs";
 import path from "node:path";
-import { isFileValue, fileContent, isSshValue, sshConfigOf, isApiValue, apiConfigOf, } from "./secrets.js";
+import { isFileValue, fileContent, isSshValue, sshConfigOf, isApiValue, apiConfigOf, isClientCertValue, clientCertOf, } from "./secrets.js";
 // POSIX single-quoting: the one escape sh actually honours inside ' is none,
 // so close, backslash-quote, reopen. Wrapper scripts embed hosts, users and
 // header values through this and nothing else.
@@ -34,7 +34,7 @@ function writeWrapper(dir, name, body) {
  * Plain values pass through untouched.
  */
 export function materializeFileSecrets(agentDir, env) {
-    const entries = Object.entries(env).filter(([, v]) => typeof v === "string" && (isFileValue(v) || isSshValue(v) || isApiValue(v)));
+    const entries = Object.entries(env).filter(([, v]) => typeof v === "string" && (isFileValue(v) || isSshValue(v) || isApiValue(v) || isClientCertValue(v)));
     if (entries.length === 0)
         return { env, dir: null };
     const parent = path.join(agentDir, ".secret-files");
@@ -50,6 +50,27 @@ export function materializeFileSecrets(agentDir, env) {
             fs.writeFileSync(file, fileContent(value), { mode: 0o600 });
             out[name] = file;
         }
+        else if (isClientCertValue(value)) {
+            // Only an exported certificate reaches here as itself (the runner
+            // withholds the rest): its parts as files, $NAME the certificate.
+            const c = clientCertOf(value);
+            if (!c.export) {
+                delete out[name];
+                continue;
+            }
+            const cert = path.join(dir, `${name.toLowerCase()}.crt`);
+            const key = path.join(dir, `${name.toLowerCase()}.key`);
+            fs.writeFileSync(cert, c.cert, { mode: 0o600 });
+            fs.writeFileSync(key, c.key, { mode: 0o600 });
+            out[name] = cert;
+            out[`${name}_CERT`] = cert;
+            out[`${name}_KEY`] = key;
+            if (c.passphrase) {
+                const pass = path.join(dir, `${name.toLowerCase()}.pass`);
+                fs.writeFileSync(pass, c.passphrase, { mode: 0o600 });
+                out[`${name}_PASSPHRASE_FILE`] = pass;
+            }
+        }
         else if (isSshValue(value)) {
             const ssh = sshConfigOf(value);
             const dest = `${ssh.user}@${ssh.host}`;

package/dist/src/secrets.d.ts

@@ -15,7 +15,7 @@ export declare function installKeyMaterial(): string;
 /** How the stored value is used at run time — "oauth2"/"service-account"
  *  are refreshed into live tokens, "file"/"ssh"/"api" are materialised into
  *  the run's scratch. Plain values have no kind. */
-export type SecretKind = "oauth2" | "service-account" | "file" | "ssh" | "api";
+export type SecretKind = "oauth2" | "service-account" | "file" | "ssh" | "api" | "client-cert" | "identity";
 interface StoredSecret {
     iv: string;
     tag: string;
@@ -133,7 +133,9 @@ export declare function rotateMasterKey(tenant: string, from: string, to: string
 export interface OAuth2Config {
     token_url: string;
     client_id: string;
-    client_secret: string;
+    /** Absent for a public client (an app with no secret, connected with
+     *  PKCE): its refresh sends client_id and refresh_token only. */
+    client_secret?: string;
     /** Required for the refresh grant; absent for client_credentials. */
     refresh_token?: string;
     /** "refresh_token" (default — user-consented) or "client_credentials"
@@ -150,6 +152,24 @@ export declare const OAUTH_REFRESH_TRIES = 3;
 export declare function oauthRetryDelayMs(n: number): number;
 export declare function setOAuth2Secret(tenant: string, name: string, config: OAuth2Config, workspace?: string): void;
 export declare function isOAuth2Value(value: string): boolean;
+/**
+ * The cache key for a live token: SHA-256 over the kind, the account and the
+ * WHOLE stored config — credential material included (client secret, refresh
+ * token, private key, subject, scopes, token URL). A caller can only hit an
+ * entry it could have minted itself. Both maps are process-wide, so a key of
+ * names alone (`sa:${name}:${issuer}`, `${name}:${client_id}:…`) once let a
+ * second account with the same names be handed the first one's token
+ * (Codex debate, 22 Oct 2026).
+ */
+export declare function tokenCacheKey(kind: "oauth2" | "sa", storedValue: string, tenant?: string): string;
+/**
+ * A provider that rotates refresh tokens (RFC 9700 §2.2.2) answered a refresh
+ * with a new one: write it back where the old one is stored — the workspace
+ * copy, else the account's — but only while that copy still holds the value
+ * this refresh used (compare-and-set), so two refreshes racing cannot put an
+ * older token over a newer one. Returns whether a copy was replaced.
+ */
+export declare function replaceOAuth2RefreshToken(tenant: string, name: string, workspace: string | undefined, usedValue: string, refreshToken: string): boolean;
 /**
  * Swap every oauth2 recipe in an env map for a live access token. The one
  * async moment in secret resolution, kept out of the sync paths: callers
@@ -171,6 +191,10 @@ export interface ServiceAccountConfig {
     scope: string;
     /** JWT audience — usually the same as token_url. */
     audience?: string;
+    /** The JWT bearer grant's subject (RFC 7523 §3): the user the account acts
+     *  as, where the provider allows it — Google's domain-wide delegation, once
+     *  a Workspace admin grants it. Absent, the account acts as itself. */
+    subject?: string;
 }
 export declare function setServiceAccountSecret(tenant: string, name: string, config: ServiceAccountConfig, workspace?: string): void;
 export declare function setFileSecret(tenant: string, name: string, content: string, workspace?: string): void;
@@ -187,10 +211,46 @@ export interface SshConfig {
 export declare function setSshSecret(tenant: string, name: string, config: SshConfig, workspace?: string): void;
 export declare function isSshValue(value: string): boolean;
 export declare function sshConfigOf(value: string): SshConfig;
+/** A client certificate for mutual TLS: presented by the egress proxy, on its
+ *  own connection, to the exact hosts the secret is bound to — the sandbox
+ *  never holds the key. `export` puts it in the sandbox as files instead,
+ *  only when asked for (a step with no egress proxy). */
+export interface ClientCertConfig {
+    /** PEM certificate, chain included. */
+    cert: string;
+    /** PEM private key. */
+    key: string;
+    passphrase?: string;
+    export?: boolean;
+}
+export declare function setClientCertSecret(tenant: string, name: string, config: ClientCertConfig, workspace?: string): void;
+/** A keyless cloud identity: no credential at all, only the audience the
+ *  platform's signed tokens are for. A step that declares it gets a token
+ *  file the sandbox driver keeps fresh through the egress proxy. */
+export interface IdentityConfig {
+    audience: string;
+}
+export declare function setIdentitySecret(tenant: string, name: string, config: IdentityConfig, workspace?: string): void;
+export declare function isIdentityValue(value: string): boolean;
+export declare function identityOf(value: string): IdentityConfig;
+export declare function isClientCertValue(value: string): boolean;
+/** An environment without the client certificates that were not saved with
+ *  `export`: those are the egress proxy's to present, never a program's. */
+export declare function withoutHeldCerts(env: Record<string, string>): Record<string, string>;
+export declare function clientCertOf(value: string): ClientCertConfig;
 export interface ApiConfig {
     base_url?: string;
     headers: Record<string, string>;
+    /** Username and password for HTTP Basic (RFC 7617): stored as the
+     *  `Authorization: Basic …` header they make, never kept apart. */
+    basic?: {
+        username: string;
+        password: string;
+    };
 }
+/** `Authorization: Basic …` from a username and password (RFC 7617 §2):
+ *  UTF-8, no colon in the username, no control characters in either. */
+export declare function basicAuthorization(username: string, password: string): string;
 export declare function setApiSecret(tenant: string, name: string, config: ApiConfig, workspace?: string): void;
 export declare function isApiValue(value: string): boolean;
 export declare function apiConfigOf(value: string): ApiConfig;