@sublang/playbook 7.0.0 → 8.0.0

package/docs/embedding.md

@@ -16,8 +16,8 @@ your own host.
 The port and runtime contracts live in the type-only module
 [`@sublang/playbook/runtime`](../src/runtime.ts) — a public,
 semver-stable surface (`PlayerResult`, `PlaybookPorts`,
-`PlaybookRuntime`, `PlaybookSession`, `PlayerCallOptions`,
-`PlayerSessionStore`, `CaptainCallOptions`, `CaptainResult`,
+`PlaybookRuntime`, `PlaybookSession`, `PlaybookRoleBinding`,
+`PlayerCallOptions`, `PlayerSessionStore`, `CaptainCallOptions`, `CaptainResult`,
 `PlaybookTraceEvent`, and `PlaybookRuntimeFactory`) that imports no CODE
 or FSM types, so a host satisfies it once and inherits every playbook.
 The generated CODE, REVIEW, and DECIDE modules re-export their shared
@@ -37,6 +37,9 @@ import type {
   CaptainCallOptions,
   CaptainResult,
   PlaybookPorts,
+  PlaybookRoleBinding,
+  PlayerResult,
+  PlayerSessionStore,
 } from '@sublang/playbook/runtime';
 import { randomUUID } from 'node:crypto';
 import PQueue from 'p-queue';
@@ -53,6 +56,33 @@ declare const captainAdapter: {
   ): Promise<CaptainResult>;
 };
 
+declare const playerAdapter: {
+  run(
+    playerId: string,
+    prompt: string,
+    options: { signal: AbortSignal; resume: string | false },
+  ): Promise<PlayerResult>;
+};
+
+// Roles are local workflow identities. Players are stable provider
+// conversations owned by the logical Captain session. `promptIdentity` is
+// the current model name, or the player's adapter when provider-default is
+// selected; rebuild it from current compatible tuning on restore.
+const roleBindings = {
+  coder: {
+    playerId: 'team.coder',
+    promptIdentity: 'claude-opus-4-8[1m]',
+  },
+  reviewer: {
+    playerId: 'team.reviewer',
+    promptIdentity: 'gpt-5.5',
+  },
+} satisfies Readonly<Record<string, PlaybookRoleBinding>>;
+
+// Supply a frame-local role view over your session-wide player ledger.
+// Equal player IDs must select/update the same token; distinct IDs must not.
+declare const playerSessions: PlayerSessionStore;
+
 // Construct one host-wide lane and reuse it for every runtime. Passing each
 // call's signal to both the lane and adapter cancels queued and active work.
 const captainLane = new PQueue({ concurrency: 1 });
