@bastani/atomic 0.9.11-alpha.6 → 0.9.11-alpha.8

package/dist/builtin/workflows/src/extension/workflow-model-catalog.ts

@@ -0,0 +1,26 @@
+import type { CreateAgentSessionOptions } from "@bastani/atomic";
+import type { WorkflowModelCatalogPort, WorkflowModelInfo } from "../shared/types.js";
+import type { PiModelContext } from "./public-types.js";
+
+export function workflowModelCatalogFromContext(
+  ctx?: PiModelContext,
+): WorkflowModelCatalogPort | undefined {
+  if (ctx?.modelRegistry === undefined && ctx?.model === undefined) return undefined;
+  return {
+    listModels: async (): Promise<readonly WorkflowModelInfo[]> => {
+      const available = ctx.modelRegistry?.getAvailable() ?? (ctx.model === undefined ? [] : [ctx.model]);
+      return available.map((model) => ({
+        provider: String(model.provider),
+        id: model.id,
+        fullId: `${String(model.provider)}/${model.id}`,
+        model: model as NonNullable<CreateAgentSessionOptions["model"]>,
+      }));
+    },
+    ...(ctx.model !== undefined
+      ? {
+          currentModel: ctx.model as NonNullable<CreateAgentSessionOptions["model"]>,
+          preferredProvider: String(ctx.model.provider),
+        }
+      : {}),
+  };
+}

package/dist/builtin/workflows/src/extension/workflow-prompts.ts

@@ -1,6 +1,6 @@
 export const WORKFLOW_TOOL_DESCRIPTION =
   "Run named builtin, project, user, or package workflows; custom definitions may import reusable project/package workflows or builtin definitions from @bastani/workflows/builtin and nest them with ctx.workflow(...), including deeper composition within the configured maxDepth; " +
-  "when workflow execution fits but another shape would better achieve the task, author a custom TypeScript workflow({...}) inline with normal coding tools, reload it, and run it; " +
+  "when workflow execution fits but another shape would better achieve the task, author a custom TypeScript workflow({...}) inline with normal coding tools, reload it, and run it; after successfully creating and reloading a newly authored custom workflow, report the folder containing its generated code as 'Custom workflow created. You can inspect its code at: <workflow-folder-path>'; do this only for newly created custom workflows, never builtin or pre-existing workflows; " +
   "discover with list/get/inputs/models, list session runs with status (no runId; statusFilter narrows the list), inspect status/stages/stage details, " +
   "send prompt answers or steering only while the root workflow is nonterminal, pause/resume/interrupt/quit runs, and reload workflow resources. " +
   "For large stage handoffs, write context to files/artifacts, pass paths via reads, and prompt downstream agents to 'Read the file at <path>...' instead of injecting large previous text. " +
