@sublang/playbook 0.1.3 → 0.4.0

package/README.md

@@ -34,36 +34,104 @@ committer loop end to end.
 
 The reference is the canonical worked example —
 [CODE source](reference/sdlc/code.md) →
-[gears](code.gears.md) →
-[FSM](code.fsm.ts) → runtime — with the
-runtime ported to cligent's `tmux-play` host out of the box.
+[gears](reference/sdlc/code.playbook/code.gears.md) →
+[FSM](reference/sdlc/code.playbook/code.fsm.ts) → runtime — with
+the runtime ported to cligent's `tmux-play` host out of the box.
+The compiled artifacts live under
+[`reference/sdlc/code.playbook/`](reference/sdlc/code.playbook),
+the slc pipeline's `<basename>.<pipeline>/` output directory.
 
 ### Install (users)
 
-Install the package globally. The bundled production config wires
-Anthropic (Captain + Coder) and OpenAI Codex (Reviewer); `@sublang/
-cligent`, the two adapter SDKs, and `xstate` are all direct
-dependencies, so a single install pulls in everything:
+Install the package globally. `@sublang/cligent`, the Claude and
+Codex adapter SDKs, and `xstate` are direct dependencies, so a single
+install pulls in the reference CODE playbook and its host:
 
 ```sh
 npm install -g @sublang/playbook
 ```
 
-Each adapter reads its own auth: the Claude SDK uses your local
-Claude Code auth (or `ANTHROPIC_API_KEY`); the Codex SDK uses your
-local codex CLI auth (or `OPENAI_API_KEY`).
-
 Then launch the reference playbook in a `tmux-play` session:
 
 ```sh
 playbook-code
 ```
 
