severally-mcp 2.3.1 → 2.4.2

package/src/brief.mjs

@@ -7,6 +7,52 @@ import { CONSULT_RESULT_SCHEMA } from './result-schema.mjs';
 import { redact } from './redact.mjs';
 import { humanSize } from './expose-paths.mjs';
 
+/**
+ * @typedef {object} BriefArtifact
+ * @property {string} name
+ * @property {string} kind
+ * @property {string | undefined} [language]
+ * @property {string | undefined} [source]
+ * @property {string} excerpt
+ */
+
+/**
+ * The validated request, as far as the brief reads it.
+ * @typedef {object} BriefRequest
+ * @property {string} question
+ * @property {string | null | undefined} [objective]
+ * @property {string[]} [success_criteria]
+ * @property {string[]} [constraints]
+ * @property {'explore' | 'review' | 'debate'} mode
+ * @property {'on' | 'off'} [network]
+ * @property {{ facts?: string[], proposal?: string | null, counterpoints?: string[], artifacts: BriefArtifact[] }} context
+ */
+
+/** @typedef {import('./expose-paths.mjs').ExposeManifest} ExposeManifest */
+
+/**
+ * A finding, unknown or check from an earlier round, with the lead's verdict on it.
+ * @typedef {object} PriorPoint
+ * @property {string} id
+ * @property {string} point
+ * @property {string | null} [grounds]
+ * @property {string | null} [verdict]
+ * @property {string | null} [effect]
+ */
+
+/**
+ * @typedef {object} PriorRound
+ * @property {number} round
+ * @property {string} mode
+ * @property {string} question
+ * @property {string} summary
+ * @property {PriorPoint[]} [findings]
+ * @property {PriorPoint[]} [unknowns]
+ * @property {PriorPoint[]} [next_checks]
+ */
+
+/** @typedef {{ round: number, priorRounds: PriorRound[] }} BriefChain */
+
 const MODE_BRIEFS = {
   explore: [
     'MODE: explore.',
@@ -38,22 +84,23 @@ const GUARDRAILS_HEAD = [
 
 // After the web bullet.
 const GUARDRAILS_RULES = [
-  '- When the question concerns security, it is a defensive review of the lead\'s own code or system: analyse the weaknesses and how to fix them.',
-  '- The Constraints section is fixed. Design notes, drafts and internal documents among the facts and artifacts are the lead\'s current direction, not a specification, and you may question them.',
+  "- When the question concerns security, it is a defensive review of the lead's own code or system: analyse the weaknesses and how to fix them.",
+  "- The Constraints section is fixed. Design notes, drafts and internal documents among the facts and artifacts are the lead's current direction, not a specification, and you may question them.",
 ];
 
 // The web bullet follows the request: with the network off the consultant has
 // no web tools, and telling it otherwise would have it look for them.
 const WEB_ON = '- You may search and browse the web freely; cite what you actually opened in `references`.';
-const WEB_OFF = '- Web search and browsing are switched off for this consultation. Answer from the brief, and record what you would have looked up under `unknowns`.';
+const WEB_OFF =
+  '- Web search and browsing are switched off for this consultation. Answer from the brief, and record what you would have looked up under `unknowns`.';
 
 // The one bullet that depends on the request: a consultation that exposed
 // paths has files, and telling it otherwise would have it record everything
 // it can plainly read under `unknowns`.
 const WORKDIR_EMPTY =
-  '- You are running in an empty working directory and do not have the lead\'s repository; everything you are meant to have is in the brief below. If something is missing, record it under `unknowns` instead of guessing or substituting an assumption.';
+  "- You are running in an empty working directory and do not have the lead's repository; everything you are meant to have is in the brief below. If something is missing, record it under `unknowns` instead of guessing or substituting an assumption.";
 const WORKDIR_EXPOSED =
-  '- Your working directory is not empty: the lead exposed specific paths, listed under "Files available to you" below and copied read-only under ./workspace. Those are the only part of the lead\'s repository you have. If something you need is missing, record it under `unknowns` instead of guessing or substituting an assumption.';
+  '- Your working directory is not empty: the lead exposed specific paths, listed under "Files available to you" below and copied read-only under ./workspace. Those are the only part of the lead\'s repository the lead gave you. If something you need is missing, record it under `unknowns` instead of guessing or substituting an assumption.';
 
 const GUARDRAILS_TAIL = [
   '- Never include credentials, API keys, tokens, or environment variable values in your answer.',
@@ -69,9 +116,18 @@ const GUARDRAILS_TAIL = [
   'Output contract: reply with exactly one JSON object matching the provided schema. No prose, no markdown fences, no commentary before or after it. Empty arrays are fine; invented content is not.',
 ];
 
+/**
+ * @param {boolean} [hasExposedPaths]
+ * @param {'on' | 'off'} [network]
+ */
 export function renderGuardrails(hasExposedPaths = false, network = 'on') {
-  return [...GUARDRAILS_HEAD, network === 'off' ? WEB_OFF : WEB_ON, ...GUARDRAILS_RULES,
-    hasExposedPaths ? WORKDIR_EXPOSED : WORKDIR_EMPTY, ...GUARDRAILS_TAIL].join('\n');
+  return [
+    ...GUARDRAILS_HEAD,
+    network === 'off' ? WEB_OFF : WEB_ON,
+    ...GUARDRAILS_RULES,
+    hasExposedPaths ? WORKDIR_EXPOSED : WORKDIR_EMPTY,
+    ...GUARDRAILS_TAIL,
+  ].join('\n');
 }
 
 // The material the lead handed over, kept in the shape it was sent in. The
@@ -79,6 +135,10 @@ export function renderGuardrails(hasExposedPaths = false, network = 'on') {
 // history holds an answer whose premises are gone -- and a finding read a month
 // later is only as good as the facts it was answering. Redacted the same way
 // renderBrief redacts the text itself, so the stored copy is what was sent.
+/**
+ * @param {BriefRequest} req
+ * @param {ExposeManifest | null} [exposeManifest]
+ */
 export function briefRecord(req, exposeManifest = null) {
   return redact({
     objective: req.objective ?? null,
@@ -100,36 +160,42 @@ export function briefRecord(req, exposeManifest = null) {
     // frozen duplicate of a repository that has moved on since.
     expose_paths: exposeManifest
       ? {
-        entries: exposeManifest.entries.map((e) => ({
-          index: e.index,
-          source: e.source,
-          exposed_as: e.exposedAs,
-          kind: e.kind,
-          files: e.files,
-          bytes: e.bytes,
-          // What every member was handed, so a reader can check they all got the same.
-          sha256: e.sha256 ?? null,
-          ...(e.base ? { base: e.base, changes: e.changes } : {}),
-          // A follow-up's copy of a path the parent round exposed: whether its bytes changed since.
-          ...(e.changed === undefined ? {} : { changed_since_parent: e.changed }),
-        })),
-        totals: exposeManifest.totals,
-        skipped: exposeManifest.skipped,
-      }
+          entries: exposeManifest.entries.map((e) => ({
+            index: e.index,
+            source: e.source,
+            exposed_as: e.exposedAs,
+            kind: e.kind,
+            files: e.files,
+            bytes: e.bytes,
+            // What every member was handed, so a reader can check they all got the same.
+            sha256: e.sha256 ?? null,
+            ...(e.base ? { base: e.base, changes: e.changes } : {}),
+            // A follow-up's copy of a path the parent round exposed: whether its bytes changed since.
+            ...(e.changed === undefined ? {} : { changed_since_parent: e.changed }),
+          })),
+          totals: exposeManifest.totals,
+          skipped: exposeManifest.skipped,
+        }
       : null,
   });
 }
 
+/**
+ * @param {string} title
+ * @param {string | null | undefined} body
+ */
 function section(title, body) {
   if (!body) return null;
   return `## ${title}\n${body}`;
 }
 
+/** @param {string[] | null | undefined} items */
 function bullets(items) {
   if (!items || items.length === 0) return null;
   return items.map((i) => `- ${i}`).join('\n');
 }
 
+/** @param {BriefArtifact[]} artifacts */
 function renderArtifacts(artifacts) {
   if (!artifacts.length) return null;
   return artifacts
@@ -147,25 +213,30 @@ function renderArtifacts(artifacts) {
 const EXPOSE_LISTING_MAX = 200;
 
 // Deleted files have no copy to open; the brief says which they were.
+/** @param {string[]} [changes] */
 function deletedLines(changes = []) {
   const gone = changes.filter((c) => c.endsWith(' (deleted)')).map((c) => c.slice(0, -' (deleted)'.length));
   if (!gone.length) return [];
   const shown = gone.slice(0, 50);
-  return [`  - deleted by the change, so not copied: ${shown.join(', ')}${gone.length > shown.length ? `, and ${gone.length - shown.length} more` : ''}`];
+  return [
+    `  - deleted by the change, so not copied: ${shown.join(', ')}${gone.length > shown.length ? `, and ${gone.length - shown.length} more` : ''}`,
+  ];
 }
 
+/** @param {ExposeManifest | null} manifest */
 function renderExposeManifest(manifest) {
   if (!manifest || (manifest.entries.length === 0 && manifest.skipped.length === 0)) return null;
   let room = EXPOSE_LISTING_MAX;
   const lines = manifest.entries.flatMap((e) => {
-    const shape = (e.kind === 'diff'
-      ? `the files the lead's change touches, against ${e.base}, at their paths in the repository; ${e.files} copied, ${humanSize(e.bytes)}; the diff itself is among the artifacts`
-      : e.kind === 'change_files'
-        ? `the files the lead's change touched in the earlier round, at their paths in the repository, copied again as they are now; ${e.files} copied, ${humanSize(e.bytes)}; the diff is not repeated`
-        : e.kind === 'directory'
-          ? `directory, ${e.files} file(s), ${humanSize(e.bytes)}`
-          : `file, ${humanSize(e.bytes)}`)
-      + (e.changed === undefined ? '' : e.changed ? '; changed since the earlier round' : '; unchanged since the earlier round');
+    const shape =
+      (e.kind === 'diff'
+        ? `the files the lead's change touches, against ${e.base}, at their paths in the repository; ${e.files} copied, ${humanSize(e.bytes)}; the diff itself is among the artifacts`
+        : e.kind === 'change_files'
+          ? `the files the lead's change touched in the earlier round, at their paths in the repository, copied again as they are now; ${e.files} copied, ${humanSize(e.bytes)}; the diff is not repeated`
+          : e.kind === 'directory'
+            ? `directory, ${e.files} file(s), ${humanSize(e.bytes)}`
+            : `file, ${humanSize(e.bytes)}`) +
+      (e.changed === undefined ? '' : e.changed ? '; changed since the earlier round' : '; unchanged since the earlier round');
     // Not where it was copied from: the consultant is never told where the
     // lead's repository is, and Codex, Antigravity and OpenCode could read
     // the unmasked original there. The source path stays in the history.
@@ -179,13 +250,24 @@ function renderExposeManifest(manifest) {
       ...(e.kind === 'diff' || e.kind === 'change_files' ? deletedLines(e.changes) : []),
     ];
   });
+  /** @param {string} reason */
   const count = (reason) => manifest.skipped.filter((x) => x.reason === reason).length;
-  const named = (reason) => manifest.skipped.filter((x) => x.reason === reason).map((x) => x.exposed_as).slice(0, 50).join(', ');
+  /** @param {string} reason */
+  const named = (reason) =>
+    manifest.skipped
+      .filter((x) => x.reason === reason)
+      .map((x) => x.exposed_as)
+      .slice(0, 50)
+      .join(', ');
   const skipped = [
     count('symlink') ? `${count('symlink')} symlink(s), or path(s) through one, were skipped, not followed.` : null,
     count('protected') ? `${count('protected')} credential or history path(s) were left out on purpose.` : null,
-    count('ignored') ? `${count('ignored')} path(s) (.git, node_modules, whatever .gitignore excludes) were left out as not source.` : null,
-    count('submodule') ? `${count('submodule')} submodule(s) or nested repositor(ies) were left out; their files are not copied.` : null,
+    count('ignored')
+      ? `${count('ignored')} path(s) (.git, node_modules, whatever .gitignore excludes) were left out as not source.`
+      : null,
+    count('submodule')
+      ? `${count('submodule')} submodule(s) or nested repositor(ies) were left out; their files are not copied.`
+      : null,
     count('gone') ? `No longer there, so not copied again: ${named('gone')}.` : null,
     count('masked') ? `Not copied again, because the record of the earlier round masked the path: ${named('masked')}.` : null,
     count('replaced') ? `The earlier round's change is replaced by the diff given in this round: ${named('replaced')}.` : null,
@@ -193,7 +275,7 @@ function renderExposeManifest(manifest) {
   if (skipped.length) skipped.unshift('');
   return [
     'The lead exposed these paths; they are copied under ./workspace in your working directory and you may read',
-    'them directly. They are the only part of the lead\'s repository you have -- if you need something that is',
+    "them directly. They are the only part of the lead's repository the lead gave you -- if you need something that is",
     'not here, record it under `unknowns` rather than guessing. Text files were passed through the same',
     'credential masking as this brief; binary files were copied unchanged.',
     '',
@@ -204,32 +286,49 @@ function renderExposeManifest(manifest) {
 
 // An earlier round's point, cut to a length that keeps a five-round chain
 // from crowding out the question it is there to inform.
+/**
+ * @param {string} s
+ * @param {number} [max]
+ */
 const clip = (s, max = 400) => (s.length > max ? `${s.slice(0, max)}...` : s);
 
 // The earlier rounds have a budget of their own, beside the request's cap:
 // when they outgrow it, the oldest rounds are left out, and the brief says so.
 const HISTORY_CHARS = 40_000;
 
+/** @param {PriorRound} p */
 function renderRound(p) {
   // Prefixed with the round, so a point from round 1 is not taken for this one's.
+  /** @param {string} id */
   const tag = (id) => `r${p.round}.${id}`;
+  /** @param {PriorPoint} x */
   const verdict = (x) => (x.verdict ? ` -- lead's verdict: ${x.verdict}${x.effect ? ` (${clip(x.effect)})` : ''}` : '');
+  /**
+   * @param {string} title
+   * @param {PriorPoint[] | undefined} items
+   * @param {(x: PriorPoint) => string} line
+   */
   const list = (title, items, line) => (items?.length ? [title, ...items.map(line)].join('\n') : null);
   return [
     `### Round ${p.round} (${p.mode})`,
     `Question asked: ${p.question}`,
     `Your answer, summarised: ${p.summary}`,
-    list('Points you raised:', p.findings,
-      (f) => `- ${tag(f.id)}: ${clip(f.point)}${verdict(f)}${f.grounds ? `\n  grounds: ${clip(f.grounds)}` : ''}`),
+    list(
+      'Points you raised:',
+      p.findings,
+      (f) => `- ${tag(f.id)}: ${clip(f.point)}${verdict(f)}${f.grounds ? `\n  grounds: ${clip(f.grounds)}` : ''}`,
+    ),
     list('Unknowns you named:', p.unknowns, (u) => `- ${tag(u.id)}: ${clip(u.point)}${verdict(u)}`),
     list('Checks you proposed:', p.next_checks, (c) => `- ${tag(c.id)}: ${clip(c.point)}${verdict(c)}`),
-  ].filter(Boolean).join('\n');
+  ]
+    .filter(Boolean)
+    .join('\n');
 }
 
 /**
- * @param {object} req validated request
- * @param {object} chain { round, priorRounds: [{question, mode, summary, findings: [{id, point, grounds, verdict, effect}],
- *   unknowns: [{id, point, verdict, effect}], next_checks: [{id, point, verdict, effect}]}] }
+ * @param {BriefRequest} req validated request
+ * @param {BriefChain} [chain] the round number and the earlier rounds of the chain
+ * @param {ExposeManifest | null} [exposeManifest]
  */
 export function renderBrief(req, chain = { round: 1, priorRounds: [] }, exposeManifest = null) {
   const parts = [];
@@ -262,19 +361,21 @@ export function renderBrief(req, chain = { round: 1, priorRounds: [] }, exposeMa
     parts.push('');
     parts.push('## Earlier rounds of this same consultation');
     parts.push(
-      'Each point carries the lead\'s own check where there is one -- confirmed: it held; not_applicable: checked, and'
-      + ' it does not apply here; unverifiable: could not be checked; unverified, or no verdict: not checked yet.',
+      "Each point carries the lead's own check where there is one -- confirmed: it held; not_applicable: checked, and" +
+        ' it does not apply here; unverifiable: could not be checked; unverified, or no verdict: not checked yet.',
     );
     const blocks = chain.priorRounds.map(renderRound);
     let kept = 0;
     let used = 0;
     // Newest first: the round being followed up always goes in.
-    for (let i = blocks.length - 1; i >= 0 && (kept === 0 || used + blocks[i].length <= HISTORY_CHARS); i--) {
-      used += blocks[i].length;
+    for (const block of [...blocks].reverse()) {
+      if (kept > 0 && used + block.length > HISTORY_CHARS) break;
+      used += block.length;
       kept += 1;
     }
     const left = chain.priorRounds.slice(0, blocks.length - kept).map((p) => p.round);
-    if (left.length) parts.push(`(Round${left.length > 1 ? 's' : ''} ${left.join(', ')} left out to keep this brief within its size.)`);
+    if (left.length)
+      parts.push(`(Round${left.length > 1 ? 's' : ''} ${left.join(', ')} left out to keep this brief within its size.)`);
     parts.push(...blocks.slice(blocks.length - kept));
     parts.push('');
     parts.push(