@inceptionstack/roundhouse 0.5.22 → 0.5.25

package/src/agents/shared/session-repair.ts

@@ -0,0 +1,328 @@
+/**
+ * session-repair.ts — File-level session repair for corrupted pi-ai session files.
+ *
+ * Pi-ai persists sessions as JSONL at ~/.roundhouse/sessions/<thread>/<id>.jsonl.
+ * Each line is a `FileEntry` in a tree (parentId links). Message entries wrap
+ * pi-ai `Message` objects (role: user | assistant | toolResult).
+ *
+ * Corruption scenarios (mid-session):
+ *   - Tool execution aborted → toolCall entry written, toolResult never lands
+ *   - Process crash between tool completion and result persist
+ *   - Manual Ctrl-C mid-tool
+ *
+ * On next resume, pi-ai loads these entries → sends history to the model →
+ * model rejects with "toolUse without toolResult" (Bedrock/Anthropic 400).
+ *
+ * This module detects and repairs orphaned tool pairs at the file level,
+ * preserving the parentId tree by re-parenting children of dropped entries.
+ *
+ * Delegates tool-pairing logic to message-validator.ts.
+ */
+
+import { readFileSync, writeFileSync, renameSync, existsSync, copyFileSync } from 'node:fs';
+import { dirname, basename, join } from 'node:path';
+import { validateToolPairing } from './message-validator.js';
+import type { Message, ToolCall, AssistantMessage, ToolResultMessage } from '@earendil-works/pi-ai';
+
+/** Minimal structural type for a pi-ai session file entry (we only touch message entries). */
+interface SessionFileEntry {
+  type: string;
+  id?: string;
+  parentId?: string | null;
+  message?: Message;
+  // other fields preserved as-is
+  [key: string]: unknown;
+}
+
+export interface SessionRepairReport {
+  repaired: boolean;
+  droppedEntryIds: string[];
+  droppedToolCallIds: string[];
+  droppedToolResultIds: string[];
+  backupPath?: string;
+  totalEntries: number;
+}
+
+/** Parse a .jsonl session file. Tolerant of trailing blank lines. Throws on malformed JSON. */
+export function parseSessionFile(path: string): SessionFileEntry[] {
+  const raw = readFileSync(path, 'utf8');
+  const lines = raw.split('\n');
+  const entries: SessionFileEntry[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim()) continue;
+    try {
+      entries.push(JSON.parse(line) as SessionFileEntry);
+    } catch (err) {
+      throw new Error(`Session file parse error at line ${i + 1}: ${(err as Error).message}`);
+    }
+  }
+  return entries;
+}
+
+/**
+ * Extract `Message[]` from file entries in the order they appear.
+ * Only includes entries of type "message" (skips session header, model_change, etc).
+ */
+function extractMessages(entries: SessionFileEntry[]): { messages: Message[]; entryIndex: number[] } {
+  const messages: Message[] = [];
+  const entryIndex: number[] = []; // parallel array: messages[i] came from entries[entryIndex[i]]
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    if (e.type === 'message' && e.message) {
+      messages.push(e.message);
+      entryIndex.push(i);
+    }
+  }
+  return { messages, entryIndex };
+}
+
+/**
+ * Re-parent children of dropped entries to preserve tree validity.
+ * If entry X is dropped and entry Y has parentId=X, set Y.parentId = X.parentId.
+ */
+function reparentDroppedEntries(
+  entries: SessionFileEntry[],
+  droppedEntryIds: Set<string>
+): SessionFileEntry[] {
+  // Build a map: droppedId → nearest non-dropped ancestor (walk up the tree)
+  const entryById = new Map<string, SessionFileEntry>();
+  for (const e of entries) {
+    if (e.id) entryById.set(e.id, e);
+  }
+
+  const remap = new Map<string, string | null>();
+  const resolveAncestor = (id: string, visited: Set<string> = new Set()): string | null => {
+    if (remap.has(id)) return remap.get(id)!;
+    if (!droppedEntryIds.has(id)) return id;
+    if (visited.has(id)) {
+      // Cycle in parentId chain (self-parent or loop) — bail with null rather than
+      // blow the stack. Should never happen in a well-formed session file.
+      remap.set(id, null);
+      return null;
+    }
+    visited.add(id);
+    const e = entryById.get(id);
+    const parent = e?.parentId ?? null;
+    const resolved = parent === null ? null : resolveAncestor(parent, visited);
+    remap.set(id, resolved);
+    return resolved;
+  };
+
+  const kept: SessionFileEntry[] = [];
+  for (const e of entries) {
+    if (e.id && droppedEntryIds.has(e.id)) continue;
+    if (e.parentId && droppedEntryIds.has(e.parentId)) {
+      kept.push({ ...e, parentId: resolveAncestor(e.parentId) });
+    } else {
+      kept.push(e);
+    }
+  }
+  return kept;
+}
+
+/**
+ * Compute the set of entry IDs to drop based on orphaned tool IDs.
+ *
+ * - Orphaned toolResult message → drop the whole entry
+ * - Orphaned toolCall inside an assistant message → drop the entry only if the
+ *   toolCall was the *only* content block (otherwise keep the entry with the
+ *   block stripped; handled separately in applyEntryEdits)
+ */
+function findEntriesToDrop(
+  entries: SessionFileEntry[],
+  orphanedToolCallIds: Set<string>,
+  orphanedToolResultIds: Set<string>
+): { entriesToDrop: Set<string>; entriesToEdit: Map<string, string[]> } {
+  const entriesToDrop = new Set<string>();
+  const entriesToEdit = new Map<string, string[]>(); // entryId → toolCallIds to strip
+
+  for (const e of entries) {
+    if (e.type !== 'message' || !e.message || !e.id) continue;
+    const msg = e.message;
+
+    if (msg.role === 'toolResult') {
+      const tr = msg as ToolResultMessage;
+      if (orphanedToolResultIds.has(tr.toolCallId)) {
+        entriesToDrop.add(e.id);
+      }
+      continue;
+    }
+
+    if (msg.role === 'assistant') {
+      const am = msg as AssistantMessage;
+      const orphanCallIds: string[] = [];
+      let hasNonOrphanContent = false;
+      for (const block of am.content) {
+        if ((block as ToolCall).type === 'toolCall') {
+          const callId = (block as ToolCall).id;
+          if (orphanedToolCallIds.has(callId)) {
+            orphanCallIds.push(callId);
+          } else {
+            hasNonOrphanContent = true;
+          }
+        } else {
+          hasNonOrphanContent = true;
+        }
+      }
+      if (orphanCallIds.length === 0) continue;
+      if (hasNonOrphanContent) {
+        entriesToEdit.set(e.id, orphanCallIds);
+      } else {
+        entriesToDrop.add(e.id);
+      }
+    }
+  }
+
+  return { entriesToDrop, entriesToEdit };
+}
+
+/** Apply in-place edits to assistant entries: strip orphaned toolCall blocks. */
+function applyEntryEdits(
+  entries: SessionFileEntry[],
+  entriesToEdit: Map<string, string[]>
+): SessionFileEntry[] {
+  if (entriesToEdit.size === 0) return entries;
+  return entries.map(e => {
+    if (!e.id || !entriesToEdit.has(e.id)) return e;
+    const orphanIds = new Set(entriesToEdit.get(e.id)!);
+    const msg = e.message as AssistantMessage;
+    const cleanedContent = msg.content.filter(block => {
+      if ((block as ToolCall).type === 'toolCall') {
+        return !orphanIds.has((block as ToolCall).id);
+      }
+      return true;
+    });
+    return { ...e, message: { ...msg, content: cleanedContent } };
+  });
+}
+
+/** Atomic write: tmp file + rename. Preserves partial-failure safety. */
+function atomicWrite(path: string, content: string): void {
+  const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, content, { encoding: 'utf8' });
+  renameSync(tmp, path);
+}
+
+/** Back up the original file before mutation. Returns the backup path. */
+function backupFile(path: string): string {
+  const ts = Date.now();
+  const backupPath = join(dirname(path), `${basename(path)}.bak-${ts}`);
+  copyFileSync(path, backupPath);
+  return backupPath;
+}
+
+/**
+ * Validate a session file for orphaned tool pairs without modifying it.
+ * Useful for pre-flight checks and tests.
+ */
+export function inspectSessionFile(path: string): {
+  hasOrphans: boolean;
+  orphanedToolCallIds: string[];
+  orphanedToolResultIds: string[];
+  totalEntries: number;
+  totalMessages: number;
+} {
+  const entries = parseSessionFile(path);
+  const { messages } = extractMessages(entries);
+  const validation = validateToolPairing(messages);
+  return {
+    hasOrphans: !validation.isValid,
+    orphanedToolCallIds: validation.orphanedToolCallIds,
+    orphanedToolResultIds: validation.orphanedToolResultIds,
+    totalEntries: entries.length,
+    totalMessages: messages.length,
+  };
+}
+
+/**
+ * Repair a corrupted session file in place. Creates a .bak-<ts> backup first.
+ *
+ * Safety:
+ * - Backup always written before mutation
+ * - Atomic tmp+rename for the repaired file
+ * - No-op if no orphans detected (returns repaired: false)
+ * - Preserves session tree by re-parenting children of dropped entries
+ *
+ * @returns report describing what was repaired
+ */
+export function repairSessionFile(path: string): SessionRepairReport {
+  if (!existsSync(path)) {
+    throw new Error(`Session file not found: ${path}`);
+  }
+
+  const entries = parseSessionFile(path);
+  const { messages } = extractMessages(entries);
+  const validation = validateToolPairing(messages);
+
+  if (validation.isValid) {
+    return {
+      repaired: false,
+      droppedEntryIds: [],
+      droppedToolCallIds: [],
+      droppedToolResultIds: [],
+      totalEntries: entries.length,
+    };
+  }
+
+  const orphanedCalls = new Set(validation.orphanedToolCallIds);
+  const orphanedResults = new Set(validation.orphanedToolResultIds);
+
+  const { entriesToDrop, entriesToEdit } = findEntriesToDrop(entries, orphanedCalls, orphanedResults);
+  const edited = applyEntryEdits(entries, entriesToEdit);
+  const kept = reparentDroppedEntries(edited, entriesToDrop);
+
+  const backupPath = backupFile(path);
+  const newContent = kept.map(e => JSON.stringify(e)).join('\n') + '\n';
+  atomicWrite(path, newContent);
+
+  return {
+    repaired: true,
+    droppedEntryIds: Array.from(entriesToDrop),
+    droppedToolCallIds: validation.orphanedToolCallIds,
+    droppedToolResultIds: validation.orphanedToolResultIds,
+    backupPath,
+    totalEntries: entries.length,
+  };
+}
+
+/**
+ * Detect whether an error from pi-ai / the model provider indicates a
+ * tool-pairing mismatch that can be recovered by session repair.
+ *
+ * Matches Bedrock Converse and Anthropic error shapes. Intentionally narrow —
+ * we don't want to repair on unrelated 400s.
+ */
+export function isToolPairingError(err: unknown): boolean {
+  if (!err) return false;
+  const msg = (err as { message?: string }).message ?? String(err);
+  const name = (err as { name?: string }).name ?? '';
+
+  // Bedrock Converse: "messages.N: `tool_use` ids were found without `tool_result` blocks..."
+  // Anthropic direct: similar phrasing
+  const patterns = [
+    /tool_use.*without.*tool_result/i,
+    /tool_result.*without.*tool_use/i,
+    /toolUse.*without.*toolResult/i,
+    /unmatched.*tool.?use/i,
+    /orphan.*tool/i,
+  ];
+
+  if (patterns.some(p => p.test(msg))) return true;
+
+  // Bedrock ValidationException may carry the pairing text in nested fields
+  // (e.g. err.cause.message, $metadata). Only stringify-search when the error
+  // *looks* like a Bedrock validation error — avoid noisy matches on unrelated
+  // messages that happen to contain '400'.
+  const httpStatus =
+    (err as { $metadata?: { httpStatusCode?: number } }).$metadata?.httpStatusCode;
+  if (name === 'ValidationException' || httpStatus === 400) {
+    try {
+      const full = JSON.stringify(err);
+      if (patterns.some(p => p.test(full))) return true;
+    } catch {
+      /* circular structure — give up */
+    }
+  }
+  return false;
+}