-The `playbook-code` bin resolves the bundled
-`tmux-play.production.config.yaml` and execs the bundled `tmux-play`
-CLI (from playbook's own `node_modules/@sublang/cligent`) against it;
-any extra flags pass through (`playbook-code --help` lists
-`tmux-play`'s).
+For a one-shot run without a global install, use the same command
+through npx:
+
+```sh
+npx playbook-code
+```
+
+On first run, `playbook-code` creates a commented user config at
+`${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook-code.config.yaml`
+from the bundled template, prints that path to stderr, then checks the
+declared adapters before launching. Later runs reuse that file and do
+not overwrite it.
+
+Known adapter readiness is intentionally light: `claude` is ready when
+local Claude Code auth exists or `ANTHROPIC_API_KEY` is set; `codex` is
+ready when local Codex CLI auth exists or `OPENAI_API_KEY` is set. If a
+known adapter is not ready, `playbook-code` prints its own help text
+with the config path, auth pointers, and agent-swap recipe, then exits
+without launching. You can view the same recovery text at any time:
+
+```sh
+playbook-code --help
+```
+
+The seed template runs each agent in cligent's protected auto mode
+(`permissions.mode: auto`), suppressing routine approval prompts.
+
+### Configure agents
+
+Edit the seeded user config when you want different coding agents:
+
+```sh
+$EDITOR "${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook-code.config.yaml"
+```
+
+Both CODE players can use `claude` or `codex`; other adapter ids are
+passed through to `tmux-play` with a warning because `playbook-code`
+does not know how to preflight their auth. The safe tuning points are
+`captain.adapter`, `captain.model`, and each player's `adapter`. Keep
+`captain.from` and the `players[].id` values fixed; the runtime binds
+to those host-configuration invariants per
+[PBRT-4](specs/user/playbook-runtime.md#pbrt-4) and derives the
+`<coder-llm>` / `<reviewer-llm>` substitution strings from each
+player entry's `adapter`.
+
+For example, this swaps the Coder to Codex and the Reviewer to Claude:
+
+```yaml
+captain:
+  from: "@sublang/playbook/code/tmux-play"
+  adapter: claude
+  model: claude-opus-4-7
+  permissions:
+    mode: auto
+
+players:
+  - id: coder      # must stay `coder` — see PBRT-4
+    adapter: codex
+    permissions:
+      mode: auto
+  - id: reviewer   # must stay `reviewer` — see PBRT-4
+    adapter: claude
+    permissions:
+      mode: auto
+```
+
+Normal `playbook-code` runs use the seeded path above. If you need a
+separate config file for a one-off run, pass it explicitly; this bypasses
+the seed and readiness gate and forwards the arguments to `tmux-play`
+verbatim, as pinned in
+[PBCODE-1](specs/user/playbook-code.md#pbcode-1):
+
+```sh
+playbook-code --config ./playbook-code.config.yaml
+```
 
 ### Install (contributors / from source)
 
@@ -77,7 +145,7 @@ pnpm build
 pnpm test
 ```
 
-`pnpm install` resolves `@sublang/cligent` (≥ 0.3.0) from the registry;
+`pnpm install` resolves `@sublang/cligent` (^0.6.0) from the registry;
 no local link required. To point pnpm at a local `cligent` checkout
 instead, copy
 [`pnpm-workspace.yaml.example`](pnpm-workspace.yaml.example)
@@ -85,11 +153,11 @@ into place; the override is gitignored so it never leaks into a
 production install.
 
 Drive a Boss turn against the source tree (uses the developer
-[`tmux-play.config.yaml`](tmux-play.config.yaml)
+[`tmux-play.config.yaml`](reference/sdlc/code.playbook/tmux-play.config.yaml)
 that imports the compiled adapter via relative path):
 
 ```sh
-pnpm exec tmux-play --config tmux-play.config.yaml
+pnpm exec tmux-play --config reference/sdlc/code.playbook/tmux-play.config.yaml
 ```
 
 `pnpm exec` resolves `tmux-play` from the package's local
@@ -98,16 +166,16 @@ installed globally.
 
 ### Running a Boss turn
 
-The Boss pane accepts four slash commands per
-[PBRT-1](specs/user/playbook-runtime.md#pbrt-1):
-
-- `/start <intent>` — begin a single coding turn
-- `/continue <#>` — pick up an IR task
-- `/summarize <#>` — turn an IR's commits into spec items
-- `/interrupt <stateId> [intent]` — preempt the FSM into a named state
+The Boss pane takes plain-language turns; the judge classifies each
+into an FSM event (start a coding turn, continue or summarize an IR,
+interrupt to a named state, or nothing) per
+[PBRT-1](specs/user/playbook-runtime.md#pbrt-1).
+When a player surfaces a clarifying question
+the FSM parks at `awaitBossReply` and the pane shows the question; your
+next turn is normally classified as the reply, or a fresh directive
+abandons it ([PBRT-2](specs/user/playbook-runtime.md#pbrt-2)).
 
-Anything else falls through to an LLM classifier. The Captain pane
-streams the state machine progression with a four-glyph vocabulary —
+The Captain pane streams the state machine with a four-glyph vocabulary —
 `◆ ▸ ⮕ ⤷` per [PBRT-3](specs/user/playbook-runtime.md#pbrt-3) — while
 player prompts ride their own panes.
 
@@ -135,14 +203,14 @@ const runtime = createPlaybookRuntime({
 
 await runtime.init(ports);
 await runtime.handleBossInput({
-  text: '/start fix the bug',
+  text: 'Start fixing the bug',
   signal: new AbortController().signal,
 });
 await runtime.dispose();
 ```
 
 See
-[`code.playbook.test.ts`](code.playbook.test.ts)
+[`code.playbook.test.ts`](reference/sdlc/code.playbook/code.playbook.test.ts)
 for the full range of port shapes (classifier, judge, abort, interrupt,
 status/telemetry) the runtime is contract-tested against.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "0.1.3",
+  "version": "0.4.0",
   "type": "module",
   "description": "Reference CODE playbook — XState v5 FSM, host-agnostic runtime, and tmux-play adapter for a coder/reviewer/committer loop driven by GEARS spec items.",
   "license": "Apache-2.0",
@@ -25,34 +25,35 @@
     "node": ">=20.6.0"
   },
   "files": [
-    "code.fsm.ts",
-    "code.fsm.js",
-    "code.fsm.d.ts",
-    "code.fsm.introspect.ts",
-    "code.fsm.introspect.js",
-    "code.fsm.introspect.d.ts",
-    "code.playbook.ts",
-    "code.playbook.js",
-    "code.playbook.d.ts",
-    "code.tmux-play.ts",
-    "code.tmux-play.js",
-    "code.tmux-play.d.ts",
-    "code.gears.md",
-    "tmux-play.config.yaml",
-    "tmux-play.production.config.yaml",
-    "bin"
+    "reference/sdlc/code.playbook/code.fsm.ts",
+    "reference/sdlc/code.playbook/code.fsm.js",
+    "reference/sdlc/code.playbook/code.fsm.d.ts",
+    "reference/sdlc/code.playbook/code.fsm.introspect.ts",
+    "reference/sdlc/code.playbook/code.fsm.introspect.js",
+    "reference/sdlc/code.playbook/code.fsm.introspect.d.ts",
+    "reference/sdlc/code.playbook/code.playbook.ts",
+    "reference/sdlc/code.playbook/code.playbook.js",
+    "reference/sdlc/code.playbook/code.playbook.d.ts",
+    "reference/sdlc/code.playbook/code.tmux-play.ts",
+    "reference/sdlc/code.playbook/code.tmux-play.js",
+    "reference/sdlc/code.playbook/code.tmux-play.d.ts",
+    "reference/sdlc/code.playbook/code.gears.md",
+    "reference/sdlc/code.playbook/tmux-play.config.yaml",
+    "reference/sdlc/code.playbook/tmux-play.production.config.yaml",
+    "reference/sdlc/code.playbook/playbook-code.config.template.yaml",
+    "reference/sdlc/code.playbook/bin"
   ],
   "bin": {
-    "playbook-code": "bin/playbook-code.js"
+    "playbook-code": "reference/sdlc/code.playbook/bin/playbook-code.js"
   },
   "exports": {
     "./code/playbook": {
-      "types": "./code.playbook.d.ts",
-      "default": "./code.playbook.js"
+      "types": "./reference/sdlc/code.playbook/code.playbook.d.ts",
+      "default": "./reference/sdlc/code.playbook/code.playbook.js"
     },
     "./code/tmux-play": {
-      "types": "./code.tmux-play.d.ts",
-      "default": "./code.tmux-play.js"
+      "types": "./reference/sdlc/code.playbook/code.tmux-play.d.ts",
+      "default": "./reference/sdlc/code.playbook/code.tmux-play.js"
     }
   },
   "scripts": {
@@ -66,7 +67,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.143",
     "@openai/codex-sdk": "^0.130.0",
-    "@sublang/cligent": "^0.4.0",
+    "@sublang/cligent": "^0.6.0",
     "xstate": "^5.19.4"
   },
   "devDependencies": {

package/reference/sdlc/code.playbook/bin/playbook-code.js

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+import { spawn } from 'node:child_process';
+import {
+  constants,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const templatePath = resolve(here, '..', 'playbook-code.config.template.yaml');
+const READINESS_FAILURE_EXIT_CODE = 2;
+
+export async function runPlaybookCodeCli(options = {}) {
+  const argv = [...(options.argv ?? process.argv.slice(2))];
+  const env = options.env ?? process.env;
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const spawnFn = options.spawn ?? spawn;
+  const tmuxPlayBin = options.tmuxPlayBin ?? resolveTmuxPlayBin();
+  const home = options.homeDir ?? env.HOME ?? homedir();
+  const userConfigPath = resolveUserConfigPath(env, home);
+
+  if (argv.includes('--help') || argv.includes('-h')) {
+    stdout.write(helpText({ userConfigPath }));
+    return { code: 0 };
+  }
+
+  const explicitConfig = hasExplicitConfig(argv);
+  const configPath = explicitConfig ? undefined : userConfigPath;
+
+  if (!explicitConfig) {
+    seedUserConfigIfMissing(userConfigPath, stderr);
+    const readiness = checkReadiness(userConfigPath, env, home);
+    for (const adapter of readiness.unknownAdapters) {
+      stderr.write(
+        `playbook-code: warning: no readiness check for adapter "${adapter}"\n`,
+      );
+    }
+    if (readiness.failingAdapters.length > 0) {
+      stderr.write(
+        helpText({
+          userConfigPath,
+          failingAdapters: readiness.failingAdapters,
+        }),
+      );
+      return { code: READINESS_FAILURE_EXIT_CODE };
+    }
+  }
+
+  const childArgs = explicitConfig
+    ? [tmuxPlayBin, ...argv]
+    : [tmuxPlayBin, '--config', configPath, ...argv];
+  return await launchTmuxPlay(spawnFn, childArgs, stderr);
+}
+
+export function resolveUserConfigPath(env = process.env, home = homedir()) {
+  const configHome = env.XDG_CONFIG_HOME || join(home, '.config');
+  return join(configHome, 'playbook', 'playbook-code.config.yaml');
+}
+
+export function collectAdaptersFromConfig(source) {
+  const adapters = new Set();
+  let section = '';
+  let captainChildIndent;
+  let playerItemIndent;
+  let playerChildIndent;
+
+  for (const line of source.split(/\r?\n/)) {
+    const uncommented = stripYamlComment(line);
+    if (uncommented.trim() === '') continue;
+
+    const indent = leadingSpaceCount(uncommented);
+    const trimmed = uncommented.trim();
+
+    if (indent === 0) {
+      if (trimmed === 'captain:') section = 'captain';
+      else if (trimmed === 'players:') section = 'players';
+      else section = '';
+      captainChildIndent = undefined;
+      playerItemIndent = undefined;
+      playerChildIndent = undefined;
+      continue;
+    }
+
+    if (section === 'captain') {
+      captainChildIndent ??= indent;
+      if (indent === captainChildIndent) {
+        collectAdapterValue(trimmed, adapters);
+      }
+      continue;
+    }
+
+    if (section === 'players') {
+      if (trimmed.startsWith('- ')) {
+        playerItemIndent = indent;
+        playerChildIndent = undefined;
+        collectAdapterValue(trimmed.slice(2).trim(), adapters);
+        continue;
+      }
+      if (playerItemIndent !== undefined && indent > playerItemIndent) {
+        playerChildIndent ??= indent;
+        if (indent === playerChildIndent) {
+          collectAdapterValue(trimmed, adapters);
+        }
+      }
+    }
+  }
+  return [...adapters];
+}
+
+export function checkReadiness(configPath, env = process.env, home = homedir()) {
+  const config = readFileSync(configPath, 'utf8');
+  const adapters = collectAdaptersFromConfig(config);
+  const failingAdapters = [];
+  const unknownAdapters = [];
+
+  for (const adapter of adapters) {
+    if (adapter === 'claude') {
+      if (!env.ANTHROPIC_API_KEY && !existsSync(join(home, '.claude'))) {
+        failingAdapters.push(adapter);
+      }
+      continue;
+    }
+    if (adapter === 'codex') {
+      if (!env.OPENAI_API_KEY && !existsSync(join(home, '.codex'))) {
+        failingAdapters.push(adapter);
+      }
+      continue;
+    }
+    unknownAdapters.push(adapter);
+  }
+
+  return { failingAdapters, unknownAdapters };
+}
+
+function seedUserConfigIfMissing(userConfigPath, stderr) {
+  if (existsSync(userConfigPath)) return;
+  mkdirSync(dirname(userConfigPath), { recursive: true });
+  copyFileSync(templatePath, userConfigPath, constants.COPYFILE_EXCL);
+  stderr.write(`playbook-code: created config at ${userConfigPath}\n`);
+}
+
+function hasExplicitConfig(argv) {
+  return argv.some((arg) => arg === '--config' || arg.startsWith('--config='));
+}
+
+function helpText({ userConfigPath, failingAdapters = [] }) {
+  const failures =
+    failingAdapters.length > 0
+      ? [
+          `Adapters not ready: ${failingAdapters.join(', ')}`,
+          '',
+        ]
+      : [];
+  return [
+    ...failures,
+    'Usage:',
+    '  playbook-code [--config <path>] [tmux-play options]',
+    '  playbook-code --help',
+    '',
+    `Default config: ${userConfigPath}`,
+    '',
+    'Adapter setup:',
+    '  claude: run Claude Code once or set ANTHROPIC_API_KEY.',
+    '  codex: run Codex CLI once or set OPENAI_API_KEY.',
+    '',
+    'Agent swap recipe:',
+    '  - change captain.adapter and captain.model for the Captain/Judge',
+    '  - change each player adapter for the Coder and Reviewer',
+    '  - keep captain.from and players[].id fixed',
+    '',
+  ].join('\n');
+}
+
+async function launchTmuxPlay(spawnFn, childArgs, stderr) {
+  return await new Promise((resolveResult) => {
+    let child;
+    try {
+      child = spawnFn(process.execPath, childArgs, { stdio: 'inherit' });
+    } catch (error) {
+      stderr.write(`playbook-code: failed to launch tmux-play: ${errorMessage(error)}\n`);
+      resolveResult({ code: 127 });
+      return;
+    }
+
+    let settled = false;
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      resolveResult(result);
+    };
+
+    child.on('error', (err) => {
+      stderr.write(
+        `playbook-code: failed to launch tmux-play: ${errorMessage(err)}\n`,
+      );
+      settle({ code: 127 });
+    });
+
+    child.on('exit', (code, signal) => {
+      if (signal) settle({ signal });
+      else settle({ code: code ?? 0 });
+    });
+  });
+}
+
+function resolveTmuxPlayBin() {
+  const tmuxPlayIndexUrl = import.meta.resolve('@sublang/cligent/tmux-play');
+  return join(dirname(fileURLToPath(tmuxPlayIndexUrl)), 'cli.js');
+}
+
+function stripYamlComment(line) {
+  let quote = '';
+  for (let index = 0; index < line.length; index += 1) {
+    const char = line[index];
+    if ((char === '"' || char === "'") && line[index - 1] !== '\\') {
+      quote = quote === char ? '' : quote || char;
+      continue;
+    }
+    if (char === '#' && !quote) {
+      return line.slice(0, index);
+    }
+  }
+  return line;
+}
+
+function unquoteYamlScalar(value) {
+  const trimmed = value.trim();
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1).trim();
+  }
+  return trimmed;
+}
+
+function collectAdapterValue(trimmedLine, adapters) {
+  const match = trimmedLine.match(/^adapter\s*:\s*(.+?)\s*$/);
+  if (!match) return;
+  const value = unquoteYamlScalar(match[1].trim());
+  if (value) adapters.add(value);
+}
+
+function leadingSpaceCount(line) {
+  return line.length - line.trimStart().length;
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isCliEntry(
+  argv1 = process.argv[1],
+  moduleUrl = import.meta.url,
+) {
+  if (!argv1) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}
+
+if (isCliEntry()) {
+  const result = await runPlaybookCodeCli();
+  if (result.signal) process.kill(process.pid, result.signal);
+  else process.exit(result.code ?? 0);
+}

package/{code.fsm.d.ts → reference/sdlc/code.playbook/code.fsm.d.ts}

@@ -4,6 +4,13 @@ type WorkflowKind = 'singleCommit' | 'iteration' | 'specSummary';
 type ChangeOrigin = 'bossIntent' | 'irTask';
 type ReviewSubject = 'commit' | 'changes';
 type AfterReview = 'continueIr' | 'summarizeSpecs' | 'done';
+type ResumableStateId = Exclude<JumpableStateId, 'ready' | 'failed'>;
+type PendingBossQuestion = {
+    resumeStateId: ResumableStateId;
+    sourceItem: string;
+    player: Player;
+    question: string;
+};
 export type CaptainInput = {
     player: Player;
     sourceItem: string;
@@ -16,6 +23,8 @@ export type CaptainInput = {
     challenges?: string;
     coderPlayer?: string;
     reviewerPlayer?: string;
+    pendingBossQuestion?: PendingBossQuestion;
+    bossReply?: string;
 };
 export type CaptainOutput = {
     guard: string;
@@ -24,6 +33,7 @@ export type CaptainOutput = {
     reviews?: string;
     challenges?: string;
     summary?: string;
+    question?: string;
     [k: string]: unknown;
 };
 export type CodingInput = {
@@ -43,6 +53,8 @@ export type CodingContext = CodingInput & {
     challenges?: string;
     lastResult?: CaptainOutput;
     lastError?: unknown;
+    pendingBossQuestion?: PendingBossQuestion;
+    bossReply?: string;
 };
 export type CodingEvent = {
     type: 'START_CODING';
@@ -58,6 +70,9 @@ export type CodingEvent = {
     targetId: JumpableStateId;
     intent?: string;
     irNumber?: string;
+} | {
+    type: 'BOSS_REPLY';
+    answer: string;
 };
 export declare const codingMachine: import("xstate").StateMachine<CodingContext, {
     type: "START_CODING";
@@ -73,6 +88,9 @@ export declare const codingMachine: import("xstate").StateMachine<CodingContext,
     targetId: JumpableStateId;
     intent?: string;
     irNumber?: string;
+} | {
+    type: "BOSS_REPLY";
+    answer: string;
 }, {
     [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<CaptainOutput, CaptainInput, import("xstate").EventObject>> | undefined;
 }, {

package/{code.fsm.introspect.d.ts → reference/sdlc/code.playbook/code.fsm.introspect.d.ts}

@@ -9,6 +9,25 @@ export interface CaptainTransition {
     readonly index: number;
     readonly target: string;
     readonly guard: TransitionGuard;
+    readonly actions: unknown;
+}
+export interface AwaitBossReplyInfo {
+    readonly stateId: string;
+    readonly bossReplyTransitions: ReadonlyArray<BossReplyTransition>;
+    readonly transitions: ReadonlyArray<AwaitBossReplyTransition>;
+}
+export interface BossReplyTransition {
+    readonly index: number;
+    readonly target: string;
+    readonly guard: TransitionGuard;
+    readonly actions: unknown;
+}
+export interface AwaitBossReplyTransition {
+    readonly eventType: string;
+    readonly index: number;
+    readonly target: string;
+    readonly guard: TransitionGuard;
+    readonly actions: unknown;
 }
 export type TransitionGuard = (args: {
     context: CodingContext;
@@ -25,6 +44,11 @@ export interface RootEventTable {
         readonly target: string;
     };
     readonly bossInterruptTargets: ReadonlyArray<string>;
+    readonly bossInterruptTargetDescriptions: ReadonlyArray<{
+        readonly stateId: string;
+        readonly description: string;
+    }>;
 }
 export declare function enumerateCaptainStates(machine: typeof codingMachine): readonly CaptainStateInfo[];
 export declare function enumerateRootEvents(machine: typeof codingMachine): RootEventTable;
+export declare function enumerateAwaitBossReply(machine: typeof codingMachine): AwaitBossReplyInfo;

package/{code.fsm.introspect.js → reference/sdlc/code.playbook/code.fsm.introspect.js}

@@ -15,6 +15,7 @@ export function enumerateCaptainStates(machine) {
             index,
             target: stripIdPrefix(String(arm.target ?? '')),
             guard: arm.guard ?? alwaysTrue,
+            actions: arm.actions,
         }));
         out.push({
             stateId,
@@ -29,13 +30,39 @@ export function enumerateRootEvents(machine) {
     const cfg = getRawConfig(machine);
     const readyOn = (cfg.states?.ready?.on ?? {});
     const rootOn = (cfg.on ?? {});
+    const bossInterruptTargets = toArmArray(rootOn.BOSS_INTERRUPT).map((arm) => stripIdPrefix(String(arm.target ?? '')));
     return {
         startCoding: { target: stripIdPrefix(String(readyOn.START_CODING?.target ?? '')) },
         continueIr: { target: stripIdPrefix(String(readyOn.CONTINUE_IR?.target ?? '')) },
         summarizeIr: { target: stripIdPrefix(String(readyOn.SUMMARIZE_IR?.target ?? '')) },
-        bossInterruptTargets: toArmArray(rootOn.BOSS_INTERRUPT).map((arm) => stripIdPrefix(String(arm.target ?? ''))),
+        bossInterruptTargets,
+        bossInterruptTargetDescriptions: bossInterruptTargets.map((stateId) => {
+            const description = cfg.states?.[stateId]?.description;
+            return {
+                stateId,
+                description: typeof description === 'string' ? description : '',
+            };
+        }),
     };
 }
+export function enumerateAwaitBossReply(machine) {
+    const stateId = 'awaitBossReply';
+    const awaitOn = getRawConfig(machine).states?.[stateId]?.on ?? {};
+    const transitions = Object.entries(awaitOn).flatMap(([eventType, value]) => toArmArray(value).map((arm, index) => ({
+        eventType,
+        index,
+        target: stripIdPrefix(String(arm.target ?? '')),
+        guard: arm.guard ?? alwaysTrue,
+        actions: arm.actions,
+    })));
+    const bossReplyTransitions = toArmArray(awaitOn.BOSS_REPLY).map((arm, index) => ({
+        index,
+        target: stripIdPrefix(String(arm.target ?? '')),
+        guard: arm.guard ?? alwaysTrue,
+        actions: arm.actions,
+    }));
+    return { stateId, bossReplyTransitions, transitions };
+}
 function getRawConfig(machine) {
     return machine.config;
 }