severally-mcp 2.4.0 → 2.5.0

package/scripts/live-check.mjs

@@ -18,10 +18,15 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { JobManager } from '../src/jobs.mjs';
+/** @typedef {import('../src/jobs.mjs').JobView} JobView */
 import { limitsSummary } from '../src/policy.mjs';
 import * as store from '../src/store.mjs';
 
 const argv = process.argv.slice(2);
+/**
+ * @param {string} name
+ * @param {string} dflt
+ */
 const arg = (name, dflt) => {
   const i = argv.indexOf(`--${name}`);
   return i === -1 ? dflt : argv[i + 1];
@@ -30,6 +35,7 @@ const arg = (name, dflt) => {
 const target = arg('target', 'antigravity');
 const mode = arg('mode', 'review');
 
+/** @type {Record<string, Record<string, unknown>>} */
 const REQUESTS = {
   review: {
     mode: 'review',
@@ -101,13 +107,12 @@ REQUESTS.sandbox = {
   },
 };
 
-const request = { target, ...REQUESTS[mode] };
+const request = { target, ...(mode === undefined ? {} : REQUESTS[mode]) };
 
 console.log('limits:', JSON.stringify(limitsSummary(), null, 2));
 const mgr = new JobManager();
-/** @type {Record<string, any>} */
 const started = mgr.start(request);
-if (!started.job_id) {
+if (!('job_id' in started)) {
   console.error('live-check runs one consultant at a time: pass a single --target, not "all"');
   process.exit(2);
 }
@@ -130,10 +135,11 @@ try {
 } catch {
   /* no working directory: the job failed before it started */
 }
-await mgr.jobs.get(started.job_id).promise;
+await mgr.jobs.get(started.job_id)?.promise;
 clearInterval(watch);
 watcher?.close();
-const view = mgr.view(started.job_id);
+// The job was started above in this process, so it exists.
+const view = /** @type {JobView} */ (mgr.view(started.job_id));
 console.log(`\n=== finished in ${((Date.now() - t0) / 1000).toFixed(1)}s: ${view.status} ===`);
 console.log(JSON.stringify(view, null, 2));
 if (mode !== 'sandbox') process.exit(view.status === 'completed' ? 0 : 1);

package/scripts/live-mcp-check.mjs

@@ -11,10 +11,15 @@ import { execFileSync } from 'node:child_process';
 
 // The globally installed server, unless another path is given.
 const BIN = process.argv[2] ?? 'severally-mcp';
-const env = { ...process.env };
+// process.env holds only strings at runtime; its type also admits undefined.
+const env = /** @type {Record<string, string>} */ ({ ...process.env });
 const client = new Client({ name: 'live-mcp', version: '1' });
 await client.connect(new StdioClientTransport({ command: BIN, args: [], env }));
-const P = (r) => JSON.parse(r.content[0].text);
+/** @typedef {import('@modelcontextprotocol/client').CallToolResult} CallToolResult */
+/** @typedef {import('@modelcontextprotocol/client').TextContent} TextContent */
+// The server answers every tool call with one text item, so content[0] is TextContent.
+/** @param {CallToolResult} r A tool result whose first content item is JSON text. */
+const P = (r) => JSON.parse(/** @type {TextContent} */ (r.content[0]).text);
 
 const request = {
   target: 'claude-code',
@@ -86,7 +91,7 @@ const before = countClaudeChildren();
 const cancelled = P(await client.callTool({ name: 'consult_cancel', arguments: { job_id: fu.job_id } }));
 console.log('cancel ->', cancelled.status, '|', cancelled.cancel_effect);
 let after = before;
-for (let i = 0; i < 40 && after >= before && before > 0; i++) {
+for (let i = 0; i < 40 && before !== null && before > 0 && after !== null && after >= before; i++) {
   await new Promise((r) => setTimeout(r, 250));
   after = countClaudeChildren();
 }
@@ -115,7 +120,8 @@ function countClaudeChildren() {
         : execFileSync('ps', ['-eo', 'args='], { encoding: 'utf8' });
     return out.split('\n').filter((l) => l.includes('--no-session-persistence') && l.includes('--restricted')).length;
   } catch (error) {
-    console.warn(`Could not inspect consultant processes: ${error.message}`);
+    // execFileSync throws an Error.
+    console.warn(`Could not inspect consultant processes: ${/** @type {Error} */ (error).message}`);
     return null;
   }
 }

package/src/adapters/antigravity-sandbox.mjs

@@ -40,7 +40,10 @@ export const SANDBOX_DENY = Object.freeze(['write_file(*)', 'command(*)', 'mcp(*
 // call also passes a PreToolUse hook that allows these names and denies the
 // rest -- an allowlist, so a tool a later agy release adds is refused until it
 // is added here. The names are agy's own (its init toolset), not rule names.
-export const ALLOWED_TOOLS = Object.freeze(['view_file', 'search_web', 'read_url_content', 'finish']);
+// agy 1.4.3 reads files with read_file; earlier releases called it view_file.
+// With only view_file listed, every read on 1.4.3 was refused and the
+// consultant answered from the brief alone (2026-10-20).
+export const ALLOWED_TOOLS = Object.freeze(['view_file', 'read_file', 'search_web', 'read_url_content', 'finish']);
 const WEB_TOOLS = new Set(['search_web', 'read_url_content']);
 
 // agy pipes the pending call to the hook as {"toolCall":{"name":...,
@@ -59,15 +62,16 @@ const WEB_TOOLS = new Set(['search_web', 'read_url_content']);
 // expanded: a consultant that can browse must not read a credential and
 // carry it out in a URL. Other tools' parameters -- the final answer passed
 // to finish among them -- are text, not paths, and are not inspected.
-const PATH_TOOLS = ['view_file', 'read_url_content'];
+const PATH_TOOLS = ['view_file', 'read_file', 'read_url_content'];
 
 // read_url_content does not hand a long page to the model: it saves it inside
 // the sandbox home and tells the model to view_file that copy (agy 1.4.0,
 // 2026-10-17). The sandbox home is protected as a whole, so without this one
 // exception no long page could be read. Only that file shape, only in this
 // sandbox: the rest of the home (credential link, transcripts) stays refused.
+/** @param {string} root */
 function spillPattern(root) {
-  const esc = (s) => s.replaceAll('\\', '/').replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const esc = (/** @type {string} */ s) => s.replaceAll('\\', '/').replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   let real = root;
   try {
     real = fs.realpathSync.native(root);
@@ -78,6 +82,13 @@ function spillPattern(root) {
   return `^(?:${roots})/\\.gemini/antigravity-cli/brain/[^/]+/\\.system_generated/steps/[0-9]+/content\\.md$`;
 }
 
+/**
+ * @param {readonly string[]} allowed
+ * @param {string[]} rootPatterns
+ * @param {string[]} namePatterns
+ * @param {string} home
+ * @param {string} spill
+ */
 function hookSource(allowed, rootPatterns, namePatterns, home, spill) {
   return `import fs from 'node:fs';
 import path from 'node:path';
@@ -150,17 +161,24 @@ process.stdin.on('end', () => {
 `;
 }
 
-/** The tools the hook lets through: no web tools when the request turned the network off. */
+/**
+ * The tools the hook lets through: no web tools when the request turned the network off.
+ * @param {'on' | 'off'} [network]
+ */
 export function allowedTools(network = 'on') {
   return ALLOWED_TOOLS.filter((t) => network !== 'off' || !WEB_TOOLS.has(t));
 }
 
-/** The settings.json permission rules; with the network off, read_url moves to deny. */
+/**
+ * The settings.json permission rules; with the network off, read_url moves to deny.
+ * @param {'on' | 'off'} [network]
+ */
 export function sandboxPermissions(network = 'on') {
   if (network !== 'off') return { allow: [...SANDBOX_ALLOW], deny: [...SANDBOX_DENY] };
   return { allow: SANDBOX_ALLOW.filter((r) => r !== 'read_url(*)'), deny: [...SANDBOX_DENY, 'read_url(*)'] };
 }
 
+/** @param {string} script */
 function hookCommand(script) {
   return [process.execPath, script]
     .map((v) => {
@@ -175,7 +193,7 @@ const TOKEN_REL = path.join('.gemini', 'antigravity-cli', 'antigravity-oauth-tok
 
 /**
  * Build the synthesised HOME for one consultation.
- * @param {{workdir: string, network?: 'on' | 'off'}} opts workdir is <jobdir>/work; the home is store.sandboxHome(<job id>).
+ * @param {{workdir: string, network?: 'on' | 'off' | undefined}} opts workdir is <jobdir>/work; the home is store.sandboxHome(<job id>).
  */
 export function prepareSandbox({ workdir, network = 'on' }) {
   const root = sandboxHome(path.basename(path.dirname(workdir)));

package/src/adapters/antigravity.mjs

@@ -18,7 +18,14 @@ import path from 'node:path';
 import { POLICY, agyExitGraceMs, timeoutMs } from '../policy.mjs';
 import { classifyMessage } from '../failures.mjs';
 
-export { prepareSandbox } from './antigravity-sandbox.mjs';
+export { prepareSandbox, ALLOWED_TOOLS } from './antigravity-sandbox.mjs';
+
+/** @typedef {import('../run.mjs').BuildRequest} BuildRequest */
+/** @typedef {import('../run.mjs').Invocation} Invocation */
+/** @typedef {import('../run.mjs').Interpreted} Interpreted */
+/** @typedef {import('../run.mjs').Sandbox} Sandbox */
+/** @typedef {import('../run.mjs').UsageRecord} UsageRecord */
+/** @typedef {import('../run.mjs').Boundary} Boundary */
 
 // Checked against `agy --help` at 1.1.28. These are inert in print mode as the
 // adapter builds it today; the list exists so a future edit that reaches for
@@ -50,6 +57,10 @@ export const FORBIDDEN_FLAGS = [
 // --effort too: the effort is chosen through the model name, in one place.
 export const RESERVED_FLAGS = ['--print', '-p', '--prompt', '--project', '--remote-control', '--effort'];
 
+/**
+ * @param {BuildRequest} req
+ * @returns {Invocation}
+ */
 export function buildInvocation({ schemaPath, consultant }) {
   const t = POLICY.clis.antigravity;
   const chosen = consultant.model;
@@ -76,8 +87,30 @@ export function buildInvocation({ schemaPath, consultant }) {
   return { command: t.cli, args, model: chosen };
 }
 
-/** Every complete NDJSON object agy wrote, oldest first. */
+/**
+ * The result envelope agy prints; the CLI controls it, so every field is optional.
+ * @typedef {object} AgyEnvelope
+ * @property {unknown} [status]
+ * @property {unknown} [error]
+ * @property {unknown} [response]
+ * @property {string | Record<string, unknown>} [structured_output]
+ * @property {({ action?: string } | null)[]} [denied_actions]
+ * @property {{ input_tokens?: unknown, cache_read_tokens?: unknown, output_tokens?: unknown, total_tokens?: unknown, thinking_tokens?: unknown }} [usage]
+ * @property {unknown} [num_turns]
+ */
+
+/**
+ * One NDJSON event: a `result` or `step_update` wrapper, or a bare envelope.
+ * @typedef {AgyEnvelope & { event?: string, result?: AgyEnvelope, step_update?: { step_index?: number, tool_name?: string, step_type?: string, state?: string } }} AgyEvent
+ */
+
+/**
+ * Every complete NDJSON object agy wrote, oldest first.
+ * @param {string} [stdout]
+ * @returns {AgyEvent[]}
+ */
 function events(stdout) {
+  /** @type {AgyEvent[]} */
   const out = [];
   for (const line of (stdout || '').split('\n')) {
     const t = line.trim();
@@ -96,11 +129,11 @@ function events(stdout) {
  * The final envelope: the `result` event under stream-json, or a bare envelope
  * when agy was run with --output-format json (as older configs and the unit
  * tests do).
+ * @param {string} [stdout]
+ * @returns {AgyEnvelope | null}
  */
 function finalEnvelope(stdout) {
-  const all = events(stdout);
-  for (let i = all.length - 1; i >= 0; i--) {
-    const e = all[i];
+  for (const e of events(stdout).reverse()) {
     if (e.event === 'result' && e.result && typeof e.result === 'object') return e.result;
     if (e.event === undefined && (e.status || e.response || e.structured_output)) return e;
   }
@@ -113,25 +146,35 @@ function finalEnvelope(stdout) {
  * one tool call", which is the difference between raising the budget and
  * narrowing the brief; and it lets the lead cut a heavy consultation short
  * instead of waiting out the whole budget for nothing.
+ * @param {{ stdout: string }} run
+ * @returns {string | null}
  */
 export function progress({ stdout }) {
-  const steps = events(stdout).filter((e) => e.event === 'step_update' && e.step_update);
-  if (!steps.length) return null;
-  const last = steps[steps.length - 1].step_update;
-  const seen = new Set(steps.map((s) => s.step_update.step_index)).size;
+  const steps = events(stdout).flatMap((e) => (e.event === 'step_update' && e.step_update ? [e.step_update] : []));
+  const last = steps.at(-1);
+  if (!last) return null;
+  const seen = new Set(steps.map((s) => s.step_index)).size;
   const what = last.tool_name ? `tool ${last.tool_name}` : (last.step_type ?? 'a step');
   return `${seen} step(s), last was ${what} (${last.state ?? 'state unknown'})`;
 }
 
-/** Tool calls seen in the step stream, one per step index; `:error` when the step failed or was refused. */
+/** The tools that read a file; a consultation whose calls to them all failed read none of its exposed files. */
+export const FILE_READ_TOOLS = ['view_file', 'read_file'];
+
+/**
+ * Tool calls seen in the step stream, one per step index; `:error` when the step failed or was refused.
+ * @param {{ stdout: string }} run
+ * @returns {Record<string, number>}
+ */
 export function toolCalls({ stdout }) {
+  /** @type {Map<unknown, string>} */
   const seen = new Map();
   for (const e of events(stdout)) {
     const s = e.event === 'step_update' ? e.step_update : null;
     if (s?.tool_name)
       seen.set(s.step_index ?? seen.size, /error|fail|cancel|denied/i.test(s.state ?? '') ? `${s.tool_name}:error` : s.tool_name);
   }
-  return [...seen.values()].reduce((o, n) => ({ ...o, [n]: (o[n] ?? 0) + 1 }), {});
+  return [...seen.values()].reduce((/** @type {Record<string, number>} */ o, n) => ({ ...o, [n]: (o[n] ?? 0) + 1 }), {});
 }
 
 /**
@@ -139,6 +182,8 @@ export function toolCalls({ stdout }) {
  * (job_790a7173c16d) agy wrote its finish step and then stayed alive for six
  * minutes; the server waits for the process to close, so without this the
  * consultation would have sat "running" until its budget ran out.
+ * @param {string} line
+ * @returns {number | null}
  */
 export function settleAfter(line) {
   if (!line.includes('"result"') && !line.includes('"finish"')) return null;
@@ -163,10 +208,12 @@ export const stopSignal = 'SIGQUIT';
  * goroutine dump and is written inside the sandbox HOME that is removed when
  * the consultation ends, and whatever reached the stderr pipe. Not redacted
  * here; the caller does that.
+ * @param {{ run: import('../run.mjs').ChildResult, sandbox: { root: string } }} args
  */
 export function diagnostics({ run, sandbox }) {
-  const tail = (s) => String(s ?? '').slice(-200_000);
+  const tail = (/** @type {unknown} */ s) => String(s ?? '').slice(-200_000);
   const dir = path.join(sandbox.root, '.gemini', 'antigravity-cli', 'log');
+  /** @type {string[]} */
   let names = [];
   try {
     names = fs.readdirSync(dir).sort();
@@ -187,6 +234,10 @@ export function diagnostics({ run, sandbox }) {
   ].join('\n');
 }
 
+/**
+ * @param {{ stdout?: string, stderr?: string, code?: number | null }} run
+ * @returns {Interpreted}
+ */
 export function interpret({ stdout, stderr, code }) {
   const payload = finalEnvelope(stdout);
   if (!payload) {
@@ -209,10 +260,16 @@ export function interpret({ stdout, stderr, code }) {
   return { ok: true, text, usageRaw: payload, denials: payload.denied_actions ?? [] };
 }
 
-export function usageRecord(payload) {
+/**
+ * @param {unknown} raw the agy result envelope, as interpret kept it
+ * @returns {UsageRecord | null}
+ */
+export function usageRecord(raw) {
+  // interpret's usageRaw is the AgyEnvelope it found (or null).
+  const payload = /** @type {AgyEnvelope | null} */ (raw);
   if (!payload) return null;
   const u = payload.usage ?? {};
-  const num = (v) => (typeof v === 'number' ? v : null);
+  const num = (/** @type {unknown} */ v) => (typeof v === 'number' ? v : null);
   return {
     input_tokens: num(u.input_tokens),
     cached_input_tokens: num(u.cache_read_tokens),
@@ -224,7 +281,9 @@ export function usageRecord(payload) {
     turns: num(payload.num_turns),
     // Which permissions the sandbox refused. A denied read_url usually explains
     // a thin evidence basis, so it is worth keeping in the record.
-    denied_actions: Array.isArray(payload.denied_actions) ? payload.denied_actions.map((d) => d?.action).filter(Boolean) : null,
+    denied_actions: Array.isArray(payload.denied_actions)
+      ? payload.denied_actions.flatMap((d) => (d?.action ? [d.action] : []))
+      : null,
   };
 }
 
@@ -232,15 +291,19 @@ export function usageRecord(payload) {
  * What this consultant was launched with, read off the invocation: the
  * boundary record kept beside each answer. Facts about the launch, not a
  * claim about what the consultant did.
+ * @param {{ sandbox: Sandbox | null }} req
+ * @returns {Boundary}
  */
 export function boundary({ sandbox }) {
+  // buildInvocation always runs with the sandbox prepareSandbox made.
+  const { tools } = /** @type {Sandbox} */ (sandbox);
   return {
     reads: 'whole disk',
     shell: 'none',
-    web: sandbox.tools.includes('search_web'),
+    web: tools.includes('search_web'),
     writes: false,
     mcp: false,
     protected_paths: 'denied (tool hook)',
-    tools: [...sandbox.tools],
+    tools: [...tools],
   };
 }

package/src/adapters/claude-code.mjs

@@ -33,6 +33,12 @@ import { POLICY, PROTECTED_FILE_NAMES, protectedRoots } from '../policy.mjs';
 import { classifyMessage } from '../failures.mjs';
 import { CONSULT_RESULT_SCHEMA } from '../result-schema.mjs';
 
+/** @typedef {import('../run.mjs').BuildRequest} BuildRequest */
+/** @typedef {import('../run.mjs').Invocation} Invocation */
+/** @typedef {import('../run.mjs').Interpreted} Interpreted */
+/** @typedef {import('../run.mjs').UsageRecord} UsageRecord */
+/** @typedef {import('../run.mjs').Boundary} Boundary */
+
 // --add-dir is not listed: the adapter passes `--add-dir /` itself, and
 // assertNoForbiddenFlags refuses any other value. --restricted confines the
 // file tools to the working directories, and without expose_paths that
@@ -89,11 +95,12 @@ export const RESERVED_FLAGS = [
 /** Read deny rules for the paths no consultant may read. */
 // Claude Code matches Windows paths in POSIX form (C:\\Users -> /c/Users), so
 // an absolute rule names the drive that way: //c/Users/..., not //C:/Users/....
-export const posixAbsolute = (p) => p.replaceAll('\\', '/').replace(/^([A-Za-z]):/, (_, d) => `/${d.toLowerCase()}`);
+export const posixAbsolute = (/** @type {string} */ p) =>
+  p.replaceAll('\\', '/').replace(/^([A-Za-z]):/, (_, /** @type {string} */ d) => `/${d.toLowerCase()}`);
 
 export function protectedReadRules() {
   const home = os.homedir().replaceAll('\\', '/');
-  const spec = (root) =>
+  const spec = (/** @type {string} */ root) =>
     root.startsWith(`${home}/`) ? `~/${root.slice(home.length + 1)}` : `//${posixAbsolute(root).replace(/^\/+/, '')}`;
   return [
     ...protectedRoots().flatMap((r) => [`Read(${spec(r)})`, `Read(${spec(r)}/**)`]),
@@ -101,6 +108,10 @@ export function protectedReadRules() {
   ];
 }
 
+/**
+ * @param {BuildRequest} req
+ * @returns {Invocation}
+ */
 export function buildInvocation({ workdir, guardrails, consultant, hasExposedPaths = false, network = 'on' }) {
   const t = POLICY.clis['claude-code'];
   const chosen = consultant.model;
@@ -145,10 +156,27 @@ export function buildInvocation({ workdir, guardrails, consultant, hasExposedPat
   return { command: t.cli, args, model: chosen, workdir };
 }
 
+/**
+ * The result JSON the CLI prints; the CLI controls it, so every field is optional.
+ * @typedef {object} ClaudeResult
+ * @property {unknown} [is_error]
+ * @property {unknown} [result]
+ * @property {string | Record<string, unknown>} [structured_output]
+ * @property {string | Record<string, unknown>} [structuredOutput]
+ * @property {unknown[]} [permission_denials]
+ * @property {{ input_tokens?: unknown, cache_read_input_tokens?: unknown, output_tokens?: unknown, server_tool_use?: { web_search_requests?: unknown } }} [usage]
+ * @property {unknown} [total_cost_usd]
+ * @property {unknown} [num_turns]
+ */
+
+/**
+ * @param {string} [stdout]
+ * @returns {ClaudeResult | null}
+ */
 function lastJsonObject(stdout) {
-  const lines = (stdout || '').split('\n');
-  for (let i = lines.length - 1; i >= 0; i--) {
-    const t = lines[i].trim();
+  const lines = (stdout || '').split('\n').reverse();
+  for (const line of lines) {
+    const t = line.trim();
     if (!t.startsWith('{')) continue;
     try {
       const parsed = JSON.parse(t);
@@ -160,6 +188,10 @@ function lastJsonObject(stdout) {
   return null;
 }
 
+/**
+ * @param {{ stdout?: string, stderr?: string, code?: number | null }} run
+ * @returns {Interpreted}
+ */
 export function interpret({ stdout, stderr, code }) {
   const payload = lastJsonObject(stdout);
   if (!payload) {
@@ -193,10 +225,16 @@ export function interpret({ stdout, stderr, code }) {
   return { ok: true, text, payload, usageRaw: payload, denials: payload.permission_denials ?? [] };
 }
 
-export function usageRecord(payload) {
+/**
+ * @param {unknown} raw the CLI's result JSON, as interpret kept it
+ * @returns {UsageRecord | null}
+ */
+export function usageRecord(raw) {
+  // interpret's usageRaw is the ClaudeResult it parsed (or null).
+  const payload = /** @type {ClaudeResult | null} */ (raw);
   if (!payload) return null;
   const u = payload.usage ?? {};
-  const num = (v) => (typeof v === 'number' ? v : null);
+  const num = (/** @type {unknown} */ v) => (typeof v === 'number' ? v : null);
   return {
     input_tokens: num(u.input_tokens),
     cached_input_tokens: num(u.cache_read_input_tokens),
@@ -212,9 +250,12 @@ export function usageRecord(payload) {
  * What this consultant was launched with, read off the invocation: the
  * boundary record kept beside each answer. Facts about the launch, not a
  * claim about what the consultant did.
+ * @param {{ args: string[], hasExposedPaths?: boolean }} req
+ * @returns {Boundary}
  */
 export function boundary({ args, hasExposedPaths }) {
-  const tools = args[args.indexOf('--tools') + 1];
+  // buildInvocation always passes --tools with a value.
+  const tools = /** @type {string} */ (args[args.indexOf('--tools') + 1]);
   return {
     reads: hasExposedPaths ? 'the exposed copy only' : 'whole disk',
     shell: 'none',

package/src/adapters/codex.mjs

@@ -56,6 +56,13 @@ import path from 'node:path';
 import { POLICY, protectedRoots } from '../policy.mjs';
 import { classifyMessage } from '../failures.mjs';
 
+/** @typedef {import('../run.mjs').BuildRequest} BuildRequest */
+/** @typedef {import('../run.mjs').ChildResult} ChildResult */
+/** @typedef {import('../run.mjs').Invocation} Invocation */
+/** @typedef {import('../run.mjs').Interpreted} Interpreted */
+/** @typedef {import('../run.mjs').UsageRecord} UsageRecord */
+/** @typedef {import('../run.mjs').Boundary} Boundary */
+
 export const FORBIDDEN_FLAGS = [
   '--dangerously-bypass-approvals-and-sandbox',
   '--dangerously-bypass-hook-trust',
@@ -85,6 +92,7 @@ export const RESERVED_FLAGS = [
 
 const PROFILE = 'severally';
 
+/** @param {string} dir @returns {string[]} */
 const listDir = (dir) => {
   try {
     return fs.readdirSync(dir);
@@ -120,6 +128,10 @@ export function filesystemPermissions() {
   return `{ ":root" = "read", ${denied.map((p) => `${JSON.stringify(p)} = "none"`).join(', ')} }`;
 }
 
+/**
+ * @param {BuildRequest} req
+ * @returns {Invocation}
+ */
 export function buildInvocation({ workdir, schemaPath, consultant, network = 'on' }) {
   const t = POLICY.clis.codex;
   const chosen = consultant.model;
@@ -163,6 +175,22 @@ export function buildInvocation({ workdir, schemaPath, consultant, network = 'on
   return { command: t.cli, args, lastMessagePath, model: chosen };
 }
 
+/**
+ * One JSONL event from `codex exec --json`, or the item inside it; the CLI
+ * controls both, so every field is optional.
+ * @typedef {object} CodexItem
+ * @property {unknown} [type]
+ * @property {unknown} [text]
+ * @property {unknown} [message]
+ * @property {unknown} [usage]
+ * @typedef {CodexItem & { error?: { message?: unknown }, item?: CodexItem }} CodexEvent
+ */
+
+/**
+ * @param {CodexItem | null | undefined} node
+ * @param {Record<string, number>} acc
+ * @returns {void}
+ */
 function walkUsage(node, acc) {
   if (!node || typeof node !== 'object') return;
   if (node.usage && typeof node.usage === 'object') {
@@ -174,8 +202,13 @@ function walkUsage(node, acc) {
   for (const v of Object.values(node)) if (v && typeof v === 'object') walkUsage(v, acc);
 }
 
-/** Parse the JSONL event stream `codex exec --json` writes to stdout. */
+/**
+ * Parse the JSONL event stream `codex exec --json` writes to stdout.
+ * @param {Partial<ChildResult> & { lastMessageText?: string }} run
+ * @returns {Interpreted}
+ */
 export function interpret({ stdout, stderr, code, lastMessageText }) {
+  /** @type {CodexEvent[]} */
   const events = [];
   for (const line of (stdout || '').split('\n')) {
     const t = line.trim();
@@ -188,14 +221,15 @@ export function interpret({ stdout, stderr, code, lastMessageText }) {
   }
 
   const errorEvents = events.filter((e) => e.type === 'error' || e.type === 'turn.failed');
+  /** @type {Record<string, number>} */
   const usage = {};
   for (const e of events) walkUsage(e, usage);
 
   let text = (lastMessageText || '').trim();
   if (!text) {
     // Fall back to the last assistant message carried in the event stream.
-    for (let i = events.length - 1; i >= 0 && !text; i--) {
-      const e = events[i];
+    for (const e of events.toReversed()) {
+      if (text) break;
       const item = e.item ?? e;
       const candidate =
         (item && item.type && String(item.type).includes('agent_message') && (item.text ?? item.message)) ||
@@ -237,6 +271,8 @@ export function interpret({ stdout, stderr, code, lastMessageText }) {
  * What this consultation has done so far. Codex already runs with `exec --json`,
  * so its event stream is there for the reading -- no flag change and no parser
  * change, only a use for events we were otherwise discarding.
+ * @param {{ stdout?: string }} run
+ * @returns {string | null}
  */
 export function progress({ stdout }) {
   const items = [];
@@ -260,8 +296,11 @@ export function progress({ stdout }) {
  * Tool calls seen in the event stream, counted by item type (and by tool for
  * MCP and collaboration calls, which is where a sub-agent spawn shows up);
  * `:error` when the item ended failed or declined.
+ * @param {{ stdout?: string }} run
+ * @returns {Record<string, number>}
  */
 export function toolCalls({ stdout }) {
+  /** @type {Map<unknown, string>} */
   const seen = new Map();
   for (const line of (stdout || '').split('\n')) {
     const t = line.trim();
@@ -279,13 +318,22 @@ export function toolCalls({ stdout }) {
     const name = item.status === 'failed' || item.status === 'declined' ? `${base}:error` : base;
     seen.set(item.id ?? `${name}#${seen.size}`, name);
   }
-  return [...seen.values()].reduce((o, n) => ({ ...o, [n]: (o[n] ?? 0) + 1 }), {});
+  return [...seen.values()].reduce((/** @type {Record<string, number>} */ o, n) => ({ ...o, [n]: (o[n] ?? 0) + 1 }), {});
 }
 
+/**
+ * @param {unknown} raw the usage figures interpret collected from the event stream
+ * @returns {UsageRecord}
+ */
 export function usageRecord(raw) {
-  const u = raw ?? {};
+  // interpret's usageRaw is the Record<string, number> walkUsage filled (or null).
+  const u = /** @type {Record<string, number>} */ (raw ?? {});
+  /** @param {...string} names */
   const pick = (...names) => {
-    for (const n of names) if (typeof u[n] === 'number') return u[n];
+    for (const n of names) {
+      const v = u[n];
+      if (typeof v === 'number') return v;
+    }
     return null;
   };
   return {
@@ -302,6 +350,8 @@ export function usageRecord(raw) {
  * What this consultant was launched with, read off the invocation: the
  * boundary record kept beside each answer. Facts about the launch, not a
  * claim about what the consultant did.
+ * @param {{ args: string[] }} launch
+ * @returns {Boundary}
  */
 export function boundary({ args }) {
   return {