@foldrun/core 2.6.0 → 2.8.0

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;

package/dist/src/secrets.js

@@ -200,6 +200,11 @@ export function setSecretSites(tenant, name, sites, workspace) {
         if (clean.length && (rec.kind === "file" || rec.kind === "ssh" || rec.kind === "api")) {
             throw new Error(`${name} is a ${rec.kind} secret, unpacked inside the sandbox — only a value sent in a request can be bound to sites`);
         }
+        // A client certificate is presented by the egress proxy to the exact
+        // hosts named — never to a whole domain on a wildcard.
+        if (rec.kind === "client-cert" && clean.some((s) => s.startsWith("*."))) {
+            throw new Error(`${name} is a client certificate — bind it to exact hosts, not a wildcard`);
+        }
         if (clean.length)
             rec.sites = clean;
         else
@@ -459,10 +464,15 @@ export function oauthRetryDelayMs(n) {
     return base * (n === 1 ? 1 : 3);
 }
 export function setOAuth2Secret(tenant, name, config, workspace) {
-    for (const field of ["token_url", "client_id", "client_secret"]) {
+    for (const field of ["token_url", "client_id"]) {
         if (!config[field]?.trim())
             throw new Error(`oauth2 secret needs ${field}`);
     }
+    // A public client (PKCE, no secret) refreshes with its client id alone;
+    // client credentials are nothing without the secret.
+    if (config.grant_type === "client_credentials" && !config.client_secret?.trim()) {
+        throw new Error("oauth2 secret needs client_secret for client_credentials");
+    }
     if (config.grant_type !== "client_credentials" && !config.refresh_token?.trim()) {
         throw new Error("oauth2 secret needs refresh_token (or grant_type: client_credentials)");
     }
@@ -481,11 +491,62 @@ export function isOAuth2Value(value) {
 // steps must not hit Google twenty times in one second.
 const tokenCache = new Map();
 const inFlight = new Map();
+/**
+ * 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 function tokenCacheKey(kind, storedValue, tenant) {
+    return crypto.createHash("sha256").update(JSON.stringify([kind, tenant ?? "", storedValue])).digest("hex");
+}
+/**
+ * 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 function replaceOAuth2RefreshToken(tenant, name, workspace, usedValue, refreshToken) {
+    if (!isOAuth2Value(usedValue))
+        return false;
+    const config = JSON.parse(usedValue.slice(OAUTH2_PREFIX.length));
+    const next = OAUTH2_PREFIX + JSON.stringify({ ...config, refresh_token: refreshToken });
+    for (const scope of workspace ? [workspace, undefined] : [undefined]) {
+        let replaced = false;
+        mutateVaultFile(secretsFile(tenant, scope), (all) => {
+            const rec = all[name];
+            if (rec && decrypt(tenant, rec) === usedValue) {
+                all[name] = { ...rec, ...encryptValue(tenant, next), updatedAt: new Date().toISOString() };
+                replaced = true;
+            }
+            return all;
+        });
+        if (replaced)
+            return true;
+    }
+    return false;
+}
+const oauthCache = new Map();
+const oauthFlight = new Map();
+/** Cache an access token, sweeping expired entries as it goes: a rotating
+ *  provider changes the stored config — and so the key — on every refresh,
+ *  and expired entries would otherwise pile up for the life of the process. */
+function cacheOAuth(key, live) {
+    const now = Date.now();
+    for (const [k, v] of oauthCache)
+        if (v.expiresAt <= now)
+            oauthCache.delete(k);
+    oauthCache.set(key, live);
+}
 async function exchange(config, cacheKey) {
-    const cached = tokenCache.get(cacheKey);
+    const cached = oauthCache.get(cacheKey);
     if (cached && cached.expiresAt > Date.now())
-        return cached.token;
-    const pending = inFlight.get(cacheKey);
+        return cached;
+    const pending = oauthFlight.get(cacheKey);
     if (pending)
         return pending;
     const flight = (async () => {
@@ -493,7 +554,7 @@ async function exchange(config, cacheKey) {
             grant_type: config.grant_type ?? "refresh_token",
             ...(config.grant_type === "client_credentials" ? {} : { refresh_token: config.refresh_token }),
             client_id: config.client_id,
-            client_secret: config.client_secret,
+            ...(config.client_secret ? { client_secret: config.client_secret } : {}),
             ...(config.extra ?? {}),
         });
         // A network blip is retried; a provider's answer is not. "fetch failed"
@@ -530,15 +591,21 @@ async function exchange(config, cacheKey) {
             throw new Error(`token refresh failed (${res.status}): ${payload.error_description ?? payload.error ?? "no access_token in the reply"}`);
         }
         const ttl = Math.max(60, (payload.expires_in ?? 3600) - 60) * 1000;
-        tokenCache.set(cacheKey, { token: payload.access_token, expiresAt: Date.now() + ttl });
-        return payload.access_token;
+        // A rotated refresh token replaces the old one, which the provider may
+        // now refuse; dropping it broke the next refresh for rotating providers.
+        const rotated = payload.refresh_token && config.grant_type !== "client_credentials" && payload.refresh_token !== config.refresh_token
+            ? payload.refresh_token
+            : undefined;
+        const live = { token: payload.access_token, expiresAt: Date.now() + ttl, ...(rotated ? { rotated } : {}) };
+        cacheOAuth(cacheKey, live);
+        return live;
     })();
-    inFlight.set(cacheKey, flight);
+    oauthFlight.set(cacheKey, flight);
     try {
         return await flight;
     }
     finally {
-        inFlight.delete(cacheKey);
+        oauthFlight.delete(cacheKey);
     }
 }
 /**
@@ -565,13 +632,23 @@ ctx) {
                 throw new Error(`secret ${name}: stored oauth2 config is unreadable`);
             }
             try {
-                // Fingerprint the WHOLE refresh token, not its first 8 chars: Google
-                // refresh tokens share a long common prefix, so an 8-char slice could
-                // collide two distinct grants onto one cache entry and hand one the
-                // other's access token. Hashed so the token is not held in a Map key.
-                const grantMaterial = config.refresh_token ?? config.grant_type ?? "";
-                const fp = crypto.createHash("sha256").update(grantMaterial).digest("hex").slice(0, 16);
-                out[name] = await exchange(config, `${name}:${config.client_id}:${fp}`);
+                const live = await exchange(config, tokenCacheKey("oauth2", value, ctx?.tenant));
+                out[name] = live.token;
+                if (live.rotated) {
+                    // This caller's copy takes the new refresh token (compare-and-set:
+                    // a copy already updated, or changed since, is left alone), and the
+                    // access token is cached under the config as it is now stored, so
+                    // the next run does not refresh again.
+                    const next = OAUTH2_PREFIX + JSON.stringify({ ...config, refresh_token: live.rotated });
+                    try {
+                        if (ctx)
+                            replaceOAuth2RefreshToken(ctx.tenant, name, ctx.workspace, value, live.rotated);
+                    }
+                    catch {
+                        // The access token is good either way; the next refresh says if not.
+                    }
+                    cacheOAuth(tokenCacheKey("oauth2", next, ctx?.tenant), { token: live.token, expiresAt: live.expiresAt });
+                }
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
@@ -590,7 +667,7 @@ ctx) {
                 throw new Error(`secret ${name}: stored service account config is unreadable`);
             }
             try {
-                out[name] = await exchangeServiceAccount(config, `sa:${name}:${config.issuer}`);
+                out[name] = await exchangeServiceAccount(config, tokenCacheKey("sa", value, ctx?.tenant));
             }
             catch (err) {
                 throw new Error(`secret ${name}: ${err instanceof Error ? err.message : String(err)}`);
@@ -619,7 +696,14 @@ export function setServiceAccountSecret(tenant, name, config, workspace) {
     if (!/BEGIN [A-Z ]{0,40}PRIVATE KEY/.test(config.private_key)) {
         throw new Error("private_key must be a PEM key (from the service account JSON)");
     }
-    setSecret(tenant, name, SERVICE_ACCOUNT_PREFIX + JSON.stringify(config), workspace, "service-account");
+    if (config.subject !== undefined) {
+        if (typeof config.subject !== "string" || !config.subject.trim())
+            throw new Error("subject is the user to act as — leave it out to act as the account itself");
+        if (config.subject.length > 320 || /[\u0000-\u001f\u007f\s]/.test(config.subject.trim()))
+            throw new Error("subject is one identifier, no spaces or control characters");
+    }
+    const stored = { ...config, ...(config.subject !== undefined ? { subject: config.subject.trim() } : {}) };
+    setSecret(tenant, name, SERVICE_ACCOUNT_PREFIX + JSON.stringify(stored), workspace, "service-account");
 }
 function base64url(input) {
     return Buffer.from(input).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
@@ -636,7 +720,9 @@ async function exchangeServiceAccount(config, cacheKey) {
         const header = base64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
         const claim = base64url(JSON.stringify({
             iss: config.issuer,
-            sub: config.issuer,
+            // The subject is part of the stored config, so of the cache key: two
+            // subjects never share a token (tokenCacheKey).
+            sub: config.subject || config.issuer,
             scope: config.scope,
             aud: config.audience ?? config.token_url,
             iat: now,
@@ -737,8 +823,108 @@ export function sshConfigOf(value) {
 // wrapper with the headers baked in — `"$NAME" /v1/charges` — so the secret
 // never appears in the bash command at all.
 const API_PREFIX = "@api ";
+const CLIENT_CERT_PREFIX = "@client-cert ";
+export function setClientCertSecret(tenant, name, config, workspace) {
+    if (!/-----BEGIN CERTIFICATE-----/.test(config.cert ?? ""))
+        throw new Error("cert must be a PEM certificate");
+    if (!/-----BEGIN [A-Z ]{0,40}PRIVATE KEY-----/.test(config.key ?? ""))
+        throw new Error("key must be a PEM private key");
+    // The pair must match: a certificate presented with another key's proof
+    // fails at the server, after the request has gone.
+    let matches = false;
+    try {
+        const key = crypto.createPrivateKey({ key: config.key, ...(config.passphrase ? { passphrase: config.passphrase } : {}) });
+        matches = new crypto.X509Certificate(config.cert).checkPrivateKey(key);
+    }
+    catch (err) {
+        throw new Error(`the certificate or key cannot be read: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!matches)
+        throw new Error("the key does not belong to the certificate");
+    const stored = {
+        cert: config.cert,
+        key: config.key,
+        ...(config.passphrase ? { passphrase: config.passphrase } : {}),
+        ...(config.export ? { export: true } : {}),
+    };
+    if (!SECRET_NAME.test(name))
+        throw new Error(`secret name "${name}" must be UPPER_SNAKE_CASE`);
+    const sealed = encryptValue(tenant, CLIENT_CERT_PREFIX + JSON.stringify(stored));
+    // Written under the vault's own lock, with the binding checked in the same
+    // step: a value set over a secret keeps its site binding, and a wildcard
+    // one would present the certificate to a whole domain.
+    mutateVaultFile(secretsFile(tenant, workspace), (all) => {
+        const sites = all[name]?.sites;
+        if (sites?.some((site) => site.startsWith("*."))) {
+            throw new Error(`${name} is bound to ${sites.join(", ")} — a client certificate is bound to exact hosts; unbind the wildcard first`);
+        }
+        all[name] = { ...sealed, updatedAt: new Date().toISOString(), kind: "client-cert", ...(sites?.length ? { sites } : {}) };
+        return all;
+    });
+}
+const IDENTITY_PREFIX = "@identity ";
+export function setIdentitySecret(tenant, name, config, workspace) {
+    const audience = typeof config.audience === "string" ? config.audience.trim() : "";
+    if (!audience)
+        throw new Error("an identity needs an audience — the value your cloud's trust expects in aud");
+    if (audience.length > 600 || /[\u0000-\u001f\u007f]/.test(audience))
+        throw new Error("audience is one value, at most 600 characters, no control characters");
+    setSecret(tenant, name, IDENTITY_PREFIX + JSON.stringify({ audience }), workspace, "identity");
+}
+export function isIdentityValue(value) {
+    return value.startsWith(IDENTITY_PREFIX);
+}
+export function identityOf(value) {
+    return JSON.parse(value.slice(IDENTITY_PREFIX.length));
+}
+export function isClientCertValue(value) {
+    return value.startsWith(CLIENT_CERT_PREFIX);
+}
+/** 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 function withoutHeldCerts(env) {
+    return Object.fromEntries(Object.entries(env).filter(([, v]) => typeof v !== "string" || !isClientCertValue(v) || clientCertOf(v).export === true));
+}
+export function clientCertOf(value) {
+    return JSON.parse(value.slice(CLIENT_CERT_PREFIX.length));
+}
+/** `Authorization: Basic …` from a username and password (RFC 7617 §2):
+ *  UTF-8, no colon in the username, no control characters in either. */
+export function basicAuthorization(username, password) {
+    if (typeof username !== "string" || typeof password !== "string")
+        throw new Error("basic needs username and password");
+    if (!username)
+        throw new Error("basic needs a username");
+    if (username.includes(":"))
+        throw new Error("a Basic username cannot contain a colon (RFC 7617)");
+    if (/[\u0000-\u001f\u007f]/.test(username) || /[\u0000-\u001f\u007f]/.test(password))
+        throw new Error("Basic credentials cannot contain control characters");
+    return `Basic ${Buffer.from(`${username}:${password}`, "utf8").toString("base64")}`;
+}
 export function setApiSecret(tenant, name, config, workspace) {
-    const headers = Object.entries(config.headers ?? {});
+    let all = { ...(config.headers ?? {}) };
+    if (config.basic) {
+        if (Object.keys(all).some((h) => h.toLowerCase() === "authorization")) {
+            throw new Error("give either basic or an Authorization header, not both");
+        }
+        // Credentials in the clear over http are leaked ones: https, or loopback.
+        const base = config.base_url?.trim();
+        if (base) {
+            let u = null;
+            try {
+                u = new URL(base);
+            }
+            catch {
+                u = null;
+            }
+            const loopback = u?.protocol === "http:" && (u.hostname === "localhost" || u.hostname === "127.0.0.1");
+            if (!u || (u.protocol !== "https:" && !loopback))
+                throw new Error("Basic credentials need an https base_url");
+        }
+        all = { ...all, Authorization: basicAuthorization(config.basic.username, config.basic.password) };
+    }
+    config = { ...(config.base_url ? { base_url: config.base_url } : {}), headers: all };
+    const headers = Object.entries(all);
     if (headers.length === 0)
         throw new Error("api secret needs at least one header");
     for (const [h, v] of headers) {

package/dist/src/starter.js

@@ -478,6 +478,7 @@ apis: [{ name: crm }]       # an HTTP API, as a tool
 mcpServers: {}              # an MCP server, as a tool
 agents: [writer]            # colleagues this one may consult (an answer, no tools)
 subagents: [researcher]     # colleagues it may delegate a job to (own context, own tools ≤ its own)
+sandbox: own                # delegated to: run each job in its own sandbox (own tools, secrets, network)
 secrets: [CRM_TOKEN]        # keys the agent uses itself; a tool's own come with the tool
 limits: {web.search: 40, crm: 20, calls: 300}  # per step; a call past a limit is refused, never run
 network: [api.example.com]  # sites its sandbox may reach, added to the trusted list; open | trusted | none

package/dist/src/store.d.ts

@@ -311,6 +311,8 @@ export interface AgentInfo {
     /** Colleagues this agent may DELEGATE to (`subagents:`) — each runs with
      *  its own context and its own tools, no wider than this agent's. */
     subagents: string[];
+    /** `sandbox: own` — delegated to, it runs each job in its own sandbox. */
+    sandbox?: "own";
     /** The `skills:` allowlist, or null when the field is absent — which is
      *  not the same thing: absent inherits every skill in scope, an empty
      *  list withholds all of them. */
@@ -1068,6 +1070,16 @@ export interface StepAttempt {
 export declare function sumAttempts(tries: StepAttempt[]): Pick<StepAttempt, "costUsd" | "tokens" | "computeSecs" | "turns">;
 export { type TokenUsage, type PromptLayerRecord, tokensOf, sumTokens, cacheHitRate, measuredHitRate, runTokens, promptLayersChanged, promptCacheNote } from "./tokens.ts";
 import { type TokenUsage, type PromptLayerRecord } from "./tokens.ts";
+/** One job a step handed to an isolated sub-agent. `id` is the job's own
+ *  record's `delegation` — not an index, which moves when records are
+ *  spliced in before it. */
+export interface StepDelegation {
+    id: string;
+    agent: string;
+    status: "running" | "completed" | "failed" | "skipped";
+    costUsd?: number | null;
+    ms?: number | null;
+}
 /** The marker rescueStep puts in a rescue's instruction; how a rescue record
  *  written before `rescueOf` existed is still recognised. */
 export declare const RESCUE_MARKER = "<rescue>\nYou are taking this step over:";
@@ -1076,6 +1088,15 @@ export declare function isRescueRecord(step: {
     rescueOf?: string;
     instruction?: string | null;
 }): boolean;
+/** Is this record put in by the runner rather than by the flow — an on-fail
+ *  rescue, or an isolated sub-agent's run (`subagentOf`)? Neither is launched
+ *  with a group, handed on as a group's output, reset by a loop, or copied by
+ *  a re-run as work. */
+export declare function isSplicedRecord(step: {
+    rescueOf?: string;
+    subagentOf?: string;
+    instruction?: string | null;
+}): boolean;
 export interface StepRecord {
     agent: string;
     instruction: string;
@@ -1242,6 +1263,19 @@ export interface StepRecord {
      *  steps). Records written before this field are recognised by their
      *  instruction's `<rescue>` block instead — see isRescueRecord. */
     rescueOf?: string;
+    /** Set on an isolated sub-agent's run (`sandbox: own`, delegate-tools.ts):
+     *  the agent of the step that delegated to it. It ran in its own sandbox
+     *  inside that step; only its reply went back. Like a rescue it is not a
+     *  step of the flow — see isSplicedRecord. */
+    subagentOf?: string;
+    /** On an isolated sub-agent's run: its job's id, as the delegating step's
+     *  `delegations[].id` names it. */
+    delegation?: string;
+    /** On a step that delegated to isolated sub-agents: each job, in order. */
+    delegations?: StepDelegation[];
+    /** On an isolated sub-agent's run: the workspace paths its sandbox's
+     *  changes were applied to — what its delegating step is told it wrote. */
+    wrote?: string[];
     /**
      * Sandbox seconds this step rented, and how many of them were cold start.
      * Set only on the isolated path — an in-process step rents nothing, so

package/dist/src/store.js

@@ -1163,6 +1163,7 @@ export function listAgents(tenant, workspace) {
             retiredTools: retiredToolNames(data),
             consults: refNames(data.agents),
             subagents: refNames(data.subagents),
+            ...(data.sandbox === "own" ? { sandbox: "own" } : {}),
             skills: data.skills === undefined ? null : refNames(data.skills),
             secrets: Array.isArray(data.secrets) ? data.secrets.map(String) : [],
             budget: runBudget(data.budget),
@@ -2662,6 +2663,13 @@ export const RESCUE_MARKER = "<rescue>\nYou are taking this step over:";
 export function isRescueRecord(step) {
     return !!step.rescueOf || (step.instruction ?? "").includes(RESCUE_MARKER);
 }
+/** Is this record put in by the runner rather than by the flow — an on-fail
+ *  rescue, or an isolated sub-agent's run (`subagentOf`)? Neither is launched
+ *  with a group, handed on as a group's output, reset by a loop, or copied by
+ *  a re-run as work. */
+export function isSplicedRecord(step) {
+    return !!step.subagentOf || isRescueRecord(step);
+}
 // ---------------------------------------------------------------- captured calls
 //
 // What each tool call took and gave (FOL-54 step 4), beside the run under
@@ -3218,6 +3226,10 @@ export function runVerdict(run) {
 }
 export function runSummary(run) {
     for (let i = run.steps.length - 1; i >= 0; i--) {
+        // A sandbox: own job is appended after every step of the flow; its reply
+        // went to the step that asked, which speaks for the run.
+        if (run.steps[i].subagentOf)
+            continue;
         const line = stepHeadline(run.steps[i]);
         if (line)
             return line;

package/dist/src/subagents.d.ts

@@ -10,6 +10,20 @@ export interface SubagentSpec {
      *  the step's own) or "inherit". */
     model: string;
 }
+/** An isolated sub-agent (`sandbox: own` on its own agent.md): what the
+ *  parent's sandbox needs to offer it as a tool. Everything else — its tools,
+ *  secrets, network, size — is resolved on the worker when the job arrives,
+ *  from its own file, and never enters the parent's sandbox. */
+export interface DelegateSpec {
+    name: string;
+    description: string;
+}
+/** Does this agent run in its own sandbox when delegated to? */
+export declare function ownSandbox(front: {
+    sandbox?: unknown;
+}): boolean;
+/** The tool the parent calls to hand an isolated sub-agent a job. */
+export declare function delegateToolName(agent: string): string;
 /** The SDK's delegation tool, under both names it has had. Never granted to a
  *  sub-agent: that is what makes the depth one. */
 export declare const DELEGATE_TOOLS: readonly ["Agent", "Task"];

package/dist/src/subagents.js

@@ -27,6 +27,14 @@ import fs from "node:fs";
 import path from "node:path";
 import { refNames } from "./refs.js";
 import { TOOL_MAP } from "./tool-names.js";
+/** Does this agent run in its own sandbox when delegated to? */
+export function ownSandbox(front) {
+    return front.sandbox === "own";
+}
+/** The tool the parent calls to hand an isolated sub-agent a job. */
+export function delegateToolName(agent) {
+    return `delegate_${agent.replaceAll("-", "_")}`;
+}
 /** The SDK's delegation tool, under both names it has had. Never granted to a
  *  sub-agent: that is what makes the depth one. */
 export const DELEGATE_TOOLS = ["Agent", "Task"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "Agents are just folders. The format, the runner, the checks.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

package/src/capture.ts

@@ -7,7 +7,7 @@
 
 import { redactText } from "./scan.ts";
 import { writeCapturedCall, CAPTURE_CAP } from "./store.ts";
-import { isFileValue, fileContent } from "./secrets.ts";
+import { isFileValue, fileContent, isApiValue, apiConfigOf, isClientCertValue, clientCertOf } from "./secrets.ts";
 import type { CallIo } from "./step-exec.ts";
 
 /** How much past the cap a step sends, so masking sees a secret whole
@@ -31,6 +31,38 @@ export function redactionsFor(secrets: Record<string, string | undefined>): [str
   };
   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: string) => {
+        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);