@sublang/playbook 4.0.0 → 6.0.0

package/slc/text2gears.md

@@ -65,6 +65,20 @@ Those requirements remain in the item's condition or `Results:` metadata.
 Adding control-oriented prompt lines merely to restate them changes the
 Boss-visible contract and is nonconformant.
 
+### Authored prompt fragments
+
+Source may compose one acting prompt from authored Markdown instruction blocks and runtime context that it explicitly says to relay in quotes (`>`).
+A fenced `markdown` block introduced as an instruction or prompt is an authored static prompt fragment: its fence delimiters are Source syntax, while every interior line and blank line is prompt content preserved after documented Markdown unescaping.
+
+An instruction fence and a relayed-context fragment that apply to one behavior shall appear in the target blockquote in their Source order.
+Distinct non-empty fragments shall be separated by one blank prompt line unless Source explicitly supplies a different boundary.
+text2gears shall not move a shared instruction ahead of behavior-specific context, move quoted evidence after an instruction that Source says follows the evidence, or otherwise regroup fragments for convenience.
+
+Where Source says that a runtime value is relayed in quotes, the leading `>` is prompt content rather than Source-only blockquote syntax.
+If Source supplies a blockquoted template for that relay, text2gears shall keep one literal leading `>` on every quoted line; the target GEARS line therefore uses its outer blockquote marker followed by the literal marker, such as `> > Coder output: <coder-output>`.
+If Source names the relayed value but supplies no template, text2gears shall emit its canonical typed placeholder on a line beginning with literal `> ` and shall not summarize, paraphrase, or invent a value in its place.
+An ordinary Source blockquote that specifies a complete acting prompt without requiring quoted relay retains the existing rule above: its one leading marker is Source syntax and is not prompt content.
+
 Source statements that assign active-leaf routing, call identity, suspension,
 or return matching to the host describe execution preconditions rather than
 behaviors for Captain to perform. text2gears shall use such a statement only as
@@ -139,6 +153,11 @@ A single-outcome producer then declares exactly one bullet naming the
 property; this consumed-output case is the sole one in which a
 single-outcome behavior carries a `Results:` label.
 
+Where a later prompt relays a delegated player's whole final response as quoted context, the producer shall declare that property in the exact annotated form `` `<field>: <verbatim final text>` ``.
+The annotation makes the field runtime-owned: the adjudicator selects the result guard, while the linked runtime carries the player's canonical final text into that field instead of asking a judge to reproduce it.
+A distinct typed field extracted from that response remains judge-authored even when a later prompt quotes its exact value; quoting a field does not turn it into the player's whole final response.
+One property name shall not be annotated as verbatim in one result contract and judge-authored in another; text2gears shall choose distinct properties or report that the Source cannot be represented by the current contract.
+
 Result metadata is compiler control data, not part of the acting agent's
 prompt.
 text2gears shall not put guard names, result-property schema, JSON control
@@ -202,11 +221,11 @@ next phase cannot compile.
 Example:
 
 ```markdown
-### DISCUSS-1
+### DECIDE-1
 
 Parallel group: initial-proposals
 
-When Boss gives a topic, Captain shall prompt Host:
+When Boss gives a topic, Captain shall prompt Coder:
 
 > Propose your design independently.
 ```
@@ -306,6 +325,7 @@ Prompts shall carry the specification's normative requirements as instructions t
 
 Source snippets may overlap or duplicate.
 When composing them into a spec item, text2gears shall deduplicate identical prompt lines.
+It shall not deduplicate across distinct authored fragments when doing so would erase a fragment boundary or change the Source-ordered prompt.
 
 Each spec item addresses one state behavior and carries its full final prompt (the static part).
 Cross-item duplication is acceptable: spec items are compiled artifacts; Source is what users maintain.

package/src/runtime.d.ts

