@mindrian_os/install 1.13.0-beta.16 → 1.13.0-beta.17

package/lib/core/mva-dispatcher.test.cjs

@@ -0,0 +1,216 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 118-01 Plan 01 Task 3 -- mva-dispatcher tests.
+ *
+ * Verifies parallel fan-out with streaming-as-settled order, per-agent
+ * timeouts, global timeout, all-fail handling, dispatchToArray collector,
+ * and the Canon Part 8 invariant that the AgentContext contains ONLY
+ * sentence_sha256 (no raw_sentence, no MVA_SENTENCE env var).
+ *
+ * Pure CJS, node built-ins only. Run via `node --test`.
+ */
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert');
+
+const { dispatch, dispatchToArray } = require('./mva-dispatcher.cjs');
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function mkAgent(id, fn) {
+  return { id, fn };
+}
+
+test('mva-dispatcher: Test 1 -- 6 fast agents fan out in parallel', async () => {
+  const agents = Array.from({ length: 6 }, (_, i) =>
+    mkAgent(`agent_${i}`, async () => ({ status: 'ok', payload: { i } }))
+  );
+  const t0 = Date.now();
+  const results = await dispatchToArray(agents, 'sha_abc');
+  const elapsed = Date.now() - t0;
+  assert.strictEqual(results.length, 6);
+  for (const r of results) {
+    assert.strictEqual(r.status, 'ok');
+  }
+  assert.ok(elapsed < 300, `wall-clock ${elapsed}ms should be < 300ms (fast fan-out)`);
+});
+
+test('mva-dispatcher: Test 2 -- 6 slow agents all timeout independently', async () => {
+  const agents = Array.from({ length: 6 }, (_, i) =>
+    mkAgent(`agent_${i}`, async (_ctx, signal) => {
+      await new Promise((resolve, reject) => {
+        const t = setTimeout(resolve, 1000);
+        signal.addEventListener('abort', () => {
+          clearTimeout(t);
+          reject(new Error('aborted'));
+        });
+      });
+      return { status: 'ok', payload: {} };
+    })
+  );
+  const t0 = Date.now();
+  const results = await dispatchToArray(agents, 'sha_abc', {
+    globalBudgetMs: 5000,
+    perAgentCapMs: 50
+  });
+  const elapsed = Date.now() - t0;
+  assert.strictEqual(results.length, 6);
+  for (const r of results) {
+    assert.strictEqual(r.status, 'timeout', `agent ${r.agent_id} should be timeout`);
+  }
+  assert.ok(elapsed < 400, `wall-clock ${elapsed}ms should be < 400ms (parallel timeouts)`);
+});
+
+test('mva-dispatcher: Test 3 -- mixed fast/slow stream in arrival order', async () => {
+  const agents = [
+    mkAgent('fast_1', async () => { await sleep(10); return { status: 'ok', payload: 'f1' }; }),
+    mkAgent('slow_1', async (_c, s) => {
+      await new Promise((resolve, reject) => {
+        const t = setTimeout(resolve, 1000);
+        s.addEventListener('abort', () => { clearTimeout(t); reject(new Error('aborted')); });
+      });
+      return { status: 'ok', payload: 's1' };
+    }),
+    mkAgent('fast_2', async () => { await sleep(10); return { status: 'ok', payload: 'f2' }; }),
+    mkAgent('slow_2', async (_c, s) => {
+      await new Promise((resolve, reject) => {
+        const t = setTimeout(resolve, 1000);
+        s.addEventListener('abort', () => { clearTimeout(t); reject(new Error('aborted')); });
+      });
+      return { status: 'ok', payload: 's2' };
+    }),
+    mkAgent('fast_3', async () => { await sleep(10); return { status: 'ok', payload: 'f3' }; }),
+    mkAgent('slow_3', async (_c, s) => {
+      await new Promise((resolve, reject) => {
+        const t = setTimeout(resolve, 1000);
+        s.addEventListener('abort', () => { clearTimeout(t); reject(new Error('aborted')); });
+      });
+      return { status: 'ok', payload: 's3' };
+    })
+  ];
+  const t0 = Date.now();
+  const order = [];
+  const stamps = [];
+  for await (const r of dispatch(agents, 'sha_abc', {
+    globalBudgetMs: 5000,
+    perAgentCapMs: 100
+  })) {
+    order.push({ id: r.agent_id, status: r.status });
+    stamps.push(Date.now() - t0);
+  }
+  assert.strictEqual(order.length, 6);
+  // First 3 yielded are fast (status=ok); next 3 are slow (status=timeout).
+  const fastOnes = order.slice(0, 3);
+  const slowOnes = order.slice(3);
+  for (const r of fastOnes) {
+    assert.strictEqual(r.status, 'ok', `expected fast ok, got ${JSON.stringify(r)}`);
+    assert.ok(['fast_1', 'fast_2', 'fast_3'].includes(r.id));
+  }
+  for (const r of slowOnes) {
+    assert.strictEqual(r.status, 'timeout');
+    assert.ok(['slow_1', 'slow_2', 'slow_3'].includes(r.id));
+  }
+  // Last fast yields well before first slow yields.
+  assert.ok(stamps[2] < 80, `fast results should yield by ~50ms; got ${stamps[2]}`);
+  assert.ok(stamps[3] >= 90, `first slow result should yield around ~100ms; got ${stamps[3]}`);
+});
+
+test('mva-dispatcher: Test 4 -- global budget short truncates remaining agents', async () => {
+  const agents = Array.from({ length: 6 }, (_, i) =>
+    mkAgent(`agent_${i}`, async (_c, s) => {
+      await new Promise((resolve, reject) => {
+        const t = setTimeout(resolve, 1000);
+        s.addEventListener('abort', () => { clearTimeout(t); reject(new Error('aborted')); });
+      });
+      return { status: 'ok', payload: {} };
+    })
+  );
+  const t0 = Date.now();
+  const results = await dispatchToArray(agents, 'sha_abc', {
+    globalBudgetMs: 100,
+    perAgentCapMs: 35000
+  });
+  const elapsed = Date.now() - t0;
+  assert.strictEqual(results.length, 6);
+  for (const r of results) {
+    assert.strictEqual(r.status, 'timeout');
+  }
+  assert.ok(elapsed < 250, `global budget should clamp wall-clock; got ${elapsed}ms`);
+});
+
+test('mva-dispatcher: Test 5 -- dispatchToArray equivalent to for-await', async () => {
+  const agents = Array.from({ length: 3 }, (_, i) =>
+    mkAgent(`agent_${i}`, async () => ({ status: 'ok', payload: { i } }))
+  );
+  const a = await dispatchToArray(agents, 'sha_abc');
+  const b = [];
+  for await (const r of dispatch(agents, 'sha_abc')) b.push(r);
+  assert.strictEqual(a.length, b.length);
+  // Order may differ since both run in parallel; compare by id set.
+  const idsA = new Set(a.map((r) => r.agent_id));
+  const idsB = new Set(b.map((r) => r.agent_id));
+  assert.deepStrictEqual([...idsA].sort(), [...idsB].sort());
+});
+
+test('mva-dispatcher: Test 6 -- AgentContext carries sentence_sha256 ONLY', async () => {
+  // Pre-condition: env var must be unset before dispatch.
+  delete process.env.MVA_SENTENCE;
+  assert.strictEqual(process.env.MVA_SENTENCE, undefined);
+
+  let observedCtx = null;
+  let envAtCall = null;
+  const agentDef = mkAgent('inspector', async (ctx, _signal) => {
+    observedCtx = ctx;
+    envAtCall = process.env.MVA_SENTENCE;
+    return { status: 'ok', payload: { sha: ctx.sentence_sha256 } };
+  });
+  const results = await dispatchToArray([agentDef], 'sha_xyz_789');
+  assert.strictEqual(results.length, 1);
+  assert.strictEqual(results[0].status, 'ok');
+  assert.strictEqual(results[0].payload.sha, 'sha_xyz_789');
+
+  // Forbidden keys: must NOT be present.
+  assert.ok(observedCtx, 'agent must have observed ctx');
+  assert.strictEqual(observedCtx.sentence_sha256, 'sha_xyz_789');
+  assert.strictEqual(observedCtx.sentence, undefined);
+  assert.strictEqual(observedCtx.prompt, undefined);
+  assert.strictEqual(observedCtx.raw_sentence, undefined);
+  assert.strictEqual(observedCtx.raw_text, undefined);
+
+  // Env escape hatch must NOT exist during dispatch.
+  assert.strictEqual(envAtCall, undefined);
+
+  // Post-condition: env still clean.
+  assert.strictEqual(process.env.MVA_SENTENCE, undefined);
+});
+
+test('mva-dispatcher: Test 7 -- all-fail returns N error/timeout results (B7 fallback path)', async () => {
+  const agents = Array.from({ length: 6 }, (_, i) =>
+    mkAgent(`agent_${i}`, async () => { throw new Error('forced fail'); })
+  );
+  const results = await dispatchToArray(agents, 'sha_abc');
+  assert.strictEqual(results.length, 6);
+  for (const r of results) {
+    assert.strictEqual(r.status, 'error');
+    assert.strictEqual(r.error, 'forced fail');
+  }
+  // The dispatcher MUST NOT throw on all-fail. Plan 118-03 renderer reads
+  // the results array and decides the sharp-question fallback when every
+  // status is non-ok.
+});
+
+test('mva-dispatcher: Test 8 -- per-agent throw does not crash sibling agents', async () => {
+  const agents = [
+    mkAgent('thrower', async () => { throw new Error('boom'); }),
+    mkAgent('happy_1', async () => ({ status: 'ok', payload: 'h1' })),
+    mkAgent('happy_2', async () => ({ status: 'ok', payload: 'h2' }))
+  ];
+  const results = await dispatchToArray(agents, 'sha_abc');
+  assert.strictEqual(results.length, 3);
+  const byId = Object.fromEntries(results.map((r) => [r.agent_id, r]));
+  assert.strictEqual(byId.thrower.status, 'error');
+  assert.strictEqual(byId.happy_1.status, 'ok');
+  assert.strictEqual(byId.happy_2.status, 'ok');
+});

