severally-mcp 2.3.1 → 2.4.2

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;
@@ -63,17 +74,43 @@ export function buildInvocation({ schemaPath, consultant }) {
   // it was. Ours has to fire first for the failure to be classified honestly.
   const budget = timeoutMs(consultant);
   const args = [
-    '--output-format', 'stream-json',
-    '--json-schema', schemaPath,
+    '--output-format',
+    'stream-json',
+    '--json-schema',
+    schemaPath,
     '--disable-slash-commands',
-    '--model', chosen,
-    '--print-timeout', `${Math.ceil((budget + 30_000) / 1000)}s`,
+    '--model',
+    chosen,
+    '--print-timeout',
+    `${Math.ceil((budget + 30_000) / 1000)}s`,
   ];
   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();
@@ -81,7 +118,9 @@ function events(stdout) {
     try {
       const parsed = JSON.parse(t);
       if (parsed && typeof parsed === 'object') out.push(parsed);
-    } catch { /* a partial line, e.g. when the child was killed mid-write */ }
+    } catch {
+      /* a partial line, e.g. when the child was killed mid-write */
+    }
   }
   return out;
 }
@@ -90,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;
   }
@@ -107,24 +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);
+    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 }), {});
 }
 
 /**
@@ -132,11 +182,17 @@ 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;
   let e;
-  try { e = JSON.parse(line); } catch { return null; }
+  try {
+    e = JSON.parse(line);
+  } catch {
+    return null;
+  }
   if (e?.event === 'result') return agyExitGraceMs().afterResult;
   if (e?.event === 'step_update' && e.step_update?.step_type === 'finish') return agyExitGraceMs().afterFinish;
   return null;
@@ -152,33 +208,48 @@ 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(); } catch { /* agy wrote no log */ }
+  try {
+    names = fs.readdirSync(dir).sort();
+  } catch {
+    /* agy wrote no log */
+  }
   return [
     `--- agy stderr ---\n${tail(run.stderr)}`,
     ...names.map((n) => {
       let text = '';
-      try { text = fs.readFileSync(path.join(dir, n), 'utf8'); } catch { /* unreadable */ }
+      try {
+        text = fs.readFileSync(path.join(dir, n), 'utf8');
+      } catch {
+        /* unreadable */
+      }
       return `--- ${n} ---\n${tail(text)}`;
     }),
   ].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) {
-    const msg = (stderr || '').trim() || (stdout || '').trim().slice(0, 2000) ||
+    const msg =
+      (stderr || '').trim() ||
+      (stdout || '').trim().slice(0, 2000) ||
       `agy exited with code ${code} and produced no JSON envelope`;
     return { ok: false, failureKind: code === 0 ? 'invalid_output' : classifyMessage(msg), message: msg, usageRaw: null };
   }
   if (payload.status && payload.status !== 'SUCCESS') {
-    const msg = typeof payload.error === 'string' && payload.error.trim()
-      ? payload.error
-      : JSON.stringify(payload).slice(0, 2000);
+    const msg =
+      typeof payload.error === 'string' && payload.error.trim() ? payload.error : JSON.stringify(payload).slice(0, 2000);
     return { ok: false, failureKind: classifyMessage(msg), message: msg, usageRaw: payload };
   }
   const structured = payload.structured_output ?? null;
@@ -189,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),
@@ -205,7 +282,7 @@ export function usageRecord(payload) {
     // 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)
+      ? payload.denied_actions.flatMap((d) => (d?.action ? [d.action] : []))
       : null,
   };
 }
