@bastani/atomic 0.9.3-alpha.1 → 0.9.3-alpha.3

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;

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

@@ -55,6 +55,18 @@ export interface WorkflowModelFallbackFields {
 }
 
 export type WorkflowModelValue = string | object;
+// Standalone authoring contract mirror of shared/types.ts StageUserMessageContent,
+// whose runtime source of truth is derived from AgentSession["sendUserMessage"].
+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;
@@ -223,6 +235,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;
@@ -284,10 +297,17 @@ export interface StageAdapters {
   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;

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

@@ -57,6 +57,28 @@ export interface WorkflowRunContext<TInputs extends WorkflowInputValues = Workfl
     parallel(steps: readonly WorkflowTaskStep[], options?: WorkflowParallelOptions): Promise<WorkflowTaskResult[]>;
     workflow<TChildInputs extends WorkflowInputValues, TChildOutputs extends WorkflowOutputValues, TChildRunInputs extends WorkflowInputValues = TChildInputs>(definition: WorkflowDefinition<TChildInputs, TChildOutputs, TChildRunInputs> & TDefinitionBrand, ...args: WorkflowRunChildArgs<TChildRunInputs>): Promise<WorkflowChildResult<TChildOutputs>>;
     readonly ui: WorkflowUIContext;
+    /**
+     * Durable cached tool execution. Runs arbitrary TypeScript code and caches
+     * the result durably so completed side effects are not repeated on resume.
+     * Only `ctx.*` blocks (tool, ui, stage, task, chain, parallel, workflow)
+     * produce durable checkpoints.
+     *
+     * cross-ref: issue #1498 — DBOS-backed cross-session resumability.
+     */
+    tool: WorkflowToolPrimitive;
+}
+/**
+ * `ctx.tool` primitive signature. Runs an async function and caches the result.
+ */
+export interface WorkflowToolPrimitive {
+    <TValue extends WorkflowSerializableValue>(name: string, args: Readonly<Record<string, WorkflowSerializableValue>>, fn: () => Promise<TValue>, options?: WorkflowToolOptions): Promise<TValue>;
+}
+/** Options for `ctx.tool`. */
+export interface WorkflowToolOptions {
+    readonly retriesAllowed?: boolean;
+    readonly maxAttempts?: number;
+    readonly intervalMs?: number;
+    readonly backoffRate?: number;
 }
 export type WorkflowRunFn<TInputs extends WorkflowInputValues = WorkflowInputValues, TOutputs extends WorkflowOutputValues = WorkflowOutputValues, TDefinitionBrand extends object = {}> = (ctx: WorkflowRunContext<TInputs, TDefinitionBrand, TOutputs>) => Promise<TOutputs> | TOutputs;
 export interface WorkflowRuntimeConfig {
@@ -140,7 +162,7 @@ export interface RunOpts {
     readonly parentRun?: WorkflowParentRunLink;
     readonly onRunStart?: (snapshot: RunSnapshot) => void;
     readonly onStageStart?: (runId: string, snapshot: StageSnapshot) => void;
-    readonly onStageEnd?: (runId: string, snapshot: StageSnapshot) => void;
+    readonly onStageEnd?: (runId: string, snapshot: StageSnapshot) => unknown;
     readonly onRunEnd?: (runId: string, status: RunStatus, result?: WorkflowOutputValues, error?: string, exitReason?: string) => void;
 }
 export interface WorkflowProgressSummary extends WorkflowSerializableObject {

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

@@ -104,6 +104,35 @@ export interface WorkflowRunContext<
     ...args: WorkflowRunChildArgs<TChildRunInputs>
   ): Promise<WorkflowChildResult<TChildOutputs>>;
   readonly ui: WorkflowUIContext;
+  /**
+   * Durable cached tool execution. Runs arbitrary TypeScript code and caches
+   * the result durably so completed side effects are not repeated on resume.
+   * Only `ctx.*` blocks (tool, ui, stage, task, chain, parallel, workflow)
+   * produce durable checkpoints.
+   *
+   * cross-ref: issue #1498 — DBOS-backed cross-session resumability.
+   */
+  tool: WorkflowToolPrimitive;
+}
+
+/**
+ * `ctx.tool` primitive signature. Runs an async function and caches the result.
+ */
+export interface WorkflowToolPrimitive {
+  <TValue extends WorkflowSerializableValue>(
+    name: string,
+    args: Readonly<Record<string, WorkflowSerializableValue>>,
+    fn: () => Promise<TValue>,
+    options?: WorkflowToolOptions,
+  ): Promise<TValue>;
+}
+
+/** Options for `ctx.tool`. */
+export interface WorkflowToolOptions {
+  readonly retriesAllowed?: boolean;
+  readonly maxAttempts?: number;
+  readonly intervalMs?: number;
+  readonly backoffRate?: number;
 }
 
 export type WorkflowRunFn<
