@sublang/playbook 17.3.0 → 17.4.0

package/reference/sdlc/code.playbook/bin/launch-config.js

@@ -2149,6 +2149,7 @@ function sessionAgentFromHostAgent(agent, path) {
   }
   return {
     adapter: agent.adapter,
+    ...(agent.browser === undefined ? {} : { browser: fastModeSelection(agent.browser, `${path}.browser`) }),
     model: tuningSelection(agent.model, `${path}.model`),
     effort: tuningSelection(agent.effort, `${path}.effort`),
     ...(agent.fastMode === undefined
@@ -2186,6 +2187,7 @@ export function projectHostAgent(agent, path = "agent") {
   const normalized = cloneJson(agent, path);
   return {
     adapter: normalized.adapter,
+    ...(normalized.browser === undefined ? {} : { browser: fastModeSelection(normalized.browser, `${path}.browser`) }),
     ...(normalized.model?.kind === "value"
       ? { model: normalized.model.value }
       : {}),

package/reference/sdlc/code.playbook/bin/portable-codec.js

@@ -2,6 +2,7 @@
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
 import { createHash } from 'node:crypto';
+import { validateAssetRef } from '../session-assets.js';
 import { posix, win32 } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import {
@@ -16,7 +17,7 @@ export const EMPTY_REPLAY_SHA256 = createHash('sha256').digest('hex');
 export const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
 const COMMON = ['schemaVersion', 'kind', 'sessionId', 'cwd', 'createdAt', 'updatedAt', 'state', 'replay', 'contextSeq'];
 const RECOVERY = ['structuralProjection', 'lastAppliedExecutionProjection', 'snapshot', 'effectLedger', 'unresolvedEffects'];
-const OPTIONAL = ['retainedGenerations', 'settledAbandonment'];
+const OPTIONAL = ['retainedGenerations', 'settledAbandonment', 'assets'];
 const HEX = /^[0-9a-f]{64}$/;
 const clone = (value) => structuredClone(value);
 const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -44,11 +45,17 @@ export function validateReplayCheckpoint(value) {
 export function validateSessionManifest(value) {
   if (!object(value) || value.schemaVersion !== 7) throw new Error(`unsupported session manifest schema ${value?.schemaVersion}`);
   const history = value.state === 'history-only';
-  exact(value, [...COMMON, ...(history ? ['reason'] : RECOVERY), ...(value.state === 'uncertain' ? ['uncertain'] : [])], history ? [] : OPTIONAL);
+  exact(value, [...COMMON, ...(history ? ['reason'] : RECOVERY), ...(value.state === 'uncertain' ? ['uncertain'] : [])], history ? ['assets'] : OPTIONAL);
   if (value.kind !== 'captain-session' || !SESSION_ID_PATTERN.test(value.sessionId) || !isRecordedAbsolutePath(value.cwd)) throw new Error('invalid session manifest identity');
   iso(value.createdAt); iso(value.updatedAt);
   if (Date.parse(value.updatedAt) < Date.parse(value.createdAt)) throw new Error('session update precedes creation');
   validateReplayCheckpoint(value.replay);
+  if (value.assets !== undefined) {
+    exact(value.assets, ['version', 'entries']);
+    if (value.assets.version !== 1 || !Array.isArray(value.assets.entries)) throw new Error('unsupported session asset manifest');
+    const ids = new Set();
+    for (const item of value.assets.entries) { const reference = validateAssetRef(item); if (ids.has(reference.assetId)) throw new Error('duplicate session asset reference'); ids.add(reference.assetId); }
+  }
   if (!(history && value.contextSeq === null) && (!Number.isSafeInteger(value.contextSeq) || value.contextSeq <= 0 || value.contextSeq > value.replay.seq)) throw new Error('invalid session context reference');
   if (history) {
     if (!nonempty(value.reason)) throw new Error('history-only session needs a reason');
@@ -60,7 +67,7 @@ export function validateSessionManifest(value) {
   return clone(value);
 }
 function recoveryFromManifestUnchecked(value) {
-  const { replay, contextSeq, ...recovery } = value;
+  const { replay, contextSeq, assets, ...recovery } = value;
   return { ...recovery, schemaVersion: 6 };
 }
 export function recoveryFromManifest(value) {
@@ -68,9 +75,9 @@ export function recoveryFromManifest(value) {
   if (manifest.state === 'history-only') throw new Error(manifest.reason);
   return validateCaptainSessionRecord(recoveryFromManifestUnchecked(manifest));
 }
-export function manifestFromRecovery(value, replay, contextSeq) {
+export function manifestFromRecovery(value, replay, contextSeq, assets) {
   const recovery = projectRecovery(validateCaptainSessionRecord(value));
-  return validateSessionManifest({ ...recovery, schemaVersion: 7, replay, contextSeq });
+  return validateSessionManifest({ ...recovery, schemaVersion: 7, replay, contextSeq, ...(assets === undefined ? {} : { assets }) });
 }
 export function projectRecovery(value) {
   const source = clone(value);

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

@@ -7,6 +7,8 @@
 // presenter; it does not construct a registry runtime or PlaybookPorts itself.
 
 import { randomUUID } from "node:crypto";
+import { workerReportExcerpt, workerRecoveryReportBlock } from "../worker-evidence.js";
+import { createSessionMediaProjector } from "./session-media.js";
 import { attachSessionHints, validateSessionContext } from "./portable-codec.js";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
@@ -995,6 +997,13 @@ export function restoreInterruptedProgress(record, ledger) {
       : `Captain preparation for ${name}: ${step.result.summary}`;
     return `${name} ${step.kind} call: ${step.result === undefined ? 'started; no result was saved' : step.result?.status === undefined ? 'result saved' : `returned ${step.result.status}`}.`;
   });
+  const workerReports = changedBoundaries.flatMap((boundary) => {
+    const completedStep = steps.find((step) => step.kind === 'player' &&
+      step.workerEvidence?.boundaryId === boundary.boundaryId);
+    if (!completedStep) return [];
+    const report = workerReportExcerpt(boundary, completedStep.workerEvidence.playerId, completedStep.result.guard);
+    return report === undefined ? [] : [report];
+  });
   const completedRoots = steps.filter((step) => step.kind === 'completion' && step.result.retention !== 'keep').map((step) => ({ kind: 'clear', rootPlaybookId: step.playbookId }));
   const report = {
     retentionUpdates: completedRoots,
@@ -1008,7 +1017,7 @@ export function restoreInterruptedProgress(record, ledger) {
         ? completion && !saved.frames?.length
           ? 'The completed run is restored; no work was repeated.'
           : 'The run stopped. Its saved position is restored; no work was repeated. Choose how to continue. Before repeating unfinished work, confirm that the earlier worker has stopped and check any outside actions it may have taken.'
-        : 'The exact stopping point was not saved. Files and repository evidence are preserved; no work was repeated. Check the saved work and stop any earlier worker before starting another attempt.', ...facts].join('\n\n'),
+        : 'The exact stopping point was not saved. Files and repository evidence are preserved; no work was repeated. Check the saved work and stop any earlier worker before starting another attempt.', ...facts, ...(workerReports.length ? [workerRecoveryReportBlock(workerReports)] : [])].join('\n\n'),
   };
   if (noWork) return { snapshot: base, report };
   if (saved) {
@@ -1068,6 +1077,7 @@ export async function createCaptainSessionHost({
   signal,
   graphs = [],
   initialVisible = [],
+  approvalHandler,
 }) {
   if (restoreSnapshot !== undefined) await sessionLease.assertContinuable({ cwd, executionProjection: config });
   const hostCapabilities = await createRepositoryEffectCapabilities({
@@ -1115,23 +1125,30 @@ export async function createCaptainSessionHost({
   if (sourceSnapshot !== undefined && !interrupted && typeof sessionLease.consumeHints === "function") {
     sourceSnapshot = attachSessionHints(sourceSnapshot, await sessionLease.consumeHints());
   }
+  let presentationAttachments = [];
+  const mediaProjector = createSessionMediaProjector({ lease: sessionLease, onEvidence: (asset, origin) => shell.recordMediaEvidence(asset, origin.runtimeSessionId) });
   const bufferedRecords = [];
   let presentationReady = false;
   const presentationTurnOffset = restoreSnapshot?.sequences.turn ?? 0;
+  const approvals = createHostApprovalScope(approvalHandler, presentationTurnOffset);
   const forwardRecord = async (record) => {
+    if (record.type === 'turn_started' && presentationAttachments.length) record = { ...record, turn: { ...record.turn, attachments: presentationAttachments } };
     const projected = presentationTurnOffset > 0 && typeof record.turnId === "number"
       ? { ...record, turnId: record.turnId + presentationTurnOffset, ...(record.type === "turn_started" ? { turn: { ...record.turn, id: record.turn.id + presentationTurnOffset } } : {}) }
       : record;
-    for (const observer of observers ?? []) await observer.onRecord?.(projected);
+    for (const value of await mediaProjector.project(projected)) for (const observer of observers ?? []) await observer.onRecord?.(value);
   };
   const bufferedObservers = [{ async onRecord(record) {
     if (!presentationReady) bufferedRecords.push(record);
     else await forwardRecord(record);
   } }];
   const shell = createPlaybookCaptainShell(captainOptionsFromConfig(config), {
+    onTurnAttachments: (references) => { presentationAttachments = references; },
+    beginPreparationMedia: (runtimeSessionId) => mediaProjector.beginPreparation(runtimeSessionId),
     abortPreparation: (reason) => host?.abortActiveTurn(typeof reason === 'string' ? reason : 'Captain preparation exceeded its 150-second limit'),
     loadModule,
     hostCapabilities,
+    ...(typeof sessionLease.resolveAttachments === 'function' ? { resolveAttachments: (references, signal) => sessionLease.resolveAttachments(references, { signal }) } : {}),
     ...(typeof sessionLease.recordProgress === 'function' ? {
       recordProgress: (change) => sessionLease.recordProgress(change),
     } : {}),
@@ -1166,6 +1183,7 @@ export async function createCaptainSessionHost({
       })),
       cwd,
       observers: bufferedObservers,
+      ...(approvals.handler ? { approvalHandler: approvals.handler } : {}),
       ...(signal ? { signal } : {}),
       ...(adapterImports ? { adapterImports } : {}),
     });
@@ -1193,9 +1211,13 @@ export async function createCaptainSessionHost({
     }
     presentationReady = true;
     for (const record of bufferedRecords) await forwardRecord(record);
-    if (interruptedReport) shell.selectInterruptedReport(interrupted.uncertain.input, interruptedReport);
-    return { shell, host, snapshot, reconcileRepositoryEffects, getInterruptedSettlement: (attemptId) => attemptId !== undefined && interruptedSettlement?.attemptId === attemptId ? interruptedSettlement.record : undefined };
+    if (interruptedReport) {
+      shell.setTurnAttachments(interrupted.uncertain.attachments ?? []);
+      shell.selectInterruptedReport(interrupted.uncertain.input, interruptedReport);
+    }
+    return { shell, host, snapshot, reconcileRepositoryEffects, cancelPendingApprovals: approvals.close, getInterruptedSettlement: (attemptId) => attemptId !== undefined && interruptedSettlement?.attemptId === attemptId ? interruptedSettlement.record : undefined };
   } catch (error) {
+    approvals.close();
     let cleanupError;
     try {
       if (host !== undefined) await host.dispose();
@@ -1213,6 +1235,48 @@ export async function createCaptainSessionHost({
   }
 }
 
+// Callback liveness belongs to the host, independently of durable turn state.
+// Closing this scope denies waits without cancelling ordinary graceful work.
+function createHostApprovalScope(handler, turnOffset) {
+  const lifetime = new AbortController();
+  return {
+    close: () => lifetime.abort('session host closing'),
+    handler: typeof handler !== 'function' ? undefined : (envelope, { signal }) => {
+      if (lifetime.signal.aborted || signal.aborted) return Promise.resolve('deny');
+      const controller = new AbortController();
+      return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (decision) => {
+          if (settled) return;
+          settled = true;
+          signal.removeEventListener('abort', cancel);
+          lifetime.signal.removeEventListener('abort', cancel);
+          if (!envelope.request.choices.includes(decision)) controller.abort('Invalid approval decision');
+          resolve(decision);
+        };
+        const fail = (error) => {
+          if (settled) return;
+          settled = true;
+          signal.removeEventListener('abort', cancel);
+          lifetime.signal.removeEventListener('abort', cancel);
+          controller.abort(error);
+          reject(error);
+        };
+        const cancel = () => {
+          controller.abort(signal.aborted ? signal.reason : lifetime.signal.reason);
+          finish('deny');
+        };
+        signal.addEventListener('abort', cancel, { once: true });
+        lifetime.signal.addEventListener('abort', cancel, { once: true });
+        Promise.resolve().then(() => {
+          if (settled) return 'deny';
+          return handler({ ...envelope, turnId: envelope.turnId + turnOffset }, { signal: controller.signal });
+        }).then(finish, fail);
+      });
+    },
+  };
+}
+
 // PBCLI-55: both presentations install one authoritative retention map at the
 // same post-shell, pre-turn boundary. Fresh-session guarded initialization
 // publishes either the intentional empty boundary or the transferred map.

package/reference/sdlc/code.playbook/bin/session-host.js

@@ -2,6 +2,7 @@
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
 import { randomUUID } from 'node:crypto';
+import { normalizeSessionTurnInput } from '../session-assets.js';
 import { createCaptainSessionStore, isUncertainTurnDiscardable, projectCaptainSessionStructure } from './session-store.js';
 import { createCaptainSessionHost, executionConfigFromPlan, installRetainedGenerationsForLaunch, validateFrozenExecutionConfig } from './run.js';
 import { createReplayRecordObserver } from './replay-observer.js';
@@ -33,9 +34,10 @@ export async function openSessionHost(options) {
     if (record !== undefined) await lease.assertContinuable({ cwd, executionProjection: selected });
     const config = await validateFrozenExecutionConfig(structure, selected, { loadModule, prepareRegistryModule: options.prepareRegistryModule });
     const replay = createReplayRecordObserver({ lease, onIncomplete: options.onIncomplete ?? (() => {}), onStored: options.onStoredRecord });
-    let terminal, replies = [];
+    let terminal, replies = [], submittedAttachments = [];
     const observe = {
       async onRecord(value) {
+        if (value.type === 'turn_started' && submittedAttachments.length) value = { ...value, turn: { ...value.turn, attachments: submittedAttachments } };
         if (value.type === "turn_finished" || value.type === "turn_aborted") terminal = value;
         if (value.type === "captain_reply") replies.push(value);
         await replay.observer.onRecord(value);
@@ -53,14 +55,21 @@ export async function openSessionHost(options) {
     const execute = async (input, retry, actionId, shellActionId) => {
       assertIdle();
       let attemptId;
+      let attachments = [];
       const operation = (async () => {
         let prior = await lease.read();
         if (retry) {
           if (prior?.state !== 'uncertain') throw new Error('session has no uncertain turn to retry');
           input = prior.uncertain.input;
+          attachments = prior.uncertain.attachments ?? [];
           if (!retryPending) throw new Error(RECOVERY_REOPEN);
         } else if (prior?.state !== 'settled') throw new Error(RECOVERY_REOPEN);
-        if (actionId === undefined && shellActionId === undefined && (typeof input !== 'string' || input.trim().length === 0)) throw new Error('session input must be nonempty');
+        if (actionId === undefined && shellActionId === undefined) {
+          const normalized = normalizeSessionTurnInput(retry ? { text: input, attachments } : input);
+          input = normalized.text; attachments = normalized.attachments;
+          if (!input.trim() && attachments.length === 0) throw new Error('session input must contain text or attachments');
+          if (attachments.length) await lease.resolveAttachments(attachments, { signal: options.signal });
+        }
         await created.reconcileRepositoryEffects();
         // The selection is made after reconciliation, so the advertised
         // reading it is validated against is the one this turn settles
@@ -74,11 +83,13 @@ export async function openSessionHost(options) {
         }
         terminal = undefined; replies = [];
         attemptId = options.createAttemptId?.() ?? randomUUID();
-        const marked = retry ? await lease.beginRetry({ expectedAttemptId: prior.uncertain.attemptId, nextAttemptId: attemptId }) : await lease.beginTurn({ input, attemptId, attemptedExecutionProjection: config });
+        const marked = retry ? await lease.beginRetry({ expectedAttemptId: prior.uncertain.attemptId, nextAttemptId: attemptId }) : await lease.beginTurn({ input, attachments, attemptId, attemptedExecutionProjection: config });
         retryPending = false;
         await replay.flushStoredRecords();
         await options.onCheckpoint?.(marked);
         await lease.assertOwner();
+        submittedAttachments = attachments;
+        created.shell.setTurnAttachments?.(attachments);
         await created.host.runBossTurn(input);
         if (terminal?.type !== "turn_finished" || replies.length !== 1 || typeof replies[0].text !== "string" || replies[0].text.trim().length === 0) throw new Error("Captain turn did not finish with one reply; session remains uncertain");
         const settlement = created.shell.exportSettlement();
@@ -101,12 +112,13 @@ export async function openSessionHost(options) {
         throw error;
       });
       active = operation;
-      try { return await operation; } finally { active = undefined; }
+      try { return await operation; } finally { active = undefined; submittedAttachments = []; }
     };
 
     const dispose = () => {
       if (closed) return Promise.resolve();
       if (closing) return closing;
+      created.cancelPendingApprovals();
       closing = (async () => {
         try { await active; } catch { /* Preserve the durable uncertain marker. */ }
         await created.host.dispose();

package/reference/sdlc/code.playbook/bin/session-media.js

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+import { randomUUID } from 'node:crypto';
+import { externalizeAgentEvent } from '../session-assets.js';
+
+/** Externalize authentic observed media before the opaque replay writer sees it. */
+export function createSessionMediaProjector({ lease, onEvidence }) {
+  const players = new Map();
+  let preparation;
+  const seen = new Map();
+  const beginPreparation = (runtimeSessionId) => {
+    if (preparation) throw new Error('a preparation media scope is already active');
+    const scope = { callId: randomUUID(), origin: { kind: 'preparation', actorId: 'captain', runtimeSessionId } };
+    preparation = scope;
+    return () => { if (preparation === scope) preparation = undefined; seen.delete(scope.callId); };
+  };
+  const project = async (record) => {
+    if (record.type === 'captain_telemetry' && record.topic === 'playbook.trace') {
+      const trace = record.payload;
+      if (trace?.schemaVersion === 4 && trace.type === 'player.call.started' && typeof trace.callId === 'string' && typeof trace.sessionId === 'string' && typeof trace.payload?.playerId === 'string') {
+        players.set(trace.payload.playerId, { callId: trace.callId, origin: { kind: 'player', actorId: trace.payload.playerId, runtimeSessionId: trace.sessionId } });
+      }
+    }
+    if (record.type === 'player_prompt' && !players.has(record.playerId)) players.set(record.playerId, { callId: randomUUID(), origin: { kind: 'player', actorId: record.playerId } });
+    if (record.type === 'player_finished') { const scope = players.get(record.playerId); if (scope) seen.delete(scope.callId); players.delete(record.playerId); }
+    if (record.type !== 'player_event' && record.type !== 'captain_event') return [record];
+    const event = record.event;
+    const scope = record.type === 'player_event' ? players.get(record.playerId) : preparation;
+    try {
+      const { event: projected, asset } = await externalizeAgentEvent(lease, event);
+      const stored = projected === event ? record : { ...record, event: projected };
+      if (!asset || !scope || typeof record.turnId !== 'number') return [stored];
+      let emitted = seen.get(scope.callId);
+      if (!emitted) { emitted = new Set(); seen.set(scope.callId, emitted); }
+      if (emitted.has(asset.assetId)) return [stored];
+      emitted.add(asset.assetId);
+      const origin = { ...scope.origin, ...(event.payload.toolUseId ? { toolUseId: event.payload.toolUseId } : {}) };
+      await onEvidence?.(asset, origin);
+      return [stored, { type: 'playbook_evidence', timestamp: record.timestamp, turnId: record.turnId, callId: scope.callId, origin, asset }];
+    } catch (error) {
+      return [{ type: 'runtime_error', timestamp: record.timestamp, turnId: record.turnId, sourceRecordType: record.type, message: `Media could not be saved: ${error instanceof Error ? error.message : String(error)}` }];
+    }
+  };
+  return Object.freeze({ project, beginPreparation });
+}