@davvidbaker/flambe-cli 0.1.0 → 0.1.2

package/src/client.mjs

@@ -1,4 +1,13 @@
 import { FlambeQueue } from './queue.mjs';
+import { defaultAgentNamesPath, rememberAgentName, rememberedAgentName } from './agentNames.mjs';
+import { assertRuntimeUrl, runtimeConfig } from './runtime.mjs';
+
+const REQUIRED_AGENT_COMMANDS = ['start', 'end', 'suspend', 'resume', 'status', 'message'];
+const ENDED_PHASES = new Set(['E', 'J', 'V']);
+
+function endedPhase(phase) {
+  return ENDED_PHASES.has(phase);
+}
 
 export function hostConfigFromEnv(env = process.env) {
   const required = ['FLAMBE_URL', 'FLAMBE_API_TOKEN'];
@@ -10,6 +19,7 @@ export function hostConfigFromEnv(env = process.env) {
 
   return {
     baseUrl: env.FLAMBE_URL.replace(/\/+$/, ''),
+    ...runtimeConfig(env),
     token: env.FLAMBE_API_TOKEN,
   };
 }
@@ -27,11 +37,15 @@ 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(/\/+$/, ''),
+    ...runtimeConfig(env),
     ...agentIdentityFromEnv(env),
     token: env.FLAMBE_API_TOKEN,
     traceId,
+    ...(defaultThread ? { defaultThread } : {}),
   };
 }
 
@@ -44,14 +58,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,35 +99,103 @@ function claudeAgentId(env) {
   return sessionId ? `claude:${sessionId}` : undefined;
 }
 
+const LIFECYCLE_PHASES = new Set(['B', 'E', 'S', 'R', 'X', 'J', 'V']);
+
 function errorDetail(payload) {
   if (!payload) return null;
   if (typeof payload.error === 'string') return payload.error;
+  if (payload.error && typeof payload.error === 'object') {
+    const message = payload.error.message ?? payload.error.code;
+    const openChildren = payload.error.open_children;
+    if (!Array.isArray(openChildren) || openChildren.length === 0) return message ?? JSON.stringify(payload.error);
+
+    const children = openChildren
+      .map(child => `${child.activity_id} (${child.activity_name ?? child.name ?? 'unnamed'})`)
+      .join(', ');
+    const ids = openChildren.map(child => child.activity_id).join(', ');
+    return `${message ?? 'Open children remain'}: ${children}. End ${ids} first (or pass --force).`;
+  }
   if (payload.errors) return JSON.stringify(payload.errors);
   return null;
 }
 
 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, runtimeMode, fetchImpl = globalThis.fetch, now = Date.now, queuePath, queue, onReducerNote }) {
+    runtimeConfig({ FLAMBE_RUNTIME_MODE: runtimeMode });
+    assertRuntimeUrl(baseUrl, runtimeMode);
+    this.runtimeMode = runtimeMode;
     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;
-    this.queue = queue ?? new FlambeQueue({ baseUrl: this.baseUrl, traceId: this.traceId, path: queuePath });
+    this.queue = queue ?? new FlambeQueue({
+      baseUrl: this.baseUrl,
+      traceId: this.traceId,
+      agentId: this.agentId,
+      path: queuePath,
+    });
+    this.agentCommandsCapability = null;
+  }
+
+  async supportsAgentCommands() {
+    if (!this.agentCommandsCapability) {
+      const probe = this.request('/api/agent-commands', { responseMetadata: true })
+        .then(({ payload, contentType }) => {
+          if (contentType.toLowerCase().startsWith('text/html')) return false;
+          const commands = payload?.data?.commands;
+          if (payload?.data?.version !== 1
+            || !Array.isArray(commands)
+            || REQUIRED_AGENT_COMMANDS.some(command => !commands.includes(command))) {
+            throw new Error('Flambe API returned an invalid agent-command capability document');
+          }
+          return true;
+        })
+        .catch(error => {
+          if (error?.status === 404 || error?.status === 405) return false;
+          this.agentCommandsCapability = null;
+          throw error;
+        });
+      this.agentCommandsCapability = probe;
+    }
+    return this.agentCommandsCapability;
+  }
+
+  async agentCommand(command, arguments_) {
+    const payload = await this.request('/api/agent-commands', {
+      method: 'POST',
+      body: { command, arguments: arguments_ },
+    });
+    return payload.data;
+  }
+
+  commandIdentity() {
+    return {
+      trace_id: this.traceId,
+      ...(this.agentId ? { agent_id: this.agentId } : {}),
+      ...(this.agentName ? { agent_name: this.agentName } : {}),
+      ...(this.agentPlatform ? { agent_platform: this.agentPlatform } : {}),
+    };
   }
 
