plumbbob 0.8.18 → 0.9.1

package/dist/lib/agents.js

@@ -1,36 +1,54 @@
-// The agent contract (D39/D46): a user-authored agent is anything executable that
-// speaks a versioned JSON envelope — a JSON manifest on disk (`agent.json`), JSON
-// on the child's stdin, JSON on its stdout, prose on its stderr. This module is
-// the contract's validator AND resolver: it type-narrows the on-disk manifest and
-// the output envelope a child returns (refusing a contract major-version mismatch
-// with an upgrade hint rather than guessing at a shape that is only stable within a
-// major — C7: additions are minor, removals/renames are major), and it walks the
-// two agent tiers to resolve an agent by name. The validators are pure; the
-// resolver reads `agent.json` files off disk (node builtins only, C2). Invocation
-// (step 4) spawns on top of these.
+// The agent contract. A user-authored agent is anything executable that speaks a
+// versioned JSON envelope — a JSON manifest on disk (`agent.json`), JSON on the
+// child's stdin, JSON on its stdout, prose on its stderr — so the doorway is
+// runtime-agnostic: any language, any framework, one subprocess boundary. This
+// module is the contract's validator, resolver, and runner: it type-narrows the
+// on-disk manifest and the output envelope a child returns (refusing a contract
+// major-version mismatch with an upgrade hint rather than guessing at a shape
+// that is only stable within a major — additions are a minor bump, removals or
+// renames a major), it walks the agent tiers to resolve an agent by name, it
+// composes the step context a child reads on stdin, and it spawns the child.
+// The validators are pure; the resolver reads `agent.json` files off disk with
+// node builtins only. The `agent run` verb (src/verbs/agent.ts) is the thin
+// shell over all of it.
 import { spawn } from 'node:child_process';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { parseBuildTitle, parseStepMeta, parseStepSeam, scrapeBullets } from "./intent.js";
-// The contract major version this plumbbob speaks. A manifest or envelope
-// declaring a different major is refused (D46): within a major the envelope only
-// gains fields, so an older CLI can read a newer minor, but a major gap means the
-// shapes may genuinely disagree.
+/**
+ * The contract major version this plumbbob speaks.
+ *
+ * A manifest or envelope declaring a different major is refused: within a major
+ * the envelope only gains fields, so an older CLI can read a newer minor, but a
+ * major gap means the shapes may genuinely disagree.
+ */
 export const CONTRACT_VERSION = 1;
-// The three lifecycle slots an agent may bind to (D43): `before` (context in),
-// `build` (the diff), `after` (advisory review). Exactly these, never a fourth —
-// "a salient point in the middle" is judgment the host model handles in prose,
-// not a declarative slot.
+/**
+ * The three lifecycle slots an agent may bind to: `before` (context in),
+ * `build` (the diff), `after` (advisory review).
+ *
+ * Exactly these, never a fourth — "a salient point in the middle" is judgment
+ * the host model handles in prose, not a declarative slot.
+ */
 export const SLOTS = ['before', 'build', 'after'];
-// The terminal states an agent reports (D52). `done` = finished; `blocked` = it
-// couldn't finish, so the human unblocks and re-runs; `drift` = it finished but
-// found the plan no longer matches reality, so the route is /pb-refine repair.
+/**
+ * The terminal states an agent reports.
+ *
+ * `done` = finished. `blocked` = it couldn't finish, so the human unblocks and
+ * re-runs. `drift` = it finished but found the plan no longer matches reality,
+ * so the route is /plumbbob:refine repair. The two halts need different medicine,
+ * which is why they are distinct statuses.
+ */
 export const ENVELOPE_STATUSES = ['done', 'blocked', 'drift'];