@@ -69,10 +99,16 @@ async function runCaptain(
 }
 
 const ports: PlaybookPorts = {
-  callPlayer: async (playerId, prompt, signal, { resume }) => {
+  callPlayer: async (roleId, prompt, signal, { resume }) => {
+    const binding = roleBindings[roleId as keyof typeof roleBindings];
+    if (binding === undefined) throw new Error(`Unknown role: ${roleId}`);
     // `resume === false` starts fresh; a string selects that player's
-    // prior backend conversation. Return the adapter's next token.
-    return { status: 'ok', finalText: 'done', resumeToken: 'next-token' };
+    // prior backend conversation. Return the adapter's next token; the
+    // runtime updates `playerSessions` only after validating this result.
+    return await playerAdapter.run(binding.playerId, prompt, {
+      signal,
+      resume,
+    });
   },
   callCaptain: async (prompt, signal, options) => {
     // Forward every option exactly: omission preserves configured tools, while
@@ -103,10 +139,7 @@ const ports: PlaybookPorts = {
   },
 };
 
-const runtime = createPlaybookRuntime({
-  coderLlm: 'claude-opus-4-8[1m]',
-  reviewerLlm: 'gpt-5.5',
-});
+const runtime = createPlaybookRuntime({});
 
 const playbookSessionId = randomUUID();
 await runtime.init({
@@ -114,6 +147,8 @@ await runtime.init({
   playbookId: 'review',
   rootSessionId: playbookSessionId,
   depth: 0,
+  roleBindings,
+  playerSessions,
   ports,
 });
 await runtime.handleBossInput({
@@ -125,23 +160,34 @@ await runtime.dispose();
 
 ## Sessions and traces
 
-Every init-to-dispose lifecycle is one playbook session. Its
+Every init-to-dispose lifecycle is one playbook session. Schema-3
 `playbook.trace` telemetry carries that immutable ID plus a contiguous
-sequence across exact Boss input, judge/player calls, FSM transitions,
-visible Captain work, nested playbook calls, status, settlement, and
-disposal. Without `PlaybookSession.playerSessions`, a standalone runtime
-starts each player fresh and privately retains the latest opaque
-`resumeToken` its adapter returned.
-
-A composing host can instead supply a frame-local `PlayerSessionStore`
-view over one root-owned continuation map. The host maps each local role
-to its effective binding, so a nested exact same-name role selects and
-updates the ancestor conversation while an unmatched child role gets
-its own binding. Child return or disposal does not clear the root's
-token, and a new root engagement starts fresh. Trace data and tokens
-never enter Boss-visible status text. Because trace observers do receive
-opaque resume tokens, persisted traces should be protected as sensitive
-data.
+sequence across exact Boss input, judge/player calls, FSM transitions, visible
+Captain work, nested playbook calls, status, settlement, and disposal. A
+shell-hosted player boundary keeps both identities: `roleId` says which local
+workflow job made the call, while `playerId` says which stable session
+conversation owned it. A standalone runtime retains the role without
+inventing host player identity.
+
+Without `PlaybookSession.playerSessions`, a standalone runtime starts each
+local role fresh and privately retains the latest opaque `resumeToken` its
+adapter returned. A composing host instead supplies a frame-local
+`PlayerSessionStore` view over one Captain-session ledger and explicit
+`roleBindings`. The store's methods receive local role IDs; the view resolves
+them to the configured stable player IDs. Equal IDs share one token and
+sequential call lane across every frame that names them, while distinct IDs
+remain isolated. Child return, frame disposal, and a later root engagement do
+not clear the session ledger.
+
+Runtime snapshots are schema 3. Their `roleResumeTokens` projection remains
+role-local, while the composing shell's own schema-3 snapshot persists the
+stable player ledger and every frame's exact role bindings. Do not restore
+schema 1 or 2 by guessing identity. On a compatible restore, rebuild
+`promptIdentity` from the current model selection (or adapter for an explicit
+provider-default selection) so the next prompt and trace describe the current
+invocation rather than stale machine state. Trace data and tokens never enter
+Boss-visible status text. Because trace observers do receive opaque resume
+tokens, persisted traces should be protected as sensitive data.
 
 See
 [`code.playbook.test.ts`](../reference/sdlc/code.playbook/code.playbook.test.ts)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "7.0.0",
+  "version": "8.0.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, and DECIDE workflows driven by GEARS specs.",
   "license": "Apache-2.0",
@@ -69,6 +69,7 @@
     "reference/sdlc/code.playbook/bin/playbook.js",
     "reference/sdlc/code.playbook/bin/launch-config.js",
     "reference/sdlc/code.playbook/bin/run.js",
+    "reference/sdlc/code.playbook/bin/interactive-session.js",
     "reference/sdlc/code.playbook/bin/session-store.js",
     "reference/sdlc/code.playbook/bin/provision.js",
     "reference/sdlc/code.playbook/bin/adapter-sdk.js",
@@ -142,7 +143,7 @@
   },
   "scripts": {
     "build": "tsc",
-    "test": "spex lint && vitest run",
+    "test": "spex lint && vitest run --exclude src/cligent-release-capabilities.test.ts && vitest run src/cligent-release-capabilities.test.ts",
     "test:acceptance": "vitest run --config vitest.acceptance.config.ts",
     "smoke:release": "node scripts/release-smoke.mjs",
     "check:links": "node scripts/check-links.mjs",
@@ -153,7 +154,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@sublang/cligent": "^0.19.0",
+    "@sublang/cligent": "^0.22.0",
     "@sublang/spex": "^2.1.1",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",

package/reference/sdlc/captain.playbook/captain.playbook.js

@@ -31,7 +31,7 @@
 //                deterministic entry mapping, the controller captain-call
 //                strategy with its single corrective re-ask (CAPPLAY-18),
 //                controller-port submission, and status formatting.
-// Compat:        spec.compat = { artifactSchema: 1, runtimeAbi: 1 }
+// Compat:        spec.compat = { artifactSchema: 2, runtimeAbi: 1 }
 //                (DR-022; checked at construction by the loading engine).
 import { createXStatePlaybookRuntime, defaultComposeCaptainPrompt, normalizeError, normalizeErrorCompact, parseJudgeJson, snapshotJsonValue, RUNTIME_ABI, } from '../../../src/xstate-runtime.js';
 import { captainMachine, } from './captain.fsm.js';
@@ -516,11 +516,11 @@ export const _internal = {
 // describe/apply control surface — lives in @sublang/playbook/xstate-runtime.
 const runtimeSpec = {
     label: 'CAPTAIN',
-    compat: { artifactSchema: 1, runtimeAbi: RUNTIME_ABI },
+    compat: { artifactSchema: 2, runtimeAbi: RUNTIME_ABI },
     snapshotOptions: snapshotCaptainOptions,
     machineInput: (options) => ({ enabledPlaybooks: options.enabledPlaybooks }),
     classifyBossText: (text, ports, signal, snapshotOrState, boundary, options) => classifyControllerTurn(text, ports, signal, snapshotOrState, boundary, options),
-    playerStates: {},
+    roleStates: {},
     classificationStatus: () => undefined,
     captainStrategy: controllerCaptainStrategy,
     // CAPPLAY-10 / PBRT-52: the Captain's own ControlView context projection —

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

@@ -31,7 +31,7 @@
 //                deterministic entry mapping, the controller captain-call
 //                strategy with its single corrective re-ask (CAPPLAY-18),
 //                controller-port submission, and status formatting.
-// Compat:        spec.compat = { artifactSchema: 1, runtimeAbi: 1 }
+// Compat:        spec.compat = { artifactSchema: 2, runtimeAbi: 1 }
 //                (DR-022; checked at construction by the loading engine).
 
 import {
@@ -798,7 +798,7 @@ export const _internal = {
 // describe/apply control surface — lives in @sublang/playbook/xstate-runtime.
 const runtimeSpec: XStatePlaybookRuntimeSpec<ValidatedCaptainOptions> = {
   label: 'CAPTAIN',
-  compat: { artifactSchema: 1, runtimeAbi: RUNTIME_ABI },
+  compat: { artifactSchema: 2, runtimeAbi: RUNTIME_ABI },
   snapshotOptions: snapshotCaptainOptions,
   machineInput: (options) => ({ enabledPlaybooks: options.enabledPlaybooks }),
   classifyBossText: (text, ports, signal, snapshotOrState, boundary, options) =>
@@ -810,7 +810,7 @@ const runtimeSpec: XStatePlaybookRuntimeSpec<ValidatedCaptainOptions> = {
       boundary,
       options,
     ) as Promise<import('xstate').EventObject | undefined>,
-  playerStates: {},
+  roleStates: {},
   classificationStatus: () => undefined,
   captainStrategy: controllerCaptainStrategy,
   // CAPPLAY-10 / PBRT-52: the Captain's own ControlView context projection —

package/reference/sdlc/code.md

@@ -4,7 +4,7 @@
 
 # Code
 
-Players:
+Roles:
 
 - Coder