@bastani/atomic 0.9.2 → 0.9.3-alpha.2

package/dist/builtin/workflows/src/runs/background/quit.ts

@@ -0,0 +1,61 @@
+import { pauseRun, type PauseResult } from "./status.js";
+import { store as defaultStore } from "../../shared/store.js";
+import type { Store } from "../../shared/store-public-types.js";
+import { topLevelWorkflowRuns } from "../../shared/run-visibility.js";
+import type { StageControlRegistry } from "../foreground/stage-control-registry.js";
+import { getDurableBackend } from "../../durable/factory.js";
+
+export type QuitRunResult = PauseResult;
+
+/**
+ * Quit/detach a workflow UI without authoritatively killing the workflow.
+ *
+ * This is the graph-panel/orchestrator close affordance: it pauses any live
+ * stage handles when possible, annotates the run as resumable via
+ * `/workflow resume`, and deliberately does NOT abort through the cancellation
+ * registry or append a terminal `workflow.run.end` entry. `/workflow kill`
+ * remains the only explicit non-resumable manual kill path.
+ */
+export function quitRun(
+  runId: string,
+  opts?: {
+    store?: Store;
+    stageControlRegistry?: StageControlRegistry;
+  },
+): QuitRunResult {
+  const activeStore = opts?.store ?? defaultStore;
+  const run = activeStore.runs().find((candidate) => candidate.id === runId);
+  if (!run) return { ok: false, runId, reason: "not_found" };
+  if (run.endedAt !== undefined) return { ok: false, runId, reason: "already_ended" };
+
+  const paused = pauseRun(runId, opts);
+  if (!paused.ok && paused.reason !== "no_active_stages") return paused;
+  activeStore.recordRunPaused(runId, undefined, { exitReason: "quit", resumable: true });
+  // Mark the durable handle inactive so `/workflow resume` in this or another
+  // session can discover it again. While the run stays `running` in the store
+  // and (after a fresh dispatch) in the durable backend, it is hidden from the
+  // resume selector and refused on resume; quitting flips durable to `paused`.
+  markDurableQuit(runId);
+  return paused.ok ? paused : { ok: true, runId, paused: [] };
+}
+
+function markDurableQuit(runId: string): void {
+  let backend;
+  try {
+    backend = getDurableBackend();
+  } catch {
+    return;
+  }
+  if (backend.getWorkflow(runId) !== undefined) {
+    backend.setWorkflowStatus(runId, "paused", undefined, true);
+  }
+}
+
+export function quitAllRuns(opts?: {
+  store?: Store;
+  stageControlRegistry?: StageControlRegistry;
+}): QuitRunResult[] {
+  const activeStore = opts?.store ?? defaultStore;
+  const inFlight = topLevelWorkflowRuns(activeStore.runs()).filter((r) => r.endedAt === undefined);
+  return inFlight.map((r) => quitRun(r.id, { store: activeStore, stageControlRegistry: opts?.stageControlRegistry }));
+}

package/dist/builtin/workflows/src/runs/background/status.ts

@@ -405,6 +405,7 @@ export function pauseAllRuns(opts?: {
   );
 }
 
+
 // ---------------------------------------------------------------------------
 // interruptRun
 // ---------------------------------------------------------------------------

package/dist/builtin/workflows/src/runs/foreground/executor-direct-helpers.ts

@@ -67,7 +67,7 @@ export async function mapParallelSteps<T>(
   concurrency: number | undefined,
   failFast: boolean | undefined,
   mapper: (step: WorkflowTaskStep) => Promise<T>,
-  onFirstFailure?: (error: unknown) => void,
+  onFirstFailure?: (error: unknown) => void | Promise<void>,
   control?: {
     readonly beforeDequeue?: () => void;
     readonly beforeMap?: () => void;
@@ -92,11 +92,11 @@ export async function mapParallelSteps<T>(
     controlSignal = error;
     if (failFastEnabled) rejectFirstFailure(error);
   };
-  const recordFailure = (index: number, error: unknown): void => {
+  const recordFailure = async (index: number, error: unknown): Promise<void> => {
     failures.push({ index, error });
     if (firstFailure === undefined) {
       firstFailure = error;
-      onFirstFailure?.(error);
+      await onFirstFailure?.(error);
       if (failFastEnabled) rejectFirstFailure(error);
     }
   };
@@ -112,7 +112,7 @@ export async function mapParallelSteps<T>(
           selectControlSignal(err);
           return;
         }
-        recordFailure(nextIndex, err);
+        await recordFailure(nextIndex, err);
         return;
       }
       if (controlSignal !== undefined) return;
@@ -128,7 +128,7 @@ export async function mapParallelSteps<T>(
           selectControlSignal(err);
           return;
         }
-        recordFailure(index, err);
+        await recordFailure(index, err);
         if (failFastEnabled) return;
       }
     }

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

