severally-mcp 2.0.0 → 2.3.1

package/src/policy.mjs

@@ -35,21 +35,50 @@ const CONFIG = (() => {
   }
 })();
 
-// Every mistake in the file, not only a syntax error. A config with any of
-// them is not run on defaults: the server still starts, so the operator can
-// read why, but every consultation is refused (jobs.mjs) -- falling back would
-// quietly re-enable a CLI the operator turned off.
+// A mistake that leaves the whole file untrustworthy (unreadable, an unknown
+// top-level key, a section of the wrong shape) is not run on defaults: the
+// server still starts, so the operator can read why, but every consultation is
+// refused (jobs.mjs) -- falling back would quietly re-enable a CLI the
+// operator turned off. A mistake inside one consultant or one CLI only takes
+// that one out of use, with the reason.
 const BUILT = buildConsultants(CONFIG);
-if (!configError && BUILT.problems.length) configError = `${CONFIG_PATH}: ${BUILT.problems.join('; ')}`;
+if (!configError && BUILT.global.length) configError = `${CONFIG_PATH}: ${BUILT.global.join('; ')}`;
+// A value that is neither, from the environment, cannot be read as either: reading it as "on" would open the web.
+if (!configError && ![undefined, '', 'on', 'off'].includes(process.env.SEVERALLY_NETWORK)) {
+  configError = `SEVERALLY_NETWORK must be "on" or "off", not ${JSON.stringify(process.env.SEVERALLY_NETWORK)}`;
+}
 const FROM = configError ? buildConsultants({}) : BUILT;
+const LOCAL = configError ? [] : BUILT.problems.filter((p) => !BUILT.global.includes(p));
 
-/** What is wrong with the config file, 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. */
 export function configProblem() {
   return configError;
 }
 