@@ -44,6 +44,7 @@ export const DEFAULT_PROMPT_GUIDANCE: string[] = [
   - For transcripts, avoid whole-file reads. Get \`sessionFile\`/\`transcriptPath\` from \`stages\` or \`stage\`, preserve the exact path and platform separators, search with \`rg\`/\`grep\`, and read small relevant ranges; use explicit \`tail\` or \`limit\` only for a bounded preview.`,
   `**Workflow authoring and handoffs**:
   - When a user asks to create or edit a workflow, clarify only unresolved requirements that materially affect its purpose, inputs, stages, handoffs, validation, success criteria, or starter pattern. Read the workflow docs/examples, implement the TypeScript definition with normal coding tools, reload it, and run representative test inputs before presenting it. Use the create-spec skill when it adds value; it is not mandatory when context is already sufficient.
+  - After creating and reloading a newly authored custom workflow, close the loop by stating the folder containing the workflow file just written, for example \`.atomic/workflows/\`, in this shape: \`Custom workflow created. You can inspect its code at: <workflow-folder-path>\`. Do this only for newly created custom workflows, never builtin or pre-existing workflows.
   - When creating or editing a workflow that pins an explicit stage \`model\` or \`fallbackModels\`, consult \`packages/coding-agent/docs/models/model-selection.md\` for role-based recommendations, then call \`workflow({ action: "models" })\` to see the models actually present in the user's configured catalog. Use only the catalog's returned \`fullId\` values as model strings, and append a thinking suffix only when that exact level appears in the entry's \`availableThinkingLevels\`; treat an absent or empty \`availableThinkingLevels\` as no suffix support rather than inferring one. If a guide-recommended model for the role is unavailable, try another guide-recommended model that is present in the catalog. If no recommendation intersects with the catalog, leave the stage unpinned rather than inventing a substitute, and mention the limitation, asking the user only if the workflow requires an explicit model choice. If the catalog is empty, continue with unpinned stages, state that no configured models were returned, and do not fabricate model IDs. Do not inspect or infer credentials, environment variables, auth files, token validity, entitlements, or the reason a model is absent; \`isCurrent\` marks the active selection, not a quality recommendation.
   - Consult docs/workflows.md and its starter patterns (Classify-and-act, Fan-out-and-synthesize, Adversarial verification, Generate-and-filter, Tournament, and Loop until done) when designing a stage graph.
   - Treat workflow composition as a first-class authoring option. Before duplicating stages, inspect reusable workflow modules and builtin exports; import their definitions and invoke them with \`ctx.workflow(...)\`, mapping typed inputs and consuming only declared outputs. Nested workflows can themselves import children, so combine small reusable graphs into a richer parent while respecting \`maxDepth\`.
@@ -56,4 +57,4 @@ export const DEFAULT_PROMPT_GUIDANCE: string[] = [
   - Pass large stage context through files/artifacts and \`reads\` with an explicit \`Read the file at <path>...\` prompt rather than large \`previous\` payloads or injected session history.
   - Separate implementation/review acceptance from explicitly authorized final actions such as PR/MR/review creation, release tagging, deployment, or publication. Stop implementation loops once acceptance is proven and carry a remaining final action separately.
   - A model stage sees its local prompt, artifacts, tools, and reads, not the graph name or surrounding implementation. State the concrete action, evidence, and success criteria directly.`,
-];
+];

package/dist/builtin/workflows/src/runs/foreground/executor-stage-control.ts

@@ -1,21 +1,31 @@
 import type { StageControlHandle, AgentSessionEventListener } from "./stage-control-registry.js";
 import type { LiveStageRuntime } from "./executor-stage-types.js";
