toolroll 0.9.104 → 0.9.105

package/dist/project-tools.js

@@ -1,24 +1,3 @@
-/**
- * Project tools (v80): the MCP servers one project's builds may use.
- *
- * A project's list REPLACES everything else a build could load: the
- * operator's global Claude and Codex MCP servers, plugins' servers and a
- * repository's own `.mcp.json` are all shut out, and each build gets
- * exactly the servers its project lists — sealed at approval, so a tool
- * added later reaches only work approved after it, while a tool removed
- * leaves every build at once. Reviewers and the lead chat never get tools.
- *
- * Secret values (API keys, tokens, any env value) never enter the
- * database, a chat, a card or a log: they live in the operating system's
- * keychain (tool-secret-store.ts) or, where there is none, in one 0600 file
- * per tool in `tool-secrets` beside the database (files kept before under
- * ~/.toolroll/tool-secrets/, or an older name's, move in on first use).
- * They are written only from the console's password-gated screen, read when a
- * run starts, and reach only that run's tool broker (tool-broker.ts), which
- * gives them to the project's server processes and sign-in headers — never to
- * the agent. A tool connected by signing in gives a run only an access token
- * of its own (oauth-run-token.ts).
- */
 import { prepareProtectedStorage, storageRefusalOf } from "./protected-storage.js";
 import { inReadOnlyRequest } from "./read-only-request.js";
 import { toolRefusal } from "./policy.js";
@@ -41,16 +20,12 @@ import { SecretStoreError, destroyOwnFile, prepareSecretFolder, registerSecretFo
 import { ACCESS, GRANTED, REFRESH, mintRunToken, mintsRunTokens, oneAtATime, runScope, scopeList, signedIn } from "./oauth-run-token.js";
 import { HEADER_NAME, SECRET_NAME, TOOL_NAME as NAME, TOOL_SPEC_LIMITS as LIMITS, readToolSpec } from "./contracts/integration-metadata.js";
 import { canonicalJson } from "./canonical-json.js";
-/** Env names a tool may never claim: the process's own plumbing, every
- * provider credential, and anything that changes how a program or its
- * interpreter loads (a secret's value must stay data, never code). */
 const RESERVED_ENV_NAMES = new Set(["PATH", "HOME", "USER", "LOGNAME", "SHELL", "LANG", "TMPDIR", "TERM", "PWD", "IFS", "ENV", "BASH_ENV", "PS4", "PROMPT_COMMAND",
     "NODE_OPTIONS", "NODE_PATH", "NODE_EXTRA_CA_CERTS", "NPM_CONFIG_PREFIX", "NPM_CONFIG_USERCONFIG", "GCONV_PATH", "SSL_CERT_FILE", "SSL_CERT_DIR",
     "JAVA_TOOL_OPTIONS", "_JAVA_OPTIONS", "JDK_JAVA_OPTIONS", "DOTNET_STARTUP_HOOKS",
     "ANTHROPIC_API_KEY", "OPENAI_API_KEY", "OPENROUTER_API_KEY", "GEMINI_API_KEY", "GOOGLE_API_KEY", "CODEX_HOME", "CLAUDE_CONFIG_DIR", "MCP_TIMEOUT"]);
 const RESERVED_ENV_PREFIX = /^(LD_|DYLD_|PYTHON|PERL5|PERLLIB|RUBY|GIT_|NODE_|NPM_CONFIG_|BUN_|DENO_|UV_|PIP_|LC_|XDG_|CLAUDE_|CODEX_|ANTHROPIC_|OPENAI_)/;
 const RESERVED_ENV = { has: (name) => RESERVED_ENV_NAMES.has(name) || RESERVED_ENV_PREFIX.test(name) };
-/** Common servers, pinned to exact versions: the lead suggests from here first. */
 export const TOOL_CATALOG = [
     { label: "Playwright", name: "playwright", transport: "stdio", command: "npx", args: ["-y", "@playwright/mcp@0.0.82", "--headless"], url: null, secrets: [], bearer: null, headerSecrets: {},
         about: "Drives a real browser to open pages, click through them and take screenshots." },
@@ -66,7 +41,6 @@ export const TOOL_CATALOG = [
         about: "Reads Sentry issues and errors." },
     { label: "Supabase (read-only)", name: "supabase", transport: "stdio", command: "npx", args: ["-y", "@supabase/mcp-server-supabase@0.13.0", "--read-only"], url: null, secrets: [{ name: "SUPABASE_ACCESS_TOKEN", optional: false }], bearer: null, headerSecrets: {},
         about: "Reads Supabase tables and schema, without changing anything." },
-    // Figma's Dev Mode server, run by its desktop app on this computer and signed in as the app is: no key.
     { label: "Figma (desktop app)", name: "figma-desktop", transport: "http", command: null, args: [], url: "http://127.0.0.1:3845/mcp", secrets: [], bearer: null, headerSecrets: {},
         about: "Code, images, variables and metadata from what you select in the Figma desktop app." },
 ];
@@ -75,7 +49,6 @@ export const LOCAL_APPS = [
         offline: "The Figma desktop app isn't running, or its Dev Mode MCP server is off. Open Figma and turn the server on in Preferences.",
         reads: ["code", "image", "screenshot", "variable", "defs", "metadata", "design", "context", "connect", "map", "figjam"] },
 ];
