severally-mcp 2.3.1 → 2.4.2

package/src/schema.mjs

@@ -5,12 +5,27 @@
 import { z } from 'zod';
 import path from 'node:path';
 import {
-  POLICY, CALLER_INPUTS, MODES, STANCES, artifactKinds,
-  resolveCaller, availableConsultants, consultantAvailable, unavailableReason, brokenConsultant,
+  POLICY,
+  CALLER_INPUTS,
+  MODES,
+  STANCES,
+  artifactKinds,
+  resolveCaller,
+  availableConsultants,
+  consultantAvailable,
+  unavailableReason,
+  brokenConsultant,
 } from './policy.mjs';
 import { normalizeName, resolveConsultant } from './consultants.mjs';
 
+/** @typedef {import('./consultants.mjs').Consultant} Consultant */
+/** @typedef {import('./consultants.mjs').CliId} CliId */
+
 const L = POLICY.input;
+/**
+ * @param {number} max
+ * @param {string} label
+ */
 const trimmed = (max, label) =>
   z.string().trim().min(1, `${label} must not be empty`).max(max, `${label} exceeds ${max} characters`);
 
@@ -36,7 +51,11 @@ 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 "-"' });
 
@@ -65,7 +84,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.
@@ -128,10 +151,59 @@ export const requestSchema = z
   })
   .strict();
 
+/**
+ * What charCount reads of a request, once parseRequest has filled in its defaults.
+ * @typedef {{
+ *   question: string,
+ *   objective?: string | null | undefined,
+ *   constraints?: string[] | undefined,
+ *   success_criteria?: string[] | undefined,
+ *   context: { facts: string[], counterpoints: string[], proposal?: string | null | undefined, artifacts: { name: string, excerpt: string }[] },
+ * }} CountedRequest
+ */
+
+/** @typedef {'explore' | 'review' | 'debate'} Mode */
+/** @typedef {z.output<typeof requestSchema>} ValidRequest */
+/** @typedef {z.output<typeof contextSchema>} ValidContext */
+
+/**
+ * A request as parseRequest returns it: validated, defaults filled in, the
+ * consultant(s) resolved. `target` is the first of `targets`.
+ * @typedef {Omit<
+ *   ValidRequest,
+ *   'target' | 'targets' | 'caller' | 'caller_model' | 'initiator' | 'followup_to' | 'mode' | 'network' | 'success_criteria' | 'constraints' | 'context'
+ * > & {
+ *   target: string,
+ *   targets: string[],
+ *   fanout: boolean,
+ *   caller: CliId | null,
+ *   caller_model: string | null,
+ *   initiator: string | null,
+ *   followup_to: string | null,
+ *   mode: Mode,
+ *   network: 'on' | 'off',
+ *   success_criteria: string[],
+ *   constraints: string[],
+ *   context: Omit<ValidContext, 'constraints' | 'success_criteria' | 'facts' | 'counterpoints' | 'artifacts' | 'proposal'> & {
+ *     facts: string[],
+ *     counterpoints: string[],
+ *     artifacts: ValidContext['artifacts'] & {},
+ *     proposal: string | null,
+ *   },
+ * }} ParsedRequest
+ */
+
+/**
+ * parseRequest's working copy: the request as it is until the defaults are filled in.
+ * `constraints` and `success_criteria` may still sit inside the context at first.
+ * @typedef {ParsedRequest & { context: { constraints?: string[] | undefined, success_criteria?: string[] | undefined } }} DraftRequest
+ */
+
+/** @param {CountedRequest} req */
 export function charCount(req) {
   let n = req.question.length + (req.objective?.length ?? 0);
-  for (const c of req.constraints) n += c.length;
-  for (const c of req.success_criteria) n += c.length;
+  for (const c of req.constraints ?? []) n += c.length;
+  for (const c of req.success_criteria ?? []) n += c.length;
   for (const f of req.context.facts) n += f.length;
   for (const c of req.context.counterpoints) n += c.length;
   if (req.context.proposal) n += req.context.proposal.length;
@@ -140,6 +212,11 @@ export function charCount(req) {
 }
 
 export class RequestError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} [code]
+   * @param {unknown[]} [details]
+   */
   constructor(message, code = 'invalid_request', details = undefined) {
     super(message);
     this.name = 'RequestError';
@@ -152,6 +229,9 @@ export class RequestError extends Error {
  * Validate + normalise a consult request.
  * `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.
+ * @param {unknown} raw
+ * @param {{ isFollowup?: boolean, parentMode?: Mode | null, groupFollowup?: boolean }} [options]
+ * @returns {ParsedRequest}
  */
 export function parseRequest(raw, { isFollowup = false, parentMode = null, groupFollowup = false } = {}) {
   const parsed = requestSchema.safeParse(raw);
@@ -159,46 +239,62 @@ 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);
   }
-  const req = parsed.data;
+  // Filled in below with what the request resolves to (targets, caller, ...), so
+  // until it returns it is only partly a ParsedRequest: the validated data is
+  // typed as the finished shape and every field the shape adds is set before the return.
+  const req = /** @type {DraftRequest} */ (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;
+  /** @param {'constraints' | 'success_criteria'} k */
+  const hoist = (k) => {
+    const inner = req.context[k];
+    if (inner === undefined) return;
     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];
+    req[k] = inner;
     delete req.context[k];
-  }
+  };
+  hoist('constraints');
+  hoist('success_criteria');
   req.network ??= 'on';
   req.success_criteria ??= [];
   req.constraints ??= [];
-  for (const k of ['facts', 'counterpoints', 'artifacts']) req.context[k] ??= [];
+  req.context.facts ??= [];
+  req.context.counterpoints ??= [];
+  req.context.artifacts ??= [];
   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`,
       'target_required',
     );
   }
+  /** @type {string[]} */
   const named = hasSingle ? [req.target] : req.targets;
   const isAll = named.map((n) => normalizeName(n) === 'all');
   if (isAll.some(Boolean) && named.length > 1) {
     throw new RequestError('"all" already means every available consultant; pass it alone', 'all_mixed');
   }
 
+  /** @type {Consultant[]} */
   let chosen;
   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
@@ -211,15 +307,18 @@ export function parseRequest(raw, { isFollowup = false, parentMode = null, group
       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');
+        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',
         );
       }
@@ -228,8 +327,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',
       );
     }
@@ -249,7 +348,7 @@ export function parseRequest(raw, { isFollowup = false, parentMode = null, group
     );
   }
   req.targets = unique;
-  req.target = unique[0]; // single-target consumers (brief, history, adapters) keep working
+  req.target = /** @type {string} */ (unique[0]); // non-empty: every name in `named` resolved to a consultant; single-target consumers (brief, history, adapters) keep working
   req.fanout = unique.length > 1;
   req.caller = resolveCaller(req.caller ?? '') ?? null;
   req.caller_model = req.caller_model ?? null;
@@ -261,8 +360,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) {
@@ -296,11 +394,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'
-        + (isFollowup ? '; on a follow-up, context.expose_from_parent: true copies again the files the earlier round was shown' : ''),
+      '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',
     );
   }