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

package/lib/core/mva-agent-contract.cjs

@@ -0,0 +1,170 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 118-01 Plan 01 Task 1 -- mva-agent-contract.
+ *
+ * The AgentResult shape + the runAgent wrapper used by mva-dispatcher.cjs
+ * (Task 3 of this plan). Plan 118-02 implements 6 specific agents against
+ * the Agent contract documented below.
+ *
+ * AgentContext interface
+ * ----------------------
+ *   {
+ *     sentence_sha256: string,        // dispatcher-provided -- ONLY identifier passed to agents
+ *     remaining_budget_ms: number,    // dispatcher-provided
+ *   }
+ *
+ *   raw_sentence is NEVER exposed to agents (Canon Part 8 hard invariant).
+ *   Agents that need linguistic features must derive them from neighborhood-graph
+ *   queries against room.db (sentence-sha8 only), NOT from the raw sentence string.
+ *
+ *   process.env.MVA_SENTENCE is NEVER set. There is no escape hatch.
+ *
+ * Agent function signature
+ * ------------------------
+ *   async function agent(context, signal) -> { status: 'ok'|'empty', payload } | null
+ *
+ *   If the agent throws, runAgent wraps with status='error'.
+ *   If the AbortSignal fires before resolve, runAgent wraps with status='timeout'.
+ *   If the agent returns null, runAgent wraps with status='empty'.
+ *
+ * Pure CJS, node built-ins only, zero new runtime dependencies.
+ * Canon Part 8 invariants:
+ *   - NEVER serialize stack traces (stack traces can contain user content).
+ *   - Error messages capped at 200 chars (sliced to prevent user-content blow-through).
+ *   - The AgentContext object passed to the agent contains ONLY documented keys.
+ */
+'use strict';
+
+const ALLOWED_STATUSES = new Set(['ok', 'empty', 'error', 'timeout']);
+
+/**
+ * AGENT_RESULT_SHAPE -- a frozen object documenting the AgentResult shape.
+ *
+ * AgentResult = {
+ *   agent_id: string,                                 // 'brain_similar' | ... | 'dashboard_graph'
+ *   status: 'ok' | 'empty' | 'error' | 'timeout',
+ *   duration_ms: number,                              // wall-clock from runAgent invocation
+ *   payload?: any,                                    // agent-specific; opaque to dispatcher
+ *   error?: string,                                   // sanitized message (<= 200 chars)
+ * };
+ */
+const AGENT_RESULT_SHAPE = Object.freeze({
+  agent_id: 'string',
+  status: "'ok' | 'empty' | 'error' | 'timeout'",
+  duration_ms: 'number >= 0',
+  payload: 'optional any',
+  error: 'optional string'
+});
+
+/**
+ * validateAgentResult -- returns true if the result conforms to AgentResult shape.
+ *
+ * @param {unknown} result
+ * @returns {boolean}
+ */
+function validateAgentResult(result) {
+  if (!result || typeof result !== 'object') return false;
+  if (typeof result.agent_id !== 'string' || result.agent_id.length === 0) return false;
+  if (typeof result.status !== 'string' || !ALLOWED_STATUSES.has(result.status)) return false;
+  if (typeof result.duration_ms !== 'number' || result.duration_ms < 0) return false;
+  return true;
+}
+
+/**
+ * Sanitize an error into a short message. Drops stack traces, drops object
+ * properties, slices to 200 chars to prevent any user-content blow-through.
+ *
+ * @param {unknown} err
+ * @returns {string}
+ */
+function sanitizeError(err) {
+  let msg;
+  if (err && typeof err === 'object' && typeof err.message === 'string') {
+    msg = err.message;
+  } else {
+    msg = String(err);
+  }
+  return msg.slice(0, 200);
+}
+
+/**
+ * runAgent -- invoke an agent function under an AbortController timeout. Catches
+ * any throw and converts to a structured AgentResult.
+ *
+ * @param {{ id: string, fn: Function }} agentDef
+ * @param {{ sentence_sha256: string }} context
+ * @param {{ timeoutMs?: number }} opts
+ * @returns {Promise<{ agent_id: string, status: string, duration_ms: number, payload?: any, error?: string }>}
+ */
+async function runAgent(agentDef, context, opts) {
+  const timeoutMs = (opts && typeof opts.timeoutMs === 'number') ? opts.timeoutMs : 35000;
+  const t0 = Date.now();
+  const controller = new AbortController();
+
+  // Build an AgentContext containing ONLY documented keys. We do not spread
+  // arbitrary caller props (defense-in-depth against accidental raw_sentence
+  // leakage). Canon Part 8 invariant.
+  const agentContext = {
+    sentence_sha256: context && context.sentence_sha256,
+    remaining_budget_ms: timeoutMs
+  };
+
+  let timer;
+  const timeoutPromise = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      reject(new Error('__mva_dispatcher_timeout__'));
+    }, timeoutMs);
+  });
+
+  try {
+    const result = await Promise.race([
+      Promise.resolve().then(() => agentDef.fn(agentContext, controller.signal)),
+      timeoutPromise
+    ]);
+
+    if (timer) clearTimeout(timer);
+
+    const duration_ms = Date.now() - t0;
+
+    if (result === null || result === undefined) {
+      return { agent_id: agentDef.id, status: 'empty', duration_ms };
+    }
+
+    // Result is { status: 'ok' | 'empty', payload }.
+    if (result && typeof result === 'object' && typeof result.status === 'string') {
+      if (result.status === 'ok' || result.status === 'empty') {
+        return {
+          agent_id: agentDef.id,
+          status: result.status,
+          duration_ms,
+          payload: result.payload
+        };
+      }
+    }
+
+    // Unknown shape -- treat as empty (defense-in-depth; agent contract violation).
+    return { agent_id: agentDef.id, status: 'empty', duration_ms };
+  } catch (err) {
+    if (timer) clearTimeout(timer);
+    const duration_ms = Date.now() - t0;
+
+    if (controller.signal.aborted) {
+      return { agent_id: agentDef.id, status: 'timeout', duration_ms };
+    }
+
+    return {
+      agent_id: agentDef.id,
+      status: 'error',
+      duration_ms,
+      error: sanitizeError(err)
+    };
+  }
+}
+
+module.exports = {
+  runAgent,
+  validateAgentResult,
+  AGENT_RESULT_SHAPE
+};

