severally-mcp 2.3.1 → 2.4.2

package/src/result-schema.mjs

@@ -3,9 +3,18 @@
 // no validation keywords beyond type/enum) so it can be handed verbatim to
 // Codex's --output-schema and Claude Code's --json-schema.
 
+/** @param {string} desc */
 const s = (desc) => ({ type: 'string', description: desc });
+/**
+ * @param {string[]} values
+ * @param {string} desc
+ */
 const enumOf = (values, desc) => ({ type: 'string', enum: values, description: desc });
 
+/**
+ * @param {Record<string, object>} properties
+ * @param {string} [description]
+ */
 const obj = (properties, description) => ({
   type: 'object',
   description,
@@ -14,6 +23,10 @@ const obj = (properties, description) => ({
   additionalProperties: false,
 });
 
+/**
+ * @param {object} items
+ * @param {string} description
+ */
 const arr = (items, description) => ({ type: 'array', description, items });
 
 export const CONSULT_RESULT_SCHEMA = obj(

package/src/run.mjs

@@ -5,10 +5,7 @@ import { spawnCommand as spawn } from './platform.mjs';
 import path from 'node:path';
 import { POLICY } from './policy.mjs';
 
-const DROP_EXACT = new Set([
-  'CLAUDECODE', 'CLAUDE_PID', 'CLAUDE_EFFORT', 'AI_AGENT',
-  'ANTHROPIC_LOG', 'NODE_OPTIONS',
-]);
+const DROP_EXACT = new Set(['CLAUDECODE', 'CLAUDE_PID', 'CLAUDE_EFFORT', 'AI_AGENT', 'ANTHROPIC_LOG', 'NODE_OPTIONS']);
 const DROP_PREFIX = ['CLAUDE_CODE_', 'SEVERALLY_', 'MCP_'];
 
 // Each consultant sees only its own vendor's credentials.
@@ -49,6 +46,7 @@ const DROP_PREFIX = ['CLAUDE_CODE_', 'SEVERALLY_', 'MCP_'];
 // The names came out of the binary with `strings`; only XDG_CONFIG_HOME was
 // probed behaviourally, so read the AGY_* line as "no evidence of a
 // config-dir override under that prefix", not as proof that none exists.
+/** @type {Record<string, string[]>} */
 const TARGET_DROP_PREFIX = {
   codex: ['ANTHROPIC_', 'GEMINI_', 'GOOGLE_', 'AGY_', 'ANTIGRAVITY_', 'ZAI_'],
   'claude-code': ['OPENAI_', 'CODEX_', 'GEMINI_', 'GOOGLE_', 'AGY_', 'ANTIGRAVITY_', 'ZAI_'],
@@ -65,6 +63,7 @@ const TARGET_DROP_PREFIX = {
 // Exact names dropped for one target only (see the note above). Kept separate
 // from DROP_EXACT so the two other consultants, whose isolation has been
 // verified with these variables present, are not changed.
+/** @type {Record<string, string[]>} */
 const TARGET_DROP_EXACT = {
   antigravity: ['XDG_CONFIG_HOME'],
 };
@@ -74,10 +73,15 @@ const TARGET_DROP_EXACT = {
  * sockets, session ids, entrypoint markers) is removed, as are the other two
  * vendors' credentials -- each consultant keeps only its own; and a recursion
  * marker is added.
+ * @param {string} target
+ * @param {Record<string, string>} [extra]
+ * @param {Record<string, string>} [operator]
+ * @returns {Record<string, string>}
  */
 export function childEnv(target, extra = {}, operator = {}) {
   const { dropPrefixes, dropExact } = dropRules(target);
   const keep = providerEnvNames(target);
+  /** @type {Record<string, string>} */
   const env = {};
   for (const [k, v] of Object.entries(process.env)) {
     if (v === undefined) continue;
@@ -104,6 +108,7 @@ export function childEnv(target, extra = {}, operator = {}) {
 const SECRET_PREFIX = ['AWS_', 'AZURE_', 'GITHUB_', 'GH_', 'GITLAB_', 'NPM_', 'DOCKER_', 'HF_', 'SLACK_', 'STRIPE_', 'OP_'];
 const SECRET_SUFFIX = /(TOKEN|SECRET|PASSWORD|PASSWD|PASSPHRASE|API_?KEY|ACCESS_KEY|PRIVATE_KEY|CREDENTIALS?)$/i;
 const SECRET_EXACT = new Set(['SSH_AUTH_SOCK', 'KUBECONFIG', 'DATABASE_URL']);
+/** @type {Record<string, string[]>} */
 const OWN_PREFIX = {
   codex: ['OPENAI_', 'CODEX_'],
   'claude-code': ['ANTHROPIC_'],
@@ -113,17 +118,25 @@ const OWN_PREFIX = {
 
 // Names the operator's OpenCode provider definitions read as "{env:NAME}":
 // the consultant needs them, wherever they were exported.
+/** @param {string} target */
 function providerEnvNames(target) {
-  const provider = JSON.stringify(POLICY.clis?.[target]?.provider ?? {});
-  return new Set([...provider.matchAll(/\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g)].map((m) => m[1]));
+  // Only OpenCode's section carries provider definitions.
+  const provider = JSON.stringify(target === 'opencode' ? POLICY.clis.opencode.provider : {});
+  return new Set([...provider.matchAll(/\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g)].flatMap(([, name]) => name ?? []));
 }
 
+/**
+ * @param {string} target
+ * @param {string} key
+ * @param {Set<string>} keep
+ */
 function foreignSecret(target, key, keep) {
   if (keep.has(key) || (OWN_PREFIX[target] ?? []).some((p) => key.startsWith(p))) return false;
   const upper = key.toUpperCase();
   return SECRET_EXACT.has(upper) || SECRET_PREFIX.some((p) => upper.startsWith(p)) || SECRET_SUFFIX.test(key);
 }
 
+/** @param {string} target */
 function dropRules(target) {
   return {
     dropPrefixes: [...DROP_PREFIX, ...(TARGET_DROP_PREFIX[target] ?? [])],
@@ -139,11 +152,15 @@ function dropRules(target) {
  * by config is refused rather than honoured; so is any name the per-job
  * sandbox sets (HOME and friends), which would otherwise be silently
  * overwritten.
+ * @param {string} target
+ * @param {unknown} env
+ * @param {string[]} [sandboxKeys]
+ * @returns {string | null}
  */
 export function operatorEnvProblem(target, env, sandboxKeys = []) {
   if (env === null || typeof env !== 'object' || Array.isArray(env)) return 'must be an object of string values';
   const { dropPrefixes, dropExact } = dropRules(target);
-  const fold = (k) => (process.platform === 'win32' ? k.toUpperCase() : k);
+  const fold = (/** @type {string} */ k) => (process.platform === 'win32' ? k.toUpperCase() : k);
   const reserved = new Set(sandboxKeys.map(fold));
   for (const [k, v] of Object.entries(env)) {
     if (typeof v !== 'string') return `${k} must be a string`;
@@ -156,6 +173,10 @@ export function operatorEnvProblem(target, env, sandboxKeys = []) {
 }
 
 export class ProcHandle {
+  /**
+   * @param {import('node:child_process').ChildProcess} child
+   * @param {() => string} [readStdout]
+   */
   constructor(child, readStdout = () => '') {
     this.child = child;
     this.killed = false;
@@ -168,6 +189,7 @@ export class ProcHandle {
    * Kill the child and every descendant it spawned -- also after the child
    * itself has exited: a descendant still holding its pipes keeps the
    * consultation from closing, and on POSIX it is still in the group.
+   * @param {NodeJS.Signals} [signal]
    */
   stop(signal = 'SIGTERM') {
     if (this.killed || !this.child) return;
@@ -179,14 +201,33 @@ export class ProcHandle {
       // before its parent exits and its descendants become unreachable. Once
       // it has exited, its pid may already be another process's: leave it.
       if (this.child.exitCode !== null || this.child.signalCode !== null) return;
-      const killer = spawn(path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'taskkill.exe'),
-        ['/pid', String(pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' });
-      const fallback = () => { try { this.child.kill('SIGKILL'); } catch { /* gone */ } };
+      const killer = spawn(
+        path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'taskkill.exe'),
+        ['/pid', String(pid), '/T', '/F'],
+        { windowsHide: true, stdio: 'ignore' },
+      );
+      const fallback = () => {
+        try {
+          this.child.kill('SIGKILL');
+        } catch {
+          /* gone */
+        }
+      };
       killer.on('error', fallback);
-      killer.on('exit', (code) => { if (code !== 0) fallback(); });
+      killer.on('exit', (code) => {
+        if (code !== 0) fallback();
+      });
       return;
     }
-    try { process.kill(-pid, signal); } catch { try { this.child.kill(signal); } catch { /* gone */ } }
+    try {
+      process.kill(-pid, signal);
+    } catch {
+      try {
+        this.child.kill(signal);
+      } catch {
+        /* gone */
+      }
+    }
     setTimeout(() => this.forceKill(), POLICY.killGraceMs).unref();
   }
 
@@ -200,21 +241,153 @@ export class ProcHandle {
   forceKill() {
     const pid = this.child?.pid;
     if (!pid || process.platform === 'win32') return;
-    try { process.kill(-pid, 'SIGKILL'); } catch { /* gone */ }
+    try {
+      process.kill(-pid, 'SIGKILL');
+    } catch {
+      /* gone */
+    }
   }
 }
 
 /**
- * @returns {{handle: ProcHandle, done: Promise<{code, signal, stdout, stderr, timedOut, cancelled, truncated}>}}
+ * @typedef {object} ChildResult
+ * @property {number | null} code
+ * @property {NodeJS.Signals | null} signal
+ * @property {string} stdout
+ * @property {string} stderr
+ * @property {boolean} truncated
+ * @property {boolean} timedOut
+ * @property {boolean} cancelled
+ * @property {boolean} stalled
+ * @property {boolean} pipesForced
+ * @property {string} [spawnError]
+ */
+
+/**
+ * What an adapter's buildInvocation returns.
+ * @typedef {object} Invocation
+ * @property {string} command
+ * @property {string[]} args
+ * @property {string} model
+ * @property {string} [workdir]
+ * @property {string} [lastMessagePath]
+ */
+
+/**
+ * The synthesised HOME of one consultation, as an adapter's prepareSandbox
+ * returns it; what the adapters share of it.
+ * @typedef {object} Sandbox
+ * @property {string} root
+ * @property {string} credentials 'symlink', 'copy' or 'missing'
+ * @property {string} credentialsSource
+ * @property {readonly string[]} tools
+ * @property {Record<string, string>} env
+ * @property {() => void} cleanup
+ * @property {(provider: string) => boolean} [seed] insert the provider's credential into the session database (OpenCode only)
+ */
+
+/**
+ * What a 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.
+ * @typedef {object} Boundary
+ * @property {string} reads
+ * @property {string} shell
+ * @property {boolean} web
+ * @property {boolean} writes
+ * @property {boolean} mcp
+ * @property {string} protected_paths
+ * @property {string[] | null} tools
+ */
+
+/**
+ * What a consultation used, as far as its CLI says; null where it does not say.
+ * @typedef {object} UsageRecord
+ * @property {number | null} input_tokens
+ * @property {number | null} cached_input_tokens
+ * @property {number | null} output_tokens
+ * @property {number | null} total_tokens
+ * @property {number | null} cost_usd
+ * @property {number | null} web_search_requests
+ * @property {number | null} [turns]
+ * @property {number | null} [thinking_tokens]
+ * @property {number | null} [reasoning_tokens]
+ * @property {string[] | null} [denied_actions]
+ */
+
+/**
+ * What jobs.mjs hands buildInvocation; each adapter reads the fields it needs.
+ * @typedef {object} BuildRequest
+ * @property {string} workdir
+ * @property {string} schemaPath
+ * @property {string} guardrails
+ * @property {Sandbox | null} sandbox the adapter's own prepareSandbox result, if it has one
+ * @property {import('./consultants.mjs').Consultant} consultant
+ * @property {boolean} [hasExposedPaths]
+ * @property {'on' | 'off' | undefined} [network]
+ */
+
+/**
+ * What an adapter's interpret makes of a finished child: an answer (text is a
+ * JSON object or the raw text to mine one out of), or a classified failure.
+ * @typedef {{ ok: true, text: string | Record<string, unknown>, usageRaw: unknown, payload?: unknown, events?: number, denials?: unknown[], recoveredError?: { failureKind: string, message: string } | null, earlierTextParts?: string[] }} InterpretedOk
+ * @typedef {{ ok: false, failureKind: string, message: string, usageRaw: unknown, payload?: unknown, events?: number }} InterpretedFail
+ * @typedef {InterpretedOk | InterpretedFail} Interpreted
  */
+
+/**
+ * The shape every adapter module (codex, claude-code, antigravity, opencode)
+ * exports; the optional members are the ones only some CLIs have.
+ * @typedef {object} Adapter
+ * @property {readonly string[]} FORBIDDEN_FLAGS
+ * @property {readonly string[]} RESERVED_FLAGS
+ * @property {(req: BuildRequest) => Invocation} buildInvocation
+ * @property {(run: Partial<ChildResult> & { lastMessageText?: string }) => Interpreted} interpret
+ * @property {(raw: unknown) => UsageRecord | null} usageRecord
+ * @property {(args: { args: string[], sandbox: Sandbox | null, network?: 'on' | 'off' | undefined, hasExposedPaths?: boolean }) => Boundary} [boundary]
+ * @property {(run: { stdout: string }) => string | null} [progress]
+ * @property {(run: { stdout: string }) => Record<string, number> | null} [toolCalls]
+ * @property {readonly string[]} [FILE_READ_TOOLS] the names toolCalls reports for reading a file
+ * @property {readonly string[]} [ALLOWED_TOOLS] the only tools the consultant may call; any other is refused
+ * @property {() => Promise<void>} [prepare]
+ * @property {(args: { workdir: string, network?: 'on' | 'off' | undefined }) => Sandbox} [prepareSandbox]
+ * @property {(args: { run: ChildResult, sandbox: Sandbox }) => string} [diagnostics]
+ * @property {(args: { interpreted: Interpreted, sandbox: Sandbox, model: string }) => boolean} [recoverAuthFailure]
+ * @property {(line: string) => string} [compactLine]
+ * @property {(line: string) => number | null | undefined} [settleAfter]
+ * @property {NodeJS.Signals} [stopSignal]
+ */
+
 /**
  * `pipesForced` in the result: the child exited but something it started kept
  * stdout or stderr open past the kill grace, so the group was stopped and the
  * pipes closed from this side. A descendant outside the group (setsid, or on
  * Windows once the parent is gone) may still be running.
+ * @param {object} options
+ * @param {string} options.command
+ * @param {readonly string[]} options.args
+ * @param {string} [options.cwd]
+ * @param {NodeJS.ProcessEnv} [options.env]
+ * @param {string | null} [options.input]
+ * @param {number} options.timeoutMs
+ * @param {(cancel: () => void) => void} [options.onCancelSignal]
+ * @param {((line: string) => string) | null} [options.compactLine]
+ * @param {((line: string) => number | null | undefined) | null} [options.settleAfter]
+ * @param {NodeJS.Signals} [options.stopSignal]
+ * @returns {{handle: ProcHandle, done: Promise<ChildResult>, pid: number | undefined}}
  */
-export function runChild({ command, args, cwd, env, input, timeoutMs, onCancelSignal, compactLine = null,
-  settleAfter = null, stopSignal = 'SIGTERM' }) {
+export function runChild({
+  command,
+  args,
+  cwd,
+  env,
+  input,
+  timeoutMs,
+  onCancelSignal,
+  compactLine = null,
+  settleAfter = null,
+  stopSignal = 'SIGTERM',
+}) {
   const child = spawn(command, args, {
     cwd,
     // PWD is the parent's otherwise, and opencode takes its project root from
@@ -237,24 +410,34 @@ export function runChild({ command, args, cwd, env, input, timeoutMs, onCancelSi
   // says it is done; past that it is stopped and `stalled` set. A later line
   // can shorten the wait, never lengthen it.
   let stalled = false;
-  let settleTimer = null;
+  /** @type {NodeJS.Timeout | undefined} */
+  let settleTimer;
   let settleAt = Infinity;
-  const watch = (line) => {
-    const ms = settleAfter(line);
+  const watch = (/** @type {string} */ line) => {
+    const ms = settleAfter?.(line);
     if (ms == null || Date.now() + ms >= settleAt) return;
     settleAt = Date.now() + ms;
     clearTimeout(settleTimer);
-    settleTimer = setTimeout(() => { stalled = true; handle.stop(stopSignal); }, ms);
+    settleTimer = setTimeout(() => {
+      stalled = true;
+      handle.stop(stopSignal);
+    }, ms);
   };
 
-  const append = (which, chunk) => {
+  const append = (/** @type {'out' | 'err'} */ which, /** @type {string | Buffer} */ chunk) => {
     const text = chunk.toString('utf8');
     if (which === 'out') {
-      if (stdout.length >= cap) { truncated = true; return; }
+      if (stdout.length >= cap) {
+        truncated = true;
+        return;
+      }
       stdout += text.slice(0, cap - stdout.length);
       if (stdout.length >= cap) truncated = true;
     } else {
-      if (stderr.length >= cap) { truncated = true; return; }
+      if (stderr.length >= cap) {
+        truncated = true;
+        return;
+      }
       stderr += text.slice(0, cap - stderr.length);
       if (stderr.length >= cap) truncated = true;
     }
@@ -265,15 +448,18 @@ export function runChild({ command, args, cwd, env, input, timeoutMs, onCancelSi
   // partial line is bounded by the cap too; past it, the line is kept as is.
   let pending = '';
   const byLine = Boolean(compactLine || settleAfter);
-  const compact = compactLine ?? ((l) => l);
+  const compact = compactLine ?? ((/** @type {string} */ l) => l);
   const flushLines = () => {
     const lines = pending.split('\n');
-    pending = lines.pop();
+    pending = lines.pop() ?? '';
     for (const l of lines) {
       if (settleAfter) watch(l);
       append('out', `${compact(l)}\n`);
     }
-    if (pending.length > cap) { append('out', pending); pending = ''; }
+    if (pending.length > cap) {
+      append('out', pending);
+      pending = '';
+    }
   };
   // Decode as a stream: a multibyte character split across two chunks would
   // otherwise turn into replacement characters inside the answer text.
@@ -298,11 +484,13 @@ export function runChild({ command, args, cwd, env, input, timeoutMs, onCancelSi
     });
   }
 
+  /** @type {Promise<ChildResult>} */
   const done = new Promise((resolve) => {
     let settled = false;
     let pipesForced = false;
-    let orphanTimer = null;
-    const finish = (payload) => {
+    /** @type {NodeJS.Timeout | undefined} */
+    let orphanTimer;
+    const finish = (/** @type {{ code: number | null, signal: NodeJS.Signals | null, spawnError?: string }} */ payload) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
@@ -310,7 +498,12 @@ export function runChild({ command, args, cwd, env, input, timeoutMs, onCancelSi
       clearTimeout(orphanTimer);
       resolve({ stdout, stderr, truncated, timedOut, cancelled, stalled, pipesForced, ...payload });
     };
-    const flushPending = () => { if (byLine && pending) { append('out', compact(pending)); pending = ''; } };
+    const flushPending = () => {
+      if (byLine && pending) {
+        append('out', compact(pending));
+        pending = '';
+      }
+    };
     child.on('error', (err) => finish({ code: null, signal: null, spawnError: err.message }));
     // 'close' waits for the pipes as well as the child. Once the child has
     // exited, a grace later the rest of its group is stopped, and a grace
@@ -336,7 +529,9 @@ export function runChild({ command, args, cwd, env, input, timeoutMs, onCancelSi
   });
 
   if (input !== undefined && input !== null) {
-    child.stdin.on('error', () => { /* child may exit before draining stdin */ });
+    child.stdin.on('error', () => {
+      /* child may exit before draining stdin */
+    });
     child.stdin.end(input);
   } else {
     child.stdin.end();