@davvidbaker/flambe-cli 0.1.3 → 0.1.5

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,69 @@ 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.
+
+## Local Codex / Single Burner hooks
+
+With Single Burner running, put its printed connection values in the target
+project's `.env`, including `FLAMBE_RUNTIME_MODE=local_self_contained`. From
+that project root run:
+
+```sh
+flambe setup codex
+```
+
+This installs project-scoped Codex hooks and the bundled `flambe-cli` skill.
+It preserves unrelated hooks, backs up an existing `hooks.json` once, and keeps
+an existing custom skill rather than overwriting it. Restart local Codex, open
+`/hooks`, and review/trust the new definitions. Hook loading remains subject to
+project trust and workspace policy. No ChatGPT plugin, Platform organization,
+tunnel, or model API key is needed for this local route.
+
+Keep `flambe` available on PATH to the Codex process. Hooks use `flambe.cmd` on
+Windows and `flambe` on macOS/Linux, with no machine-specific checkout paths.
+If you installed the CLI while Codex was already open, restart the app so it can
+see the updated PATH.
+
+- Session start, resume, prompts, subagent start, and compaction restore context.
+- Tool hooks use a small cache, refresh local status at most once per 30 seconds
+  during ordinary work, and request a fresh stack check every ten tool calls or
+  90 seconds while tools continue. Explicit lifecycle checkpoints reset the
+  call counter; a timer does not run while the agent is idle.
+- Stop requests at most one reconciliation continuation after substantial tool
+  work without a verified checkpoint. It does not automatically close parents.
+- Interrupt records a pending local reconciliation reminder; it does not mutate
+  activities or prevent interruption.
+
+The agent still names/nests activities, decides when work changed, and submits
+requested reducer decisions. Hooks only send status requests to the configured
+numeric-loopback server. They do not call a model, inspect transcripts, or
+queue activity mutations. Missing configuration, an unavailable server, or an
+unidentifiable agent produces bounded feedback and permits work to continue.
+The local cache contains counters/fingerprints, not prompts, command text,
+credentials, or activity names. See [ADR-023](../docs/ADR-023-portable-local-codex-hooks.md).
+
+```sh
+flambe setup codex --check
+flambe setup codex --remove
+```
+
+`--check` inspects installed files and local connection configuration; it cannot
+confirm a live server, Codex trust, or workspace policy.
+`--remove` retains skills and unrelated hooks. For a live check, restart Codex,
+confirm these hooks are trusted in `/hooks`, then ask it to track a short local
+activity, request/submit an agent-mode review, and end or suspend the activity.
+Verify that the chart and that agent's lane reflect the result. A fresh install
+on the work laptop still needs this native Codex verification.

package/bin/flambe.mjs

@@ -3,7 +3,8 @@
 import { run } from '../src/cli.mjs';
 import { loadProjectEnv } from '../src/env.mjs';
 
