@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/roles/event-bus.mjs

@@ -0,0 +1,79 @@
+/**
+ * lib/roles/event-bus.mjs — append-only event log at ~/.cx/events.jsonl.
+ *
+ * Hook processes emit failure/signal events here. The router + gateway read
+ * recent events to decide escalation. Lines are rotated to keep the file
+ * bounded. Fingerprint = sha1(type + project + first summary line) so the
+ * same failure dedups across emits.
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, appendFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const MAX_LINES = 1000;
+
+function rootDir() {
+  return process.env.CONSTRUCT_ROLES_ROOT || join(homedir(), '.cx');
+}
+function eventsPath() {
+  return join(rootDir(), 'events.jsonl');
+}
+function ensureDir() {
+  const r = rootDir();
+  if (!existsSync(r)) mkdirSync(r, { recursive: true });
+}
+
+export function fingerprintOf(type, project, summary) {
+  const firstLine = String(summary || '').split('\n')[0].trim();
+  return createHash('sha1').update(`${type}|${project}|${firstLine}`).digest('hex').slice(0, 16);
+}
+
+export function emit(eventType, payload = {}) {
+  ensureDir();
+  const project = payload.project || '';
+  const summary = payload.summary || '';
+  const fingerprint = fingerprintOf(eventType, project, summary);
+  const line = {
+    ts: Date.now(),
+    type: eventType,
+    project,
+    branch: payload.branch || '',
+    cwd: payload.cwd || '',
+    summary,
+    context: payload.context ?? null,
+    fingerprint,
+  };
+  appendFileSync(eventsPath(), JSON.stringify(line) + '\n');
+  rotate();
+  return line;
+}
+
+export function recent({ since = 0, type, fingerprint, limit = 200 } = {}) {
+  const ep = eventsPath();
+  if (!existsSync(ep)) return [];
+  const raw = readFileSync(ep, 'utf8').split('\n').filter(Boolean);
+  const out = [];
+  for (let i = raw.length - 1; i >= 0 && out.length < limit; i--) {
+    let entry;
+    try { entry = JSON.parse(raw[i]); } catch { continue; }
+    if (since && entry.ts < since) break;
+    if (type && entry.type !== type) continue;
+    if (fingerprint && entry.fingerprint !== fingerprint) continue;
+    out.push(entry);
+  }
+  return out;
+}
+
+function rotate() {
+  try {
+    const ep = eventsPath();
+    const raw = readFileSync(ep, 'utf8').split('\n').filter(Boolean);
+    if (raw.length <= MAX_LINES) return;
+    const trimmed = raw.slice(raw.length - MAX_LINES).join('\n') + '\n';
+    writeFileSync(ep, trimmed);
+  } catch { /* rotate is best-effort */ }
+}
+
+export const _paths = { rootDir, eventsPath };

package/lib/roles/fence.mjs