@@ -206,7 +235,7 @@ export interface RunOpts {
   readonly parentRun?: WorkflowParentRunLink;
   readonly onRunStart?: (snapshot: RunSnapshot) => void;
   readonly onStageStart?: (runId: string, snapshot: StageSnapshot) => void;
-  readonly onStageEnd?: (runId: string, snapshot: StageSnapshot) => void;
+  readonly onStageEnd?: (runId: string, snapshot: StageSnapshot) => unknown;
   readonly onRunEnd?: (runId: string, status: RunStatus, result?: WorkflowOutputValues, error?: string, exitReason?: string) => void;
 }
 

package/dist/builtin/workflows/src/shared/store-public-types.ts

@@ -30,6 +30,10 @@ export interface RunEndMetadata {
   readonly exitReason?: string;
 }
 
+export interface RunPauseMetadata {
+  readonly resumable?: boolean;
+  readonly exitReason?: string;
+}
 export interface RunBlockedMetadata extends RunEndMetadata {
   readonly failureRecoverability: "recoverable";
   readonly failedStageId: string;
@@ -204,8 +208,8 @@ export interface Store {
   recordStageBlocked(runId: string, stageId: string, blockedBy: string): boolean;
   recordStageUnblocked(runId: string, stageId: string): boolean;
   recordStageNotice(runId: string, stageId: string, notice: StageNotice): boolean;
-  /** Mark a run as `paused`. */
-  recordRunPaused(runId: string, pausedAt?: number): boolean;
+  /** Mark a run as `paused`. Optional metadata can annotate resumable quit/detach state. */
+  recordRunPaused(runId: string, pausedAt?: number, metadata?: RunPauseMetadata): boolean;
   /** Restore a run from `paused` back to `running`. */
   recordRunResumed(runId: string, resumedAt?: number): boolean;
   /** Drop every run and notice. */

package/dist/builtin/workflows/src/shared/store-run-methods.ts

@@ -1,5 +1,5 @@
 import type { WorkflowOutputValues } from "./types.js";
-import type { Store, RunBlockedMetadata, RunEndMetadata } from "./store-public-types.js";
+import type { Store, RunBlockedMetadata, RunEndMetadata, RunPauseMetadata } from "./store-public-types.js";
 import type { RunSnapshot, RunStatus, StoreSnapshot, WorkflowNotice } from "./store-types.js";
 import { accumulatePausedDurationMs, elapsedRunMs } from "./timing.js";
 import { isTopLevelWorkflowRun } from "./run-visibility.js";
@@ -164,14 +164,19 @@ export function createRunStoreMethods(context: StoreContext): RunStoreMethods {
       return true;
     },
 
-    recordRunPaused(runId: string, pausedAt?: number): boolean {
+    recordRunPaused(runId: string, pausedAt?: number, metadata?: RunPauseMetadata): boolean {
       const run = context.findRun(runId);
       if (!run) return false;
       if (TERMINAL_STATUSES.has(run.status)) return false;
-      if (run.status === "paused") return false;
-      run.status = "paused";
-      run.pausedAt = pausedAt ?? Date.now();
-      run.resumedAt = undefined;
+      const wasPaused = run.status === "paused";
+      if (!wasPaused) {
+        run.status = "paused";
+        run.pausedAt = pausedAt ?? Date.now();
+        run.resumedAt = undefined;
+      }
+      if (metadata?.resumable !== undefined) run.resumable = metadata.resumable;
+      if (metadata?.exitReason !== undefined) run.exitReason = metadata.exitReason;
+      if (wasPaused && metadata === undefined) return false;
       context.bumpAndNotify();
       return true;
     },
@@ -186,6 +191,7 @@ export function createRunStoreMethods(context: StoreContext): RunStoreMethods {
       run.pausedDurationMs = accumulatePausedDurationMs(run.pausedDurationMs, run.pausedAt, resumedTs);
       run.resumedAt = resumedTs;
       run.pausedAt = undefined;
+      delete run.exitReason;
       context.bumpAndNotify();
       return true;
     },

package/dist/builtin/workflows/src/shared/types.ts

@@ -21,6 +21,15 @@ export type { TSchema };
 
 export type { AgentSessionEvent, ContextCompactionResult, ModelCycleResult, PromptOptions };
 
+export type StageUserMessageContent = Parameters<AgentSession["sendUserMessage"]>[0];
+
+export type StageUserMessageDelivery = "steer" | "followUp";
+
+export interface StageSendUserMessageOptions {
+  /** Delivery mode to use when the stage session is already streaming. Defaults to followUp. */
+  readonly deliverAs?: StageUserMessageDelivery;
+}
+
 export type WorkflowModelValue = NonNullable<CreateAgentSessionOptions["model"]> | string;
 export type WorkflowModelUsage = AuthoringContract.WorkflowModelUsage;
 export type WorkflowModelAttempt = AuthoringContract.WorkflowModelAttempt;
@@ -178,6 +187,10 @@ export interface StageOptions<TSchemaDef extends TSchema | undefined = TSchema |
   scopedModels?: CreateAgentSessionOptions["scopedModels"];
   sessionManager?: SessionManager;
   settingsManager?: SettingsManager;
+  /** Internal durable resume hook: reopen this exact Atomic/Pi session file instead of forking. */
+  resumeFromSessionFile?: string;
+  /** Internal durable replay key used to map a live LM session to durable resume state. */
+  durableReplayKey?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -299,6 +312,15 @@ export interface StageContext<TSchemaDef extends TSchema | undefined = undefined
   prompt(text: string, options?: StagePromptOptions): Promise<WorkflowStageResult<TSchemaDef>>;
   complete(text: string, options?: CompleteStageOpts): Promise<string>;
 
+  /**
+   * Send a user-authored follow-on message to this stage session.
+   *
+   * When the session is idle this starts a new user turn immediately. When the
+   * session is streaming, the message is queued as a follow-up by default, or
+   * as steering when `deliverAs: "steer"` is provided.
+   */
+  sendUserMessage(content: StageUserMessageContent, options?: StageSendUserMessageOptions): Promise<void>;
+
   /** Queue messages during streaming. */
   steer(text: string): Promise<void>;
   followUp(text: string): Promise<void>;
@@ -381,6 +403,39 @@ export interface WorkflowRunContext<
   ): Promise<WorkflowChildResult<TChildOutputs>>;
   /** HIL primitives for user interaction during a run. */
   readonly ui: WorkflowUIContext;
+  /**
+   * Durable cached tool execution. Runs arbitrary TypeScript code and caches
+   * the result so completed side effects are not repeated on resume.
+   * Only `ctx.*` blocks produce durable checkpoints.
+   *
+   * cross-ref: issue #1498 — DBOS-backed cross-session resumability.
+   */
+  tool: WorkflowToolPrimitive;
+}
+
+/**
+ * `ctx.tool` primitive signature. Runs an async function and caches the result
+ * durably via the durable workflow backend.
+ */
+export interface WorkflowToolPrimitive {
+  <TValue extends WorkflowSerializableValue>(
+    name: string,
+    args: Readonly<Record<string, WorkflowSerializableValue>>,
+    fn: () => Promise<TValue>,
+    options?: WorkflowToolOptions,
+  ): Promise<TValue>;
+}
+
+/** Options for `ctx.tool`. */
+export interface WorkflowToolOptions {
+  /** When true, the tool function is retried on failure. Default false. */
+  readonly retriesAllowed?: boolean;
+  /** Max retry attempts when retriesAllowed is true. Default 3. */
+  readonly maxAttempts?: number;
+  /** Initial retry interval in ms. Default 1000. */
+  readonly intervalMs?: number;
+  /** Backoff multiplier. Default 2. */
+  readonly backoffRate?: number;
 }
 
 // ---------------------------------------------------------------------------

package/dist/builtin/workflows/src/tui/graph-view-constants.ts

@@ -3,7 +3,7 @@ export const HINT_KEYS: Array<{ key: string; label: string }> = [
   { key: "↵", label: "attach" },
   { key: "/", label: "stages" },
   { key: "ctrl+d", label: "detach" },
-  { key: "q", label: "kill" },
+  { key: "q", label: "quit" },
 ];
 
 /**