@davvidbaker/flambe-cli 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,63 @@
+# @davvidbaker/flambe-cli
+
+Zero-dependency Node 22 CLI that streams coding-agent work into a Flambe trace.
+
+## Install
+
+```sh
+npm install -g @davvidbaker/flambe-cli
+```
+
+That puts `flambe` on `PATH`. One-off:
+
+```sh
+npx @davvidbaker/flambe-cli --help
+```
+
+From this checkout (no npm):
+
+```sh
+node cli/bin/flambe.mjs --help
+# or
+cd cli && npm link
+```
+
+## Cursor Cloud and other repos
+
+1. Install the CLI in the environment (or at the start of an agent session):
+
+   ```sh
+   npm install -g @davvidbaker/flambe-cli
+   ```
+
+2. Set Cloud secrets / env: `FLAMBE_URL`, `FLAMBE_API_TOKEN`, `FLAMBE_TRACE_ID`.
+   Optional: `FLAMBE_THREAD` (name, unique slug, or id) is sent on `start` when
+   `--thread` is omitted. Do not list threads and pick one by project name.
+   Copy the `flambe-cli` skill from this repo (`.codex/skills/flambe-cli`) so
+   agents know when to `start` / `end`.
+
+3. Set `FLAMBE_AGENT_PLATFORM` to the product (`Cursor Cloud`) as a Cloud
+   secret; it is shared by every agent there. Agents do not need a name: the
+   reducer assigns one on first contact and the CLI remembers it
+   (`flambe whoami`). Set `FLAMBE_AGENT_NAME` only to override. Do not put
+   `FLAMBE_AGENT_ID` or `FLAMBE_AGENT_NAME` in `.env`.
+
+CI publishes this package from `cli/` via npm trusted publishing when
+`cli/package.json` on `main` changes. Local `npm publish` needs access to
+`@davvidbaker`.
+
+## Configure
+
+Create a `.env` in the project working directory (or set the same names in the
+shell; shell wins):
+
+```dotenv
+FLAMBE_URL=https://your-app.fly.dev
+FLAMBE_API_TOKEN=flb_...
+FLAMBE_TRACE_ID=1
+# FLAMBE_THREAD=flambe
+```
+
+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`).

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "@davvidbaker/flambe-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "CLI for streaming coding-agent activity into Flambe",
   "type": "module",
   "bin": {
     "flambe": "./bin/flambe.mjs"
   },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "prepublishOnly": "npm test"
   },
   "engines": {
     "node": ">=22"
@@ -15,6 +21,14 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/davvidbaker/flambe.git"
+    "url": "git+https://github.com/davvidbaker/flambe.git",
+    "directory": "cli"
+  },
+  "homepage": "https://github.com/davvidbaker/flambe/tree/main/cli",
+  "bugs": {
+    "url": "https://github.com/davvidbaker/flambe/issues"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/agentNames.mjs

@@ -0,0 +1,35 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+// Names the reducer assigned to agents on this machine, keyed by agent id (ADR-012).
+// Read synchronously because identity is resolved while the client is constructed.
+
+export function defaultAgentNamesPath() {
+  return join(homedir(), '.flambe', 'agent-names.json');
+}
+
+export function readAgentNames(path = defaultAgentNamesPath()) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+export function rememberedAgentName(agentId, path = defaultAgentNamesPath()) {
+  if (!agentId) return undefined;
+  const name = readAgentNames(path)[agentId];
+  return typeof name === 'string' && name.trim() ? name : undefined;
+}
+
+export function rememberAgentName(agentId, name, path = defaultAgentNamesPath()) {
+  if (!agentId || !name) return;
+  const names = { ...readAgentNames(path), [agentId]: name };
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(names, null, 2)}\n`);
+  renameSync(tmp, path);
+}

package/src/cli.mjs

