@foldrun/core 1.0.0 → 1.1.1

package/dist/src/runner.js

@@ -35,7 +35,8 @@ import { TOOL_MAP, BUILTIN_TOOLS, ownToolNames, toolRefs, legacyUseNames, legacy
 import { refNames } from "./refs.js";
 import { accountDir, workspaceDir, buildMemoryIndex, workspaceMemoryIndex, knowledgeIndex, workspaceKnowledgeIndex, workspaceTools, brokenToolReport, listWorkspaces, listTenants, listRuns, syncBundleFor, parseToolDef, readFlow, markerPresent, whenRowsPath, parseApis, resolveModel, parseProvider, providerEnvFor, resolveEffort, isEffortWord, EFFORT_LEVELS, checkFormatVersion, readRun, writeRun, runSummary, verdictOf, sumAttempts, parseSchemaText, STORAGE_DIR, adoptLegacyVersionKey, listAgents, } from "./store.js";
 import { loadCatalog, checkModel, clampEffort, catalogCost, findModel } from "./catalog.js";
-import { resolveSecrets, getSecret, materializeSecrets } from "./secrets.js";
+import { resolveSecrets, getSecret, materializeSecrets, secretSites } from "./secrets.js";
+import { resolveNetwork, networkLine, proxyEnv, EGRESS_CA_ENV } from "./network.js";
 import { materializeFileSecrets, cleanupFileSecrets } from "./secret-files.js";
 import { buildApiTools, secretsUsedByApi } from "./api-tools.js";
 import { attachOperations, prefetchOpenApi } from "./openapi.js";
@@ -60,6 +61,24 @@ export { localDate } from "./clock.js";
 // An MCP tool definition becomes an SDK server config. ${SECRET} placeholders
 // in env and headers resolve server-side, so a credential reaches the server
 // process without ever entering the model's context.
+/** Remote MCP servers with each bound secret's value put back as its
+ *  `${NAME}`, granted to that server's host — the sandbox then holds the
+ *  name and the proxy fills it, as for an http tool. */
+function unbindMcpHeaders(servers, bound, values, grant) {
+    const known = Object.fromEntries(bound.filter((n) => n in values).map((n) => [n, values[n]]));
+    const out = {};
+    for (const [name, server] of Object.entries(servers)) {
+        if (server.type !== "http" || !server.headers) {
+            out[name] = server;
+            continue;
+        }
+        const host = hostOf(server.url);
+        out[name] = host
+            ? { ...server, headers: Object.fromEntries(Object.entries(server.headers).map(([k, v]) => [k, unsubstitute(v, known, host, grant)])) }
+            : server;
+    }
+    return out;
+}
 function mcpConfig(spec, tenant, workspace) {
     const fill = (values) => {
         const out = {};
@@ -2231,7 +2250,46 @@ stepIndex) {
                     }
                 }
             }
+            // `network:` — which sites the sandbox may reach (network.ts). Resolved
+            // before the lease, because the proxy holds the list per request. A
+            // step that may fetch or browse the open web defaults to open; every
+            // other to the trusted list plus what it declares.
+            const workspaceName = path.basename(workspaceRootOf(agentDir));
+            const readsWeb = scriptSpecs.some((sc) => sc.name === "web") && (!web.actions || web.actions.some((a) => a === "fetch" || a === "browse"));
+            // Secrets bound to sites in the vault: filled by the proxy for those
+            // sites alone, never put in the sandbox (egress.ts).
+            const boundSites = secretSites(tenant, Object.keys(liveSecrets), workspaceName);
+            const network = resolveNetwork({
+                account: readAgentsMd(accountDir(tenant))?.data?.network,
+                workspace: readAgentsMd(workspaceRootOf(agentDir))?.data?.network,
+                agent: front.network,
+                readsWeb,
+                implied: [
+                    ...apiSpecs.map((a) => hostOf(a.base)).filter((h) => !!h),
+                    ...Object.values(mcpServers).map((m) => ("url" in m && typeof m.url === "string" ? hostOf(m.url) : null)).filter((h) => !!h),
+                    ...Object.values(grant.secrets).flatMap((g) => g.hosts),
+                    ...Object.values(boundSites).flat(),
+                ],
+            });
+            grant.network = { level: network.level, hosts: network.hosts };
             const lease = await platform.egress.lease({ tenant, runId: runId ?? "adhoc", grant, test: testRun, ...(stepIndex !== undefined && stepIndex >= 0 ? { step: stepIndex } : {}) });