-  async request(path, { method = 'GET', body } = {}) {
+  async request(path, { method = 'GET', body, responseMetadata = false } = {}) {
+    assertRuntimeUrl(`${this.baseUrl}${path}`, this.runtimeMode);
     let response;
     try {
       response = await this.fetch(`${this.baseUrl}${path}`, {
         method,
+        ...(this.runtimeMode === 'local_self_contained' ? { redirect: 'manual' } : {}),
         headers: {
           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 +224,48 @@ export class FlambeClient {
       throw error;
     }
 
+    this.adoptAgentName(response.headers);
+    if (responseMetadata) {
+      return {
+        payload,
+        contentType: response.headers.get('content-type') ?? '',
+        status: response.status,
+      };
+    }
     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 +273,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,
     }));
   }
 
@@ -155,8 +291,31 @@ export class FlambeClient {
     return payload.data;
   }
 
-  async status({ activeOnly = false, suspendedOnly = false } = {}) {
+  async plan({ name, description, weight, scheduledStart, scheduledEnd }) {
+    if (!name?.trim()) throw new Error('Activity name is required');
+    const result = await this.agentCommand('plan', {
+      ...this.commandIdentity(),
+      name: name.trim(),
+      ...(description ? { description } : {}),
+      ...(weight == null ? {} : { weight }),
+      ...(scheduledStart == null ? {} : { scheduled_start: scheduledStart }),
+      ...(scheduledEnd == null ? {} : { scheduled_end: scheduledEnd }),
+    });
+    this.reportCommandResult(result);
+    return result.activity_id;
+  }
+
+  async status({ activeOnly = false, suspendedOnly = false, includeUnstarted = false } = {}) {
     if (activeOnly && suspendedOnly) throw new Error('--active and --suspended cannot be used together');
+    if (await this.supportsAgentCommands()) {
+      const result = await this.agentCommand('status', {
+        ...this.commandIdentity(),
+        active_only: activeOnly,
+        suspended_only: suspendedOnly,
+        ...(includeUnstarted ? { include_unstarted: true } : {}),
+      });
+      return result.state;
+    }
     const trace = await this.getTrace();
     return this.statusFromTrace(trace, { activeOnly, suspendedOnly });
   }
@@ -168,6 +327,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);
@@ -191,7 +352,7 @@ export class FlambeClient {
     };
 
     const activities = [...latestByActivity.values()]
-      .filter(event => !activeOnly || event.phase === 'B' || event.phase === 'R')
+      .filter(event => !activeOnly || ['B', 'R', 'X'].includes(event.phase))
       .filter(event => !suspendedOnly || event.phase === 'S')
       .sort(compareEvents)
       .map(event => ({
@@ -218,16 +379,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 +433,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 +447,37 @@ 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
+    if (await this.supportsAgentCommands()) {
+      const resolvedParentId = parentId === undefined || parentId === null
+        ? parentId
+        : await this.queue.resolveActivityId(parentId);
+      if (String(resolvedParentId).startsWith('offline-')) {
+        const error = new Error('Parent activity is queued for offline delivery');
+        error.retryable = true;
+        throw error;
+      }
+      const result = await this.agentCommand('start', {
+        ...this.commandIdentity(),
+        name,
+        ...(description ? { description } : {}),
+        ...(threadId === undefined ? {} : { thread_id: Number(threadId) }),
+        ...(resolvedParentId === undefined ? {} : { parent_id: resolvedParentId }),
+        category_ids: categoryIds,
+        timestamp,
+      });
+      this.reportCommandResult(result);
+      return result.activity_id;
+    }
+
+    const resolvedParentId = parentId === undefined || parentId === null
+      ? parentId
       : await this.queue.resolveActivityId(parentId);
 
     if (String(resolvedParentId).startsWith('offline-')) {
@@ -303,11 +490,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,12 +504,26 @@ 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 }) {
-    if (!force) await this.assertNoOpenChildren(activityId);
-    return this.lifecycleEvent({ activityId, message, phase: 'E', queueType: 'end' });
+    const phase = message ? 'V' : 'E';
+    return this.lifecycleEvent({ activityId, message, phase, queueType: 'end', force, guardChildren: !force });
   }
 
   /**
@@ -362,14 +563,20 @@ export class FlambeClient {
     return this.lifecycleEvent({ activityId, message, phase: 'R', queueType: 'resume' });
   }
 
-  async lifecycleEvent({ activityId, message, phase, queueType }) {
+  async lifecycleEvent({ activityId, message, phase, queueType, force = false, guardChildren = false }) {
     if (!String(activityId).startsWith('offline-')) {
       const id = Number(activityId);
       if (!Number.isInteger(id) || id <= 0) throw new Error('Activity id must be a positive integer');
     }
 
     const timestamp = this.now();
-    const input = { activityId, message, timestamp };
+    const input = {
+      activityId,
+      message,
+      timestamp,
+      phase,
+      ...(queueType === 'end' ? { force } : {}),
+    };
 
     try {
       const id = await this.queue.resolveActivityId(activityId);
@@ -377,8 +584,11 @@ export class FlambeClient {
         await this.queue.enqueue(queueType, input);
         return 'queued';
       }
-      const eventId = await this.postLifecycleEvent({ ...input, activityId: id, phase });
-      if (phase === 'E') await this.queue.removeAlias(activityId);
+      if (guardChildren && !await this.supportsAgentCommands()) {
+        await this.assertNoOpenChildren(id);
+      }
+      const eventId = await this.postLifecycleEvent({ ...input, activityId: id, phase, force });
+      if (endedPhase(phase)) await this.queue.removeAlias(activityId);
       return eventId;
     } catch (error) {
       if (!error?.retryable) throw error;
@@ -387,7 +597,21 @@ export class FlambeClient {
     }
   }
 
-  async postLifecycleEvent({ activityId, message, timestamp, phase }) {
+  async postLifecycleEvent({ activityId, message, timestamp, phase, force = false }) {
+    if (await this.supportsAgentCommands()) {
+      const command = { E: 'end', J: 'end', V: 'end', S: 'suspend', R: 'resume' }[phase];
+      const result = await this.agentCommand(command, {
+        ...this.commandIdentity(),
+        activity_id: Number(activityId),
+        ...(message ? { message } : {}),
+        timestamp,
+        ...(command === 'end' ? { force, ...(phase ? { phase } : {}) } : {}),
+      });
+      this.reportClosedDescendants(Number(activityId), result.closed_descendants ?? []);
+      this.reportCommandResult(result);
+      return result.event_id;
+    }
+
     const payload = await this.request('/api/events', {
       method: 'POST',
       body: {
@@ -402,10 +626,32 @@ export class FlambeClient {
     });
 
     const closed = payload.data.reducer?.closed_descendants ?? [];
+    this.reportClosedDescendants(Number(activityId), closed);
+
+    return payload.data.id;
+  }
+
+  reportCommandResult(result) {
+    if (!result) return;
+    const actions = result.actions_applied ?? [];
+    const direction = result.direction ?? null;
+    const reply = result.reply ?? null;
+    if (!direction && !reply && actions.length === 0) return;
+    this.onReducerNote?.({
+      type: 'command_result',
+      activityId: result.activity_id,
+      direction,
+      reply,
+      actionsApplied: actions,
+      asked: actions.some(action => action.type === 'ask'),
+    });
+  }
+
+  reportClosedDescendants(activityId, closed) {
     if (closed.length > 0) {
       this.onReducerNote?.({
         type: 'closed_descendants',
-        activityId: Number(activityId),
+        activityId,
         closedDescendants: closed.map(item => ({
           activityId: item.activity_id,
           activityName: item.activity_name,
@@ -413,14 +659,15 @@ export class FlambeClient {
         })),
       });
     }
-
-    return payload.data.id;
   }
 
   async flushQueue() {
     return this.queue.flush({
       start: input => this.postStart(input),
-      end: input => this.postLifecycleEvent({ ...input, phase: 'E' }),
+      end: input => this.postLifecycleEvent({
+        ...input,
+        phase: input.phase ?? (input.message ? 'V' : 'E'),
+      }),
       suspend: input => this.postLifecycleEvent({ ...input, phase: 'S' }),
       resume: input => this.postLifecycleEvent({ ...input, phase: 'R' }),
       observe: input => this.postObservation(input),
@@ -461,6 +708,28 @@ export class FlambeClient {
   async message({ activityId, text }) {
     if (!text?.trim()) throw new Error('Message text is required');
 
+    if (await this.supportsAgentCommands()) {
+      let resolvedActivityId = activityId;
+      if (activityId !== undefined) {
+        resolvedActivityId = await this.queue.resolveActivityId(activityId);
+        if (String(resolvedActivityId).startsWith('offline-')) {
+          throw new Error('Activity is still queued for offline delivery; retry once Flambe is reachable');
+        }
+        const id = Number(resolvedActivityId);
+        if (!Number.isInteger(id) || id <= 0) throw new Error('--activity must be a positive integer');
+        resolvedActivityId = id;
+      }
+
+      const result = await this.agentCommand('message', {
+        ...this.commandIdentity(),
+        ...(resolvedActivityId === undefined ? {} : { activity_id: resolvedActivityId }),
+        message: text.trim(),
+      });
+      const decision = { activityId: result.activity_id ?? resolvedActivityId, ...result };
+      this.reportCommandResult(result);
+      return decision;
+    }
+
     const resolvedActivityId = activityId === undefined
       ? await this.currentActivityId()
       : await this.queue.resolveActivityId(activityId);
@@ -547,3 +816,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;
+  }
 }