@sublang/playbook 0.4.2 → 0.6.0

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

@@ -4,8 +4,10 @@
 // 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
+//                Committer→ configured committerPlayer alias when set
+//                (per-run remapping via options — PBRT-8); else the
+//                baked CODE-18/19 fallback (coder-first: CODE-19 wires
+//                both coderPlayer and reviewerPlayer, Coder wins as the
 //                alias's first alternative)
 // Boss event:    free-text judge classification
 // Adjudication:  LLM-judge per state
@@ -16,6 +18,65 @@ const BOSS_REPLY_ERRORS = {
     missingQuestion: "needsBossReply outcome missing 'question' field",
     unregisteredState: (stateId) => `state ${stateId} declared needsBossReply but is not registered as resumable`,
 };
+// Required-payload fields whose value is the player's verbatim long-form
+// prose. The runtime carries `finalText.trim()` into these fields rather
+// than asking the judge to round-trip the text through JSON. Short
+// extracted fields (`question`, `taskDescription`, `irNumber`, …) stay
+// judge-extracted — they are not in this set.
+const VERBATIM_PAYLOAD_FIELDS = new Set([
+    'reviews',
+    'challenges',
+]);
+// Normalize an unknown error value to the compact `{ name, message }`
+// shape used by Captain-pane / status emissions. Returns `undefined`
+// for nullish input so callers can omit absent errors.
+function normalizeErrorCompact(err) {
+    if (err === undefined || err === null)
+        return undefined;
+    if (err instanceof Error) {
+        return { name: err.name, message: err.message };
+    }
+    if (typeof err === 'object') {
+        const o = err;
+        if (typeof o.message === 'string') {
+            return {
+                name: typeof o.name === 'string' ? o.name : 'Error',
+                message: o.message,
+            };
+        }
+    }
+    return { name: 'Error', message: String(err) };
+}
+// Normalize an unknown error value to the full `{ name, message, stack }`
+// shape used by telemetry emissions. Returns `undefined` for nullish
+// input. `stack` is omitted when not available on the source value.
+function normalizeErrorFull(err) {
+    const compact = normalizeErrorCompact(err);
+    if (compact === undefined)
+        return undefined;
+    if (err instanceof Error) {
+        return err.stack !== undefined ? { ...compact, stack: err.stack } : compact;
+    }
+    if (typeof err === 'object' && err !== null) {
+        const stack = err.stack;
+        if (typeof stack === 'string') {
+            return { ...compact, stack };
+        }
+    }
+    return compact;
+}
+// Normalize any `error` field inside a telemetry event so failed
+// transitions don't leak raw Error instances through the channel.
+function normalizeEventForTelemetry(event) {
+    if (event === null || typeof event !== 'object' || Array.isArray(event)) {
+        return event;
+    }
+    const e = event;
+    if (!('error' in e))
+        return event;
+    const normalized = normalizeErrorFull(e.error);
+    return { ...e, error: normalized };
+}
 // Internal capabilities (DR-004 §10). Each ships with its final
 // signature; behavior lands in the per-capability task noted by the
 // TODO marker.
@@ -63,15 +124,21 @@ function composePlayerPrompt(input) {
     }
     return blocks.join('\n\n');
 }
-// Player-id resolver — DR-004 §2.
+// Player-id resolver — DR-004 §2 / PBRT-8.
 // 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.