-import type { StageUserMessageDeliveryAction } from "./stage-runner-types.js";
+import type { StageUserMessageDeliveryAction, StageUserMessagePreparation } from "./stage-runner-types.js";
 import { isTerminalStage } from "./executor-scheduler.js";
 import { StageToolExecutionBuffer } from "./stage-tool-execution-buffer.js";
 
 export function createStageControlHandle(runtime: LiveStageRuntime): StageControlHandle {
-  const ensureMessagingSession = async (): Promise<void> => {
+  const messagePreparation = (): StageUserMessagePreparation => {
     const meta = runtime.innerCtx.__sessionMeta();
-    if (meta.sessionId !== undefined || meta.sessionFile !== undefined) return;
+    if (meta.sessionId !== undefined || meta.sessionFile !== undefined) {
+      return { beforePreparation: runtime.throwIfStageMutationBlocked };
+    }
     if (runtime.stageSnapshot.sessionFile !== undefined) {
-      await runtime.innerCtx.__ensureSessionFromFile(runtime.stageSnapshot.sessionFile);
-      runtime.captureStageSessionMeta();
-      return;
+      return {
+        sessionFile: runtime.stageSnapshot.sessionFile,
+        beforePreparation: runtime.throwIfStageMutationBlocked,
+      };
     }
     if (isTerminalStage(runtime.stageSnapshot)) {
       throw new Error(`atomic-workflows: cannot message stage "${runtime.name}" because no retained session metadata is available.`);
     }
+    return { beforePreparation: runtime.throwIfStageMutationBlocked };
+  };
+  const ensureMessagingSession = async (): Promise<void> => {
+    const sessionFile = messagePreparation().sessionFile;
+    if (sessionFile === undefined) return;
+    await runtime.innerCtx.__ensureSessionFromFile(sessionFile);
+    runtime.captureStageSessionMeta();
   };
   const toolExecutions = new StageToolExecutionBuffer();
   const unsubscribeToolExecutions = runtime.innerCtx.subscribe((event) => toolExecutions.record(event));
@@ -57,8 +67,7 @@ export function createStageControlHandle(runtime: LiveStageRuntime): StageContro
     },
     async sendUserMessage(text, options, beforeDelivery) {
       runtime.throwIfStageMutationBlocked();
-      await ensureMessagingSession();
-      runtime.throwIfStageMutationBlocked();
+      const preparation = messagePreparation();
       const admitDelivery = (): void => {
         runtime.throwIfStageMutationBlocked();
         beforeDelivery?.();
@@ -68,6 +77,7 @@ export function createStageControlHandle(runtime: LiveStageRuntime): StageContro
           text,
           options,
           admitDelivery,
+          preparation,
         );
         if (action === "steer" || action === "followUp") {
           runtime.state.resumeContinuationPending = "queued-user-message";
@@ -79,13 +89,14 @@ export function createStageControlHandle(runtime: LiveStageRuntime): StageContro
     },
     async prompt(text: string) {
       runtime.throwIfStageMutationBlocked();
-      await ensureMessagingSession();
+      const preparation = messagePreparation();
       let action: StageUserMessageDeliveryAction | undefined;
       try {
         action = await runtime.innerCtx.__sendUserMessage(
           text,
           undefined,
           runtime.throwIfStageMutationBlocked,
+          preparation,
         );
       } finally {
         runtime.captureStageSessionMeta();
@@ -197,6 +208,9 @@ export function createStageControlHandle(runtime: LiveStageRuntime): StageContro
     subscribe(listener: AgentSessionEventListener) {
       return runtime.innerCtx.subscribe(listener);
     },
+    subscribeDeliveryActivity(listener) {
+      return runtime.innerCtx.__subscribeDeliveryActivity(listener);
+    },
     async dispose() {
       unsubscribeToolExecutions();
       toolExecutions.clear();

package/dist/builtin/workflows/src/runs/foreground/executor-stage-replay.ts

@@ -100,6 +100,7 @@ export function createReplayStageContext(input: {
     steer: async () => rejectReplayMutation("steer"),
     followUp: async () => rejectReplayMutation("follow up"),
     subscribe: () => () => {},
+    __subscribeDeliveryActivity: () => () => {},
     get sessionFile() { return replaySource.sessionFile; },
     get sessionId() { return replaySource.sessionId ?? ""; },
     setModel: async () => rejectReplayMutation("set model"),

package/dist/builtin/workflows/src/runs/foreground/postmortem-stage-chat.ts

@@ -34,6 +34,7 @@ import {
   type StageControlHandle,
   type StageControlRegistry,
 } from "./stage-control-registry.js";
+import type { StageUserMessagePreparation } from "./stage-runner-types.js";
 
 /** Why a terminal stage could not be revived as an interactive post-mortem chat. */
 export type PostMortemUnavailableReason =
@@ -153,10 +154,18 @@ export function createPostMortemStageHandle(
     ...(defaultSessionDir !== undefined ? { defaultSessionDir } : {}),
   });
   let disposed = false;
-  const ensureAttached = async (): Promise<void> => {
+  const throwIfClosed = (): void => {
     if (disposed) throw new Error(`Post-mortem stage chat "${stage.name}" is closed.`);
-    if (context.__sessionMeta().sessionFile === undefined) {
-      await context.__ensureSessionFromFile(sessionFile);
+  };
+  const messagePreparation = (): StageUserMessagePreparation => ({
+    ...(context.__sessionMeta().sessionFile === undefined ? { sessionFile } : {}),
+    beforePreparation: throwIfClosed,
+  });
+  const ensureAttached = async (): Promise<void> => {
+    throwIfClosed();
+    const sessionFileToRestore = messagePreparation().sessionFile;
+    if (sessionFileToRestore !== undefined) {
+      await context.__ensureSessionFromFile(sessionFileToRestore);
     }
   };
   return {
@@ -172,8 +181,13 @@ export function createPostMortemStageHandle(
     get agentSession() { return context.__agentSession(); },
     async ensureAttached() { await ensureAttached(); },
     async sendUserMessage(text, options, beforeDelivery) {
-      await ensureAttached();
-      return context.__sendUserMessage(text, options, beforeDelivery);
+      throwIfClosed();
+      const preparation = messagePreparation();
+      const admitDelivery = (): void => {
+        throwIfClosed();
+        beforeDelivery?.();
+      };
+      return context.__sendUserMessage(text, options, admitDelivery, preparation);
     },
     async prompt(text: string) {
       await ensureAttached();
@@ -194,6 +208,7 @@ export function createPostMortemStageHandle(
       throw new Error("Post-mortem stage chat cannot pause or resume workflow execution.");
     },
     subscribe(listener: AgentSessionEventListener) { return context.subscribe(listener); },
+    subscribeDeliveryActivity(listener) { return context.__subscribeDeliveryActivity(listener); },
     async dispose() {
       if (disposed) return;
       disposed = true;

package/dist/builtin/workflows/src/runs/foreground/stage-control-registry.ts

@@ -26,6 +26,7 @@
  */
 
 import type { AgentSession, AgentSessionEvent } from "@bastani/atomic";
+import type { StageDeliveryActivityEvent } from "./stage-delivery-activity.js";
 import type { StageUserMessageDeliveryAction } from "./stage-runner-types.js";
 
 export type StageControlStatus =
@@ -98,6 +99,15 @@ export interface StageControlHandle {
    * before the session exists are buffered and bound on first attach.
    */
   subscribe(listener: AgentSessionEventListener): () => void;
+  /**
+   * Subscribe to workflow-owned delivery lifecycle facts. Present only for
+   * handles backed by a live stage runner. An accepted idle delivery reports
+   * `delivery_start` before the public `agent_start` is published, letting an
+   * attached chat show Working for the whole turn.
+   */
+  subscribeDeliveryActivity?(
+    listener: (event: StageDeliveryActivityEvent) => void,
+  ): () => void;
   /** Release the underlying SDK session and unregister this direct chat handle. */
   dispose?(): void | Promise<void>;
 }

package/dist/builtin/workflows/src/runs/foreground/stage-delivery-activity.ts

@@ -0,0 +1,86 @@
+/**
+ * Internal stage delivery-activity channel.
+ *
+ * An accepted *idle* stage delivery starts a real backend turn long before the
+ * public `agent_start` clears the session's ordered extension event queue. The
+ * attached stage chat therefore had no signal to paint `Working` with, and the
+ * pane looked idle while the model was already running.
+ *
+ * This channel carries only that fact — "an idle delivery was admitted and is
+ * now starting a turn" — as a workflow-internal event, so the chat can start
+ * its existing Working lifecycle without fabricating SDK lifecycle events or
+ * reordering the public event stream.
+ *
+ * Streaming deliveries (`steer` / `followUp`) never emit here: they join an
+ * in-flight turn that already owns the indicator.
+ *
+ * cross-ref:
+ *   - src/runs/foreground/stage-runner-send-user-message.ts (emitter)
+ *   - src/tui/stage-chat-view-delivery-activity.ts (consumer)
+ */
+
+export type StageDeliveryActivityEvent =
+  | { readonly type: "delivery_start"; readonly deliveryId: number }
+  | { readonly type: "delivery_settled"; readonly deliveryId: number };
+
+export type StageDeliveryActivityListener = (event: StageDeliveryActivityEvent) => void;
+
+export class StageDeliveryActivity {
+  private readonly listeners = new Set<StageDeliveryActivityListener>();
+  private readonly active = new Set<number>();
+  private nextDeliveryId = 0;
+
+  /**
+   * Register `listener`, then synchronously replay every currently-active
+   * delivery as `delivery_start`.
+   *
+   * A stage chat can attach after a delivery was admitted — a late `/workflow
+   * attach`, or a remount — and would otherwise see nothing until the public
+   * `agent_start` finally arrives. Registering before replaying matters:
+   * snapshotting first would drop a start or settlement that lands in between.
+   */
+  subscribe(listener: StageDeliveryActivityListener): () => void {
+    this.listeners.add(listener);
+    for (const deliveryId of [...this.active]) {
+      if (!this.listeners.has(listener)) break;
+      listener({ type: "delivery_start", deliveryId });
+    }
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /** Report an admitted idle delivery that is about to start a turn. */
+  start(): number {
+    const deliveryId = ++this.nextDeliveryId;
+    this.active.add(deliveryId);
+    this.emit({ type: "delivery_start", deliveryId });
+    return deliveryId;
+  }
+
+  /** Keep one correlated delivery active for the full asynchronous operation. */
+  async runWithLease<T>(operation: () => Promise<T>): Promise<T> {
+    const deliveryId = this.start();
+    try {
+      return await operation();
+    } finally {
+      this.settle(deliveryId);
+    }
+  }
+
+  /** Report that a delivery finished, failed, or started no turn at all. */
+  settle(deliveryId: number | undefined): void {
+    if (deliveryId === undefined || !this.active.delete(deliveryId)) return;
+    this.emit({ type: "delivery_settled", deliveryId });
+  }
+
+  /** Settle every outstanding delivery, then drop listeners. */
+  dispose(): void {
+    for (const deliveryId of [...this.active]) this.settle(deliveryId);
+    this.listeners.clear();
+  }
+
+  private emit(event: StageDeliveryActivityEvent): void {
+    for (const listener of [...this.listeners]) listener(event);
+  }
+}

package/dist/builtin/workflows/src/runs/foreground/stage-runner-context.ts

@@ -110,8 +110,8 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
       await controller.sendUserMessage(text, options);
     },
 
-    async __sendUserMessage(text, options, beforeDelivery) {
-      return controller.sendUserMessage(text, options, beforeDelivery);
+    async __sendUserMessage(text, options, beforeDelivery, preparation) {
+      return controller.sendUserMessage(text, options, beforeDelivery, preparation);
     },
 
     async steer(text) {
@@ -126,6 +126,10 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
       return controller.subscribe(listener);
     },
 
+    __subscribeDeliveryActivity(listener) {
+      return controller.subscribeDeliveryActivity(listener);
+    },
+
     get sessionFile() {
       return controller.currentSession?.sessionFile;
     },

package/dist/builtin/workflows/src/runs/foreground/stage-runner-controller.ts

@@ -9,8 +9,9 @@ import { structuredOutputToolErrorFromEvent } from "./stage-runner-structured-ou
 import { buildStageSessionOptions } from "./stage-runner-session-options.js";
 import { sendStageUserMessage } from "./stage-runner-send-user-message.js";
 import { StageMessageAdmission } from "./stage-runner-message-admission.js";
+import { StageDeliveryActivity, type StageDeliveryActivityListener } from "./stage-delivery-activity.js";
 import { nextResumedContextOverflowFallbackIndex, terminatingToolCallId, unresolvedContextOverflowFailure, unresolvedContextOverflowMessage } from "./stage-runner-unresolved-overflow.js";
-import type { AgentSessionConsumer, StageModelFallbackMeta, StageRunnerOpts, StageSessionCreateOptions, StageSessionCreateResult, StageSessionEvent, StageSessionRuntime, WorkflowFastModeSettingsManager } from "./stage-runner-types.js";
+import type { AgentSessionConsumer, StageModelFallbackMeta, StageRunnerOpts, StageSessionCreateOptions, StageSessionCreateResult, StageSessionEvent, StageSessionRuntime, StageUserMessagePreparation, WorkflowFastModeSettingsManager } from "./stage-runner-types.js";
 import { StageSessionReplacement } from "./stage-runner-replacement.js";
 import { StageSessionPause, type StageSessionPauseResumeResult } from "./stage-runner-pause.js";
 
@@ -34,7 +35,7 @@ export class StageSessionController {
   private candidatesPromise: Promise<WorkflowResolvedModelCandidate[]> | undefined;
   private activeCandidateIndex: number | undefined;
   private selectedModel: string | undefined;
-  private sharedModelRegistry: CreateAgentSessionOptions["modelRegistry"];
+  private sharedModelRuntime: CreateAgentSessionOptions["modelRuntime"];
   private sharedOrchestrationContext: CreateAgentSessionOptions["orchestrationContext"];
   private resumeCurrentSession = false;
   private readonly modelAttempts: WorkflowModelAttempt[] = [];
@@ -44,6 +45,7 @@ export class StageSessionController {
   private sessionSettingsManager: WorkflowFastModeSettingsManager | undefined;
   private readonly replacement = new StageSessionReplacement();
   private readonly messageAdmission = new StageMessageAdmission();
+  private readonly deliveryActivity = new StageDeliveryActivity();
 
   constructor(
     private readonly opts: StageRunnerOpts,
@@ -106,21 +108,25 @@ export class StageSessionController {
     return session;
   }
 
-  async sendUserMessage(content: StageUserMessageContent, options?: StageSendUserMessageOptions, beforeDelivery?: () => void):
-    Promise<Awaited<ReturnType<typeof sendStageUserMessage>>> {
+  async sendUserMessage(content: StageUserMessageContent, options?: StageSendUserMessageOptions,
+    beforeDelivery?: () => void, preparation?: StageUserMessagePreparation): Promise<Awaited<ReturnType<typeof sendStageUserMessage>>> {
     return this.messageAdmission.run(async (release) => {
-      const pausedDelivery = this.pauseControl.deferRunnerOwnedDelivery(
-        () => this.sendUserMessage(content, options, beforeDelivery),
-      );
-      if (pausedDelivery !== undefined) {
-        release();
-        return pausedDelivery;
-      }
-      return sendStageUserMessage(
-        await this.ensureSession("prompt"), content, options, beforeDelivery, release, this.messageAdmission,
+      const pausedDelivery = this.pauseControl.deferRunnerOwnedDelivery(() =>
+        this.sendUserMessage(content, options, beforeDelivery, preparation));
+      if (pausedDelivery !== undefined) { release(); return pausedDelivery; }
+      preparation?.beforePreparation?.();
+      const sessionFile = preparation?.sessionFile;
+      const deliver = async (activity?: StageDeliveryActivity) => sendStageUserMessage(
+        sessionFile === undefined ? await this.ensureSession("prompt")
+          : await this.ensureSessionFromFile(sessionFile, "prompt"),
+        content, options, beforeDelivery, release, this.messageAdmission, activity,
       );
+      if (this.session === undefined || sessionFile !== undefined) return this.deliveryActivity.runWithLease(() => deliver());
+      return deliver(this.deliveryActivity);
     });
   }
+  /** Internal pre-stream delivery lifecycle consumed by an attached stage chat. */
+  subscribeDeliveryActivity(listener: StageDeliveryActivityListener): () => void { return this.deliveryActivity.subscribe(listener); }
 
   sealGeneration(): void {
     this.generationSealed = true;
@@ -201,7 +207,7 @@ export class StageSessionController {
     this.pendingListeners.clear();
     this.unsubscribeTerminateWatcher?.();
     this.unsubscribeTerminateWatcher = undefined;
-    this.terminatingToolCallIds.clear(); this.messageAdmission.dispose();
+    this.terminatingToolCallIds.clear(); this.messageAdmission.dispose(); this.deliveryActivity.dispose();
     await this.replacement.dispose();
     await disposeStageSession(this.session);
   }
@@ -293,7 +299,7 @@ export class StageSessionController {
       candidate,
       restoreSavedModel: resumeOptions?.restoreSavedModel,
       reattachSessionFile: this.reattachSessionFile,
-      sharedModelRegistry: this.sharedModelRegistry,
+      sharedModelRuntime: this.sharedModelRuntime,
     });
     const created = this.opts.adapters.agentSession
       ? await this.opts.adapters.agentSession.create(
@@ -319,9 +325,9 @@ export class StageSessionController {
     if (this.generationSealed) result.session.sealWorkflowStageGeneration?.();
     this.replacement.adopt(result.session);
     this.session = result.session;
-    if (this.sharedModelRegistry === undefined) {
-      const withRegistry = result.session as Partial<Pick<AgentSession, "modelRegistry">>;
-      if (withRegistry.modelRegistry !== undefined) this.sharedModelRegistry = withRegistry.modelRegistry;
+    if (this.sharedModelRuntime === undefined) {
+      const withRegistry = result.session as Partial<Pick<AgentSession, "modelRuntime">>;
+      if (withRegistry.modelRuntime !== undefined) this.sharedModelRuntime = withRegistry.modelRuntime;
     }
     this.sessionSettingsManager = result.settingsManager ?? result.session.settingsManager;
     if (this.pendingThinkingLevel !== undefined) result.session.setThinkingLevel(this.pendingThinkingLevel);

package/dist/builtin/workflows/src/runs/foreground/stage-runner-send-user-message.ts

@@ -1,4 +1,5 @@
 import type { StageSendUserMessageOptions, StageUserMessageContent } from "../../shared/types.js";
+import type { StageDeliveryActivity } from "./stage-delivery-activity.js";
 import type { StageMessageAdmission, StageMessageTurn } from "./stage-runner-message-admission.js";
 import type { StageSessionRuntime, StageUserMessageDeliveryAction } from "./stage-runner-types.js";
 
@@ -59,6 +60,7 @@ export async function sendStageUserMessage(
   beforeDelivery?: () => void,
   promptStarted?: () => void,
   admission?: StageMessageAdmission,
+  activity?: StageDeliveryActivity,
 ): Promise<StageUserMessageDeliveryAction> {
   const streaming = activeSession.isStreaming || admission?.isOwned(activeSession) === true;
   const deliverAs = streaming ? options?.deliverAs ?? "followUp" : options?.deliverAs;
@@ -71,6 +73,9 @@ export async function sendStageUserMessage(
         ? createLocalPromptOwnershipObserver(activeSession, promptStarted)
         : coordinatedPromptOwnershipObserver(admission.startTurn(activeSession, promptStarted ?? (() => {})));
     ownership?.arm();
+    // An admitted idle delivery owns the visible Working period from here until
+    // it settles; a streaming delivery joins a turn that already owns it.
+    const deliveryId = streaming ? undefined : activity?.start();
     try {
       const delivery = activeSession.sendUserMessage(content, {
         ...(deliverAs === undefined ? {} : { deliverAs }),
@@ -89,6 +94,7 @@ export async function sendStageUserMessage(
       throw error;
     } finally {
       ownership?.dispose();
+      activity?.settle(deliveryId);
     }
   }
   if (typeof content !== "string") throw unsupportedContentError();
@@ -102,6 +108,7 @@ export async function sendStageUserMessage(
     ? createLocalPromptOwnershipObserver(activeSession, promptStarted)
     : coordinatedPromptOwnershipObserver(admission.startTurn(activeSession, promptStarted ?? (() => {})));
   ownership.arm();
+  const deliveryId = activity?.start();
   try {
     const turn = activeSession.prompt(content);
     ownership.observeStreaming();
@@ -113,5 +120,6 @@ export async function sendStageUserMessage(
     throw error;
   } finally {
     ownership.dispose();
+    activity?.settle(deliveryId);
   }
 }

package/dist/builtin/workflows/src/runs/foreground/stage-runner-session-options.ts

@@ -10,7 +10,7 @@ interface StageSessionOptionsInput {
   readonly candidate: WorkflowResolvedModelCandidate | undefined;
   readonly restoreSavedModel?: boolean;
   readonly reattachSessionFile: string | undefined;
-  readonly sharedModelRegistry: CreateAgentSessionOptions["modelRegistry"];
+  readonly sharedModelRuntime: CreateAgentSessionOptions["modelRuntime"];
 }
 
 export function buildStageSessionOptions(input: StageSessionOptionsInput): StageOptions | undefined {
@@ -31,8 +31,8 @@ export function buildStageSessionOptions(input: StageSessionOptionsInput): Stage
     options.context = undefined;
     options.forkFromSessionFile = undefined;
   }
-  if (input.sharedModelRegistry !== undefined && options.modelRegistry === undefined) {
-    options.modelRegistry = input.sharedModelRegistry;
+  if (input.sharedModelRuntime !== undefined && options.modelRuntime === undefined) {
+    options.modelRuntime = input.sharedModelRuntime;
   }
   return Object.keys(options).length === 0 ? undefined : options;
 }

package/dist/builtin/workflows/src/runs/foreground/stage-runner-session.ts

@@ -35,11 +35,11 @@ export async function disposeStageSession(current: StageSessionRuntime | undefin
 
 export function asAgentSession(activeSession: StageSessionRuntime | undefined): AgentSession | undefined {
   if (!activeSession) return undefined;
-  const candidate = activeSession as StageSessionRuntime & Partial<Pick<AgentSession, "state" | "sessionManager" | "modelRegistry" | "getContextUsage">>;
+  const candidate = activeSession as StageSessionRuntime & Partial<Pick<AgentSession, "state" | "sessionManager" | "modelRuntime" | "getContextUsage">>;
   if (
     candidate.state !== undefined &&
     candidate.sessionManager !== undefined &&
-    candidate.modelRegistry !== undefined &&
+    candidate.modelRuntime !== undefined &&
     typeof candidate.getContextUsage === "function"
   ) {
     return candidate as AgentSession;

package/dist/builtin/workflows/src/runs/foreground/stage-runner-types.ts

@@ -29,6 +29,12 @@ export type WorkflowFastModeSettingsManager = {
 
 export type StageUserMessageDeliveryAction = "prompt" | "steer" | "followUp" | "handled";
 
+/** Internal session preparation and side-effect-free eligibility boundary. */
+export interface StageUserMessagePreparation {
+  readonly sessionFile?: string;
+  readonly beforePreparation?: () => void;
+}
+
 export interface StageUserMessageDeliveryHooks {
   readonly beforeDelivery?: () => void;
   /** Releases serialized admission once an idle prompt synchronously owns the turn. */
@@ -152,7 +158,17 @@ export interface InternalStageContext extends StageContext {
     content: StageUserMessageContent,
     options?: StageSendUserMessageOptions,
     beforeDelivery?: () => void,
+    preparation?: StageUserMessagePreparation,
   ): Promise<StageUserMessageDeliveryAction>;
+  /**
+   * Internal: subscribe to workflow-owned delivery lifecycle facts for this
+   * stage. An accepted idle delivery reports `delivery_start` before the public
+   * `agent_start` reaches subscribers, so an attached chat can paint Working
+   * for the whole turn rather than only after the SDK event queue drains.
+   */
+  __subscribeDeliveryActivity(
+    listener: (event: import("./stage-delivery-activity.js").StageDeliveryActivityEvent) => void,
+  ): () => void;
   /** Internal: synchronously reject new detached traffic without waiting for active work. */
   __sealGeneration(): void;
   /** Internal: atomically stop detached traffic admission and drain admitted work. */