@davvidbaker/flambe-cli 0.1.1 → 0.1.3

package/README.md

@@ -52,10 +52,12 @@ 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_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#coding-agent-cli) for commands (`start`, `end`, `message`, `observe`, local `serve`).
+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,6 +1,6 @@
 {
   "name": "@davvidbaker/flambe-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "CLI for streaming coding-agent activity into Flambe",
   "type": "module",
   "bin": {

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
@@ -19,7 +20,8 @@ const usage = `Usage:
   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
@@ -52,6 +54,7 @@ Optional:
                      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).`;
 
@@ -125,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) {
@@ -275,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);
 }
 
@@ -286,6 +332,15 @@ function formatReducerNote(note) {
   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}`);
@@ -298,7 +353,7 @@ function formatReducerNote(note) {
   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') {
@@ -320,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 {
@@ -347,14 +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 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`);
@@ -378,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`);
       }
     }
 
@@ -439,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 {

package/src/client.mjs

@@ -1,5 +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'];
@@ -11,6 +19,7 @@ export function hostConfigFromEnv(env = process.env) {
 
   return {
     baseUrl: env.FLAMBE_URL.replace(/\/+$/, ''),
+    ...runtimeConfig(env),
     token: env.FLAMBE_API_TOKEN,
   };
 }
@@ -32,6 +41,7 @@ export function configFromEnv(env = process.env) {
 
   return {
     baseUrl: env.FLAMBE_URL.replace(/\/+$/, ''),
+    ...runtimeConfig(env),
     ...agentIdentityFromEnv(env),
     token: env.FLAMBE_API_TOKEN,
     traceId,
@@ -89,17 +99,31 @@ function claudeAgentId(env) {
   return sessionId ? `claude:${sessionId}` : undefined;
 }
 
-const LIFECYCLE_PHASES = new Set(['B', 'E', 'S', 'R']);
+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, threadId, defaultThread, agentId, agentName, agentPlatform, agentNamesPath, 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;
@@ -111,14 +135,62 @@ export class FlambeClient {
     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;
   }
 
-  async request(path, { method = 'GET', body } = {}) {
+  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, 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 } : {}),
@@ -153,6 +225,13 @@ export class FlambeClient {
     }
 
     this.adoptAgentName(response.headers);
+    if (responseMetadata) {
+      return {
+        payload,
+        contentType: response.headers.get('content-type') ?? '',
+        status: response.status,
+      };
+    }
     return payload;
   }
 
@@ -212,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 });
   }
@@ -250,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 => ({
@@ -352,6 +454,28 @@ export class FlambeClient {
    * sends only what the worker actually said: `parent_id` absent = infer, `null` = root.
    */
   async postStart({ name, description, threadId, parentId, categoryIds, timestamp }) {
+    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);
@@ -398,8 +522,8 @@ export class FlambeClient {
   }
 
   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 });
   }
 
   /**
@@ -439,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);
@@ -454,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;
@@ -464,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: {
@@ -479,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,
@@ -490,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),
@@ -538,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);