@davvidbaker/flambe-cli 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,61 @@
+# @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://flambe.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#coding-agent-cli) 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.1",
   "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

@@ -15,7 +15,7 @@ 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]
@@ -23,6 +23,7 @@ const usage = `Usage:
   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,7 +42,14 @@ 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)
 
@@ -275,6 +283,18 @@ 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 === '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`;
 }
 
@@ -327,7 +347,10 @@ 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 onReducerNote = note => {
+    const text = formatReducerNote(note);
+    if (text) stderr.write(text);
+  };
   const flambe = client ?? clientFromEnv(env, { onReducerNote });
   flambe.onReducerNote ??= onReducerNote;
   await flambe.flushQueue?.();
@@ -399,6 +422,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`);

package/src/client.mjs

@@ -1,4 +1,5 @@
 import { FlambeQueue } from './queue.mjs';
+import { defaultAgentNamesPath, rememberAgentName, rememberedAgentName } from './agentNames.mjs';
 
 export function hostConfigFromEnv(env = process.env) {
   const required = ['FLAMBE_URL', 'FLAMBE_API_TOKEN'];
@@ -27,11 +28,14 @@ export function configFromEnv(env = process.env) {
     throw new Error('FLAMBE_TRACE_ID must be a positive integer');
   }
 
+  const defaultThread = env.FLAMBE_THREAD?.trim() || undefined;
+
   return {
     baseUrl: env.FLAMBE_URL.replace(/\/+$/, ''),
     ...agentIdentityFromEnv(env),
     token: env.FLAMBE_API_TOKEN,
     traceId,
+    ...(defaultThread ? { defaultThread } : {}),
   };
 }
 
@@ -44,14 +48,27 @@ export function agentIdentityFromEnv(env = process.env) {
       ? `cursor:${env.CURSOR_CONVERSATION_ID.trim()}`
       : undefined)
     || claudeAgentId(env);
-  const agentName = env.FLAMBE_AGENT_NAME?.trim() || undefined;
+  const agentNamesPath = env.FLAMBE_AGENT_NAMES_PATH?.trim() || defaultAgentNamesPath();
+  // An explicit name is an override; otherwise reuse whatever the reducer named this agent.
+  const agentName = env.FLAMBE_AGENT_NAME?.trim() || rememberedAgentName(agentId, agentNamesPath);
+  // The product the agent runs on ("Cursor Cloud", "Codex"); many agents share one.
+  const agentPlatform = env.FLAMBE_AGENT_PLATFORM?.trim() || platformFromAgentId(agentId);
 
   return {
-    ...(agentId ? { agentId } : {}),
+    ...(agentId ? { agentId, agentNamesPath } : {}),
     ...(agentName ? { agentName } : {}),
+    ...(agentPlatform ? { agentPlatform } : {}),
   };
 }
 
+function platformFromAgentId(agentId) {
+  if (!agentId) return undefined;
+  if (agentId.startsWith('codex:')) return 'Codex';
+  if (agentId.startsWith('cursor:')) return 'Cursor';
+  if (agentId.startsWith('claude:')) return 'Claude Code';
+  return undefined;
+}
+
 function firstPresent(...values) {
   for (const value of values) {
     const trimmed = value?.trim();
@@ -72,6 +89,8 @@ function claudeAgentId(env) {
   return sessionId ? `claude:${sessionId}` : undefined;
 }
 
+const LIFECYCLE_PHASES = new Set(['B', 'E', 'S', 'R']);
+
 function errorDetail(payload) {
   if (!payload) return null;
   if (typeof payload.error === 'string') return payload.error;
@@ -80,12 +99,15 @@ function errorDetail(payload) {
 }
 
 export class FlambeClient {
-  constructor({ baseUrl, token, traceId, agentId, agentName, fetchImpl = globalThis.fetch, now = Date.now, queuePath, queue, onReducerNote }) {
+  constructor({ baseUrl, token, traceId, threadId, defaultThread, agentId, agentName, agentPlatform, agentNamesPath, fetchImpl = globalThis.fetch, now = Date.now, queuePath, queue, onReducerNote }) {
     this.baseUrl = baseUrl.replace(/\/+$/, '');
     this.token = token;
     this.agentId = agentId;
     this.agentName = agentName;
+    this.agentPlatform = agentPlatform;
+    this.agentNamesPath = agentNamesPath;
     this.traceId = Number(traceId);
+    this.defaultThread = firstPresent(defaultThread, threadId == null ? undefined : String(threadId));
     this.fetch = fetchImpl;
     this.now = now;
     this.onReducerNote = onReducerNote;
@@ -101,6 +123,7 @@ export class FlambeClient {
           authorization: `Bearer ${this.token}`,
           ...(this.agentId ? { 'x-flambe-agent-id': this.agentId } : {}),
           ...(this.agentId && this.agentName ? { 'x-flambe-agent-name': this.agentName } : {}),
+          ...(this.agentId && this.agentPlatform ? { 'x-flambe-agent-platform': this.agentPlatform } : {}),
           ...(body === undefined ? {} : { 'content-type': 'application/json' }),
         },
         ...(body === undefined ? {} : { body: JSON.stringify(body) }),
@@ -129,9 +152,41 @@ export class FlambeClient {
       throw error;
     }
 
+    this.adoptAgentName(response.headers);
     return payload;
   }
 
+  /**
+   * The reducer names agents that arrive without a name and echoes the name on every
+   * response (ADR-012). Keep it for the rest of this process, remember it for future
+   * ones, and tell the worker the first time.
+   */
+  adoptAgentName(headers) {
+    if (!this.agentId || !headers?.get) return;
+    const name = headers.get('x-flambe-agent-name')?.trim();
+    if (!name) return;
+
+    const assigned = headers.get('x-flambe-agent-name-assigned') === 'true';
+    if (name !== this.agentName) {
+      this.agentName = name;
+      if (this.agentNamesPath) rememberAgentName(this.agentId, name, this.agentNamesPath);
+    }
+    if (assigned) this.onReducerNote?.({ type: 'agent_named', agentId: this.agentId, name });
+  }
+
+  async whoami() {
+    if (!this.agentId) {
+      throw new Error('No agent id for this process; set FLAMBE_AGENT_ID (Cursor, Codex, and Claude Code sessions derive one automatically)');
+    }
+    const payload = await this.request('/api/agents/me');
+    return {
+      agentId: payload.data.agent_id,
+      name: payload.data.name,
+      platform: payload.data.platform ?? null,
+      nameAssigned: payload.data.name_assigned === true,
+    };
+  }
+
   async getTrace() {
     const payload = await this.request(`/api/traces/${this.traceId}`);
     return payload.data;
@@ -139,14 +194,16 @@ export class FlambeClient {
 
   async threads() {
     const trace = await this.getTrace();
-    const threads = [...(trace.threads ?? [])]
-      .sort((a, b) => (a.rank - b.rank) || (a.id - b.id));
+    const threads = sortedThreads(trace);
+    const defaultId = this.defaultThread
+      ? matchThread(threads, this.defaultThread, this.traceId).id
+      : threads[0]?.id;
 
-    return threads.map((thread, index) => ({
+    return threads.map(thread => ({
       id: thread.id,
       name: thread.name,
       rank: thread.rank,
-      default: index === 0,
+      default: thread.id === defaultId,
     }));
   }
 
@@ -168,6 +225,8 @@ export class FlambeClient {
 
     for (const event of trace.events ?? []) {
       if (!event.activity) continue;
+      // Reducer annotations (reducer_incoming / reducer_decision) do not change state.
+      if (!LIFECYCLE_PHASES.has(event.phase)) continue;
 
       if (event.phase === 'B') {
         const startedAt = startedAtByActivity.get(event.activity.id);
@@ -218,16 +277,20 @@ export class FlambeClient {
     };
   }
 
-  resolveThreadId(explicitThreadId, trace) {
-    if (explicitThreadId !== undefined && explicitThreadId !== null) {
-      const id = Number(explicitThreadId);
-      if (!Number.isInteger(id) || id <= 0) throw new Error('--thread must be a positive integer');
+  async resolveThreadId(explicitThreadId) {
+    const hasExplicit = explicitThreadId != null && String(explicitThreadId).trim() !== '';
+    const selector = hasExplicit ? explicitThreadId : this.defaultThread;
+    if (selector == null || String(selector).trim() === '') return undefined;
+
+    const raw = String(selector).trim();
+    if (/^\d+$/.test(raw)) {
+      const id = Number(raw);
+      if (id <= 0) throw new Error('--thread must be a positive integer');
       return id;
     }
 
-    const threads = [...(trace.threads ?? [])].sort((a, b) => (a.rank - b.rank) || (a.id - b.id));
-    if (threads.length === 0) throw new Error(`Trace ${this.traceId} has no threads`);
-    return threads[0].id;
+    const trace = await this.getTrace();
+    return matchThread(sortedThreads(trace), raw, this.traceId).id;
   }
 
   resolveCategoryIds(categoryIds = []) {
@@ -268,7 +331,7 @@ export class FlambeClient {
     const input = {
       name: name.trim(),
       description,
-      threadId,
+      threadId: await this.resolveThreadId(threadId),
       parentId: this.resolveParentId(parentId),
       categoryIds: resolvedCategoryIds,
       timestamp,
@@ -282,15 +345,15 @@ export class FlambeClient {
     }
   }
 
+  /**
+   * `start` is a proposal (ADR-012): the reducer picks the parent (this agent's newest
+   * active activity unless `--parent`/`--root` said otherwise), puts a child on its
+   * parent's thread, inherits categories, and places roots asynchronously. So the CLI
+   * sends only what the worker actually said: `parent_id` absent = infer, `null` = root.
+   */
   async postStart({ name, description, threadId, parentId, categoryIds, timestamp }) {
-    const trace = await this.getTrace();
-    const resolvedThreadId = this.resolveThreadId(threadId, trace);
-    const activeActivities = this.statusFromTrace(trace, { activeOnly: true }).activities;
-    const inferredParentId = activeActivities
-      .filter(activity => activity.threadId === resolvedThreadId)
-      .at(-1)?.id;
-    const resolvedParentId = parentId === undefined
-      ? inferredParentId
+    const resolvedParentId = parentId === undefined || parentId === null
+      ? parentId
       : await this.queue.resolveActivityId(parentId);
 
     if (String(resolvedParentId).startsWith('offline-')) {
@@ -303,11 +366,11 @@ export class FlambeClient {
       method: 'POST',
       body: {
         trace_id: this.traceId,
-        thread_id: resolvedThreadId,
+        ...(threadId === undefined ? {} : { thread_id: threadId }),
         activity: {
           name,
           ...(description ? { description } : {}),
-          ...(resolvedParentId ? { parent_id: resolvedParentId } : {}),
+          ...(resolvedParentId === undefined ? {} : { parent_id: resolvedParentId }),
           categories: categoryIds,
         },
         event: {
@@ -317,7 +380,21 @@ export class FlambeClient {
       },
     });
 
-    return payload.data.activity.id;
+    const { activity, reducer } = payload.data;
+    if (reducer) {
+      this.onReducerNote?.({
+        type: 'start_reduced',
+        activityId: activity.id,
+        parentId: activity.parent_id ?? null,
+        threadId: activity.thread_id,
+        requestedThreadId: threadId,
+        parentSource: reducer.parent_source,
+        threadSource: reducer.thread_source,
+        categoriesSource: reducer.categories_source,
+      });
+    }
+
+    return activity.id;
   }
 
   async end({ activityId, message, force = false }) {
@@ -547,3 +624,52 @@ function compareEvents(a, b) {
   const timestampDifference = Date.parse(a.timestamp) - Date.parse(b.timestamp);
   return timestampDifference || (a.id - b.id);
 }
+
+function sortedThreads(trace) {
+  return [...(trace.threads ?? [])].sort((a, b) => (a.rank - b.rank) || (a.id - b.id));
+}
+
+export function threadSlug(name) {
+  return String(name)
+    .normalize('NFD')
+    .replace(/\p{M}/gu, '')
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, '');
+}
+
+function matchThread(threads, selector, traceId) {
+  const raw = String(selector).trim();
+  const available = threads.map(thread => thread.name).join(', ');
+  const notFound = label => new Error(
+    `Thread ${label} not found in trace ${traceId}${available ? ` (threads: ${available})` : ''}`,
+  );
+
+  if (/^\d+$/.test(raw)) {
+    const id = Number(raw);
+    const byId = threads.find(thread => thread.id === id);
+    if (byId) return byId;
+    throw notFound(raw);
+  }
+
+  const exact = threads.filter(thread => thread.name === raw);
+  if (exact.length === 1) return exact[0];
+  if (exact.length > 1) {
+    throw new Error(`Thread name "${raw}" is ambiguous in trace ${traceId}`);
+  }
+
+  const caseInsensitive = threads.filter(thread => thread.name.toLowerCase() === raw.toLowerCase());
+  if (caseInsensitive.length === 1) return caseInsensitive[0];
+  if (caseInsensitive.length > 1) {
+    throw new Error(`Thread name "${raw}" is ambiguous in trace ${traceId}`);
+  }
+
+  const slug = threadSlug(raw);
+  if (!slug) throw notFound(`"${raw}"`);
+  const bySlug = threads.filter(thread => threadSlug(thread.name) === slug);
+  if (bySlug.length === 1) return bySlug[0];
+  if (bySlug.length > 1) {
+    throw new Error(`Thread "${raw}" is ambiguous in trace ${traceId} (matches: ${bySlug.map(thread => thread.name).join(', ')})`);
+  }
+
+  throw notFound(`"${raw}"`);
+}

package/src/local/agents.mjs

@@ -1,24 +1,30 @@
 import { createHash } from 'node:crypto';
 
+// Mirrors FlambeNext.Agents (ADR-012): keep the roster and picking rule in sync.
 const NAMES = [
-  'Steve', 'Belinda', 'Juniper', 'Marcel', 'Priya', 'Otis', 'Nia', 'Theo',
-  'Carmen', 'Felix', 'Imani', 'Rory', 'Greta', 'Miles', 'Suki',
+  'Steve', 'Belinda', 'Juniper', 'Marcel', 'Priya', 'Otis', 'Nia', 'Theo', 'Carmen', 'Felix', 'Imani', 'Rory', 'Greta', 'Miles', 'Suki',
+  'Anouk', 'Bastian', 'Cleo', 'Dashiell', 'Esme', 'Fitz', 'Hollis', 'Ines', 'Jasper', 'Kenji', 'Lucia', 'Mattias', 'Noor', 'Oona',
+  'Pilar', 'Quill', 'Ravi', 'Sable', 'Tamsin', 'Ulla', 'Vera', 'Wren', 'Xiomara', 'Yusuf', 'Zadie',
 ];
 
-export function agentDisplayName(instanceId, providedName, tokenName) {
-  if (usableName(providedName)) return providedName.trim();
-  if (usableName(tokenName)) return tokenName.trim();
-  return nameFor(instanceId);
-}
-
-function usableName(name) {
+export function usableName(name) {
   if (typeof name !== 'string') return false;
   const trimmed = name.trim();
   return trimmed !== '' && Buffer.byteLength(trimmed) <= 100
     && !trimmed.includes('\n') && !trimmed.includes('\r');
 }
 
-function nameFor(instanceId) {
-  const first = createHash('sha256').update(instanceId).digest()[0];
-  return NAMES[first % NAMES.length];
+/** A name for `agentId` that none of `taken` uses; deterministic for the id. */
+export function pickName(agentId, taken = []) {
+  const lower = new Set(taken.map(name => name.toLowerCase()));
+  const offset = createHash('sha256').update(agentId).digest().readUInt16BE(0);
+  for (let index = 0; index < NAMES.length; index += 1) {
+    const candidate = NAMES[(offset + index) % NAMES.length];
+    if (!lower.has(candidate.toLowerCase())) return candidate;
+  }
+  const base = NAMES[offset % NAMES.length];
+  for (let n = 2; ; n += 1) {
+    const candidate = `${base} ${n}`;
+    if (!lower.has(candidate.toLowerCase())) return candidate;
+  }
 }

package/src/local/http.mjs

@@ -10,8 +10,8 @@ function sendJson(res, status, body) {
   res.end(payload);
 }
 
-function sendEmpty(res, status) {
-  res.writeHead(status);
+function sendEmpty(res, status, headers = {}) {
+  res.writeHead(status, headers);
   res.end();
 }
 
@@ -88,12 +88,32 @@ function headerBag() {
   };
 }
 
-async function dispatch(store, req, url, body) {
-  const method = req.method ?? 'GET';
-  const path = url.pathname;
-  const auth = authenticate(store, req);
+// Same contract as FlambeNextWeb.Plugs.AgentIdentity (ADR-012).
+function identifyAgent(store, req, auth) {
+  if (!auth) return null;
   const agentId = req.headers['x-flambe-agent-id'];
   const agentName = req.headers['x-flambe-agent-name'];
+  const agentPlatform = req.headers['x-flambe-agent-platform'];
+  if (typeof agentId !== 'string') return null;
+  return store.identifyAgent(
+    auth.user.id,
+    agentId,
+    typeof agentName === 'string' ? agentName : undefined,
+    typeof agentPlatform === 'string' ? agentPlatform : undefined,
+  );
+}
+
+function agentHeaders(agent) {
+  if (!agent) return {};
+  return {
+    'x-flambe-agent-name': agent.name,
+    ...(agent.assigned ? { 'x-flambe-agent-name-assigned': 'true' } : {}),
+  };
+}
+
+async function dispatch(store, req, url, body, { auth, agent }) {
+  const method = req.method ?? 'GET';
+  const path = url.pathname;
 
   if (method === 'GET' && path === '/api/health') {
     return { status: 200, json: { status: 'ok' } };
@@ -123,6 +143,13 @@ async function dispatch(store, req, url, body) {
 
   const userId = auth?.user?.id;
 
+  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' } };
+    }
+    return { status: 200, json: { data: { agent_id: agent.agent_id, name: agent.name, platform: agent.platform ?? null, name_assigned: agent.assigned } } };
+  }
+
   if (method === 'GET' && path === '/api/export') {
     return { status: 200, json: store.exportBundle() };
   }
@@ -225,9 +252,9 @@ async function dispatch(store, req, url, body) {
       threadId: body.thread_id,
       activity: body.activity ?? {},
       event: body.event ?? {},
-      agentId: typeof agentId === 'string' ? agentId : undefined,
-      agentName: typeof agentName === 'string' ? agentName : undefined,
-      tokenName: auth.tokenName,
+      agent,
+      // Bearer callers are agents proposing a start; the SPA (cookie) writes what it sent.
+      reduce: auth.tokenName !== null,
     });
     if (result.error) return { status: 404, json: { error: 'NOT_FOUND' } };
     return { status: 201, json: { data: result } };
@@ -374,15 +401,18 @@ FLAMBE_TRACE_ID=${traceId}</pre>
     return;
   }
 
-  const result = await dispatch(store, req, url, body);
+  const auth = authenticate(store, req);
+  const agent = identifyAgent(store, req, auth);
+  const result = await dispatch(store, req, url, body, { auth, agent });
+  const identity = agentHeaders(agent);
   if (result.status === 204) {
-    if (result.headers) result.headers.apply(res, 204);
-    else sendEmpty(res, 204);
+    if (result.headers) result.headers.apply(res, 204, identity);
+    else sendEmpty(res, 204, identity);
     return;
   }
 
   const payload = JSON.stringify(result.json);
-  const extra = { 'content-type': 'application/json; charset=utf-8', 'content-length': Buffer.byteLength(payload) };
+  const extra = { 'content-type': 'application/json; charset=utf-8', 'content-length': Buffer.byteLength(payload), ...identity };
   if (result.headers) result.headers.apply(res, result.status, extra);
   else res.writeHead(result.status, extra);
   res.end(payload);