@sublang/playbook 1.0.0 → 1.3.0

package/README.md

@@ -149,7 +149,14 @@ and the captain default to `claude`; bind them with
 `claude@high` for the default model at high reasoning effort; the
 model keeps every interior colon (`opencode:ollama/llama3:8b@max`),
 and unsupported efforts are rejected up front naming the adapter's
-supported values. Pass a playbook option with
+supported values. To stop retyping those flags, set durable defaults
+once in the user config's top-level `run:` block — `run.captain`,
+`run.players.<role>`, and a `run.player` catch-all for any other
+required role, each the same agent string; flags keep winning per
+role, and `resume` always keeps the lineup stored with the parked
+session ([PBCLI-28](specs/user/playbook-cli.md#pbcli-28),
+[DR-017](specs/decisions/017-run-defaults-config.md)). Pass a
+playbook option with
 `--option <key>=<value>`, and add `--json` to print one JSON envelope
 (`outcome`, `sessionId`, and the output or pending questions) instead
 of plain text. It exits `0` on a terminal outcome, `2` on failure, `3`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "1.0.0",
+  "version": "1.3.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, and DISCUSS workflows driven by GEARS specs.",
   "license": "Apache-2.0",
@@ -31,6 +31,9 @@
     "src/xstate-runtime.ts",
     "src/xstate-runtime.js",
     "src/xstate-runtime.d.ts",
+    "src/xstate-playbook-runtime.ts",
+    "src/xstate-playbook-runtime.js",
+    "src/xstate-playbook-runtime.d.ts",
     "slc/link.md",
     "slc/gears2fsm.md",
     "slc/text2gears.md",
@@ -124,6 +127,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.154",
     "@openai/codex-sdk": "^0.139.0",
     "@sublang/cligent": "^0.15.0",
+    "@sublang/spex": "^0.3.0",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",
     "yaml": "^2.9.0"

package/reference/sdlc/captain.playbook/captain.fsm.d.ts

@@ -198,7 +198,7 @@ export declare const captainMachine: import("xstate").StateMachine<Context, Boss
 } | {
     type: "isAuthoredChildError";
     params: unknown;
-}, never, "done" | "failed" | "callPlaybook" | "routing" | "reassessing" | "ready" | "awaitBossReply", string, CaptainMachineInput, CaptainMachineOutput, import("xstate").EventObject, import("xstate").MetaObject, {
+}, never, "done" | "failed" | "callPlaybook" | "awaitBossReply" | "ready" | "routing" | "reassessing", string, CaptainMachineInput, CaptainMachineOutput, import("xstate").EventObject, import("xstate").MetaObject, {
     id: "captain";
     states: {
         readonly ready: {

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

@@ -44,6 +44,9 @@ export async function runPlaybookCli(options = {}) {
   const stdout = options.stdout ?? process.stdout;
   const stderr = options.stderr ?? process.stderr;
   const loadModule = options.loadModule ?? ((specifier) => import(specifier));
+  const home = options.homeDir ?? env.HOME ?? homedir();
+  const userConfigPath =
+    options.userConfigPath ?? resolveUserConfigPath(env, home);
 
   // PBCLI-18: `playbook run ...` is the non-interactive one-shot path; it
   // never seeds, composes, resolves tmux-play, or launches it.
@@ -53,6 +56,9 @@ export async function runPlaybookCli(options = {}) {
       argv: argv.slice(1),
       stdout,
       stderr,
+      // PBCLI-29: the run host reads the same user config as the launcher,
+      // honoring any injected env, home, or explicit path.
+      userConfigPath,
       ...(options.loadModule ? { loadModule: options.loadModule } : {}),
       ...(options.createAgent ? { createAgent: options.createAgent } : {}),
       ...(options.readStdin ? { readStdin: options.readStdin } : {}),
@@ -62,8 +68,6 @@ export async function runPlaybookCli(options = {}) {
 
   const spawnFn = options.spawn ?? spawn;
   const tmuxPlayBin = options.tmuxPlayBin ?? resolveTmuxPlayBin();
-  const home = options.homeDir ?? env.HOME ?? homedir();
-  const userConfigPath = resolveUserConfigPath(env, home);
 
   // PBCLI-6: `--help` / `-h` print help and exit 0 without seeding,
   // composing, or launching.

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

@@ -27,6 +27,7 @@ import {
   isEffortSupported,
   supportedEffortValues,
 } from '@sublang/cligent';
+import { parse as parseYaml } from 'yaml';
 
 // PBCLI-19: adapter shorthands the run host can construct.
 const ADAPTER_LOADERS = {
@@ -61,6 +62,10 @@ export async function runPlaybookRun(options = {}) {
   const createAgent = options.createAgent ?? defaultCreateAgent;
   const readStdin = options.readStdin ?? readAllStdin;
   const sessionsDir = options.sessionsDir ?? defaultSessionsDir(process.env);
+  // PBCLI-28/29: config defaults come from the same user config file the
+  // interactive launcher resolves; tests inject a hermetic path.
+  const userConfigPath =
+    options.userConfigPath ?? (await defaultUserConfigPath());
   const ctx = {
     stdout,
     stderr,
@@ -69,6 +74,7 @@ export async function runPlaybookRun(options = {}) {
     createAgent,
     readStdin,
     sessionsDir,
+    userConfigPath,
   };
 
   let args;
@@ -105,9 +111,28 @@ async function runFirst(args, ctx) {
     return { code: EXIT.arg };
   }
 
-  // PBCLI-19: bind every required role, then the captain; defaults to claude.
+  // PBCLI-28 (DR-017): config-supplied defaults bind only a first run;
+  // runResume rebuilds the lineup stored with the session.
+  let runDefaults;
+  try {
+    runDefaults = await loadRunDefaults(ctx.userConfigPath);
+  } catch (error) {
+    stderr.write(`playbook run: ${message(error)}\n`);
+    return { code: EXIT.arg };
+  }
+
+  // PBCLI-19/28: bind every required role, then the captain — flag over
+  // config default over built-in claude. An unrequired run.players role is
+  // ignored (the config is global across playbooks); an unrequired
+  // --player flag stays an error below.
   const roleSpecs = new Map(
-    entry.requiredRoleIds.map((role) => [role, { adapter: DEFAULT_ADAPTER }]),
+    entry.requiredRoleIds.map((role) => [
+      role,
+      {
+        ...(runDefaults.players.get(role) ??
+          runDefaults.player ?? { adapter: DEFAULT_ADAPTER }),
+      },
+    ]),
   );
   for (const [role, spec] of args.players) {
     if (!roleSpecs.has(role)) {
@@ -116,7 +141,8 @@ async function runFirst(args, ctx) {
     }
     roleSpecs.set(role, spec);
   }
-  const captainSpec = args.captain ?? { adapter: DEFAULT_ADAPTER };
+  const captainSpec =
+    args.captain ?? runDefaults.captain ?? { adapter: DEFAULT_ADAPTER };
   const specError = specsDiagnostic([...roleSpecs.values(), captainSpec]);
   if (specError !== undefined) {
     stderr.write(`playbook run: ${specError}\n`);
@@ -586,6 +612,83 @@ function isAgentSpec(spec) {
   );
 }
 
+// PBCLI-29: the run host reads the same user config file the interactive
+// launcher resolves. The resolver is imported lazily: a static import of
+// ./playbook.js would deadlock the CLI entry — playbook.js is still
+// mid-evaluation of its own top-level await when it dynamically imports
+// this module, and a circular static edge back to it can never settle.
+// The launcher always injects userConfigPath, so this default runs only
+// for direct runPlaybookRun callers, where playbook.js is not evaluating.
+async function defaultUserConfigPath() {
+  const { resolveUserConfigPath } = await import('./playbook.js');
+  return resolveUserConfigPath(process.env, process.env.HOME ?? homedir());
+}
+
+// PBCLI-28/29 (DR-017): default agent specs for a first run, read from the
+// user config's top-level `run` map. An absent file or absent map is an
+// empty default set; a malformed file or block fails closed — the run must
+// never silently bind different agents than the user configured. Adapter
+// and effort support of the specs actually bound flow through the shared
+// specsDiagnostic path.
+async function loadRunDefaults(userConfigPath) {
+  const defaults = { players: new Map() };
+  let text;
+  try {
+    text = await readFile(userConfigPath, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return defaults;
+    throw new Error(`cannot read config ${userConfigPath}: ${message(error)}`);
+  }
+  let config;
+  try {
+    config = parseYaml(text);
+  } catch (error) {
+    throw new Error(`cannot parse config ${userConfigPath}: ${message(error)}`);
+  }
+  const run = isPlainMap(config) ? config.run : undefined;
+  if (run === undefined || run === null) return defaults;
+  if (!isPlainMap(run)) {
+    throw new Error(`${userConfigPath}: run must be a map of agent defaults`);
+  }
+  if (run.captain !== undefined) {
+    defaults.captain = parseAgentDefault(run.captain, 'run.captain', userConfigPath);
+  }
+  if (run.player !== undefined) {
+    defaults.player = parseAgentDefault(run.player, 'run.player', userConfigPath);
+  }
+  if (run.players !== undefined && run.players !== null) {
+    if (!isPlainMap(run.players)) {
+      throw new Error(
+        `${userConfigPath}: run.players must be a map of <role>: <agent>`,
+      );
+    }
+    for (const [role, value] of Object.entries(run.players)) {
+      defaults.players.set(
+        role,
+        parseAgentDefault(value, `run.players.${role}`, userConfigPath),
+      );
+    }
+  }
+  return defaults;
+}
+
+function parseAgentDefault(value, key, userConfigPath) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(
+      `${userConfigPath}: ${key} must be an <adapter>[:<model>][@<effort>] string`,
+    );
+  }
+  try {
+    return parseAgent(value);
+  } catch (error) {
+    throw new Error(`${userConfigPath}: ${key}: ${message(error)}`);
+  }
+}
+
+function isPlainMap(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 // PBCLI-23: the session store honors XDG_STATE_HOME at invocation time.
 export function defaultSessionsDir(env = process.env) {
   const stateHome =
@@ -877,7 +980,10 @@ function runHelpText() {
     '  <agent> is <adapter>[:<model>][@<effort>] over the shorthands',
     '  claude, codex, gemini, opencode — e.g. codex:gpt-5.5@xhigh, or',
     '  claude@high for the default model at high effort. Every role and',
-    '  the captain default to claude.',
+    '  the captain default to claude, unless a top-level run: block in',
+    '  ${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml',
+    '  supplies defaults — run.captain, run.players.<role>, or the',
+    '  run.player catch-all for other roles; flags override per role.',
     '',
     '  When a playbook needs a Boss reply, the run prints the question,',
     '  parks the session under',

package/reference/sdlc/code.playbook/code.playbook.d.ts

@@ -1,27 +1,14 @@
+import { normalizeErrorCompact, normalizeErrorFull, type PlaybookPlayerInput, type RuntimeBoundaryCalls } from '../../../src/xstate-runtime.js';
 import { type PlayerInput, type PlayerOutput, type CodingEvent, type CodingInput } from './code.fsm.js';
 import type { CaptainCallOptions, CaptainResult, JsonValue, NormalizedError, PlayerCallOptions, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookPendingCall, PlaybookRunResult, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlaybookStateValue, PlaybookTraceEvent, PlaybookTraceType, PlaybookPorts, PlaybookRuntime, PlaybookRuntimeFactory, PlayerResult } from '@sublang/playbook/runtime';
 export type { CaptainCallOptions, CaptainResult, JsonValue, NormalizedError, PlayerCallOptions, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookPendingCall, PlaybookRunResult, PlayerResult, PlaybookPorts, PlaybookSession, PlaybookState, PlaybookStateValue, PlaybookTraceEvent, PlaybookTraceType, PlaybookRuntime, PlaybookRuntimeFactory, PlaybookRuntimeSnapshot, };
 export type CodePlaybookOptions = CodingInput;
-declare function normalizeErrorCompact(err: unknown): {
-    name: string;
-    message: string;
-} | undefined;
-declare function normalizeErrorFull(err: unknown): {
-    name: string;
-    message: string;
-    stack?: string;
-} | undefined;
 declare function normalizeEventForTelemetry(event: unknown): unknown;
 declare function composePlayerPrompt(input: PlayerInput): string;
 declare function resolvePlayerId(input: PlayerInput): string;
-type JudgePurpose = 'boss-input-classification' | 'player-output-adjudication';
-interface RuntimeBoundaryCalls {
-    callPlayer(input: PlayerInput, playerId: string, prompt: string, signal: AbortSignal): Promise<PlayerResult>;
-    callJudge(purpose: JudgePurpose, stateId: string | undefined, prompt: string, signal: AbortSignal): Promise<string>;
-}
 declare function adjudicate(input: PlayerInput, finalText: string, ports: PlaybookPorts, signal: AbortSignal, boundary?: RuntimeBoundaryCalls): Promise<PlayerOutput>;
 declare function classifyBossText(text: string, ports: PlaybookPorts, signal: AbortSignal, snapshotOrState?: unknown, boundary?: RuntimeBoundaryCalls): Promise<CodingEvent | undefined>;
-declare function captainBridge(ports: PlaybookPorts, getActiveSignal?: () => AbortSignal | undefined, boundary?: RuntimeBoundaryCalls, onControlPlaneError?: (error: unknown) => void): import("xstate").PromiseActorLogic<import("./code.fsm.js").CaptainOutput, PlayerInput, import("xstate").EventObject>;
+declare function captainBridge(ports: PlaybookPorts, getActiveSignal?: () => AbortSignal | undefined, boundary?: RuntimeBoundaryCalls, onControlPlaneError?: (error: unknown) => void): import("xstate").PromiseActorLogic<import("../../../src/xstate-playbook-runtime.js").PlaybookActorOutput, PlaybookPlayerInput>;
 interface StateMetadata {
     player: PlayerInput['player'];
     sourceItem: string;
@@ -64,4 +51,5 @@ export declare const _internal: {
     normalizeEventForTelemetry: typeof normalizeEventForTelemetry;
     VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string>;
 };
-export default function createPlaybookRuntime(options: CodePlaybookOptions): PlaybookRuntime;
+declare const createPlaybookRuntime: PlaybookRuntimeFactory<CodePlaybookOptions>;
+export default createPlaybookRuntime;