+// Committer (= Coder | Reviewer per code.gears.md) resolves to the
+// configured alias when present: `input.committerPlayer`, the
+// validated `captain.options.code.committer` (PBRT-8 / PBRT-30),
+// already a baked player id ('coder' / 'reviewer'). Absent a
+// configured alias it falls back to the DR-004 §2 baked binding by
+// populated <playerName>Player field: 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. The alias selects only the host pane; it is not a PBRT-4
+// identity string, so it leaves <coder-llm> / <reviewer-llm>
+// untouched and `input.player` stays `Committer` (PLAYBOOK-3).
 function resolvePlayerId(input) {
     switch (input.player) {
         case 'Coder':
@@ -79,6 +146,8 @@ function resolvePlayerId(input) {
         case 'Reviewer':
             return 'reviewer';
         case 'Committer':
+            if (input.committerPlayer !== undefined)
+                return input.committerPlayer;
             if (input.coderPlayer !== undefined)
                 return 'coder';
             if (input.reviewerPlayer !== undefined)
@@ -116,8 +185,17 @@ async function adjudicate(input, finalText, ports, signal) {
     // 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.
+    // the judge response — except for VERBATIM_PAYLOAD_FIELDS
+    // (`reviews`, `challenges`), where the runtime substitutes
+    // `finalText.trim()` so the long-form prose is not round-tripped
+    // through judge JSON. Short extracted fields like `question` and
+    // `taskDescription` keep the existing extract-and-validate path.
+    const verbatim = finalText.trim();
     for (const field of extractRequiredFields(input.result[guard])) {
+        if (VERBATIM_PAYLOAD_FIELDS.has(field)) {
+            obj[field] = verbatim;
+            continue;
+        }
         if (typeof obj[field] !== 'string') {
             if (guard === 'needsBossReply' && field === 'question') {
                 throw new Error(BOSS_REPLY_ERRORS.missingQuestion);
@@ -145,24 +223,155 @@ function buildJudgePrompt(input, finalText) {
     lines.push('');
     lines.push('Pick exactly one outcome by `guard` and return JSON ' +
         '`{ guard, …payloadFields }`. Required payload fields are ' +
-        'named in the outcome description.');
+        'named in the outcome description. Do not copy long-form ' +
+        'verbatim fields (`reviews`, `challenges`) — the runtime ' +
+        "carries the player's output into those fields verbatim, " +
+        'so any value you supply for them will be overwritten.');
     lines.push('');
     for (const [key, description] of Object.entries(input.result)) {
         lines.push(`- \`${key}\` — ${description}`);
     }
     return lines.join('\n');
 }
+// Judge replies are meant to be a single JSON object, but LLMs
+// routinely wrap them in prose ("Here is the result: …"), Markdown
+// code fences, or trailing commentary, and occasionally emit a
+// trailing comma or truncate the tail (a dropped closing brace, an
+// unterminated string). parseJudgeJson is deliberately lenient: it
+// first tries a strict parse of the (optionally fenced) body, then
+// scans every `{`/`[` as a possible start in document order and
+// returns the first recoverable object. At each start it prefers a
+// strict balanced span and falls back to a repaired (trailing-comma /
+// truncation) span, so a damaged object earlier in the prose is not
+// overridden by a cleaner one later. Scanning every start (not just
+// the first bracket) keeps a bracketed fragment in surrounding prose —
+// e.g. an aside like `see [1]` or `{n/a}` before the real object —
+// from masking a later, genuinely valid object. Both callers
+// (classification and adjudication) expect an object, so plain objects
+// win over arrays/scalars; the first value of any shape is remembered
+// so a legitimately array/scalar reply still surfaces to the caller's
+// own object check. Only a reply from which no JSON value can be
+// recovered is treated as malformed and throws, preserving the
+// control-plane error contract (PBRT-7, PBRT-10).
 function parseJudgeJson(raw) {
-    let text = raw.trim();
-    const fence = text.match(/^```(?:json)?\s*\n?([\s\S]*?)\n?```$/);
-    if (fence)
-        text = fence[1].trim();
+    const fenced = stripCodeFence(raw.trim());
+    // Fast path: a well-formed (optionally fenced) JSON body.
     try {
-        return JSON.parse(text);
-    }
-    catch (e) {
-        throw new Error(`adjudicate: judge response is not valid JSON: ${e.message}`);
-    }
+        return JSON.parse(fenced);
+    }
+    catch {
+        // Fall through to lenient extraction + repair.
+    }
+    const starts = [];
+    for (let i = 0; i < fenced.length; i++) {
+        const ch = fenced[i];
+        if (ch === '{' || ch === '[')
+            starts.push(i);
+    }
+    // Walk starts in document order. At each start prefer a strict
+    // balanced span (most trustworthy) and fall back to a repaired one
+    // for a trailing-comma / truncated tail, so the earliest intended
+    // object wins even when it needs repair. Return the first plain
+    // object; remember the first value of any shape so a legitimately
+    // array/scalar reply still surfaces to the caller's own object check.
+    let firstValue;
+    for (const start of starts) {
+        let parsedHere;
+        for (const repair of [false, true]) {
+            const candidate = extractJsonValue(fenced, start, repair);
+            if (candidate === undefined)
+                continue;
+            try {
+                parsedHere = { value: JSON.parse(candidate) };
+            }
+            catch {
+                continue; // not parseable this way — try repair, then next start
+            }
+            break; // prefer the strict span at this start over its repair
+        }
+        if (parsedHere === undefined)
+            continue;
+        if (isPlainObject(parsedHere.value))
+            return parsedHere.value;
+        if (firstValue === undefined)
+            firstValue = parsedHere;
+    }
+    if (firstValue !== undefined)
+        return firstValue.value;
+    throw new Error('adjudicate: judge response is not valid JSON');
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// Strip a single Markdown code fence that wraps the whole string.
+function stripCodeFence(text) {
+    const fence = text.match(/^```(?:json)?\s*\n?([\s\S]*?)\n?```$/);
+    return fence ? fence[1].trim() : text;
+}
+// Scan from `start` (a `{`/`[` index), tracking string and
+// bracket-nesting state, and emit the balanced JSON value rooted
+// there. Anything after the top-level value closes is ignored (so a
+// trailing code fence or commentary does not matter). With
+// `repair === false` the span is returned only if it actually closes,
+// and trailing commas are left intact — so the caller can prefer a
+// cleanly-balanced span before attempting repair; if input ends
+// before the value closes, undefined is returned. With
+// `repair === true` common damage is fixed: a trailing comma before a
+// close is removed, an unterminated string is closed, and any
+// brackets still open at end-of-input are closed in order.
+function extractJsonValue(text, start, repair) {
+    const stack = [];
+    let out = '';
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            out += ch;
+            if (escaped)
+                escaped = false;
+            else if (ch === '\\')
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            out += ch;
+            continue;
+        }
+        if (ch === '{' || ch === '[') {
+            stack.push(ch === '{' ? '}' : ']');
+            out += ch;
+            continue;
+        }
+        if (ch === '}' || ch === ']') {
+            if (repair)
+                out = dropTrailingComma(out);
+            out += ch;
+            stack.pop();
+            if (stack.length === 0)
+                return out; // top-level value complete
+            continue;
+        }
+        out += ch;
+    }
+    // End of input before the top-level value closed.
+    if (!repair)
+        return undefined; // strict pass: no balanced span here
+    if (inString)
+        out += '"';
+    out = dropTrailingComma(out);
+    while (stack.length > 0)
+        out += stack.pop();
+    return out;
+}
+// Remove a trailing comma (and any whitespace after it) at the end of
+// the accumulated output, so `{"a":1,}` / `[1,2,]` and truncated
+// `{"a":1,` repair to valid JSON.
+function dropTrailingComma(out) {
+    return out.replace(/,(\s*)$/, '$1');
 }
 // Boss-event classifier — DR-004 §3.
 // Every non-empty Boss turn goes through ports.callJudge. Slash-prefixed
@@ -184,7 +393,18 @@ async function classifyWithLlm(text, ports, signal, snapshotOrState) {
     const state = classifierState(snapshotOrState);
     const prompt = buildClassifierPrompt(text, state);
     const raw = await ports.callJudge(prompt, signal);
-    const parsed = parseJudgeJson(raw);
+    let parsed;
+    try {
+        parsed = parseJudgeJson(raw);
+    }
+    catch {
+        // No JSON value could be recovered. Classification failures are
+        // non-fatal — unlike adjudication, which throws to the failure
+        // state (PBRT-10) — so surface one status and take no FSM action,
+        // consistent with the other invalid-reply paths below (PBRT-7).
+        await ports.emitStatus('Classifier reply was not recoverable JSON');
+        return undefined;
+    }
     if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
         await ports.emitStatus('Classifier returned a non-object JSON response');
         return undefined;
@@ -444,20 +664,31 @@ function pendingBossQuestionFromContext(context) {
         question: candidate.question,
     };
 }
-function questionExcerpt(question) {
-    return question.replace(/[\r\n]+/g, ' ').slice(0, 80);
+// PBRT-3 / PBRT-14: on entry to `awaitBossReply` the runtime surfaces
+// the pending player question as a captain-speech act attributed to the
+// asking player (`<player> asks: <full question>`), emitted with no
+// glyph so the host renders it as captain speech. The question is
+// carried verbatim and in full — the judge JSON that produced it rides
+// a hidden callCaptain (PBRT-15), so this line is the Boss's only
+// legible view of what was asked.
+function formatAwaitBossReplyQuestion(context) {
+    const pending = pendingBossQuestionFromContext(context);
+    const player = pending?.player ?? 'unknown';
+    const question = pending?.question ?? '';
+    return `${player} asks: ${question}`;
 }
-function formatAwaitBossReplyEntry(context) {
+// The rider-less routing marker emitted right after the question line.
+// It carries only the resume target, asking player, and source item;
+// the former `q="<first 80 chars>"` excerpt rider is dropped now that
+// the full question rides the captain-speech line above.
+function formatAwaitBossReplyMarker(context) {
     const pending = pendingBossQuestionFromContext(context);
     const resumeStateId = pending?.resumeStateId ?? 'unknown';
     const player = pending?.player ?? 'unknown';
     const sourceItem = pending?.sourceItem ?? 'unknown';
-    const question = questionExcerpt(pending?.question ?? '');
-    return `◆ awaiting Boss reply · ${resumeStateId} · ${player} · ${sourceItem} · q=${JSON.stringify(question)}`;
+    return `◆ awaiting Boss reply · ${resumeStateId} · ${player} · ${sourceItem}`;
 }
-function formatStateEntry(stateId, context = {}) {
-    if (stateId === 'awaitBossReply')
-        return formatAwaitBossReplyEntry(context);
+function formatStateEntry(stateId) {
     if (SUPPRESSED_ENTRY_STATES.has(stateId))
         return undefined;
     if (stateId === 'failed')
@@ -490,13 +721,23 @@ function formatClassification(eventType) {
     return eventType;
 }
 function stateTelemetryPayload(from, to, event, context) {
-    const payload = { from, to, event };
+    const payload = {
+        from,
+        to,
+        event: normalizeEventForTelemetry(event),
+    };
     if (to === 'awaitBossReply') {
         const pendingBossQuestion = pendingBossQuestionFromContext(context);
         if (pendingBossQuestion !== undefined) {
             payload.pendingBossQuestion = pendingBossQuestion;
         }
     }
+    if (to === 'failed') {
+        const lastError = normalizeErrorFull(context.lastError);
+        if (lastError !== undefined) {
+            payload.lastError = lastError;
+        }
+    }
     return payload;
 }
 // Internal export surface for tests. Not part of the stable public API;
@@ -512,11 +753,16 @@ export const _internal = {
     STATE_LABELS,
     stateMetadata,
     pendingBossQuestionFromContext,
-    formatAwaitBossReplyEntry,
+    formatAwaitBossReplyQuestion,
+    formatAwaitBossReplyMarker,
     formatStateEntry,
     formatTransition,
     formatClassification,
     stateTelemetryPayload,
+    normalizeErrorCompact,
+    normalizeErrorFull,
+    normalizeEventForTelemetry,
+    VERBATIM_PAYLOAD_FIELDS,
 };
 export default function createPlaybookRuntime(options) {
     let actor;
@@ -590,13 +836,25 @@ export default function createPlaybookRuntime(options) {
                 if (transitionLine !== undefined) {
                     enqueueEmit(() => ports.emitStatus(transitionLine));
                 }
-                const entryLine = formatStateEntry(to, context);
+                // awaitBossReply surfaces two lines per PBRT-3 / PBRT-14: the
+                // full player question as captain speech, then the rider-less
+                // routing marker. The full-question telemetry rides
+                // stateTelemetryPayload above.
+                if (to === 'awaitBossReply') {
+                    const questionLine = formatAwaitBossReplyQuestion(context);
+                    const markerLine = formatAwaitBossReplyMarker(context);
+                    enqueueEmit(() => ports.emitStatus(questionLine));
+                    enqueueEmit(() => ports.emitStatus(markerLine));
+                    return;
+                }
+                const entryLine = formatStateEntry(to);
                 if (entryLine === undefined)
                     return;
                 if (to === 'failed') {
                     const lastError = snap.context
                         ?.lastError;
-                    enqueueEmit(() => ports.emitStatus(entryLine, { lastError }));
+                    const data = { lastError: normalizeErrorCompact(lastError) };
+                    enqueueEmit(() => ports.emitStatus(entryLine, data));
                 }
                 else {
                     enqueueEmit(() => ports.emitStatus(entryLine));