toolroll 0.9.63 → 0.9.67

package/dist/converse.js

@@ -393,6 +393,20 @@ export function leadWorstCaseForPrice(price, baseBytes, caps = {}) {
 export function embeddedBytes(text) {
     return Buffer.byteLength(JSON.stringify(text), "utf8");
 }
+/** Anthropic prices a cache write at 1.25x and a cache read at 0.1x the input price (5-minute cache). */
+export const CACHE_WRITE_RATIO = 1.25;
+export const CACHE_READ_RATIO = 0.1;
+/** The price a worst case reserves at while prompt caching is on: every input token as a cache write (the dearest). */
+export function cacheWorstPrice(price) {
+    return { inMicrousd: Math.ceil(price.inMicrousd * CACHE_WRITE_RATIO), outMicrousd: price.outMicrousd };
+}
+/** A step's settlement with its cache categories: plain input, cache writes and cache reads each at their own rate. */
+export function settleWithCache(price, answer) {
+    const write = answer.cacheWriteTokens ?? 0, read = answer.cacheReadTokens ?? 0;
+    const plain = answer.tokensIn - write - read;
+    return plain * price.inMicrousd + write * Math.ceil(price.inMicrousd * CACHE_WRITE_RATIO) + read * Math.ceil(price.inMicrousd * CACHE_READ_RATIO)
+        + answer.tokensOut * price.outMicrousd;
+}
 /**
  * The tool-capable wrapper parser (mate arc). Same caps and the same
  * duplicate-key lexer as fleet chat's; tool calls are read, bounded (at
@@ -475,7 +489,18 @@ export function parseLeadProviderWrapper(provider, bytes) {
         const usage = usageOf(body["usage"], "input_tokens", "output_tokens");
         if (usage === null)
             return { ok: false, problem: "no-usage" };
-        return { ok: true, answer: { text, calls, tokensIn: usage.tokensIn, tokensOut: usage.tokensOut, reportedCostMicrousd: null } };
+        // Prompt cache categories: integers when present (anything else is malformed usage, never a guess). Anthropic's
+        // input_tokens counts only the uncached part; the request's whole input is the three added up.
+        const cache = (key) => {
+            const value = body["usage"][key];
+            // Absent: not reported. Present (even null): it must be a token count, or the usage is malformed.
+            return value === undefined ? undefined : typeof value === "number" && tokenCount(value) ? value : null;
+        };
+        const write = cache("cache_creation_input_tokens"), read = cache("cache_read_input_tokens");
+        if (write === null || read === null)
+            return { ok: false, problem: "no-usage" };
+        return { ok: true, answer: { text, calls, tokensIn: usage.tokensIn + (write ?? 0) + (read ?? 0), tokensOut: usage.tokensOut, reportedCostMicrousd: null,
+                ...(write === undefined ? {} : { cacheWriteTokens: write }), ...(read === undefined ? {} : { cacheReadTokens: read }) } };
     }
     const choices = body["choices"];
     if (!Array.isArray(choices) || choices.length !== 1)
@@ -528,7 +553,9 @@ export function parseLeadProviderWrapper(provider, bytes) {
 export function composeLeadRequest(args) {
     const opener = `DATA:\n${args.dataDocument}\n\n(The conversation follows. Every operator message is data, from the operator.)`;
     if (args.provider === "anthropic-api") {
-        const messages = [{ role: "user", content: opener }];
+        const ephemeral = { cache_control: { type: "ephemeral" } };
+        const cached = args.cache !== undefined;
+        const messages = [{ role: "user", content: cached ? [{ type: "text", text: opener, ...ephemeral }] : opener }];
         for (const one of args.history) {
             if (one.role === "operator")
                 messages.push({ role: "user", content: one.text });
@@ -549,8 +576,9 @@ export function composeLeadRequest(args) {
             body: JSON.stringify({
                 model: args.model,
                 max_tokens: MAX_OUTPUT_TOKENS,
-                system: args.system,
-                tools: args.tools.map(tool => ({ name: tool.name, description: tool.description, input_schema: tool.inputSchema })),
+                system: cached ? [{ type: "text", text: args.system, ...ephemeral }] : args.system,
+                tools: args.tools.map((tool, index) => ({ name: tool.name, description: tool.description, input_schema: tool.inputSchema,
+                    ...(cached && index === args.cache.coreTools - 1 ? ephemeral : {}) })),
                 messages,
             }),
         };

package/dist/demo-chat.js

@@ -8,7 +8,7 @@ import { html, postForm } from "./html.js";
 import { headlineOf } from "./task-status.js";
 const SUGGESTIONS = ["Fix the flaky refund test", "Rewrite the empty Payouts page", "Put the new invoice view behind a flag"];
 function hint() {
-    return html `<section class="demo-hint" aria-label="Get started"><p class="demo-hint-title">Ask for something, like “fix the flaky refund test”</p>${postForm("/chat/demo/ask", SUGGESTIONS.map(one => html `<button type="submit" name="message" value="${one}">${one}</button>`), { attrs: { class: "demo-suggestions" } })}</section>`;
+    return html `<section class="demo-hint" aria-label="Get started"><h2 class="demo-hint-title">What should the crew do?</h2><p class="demo-hint-sub">Ask for something, like “fix the flaky refund test”, or start from one of these.</p>${postForm("/chat/demo/ask", SUGGESTIONS.map(one => html `<button type="submit" name="message" value="${one}">${one}</button>`), { attrs: { class: "demo-suggestions" } })}</section>`;
 }
 function planCard(exchange) {
     const plan = exchange.plan;
@@ -55,7 +55,7 @@ export function demoThreadHtml(exchanges, resultOf) {
     return html `${exchanges.map(exchange => {
         const parts = [
             html `<div class="demo-said demo-you"><p>${exchange.asked}</p></div>`,
-            html `<div class="demo-said demo-lead"><p class="demo-who">Lead</p><p>${exchange.reply}</p></div>`,
+            html `<div class="demo-said demo-lead"><p class="demo-who"><span class="demo-avatar" aria-hidden="true">L</span>Lead</p><p>${exchange.reply}</p></div>`,
             planCard(exchange),
         ];
         if (exchange.state === "working")
@@ -63,14 +63,14 @@ export function demoThreadHtml(exchanges, resultOf) {
         if (exchange.state === "ready" || exchange.state === "complete" || exchange.state === "sent-back")
             parts.push(resultCard(exchange, resultOf(exchange)));
         if (exchange.state === "complete") {
-            parts.push(html `<div class="demo-said demo-lead"><p class="demo-who">Lead</p><p>Done. That's the whole loop: ask, approve, Ready, Complete. Ask for something else whenever you like.</p></div>`, html `<section class="card demo-handoff" data-demo-handoff aria-label="Your own project"><h2>Now try it on your own project</h2><p>In your repository's folder, run:</p><pre class="demo-command"><code>${START_COMMAND}</code></pre><p class="meta">It opens in your browser, already signed in.</p></section>`);
+            parts.push(html `<div class="demo-said demo-lead"><p class="demo-who"><span class="demo-avatar" aria-hidden="true">L</span>Lead</p><p>Done. That's the whole loop: ask, approve, Ready, Complete. Ask for something else whenever you like.</p></div>`, html `<section class="card demo-handoff" data-demo-handoff aria-label="Your own project"><h2>Now try it on your own project</h2><p>In your repository's folder, run:</p><pre class="demo-command"><code>${START_COMMAND}</code></pre><p class="meta">It opens in your browser, already signed in.</p></section>`);
         }
         return html `<article class="demo-turn" id="demo-${exchange.id}">${parts}</article>`;
     })}`;
 }
 export function demoChatHtml(input) {
     const working = input.exchanges.some(one => one.state === "working");
-    return html `<div class="demo-chat">${input.problem === null ? "" : html `<p class="problem" role="alert">${input.problem}</p>`}<div id="demo-thread" class="demo-thread" aria-live="polite" data-version="${input.version}" data-working="${working ? "1" : "0"}">${demoThreadHtml(input.exchanges, input.resultOf)}</div>${postForm("/chat/demo/ask", html `<label for="demo-message" class="so-sr-only">Message the lead</label><textarea id="demo-message" name="message" rows="2" maxlength="500" placeholder="Ask the lead for a change" required></textarea><button type="submit" class="demo-primary">Send</button>`, { attrs: { class: "demo-composer" } })}</div>`;
+    return html `<div class="demo-chat${input.exchanges.length === 0 ? " demo-chat--empty" : ""}">${input.problem === null ? "" : html `<p class="problem" role="alert">${input.problem}</p>`}<div id="demo-thread" class="demo-thread" aria-live="polite" data-version="${input.version}" data-working="${working ? "1" : "0"}">${demoThreadHtml(input.exchanges, input.resultOf)}</div>${postForm("/chat/demo/ask", html `<label for="demo-message" class="so-sr-only">Message the lead</label><div class="demo-composer-card"><textarea id="demo-message" name="message" rows="1" maxlength="500" placeholder="Ask the lead for a change" required aria-describedby="demo-composer-hint"></textarea><div class="demo-composer-bar"><span id="demo-composer-hint">Enter to send · Shift + Enter for a new line</span><button type="submit" class="demo-primary demo-send" aria-label="Send"><svg aria-hidden="true" viewBox="0 0 16 16" width="16" height="16" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M8 13V3M3.5 7.5 8 3l4.5 4.5"/></svg></button></div></div>`, { attrs: { class: "demo-composer" } })}</div>`;
 }
 /**
  * Keeps a running build live: polls while one is working and swaps the

package/dist/demo.js

@@ -1044,14 +1044,14 @@ function seedDemoFlows(store, folder, now) {
         ["Parcel arrived crushed", "The box was crushed and two glasses inside are broken.", "Delivery problem", 0.91, "delivery", "Soon: the customer is waiting on it", true, 120],
         ["Where is my order and why was I billed?", "It hasn't arrived and there's a charge I don't recognise.", "Delivery problem", 0.58, "by-hand", "Soon: the customer is waiting on it", false, 45],
     ]) {
-        const card = store.addFlowCard({ flow: desk, title, description, stage: "sort", by: "Support form" }, at(minutes));
+        const card = store.addFlowCard({ flow: desk, title, description, stage: "sort", by: "Support form", byKind: "automation" }, at(minutes));
         const confident = sure >= 0.8;
         step(card, "sort", "sort", at(minutes - 1), confident ? `${answer}, ${Math.round(sure * 100)}% sure.` : `Not sure: ${Math.round(sure * 100)}% ${answer}.`, `${confident ? `${answer}, ${Math.round(sure * 100)}% sure.` : `Not sure: ${Math.round(sure * 100)}% ${answer}.`} How urgent is it? ${urgency.split(":")[0]}.`, { decisionJson: sorted(answer, sure, to, urgency, refund) });
         move(card, to, at(minutes - 1));
     }
     const replies = store.createFlow({ repo, name: "Customer replies", definitionJson: template("email-replies"), by: "demo" }, at(200));
     const drafted = (title, description, draft, minutes) => {
-        const card = store.addFlowCard({ flow: replies, title, description, stage: "write", by: "Contact form" }, at(minutes));
+        const card = store.addFlowCard({ flow: replies, title, description, stage: "write", by: "Contact form", byKind: "automation" }, at(minutes));
         step(card, "write", "draft", at(minutes - 1), `Drafted ${draft.split(/\s+/).length} words.`, draft, { log: `Claude (sonnet) · 4.2 s\n\n${draft}` });
         move(card, "check", at(minutes - 1));
         return card;

package/dist/desktop-update-gate.js

@@ -1,4 +1,5 @@
 import { activeCodingUpdateWork, installCodingUpdateGate, removeCodingUpdateGate } from "./coding-update.js";
+import { activeTerminalUpdateWork, installTerminalUpdateGate, removeTerminalUpdateGate } from "./terminal-catalog.js";
 export const UPDATE_PAUSED = "Toolroll is updating. Current work can finish; new work will resume after the update. Open Update status in the desktop app.";
 const prefix = "so_desktop_update_";
 const rows = (db) => db.prepare("SELECT name, sql FROM sqlite_master WHERE type='trigger' AND name GLOB 'so_desktop_update_*' ORDER BY name").all();
@@ -36,6 +37,7 @@ export function installUpdateGate(db, id) {
         throw error;
     }
     installCodingUpdateGate(db, id);
+    installTerminalUpdateGate(db, id);
 }
 export function removeUpdateGate(db, id) {
     const wanted = [...statements(id), ...statements(id, true)];
@@ -45,6 +47,7 @@ export function removeUpdateGate(db, id) {
         if (existing.some(row => !owns(wanted, row.sql)))
             throw Error("This update does not own the admission pause. Nothing was cleared.");
         removeCodingUpdateGate(db, id);
+        removeTerminalUpdateGate(db, id);
         for (const row of existing)
             db.exec(`DROP TRIGGER "${String(row.name)}"`);
         db.exec("COMMIT");
@@ -67,6 +70,8 @@ export function activeUpdateWork(db) {
         conversations: count("SELECT count(*) n FROM mate_turn WHERE state IN ('queued','running')") + count("SELECT count(*) n FROM chat_turn WHERE state IN ('queued','running')"),
         stopping: count("SELECT count(*) n FROM run_stop WHERE settled_at IS NULL"),
         ...activeCodingUpdateWork(db),
+        // Live terminals in a console that is still running (terminal-catalog.ts).
+        ...activeTerminalUpdateWork(db),
     };
 }
 /** Last admission race closes in the same SQLite write transaction as the
@@ -77,6 +82,7 @@ export function freezeUpdateGate(db, id) {
         if (!updateGateOwned(db, id))
             throw Error("The update no longer owns admission.");
         installCodingUpdateGate(db, id);
+        installTerminalUpdateGate(db, id);
         const idle = Object.values(activeUpdateWork(db)).every(n => n === 0);
         if (idle) {
             for (const row of rows(db))

package/dist/desktop-update.d.ts

@@ -94,7 +94,6 @@ export declare function prepareDesktopUpdate(stateDir: string, installed: string
 export declare function sqliteLock(file: string, busyTimeoutMs?: number): DatabaseSync | null;
 export declare const installationLock: (j: UpdateJournal) => DatabaseSync | null;
 export declare function desktopUpdateStatus(stateDir: string): {
-    version?: never;
     active: boolean;
     phase: string;
     detail: string;
@@ -108,6 +107,7 @@ export declare function desktopUpdateStatus(stateDir: string): {
     wasRunning?: never;
     backupPath?: never;
     updateId?: never;
+    version?: never;
     buildId?: never;
     workDir?: never;
 } | {

package/dist/discord-chat.js

@@ -8,7 +8,7 @@ import { roomCommand } from "./chat-rooms.js";
 import { ChatState, ChatDeliveryError, chatHash, partContent, } from "./chat-delivery-state.js";
 import { readChatPart } from "./contracts/chat-content.js";
 import { readDiscordButtonToken, readDiscordComponentInteraction } from "./contracts/discord-callback.js";
-import { processChatEvent, planChatNotifications, channelAccess, chatObject as object, planRoomMessages, } from "./chat-delivery.js";
+import { processChatEvent, planChatNotifications, channelAccess, chatObject as object, planRoomMessages, heldForWatch, } from "./chat-delivery.js";
 import { chatResultHref } from "./chat-controls.js";
 import { LEAD_MESSAGE_MAX_CHARS } from "./lead.js";
 import { discordPlain, renderReply } from "./reply-shape.js";
@@ -379,6 +379,9 @@ export async function deliverDiscordPart(options) {
                     fail_if_not_exists: false,
                 };
         }
+        // The watch, at the last moment before the network (cockpit §3).
+        if (heldForWatch(state, store, row.id, event, binding.approver, content, now))
+            return true;
         const answer = await options.api(target ? "PATCH" : "POST", `/channels/${destination}/messages${target ? `/${target}` : ""}`, args, file);
         if (!discordId(answer.id) ||
             answer.channel_id !== destination ||

package/dist/doctor.js

@@ -110,7 +110,7 @@ function reinstallCommand(args) {
     const freeform = new Set(["--runner", "--repo", "--token-file", "--pool", "--model", "--repair-model", "--plan-model"]);
     const numeric = new Set(["--max", "--turns", "--tick-every", "--bridge-every", "--reconcile-every", "--max-open-decisions"]);
     const enums = {
-        "--provider": ["claude", "codex", "gemini", "openrouter"],
+        "--provider": ["claude", "codex", "gemini", "openrouter", "opencode", "cursor", "cline", "qwen", "goose"],
         "--plan-provider": ["claude", "codex", "gemini", "openrouter"],
         "--containment": ["observed", "preferred", "required"],
     };

package/dist/egress-bridge.d.ts

@@ -0,0 +1,17 @@
+/** The prefix of a bridge folder in the temp folder (agent-fence.ts RUN_FOLDER_PREFIXES denies every other run's). */
+export declare const BRIDGE_PREFIX = "so-net-";
+/** The forwarder, run inside the namespace as `node forward.mjs <folder> <port>... -- <command>`. Zero dependencies. */
+export declare const FORWARDER_SOURCE: string;
+/** Whether a bridge made under `root` keeps every socket path within the limit (its folder and `<port>.sock`). */
+export declare function bridgeFits(root: string): boolean;
+export type EgressBridge = {
+    folder: string;
+    forwarder: string;
+    close: () => Promise<void>;
+};
+/**
+ * Serve one socket per port (each relayed to that port on the host's loopback) in a fresh owner-only folder under
+ * `root`: the plane's own bridge folder beside the database (agent-fence.ts BRIDGE_DIR), which every build's fence
+ * hides from launch, so no other build can change the forwarder or reach the sockets.
+ */
+export declare function startEgressBridge(ports: readonly number[], root?: string): Promise<EgressBridge>;

package/dist/egress-bridge.js

@@ -0,0 +1,111 @@
+/**
+ * How a Linux build with a network of its own reaches its proxy and tool broker (agent-fence.ts linuxFenced). The
+ * plane serves one unix socket per port in a folder of its own (`<folder>/<port>.sock`, each relayed to that port on
+ * the host's loopback); bubblewrap binds the folder read-only into the build's namespace, where the forwarder below
+ * listens on the namespace's own 127.0.0.1 at the same ports and relays each connection to its socket. Only those
+ * ports cross: nothing else of the host's network is reachable, and the relay never opens a connection of its own.
+ *
+ * The forwarder is written into the folder at launch (the plane's own file, read-only to the build), so it never runs
+ * from an installation path a fence might hide or a build could change.
+ */
+import { chmodSync, lstatSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { connect, createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/** The prefix of a bridge folder in the temp folder (agent-fence.ts RUN_FOLDER_PREFIXES denies every other run's). */
+export const BRIDGE_PREFIX = "so-net-";
+/** The forwarder, run inside the namespace as `node forward.mjs <folder> <port>... -- <command>`. Zero dependencies. */
+export const FORWARDER_SOURCE = String.raw `import { connect, createServer } from "node:net";
+import { spawn } from "node:child_process";
+const argv = process.argv.slice(2);
+const split = argv.indexOf("--");
+if (split < 1 || split === argv.length - 1) { process.stderr.write("toolroll forwarder: usage <folder> <port>... -- <command>\n"); process.exit(2); }
+const folder = argv[0];
+const ports = argv.slice(1, split).map(Number);
+const command = argv.slice(split + 1);
+let ready = 0;
+for (const port of ports) {
+  const server = createServer(client => {
+    const upstream = connect(folder + "/" + port + ".sock");
+    client.on("error", () => upstream.destroy());
+    upstream.on("error", () => client.destroy());
+    client.pipe(upstream);
+    upstream.pipe(client);
+  });
+  server.on("error", error => { process.stderr.write("toolroll forwarder: " + error.message + "\n"); process.exit(70); });
+  server.listen(port, "127.0.0.1", () => { if (++ready === ports.length) start(); });
+}
+if (ports.length === 0) start();
+function start() {
+  const child = spawn(command[0], command.slice(1), { stdio: "inherit" });
+  for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) process.on(signal, () => child.kill(signal));
+  child.on("error", error => { process.stderr.write("toolroll forwarder: " + error.message + "\n"); process.exit(127); });
+  child.on("exit", (code, signal) => {
+    if (signal === null) process.exit(code ?? 1);
+    // Die the way the agent died: this process's own handlers (which only pass a signal on) step aside first.
+    process.removeAllListeners(signal);
+    process.kill(process.pid, signal);
+    setTimeout(() => process.exit(128), 1000).unref();
+  });
+}
+`;
+/** The longest a unix socket's path may be here (macOS 104 bytes, Linux 108, with room to spare). */
+const SOCKET_PATH_MAX = 100;
+/** Whether a bridge made under `root` keeps every socket path within the limit (its folder and `<port>.sock`). */
+export function bridgeFits(root) {
+    return join(root, `${BRIDGE_PREFIX}XXXXXX`, "65535.sock").length <= SOCKET_PATH_MAX;
+}
+/**
+ * Serve one socket per port (each relayed to that port on the host's loopback) in a fresh owner-only folder under
+ * `root`: the plane's own bridge folder beside the database (agent-fence.ts BRIDGE_DIR), which every build's fence
+ * hides from launch, so no other build can change the forwarder or reach the sockets.
+ */
+export async function startEgressBridge(ports, root = tmpdir()) {
+    // The root must be a real folder of this user's alone, never a link a build could have planted before it existed.
+    const held = lstatSync(root);
+    if (held.isSymbolicLink() || !held.isDirectory() || (process.getuid !== undefined && held.uid !== process.getuid()) || (root !== tmpdir() && (held.mode & 0o077) !== 0)) {
+        throw new Error(`the bridge folder ${root} isn't a private folder of this user's`);
+    }
+    if (!bridgeFits(root))
+        throw new Error(`the bridge folder ${root} is too deep for a socket path`);
+    const folder = mkdtempSync(join(root, BRIDGE_PREFIX));
+    chmodSync(folder, 0o700);
+    const forwarder = join(folder, "forward.mjs");
+    writeFileSync(forwarder, FORWARDER_SOURCE, { mode: 0o500, flag: "wx" });
+    const servers = [];
+    const sockets = new Set();
+    try {
+        for (const port of ports) {
+            const server = createServer(client => {
+                sockets.add(client);
+                const upstream = connect(port, "127.0.0.1");
+                sockets.add(upstream);
+                const drop = () => { client.destroy(); upstream.destroy(); };
+                client.on("error", drop);
+                upstream.on("error", drop);
+                client.on("close", () => { sockets.delete(client); upstream.destroy(); });
+                upstream.on("close", () => { sockets.delete(upstream); client.destroy(); });
+                client.pipe(upstream);
+                upstream.pipe(client);
+            });
+            await new Promise((done, fail) => { server.once("error", fail); server.listen(join(folder, `${port}.sock`), () => { server.off("error", fail); done(); }); });
+            servers.push(server);
+        }
+    }
+    catch (error) {
+        for (const server of servers)
+            server.close();
+        rmSync(folder, { recursive: true, force: true });
+        throw error;
+    }
+    return {
+        folder,
+        forwarder,
+        close: async () => {
+            for (const socket of sockets)
+                socket.destroy();
+            await Promise.all(servers.map(server => new Promise(done => server.close(() => done()))));
+            rmSync(folder, { recursive: true, force: true });
+        },
+    };
+}

package/dist/egress.d.ts

@@ -0,0 +1,119 @@
+import { type Lookup } from "./scout-net.js";
+/** The policy's shape version: a worker enforces the versions it knows and refuses any other. */
+export declare const NETWORK_POLICY_VERSION = 1;
+/** `allowlist`: only the snapshot's hosts, through the run's proxy. `open`: anywhere (an approver's explicit choice). */
+export type NetworkMode = "allowlist" | "open";
+/**
+ * What a build may reach on this machine's own loopback. Linux gives every build a loopback of its own, so this only
+ * matters on macOS, where one loopback serves everything and the sandbox can't admit some local ports while refusing
+ * others: `proxy-only` (the default) admits nothing local but the run's own proxy and tool broker; `any` admits every
+ * local service on this Mac — local test servers, and also anything else listening here — an approver's explicit choice.
+ */
+export type LoopbackMode = "any" | "proxy-only";
+/** The network a scope was approved with (sealed in its execution profile). */
+export type NetworkProfile = {
+    version: 1;
+    mode: NetworkMode;
+    hosts: string[];
+    loopback: LoopbackMode;
+};
+/** A project's own network setting (an approver's): what new scopes of it are written with. */
+export type ProjectNetwork = {
+    mode: NetworkMode;
+    hosts: string[];
+    loopback: LoopbackMode;
+};
+export declare const PROJECT_NETWORK_DEFAULT: ProjectNetwork;
+/** At most this many hosts a project adds (a list longer than this is a different policy: open). */
+export declare const MAX_NETWORK_HOSTS = 200;
+/** At most this many in a sealed snapshot: the project's, plus its provider's and every registry's. */
+export declare const MAX_SNAPSHOT_HOSTS: number;
+/**
+ * A host as a policy names it: lowercase ASCII (an international name in its punycode form), no trailing dot, at
+ * least two labels, each 1–63 letters, digits or hyphens; or `*.` and such a name, for every name under it. Never an
+ * IP address, a port, a path or a bare top-level name. Null when it is none of these.
+ */
+export declare function normalizeHost(input: string): string | null;
+/** Whether `host` (as a client named it) is one a policy's list admits: an exact name, or a name under a `*.` entry. */
+export declare function hostAllowed(host: string, hosts: readonly string[]): boolean;
+/**
+ * Each provider's own hosts (catalog version 1): its model API and the sign-in refresh its CLI needs. Codex starts
+ * its harness outside its command sandbox, so its hosts matter only to what its commands may reach. An ACP agent
+ * talks to whatever model service it was set up with; its row names the hosts its own service uses.
+ */
+export declare const PROVIDER_HOSTS: Readonly<Record<string, readonly string[]>>;
+/** A package ecosystem a project's files name, and the registry hosts its installs read from. */
+export type Ecosystem = "npm" | "python" | "rust" | "go" | "ruby" | "jvm";
+export declare const REGISTRY_HOSTS: Readonly<Record<Ecosystem, readonly string[]>>;
+/** The ecosystems a list of repository paths names (requirements-*.txt counts as Python). */
+export declare function ecosystemsOf(paths: readonly string[]): Ecosystem[];
+/**
+ * The ecosystems the project's own checkout names: its files a few folders deep, read straight from the folder the
+ * plane registered (which no build can write: agent-fence.ts taskBoundary), never a build's worktree. No process is
+ * started and nothing in the repository runs. An unreadable folder names none: its builds reach the provider and the
+ * project's own hosts only.
+ */
+export declare function repositoryEcosystems(repo: string): Ecosystem[];
+/** The network a new scope is written with: the project's setting, its provider's hosts and its ecosystems' registries. */
+export declare function resolveNetwork(provider: string, project: ProjectNetwork, ecosystems: readonly Ecosystem[]): NetworkProfile;
+/** The network of a launch nothing sealed one for (a planner, a check): its provider's own hosts and nothing else. */
+export declare function providerOnlyNetwork(provider: string): NetworkProfile;
+/**
+ * The network an approval sealed before network policies existed runs under: a deliberate narrowing (provider hosts
+ * and the repository's registries, nothing the project added since, local services of this Mac out of reach). Never
+ * widened by a setting changed after it was approved.
+ */
+export declare function legacyNetwork(provider: string, ecosystems: readonly Ecosystem[]): NetworkProfile;
+/** Strict re-hydration (scope.ts profileFromJson): exactly the keys this code writes, every host normalized, or null. */
+export declare function networkFromValue(value: unknown): NetworkProfile | null;
+/** A project setting as saved (store.ts project_network), or null when it isn't one this code wrote. */
+export declare function projectNetworkFromValue(value: unknown): ProjectNetwork | null;
+/** The network in plain words, for an approval card and a run's record. */
+export declare function networkWords(network: NetworkProfile | null): string;
+/** What the run's proxy saw: connections it made and refused, by host (at most HOST_LIMIT hosts, the rest summed). */
+export type EgressCounts = {
+    connections: number;
+    refused: number;
+    hosts: {
+        host: string;
+        connections: number;
+        refused: number;
+    }[];
+    otherHosts: number;
+};
+/** What a run's record keeps about its network: the mode it ran under, whether a caller's own proxy carried it, how many
+ * hosts its list held, and what the run's proxy saw. */
+export type RunNetworkRecord = {
+    mode: "open" | "allowlist";
+    phase: "agent";
+    via?: true;
+    hosts?: number;
+    loopback?: LoopbackMode;
+    counts?: EgressCounts;
+};
+/** A stored record read back strictly: anything this code didn't write reads as none. */
+export declare function runNetworkFromValue(value: unknown): RunNetworkRecord | null;
+export type EgressProxy = {
+    /** The proxy's address with this run's credentials, for HTTPS_PROXY and the like. */
+    url: string;
+    port: number;
+    counts: () => EgressCounts;
+    close: () => Promise<void>;
+};
+/** Every proxy setting a program might read, both cases, so none falls back to a direct connection the OS refuses. */
+export declare function proxyEnv(proxy: EgressProxy, loopback: LoopbackMode): Record<string, string>;
+/**
+ * Start one run's proxy on loopback. Only a client presenting this run's credentials is served (another run's agent
+ * on the same machine can't borrow it). CONNECT goes only to port 443 and plain HTTP only to port 80, only to a host
+ * the run's list admits (matched by name before it is resolved), only to public addresses (the proxy resolves the
+ * name itself and connects to exactly the addresses it checked). A plain HTTP request's Host must be the URL's host.
+ */
+export declare function startEgressProxy(options: {
+    hosts: readonly string[];
+    lookup?: Lookup;
+    decided?: (host: string, allowed: boolean, why: string) => void;
+    /** Tests only: which resolved addresses may be reached (default: public internet addresses), and the port an
+     * approved request is relayed to (default: the one it asked for). */
+    addressAllowed?: (address: string) => boolean;
+    upstreamPort?: (port: number) => number;
+}): Promise<EgressProxy>;