severally-mcp 2.3.1 → 2.4.2

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',
@@ -69,13 +76,30 @@ export const FORBIDDEN_FLAGS = [
 // feature switch that could re-enable what --ignore-user-config drops, and
 // the modes that leave the read-only sandbox.
 export const RESERVED_FLAGS = [
-  '-s', '--sandbox', '--config', '--cd', '--model', '--output-last-message',
-  '--profile', '-p', '--enable', '--full-auto', '--worktree', '--cyber-access-program',
+  '-s',
+  '--sandbox',
+  '--config',
+  '--cd',
+  '--model',
+  '--output-last-message',
+  '--profile',
+  '-p',
+  '--enable',
+  '--full-auto',
+  '--worktree',
+  '--cyber-access-program',
 ];
 
 const PROFILE = 'severally';
 
-const listDir = (dir) => { try { return fs.readdirSync(dir); } catch { return []; } };
+/** @param {string} dir @returns {string[]} */
+const listDir = (dir) => {
+  try {
+    return fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+};
 
 /**
  * The profile's filesystem table, as TOML: everything readable, the protected
@@ -90,15 +114,24 @@ export function filesystemPermissions() {
   fs.mkdirSync(path.join(POLICY.home, 'homes'), { recursive: true, mode: 0o700 });
   const codexHome = path.join(os.homedir(), '.codex').replaceAll('\\', '/');
   const denied = protectedRoots().flatMap((p) => {
-    if (p === codexHome) return listDir(codexHome).filter((n) => n !== 'packages').map((n) => `${codexHome}/${n}`);
+    if (p === codexHome)
+      return listDir(codexHome)
+        .filter((n) => n !== 'packages')
+        .map((n) => `${codexHome}/${n}`);
     const star = p.indexOf('/*/');
     if (star === -1) return [p];
     const [parent, rest] = [p.slice(0, star), p.slice(star + 3)];
-    return listDir(parent).map((n) => `${parent}/${n}/${rest}`).filter((q) => fs.existsSync(q));
+    return listDir(parent)
+      .map((n) => `${parent}/${n}/${rest}`)
+      .filter((q) => fs.existsSync(q));
   });
   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;
@@ -106,29 +139,58 @@ export function buildInvocation({ workdir, schemaPath, consultant, network = 'on
   const args = [
     'exec',
     '--json',
-    '--color', 'never',
-    '-m', chosen,
-    '-c', `model_reasoning_effort="${consultant.effort ?? 'high'}"`,
-    '-c', `tools.web_search=${network !== 'off'}`,
+    '--color',
+    'never',
+    '-m',
+    chosen,
+    '-c',
+    `model_reasoning_effort="${consultant.effort ?? 'high'}"`,
+    '-c',
+    `tools.web_search=${network !== 'off'}`,
     ...(network === 'off' ? ['-c', 'web_search="disabled"'] : []),
-    '-c', 'hooks.enabled=false',
-    '-c', 'agents.enabled=false',
-    '-c', 'shell_environment_policy.inherit="core"',
-    '-c', 'shell_environment_policy.set={SEVERALLY_ACTIVE="1"}',
+    '-c',
+    'hooks.enabled=false',
+    '-c',
+    'agents.enabled=false',
+    '-c',
+    'shell_environment_policy.inherit="core"',
+    '-c',
+    'shell_environment_policy.set={SEVERALLY_ACTIVE="1"}',
     '--ignore-user-config',
     '--ignore-rules',
     '--skip-git-repo-check',
     '--ephemeral',
-    '-c', `default_permissions="${PROFILE}"`,
-    '-c', `permissions.${PROFILE}.filesystem=${filesystemPermissions()}`,
-    '-C', workdir,
-    '--output-schema', schemaPath,
-    '-o', lastMessagePath,
+    '-c',
+    `default_permissions="${PROFILE}"`,
+    '-c',
+    `permissions.${PROFILE}.filesystem=${filesystemPermissions()}`,
+    '-C',
+    workdir,
+    '--output-schema',
+    schemaPath,
+    '-o',
+    lastMessagePath,
     '-',
   ];
   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') {
@@ -140,24 +202,34 @@ 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();
     if (!t.startsWith('{')) continue;
-    try { events.push(JSON.parse(t)); } catch { /* partial line */ }
+    try {
+      events.push(JSON.parse(t));
+    } catch {
+      /* partial line */
+    }
   }
 
   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)) ||
@@ -167,9 +239,7 @@ export function interpret({ stdout, stderr, code, lastMessageText }) {
     }
   }
 
-  const errorMsg = errorEvents
-    .map((e) => e.message ?? e.error?.message ?? JSON.stringify(e))
-    .join(' | ');
+  const errorMsg = errorEvents.map((e) => e.message ?? e.error?.message ?? JSON.stringify(e)).join(' | ');
   // An error the turn recovered from (the stream still ends in
   // turn.completed, with an answer) does not throw the answer away; the lead
   // is told about it instead. A turn that ends in turn.failed has failed,
