severally-mcp 2.4.0 → 2.5.0

package/src/policy.mjs

@@ -7,7 +7,10 @@ import os from 'node:os';
 import path from 'node:path';
 import { parseJsonc } from './jsonc.mjs';
 import { findCommand } from './platform.mjs';
-import { buildConsultants, normalizeName } from './consultants.mjs';
+import { buildConsultants, isObject, normalizeName } from './consultants.mjs';
+
+/** @typedef {import('./consultants.mjs').Consultant} Consultant */
+/** @typedef {import('./consultants.mjs').CliId} CliId */
 
 // One file, read once at start, so an operator configures a machine in a
 // single place instead of editing each client's MCP registration. Precedence
@@ -22,7 +25,9 @@ const CONFIG_PATH =
   [path.join(CONFIG_HOME, 'config.jsonc'), path.join(CONFIG_HOME, 'config.json')].find((p) => fs.existsSync(p)) ||
   path.join(CONFIG_HOME, 'config.json');
 
+/** @type {string | null} */
 let configError = null;
+/** @type {unknown} the parsed config file, before validation */
 const CONFIG = (() => {
   try {
     return parseJsonc(fs.readFileSync(CONFIG_PATH, 'utf8'));
@@ -30,7 +35,8 @@ const CONFIG = (() => {
     // A missing file is the normal case. A malformed one is not: silently
     // ignoring it would run the machine on defaults the operator thinks they
     // overrode, so it is surfaced on stderr when the server starts.
-    if (err.code !== 'ENOENT') configError = `${CONFIG_PATH}: ${err.message}`;
+    const code = err instanceof Error && 'code' in err ? err.code : undefined;
+    if (code !== 'ENOENT') configError = `${CONFIG_PATH}: ${err instanceof Error ? err.message : String(err)}`;
     return {};
   }
 })();
@@ -50,7 +56,10 @@ if (!configError && ![undefined, '', 'on', 'off'].includes(process.env.SEVERALLY
 const FROM = configError ? buildConsultants({}) : BUILT;
 const LOCAL = configError ? [] : BUILT.problems.filter((p) => !BUILT.global.includes(p));
 
-/** What is wrong with the config file as a whole, or null. Reported at startup; while set, nothing can be started. */
+/**
+ * What is wrong with the config file as a whole, or null. Reported at startup; while set, nothing can be started.
+ * @returns {string | null}
+ */
 export function configProblem() {
   return configError;
 }
@@ -65,34 +74,66 @@ export function brokenConsultantNames() {
   return configError ? [] : Object.keys(BUILT.broken);
 }
 
-/** Why the consultant of this name is out of use because of a config mistake, or null. */
+/**
+ * Why the consultant of this name is out of use because of a config mistake, or null.
+ * @param {string} name
+ */
 export function brokenConsultant(name) {
   const p = !configError && Object.hasOwn(BUILT.broken, name) ? BUILT.broken[name] : null;
   return p ? `the config file has a mistake in it: ${p.join('; ')}` : null;
 }
 
-const usable = configError ? {} : CONFIG;
+/**
+ * One CLI's section of the config file. `args`, `env` and `provider` are read
+ * only after buildConsultants has checked them (a section with a mistake is
+ * replaced by a disabled one in cfgCli), so they have the types given here.
+ * @typedef {object} CliSection
+ * @property {unknown} [enabled]
+ * @property {unknown} [note]
+ * @property {unknown} [bin]
+ * @property {string[]} [args]
+ * @property {Record<string, string>} [env]
+ * @property {Record<string, Record<string, unknown>>} [provider]
+ */
+
+/** @type {Record<string, unknown>} */
+const usable = configError || !isObject(CONFIG) ? {} : CONFIG;
 // A CLI whose own section has a mistake is off, whatever else the section says.
+/**
+ * @param {string} id
+ * @returns {CliSection}
+ */
 const cfgCli = (id) => {
-  if (Object.hasOwn(BUILT.brokenClis, id) && !configError) {
+  const broken = Object.hasOwn(BUILT.brokenClis, id) ? BUILT.brokenClis[id] : undefined;
+  if (broken && !configError) {
     return {
       enabled: false,
-      note: `turned off: the config file has a mistake in clis.${id}: ${BUILT.brokenClis[id].join('; ')}`,
+      note: `turned off: the config file has a mistake in clis.${id}: ${broken.join('; ')}`,
     };
   }
-  return usable.clis && typeof usable.clis === 'object' ? (usable.clis[id] ?? {}) : {};
+  const def = isObject(usable.clis) ? usable.clis[id] : undefined;
+  // A section reaches here only when buildConsultants found no mistake in it.
+  return isObject(def) ? /** @type {CliSection} */ (def) : {};
 };
-const cfgServer = usable.server && typeof usable.server === 'object' ? usable.server : {};
+const cfgServer = isObject(usable.server) ? usable.server : {};
 
 /**
  * Is this command runnable here? Absolute/relative paths are checked as given.
  * Exported so the config generator can report what a machine has without
  * going through POLICY, which already reflects any config file it found.
+ * @param {string} command
  */
 export function isInstalled(command) {
   return findCommand(command) !== null;
 }
 
+/**
+ * @param {string} name
+ * @param {number | null} dflt
+ * @param {number} min
+ * @param {number} max
+ * @returns {number | null}
+ */
 const num = (name, dflt, min, max) => {
   const raw = process.env[name];
   if (raw === undefined || raw === '') return dflt;
@@ -105,6 +146,14 @@ const num = (name, dflt, min, max) => {
 // the same range whichever one supplied it. Codex and OpenCode do not pass the
 // user's shell environment to an MCP server, so for them the file is the only
 // place an operator can reach without editing the client's registration.
+/**
+ * @param {string} name
+ * @param {unknown} fromCfg
+ * @param {number} dflt
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
 const limit = (name, fromCfg, dflt, min, max) => {
   const fromEnv = num(name, null, min, max);
   if (fromEnv !== null) return fromEnv;
@@ -112,6 +161,11 @@ const limit = (name, fromCfg, dflt, min, max) => {
   return dflt;
 };
 
+/**
+ * @param {string} name
+ * @param {string} dflt
+ * @returns {string}
+ */
 const str = (name, dflt) => {
   const raw = process.env[name];
   return raw === undefined || raw === '' ? dflt : raw;
@@ -120,6 +174,7 @@ const str = (name, dflt) => {
 // The CLI a lead runs in, by any everyday name. Only `caller` uses this:
 // which consultant a name reaches is consultants.mjs's resolveConsultant.
 // Object.create(null) so 'constructor' is an unknown name, not a function.
+/** @type {Readonly<Record<string, CliId>>} */
 export const CALLER_ALIASES = Object.freeze(
   Object.assign(Object.create(null), {
     codex: 'codex',
@@ -140,14 +195,22 @@ export const CALLER_ALIASES = Object.freeze(
 
 export const CALLER_INPUTS = Object.freeze(Object.keys(CALLER_ALIASES));
 
-/** The CLI id for any accepted spelling of a caller, or null. */
+/**
+ * The CLI id for any accepted spelling of a caller, or null.
+ * @param {unknown} raw
+ * @returns {CliId | null}
+ */
 export function resolveCaller(raw) {
   const key = normalizeName(raw);
-  return typeof key === 'string' && Object.hasOwn(CALLER_ALIASES, key) ? CALLER_ALIASES[key] : null;
+  return typeof key === 'string' ? (CALLER_ALIASES[key] ?? null) : null;
 }
 
 // Which CLI is hosting this server. Used only to annotate a consultation that
 // goes to the caller's own vendor; it never affects permissions or limits.
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {CliId | null}
+ */
 export function detectCaller(env = process.env) {
   if (env.CLAUDECODE === '1' || env.CLAUDE_CODE_ENTRYPOINT) return 'claude-code';
   if (env.CODEX_HOME || env.CODEX_SANDBOX || env.CODEX_SANDBOX_NETWORK_DISABLED) return 'codex';
@@ -167,12 +230,15 @@ export const VERDICTS = ['unverified', 'confirmed', 'not_applicable', 'unverifia
 // The consultant's own one-word bottom line. Also what the lead may predict
 // before asking -- the same vocabulary, so a prediction and an answer can be
 // read side by side without anyone translating between two scales.
-export const STANCES = ['proceed', 'do_not_proceed', 'alternative', 'undetermined'];
+export const STANCES = /** @type {const} */ (['proceed', 'do_not_proceed', 'alternative', 'undetermined']);
 
 /**
  * A leading ~ is a shell courtesy, not a path: nothing expands it here, so
  * "~/.local/bin/claudex" would simply not exist and the consultant would drop
  * out of the available list without saying why. Expand it where a path is read.
+ * @template T
+ * @param {T} value
+ * @returns {T | string}
  */
 function expandHome(value) {
   if (typeof value !== 'string') return value;
@@ -181,6 +247,12 @@ function expandHome(value) {
 }
 
 // env > config file > built-in default, for a CLI's bin.
+/**
+ * @param {string} id
+ * @param {string} envName
+ * @param {string} dflt
+ * @returns {string}
+ */
 const binFor = (id, envName, dflt) => {
   const fromEnv = process.env[envName];
   if (fromEnv !== undefined && fromEnv !== '') return expandHome(fromEnv);
@@ -191,11 +263,16 @@ const binFor = (id, envName, dflt) => {
 // Why a consultant is off, in the operator's words: "quota exhausted until
 // 15:00" is more use to a lead than a bare refusal, and it is the reason a CLI
 // that IS installed gets excluded.
+/** @param {string} id */
 const disabledNote = (id) => {
   const n = cfgCli(id).note;
   return typeof n === 'string' && n.trim() !== '' ? n.trim() : null;
 };
 
+/**
+ * @param {string} id
+ * @param {string} cli
+ */
 const isEnabled = (id, cli) => {
   const flag = cfgCli(id).enabled;
   if (typeof flag === 'boolean') return flag;
@@ -210,7 +287,14 @@ const OPENCODE_BIN = binFor('opencode', 'SEVERALLY_OPENCODE_BIN', 'opencode');
 // Operator-only extras for the child process (config: args, env). Config-only,
 // never from a request, and validated at launch (jobs.mjs) where the isolation
 // flags and variables they must not undo are known.
-const extras = (id) => ({ extraArgs: cfgCli(id).args ?? [], extraEnv: cfgCli(id).env ?? {} });
+/**
+ * @param {string} id
+ * @returns {{ extraArgs: string[], extraEnv: Record<string, string> }}
+ */
+const extras = (id) => ({
+  extraArgs: cfgCli(id).args ?? [],
+  extraEnv: cfgCli(id).env ?? {},
+});
 
 export const POLICY = Object.freeze({
   home: str('SEVERALLY_HOME', path.join(os.homedir(), '.severally')),
@@ -316,6 +400,8 @@ export const POLICY = Object.freeze({
   }),
 });
 
+/** @typedef {typeof POLICY} Policy */
+
 /**
  * Wall-clock budget for one consultation of this consultant. Read at job
  * start (not frozen into the module) so an operator restart is not needed to
@@ -323,6 +409,7 @@ export const POLICY = Object.freeze({
  * same time: a long Gemini answer should not force the same patience on every
  * other consultant. The two hour ceiling stays -- past that the answer is a
  * different request, not a slower one.
+ * @param {Consultant | null} [consultant]
  */
 export function timeoutMs(consultant) {
   return consultant?.timeoutMs ?? limit('SEVERALLY_TIMEOUT_MS', cfgServer.timeout_ms, 1_800_000, 1_000, 7_200_000);
@@ -417,8 +504,12 @@ export const PROTECTED_FILE_NAMES = Object.freeze([
   'id_dsa',
 ]);
 
-/** Absolute protected roots, with forward slashes; `*` stands for one path segment. */
+/**
+ * Absolute protected roots, with forward slashes; `*` stands for one path segment.
+ * @returns {string[]}
+ */
 export function protectedRoots() {
+  /** @param {string} p */
   const fwd = (p) => p.replaceAll('\\', '/');
   return [
     ...PROTECTED_HOME_PATHS.map((rel) => fwd(path.join(os.homedir(), rel))),
@@ -426,10 +517,14 @@ export function protectedRoots() {
   ];
 }
 
+/** @param {string} s */
 const escapeRe = (s) => s.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
 // Case-insensitive where the default file system is: Windows and macOS.
 export const PATHS_CASE_INSENSITIVE = process.platform === 'win32' || process.platform === 'darwin';
-/** Regex sources: one per protected root, matching it and anything under it. */
+/**
+ * Regex sources: one per protected root, matching it and anything under it.
+ * @param {string[]} [extraRoots]
+ */
 export function protectedRootPatterns(extraRoots = []) {
   return [...protectedRoots(), ...extraRoots.map((r) => r.replaceAll('\\', '/'))].map(
     (r) => `^${escapeRe(r.replace(/\/+$/, '')).replaceAll('*', '[^/]+')}(/|$)`,
@@ -440,7 +535,10 @@ export function protectedNamePatterns() {
   return PROTECTED_FILE_NAMES.map((n) => `^${escapeRe(n).replaceAll('*', '.*')}$`);
 }
 
-/** Whether an absolute path, or the file it links to, is protected. */
+/**
+ * Whether an absolute path, or the file it links to, is protected.
+ * @param {string} abs
+ */
 export function isProtectedPath(abs) {
   const flags = PATHS_CASE_INSENSITIVE ? 'i' : '';
   const roots = protectedRootPatterns().map((p) => new RegExp(p, flags));
@@ -459,12 +557,31 @@ export function isProtectedPath(abs) {
 
 export const artifactKinds = ['code', 'log', 'doc', 'data', 'diff', 'spec', 'test-output', 'config'];
 
-/** The consultant with this exact name, or undefined. */
+/**
+ * The consultant with this exact name, or undefined.
+ * @param {string} name
+ */
 export function consultantByName(name) {
   return POLICY.consultants.find((c) => c.name === name);
 }
 
-/** Can this consultant run here: turned on itself, and its CLI usable. */
+/**
+ * The consultant with this exact name, for a caller that holds a name it got
+ * from a consultant already (a started job's target). Throws when there is
+ * none; use consultantByName when the name may be unknown.
+ * @param {string} name
+ * @returns {Consultant}
+ */
+export function consultantNamed(name) {
+  const c = consultantByName(name);
+  if (!c) throw new Error(`no consultant named "${name}"`);
+  return c;
+}
+
+/**
+ * Can this consultant run here: turned on itself, and its CLI usable.
+ * @param {Consultant} c
+ */
 export function consultantAvailable(c) {
   return c.enabled && POLICY.clis[c.cli].available;
 }
@@ -472,6 +589,8 @@ export function consultantAvailable(c) {
 /**
  * Why this consultant cannot be reached, or null when it can. The operator's
  * own note wins: "installed but rate-limited" is a case only they can state.
+ * @param {Consultant | null | undefined} c
+ * @returns {string | null}
  */
 export function unavailableReason(c) {
   if (!c || consultantAvailable(c)) return null;
@@ -489,6 +608,7 @@ export function availableConsultants() {
 
 export function limitsSummary() {
   const list = availableConsultants();
+  /** @param {(c: Consultant) => unknown} f */
   const by = (f) => Object.fromEntries(list.map((c) => [c.name, f(c)]));
   return {
     available_targets: list.map((c) => c.name),
@@ -504,16 +624,19 @@ export function limitsSummary() {
     max_concurrent_jobs: POLICY.maxConcurrent,
     max_wait_ms: POLICY.maxWaitMs,
     input_char_budget: POLICY.input.totalCharsMax,
-    // Stated so it is true of all three consultants. Reading is allowed for
-    // every one of them -- what keeps a consultation brief-only is that the
-    // child starts in an empty working directory and is never told where the
-    // repository is, not that it cannot read. Codex is additionally sandboxed
-    // read-only rather than execution-free, so do not advertise "no execution".
+    // Stated so it is true of all four CLIs. Reading is allowed for every one
+    // of them -- what keeps a consultation brief-only is that the child starts
+    // in an empty working directory and is never told where the repository
+    // is, not that it cannot read. Only Claude Code drops its whole-disk read
+    // when files are exposed (claude-code.mjs). Codex is additionally
+    // sandboxed read-only rather than execution-free, so do not advertise
+    // "no execution".
     consultant_permissions:
-      'web search/browse and reading local files allowed, but the consultant starts in an empty working ' +
-      'directory and is not told where your repository is -- unless context.expose_paths names files or ' +
-      'directories, which are copied read-only into that working directory and are then the only part of ' +
-      'your repository it has; file edits, network access, MCP tools and further consultations denied; the ' +
-      'Codex consultant additionally has a read-only shell',
+      'web search/browse and reading local files allowed; the consultant starts in an empty working ' +
+      'directory and is not told where your repository is. context.expose_paths copies the files or ' +
+      'directories it names read-only into that working directory, but that is not a read boundary: apart ' +
+      'from the protected credential paths, Codex, Antigravity and OpenCode can read any file your account ' +
+      'can, and so can Claude Code when nothing is exposed; file edits, network access, MCP tools and ' +
+      'further consultations denied; the Codex consultant additionally has a read-only shell',
   };
 }

package/src/redact.mjs

@@ -20,6 +20,10 @@ const CODE_WORDS = new Set([
 // variable reference (${X}, $X, process.env.X, os.environ[...]), and -- unless
 // it is a long value under a full PASSWORD/PASSWD name, which stays masked
 // whatever it looks like -- a dotted name, a call or a borrow (&str).
+/**
+ * @param {string} name
+ * @param {string} value
+ */
 function looksLikeCode(name, value) {
   if (
     CODE_WORDS.has(value.toLowerCase()) ||
@@ -28,12 +32,12 @@ function looksLikeCode(name, value) {
     /^(?:process\.env\.|os\.environ\b)/.test(value)
   )
     return true;
-  if (value.length >= 8 && /^PASSW(?:OR)?D$/i.test(name.split('_').at(-1))) return false;
+  if (value.length >= 8 && /^PASSW(?:OR)?D$/i.test(name.split('_').at(-1) ?? '')) return false;
   return /^[A-Za-z_][\w$]*(?:\.[A-Za-z_$][\w$]*)+$/.test(value) || /^[A-Za-z_][\w$.]*\(/.test(value) || value.startsWith('&');
 }
 
 // A replacement is a string or a function of the match.
-/** @type {Array<[RegExp, any]>} */
+/** @type {Array<[RegExp, string | ((...groups: string[]) => string)]>} */
 const PATTERNS = [
   // Provider API keys
   [/\bsk-ant-[A-Za-z0-9_-]{12,}/g, '[REDACTED:anthropic-key]'],
@@ -75,15 +79,29 @@ const PATTERNS = [
   [/\b([A-Z0-9_]+_KEY)(\s*=\s*["']?)([^\s"',;)]{8,})/g, (_m, k, sep, _v) => `${k}${sep}[REDACTED]`],
 ];
 
+/**
+ * Any JSON-like value in, the same shape out with its strings scrubbed.
+ * @template T
+ * @overload
+ * @param {T} value
+ * @returns {T}
+ */
+/**
+ * @param {unknown} value
+ * @returns {unknown}
+ */
 export function redact(value) {
   if (value === null || value === undefined) return value;
   if (typeof value === 'string') {
+    /** @type {string} */
     let out = value;
-    for (const [re, rep] of PATTERNS) out = out.replace(re, rep);
+    // The same call either way: replace() has one overload for a string and one for a function.
+    for (const [re, rep] of PATTERNS) out = typeof rep === 'string' ? out.replace(re, rep) : out.replace(re, rep);
     return out;
   }
   if (Array.isArray(value)) return value.map(redact);
   if (typeof value === 'object') {
+    /** @type {Record<string, unknown>} */
     const out = {};
     for (const [k, v] of Object.entries(value)) out[k] = redact(v);
     return out;
@@ -91,6 +109,7 @@ export function redact(value) {
   return value;
 }
 
+/** @param {unknown} text */
 export function containsSecret(text) {
   if (typeof text !== 'string') return false;
   return redact(text) !== text;

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(