package/lib/core/mva-option-router.cjs

@@ -0,0 +1,292 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 118-05 Plan 05 -- mva-option-router.
+ *
+ * Routes the user's selection from the 3-option footer that renders after the
+ * 30-second MVA brief (per binding decision B4 + Canon Part 3 verbs 7/8/5).
+ *
+ * Option 1 -> stay_in_just_talk (Canon verb 7 Synthesize): operator transitions
+ *             to JUST_TALK; the brief stays in scrollback; user can ask any
+ *             follow-up.
+ * Option 2 -> phase_119_stub (Canon verb 8 Bank Opportunity, deferred): surfaces
+ *             the STUB_MESSAGE_119 verbatim per binding decision B6 OPTION A.
+ *             Does NOT invoke /mos:new-project (that wiring lands in Phase 119
+ *             v1.13.0-beta.18).
+ * Option 3 -> invoke_challenge_assumptions (Canon verb 5 Devil's Advocate):
+ *             operator transitions to METHODOLOGY; the wrapper invokes
+ *             /mos:challenge-assumptions --from-brief <sha8>.
+ *
+ * CRITICAL-3 part 2 wire:
+ *   resolveCurrentSha8() reads ~/.mindrian/mva/state.json (the manifest written
+ *   atomically by Plan 118-03 orchestrator after mva_brief_rendered emission)
+ *   and returns the latest sha8 -- or null if the manifest is absent (fresh
+ *   install / Hebrew refusal short-circuit). The /mos:mva-option command
+ *   wrapper uses this to auto-discover the most recent brief when the user
+ *   types `1`, `2`, or `3` without an explicit sha argument.
+ *
+ * Canon Part 8 invariants:
+ *   - This module reads only sentence_sha256 (one-way hash) + agent payload
+ *     scalars from the side-file. It NEVER reads .sentence, .raw_sentence,
+ *     .prompt, or any free-text source string.
+ *   - Telemetry payload carries ONLY sentence_sha256 + option_id +
+ *     time_to_click_ms. No content. No URLs.
+ *   - mva_option_selected event uses the ALLOWED_FIELDS frozen schema from
+ *     mva-telemetry.cjs; validation rejects unknown fields and over-long
+ *     strings.
+ *
+ * Em-dash invariant:
+ *   STUB_MESSAGE_119 + OPTION_BEHAVIOR narratives use `--`, NEVER `—`. Test 7
+ *   asserts the rendered text; Test 16 asserts both the command markdown and
+ *   the skill markdown.
+ *
+ * Hermetic test isolation:
+ *   All paths are derived from process.env.HOME via _home() at call time, so
+ *   tests can mkdtempSync a fresh HOME, swap process.env.HOME, and verify the
+ *   side-file / state.json / telemetry surfaces independently.
+ *
+ * Pure CJS, node built-ins only. Zero new runtime dependencies.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const { transitionViaMVAOption } = require('../conversation/operator.cjs');
+const telemetry = require('./mva-telemetry.cjs');
+
+// ---------- Frozen strings ----------
+
+// Per binding decision B6 OPTION A (verbatim text). Em-dash-free.
+const STUB_MESSAGE_119 = [
+  'Building a room around this is the next layer; shipping in beta.18 (Phase 119).',
+  'For now, press option 1 to keep this brief visible, or option 3 to go deeper.',
+].join('\n');
+
+const OPTION_BEHAVIOR = Object.freeze({
+  1: Object.freeze({
+    action: 'stay_in_just_talk',
+    next_operator: 'JUST_TALK',
+    canon_verb: 7, // Synthesize
+    narrative: 'Keeping the brief in scrollback. Ask me anything about what you just saw.',
+  }),
+  2: Object.freeze({
+    action: 'phase_119_stub',
+    next_operator: null,
+    canon_verb: 8, // Bank Opportunity (deferred)
+    narrative: STUB_MESSAGE_119,
+  }),
+  3: Object.freeze({
+    action: 'invoke_challenge_assumptions',
+    next_operator: 'METHODOLOGY',
+    canon_verb: 5, // Devil's Advocate
+    narrative: "Going deeper. Pulling the brief into a Devil's Advocate pass.",
+  }),
+});
+
+// ---------- Path resolvers (env-aware for hermetic testing) ----------
+
+function _home() {
+  return process.env.HOME || process.env.USERPROFILE || os.homedir();
+}
+
+function _statePath() {
+  return path.join(_home(), '.mindrian', 'mva', 'state.json');
+}
+
+function _sideFilePath(sha8) {
+  return path.join(_home(), '.mindrian', 'mva', 'briefs', sha8 + '.json');
+}
+
+function _telemetryFilePath() {
+  return path.join(_home(), '.mindrian', 'telemetry', 'v1.13', 'mva.jsonl');
+}
+
+// ---------- CRITICAL-3 part 2 wire: resolveCurrentSha8 ----------
+
+/**
+ * resolveCurrentSha8() -> string | null
+ *
+ * Reads ~/.mindrian/mva/state.json (the manifest written atomically by Plan
+ * 118-03 orchestrator after mva_brief_rendered emission) and returns the
+ * `current_sha8` field. Returns null when:
+ *   - state.json does not exist (fresh install OR Hebrew refusal short-circuit)
+ *   - state.json is unreadable or invalid JSON
+ *   - current_sha8 is missing or not a string
+ *
+ * Staleness is NOT enforced here -- the caller (router or wrapper) can choose
+ * to compare rendered_at_ms against an expiration threshold and surface a
+ * "brief expired" message. This function's only job is to return the most
+ * recent known sha8 from the manifest.
+ */
+function resolveCurrentSha8() {
+  try {
+    const p = _statePath();
+    if (!fs.existsSync(p)) return null;
+    const raw = fs.readFileSync(p, 'utf8');
+    const manifest = JSON.parse(raw);
+    if (manifest && typeof manifest.current_sha8 === 'string' && manifest.current_sha8.length > 0) {
+      return manifest.current_sha8;
+    }
+    return null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// ---------- Internal helpers ----------
+
+function _readSideFile(sha8) {
+  try {
+    const p = _sideFilePath(sha8);
+    if (!fs.existsSync(p)) return null;
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Find the most recent mva_brief_rendered event for the given sentence_sha256
+ * in ~/.mindrian/telemetry/v1.13/mva.jsonl. Returns the parsed event object
+ * or null if none found.
+ */
+function _readLastBriefRenderedEvent(sentenceSha256) {
+  try {
+    const p = _telemetryFilePath();
+    if (!fs.existsSync(p)) return null;
+    const text = fs.readFileSync(p, 'utf8').trim();
+    if (!text) return null;
+    const lines = text.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+      if (!lines[i]) continue;
+      let evt;
+      try { evt = JSON.parse(lines[i]); } catch (_) { continue; }
+      if (evt.event === 'mva_brief_rendered' && evt.sentence_sha256 === sentenceSha256) {
+        return evt;
+      }
+    }
+    return null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// ---------- Public: routeOption ----------
+
+/**
+ * routeOption(optionId, sha8, opts?) -> Promise<{
+ *   ok: boolean,
+ *   action?: 'stay_in_just_talk' | 'phase_119_stub' | 'invoke_challenge_assumptions',
+ *   message?: string,
+ *   next_state?: string | null,
+ *   time_to_click_ms?: number,
+ *   invoke_command?: string,    // option 3 only
+ *   error?: string,             // on failure
+ *   no_transition?: boolean,
+ *   reason?: string
+ * }>
+ *
+ * opts:
+ *   roomDir: filesystem path used by transitionViaMVAOption for operator state
+ *            (defaults to process.cwd())
+ *
+ * Validation order (matches Test 4 / Test 5 / Test 8 expectations):
+ *   1. optionId in {1, 2, 3} else -> invalid_option (no I/O, no telemetry)
+ *   2. side-file present for sha8 else -> brief_not_found (no telemetry)
+ *   3. mva_brief_rendered event present for the brief's sha256 else ->
+ *      brief_still_rendering (no telemetry; OQ16 lean)
+ *   4. compute time_to_click_ms from (now - mva_brief_rendered.timestamp)
+ *   5. transition operator via transitionViaMVAOption(roomDir, optionId)
+ *   6. emit mva_option_selected telemetry (sentence_sha256 + option_id +
+ *      time_to_click_ms; ALLOWED_FIELDS-validated by mva-telemetry)
+ *   7. return action + message + next_state (+ invoke_command on option 3)
+ */
+async function routeOption(optionId, sha8, opts) {
+  opts = opts || {};
+
+  // (1) Strict option validation -- runs BEFORE any I/O so invalid options
+  //     are cheap to reject and never emit telemetry.
+  if (!Number.isInteger(optionId) || ![1, 2, 3].includes(optionId)) {
+    return { ok: false, error: 'invalid_option', valid_options: [1, 2, 3] };
+  }
+
+  // (2) Side-file lookup.
+  if (typeof sha8 !== 'string' || sha8.length === 0) {
+    return {
+      ok: false,
+      error: 'brief_not_found',
+      message: 'The brief data has expired or was not deployed. Type your sentence again to re-fire the pipeline.',
+    };
+  }
+  const brief = _readSideFile(sha8);
+  if (!brief || typeof brief.sha256 !== 'string') {
+    return {
+      ok: false,
+      error: 'brief_not_found',
+      message: 'The brief data has expired or was not deployed. Type your sentence again to re-fire the pipeline.',
+    };
+  }
+
+  // (3) mva_brief_rendered lookup (the "is the brief done streaming?" signal).
+  const lastRendered = _readLastBriefRenderedEvent(brief.sha256);
+  if (!lastRendered || !lastRendered.timestamp) {
+    return {
+      ok: false,
+      error: 'brief_still_rendering',
+      message: 'Brief is still rendering -- options will activate when it completes.',
+    };
+  }
+
+  // (4) Compute time-to-click.
+  const renderedAtMs = new Date(lastRendered.timestamp).getTime();
+  const nowMs = Date.now();
+  const time_to_click_ms = Math.max(0, nowMs - renderedAtMs);
+
+  // (5) Operator transition. transitionViaMVAOption handles the per-option
+  //     rules (1 -> JUST_TALK, 2 -> no-op, 3 -> METHODOLOGY).
+  const roomDir = typeof opts.roomDir === 'string' ? opts.roomDir : process.cwd();
+  const transitionResult = transitionViaMVAOption(roomDir, optionId);
+
+  // (6) Telemetry. Best-effort: telemetry.emit() validates against
+  //     ALLOWED_FIELDS.mva_option_selected and writes JSONL to
+  //     ~/.mindrian/telemetry/v1.13/mva.jsonl. Validation throws (so we
+  //     cannot leak invalid payloads); disk failures are swallowed by emit().
+  try {
+    telemetry.emit('mva_option_selected', {
+      sentence_sha256: brief.sha256,
+      option_id: optionId,
+      time_to_click_ms: time_to_click_ms,
+    });
+  } catch (_) {
+    // Validation error here would be a programming bug (we control the
+    // payload shape). Swallow to keep the user-facing flow intact; the
+    // test harness will surface the issue.
+  }
+
+  // (7) Build response.
+  const behavior = OPTION_BEHAVIOR[optionId];
+  const out = {
+    ok: true,
+    action: behavior.action,
+    message: behavior.narrative,
+    next_state: transitionResult && transitionResult.ok ? (transitionResult.new_state || null) : null,
+    time_to_click_ms: time_to_click_ms,
+  };
+  if (transitionResult && transitionResult.no_transition) {
+    out.no_transition = true;
+    out.reason = transitionResult.reason;
+  }
+  if (optionId === 3) {
+    out.invoke_command = '/mos:challenge-assumptions --from-brief ' + sha8;
+  }
+  return out;
+}
+
+module.exports = {
+  routeOption,
+  resolveCurrentSha8,
+  OPTION_BEHAVIOR,
+  STUB_MESSAGE_119,
+};