@davvidbaker/flambe-cli 0.1.3 → 0.1.4

package/README.md

@@ -1,6 +1,6 @@
 # @davvidbaker/flambe-cli
 
-Zero-dependency Node 22 CLI that streams coding-agent work into a Flambe trace.
+Node 22 CLI that streams coding-agent work into a Flambe trace.
 
 ## Install
 
@@ -61,3 +61,16 @@ FLAMBE_TRACE_ID=1
 Mint a token in Flambe Settings → API tokens. See the
 [repository README](https://github.com/davvidbaker/flambe#connect-coding-agents)
 for commands (`start`, `end`, `message`, `observe`, local `serve`).
+
+## Single Burner AI review
+
+When running `flambe serve`, optional AI review is configured in that server
+process with `FLAMBE_LOCAL_REDUCER_MODE=off|agent|api|local`. It is off by default;
+provider failures never reroute work to Cloud. See the
+[Single Burner configuration guide](../single-burner/README.md#optional-ai-reducer)
+for model, endpoint, credential, timeout, and data-boundary settings. Client
+processes only need their normal local Flambe connection settings.
+
+In `agent` mode, your current work AI reads the review returned by `flambe message`
+and submits its decision with `flambe decide <review-id> --file <decision.json>`.
+No separate model or inference API key is required.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davvidbaker/flambe-cli",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "CLI for streaming coding-agent activity into Flambe",
   "type": "module",
   "bin": {
@@ -30,5 +30,9 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/node": "2.1.1",
+    "@modelcontextprotocol/server": "2.3.1"
   }
 }

package/src/cli.mjs

@@ -27,6 +27,7 @@ const usage = `Usage:
   flambe ping
   flambe whoami [--json]
   flambe message <text> [--activity <id>] [--json]
+  flambe decide <review-id> --file <decision.json>
   flambe observe <kind> <value> [--unit <unit>] [--on <YYYY-MM-DD>] [--payload <json>] [--at <ISO-8601>]
   flambe serve [--port <n>] [--db <path>] [--static <dir>]
   flambe export [file] [--db <path>]
@@ -55,6 +56,7 @@ Optional:
   FLAMBE_QUEUE_PATH  Local offline queue path (default: ~/.flambe/event-queue.json)
   FLAMBE_LOCAL_DB    SQLite path for flambe serve / export (default: ~/.flambe/local.sqlite)
   FLAMBE_RUNTIME_MODE  local_self_contained restricts CLI requests to numeric loopback; cloud preserves hosted access
+  FLAMBE_LOCAL_REDUCER_MODE  off (default), agent, api, or local; see the Single Burner README
 
 serve / export do not need FLAMBE_URL. import needs FLAMBE_URL and FLAMBE_API_TOKEN (the production instance).`;
 
@@ -336,6 +338,11 @@ function formatReducerNote(note) {
     const lines = [];
     if (note.direction) lines.push(`direction\t${note.direction}\n`);
     if (note.reply) lines.push(`reply\t${note.reply}\n`);
+    if (note.modelReview?.status === 'available') lines.push(`review available\tRequest flambe message --activity ${note.activityId} when scope judgment is needed.\n`);
+    if (note.review) lines.push(`review\t${JSON.stringify(note.review)}\n`);
+    if (note.modelReview?.status === 'failed') {
+      lines.push(`model review\t${note.modelReview.code}: ${note.modelReview.message} Recorded work was preserved.\n`);
+    }
     if (note.actionsApplied?.length) {
       lines.push(`actions\t${note.actionsApplied.map(formatAction).join('; ')}\n`);
     }
@@ -364,7 +371,7 @@ export async function run(argv, { env = process.env, stdout = process.stdout, st
   if (command === 'serve') {
     const options = parseServe(args, env);
     const { listenLocal, printServeBanner } = await loadServe();
-    const listening = await listenLocal(options);
+    const listening = await listenLocal({ ...options, reducer: { env } });
     printServeBanner(listening, stdout);
     await new Promise((resolveClose, reject) => {
       listening.server.on('close', resolveClose);
@@ -518,11 +525,24 @@ export async function run(argv, { env = process.env, stdout = process.stdout, st
     return;
   }
 
+  if (command === 'decide') {
+    const { value: file, rest } = takeOption(args, '--file');
+    if (!file || rest.length !== 1 || rest[0].startsWith('--')) {
+      throw new Error('Usage: flambe decide <review-id> --file <decision.json>');
+    }
+    const content = readFileSync(resolve(file), 'utf8');
+    if (Buffer.byteLength(content) > 65_536) throw new Error('Decision file exceeds the size limit');
+    const result = await flambe.decide({ reviewId: rest[0], decision: JSON.parse(content) });
+    if (persistQuestions && !(result.actions_applied ?? []).some(a => a.type === 'ask')) clearQuestion(traceId, questionFile);
+    stdout.write(`${JSON.stringify(result)}\n`);
+    return;
+  }
+
   if (command === 'message') {
     const { text, activityId, json } = parseMessage(args);
     const decision = await flambe.message({ activityId, text });
-    if (persistQuestions) clearQuestion(traceId, questionFile);
-    if (json) {
+    if (persistQuestions && !decision.review) clearQuestion(traceId, questionFile);
+    if (json || decision.review) {
       stdout.write(`${JSON.stringify(decision)}\n`);
     } else {
       stdout.write(`activity\t${decision.activityId}\n`);

package/src/client.mjs

@@ -155,6 +155,7 @@ export class FlambeClient {
             || REQUIRED_AGENT_COMMANDS.some(command => !commands.includes(command))) {
             throw new Error('Flambe API returned an invalid agent-command capability document');
           }
+          this.agentCommandDetails = payload.data;
           return true;
         })
         .catch(error => {
@@ -636,13 +637,15 @@ export class FlambeClient {
     const actions = result.actions_applied ?? [];
     const direction = result.direction ?? null;
     const reply = result.reply ?? null;
-    if (!direction && !reply && actions.length === 0) return;
+    if (!direction && !reply && actions.length === 0 && !result.model_review) return;
     this.onReducerNote?.({
       type: 'command_result',
       activityId: result.activity_id,
       direction,
       reply,
       actionsApplied: actions,
+      ...(result.model_review ? { modelReview: result.model_review } : {}),
+      ...(result.review ? { review: result.review } : {}),
       asked: actions.some(action => action.type === 'ask'),
     });
   }
@@ -699,6 +702,16 @@ export class FlambeClient {
     return this.request('/api/imports', { method: 'POST', body: bundle });
   }
 
+  /** Work-AI decisions are never queued or sent to a substitute connection. */
+  async decide({ reviewId, decision }) {
+    if (!(await this.supportsAgentCommands()) || !this.agentCommandDetails?.reducer?.work_ai_reviews) {
+      throw new Error('This connection does not support work-AI reviews. Configure agent reducer mode on Single Burner.');
+    }
+    const result = await this.agentCommand('decide', { ...this.commandIdentity(), review_id: reviewId, decision });
+    this.reportCommandResult(result);
+    return result;
+  }
+
   /**
    * Send a free-text update to the Reducer Agent. It answers with assessment /
    * direction / reply and, as the single writer for the stack (ADR-011), may apply at
@@ -726,7 +739,7 @@ export class FlambeClient {
         message: text.trim(),
       });
       const decision = { activityId: result.activity_id ?? resolvedActivityId, ...result };
-      this.reportCommandResult(result);
+      if (!result.review) this.reportCommandResult(result);
       return decision;
     }
 

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 };

package/src/local/mcp.mjs

@@ -0,0 +1,92 @@
+import { readFileSync } from 'node:fs';
+import { Server, createMcpHandler, fromJsonSchema, ProtocolError } from '@modelcontextprotocol/server';
+import { toNodeHandler } from '@modelcontextprotocol/node';
+import { CommandError, executeCommand } from './commands.mjs';
+import { schema as decisionSchema } from './reducer-review.mjs';
+
+const baseTools = JSON.parse(readFileSync(new URL('../mcp-tools.json', import.meta.url), 'utf8'));
+const decideTool = {
+  name: 'flambe_decide', title: 'Submit your Single Burner review decision',
+  description: 'Submit the current work AI decision for a review returned by flambe_message or a flagged start. Use that exact review_id, trace, instance, and agent_id. Single Burner validates and applies it locally, without another model call. Identical retries return a receipt; stale reviews require a fresh flambe_message. This is the work AI reviewing its own context, not independent approval.',
+  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  inputSchema: { type: 'object', additionalProperties: false,
+    required: ['expected_instance_id', 'trace_id', 'agent_id', 'review_id', 'decision'],
+    properties: {
+      ...Object.fromEntries(['expected_instance_id', 'trace_id', 'agent_id'].map(key =>
+        [key, baseTools.find(t => t.name === 'flambe_message').inputSchema.properties[key]])),
+      review_id: { type: 'string', minLength: 1, description: 'Exact review.review_id returned by this Single Burner connection.' },
+      decision: decisionSchema,
+    } },
+};
+
+function result(instance, data, isError = false) {
+  const structuredContent = { ...data, instance };
+  return { content: [{ type: 'text', text: JSON.stringify(structuredContent) }], structuredContent, isError };
+}
+
+/** Stateless MCP transport; the existing SQLite command engine owns all mutations. */
+export function createLocalMcpHandler(store, runCommand = (userId, command, args, agent) => executeCommand(store, userId, command, args, agent)) {
+  const tools = [...baseTools, ...(runCommand.info?.work_ai_reviews ? [decideTool] : [])];
+  const validators = new Map(tools.map(tool => [tool.name, fromJsonSchema(tool.inputSchema)['~standard']]));
+  const reviewDescription = runCommand.info?.work_ai_reviews
+    ? ' Work-AI review: this returns review context and a review_id. Reason over it and submit your decision with flambe_decide, using the same agent_id. No separate model is called.'
+    : ` AI reducer mode: ${runCommand.info?.mode ?? 'off'}; API mode sends activity context to the configured model provider, local mode uses a loopback model endpoint.`;
+  const handler = createMcpHandler(context => {
+    const instance = store.instance();
+    const token = context.requestInfo.headers.get('authorization')?.replace(/^Bearer /, '');
+    const auth = store.authenticateToken(token);
+    const server = new Server({ name: 'flambe', title: 'Flambe — Single Burner', version: '0.1.0' }, {
+      capabilities: { tools: { listChanged: false } },
+      instructions: `This connection accesses Single Burner only. Discover its instance with flambe_traces; never substitute Cloud or Development. AI reducer mode: ${runCommand.info?.mode ?? 'off'}.`,
+    });
+
+    server.setRequestHandler('tools/list', () => ({ tools: tools.map(({ securitySchemes, ...tool }) => ({
+      ...tool,
+      description: `${tool.description} Connected instance: Single Burner. This connection cannot access Cloud or Development.${tool.name === 'flambe_message' ? reviewDescription : ''}`,
+      annotations: { ...tool.annotations, openWorldHint: false },
+    })) }));
+
+    server.setRequestHandler('tools/call', async request => {
+      const { name, arguments: args = {} } = request.params;
+      const validator = validators.get(name);
+      if (!validator) throw new ProtocolError(-32602, `Unknown tool: ${name}`);
+      if (name !== 'flambe_traces') {
+        const code = !args.expected_instance_id ? 'INSTANCE_REQUIRED'
+          : args.expected_instance_id !== instance.id ? 'INSTANCE_MISMATCH' : null;
+        if (code) return result(instance, { code, message: code === 'INSTANCE_REQUIRED'
+          ? 'Call flambe_traces on this connection and pass its instance.id as expected_instance_id.'
+          : 'This connection is Single Burner. The requested instance does not match; no activity was read or changed.' }, true);
+      }
+      const validated = await validator.validate(args);
+      if (validated.issues) return result(instance, { code: 'INVALID_INPUT', message: validated.issues.map(issue => issue.message).join('; ') }, true);
+      if (name === 'flambe_traces') {
+        const traces = store.listTraces(auth.user.id).map(({ id, name: traceName }) => ({ id, name: traceName }));
+        return result(instance, { traces, default_trace_id: traces[0]?.id ?? null, reducer: runCommand.info ?? { mode: 'off' } });
+      }
+      const { expected_instance_id, ...arguments_ } = args;
+      // Header identity has the same precedence as the REST adapter.
+      const agentId = context.requestInfo.headers.get('x-flambe-agent-id') ?? arguments_.agent_id;
+      const agent = agentId ? store.identifyAgent(auth.user.id, agentId,
+        context.requestInfo.headers.get('x-flambe-agent-name') ?? arguments_.agent_name,
+        context.requestInfo.headers.get('x-flambe-agent-platform') ?? arguments_.platform) : null;
+      try {
+        return result(instance, await runCommand(auth.user.id, name.slice('flambe_'.length), arguments_, agent));
+      } catch (error) {
+        if (!(error instanceof CommandError)) throw error;
+        const { error: { code, message, ...details } } = error.body;
+        return result(instance, { code, message, ...details }, true);
+      }
+    });
+    return server;
+  });
+
+  // Bearer authentication is checked before the SDK sees any MCP method.
+  const nodeHandler = toNodeHandler({ fetch(request) {
+    const header = request.headers.get('authorization');
+    if (!header?.startsWith('Bearer ') || !store.authenticateToken(header.slice(7))) {
+      return Response.json({ error: 'UNAUTHENTICATED' }, { status: 401 });
+    }
+    return handler.fetch(request);
+  } });
+  return { handle: nodeHandler, close: () => handler.close() };
+}

package/src/local/reducer-provider.mjs

@@ -0,0 +1,106 @@
+import { CommandError } from './commands.mjs';
+
+const configError = message => new CommandError(503, 'REDUCER_CONFIG_INVALID', message);
+const providerError = message => new CommandError(502, 'REDUCER_PROVIDER_ERROR', message);
+const loopback = host => ['127.0.0.1', 'localhost', '[::1]'].includes(host);
+
+/** Explicit opt-in: unrelated OPENAI_API_KEY/Cloud settings never enable review. */
+export function reducerConfig(env = process.env) {
+  const mode = env.FLAMBE_LOCAL_REDUCER_MODE ?? 'off';
+  if (mode === 'off') return { mode };
+  if (mode === 'agent') {
+    const reviewStarts = env.FLAMBE_LOCAL_REDUCER_REVIEW_STARTS ?? 'false';
+    if (!['false', 'true'].includes(reviewStarts)) throw configError('FLAMBE_LOCAL_REDUCER_REVIEW_STARTS must be true or false.');
+    return { mode, reviewStarts: reviewStarts === 'true' };
+  }
+  if (!['api', 'local'].includes(mode)) throw configError('FLAMBE_LOCAL_REDUCER_MODE must be off, agent, api, or local.');
+  const model = env.FLAMBE_LOCAL_REDUCER_MODEL?.trim();
+  if (!model) throw configError('Set FLAMBE_LOCAL_REDUCER_MODEL explicitly.');
+  let base;
+  try {
+    base = new URL(env.FLAMBE_LOCAL_REDUCER_BASE_URL ?? (mode === 'api'
+      ? 'https://api.openai.com/v1/' : 'http://127.0.0.1:11434/'));
+  } catch { throw configError('The reducer base URL is invalid.'); }
+  if (base.username || base.password || base.search || base.hash) {
+    throw configError('The reducer URL must not contain credentials, a query, or a fragment.');
+  }
+  if (mode === 'local' && (!['http:', 'https:'].includes(base.protocol) || !loopback(base.hostname))) {
+    throw configError('Local reducer mode requires a loopback model endpoint.');
+  }
+  if (mode === 'local' && /(?:^|[-:])cloud(?:$|[-:])/i.test(model)) {
+    throw configError('Choose an installed local model, not a cloud model.');
+  }
+  if (mode === 'api' && base.protocol !== 'https:') throw configError('API reducer mode requires HTTPS.');
+  const apiKey = mode === 'api' ? env.FLAMBE_LOCAL_REDUCER_API_KEY?.trim() : undefined;
+  if (mode === 'api' && !apiKey) throw configError('Set FLAMBE_LOCAL_REDUCER_API_KEY for API mode.');
+  const timeoutMs = Number(env.FLAMBE_LOCAL_REDUCER_TIMEOUT_MS ?? 30_000);
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 90_000) {
+    throw configError('Reducer timeout must be between 1 and 90000 milliseconds.');
+  }
+  if (!base.pathname.endsWith('/')) base.pathname += '/';
+  return { mode, model, apiKey, timeoutMs,
+    endpoint: new URL(mode === 'api' ? 'responses' : 'api/chat', base).href };
+}
+
+async function boundedJson(response) {
+  if (!response.ok) {
+    await response.body?.cancel();
+    throw providerError(`Model request failed (HTTP ${response.status}).`);
+  }
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > 1_048_576) throw providerError('Model response exceeded the size limit.');
+      chunks.push(value);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  } finally { await reader.cancel().catch(() => {}); }
+}
+
+export function createReducerProvider(config, { fetchImpl = globalThis.fetch } = {}) {
+  return {
+    mode: config.mode,
+    model: config.model,
+    reviewStarts: config.reviewStarts,
+    async review({ system, context, schema }) {
+      if (['off', 'agent'].includes(config.mode)) throw new CommandError(503, 'REDUCER_NOT_CONFIGURED', 'AI reducer review is off.');
+      const input = JSON.stringify(context);
+      const body = config.mode === 'api' ? {
+        model: config.model, store: false, max_output_tokens: 2000,
+        input: [{ role: 'system', content: system }, { role: 'user', content: input }],
+        text: { format: { type: 'json_schema', name: 'flambe_reducer_decision', strict: true, schema } },
+      } : {
+        model: config.model, stream: false, format: schema,
+        messages: [{ role: 'system', content: system }, { role: 'user', content: input }],
+        options: { temperature: 0, num_predict: 2000 },
+      };
+      try {
+        const response = await fetchImpl(config.endpoint, {
+          method: 'POST', redirect: 'error', signal: AbortSignal.timeout(config.timeoutMs),
+          headers: { 'content-type': 'application/json', ...(config.mode === 'api'
+            ? { authorization: `Bearer ${config.apiKey}` } : {}) },
+          body: JSON.stringify(body),
+        });
+        const data = await boundedJson(response);
+        if ((config.mode === 'api' && data.status && data.status !== 'completed')
+          || data.done === false || data.done_reason === 'length') throw providerError('Model response was incomplete.');
+        const text = config.mode === 'local' ? data.message?.content
+          : data.output?.flatMap(item => item.content ?? []).find(item => item.type === 'output_text')?.text;
+        if (typeof text !== 'string') throw providerError('Model did not return a decision.');
+        return JSON.parse(text);
+      } catch (error) {
+        if (error instanceof CommandError) throw error;
+        if (['TimeoutError', 'AbortError'].includes(error?.name)) {
+          throw new CommandError(504, 'REDUCER_TIMEOUT', 'AI reducer review timed out.');
+        }
+        // Never return provider response bodies, URLs, headers, or credential-bearing errors.
+        throw providerError('AI reducer request failed or returned invalid JSON.');
+      }
+    },
+  };
+}