@@ -8,6 +8,21 @@ import { hasExplicitFastModeCandidate } from "./executor-direct-helpers.js";
 import { applyFailureToStage } from "./executor-lifecycle.js";
 import { isTerminalStage } from "./executor-scheduler.js";
 
+export interface TrackedStageCallOptions {
+  readonly eagerSession?: boolean;
+  readonly allowFinalized?: boolean;
+}
+
+export type TrackedStageCaller = <T>(
+  call: () => Promise<T>,
+  eagerSessionOrOptions?: boolean | TrackedStageCallOptions,
+) => Promise<T>;
+
+function normalizeTrackedStageCallOptions(input: boolean | TrackedStageCallOptions | undefined): Required<TrackedStageCallOptions> {
+  if (typeof input === "boolean") return { eagerSession: input, allowFinalized: false };
+  return { eagerSession: input?.eagerSession === true, allowFinalized: input?.allowFinalized === true };
+}
+
 export function createTrackedStageCaller(input: {
   readonly runtime: LiveStageRuntime;
   readonly limiter: ConcurrencyLimiter;
@@ -15,7 +30,7 @@ export function createTrackedStageCaller(input: {
   readonly adapters: StageAdapters;
   readonly hasContinuation: boolean;
   readonly hasScopedParents: boolean;
-}): <T>(call: () => Promise<T>, eagerSession?: boolean) => Promise<T> {
+}): TrackedStageCaller {
   const { runtime } = input;
   const readinessGateEnabled = runtime.opts.confirmStageReadiness !== undefined || runtime.opts.usePromptNodesForUi === true;
   const confirmReadiness = async (): Promise<"advance" | "stay"> => {
@@ -68,22 +83,24 @@ export function createTrackedStageCaller(input: {
     return result;
   };
 
-  return async <T>(call: () => Promise<T>, eagerSession = false): Promise<T> => {
+  return async <T>(call: () => Promise<T>, eagerSessionOrOptions?: boolean | TrackedStageCallOptions): Promise<T> => {
+    const callOptions = normalizeTrackedStageCallOptions(eagerSessionOrOptions);
     runtime.exit.throwIfWorkflowExitSelected();
     await runtime.scheduler.waitForStageRelease(runtime.stageId, runtime.releaseLiveHandle);
-    if (runtime.state.stageFinalized) throw runtime.parallelFailFastError();
+    if (runtime.state.stageFinalized && !callOptions.allowFinalized) throw runtime.parallelFailFastError();
 
     await input.limiter.acquire();
     try {
       await runtime.scheduler.waitForStageRelease(runtime.stageId, runtime.releaseLiveHandle);
       runtime.exit.throwIfWorkflowExitSelected();
-      if (runtime.state.stageFinalized) throw runtime.parallelFailFastError();
+      if (runtime.state.stageFinalized && !callOptions.allowFinalized) throw runtime.parallelFailFastError();
     } catch (err) {
       input.limiter.release();
       throw err;
     }
 
-    if (!input.hasContinuation && runtime.stageSnapshot.startedAt === undefined && !input.hasScopedParents) {
+    const trackStageLifecycle = !runtime.state.stageFinalized;
+    if (trackStageLifecycle && !input.hasContinuation && runtime.stageSnapshot.startedAt === undefined && !input.hasScopedParents) {
       const actualParentIds = runtime.scheduler.tracker.currentParents();
       const sameParents = actualParentIds.length === runtime.stageSnapshot.parentIds.length &&
         actualParentIds.every((value) => runtime.stageSnapshot.parentIds.includes(value));
@@ -92,25 +109,29 @@ export function createTrackedStageCaller(input: {
         runtime.scheduler.setStageParentIds(runtime.stageSnapshot, actualParentIds);
       }
     }
-    runtime.stageSnapshot.status = "running";
-    runtime.stageSnapshot.startedAt = Date.now();
-    const hasNoExplicitModelConfig = input.options?.model === undefined && input.options?.fallbackModels === undefined;
-    const promptAdapterHandlesInitialPrompt = input.adapters.prompt !== undefined;
-    if (eagerSession && !promptAdapterHandlesInitialPrompt && (hasNoExplicitModelConfig || await hasExplicitFastModeCandidate({
-      model: input.options?.model,
-      fallbackModels: input.options?.fallbackModels,
-      models: runtime.opts.models,
-    }))) {
-      try {
-        await runtime.innerCtx.__ensureSession();
-        runtime.captureStageSessionMeta();
-      } catch (err) {
-        if (!(err instanceof Error && err.message.includes("prompt adapter not configured"))) throw err;
+    if (trackStageLifecycle) {
+      runtime.stageSnapshot.status = "running";
+      runtime.stageSnapshot.startedAt = Date.now();
+      const hasNoExplicitModelConfig = input.options?.model === undefined && input.options?.fallbackModels === undefined;
+      const promptAdapterHandlesInitialPrompt = input.adapters.prompt !== undefined;
+      if (callOptions.eagerSession && !promptAdapterHandlesInitialPrompt && (hasNoExplicitModelConfig || await hasExplicitFastModeCandidate({
+        model: input.options?.model,
+        fallbackModels: input.options?.fallbackModels,
+        models: runtime.opts.models,
+      }))) {
+        try {
+          await runtime.innerCtx.__ensureSession();
+          runtime.captureStageSessionMeta();
+        } catch (err) {
+          if (!(err instanceof Error && err.message.includes("prompt adapter not configured"))) throw err;
+        }
       }
+      runtime.applyModelFallbackMeta(runtime.innerCtx.__modelFallbackMeta());
+      runtime.activeStore.recordStageStart(runtime.runId, runtime.stageSnapshot);
+      runtime.appendStageStartOnce();
+    } else {
+      runtime.applyModelFallbackMeta(runtime.innerCtx.__modelFallbackMeta());
     }
-    runtime.applyModelFallbackMeta(runtime.innerCtx.__modelFallbackMeta());
-    runtime.activeStore.recordStageStart(runtime.runId, runtime.stageSnapshot);
-    runtime.appendStageStartOnce();
 
     runtime.mcpScope.apply();
 
@@ -158,37 +179,57 @@ export function createTrackedStageCaller(input: {
       }
       runtime.captureStageSessionMeta();
       runtime.applyModelFallbackMeta(runtime.innerCtx.__modelFallbackMeta());
-      if (runtime.stageFailFastScope?.failed === true && runtime.stageFailFastScope.activeStages.has(runtime.stageId)) {
+      if (trackStageLifecycle && runtime.stageFailFastScope?.failed === true && runtime.stageFailFastScope.activeStages.has(runtime.stageId)) {
         runtime.markSkippedForParallelFailFast();
         throw runtime.parallelFailFastError();
       }
-      if (runtime.state.stageFinalized) throw runtime.parallelFailFastError();
-      runtime.stageSnapshot.status = "completed";
-      const assistantText = runtime.innerCtx.__getLastAssistantText();
-      if (assistantText !== undefined) runtime.stageSnapshot.result = assistantText;
+      if (trackStageLifecycle && runtime.state.stageFinalized) throw runtime.parallelFailFastError();
+      if (trackStageLifecycle) {
+        runtime.stageSnapshot.status = "completed";
+        const assistantText = runtime.innerCtx.__getLastAssistantText();
+        if (assistantText !== undefined) runtime.stageSnapshot.result = assistantText;
+      }
       return result;
     } catch (err) {
       const workflowExitAbort = runtime.signal.aborted ? runtime.exit.currentWorkflowExitAbortReason() : undefined;
       if (workflowExitAbort !== undefined && !runtime.state.skippedForParallelFailFast) {
         runtime.state.stageClosedByWorkflowExit = true;
-        if (!isTerminalStage(runtime.stageSnapshot)) {
+        if (trackStageLifecycle && !isTerminalStage(runtime.stageSnapshot)) {
           runtime.stageSnapshot.status = "skipped";
           runtime.stageSnapshot.skippedReason = runtime.exit.workflowExitSkippedReason(workflowExitAbort.reason);
         }
-      } else if (!runtime.signal.aborted && !runtime.state.skippedForParallelFailFast) {
+      } else if (trackStageLifecycle && !runtime.signal.aborted && !runtime.state.skippedForParallelFailFast) {
         applyFailureToStage(runtime.stageSnapshot, runtime.classifyExecutorFailure(err));
       }
       throw err;
     } finally {
+      // Finalization, handle release, and limiter release are each independent.
+      // If finalizeStageSnapshot() throws, the limiter must still be released
+      // so the concurrency semaphore is not leaked.
+      // cross-ref: issue #1498 — durable finalization failures must not leak the stage limiter.
       runtime.mcpScope.clear();
       runtime.captureStageSessionMeta();
-      runtime.finalizeStageSnapshot();
-      if (runtime.state.stageClosedByWorkflowExit || runtime.exit.currentWorkflowExitAbortReason() !== undefined) {
+      let finalizationError: { readonly thrown: true; readonly error: unknown } | undefined;
+      if (trackStageLifecycle) {
+        try {
+          await runtime.finalizeStageSnapshot();
+        } catch (err) {
+          finalizationError = { thrown: true, error: err };
+        }
+        try {
+          if (runtime.state.stageClosedByWorkflowExit || runtime.exit.currentWorkflowExitAbortReason() !== undefined) {
+            await runtime.releaseLiveHandle().catch(() => {});
+          } else {
+            await runtime.dropStageControlForCompletion().catch(() => {});
+          }
+        } catch {
+          // Best-effort: handle release failure must not prevent limiter release.
+        }
+      } else if (runtime.state.stageClosedByWorkflowExit || runtime.exit.currentWorkflowExitAbortReason() !== undefined) {
         await runtime.releaseLiveHandle().catch(() => {});
-      } else {
-        await runtime.dropStageControlForCompletion().catch(() => {});
       }
       input.limiter.release();
+      if (finalizationError !== undefined) throw finalizationError.error;
     }
   };
 }

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

@@ -1,5 +1,6 @@
 import type { StageContextWithMeta, StageNoticeInput, LiveStageRuntime } from "./executor-stage-types.js";
 import type { InternalStageContext } from "./stage-runner.js";
+import type { TrackedStageCaller } from "./executor-stage-call.js";
 
 function noticeValue(value: unknown): string {
   if (typeof value === "string") return value;
@@ -31,7 +32,7 @@ function compactionMeta(result: unknown): string | undefined {
 
 export function createStageContext(input: {
   readonly runtime: LiveStageRuntime;
-  readonly runTrackedStageCall: <T>(call: () => Promise<T>, eagerSession?: boolean) => Promise<T>;
+  readonly runTrackedStageCall: TrackedStageCaller;
 }): StageContextWithMeta {
   const { runtime } = input;
   const recordStageNotice = (notice: StageNoticeInput): void => {
@@ -43,6 +44,19 @@ export function createStageContext(input: {
   };
 
   const innerCtx: InternalStageContext = runtime.innerCtx;
+  const sendStreamingUserMessage: InternalStageContext["sendUserMessage"] = async (text, options) => {
+    runtime.mcpScope.apply();
+    try {
+      await innerCtx.sendUserMessage(text, options);
+    } finally {
+      try {
+        runtime.mcpScope.clear();
+      } finally {
+        runtime.captureStageSessionMeta();
+        runtime.applyModelFallbackMeta(innerCtx.__modelFallbackMeta());
+      }
+    }
+  };
   return {
     name: innerCtx.name,
     prompt: (text, promptOptions) => {
@@ -53,6 +67,11 @@ export function createStageContext(input: {
       runtime.throwIfStageMutationBlocked();
       return input.runTrackedStageCall(() => innerCtx.complete(text, completeOptions));
     },
+    sendUserMessage: (text, options) => {
+      runtime.throwIfStageMutationBlocked();
+      if (innerCtx.isStreaming) return sendStreamingUserMessage(text, options);
+      return input.runTrackedStageCall(() => innerCtx.sendUserMessage(text, options), { allowFinalized: true });
+    },
     steer: (text) => {
       runtime.throwIfStageMutationBlocked();
       return innerCtx.steer(text);

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

@@ -193,6 +193,7 @@ export function createWorkflowStageFactory(input: {
       if (meta.sessionId !== undefined) stageSnapshot.sessionId = meta.sessionId;
       if (meta.sessionFile !== undefined) stageSnapshot.sessionFile = meta.sessionFile;
       if (meta.sessionId !== undefined || meta.sessionFile !== undefined) input.activeStore.recordStageSession(input.runId, stageId, meta);
+      void input.opts.onStageSession?.(input.runId, stageSnapshot);
     };
     const releaseLiveHandle = async (): Promise<void> => {
       if (state.liveHandleReleased) return;
@@ -226,7 +227,7 @@ export function createWorkflowStageFactory(input: {
       });
     };
 
-    const finalizeStageSnapshot = (): boolean => {
+    const finalizeStageSnapshot = async (): Promise<boolean> => {
       if (state.stageFinalized) return false;
       if (stageSnapshot.endedAt !== undefined && isTerminalStage(stageSnapshot)) {
         state.stageFinalized = true;
@@ -242,7 +243,7 @@ export function createWorkflowStageFactory(input: {
       applyModelFallbackMeta(innerCtx.__modelFallbackMeta());
       input.activeStore.recordStageEnd(input.runId, stageSnapshot);
       stageUiBroker.cancelStagePrompt(input.runId, stageId, new Error(`atomic-workflows: stage ${stageId} completed with pending custom UI`));
-      input.opts.onStageEnd?.(input.runId, stageSnapshot);
+      await input.opts.onStageEnd?.(input.runId, stageSnapshot);
       if (input.opts.persistence) {
         appendStageStartOnce();
         appendStageEnd(input.opts.persistence, {
@@ -325,12 +326,12 @@ export function createWorkflowStageFactory(input: {
     // workflow-exit cleanup and removes the stage from the fail-fast active set.
     // Later paths must not overwrite the terminal skippedReason; they only abort
     // and release idempotent live handles.
-    const skipForParallelFailFast = (): void => {
+    const skipForParallelFailFast = async (): Promise<void> => {
       if (isTerminalStage(stageSnapshot)) return;
       markSkippedForParallelFailFast();
-      finalizeStageSnapshot();
-      void innerCtx.abort().catch(() => {});
-      void dropStageControlForCompletion().catch(() => {});
+      await finalizeStageSnapshot();
+      await innerCtx.abort().catch(() => {});
+      await dropStageControlForCompletion().catch(() => {});
     };
     stageFailFastScope?.activeStages.set(stageId, { skip: skipForParallelFailFast });
     runtime.unregisterWorkflowExitCleanup = input.exit.registerWorkflowExitCleanup(stageId, {
@@ -339,7 +340,7 @@ export function createWorkflowStageFactory(input: {
         if (!isTerminalStage(stageSnapshot)) {
           stageSnapshot.status = "skipped";
           stageSnapshot.skippedReason = input.exit.workflowExitSkippedReason(reason);
-          finalizeStageSnapshot();
+          await finalizeStageSnapshot();
         }
         await innerCtx.abort().catch(() => {});
         await releaseLiveHandle().catch(() => {});

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

@@ -95,6 +95,7 @@ export function createReplayStageContext(input: {
     name,
     prompt: replayText,
     complete: replayText,
+    sendUserMessage: async () => rejectReplayMutation("send a user message"),
     steer: async () => rejectReplayMutation("steer"),
     followUp: async () => rejectReplayMutation("follow up"),
     subscribe: () => () => {},

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

@@ -48,7 +48,7 @@ export interface LiveStageRuntime {
   readonly captureStageSessionMeta: () => void;
   readonly applyModelFallbackMeta: (meta: ReturnType<InternalStageContext["__modelFallbackMeta"]>) => void;
   readonly appendStageStartOnce: () => void;
-  readonly finalizeStageSnapshot: () => boolean;
+  readonly finalizeStageSnapshot: () => Promise<boolean>;
   readonly releaseLiveHandle: () => Promise<void>;
   readonly dropStageControlForCompletion: () => Promise<void>;
   readonly markSkippedForParallelFailFast: () => void;

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

@@ -70,6 +70,22 @@ export interface RunOpts extends Omit<AuthoringContract.RunOpts, "adapters" | "s
   runId?: string;
   /** Replay completed stages from a failed source run, then resume at this stage. */
   continuation?: RunContinuationOpts;
+  /**
+   * Durable workflow backend override (for testing). Defaults to the global
+   * backend resolved by `getDurableBackend()`.
+   *
+   * cross-ref: issue #1498 — DBOS-backed cross-session resumability.
+   */
+  durableBackend?: import("../../durable/backend.js").DurableWorkflowBackend;
+  /**
+   * Durable scope for a child workflow run. When set, the child's internal
+   * `ctx.tool`/`ctx.ui`/`ctx.stage` checkpoints are routed under the root
+   * workflow id with a stable boundary prefix so an interrupted child does
+   * not re-execute completed side effects on parent resume.
+   *
+   * cross-ref: issue #1498.
+   */
+  durableScope?: import("../../durable/scoped-backend.js").DurableScope;
   /** Internal parent linkage for nested ctx.workflow(...) runs. */
   parentRun?: {
     readonly runId: string;
@@ -78,7 +94,8 @@ export interface RunOpts extends Omit<AuthoringContract.RunOpts, "adapters" | "s
   };
   onRunStart?: (snapshot: RunSnapshot) => void;
   onStageStart?: (runId: string, snapshot: StageSnapshot) => void;
-  onStageEnd?: (runId: string, snapshot: StageSnapshot) => void;
+  onStageEnd?: (runId: string, snapshot: StageSnapshot) => unknown;
+  onStageSession?: (runId: string, snapshot: StageSnapshot) => unknown;
   onRunEnd?: (runId: string, status: RunStatus, result?: WorkflowOutputValues, error?: string, exitReason?: string) => void;
 }
 
@@ -94,7 +111,7 @@ export interface RunResult<TOutputs extends WorkflowOutputValues = WorkflowOutpu
 }
 
 export interface ParallelFailFastStage {
-  readonly skip: () => void;
+  readonly skip: () => Promise<void>;
 }
 
 export interface ParallelFailFastScope {

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

@@ -92,6 +92,10 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
       return lastAssistantText;
     },
 
+    async sendUserMessage(text, options) {
+      await controller.sendUserMessage(text, options);
+    },
+
     async steer(text) {
       await (await controller.ensureSession()).steer(text);
     },

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

@@ -1,10 +1,11 @@
 import { getModelDefaultContextWindow, getSupportedContextWindows, SessionManager, shouldApplyCodexFastModeForScope, type AgentSession, type CreateAgentSessionOptions, type PromptOptions, type StructuredOutputCapture } from "@bastani/atomic";
-import type { StageContext, StageExecutionMeta, StageOptions, WorkflowModelAttempt, WorkflowModelCatalogPort } from "../../shared/types.js";
+import type { StageContext, StageExecutionMeta, StageOptions, StageSendUserMessageOptions, StageUserMessageContent, WorkflowModelAttempt, WorkflowModelCatalogPort } from "../../shared/types.js";
 import { buildModelCandidatesFromCatalog, errorMessage, isRetryableModelFailure, workflowModelId, type WorkflowResolvedModelCandidate } from "../shared/model-fallback.js";
 import { WorkflowPromptModelFailure, lastAssistantTextFromSession, latestTerminalAssistantFailureSince } from "./stage-runner-messages.js";
 import { missingAdapter, stripWorkflowOnlyOptions, unavailableSync } from "./stage-runner-options.js";
 import { asAgentSession, disposeStageSession, normalizeSessionCreateResult } from "./stage-runner-session.js";
 import { structuredOutputToolErrorFromEvent } from "./stage-runner-structured-output.js";
+import { sendStageUserMessage } from "./stage-runner-send-user-message.js";
 import type { AgentSessionConsumer, StageModelFallbackMeta, StageRunnerOpts, StageSessionCreateOptions, StageSessionCreateResult, StageSessionEvent, StageSessionRuntime, WorkflowFastModeSettingsManager } from "./stage-runner-types.js";
 
 type PauseRequest = {
@@ -60,7 +61,6 @@ export class StageSessionController {
   get latestStructuredOutputToolError(): string | undefined { return this.latestStructuredOutputToolErrorValue; }
 
   resetStructuredOutputToolError(): void { this.latestStructuredOutputToolErrorValue = undefined; }
-
   requireSession(property: string): StageSessionRuntime {
     if (!this.session) unavailableSync(property);
     return this.session;
@@ -98,6 +98,10 @@ export class StageSessionController {
     return this.ensureSession(consumer);
   }
 
+  async sendUserMessage(content: StageUserMessageContent, options?: StageSendUserMessageOptions): Promise<void> {
+    await sendStageUserMessage(await this.ensureSession("prompt"), content, options);
+  }
+
   async promptWithFallback(
     text: string,
     sdkOptions: PromptOptions | undefined,
@@ -242,14 +246,10 @@ export class StageSessionController {
           fallbackThinkingLevels: undefined,
         };
     if (resumeOptions?.restoreSavedModel) delete optionsForCandidate.model;
-    // Pin a tiered model's natural default (short) context window when neither
-    // the `(1m)` model-string token nor an explicit stage-level contextWindow
-    // selects one for a fresh (non-resumed) stage session. This prevents a
-    // persisted interactive context-window preference (e.g. a previously
-    // selected long tier) from leaking into workflow stages, so a tiered model
-    // uses its short tier unless the author explicitly opts into the long tier
-    // via the `(1m)` token or the numeric contextWindow option. Single-window
-    // models carry no selectable long tier, so they are left untouched.
+    // Pin a tiered model's short default context window for fresh, non-resumed
+    // stage sessions unless the author selected a long tier via `(1m)` or
+    // contextWindow. This prevents persisted interactive long-tier preferences
+    // from leaking into workflow stages; single-window models are left alone.
     if (
       resumeOptions?.restoreSavedModel !== true &&
       this.reattachSessionFile === undefined &&

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

@@ -18,6 +18,8 @@ export function stripWorkflowOnlyOptions(
     fallbackThinkingLevels: _fallbackThinkingLevels,
     context,
     forkFromSessionFile,
+    resumeFromSessionFile,
+    durableReplayKey: _durableReplayKey,
     sessionDir,
     gitWorktreeDir: _gitWorktreeDir,
     baseBranch: _baseBranch,
@@ -26,7 +28,9 @@ export function stripWorkflowOnlyOptions(
   if (sessionOptions.sessionManager === undefined) {
     const cwd = sessionOptions.cwd ?? process.cwd();
     const effectiveSessionDir = sessionDir ?? defaultSessionDir;
-    if (context === "fork" && forkFromSessionFile !== undefined) {
+    if (resumeFromSessionFile !== undefined) {
+      sessionOptions.sessionManager = SessionManager.open(resumeFromSessionFile, effectiveSessionDir, cwd);
+    } else if (context === "fork" && forkFromSessionFile !== undefined) {
       sessionOptions.sessionManager = SessionManager.forkFrom(forkFromSessionFile, cwd, effectiveSessionDir);
     } else if (effectiveSessionDir !== undefined) {
       sessionOptions.sessionManager = SessionManager.create(cwd, effectiveSessionDir);

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

@@ -0,0 +1,25 @@
+import type { StageSendUserMessageOptions, StageUserMessageContent } from "../../shared/types.js";
+import type { StageSessionRuntime } from "./stage-runner-types.js";
+
+function unsupportedContentError(): Error {
+  return new Error("atomic-workflows: this stage session adapter does not support non-string sendUserMessage content; provide a runtime sendUserMessage implementation for text/image blocks.");
+}
+
+export async function sendStageUserMessage(
+  activeSession: StageSessionRuntime,
+  content: StageUserMessageContent,
+  options?: StageSendUserMessageOptions,
+): Promise<void> {
+  const deliverAs = activeSession.isStreaming ? options?.deliverAs ?? "followUp" : options?.deliverAs;
+  if (activeSession.sendUserMessage !== undefined) {
+    await activeSession.sendUserMessage(content, deliverAs === undefined ? undefined : { deliverAs });
+    return;
+  }
+  if (typeof content !== "string") throw unsupportedContentError();
+  if (activeSession.isStreaming) {
+    if (deliverAs === "steer") await activeSession.steer(content);
+    else await activeSession.followUp(content);
+    return;
+  }
+  await activeSession.prompt(content);
+}

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

@@ -6,6 +6,8 @@ import type {
 import type {
   CompleteStageOpts,
   StageContext,
+  StageSendUserMessageOptions,
+  StageUserMessageContent,
   StageExecutionMeta,
   StageOptions,
   WorkflowExecutionMode,
@@ -26,6 +28,7 @@ export type WorkflowFastModeSettingsManager = {
 
 export interface StageSessionRuntime {
   prompt(text: string, options?: PromptOptions): Promise<string | void>;
+  sendUserMessage?(content: StageUserMessageContent, options?: StageSendUserMessageOptions): Promise<void>;
   steer(text: string): Promise<void>;
   followUp(text: string): Promise<void>;
   subscribe(listener: (event: StageSessionEvent) => void): () => void;

package/dist/builtin/workflows/src/shared/authoring-contract-stage.d.ts

@@ -40,6 +40,16 @@ export interface WorkflowModelFallbackFields {
     readonly fallbackThinkingLevels?: readonly string[];
 }
 export type WorkflowModelValue = string | object;
+export interface StageTextContent {
+    readonly type: "text";
+    readonly text: string;
+}
+export interface StageImageContent {
+    readonly type: "image";
+    readonly data: string;
+    readonly mimeType: string;
+}
+export type StageUserMessageContent = string | readonly (StageTextContent | StageImageContent)[];
 export type WorkflowStageResult<TSchemaDef extends TSchema | undefined = undefined> = [TSchemaDef] extends [TSchema] ? Static<TSchemaDef> : string;
 export interface WorkflowModelUsage extends WorkflowSerializableObject {
     readonly input?: number;
@@ -178,6 +188,7 @@ export interface WorkflowPersistencePort {
 }
 export interface StageSessionRuntime {
     prompt(text: string, options?: PromptOptions): Promise<string | void>;
+    sendUserMessage?(content: StageUserMessageContent, options?: StageSendUserMessageOptions): Promise<void>;
     steer(text: string): Promise<void>;
     followUp(text: string): Promise<void>;
     subscribe(listener: (event: never) => void): () => void;
@@ -236,10 +247,15 @@ export interface StageAdapters {
     readonly prompt?: PromptAdapter;
     readonly complete?: CompleteAdapter;
 }
+export type StageUserMessageDelivery = "steer" | "followUp";
+export interface StageSendUserMessageOptions {
+    readonly deliverAs?: StageUserMessageDelivery;
+}
 export interface StageContext<TSchemaDef extends TSchema | undefined = undefined> {
     readonly name: string;
     prompt(text: string, options?: StagePromptOptions): Promise<WorkflowStageResult<TSchemaDef>>;
     complete(text: string, options?: CompleteStageOpts): Promise<string>;
+    sendUserMessage(content: StageUserMessageContent, options?: StageSendUserMessageOptions): Promise<void>;
     steer(text: string): Promise<void>;
     followUp(text: string): Promise<void>;
     subscribe(listener: (event: never) => void): () => void;