@bastani/atomic 0.9.2 → 0.9.3-alpha.2

package/dist/builtin/workflows/src/durable/stage-primitive.ts

@@ -0,0 +1,284 @@
+/** Durable `ctx.stage` / `ctx.task` replay and checkpoint helpers. */
+
+import type { StageContext, StageOptions, WorkflowTaskOptions, WorkflowTaskResult } from "../shared/types.js";
+import type { StageSnapshot } from "../shared/store-types.js";
+import type { WorkflowSerializableValue } from "../shared/types.js";
+import type { DurableWorkflowBackend } from "./backend.js";
+import type { ParallelFailFastScope } from "../runs/foreground/executor-types.js";
+import { durableHash } from "./backend.js";
+import { recordCheckpointDurably } from "./tool-primitive.js";
+import type { DurableStageCheckpoint } from "./types.js";
+
+export interface DurableStageDeps {
+  readonly workflowId: string;
+  readonly backend: DurableWorkflowBackend;
+  readonly nextCheckpointId: () => string;
+  readonly nextReplayKey: (stageName: string) => string;
+  readonly replayKeyForCompletedStage?: (stage: StageSnapshot) => string | undefined;
+}
+
+export async function recordStageCheckpoint(deps: DurableStageDeps, stage: StageSnapshot): Promise<boolean> {
+  if (stage.status !== "completed") return false;
+  const replayKey = deps.replayKeyForCompletedStage?.(stage) ?? stage.replayKey ?? deps.nextReplayKey(stage.name);
+  if (deps.backend.getStageOutput(deps.workflowId, replayKey) !== undefined) return false;
+  const checkpoint: DurableStageCheckpoint = {
+    kind: "stage",
+    workflowId: deps.workflowId,
+    checkpointId: stableCheckpointId("stage", replayKey),
+    name: stage.name,
+    replayKey,
+    output: stageOutput(stage),
+    completedAt: stage.endedAt ?? Date.now(),
+  };
+  await recordCheckpointDurably(deps.backend, checkpoint);
+  return true;
+}
+
+export async function recordStageSessionCheckpoint(deps: DurableStageDeps, stage: StageSnapshot): Promise<boolean> {
+  const replayKey = deps.replayKeyForCompletedStage?.(stage) ?? stage.replayKey ?? deps.nextReplayKey(stage.name);
+  if (stage.sessionFile === undefined) return false;
+  const current = deps.backend.getStageSession(deps.workflowId, replayKey);
+  if (current?.sessionFile === stage.sessionFile) return false;
+  const checkpoint: DurableStageCheckpoint = {
+    kind: "stage",
+    workflowId: deps.workflowId,
+    checkpointId: stageSessionCheckpointId(replayKey, stage),
+    name: stage.name,
+    replayKey,
+    ...(stage.sessionId !== undefined ? { sessionId: stage.sessionId } : {}),
+    sessionFile: stage.sessionFile,
+    completedAt: Date.now(),
+  };
+  await recordCheckpointDurably(deps.backend, checkpoint);
+  return true;
+}
+
+const MID_SESSION_RESUME_PROMPT = "Continue";
+
+function withMidSessionResumePrompt<T extends StageContext>(stage: T, enabled: boolean): T {
+  if (!enabled) return stage;
+  // Do NOT spread `stage` (e.g. `{ ...stage, prompt }`). The live StageContext
+  // exposes lazy getters for `sessionId`/`sessionFile`/`messages`/`isStreaming`
+  // that throw until the underlying SDK session has been created, and a spread
+  // would eagerly read them before the first `prompt()` lands. Override
+  // `prompt` in place instead — `prompt` is a normal configurable own property.
+  const originalPrompt = stage.prompt.bind(stage);
+  Object.defineProperty(stage, "prompt", {
+    value: (_text: string, options?: Parameters<StageContext["prompt"]>[1]) =>
+      originalPrompt(MID_SESSION_RESUME_PROMPT, options as never),
+    writable: true,
+    configurable: true,
+    enumerable: true,
+  });
+  return stage;
+}
+
+
+export function createDurableStagePrimitive(input: {
+  readonly workflowId: string;
+  readonly backend: DurableWorkflowBackend;
+  readonly nextReplayKey: (stageName: string) => string;
+  readonly stage: (name: string, options: StageOptions | undefined, replayKey: string) => StageContext;
+  readonly recordCachedStage?: (name: string, replayKey: string, output: WorkflowSerializableValue) => void;
+}): (name: string, options?: StageOptions) => StageContext {
+  return (name: string, options?: StageOptions): StageContext => {
+    const replayKey = input.nextReplayKey(name);
+    const cached = input.backend.getStageOutput(input.workflowId, replayKey);
+    if (cached !== undefined) {
+      input.recordCachedStage?.(name, replayKey, cached);
+      return createCachedStageContext(name, cached);
+    }
+    const session = input.backend.getStageSession(input.workflowId, replayKey);
+    const isMidSessionResume = session?.sessionFile !== undefined;
+    const liveOptions: StageOptions | undefined = {
+      ...(options ?? {}),
+      durableReplayKey: replayKey,
+      ...(isMidSessionResume ? { resumeFromSessionFile: session.sessionFile } : {}),
+    };
+    const live = withMidSessionResumePrompt(input.stage(name, liveOptions, replayKey), isMidSessionResume);
+    if (options?.schema === undefined) return live;
+    return wrapSchemaStageForDurability({
+      stage: live,
+      workflowId: input.workflowId,
+      backend: input.backend,
+      replayKey,
+      name,
+    });
+  };
+}
+
+export function createDurableTaskPrimitive(input: {
+  readonly workflowId: string;
+  readonly backend: DurableWorkflowBackend;
+  readonly nextReplayKey: (stageName: string) => string;
+  readonly task: (name: string, options: WorkflowTaskOptions, stageFailFastScope?: ParallelFailFastScope) => Promise<WorkflowTaskResult>;
+  readonly recordCachedTask?: (name: string, replayKey: string, output: WorkflowTaskResult) => void;
+}): (name: string, options: WorkflowTaskOptions) => Promise<WorkflowTaskResult> {
+  return async (name: string, options: WorkflowTaskOptions, stageFailFastScope?: ParallelFailFastScope): Promise<WorkflowTaskResult> => {
+    const replayKey = input.nextReplayKey(`task:${name}`);
+    const cached = input.backend.getStageOutput(input.workflowId, replayKey);
+    if (cached !== undefined && isWorkflowTaskResult(cached)) {
+      input.recordCachedTask?.(name, replayKey, cached);
+      return cached;
+    }
+    const session = input.backend.getStageSession(input.workflowId, replayKey);
+    const taskOptions: WorkflowTaskOptions = {
+      ...options,
+      durableReplayKey: replayKey,
+      ...(session?.sessionFile !== undefined ? { resumeFromSessionFile: session.sessionFile } : {}),
+    };
+    const result = await input.task(name, taskOptions, stageFailFastScope);
+    await recordCheckpointDurably(input.backend, {
+      kind: "stage",
+      workflowId: input.workflowId,
+      checkpointId: stableCheckpointId("task", replayKey),
+      name,
+      replayKey,
+      output: result,
+      completedAt: Date.now(),
+    });
+    return result;
+  };
+}
+
+function wrapSchemaStageForDurability(input: {
+  readonly stage: StageContext;
+  readonly workflowId: string;
+  readonly backend: DurableWorkflowBackend;
+  readonly replayKey: string;
+  readonly name: string;
+}): StageContext {
+  const stage = input.stage;
+  const wrapped = Object.create(stage) as StageContext;
+  Object.defineProperty(wrapped, "prompt", {
+    value: async (text: string, options?: Parameters<StageContext["prompt"]>[1]) => {
+      const result = await stage.prompt(text, options);
+      // Checkpoint both structured results AND empty string results so that
+      // a schema-backed stage returning "" is replayed as "" rather than
+      // being dropped (treated as no checkpoint).
+      // cross-ref: issue #1498 — empty string stage outputs must survive durable checkpointing.
+      if (typeof result !== "string" || result.length === 0) {
+        await recordCheckpointDurably(input.backend, {
+          kind: "stage",
+          workflowId: input.workflowId,
+          checkpointId: stableCheckpointId("stage", input.replayKey),
+          name: input.name,
+          replayKey: input.replayKey,
+          output: result as WorkflowSerializableValue,
+          completedAt: Date.now(),
+        });
+      }
+      return result;
+    },
+  });
+  return wrapped;
+}
+
+function createCachedStageContext(name: string, output: WorkflowSerializableValue): StageContext {
+  const text = typeof output === "string" ? output : JSON.stringify(output);
+  const unsupported = async (): Promise<never> => { throw new Error(`Stage "${name}" was replayed from a durable checkpoint; live session operations are unavailable.`); };
+  const cached = {
+    name,
+    async prompt() { return output as Awaited<ReturnType<StageContext["prompt"]>>; },
+    async complete() { return text; },
+    sendUserMessage: unsupported,
+    async steer() {},
+    async followUp() {},
+    subscribe() { return () => {}; },
+    sessionFile: undefined,
+    sessionId: `durable-replay:${name}`,
+    setModel: unsupported,
+    setThinkingLevel() {},
+    cycleModel: unsupported,
+    cycleThinkingLevel() { return undefined; },
+    agent: undefined,
+    model: undefined,
+    thinkingLevel: undefined,
+    messages: [],
+    isStreaming: false,
+    navigateTree: unsupported,
+    compact: unsupported,
+    abortCompaction() {},
+    abort: async () => {},
+  };
+  return cached as never as StageContext;
+}
+
+function stageOutput(stage: StageSnapshot): WorkflowSerializableValue {
+  // Preserve empty string ("") distinctly from undefined (no result).
+  // A stage that completed with empty assistant text must replay as empty,
+  // not be collapsed into a status object.
+  // cross-ref: issue #1498 — empty string stage outputs must survive durable checkpointing.
+  if (stage.result !== undefined) return stage.result;
+  return { status: stage.status, stageId: stage.id };
+}
+
+export function createStageReplayKeyGenerator(_workflowId: string): (stageName: string, stageId?: string) => string {
+  const counts = new Map<string, number>();
+  return (stageName: string, _stageId?: string): string => {
+    const next = (counts.get(stageName) ?? 0) + 1;
+    counts.set(stageName, next);
+    return `stage:${stageName}:${next}`;
+  };
+}
+
+export function stableCheckpointId(kind: string, replayKey: string): string {
+  return `${kind}:${replayKey}`;
+}
+
+function stageSessionCheckpointId(replayKey: string, stage: StageSnapshot): string {
+  return `${stableCheckpointId("stage-session", replayKey)}:${durableHash({
+    sessionId: stage.sessionId ?? "",
+    sessionFile: stage.sessionFile ?? "",
+  })}`;
+}
+
+export function cachedStageId(runId: string, replayKey: string): string {
+  return `durable-${durableHash({ runId, replayKey })}`;
+}
+
+export function recordCachedStageIntoStore(
+  store: import("../shared/store.js").Store,
+  runId: string,
+  name: string,
+  replayKey: string,
+  output: WorkflowSerializableValue,
+  completedStageReplayKeys: Map<string, string>,
+  parentIds?: readonly string[],
+): void {
+  const now = Date.now();
+  const stageId = cachedStageId(runId, replayKey);
+  const result = typeof output === "string" ? output : JSON.stringify(output);
+  const snapshot: StageSnapshot = {
+    id: stageId, name, status: "completed", parentIds: parentIds !== undefined ? Object.freeze([...parentIds]) : [], startedAt: now, endedAt: now, durationMs: 0, result,
+    replayKey, replayed: true, skippedReason: "durable checkpoint replay", toolEvents: [], attachable: false,
+  };
+  store.recordStageStart(runId, snapshot);
+  store.recordStageEnd(runId, snapshot);
+  completedStageReplayKeys.set(stageId, replayKey);
+}
+
+/**
+ * Record a cached durable stage into the store AND register it in the graph
+ * frontier tracker so parent/frontier lineage is preserved for subsequent stages.
+ * cross-ref: issue #1498 — replayed durable stages preserve graph lineage.
+ */
+export function recordCachedStageWithTracker(
+  store: import("../shared/store.js").Store,
+  tracker: import("../engine/graph-inference.js").GraphFrontierTracker,
+  runId: string,
+  name: string,
+  replayKey: string,
+  output: WorkflowSerializableValue,
+  completedStageReplayKeys: Map<string, string>,
+): void {
+  const stageId = cachedStageId(runId, replayKey);
+  const parentIds = tracker.onSpawn(stageId, name);
+  recordCachedStageIntoStore(store, runId, name, replayKey, output, completedStageReplayKeys, parentIds);
+  tracker.onSettle(stageId);
+}
+
+function isWorkflowTaskResult(value: WorkflowSerializableValue): value is WorkflowTaskResult {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  return typeof (value as Record<string, WorkflowSerializableValue>)["text"] === "string";
+}