@@ -214,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
@@ -55,42 +61,77 @@ export const FORBIDDEN_FLAGS = [
 // (settings, agents, a replaced system prompt, an old session, an IDE or
 // browser link, a remote session).
 export const RESERVED_FLAGS = [
-  '--print', '--allowed-tools', '--settings', '--agent', '--agents',
-  '--system-prompt', '--system-prompt-file', '--append-system-prompt-file',
-  '--continue', '-c', '--resume', '-r', '--session-id', '--fork-session', '--from-pr', '--teleport',
-  '--input-format', '--file', '--worktree', '-w', '--tmux', '--background', '--bg',
-  '--chrome', '--ide', '--remote-control', '--cloud', '--environment', '--desktop',
+  '--print',
+  '--allowed-tools',
+  '--settings',
+  '--agent',
+  '--agents',
+  '--system-prompt',
+  '--system-prompt-file',
+  '--append-system-prompt-file',
+  '--continue',
+  '-c',
+  '--resume',
+  '-r',
+  '--session-id',
+  '--fork-session',
+  '--from-pr',
+  '--teleport',
+  '--input-format',
+  '--file',
+  '--worktree',
+  '-w',
+  '--tmux',
+  '--background',
+  '--bg',
+  '--chrome',
+  '--ide',
+  '--remote-control',
+  '--cloud',
+  '--environment',
+  '--desktop',
 ];
 
 /** 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) => (root.startsWith(`${home}/`) ? `~/${root.slice(home.length + 1)}` : `//${posixAbsolute(root).replace(/^\/+/, '')}`);
+  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)}/**)`]),
     ...PROTECTED_FILE_NAMES.map((n) => `Read(//**/${n})`),
   ];
 }
 
+/**
+ * @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;
   const web = network !== 'off';
   const args = [
     '-p',
-    '--model', chosen,
-    '--effort', consultant.effort ?? 'high',
+    '--model',
+    chosen,
+    '--effort',
+    consultant.effort ?? 'high',
     '--restricted',
     '--strict-mcp-config',
-    '--setting-sources', '',
+    '--setting-sources',
+    '',
     '--disable-slash-commands',
-    '--tools', web ? 'WebSearch,WebFetch,Read,Glob,Grep' : 'Read,Glob,Grep',
+    '--tools',
+    web ? 'WebSearch,WebFetch,Read,Glob,Grep' : 'Read,Glob,Grep',
     ...(web ? ['--allowedTools', 'WebSearch,WebFetch'] : []),
-    '--settings', JSON.stringify({ permissions: { deny: protectedReadRules() } }),
+    '--settings',
+    JSON.stringify({ permissions: { deny: protectedReadRules() } }),
     // When the lead has exposed paths, they are already copied into the
     // working directory --restricted confines the file tools to, and the
     // lead has said what this consultation may see. Widening to the whole
@@ -98,36 +139,73 @@ export function buildInvocation({ workdir, guardrails, consultant, hasExposedPat
     // flag goes. Equal-reader parity is not lost: what every consultant now
     // has is the same copied tree, which is the material that exists.
     ...(hasExposedPaths ? [] : ['--add-dir', '/']),
-    '--permission-prompts', 'none',
-    '--permission-mode', 'manual',
+    '--permission-prompts',
+    'none',
+    '--permission-mode',
+    'manual',
     '--no-session-persistence',
-    '--output-format', 'json',
-    '--json-schema', JSON.stringify(CONSULT_RESULT_SCHEMA),
-    '--max-budget-usd', String(consultant.maxBudgetUsd ?? 10),
-    '--append-system-prompt', guardrails,
+    '--output-format',
+    'json',
+    '--json-schema',
+    JSON.stringify(CONSULT_RESULT_SCHEMA),
+    '--max-budget-usd',
+    String(consultant.maxBudgetUsd ?? 10),
+    '--append-system-prompt',
+    guardrails,
   ];
   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);
       if (parsed && typeof parsed === 'object') return parsed;
-    } catch { /* not the result line */ }
+    } catch {
+      /* not the result line */
+    }
   }
   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) {
-    const msg = (stderr || '').trim() || (stdout || '').trim().slice(0, 2000) ||
+    const msg =
+      (stderr || '').trim() ||
+      (stdout || '').trim().slice(0, 2000) ||
       `claude exited with code ${code} and produced no JSON result`;
-    return { ok: false, failureKind: code === 0 ? 'invalid_output' : classifyMessage(msg), message: msg, payload: null, usageRaw: null };
+    return {
+      ok: false,
+      failureKind: code === 0 ? 'invalid_output' : classifyMessage(msg),
+      message: msg,
+      payload: null,
+      usageRaw: null,
+    };
   }
   if (payload.is_error) {
     const msg = typeof payload.result === 'string' ? payload.result : JSON.stringify(payload).slice(0, 2000);
@@ -136,15 +214,27 @@ export function interpret({ stdout, stderr, code }) {
   const structured = payload.structured_output ?? payload.structuredOutput ?? null;
   const text = structured ?? (typeof payload.result === 'string' ? payload.result : null);
   if (!text) {
-    return { ok: false, failureKind: 'invalid_output', message: 'result payload contained no answer', payload, usageRaw: payload };
+    return {
+      ok: false,
+      failureKind: 'invalid_output',
+      message: 'result payload contained no answer',
+      payload,
+      usageRaw: payload,
+    };
   }
   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),
@@ -160,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',