heyspex 0.1.0

package/vendor/heyspex-mcp/seat-identity.mjs

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+// Dev-factory seat identity resolution for the HeySpex MCP server.
+//
+// The MCP server is the one point EVERY caller passes through (Claude Code,
+// Cursor, or a spawned fleet worker). This module resolves which dev-factory
+// seat a caller holds so the server can surface that seat's mandate on connect —
+// moving seat identity from Claude-Code-only (the SessionStart hook) to
+// universal. Owning epic: [[HS-CXO0-EPIC-seat-identity-surfaced-to-every-caller-f]].
+//
+// Source of truth for seats: dev-factory/seats.json (read off the MCP vaultRoot).
+// Fail-silent contract (mirror scripts/claude-hooks/inject-coo-seat.mjs): a
+// missing/corrupt registry, or an unknown caller, resolves to null — inject
+// nothing, never throw.
+//
+// The deterministic gate for this module is its own `--self-test` (run via
+// `node dev-factory/controller.mjs --self-test-gate`). The assertions below ARE
+// the acceptance criteria made executable — the Builder seat implements the
+// three function bodies until every case passes.
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Read and parse <vaultRoot>/dev-factory/seats.json.
+ * @returns {{settings?: object, seats?: Array}|null} parsed registry, or null on
+ *   missing file / parse error (fail-silent — never throws).
+ */
+export function readSeatsRegistry(vaultRoot) {
+  try {
+    const seatsPath = path.join(vaultRoot, "dev-factory", "seats.json");
+    const raw = readFileSync(seatsPath, "utf8");
+    return JSON.parse(raw);
+  } catch (err) {
+    // Fail-silent as per brief.
+    return null;
+  }
+}
+
+/**
+ * Resolve the active dev-factory seat for a caller. Pure — no filesystem.
+ * @param {{agent?: string, sessionId?: string}} identity
+ * @param {{registry?: object, env?: object}} opts  registry from readSeatsRegistry; env bag
+ * @returns {object|null} the matching ACTIVE seat object augmented with a
+ *   `resolvedVia` string, or null when nothing matches / seat inactive / no registry.
+ *
+ * Precedence (first match wins):
+ *   1. env.HEYSPEX_SEAT        — exact seat id (case-insensitive)      → resolvedVia "env:HEYSPEX_SEAT"
+ *   2. env.HEYSPEX_FLEET_ROLE  — builder|build→build, critic→critic,
+ *                                breakdown→breakdown, expand→expand,
+ *                                else the value as a seat id           → resolvedVia "env:HEYSPEX_FLEET_ROLE"
+ *   3. env.HEYSPEX_COO_WINDOW  — truthy ("1"/"true") → seat id "coo"   → resolvedVia "env:HEYSPEX_COO_WINDOW"
+ *   4. agent starts with "Claude"/"Cursor" → seat id "coo"            → resolvedVia "agent-default"
+ *      otherwise → null
+ * A matched seat is only returned when seat.active === true; else null.
+ */
+export function resolveSeat(identity = {}, opts = {}) {
+  const { agent = "", sessionId = "" } = identity;
+  const { registry, env = {} } = opts;
+
+  if (!registry || !Array.isArray(registry.seats)) return null;
+
+  // 1. env.HEYSPEX_SEAT — exact seat id (case-insensitive)
+  if (env.HEYSPEX_SEAT) {
+    const seatId = env.HEYSPEX_SEAT.toLowerCase();
+    const seat = registry.seats.find((s) => s.id.toLowerCase() === seatId);
+    if (seat && seat.active)
+      return { ...seat, resolvedVia: "env:HEYSPEX_SEAT" };
+  }
+
+  // 2. env.HEYSPEX_FLEET_ROLE
+  if (env.HEYSPEX_FLEET_ROLE) {
+    const role = env.HEYSPEX_FLEET_ROLE.toLowerCase();
+    let seatId;
+    switch (role) {
+      case "builder":
+        seatId = "build";
+        break;
+      case "critic":
+        seatId = "critic";
+        break;
+      case "breakdown":
+        seatId = "breakdown";
+        break;
+      case "expand":
+        seatId = "expand";
+        break;
+      default:
+        seatId = role; // treat as literal seat id
+    }
+    const seat = registry.seats.find((s) => s.id === seatId);
+    if (seat && seat.active)
+      return { ...seat, resolvedVia: "env:HEYSPEX_FLEET_ROLE" };
+  }
+
+  // 3. env.HEYSPEX_COO_WINDOW — truthy → "coo"
+  if (
+    env.HEYSPEX_COO_WINDOW &&
+    ["1", "true"].includes(env.HEYSPEX_COO_WINDOW)
+  ) {
+    const seat = registry.seats.find((s) => s.id === "coo");
+    if (seat && seat.active)
+      return { ...seat, resolvedVia: "env:HEYSPEX_COO_WINDOW" };
+  }
+
+  // 4. agent default
+  if (agent.startsWith("Claude") || agent.startsWith("Cursor")) {
+    const seat = registry.seats.find((s) => s.id === "coo");
+    if (seat && seat.active) return { ...seat, resolvedVia: "agent-default" };
+  }
+
+  return null;
+}
+
+/**
+ * Convenience: read the registry off vaultRoot then resolve the seat.
+ * @returns {object|null}
+ */
+export function resolveSeatForCaller({
+  agent,
+  sessionId,
+  vaultRoot,
+  env = {},
+} = {}) {
+  const registry = readSeatsRegistry(vaultRoot);
+  return resolveSeat({ agent, sessionId }, { registry, env });
+}
+
+/**
+ * Render a resolved seat as a single-line identity banner for delivery to the
+ * caller — the same seat's OWN mandate, so a Builder worker sees "Builder" and a
+ * COO session sees "COO" (no cross-contamination). Pure; safe on any input.
+ * @param {object|null} seat a seat object (from resolveSeat), or null.
+ * @returns {string} `DEV-FACTORY SEAT: <title> — <mandate>`, or "" when nothing
+ *   resolves / the seat lacks a title (caller injects nothing).
+ */
+export function formatSeatBanner(seat) {
+  if (!seat || typeof seat !== "object" || typeof seat.title !== "string")
+    return "";
+  const mandate = typeof seat.mandate === "string" ? seat.mandate : "";
+  const suffix = mandate ? ` — ${mandate}` : "";
+  return `DEV-FACTORY SEAT: ${seat.title}${suffix}`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Deterministic gate — `node vendor/heyspex-mcp/seat-identity.mjs --self-test`
+// These assertions are the acceptance criteria. Do NOT weaken them.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const FIXTURE = {
+  settings: { cooMode: true },
+  seats: [
+    { id: "coo", title: "COO", active: true, mandate: "coo mandate" },
+    { id: "build", title: "Builder", active: true, mandate: "builder mandate" },
+    { id: "critic", title: "Critic", active: true, mandate: "critic mandate" },
+    {
+      id: "software-architect",
+      title: "Software Architect",
+      active: false,
+      mandate: "staged",
+    },
+  ],
+};
+
+function selfTest() {
+  const failures = [];
+  const check = (cond, label) => {
+    if (!cond) failures.push(label);
+  };
+
+  // Repo root is two dirs up from this file (vendor/heyspex-mcp/ → repo root).
+  const repoRoot = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "..",
+  );
+
+  // 1. Real registry smoke-read.
+  const real = readSeatsRegistry(repoRoot);
+  check(
+    real && Array.isArray(real.seats) && real.seats.length > 0,
+    "readSeatsRegistry reads real seats.json",
+  );
+
+  // 2. Missing registry → null (fail-silent).
+  check(
+    readSeatsRegistry(path.join(repoRoot, "no", "such", "dir")) === null,
+    "readSeatsRegistry missing → null",
+  );
+
+  // 3. Claude Code session, empty env → coo via agent-default.
+  const s3 = resolveSeat(
+    { agent: "Claude Code", sessionId: "s1" },
+    { registry: FIXTURE, env: {} },
+  );
+  check(
+    s3 && s3.id === "coo" && s3.resolvedVia === "agent-default",
+    "Claude Code + empty env → coo (agent-default)",
+  );
+
+  // 4. Fleet builder role → build, NOT coo (the core acceptance point).
+  const s4 = resolveSeat(
+    { agent: "", sessionId: "w1" },
+    { registry: FIXTURE, env: { HEYSPEX_FLEET_ROLE: "builder" } },
+  );
+  check(
+    s4 && s4.id === "build",
+    "HEYSPEX_FLEET_ROLE=builder → build (not coo)",
+  );
+
+  // 5. COO window env → coo.
+  const s5 = resolveSeat(
+    { agent: "", sessionId: "" },
+    { registry: FIXTURE, env: { HEYSPEX_COO_WINDOW: "1" } },
+  );
+  check(
+    s5 && s5.id === "coo" && s5.resolvedVia === "env:HEYSPEX_COO_WINDOW",
+    "HEYSPEX_COO_WINDOW=1 → coo",
+  );
+
+  // 6. HEYSPEX_SEAT override beats agent-default.
+  const s6 = resolveSeat(
+    { agent: "Claude Code", sessionId: "s" },
+    { registry: FIXTURE, env: { HEYSPEX_SEAT: "critic" } },
+  );
+  check(
+    s6 && s6.id === "critic" && s6.resolvedVia === "env:HEYSPEX_SEAT",
+    "HEYSPEX_SEAT=critic overrides agent-default",
+  );
+
+  // 7. Unknown external caller → null.
+  const s7 = resolveSeat(
+    { agent: "External agent", sessionId: "x" },
+    { registry: FIXTURE, env: {} },
+  );
+  check(s7 === null, "unknown external agent + empty env → null");
+
+  // 8. Inactive seat via HEYSPEX_SEAT → null (only active seats inject).
+  const s8 = resolveSeat(
+    { agent: "", sessionId: "" },
+    { registry: FIXTURE, env: { HEYSPEX_SEAT: "software-architect" } },
+  );
+  check(s8 === null, "inactive seat (software-architect) → null");
+
+  // 9. Null registry → null.
+  check(
+    resolveSeat({ agent: "Claude Code" }, { registry: null, env: {} }) === null,
+    "null registry → null",
+  );
+
+  // 10. formatSeatBanner renders the seat's OWN title + mandate (Builder ≠ COO).
+  const builderSeat = FIXTURE.seats.find((s) => s.id === "build");
+  check(
+    formatSeatBanner(builderSeat) === "DEV-FACTORY SEAT: Builder — builder mandate",
+    "formatSeatBanner renders the seat's own title + mandate",
+  );
+
+  // 11. formatSeatBanner on null / titleless → "" (inject nothing).
+  check(
+    formatSeatBanner(null) === "" && formatSeatBanner({ mandate: "x" }) === "",
+    "formatSeatBanner(null / titleless) → empty string",
+  );
+
+  if (failures.length > 0) {
+    console.error(`seat-identity --self-test: ${failures.length} FAILED:`);
+    for (const f of failures) console.error(`  ✗ ${f}`);
+    process.exit(1);
+  }
+  console.log("seat-identity --self-test: all 11 cases passed");
+  process.exit(0);
+}
+
+// isMain guard (mirrors dev-factory/lib/run-events.mjs): without it, any script that
+// imports this module while itself being run with --self-test (e.g. `node
+// coo-dispatcher.mjs --self-test` after HS-OJ5J wired seat resolution into the
+// dispatcher) would have ITS OWN self-test hijacked by this module's side effect on
+// import, since `process.argv` is shared across the whole process.
+const isMain = process.argv[1]?.replaceAll("\\", "/").endsWith("/seat-identity.mjs");
+if (isMain && process.argv.includes("--self-test")) {
+  selfTest();
+}