package/dist/builtin/workflows/src/durable/tool-primitive.ts

@@ -0,0 +1,180 @@
+/**
+ * `ctx.tool` primitive — durable cached execution of arbitrary TypeScript code.
+ *
+ * Runs a user-supplied async function and caches the result durably via the
+ * {@link DurableWorkflowBackend}. On resume, if the tool already completed
+ * (matched by content hash of name + args), the cached result is returned
+ * without re-executing the function — ensuring completed side effects are not
+ * repeated.
+ *
+ * Only `ctx.*` blocks produce durable checkpoints. Anything outside `ctx.*`
+ * (including bare `await someFunction()`) is never saved, matching the issue's
+ * requirement: "checkpoints are effectively only `ctx.*` blocks."
+ *
+ * cross-ref: issue #1498 — "Introduce ctx.tool which allows you to run any
+ * typescript code and cache the result for DBOS."
+ */
+
+import type { WorkflowSerializableValue } from "../shared/types.js";
+import type { DurableWorkflowBackend } from "./backend.js";
+import { durableHash } from "./backend.js";
+import type { DurableCheckpoint, DurableToolCheckpoint } from "./types.js";
+
+/**
+ * Options for `ctx.tool(name, args, fn)`.
+ */
+export interface WorkflowToolOptions {
+  /**
+   * When true, the tool function is retried on failure with exponential
+   * backoff. Defaults to false (matching DBOS step default).
+   */
+  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;
+}
+
+/**
+ * The `ctx.tool` primitive type exposed on {@link WorkflowRunContext}.
+ *
+ * @param name Tool name (for display and checkpoint identity).
+ * @param args Tool arguments (JSON-serializable; included in the content hash).
+ * @param fn The async function to execute. Its return must be JSON-serializable.
+ * @param options Retry configuration.
+ */
+export type WorkflowToolPrimitive = <T extends WorkflowSerializableValue>(
+  name: string,
+  args: Readonly<Record<string, WorkflowSerializableValue>>,
+  fn: () => Promise<T>,
+  options?: WorkflowToolOptions,
+) => Promise<T>;
+
+export interface CreateToolPrimitiveInput {
+  readonly workflowId: string;
+  readonly backend: DurableWorkflowBackend;
+  /** Monotonic checkpoint id counter source. */
+  readonly nextCheckpointId: () => string;
+  /** Abort check; throws if the workflow has been cancelled. */
+  readonly throwIfCancelled: () => void;
+  /** Optional signal for aborting retry backoff sleeps. */
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Create the `ctx.tool` primitive wired to a durable backend.
+ */
+export function createToolPrimitive(input: CreateToolPrimitiveInput): WorkflowToolPrimitive {
+  const ordinals = new Map<string, number>();
+  return async <T extends WorkflowSerializableValue>(
+    name: string,
+    args: Readonly<Record<string, WorkflowSerializableValue>>,
+    fn: () => Promise<T>,
+    options?: WorkflowToolOptions,
+  ): Promise<T> => {
+    input.throwIfCancelled();
+    const callKey = durableHash({ name, args });
+    const ordinal = (ordinals.get(callKey) ?? 0) + 1;
+    ordinals.set(callKey, ordinal);
+    const argsHash = durableHash({ name, args, ordinal });
+
+    // Check for cached result — completed side effects are not repeated.
+    const cached = input.backend.getToolOutput(input.workflowId, argsHash);
+    if (cached !== undefined) return cached as T;
+
+    // Execute (with optional retries).
+    const result = await executeWithRetries(fn, options, input.throwIfCancelled, input.signal);
+
+    // Re-check cancellation after the tool function resolves but BEFORE the
+    // side-effect result is durably checkpointed/returned. A side effect that
+    // completes concurrently with a cancellation must not be recorded as a
+    // durable checkpoint that a resume would silently replay.
+    // cross-ref: issue #1498.
+    input.throwIfCancelled();
+
+    // Record the checkpoint durably.
+    const checkpoint: DurableToolCheckpoint = {
+      kind: "tool",
+      workflowId: input.workflowId,
+      checkpointId: `tool:${argsHash}`,
+      name,
+      argsHash,
+      output: result,
+      completedAt: Date.now(),
+    };
+    await recordCheckpointDurably(input.backend, checkpoint);
+    return result;
+  };
+}
+
+export async function recordCheckpointDurably(backend: DurableWorkflowBackend, checkpoint: DurableCheckpoint): Promise<void> {
+  if (backend.recordCheckpointAsync !== undefined) {
+    await backend.recordCheckpointAsync(checkpoint);
+    return;
+  }
+  backend.recordCheckpoint(checkpoint);
+  await backend.flush?.();
+}
+
+async function executeWithRetries<T>(
+  fn: () => Promise<T>,
+  options: WorkflowToolOptions | undefined,
+  throwIfCancelled: () => void,
+  signal?: AbortSignal,
+): Promise<T> {
+  throwIfCancelled();
+  if (!options?.retriesAllowed) return fn();
+  const maxAttempts = options.maxAttempts ?? 3;
+  const intervalMs = options.intervalMs ?? 1000;
+  const backoffRate = options.backoffRate ?? 2;
+  let lastError: Error | undefined;
+  let delay = intervalMs;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    throwIfCancelled();
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      if (attempt < maxAttempts) {
+        await sleepOrAbort(delay, signal);
+        throwIfCancelled();
+        delay = Math.min(delay * backoffRate, 3600_000);
+      }
+    }
+  }
+  throw lastError ?? new Error("ctx.tool: retries exhausted");
+}
+
+export function sleepOrAbort(ms: number, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) return Promise.reject(signal.reason instanceof Error ? signal.reason : new Error("atomic-workflows: workflow cancelled"));
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const cleanup = (): void => signal?.removeEventListener("abort", onAbort);
+    const finish = (): void => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve();
+    };
+    const fail = (err: Error): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      cleanup();
+      reject(err);
+    };
+    const timer = setTimeout(finish, ms);
+    const onAbort = (): void => fail(signal?.reason instanceof Error ? signal.reason : new Error("atomic-workflows: workflow cancelled"));
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/**
+ * Create a monotonic checkpoint id generator for a workflow.
+ */
+export function createCheckpointIdGenerator(): () => string {
+  let counter = 0;
+  return () => `cp-${++counter}`;
+}

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