@@ -1,8 +1,9 @@
-import { readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 
 import { clientFromEnv, clientFromHostEnv } from './client.mjs';
+import { clearQuestion, readOpenQuestion, rememberQuestion } from './questions.mjs';
 
 // `node:sqlite` still prints an ExperimentalWarning on import in some Node 22 releases.
 // Only serve/export need it, so load those modules on demand and keep every other
@@ -15,14 +16,16 @@ function defaultDbPath() {
 }
 
 const usage = `Usage:
-  flambe start <activity name> [--description <text>] [--thread <id>] [--parent <id> | --root] [--category <id>...] [--started-at <ISO-8601>]
+  flambe start <activity name> [--description <text>] [--thread <id|name>] [--parent <id> | --root] [--category <id>...] [--started-at <ISO-8601>]
   flambe end <activity-id> [message] [--force]
   flambe suspend <activity-id> [message]
   flambe resume <activity-id> [message]
-  flambe status [--active | --suspended] [--json]
+  flambe plan <activity name> [--start <ISO-8601>] [--end <ISO-8601>] [--description <text>] [--weight <n>]
+  flambe status [--active | --suspended] [--unstarted] [--json]
   flambe threads [--json]
   flambe categories [--json]
   flambe ping
+  flambe whoami [--json]
   flambe message <text> [--activity <id>] [--json]
   flambe observe <kind> <value> [--unit <unit>] [--on <YYYY-MM-DD>] [--payload <json>] [--at <ISO-8601>]
   flambe serve [--port <n>] [--db <path>] [--static <dir>]
@@ -41,9 +44,17 @@ Required values:
 Optional:
   FLAMBE_AGENT_ID    Stable ID for this running agent; enables named flame lanes.
                      Derived from Codex, Cursor, or Claude Code session env when unset.
-  FLAMBE_AGENT_NAME  Display name for this agent's lane. Do not put this in .env.
+  FLAMBE_AGENT_NAME  Override the lane name. Unset, the reducer names the agent and the
+                     CLI remembers it in ~/.flambe/agent-names.json. Do not put this in .env.
+  FLAMBE_AGENT_PLATFORM  Product the agent runs on, shared by many agents ("Cursor Cloud",
+                     "Codex"). Derived from the session type when unset.
+  FLAMBE_AGENT_NAMES_PATH  Where remembered agent names live.
+  FLAMBE_THREAD      Thread name, unique slug, or id for start when --thread is omitted
+                     (overridden by --thread). 'flambe' matches 'flambé🔥'. The reducer
+                     still keeps a child on its parent's thread.
   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
 
 serve / export do not need FLAMBE_URL. import needs FLAMBE_URL and FLAMBE_API_TOKEN (the production instance).`;
 
@@ -117,20 +128,55 @@ function parseEnd(args) {
   };
 }
 