-loadProjectEnv();
+// Hook input selects its installed project root; do not preload a nested .env.
+if (process.argv[2] !== 'hook') loadProjectEnv();
 
 try {
   await run(process.argv.slice(2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davvidbaker/flambe-cli",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "CLI for streaming coding-agent activity into Flambe",
   "type": "module",
   "bin": {
@@ -9,11 +9,14 @@
   "files": [
     "bin",
     "src",
-    "README.md"
+    "README.md",
+    "skills",
+    "scripts/prepare-skills.mjs"
   ],
   "scripts": {
     "test": "node --test",
-    "prepublishOnly": "npm test"
+    "prepublishOnly": "npm test",
+    "prepack": "node scripts/prepare-skills.mjs"
   },
   "engines": {
     "node": ">=22"
@@ -30,5 +33,9 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/node": "2.1.1",
+    "@modelcontextprotocol/server": "2.3.1"
   }
 }

package/scripts/prepare-skills.mjs

@@ -0,0 +1,12 @@
+import {copyFileSync, existsSync, mkdirSync} from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import {dirname} from 'node:path';
+
+const source = fileURLToPath(new URL('../../.codex/skills/flambe-cli/SKILL.md', import.meta.url));
+const target = fileURLToPath(new URL('../skills/flambe-cli/SKILL.md', import.meta.url));
+if (existsSync(source)) {
+  mkdirSync(dirname(target), {recursive: true});
+  copyFileSync(source, target);
+} else if (!existsSync(target)) {
+  throw new Error('The CLI package is missing its canonical flambe-cli skill.');
+}

package/skills/flambe-cli/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: flambe-cli
+description: Track coding-agent work in a Flambe trace with the flambe CLI. Use when logging substantial or multi-step work in a project configured with FLAMBE_URL, FLAMBE_API_TOKEN, and FLAMBE_TRACE_ID.
+---
+
+# Flambe CLI
+
+Log semantic work units as a live flame chart — not commands, file opens, or hidden reasoning. Skip trivial questions. If `FLAMBE_URL`, `FLAMBE_API_TOKEN`, or `FLAMBE_TRACE_ID` is set neither in `.env` nor in the shell environment (Cloud Agent secrets arrive as environment variables), skip silently.
+
+Needs Node 22+ and `flambe` on `PATH`. If it is missing, `npm install -g @davvidbaker/flambe-cli`; in this repo without a global install, use `node cli/bin/flambe.mjs`. You do not need to pick a name: the reducer names each agent on its first request, the CLI remembers it (`~/.flambe/agent-names.json`) and prints `reducer named this agent "X"` on stderr once. `flambe whoami` shows your id, name, and platform. `FLAMBE_AGENT_PLATFORM` is the product you run on (`"Cursor Cloud"`, `"Codex"`; derived from the session when unset) and is shared by many agents; it is not your name. Set `FLAMBE_AGENT_NAME` only to override; never put `FLAMBE_AGENT_ID`, `FLAMBE_AGENT_NAME`, or `FLAMBE_AGENT_PLATFORM` in `.env`.
+
+## Think in a stack
+
+Always treat attention as a **call stack**, not a flat to-do list.
+
+You will often produce some progress on a parent goal, then go down a rabbit hole about one specific thing (a bug, a prerequisite, a design question, a test failure). That digression is a **push**: start a nested activity under the still-running parent. When the rabbit hole is done, **pop**: end the nested activity with the outcome, and continue the parent where you left off.
+
+- Leave parents running while you dig. Ending the parent when you dive deeper flattens the chart and loses the “come back up” story.
+- Nested steps belong under the workstream they serve — not as siblings of the top objective.
+- When attention moves to a true sibling of the current leaf, end the leaf first, then start the sibling under the same parent.
+- Use `--root` only for a genuinely new top-level workstream, not for every digression.
+- Keep the active stack truthful as work changes. Do not plan a detailed chart up front or reconstruct one afterward.
+
+## Local Codex hooks
+
+For a Single Burner project, run `flambe setup codex` from its root after setting
+its local connection values in `.env`. Setup merges project hooks into
+`.codex/hooks.json` and installs this skill if it is missing. Existing custom
+skills and unrelated hooks are retained. Restart local Codex and review/trust
+these hooks with `/hooks`; installed files alone do not prove they are running.
+Use `flambe setup codex --check` to inspect the files, and `--remove` to remove
+only Flambe's own hook handlers. Keep `flambe` on PATH; Windows hooks use
+`flambe.cmd` so PowerShell script policy does not select `flambe.ps1`.
+
+Hooks restore workflow context, request periodic stack checks, and can request
+one reconciliation continuation before a substantive turn ends. They make no
+inference calls or semantic activity changes. You still start/nest/end the real
+work and complete requested work-AI reviews. A turn ending does not mean its
+parent task ended. Missing servers or identity produce feedback without blocking
+ordinary work. Hooks require `local_self_contained`; they do not route to Cloud.
+
+## Commands
+
+```sh
+flambe start "Fix USERPROFILE resolution"     # prints id; nests under the current active activity
+flambe start "Add Windows support" --root     # new top-level workstream
+flambe end "$ID" "Resolved USERPROFILE on Windows"
+flambe suspend "$ID" "Waiting for product decision"   # only when explicitly tabling work
+flambe resume "$ID" "Decision received"
+flambe observe carbon 312.4 --unit gCO2eq/kWh --on 2026-09-04 --payload '{"source":"us-ba-mean"}'
+flambe message "Auth fix needs the session module refactored too; widening scope"   # ask the Reducer Agent
+```
+
+`observe` writes a user overlay (carbon, mood, …), not an activity. Same `kind` + `--on` date upserts and merges payload keys. Omit `--on` to always insert.
+
+**255-character hard limit on activity names and `--description`.** The column is `varchar(255)`. A longer value returns a 500 and can wedge the offline queue. Count before `start`. Prefer a short concrete name; put detail in the end/suspend/resume message (those are unbounded).
+
+Reuse this conversation's activity id when you already have one. Run `flambe status --active --json` only to find a matching open activity from this session; ignore unrelated active work. Do not fetch threads or categories to decide placement; that is the reducer's job.
+
+Every command is a proposal; the reducer owns the stack. Without `--parent`/`--root`, `start` nests under **your own** newest active activity (other agents' work is never your parent), puts a child on its parent's thread, and gives it the parent's categories; a new root gets its thread and categories chosen by the reducer a few seconds later. `FLAMBE_THREAD` (name, unique slug, or id) is sent as `--thread` when that flag is omitted; do not list threads and pick one by project name. Pass `--thread` / `--parent` / `--category` only when you are certain. Offline `offline-…` ids from `start` are valid for `end`. Do not retry queued operations. Offline results carry no immediate reducer output; nothing is dropped. Local `serve` always applies deterministic rules, including duplicate reuse, ancestor resumption, and descendant closure. Optional review is off by default; an explicitly configured server can ask the current work AI to review or call a separate model.
+
+## Read every result; the reducer may rewrite
+
+Any command (`start`, `end`, `suspend`, `resume`, `message`) may come back with `direction`, `reply`, and `actions_applied`, not only `message`. The reducer records what you proposed and then corrects the structure around it when needed: re-parent, rename, treat your `start` as a resume of an already-open same-name activity, resume a suspended ancestor before nesting under it, or close open descendants when you end a parent (`--force`). The CLI prints each rewrite on stderr (`reducer nested 43 under 42`, `actions`). The returned state is the truth: keep using the ids it gives you, do not undo a rewrite, and do not re-issue the proposal.
+
+The reducer may answer a proposal with a question in `reply`, usually when a name does not fit its ancestors. Answer before your next step: rename the activity, or reply with `flambe message`. The CLI reminds you on the next command if a question is still open; it never refuses.
+
+A returned `direction` is binding: act on it before doing more work. On `pause`, `stop`, or `escalate`, stop and surface the reply to David rather than deciding yourself. `direction -` or none means continue as you were. A model-judged `start` can take a few seconds; wait for it.
+
+## Review with the AI doing the work
+
+Review only at meaningful scope/approach decisions or when placement is uncertain.
+Routine lifecycle tracking uses deterministic local rules. Do not review every
+start/end, and do not request full history for routine bookkeeping. Work-AI
+review context contains the current path and this agent's open work. Compact
+lifecycle replies mark their state scope; omitted activities are not ended.
+
+When a local result contains `review` and `model_review.status: awaiting_decision`,
+you are the reviewer. This is the current work AI evaluating its own context,
+not independent approval. Do not start another model, ask for provider keys, or
+claim a separate reviewer approved your work.
+
+Read `review.instructions`, `review.context`, and `review.decision_schema`.
+Evaluate the user's intent, current path, and proposed scope. Choose concise
+assessment, direction, reply, rationale, and at most one permitted action.
+Write that decision as JSON and submit it with:
+
+```sh
+flambe decide <review.review_id> --file <decision.json>
+```
+
+`flambe message` returns the review JSON in this mode. Flagged starts normally
+print only a small review-available notice on stderr; request review only when
+scope or placement needs judgment. They include full review JSON only when the
+server explicitly enables automatic start reviews. Stdout remains the recorded id. Keep the same local
+connection, trace, and stable agent id for both steps. Ordinary
+lifecycle tracking continues to use start/end/suspend/resume.
+
+Complete a requested review before continuing substantive work. Follow the
+returned direction after submission; escalate unresolved human judgment with no
+actions and ask the user. Do not repeat the recorded start to request review.
+On `REDUCER_STATE_CHANGED` or `REVIEW_EXPIRED`, request a fresh review with
+`flambe message` for that activity, reassess it, and submit against the new id.
+Do not resubmit the old decision blindly. Identical retries of a completed
+submission return a receipt; `replayed: true` means no new action was applied.
+If the server lacks work-AI review support, report that instead of changing instances.
+
+## End of work
+
+When the work you were doing is finished, check limbo and scheduled activities before you stop. Run `flambe status --unstarted --json`. If something there is worth doing next, propose that candidate with `flambe message` and begin it only if the reply says continue. Do not begin it unasked, and do not ask David in chat.
+
+## Ask the reducer before you drift
+
+`flambe message "<update>"` is your own channel: it sends your update plus the live flame (open and suspended work, the path to the current activity, and ended work from the last 21 days) and answers with `assessment`, `direction`, `reply`, and at most one stack change. Message when you are about to:
+
+- widen scope beyond the activity you started
+- change approach after the plan stalled
+- end a root workstream
+- continue while suspecting the work has drifted from what David asked
+- answer a question the reducer asked
+
+Do not message for routine progress, and never instead of `start`/`end`. Defaults to your newest active activity; pass `--activity <id>` to target another. Needs a reachable server with model review configured (not queued). Local self-contained `serve` has optional review, off by default, including an `agent` mode that returns review context for you to evaluate. On `REDUCER_NOT_CONFIGURED`, do not retry or switch to a remote server; surface unresolved judgment to the user and continue deterministic logging. A lifecycle result with `model_review.status: failed` still recorded the activity: keep its returned id/state, surface the review failure, and do not repeat the start or retarget another instance.
+
+## What to record
+
+- Start a new activity when the goal or scope meaningfully changes (a specific implementation, a discovered prerequisite, a concrete bug, focused tests, verification) — that is a stack push.
+- Do not start an activity for committing or pushing. Those are wrap-up of the current leaf; mention them in the end-message if useful. Exception: the assigned work *is* getting code onto a remote.
+- Name the concrete action and object (`Fix USERPROFILE config resolution`), not `Investigate` / `Implement` / `Work on tests`. Stay well under 255 characters; do not compensate with a long name or `--description`.
+- End-message: the outcome, not `done`. That records a resolution. Omitting the message is a plain end. No secrets, tokens, or transcripts. Ending the leaf is the pop; then resume the parent mentally and in the log.

package/src/cli.mjs

@@ -27,6 +27,8 @@ const usage = `Usage:
   flambe ping
   flambe whoami [--json]
   flambe message <text> [--activity <id>] [--json]
+  flambe decide <review-id> --file <decision.json>
+  flambe setup codex [--check | --remove]
   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 +57,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 +339,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`);
     }
@@ -353,9 +361,43 @@ function formatReducerNote(note) {
   return `reducer: ${JSON.stringify(note)}\n`;
 }
 
-export async function run(argv, { env = process.env, stdout = process.stdout, stderr = process.stderr, client, questionsPath } = {}) {
+export async function run(argv, { env = process.env, stdout = process.stdout, stderr = process.stderr, stdin = process.stdin, client, questionsPath } = {}) {
   const [command, ...args] = argv;
 
+  if (command === 'hook' && args.length === 1 && args[0] === 'codex') {
+    const {readHookInput, runCodexHook} = await import('./codex-hook.mjs');
+    let output;
+    try { output = await runCodexHook(await readHookInput(stdin), {env}); }
+    catch { output = {systemMessage: 'Single Burner hook input could not be read; work may continue.'}; }
+    stdout.write(`${JSON.stringify(output)}\n`);
+    return;
+  }
+
+  if (command === 'setup') {
+    if (args[0] !== 'codex' || args.length > 2
+      || (args[1] !== undefined && !['--check', '--remove'].includes(args[1]))) {
+      throw new Error('Usage: flambe setup codex [--check | --remove]');
+    }
+    const {setupCodex} = await import('./codex-setup.mjs');
+    const action = args[1] === '--check' ? 'check' : args[1] === '--remove' ? 'remove' : 'install';
+    const result = setupCodex({action});
+    let localConnectionConfigured = false;
+    try {
+      localConnectionConfigured = env.FLAMBE_RUNTIME_MODE === 'local_self_contained' && Boolean(clientFromEnv(env));
+    } catch { /* Only report whether the config is usable; never echo credentials. */ }
+    if (action === 'check') stdout.write(`${JSON.stringify({...result, localConnectionConfigured})}\n`);
+    else if (action === 'remove') stdout.write(`Single Burner Codex hooks ${result.removed ? 'removed' : 'were not installed'}. Existing skills and unrelated hooks were retained.\n`);
+    else {
+      stdout.write(`Single Burner Codex hooks installed in ${result.root}\n`);
+      stdout.write(result.skillInstalled ? 'Installed the flambe-cli skill.\n' : 'Kept the existing flambe-cli skill.\n');
+      if (!result.skillMatches) stdout.write('The existing skill differs from the bundled version; review it for current work-AI review instructions.\n');
+      if (!localConnectionConfigured) stdout.write('Copy Single Burner connection values into this project .env, including FLAMBE_RUNTIME_MODE=local_self_contained, before using the hooks.\n');
+      stdout.write('Restart the local Codex session. Review and trust these project hooks with /hooks before relying on them. Workspace policy can restrict hooks.\n');
+      stdout.write('Run flambe setup codex --check to inspect installed files and connection configuration. This does not confirm Codex trust or live hook execution.\n');
+    }
+    return;
+  }
+
   if (!command || command === 'help' || command === '--help' || command === '-h') {
     stdout.write(`${usage}\n`);
     return;
@@ -364,7 +406,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 +560,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;
     }