package/lib/core/mva-agent-contract.test.cjs

@@ -0,0 +1,169 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 118-01 Plan 01 Task 1 -- mva-agent-contract tests.
+ *
+ * Tests the AgentResult shape, validateAgentResult, and runAgent wrapper.
+ * Per Canon Part 8 (Graph Boundary): AgentContext NEVER carries raw sentence;
+ * the only sentence-derived field is sentence_sha256. There is no escape hatch
+ * via process.env.MVA_SENTENCE.
+ *
+ * Pure CJS, node built-ins only. Run via `node --test`.
+ */
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert');
+
+const {
+  runAgent,
+  validateAgentResult,
+  AGENT_RESULT_SHAPE
+} = require('./mva-agent-contract.cjs');
+
+test('mva-agent-contract: Test 1 -- agent returns ok wraps result', async () => {
+  const agentDef = {
+    id: 'test',
+    fn: async (_ctx, _signal) => ({ status: 'ok', payload: { x: 1 } })
+  };
+  const result = await runAgent(
+    agentDef,
+    { sentence_sha256: 'abc123' },
+    { timeoutMs: 1000 }
+  );
+  assert.strictEqual(result.agent_id, 'test');
+  assert.strictEqual(result.status, 'ok');
+  assert.deepStrictEqual(result.payload, { x: 1 });
+  assert.strictEqual(typeof result.duration_ms, 'number');
+  assert.ok(result.duration_ms >= 0);
+});
+
+test('mva-agent-contract: Test 2 -- agent throws becomes error result', async () => {
+  const agentDef = {
+    id: 'test',
+    fn: async (_ctx, _signal) => { throw new Error('boom'); }
+  };
+  const result = await runAgent(
+    agentDef,
+    { sentence_sha256: 'abc123' },
+    { timeoutMs: 1000 }
+  );
+  assert.strictEqual(result.agent_id, 'test');
+  assert.strictEqual(result.status, 'error');
+  assert.strictEqual(result.error, 'boom');
+  assert.ok(!('stack' in result), 'result must never carry stack');
+  assert.strictEqual(typeof result.duration_ms, 'number');
+});
+
+test('mva-agent-contract: Test 3 -- agent returns null becomes empty', async () => {
+  const agentDef = {
+    id: 'test',
+    fn: async (_ctx, _signal) => null
+  };
+  const result = await runAgent(
+    agentDef,
+    { sentence_sha256: 'abc123' },
+    { timeoutMs: 1000 }
+  );
+  assert.strictEqual(result.agent_id, 'test');
+  assert.strictEqual(result.status, 'empty');
+  assert.strictEqual(typeof result.duration_ms, 'number');
+});
+
+test('mva-agent-contract: Test 4 -- agent exceeds timeout returns timeout', async () => {
+  const agentDef = {
+    id: 'test',
+    fn: async (_ctx, signal) => {
+      await new Promise((resolve, reject) => {
+        const t = setTimeout(resolve, 500);
+        signal.addEventListener('abort', () => {
+          clearTimeout(t);
+          reject(new Error('aborted'));
+        });
+      });
+      return { status: 'ok', payload: {} };
+    }
+  };
+  const t0 = Date.now();
+  const result = await runAgent(
+    agentDef,
+    { sentence_sha256: 'abc123' },
+    { timeoutMs: 100 }
+  );
+  const elapsed = Date.now() - t0;
+  assert.strictEqual(result.agent_id, 'test');
+  assert.strictEqual(result.status, 'timeout');
+  assert.ok(elapsed < 300, `elapsed ${elapsed} must be under 300ms`);
+  assert.ok(result.duration_ms >= 90, `duration_ms ${result.duration_ms} should be ~100`);
+});
+
+test('mva-agent-contract: Test 5 -- agent receives both args, signal observed', async () => {
+  let observedSignalAbortedAtStart = null;
+  let observedSignalAbortedAtEnd = null;
+  let observedSha = null;
+  let observedRemaining = null;
+  const agentDef = {
+    id: 'test',
+    fn: async (ctx, signal) => {
+      observedSignalAbortedAtStart = signal.aborted;
+      observedSha = ctx.sentence_sha256;
+      observedRemaining = ctx.remaining_budget_ms;
+      // Wait long enough to be cancelled
+      await new Promise((resolve, reject) => {
+        const t = setTimeout(resolve, 500);
+        signal.addEventListener('abort', () => {
+          clearTimeout(t);
+          observedSignalAbortedAtEnd = signal.aborted;
+          reject(new Error('aborted'));
+        });
+      });
+      return { status: 'ok', payload: {} };
+    }
+  };
+  const result = await runAgent(
+    agentDef,
+    { sentence_sha256: 'def456' },
+    { timeoutMs: 100 }
+  );
+  assert.strictEqual(observedSignalAbortedAtStart, false, 'signal must start non-aborted');
+  assert.strictEqual(observedSignalAbortedAtEnd, true, 'signal must be aborted on timeout');
+  assert.strictEqual(observedSha, 'def456');
+  assert.strictEqual(observedRemaining, 100);
+  assert.strictEqual(result.status, 'timeout');
+});
+
+test('mva-agent-contract: Test 6 -- validateAgentResult', () => {
+  assert.strictEqual(
+    validateAgentResult({ agent_id: 'x', status: 'ok', duration_ms: 10 }),
+    true
+  );
+  assert.strictEqual(
+    validateAgentResult({ agent_id: 'x', status: 'empty', duration_ms: 10 }),
+    true
+  );
+  assert.strictEqual(
+    validateAgentResult({ agent_id: 'x', status: 'error', duration_ms: 10, error: 'e' }),
+    true
+  );
+  assert.strictEqual(
+    validateAgentResult({ agent_id: 'x', status: 'timeout', duration_ms: 10 }),
+    true
+  );
+  assert.strictEqual(validateAgentResult(null), false);
+  assert.strictEqual(validateAgentResult({}), false);
+  assert.strictEqual(validateAgentResult({ status: 'ok', duration_ms: 10 }), false);
+  assert.strictEqual(validateAgentResult({ agent_id: 'x', duration_ms: 10 }), false);
+  assert.strictEqual(
+    validateAgentResult({ agent_id: 'x', status: 'invalid', duration_ms: 10 }),
+    false
+  );
+  assert.strictEqual(
+    validateAgentResult({ agent_id: 'x', status: 'ok', duration_ms: -1 }),
+    false
+  );
+  assert.strictEqual(
+    validateAgentResult({ agent_id: 'x', status: 'ok' }),
+    false
+  );
+  assert.ok(AGENT_RESULT_SHAPE, 'shape doc must be exported');
+});

