severally-mcp 2.4.0 → 2.4.2

package/src/adapters/opencode.mjs

@@ -30,6 +30,16 @@ import { POLICY } from '../policy.mjs';
 import { classifyMessage } from '../failures.mjs';
 import { spawnCommand } from '../platform.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').Sandbox} Sandbox */
+/** @typedef {import('../run.mjs').UsageRecord} UsageRecord */
+/** @typedef {import('../run.mjs').Boundary} Boundary */
+/** @typedef {import('../run.mjs').InterpretedOk} OpencodeOk */
+/** @typedef {import('../run.mjs').InterpretedFail} InterpretedFail */
+
 // Checked against opencode 1.18.31. The list exists so a future edit that
 // reaches for one of them is refused rather than quietly widening the
 // consultant:
@@ -82,21 +92,28 @@ export { prepareSandbox } from './opencode-sandbox.mjs';
 // server lives and dies with the child's process group. 1.18.31 has no such
 // flag (unknown flags die with a usage dump), so support is probed once per
 // process through `run --help` and the invocation stays 1.x-exact without it.
+/** @type {boolean | null} */
 let standaloneSupport = null;
+/** @type {Promise<void> | null} */
 let probePromise = null;
 
 /** Probe the CLI's capabilities once per process; safe to call per job. */
 export async function prepare() {
   if (standaloneSupport !== null) return;
   if (!probePromise) {
-    probePromise = new Promise((resolve) => {
+    probePromise = new Promise((/** @type {() => void} */ resolve) => {
       let settled = false;
+      /** @type {NodeJS.Timeout | null} */
       let timer = null;
       // Only a SUCCESSFUL help invocation may cache its answer: a spawn
       // error, a timeout or a nonzero exit is transient, and caching it as
       // "unsupported" would pin a 2.x install to the shared-service route
       // for the process lifetime. Transient outcomes resolve without
       // caching, so the next job probes again.
+      /**
+       * @param {boolean} supported
+       * @param {boolean} cache
+       */
       const finishProbe = (supported, cache) => {
         if (settled) return;
         settled = true;
@@ -115,10 +132,11 @@ export async function prepare() {
         );
         const child = spawnCommand(POLICY.clis.opencode.cli, ['run', '--help'], { env, stdio: ['ignore', 'pipe', 'pipe'] });
         let out = '';
-        child.stdout.on('data', (c) => {
+        // stdio above is 'pipe' for both, so the streams exist.
+        /** @type {NonNullable<typeof child.stdout>} */ (child.stdout).on('data', (c) => {
           out += c;
         });
-        child.stderr.on('data', (c) => {
+        /** @type {NonNullable<typeof child.stderr>} */ (child.stderr).on('data', (c) => {
           out += c;
         });
         child.on('error', () => finishProbe(false, false));
@@ -162,6 +180,8 @@ export async function resetProbe() {
  * and the caller retries once. Strictly once per job; every other failure
  * kind -- an auth rejection, a usage limit, invalid output -- means a
  * respawn is wasted compute.
+ * @param {{ interpreted: Interpreted, sandbox: Sandbox | undefined, model: string }} args
+ * @returns {boolean}
  */
 export function recoverAuthFailure({ interpreted, sandbox, model }) {
   if (!interpreted || interpreted.ok !== false || interpreted.failureKind !== 'model_unavailable') return false;
@@ -176,6 +196,10 @@ export function recoverAuthFailure({ interpreted, sandbox, model }) {
 // adapter adds or leaves out by capability probe.
 export const RESERVED_FLAGS = ['--model', '--standalone', '--wizard'];
 
+/**
+ * @param {BuildRequest} req
+ * @returns {Invocation}
+ */
 export function buildInvocation({ consultant }) {
   const t = POLICY.clis.opencode;
   const chosen = consultant.model;
@@ -204,8 +228,43 @@ export function buildInvocation({ consultant }) {
   return { command: t.cli, args, model: chosen };
 }
 
-/** Every complete NDJSON object opencode wrote to stdout, oldest first. */
+/**
+ * One NDJSON event from `opencode run --format json`; the CLI controls it, so
+ * every field is optional. `error` is {type, message} on 2.x and
+ * {name, data:{message}} on 1.x.
+ * @typedef {object} OpencodeEvent
+ * @property {string} [type]
+ * @property {{
+ *   type?: string,
+ *   text?: unknown,
+ *   time?: { end?: unknown },
+ *   tokens?: OpencodeTokens,
+ *   cost?: unknown,
+ *   tool?: string,
+ *   callID?: string,
+ *   id?: string,
+ *   state?: { status?: string },
+ * }} [part]
+ * @property {{ message?: unknown, name?: unknown, data?: { message?: unknown } }} [error]
+ */
+
+/**
+ * The token figures of a step-finish part.
+ * @typedef {{ input?: unknown, output?: unknown, total?: unknown, reasoning?: unknown, cache_read?: unknown, cache?: { read?: unknown } }} OpencodeTokens
+ */
+
+/**
+ * The usage figures interpret collects from the event stream.
+ * @typedef {{ tokens?: OpencodeTokens | null, cost?: unknown, steps?: unknown }} OpencodeUsage
+ */
+
+/**
+ * Every complete NDJSON object opencode wrote to stdout, oldest first.
+ * @param {string | undefined} stdout
+ * @returns {OpencodeEvent[]}
+ */
 export function events(stdout) {
+  /** @type {OpencodeEvent[]} */
   const out = [];
   for (const line of (stdout || '').split('\n')) {
     const t = line.trim();
@@ -227,6 +286,8 @@ export function events(stdout) {
  * filled rawCaptureMax and cut the final answer off the stream. Nothing here
  * reads tool results: interpret wants text/step_finish/error, and progress
  * only the tool name.
+ * @param {string} line
+ * @returns {string}
  */
 export function compactLine(line) {
   if (!line.includes('"tool_use"')) return line;
@@ -242,7 +303,11 @@ export function compactLine(line) {
   }
 }
 
-/** One line naming the error opencode reported, in classifyMessage's terms. */
+/**
+ * One line naming the error opencode reported, in classifyMessage's terms.
+ * @param {NonNullable<OpencodeEvent['error']>} error
+ * @returns {string}
+ */
 function errorMessage(error) {
   if (!error || typeof error !== 'object') return JSON.stringify(error);
   // 2.x: {type, message} -- the message is already a complete human sentence,
@@ -260,6 +325,8 @@ function errorMessage(error) {
  * log line lands). Raw stdout is never the message: it is the event stream
  * of a run that was working fine, its head says nothing about the failure, and
  * numbers inside it ("reasoning":403) would be classified as HTTP statuses.
+ * @param {{ errors: string[], stderr?: string | undefined, stdout?: string | undefined, code?: number | null | undefined, signal?: NodeJS.Signals | null | undefined, what: string }} run
+ * @returns {{ msg: string, kind: string }}
  */
 function failureMessage({ errors, stderr, stdout, code, signal, what }) {
   if (errors.length) {
@@ -276,20 +343,25 @@ function failureMessage({ errors, stderr, stdout, code, signal, what }) {
  * Parse the event stream `opencode run --format json` writes to stdout.
  * The answer is the LAST completed text part: a consultation can emit prose
  * between tool calls, and only the final part carries the reply contract.
+ * @param {Partial<ChildResult>} run
+ * @returns {OpencodeOk | InterpretedFail}
  */
 export function interpret({ stdout, stderr, code, signal = null, truncated = false }) {
   const all = events(stdout);
+  /** @type {string | null} */
   let text = null;
   let textIndex = -1;
   let lastErrorIndex = -1;
+  let lastError = '';
   let finishedAfterText = false;
   let tokens = null;
   let cost = null;
   let steps = 0;
+  /** @type {string[]} */
   const errors = [];
+  /** @type {string[]} */
   const earlierTextParts = [];
-  for (let i = 0; i < all.length; i++) {
-    const e = all[i];
+  for (const [i, e] of all.entries()) {
     const part = e.part;
     if (e.type === 'text' && part?.type === 'text' && part.time?.end && typeof part.text === 'string' && part.text.trim()) {
       // The last completed part wins as the answer, but every part that had
@@ -309,7 +381,8 @@ export function interpret({ stdout, stderr, code, signal = null, truncated = fal
       if (part.tokens && typeof part.tokens === 'object') tokens = part.tokens;
       if (typeof part.cost === 'number') cost = part.cost;
     } else if (e.type === 'error' && e.error) {
-      errors.push(errorMessage(e.error));
+      lastError = errorMessage(e.error);
+      errors.push(lastError);
       lastErrorIndex = i;
     }
   }
@@ -329,7 +402,7 @@ export function interpret({ stdout, stderr, code, signal = null, truncated = fal
     // failure. What text exists is interim prose, and 2.x exits 0 even on
     // provider errors, so order -- not the exit code -- is what tells this
     // apart from the recovered-retry case below.
-    const msg = errors[errors.length - 1];
+    const msg = lastError;
     return { ok: false, failureKind: classifyMessage(msg), message: msg, usageRaw };
   }
   if (code !== 0) {
@@ -339,7 +412,7 @@ export function interpret({ stdout, stderr, code, signal = null, truncated = fal
     const { msg, kind } = failureMessage({ errors, stderr, stdout, code, signal, what: 'after producing an answer' });
     return { ok: false, failureKind: kind, message: msg, usageRaw };
   }
-  if (truncated && !(finishedAfterText && all.length > 0 && all[all.length - 1].type === 'step_finish')) {
+  if (truncated && !(finishedAfterText && all.at(-1)?.type === 'step_finish')) {
     // stdout hit the rawCaptureMax before the consultation finished, so the
     // final answer event may never have been read. Under truncation only a
     // stream that ENDS on a step-finish -- the terminal event of a completed
@@ -362,34 +435,53 @@ export function interpret({ stdout, stderr, code, signal = null, truncated = fal
   return { ok: true, text, earlierTextParts, usageRaw };
 }
 
+/** The tools that read a file's contents (glob only lists names); a consultation whose calls to them all failed read none of its exposed files. */
+export const FILE_READ_TOOLS = ['read', 'grep'];
+
 /**
  * What this consultation has done so far -- read while it runs. Separates
  * "working steadily through tool calls" from "wedged on one call", which is
  * the difference between raising the budget and narrowing the brief.
  */
-/** Tool calls seen in the event stream, one per call id; `:error` when the call failed or was refused. */
+/**
+ * Tool calls seen in the event stream, one per call id; `:error` when the call 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)) {
     if (e.type === 'tool_use' && e.part?.tool) {
       seen.set(e.part.callID ?? e.part.id ?? seen.size, e.part.state?.status === 'error' ? `${e.part.tool}:error` : e.part.tool);
     }
   }
-  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 {{ stdout?: string | undefined }} run
+ * @returns {string | null}
+ */
 export function progress({ stdout }) {
-  const seen = events(stdout).filter((e) => ['step_start', 'step_finish', 'text', 'tool_use'].includes(e.type));
-  if (!seen.length) return null;
-  const last = seen[seen.length - 1];
+  const seen = events(stdout).filter(
+    (e) => e.type !== undefined && ['step_start', 'step_finish', 'text', 'tool_use'].includes(e.type),
+  );
+  const last = seen.at(-1);
+  if (!last) return null;
   const what = last.type === 'tool_use' && last.part?.tool ? `tool ${last.part.tool}` : last.type;
   return `${seen.length} event(s), last was ${what}`;
 }
 
+/**
+ * @param {unknown} raw the usage figures interpret collected from the event stream
+ * @returns {UsageRecord}
+ */
 export function usageRecord(raw) {
-  const r = raw ?? {};
+  // interpret's usageRaw is the OpencodeUsage it built (or null).
+  const r = /** @type {OpencodeUsage | null} */ (raw) ?? {};
   const t = r.tokens && typeof r.tokens === 'object' ? r.tokens : {};
-  const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+  const num = (/** @type {unknown} */ v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
   const cache = t.cache && typeof t.cache === 'object' ? t.cache : {};
   return {
     input_tokens: num(t.input),
@@ -407,15 +499,19 @@ 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 {{ sandbox: Sandbox | null }} launch
+ * @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('webfetch'),
+    web: tools.includes('webfetch'),
     writes: false,
     mcp: false,
     protected_paths: 'denied (permission rules)',
-    tools: [...sandbox.tools],
+    tools: [...tools],
   };
 }

package/src/brief.mjs

@@ -7,6 +7,52 @@ import { CONSULT_RESULT_SCHEMA } from './result-schema.mjs';
 import { redact } from './redact.mjs';
 import { humanSize } from './expose-paths.mjs';
 
+/**
+ * @typedef {object} BriefArtifact
+ * @property {string} name
+ * @property {string} kind
+ * @property {string | undefined} [language]
+ * @property {string | undefined} [source]
+ * @property {string} excerpt
+ */
+
+/**
+ * The validated request, as far as the brief reads it.
+ * @typedef {object} BriefRequest
+ * @property {string} question
+ * @property {string | null | undefined} [objective]
+ * @property {string[]} [success_criteria]
+ * @property {string[]} [constraints]
+ * @property {'explore' | 'review' | 'debate'} mode
+ * @property {'on' | 'off'} [network]
+ * @property {{ facts?: string[], proposal?: string | null, counterpoints?: string[], artifacts: BriefArtifact[] }} context
+ */
+
+/** @typedef {import('./expose-paths.mjs').ExposeManifest} ExposeManifest */
+
+/**
+ * A finding, unknown or check from an earlier round, with the lead's verdict on it.
+ * @typedef {object} PriorPoint
+ * @property {string} id
+ * @property {string} point
+ * @property {string | null} [grounds]
+ * @property {string | null} [verdict]
+ * @property {string | null} [effect]
+ */
+
+/**
+ * @typedef {object} PriorRound
+ * @property {number} round
+ * @property {string} mode
+ * @property {string} question
+ * @property {string} summary
+ * @property {PriorPoint[]} [findings]
+ * @property {PriorPoint[]} [unknowns]
+ * @property {PriorPoint[]} [next_checks]
+ */
+
+/** @typedef {{ round: number, priorRounds: PriorRound[] }} BriefChain */
+
 const MODE_BRIEFS = {
   explore: [
     'MODE: explore.',
@@ -54,7 +100,7 @@ const WEB_OFF =
 const WORKDIR_EMPTY =
   "- You are running in an empty working directory and do not have the lead's repository; everything you are meant to have is in the brief below. If something is missing, record it under `unknowns` instead of guessing or substituting an assumption.";
 const WORKDIR_EXPOSED =
-  '- Your working directory is not empty: the lead exposed specific paths, listed under "Files available to you" below and copied read-only under ./workspace. Those are the only part of the lead\'s repository you have. If something you need is missing, record it under `unknowns` instead of guessing or substituting an assumption.';
+  '- Your working directory is not empty: the lead exposed specific paths, listed under "Files available to you" below and copied read-only under ./workspace. Those are the only part of the lead\'s repository the lead gave you. If something you need is missing, record it under `unknowns` instead of guessing or substituting an assumption.';
 
 const GUARDRAILS_TAIL = [
   '- Never include credentials, API keys, tokens, or environment variable values in your answer.',
@@ -70,6 +116,10 @@ const GUARDRAILS_TAIL = [
   'Output contract: reply with exactly one JSON object matching the provided schema. No prose, no markdown fences, no commentary before or after it. Empty arrays are fine; invented content is not.',
 ];
 
+/**
+ * @param {boolean} [hasExposedPaths]
+ * @param {'on' | 'off'} [network]
+ */
 export function renderGuardrails(hasExposedPaths = false, network = 'on') {
   return [
     ...GUARDRAILS_HEAD,
@@ -85,6 +135,10 @@ export function renderGuardrails(hasExposedPaths = false, network = 'on') {
 // history holds an answer whose premises are gone -- and a finding read a month
 // later is only as good as the facts it was answering. Redacted the same way
 // renderBrief redacts the text itself, so the stored copy is what was sent.
+/**
+ * @param {BriefRequest} req
+ * @param {ExposeManifest | null} [exposeManifest]
+ */
 export function briefRecord(req, exposeManifest = null) {
   return redact({
     objective: req.objective ?? null,
@@ -126,16 +180,22 @@ export function briefRecord(req, exposeManifest = null) {
   });
 }
 
+/**
+ * @param {string} title
+ * @param {string | null | undefined} body
+ */
 function section(title, body) {
   if (!body) return null;
   return `## ${title}\n${body}`;
 }
 
+/** @param {string[] | null | undefined} items */
 function bullets(items) {
   if (!items || items.length === 0) return null;
   return items.map((i) => `- ${i}`).join('\n');
 }
 
+/** @param {BriefArtifact[]} artifacts */
 function renderArtifacts(artifacts) {
   if (!artifacts.length) return null;
   return artifacts
@@ -153,6 +213,7 @@ function renderArtifacts(artifacts) {
 const EXPOSE_LISTING_MAX = 200;
 
 // Deleted files have no copy to open; the brief says which they were.
+/** @param {string[]} [changes] */
 function deletedLines(changes = []) {
   const gone = changes.filter((c) => c.endsWith(' (deleted)')).map((c) => c.slice(0, -' (deleted)'.length));
   if (!gone.length) return [];
@@ -162,6 +223,7 @@ function deletedLines(changes = []) {
   ];
 }
 
+/** @param {ExposeManifest | null} manifest */
 function renderExposeManifest(manifest) {
   if (!manifest || (manifest.entries.length === 0 && manifest.skipped.length === 0)) return null;
   let room = EXPOSE_LISTING_MAX;
@@ -188,7 +250,9 @@ function renderExposeManifest(manifest) {
       ...(e.kind === 'diff' || e.kind === 'change_files' ? deletedLines(e.changes) : []),
     ];
   });
+  /** @param {string} reason */
   const count = (reason) => manifest.skipped.filter((x) => x.reason === reason).length;
+  /** @param {string} reason */
   const named = (reason) =>
     manifest.skipped
       .filter((x) => x.reason === reason)
@@ -211,7 +275,7 @@ function renderExposeManifest(manifest) {
   if (skipped.length) skipped.unshift('');
   return [
     'The lead exposed these paths; they are copied under ./workspace in your working directory and you may read',
-    "them directly. They are the only part of the lead's repository you have -- if you need something that is",
+    "them directly. They are the only part of the lead's repository the lead gave you -- if you need something that is",
     'not here, record it under `unknowns` rather than guessing. Text files were passed through the same',
     'credential masking as this brief; binary files were copied unchanged.',
     '',
@@ -222,16 +286,28 @@ function renderExposeManifest(manifest) {
 
 // An earlier round's point, cut to a length that keeps a five-round chain
 // from crowding out the question it is there to inform.
+/**
+ * @param {string} s
+ * @param {number} [max]
+ */
 const clip = (s, max = 400) => (s.length > max ? `${s.slice(0, max)}...` : s);
 
 // The earlier rounds have a budget of their own, beside the request's cap:
 // when they outgrow it, the oldest rounds are left out, and the brief says so.
 const HISTORY_CHARS = 40_000;
 
+/** @param {PriorRound} p */
 function renderRound(p) {
   // Prefixed with the round, so a point from round 1 is not taken for this one's.
+  /** @param {string} id */
   const tag = (id) => `r${p.round}.${id}`;
+  /** @param {PriorPoint} x */
   const verdict = (x) => (x.verdict ? ` -- lead's verdict: ${x.verdict}${x.effect ? ` (${clip(x.effect)})` : ''}` : '');
+  /**
+   * @param {string} title
+   * @param {PriorPoint[] | undefined} items
+   * @param {(x: PriorPoint) => string} line
+   */
   const list = (title, items, line) => (items?.length ? [title, ...items.map(line)].join('\n') : null);
   return [
     `### Round ${p.round} (${p.mode})`,
@@ -250,9 +326,9 @@ function renderRound(p) {
 }
 
 /**
- * @param {object} req validated request
- * @param {object} chain { round, priorRounds: [{question, mode, summary, findings: [{id, point, grounds, verdict, effect}],
- *   unknowns: [{id, point, verdict, effect}], next_checks: [{id, point, verdict, effect}]}] }
+ * @param {BriefRequest} req validated request
+ * @param {BriefChain} [chain] the round number and the earlier rounds of the chain
+ * @param {ExposeManifest | null} [exposeManifest]
  */
 export function renderBrief(req, chain = { round: 1, priorRounds: [] }, exposeManifest = null) {
   const parts = [];
@@ -292,8 +368,9 @@ export function renderBrief(req, chain = { round: 1, priorRounds: [] }, exposeMa
     let kept = 0;
     let used = 0;
     // Newest first: the round being followed up always goes in.
-    for (let i = blocks.length - 1; i >= 0 && (kept === 0 || used + blocks[i].length <= HISTORY_CHARS); i--) {
-      used += blocks[i].length;
+    for (const block of [...blocks].reverse()) {
+      if (kept > 0 && used + block.length > HISTORY_CHARS) break;
+      used += block.length;
       kept += 1;
     }
     const left = chain.priorRounds.slice(0, blocks.length - kept).map((p) => p.round);