@sublang/playbook 0.8.0 → 1.0.0

package/src/runtime.ts

@@ -10,24 +10,222 @@
 
 export interface PlayerResult {
   status: 'ok' | 'aborted' | 'error';
+  resumeToken?: string;
   finalText?: string;
   error?: string;
 }
 
+export interface PlayerCallOptions {
+  resume: string | false;
+}
+
+export interface CaptainCallOptions {
+  visibility: 'visible' | 'hidden';
+  resume: string | false;
+  allowedTools?: readonly string[];
+}
+
+export interface CaptainResult {
+  status: 'ok' | 'aborted' | 'error';
+  finalText?: string;
+  error?: string;
+}
+
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+export interface NormalizedError {
+  name: string;
+  message: string;
+  stack?: string;
+}
+
+export type PlaybookStateValue =
+  | string
+  | { readonly [key: string]: PlaybookStateValue };
+
+export interface PlaybookState {
+  value: PlaybookStateValue;
+  activeStateIds: readonly string[];
+  tags: readonly string[];
+  status: 'active' | 'done' | 'error' | 'stopped';
+  quiescent: boolean;
+  stateId?: string;
+}
+
+export interface PlaybookPendingCall {
+  callId: string;
+  playbookId: string;
+  childSessionId: string;
+}
+
+export interface PlaybookCallRequest {
+  callId: string;
+  playbookId: string;
+  text: string;
+}
+
+export type PlaybookCallResult =
+  | {
+      status: 'ok';
+      playbookId: string;
+      childSessionId: string;
+      state?: PlaybookState;
+      output?: JsonValue;
+    }
+  | {
+      status: 'aborted';
+      playbookId: string;
+      childSessionId?: string;
+      state?: PlaybookState;
+      error?: NormalizedError;
+    }
+  | {
+      status: 'error';
+      playbookId: string;
+      childSessionId?: string;
+      state?: PlaybookState;
+      error: NormalizedError;
+    };
+
+export type PlaybookCallStart =
+  | { state: 'settled'; result: PlaybookCallResult }
+  | { state: 'suspended'; childSessionId: string };
+
+export type PlaybookRunResult =
+  | { outcome: 'quiescent' | 'no-action'; state: PlaybookState }
+  | {
+      outcome: 'failed' | 'aborted';
+      state: PlaybookState;
+      error?: NormalizedError;
+    }
+  | {
+      outcome: 'terminal';
+      state: PlaybookState;
+      output?: JsonValue;
+    }
+  | {
+      outcome: 'suspended';
+      state: PlaybookState;
+      pendingCall: PlaybookPendingCall;
+    };
+
 export interface PlaybookPorts {
   callPlayer(
     playerId: string,
     prompt: string,
     signal: AbortSignal,
+    options: PlayerCallOptions,
   ): Promise<PlayerResult>;
+  callCaptain(
+    prompt: string,
+    signal: AbortSignal,
+    options: CaptainCallOptions,
+  ): Promise<CaptainResult>;
   callJudge(prompt: string, signal: AbortSignal): Promise<string>;
+  callPlaybook(
+    request: PlaybookCallRequest,
+    signal: AbortSignal,
+  ): Promise<PlaybookCallStart>;
   emitStatus(message: string, data?: unknown): Promise<void>;
   emitTelemetry(event: { topic: string; payload: unknown }): Promise<void>;
 }
 