@@ -0,0 +1,84 @@
+/**
+ * lib/roles/fence.mjs — pure action-vs-manifest fence check.
+ *
+ * Invoked from the policy-engine and edit-guard hooks when a session is
+ * tagged with a persona. Glob patterns use simple ** / * matching (no full
+ * minimatch).
+ *
+ * Decision semantics:
+ *   - allowed:    target is inside the persona's allowedPaths/Commands/Labels
+ *   - approval:   target matches an entry in approvalRequired (needs user yes)
+ *   - denied:     neither — default deny
+ */
+
+import { loadManifest } from './manifest.mjs';
+
+function globMatch(pattern, target) {
+  if (!pattern || !target) return false;
+  const re = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*\//g, '__GLOBSTARSLASH__')
+    .replace(/\*\*/g, '__GLOBSTAR__')
+    .replace(/\*/g, '[^/]*')
+    .replace(/__GLOBSTARSLASH__/g, '(?:.*\\/)?')
+    .replace(/__GLOBSTAR__/g, '.*');
+  return new RegExp('^' + re + '$').test(target);
+}
+
+function matchAny(patterns, target) {
+  if (!Array.isArray(patterns)) return false;
+  return patterns.some((p) => globMatch(p, target));
+}
+
+function actionPrefix(action) {
+  const idx = action.indexOf(':');
+  return idx === -1 ? action : action.slice(0, idx);
+}
+
+export function checkAction({ personaId, action, target = '' }) {
+  const manifest = loadManifest(personaId);
+  if (!manifest) return { allowed: false, reason: 'persona-not-onboarded' };
+  const fence = manifest.fence || {};
+
+  if (action === 'edit' || action === 'write') {
+    if (matchAny(fence.allowedPaths, target)) return { allowed: true };
+    const approvalForms = [`edit:${target}`, 'edit:**', `${action}:${target}`];
+    if (
+      (fence.approvalRequired || []).some((req) =>
+        req === 'edit' || req === action || approvalForms.includes(req) || globMatch(req.replace(/^edit:/, ''), target)
+      )
+    ) {
+      return { allowed: false, reason: 'needs-approval', approval: true };
+    }
+    return { allowed: false, reason: 'outside-fence' };
+  }
+
+  if (action === 'bash') {
+    const cmd = String(target).trim();
+    const allowed = fence.allowedCommands || [];
+    const isPrefixMatch = allowed.some((c) => cmd === c || cmd.startsWith(c + ' '));
+    if (isPrefixMatch) return { allowed: true };
+    if ((fence.approvalRequired || []).includes('bash')) {
+      return { allowed: false, reason: 'needs-approval', approval: true };
+    }
+    return { allowed: false, reason: 'outside-fence' };
+  }
+
+  if (action === 'commit' || action === 'push') {
+    if ((fence.approvalRequired || []).includes(action)) {
+      return { allowed: false, reason: 'needs-approval', approval: true };
+    }
+    return { allowed: false, reason: 'outside-fence' };
+  }
+
+  if (action === 'bd-label') {
+    const labels = String(target).split(',').map((s) => s.trim()).filter(Boolean);
+    const allowed = fence.allowedBdLabels || [];
+    if (labels.every((l) => allowed.includes(l) || l.startsWith('next:'))) return { allowed: true };
+    return { allowed: false, reason: 'label-outside-fence' };
+  }
+
+  return { allowed: false, reason: 'unknown-action' };
+}
+
+export { globMatch };

package/lib/roles/gateway.mjs