+/** The mistakes kept to one consultant or one CLI, each of which is out of use until fixed. */
+export function configWarnings() {
+  return LOCAL.map((p) => `${CONFIG_PATH}: ${p}`);
+}
+
+/** The names of the consultants out of use because of a mistake in their own config section. */
+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. */
+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;
-const cfgCli = (id) => (usable.clis && typeof usable.clis === 'object' ? usable.clis[id] ?? {} : {});
+// A CLI whose own section has a mistake is off, whatever else the section says.
+const cfgCli = (id) => {
+  if (Object.hasOwn(BUILT.brokenClis, id) && !configError) {
+    return { enabled: false, note: `turned off: the config file has a mistake in clis.${id}: ${BUILT.brokenClis[id].join('; ')}` };
+  }
+  return usable.clis && typeof usable.clis === 'object' ? usable.clis[id] ?? {} : {};
+};
 const cfgServer = usable.server && typeof usable.server === 'object' ? usable.server : {};
 
 /**
@@ -214,9 +243,14 @@ export const POLICY = Object.freeze({
   // going beyond that is an operator decision with quota to match.
   maxConcurrent: limit('SEVERALLY_MAX_CONCURRENT', cfgServer.max_concurrent, 9, 1, 9),
   maxJobsRetained: limit('SEVERALLY_MAX_JOBS_RETAINED', cfgServer.max_jobs_retained, 200, 20, 2000),
-  // Upper bound for consult_get(wait_ms). Deliberately under the 60s default
-  // request timeout that MCP clients apply, so a long wait does not blow up as
-  // a client-side timeout while the consultation is still healthy.
+  // Upper bound for consult_get(wait_ms). 45 s stays under the 60 s some MCP
+  // clients allow a tool call, so a long wait does not blow up as a client-side
+  // timeout while the consultation is still healthy; a client registration
+  // that is known to wait longer raises it (scripts/install.mjs).
+  // "off" takes the web away from every consultation, whatever the request
+  // asks; "on" leaves it to each request's own network.
+  // Either source can close it; neither can reopen what the other closed.
+  network: [process.env.SEVERALLY_NETWORK, cfgServer.network].includes('off') ? 'off' : 'on',
   maxWaitMs: limit('SEVERALLY_MAX_WAIT_MS', cfgServer.max_wait_ms, 45_000, 0, 600_000),
 
   input: Object.freeze({
@@ -261,7 +295,7 @@ export const POLICY = Object.freeze({
  * different request, not a slower one.
  */
 export function timeoutMs(consultant) {
-  return consultant?.timeoutMs ?? limit('SEVERALLY_TIMEOUT_MS', cfgServer.timeout_ms, 3_600_000, 1_000, 7_200_000);
+  return consultant?.timeoutMs ?? limit('SEVERALLY_TIMEOUT_MS', cfgServer.timeout_ms, 1_800_000, 1_000, 7_200_000);
 }
 
 /**
@@ -388,11 +422,15 @@ export function limitsSummary() {
   const by = (f) => Object.fromEntries(list.map((c) => [c.name, f(c)]));
   return {
     available_targets: list.map((c) => c.name),
+    // A consultant or CLI out of use because of a mistake in its own section.
+    ...(LOCAL.length ? { config_mistakes: configWarnings() } : {}),
     clis: by((c) => c.cli),
     models: by((c) => c.model),
     // Per consultant, because they no longer share one budget.
     timeout_ms: by(timeoutMs),
     max_rounds_per_chain: POLICY.maxRounds,
+    // "off": the operator has taken the web away from every consultation.
+    network: POLICY.network,
     max_concurrent_jobs: POLICY.maxConcurrent,
     max_wait_ms: POLICY.maxWaitMs,
     input_char_budget: POLICY.input.totalCharsMax,

package/src/redact.mjs

@@ -1,6 +1,19 @@
 // Credential scrubbing. Applied on the way out (brief sent to the consultant),
 // on the way in (consultant output), and to everything persisted to disk.
 
+const CODE_WORDS = new Set(['true', 'false', 'null', 'none', 'undefined', 'string', 'str', 'number', 'boolean', 'bool', 'int', 'bytes']);
+
+// A password-type value that is code, not a secret: a flag or a type, a
+// 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).
+function looksLikeCode(name, value) {
+  if (CODE_WORDS.has(value.toLowerCase()) || value.startsWith('${') || /^\$[A-Z_][A-Z0-9_]*$/.test(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;
+  return /^[A-Za-z_][\w$]*(?:\.[A-Za-z_$][\w$]*)+$/.test(value) || /^[A-Za-z_][\w$.]*\(/.test(value) || value.startsWith('&');
+}
+
 const PATTERNS = [
   // Provider API keys
   [/\bsk-ant-[A-Za-z0-9_\-]{12,}/g, '[REDACTED:anthropic-key]'],
@@ -9,6 +22,7 @@ const PATTERNS = [
   [/\bgh[pousr]_[A-Za-z0-9]{16,}/g, '[REDACTED:github-token]'],
   [/\bgithub_pat_[A-Za-z0-9_]{20,}/g, '[REDACTED:github-token]'],
   [/\bxox[baprs]-[A-Za-z0-9-]{10,}/g, '[REDACTED:slack-token]'],
+  [/https:\/\/hooks\.slack\.com\/services\/T[A-Za-z0-9]+\/B[A-Za-z0-9]+\/[A-Za-z0-9]+/g, '[REDACTED:slack-webhook]'],
   [/\bAKIA[0-9A-Z]{16}\b/g, '[REDACTED:aws-access-key-id]'],
   [/\bASIA[0-9A-Z]{16}\b/g, '[REDACTED:aws-access-key-id]'],
   [/\bAIza[0-9A-Za-z_\-]{30,}/g, '[REDACTED:google-api-key]'],
@@ -25,8 +39,13 @@ const PATTERNS = [
   // The password in a URL's userinfo, also with an empty user (redis://:pass@host)
   [/(:\/\/[^\s:/@]*:)[^\s@/]+(@)/g, '$1[REDACTED]$2'],
   // KEY=value / "token": "value" style assignments
-  [/\b((?:[A-Za-z0-9_]*_)?(?:API_KEY|APIKEY|ACCESS_KEY|PRIVATE_KEY|ACCESS_TOKEN|REFRESH_TOKEN|ID_TOKEN|SECRET_KEY|CLIENT_SECRET|AUTH_TOKEN|CREDENTIALS|PASSWORD|PASSWD|SECRET|TOKEN))(["']?\s*[:=]\s*["']?)([^\s"',;)]{8,})/gi,
+  [/\b((?:[A-Za-z0-9_]*_)?(?:API_KEY|APIKEY|ACCESS_KEY|PRIVATE_KEY|ACCESS_TOKEN|REFRESH_TOKEN|ID_TOKEN|SECRET_KEY|CLIENT_SECRET|AUTH_TOKEN|CREDENTIALS|ACCOUNTKEY|SHAREDACCESSKEY|SECRET|TOKEN))(["']?\s*[:=]\s*["']?)([^\s"',;)]{8,})/gi,
     (_m, k, sep, _v) => `${k}${sep}[REDACTED]`],
+  // Password-type names, with values from 4 characters; PASS and PWD too (PWD
+  // only after `_` or a letter: bare PWD is the working directory). What reads
+  // as code rather than a password is left alone (looksLikeCode).
+  [/\b((?:[A-Za-z0-9_]*_)?(?:PASSWORD|PASSWD|PASS|(?<=[A-Za-z_])PWD))(["']?\s*[:=]\s*["']?)([^\s"',;)]{4,})/gi,
+    (m, k, sep, v) => (looksLikeCode(k, v) ? m : `${k}${sep}[REDACTED]`)],
   // Any environment variable named *_KEY. Upper case only: in code, primary_key,
   // sort_key and idempotency_key name things, not secrets.
   [/\b([A-Z0-9_]+_KEY)(\s*=\s*["']?)([^\s"',;)]{8,})/g, (_m, k, sep, _v) => `${k}${sep}[REDACTED]`],

package/src/run.mjs

@@ -164,15 +164,21 @@ export class ProcHandle {
     this.stdoutSoFar = readStdout;
   }
 
-  /** Kill the child and every descendant it spawned. */
+  /**
+   * 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.
+   */
   stop(signal = 'SIGTERM') {
-    if (this.killed || !this.child || this.child.exitCode !== null) return;
+    if (this.killed || !this.child) return;
     this.killed = true;
     const pid = this.child.pid;
     if (!pid) return;
     if (process.platform === 'win32') {
       // Negative PIDs/process groups are POSIX-only. Kill the Windows tree
-      // before its parent exits and its descendants become unreachable.
+      // 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 */ } };
@@ -201,6 +207,12 @@ export class ProcHandle {
 /**
  * @returns {{handle: ProcHandle, done: Promise<{code, signal, stdout, stderr, timedOut, cancelled, truncated}>}}
  */
+/**
+ * `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.
+ */
 export function runChild({ command, args, cwd, env, input, timeoutMs, onCancelSignal, compactLine = null,
   settleAfter = null, stopSignal = 'SIGTERM' }) {
   const child = spawn(command, args, {
@@ -288,16 +300,37 @@ export function runChild({ command, args, cwd, env, input, timeoutMs, onCancelSi
 
   const done = new Promise((resolve) => {
     let settled = false;
+    let pipesForced = false;
+    let orphanTimer = null;
     const finish = (payload) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
       clearTimeout(settleTimer);
-      resolve({ stdout, stderr, truncated, timedOut, cancelled, stalled, ...payload });
+      clearTimeout(orphanTimer);
+      resolve({ stdout, stderr, truncated, timedOut, cancelled, stalled, pipesForced, ...payload });
     };
+    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
+    // after that the pipes are closed from here, whoever still holds them.
+    child.on('exit', (code, signal) => {
+      const grace = POLICY.killGraceMs;
+      orphanTimer = setTimeout(() => {
+        pipesForced = true;
+        handle.stop(stopSignal);
+        orphanTimer = setTimeout(() => {
+          handle.forceKill();
+          flushPending();
+          child.stdout.destroy();
+          child.stderr.destroy();
+          finish({ code, signal });
+        }, grace);
+      }, grace);
+    });
     child.on('close', (code, signal) => {
-      if (byLine && pending) { append('out', compact(pending)); pending = ''; }
+      flushPending();
       finish({ code, signal });
     });
   });

package/src/schema.mjs

@@ -6,7 +6,7 @@ import { z } from 'zod';
 import path from 'node:path';
 import {
   POLICY, CALLER_INPUTS, MODES, STANCES, artifactKinds,
-  resolveCaller, availableConsultants, consultantAvailable, unavailableReason,
+  resolveCaller, availableConsultants, consultantAvailable, unavailableReason, brokenConsultant,
 } from './policy.mjs';
 import { normalizeName, resolveConsultant } from './consultants.mjs';
 
@@ -42,10 +42,10 @@ const gitRevision = z.string().trim().min(1).max(200)
 
 export const contextSchema = z
   .object({
-    facts: z.array(trimmed(L.factMax, 'context.facts[]')).max(L.factsMax).default([]),
+    facts: z.array(trimmed(L.factMax, 'context.facts[]')).max(L.factsMax).optional(),
     proposal: z.string().trim().max(L.proposalMax).nullish(),
-    counterpoints: z.array(trimmed(L.counterpointMax, 'context.counterpoints[]')).max(L.counterpointsMax).default([]),
-    artifacts: z.array(artifactSchema).max(L.artifactsMax).default([]),
+    counterpoints: z.array(trimmed(L.counterpointMax, 'context.counterpoints[]')).max(L.counterpointsMax).optional(),
+    artifacts: z.array(artifactSchema).max(L.artifactsMax).optional(),
     expose_paths: z.array(exposedPathSchema).max(L.exposePathsMax).default([]),
     // The lead's uncommitted (or since-`base`) change: its diff goes in the
     // brief and the files it touches are copied, under workspace/repo/ at
@@ -55,6 +55,9 @@ export const contextSchema = z
     // round exposed. Never implied -- what reaches another vendor's model is
     // what the lead named in this call.
     expose_from_parent: z.boolean().optional(),
+    // Read as the request's own: a lead often nests them beside the facts.
+    constraints: z.array(trimmed(L.constraintMax, 'context.constraints[]')).max(L.constraintsMax).optional(),
+    success_criteria: z.array(trimmed(L.constraintMax, 'context.success_criteria[]')).max(L.constraintsMax).optional(),
   })
   .strict();
 
@@ -100,13 +103,13 @@ export const requestSchema = z
     // "off" takes web search and browsing away from every consultant in this
     // round, for a brief that must not leave the machine through a URL. The
     // consultant still reads the brief and the disk; it reaches nothing else.
-    network: z.enum(NETWORK_MODES).default('on'),
+    network: z.enum(NETWORK_MODES).optional(),
     question: trimmed(L.questionMax, 'question'),
     // Optional: most consultations state what they are after in the question
     // itself, and a second field that repeats it is friction, not information.
     objective: trimmed(L.objectiveMax, 'objective').nullish(),
-    success_criteria: z.array(trimmed(L.constraintMax, 'success_criteria[]')).max(L.constraintsMax).default([]),
-    constraints: z.array(trimmed(L.constraintMax, 'constraints[]')).max(L.constraintsMax).default([]),
+    success_criteria: z.array(trimmed(L.constraintMax, 'success_criteria[]')).max(L.constraintsMax).optional(),
+    constraints: z.array(trimmed(L.constraintMax, 'constraints[]')).max(L.constraintsMax).optional(),
     // prefault, not default: zod 4 returns a default as is, skipping the inner defaults (expose_paths among them).
     context: contextSchema.prefault({}),
     // Written by the lead before the consultant is launched, kept on this
@@ -147,15 +150,31 @@ export class RequestError extends Error {
 
 /**
  * Validate + normalise a consult request.
- * `isFollowup` is decided by the caller (the job store resolves followup_to first).
+ * `isFollowup` is decided by the caller (the job store resolves followup_to first);
+ * `groupFollowup` when followup_to named a fan-out, whose members are the targets.
  */
-export function parseRequest(raw, { isFollowup = false, parentMode = null } = {}) {
+export function parseRequest(raw, { isFollowup = false, parentMode = null, groupFollowup = false } = {}) {
   const parsed = requestSchema.safeParse(raw);
   if (!parsed.success) {
     const issues = parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`);
     throw new RequestError(`request failed validation: ${issues.join('; ')}`, 'invalid_request', issues);
   }
   const req = parsed.data;
+  // Left without a default in the schema, so that a follow-up can tell a list
+  // it left out (inherited from the round before, jobs.mjs) from one it
+  // emptied on purpose: the tool layer applies the schema's defaults first.
+  for (const k of ['constraints', 'success_criteria']) {
+    if (req.context[k] === undefined) continue;
+    if (req[k] !== undefined) {
+      throw new RequestError(`pass ${k} once: at the top of the request or inside context, not both`, 'invalid_request');
+    }
+    req[k] = req.context[k];
+    delete req.context[k];
+  }
+  req.network ??= 'on';
+  req.success_criteria ??= [];
+  req.constraints ??= [];
+  for (const k of ['facts', 'counterpoints', 'artifacts']) req.context[k] ??= [];
   const hasSingle = req.target !== undefined && req.target !== null;
   const hasMany = Array.isArray(req.targets) && req.targets.length > 0;
   if (hasSingle && hasMany) {
@@ -191,6 +210,9 @@ export function parseRequest(raw, { isFollowup = false, parentMode = null } = {}
     chosen = named.map((name) => {
       let r = resolveConsultant(name, reachable, POLICY.ranking);
       if (r.none) r = resolveConsultant(name, POLICY.consultants, POLICY.ranking);
+      if (r.none && brokenConsultant(name)) {
+        throw new RequestError(`consultant ${JSON.stringify(name)} is not available: ${brokenConsultant(name)}; available: ${listed()}`, 'target_unavailable');
+      }
       if (r.none) {
         throw new RequestError(`no consultant answers to ${JSON.stringify(name)}; available: ${listed()}`, 'unknown_target');
       }
@@ -220,9 +242,9 @@ export function parseRequest(raw, { isFollowup = false, parentMode = null } = {}
       'duplicate_targets',
     );
   }
-  if (isFollowup && unique.length > 1) {
+  if (isFollowup && !groupFollowup && unique.length > 1) {
     throw new RequestError(
-      'a follow-up continues the exchange with one consultant; name exactly one target',
+      'a follow-up to a job continues the exchange with one consultant; name exactly one target, or pass followup_to a group_id to ask every member of that fan-out again',
       'followup_fanout_not_allowed',
     );
   }
@@ -277,7 +299,8 @@ export function parseRequest(raw, { isFollowup = false, parentMode = null } = {}
   if (req.context.facts.length === 0 && req.context.artifacts.length === 0 && req.context.expose_paths.length === 0
     && !req.context.expose_diff && !req.context.expose_from_parent) {
     throw new RequestError(
-      'provide at least one entry in context.facts, context.artifacts or context.expose_paths: the consultant starts in an empty working directory and is not told where your repository is, so every fact it needs must be in the request',
+      'provide at least one entry in context.facts, context.artifacts or context.expose_paths: the consultant starts in an empty working directory and is not told where your repository is, so every fact it needs must be in the request'
+        + (isFollowup ? '; on a follow-up, context.expose_from_parent: true copies again the files the earlier round was shown' : ''),
       'context_required',
     );
   }