-// Validate a parsed `agent.json`. Contract is checked first (a version mismatch
-// gets an upgrade hint, not a field complaint, since older field checks may not
-// apply across a major). Then: a non-empty `name` and `command`, and a `slots`
-// subset of {before, build, after}. Unknown keys pass through untouched.
+/**
+ * Validate a parsed `agent.json`.
+ *
+ * Contract is checked first (a version mismatch gets an upgrade hint, not a
+ * field complaint, since older field checks may not apply across a major).
+ * Then: a non-empty `name` and `command`, and a `slots` subset of {before,
+ * build, after}. Unknown keys pass through untouched.
+ */
 export function parseManifest(raw) {
     if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
         return manifestFail('agent.json must be a JSON object.');
@@ -62,10 +80,13 @@ export function parseManifest(raw) {
         },
     };
 }
-// Validate a child's output envelope (already JSON-parsed from its stdout).
-// Contract first (mismatch → upgrade hint), then a `status` in {done, blocked,
-// drift}, a non-empty `summary`, and a well-formed `parked[]`. Optional prose
-// fields default to empty; unknown keys are tolerated (C7).
+/**
+ * Validate a child's output envelope (already JSON-parsed from its stdout).
+ *
+ * Contract first (mismatch → upgrade hint), then a `status` in {done, blocked,
+ * drift}, a non-empty `summary`, and a well-formed `parked[]`. Optional prose
+ * fields default to empty; unknown keys are tolerated.
+ */
 export function parseEnvelope(raw) {
     if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
         return envelopeFail('the agent envelope must be a JSON object on stdout.');
@@ -97,15 +118,24 @@ export function parseEnvelope(raw) {
         },
     };
 }
-// True when a string names one of the three slots. Exported for step 4's
-// `--mode` refusal (D54): a mode the manifest doesn't declare is refused loud.
+/**
+ * True when a string names one of the three slots.
+ *
+ * Exported for the `agent run` verb's `--mode` refusal: a mode the manifest
+ * doesn't declare is refused loud — the user who typed it asked for that slot
+ * specifically.
+ */
 export function isSlot(value) {
     return SLOTS.includes(value);
 }
