@sublang/playbook 0.5.0 → 0.7.0

package/reference/sdlc/code.playbook/code.tmux-play.ts

@@ -1,203 +1,29 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
-// tmux-play host adapter for the CODE playbook — DR-004 §11. This is
-// the only file in IR-004 that imports cligent; removing the import
-// shall not affect code.playbook.ts or its tests.
-
-import type {
-  BossTurn,
-  Captain,
-  CaptainContext,
-  CaptainSession,
-} from '@sublang/cligent/tmux-play';
-import createPlaybookRuntime, {
-  type CodePlaybookOptions,
-  type PlaybookPorts,
-  type PlaybookRuntime,
-} from './code.playbook.js';
-
-// PBRT-29/30: CODE runtime options are carried under
-// `captain.options.code`, a namespaced object the host forwards
-// verbatim through `captain.options`. cligent neither reads nor
-// validates `options.code` (PBRT-30); this adapter is the sole
-// validator. The CODE options schema defines one key, `committer`: an
-// optional Committer-alias player id, one of the baked player ids
-// `coder` / `reviewer`. A valid `options.code` is absent, `{}`, or
-// `{ committer: 'coder' | 'reviewer' }`; every other key is unknown
-// and rejected with a path-named error, and an out-of-range
-// `committer` value is rejected naming `captain.options.code.committer`.
-// A further CODE option shall be introduced as its own higher-numbered
-// item that widens `CODE_OPTION_KEYS`; the validator still fails closed
-// on stray keys.
-const CODE_OPTION_KEYS = new Set<string>(['committer']);
-const COMMITTER_PLAYER_IDS = new Set<string>(['coder', 'reviewer']);
-
-// The validated CODE options set. `committer`, when present, is the
-// resolved Committer-alias player id (PBRT-8 / PBRT-30); a future CODE
-// option widens both this type and `CODE_OPTION_KEYS`.
-export interface CodeOptions {
-  committer?: 'coder' | 'reviewer';
-}
-
-export function validateCodeOptions(captainOptions: unknown): CodeOptions {
-  const code = readCodeNamespace(captainOptions);
-  if (code === undefined) return {};
-  if (typeof code !== 'object' || code === null || Array.isArray(code)) {
-    throw new Error('captain.options.code must be an object');
-  }
-  for (const key of Object.keys(code)) {
-    if (!CODE_OPTION_KEYS.has(key)) {
-      throw new Error(`Unknown config field captain.options.code.${key}`);
-    }
-  }
-  const options: CodeOptions = {};
-  const committer = (code as Record<string, unknown>).committer;
-  if (committer !== undefined) {
-    if (typeof committer !== 'string' || !COMMITTER_PLAYER_IDS.has(committer)) {
-      throw new Error(
-        "captain.options.code.committer must be 'coder' or 'reviewer'",
-      );
-    }
-    options.committer = committer as 'coder' | 'reviewer';
-  }
-  return options;
-}
-
-function readCodeNamespace(captainOptions: unknown): unknown {
-  if (
-    typeof captainOptions !== 'object' ||
-    captainOptions === null ||
-    Array.isArray(captainOptions)
-  ) {
-    return undefined;
-  }
-  return (captainOptions as Record<string, unknown>).code;
-}
-
-// Captain factory per TMUX-014: `(options: unknown) => Captain`.
-// `options` is whatever `captain.options` carries in the YAML config;
-// CODE reads only the namespaced `options.code` (PBRT-30). The per-run
-// player identity strings (`coderPlayer`, `reviewerPlayer`) are
-// derived from `session.players` at init time per PBRT-4 — preferring
-// each entry's `model` and falling back to `adapter` when no model is
-// pinned — so player prompts and commit-message trailers carry the
-// concrete model identity (e.g. `claude-opus-4-7`) rather than the
-// adapter family name (e.g. `claude`). They come from `session.players`
-// independent of `captain.options.code` and override any same-named
-// keys.
+import type { Captain } from '@sublang/cligent/tmux-play';
+import createPlaybookCaptainShell from './playbook-captain.js';
+
+export {
+  codeCopyPasteGuardNames,
+  codeStateCountLabels,
+  codePlaybookRegistryEntry,
+  createCodeRuntimeOptions,
+  validateCodeOptions,
+} from './code.registry.js';
+export type {
+  CodeOptions,
+  CodePlaybookRegistryEntry,
+  CreateCodeRuntimeOptions,
+  RegistryPlayer,
+} from './code.registry.js';
+
+// Compatibility shim for the historic `./code/tmux-play` package
+// export. Public launch paths now target the Playbook Captain shell
+// directly; explicit configs that still import this module get the
+// same shell with CODE registered.
 export default function createCodeTmuxPlayCaptain(
   options: unknown,
 ): Captain {
-  // CaptainSession is bound at init time and persists across turns;
-  // CaptainContext is rebuilt per turn and carries the call
-  // primitives. The runtime is constructed in `init` so identity
-  // strings derived from `session.players` can flow into its options;
-  // PlaybookPorts is built once at init, so the per-turn context
-  // lives in a closure-scoped slot the port callbacks query lazily.
-  let runtime: PlaybookRuntime | undefined;
-  let activeContext: CaptainContext | undefined;
-
-  return {
-    async init(session: CaptainSession): Promise<void> {
-      // PBRT-30: validate `captain.options.code` before constructing
-      // the runtime so a stray key fails `init` closed with a
-      // path-named error; the empty schema yields an empty options set.
-      const codeOptions = validateCodeOptions(options);
-      const playerIdentity = (id: string): string | undefined => {
-        const entry = session.players.find((p) => p.id === id);
-        return entry?.model ?? entry?.adapter;
-      };
-      const coderPlayer = playerIdentity('coder');
-      const reviewerPlayer = playerIdentity('reviewer');
-      // Identity strings from `session.players` override any same-named
-      // keys and are independent of `captain.options.code` (PBRT-30).
-      // The validated `committer` alias threads in as the runtime's
-      // Committer player id (`committerPlayer`, PBRT-8).
-      const runtimeOptions: CodePlaybookOptions = {
-        coderPlayer,
-        reviewerPlayer,
-        ...(codeOptions.committer !== undefined
-          ? { committerPlayer: codeOptions.committer }
-          : {}),
-      };
-      runtime = createPlaybookRuntime(runtimeOptions);
-      const ports: PlaybookPorts = {
-        callPlayer: async (playerId, prompt, _signal) => {
-          if (!activeContext) {
-            throw new Error('callPlayer invoked outside a Boss turn');
-          }
-          // PlayerRunResult per TMUX-033 already matches PlayerResult
-          // (`status: 'ok' | 'aborted' | 'error'`, `finalText?`,
-          // `error?`). cligent honors context.signal internally;
-          // the runtime's signal is the same source forwarded
-          // through handleBossInput, so dropping `_signal` is
-          // safe.
-          const r = await activeContext.callPlayer(playerId, prompt);
-          return {
-            status: r.status,
-            finalText: r.finalText,
-            error: r.error,
-          };
-        },
-        callJudge: async (prompt, _signal) => {
-          if (!activeContext) {
-            throw new Error('callJudge invoked outside a Boss turn');
-          }
-          // PBRT-15 / DR-007: run the judge call hidden so its JSON
-          // reply never reaches the Boss pane; the runtime composes the
-          // human-readable pane lines (PBRT-3) from the parsed result.
-          const r = await activeContext.callCaptain(prompt, {
-            visibility: 'hidden',
-          });
-          if (r.status !== 'ok') {
-            throw new Error(
-              r.error ?? `callCaptain status "${r.status}"`,
-            );
-          }
-          if (r.finalText === undefined) {
-            throw new Error(
-              'callCaptain returned status=ok with no finalText',
-            );
-          }
-          return r.finalText;
-        },
-        emitStatus: async (message, data) => {
-          await session.emitStatus(
-            message,
-            data as Record<string, unknown> | undefined,
-          );
-        },
-        emitTelemetry: async (event) => {
-          await session.emitTelemetry(event);
-        },
-      };
-      await runtime.init(ports);
-    },
-
-    async handleBossTurn(
-      turn: BossTurn,
-      context: CaptainContext,
-    ): Promise<void> {
-      if (!runtime) {
-        throw new Error('init must be called first');
-      }
-      activeContext = context;
-      try {
-        // Forward the Boss prompt + cligent's per-turn signal into
-        // the runtime; the runtime stashes the signal so the
-        // captain bridge passes it down to callPlayer / callJudge.
-        await runtime.handleBossInput({
-          text: turn.prompt,
-          signal: context.signal,
-        });
-      } finally {
-        activeContext = undefined;
-      }
-    },
-
-    async dispose(): Promise<void> {
-      await runtime?.dispose();
-    },
-  };
+  return createPlaybookCaptainShell(options);
 }

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

@@ -0,0 +1,21 @@
+import type { Captain } from '@sublang/cligent/tmux-play';
+import type { PlaybookRuntime } from './code.playbook.js';
+import { type RegistryPlayer } from './code.registry.js';
+export interface CreatePlaybookRuntimeOptions {
+    captainOptions: unknown;
+    players: readonly RegistryPlayer[];
+}
+export interface PlaybookCaptainRegistryEntry {
+    id: string;
+    command: string;
+    intent: string;
+    idleStateId: string;
+    finalStateId: string;
+    copyPasteGuardNames: readonly string[];
+    stateCountLabels?: Readonly<Record<string, string>>;
+    validateOptions(captainOptions: unknown): unknown;
+    createRuntime(options: CreatePlaybookRuntimeOptions): PlaybookRuntime;
+}
+export declare const playbookCaptainRegistry: readonly PlaybookCaptainRegistryEntry[];
+export declare function createPlaybookCaptainShell(options: unknown, registry?: readonly PlaybookCaptainRegistryEntry[]): Captain;
+export default createPlaybookCaptainShell;