@@ -0,0 +1,168 @@
+/**
+ * Durable workflow state types for DBOS-backed cross-session resumability.
+ *
+ * These types describe the checkpoint records that the durable backend stores
+ * for each `ctx.*` operation (tool, ui, stage). Only `ctx.*` blocks produce
+ * durable checkpoints — anything outside `ctx.*` is never saved, matching the
+ * issue's "checkpoints are effectively only `ctx.*` blocks" requirement.
+ *
+ * cross-ref: issue #1498
+ */
+
+import type { WorkflowSerializableValue } from "../shared/types.js";
+
+// ---------------------------------------------------------------------------
+// Top-level workflow identity
+// ---------------------------------------------------------------------------
+
+/**
+ * A resumable top-level workflow. The `workflowId` is the public resume handle
+ * (a run id); internal nested workflow ids are abstracted away from users.
+ */
+export interface DurableWorkflowHandle {
+  /** Top-level workflow id used by `/workflow resume <id>`. */
+  readonly workflowId: string;
+  /** Workflow definition name. */
+  readonly name: string;
+  /** Workflow inputs (JSON-serializable). */
+  readonly inputs: Readonly<WorkflowSerializableObject>;
+  /** Creation timestamp (ms since epoch). */
+  readonly createdAt: number;
+  /** Last update timestamp (ms since epoch). */
+  readonly updatedAt: number;
+  /** Current durable status. */
+  readonly status: DurableWorkflowStatus;
+  /** Session file path that caches this workflow's durable metadata. */
+  readonly sessionFile?: string;
+  /** Number of completed durable checkpoints. */
+  readonly completedCheckpoints: number;
+  /** Number of pending (unanswered) UI prompts. */
+  readonly pendingPrompts: number;
+  /** Optional human-readable label. */
+  readonly label?: string;
+  /** Root workflow id. Omitted or equal to workflowId means top-level. */
+  readonly rootWorkflowId?: string;
+  /** Explicit resumability flag for failed/blocked runs. */
+  readonly resumable?: boolean;
+}
+
+export type DurableWorkflowStatus =
+  | "running"
+  | "paused"
+  | "completed"
+  | "failed"
+  | "cancelled"
+  | "blocked";
+
+// ---------------------------------------------------------------------------
+// Checkpoint records
+// ---------------------------------------------------------------------------
+
+/**
+ * Discriminated union of durable checkpoint records.
+ * Each `ctx.*` operation that should survive cross-session resume writes one
+ * of these. The backend keys checkpoints by (workflowId, kind, checkpointId).
+ */
+export type DurableCheckpoint = DurableToolCheckpoint | DurableUiCheckpoint | DurableStageCheckpoint;
+
+export type DurableCheckpointKind = "tool" | "ui" | "stage";
+
+/** A `ctx.tool(...)` result cached durably. */
+export interface DurableToolCheckpoint {
+  readonly kind: "tool";
+  readonly workflowId: string;
+  /** Unique checkpoint id within the workflow (monotonic). */
+  readonly checkpointId: string;
+  /** Tool name for display/debugging. */
+  readonly name: string;
+  /** Deterministic hash of the tool arguments for idempotency. */
+  readonly argsHash: string;
+  /** Cached tool output (JSON-serializable). */
+  readonly output: WorkflowSerializableValue;
+  readonly completedAt: number;
+}
+
+/** A `ctx.ui.*` user response cached durably. */
+export interface DurableUiCheckpoint {
+  readonly kind: "ui";
+  readonly workflowId: string;
+  readonly checkpointId: string;
+  /** UI prompt kind (input/confirm/select/editor/custom). */
+  readonly promptKind: UiPromptKind;
+  /** Prompt message shown to the user. */
+  readonly message: string;
+  /** Deterministic hash of the prompt identity for replay matching. */
+  readonly promptHash: string;
+  /** User response (JSON-serializable). */
+  readonly response: WorkflowSerializableValue;
+  readonly completedAt: number;
+}
+
+/** A `ctx.stage(...)` / `ctx.task(...)` durable checkpoint or resumable session marker. */
+export interface DurableStageCheckpoint {
+  readonly kind: "stage";
+  readonly workflowId: string;
+  readonly checkpointId: string;
+  /** Stage name for display. */
+  readonly name: string;
+  /** Stable replay key (matches existing continuation replay semantics). */
+  readonly replayKey: string;
+  /** Stage output text or structured result when the stage completed. */
+  readonly output?: WorkflowSerializableValue;
+  /** Resumable Atomic/Pi session metadata for in-progress LM stages. */
+  readonly sessionId?: string;
+  readonly sessionFile?: string;
+  readonly completedAt: number;
+}
+
+export type UiPromptKind = "input" | "confirm" | "select" | "editor" | "custom";
+
+// ---------------------------------------------------------------------------
+// Serializable helpers
+// ---------------------------------------------------------------------------
+
+export type WorkflowSerializableObject = Readonly<Record<string, WorkflowSerializableValue>>;
+
+// ---------------------------------------------------------------------------
+// Resume catalog entry (cached on session JSONL)
+// ---------------------------------------------------------------------------
+
+/**
+ * Durable workflow metadata cached as a `workflow.durable.checkpoint` session
+ * entry. This is the session-file cache described by the issue — it lets a new
+ * session discover resumable workflows without scanning the full DBOS system
+ * database. DBOS remains the checkpoint source of truth; this cache mirrors
+ * the minimal top-level metadata needed for `/workflow resume` discovery.
+ */
+export interface DurableCheckpointEntry {
+  readonly type: "workflow.durable.checkpoint";
+  readonly workflowId: string;
+  readonly name: string;
+  readonly inputs: WorkflowSerializableObject;
+  readonly status: DurableWorkflowStatus;
+  readonly completedCheckpoints: number;
+  readonly pendingPrompts: number;
+  readonly label?: string;
+  readonly rootWorkflowId?: string;
+  readonly resumable?: boolean;
+  readonly ts: number;
+}
+
+/**
+ * Resume catalog entry for the cross-session `/workflow resume` selector.
+ * Built from durable checkpoint entries found across session files.
+ */
+export interface ResumableWorkflowEntry {
+  readonly workflowId: string;
+  readonly name: string;
+  readonly inputs?: WorkflowSerializableObject;
+  readonly status: DurableWorkflowStatus;
+  readonly completedCheckpoints: number;
+  readonly pendingPrompts: number;
+  readonly sessionFile?: string;
+  readonly label?: string;
+  readonly rootWorkflowId?: string;
+  readonly resumable?: boolean;
+  readonly createdAt: number;
+  readonly updatedAt: number;
+}