severally-mcp 2.1.0 → 2.4.0

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.
@@ -164,23 +161,48 @@ 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.
-      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 */ } };
+      // 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 */
+        }
+      };
       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();
   }
 
@@ -194,15 +216,35 @@ 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}>}}
  */
-export function runChild({ command, args, cwd, env, input, timeoutMs, onCancelSignal, compactLine = null,
-  settleAfter = null, stopSignal = 'SIGTERM' }) {
+/**
+ * `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, {
     cwd,
     // PWD is the parent's otherwise, and opencode takes its project root from
@@ -232,17 +274,26 @@ export function runChild({ command, args, cwd, env, input, timeoutMs, onCancelSi
     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 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;
     }
@@ -261,7 +312,10 @@ export function runChild({ command, args, cwd, env, input, timeoutMs, onCancelSi
       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.
@@ -288,22 +342,50 @@ 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 });
     });
   });
 
   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();

package/src/schema.mjs

@@ -5,8 +5,16 @@
 import { z } from 'zod';
 import path from 'node:path';
 import {
-  POLICY, CALLER_INPUTS, MODES, STANCES, artifactKinds,
-  resolveCaller, availableConsultants, consultantAvailable, unavailableReason,
+  POLICY,
+  CALLER_INPUTS,
+  MODES,
+  STANCES,
+  artifactKinds,
+  resolveCaller,
+  availableConsultants,
+  consultantAvailable,
+  unavailableReason,
+  brokenConsultant,
 } from './policy.mjs';
 import { normalizeName, resolveConsultant } from './consultants.mjs';
 
@@ -36,16 +44,20 @@ const exposedPathSchema = z
   .refine((p) => path.isAbsolute(p), { message: 'context.expose_paths[] must be an absolute path' });
 
 // A revision for `git diff`: a ref, a commit, or HEAD~n -- never an option.
-const gitRevision = z.string().trim().min(1).max(200)
+const gitRevision = z
+  .string()
+  .trim()
+  .min(1)
+  .max(200)
   .regex(/^[A-Za-z0-9._/~^@{}-]+$/, 'context.expose_diff.base must be a git revision (a branch, tag, commit or HEAD~n)')
   .refine((r) => !r.startsWith('-'), { message: 'context.expose_diff.base must not start with "-"' });
 
 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 +67,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();
 
@@ -62,7 +77,11 @@ export const contextSchema = z
 // for it, its CLI, its vendor, or its model ("glm", "claude opus"). Which
 // consultant that is depends on the operator's config, so it is resolved in
 // parseRequest, not by an enum here.
-const targetSpec = z.string().trim().min(1, 'target must not be empty').max(120, 'target exceeds 120 characters')
+const targetSpec = z
+  .string()
+  .trim()
+  .min(1, 'target must not be empty')
+  .max(120, 'target exceeds 120 characters')
   .regex(/^[^\p{Cc}\p{Cf}]+$/u, 'target must be a single line of printable characters');
 
 // Who asked for a consultation, as the lead reports it.
@@ -100,13 +119,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
@@ -156,14 +175,33 @@ export function parseRequest(raw, { isFollowup = false, parentMode = null, group
     const issues = parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`);
     throw new RequestError(`request failed validation: ${issues.join('; ')}`, 'invalid_request', issues);
   }
+  // Filled in below with what the request resolves to (targets, caller, ...).
+  /** @type {Record<string, any>} */
   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) {
     throw new RequestError('pass either target (one consultant) or targets (several), not both', 'invalid_request');
   }
-  const listed = () => availableConsultants().map((c) => `${c.name} (${c.cli}, ${c.model})`).join(', ')
-    || 'none -- no consultant CLI is available here';
+  const listed = () =>
+    availableConsultants()
+      .map((c) => `${c.name} (${c.cli}, ${c.model})`)
+      .join(', ') || 'none -- no consultant CLI is available here';
   if (!hasSingle && !hasMany) {
     throw new RequestError(
       `name the consultant: target: a consultant, its CLI or its model (available: ${listed()}), or targets: [...] to ask several the same question, targets: ["all"] to ask everyone`,
@@ -180,7 +218,10 @@ export function parseRequest(raw, { isFollowup = false, parentMode = null, group
   if (isAll[0]) {
     chosen = availableConsultants();
     if (!chosen.length) {
-      throw new RequestError('no consultant is available on this machine -- install one of the CLIs, or check the config file', 'target_unavailable');
+      throw new RequestError(
+        'no consultant is available on this machine -- install one of the CLIs, or check the config file',
+        'target_unavailable',
+      );
     }
   } else {
     // Resolved among the reachable consultants first, so one that is off does
@@ -192,13 +233,19 @@ export function parseRequest(raw, { isFollowup = false, parentMode = null, group
     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');
       }
       if (r.ambiguous) {
         throw new RequestError(
-          `${JSON.stringify(name)} fits more than one consultant and no ranking rule decides between `
-          + `${r.ambiguous.map((c) => `${c.name} (${c.cli}, ${c.model})`).join(', ')}; name one of them`,
+          `${JSON.stringify(name)} fits more than one consultant and no ranking rule decides between ` +
+            `${r.ambiguous.map((c) => `${c.name} (${c.cli}, ${c.model})`).join(', ')}; name one of them`,
           'target_ambiguous',
         );
       }
@@ -207,8 +254,8 @@ export function parseRequest(raw, { isFollowup = false, parentMode = null, group
     const off = [...new Set(chosen.filter((c) => !consultantAvailable(c)))];
     if (off.length) {
       throw new RequestError(
-        `consultant ${off.map((c) => `${JSON.stringify(c.name)} (${unavailableReason(c)})`).join(', ')} `
-        + `is not available on this machine; available: ${listed()}`,
+        `consultant ${off.map((c) => `${JSON.stringify(c.name)} (${unavailableReason(c)})`).join(', ')} ` +
+          `is not available on this machine; available: ${listed()}`,
         'target_unavailable',
       );
     }
@@ -240,8 +287,7 @@ export function parseRequest(raw, { isFollowup = false, parentMode = null, group
   // one its context fits -- no proposal is explore, a proposal is review, a
   // proposal with the other side's claims is debate. Checked below like a
   // mode that was given.
-  req.mode ??= parentMode
-    ?? (!req.context.proposal ? 'explore' : req.context.counterpoints.length ? 'debate' : 'review');
+  req.mode ??= parentMode ?? (!req.context.proposal ? 'explore' : req.context.counterpoints.length ? 'debate' : 'review');
 
   const total = charCount(req);
   if (total > L.totalCharsMax) {
@@ -275,10 +321,18 @@ export function parseRequest(raw, { isFollowup = false, parentMode = null, group
       'expose_from_parent_needs_followup',
     );
   }
-  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) {
+  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',
     );
   }