severally-mcp 2.4.0 → 2.5.0

package/src/status.mjs

@@ -37,9 +37,18 @@ const CLIENTS = [
   { label: 'OpenCode', cmd: 'opencode', checks: [['mcp', 'list']] },
 ];
 
+/**
+ * A field of whatever was thrown, or undefined when it carries none.
+ * @param {unknown} e
+ * @param {string} key
+ * @returns {unknown}
+ */
+const thrown = (e, key) => (typeof e === 'object' && e !== null ? Reflect.get(e, key) : undefined);
+
 // "registered": the client's own listing names severally (it may still be
 // turned off there). "not registered": the client answered, without it.
 // No answer at all (a timeout, a failure to start): unknown.
+/** @param {{ cmd: string, checks: string[][] }} client */
 function registration({ cmd, checks }) {
   if (!findCommand(cmd)) return 'not installed';
   let ran = false;
@@ -51,7 +60,7 @@ function registration({ cmd, checks }) {
     } catch (err) {
       // It ran and said no (`mcp get` of a missing server exits non-zero); a
       // timeout or a failure to start says nothing either way.
-      if (typeof err.status === 'number') ran = true;
+      if (typeof thrown(err, 'status') === 'number') ran = true;
     }
   }
   return ran ? 'not registered' : `could not tell (${cmd} ${checks.map((a) => a.join(' ')).join(' / ')} failed)`;