+            // The forward door: every program in the sandbox sends through the
+            // proxy, which holds the site list and fills bound secrets. A proxy
+            // without the door (an older platform) leaves programs going direct.
+            // A step that may browse gets no proxy variables: the browser in it
+            // reads HTTPS_PROXY too, and Chromium cannot send credentials written
+            // into a proxy URL — every page failed ERR_INVALID_AUTH_CREDENTIALS
+            // (14 Oct 2026, the reel posters). Such a step is open by default,
+            // and its bound secrets materialise as they did before the door.
+            const browses = scriptSpecs.some((sc) => sc.name === "web") && (!web.actions || web.actions.includes("browse"));
+            const forward = lease?.proxy && !browses ? lease : null;
+            push("info", networkLine(network, forward ? forward.enforce === true : null));
+            const bound = forward ? Object.keys(boundSites).filter((name) => name in liveSecrets) : [];
+            for (const name of bound) {
+                for (const site of boundSites[name])
+                    addGrant(grant, name, liveSecrets[name], site);
+                (grant.healthKeys ??= {})[name] = healthKey(name, secretScopes[name] === "workspace" ? "workspace" : "account", workspaceName);
+            }
             // Which secrets must still be real inside the sandbox: a script tool
             // reads them from its environment, and unless it says `secrets:
             // proxied` it needs the value, not the name. bash is a script by
@@ -2243,19 +2301,24 @@ stepIndex) {
                 ...(scriptSpecs.some((sc) => sc.name === "web") && (!web.actions || web.actions.includes("browse")) ? ["web (browse)"] : []),
                 ...(allowed.includes("Bash") ? ["bash"] : []),
             ];
-            const materialise = !lease || materialisers.length > 0;
             const declared = Object.keys(liveSecrets);
+            // A bound secret is never materialised, whatever the step grants.
+            const unbound = declared.filter((name) => !bound.includes(name));
+            const materialise = (!lease || materialisers.length > 0) && unbound.length > 0;
             if (lease) {
+                const boundNote = bound.length ? `${bound.join(", ")} bound to sites — filled by the egress proxy, never in the sandbox` : "";
                 push("info", declared.length
                     ? materialise
-                        ? `secrets: ${declared.join(", ")} materialised in the sandbox for ${materialisers.join(", ")}; api tools and the model key go through the egress proxy`
-                        : `secrets: ${declared.join(", ")} proxied — nothing in the sandbox but the names`
+                        ? `secrets: ${unbound.join(", ")} materialised in the sandbox for ${materialisers.join(", ")}${boundNote ? `; ${boundNote}` : ""}; api tools and the model key go through the egress proxy`
+                        : `secrets: ${declared.join(", ")} proxied — nothing in the sandbox but the names${boundNote ? ` (${boundNote})` : ""}`
                     : "secrets: none declared; the model key goes through the egress proxy");
             }
             // Sandbox env for the declared secrets: the value, or its own name as
             // a placeholder that the proxy fills on the way out.
             const placeholders = Object.fromEntries(declared.map((name) => [name, `\${${name}}`]));
-            let sandboxSecrets = materialise ? liveSecrets : placeholders;
+            let sandboxSecrets = materialise
+                ? { ...liveSecrets, ...Object.fromEntries(bound.map((name) => [name, placeholders[name]])) }
+                : placeholders;
             // A test run hands the sandbox no send-capable value. The env var is
             // still there, reading TEST_MODE_WITHHELD, so a script that never
             // checked FOLDRUN_TEST_MODE fails at the provider's door with an auth
