@davvidbaker/flambe-cli 0.1.3 → 0.1.5

package/src/codex-hook.mjs

@@ -0,0 +1,237 @@
+import {createHash} from 'node:crypto';
+import {existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync} from 'node:fs';
+import {homedir} from 'node:os';
+import {dirname, join, resolve} from 'node:path';
+import {setTimeout as delay} from 'node:timers/promises';
+import {agentIdentityFromEnv, clientFromEnv} from './client.mjs';
+import {loadProjectEnv} from './env.mjs';
+import {atomicWrite, hasFlambeHooks} from './codex-setup.mjs';
+import {assertRuntimeUrl} from './runtime.mjs';
+
+const RESTORE = new Set(['SessionStart', 'SubagentStart', 'PostCompact', 'UserPromptSubmit']);
+const EVENTS = new Set([...RESTORE, 'PreToolUse', 'PostToolUse', 'Stop', 'Interrupt']);
+const hash = text => createHash('sha256').update(text).digest('hex');
+const clean = value => String(value).replace(/[\x00-\x1f\x7f]/g, ' ').slice(0, 160);
+const emptyState = () => ({workInTurn: 0, workSinceTracked: 0, callsSinceReminder: 0});
+
+function projectRoot(cwd) {
+  let directory = resolve(cwd);
+  for (;;) {
+    const path = join(directory, '.codex', 'hooks.json');
+    if (existsSync(path) && hasFlambeHooks(JSON.parse(readFileSync(path, 'utf8')))) return directory;
+    const parent = dirname(directory);
+    if (parent === directory || existsSync(join(directory, '.git'))) return null;
+    directory = parent;
+  }
+}
+
+function context(event, text) {
+  return {hookSpecificOutput: {hookEventName: event, additionalContext: text}};
+}
+
+function connectionWarning(event) {
+  const text = 'Single Burner hook could not verify the local connection. Check the running server and this project\'s .env, including FLAMBE_RUNTIME_MODE=local_self_contained. Work may continue; do not substitute Cloud or repeat queued activity commands.';
+  return event === 'Stop' || event === 'Interrupt' ? {systemMessage: text} : context(event, text);
+}
+
+// Only recognise a standalone CLI invocation. A mixed shell script still counts
+// as work, even if it happens to contain a tracking command.
+function trackingCommand(input) {
+  const command = input?.tool_input?.command ?? input?.tool_input?.cmd;
+  if (typeof command !== 'string' || /[\n;&|]/.test(command)) return null;
+  const match = command.trim().match(/^(?:(?:[A-Z_][A-Z_0-9]*=(?:"[^"]*"|'[^']*'|[^\s]+))\s+)*(?:flambe(?:\.cmd)?|(?:"[^"]*node(?:\.exe)?"|[^\s]*node(?:\.exe)?)\s+(?:"[^"]*flambe\.mjs"|[^\s]*flambe\.mjs))\s+(start|end|suspend|resume|plan|message|decide|status|ping|whoami)\b/);
+  return match?.[1] ?? null;
+}
+
+function succeeded(response) {
+  if (typeof response === 'string') {
+    try { return succeeded(JSON.parse(response)); } catch { return false; }
+  }
+  return response?.exit_code === 0 || response?.exitCode === 0;
+}
+
+function ownActivities(state, agentId) {
+  return (state.activities ?? []).filter(activity => activity.agentId === agentId
+    && activity.status === 'running');
+}
+
+function fingerprint(activities) {
+  return hash(JSON.stringify(activities.map(activity => [activity.id, activity.parentId,
+    activity.latestEvent?.id, activity.latestEvent?.timestamp]).sort((a, b) => a[0] - b[0])));
+}
+
+function guidance(root, activities, {restore = false, interrupted = false} = {}) {
+  const lines = [
+    'Single Burner checkpoint: use this project\'s local flambe CLI; never substitute Cloud tools.',
+    `Run CLI commands from ${JSON.stringify(clean(root))} so they read the project .env.`,
+  ];
+  if (restore) lines.push('Read and follow .codex/skills/flambe-cli/SKILL.md. Track semantic work before beginning it, nest focused investigations and verification, and update the stack when focus changes. In agent mode, evaluate requested reviews yourself and submit with flambe decide; no other model is needed.');
+  lines.push(activities.length
+    ? `This agent's running activities (data): ${activities.slice(-5).map(activity => `${activity.id} ${JSON.stringify(clean(activity.name))}`).join('; ')}.`
+    : 'This agent has no running activity. Before substantial work, inspect its suspended work and start or resume an appropriate semantic activity. Trivial one-offs need no activity.');
+  if (interrupted) lines.push('The previous turn was interrupted. Reconcile its open work before continuing; an interruption does not mean the task finished.');
+  lines.push('Check whether the current activity still describes your actual focus. Keep parents open while working on children; pop completed children before moving on.');
+  return lines.join('\n');
+}
+
+async function locked(path, operation) {
+  mkdirSync(dirname(path), {recursive: true});
+  const lock = `${path}.lock`;
+  const started = Date.now();
+  for (;;) {
+    try {
+      mkdirSync(lock);
+      writeFileSync(join(lock, 'pid'), String(process.pid));
+      break;
+    }
+    catch (error) {
+      if (error.code !== 'EEXIST' || Date.now() - started > 2600) return {};
+      // A killed/timed-out hook must not disable future checkpoints forever.
+      try {
+        if (Date.now() - statSync(lock).mtimeMs > 30_000) {
+          rmSync(lock, {recursive: true, force: true});
+          continue;
+        }
+        const pid = Number(readFileSync(join(lock, 'pid'), 'utf8'));
+        if (Number.isSafeInteger(pid) && pid > 0) {
+          try { process.kill(pid, 0); }
+          catch (check) { if (check.code === 'ESRCH') rmSync(lock, {recursive: true, force: true}); }
+        }
+      } catch {
+        try { if (Date.now() - statSync(lock).mtimeMs > 10_000) rmSync(lock, {recursive: true, force: true}); }
+        catch { /* Another hook just released it. */ }
+      }
+      await delay(20);
+    }
+  }
+  try { return await operation(); }
+  finally { rmSync(lock, {recursive: true, force: true}); }
+}
+
+/** A checkpoint adapter, not an activity generator or model client. */
+export async function runCodexHook(input, {
+  env: shellEnv = process.env, now = Date.now,
+  stateDir = shellEnv.FLAMBE_CODEX_HOOK_STATE_DIR?.trim() || join(homedir(), '.flambe', 'codex-hooks'),
+  fetchImpl = globalThis.fetch, checkEveryMs = 30_000,
+  remindEveryCalls = 10, remindEveryMs = 90_000,
+} = {}) {
+  const event = input?.hook_event_name;
+  if (!EVENTS.has(event) || typeof input.cwd !== 'string' || !input.session_id) return {};
+  if (event === 'Stop' && input.stop_hook_active) return {};
+  let root;
+  let env;
+  let identity;
+  try {
+    root = projectRoot(input.cwd);
+    if (!root) return {};
+    env = {...shellEnv};
+    loadProjectEnv({cwd: root, env});
+    if (!['FLAMBE_URL', 'FLAMBE_API_TOKEN', 'FLAMBE_TRACE_ID'].some(key => env[key])) return {};
+    if (env.FLAMBE_RUNTIME_MODE !== 'local_self_contained') return connectionWarning(event);
+    assertRuntimeUrl(env.FLAMBE_URL, 'local_self_contained');
+    identity = agentIdentityFromEnv(env);
+    if (!identity.agentId) {
+      return RESTORE.has(event) ? context(event,
+        'Single Burner: read .codex/skills/flambe-cli/SKILL.md. The hook could not derive this Codex agent\'s identity, so it did not inspect any activity stack. Check flambe whoami in the local Codex environment; do not reuse another agent\'s identity or put agent IDs in .env.') : {};
+    }
+  } catch { return connectionWarning(event); }
+  const key = hash(JSON.stringify([root, env.FLAMBE_URL, env.FLAMBE_TRACE_ID, identity.agentId, input.session_id]));
+  const path = join(stateDir, `${key}.json`);
+  try {
+    return await locked(path, async () => {
+      let state;
+      try { state = {...emptyState(), ...JSON.parse(readFileSync(path, 'utf8'))}; }
+      catch { state = emptyState(); }
+      const at = now();
+      const save = output => { atomicWrite(path, `${JSON.stringify(state)}\n`); return output; };
+      const turn = input.turn_id ?? state.turn ?? 'unknown';
+      if (turn !== state.turn || event === 'UserPromptSubmit') {
+        state.turn = turn;
+        delete state.stopTurn;
+        state.workInTurn = 0;
+        state.workSinceTracked = 0;
+        state.callsSinceReminder = 0;
+        state.missingWarned = false;
+      }
+      if (event === 'Interrupt') {
+        state.interrupted = true;
+        return save({});
+      }
+      const tracking = trackingCommand(input);
+      if (event === 'PostToolUse') {
+        if (tracking && !['status', 'ping', 'whoami'].includes(tracking) && succeeded(input.tool_response)) {
+          state.workSinceTracked = 0;
+          state.callsSinceReminder = 0;
+          state.remindedAt = at;
+          state.checkedAt = 0;
+        }
+        return save({});
+      }
+      if (event === 'PreToolUse') {
+        if (tracking) return save({});
+        const weight = /^(apply_patch|Edit|Write)$/.test(input.tool_name ?? '') ? 3 : 1;
+        state.workInTurn += weight;
+        state.workSinceTracked += weight;
+        state.callsSinceReminder++;
+        state.lastWorkAt = at;
+      }
+      if (event === 'Stop' && (state.workInTurn < 3 || state.workSinceTracked === 0 || state.stopTurn === turn)) return save({});
+      const restore = RESTORE.has(event);
+      const periodic = state.callsSinceReminder >= remindEveryCalls || at - (state.remindedAt ?? at) >= remindEveryMs;
+      const due = restore || periodic || event === 'Stop' || !state.checkedAt || at - state.checkedAt >= checkEveryMs;
+      let activities = [];
+      if (due) {
+        state.checkedAt = at;
+        try {
+          const client = clientFromEnv(env);
+          client.fetch = (url, options) => fetchImpl(url, {...options, signal: AbortSignal.timeout(1200)});
+          activities = ownActivities(await client.status({activeOnly: true}), identity.agentId);
+          const current = fingerprint(activities);
+          const latestChange = Math.max(0, ...activities.map(activity => Date.parse(activity.latestEvent?.timestamp) || 0));
+          if (state.fingerprint && state.fingerprint !== current
+            && ((!activities.length && state.hasActive) || latestChange >= (state.lastWorkAt ?? 0))) {
+            state.workSinceTracked = 0;
+            state.callsSinceReminder = 0;
+            state.remindedAt = at;
+          }
+          state.fingerprint = current;
+          state.available = true;
+          state.hasActive = activities.length > 0;
+        } catch {
+          state.available = false;
+          if (!state.warnedAt || at - state.warnedAt >= remindEveryMs || restore) {
+            state.warnedAt = at;
+            return save(connectionWarning(event));
+          }
+          return save({});
+        }
+      }
+      if (!state.available) return save({});
+      if (event === 'Stop') {
+        if (!state.workSinceTracked) return save({});
+        state.stopTurn = turn;
+        return save({decision: 'block', reason: guidance(root, activities)
+          + '\nBefore handing back, reconcile the work you actually did. End completed activities, suspend work waiting on the user, or explain why an activity remains running. Complete any requested reducer review. This is one checkpoint, not an instruction to invent work or end every open parent.'});
+      }
+      const firstUntracked = event === 'PreToolUse' && !state.missingWarned && !state.hasActive;
+      if (restore || firstUntracked || periodic) {
+        if (firstUntracked) state.missingWarned = true;
+        state.callsSinceReminder = 0;
+        state.remindedAt = at;
+        const interrupted = state.interrupted;
+        state.interrupted = false;
+        return save(context(event, guidance(root, activities, {restore, interrupted})));
+      }
+      return save({});
+    });
+  } catch { return connectionWarning(event); }
+}
+
+export async function readHookInput(stdin = process.stdin) {
+  let body = '';
+  for await (const chunk of stdin) {
+    body += chunk;
+    if (Buffer.byteLength(body) > 1024 * 1024) throw new Error('Hook input exceeds 1 MiB');
+  }
+  return JSON.parse(body);
+}

package/src/codex-setup.mjs

@@ -0,0 +1,104 @@
+import {existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync} from 'node:fs';
+import {dirname, join, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {randomUUID} from 'node:crypto';
+
+export const HOOK_COMMAND = 'flambe hook codex';
+export const HOOK_COMMAND_WINDOWS = 'flambe.cmd hook codex';
+export const HOOK_EVENTS = ['SessionStart', 'SubagentStart', 'UserPromptSubmit', 'PostCompact', 'PreToolUse', 'PostToolUse', 'Stop', 'Interrupt'];
+
+export function managedHook(hook) {
+  return hook?.type === 'command' && hook.command === HOOK_COMMAND
+    && hook.commandWindows === HOOK_COMMAND_WINDOWS;
+}
+
+export function hasFlambeHooks(config) {
+  return Object.values(config?.hooks ?? {}).some(groups => Array.isArray(groups)
+    && groups.some(group => group.hooks?.some(managedHook)));
+}
+
+function readConfig(path) {
+  if (!existsSync(path)) return {hooks: {}};
+  let config;
+  try { config = JSON.parse(readFileSync(path, 'utf8')); }
+  catch { throw new Error('Cannot read .codex/hooks.json as JSON; existing hooks were not changed.'); }
+  if (!config || typeof config !== 'object' || Array.isArray(config)
+    || (config.hooks !== undefined && (!config.hooks || typeof config.hooks !== 'object' || Array.isArray(config.hooks)))
+    || Object.values(config.hooks ?? {}).some(groups => !Array.isArray(groups)
+      || groups.some(group => !group || !Array.isArray(group.hooks)))) {
+    throw new Error('Unsupported .codex/hooks.json structure; existing hooks were not changed.');
+  }
+  return config;
+}
+
+export function atomicWrite(path, text) {
+  mkdirSync(dirname(path), {recursive: true});
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporary, text, {mode: 0o600, flag: 'wx'});
+    renameSync(temporary, path);
+  } finally {
+    if (existsSync(temporary)) unlinkSync(temporary);
+  }
+}
+
+export function bundledSkill() {
+  const bundled = fileURLToPath(new URL('../skills/flambe-cli/SKILL.md', import.meta.url));
+  const source = fileURLToPath(new URL('../../.codex/skills/flambe-cli/SKILL.md', import.meta.url));
+  return readFileSync(existsSync(bundled) ? bundled : source, 'utf8');
+}
+
+function withoutManagedHooks(config) {
+  const result = {...config, hooks: {...config.hooks}};
+  for (const [event, groups] of Object.entries(result.hooks)) {
+    result.hooks[event] = groups.flatMap(group => {
+      if (!group.hooks.some(managedHook)) return [group];
+      const hooks = group.hooks.filter(hook => !managedHook(hook));
+      return hooks.length ? [{...group, hooks}] : [];
+    });
+    if (!result.hooks[event].length) delete result.hooks[event];
+  }
+  return result;
+}
+
+export function setupCodex({cwd = process.cwd(), action = 'install', skill = bundledSkill()} = {}) {
+  const root = resolve(cwd);
+  const path = join(root, '.codex', 'hooks.json');
+  const skillPath = join(root, '.codex', 'skills', 'flambe-cli', 'SKILL.md');
+  const existing = readConfig(path);
+  const installedEvents = HOOK_EVENTS.filter(event => existing.hooks?.[event]?.some(group =>
+    group.hooks.some(managedHook)));
+  const skillExists = existsSync(skillPath);
+  if (action === 'check') return {
+    root, hooksPath: path, installed: installedEvents.length === HOOK_EVENTS.length,
+    installedEvents, skillExists,
+    skillMatches: skillExists && readFileSync(skillPath, 'utf8') === skill,
+  };
+  const config = withoutManagedHooks(existing);
+  if (action === 'remove') {
+    if (installedEvents.length) atomicWrite(path, `${JSON.stringify(config, null, 2)}\n`);
+    return {root, hooksPath: path, removed: installedEvents.length > 0, skillRetained: skillExists};
+  }
+  if (action !== 'install') throw new Error('Unknown Codex setup action');
+  for (const event of HOOK_EVENTS) {
+    config.hooks[event] ??= [];
+    config.hooks[event].push({hooks: [{
+      type: 'command', command: HOOK_COMMAND, commandWindows: HOOK_COMMAND_WINDOWS,
+      timeout: event === 'Interrupt' ? 3 : 5,
+      statusMessage: 'Single Burner tracking checkpoint', additionalContextLimit: 1800,
+    }]});
+  }
+  // Preserve custom/existing instructions. Never silently replace a skill.
+  if (!skillExists) atomicWrite(skillPath, skill);
+  const serialized = `${JSON.stringify(config, null, 2)}\n`;
+  const unchanged = existsSync(path) && readFileSync(path, 'utf8') === serialized;
+  if (!unchanged) {
+    if (existsSync(path)) {
+      const backup = `${path}.before-flambe`;
+      if (!existsSync(backup)) writeFileSync(backup, readFileSync(path), {flag: 'wx', mode: 0o600});
+    }
+    atomicWrite(path, serialized);
+  }
+  return {root, hooksPath: path, unchanged, skillInstalled: !skillExists,
+    skillMatches: !skillExists || readFileSync(skillPath, 'utf8') === skill};
+}

package/src/local/commands.mjs

@@ -92,7 +92,7 @@ export function commandState(trace, filters = {}) {
 }
 
 /** A command and all of its corrections commit together, or not at all. */
-export function executeCommand(store, userId, command, attrs, headerAgent = null) {
+export function executeCommand(store, userId, command, attrs, headerAgent = null, { modelReviewAvailable = false, reviewStarts = true } = {}) {
   if (!COMMANDS.includes(command) || !attrs || typeof attrs !== 'object' || Array.isArray(attrs)) {
     invalid('command and arguments are required');
   }
@@ -112,6 +112,8 @@ export function executeCommand(store, userId, command, attrs, headerAgent = null
     include_unstarted: bool(attrs.include_unstarted, 'include_unstarted') };
   if (filters.active_only && filters.suspended_only) invalid('active_only and suspended_only cannot both be true');
   const result = { direction: null, reply: null, actions_applied: [], rules_fired: [], closed_descendants: [] };
+  const structuralReview = !modelReviewAvailable ? { type: 'skipped', reason: 'model_unavailable' }
+    : reviewStarts ? { type: 'pending_model_review' } : { type: 'available', reason: 'work_ai_review_on_request' };
   if (command === 'status') {
     const state = commandState(trace, filters);
     if (filters.include_unstarted && !filters.active_only && !filters.suspended_only) {
@@ -150,7 +152,7 @@ export function executeCommand(store, userId, command, attrs, headerAgent = null
     requiredText(attrs.message, 'message');
     if (attrs.activity_id != null && !byId.has(positiveId(attrs.activity_id, 'activity_id'))) notFound();
     throw new CommandError(503, 'REDUCER_NOT_CONFIGURED',
-      'Model review is unavailable in the self-contained runtime. Lifecycle commands remain available; no content was sent to a provider.');
+      'AI reducer review is off. Configure FLAMBE_LOCAL_REDUCER_MODE to enable it. Lifecycle commands remain available; no content was sent to a provider.');
   }
   if (attrs.message != null && typeof attrs.message !== 'string') invalid('message must be a string');
   if (attrs.description != null && typeof attrs.description !== 'string') invalid('description must be a string');
@@ -246,12 +248,12 @@ export function executeCommand(store, userId, command, attrs, headerAgent = null
         if (result.actions_applied.length) annotate(result.activity_id, 'resume_ancestor',
           result.actions_applied.map(a => a.activity_id));
         if (!parent && agentId && before.activities.some(a => a.agentId === agentId && a.status === 'running')) {
-          annotate(result.activity_id, 'new_root_while_open', { type: 'skipped', reason: 'model_unavailable' });
+          annotate(result.activity_id, 'new_root_while_open', structuralReview);
         } else if (parent) {
           const ancestorTokens = new Set(ancestors(parent).flatMap(a => tokens(a.name)));
           const childTokens = tokens(name);
           if (childTokens.length && childTokens.every(t => !ancestorTokens.has(t))) {
-            annotate(result.activity_id, 'name_unfit', { type: 'skipped', reason: 'model_unavailable' });
+            annotate(result.activity_id, 'name_unfit', structuralReview);
           }
         }
       }

package/src/local/history.mjs

@@ -0,0 +1,98 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+/** Signed reciprocal creation history; snapshots never accept client-supplied row contents. */
+export function reverseCreation(store, userId, traceId, body) {
+  traceId = Number(traceId);
+  if (!store.getTrace(userId, traceId)) return { status: 404, json: { error: 'NOT_FOUND' } };
+  const db = store.db;
+  const row = (table, id) => db.prepare(`SELECT * FROM ${table} WHERE id = ?`).get(Number(id));
+  const rows = (table, activityId) => db.prepare(`SELECT * FROM ${table} WHERE activity_id = ? ORDER BY id`).all(activityId);
+  const children = id => db.prepare('SELECT id, parent_id, thread_id FROM activities WHERE parent_id = ? ORDER BY id').all(id);
+  const categories = id => db.prepare('SELECT category_id FROM activities_categories WHERE activity_id = ? ORDER BY category_id').all(id).map(c => c.category_id);
+  const equal = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+  const fail = () => { throw new Error('HISTORY_CHANGED'); };
+  const signature = value => createHmac('sha256', store.credentials().rawToken).update(`creation-history-v1:${value}`).digest();
+  const sign = record => {
+    const value = Buffer.from(JSON.stringify(record)).toString('base64url');
+    return `${value}.${signature(value).toString('base64url')}`;
+  };
+  const insert = (table, data) => {
+    // Column names come from this database, not the restoration token.
+    const columns = db.prepare(`PRAGMA table_info(${table})`).all().map(c => c.name);
+    db.prepare(`INSERT INTO ${table} (${columns.join(',')}) VALUES (${columns.map(() => '?').join(',')})`)
+      .run(...columns.map(column => data[column] ?? null));
+  };
+  let record;
+  if (typeof body.token === 'string') {
+    try {
+      const [value, mac, extra] = body.token.split('.');
+      const expected = signature(value);
+      const supplied = Buffer.from(mac ?? '', 'base64url');
+      if (extra || supplied.length !== expected.length || !timingSafeEqual(supplied, expected)) throw new Error();
+      record = JSON.parse(Buffer.from(value, 'base64url').toString());
+      if (record.userId !== userId || record.traceId !== traceId || !['remove', 'restore'].includes(record.mode)) throw new Error();
+    } catch { return { status: 422, json: { error: 'INVALID_HISTORY' } }; }
+  }
+  db.exec('SAVEPOINT history_reverse');
+  try {
+    if (!record) {
+      const id = Number(body.target_id);
+      const activity = body.kind === 'activity' ? store.getActivity(userId, id) : null;
+      const event = body.kind === 'event' ? row('events', id) : null;
+      if (activity && (store.getThread(userId, activity.thread_id) && row('threads', activity.thread_id)?.trace_id) === traceId) {
+        record = { userId, traceId, mode: 'remove', snapshot: { kind: 'activity',
+          activity: row('activities', id), events: rows('events', id), categories: categories(id), children: children(id) } };
+      } else if (event?.trace_id === traceId) {
+        let weight = null;
+        if (body.restore_weight) {
+          const activityId = Number(body.restore_weight.activity_id);
+          const old = body.restore_weight.weight;
+          if (activityId !== event.activity_id || (old !== null && !Number.isInteger(old))) fail();
+          weight = { activity_id: activityId, before: row('activities', activityId).weight, after: old };
+        }
+        record = { userId, traceId, mode: 'remove', snapshot: { kind: 'event', event, weight } };
+      } else fail();
+    }
+    const { snapshot, mode } = record;
+    if (snapshot.kind === 'activity') {
+      const activity = snapshot.activity;
+      if ((store.getThread(userId, activity.thread_id) && row('threads', activity.thread_id)?.trace_id) !== traceId) fail();
+      if (mode === 'remove') {
+        if (!equal(row('activities', activity.id), activity) || !equal(rows('events', activity.id), snapshot.events)
+          || !equal(categories(activity.id), snapshot.categories) || !equal(children(activity.id), snapshot.children)) fail();
+        db.prepare('DELETE FROM activities WHERE id = ?').run(activity.id);
+      } else {
+        if (row('activities', activity.id)) fail();
+        if (activity.parent_id && row('activities', activity.parent_id)?.thread_id !== activity.thread_id) fail();
+        for (const child of snapshot.children) {
+          const current = store.getActivity(userId, child.id);
+          if (!current || current.parent_id !== null || current.thread_id !== child.thread_id) fail();
+        }
+        for (const event of snapshot.events) if (row('events', event.id) || event.trace_id !== traceId || event.activity_id !== activity.id) fail();
+        for (const id of snapshot.categories) if (row('categories', id)?.user_id !== userId) fail();
+        insert('activities', activity);
+        for (const event of snapshot.events) insert('events', event);
+        for (const id of snapshot.categories) db.prepare('INSERT INTO activities_categories (activity_id, category_id) VALUES (?, ?)').run(activity.id, id);
+        for (const child of snapshot.children) db.prepare('UPDATE activities SET parent_id = ? WHERE id = ?').run(activity.id, child.id);
+      }
+    } else if (snapshot.kind === 'event') {
+      const event = snapshot.event;
+      if (event.trace_id !== traceId || !store.getActivity(userId, event.activity_id)) fail();
+      if (mode === 'remove' ? !equal(row('events', event.id), event) : Boolean(row('events', event.id))) fail();
+      if (snapshot.weight) {
+        const weight = snapshot.weight;
+        if (weight.activity_id !== event.activity_id) fail();
+        if (row('activities', weight.activity_id).weight !== (mode === 'remove' ? weight.before : weight.after)) fail();
+        db.prepare('UPDATE activities SET weight = ? WHERE id = ?').run(mode === 'remove' ? weight.after : weight.before, weight.activity_id);
+      }
+      if (mode === 'remove') db.prepare('DELETE FROM events WHERE id = ?').run(event.id);
+      else insert('events', event);
+    } else fail();
+    const inverse = sign({ ...record, mode: mode === 'remove' ? 'restore' : 'remove' });
+    db.exec('RELEASE history_reverse');
+    return { status: 200, json: { data: { undo_token: inverse } } };
+  } catch {
+    db.exec('ROLLBACK TO history_reverse; RELEASE history_reverse');
+    return { status: 409, json: { error: 'HISTORY_CHANGED' } };
+  }
+}

package/src/local/http.mjs

@@ -1,5 +1,6 @@
 import { createReadStream, existsSync, statSync } from 'node:fs';
 import { extname, join, normalize, resolve } from 'node:path';
+import { reverseCreation } from './history.mjs';
 import { COMMANDS, CommandError, executeCommand } from './commands.mjs';
 
 function sendJson(res, status, body) {
@@ -112,7 +113,7 @@ function agentHeaders(agent) {
   };
 }
 
-async function dispatch(store, req, url, body, { auth, agent }) {
+async function dispatch(store, req, url, body, { auth, agent, runCommand }) {
   const method = req.method ?? 'GET';
   const path = url.pathname;
 
@@ -146,13 +147,18 @@ async function dispatch(store, req, url, body, { auth, agent }) {
 
   if (path === '/api/agent-commands') {
     if (method === 'GET') return { status: 200, json: { data: {
-      version: 1, commands: COMMANDS, runtime_mode: 'local_self_contained', model_review: false,
+      version: 1, commands: [...COMMANDS, ...(runCommand.info?.work_ai_reviews ? ['decide'] : [])], runtime_mode: 'local_self_contained',
+      model_review: runCommand.info?.enabled ?? false, reducer: runCommand.info ?? { mode: 'off' },
     } } };
     if (method === 'POST') return { status: 200, json: {
-      data: executeCommand(store, userId, body.command, body.arguments, agent),
+      data: await runCommand(userId, body.command, body.arguments, agent),
     } };
   }
 
+  if (method === 'GET' && path === '/api/agents') {
+    return { status: 200, json: { data: store.listAgents(userId) } };
+  }
+
   if (method === 'GET' && path === '/api/agents/me') {
     if (!agent) {
       return { status: 400, json: { error: 'AGENT_ID_REQUIRED', detail: 'Send x-flambe-agent-id with a bearer token' } };
@@ -212,6 +218,9 @@ async function dispatch(store, req, url, body, { auth, agent }) {
     return { status: 200, json: { data: { threads: result.threads } } };
   }
 
+  const historyMatch = path.match(/^\/api\/traces\/(\d+)\/reverse_creation$/);
+  if (method === 'POST' && historyMatch) return reverseCreation(store, userId, historyMatch[1], body);
+
   const traceMatch = path.match(/^\/api\/traces\/(\d+)$/);
   if (traceMatch) {
     const id = traceMatch[1];
@@ -259,7 +268,7 @@ async function dispatch(store, req, url, body, { auth, agent }) {
   if (method === 'POST' && path === '/api/activities') {
     if (!Object.hasOwn(body, 'event') && auth.tokenName !== null) {
       const activity = body.activity ?? {};
-      const planned = executeCommand(store, userId, 'plan', {
+      const planned = await runCommand(userId, 'plan', {
         trace_id: body.trace_id, name: activity.name, description: activity.description,
         weight: activity.weight, category_ids: activity.categories,
         scheduled_start: activity.scheduled_start_integer,
@@ -271,7 +280,7 @@ async function dispatch(store, req, url, body, { auth, agent }) {
     }
     if (auth.tokenName !== null) {
       const activity = body.activity ?? {};
-      const folded = executeCommand(store, userId, 'start', {
+      const folded = await runCommand(userId, 'start', {
         trace_id: body.trace_id, thread_id: body.thread_id, name: activity.name,
         description: activity.description, category_ids: activity.categories,
         ...(Object.hasOwn(activity, 'parent_id') ? { parent_id: activity.parent_id } : {}),
@@ -283,7 +292,7 @@ async function dispatch(store, req, url, body, { auth, agent }) {
           phase: folded.state.activities.find(a => a.id === folded.activity_id)?.latestEvent.phase },
         reducer: folded.reducer ?? { actions_applied: folded.actions_applied },
         direction: folded.direction, reply: folded.reply, rules_fired: folded.rules_fired,
-        actions_applied: folded.actions_applied,
+        actions_applied: folded.actions_applied, model_review: folded.model_review, review: folded.review,
       } } };
     }
     const result = store.createActivity(userId, {
@@ -327,7 +336,7 @@ async function dispatch(store, req, url, body, { auth, agent }) {
     const phase = body.event?.phase;
     const command = { E: 'end', J: 'end', V: 'end', S: 'suspend', R: 'resume' }[phase];
     if (auth.tokenName !== null && command) {
-      const folded = executeCommand(store, userId, command, {
+      const folded = await runCommand(userId, command, {
         trace_id: body.trace_id, activity_id: body.activity_id,
         timestamp: body.event?.timestamp_integer, message: body.event?.message,
         phase, force: body.force ?? true,
@@ -336,7 +345,7 @@ async function dispatch(store, req, url, body, { auth, agent }) {
         id: folded.event_id, phase,
         reducer: { closed_descendants: folded.closed_descendants,
           rules_fired: folded.rules_fired, actions_applied: folded.actions_applied,
-          direction: folded.direction, reply: folded.reply },
+          direction: folded.direction, reply: folded.reply, model_review: folded.model_review },
       } } };
     }
     const result = store.createEvent(userId, {
@@ -429,7 +438,8 @@ function tryStatic(staticDir, urlPath, res) {
   return true;
 }
 
-export async function handleLocalRequest(store, req, res, { staticDir } = {}) {
+export async function handleLocalRequest(store, req, res, { staticDir, mcp,
+  runCommand = (userId, command, args, agent) => executeCommand(store, userId, command, args, agent) } = {}) {
   const host = req.headers.host ?? '127.0.0.1';
   const url = new URL(req.url ?? '/', `http://${host}`);
   // A locally served UI must not send trace content to a compiled-in remote API.
@@ -448,6 +458,22 @@ export async function handleLocalRequest(store, req, res, { staticDir } = {}) {
     }
   }
 
+  // Single Burner has no OAuth discovery documents. Do not serve the SPA (or
+  // its setup credentials) to MCP clients probing standard metadata paths.
+  if (url.pathname.startsWith('/.well-known/')) {
+    sendJson(res, 404, { error: 'NOT_FOUND' });
+    return;
+  }
+
+  if (url.pathname === '/mcp' && mcp) {
+    if (req.headers.origin) {
+      sendJson(res, 403, { error: 'MCP_BROWSER_ORIGIN_FORBIDDEN' });
+      return;
+    }
+    await mcp.handle(req, res);
+    return;
+  }
+
   if (!url.pathname.startsWith('/api') && !url.pathname.startsWith('/auth')) {
     if (tryStatic(staticDir, url.pathname, res)) return;
     const { rawToken, traceId } = store.credentials();
@@ -477,7 +503,7 @@ FLAMBE_TRACE_ID=${traceId}</pre>
   const agent = identifyAgent(store, req, auth);
   let result;
   try {
-    result = await dispatch(store, req, url, body, { auth, agent });
+    result = await dispatch(store, req, url, body, { auth, agent, runCommand });
   } catch (error) {
     if (!(error instanceof CommandError)) throw error;
     result = { status: error.status, json: error.body };