@sublang/playbook 4.0.0 → 5.0.0

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

@@ -48,7 +48,20 @@ 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;
@@ -81,6 +94,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,8 +165,18 @@ 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>;
+    /** 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 names an event. Default: none. */
     classificationStatus?: (event: EventObject) => string | undefined;
     /** Map a player-invoking state's input to the host player id. Default: lowercased player name. */
@@ -130,6 +193,18 @@ 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. */
@@ -215,6 +290,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 +303,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>;