+export interface PlaybookSession {
+  sessionId: string;
+  playbookId: string;
+  rootSessionId: string;
+  parentSessionId?: string;
+  parentCallId?: string;
+  depth: number;
+  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 interface PlaybookTraceEvent {
+  schemaVersion: 2;
+  sessionId: string;
+  playbookId: string;
+  rootSessionId: string;
+  parentSessionId?: string;
+  parentCallId?: string;
+  depth: number;
+  sequence: number;
+  timestamp: number;
+  type: PlaybookTraceType;
+  turnId?: number;
+  callId?: string;
+  payload: JsonValue;
+}
+
+export interface PlaybookPendingBossQuestion {
+  questionId: string;
+  player: string;
+  question: string;
+  sourceItem?: string;
+}
+
+// DR-014 §1: JSON-safe capture of a parked session. `machine` is the
+// XState persisted snapshot and is opaque to hosts; the pending Boss
+// questions are first-class so a host can surface what was asked
+// without parsing status lines or telemetry.
+export interface PlaybookRuntimeSnapshot {
+  schemaVersion: 1;
+  playbookId: string;
+  machine: JsonValue;
+  playerResumeTokens: { readonly [playerId: string]: string };
+  sequences: {
+    trace: number;
+    turn: number;
+    judgeCall: number;
+    playerCall: number;
+    playbookCall: number;
+  };
+  state: PlaybookState;
+  pendingBossQuestions: readonly PlaybookPendingBossQuestion[];
+}
+
 export interface PlaybookRuntime {
-  init(ports: PlaybookPorts): Promise<void>;
-  handleBossInput(turn: { text: string; signal: AbortSignal }): Promise<void>;
+  init(session: PlaybookSession): Promise<void>;
+  // DR-014 §1 optional durable-session capability: a runtime implements
+  // both members or neither. `exportSnapshot` returns undefined outside
+  // a safe capture point (parked quiescence between public boundaries);
+  // `restore` is an alternative to `init` that rehydrates the exported
+  // snapshot under the same immutable session identity.
+  exportSnapshot?(): PlaybookRuntimeSnapshot | undefined;
+  restore?(
+    session: PlaybookSession,
+    snapshot: PlaybookRuntimeSnapshot,
+  ): Promise<void>;
+  handleBossInput(turn: {
+    text: string;
+    signal: AbortSignal;
+  }): Promise<PlaybookRunResult>;
+  resumePlaybookCall(input: {
+    callId: string;
+    result: PlaybookCallResult;
+    signal: AbortSignal;
+  }): Promise<PlaybookRunResult>;
   dispose(): Promise<void>;
 }
 

package/src/xstate-runtime.d.ts

@@ -0,0 +1,94 @@
+import { type AnyActorRef, type PromiseActorLogic, type SnapshotFrom } from 'xstate';
+import type { CaptainResult, JsonValue, NormalizedError, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookPendingCall, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlayerResult } from './runtime.js';
+/**
+ * Compose invocation-lifetime and imperative-boundary cancellation without
+ * installing a second forwarding listener in each generated runtime.
+ */
+export declare function combineAbortSignals(...signals: readonly (AbortSignal | undefined)[]): AbortSignal;
+/**
+ * Register host cleanup started synchronously by an invocation abort.
+ * The nested bridge drains these promises before it publishes the matching
+ * call-finish boundary, without widening the public six-port contract.
+ */
+export declare function registerPlaybookAbortCleanup(signal: AbortSignal, cleanup: Promise<unknown>): void;
+/** Reject values that would be changed, omitted, or rejected by JSON. */
+export declare function assertJsonSafe(value: unknown, path?: string, ancestors?: ReadonlySet<object>): asserts value is JsonValue;
+/** Validate, detach, and recursively freeze host-owned JSON input. */
+export declare function snapshotJsonValue(value: unknown, path?: string): JsonValue;
+/** Validate session causality and detach its immutable identity from the host. */
+export declare function snapshotPlaybookSession(session: PlaybookSession): PlaybookSession;
+export declare function normalizeError(error: unknown): NormalizedError;
+export interface PlaybookStateMetadata {
+    stateId: string;
+    description: string;
+}
+/** Read stable state identity without consulting XState's private `_nodes`. */
+export declare function activePlaybookStateMetadata(snapshot: unknown): readonly PlaybookStateMetadata[];
+export interface SnapshotNormalizationOptions {
+    pendingCall?: PlaybookPendingCall;
+}
+export declare function normalizePlaybookSnapshot(snapshot: unknown, options?: SnapshotNormalizationOptions): PlaybookState;
+export declare function detachPersistedMachineSnapshot(persisted: unknown): JsonValue;
+export declare function assertPlaybookRuntimeSnapshot(value: unknown, expectedPlaybookId: string): PlaybookRuntimeSnapshot;
+export interface NestedPlaybookInput {
+    stateId: string;
+    playbookId: string;
+    text: string;
+}
+export interface PlaybookCallStarted {
+    callId: string;
+    stateId: string;
+    playbookId: string;
+    text: string;
+}
+export interface PlaybookCallFinished extends PlaybookCallStarted {
+    result: PlaybookCallResult;
+}
+export interface NestedPlaybookBridgeOptions {
+    nextCallId(): string;
+    /** Active public runtime boundary whose abort also owns a new child call. */
+    getBoundarySignal?(): AbortSignal | undefined;
+    callPlaybook(request: PlaybookCallRequest, signal: AbortSignal): Promise<PlaybookCallStart>;
+    emitStarted(event: PlaybookCallStarted): Promise<void>;
+    emitFinished(event: PlaybookCallFinished): Promise<void>;
+    drain(): Promise<void>;
+    bindResumeSignal?(signal: AbortSignal): void;
+    onControlPlaneError?(error: unknown): void;
+    onBackgroundError?(error: unknown): void;
+}
+export declare class NestedPlaybookCallError extends Error {
+    readonly result: PlaybookCallResult;
+    constructor(result: PlaybookCallResult);
+}
+export interface PendingCallObserver {
+    getPendingCall(): PlaybookPendingCall | undefined;
+    subscribePendingCall(listener: (pendingCall: PlaybookPendingCall) => void): () => void;
+}
+export interface NestedPlaybookBridge<TInput extends NestedPlaybookInput = NestedPlaybookInput> extends PendingCallObserver {
+    actorLogic: PromiseActorLogic<JsonValue | undefined, TInput>;
+    resume(input: {
+        callId: string;
+        result: PlaybookCallResult;
+        signal: AbortSignal;
+    }): Promise<void>;
+    abortPending(error?: unknown): Promise<void>;
+    dispose(): Promise<void>;
+}
+/** Validate, detach, and freeze a host direct-Captain result. */
+export declare function validateCaptainResult(value: unknown, path?: string): CaptainResult;
+/** Validate, detach, and freeze a host delegated-player result. */
+export declare function validatePlayerResult(value: unknown, path?: string): PlayerResult;
+export declare function validatePlaybookCallResult(result: unknown, expectedPlaybookId: string, expectedChildSessionId?: string): PlaybookCallResult;
+export declare function validatePlaybookCallStart(start: unknown, expectedPlaybookId: string): PlaybookCallStart;
+export declare function createNestedPlaybookBridge<TInput extends NestedPlaybookInput = NestedPlaybookInput>(options: NestedPlaybookBridgeOptions): NestedPlaybookBridge<TInput>;
+export interface WaitForPlaybookQuiescenceOptions {
+    signal?: AbortSignal;
+    timeout?: number;
+    pendingCalls?: PendingCallObserver;
+}
+/**
+ * Wait at the imperative runtime boundary; workflow waiting remains in XState.
+ * A pending-call notification covers the case where the suspended state was
+ * entered before its host returned the child session id.
+ */
+export declare function waitForPlaybookQuiescence<TActorRef extends AnyActorRef>(actor: TActorRef, options?: WaitForPlaybookQuiescenceOptions): Promise<SnapshotFrom<TActorRef>>;