@@ -2263,11 +2326,13 @@ stepIndex) {
             // has a declared sender (everything withheld) or a declared reader
             // (nothing withheld); see test-mode.ts for the order.
             if (testRun && materialise) {
-                const held = withholdSecrets(liveSecrets, {
+                const held = withholdSecrets(Object.fromEntries(unbound.map((name) => [name, liveSecrets[name]])), {
                     outward: scriptSpecs.some((sc) => sc.outward),
                     allow: scriptSpecs.some((sc) => sc.testMode === "allow"),
                 });
-                sandboxSecrets = held.env;
+                // Bound secrets stay placeholders: the proxy, which holds the test
+                // policy, is the only party that ever fills them.
+                sandboxSecrets = { ...held.env, ...Object.fromEntries(bound.map((name) => [name, placeholders[name]])) };
                 for (const name of held.withheld) {
                     push("info", `test: ${name} withheld from the sandbox — TEST_MODE_WITHHELD`, { effect: { kind: "withheld", summary: `${name} withheld from the sandbox` } });
                 }
@@ -2322,7 +2387,9 @@ stepIndex) {
                     systemPrompt,
                     allowed,
                     mcpNames: consultNames,
-                    mcpServers,
+                    // A remote MCP server's headers had their secrets filled host-side;
+                    // a bound one goes back to its ${NAME} for the proxy to fill.
+                    mcpServers: bound.length ? unbindMcpHeaders(mcpServers, bound, liveSecrets, grant) : mcpServers,
                     apis: substitutedApis,
                     scripts: scriptSpecs,
                     // The merged spec, not `front.runtime` — see the plan's `runtime`
@@ -2365,6 +2432,14 @@ stepIndex) {
                     // after and carries the agent's chosen endpoint + token.
                     ...proxied(Object.keys(providerEnv).length === 0 ? modelEnv : providerEnv, keyName),
                     ...(lease ? { [EGRESS_ENV]: lease.url } : {}),
+                    // Every program's HTTP(S) through the proxy's forward door, and
+                    // the CA it signs bound sites with, for the sandbox to trust.
+                    ...(forward ? proxyEnv(forward.proxy) : {}),
+                    // Only a step with a bound secret has a site the proxy
+                    // intercepts, so only that step's TLS clients are pointed at a
+                    // bundle with the egress CA in it; every other step's are as
+                    // they always were.
+                    ...(forward?.ca && bound.length ? { [EGRESS_CA_ENV]: Buffer.from(forward.ca).toString("base64") } : {}),
                     ...clockEnv,
                     // Who is running: the in-process path stamps scripts with these
                     // host-side, but a container rebuilds its tools from its own
@@ -2381,6 +2456,9 @@ stepIndex) {
                 // Stamps the sandbox, so stopping this run can destroy it.
                 runId,
                 size,
+                // The pod's network, for the executor's own wall (the k8s tier's
+                // network policy): a filtered pod reaches the proxy and DNS only.
+                network: { level: network.level, enforced: forward?.enforce === true },
                 // A test run's state/ and storage/ changes come out under the run.
                 divert: testRun && runId ? divertFor(runId) : undefined,
                 test: testRun,
@@ -4297,11 +4375,13 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                 // Not after a stop: the failure a stop leaves behind is not one a
                 // rescuer should take over. The merge in save() surfaces the flag.
                 save();
-                for (const step of freshGroup) {
-                    if (run.stopRequested)
-                        break;
-                    if (step.status !== "failed" || !step.onFail)
-                        continue;
+                // One rescue of one failed step. Also used when an evaluator loop
+                // runs out of cycles below, which used to fail the run without ever
+                // reaching the step's on-fail (medium-desk's claim-trimmer was
+                // written for exactly that case and could never run).
+                const rescueStep = async (step) => {
+                    if (!step.onFail)
+                        return;
                     const rescuerDir = path.join(pDir, "agents", step.onFail);
                     if (!fs.existsSync(path.join(rescuerDir, "agent.md"))) {
                         step.events.push({
@@ -4309,7 +4389,7 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                             type: "error",
                             text: `on-fail: "${step.onFail}" is not an agent in this workspace — no rescue`,
                         });
-                        continue;
+                        return;
                     }
                     step.events.push({
                         t: new Date().toISOString(),
@@ -4317,10 +4397,21 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                         text: `failed — handing to [[${step.onFail}]] (on-fail)`,
                     });
                     const failure = (step.result ?? step.events.filter((e) => e.type === "error").map((e) => e.text).join("\n")).slice(0, 4000);
+                    // A gated step's approval travels with it: the rescuer acts inside
+                    // the same answer the failed agent had, and must be told what it
+                    // was. Fixers used to dig it out of the run record, and stop when
+                    // they could not (15 Oct 2026).
+                    const approved = step.approvedAt
+                        ? `\nA person approved this step before it ran${step.approvalNote ? " — their answer is below" : ", with no note: a plain yes"}. Act within that approval and nothing wider.`
+                        : "";
+                    const owesMarker = step.until ? `\nThe step's loop ended without its marker: your reply must end with a line saying ${step.until}.` : "";
                     const rescue = {
                         agent: step.onFail,
                         instruction: `${step.instruction}\n\n<rescue>\nYou are taking this step over: [[${step.agent}]] attempted it and failed. ` +
-                            `Its failure, for whatever it is worth:\n${failure}\n</rescue>`,
+                            `Its failure, for whatever it is worth:\n${failure}${approved}${owesMarker}\n</rescue>`,
+                        ...(step.ask ? { ask: step.ask } : {}),
+                        ...(step.approvedAt ? { approvedAt: step.approvedAt } : {}),
+                        ...(step.approvalNote ? { approvalNote: step.approvalNote } : {}),
                         group: step.group,
                         optional: false,
                         model: step.model,
@@ -4368,6 +4459,13 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                         });
                     }
                     save();
+                };
+                for (const step of freshGroup) {
+                    if (run.stopRequested)
+                        break;
+                    if (step.status !== "failed" || !step.onFail)
+                        continue;
+                    await rescueStep(step);
                 }
                 // A step carried into a re-run failed in the run it came from, not
                 // here: the person chose to start after it. Counting it stopped
@@ -4467,7 +4565,21 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                         text: `loop exhausted: after ${looper.loop} cycle${looper.loop === 1 ? "" : "s"} the result still does not say "${looper.until}"`,
                     });
                     save();
-                    if (!looper.optional) {
+                    if (looper.onFail && !run.stopRequested) {
+                        await rescueStep(looper);
+                        // The rescuer owes what the loop owed: its marker.
+                        // rescueStep mutates the status; widen past TS's "failed" narrowing.
+                        if (looper.status === "completed" && !saysUntilMarker(looper.result ?? null, looper.until)) {
+                            looper.status = "failed";
+                            looper.events.push({
+                                t: new Date().toISOString(),
+                                type: "error",
+                                text: `on-fail: [[${looper.onFail}]]'s result does not say "${looper.until}" either`,
+                            });
+                            save();
+                        }
+                    }
+                    if (looper.status === "failed" && !looper.optional) {
                         run.status = "failed";
                         break;
                     }

package/dist/src/secrets.d.ts

@@ -26,6 +26,11 @@ interface StoredSecret {
      *  record written before per-account keys existed is encrypted with — so an
      *  old vault stays readable without a migration having to run first. */
     k?: "tenant";
+    /** The sites this secret is bound to (network.ts SITE shape). A bound
+     *  secret never enters a sandbox: the egress proxy fills its `${NAME}` for
+     *  these sites alone. Metadata, not a value, so it is stored in the clear
+     *  beside the ciphertext and survives the value being set again. */
+    sites?: string[];
 }
 type SecretsFile = Record<string, StoredSecret>;
 /**
@@ -36,6 +41,18 @@ type SecretsFile = Record<string, StoredSecret>;
 export declare function mutateVaultFile(file: string, change: (all: SecretsFile) => SecretsFile | null): SecretsFile;
 export declare const SECRET_NAME: RegExp;
 export declare function setSecret(tenant: string, name: string, value: string, workspace?: string, kind?: SecretKind): void;
+/**
+ * Bind a secret to sites, or unbind it (an empty list). The secret must
+ * exist in that scope. Sites are `api.example.com` or `*.example.com` — no
+ * scheme, path or port. Returns the list as stored.
+ */
+export declare function setSecretSites(tenant: string, name: string, sites: string[], workspace?: string): string[];
+/**
+ * The sites each named secret is bound to, nearest scope first — the same
+ * record getSecret would read the value from. A name with no binding (or
+ * no secret) is absent from the answer.
+ */
+export declare function secretSites(tenant: string, names: string[], workspace?: string): Record<string, string[]>;
 /** Encrypt one value for an account — the same envelope secrets use, exported
  *  so sibling stores (OAuth clients) don't invent a second crypto path. */
 export declare function encryptValue(tenant: string, value: string): {
@@ -65,6 +82,9 @@ export interface SecretEntry {
     /** How this credential works: auto-refreshing oauth2, a signed service
      *  account, a file/ssh/api materialised into runs — absent for static values. */
     kind?: SecretKind;
+    /** The sites it is bound to — the proxy fills it for these and no other,
+     *  and it never enters a sandbox. Absent when unbound. */
+    sites?: string[];
 }
 export declare function listSecrets(tenant: string, workspace?: string): SecretEntry[];
 export declare function resolveSecrets(tenant: string, names: string[], workspace?: string): {

package/dist/src/secrets.js

@@ -39,6 +39,7 @@ const tenantKey = (tenant) => platform.tenantKey(tenant);
 import crypto from "node:crypto";
 import { assertSafeName } from "./store.js";
 import { trimSlashes } from "./paths.js";
+import { SITE } from "./network.js";
 const keyFile = () => path.join(dataRoot(), ".secret-key");
 /**
  * The install's root secret, as text: FOLDRUN_SECRET_KEY when set, else the
@@ -163,14 +164,70 @@ export function setSecret(tenant, name, value, workspace, kind) {
         throw new Error("secret too long");
     const sealed = encryptValue(tenant, value);
     mutateVaultFile(secretsFile(tenant, workspace), (all) => {
+        // A new value keeps the sites the old one was bound to: binding is a
+        // property of the credential's use, not of its current value, and a
+        // rotation that silently unbound it would put the new value in pods.
+        const sites = all[name]?.sites;
         all[name] = {
             ...sealed,
             updatedAt: new Date().toISOString(),
             ...(kind ? { kind } : {}),
+            ...(sites?.length ? { sites } : {}),
         };
         return all;
     });
 }
+/**
+ * Bind a secret to sites, or unbind it (an empty list). The secret must
+ * exist in that scope. Sites are `api.example.com` or `*.example.com` — no
+ * scheme, path or port. Returns the list as stored.
+ */
+export function setSecretSites(tenant, name, sites, workspace) {
+    const clean = [...new Set(sites.map((x) => x.trim().toLowerCase()).filter(Boolean))];
+    for (const site of clean) {
+        if (!SITE.test(site))
+            throw new Error(`"${site}" is not a site — a domain like api.example.com or *.example.com, no scheme, path or port`);
+    }
+    let found = false;
+    mutateVaultFile(secretsFile(tenant, workspace), (all) => {
+        const rec = all[name];
+        if (!rec)
+            return null;
+        found = true;
+        // A file, an ssh key or an @api header set is not a value that travels
+        // in a header — it is unpacked inside the sandbox, so there is nothing
+        // for the proxy to fill.
+        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`);
+        }
+        if (clean.length)
+            rec.sites = clean;
+        else
+            delete rec.sites;
+        return all;
+    });
+    if (!found)
+        throw new Error(`no secret ${name}${workspace ? ` in workspace ${workspace}` : " in the account"}`);
+    return clean;
+}
+/**
+ * The sites each named secret is bound to, nearest scope first — the same
+ * record getSecret would read the value from. A name with no binding (or
+ * no secret) is absent from the answer.
+ */
+export function secretSites(tenant, names, workspace) {
+    const out = {};
+    const own = workspace ? read(tenant, workspace) : {};
+    const source = workspace ? platform.previewSourceOf(tenant, workspace) : null;
+    const inherited = source ? read(tenant, source) : {};
+    const account = read(tenant);
+    for (const name of names) {
+        const rec = own[name] ?? inherited[name] ?? account[name];
+        if (rec?.sites?.length)
+            out[name] = [...rec.sites];
+    }
+    return out;
+}
 /**
  * Which key writes this account's records.
  *
@@ -271,6 +328,7 @@ export function listSecrets(tenant, workspace) {
         updatedAt: rec.updatedAt,
         scope: "account",
         ...(rec.kind ? { kind: rec.kind } : {}),
+        ...(rec.sites?.length ? { sites: [...rec.sites] } : {}),
     }));
     if (!workspace)
         return account.sort((a, b) => a.name.localeCompare(b.name));
@@ -280,6 +338,7 @@ export function listSecrets(tenant, workspace) {
         scope: "workspace",
         shadowed: account.some((a) => a.name === name),
         ...(rec.kind ? { kind: rec.kind } : {}),
+        ...(rec.sites?.length ? { sites: [...rec.sites] } : {}),
     }));
     const ownNames = new Set(own.map((s) => s.name));
     return [...own, ...account.filter((a) => !ownNames.has(a.name))].sort((a, b) => a.name.localeCompare(b.name));
@@ -748,7 +807,12 @@ export function rewrapTenantSecrets(tenant) {
                 return null;
             const next = { ...all };
             for (const [name, value] of plain) {
-                next[name] = { ...encryptValue(tenant, value), updatedAt: all[name].updatedAt, ...(all[name].kind ? { kind: all[name].kind } : {}) };
+                next[name] = {
+                    ...encryptValue(tenant, value),
+                    updatedAt: all[name].updatedAt,
+                    ...(all[name].kind ? { kind: all[name].kind } : {}),
+                    ...(all[name].sites?.length ? { sites: all[name].sites } : {}),
+                };
             }
             moved += plain.size;
             return next;

package/dist/src/starter.js

@@ -295,7 +295,11 @@ memory an agent wrote that your push does not mention. Those belong to the platf
 reverted what an agent learned would make every run a little dumber.
 
 Secrets never go in these files. \`foldrun secrets\` puts them in the vault, and
-agents reference them by name.
+agents reference them by name. Bind one to the sites it is for
+(\`foldrun secrets sites NAME api.example.com\`) and it never enters a sandbox:
+the egress proxy fills \`\${NAME}\` in requests to those sites alone. Which sites
+a sandbox may reach at all is \`network:\` — open for an agent that reads the web,
+the trusted list plus what it declares for every other (\`foldrun agent network\`).
 
 ## Talking to a deployed workspace
 
@@ -341,6 +345,7 @@ All of it, \`/api/workspaces/<workspace>\` unless noted:
 | \`/export\` · \`/import\` | GET · POST | the workspace, a flow (\`?kind=flow&name=\`) or an agent as a .zip; take one in (\`?dryRun=1\` first, \`?overwrite=1\` to replace) |
 | \`/restore\` | POST | the workspace's source back to a point in its history — \`dryRun\` first, then \`confirm\` |
 | \`/vocabulary\` | GET | what this workspace's documents may say |
+| \`/assistant\` | POST | ask the assistant, or have it write agents, flows, tools and skills — from the docs only; proposals come back, nothing is written |
 
 Account-level, outside \`/workspaces\`: \`/api/secrets\`, \`/api/keys\`, \`/api/schedule\`,
 \`/api/approvals\`, \`/api/usage\`, \`/api/library/<kind>\`, \`/api/team\`, \`/api/billing\`,
@@ -448,6 +453,7 @@ agents: [writer]            # colleagues this one may consult (an answer, no too
 subagents: [researcher]     # colleagues it may delegate a job to (own context, own tools ≤ its own)
 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
 timezone: Australia/Sydney  # the calendar it works to — IANA name or UTC+10
 provider: {}                # BYOK for this agent; account-wide: \`foldrun account model set\`
 permissionMode: plan        # plan first, act once approved

package/dist/src/store.d.ts

@@ -12,6 +12,7 @@ import type { OperatorEvent } from "./operator.ts";
  * the runtime, and there is nothing to fail to import.
  */
 export declare function readFrontmatter(file: string): Record<string, unknown>;
+import { type NetworkPolicy } from "./network.ts";
 import { type WireFormat, type AuthShape } from "./providers.ts";
 /**
  * Single-workspace mode. When set, the workspace IS this directory — no
@@ -331,6 +332,17 @@ export interface AgentInfo {
     /** What is wrong with the `limits:` block's shape; key-vs-grant problems
      *  need the tool lists, and `check` adds them (limits.ts limitKeyProblems). */
     limitProblems: string[];
+    /** What cannot be read in `network:` (network.ts) — a level that is not
+     *  one, a site with a scheme or a path. */
+    networkProblems: string[];
+    /** The sites this agent's steps may reach, resolved the way a run
+     *  resolves them — its `network:`, the workspace's, the account's, and
+     *  the default (open when it may fetch or browse the web, else trusted).
+     *  `implied` here is its `apis:` hosts; a run also adds its MCP servers',
+     *  its web providers' and its bound secrets' sites. */
+    network: NetworkPolicy & {
+        readsWeb: boolean;
+    };
     /** Tools this agent declares inline rather than in `tools:` — `apis:`,
      *  `scripts:` and `mcpServers:` names — which a limit may also name. */
     inlineTools: string[];

package/dist/src/store.js

@@ -44,7 +44,8 @@ import { refNames } from "./refs.js";
 import { parseBudget, budgetProblem } from "./budget.js";
 import { timezoneProblem } from "./clock.js";
 import { parseStepLimits, readLimits } from "./limits.js";
-import { webProblems, webWarnings, runnerEngines } from "./providers.js";
+import { networkProblems, resolveNetwork } from "./network.js";
+import { webProblems, webWarnings, runnerEngines, webConfig } from "./providers.js";
 import { actionProblems } from "./web-actions.js";
 import { languageProblem } from "./language.js";
 import { localeProblems } from "./locale.js";
@@ -1095,6 +1096,17 @@ export function listAgents(tenant, workspace) {
     const dir = path.join(workspaceDir(tenant, workspace), "agents");
     if (!fs.existsSync(dir))
         return [];
+    // The two levels above every agent, for the network: cascade.
+    const frontOf = (file) => {
+        try {
+            return readFrontmatter(file);
+        }
+        catch {
+            return {}; // no AGENTS.md at that level, or one that does not parse
+        }
+    };
+    const accountFront = frontOf(path.join(accountDir(tenant), "AGENTS.md"));
+    const workspaceFront = frontOf(path.join(workspaceDir(tenant, workspace), "AGENTS.md"));
     return fs
         .readdirSync(dir)
         .filter((n) => fs.existsSync(path.join(dir, n, "agent.md")))
@@ -1102,7 +1114,25 @@ export function listAgents(tenant, workspace) {
         .map((name) => {
         const { data } = matter(fs.readFileSync(path.join(dir, name, "agent.md"), "utf8"));
         const tools = refNames(data.tools);
+        const actions = webConfig(data, { ...accountFront, ...workspaceFront }).actions;
+        const readsWeb = tools.includes("web") && (!actions || actions.some((a) => a === "fetch" || a === "browse"));
+        const network = {
+            ...resolveNetwork({
+                account: accountFront.network,
+                workspace: workspaceFront.network,
+                agent: data.network,
+                readsWeb,
+                implied: parseApis(data.apis).map((a) => { try {
+                    return new URL(a.base).host;
+                }
+                catch {
+                    return "";
+                } }),
+            }),
+            readsWeb,
+        };
         return {
+            network,
             name,
             description: data.description ?? "",
             model: data.model ?? "default",
@@ -1126,6 +1156,7 @@ export function listAgents(tenant, workspace) {
             webWarnings: webWarnings(data, { chrome: runnerEngines()?.chrome, chromium: runnerEngines()?.chromium }),
             scheduleProblem: agentScheduleProblem(data),
             ...(() => { const l = readLimits(data.limits); return { limits: l.limits, limitProblems: l.problems }; })(),
+            networkProblems: networkProblems(data.network),
             inlineTools: inlineToolNames(data),
         };
     });

package/dist/src/tool-loop.d.ts

@@ -0,0 +1,45 @@
+/** One string argument: what it means, whether it may be left out, how long it may be. */
+export interface LoopArg {
+    description?: string;
+    optional?: boolean;
+    max?: number;
+}
+export interface LoopTool {
+    name: string;
+    description: string;
+    args: Record<string, LoopArg>;
+    /** The answer the model reads. A throw becomes an error result, not a crash. */
+    run: (args: Record<string, string | undefined>) => Promise<string> | string;
+}
+export interface LoopUsage {
+    /** Everything sent, cache reads and writes included. */
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+}
+export interface LoopResult {
+    /** The last turn's text — the answer, not the thinking aloud between tool calls. */
+    text: string;
+    /** What the SDK reports the query cost; 0 when it never reported (killed). */
+    costUsd: number;
+    usage: LoopUsage | null;
+    /** Why it ended, when it did not end well: max turns, budget, wall clock. */
+    stopped: string | null;
+}
+export interface LoopOptions {
+    system: string;
+    prompt: string;
+    tools: LoopTool[];
+    model: string;
+    /** The model credential and anything else the SDK process needs. */
+    env: Record<string, string | undefined>;
+    maxTurns: number;
+    maxBudgetUsd: number;
+    maxOutputTokens: number;
+    wallSeconds: number;
+    /** The reply as it is written, for a live view. */
+    onText?: (delta: string) => void;
+}
+/** The Agent SDK's name for one of our tools. */
+export declare const loopToolName: (name: string) => string;
+export declare function runToolLoop(o: LoopOptions): Promise<LoopResult>;