@sublang/playbook 12.3.0 → 13.1.0

package/src/runtime.d.ts

@@ -6,6 +6,8 @@ export interface PlayerResult {
 }
 export interface PlayerCallOptions {
     resume: string | false;
+    /** Complete task and clarification context if the host must start fresh. */
+    freshPrompt?: string;
 }
 export interface PlayerSessionStore {
     select(roleId: string): string | false;

package/src/runtime.ts

@@ -17,6 +17,8 @@ export interface PlayerResult {
 
 export interface PlayerCallOptions {
   resume: string | false;
+  /** Complete task and clarification context if the host must start fresh. */
+  freshPrompt?: string;
 }
 
 // DR-032: a composing host may supply one frame-local role view of the

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

@@ -329,7 +329,7 @@ interface XStatePlaybookRuntimeSpecBase<TOptions> {
     /** Complete FSM-derived Boss-facing metadata for every `player` state. */
     roleStates?: Readonly<Record<string, XStateRoleStateStatus>>;
     /** Compose the player prompt. Default: continuation blocks + `<field>` placeholder substitution. */
-    composePlayerPrompt?: (input: PlaybookPlayerInput, promptIdentity: XStatePromptIdentity) => string;
+    composePlayerPrompt?: (input: PlaybookPlayerInput, promptIdentity: XStatePromptIdentity, resuming?: boolean) => string;
     /** Compose the direct-Captain prompt. Default: continuation blocks + placeholder substitution with deterministic JSON rendering. */
     composeCaptainPrompt?: (input: PlaybookCaptainInput) => string;
     /** Linker-known exceptions to the default kebab-token → camel-field mapping. */
@@ -388,6 +388,8 @@ export declare function normalizeErrorFull(err: unknown): {
 } | undefined;
 /** Read the FSM context's single pending Boss question, when well-formed. */
 export declare function pendingBossQuestionFromContext(context: Record<string, unknown>): PlaybookPendingBossQuestionContext | undefined;
+/** Add clarification context without repeating the question in a live conversation. */
+export declare function composePlayerContinuation(input: Pick<PlaybookPlayerInput, 'pendingBossQuestion' | 'bossReply'>, body: string, resuming?: boolean): string;
 /**
  * Default player-prompt composer (slc/link.md §Player prompt composition).
  * One callback-based pass substitutes each `<fieldName>` placeholder whose
@@ -395,7 +397,7 @@ export declare function pendingBossQuestionFromContext(context: Record<string, u
  * placeholder-looking text inside a value is never re-substituted. The
  * continuation preamble and Q/A blocks precede the domain body on resume.
  */
-export declare function defaultComposePlayerPrompt(input: PlaybookPlayerInput, placeholderFields?: Readonly<Record<string, string>>): string;
+export declare function defaultComposePlayerPrompt(input: PlaybookPlayerInput, placeholderFields?: Readonly<Record<string, string>>, resuming?: boolean): string;
 /**
  * Default direct-Captain prompt composer (slc/link.md §Captain prompt
  * composition). Placeholder substitution is presence-based: string fields

package/src/xstate-playbook-runtime.js

@@ -402,17 +402,21 @@ export function pendingBossQuestionFromContext(context) {
 // ---------------------------------------------------------------------------
 // Generic strategy defaults.
 // ---------------------------------------------------------------------------
-const CONTINUATION_PREAMBLE = 'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.';
-function continuationBlocks(input) {
+const CONTINUATION_PREAMBLE = 'Continue the same task using Boss’s reply below.';
+function continuationBlocks(input, resuming = false) {
     if (input.pendingBossQuestion === undefined || input.bossReply === undefined) {
         return [];
     }
     return [
         CONTINUATION_PREAMBLE,
-        `Boss question:\n${input.pendingBossQuestion.question}`,
+        ...(resuming ? [] : [`Your previous question:\n${input.pendingBossQuestion.question}`]),
         `Boss reply:\n${input.bossReply}`,
     ];
 }
+/** Add clarification context without repeating the question in a live conversation. */
+export function composePlayerContinuation(input, body, resuming = false) {
+    return [...continuationBlocks(input, resuming), body].join('\n\n');
+}
 const PLACEHOLDER_PATTERN = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
 function placeholderFieldName(token, fields) {
     const explicit = fields[token];
@@ -429,15 +433,13 @@ function placeholderFieldName(token, fields) {
  * placeholder-looking text inside a value is never re-substituted. The
  * continuation preamble and Q/A blocks precede the domain body on resume.
  */
-export function defaultComposePlayerPrompt(input, placeholderFields = {}) {
-    const blocks = continuationBlocks(input);
+export function defaultComposePlayerPrompt(input, placeholderFields = {}, resuming = false) {
     const fields = input;
     const body = input.prompt.replace(PLACEHOLDER_PATTERN, (match, token) => {
         const value = fields[placeholderFieldName(token, placeholderFields)];
         return typeof value === 'string' ? value : match;
     });
-    blocks.push(body);
-    return blocks.join('\n\n');
+    return composePlayerContinuation(input, body, resuming);
 }
 function sortJson(value) {
     if (Array.isArray(value))
@@ -1901,7 +1903,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
         }
     }
     const composePlayerPrompt = spec.composePlayerPrompt ??
-        ((input) => defaultComposePlayerPrompt(input, spec.placeholderFields));
+        ((input, _identity, resuming = false) => defaultComposePlayerPrompt(input, spec.placeholderFields, resuming));
     const composeCaptainPrompt = spec.composeCaptainPrompt ??
         ((input) => defaultComposeCaptainPrompt(input, spec.placeholderFields));
     const extractFields = spec.extractRequiredFields ?? defaultExtractRequiredFields;
@@ -2522,7 +2524,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
             }
             return session?.roleBindings?.[roleId]?.promptIdentity ?? roleId;
         }
-        function composeBoundPlayerPrompt(input) {
+        function composeBoundPlayerPrompt(input, resuming = false) {
             let active = true;
             const lookup = (roleId) => {
                 if (!active) {
@@ -2531,7 +2533,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
                 return promptIdentity(roleId);
             };
             try {
-                return composePlayerPrompt(input, lookup);
+                return composePlayerPrompt(input, lookup, resuming);
             }
             finally {
                 active = false;
@@ -2847,7 +2849,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
             };
         }
         function detachedPlayerContinuation(roleId, playerId) {
-            return snapshotJsonValue(selectPlayerResume(roleId, playerId), `${label} deferred player continuation`);
+            return snapshotJsonValue({ v: 1, playerId: playerId ?? roleId }, `${label} deferred player continuation`);
         }
         function completionEvidenceFor(input, roleId, playerId, signal, operationId) {
             return async (completion) => {
@@ -3372,7 +3374,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
             failedGovernedAttemptId = attemptIds.values().next().value;
         }
         const boundary = {
-            async callPlayer(input, roleId, prompt, signal) {
+            async callPlayer(input, roleId, freshPrompt, signal) {
                 // State-entry telemetry/status must precede the call they describe.
                 await drainEmissions();
                 signal.throwIfAborted();
@@ -3399,6 +3401,8 @@ export function createXStatePlaybookRuntime(machine, spec) {
                         controlPlaneError ??= error;
                     throw error;
                 }
+                const prompt = selectedResume === false
+                    ? freshPrompt : composeBoundPlayerPrompt(input, true);
                 const callId = deferredContinuation?.effectBoundary.callId ??
                     `player-${++playerCallSequence}`;
                 const callIdentity = (resume) => ({
@@ -3427,7 +3431,8 @@ export function createXStatePlaybookRuntime(machine, spec) {
                 try {
                     const runTracedPlayerCall = async (resume = selectedResume) => {
                         const identity = callIdentity(resume);
-                        await emitCallStarted('player.call.started', 'player.call.finished', { ...identity, prompt }, position, signal);
+                        const callPrompt = resume === false ? freshPrompt : prompt;
+                        await emitCallStarted('player.call.started', 'player.call.finished', { ...identity, prompt: callPrompt }, position, signal);
                         let rawResult;
                         try {
                             // An abort may land while the awaited started emission drains
@@ -3435,7 +3440,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
                             // never start after abort, so settle the already-started pair
                             // as `aborted` through the catch below.
                             signal.throwIfAborted();
-                            rawResult = await requireHostPorts().callPlayer(roleId, prompt, signal, { resume });
+                            rawResult = await requireHostPorts().callPlayer(roleId, callPrompt, signal, { resume, ...(callPrompt === freshPrompt ? {} : { freshPrompt }) });
                             // A host promise is not required to honor cancellation. Do not
                             // let a late result mutate continuity or publish a successful
                             // finish.
@@ -4979,6 +4984,15 @@ export function createXStatePlaybookRuntime(machine, spec) {
                 throw new Error(`${label} deferred continuation requires repository.runDeferred`);
             }
             const effectBoundary = continuationBoundarySeed(operation, turnId);
+            const boundPlayerId = resolvedPlayerId(effectBoundary.roleId);
+            const validateBinding = (value) => {
+                if (!isPlainObject(value) || Object.keys(value).length !== 2 ||
+                    value.v !== 1 ||
+                    value.playerId !== (boundPlayerId ?? effectBoundary.roleId)) {
+                    throw new TypeError(`${label} bound deferred player continuation is invalid`);
+                }
+            };
+            validateBinding(operation.playerContinuation);
             const continuation = {
                 operationId: operation.operationId,
                 effectBoundary,
@@ -5004,18 +5018,8 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     operationId: operation.operationId,
                     effectBoundary,
                     operation: async ({ playerContinuation }) => {
-                        const selectedContinuation = retainedEffectSourceSessionId === undefined
-                            ? playerContinuation
-                            : selectPlayerResume(effectBoundary.roleId, resolvedPlayerId(effectBoundary.roleId));
-                        if (selectedContinuation !== false &&
-                            (typeof selectedContinuation !== 'string' ||
-                                selectedContinuation.trim().length === 0)) {
-                            throw new TypeError(`${label} bound deferred player continuation is invalid`);
-                        }
-                        // Retained adoption owns a fresh Captain-session player ledger;
-                        // no source token becomes target ownership. Same-engagement
-                        // continuation still uses the exact durable binding.
-                        continuation.playerContinuation = selectedContinuation;
+                        validateBinding(playerContinuation);
+                        continuation.playerContinuation = selectPlayerResume(effectBoundary.roleId, boundPlayerId);
                         continuationStarted = true;
                         actor.send(event);
                         // The host has durably started this boundary and the FSM has

package/src/xstate-playbook-runtime.ts

@@ -776,6 +776,7 @@ interface XStatePlaybookRuntimeSpecBase<TOptions> {
   composePlayerPrompt?: (
     input: PlaybookPlayerInput,
     promptIdentity: XStatePromptIdentity,
+    resuming?: boolean,
   ) => string;
   /** Compose the direct-Captain prompt. Default: continuation blocks + placeholder substitution with deterministic JSON rendering. */
   composeCaptainPrompt?: (input: PlaybookCaptainInput) => string;
@@ -1064,22 +1065,31 @@ export function pendingBossQuestionFromContext(
 // ---------------------------------------------------------------------------
 
 const CONTINUATION_PREAMBLE =
-  'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.';
+  'Continue the same task using Boss’s reply below.';
 
 function continuationBlocks(input: {
   pendingBossQuestion?: { readonly question: string };
   bossReply?: string;
-}): string[] {
+}, resuming = false): string[] {
   if (input.pendingBossQuestion === undefined || input.bossReply === undefined) {
     return [];
   }
   return [
     CONTINUATION_PREAMBLE,
-    `Boss question:\n${input.pendingBossQuestion.question}`,
+    ...(resuming ? [] : [`Your previous question:\n${input.pendingBossQuestion.question}`]),
     `Boss reply:\n${input.bossReply}`,
   ];
 }
 
+/** Add clarification context without repeating the question in a live conversation. */
+export function composePlayerContinuation(
+  input: Pick<PlaybookPlayerInput, 'pendingBossQuestion' | 'bossReply'>,
+  body: string,
+  resuming = false,
+): string {
+  return [...continuationBlocks(input, resuming), body].join('\n\n');
+}
+
 const PLACEHOLDER_PATTERN = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
 
 function placeholderFieldName(
@@ -1104,16 +1114,15 @@ function placeholderFieldName(
 export function defaultComposePlayerPrompt(
   input: PlaybookPlayerInput,
   placeholderFields: Readonly<Record<string, string>> = {},
+  resuming = false,
 ): string {
-  const blocks = continuationBlocks(input);
   const fields = input as unknown as Record<string, unknown>;
   const body = input.prompt.replace(PLACEHOLDER_PATTERN, (match, token) => {
     const value =
       fields[placeholderFieldName(token as string, placeholderFields)];
     return typeof value === 'string' ? value : match;
   });
-  blocks.push(body);
-  return blocks.join('\n\n');
+  return composePlayerContinuation(input, body, resuming);
 }
 
 function sortJson(value: JsonValue): JsonValue {
@@ -3158,8 +3167,8 @@ export function createXStatePlaybookRuntime<
   }
   const composePlayerPrompt =
     spec.composePlayerPrompt ??
-    ((input: PlaybookPlayerInput) =>
-      defaultComposePlayerPrompt(input, spec.placeholderFields));
+    ((input: PlaybookPlayerInput, _identity: XStatePromptIdentity, resuming = false) =>
+      defaultComposePlayerPrompt(input, spec.placeholderFields, resuming));
   const composeCaptainPrompt =
     spec.composeCaptainPrompt ??
     ((input: PlaybookCaptainInput) =>
@@ -4074,7 +4083,7 @@ export function createXStatePlaybookRuntime<
       return session?.roleBindings?.[roleId]?.promptIdentity ?? roleId;
     }
 
-    function composeBoundPlayerPrompt(input: PlaybookPlayerInput): string {
+    function composeBoundPlayerPrompt(input: PlaybookPlayerInput, resuming = false): string {
       let active = true;
       const lookup: XStatePromptIdentity = (roleId) => {
         if (!active) {
@@ -4085,7 +4094,7 @@ export function createXStatePlaybookRuntime<
         return promptIdentity(roleId);
       };
       try {
-        return composePlayerPrompt(input, lookup);
+        return composePlayerPrompt(input, lookup, resuming);
       } finally {
         active = false;
       }
@@ -4523,7 +4532,7 @@ export function createXStatePlaybookRuntime<
       playerId: string | undefined,
     ): JsonValue {
       return snapshotJsonValue(
-        selectPlayerResume(roleId, playerId),
+        { v: 1, playerId: playerId ?? roleId },
         `${label} deferred player continuation`,
       );
     }
@@ -5321,7 +5330,7 @@ export function createXStatePlaybookRuntime<
       async callPlayer(
         input,
         roleId,
-        prompt,
+        freshPrompt,
         signal,
       ): Promise<PlayerResult> {
         // State-entry telemetry/status must precede the call they describe.
@@ -5356,6 +5365,8 @@ export function createXStatePlaybookRuntime<
           if (!isAbortFailure(error, signal)) controlPlaneError ??= error;
           throw error;
         }
+        const prompt = selectedResume === false
+          ? freshPrompt : composeBoundPlayerPrompt(input, true);
         const callId =
           deferredContinuation?.effectBoundary.callId ??
           `player-${++playerCallSequence}`;
@@ -5401,10 +5412,11 @@ export function createXStatePlaybookRuntime<
             resume: string | false = selectedResume,
           ): Promise<PlayerResult> => {
             const identity = callIdentity(resume);
+            const callPrompt = resume === false ? freshPrompt : prompt;
             await emitCallStarted(
               'player.call.started',
               'player.call.finished',
-              { ...identity, prompt },
+              { ...identity, prompt: callPrompt },
               position,
               signal,
             );
@@ -5418,9 +5430,9 @@ export function createXStatePlaybookRuntime<
               signal.throwIfAborted();
               rawResult = await requireHostPorts().callPlayer(
                 roleId,
-                prompt,
+                callPrompt,
                 signal,
-                { resume },
+                { resume, ...(callPrompt === freshPrompt ? {} : { freshPrompt }) },
               );
               // A host promise is not required to honor cancellation. Do not
               // let a late result mutate continuity or publish a successful
@@ -7324,6 +7336,15 @@ export function createXStatePlaybookRuntime<
         );
       }
       const effectBoundary = continuationBoundarySeed(operation, turnId);
+      const boundPlayerId = resolvedPlayerId(effectBoundary.roleId);
+      const validateBinding = (value: unknown): void => {
+        if (!isPlainObject(value) || Object.keys(value).length !== 2 ||
+            value.v !== 1 ||
+            value.playerId !== (boundPlayerId ?? effectBoundary.roleId)) {
+          throw new TypeError(`${label} bound deferred player continuation is invalid`);
+        }
+      };
+      validateBinding(operation.playerContinuation);
       const continuation: NonNullable<typeof activeDeferredContinuation> = {
         operationId: operation.operationId,
         effectBoundary,
@@ -7349,26 +7370,10 @@ export function createXStatePlaybookRuntime<
           operationId: operation.operationId,
           effectBoundary,
           operation: async ({ playerContinuation }) => {
-            const selectedContinuation =
-              retainedEffectSourceSessionId === undefined
-                ? playerContinuation
-                : selectPlayerResume(
-                    effectBoundary.roleId,
-                    resolvedPlayerId(effectBoundary.roleId),
-                  );
-            if (
-              selectedContinuation !== false &&
-              (typeof selectedContinuation !== 'string' ||
-                selectedContinuation.trim().length === 0)
-            ) {
-              throw new TypeError(
-                `${label} bound deferred player continuation is invalid`,
-              );
-            }
-            // Retained adoption owns a fresh Captain-session player ledger;
-            // no source token becomes target ownership. Same-engagement
-            // continuation still uses the exact durable binding.
-            continuation.playerContinuation = selectedContinuation;
+            validateBinding(playerContinuation);
+            continuation.playerContinuation = selectPlayerResume(
+              effectBoundary.roleId, boundPlayerId,
+            );
             continuationStarted = true;
             actor!.send(event);
             // The host has durably started this boundary and the FSM has