@@ -201,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 = [];
@@ -210,7 +282,9 @@ export function progress({ stdout }) {
     try {
       const e = JSON.parse(t);
       if (typeof e?.type === 'string' && e.type.startsWith('item.')) items.push(e);
-    } 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 */
+    }
   }
   if (!items.length) return null;
   const last = items[items.length - 1];
@@ -222,14 +296,21 @@ 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();
     if (!t.startsWith('{')) continue;
     let e;
-    try { e = JSON.parse(t); } catch { continue; }
+    try {
+      e = JSON.parse(t);
+    } catch {
+      continue;
+    }
     const item = e?.item;
     if (!item?.type || !['item.started', 'item.completed'].includes(e.type)) continue;
     if (['agent_message', 'reasoning', 'error'].includes(item.type)) continue;
@@ -237,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 {
@@ -260,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 {
@@ -269,9 +361,9 @@ export function boundary({ args }) {
     writes: false,
     mcp: false,
     protected_paths: args.some((a) => a.startsWith(`permissions.${PROFILE}.filesystem=`))
-      ? 'denied by path (permission profile), as the paths stood at launch: ~/.codex entries other than packages/, '
-        + 'and legacy job homes, created later are not covered; file names such as .env anywhere are not; on Linux a '
-        + 'protected file replaced by rename during the run is readable'
+      ? 'denied by path (permission profile), as the paths stood at launch: ~/.codex entries other than packages/, ' +
+        'and legacy job homes, created later are not covered; file names such as .env anywhere are not; on Linux a ' +
+        'protected file replaced by rename during the run is readable'
       : 'not enforced',
     tools: null,
   };

package/src/adapters/opencode-sandbox.mjs

@@ -48,8 +48,13 @@ import { sandboxHome } from '../store.mjs';
 // node:sqlite ships unflagged from Node 23 (and late 22.x); the engines field
 // allows older runtimes, where credential seeding degrades to a no-op and the
 // job fails with the CLI's own auth error instead.
+/** @type {typeof import('node:sqlite').DatabaseSync | null} */
 let DatabaseSync = null;
-try { ({ DatabaseSync } = sqliteRequire(import.meta.url)('node:sqlite')); } catch { /* unavailable */ }
+try {
+  ({ DatabaseSync } = sqliteRequire(import.meta.url)('node:sqlite'));
+} catch {
+  /* unavailable */
+}
 
 // Reading is allowed, not denied: every consultant is an equal reader (Codex
 // runs a read-only shell; Claude Code and Antigravity can read the whole
@@ -93,18 +98,28 @@ const SANDBOX_TOOLS_OFF = Object.freeze({ edit: false, write: false, patch: fals
 // workdir, and a run that cannot ask refuses -- so this consultant read less
 // than the others. The last matching rule wins, so "*" comes first.
 function readRules() {
-  const deny = [
-    ...protectedRoots().flatMap((r) => [r, `${r}/**`]),
-    ...PROTECTED_FILE_NAMES.flatMap((n) => [n, `**/${n}`]),
-  ];
+  const deny = [...protectedRoots().flatMap((r) => [r, `${r}/**`]), ...PROTECTED_FILE_NAMES.flatMap((n) => [n, `**/${n}`])];
   return { '*': 'allow', ...Object.fromEntries(deny.map((p) => [p, 'deny'])) };
 }
 
 const AUTH_REL = path.join('.local', 'share', 'opencode', 'auth.json');
 
+/**
+ * The synthesised HOME of one consultation, as prepareSandbox returns it.
+ * @typedef {object} OpencodeSandbox
+ * @property {string} root
+ * @property {string} credentials 'copy' or 'missing'
+ * @property {string[]} tools
+ * @property {string} credentialsSource
+ * @property {Record<string, string>} env
+ * @property {() => void} cleanup
+ * @property {(provider: string) => boolean} seed insert the provider's credential into the session database
+ */
+
 /**
  * Build the synthesised HOME for one consultation.
- * @param {{workdir: string}} 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>).
+ * @returns {OpencodeSandbox}
  */
 export function prepareSandbox({ workdir, network = 'on' }) {
   const root = sandboxHome(path.basename(path.dirname(workdir)));
@@ -162,6 +177,7 @@ export function prepareSandbox({ workdir, network = 'on' }) {
     credentials = 'copy';
   }
 
+  /** @type {OpencodeSandbox} */
   const sandbox = {
     root,
     credentials,
@@ -180,19 +196,25 @@ export function prepareSandbox({ workdir, network = 'on' }) {
       // parent directories of the (empty) working directory.
       OPENCODE_DISABLE_AUTOUPDATE: '1',
       OPENCODE_DISABLE_PROJECT_CONFIG: '1',
-      ...(process.platform === 'win32' ? {
-        USERPROFILE: root,
-        HOMEDRIVE: path.parse(root).root.replace(/[\\/]$/, ''),
-        HOMEPATH: root.slice(path.parse(root).root.length - 1),
-        APPDATA: path.join(root, 'AppData', 'Roaming'),
-        LOCALAPPDATA: path.join(root, 'AppData', 'Local'),
-      } : {}),
+      ...(process.platform === 'win32'
+        ? {
+            USERPROFILE: root,
+            HOMEDRIVE: path.parse(root).root.replace(/[\\/]$/, ''),
+            HOMEPATH: root.slice(path.parse(root).root.length - 1),
+            APPDATA: path.join(root, 'AppData', 'Roaming'),
+            LOCALAPPDATA: path.join(root, 'AppData', 'Local'),
+          }
+        : {}),
     },
     cleanup() {
-      try { fs.rmSync(root, { recursive: true, force: true }); } catch { /* best effort */ }
+      try {
+        fs.rmSync(root, { recursive: true, force: true });
+      } catch {
+        /* best effort */
+      }
     },
+    seed: (provider) => seedCredentialFromAuth(sandbox, provider),
   };
-  sandbox.seed = (provider) => seedCredentialFromAuth(sandbox, provider);
   return sandbox;
 }
 
@@ -207,6 +229,8 @@ export function prepareSandbox({ workdir, network = 'on' }) {
  * -- note "key" (the method), not the "api" auth.json uses. Only api-key
  * entries are seeded; OAuth tokens have a different shape and lifecycle.
  *
+ * @param {{ root: string }} sandbox
+ * @param {unknown} provider
  * @returns {boolean} true when a row was written and a retry is worth it.
  */
 export function seedCredentialFromAuth(sandbox, provider) {
@@ -218,6 +242,7 @@ export function seedCredentialFromAuth(sandbox, provider) {
   // CLI's own migrations, so an unbootstrapped sandbox is simply not seedable.
   if (!fs.existsSync(dbPath)) return false;
 
+  /** @type {{ label: import('node:sqlite').SQLInputValue, value: string } | null} */
   let row = null;
   // The operator's session database is what the 2.x CLI itself authenticates
   // with, so it outranks the copied auth.json: an operator who rotated their
@@ -231,7 +256,9 @@ export function seedCredentialFromAuth(sandbox, provider) {
     try {
       const db = new DatabaseSync(operatorDb, { readOnly: true });
       try {
-        const found = db.prepare('SELECT label, value FROM credential WHERE integration_id = ? ORDER BY time_updated DESC LIMIT 1').get(provider);
+        const found = db
+          .prepare('SELECT label, value FROM credential WHERE integration_id = ? ORDER BY time_updated DESC LIMIT 1')
+          .get(provider);
         if (found && typeof found.value === 'string') {
           const parsed = JSON.parse(found.value);
           if (parsed && typeof parsed === 'object' && typeof parsed.key === 'string' && parsed.key) {
@@ -241,23 +268,33 @@ export function seedCredentialFromAuth(sandbox, provider) {
       } finally {
         db.close();
       }
-    } catch { /* unreadable or reshaped: try the auth.json source */ }
+    } catch {
+      /* unreadable or reshaped: try the auth.json source */
+    }
   }
   if (!row && fs.existsSync(authPath)) {
     try {
       const entry = JSON.parse(fs.readFileSync(authPath, 'utf8'))[provider];
-      if (entry && typeof entry === 'object' && typeof entry.key === 'string' && entry.key
-        && (!entry.type || entry.type === 'api')) {
+      if (
+        entry &&
+        typeof entry === 'object' &&
+        typeof entry.key === 'string' &&
+        entry.key &&
+        (!entry.type || entry.type === 'api')
+      ) {
         row = { label: 'API key', value: JSON.stringify({ type: 'key', key: entry.key }) };
       }
-    } catch { /* unreadable auth.json: nothing seedable */ }
+    } catch {
+      /* unreadable auth.json: nothing seedable */
+    }
   }
   if (!row) return false;
   try {
     const db = new DatabaseSync(dbPath);
     try {
-      db.prepare('INSERT INTO credential (id, integration_id, label, value, time_created, time_updated) VALUES (?, ?, ?, ?, ?, ?)')
-        .run(`cred_${crypto.randomBytes(18).toString('base64url')}`, provider, row.label, row.value, Date.now(), Date.now());
+      db.prepare(
+        'INSERT INTO credential (id, integration_id, label, value, time_created, time_updated) VALUES (?, ?, ?, ?, ?, ?)',
+      ).run(`cred_${crypto.randomBytes(18).toString('base64url')}`, provider, row.label, row.value, Date.now(), Date.now());
     } finally {
       db.close();
     }