@sublang/playbook 0.1.0

package/code.playbook.js

@@ -0,0 +1,598 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+//
+// Generated by slc/link.md (FSM-to-Runtime linker).
+// Source FSM:    ./code.fsm.ts
+// Player bind:   Coder→coder, Reviewer→reviewer,
+//                Committer→{coder per CODE-18/19} (CODE-19 wires both
+//                coderPlayer and reviewerPlayer; Coder wins as the
+//                alias's first alternative)
+// Boss event:    slash-prefix (LLM-classifier fallback)
+// Adjudication:  LLM-judge per state
+import { createActor, fromPromise } from 'xstate';
+import { codingMachine, } from './code.fsm.js';
+import { enumerateCaptainStates } from './code.fsm.introspect.js';
+// Internal capabilities (DR-004 §10). Each ships with its final
+// signature; behavior lands in the per-capability task noted by the
+// TODO marker.
+// Player-prompt composer — DR-004 §6.
+// Substitutes the three placeholder tokens in `input.prompt` (literal
+// string replace, no escaping) and prepends labelled blocks for any
+// populated structured field. The FSM's prompt body is never re-flowed.
+function composePlayerPrompt(input) {
+    const blocks = [];
+    if (input.intent !== undefined) {
+        blocks.push(`Boss intent:\n${input.intent}`);
+    }
+    if (input.reviews !== undefined) {
+        blocks.push(`Review items:\n${input.reviews}`);
+    }
+    if (input.challenges !== undefined) {
+        blocks.push(`Rebuttals:\n${input.challenges}`);
+    }
+    if (input.taskDescription !== undefined) {
+        blocks.push(`Task description:\n${input.taskDescription}`);
+    }
+    let body = input.prompt;
+    if (input.irNumber !== undefined) {
+        body = body.replaceAll('<#>', input.irNumber);
+    }
+    if (input.coderPlayer !== undefined) {
+        body = body.replaceAll('<coder-llm>', input.coderPlayer);
+    }
+    if (input.reviewerPlayer !== undefined) {
+        body = body.replaceAll('<reviewer-llm>', input.reviewerPlayer);
+    }
+    blocks.push(body);
+    return blocks.join('\n\n');
+}
+// Player-id resolver — DR-004 §2.
+// Non-composite: Coder→'coder', Reviewer→'reviewer'. The composite
+// Committer (= Coder | Reviewer per code.gears.md) resolves per
+// populated <playerName>Player field on `CaptainInput`: prefer
+// `coderPlayer` (CODE-18 wires only coderPlayer; CODE-19 wires both
+// so coderPlayer still wins as the alias's first alternative), fall
+// back to `reviewerPlayer` only if a future gear ships a
+// reviewer-only Committer item, and finally to the alias's first
+// alternative (Coder) when neither is set.
+function resolvePlayerId(input) {
+    switch (input.player) {
+        case 'Coder':
+            return 'coder';
+        case 'Reviewer':
+            return 'reviewer';
+        case 'Committer':
+            if (input.coderPlayer !== undefined)
+                return 'coder';
+            if (input.reviewerPlayer !== undefined)
+                return 'reviewer';
+            return 'coder';
+        default: {
+            const exhaustive = input.player;
+            throw new Error(`resolvePlayerId: unknown player ${String(exhaustive)}`);
+        }
+    }
+}
+// LLM judge — DR-004 §4. Builds a prompt that lists each declared
+// outcome verbatim, asks ports.callJudge for a JSON
+// `{ guard, …payloadFields }` response, and returns the parsed
+// object once the chosen guard is one of the input.result keys.
+// Adjudicator failures (malformed JSON, missing/unknown guard) are
+// control-plane errors and propagate via throw per slc/link.md.
+async function adjudicate(input, finalText, ports, signal) {
+    const prompt = buildJudgePrompt(input, finalText);
+    const raw = await ports.callJudge(prompt, signal);
+    const parsed = parseJudgeJson(raw);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('adjudicate: judge response is not a JSON object');
+    }
+    const obj = parsed;
+    const guard = obj.guard;
+    if (typeof guard !== 'string') {
+        throw new Error('adjudicate: judge response missing string "guard" field');
+    }
+    if (!Object.prototype.hasOwnProperty.call(input.result, guard)) {
+        throw new Error(`adjudicate: unknown guard "${guard}" — declared guards: ${Object.keys(input.result).join(', ')}`);
+    }
+    // Per slc/link.md, a missing payload field the state's `result`
+    // description requires is a control-plane error. The FSM names
+    // required fields with the literal phrase
+    //   Output shall include `<fieldName>: <...>`
+    // so we extract those tokens and require each to be a string in
+    // the judge response.
+    for (const field of extractRequiredFields(input.result[guard])) {
+        if (typeof obj[field] !== 'string') {
+            throw new Error(`adjudicate: judge response missing required field "${field}" for guard "${guard}"`);
+        }
+    }
+    return obj;
+}
+function extractRequiredFields(description) {
+    const fields = [];
+    const re = /Output shall include `([A-Za-z_][A-Za-z0-9_]*):/g;
+    for (const m of description.matchAll(re)) {
+        fields.push(m[1]);
+    }
+    return fields;
+}
+function buildJudgePrompt(input, finalText) {
+    const lines = [];
+    lines.push(`The ${input.player} just produced this output:`);
+    lines.push('');
+    lines.push('```');
+    lines.push(finalText);
+    lines.push('```');
+    lines.push('');
+    lines.push('Pick exactly one outcome by `guard` and return JSON ' +
+        '`{ guard, …payloadFields }`. Required payload fields are ' +
+        'named in the outcome description.');
+    lines.push('');
+    for (const [key, description] of Object.entries(input.result)) {
+        lines.push(`- \`${key}\` — ${description}`);
+    }
+    return lines.join('\n');
+}
+function parseJudgeJson(raw) {
+    let text = raw.trim();
+    const fence = text.match(/^```(?:json)?\s*\n?([\s\S]*?)\n?```$/);
+    if (fence)
+        text = fence[1].trim();
+    try {
+        return JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`adjudicate: judge response is not valid JSON: ${e.message}`);
+    }
+}
+// Boss-event classifier — DR-004 §3.
+// Slash forms tried first; unknown slash forms surface as
+// emitStatus and return undefined per slc/link.md ("Unknown
+// commands surface as emitStatus, not as a silently-dropped
+// turn"). Anything that isn't a slash form falls through to the
+// LLM classifier via ports.callJudge with a fixed prompt that
+// names the four event types and their payload shapes.
+async function classifyBossText(text, ports, signal) {
+    const trimmed = text.trim();
+    if (trimmed === '')
+        return undefined;
+    if (trimmed === '/start' || trimmed.startsWith('/start ')) {
+        return { type: 'START_CODING', intent: trimmed.slice('/start'.length).trim() };
+    }
+    if (trimmed === '/continue' || trimmed.startsWith('/continue ')) {
+        return {
+            type: 'CONTINUE_IR',
+            irNumber: trimmed.slice('/continue'.length).trim(),
+        };
+    }
+    if (trimmed === '/summarize' || trimmed.startsWith('/summarize ')) {
+        return {
+            type: 'SUMMARIZE_IR',
+            irNumber: trimmed.slice('/summarize'.length).trim(),
+        };
+    }
+    if (trimmed === '/interrupt' || trimmed.startsWith('/interrupt ')) {
+        return parseInterruptSlash(trimmed, ports);
+    }
+    if (trimmed.startsWith('/')) {
+        const cmd = trimmed.split(/\s+/)[0];
+        await ports.emitStatus(`Unknown slash command: ${cmd}`);
+        return undefined;
+    }
+    return classifyWithLlm(trimmed, ports, signal);
+}
+async function parseInterruptSlash(trimmed, ports) {
+    const rest = trimmed.slice('/interrupt'.length).trim();
+    if (rest === '') {
+        await ports.emitStatus('/interrupt requires a stateId');
+        return undefined;
+    }
+    const firstSpace = rest.search(/\s/);
+    const targetId = firstSpace === -1 ? rest : rest.slice(0, firstSpace);
+    const intent = firstSpace === -1 ? '' : rest.slice(firstSpace).trim();
+    return {
+        type: 'BOSS_INTERRUPT',
+        targetId: targetId,
+        ...(intent ? { intent } : {}),
+    };
+}
+async function classifyWithLlm(text, ports, signal) {
+    const prompt = buildClassifierPrompt(text);
+    const raw = await ports.callJudge(prompt, signal);
+    const parsed = parseJudgeJson(raw);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        await ports.emitStatus('Classifier returned a non-object JSON response');
+        return undefined;
+    }
+    const obj = parsed;
+    const eventType = obj.event;
+    if (typeof eventType !== 'string') {
+        await ports.emitStatus('Classifier did not name an event type');
+        return undefined;
+    }
+    const payload = typeof obj.payload === 'object' &&
+        obj.payload !== null &&
+        !Array.isArray(obj.payload)
+        ? obj.payload
+        : {};
+    switch (eventType) {
+        case 'START_CODING': {
+            if (typeof payload.intent !== 'string') {
+                await ports.emitStatus('Classifier omitted intent for START_CODING');
+                return undefined;
+            }
+            return { type: 'START_CODING', intent: payload.intent };
+        }
+        case 'CONTINUE_IR': {
+            if (typeof payload.irNumber !== 'string') {
+                await ports.emitStatus('Classifier omitted irNumber for CONTINUE_IR');
+                return undefined;
+            }
+            return { type: 'CONTINUE_IR', irNumber: payload.irNumber };
+        }
+        case 'SUMMARIZE_IR': {
+            if (typeof payload.irNumber !== 'string') {
+                await ports.emitStatus('Classifier omitted irNumber for SUMMARIZE_IR');
+                return undefined;
+            }
+            return { type: 'SUMMARIZE_IR', irNumber: payload.irNumber };
+        }
+        case 'BOSS_INTERRUPT': {
+            if (typeof payload.targetId !== 'string') {
+                await ports.emitStatus('Classifier omitted targetId for BOSS_INTERRUPT');
+                return undefined;
+            }
+            return {
+                type: 'BOSS_INTERRUPT',
+                targetId: payload.targetId,
+                ...(typeof payload.intent === 'string'
+                    ? { intent: payload.intent }
+                    : {}),
+                ...(typeof payload.irNumber === 'string'
+                    ? { irNumber: payload.irNumber }
+                    : {}),
+            };
+        }
+        default:
+            await ports.emitStatus(`Classifier returned unknown event type: ${eventType}`);
+            return undefined;
+    }
+}
+function buildClassifierPrompt(text) {
+    return [
+        'Classify the following Boss message into exactly one of these events.',
+        'Respond with JSON: { "event": "<TYPE>", "payload": { ...fields } }.',
+        '',
+        'Events:',
+        '- START_CODING: payload { intent: "<free-form goal>" }',
+        '- CONTINUE_IR: payload { irNumber: "<number>" }',
+        '- SUMMARIZE_IR: payload { irNumber: "<number>" }',
+        '- BOSS_INTERRUPT: payload { targetId: "<stateId>", intent?: "<free-form goal>", irNumber?: "<number>" }',
+        '',
+        'Boss message:',
+        '```',
+        text,
+        '```',
+    ].join('\n');
+}
+// Captain-actor bridge — DR-004 §7. One PromiseActorLogic that the
+// codingMachine invokes from every captain-invoking state. Per turn:
+// resolve playerId, compose the player prompt, await
+// ports.callPlayer, adjudicate the finalText. PlayerResult status of
+// 'aborted' or 'error' throws so XState routes via onError → #failed
+// (the single fail-stop sink for both Captain errors and player
+// failures).
+//
+// `getActiveSignal` is the runtime's hook for flowing the Boss's
+// `handleBossInput.signal` into the host port calls — fromPromise
+// hands the bridge XState's actor-scoped signal, which only fires
+// on actor.stop(), not on Boss abort. When omitted (e.g. direct
+// captainBridge tests), the bridge falls back to XState's signal.
+function captainBridge(ports, getActiveSignal) {
+    return fromPromise(async ({ input, signal }) => {
+        const activeSignal = getActiveSignal?.() ?? signal;
+        const playerId = resolvePlayerId(input);
+        const prompt = composePlayerPrompt(input);
+        const result = await ports.callPlayer(playerId, prompt, activeSignal);
+        if (result.status !== 'ok') {
+            throw new Error(result.error ??
+                `captainBridge: callPlayer status "${result.status}"`);
+        }
+        if (result.finalText === undefined) {
+            throw new Error('captainBridge: callPlayer returned status=ok with no finalText');
+        }
+        return adjudicate(input, result.finalText, ports, activeSignal);
+    });
+}
+// Captain pane display — PBRT-3 / PBRT-14.
+// The Captain pane is a stream keyed on four glyphs so a reader can
+// parse each line at a glance:
+//   ◆  terminal entry (ready / done / failed)
+//   ▸  Boss input echo
+//   ⮕  captain-invoking state entry (label + player + CODE-N)
+//   ⤷  transition (guard fired by the just-finished captain call)
+// Prompts and full player output ride the player panes; the Captain
+// pane keeps to the state-machine shape.
+const STATE_LABELS = {
+    planAndImplement: 'plan & implement',
+    respondToReview: 'respond to review',
+    continueIr: 'continue IR task',
+    summarizeSpecs: 'summarize IR into specs',
+    reviewBossCommitSpecs: 'review Boss-intent commit (specs only)',
+    reviewBossCommitCode: 'review Boss-intent commit (code only)',
+    reviewBossCommitMixed: 'review Boss-intent commit (specs + code)',
+    reviewIrTaskCommitSpecs: 'review IR-task commit (specs only)',
+    reviewIrTaskCommitCode: 'review IR-task commit (code only)',
+    reviewIrTaskCommitMixed: 'review IR-task commit (specs + code)',
+    reviewChangesSpecs: 'review uncommitted edits (specs only)',
+    reviewChangesCode: 'review uncommitted edits (code only)',
+    reviewChangesMixed: 'review uncommitted edits (specs + code)',
+    reviewChangesAndChallengesSpecs: 'review uncommitted edits + rebuttals (specs only)',
+    reviewChangesAndChallengesCode: 'review uncommitted edits + rebuttals (code only)',
+    reviewChangesAndChallengesMixed: 'review uncommitted edits + rebuttals (specs + code)',
+    adjudicateChallenges: 'adjudicate rebuttals',
+    commitCoderInitial: "commit Coder's initial changes",
+    commitJoint: 'commit reviewed changes',
+};
+const stateMetadata = (() => {
+    const m = new Map();
+    for (const s of enumerateCaptainStates(codingMachine)) {
+        const label = STATE_LABELS[s.stateId];
+        if (!label) {
+            throw new Error(`code.playbook.ts: STATE_LABELS missing entry for captain-invoking state '${s.stateId}'`);
+        }
+        const input = s.getInput({});
+        m.set(s.stateId, { player: input.player, sourceItem: s.sourceItem, label });
+    }
+    return m;
+})();
+const TERMINAL_STATES = new Set([
+    'ready',
+    'done',
+    'failed',
+]);
+// Captain-pane surface (PBRT-3): every captain-invoking state plus
+// the three terminal/idle states. Wider than the prior
+// "Boss-relevant" set per slc/link.md's default "emit on every
+// transition; let the host filter."
+const CAPTAIN_PANE_STATES = new Set([
+    ...stateMetadata.keys(),
+    ...TERMINAL_STATES,
+]);
+function formatStateEntry(stateId) {
+    if (TERMINAL_STATES.has(stateId))
+        return `◆ ${stateId}`;
+    const meta = stateMetadata.get(stateId);
+    if (!meta)
+        return `⮕ ${stateId}`;
+    return `⮕ ${meta.label}  ${meta.player} per ${meta.sourceItem}`;
+}
+function formatTransition(event) {
+    const output = event?.output;
+    if (!output || typeof output.guard !== 'string')
+        return undefined;
+    const tallies = [];
+    for (const field of ['reviews', 'challenges']) {
+        const value = output[field];
+        if (typeof value === 'string' && value.trim().length > 0) {
+            const items = value.match(/^\s*\d+\.\s/gm);
+            tallies.push(`${field}=${items ? items.length : 1}`);
+        }
+    }
+    const suffix = tallies.length > 0 ? `  ${tallies.join(' ')}` : '';
+    return `⤷ ${output.guard}${suffix}`;
+}
+function formatBossEcho(text, eventType) {
+    return eventType !== undefined
+        ? `▸ BOSS  ${text}  → ${eventType}`
+        : `▸ BOSS  ${text}`;
+}
+// Rider fields PBRT-14 names — surfaced inline on a state entry
+// whenever the FSM context populates them, regardless of which
+// captain-invoking state is being entered. Routing-only context
+// (reviewSubject, afterReview, etc.) stays out of the pane and is
+// visible via emitTelemetry instead.
+const RIDER_FIELDS = ['intent', 'irNumber', 'taskDescription'];
+function formatRiders(context) {
+    const parts = [];
+    for (const f of RIDER_FIELDS) {
+        const v = context[f];
+        if (typeof v === 'string' && v.length > 0) {
+            parts.push(`${f}=${JSON.stringify(v)}`);
+        }
+    }
+    return parts.length > 0 ? `  ${parts.join(' ')}` : '';
+}
+// Internal export surface for tests. Not part of the stable public API;
+// the leading underscore signals "subject to change." Each member is
+// referenced here so `noUnusedLocals` stays clean while later tasks
+// wire the factory body to use them.
+export const _internal = {
+    composePlayerPrompt,
+    resolvePlayerId,
+    adjudicate,
+    classifyBossText,
+    captainBridge,
+    STATE_LABELS,
+    stateMetadata,
+    formatStateEntry,
+    formatTransition,
+    formatBossEcho,
+    formatRiders,
+};
+export default function createPlaybookRuntime(options) {
+    let actor;
+    let savedPorts;
+    // The Boss's per-turn AbortSignal, surfaced to captainBridge so
+    // ports.callPlayer / callJudge see the right cancellation source.
+    // null between turns; set by handleBossInput.
+    let activeSignal;
+    // Previous root-machine state for the inspect-driven telemetry /
+    // status emitter. undefined before the first inspect firing.
+    let priorState;
+    // Emission queue. slc/link.md says emissions "shall be ordered,
+    // awaited, and never-dropped"; subscribe/inspect callbacks are
+    // synchronous and can't await, so each emit is enqueued and a
+    // single drainer processes them sequentially.
+    const emitQueue = [];
+    let drainer;
+    function enqueueEmit(fn) {
+        emitQueue.push(fn);
+        if (!drainer) {
+            drainer = (async () => {
+                while (emitQueue.length > 0) {
+                    try {
+                        await emitQueue.shift()();
+                    }
+                    catch {
+                        // Suppress host-side emission errors; the control plane
+                        // surfaces real failures via handleBossInput throws.
+                    }
+                }
+                drainer = undefined;
+            })();
+        }
+    }
+    function drainEmissions() {
+        return drainer ?? Promise.resolve();
+    }
+    function buildActor(ports) {
+        priorState = undefined;
+        return createActor(codingMachine.provide({
+            actors: { captain: captainBridge(ports, () => activeSignal) },
+        }), {
+            input: options,
+            inspect: (inspectionEvent) => {
+                if (inspectionEvent.type !== '@xstate.snapshot')
+                    return;
+                const snap = inspectionEvent.snapshot;
+                // Filter out captain sub-actor (fromPromise) snapshots —
+                // only the root codingMachine snapshot has a string value.
+                if (typeof snap.value !== 'string')
+                    return;
+                const to = snap.value;
+                if (priorState === to)
+                    return;
+                const from = priorState;
+                priorState = to;
+                // Telemetry on every transition (PBRT-14).
+                enqueueEmit(() => ports.emitTelemetry({
+                    topic: 'playbook.fsm.state',
+                    payload: { from, to, event: inspectionEvent.event },
+                }));
+                // Captain pane (PBRT-3 / PBRT-14): show the transition
+                // guard first (when this is an actor-done transition with
+                // a known guard), then the new state entry, then any
+                // context riders the entering state cares about. Terminal
+                // entry to `failed` carries `lastError` as the data arg.
+                if (!CAPTAIN_PANE_STATES.has(to))
+                    return;
+                const transitionLine = formatTransition(inspectionEvent.event);
+                if (transitionLine !== undefined) {
+                    enqueueEmit(() => ports.emitStatus(transitionLine));
+                }
+                const entryLine = formatStateEntry(to);
+                const riderSuffix = stateMetadata.has(to)
+                    ? formatRiders(snap.context ?? {})
+                    : '';
+                const message = entryLine + riderSuffix;
+                if (to === 'failed') {
+                    const lastError = snap.context
+                        ?.lastError;
+                    enqueueEmit(() => ports.emitStatus(message, { lastError }));
+                }
+                else {
+                    enqueueEmit(() => ports.emitStatus(message));
+                }
+            },
+        });
+    }
+    const runtime = {
+        async init(ports) {
+            savedPorts = ports;
+            actor = buildActor(ports);
+            actor.start();
+            await drainEmissions();
+        },
+        async handleBossInput({ text, signal, }) {
+            if (!actor || !savedPorts) {
+                throw new Error('createPlaybookRuntime.handleBossInput: init must be called first');
+            }
+            activeSignal = signal;
+            try {
+                // 1. Classify text into an FSM event (slash → event; else LLM).
+                const event = await classifyBossText(text, savedPorts, signal);
+                // Unknown slash or empty input — classifier already surfaced
+                // status; nothing to send.
+                if (event === undefined) {
+                    await drainEmissions();
+                    return;
+                }
+                // 2. Captain-pane Boss-input echo (PBRT-14): the verbatim
+                //    Boss text and the FSM event it classified to, before
+                //    the FSM advances. Enqueued so it interleaves cleanly
+                //    with the inspect-driven transition emissions.
+                const echoPorts = savedPorts;
+                enqueueEmit(() => echoPorts.emitStatus(formatBossEcho(text, event.type)));
+                // 3. final state ('done') cannot accept new events — dispose
+                //    and reconstruct per DR-004 §5.
+                if (actor.getSnapshot().status === 'done') {
+                    actor.stop();
+                    actor = buildActor(savedPorts);
+                    actor.start();
+                }
+                // 4. Send the event.
+                actor.send(event);
+                // 5. Drive to quiescence. On signal-abort we take no FSM
+                //    action: the captain bridge's awaited callPlayer rejects
+                //    naturally, the bridge throws, XState routes through
+                //    onError → #failed, and this loop sees the quiescent
+                //    snapshot and returns (DR-004 §8 natural rejection).
+                await driveToQuiescence(actor);
+                // Drain transition emissions before returning so the Boss
+                // sees the final status line for this turn.
+                await drainEmissions();
+            }
+            finally {
+                activeSignal = undefined;
+            }
+        },
+        async dispose() {
+            if (actor) {
+                actor.stop();
+                actor = undefined;
+            }
+            // Drain any in-flight emissions per slc/link.md §Session
+            // lifecycle ("stop the actor and drain pending port emissions").
+            await drainEmissions();
+            savedPorts = undefined;
+        },
+        // @internal — test-only escape hatch for inspecting the
+        // underlying actor's snapshot. Most state assertions are now
+        // expressible via the recorded emitStatus / emitTelemetry
+        // calls (DR-004 §9); the hatch stays for the few cases where
+        // direct context inspection is clearer (e.g., the dispose
+        // teardown test).
+        _getActor() {
+            return actor;
+        },
+    };
+    return runtime;
+}
+function driveToQuiescence(actor) {
+    return new Promise((resolve) => {
+        if (isQuiescent(actor.getSnapshot())) {
+            resolve();
+            return;
+        }
+        const sub = actor.subscribe((snap) => {
+            if (isQuiescent(snap)) {
+                sub.unsubscribe();
+                resolve();
+            }
+        });
+    });
+}
+function isQuiescent(snap) {
+    const v = snap.value;
+    return v === 'ready' || v === 'failed' || v === 'done';
+}