package/src/cli/cron-commands.ts

@@ -12,8 +12,21 @@ import { validateSchedule } from "../cron/schedule";
 import { validateTemplate } from "../cron/template";
 import { parseDuration } from "../cron/durations";
 import type { CronJobConfig, CronSchedule } from "../cron/types";
-import { DEFAULT_TIMEOUT_MS, DEFAULT_TIMEZONE, VALID_NOTIFY_ON, DEFAULT_RUNS_LIMIT } from "../cron/constants";
+import { DEFAULT_TIMEZONE, VALID_NOTIFY_ON, DEFAULT_RUNS_LIMIT } from "../cron/constants";
 import { formatSchedule, formatRunCounts, formatJobSummary, formatJobDetail, formatRunLine, runStatusIcon, jobEnabledIcon } from "../cron/format";
+import { sendIpc } from "../ipc/client";
+
+/**
+ * Send a notification about a cron management action via IPC to the gateway.
+ * Non-fatal — if gateway is not running, silently skip.
+ */
+async function notifyCronAction(message: string): Promise<void> {
+  try {
+    await sendIpc({ type: "notify", text: message });
+  } catch {
+    // Gateway not running — CLI is standalone, skip notification
+  }
+}
 
 function rejectBuiltin(id: string): void {
   if (isBuiltinJob(id)) {
@@ -22,6 +35,22 @@ function rejectBuiltin(id: string): void {
   }
 }
 
+/** Validate ID, reject builtins, load job or exit with error. */
+async function requireJob(store: CronStore, positional: string[], usage: string): Promise<{ id: string; job: CronJobConfig }> {
+  const { id, job } = await loadJob(store, positional, usage);
+  rejectBuiltin(id);
+  return { id, job };
+}
+
+/** Validate ID and load job or exit with error (no builtin check — for read-only commands). */
+async function loadJob(store: CronStore, positional: string[], usage: string): Promise<{ id: string; job: CronJobConfig }> {
+  const id = positional[1];
+  if (!id) { console.error(`Usage: ${usage}`); process.exit(1); }
+  const job = await store.getJob(id);
+  if (!job) { console.error(`Job not found: ${id}`); process.exit(1); }
+  return { id, job };
+}
+
 function validateNotifyOn(value?: string): "always" | "success" | "failure" {
   const v = value ?? "always";
   if (!(VALID_NOTIFY_ON as readonly string[]).includes(v)) {
@@ -100,8 +129,12 @@ export async function cronAdd(store: CronStore, positional: string[], flags: Rec
   };
 
   await store.writeJob(job);
-  console.log(`✅ Cron job "${id}" ${existing ? "updated" : "created"}.`);
+  const verb = existing ? "updated" : "created";
+  console.log(`✅ Cron job "${id}" ${verb}.`);
   if (flags.json) console.log(JSON.stringify(job, null, 2));
+
+  const schedDesc = flags.cron ? `cron: ${flags.cron}` : flags.every ? `every ${flags.every}` : flags.at ? `once at ${flags.at}` : "";
+  await notifyCronAction(`📋 Cron job **${verb}**: \`${id}\`\n${schedDesc}${flags.description ? " — " + flags.description : ""}`);
 }
 
 export async function cronList(store: CronStore, _positional: string[], flags: Record<string, string>): Promise<void> {
@@ -135,10 +168,7 @@ export async function cronList(store: CronStore, _positional: string[], flags: R
 }
 
 export async function cronShow(store: CronStore, positional: string[], flags: Record<string, string>): Promise<void> {
-  const id = positional[1];
-  if (!id) { console.error("Usage: roundhouse cron show <id>"); process.exit(1); }
-  const job = await store.getJob(id);
-  if (!job) { console.error(`Job not found: ${id}`); process.exit(1); }
+  const { id, job } = await loadJob(store, positional, "roundhouse cron show <id>");
   const state = await store.getState(id);
   const runs = await store.listRuns(id, 5);
   if (flags.json) {
@@ -149,11 +179,7 @@ export async function cronShow(store: CronStore, positional: string[], flags: Re
 }
 
 export async function cronTrigger(store: CronStore, positional: string[], _flags: Record<string, string>): Promise<void> {
-  const id = positional[1];
-  if (!id) { console.error("Usage: roundhouse cron trigger <id>"); process.exit(1); }
-  rejectBuiltin(id);
-  const job = await store.getJob(id);
-  if (!job) { console.error(`Job not found: ${id}`); process.exit(1); }
+  const { id, job } = await requireJob(store, positional, "roundhouse cron trigger <id>");
   console.log(`Triggering ${id}...`);
   const runner = new CronRunner(store);
   const record = await runner.runJob(job, new Date(), "manual");
@@ -164,8 +190,7 @@ export async function cronTrigger(store: CronStore, positional: string[], _flags
 }
 
 export async function cronRuns(store: CronStore, positional: string[], flags: Record<string, string>): Promise<void> {
-  const id = positional[1];
-  if (!id) { console.error("Usage: roundhouse cron runs <id>"); process.exit(1); }
+  const { id } = await loadJob(store, positional, "roundhouse cron runs <id>");
   const runs = await store.listRuns(id, parseInt(flags.limit ?? String(DEFAULT_RUNS_LIMIT), 10));
   if (runs.length === 0) {
     console.log(`No runs for ${id}.`);
@@ -179,35 +204,27 @@ export async function cronRuns(store: CronStore, positional: string[], flags: Re
 }
 
 export async function cronPause(store: CronStore, positional: string[], _flags: Record<string, string>): Promise<void> {
-  const id = positional[1];
-  if (!id) { console.error("Usage: roundhouse cron pause <id>"); process.exit(1); }
-  rejectBuiltin(id);
-  const job = await store.getJob(id);
-  if (!job) { console.error(`Job not found: ${id}`); process.exit(1); }
-  job.enabled = false;
-  job.updatedAt = new Date().toISOString();
-  await store.writeJob(job);
-  console.log(`⏸️ Job "${id}" paused.`);
+  await cronToggleEnabled(store, positional, false);
 }
 
 export async function cronResume(store: CronStore, positional: string[], _flags: Record<string, string>): Promise<void> {
-  const id = positional[1];
-  if (!id) { console.error("Usage: roundhouse cron resume <id>"); process.exit(1); }
-  rejectBuiltin(id);
-  const job = await store.getJob(id);
-  if (!job) { console.error(`Job not found: ${id}`); process.exit(1); }
-  job.enabled = true;
+  await cronToggleEnabled(store, positional, true);
+}
+
+async function cronToggleEnabled(store: CronStore, positional: string[], enabled: boolean): Promise<void> {
+  const cmd = enabled ? "resume" : "pause";
+  const { id, job } = await requireJob(store, positional, `roundhouse cron ${cmd} <id>`);
+  job.enabled = enabled;
   job.updatedAt = new Date().toISOString();
   await store.writeJob(job);
-  console.log(`▶️ Job "${id}" resumed.`);
+  const emoji = enabled ? "▶️" : "⏸️";
+  const verb = enabled ? "resumed" : "paused";
+  console.log(`${emoji} Job "${id}" ${verb}.`);
+  await notifyCronAction(`${emoji} Cron job **${verb}**: \`${id}\``);
 }
 
 export async function cronEdit(store: CronStore, positional: string[], flags: Record<string, string>): Promise<void> {
-  const id = positional[1];
-  if (!id) { console.error("Usage: roundhouse cron edit <id> [--prompt '...'] [--cron '...'] ..."); process.exit(1); }
-  rejectBuiltin(id);
-  const job = await store.getJob(id);
-  if (!job) { console.error(`Job not found: ${id}`); process.exit(1); }
+  const { id, job } = await requireJob(store, positional, "roundhouse cron edit <id> [--prompt '...'] [--cron '...'] ...");
 
   if (flags.prompt) job.prompt = flags.prompt;
   if (flags.description) job.description = flags.description;
@@ -232,16 +249,14 @@ export async function cronEdit(store: CronStore, positional: string[], flags: Re
   job.updatedAt = new Date().toISOString();
   await store.writeJob(job);
   console.log(`✅ Job "${id}" updated.`);
+  await notifyCronAction(`✏️ Cron job **edited**: \`${id}\``);
 }
 
 export async function cronDelete(store: CronStore, positional: string[], _flags: Record<string, string>): Promise<void> {
-  const id = positional[1];
-  if (!id) { console.error("Usage: roundhouse cron delete <id>"); process.exit(1); }
-  rejectBuiltin(id);
-  const job = await store.getJob(id);
-  if (!job) { console.error(`Job not found: ${id}`); process.exit(1); }
+  const { id } = await requireJob(store, positional, "roundhouse cron delete <id>");
   await store.deleteJob(id);
   console.log(`🗑️ Job "${id}" deleted.`);
+  await notifyCronAction(`🗑️ Cron job **deleted**: \`${id}\``);
 }
 
 export function cronHelp(): void {

package/src/gateway/command-registry.ts

@@ -0,0 +1,158 @@
+/**
+ * gateway/command-registry.ts — Descriptor-based command registration
+ *
+ * Problem: previously, adding a new Telegram command required editing
+ * `gateway.ts` in 2–3 places (import, text-dispatch branch, onAction
+ * subscription). That's an OCP violation — gateway wasn't closed for
+ * modification. At 2 commands it was fine. At 5–8 it becomes noise.
+ *
+ * Solution: each command module exports a `CommandDescriptor` bundling
+ * its trigger tokens, an `invoke()` closure, optional inline-keyboard
+ * action handlers, and a `stage` hint. The gateway iterates a single
+ * `COMMANDS` array to wire everything. Adding a new command = one new
+ * descriptor + one line in the array.
+ *
+ * Pattern: Command (GoF) + Observer registration. Not a Mediator — the
+ * gateway is still the composition root, it just stops special-casing.
+ *
+ * Stages:
+ *   - "pre-turn"  fires before the allowlist/pairing gate inside
+ *                 handleOrAbort(). Used for abort-style commands like
+ *                 /stop that must interrupt an in-flight agent run.
+ *                 Handlers own their own allowlist check if needed.
+ *   - "in-turn"   fires inside the main message handler, after pairing,
+ *                 allowlist, and the "is this even text" guards. The
+ *                 default — most commands belong here.
+ *
+ * Action handlers (inline-keyboard callbacks) are registered unconditionally
+ * at startup via chat.onAction(). The gateway doesn't care which descriptor
+ * owns which action id.
+ */
+
+import type { ChatThreadLike } from "./inline-keyboard";
+
+/** Dispatch stages — see module doc. */
+export type CommandStage = "pre-turn" | "in-turn";
+
+/**
+ * What the gateway passes to a descriptor's `invoke()`. Thin by design —
+ * the command closure captures everything else from its own module or
+ * from the gateway's `buildCommandContext()`.
+ */
+export interface CommandInvocation {
+  /** The chat thread (subscribed). */
+  thread: any;
+  /** The raw incoming message object from the Chat SDK. */
+  message: any;
+  /** The already-trimmed text of the message. */
+  text: string;
+  /** The resolved agent thread id (post topic-override). */
+  agentThreadId: string;
+}
+
+/**
+ * Inline-keyboard callback event shape. Matches what
+ * `chat.onAction(actionId, handler)` already provides today.
+ */
+export interface ActionInvocation {
+  value?: string;
+  thread: ChatThreadLike;
+}
+
+/**
+ * A single command's self-describing registration metadata.
+ *
+ * Design notes:
+ * - `triggers` is a list so we can declare aliases like `/crons` + `/jobs`
+ *   without duplicating descriptors.
+ * - `acceptsArgs` controls whether we match `/cmd foo` as well as bare
+ *   `/cmd` (maps to the existing `isCommandWithArgs` helper).
+ * - `invoke` is the closure that does the actual work. It returns `void`
+ *   but may be `async`. The gateway awaits it and then short-circuits
+ *   further dispatch — so descriptors are "run first match wins".
+ * - `actions` wires `chat.onAction(id, …)` at startup. Keys are the
+ *   ACTION_ID constants, values are handler closures. Co-locates button
+ *   protocol with the command that owns it (SRP).
+ */
+export interface CommandDescriptor {
+  /** Command strings including the leading slash, e.g. `"/topic"`. */
+  triggers: readonly string[];
+  /** Default `"in-turn"`. */
+  stage?: CommandStage;
+  /** If true, `/cmd arg1 arg2` also matches. Default false. */
+  acceptsArgs?: boolean;
+  /** Do the work. Return (or resolve) when done — gateway will skip further dispatch. */
+  invoke: (inv: CommandInvocation) => Promise<void> | void;
+  /** Optional inline-keyboard callback handlers keyed by action id. */
+  actions?: Record<string, (inv: ActionInvocation) => Promise<void> | void>;
+}
+
+/**
+ * Helper: has this descriptor opted into pre-turn dispatch?
+ * Extracted as a tiny predicate so gateway.ts reads naturally:
+ *   `if (isPreTurn(cmd)) { … }`
+ */
+export function isPreTurn(cmd: CommandDescriptor): boolean {
+  return cmd.stage === "pre-turn";
+}
+
+/**
+ * Does `text` invoke any of this descriptor's triggers?
+ *
+ * Matching is delegated to the caller via `matchers` so this module doesn't
+ * depend on the specific `isCommand` / `isCommandWithArgs` implementations
+ * (keeps it pure & unit-testable). `acceptsArgs` controls whether the
+ * args-matcher is also consulted.
+ */
+export interface CommandMatchers {
+  /** Exact-match: `/cmd` or `/cmd@botname`, no trailing args. */
+  isCommand: (text: string, cmd: string) => boolean;
+  /** Args-match: `/cmd arg1` or `/cmd@botname arg1 arg2`. */
+  isCommandWithArgs: (text: string, cmd: string) => boolean;
+}
+
+export function matchesDescriptor(
+  desc: CommandDescriptor,
+  text: string,
+  matchers: CommandMatchers,
+): boolean {
+  for (const trigger of desc.triggers) {
+    if (matchers.isCommand(text, trigger)) return true;
+    if (desc.acceptsArgs && matchers.isCommandWithArgs(text, trigger)) return true;
+  }
+  return false;
+}
+
+/**
+ * Validate that no two descriptors claim the same action id.
+ *
+ * Why: duplicate registrations at `chat.onAction(actionId, …)` produce
+ * silent misbehavior — last-wins on some adapters, double-fire on others.
+ * Failing fast at startup makes the coupling surface explicit.
+ *
+ * Throws on the first collision with both owners' trigger lists for easy
+ * diagnosis. Returns the set of (actionId, handler) pairs in registration
+ * order so the caller can iterate without re-walking descriptors.
+ */
+export function collectAndValidateActions(
+  descriptors: readonly CommandDescriptor[],
+): Array<{ actionId: string; handler: NonNullable<CommandDescriptor["actions"]>[string]; ownerTriggers: readonly string[] }> {
+  const result: Array<{ actionId: string; handler: any; ownerTriggers: readonly string[] }> = [];
+  const ownerByAction = new Map<string, readonly string[]>();
+
+  for (const desc of descriptors) {
+    if (!desc.actions) continue;
+    for (const [actionId, handler] of Object.entries(desc.actions)) {
+      const prior = ownerByAction.get(actionId);
+      if (prior) {
+        throw new Error(
+          `[command-registry] duplicate action id '${actionId}': claimed by ` +
+          `[${prior.join(",")}] and [${desc.triggers.join(",")}]. Action IDs must be unique.`,
+        );
+      }
+      ownerByAction.set(actionId, desc.triggers);
+      result.push({ actionId, handler, ownerTriggers: desc.triggers });
+    }
+  }
+  return result;
+}