+function parsePlan(args) {
+  const nameParts = [];
+  let description;
+  let weight;
+  let start;
+  let end;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--description') {
+      description = args[index + 1];
+      if (description === undefined) throw new Error('--description requires a value');
+      index += 1;
+    } else if (arg === '--weight') {
+      weight = Number(args[index + 1]);
+      if (!Number.isInteger(weight)) throw new Error('--weight requires an integer');
+      index += 1;
+    } else if (arg === '--start' || arg === '--end') {
+      const raw = args[index + 1];
+      if (raw === undefined) throw new Error(`${arg} requires an ISO-8601 timestamp`);
+      const parsed = Date.parse(raw);
+      if (!Number.isFinite(parsed)) throw new Error(`${arg} must be a valid ISO-8601 timestamp`);
+      if (arg === '--start') start = parsed;
+      else end = parsed;
+      index += 1;
+    } else if (arg.startsWith('--')) {
+      throw new Error(`Unknown option: ${arg}`);
+    } else nameParts.push(arg);
+  }
+  const name = nameParts.join(' ').trim();
+  if (!name) throw new Error('Usage: flambe plan <activity name> [--start <ISO-8601>] [--end <ISO-8601>]');
+  return { name, description, weight, scheduledStart: start, scheduledEnd: end };
+}
+
 function parseStatus(args) {
   let activeOnly = false;
   let suspendedOnly = false;
+  let includeUnstarted = false;
   let json = false;
 
   for (const arg of args) {
     if (arg === '--active') activeOnly = true;
     else if (arg === '--suspended') suspendedOnly = true;
+    else if (arg === '--unstarted') includeUnstarted = true;
     else if (arg === '--json') json = true;
     else throw new Error(`Unknown option: ${arg}`);
   }
 
   if (activeOnly && suspendedOnly) throw new Error('--active and --suspended cannot be used together');
-  return { activeOnly, suspendedOnly, json };
+  return { activeOnly, suspendedOnly, includeUnstarted, json };
 }
 
 function parseObserve(args) {
@@ -267,6 +313,14 @@ function parseImport(args) {
 function formatAction(action) {
   if (action.type === 'create_child') return `created child ${action.activity_id} under ${action.parent_activity_id}`;
   if (action.type === 'update_activity') return `updated activity ${action.activity_id}`;
+  if (action.type === 'reparent') return `reparented ${action.activity_id} under ${action.parent_activity_id}`;
+  if (action.type === 'rename') return `renamed ${action.activity_id} to ${action.name}`;
+  if (action.type === 'ask') return `asked about ${action.activity_id}`;
+  if (action.type === 'resume_existing') return `resumed existing ${action.activity_id}`;
+  if (action.type === 'resume_ancestor') return `resumed ancestor ${action.activity_id}`;
+  if (action.type === 'no_op') return `left ${action.activity_id} as it was`;
+  if (action.type === 'keep') return 'kept the recorded structure';
+  if (action.type === 'skipped') return 'recorded the proposal; model review skipped';
   return JSON.stringify(action);
 }
 
@@ -275,10 +329,31 @@ function formatReducerNote(note) {
     const list = note.closedDescendants.map(item => `${item.activityId} (${item.activityName})`).join(', ');
     return `reducer closed open descendants of ${note.activityId}: ${list}\n`;
   }
+  if (note.type === 'agent_named') {
+    return `reducer named this agent "${note.name}"; the CLI will use it from now on\n`;
+  }
+  if (note.type === 'command_result') {
+    const lines = [];
+    if (note.direction) lines.push(`direction\t${note.direction}\n`);
+    if (note.reply) lines.push(`reply\t${note.reply}\n`);
+    if (note.actionsApplied?.length) {
+      lines.push(`actions\t${note.actionsApplied.map(formatAction).join('; ')}\n`);
+    }
+    return lines.join('');
+  }
+  if (note.type === 'start_reduced') {
+    const parts = [];
+    if (note.parentSource === 'inferred') parts.push(`nested ${note.activityId} under ${note.parentId}`);
+    if (note.threadSource === 'parent' && note.requestedThreadId !== undefined && note.requestedThreadId !== note.threadId) {
+      parts.push(`kept it on the parent's thread ${note.threadId}, not ${note.requestedThreadId}`);
+    }
+    if (note.categoriesSource === 'parent') parts.push('inherited the parent\'s categories');
+    return parts.length > 0 ? `reducer ${parts.join('; ')}\n` : '';
+  }
   return `reducer: ${JSON.stringify(note)}\n`;
 }
 
-export async function run(argv, { env = process.env, stdout = process.stdout, stderr = process.stderr, client } = {}) {
+export async function run(argv, { env = process.env, stdout = process.stdout, stderr = process.stderr, client, questionsPath } = {}) {
   const [command, ...args] = argv;
 
   if (!command || command === 'help' || command === '--help' || command === '-h') {
@@ -300,6 +375,9 @@ export async function run(argv, { env = process.env, stdout = process.stdout, st
 
   if (command === 'export') {
     const { file, dbPath } = parseExport(args, env);
+    if (!existsSync(dbPath)) {
+      throw new Error(`Local database does not exist: ${dbPath}`);
+    }
     const { LocalStore } = await loadStore();
     const store = new LocalStore(dbPath);
     try {
@@ -327,11 +405,32 @@ export async function run(argv, { env = process.env, stdout = process.stdout, st
   }
 
   // Reducer notes go to stderr so stdout stays a machine-friendly id.
-  const onReducerNote = note => stderr.write(formatReducerNote(note));
+  const questionFile = questionsPath ?? (client ? undefined : env.FLAMBE_QUESTIONS_PATH);
+  const persistQuestions = Boolean(questionsPath) || !client;
+  const traceId = env.FLAMBE_TRACE_ID;
+  const pendingQuestion = !persistQuestions || command === 'message'
+    ? undefined
+    : readOpenQuestion(traceId, questionFile);
+  if (pendingQuestion) {
+    stderr.write(`reducer still waiting on activity ${pendingQuestion.activityId}: ${pendingQuestion.reply}\n`);
+  }
+  const onReducerNote = note => {
+    const text = formatReducerNote(note);
+    if (text) stderr.write(text);
+    if (persistQuestions && note.type === 'command_result' && note.asked) {
+      rememberQuestion(traceId, { activityId: note.activityId, reply: note.reply }, questionFile);
+    }
+  };
   const flambe = client ?? clientFromEnv(env, { onReducerNote });
   flambe.onReducerNote ??= onReducerNote;
   await flambe.flushQueue?.();
 
+  if (command === 'plan') {
+    const activityId = await flambe.plan(parsePlan(args));
+    stdout.write(`${activityId}\n`);
+    return;
+  }
+
   if (command === 'start') {
     const activityId = await flambe.start(parseStart(args));
     stdout.write(`${activityId}\n`);
@@ -355,14 +454,20 @@ export async function run(argv, { env = process.env, stdout = process.stdout, st
   }
 
   if (command === 'status') {
-    const { activeOnly, suspendedOnly, json } = parseStatus(args);
-    const status = await flambe.status({ activeOnly, suspendedOnly });
+    const { activeOnly, suspendedOnly, includeUnstarted, json } = parseStatus(args);
+    const status = await flambe.status({
+      activeOnly,
+      suspendedOnly,
+      ...(includeUnstarted ? { includeUnstarted } : {}),
+    });
 
     if (json) {
       stdout.write(`${JSON.stringify(status)}\n`);
     } else {
       for (const activity of status.activities) {
-        stdout.write(`${activity.id}\t${activity.path.join(' > ')}\t${activity.threadId}\t${activity.threadName ?? ''}\t${activity.categoryIds.join(',')}\t${activity.latestEvent.phase}\t${activity.latestEvent.timestamp}\n`);
+        const phase = activity.latestEvent?.phase ?? activity.status;
+        const when = activity.latestEvent?.timestamp ?? '';
+        stdout.write(`${activity.id}\t${activity.path.join(' > ')}\t${activity.threadId}\t${activity.threadName ?? ''}\t${activity.categoryIds.join(',')}\t${phase}\t${when}\n`);
       }
     }
 
@@ -399,6 +504,14 @@ export async function run(argv, { env = process.env, stdout = process.stdout, st
     return;
   }
 
+  if (command === 'whoami') {
+    const json = parseJson(args);
+    const me = await flambe.whoami();
+    if (json) stdout.write(`${JSON.stringify(me)}\n`);
+    else stdout.write(`${me.agentId}\t${me.name}\t${me.platform ?? ''}\n`);
+    return;
+  }
+
   if (command === 'observe') {
     const observationId = await flambe.observe(parseObserve(args));
     stdout.write(`${observationId}\n`);
@@ -408,6 +521,7 @@ export async function run(argv, { env = process.env, stdout = process.stdout, st
   if (command === 'message') {
     const { text, activityId, json } = parseMessage(args);
     const decision = await flambe.message({ activityId, text });
+    if (persistQuestions) clearQuestion(traceId, questionFile);
     if (json) {
       stdout.write(`${JSON.stringify(decision)}\n`);
     } else {