@@ -60,6 +69,7 @@ function registration({ cmd, checks }) {
 // Each CLI's own word on its login, read without sending a prompt. Only the
 // verdict is kept: `claude auth status` also prints the account's email.
 // Antigravity has no such command, so it is not checked.
+/** @type {Record<string, { cmd: string, args: string[], read: (out: string, ok: boolean) => boolean | string }>} */
 const LOGIN = {
   'claude-code': { cmd: 'claude', args: ['auth', 'status', '--json'], read: (out) => JSON.parse(out).loggedIn === true },
   // Codex prints its answer on stderr; the exit status carries the verdict.
@@ -76,17 +86,19 @@ const LOGIN = {
   },
 };
 
+/** @param {string} cli */
 function login(cli) {
   const check = LOGIN[cli];
   if (!check) return 'not checked (no login status command)';
   if (!findCommand(check.cmd)) return 'not installed';
+  /** @type {string} */
   let out;
   let ok = true;
   try {
     out = execCommandSync(check.cmd, check.args, { encoding: 'utf8', timeout: 20_000, stdio: ['ignore', 'pipe', 'pipe'] });
-  } catch (err) {
-    if (typeof err.status !== 'number') return `could not tell (${check.cmd} ${check.args.join(' ')} failed)`;
-    out = `${err.stdout ?? ''}`;
+  } catch (e) {
+    if (typeof thrown(e, 'status') !== 'number') return `could not tell (${check.cmd} ${check.args.join(' ')} failed)`;
+    out = `${thrown(e, 'stdout') ?? ''}`;
     ok = false;
   }
   try {

package/src/store.mjs

@@ -7,6 +7,204 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { POLICY } from './policy.mjs';
 
+/**
+ * @typedef {object} JobFailure
+ * @property {string} kind
+ * @property {string} message
+ * @property {string | null} detail
+ * @property {boolean} retriable
+ * @property {boolean} delivered_advice
+ */
+
+/**
+ * What the lead wrote about one point of an answer.
+ * @typedef {object} RecordEntry
+ * @property {string} id
+ * @property {string} verdict
+ * @property {string | null} effect
+ * @property {string | null} note
+ * @property {string} recorded_at
+ */
+
+/**
+ * The lead's verdicts on a round. The counts are present in a view
+ * (recordSummary), not in what the history keeps.
+ * @typedef {object} JobRecord
+ * @property {string} updated_at
+ * @property {RecordEntry[]} entries
+ * @property {Record<string, number> | undefined} [verdicts]
+ * @property {{recordable: number, recorded: number} | undefined} [coverage]
+ * @property {string[] | undefined} [unrecorded]
+ */
+
+/**
+ * What the answer added over what the lead expected, in the lead's words.
+ * @typedef {object} Reflection
+ * @property {string} delta
+ * @property {string[]} related_item_ids
+ * @property {string} recorded_at
+ */
+
+/**
+ * Written before the consultant is launched and never sent to it.
+ * @typedef {object} Prediction
+ * @property {string} expected
+ * @property {string} worry
+ * @property {string} recorded_at
+ */
+
+/** @typedef {import('./parse-result.mjs').ConsultResult} ConsultResult A consultant's normalized answer (see normalizeResult). */
+/** @typedef {import('./parse-result.mjs').Finding | import('./parse-result.mjs').Unknown | import('./parse-result.mjs').NextCheck} ResultItem One finding, unknown or next check of an answer. */
+/** @typedef {import('./schema.mjs').Mode} Mode */
+/** @typedef {import('./run.mjs').Boundary} Boundary What the consultant could and could not do, as its launch set it. */
+/** @typedef {import('./run.mjs').UsageRecord} UsageRecord */
+
+/**
+ * What the server derived from a normalized answer and the checks around it.
+ * @typedef {object} Quality
+ * @property {string[]} missing_sections
+ * @property {number} findings_without_grounds
+ * @property {boolean} unsourced
+ * @property {Record<string, number> | undefined} [list_truncated]
+ * @property {import('./parse-result.mjs').EvidenceBasis | null | undefined} [evidence_basis]
+ * @property {string | null | undefined} [caveat]
+ */
+
+/**
+ * The material the lead handed over, as the round keeps it (see briefRecord).
+ * @typedef {object} BriefRecord
+ * @property {string | null} objective
+ * @property {string[]} success_criteria
+ * @property {string[]} constraints
+ * @property {string[]} facts
+ * @property {string | null} proposal
+ * @property {string[]} counterpoints
+ * @property {Array<{name: string, kind: string, language: string | null, source: string | null, excerpt: string}>} artifacts
+ * @property {{entries: BriefExposeEntry[], totals: import('./expose-paths.mjs').ExposeTotals, skipped: import('./expose-paths.mjs').SkippedPath[]} | null} expose_paths
+ */
+
+/**
+ * @typedef {object} BriefExposeEntry
+ * @property {number} index
+ * @property {string} source
+ * @property {string} exposed_as
+ * @property {string} kind
+ * @property {number} files
+ * @property {number} bytes
+ * @property {string | null} sha256
+ * @property {string | undefined} [base]
+ * @property {string[] | undefined} [changes]
+ * @property {boolean | undefined} [changed_since_parent]
+ */
+
+/**
+ * The tail of what a timed-out consultant had written (raw, unparsed).
+ * @typedef {object} PartialOutput
+ * @property {true} partial
+ * @property {number} chars_total
+ * @property {boolean} capture_truncated
+ * @property {string} tail
+ * @property {string} stopped_at
+ * @property {string} note
+ */
+
+/**
+ * One earlier attempt of a consultation that was run again.
+ * @typedef {object} RetryRecord
+ * @property {string} failure_kind
+ * @property {string} reason
+ * @property {string} at
+ * @property {UsageRecord | null} usage
+ */
+
+/**
+ * One consultation as the history keeps it (see JobManager#record) and as the
+ * process running it describes it; written to history/<chain>/round-NN.json.
+ * @typedef {object} Round
+ * @property {string} job_id
+ * @property {string} chain_id
+ * @property {string | null | undefined} [group_id]
+ * @property {number} round
+ * @property {string} target
+ * @property {string} cli
+ * @property {string | null | undefined} [vendor]
+ * @property {string | null | undefined} [caller]
+ * @property {string | null | undefined} [caller_model]
+ * @property {string | null | undefined} [initiator]
+ * @property {'on' | 'off' | undefined} [network]
+ * @property {Boundary | null | undefined} [boundary]
+ * @property {RetryRecord[] | undefined} [retries]
+ * @property {PartialOutput | null | undefined} [partial_output]
+ * @property {Record<string, number> | null | undefined} [tool_calls]
+ * @property {string | null | undefined} [diagnostics]
+ * @property {Mode} mode
+ * @property {string} status
+ * @property {string} model
+ * @property {string} question
+ * @property {BriefRecord | null} brief
+ * @property {Prediction | null | undefined} [prediction]
+ * @property {Reflection | null | undefined} [reflection]
+ * @property {JobRecord | null | undefined} [record]
+ * @property {string} created_at
+ * @property {string | null} started_at
+ * @property {string | null} finished_at
+ * @property {number | null} duration_ms
+ * @property {ConsultResult | null} result
+ * @property {Quality | null} quality
+ * @property {UsageRecord | null} usage
+ * @property {JobFailure | null} failure
+ * @property {number | null | undefined} [references_count]
+ * @property {string | null} followup_to
+ * @property {number | undefined} [rounds_used]
+ * @property {number | undefined} [rounds_remaining]
+ */
+
+/** @typedef {Round & { owner?: Seat['owner'] }} RunningRecord The in-progress marker: a round record so far, plus who runs it. */
+
+/**
+ * One line of history/index.jsonl.
+ * @typedef {object} IndexRow
+ * @property {string} job_id
+ * @property {string} chain_id
+ * @property {number} round
+ * @property {string} target
+ * @property {string | null} cli
+ * @property {string | null} initiator
+ * @property {string} mode
+ * @property {string} status
+ * @property {string | null} failure_kind
+ * @property {string} model
+ * @property {string} created_at
+ * @property {number | null} duration_ms
+ */
+
+/**
+ * A seat file: one running consultation, shared by every severally process on one home.
+ * @typedef {object} Seat
+ * @property {string} job_id
+ * @property {string | undefined} [chain_id] set on a follow-up: the chain it continues
+ * @property {number | undefined} [round] set on a follow-up: the round it opens
+ * @property {{ pid: number, deadline_at: string } | undefined} [owner]
+ */
+
+/**
+ * What takeSeats says: `chainBusy` when the chain already has a round under way,
+ * otherwise `live` (the seats held) and, when the cap is hit, `elsewhere`.
+ * @typedef {{ ok: true, live: number, elsewhere?: undefined, chainBusy?: undefined }
+ *   | { ok: false, live?: undefined, elsewhere?: undefined, chainBusy: { live: Seat, mine: Seat } }
+ *   | { ok: false, live: number, elsewhere: number, chainBusy?: undefined }} SeatResult
+ */
+
+/**
+ * A fan-out, recorded under history/groups/.
+ * @typedef {object} Group
+ * @property {string} group_id
+ * @property {string} created_at
+ * @property {Mode} mode
+ * @property {string} question
+ * @property {string[]} job_ids
+ */
+
 export function ensureDirs() {
   const home = POLICY.home;
   fs.mkdirSync(path.join(home, 'history'), { recursive: true, mode: 0o700 });
@@ -20,6 +218,7 @@ export function ensureDirs() {
   return home;
 }
 
+/** @param {string} jobId */
 export function jobDir(jobId) {
   return path.join(POLICY.home, 'jobs', jobId);
 }
@@ -28,10 +227,12 @@ export function jobDir(jobId) {
 // directories, under one root: a consultant's read rules can then refuse that
 // one directory, including homes created after it started. Codex's permission
 // profile cannot express a wildcard such as jobs/*/home.
+/** @param {string} jobId */
 export function sandboxHome(jobId) {
   return path.join(POLICY.home, 'homes', jobId);
 }
 
+/** @param {string} jobId */
 export function makeWorkdir(jobId) {
   // Empty, dedicated, and outside any project: nothing for the consultant to
   // pick up as ambient context (no AGENTS.md / CLAUDE.md / repo files).
@@ -40,6 +241,11 @@ export function makeWorkdir(jobId) {
   return dir;
 }
 
+/**
+ * @param {string} jobId
+ * @param {string} name
+ * @param {string | NodeJS.ArrayBufferView} content
+ */
 export function writeJobArtifact(jobId, name, content) {
   const dir = jobDir(jobId);
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -48,6 +254,7 @@ export function writeJobArtifact(jobId, name, content) {
   return p;
 }
 
+/** @param {string} p */
 export function readIfExists(p) {
   try {
     return fs.readFileSync(p, 'utf8');
@@ -60,6 +267,10 @@ export function readIfExists(p) {
 // read back from its round file. Verdicts are written after the checking, and
 // the checking can take days, so the record must not depend on the job still
 // being in this process's memory. Returns null when the index has no such job.
+/**
+ * @param {string} jobId
+ * @returns {IndexRow | null}
+ */
 function indexRow(jobId) {
   for (const line of readIfExists(path.join(POLICY.home, 'history', 'index.jsonl')).split('\n')) {
     if (!line.trim()) continue;
@@ -73,7 +284,10 @@ function indexRow(jobId) {
   return null;
 }
 
-/** Every row of the history index, in the order written; a damaged line is skipped. */
+/**
+ * Every row of the history index, in the order written; a damaged line is skipped.
+ * @returns {IndexRow[]}
+ */
 export function indexRows() {
   return readIfExists(path.join(POLICY.home, 'history', 'index.jsonl'))
     .split('\n')
@@ -87,7 +301,11 @@ export function indexRows() {
     });
 }
 
-/** The round file an index row points at, or null. */
+/**
+ * The round file an index row points at, or null.
+ * @param {{ chain_id: string, round: number }} row
+ * @returns {Round | null}
+ */
 export function loadRoundAt(row) {
   try {
     return JSON.parse(fs.readFileSync(roundPath(row.chain_id, row.round), 'utf8'));
@@ -96,10 +314,19 @@ export function loadRoundAt(row) {
   }
 }
 
+/**
+ * @param {string} chainId
+ * @param {number} round
+ */
 export const roundPath = (chainId, round) =>
   path.join(POLICY.home, 'history', chainId, `round-${String(round).padStart(2, '0')}.json`);
 
-/** Kept beside the round when a consultant did not end on its own; `text` is already redacted. */
+/**
+ * Kept beside the round when a consultant did not end on its own; `text` is already redacted.
+ * @param {string} chainId
+ * @param {number} round
+ * @param {string} text
+ */
 export function writeDiagnostics(chainId, round, text) {
   fs.mkdirSync(path.join(POLICY.home, 'history', chainId), { recursive: true, mode: 0o700 });
   const file = roundPath(chainId, round).replace(/\.json$/, '.diagnostics.txt');
@@ -107,6 +334,10 @@ export function writeDiagnostics(chainId, round, text) {
   return file;
 }
 
+/**
+ * @param {string} jobId
+ * @returns {Round | null}
+ */
 export function loadRound(jobId) {
   const row = indexRow(jobId);
   if (!row) return null;
@@ -119,8 +350,13 @@ export function loadRound(jobId) {
 
 // Every round file of one chain, oldest first: a follow-up to a consultation
 // from an earlier server session needs the rounds before it, not just one.
+/**
+ * @param {string} chainId
+ * @returns {Round[]}
+ */
 export function loadChain(chainId) {
   const dir = path.join(POLICY.home, 'history', chainId);
+  /** @type {string[]} */
   let names = [];
   try {
     names = fs
@@ -142,6 +378,10 @@ export function loadChain(chainId) {
 // `appendIndex: false` rewrites a round that has already been recorded -- the
 // lead adding a verdict to it later. index.jsonl stays one line per
 // consultation, so counting rounds there never counts edits.
+/**
+ * @param {Round} record
+ * @param {{ appendIndex?: boolean }} [opts]
+ */
 export function persistRound(record, { appendIndex = true } = {}) {
   fs.mkdirSync(path.join(POLICY.home, 'history', record.chain_id), { recursive: true, mode: 0o700 });
   // Written aside and renamed into place, so a write that fails part-way
@@ -189,8 +429,10 @@ export function persistRound(record, { appendIndex = true } = {}) {
 const JOB_ID = /^job_[0-9a-f]{12}$/;
 const GROUP_ID = /^group_[0-9a-f]{12}$/;
 const runningDir = () => path.join(POLICY.home, 'history', 'running');
+/** @param {string} jobId */
 const runningFile = (jobId) => path.join(runningDir(), `${jobId}.json`);
 
+/** @param {RunningRecord} record */
 export function writeRunning(record) {
   if (!JOB_ID.test(record.job_id)) return;
   fs.mkdirSync(runningDir(), { recursive: true, mode: 0o700 });
@@ -200,6 +442,10 @@ export function writeRunning(record) {
   fs.renameSync(tmp, runningFile(record.job_id));
 }
 
+/**
+ * @param {string} jobId
+ * @returns {RunningRecord | null}
+ */
 export function loadRunning(jobId) {
   if (!JOB_ID.test(jobId)) return null;
   try {
@@ -209,6 +455,7 @@ export function loadRunning(jobId) {
   }
 }
 
+/** @returns {string[]} */
 export function listRunning() {
   try {
     return fs
@@ -220,6 +467,7 @@ export function listRunning() {
   }
 }
 
+/** @param {string} jobId */
 export function removeRunning(jobId) {
   if (!JOB_ID.test(jobId)) return;
   try {
@@ -235,10 +483,16 @@ export function removeRunning(jobId) {
 // admitting at once cannot both see the last free seat. `held(seat)` says
 // whether a seat's owner is still running it; one that is not is removed.
 const seatsDir = () => path.join(POLICY.home, 'slots');
+/** @param {string} jobId */
 const seatFile = (jobId) => path.join(seatsDir(), `${jobId}.json`);
 const LOCK_WAIT_MS = 2_000;
 const LOCK_STALE_MS = 10_000;
 
+/**
+ * @template T
+ * @param {() => T} fn
+ * @returns {T}
+ */
 function withSeatLock(fn) {
   const lock = path.join(seatsDir(), '.lock');
   fs.mkdirSync(seatsDir(), { recursive: true, mode: 0o700 });
@@ -248,7 +502,7 @@ function withSeatLock(fn) {
       fs.mkdirSync(lock);
       break;
     } catch (err) {
-      if (err.code !== 'EEXIST') throw err;
+      if (!(err instanceof Error && 'code' in err && err.code === 'EEXIST')) throw err;
       // Held for a few file operations at most: one this old was left by a
       // process that died holding it.
       try {
@@ -271,9 +525,23 @@ function withSeatLock(fn) {
   }
 }
 
-/** Takes one seat per entry of `seats` ({ job_id, owner }), all or none. */
+/**
+ * A seat that continues a chain names it and the round it opens together.
+ * @param {Seat} seat
+ * @returns {seat is Seat & { chain_id: string, round: number }}
+ */
+const continuesChain = (seat) => Boolean(seat.chain_id);
+
+/**
+ * Takes one seat per entry of `seats` ({ job_id, owner }), all or none.
+ * @param {Seat[]} seats
+ * @param {number} cap
+ * @param {(seat: Seat) => boolean} held
+ * @returns {SeatResult}
+ */
 export function takeSeats(seats, cap, held) {
   return withSeatLock(() => {
+    /** @type {Seat[]} */
     const live = [];
     const names = fs.readdirSync(seatsDir());
     // A cancel asked for after its consultation ended has no seat left to go with.
@@ -287,6 +555,7 @@ export function takeSeats(seats, cap, held) {
     }
     for (const name of names) {
       if (!name.endsWith('.json')) continue;
+      /** @type {Seat | null} */
       let seat = null;
       try {
         seat = JSON.parse(fs.readFileSync(path.join(seatsDir(), name), 'utf8'));
@@ -304,7 +573,8 @@ export function takeSeats(seats, cap, held) {
     // A chain runs one round at a time, across processes: a live seat on the
     // same chain, or a round file already at the number chosen, means another
     // server continued it first.
-    for (const mine of seats.filter((x) => x.chain_id)) {
+    for (const mine of seats.filter(continuesChain)) {
+      /** @type {Seat | undefined} */
       let other = live.find((x) => x.chain_id === mine.chain_id);
       if (!other && fs.existsSync(roundPath(mine.chain_id, mine.round))) {
         try {
@@ -326,6 +596,7 @@ export function takeSeats(seats, cap, held) {
   });
 }
 
+/** @param {string} jobId */
 export function releaseSeat(jobId) {
   if (!JOB_ID.test(jobId)) return;
   try {
@@ -338,7 +609,9 @@ export function releaseSeat(jobId) {
 
 // A cancel asked for by a server that does not run the consultation: left
 // beside its seat, for the server that does to find and act on.
+/** @param {string} jobId */
 const cancelFile = (jobId) => path.join(seatsDir(), `${jobId}.cancel`);
+/** @param {string} jobId */
 export function requestCancel(jobId) {
   if (!JOB_ID.test(jobId)) return false;
   try {
@@ -349,7 +622,9 @@ export function requestCancel(jobId) {
     return false;
   }
 }
+/** @param {string} jobId */
 export const cancelRequested = (jobId) => JOB_ID.test(jobId) && fs.existsSync(cancelFile(jobId));
+/** @param {string} jobId */
 export function clearCancel(jobId) {
   if (JOB_ID.test(jobId))
     try {
@@ -359,6 +634,10 @@ export function clearCancel(jobId) {
     }
 }
 
+/**
+ * @param {string} groupId
+ * @returns {Group | null}
+ */
 export function loadGroup(groupId) {
   if (!GROUP_ID.test(groupId)) return null;
   try {
@@ -371,12 +650,14 @@ export function loadGroup(groupId) {
 // A fan-out is recorded as its own record so a later reader can tell which
 // answers were asked the same question at the same time; each member job still
 // writes its own round file under its own chain.
+/** @param {Group} group */
 export function persistGroup(group) {
   const dir = path.join(POLICY.home, 'history', 'groups');
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
   fs.writeFileSync(path.join(dir, `${group.group_id}.json`), JSON.stringify(group, null, 2), { mode: 0o600 });
 }
 
+/** @param {string} jobId */
 export function cleanupJobDir(jobId) {
   for (const dir of [jobDir(jobId), sandboxHome(jobId)]) {
     try {