@@ -7,6 +7,12 @@ export interface PlayerResult {
 export interface PlayerCallOptions {
     resume: string | false;
 }
+export interface PlayerSessionStore {
+    select(playerId: string): string | false;
+    update(playerId: string, resumeToken?: string): void;
+    snapshot(): Readonly<Record<string, string>>;
+    restore(tokens: Readonly<Record<string, string>>): void;
+}
 export interface CaptainCallOptions {
     visibility: 'visible' | 'hidden';
     resume: string | false;
@@ -106,9 +112,10 @@ export interface PlaybookSession {
     parentSessionId?: string;
     parentCallId?: string;
     depth: number;
+    playerSessions?: PlayerSessionStore;
     ports: PlaybookPorts;
 }
-export type PlaybookTraceType = 'session.started' | 'boss.input.received' | 'judge.call.started' | 'judge.call.finished' | 'player.call.started' | 'player.call.finished' | 'captain.call.started' | 'captain.call.finished' | 'playbook.call.started' | 'playbook.call.finished' | 'fsm.transition' | 'status.emitted' | 'boss.input.settled' | 'session.disposed';
+export type PlaybookTraceType = 'session.started' | 'boss.input.received' | 'judge.call.started' | 'judge.call.finished' | 'player.call.started' | 'player.call.finished' | 'captain.call.started' | 'captain.call.finished' | 'playbook.call.started' | 'playbook.call.finished' | 'apply.started' | 'apply.finished' | 'fsm.transition' | 'status.emitted' | 'boss.input.settled' | 'session.disposed';
 export interface PlaybookTraceEvent {
     schemaVersion: 2;
     sessionId: string;
@@ -148,10 +155,38 @@ export interface PlaybookRuntimeSnapshot {
     state: PlaybookState;
     pendingBossQuestions: readonly PlaybookPendingBossQuestion[];
 }
+export interface PlaybookControlAction {
+    id: string;
+    label: string;
+}
+export interface PlaybookControlView {
+    state: PlaybookState;
+    stateDescription?: string;
+    context?: JsonValue;
+    pendingQuestions: readonly PlaybookPendingBossQuestion[];
+    lastError?: NormalizedError;
+    actions: readonly PlaybookControlAction[];
+}
+export type PlaybookControlReceipt = {
+    disposition: 'rejected';
+    reason: string;
+} | {
+    disposition: 'executed';
+    run: PlaybookRunResult;
+} | {
+    disposition: 'failed';
+    error: NormalizedError;
+};
 export interface PlaybookRuntime {
     init(session: PlaybookSession): Promise<void>;
     exportSnapshot?(): PlaybookRuntimeSnapshot | undefined;
     restore?(session: PlaybookSession, snapshot: PlaybookRuntimeSnapshot): Promise<void>;
+    describe?(): PlaybookControlView;
+    apply?(input: {
+        actionId: string;
+        key: string;
+        signal: AbortSignal;
+    }): Promise<PlaybookControlReceipt>;
     handleBossInput(turn: {
         text: string;
         signal: AbortSignal;

package/src/runtime.ts

@@ -19,6 +19,17 @@ export interface PlayerCallOptions {
   resume: string | false;
 }
 
+// DR-030: a composing host may supply one frame-local view of the root
+// engagement's player continuation. The runtime selects through this store
+// before tracing/calling and updates it from the validated result. Hosts that
+// omit it retain the runtime's private per-session store.
+export interface PlayerSessionStore {
+  select(playerId: string): string | false;
+  update(playerId: string, resumeToken?: string): void;
+  snapshot(): Readonly<Record<string, string>>;
+  restore(tokens: Readonly<Record<string, string>>): void;
+}
+
 export interface CaptainCallOptions {
   visibility: 'visible' | 'hidden';
   resume: string | false;
@@ -143,6 +154,7 @@ export interface PlaybookSession {
   parentSessionId?: string;
   parentCallId?: string;
   depth: number;
+  playerSessions?: PlayerSessionStore;
   ports: PlaybookPorts;
 }
 
@@ -157,6 +169,8 @@ export type PlaybookTraceType =
   | 'captain.call.finished'
   | 'playbook.call.started'
   | 'playbook.call.finished'
+  | 'apply.started'
+  | 'apply.finished'
   | 'fsm.transition'
   | 'status.emitted'
   | 'boss.input.settled'
@@ -206,6 +220,38 @@ export interface PlaybookRuntimeSnapshot {
   pendingBossQuestions: readonly PlaybookPendingBossQuestion[];
 }
 
+// DR-029: one currently valid, runtime-advertised control action. The id
+// is stable within the returned view; the label is runtime-written,
+// Boss-appropriate text derived from source state descriptions.
+export interface PlaybookControlAction {
+  id: string;
+  label: string;
+}
+
+// DR-029: the sanitized control view `describe()` returns — current
+// state and the runtime-written description of what that state means,
+// the authored context projection, pending Boss questions, the last
+// recorded error, and the currently valid actions. `stateDescription` is
+// the Boss-appropriate grounding a host may speak from; the state id is
+// internal and is absent from it whenever the runtime's source declares
+// no description for the state it is in.
+export interface PlaybookControlView {
+  state: PlaybookState;
+  stateDescription?: string;
+  context?: JsonValue;
+  pendingQuestions: readonly PlaybookPendingBossQuestion[];
+  lastError?: NormalizedError;
+  actions: readonly PlaybookControlAction[];
+}
+
+// DR-029: the receipt `apply()` returns says which of three things
+// happened — rejected before any effect, executed with the settled run
+// result, or failed after effects may exist.
+export type PlaybookControlReceipt =
+  | { disposition: 'rejected'; reason: string }
+  | { disposition: 'executed'; run: PlaybookRunResult }
+  | { disposition: 'failed'; error: NormalizedError };
+
 export interface PlaybookRuntime {
   init(session: PlaybookSession): Promise<void>;
   // DR-014 §1 optional durable-session capability: a runtime implements
@@ -218,6 +264,19 @@ export interface PlaybookRuntime {
     session: PlaybookSession,
     snapshot: PlaybookRuntimeSnapshot,
   ): Promise<void>;
+  // DR-029 optional control-surface capability: a runtime implements
+  // both members or neither. `describe` is side-effect free and valid at
+  // parked quiescence outside an active boundary; `apply` revalidates the
+  // named action against the live state, executes it at most once per
+  // idempotency key within that runtime instance, and returns a receipt. A
+  // runtime lacking the pair advertises no actions; plain text delivery is
+  // the only verb against it.
+  describe?(): PlaybookControlView;
+  apply?(input: {
+    actionId: string;
+    key: string;
+    signal: AbortSignal;
+  }): Promise<PlaybookControlReceipt>;
   handleBossInput(turn: {
     text: string;
     signal: AbortSignal;

package/src/xstate-playbook-runtime.d.ts

@@ -48,12 +48,30 @@ export type JudgePurpose = 'boss-input-classification' | 'player-output-adjudica
 export interface RuntimeBoundaryCalls {
     callPlayer(input: PlaybookPlayerInput, playerId: string, prompt: string, signal: AbortSignal): Promise<PlayerResult>;
     callJudge(purpose: JudgePurpose, stateId: string | undefined, prompt: string, signal: AbortSignal): Promise<string>;
-    callCaptain?(input: PlaybookCaptainInput, prompt: string, signal: AbortSignal): Promise<CaptainResult>;
+    callCaptain?(input: PlaybookCaptainInput, prompt: string, signal: AbortSignal, callOptions?: XStateCaptainCallOptions): Promise<CaptainResult>;
+}
+/**
+ * Presentation selection for one traced direct-Captain call
+ * (slc/link.md §Captain adjudication). `'visible'` (the default) is the
+ * workflow form: the port receives `{ visibility: 'visible', resume: false }`
+ * and the trace pair carries both members. `'hidden'` is the controller form
+ * (DR-029): the port receives `{ visibility: 'hidden', resume: false }`
+ * while the host's session-Captain wrapper owns the actual durable-conversation
+ * resume selection, so the trace pair carries `visibility: 'hidden'` and no
+ * `resume` member — the pinned token never enters runtime telemetry.
+ */
+export interface XStateCaptainCallOptions {
+    visibility?: 'visible' | 'hidden';
 }
 export interface ScheduledStatus {
     message: string;
     data?: JsonValue;
 }
+/** Boss-facing identity for one FSM state whose invoked actor is `player`. */
+export interface XStatePlayerStateStatus {
+    player: string;
+    label: string;
+}
 export interface XStateBossEventFieldSpec {
     /** The judge supplies routing data; the runtime supplies exact Boss text. */
     source: 'judge' | 'text';
@@ -81,6 +99,46 @@ export interface XStatePlaybookRuntimeCompat {
     /** The engine ABI the artifact was linked against. */
     runtimeAbi: number;
 }
+/**
+ * One direct-Captain actor invocation handed to a spec's `captainStrategy`
+ * (slc/link.md §Captain adjudication, controller form). The engine owns
+ * signal combination, emission draining, trace pairing, the shared
+ * Captain/judge lane, and control-plane latching; the strategy owns the
+ * playbook-specific call pipeline — e.g. the controller's hidden decision
+ * call, `{ action, … }` control-JSON validation with its single corrective
+ * re-ask, and controller-port submission.
+ */
+export interface XStateCaptainStrategyRun<TOptions> {
+    input: PlaybookCaptainInput;
+    /** The prompt composed by the spec's Captain composer for `input`. */
+    prompt: string;
+    /** Combined invocation-lifetime + active-boundary abort signal. */
+    signal: AbortSignal;
+    /** The immutable validated runtime options. */
+    options: TOptions;
+    /** The bound immutable playbook session identity. */
+    session: PlaybookSession;
+    /**
+     * One traced Captain call through the shared serialized lane; every call —
+     * initial or corrective — emits its own paired `captain.call.started` /
+     * `captain.call.finished` boundary. Throws the boundary's authoritative
+     * failure for non-`ok` and empty-`ok` results exactly as the default
+     * pipeline does.
+     */
+    callCaptain(prompt: string, callOptions?: XStateCaptainCallOptions): Promise<CaptainResult>;
+    /**
+     * DR-028: true when `error` is the boundary's re-askable empty-`ok`
+     * marker; the strategy may re-issue the same composed call exactly once.
+     */
+    isEmptyOkRetry(error: unknown): boolean;
+    /**
+     * Mark `error` as a recoverable FSM-result failure: it travels the invoked
+     * actor's XState `onError` path without being latched as a control-plane
+     * error, so the machine's authored recovery arms can route it.
+     */
+    recoverableFailure<E extends Error>(error: E): E;
+}
+export type XStateCaptainStrategy<TOptions> = (run: XStateCaptainStrategyRun<TOptions>) => Promise<PlaybookActorOutput>;
 export interface XStatePlaybookRuntimeSpec<TOptions> {
     /** Diagnostic label used in internal invariant errors. Default 'playbook'. */
     label?: string;
@@ -112,10 +170,22 @@ export interface XStatePlaybookRuntimeSpec<TOptions> {
      * the XState machine alone.
      */
     bossEvents?: readonly XStateBossEventSpec[];
-    /** Boss-input classifier override; default: generic parked-state classifier. */
-    classifyBossText?: (text: string, ports: PlaybookPorts, signal: AbortSignal, snapshotOrState: unknown, boundary?: RuntimeBoundaryCalls) => Promise<EventObject | undefined>;
-    /** Status line emitted after classification names an event. Default: none. */
+    /** Boss-input classifier override; default: generic parked-state classifier. Receives the bound validated options last so a fully deterministic controller mapping can consult host-supplied option members (slc/link.md §Boss-event mapping). */
+    classifyBossText?: (text: string, ports: PlaybookPorts, signal: AbortSignal, snapshotOrState: unknown, boundary?: RuntimeBoundaryCalls, options?: TOptions) => Promise<EventObject | undefined>;
+    /**
+     * Direct-Captain actor strategy override (slc/link.md §Captain
+     * adjudication, controller form): replaces the default visible-call +
+     * hidden-judge pipeline for every `captain` state of this machine. The
+     * engine still composes the prompt, combines signals, traces each call as
+     * its own pair, and latches control-plane errors; failures the strategy
+     * marks with `recoverableFailure` travel the actor's `onError` path as
+     * recoverable FSM-result failures instead.
+     */
+    captainStrategy?: XStateCaptainStrategy<TOptions>;
+    /** Status line emitted after classification; canonical metadata defaults to the event type, legacy artifacts to none. */
     classificationStatus?: (event: EventObject) => string | undefined;
+    /** Complete FSM-derived Boss-facing metadata for every `player` state; its presence selects the canonical status profile. */
+    playerStates?: Readonly<Record<string, XStatePlayerStateStatus>>;
     /** Map a player-invoking state's input to the host player id. Default: lowercased player name. */
     resolvePlayerId?: (input: PlaybookPlayerInput, options: TOptions) => string;
     /** Compose the player prompt. Default: continuation blocks + `<field>` placeholder substitution. */
@@ -130,9 +200,21 @@ export interface XStatePlaybookRuntimeSpec<TOptions> {
     extractRequiredFields?: (description: string) => string[];
     /** Required fields carried verbatim from the player's finalText instead of judge JSON. Default: none. */
     verbatimPayloadFields?: ReadonlySet<string>;
+    /**
+     * DR-029 / PBRT-52: the runtime-authored ControlView context
+     * projection — the exact FSM context members `describe()` may expose,
+     * in the order the view lists them. Only this artifact knows which of
+     * its context members are safe and relevant for a controller prompt, so
+     * the engine exports what is named here and nothing else: a member the
+     * artifact has not named stays private, and a member added to the FSM
+     * later stays private until someone names it. Absent or empty: the view
+     * carries no context at all. `pendingBossQuestion` and `lastError` are
+     * surfaced first-class by the view and shall not be named here.
+     */
+    controlContextFields?: readonly string[];
     /** States that may suspend for a Boss reply. Default: targets of the FSM's `awaitBossReply` BOSS_REPLY transitions. */
     resumableStateIds?: ReadonlySet<string>;
-    /** Human status lines for a root transition. Default: entry lines with question/failure surfacing. */
+    /** Human status lines for a root transition. Default: guard, declared-player, question, and failure lines. */
     statusesForState?: (state: PlaybookState, context: Record<string, unknown>, event: unknown) => readonly ScheduledStatus[];
     /** Detached JSON-safe transition-event descriptor. Default: `type` + `transitionEventFields` strings + validated output + normalized error. */
     normalizeTransitionEvent?: (event: unknown) => JsonValue | undefined;
@@ -215,6 +297,12 @@ export declare function defaultBuildCaptainJudgePrompt(input: {
 }, finalText: string): string;
 /** Targets of the FSM's `awaitBossReply` BOSS_REPLY transitions. */
 export declare function resumableStateIdsFromMachine(machine: AnyStateMachine): ReadonlySet<string>;
+/**
+ * Source state descriptions by state key, node id, and `meta.playbook`
+ * state id, read from `machine.config`. Control actions are labeled from
+ * these descriptions (DR-029); a state without one has no entry.
+ */
+export declare function stateDescriptionsFromMachine(machine: AnyStateMachine): ReadonlyMap<string, string>;
 /**
  * Build a `PlaybookRuntimeFactory` that interprets the given FSM artifact
  * under the slc/link.md contract. The factory provides every actor kind the
@@ -222,7 +310,8 @@ export declare function resumableStateIdsFromMachine(machine: AnyStateMachine):
  * (literal and dynamic) — and implements the full runtime lifecycle including
  * the optional parked-session snapshot capability (DR-014).
  *
- * Scope: single-region root machines (each snapshot exposes exactly one
- * playbook state id). Parallel-region FSMs keep their own linked runtimes.
+ * Scope: machines that declare no parallel state (each snapshot exposes
+ * exactly one playbook state id). Parallel-region FSMs keep their own linked
+ * runtimes.
  */
 export declare function createXStatePlaybookRuntime<TOptions>(machine: AnyStateMachine, spec: XStatePlaybookRuntimeSpec<TOptions>): PlaybookRuntimeFactory<TOptions>;