package/vendor/heyspex-mcp/settings-tools.mjs

@@ -0,0 +1,119 @@
+/**
+ * HeySpex settings MCP tools — the agent face over the settings core
+ * (config-settings.mjs), mounted in cli.mjs as:
+ *   - heyspex_settings_list  (read — open)
+ *   - heyspex_settings_get   (read — open)
+ *   - heyspex_settings_set   (WRITE — permission-gated two-step confirm)
+ *
+ * WRITE-PERMISSION GUARDRAIL (owner directive 2026-07-11, documented in
+ * specs/protocols/agent-settings-protocol.md): a settings write is a protected
+ * class. `heyspex_settings_set` without `confirm_token` never writes — it records
+ * the proposed change and returns `confirmation_required` plus a token; the agent
+ * must show the user the exact change (key, current → proposed) and obtain the
+ * user's explicit approval IN THEIR OWN WORDS before calling again with the token.
+ * This holds regardless of `agent_behaviors.ask_forgiveness_not_permission` — that
+ * switch governs autonomous behaviors, never its own controls. A PreToolUse gate
+ * (scripts/claude-hooks/settings-write-gate.mjs) additionally routes the confirm
+ * call through the harness permission prompt in Claude Code.
+ *
+ * Pattern source: procedure-tools.mjs (pure-logic execute* functions; cli.mjs wraps).
+ */
+
+import {
+  listConfigLeaves,
+  getConfigLeaf,
+  requestSettingsWrite,
+  confirmSettingsWrite,
+  validateSettingKey,
+  CONFIG_REL,
+} from './config-settings.mjs';
+
+const MCP_FACE = 'mcp';
+
+export function executeSettingsList(vaultRoot, args = {}) {
+  const prefix = typeof args.prefix === 'string' ? args.prefix.trim() : '';
+  let settings = listConfigLeaves(vaultRoot);
+  if (prefix) {
+    settings = settings.filter((s) => s.key === prefix || s.key.startsWith(prefix + '.'));
+  }
+  return {
+    ok: true,
+    config_file: CONFIG_REL.replace(/\\/g, '/'),
+    count: settings.length,
+    settings: settings.map(({ key, value }) => ({ key, value })),
+  };
+}
+
+export function executeSettingsGet(vaultRoot, args = {}) {
+  const key = typeof args.key === 'string' ? args.key.trim() : '';
+  const check = validateSettingKey(key);
+  if (!check.ok) return { ok: false, error: 'invalid_key', message: check.reason };
+  const leaf = getConfigLeaf(vaultRoot, key);
+  return {
+    ok: true,
+    key,
+    found: leaf.found,
+    value: leaf.found ? leaf.value : null,
+    ...(leaf.found ? {} : { note: 'Key absent from .heyspex/config.yaml — consumers fall back to their documented default.' }),
+  };
+}
+
+/** Coerce the `value` argument (which may arrive as a JSON scalar or a string). */
+function coerceValue(raw) {
+  if (raw === null || typeof raw === 'boolean' || typeof raw === 'number') return raw;
+  if (typeof raw !== 'string') return undefined;
+  const v = raw.trim();
+  if (v === 'null') return null;
+  if (v === 'true') return true;
+  if (v === 'false') return false;
+  if (/^-?\d+(\.\d+)?$/.test(v)) return Number(v);
+  return raw;
+}
+
+export function executeSettingsSet(vaultRoot, args = {}) {
+  const actor = typeof args.actor === 'string' && args.actor.trim() ? args.actor.trim() : 'agent (MCP)';
+
+  // Step 2 — confirm an already-reviewed change.
+  if (typeof args.confirm_token === 'string' && args.confirm_token.trim()) {
+    const result = confirmSettingsWrite(vaultRoot, {
+      token: args.confirm_token.trim(),
+      actor,
+      face: MCP_FACE,
+    });
+    if (!result.ok) return result;
+    return {
+      ok: true,
+      status: 'applied',
+      key: result.key,
+      previous: result.previous,
+      value: result.value,
+      created: result.created,
+      note: 'Setting applied and audited to .heyspex/settings-history.jsonl.',
+    };
+  }
+
+  // Step 1 — record the proposed change; nothing is written yet.
+  const key = typeof args.key === 'string' ? args.key.trim() : '';
+  const value = coerceValue(args.value);
+  if (value === undefined) {
+    return { ok: false, error: 'invalid_value', message: 'value must be a scalar (string, number, boolean, or null)' };
+  }
+  const req = requestSettingsWrite(vaultRoot, { key, value, actor, face: MCP_FACE });
+  if (!req.ok) return req;
+  return {
+    ok: true,
+    status: 'confirmation_required',
+    key: req.key,
+    current_value: req.current_found ? req.current_value : null,
+    current_found: req.current_found,
+    proposed_value: req.value,
+    confirm_token: req.token,
+    expires_at: req.expires_at,
+    instructions:
+      'NOTHING WAS WRITTEN. Settings writes require EXPLICIT user permission (this is independent of ' +
+      'ask_forgiveness_not_permission — that switch never governs its own controls). Show the user the exact ' +
+      `change — "${req.key}: ${JSON.stringify(req.current_found ? req.current_value : null)} → ${JSON.stringify(req.value)}" — ` +
+      'and ask for approval. ONLY after the user explicitly approves, call heyspex_settings_set again with ' +
+      'confirm_token to apply. If the user declines, drop it — do not retry or edit .heyspex/config.yaml directly.',
+  };
+}