-/** The local app a project's tool is, when it is one exactly as listed (same name and address). */
 export function localAppOf(spec) {
     const app = LOCAL_APPS.find(one => one.tool === spec.name);
     return app !== undefined && spec.url !== null && spec.url === catalogTool(app.tool)?.url ? app : null;
@@ -83,7 +56,6 @@ export function localAppOf(spec) {
 export function catalogTool(id) {
     return TOOL_CATALOG.find(one => one.name === id) ?? null;
 }
-/** What a build is held to: how the server starts and which secrets it names — never their values or its description. */
 export function toolDigest(spec) {
     const { about: _about, ...terms } = spec;
     return createHash("sha256").update(`standing-orders:tool:v1:${canonicalJson(terms)}`, "utf8").digest("hex").slice(0, 32);
@@ -95,10 +67,6 @@ const str = (value, cap, what) => {
         throw new Error(`${what} cannot contain control characters.`);
     return value.trim();
 };
-/**
- * A tool definition from any source (catalog, console form, the lead, an import, a saved row), checked whole and made
- * the spec its schema (src/contracts/integration-metadata.ts) says. Throws in plain words.
- */
 export function validateToolSpec(input) {
     const name = str(input["name"], LIMITS.name, "A short name").toLowerCase();
     if (!NAME.test(name))
@@ -162,7 +130,6 @@ export function validateToolSpec(input) {
         : TOOL_CATALOG.find(one => one.name === name)?.about
             ?? (transport === "http" ? `Tools from ${new URL(url).hostname}.` : `Tools from ${programName(command, args)}.`);
     const spec = { name, transport, command, args, url, secrets, bearer, headerSecrets, about };
-    // Values belong in the secret store; a key typed into a command, argument or address is refused.
     if (scanForSecrets([command ?? "", ...args, url ?? "", about].join("\n")).length > 0)
         throw new Error("That looks like a key or token in the tool's settings. Name it as a secret instead; its value is set on the secure Tools screen.");
     const checked = readToolSpec(spec);
@@ -170,57 +137,38 @@ export function validateToolSpec(input) {
         throw new Error(`That tool is not valid: ${checked.issues.map(issue => issue.line).join("; ")}`);
     return checked.value;
 }
-/** What a local tool is, in a word: the package a runner like npx starts, else the program's own name. */
 function programName(command, args) {
     const base = command.split(/[\\/]/).pop() ?? command;
     const runner = ["npx", "bunx", "uvx", "pnpx", "pipx"].includes(base);
     const target = runner ? args.find(arg => !arg.startsWith("-")) : undefined;
     return target === undefined ? base : target.replace(/@[^@/]*$/, "") || target;
 }
-/** How the tool starts, in one line a person can check. Never a secret value. */
 export function toolCommandLine(spec) {
     if (spec.transport === "http")
         return `${spec.url}${spec.bearer === null ? "" : ` (signs in with ${spec.bearer})`}`;
     return [spec.command, ...spec.args].map(part => /^[A-Za-z0-9@%+=:,./_-]+$/.test(part ?? "") ? part : JSON.stringify(part)).join(" ");
 }
-// ---- secrets -----------------------------------------------------------------
-/**
- * Where tool secrets were kept before (an existing ~/.toolroll/tool-secrets, or an older name's), read once when
- * Toolroll starts so their files move in on first use. Never where new secrets go.
- */
 export function legacyToolSecretsDir(home = homedir()) {
     const found = namedPath(home, ["tool-secrets"], { dot: true });
     return existsSync(found) ? found : null;
 }
-/** Commands that can start builds or serve the console: Toolroll's folder for secrets is made before any build runs. */
 export const SECRETS_FIRST = new Set(["serve", "up", "daemon", "watch", "worker", "tick", "build", "run", "reconcile", "bridge"]);
-/**
- * Toolroll's folder for the secrets it holds, beside `databaseFile`, checked against the sealing key the database
- * recorded: made now when `eager` (a command that can start builds), else the first time a secret is used.
- * A folder that can't be used is said in Settings and `toolroll integrations`; every secret is refused until then.
- */
 export function startToolSecrets(store, databaseFile, clock, options) {
     const anchor = { read: () => store.toolSecretKeyDigest(), swap: (expected, next) => store.swapToolSecretKeyDigest(expected, next, clock()) };
-    // The old folder is found once, at the first start of a command that can start builds (so before any build ran), then
-    // read from the record.
     const state = dirname(databaseFile), legacy = store.toolSecretLegacyDir(() => legacyToolSecretsDir(), clock(), { record: options.eager });
     if (options.eager)
         prepareSecretFolder(state, anchor, { standing: true, legacy });
     else
         registerSecretFolder(state, anchor, { legacy });
 }
-/** Toolroll's folder for secrets (tool-secret-store.ts): beside the database Toolroll started with, or a test's `state`. */
 export function toolSecretsDir(state) {
     return secretFolder(state).dir;
 }
 const repoHash = (repo) => createHash("sha256").update(repo).digest("hex").slice(0, 16);
 const toolName = (tool) => { if (!NAME.test(tool))
     throw new Error("Choose a tool by its name."); return tool; };
-/** A tool's own file in the folder: its secrets where there's no keychain, or the names of those set. */
 const toolFile = (folder, repo, tool, suffix, make = false) => pathIn(folder.dir, [repoHash(repo), `${toolName(tool)}${suffix}`], { make });
-/** The same tool's file where secrets were kept before Toolroll's folder; null when there was none. */
 const legacyFile = (folder, repo, tool) => folder.legacy === null ? null : pathIn(folder.legacy, [repoHash(repo), `${toolName(tool)}.json`]);
-/** A tool's keychain item: this Toolroll's folder and the project, hashed, and the tool's name. Never a secret. */
 const secretItem = (folder, repo, tool) => ({ service: serviceOf(folder), account: `${repoHash(repo)}.${toolName(tool)}` });
 const secretValues = (parsed) => parsed === null || typeof parsed !== "object" || Array.isArray(parsed) ? {}
     : Object.fromEntries(Object.entries(parsed).filter((entry) => SECRET_NAME.test(entry[0]) && typeof entry[1] === "string"));
@@ -232,12 +180,10 @@ const parsedValues = (text) => {
         throw new SecretStoreError("A tool's stored secrets are damaged.");
     }
 };
-/** A secrets file (owner-only, never through a link); null when there is none. */
 function readSecretFile(file) {
     const text = readOwnFile(file);
     return text === null ? null : parsedValues(text);
 }
-/** What the current store holds for a tool: its keychain item, or (no keychain) its file in Toolroll's folder; null when nothing. */
 function readStored(backend, folder, repo, tool) {
     if (backend === null)
         return readSecretFile(toolFile(folder, repo, tool, ".json"));
@@ -260,9 +206,7 @@ function writeStored(backend, folder, repo, tool, values, options = {}) {
         writeOwnFile(file, JSON.stringify(values));
     return "ok";
 }
-/** One change to a tool's secrets at a time, across Toolroll's processes, re-entrant within one. */
 const withToolLock = (folder, repo, tool, work) => withSecretLock(folder, `${repoHash(repo)}.${toolName(tool)}`, work);
-/** The names of a tool's secrets that have a value, kept beside them so a page never reads a value to say so. */
 function writeNames(folder, repo, tool, names) {
     const file = toolFile(folder, repo, tool, ".names.json", true);
     if (names.length === 0)
@@ -270,19 +214,12 @@ function writeNames(folder, repo, tool, names) {
     else
         writeOwnFile(file, JSON.stringify([...names].sort()));
 }
-/**
- * A tool's secrets moved into the current store from where they were kept before — the old home folder, or (now that
- * there is a keychain) its file in Toolroll's folder — the first time they are used: stored, read back and compared,
- * and only then is the file destroyed. What the store already holds (an earlier move, or a change since) wins over
- * the file. A failure leaves the file as it was, and says so.
- */
 function moveIn(backend, folder, repo, tool) {
     const sources = [legacyFile(folder, repo, tool), backend === null ? null : toolFile(folder, repo, tool, ".json")].filter((one) => one !== null && existsSync(one));
     if (sources.length === 0)
         return;
     withToolLock(folder, repo, tool, () => {
         for (const file of sources) {
-            // Damaged, a link, or not plainly Toolroll's: kept as it is, and never used.
             let values;
             try {
                 values = readSecretFile(file);
@@ -306,7 +243,7 @@ function moveIn(backend, folder, repo, tool) {
                             if (backend !== null)
                                 removeValue(backend, secretItem(folder, repo, tool));
                         }
-                        catch { /* the file stays the copy that counts */ }
+                        catch { }
                         throw new SecretStoreError("A tool's secrets couldn't be moved to the keychain; they stay in their file until they can.");
                     }
                 }
@@ -317,11 +254,9 @@ function moveIn(backend, folder, repo, tool) {
         }
     });
 }
-/** A tool's secret values. Read only to test it, change it or start a run: a page reads which are set (secretsSetFor). */
 export function readToolSecrets(repo, tool, state) {
     const folder = secretFolder(state);
     const backend = secretBackend();
-    // A page visit moves nothing (docs/plans/get-side-effects.md): it reads the store, else the file not yet moved in.
     if (inReadOnlyRequest()) {
         const stored = readStored(backend, folder, repo, tool);
         if (stored !== null)
@@ -334,18 +269,16 @@ export function readToolSecrets(repo, tool, state) {
                 if (values !== null)
                     return values;
             }
-            catch { /* kept as it is, and never used */ }
+            catch { }
         }
         return {};
     }
     moveIn(backend, folder, repo, tool);
     return readStored(backend, folder, repo, tool) ?? {};
 }
-/** Set (or, with an empty value, clear) one secret of one tool. */
 export function setToolSecret(repo, tool, name, value, state) {
     setToolSecrets(repo, tool, { [name]: value }, state);
 }
-/** Set (or, with empty values, clear) some secrets of one tool, in one change. */
 export function setToolSecrets(repo, tool, values, state) {
     for (const [name, value] of Object.entries(values)) {
         if (!SECRET_NAME.test(name) || RESERVED_ENV.has(name))
@@ -378,16 +311,10 @@ export function clearToolSecrets(repo, tool, state) {
         rmSync(toolFile(folder, repo, tool, ".names.json"), { force: true });
     });
 }
-/**
- * One renewal of a sign-in at a time, across Toolroll's processes (a lock in its folder) and within one: a service
- * that rotates its refresh token on every use would otherwise see the same one twice, and whichever answer was saved
- * last would be the newest only by luck.
- */
 export function renewingSignIn(repo, tool, state, work) {
     const folder = secretFolder(state);
     return oneAtATime(`${folder.root}\0${repo}\0${tool}`, () => withSecretLockAsync(folder, `${repoHash(repo)}.${toolName(tool)}.renew`, work));
 }
-/** Required secrets with no value yet: the tool is left out of builds until they are set. */
 export function missingSecrets(spec, values) {
     return spec.secrets.filter(one => !one.optional && (values[one.name] ?? "") === "").map(one => one.name);
 }
@@ -491,12 +418,6 @@ function fromCodexEntry(raw, environment) {
     }
     return null;
 }
-/**
- * The MCP servers this computer already configures for a project: the
- * repository's `.mcp.json`, Claude's global and per-project servers, and
- * Codex's (from `codex mcp list --json`, passed in). The first of each
- * name wins; unusable entries are left out.
- */
 export function discoverTools(repo, codexServers, home = homedir(), environment = process.env, projectConfig) {
     const found = [];
     const add = (one) => { if (one !== null && !found.some(other => other.spec.name === one.spec.name))
@@ -510,8 +431,6 @@ export function discoverTools(repo, codexServers, home = homedir(), environment
             return null;
         }
     };
-    // The project's own file as given (the console reads it off its thread: folder-look.ts), else as last read there
-    // (savedProjectMcp), else read here (the CLI and the worker).
     const project = projectConfig !== undefined ? projectConfig : savedProjectMcp.has(repo) ? savedProjectMcp.get(repo) ?? null : readJson(join(repo, ".mcp.json"));
     for (const [name, raw] of Object.entries((project?.["mcpServers"] ?? {})))
         add(fromClaudeEntry(name, raw, "this project's .mcp.json"));
@@ -525,23 +444,16 @@ export function discoverTools(repo, codexServers, home = homedir(), environment
         add(fromCodexEntry(raw, environment));
     return found;
 }
-// ---- the Test button --------------------------------------------------------------
 const PROTOCOL = "2025-06-18";
 const initialize = (id) => ({ jsonrpc: "2.0", id, method: "initialize", params: { protocolVersion: PROTOCOL, capabilities: {}, clientInfo: { name: "toolroll", version: "1" } } });
 function toolNames(result) {
     const tools = result?.tools;
     return Array.isArray(tools) ? tools.map(one => one.name).filter((name) => typeof name === "string").slice(0, 200) : [];
 }
-/** Start the server once, ask for its tools, and stop it: the proof a build can use it. */
 export async function testTool(spec, values, options) {
     const answer = await exchange(spec, values, { method: "tools/list", params: {}, doing: "listing its tools" }, options);
     return answer.ok ? { ok: true, tools: toolNames(answer.result) } : answer;
 }
-/**
- * Start the server once and read what each of its tools does (v94): the name,
- * its description, what input it takes, and whether it says it only reads.
- * A subagent is offered these, each under its own rule.
- */
 export async function listProjectToolActions(spec, values, options) {
     const answer = await exchange(spec, values, { method: "tools/list", params: {}, doing: "listing its tools" }, options);
     return answer.ok ? { ok: true, actions: toolActions(answer.result) } : answer;
@@ -558,11 +470,6 @@ export function toolActions(result) {
         return [{ name: one.name, about: typeof one.description === "string" ? safeLine(one.description).slice(0, 300) : "", input, readOnly: one.annotations?.readOnlyHint === true }];
     }).slice(0, 100);
 }
-/**
- * Start the server once, call one of its tools, and stop it (v87): a flow's
- * "Use a tool" step. The answer's text parts are kept; a tool that says it
- * failed (isError) is an answer, not trouble reaching it.
- */
 export async function callProjectTool(spec, values, name, args, options) {
     const answer = await exchange(spec, values, { method: "tools/call", params: { name, arguments: args }, doing: `using ${name}` }, options);
     if (!answer.ok)
@@ -574,7 +481,6 @@ export async function callProjectTool(spec, values, name, args, options) {
     return { ok: true, text, isError: result.isError === true };
 }
 async function exchange(spec, values, request, options) {
-    // The server's fence may still be on its way (toolServerFor): an answer that isn't used is never an unhandled failure.
     const served = Promise.resolve(options.server);
     served.catch(() => undefined);
     const missing = missingSecrets(spec, values);
@@ -583,7 +489,6 @@ async function exchange(spec, values, request, options) {
     const timeoutMs = options.timeoutMs ?? 60_000;
     if (spec.transport === "http")
         return exchangeHttp(spec, values, timeoutMs, request);
-    // A local server starts only in the server fence its caller made (toolServerFor), never bare.
     const server = await served;
     if ("problem" in server)
         return { ok: false, problem: server.problem };
@@ -598,7 +503,6 @@ function exchangeStdio(spec, values, timeoutMs, base, omit, request, fence) {
         let child;
         try {
             const launch = confined(spec.command, spec.args, { ...(fence ?? {}), temp: env["TMPDIR"] });
-            // A fenced server gets no chat or vault variable (protected-storage.ts) but the tool's own secrets, set by name.
             child = spawn(launch.file, launch.args, { env: fence === null ? { ...env, ...launch.env } : { ...Object.fromEntries(Object.entries(env).filter(([name]) => !isProtectedEnvName(name) || Object.hasOwn(values, name))), ...launch.env }, stdio: ["pipe", "pipe", "pipe"], detached: process.platform !== "win32" });
         }
         catch (error) {
@@ -621,14 +525,14 @@ function exchangeStdio(spec, values, timeoutMs, base, omit, request, fence) {
                 else
                     child.kill("SIGTERM");
             }
-            catch { /* already gone */ }
+            catch { }
             resolve(outcome);
         };
         const timer = setTimeout(() => finish({ ok: false, problem: `It did not answer within ${Math.round(timeoutMs / 1000)} seconds.` }), timeoutMs);
         const send = (message) => { try {
             child.stdin?.write(`${JSON.stringify(message)}\n`);
         }
-        catch { /* the exit handler reports */ } };
+        catch { } };
         child.on("error", error => finish({ ok: false, problem: `It could not start: ${error.message}.` }));
         child.on("exit", code => finish({ ok: false, problem: `It stopped before ${request.doing} (exit ${code ?? "signal"})${stderr.trim() === "" ? "" : `: ${safeLine(stderr)}`}.` }));
         child.stderr?.on("data", (chunk) => { stderr = (stderr + chunk.toString("utf8")).slice(-2_000); });
@@ -706,29 +610,20 @@ async function exchangeHttp(spec, values, timeoutMs, request) {
         return { ok: false, problem: error instanceof Error && error.name === "TimeoutError" ? `It did not answer within ${Math.round(timeoutMs / 1000)} seconds.` : localAppOf(spec)?.offline ?? "It could not be reached." };
     }
 }
-/** One line of a server's own words, never a secret. */
 function safeLine(text) {
     const line = text.replace(/\s+/g, " ").trim().slice(0, 200);
     return scanForSecrets(line).length > 0 ? "(its message was withheld: it looked like a secret)" : line;
 }
 const toml = (value) => `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 const tomlList = (values) => `[${values.map(toml).join(",")}]`;
-/** The launch's broker, holding its tools' values; the agent gets only its address and token. */
 function brokerFor(launch, options) {
     return startToolBroker(launch.tools.map(tool => ({ spec: tool.spec, values: tool.values, ...(options.enabledTools?.[tool.spec.name] === undefined ? {} : { actions: options.enabledTools[tool.spec.name] }) })), options.broker);
 }
-/** A private 0700 folder for one launch's files, and its cleanup with the broker's. */
 function launchFolder(broker) {
     const dir = mkdtempSync(join(tmpdir(), "so-tools-"));
     chmodSync(dir, 0o700);
     return { dir, cleanup: () => { broker?.close(); rmSync(dir, { recursive: true, force: true }); } };
 }
-/**
- * Claude: only these servers, in a private 0600 file removed after the run
- * (the provider adds `--strict-mcp-config`). Each is the broker's address
- * with this launch's token: Claude and its shell share one sandbox, so the
- * file holds nothing a tool signs in with.
- */
 export async function claudeToolArgs(launch, options = {}) {
     const broker = launch.tools.length === 0 ? null : await brokerFor(launch, options);
     const servers = {};
@@ -739,7 +634,6 @@ export async function claudeToolArgs(launch, options = {}) {
     writeFileSync(file, JSON.stringify({ mcpServers: servers }), { mode: 0o600 });
     return {
         argv: ["--mcp-config", file],
-        // A first `npx` download can take longer than the default start-up wait.
         env: launch.tools.length > 0 ? { MCP_TIMEOUT: "60000" } : {},
         omitEnv: [],
         cleanup,
@@ -747,21 +641,10 @@ export async function claudeToolArgs(launch, options = {}) {
         ...(broker === null ? {} : { serverPids: broker.pids, brokerPort: broker.port }),
     };
 }
-/** Where the tool launcher lives beside this module, built. */
 export function toolLauncherPath() {
     return fileURLToPath(new URL("./tool-launcher.js", import.meta.url));
 }
-/** The secret name a launch file gives the broker's token. */
 const BROKER_TOKEN = "TOOLROLL_TOOL_TOKEN";
-/**
- * Codex: each tool is named by `-c` and started through the launcher, which
- * relays it to the launch's broker. The operator's config.toml, rules, apps,
- * plugins and hooks are already off (the provider's
- * CODEX_BUILD_ISOLATION_ARGV), and nothing of config.toml is carried. Codex
- * gives its own environment to the agent's shell whatever its policy says,
- * so nothing rides it: the launch files name the broker and its token, and
- * the folder holding them is fenced from the agent.
- */
 export async function codexToolArgs(launch, options = {}) {
     const argv = [];
     if (launch.tools.length === 0)
@@ -775,19 +658,14 @@ export async function codexToolArgs(launch, options = {}) {
         const relay = { ...tool.spec, transport: "http", command: null, args: [], url: broker.url(tool.spec.name), secrets: [{ name: BROKER_TOKEN, optional: false }], bearer: BROKER_TOKEN, headerSecrets: {} };
         writeFileSync(file, JSON.stringify({ spec: relay, values: { [BROKER_TOKEN]: broker.token } }), { mode: 0o600 });
         const key = `mcp_servers.${tool.spec.name}`;
-        argv.push("-c", `${key}.command=${toml(node)}`, "-c", `${key}.args=${tomlList([launcher, file])}`, "-c", `${key}.startup_timeout_sec=60`, 
-        // Adding a tool to a project is the operator's yes to its calls: an unattended build has no one to ask.
-        "-c", `${key}.default_tools_approval_mode="approve"`);
-        // A research step's server offers only its read-only actions.
+        argv.push("-c", `${key}.command=${toml(node)}`, "-c", `${key}.args=${tomlList([launcher, file])}`, "-c", `${key}.startup_timeout_sec=60`, "-c", `${key}.default_tools_approval_mode="approve"`);
         const enabled = options.enabledTools?.[tool.spec.name];
         if (enabled !== undefined)
             argv.push("-c", `${key}.enabled_tools=${tomlList(enabled)}`);
     }
     return { argv, env: {}, omitEnv: [], cleanup, privateDir: dir, serverPids: broker.pids, brokerPort: broker.port };
 }
-/** Gemini: no way yet to hand it exactly these servers, so it gets none. */
 export const GEMINI_NO_TOOLS_ARGV = ["--allowed-mcp-server-names", "standing-orders-none"];
-/** The project's active tools with their parsed definitions and last test. */
 export function projectToolsOf(store, repo) {
     return store.projectTools(repo).flatMap(row => {
         try {
@@ -806,12 +684,6 @@ export function projectToolsOf(store, repo) {
         }
     });
 }
-/**
- * The exact tools one attempt launches with: the project's active tools,
- * limited to those its approval saw (a task approved before tools were
- * sealed gets today's list), each with every required secret set. What is
- * left out says why, in words the task page can show.
- */
 export function toolLaunchFor(store, runId, home) {
     const run = store.getRun(runId);
     const ref = run === null ? null : store.refById(run.taskRef);
@@ -823,7 +695,6 @@ export function toolLaunchFor(store, runId, home) {
     const claimed = new Map();
     const policy = store.orgPolicy();
     for (const tool of projectToolsOf(store, ref.repo)) {
-        // Sprint 8: a tool the organisation policy doesn't allow is left out, and the run says why.
         const disallowed = toolRefusal(policy, tool.name);
         if (disallowed !== null) {
             launch.skipped.push({ name: tool.name, reason: disallowed });
@@ -833,16 +704,12 @@ export function toolLaunchFor(store, runId, home) {
             launch.skipped.push({ name: tool.name, reason: "added or changed after this task was approved; approve it again to use it" });
             continue;
         }
-        // A tool that declares no secret never reads the store: a store that isn't ready (a process that didn't start
-        // Toolroll's folder) or a keychain that refuses can't take a keyless tool out of the run.
         const values = tool.spec.secrets.length === 0 ? {} : readToolSecrets(ref.repo, tool.name, home);
         const missing = missingSecrets(tool.spec, values);
         if (missing.length > 0) {
             launch.skipped.push({ name: tool.name, reason: `needs ${missing.join(", ")} set on the Tools page` });
             continue;
         }
-        // A tool connected by signing in launches with its access token alone: its refresh token, client and the rest
-        // stay in the store, and a run that renews gets an access token of its own (prepareRunTools).
         const kept = signedIn(tool.spec) ? { [ACCESS]: values[ACCESS] }
             : Object.fromEntries(tool.spec.secrets.filter(one => (values[one.name] ?? "") !== "").map(one => [one.name, values[one.name]]));
         const clash = Object.entries(kept).find(([name, value]) => claimed.has(name) && claimed.get(name) !== value);
@@ -856,13 +723,6 @@ export function toolLaunchFor(store, runId, home) {
     }
     return launch;
 }
-/**
- * Why a local tool that carries secrets can't start for this launch, or null when it can. Its server's environment
- * holds the values, and a process of the same user can read another's (KERN_PROCARGS2, /proc/<pid>/environ) unless
- * an OS fence stops it: only the macOS sandbox around a Claude build does. Codex's filesystem policy can't deny that
- * read (OpenRouter uses the same harness); Claude's own file rules and Linux's bubblewrap don't stop it, and on Linux
- * hidepid hides nothing from the same user, so Linux never starts one.
- */
 export function secretToolRefusal(provider, containment) {
     if (provider === "codex" || provider === "openrouter")
         return "This tool needs a Claude build to protect its sign-in details.";
@@ -872,15 +732,8 @@ export function secretToolRefusal(provider, containment) {
         return "This build has no macOS sandbox, so it could read this tool's sign-in details. Toolroll didn't start it.";
     return null;
 }
-/**
- * One attempt's tools, ready for its provider, and recorded on the run:
- * what it launched with and what was left out and why. The caller spawns
- * with `argv`/`env` and calls `cleanup` when the process is done.
- */
 export async function prepareRunTools(store, runId, provider, options) {
     const launch = limitedTo(toolLaunchFor(store, runId, options.home), options.readOnly, options.withheld);
-    // A local server with secrets starts only where the build can't read its environment; the rest are left out,
-    // saying why, before the broker exists. Gemini and ACP agents start none (below).
     const toolless = provider === "gemini" || isAcpProvider(provider);
     const refusal = toolless ? null : secretToolRefusal(provider, options.containment);
     if (refusal !== null) {
@@ -902,13 +755,11 @@ export async function prepareRunTools(store, runId, provider, options) {
                     : { argv: [], env: {}, omitEnv: [], cleanup: () => undefined };
     }
     catch (error) {
-        // Tokens were made for a run that won't start: each is revoked, and the run with them.
         if (revokes.length === 0)
             throw error;
         await revoke();
         throw new RunSignInError("This run's tools couldn't be prepared, so it didn't start; the sign-ins made for it were revoked.");
     }
-    // The run's own sign-ins end with it: the broker closes first, so nothing uses a token as it is revoked.
     const prepared = revokes.length === 0 ? launched : { ...launched, cleanup: () => { launched.cleanup(); void revoke(); } };
     const skipped = toolless
         ? [...launch.skipped, ...launch.tools.map(one => ({ name: one.spec.name, reason: provider === "gemini" ? "Gemini builds can't use project tools yet" : "ACP agents can't use project tools yet" }))]
@@ -927,16 +778,8 @@ export async function prepareRunTools(store, runId, provider, options) {
     }
     return prepared;
 }
-/** A run whose sign-ins couldn't all be made and kept: it doesn't start, and every token made for it is revoked. */
 export class RunSignInError extends Error {
 }
-/**
- * Each signed-in tool's own access token for this run (oauth-run-token.ts), read and renewed here, outside the fence,
- * one renewal at a time across Toolroll's processes. A rotated refresh token is saved before the run is let in; when
- * it can't be, or anything else fails once a token is made, every token made for this run is revoked, the saved
- * sign-in is left as it was, and the run doesn't start (RunSignInError). Only the new access token joins the launch.
- * A tool that can't be signed in is left out, saying why. Returns how to revoke the run's tokens.
- */
 async function signInRun(launch, options) {
     const repo = launch.repo;
     const revokes = [];
@@ -951,7 +794,6 @@ async function signInRun(launch, options) {
             }
             const minted = await renewingSignIn(repo, tool.spec.name, options.home, async () => {
                 const values = readToolSecrets(repo, tool.spec.name, options.home);
-                // No refresh token: the one access token the sign-in gave stays in the broker, like a key.
                 if (!mintsRunTokens(values))
                     return { ok: true, token: null };
                 const scope = runScope(scopeList(values[GRANTED]), options.readOnly);
@@ -988,7 +830,6 @@ async function signInRun(launch, options) {
     launch.tools = kept;
     return revokes;
 }
-/** A research step's launch: only the servers it may read, each limited to its read-only actions; the rest left out, saying why (`withheld`, when a service has its own reason). */
 function limitedTo(launch, readOnly, withheld = {}) {
     if (readOnly === undefined)
         return launch;
@@ -999,7 +840,6 @@ function limitedTo(launch, readOnly, withheld = {}) {
         skipped: [...launch.skipped, ...launch.tools.filter(one => !readable(one.spec.name)).map(one => ({ name: one.spec.name, reason: withheld[one.spec.name] ?? "research reads only connected services' read-only actions" }))],
     };
 }
-/** When a launch's tools cannot be prepared, it still gets none of anything else's: the same isolation with an empty list. */
 export function noToolsArgs(provider) {
     if (provider === "claude")
         return { argv: ["--mcp-config", '{"mcpServers":{}}'], env: {}, omitEnv: [], cleanup: () => undefined };
@@ -1007,7 +847,6 @@ export function noToolsArgs(provider) {
         return { argv: [...GEMINI_NO_TOOLS_ARGV], env: {}, omitEnv: [], cleanup: () => undefined };
     return { argv: [], env: {}, omitEnv: [], cleanup: () => undefined };
 }
-/** Add one tool (and, for an import, the values it brings) to a project's builds. */
 export function addToolTo(store, repo, input, source, by, now, options = {}) {
     let spec;
     try {
@@ -1030,17 +869,15 @@ export function addToolTo(store, repo, input, source, by, now, options = {}) {
     }
     return { ok: true, spec };
 }
-/** Take one tool away from every build now, with its stored secrets. */
 export function removeToolFrom(store, repo, name, by, now, home) {
     if (!store.removeProjectTool(repo, name, by, now))
         return false;
     try {
         clearToolSecrets(repo, name, home);
     }
-    catch { /* the row is gone; an orphan file is never read */ }
+    catch { }
     return true;
 }
-/** Test one tool of a project and keep the answer on it. */
 export async function testToolOf(store, repo, name, now, options = {}) {
     const tool = projectToolsOf(store, repo).find(one => one.name === name);
     if (tool === undefined)
@@ -1051,7 +888,6 @@ export async function testToolOf(store, repo, name, now, options = {}) {
     store.recordProjectToolTest(repo, name, JSON.stringify(test));
     return test;
 }
-/** Where a tool stands, in a few words: what a person reads first. */
 export function toolStanding(tool, secretsSet) {
     const missing = tool.spec.secrets.filter(one => !one.optional && !secretsSet.includes(one.name)).map(one => one.name);
     if (missing.length > 0)
@@ -1067,7 +903,6 @@ export const CREDENTIAL_MODES = {
     "held-key": { words: "Key held by Toolroll", detail: "Runs reach this tool through Toolroll, which adds the key. The key never enters a build." },
     "no-key": { words: "No key needed", detail: null },
 };
-/** A tool's credential mode from the names of its secrets that are set (never their values); null while a key it needs is missing. */
 export function credentialModeOf(spec, secretsSet) {
     const mode = spec.secrets.every(one => one.optional && !secretsSet.includes(one.name)) ? "no-key"
         : signedIn(spec) && mintsRunTokens(secretsSet) ? "run-token"
@@ -1075,7 +910,6 @@ export function credentialModeOf(spec, secretsSet) {
                 : "held-key";
     return mode === null ? null : { mode, ...CREDENTIAL_MODES[mode] };
 }
-/** Names of a tool's secrets that have a value, never the values: in the keychain, from the names kept beside them. */
 export function secretsSetFor(repo, tool, state) {
     const folder = secretFolder(state);
     let names = null;
@@ -1097,11 +931,9 @@ export function secretsSetFor(repo, tool, state) {
     }
     return tool.secrets.filter(one => names.includes(one.name)).map(one => one.name);
 }
-/** Where this computer keeps tool secrets, in the words Settings and `toolroll integrations` share; `problem` when they can't be used. */
 export function toolSecretStorage() {
     return secretStorage();
 }
-/** A command line split into program and arguments, honouring "double" and 'single' quotes. */
 export function splitCommandLine(line) {
     const parts = [];
     let current = "", quote = null, started = false;
@@ -1135,13 +967,6 @@ export function splitCommandLine(line) {
         parts.push(current);
     return parts;
 }
-/**
- * The server fence for a project tool started outside a build (docs/plans/sandbox-parity.md C2): discovery, its Test
- * button, a flow's "Use a tool" step, a subagent's call. As the broker's servers are fenced: Toolroll's state, every
- * other launch's folder and the checkout pools denied, and nothing a build writes (its project's caches) read, so no
- * byte a build wrote can load into a process that holds the tool's secrets. Required: where this machine can't confine
- * it, it doesn't start unless an instance operator allowed unconfined agents.
- */
 export async function toolServerFor(store, repo, options = {}) {
     const databaseFile = store.databaseFile();
     if (databaseFile === null || databaseFile === "" || databaseFile === ":memory:")
@@ -1154,7 +979,6 @@ export async function toolServerFor(store, repo, options = {}) {
     const poolRoots = [join(dirname(databaseFile), "worktrees"), ...store.listWorktrees().map(record => poolRootOf(record.path, record.repo))];
     const cache = buildCacheFolder(repo, home);
     const untrusted = existsSync(cache) ? [realpathSync(cache)] : [];
-    // The storage check, awaited off this thread (protected-storage.ts): the console's Test button never waits on it.
     let storage;
     try {
         storage = await prepareProtectedStorage(home);
@@ -1167,6 +991,4 @@ export async function toolServerFor(store, repo, options = {}) {
     }
     return { fence: fenceFor("tool-server", { databaseFile, worktree: null, home, boundary: null, binding: null, runFolders: runFolders(null), poolRoots, storage, extra: untrusted }) };
 }
-/** Each project's `.mcp.json` as the console last read it off its thread (its background pass): what its pages and the
- * lead offer, so neither reads a project folder on the console's thread. */
 export const savedProjectMcp = new Map();