-// Validate the shared `contract` field. A missing / non-integer contract is
-// malformed; a present-but-different major is a version mismatch (D46) and gets an
-// upgrade hint pointing at whichever side is behind. Returns an error string, or
-// null when the contract is the supported major.
+/**
+ * Validate the shared `contract` field.
+ *
+ * A missing / non-integer contract is malformed; a present-but-different major
+ * is a version mismatch and gets an upgrade hint pointing at whichever side is
+ * behind. Returns an error string, or null when the contract is the supported
+ * major.
+ */
 function checkContract(value, what) {
     if (typeof value !== 'number' || !Number.isInteger(value)) {
         return `${what} needs an integer "contract" version — this plumbbob speaks contract ${CONTRACT_VERSION}.`;
@@ -117,9 +147,12 @@ function checkContract(value, what) {
     }
     return null;
 }
-// Narrow the manifest's `slots` to the subset it declares. Must be a non-empty
-// array drawn from SLOTS, with strangers refused and duplicates collapsed.
-// Returns the narrowed slots, or an error string.
+/**
+ * Narrow the manifest's `slots` to the subset it declares.
+ *
+ * Must be a non-empty array drawn from SLOTS, with strangers refused and
+ * duplicates collapsed. Returns the narrowed slots, or an error string.
+ */
 function parseSlots(value) {
     if (!Array.isArray(value) || value.length === 0) {
         return `agent.json needs a non-empty "slots" array drawn from ${SLOTS.join(', ')}.`;
@@ -133,10 +166,14 @@ function parseSlots(value) {
     }
     return [...seen];
 }
-// `parked[]` is optional (absent = none). Present, it must be an array of
-// non-blank strings — each becomes a park line the CLI lands through the park
-// verb (D44). A malformed list is refused rather than silently dropped: losing a
-// parked concern is a quiet data loss. Returns the trimmed lines or an error.
+/**
+ * Narrow the envelope's optional `parked[]` (absent = none).
+ *
+ * Present, it must be an array of non-blank strings — each becomes a park line
+ * the CLI lands through the park verb. A malformed list is refused rather than
+ * silently dropped: losing a parked concern is a quiet data loss. Returns the
+ * trimmed lines or an error string.
+ */
 function parseParked(value) {
     if (value === undefined || value === null) {
         return [];
@@ -153,39 +190,66 @@ function parseParked(value) {
     }
     return parked;
 }
-// Optional prose fields (description, when, body, notes) default to empty —
-// absent and blank read the same to the host model, and a non-string value is
-// coerced away rather than refused, because these are advisory prose, not gates.
+/**
+ * Coerce an optional prose field (description, when, body, notes) to a string.
+ *
+ * Absent and blank read the same to the host model, and a non-string value is
+ * coerced away rather than refused, because these are advisory prose, not
+ * gates.
+ */
 function asString(value) {
     return typeof value === 'string' ? value : '';
 }
+/**
+ * True when a string names one of the envelope statuses.
+ */
 function isStatus(value) {
     return ENVELOPE_STATUSES.includes(value);
 }
+/**
+ * Wrap an error string as a failed manifest parse.
+ */
 function manifestFail(error) {
     return { ok: false, error };
 }
+/**
+ * Wrap an error string as a failed envelope parse.
+ */
 function envelopeFail(error) {
     return { ok: false, error };
 }
+/**
+ * The project agents tier — `.plumbbob/agents/` under the repo root.
+ */
 export function projectAgentsDir(root) {
     return join(root, '.plumbbob', 'agents');
 }
+/**
+ * The personal agents tier — `~/.plumbbob/agents/`, the user's own library.
+ */
 export function personalAgentsDir(home) {
     return join(home, '.plumbbob', 'agents');
 }
-// The home dir the personal tier resolves under. Callers (verbs) pass nothing and
-// get the environment's HOME (matching doctor.ts); tests pass an explicit dir to
-// exercise an HOME-overridden personal library without touching process.env.
+/**
+ * The home dir the personal tier resolves under.
+ *
+ * Callers (verbs) pass nothing and get the environment's HOME (matching
+ * doctor.ts); tests pass an explicit dir to exercise an HOME-overridden
+ * personal library without touching process.env.
+ */
 function agentsHome(home) {
     return home ?? process.env.HOME ?? homedir();
 }
-// Resolve an agent by name across the tiers (D41), first hit wins. A `flagPath`
-// (from `--agent <path>`) points straight at an agent directory and takes top
-// priority. A tier "hits" when it holds an `agent.json`: a malformed one there is
-// surfaced as an error (project still shadows personal — D54's fail-loud), never
-// silently skipped in favor of a different agent. Returns the not-found error only
-// when no tier holds a manifest at all.
+/**
+ * Resolve an agent by name across the tiers, first hit wins.
+ *
+ * A `flagPath` (from `--agent <path>`) points straight at an agent directory
+ * and takes top priority. A tier "hits" when it holds an `agent.json`: a
+ * malformed one there is surfaced as an error (project still shadows
+ * personal), never silently skipped in favor of a different agent — an
+ * explicit ask fails loud. Returns the not-found error only when no tier holds
+ * a manifest at all.
+ */
 export function resolveAgent(root, name, opts = {}) {
     if (opts.flagPath !== undefined) {
         const hit = loadAgentDir(opts.flagPath, 'flag');
@@ -206,10 +270,13 @@ export function resolveAgent(root, name, opts = {}) {
         error: `no agent named "${name}" — looked in ${projectAgentsDir(root)} and ${personalAgentsDir(home)}.`,
     };
 }
-// Every resolvable agent across both tiers, sorted by name, project shadowing
-// personal (a name defined in both resolves — and lists — from project). Each
-// entry carries its origin and resolution; a malformed manifest lands as an errored
-// resolution rather than crashing the walk.
+/**
+ * Every resolvable agent across both tiers, sorted by name.
+ *
+ * Project shadows personal: a name defined in both resolves — and lists — from
+ * project. Each entry carries its origin and resolution; a malformed manifest
+ * lands as an errored resolution rather than crashing the walk.
+ */
 export function listAgents(root, opts = {}) {
     const home = agentsHome(opts.home);
     const tiers = [
@@ -229,9 +296,13 @@ export function listAgents(root, opts = {}) {
         resolution: resolveAgent(root, name, { home }),
     }));
 }
-// Render `agent list`'s output. Pure so the verb stays a thin read-write shell and
-// the formatting is unit-tested here. Prints name, origin, slots, and description
-// per agent (D41's done-when); a malformed manifest gets a `✗ … invalid:` line.
+/**
+ * Render `agent list`'s output.
+ *
+ * Pure so the verb stays a thin read-write shell and the formatting is
+ * unit-tested here. Prints name, origin, slots, and description per agent; a
+ * malformed manifest gets a `✗ … invalid:` line.
+ */
 export function formatAgentList(listings) {
     if (listings.length === 0) {
         return 'plumbbob: no agents. Add one under .plumbbob/agents/<name>/ or ~/.plumbbob/agents/<name>/.';
@@ -248,10 +319,14 @@ export function formatAgentList(listings) {
     }
     return lines.join('\n');
 }
-// Load and validate the `agent.json` in one agent directory. Returns null when the
-// directory holds no manifest (a tier miss, so resolution falls through), an errored
-// resolution when the manifest is present but unreadable/malformed, else the resolved
-// agent. A missing file (ENOENT throw) is the miss signal — one read, no TOCTOU race.
+/**
+ * Load and validate the `agent.json` in one agent directory.
+ *
+ * Returns null when the directory holds no manifest (a tier miss, so
+ * resolution falls through), an errored resolution when the manifest is
+ * present but unreadable/malformed, else the resolved agent. A missing file
+ * (ENOENT throw) is the miss signal — one read, no TOCTOU race.
+ */
 function loadAgentDir(dir, origin) {
     const file = join(dir, 'agent.json');
     let raw;
@@ -273,9 +348,12 @@ function loadAgentDir(dir, origin) {
         ? { ok: true, agent: { manifest: result.manifest, origin, dir } }
         : { ok: false, error: `${file}: ${result.error}` };
 }
-// The names of subdirectories under an agents tier that actually carry an
-// `agent.json` — so `listAgents` never lists a bare folder that resolution would
-// then miss. An absent tier directory yields no names.
+/**
+ * The names of subdirectories under an agents tier that carry an `agent.json`.
+ *
+ * Filtering here means `listAgents` never lists a bare folder that resolution
+ * would then miss. An absent tier directory yields no names.
+ */
 function agentDirNames(dir) {
     try {
         return readdirSync(dir, { withFileTypes: true })
@@ -286,11 +364,15 @@ function agentDirNames(dir) {
         return [];
     }
 }
-// Compose the StepContext for one step. The strict seam parse is the only refusal
-// path — a missing step or unparseable seam gates git behavior, so it fails loud;
-// everything else is best-effort and lands whatever it can, returning `warnings`
-// (skipped-bullet lines) for the caller to print on stderr rather than writing
-// there itself (this module stays pure — the verb does the IO).
+/**
+ * Compose the StepContext for one step.
+ *
+ * The strict seam parse is the only refusal path — a missing step or
+ * unparseable seam gates git behavior, so it fails loud; everything else is
+ * best-effort and lands whatever it can, returning `warnings` (skipped-bullet
+ * lines) for the caller to print on stderr rather than writing there itself —
+ * this module stays pure, the verb does the IO.
+ */
 export function composeStepContext(params) {
     const seam = parseStepSeam(params.intent, params.step);
     if (!seam.ok) {
@@ -318,15 +400,22 @@ export function composeStepContext(params) {
         warnings,
     };
 }
+/**
+ * Format the skipped-line warnings for one scraped intent.md section.
+ */
 function skipWarnings(heading, skipped) {
     return skipped.map((line) => `intent.md: skipped a non-bullet line under ${heading} — ${JSON.stringify(line.trim())}`);
 }
-// Validate a parsed harness.json. Contract first (a major mismatch gets the same
-// upgrade hint as the manifest/envelope, D46). Structure is strict — a `steps` that
-// is not an object, a non-numeric step key, or a step entry that is not an object
-// is the author's error and is refused loud. Slot *contents* stay lenient (D61): a
-// slot value may be one name or a list, and blanks/non-strings drop rather than
-// refuse, because bindings feed a spawn, not a git-gating parse.
+/**
+ * Validate a parsed harness.json.
+ *
+ * Contract first (a major mismatch gets the same upgrade hint as the manifest
+ * and envelope). Structure is strict — a `steps` that is not an object, a
+ * non-numeric step key, or a step entry that is not an object is the author's
+ * error and is refused loud. Slot *contents* stay lenient: a slot value may be
+ * one name or a list, and blanks/non-strings drop rather than refuse, because
+ * bindings feed a spawn, not a git-gating parse.
+ */
 function parseHarness(raw) {
     if (!isObject(raw)) {
         return { ok: false, error: 'harness.json must be a JSON object.' };
@@ -353,12 +442,16 @@ function parseHarness(raw) {
     }
     return { ok: true, harness: { contract: CONTRACT_VERSION, defaults, steps } };
 }
-// Read and validate a harness.json at `path`. The caller builds the path from the
-// build folder — this module stays ignorant of the sidecar layout, taking the full
-// path. null when the file is absent (a build with no bound agents — a clean
-// no-op); an errored parse when present-but-broken (invalid JSON or a malformed
-// structure the author must fix); else the validated bindings. Shared so every
-// reader (`agent run`, `status`) parses the harness the same way.
+/**
+ * Read and validate a harness.json at `path`.
+ *
+ * The caller builds the path from the build folder — this module stays
+ * ignorant of the sidecar layout, taking the full path. Returns null when the
+ * file is absent (a build with no bound agents — a clean no-op); an errored
+ * parse when present-but-broken (invalid JSON or a malformed structure the
+ * author must fix); else the validated bindings. Shared so every reader
+ * (`agent run`, `status`) parses the harness the same way.
+ */
 export function readHarnessFile(path) {
     let raw;
     try {
@@ -376,12 +469,16 @@ export function readHarnessFile(path) {
     }
     return parseHarness(parsed);
 }
-// Narrow a raw slot→agents object (a harness `defaults`, a per-step entry, or the
-// settings-level defaults, D57) to the slots it actually binds. A slot value may be
-// a single agent name or a list; blanks and non-strings drop. Only the three real
-// slots are read — `note` and any stranger key are ignored here. A slot present but
-// naming no valid agent still counts as bound-to-nothing (an explicit override to
-// none), so callers get clean replace semantics up the ladder.
+/**
+ * Narrow a raw slot→agents object to the slots it actually binds.
+ *
+ * Accepts a harness `defaults` block, a per-step entry, or the settings-level
+ * defaults. A slot value may be a single agent name or a list; blanks and
+ * non-strings drop. Only the three real slots are read — `note` and any
+ * stranger key are ignored here. A slot present but naming no valid agent
+ * still counts as bound-to-nothing (an explicit override to none), so callers
+ * get clean replace semantics up the ladder.
+ */
 export function parseSlotBindings(raw) {
     if (!isObject(raw))
         return {};
@@ -392,12 +489,16 @@ export function parseSlotBindings(raw) {
     }
     return out;
 }
-// The agents bound to one slot for one step, merging the ladder (D57): a per-step
-// slot entry overrides the harness `defaults`, which override the settings-level
-// defaults — the first level that names the slot wins (replace, not append). The
-// `--agent` flag and an explicit name sit above all of this, but the verb takes the
-// single-agent path for those and never reaches here. Returns [] when no level
-// binds the slot: nothing to run, a clean no-op.
+/**
+ * The agents bound to one slot for one step, merged down the bindings ladder.
+ *
+ * A per-step slot entry overrides the harness `defaults`, which override the
+ * settings-level defaults — the first level that names the slot wins, replace
+ * not append, the same most-specific-wins shape as the settings ladder. The
+ * `--agent` flag and an explicit name sit above all of this, but the verb
+ * takes the single-agent path for those and never reaches here. Returns []
+ * when no level binds the slot: nothing to run, a clean no-op.
+ */
 export function resolveSlotAgents(params) {
     const perStep = params.harness?.steps.get(params.step)?.bindings;
     if (perStep && params.slot in perStep)
@@ -409,23 +510,36 @@ export function resolveSlotAgents(params) {
         return params.settingsDefaults[params.slot] ?? [];
     return [];
 }
+/**
+ * Coerce a slot value — one agent name or a list — to a trimmed name list,
+ * dropping blanks and non-strings.
+ */
 function asNameList(value) {
     const items = Array.isArray(value) ? value : [value];
     return items.filter((v) => typeof v === 'string' && v.trim().length > 0).map((v) => v.trim());
 }
+/**
+ * True when a value is a plain JSON object — not null, not an array.
+ */
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-// Spawn an agent's `command` via the shell (D49: `sh -c` on POSIX) at the repo
-// root, with the composed StepContext delivered as JSON on stdin. Stdout is piped
-// and captured (the envelope); stderr is inherited so the child's prose streams
-// live to the terminal (D46 — production narrates, consumption stays structured);
-// the agent's own directory rides in `PLUMBBOB_AGENT_DIR` (D49) so a root-cwd
-// agent can still reach its files. A SIGINT while the child runs kills it and
-// reports `interrupted` rather than orphaning it (D58); a positive `timeoutSeconds`
-// arms a kill timer (D51, 0 = off). Async `spawn`, not `spawnSync` (D60), so the
-// parent stays live to interrupt gracefully. Never rejects — every failure mode is
-// a resolved `AgentRunResult`.
+/**
+ * Spawn an agent's `command` and settle with the run's outcome.
+ *
+ * The command runs via the shell (`sh -c` on POSIX) at the repo root, so a
+ * build-slot agent's repo-relative seam edits resolve; the agent's own
+ * directory rides in `PLUMBBOB_AGENT_DIR` so a root-cwd agent can still reach
+ * its files. The composed StepContext is delivered as JSON on stdin. Stdout is
+ * piped and captured (the envelope); stderr is inherited so the child's prose
+ * streams live to the terminal — production (narrating) never collides with
+ * consumption (one structured result at the pause). A SIGINT while the child
+ * runs kills it and reports `interrupted` rather than orphaning it — the human
+ * is present, Ctrl-C works. A positive `timeoutSeconds` arms a kill timer
+ * (0 = off; a timeout is the user's explicit opt-in). Async `spawn`, not
+ * `spawnSync`, so the parent stays live to interrupt gracefully. Never
+ * rejects — every failure mode is a resolved `AgentRunResult`.
+ */
 export function runAgent(params) {
     return new Promise((resolve) => {
         const child = spawn(params.command, {
@@ -446,7 +560,7 @@ export function runAgent(params) {
             process.off('SIGINT', onSigint);
             resolve(result);
         };
-        // Kill the child and report, rather than let a Ctrl-C orphan it (D58). The
+        // Kill the child and report, rather than let a Ctrl-C orphan it. The
         // SIGKILL escalation covers a child that ignores the interrupt.
         function onSigint() {
             child.kill('SIGKILL');
@@ -482,10 +596,14 @@ export function runAgent(params) {
         child.stdin.end();
     });
 }
-// Parse the child's captured stdout into a validated envelope: JSON first (a
-// non-JSON stdout is out of contract, D46), then the envelope validator (which
-// carries the contract-mismatch hint). Kept private — `runAgent` is the only
-// caller and the verb reads the union, not this.
+/**
+ * Parse the child's captured stdout into a validated envelope.
+ *
+ * JSON first (a non-JSON stdout is out of contract — the envelope must be one
+ * JSON object), then the envelope validator, which carries the
+ * contract-mismatch hint. Kept private — `runAgent` is the only caller and the
+ * verb reads the union, not this.
+ */
 function parseChildEnvelope(stdout) {
     let raw;
     try {