package/lib/core/mva-budget.cjs

@@ -0,0 +1,75 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 118-01 Plan 01 Task 2 -- mva-budget.
+ *
+ * Global wall-clock budget tracker used by mva-dispatcher.cjs. Per binding
+ * decision B2 (HARD):
+ *   GLOBAL_BUDGET_MS = 45000   (the hard 30-Second-MVA cap; named for the
+ *                               sharp-question fallback window per source spec
+ *                               line 113 -- "Hard budget: 45 seconds maximum")
+ *   PER_AGENT_CAP_MS = 35000   (each agent gets at most 35s OR remaining
+ *                               global, whichever is less -- source spec
+ *                               line 123 -- "Agents return structured JSON
+ *                               within 35s budget each")
+ *
+ * The dispatcher creates ONE budget per dispatch call. Each agent's per-agent
+ * abort signal feeds from this budget via perAgentMs(): min(35000, remainingMs()).
+ *
+ * Pure CJS, leaf module -- no dependencies on any other lib/core file.
+ * Canon Part 8: this module touches NO user content; it is wall-clock math only.
+ */
+'use strict';
+
+const GLOBAL_BUDGET_MS = 45000;
+const PER_AGENT_CAP_MS = 35000;
+
+/**
+ * Create a wall-clock budget tracker.
+ *
+ * @param {number} [globalBudgetMs=45000]
+ * @returns {{
+ *   startedAt: number,
+ *   globalBudgetMs: number,
+ *   remainingMs: () => number,
+ *   perAgentMs: (cap?: number) => number,
+ *   isExpired: () => boolean,
+ *   elapsedMs: () => number,
+ * }}
+ */
+function createBudget(globalBudgetMs) {
+  const cap = (typeof globalBudgetMs === 'number') ? globalBudgetMs : GLOBAL_BUDGET_MS;
+  const startedAt = Date.now();
+
+  function remainingMs() {
+    return Math.max(0, cap - (Date.now() - startedAt));
+  }
+
+  function perAgentMs(perAgentCapMs) {
+    const requested = (typeof perAgentCapMs === 'number') ? perAgentCapMs : PER_AGENT_CAP_MS;
+    return Math.max(0, Math.min(requested, remainingMs()));
+  }
+
+  function isExpired() {
+    return remainingMs() === 0;
+  }
+
+  function elapsedMs() {
+    return Date.now() - startedAt;
+  }
+
+  return {
+    startedAt,
+    globalBudgetMs: cap,
+    remainingMs,
+    perAgentMs,
+    isExpired,
+    elapsedMs
+  };
+}
+
+module.exports = {
+  createBudget,
+  GLOBAL_BUDGET_MS,
+  PER_AGENT_CAP_MS
+};

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

@@ -0,0 +1,68 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 118-01 Plan 01 Task 2 -- mva-budget tests.
+ *
+ * Per binding decision B2 (HARD):
+ *   45-second global wall-clock budget + 35-second per-agent budget.
+ *   Per-agent abort signal feeds from the global deadline: each agent gets
+ *   min(35s, remaining_global_budget).
+ *
+ * Pure CJS, node built-ins only. Run via `node --test`.
+ */
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert');
+
+const {
+  createBudget,
+  GLOBAL_BUDGET_MS,
+  PER_AGENT_CAP_MS
+} = require('./mva-budget.cjs');
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+test('mva-budget: Test 1 -- remaining decreases over time', async () => {
+  const budget = createBudget(45000);
+  const r0 = budget.remainingMs();
+  assert.ok(r0 >= 44990 && r0 <= 45000, `expected ~45000, got ${r0}`);
+  await sleep(100);
+  const r1 = budget.remainingMs();
+  // Allow generous slop for slow CI / GC pauses.
+  assert.ok(r1 >= 44800 && r1 <= 44910, `expected ~44900, got ${r1}`);
+});
+
+test('mva-budget: Test 2 -- default globalBudgetMs is 45000', () => {
+  const budget = createBudget();
+  const r = budget.remainingMs();
+  assert.ok(r >= 44990 && r <= 45000, `expected ~45000, got ${r}`);
+  assert.strictEqual(budget.globalBudgetMs, 45000);
+});
+
+test('mva-budget: Test 3 -- perAgentMs returns 35000 when remaining is 45000', () => {
+  const budget = createBudget(45000);
+  assert.strictEqual(budget.perAgentMs(35000), 35000);
+});
+
+test('mva-budget: Test 4 -- perAgentMs caps at remaining', async () => {
+  const budget = createBudget(200);
+  await sleep(150);
+  const cap = budget.perAgentMs(180);
+  // remaining is ~50; perAgentCap 180 -> min(180, 50) = ~50
+  assert.ok(cap >= 0 && cap <= 80, `expected ~50, got ${cap}`);
+  assert.ok(cap < 180, 'must NOT return 180 when remaining is lower');
+});
+
+test('mva-budget: Test 5 -- isExpired flips true after globalBudgetMs', async () => {
+  const budget = createBudget(80);
+  assert.strictEqual(budget.isExpired(), false);
+  await sleep(120);
+  assert.strictEqual(budget.isExpired(), true);
+  assert.strictEqual(budget.remainingMs(), 0);
+});
+
+test('mva-budget: Test 6 -- exported constants', () => {
+  assert.strictEqual(GLOBAL_BUDGET_MS, 45000);
+  assert.strictEqual(PER_AGENT_CAP_MS, 35000);
+});