@@ -0,0 +1,260 @@
+/**
+ * lib/roles/gateway.mjs — single entry point hooks call to record events and
+ * (maybe) invoke a persona.
+ *
+ * Flow: kill-switch checks → emit to bus → route → threshold/cooldown/rate
+ * ceiling → create bd issue → queue pending invocation → SSE toast.
+ *
+ * Defensive: every step is best-effort so a partial failure (bd unavailable,
+ * SSE bus unloaded) never blocks the calling hook. Returns a structured
+ * decision so callers can log / chain.
+ */
+
+import { existsSync, readFileSync, appendFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { emit, _paths } from './event-bus.mjs';
+import { route as routeEvent } from './router.mjs';
+import { runBd } from '../beads-client.mjs';
+
+function rootDir() {
+  return process.env.CONSTRUCT_ROLES_ROOT || join(homedir(), '.cx');
+}
+function pendingPath() {
+  return join(rootDir(), 'role-pending.jsonl');
+}
+
+const DEFAULTS = {
+  thresholdHits: 2,
+  thresholdWindowMs: 10 * 60 * 1000,
+  cooldownMs: 30 * 60 * 1000,
+  rateCeilingPerHour: 3,
+};
+
+function ensureDir() {
+  const r = rootDir();
+  if (!existsSync(r)) mkdirSync(r, { recursive: true });
+}
+
+function readPending() {
+  const pp = pendingPath();
+  if (!existsSync(pp)) return [];
+  try {
+    return readFileSync(pp, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .map((l) => { try { return JSON.parse(l); } catch { return null; } })
+      .filter(Boolean);
+  } catch { return []; }
+}
+
+function appendPending(entry) {
+  ensureDir();
+  appendFileSync(pendingPath(), JSON.stringify(entry) + '\n');
+}
+
+export function shouldEscalate(event, manifest, now = Date.now()) {
+  const fp = event.fingerprint;
+  const pending = readPending();
+
+  // Cooldown: same fingerprint already escalated within window?
+  const recentSame = pending.find(
+    (p) => p.fingerprint === fp && now - p.ts < DEFAULTS.cooldownMs
+  );
+  if (recentSame) return { escalate: false, reason: 'cooldown' };
+
+  // Rate ceiling per persona per hour
+  const personaId = (manifest && manifest.killSwitchEnv) ? manifest.killSwitchEnv : '';
+  const hourAgo = now - 60 * 60 * 1000;
+  const recentForPersona = pending.filter(
+    (p) => p.ts > hourAgo && p.killSwitchEnv === personaId
+  );
+  if (recentForPersona.length >= DEFAULTS.rateCeilingPerHour) {
+    return { escalate: false, reason: 'rate-ceiling' };
+  }
+
+  // Severity short-circuit: immediate on first hit
+  const immediate = Array.isArray(manifest?.severityImmediate)
+    && manifest.severityImmediate.includes(event.type);
+  if (immediate) return { escalate: true, reason: 'severity-immediate', count: 1 };
+
+  // Threshold: N hits within window from events.jsonl
+  const ep = _paths.eventsPath();
+  let hits = 0;
+  if (existsSync(ep)) {
+    const lines = readFileSync(ep, 'utf8').split('\n').filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i--) {
+      let e;
+      try { e = JSON.parse(lines[i]); } catch { continue; }
+      if (now - e.ts > DEFAULTS.thresholdWindowMs) break;
+      if (e.fingerprint === fp) hits++;
+    }
+  }
+  if (hits >= DEFAULTS.thresholdHits) {
+    return { escalate: true, reason: 'threshold', count: hits };
+  }
+  return { escalate: false, reason: 'below-threshold', count: hits };
+}
+
+async function createBdIncident(event, routeResult) {
+  const labels = (routeResult.manifest.outputs?.bdLabels || []).join(',') || 'incident';
+  const firstLine = String(event.summary || '').split('\n')[0].slice(0, 120);
+  const title = `[${routeResult.personaId}] ${event.type} — ${firstLine}`;
+  const body = JSON.stringify(
+    {
+      eventType: event.type,
+      ts: event.ts,
+      project: event.project,
+      branch: event.branch,
+      cwd: event.cwd,
+      summary: event.summary,
+      context: event.context,
+      fingerprint: event.fingerprint,
+      fence: routeResult.manifest.fence || {},
+      handoffCandidates: routeResult.manifest.handoffCandidates || [],
+    },
+    null,
+    2
+  );
+  const result = await runBd(
+    ['create', title, '-t', 'bug', '-l', labels, '-d', body],
+    { actor: `roles:${routeResult.personaId}`, silent: true, timeoutSeconds: 10, commandTimeoutSeconds: 30 }
+  );
+  if (!result.success) return { success: false, error: result.error || 'bd-failed' };
+  const match = String(result.output || '').match(/Created issue:\s*([\w-]+)/);
+  return { success: true, issueId: match ? match[1] : null, raw: result.output };
+}
+
+async function emitToastBestEffort(payload) {
+  try {
+    const mod = await import('../embed/notifications.mjs');
+    if (typeof mod.emitEmbedNotification === 'function') {
+      mod.emitEmbedNotification(payload);
+    }
+  } catch { /* dashboard not loaded; toast is best-effort */ }
+}
+
+export async function tryEscalate(event) {
+  const r = routeEvent(event);
+  if (!r) return { escalated: false, event, reason: 'no-owner' };
+
+  if (r.manifest.killSwitchEnv && process.env[r.manifest.killSwitchEnv] === 'off') {
+    return { escalated: false, event, reason: 'persona-off' };
+  }
+
+  const decision = shouldEscalate(event, r.manifest);
+  if (!decision.escalate) {
+    return { escalated: false, event, reason: decision.reason, decision };
+  }
+
+  try {
+    const { checkBudget } = await import('../cost-ledger.mjs');
+    const budget = checkBudget({ personaId: r.personaId });
+    if (!budget.allowed) {
+      return { escalated: false, event, reason: 'budget-exhausted', budget };
+    }
+  } catch { /* cost ledger optional — never block on missing module */ }
+
+  const bd = await createBdIncident(event, r);
+  if (!bd.success) {
+    return { escalated: false, event, reason: 'bd-create-failed', error: bd.error };
+  }
+
+  const pendingEntry = {
+    ts: Date.now(),
+    personaId: r.personaId,
+    cxId: r.cxId,
+    bdIssueId: bd.issueId,
+    fingerprint: event.fingerprint,
+    eventType: event.type,
+    summary: String(event.summary || '').split('\n')[0],
+    killSwitchEnv: r.manifest.killSwitchEnv || '',
+  };
+  appendPending(pendingEntry);
+
+  await emitToastBestEffort({
+    type: 'warning',
+    source: 'roles',
+    message: `${r.cxId}: ${pendingEntry.summary}`,
+    meta: {
+      personaId: r.personaId,
+      bdIssueId: bd.issueId,
+      fingerprint: event.fingerprint,
+      eventType: event.type,
+    },
+  });
+
+  return { escalated: true, event, personaId: r.personaId, bdIssueId: bd.issueId, decision };
+}
+
+export async function recordAndMaybeInvoke(eventType, payload = {}) {
+  if (process.env.CONSTRUCT_ROLES === 'off') {
+    return { recorded: false, escalated: false, reason: 'global-off' };
+  }
+  const event = emit(eventType, payload);
+  const r = await tryEscalate(event);
+  return { recorded: true, ...r };
+}
+
+export function listPending({ unresolved = true } = {}) {
+  const entries = readPending();
+  if (!unresolved) return entries;
+  return entries.filter((e) => !e.resolvedAt);
+}
+
+// Drain events that accumulated outside a Claude session. Walks recent
+// events.jsonl, runs each unescalated one through tryEscalate. Bounded by
+// `sinceMs` and `maxProcess` so a long-quiet machine can't trigger a flood.
+
+export async function processBacklog({ sinceMs = 60 * 60 * 1000, maxProcess = 10 } = {}) {
+  if (process.env.CONSTRUCT_ROLES === 'off') return { processed: 0, escalated: 0, reason: 'global-off' };
+
+  const ep = _paths.eventsPath();
+  if (!existsSync(ep)) return { processed: 0, escalated: 0 };
+  const cutoff = Date.now() - sinceMs;
+  const lines = readFileSync(ep, 'utf8').split('\n').filter(Boolean);
+  const pending = readPending();
+  const pendingFps = new Set(pending.map((p) => p.fingerprint));
+
+  const candidates = [];
+  for (let i = lines.length - 1; i >= 0 && candidates.length < maxProcess * 4; i--) {
+    let e;
+    try { e = JSON.parse(lines[i]); } catch { continue; }
+    if (e.ts < cutoff) break;
+    if (pendingFps.has(e.fingerprint)) continue;
+    candidates.push(e);
+  }
+
+  let escalated = 0;
+  let processed = 0;
+  for (const e of candidates.reverse()) {
+    if (processed >= maxProcess) break;
+    processed++;
+    const r = await tryEscalate(e);
+    if (r.escalated) escalated++;
+  }
+  return { processed, escalated };
+}
+
+export function markResolved(fingerprint) {
+  const entries = readPending();
+  let changed = false;
+  const next = entries.map((e) => {
+    if (e.fingerprint === fingerprint && !e.resolvedAt) {
+      changed = true;
+      return { ...e, resolvedAt: Date.now() };
+    }
+    return e;
+  });
+  if (!changed) return false;
+  writeFileSync(pendingPath(), next.map((e) => JSON.stringify(e)).join('\n') + '\n');
+  return true;
+}
+
+export function resetPending() {
+  const pp = pendingPath();
+  if (existsSync(pp)) writeFileSync(pp, '');
+}
+
+export const _gatewayPaths = { rootDir, pendingPath };

package/lib/roles/hook-emit.mjs

@@ -0,0 +1,37 @@
+/**
+ * lib/roles/hook-emit.mjs — synchronous one-liner hooks call to publish events.
+ *
+ * Wraps event-bus.emit with auto-detection of project + branch from the hook
+ * input. Never throws — hooks must stay on the hot path. Returns the event or
+ * null on failure. Use `emitRoleEvent({ type, summary, hookInput, context })`.
+ */
+
+import { execSync } from 'node:child_process';
+import { emit } from './event-bus.mjs';
+
+function gitInfo(cwd) {
+  try {
+    const project = execSync('git rev-parse --show-toplevel 2>/dev/null', { cwd, timeout: 1000 }).toString().trim();
+    const branch = execSync('git rev-parse --abbrev-ref HEAD 2>/dev/null', { cwd, timeout: 1000 }).toString().trim();
+    return { project, branch };
+  } catch {
+    return { project: cwd || '', branch: '' };
+  }
+}
+
+export function emitRoleEvent({ type, summary, hookInput = {}, context = null }) {
+  if (process.env.CONSTRUCT_ROLES === 'off') return null;
+  try {
+    const cwd = hookInput.cwd || process.cwd();
+    const { project, branch } = gitInfo(cwd);
+    return emit(type, {
+      project,
+      branch,
+      cwd,
+      summary: String(summary || '').slice(0, 4096),
+      context,
+    });
+  } catch {
+    return null;
+  }
+}

package/lib/roles/manifest.mjs

@@ -0,0 +1,48 @@
+/**
+ * lib/roles/manifest.mjs — role manifest loader.
+ *
+ * Reads agents/role-manifests.json. A persona is "onboarded" when its
+ * `events` array is non-empty. Empty entries reserve the slot for future
+ * wiring without code change.
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const MANIFEST_PATH = join(__dirname, '..', '..', 'agents', 'role-manifests.json');
+
+let cached = null;
+
+function load() {
+  if (cached) return cached;
+  const raw = readFileSync(MANIFEST_PATH, 'utf8');
+  const parsed = JSON.parse(raw);
+  cached = parsed.personas || {};
+  return cached;
+}
+
+export function loadManifest(personaId) {
+  const id = String(personaId).replace(/^cx-/, '');
+  const all = load();
+  return all[id] || null;
+}
+
+export function isOnboarded(personaId) {
+  const m = loadManifest(personaId);
+  return !!(m && Array.isArray(m.events) && m.events.length > 0);
+}
+
+export function listOnboardedPersonas() {
+  const all = load();
+  return Object.keys(all).filter((id) => isOnboarded(id));
+}
+
+export function listAllPersonas() {
+  return Object.keys(load());
+}
+
+export function _resetCache() {
+  cached = null;
+}

package/lib/roles/router.mjs

@@ -0,0 +1,27 @@
+/**
+ * lib/roles/router.mjs — pure event → persona resolver.
+ *
+ * Uses EVENT_OWNERSHIP from orchestration-policy and validates against
+ * the loaded role manifest. Returns null (no owner) silently if the
+ * event has no declared owner or the persona is not yet onboarded —
+ * letting us declare ownership ahead of full wiring.
+ */
+
+import { EVENT_OWNERSHIP } from '../orchestration-policy.mjs';
+import { loadManifest, isOnboarded } from './manifest.mjs';
+
+export function route(event) {
+  const type = event?.type;
+  if (!type) return null;
+  const ownerCxId = EVENT_OWNERSHIP[type];
+  if (!ownerCxId) return null;
+  const personaId = ownerCxId.replace(/^cx-/, '');
+  if (!isOnboarded(personaId)) return null;
+  const manifest = loadManifest(personaId);
+  if (!manifest.events.includes(type)) return null;
+  return { personaId, cxId: ownerCxId, manifest };
+}
+
+export function ownerOf(eventType) {
+  return EVENT_OWNERSHIP[eventType] || null;
+}