@bastani/atomic 0.8.14-0 → 0.8.15-0

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

@@ -84,6 +84,8 @@ export interface StageControlHandle {
    * before the session exists are buffered and bound on first attach.
    */
   subscribe(listener: AgentSessionEventListener): () => void;
+  /** Release the underlying SDK session and unregister this direct chat handle. */
+  dispose?(): void | Promise<void>;
 }
 
 /**
@@ -131,8 +133,9 @@ export interface StageControlRegistry {
   /** Build a run-level control aggregate. Cheap; not memoised. */
   run(runId: string): WorkflowRunControlHandle;
   /**
-   * Drop every registration. Used on session boundaries to release
-   * any leaked handles when the host store is cleared.
+   * Drop every registration and invoke each handle's optional dispose hook.
+   * Used on session boundaries to release retained direct chat handles and
+   * their subscriptions when the host store is cleared.
    */
   clear(): void;
 }
@@ -267,7 +270,15 @@ export function createStageControlRegistry(): StageControlRegistry {
       return makeRunHandle(runId);
     },
     clear(): void {
+      const handles = [..._byRun.values()].flatMap((runMap) =>
+        [...runMap.values()].map((entry) => entry.handle),
+      );
       _byRun.clear();
+      for (const handle of handles) {
+        void Promise.resolve(handle.dispose?.()).catch((err: unknown) => {
+          console.warn("pi-workflows: stage handle dispose failed", err);
+        });
+      }
     },
   };
 }

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

@@ -157,7 +157,14 @@ function stripWorkflowOnlyOptions(options: StageOptions | undefined): CreateAgen
   return sessionOptions as CreateAgentSessionOptions;
 }
 
-function missingAdapter(): never {
+type AgentSessionConsumer = "prompt" | "complete";
+
+function missingAdapter(consumer: AgentSessionConsumer): never {
+  if (consumer === "complete") {
+    throw new Error(
+      "pi-workflows: ctx.complete requires either RunOpts.adapters.complete or RunOpts.adapters.agentSession",
+    );
+  }
   throw new Error(
     "pi-workflows: prompt adapter not configured — provide an AgentSessionAdapter via RunOpts.adapters.agentSession",
   );
@@ -457,27 +464,30 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
     return created;
   }
 
-  async function createSession(candidate: WorkflowResolvedModelCandidate | undefined): Promise<StageSessionRuntime> {
+  async function createSession(
+    candidate: WorkflowResolvedModelCandidate | undefined,
+    consumer: AgentSessionConsumer,
+  ): Promise<StageSessionRuntime> {
     const created = adapters.agentSession
       ? await adapters.agentSession.create(stripWorkflowOnlyOptions(stageOptionsForCandidate(candidate)) as StageSessionCreateOptions, {
         ...meta,
         stageOptions: stageOptionsForCandidate(candidate),
       })
-      : missingAdapter();
+      : missingAdapter(consumer);
     return attachSession(created);
   }
 
-  async function ensureSession(): Promise<StageSessionRuntime> {
+  async function ensureSession(consumer: AgentSessionConsumer = "prompt"): Promise<StageSessionRuntime> {
     if (disposed) throw new Error(`pi-workflows: stage "${stageName}" session has been disposed`);
     if (!sessionPromise) {
       sessionPromise = (async () => {
-        if (!hasExplicitModelFallbackConfig) return createSession(undefined);
+        if (!hasExplicitModelFallbackConfig) return createSession(undefined, consumer);
         const candidates = await modelCandidates();
         const first = candidates[0];
-        if (first === undefined) return createSession(undefined);
+        if (first === undefined) return createSession(undefined, consumer);
         activeCandidateIndex = 0;
         selectedModel = first.id;
-        return createSession(first);
+        return createSession(first, consumer);
       })();
     }
     return sessionPromise;
@@ -531,15 +541,19 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
     }
   }
 
-  async function promptWithFallback(text: string, sdkOptions: PromptOptions | undefined): Promise<void> {
+  async function promptWithFallback(
+    text: string,
+    sdkOptions: PromptOptions | undefined,
+    consumer: AgentSessionConsumer = "prompt",
+  ): Promise<void> {
     if (!hasExplicitModelFallbackConfig) {
-      await promptWithPauseResume(await ensureSession(), text, sdkOptions);
+      await promptWithPauseResume(await ensureSession(consumer), text, sdkOptions);
       return;
     }
 
     const candidates = await modelCandidates();
     if (candidates.length === 0) {
-      await promptWithPauseResume(await ensureSession(), text, sdkOptions);
+      await promptWithPauseResume(await ensureSession(consumer), text, sdkOptions);
       return;
     }
 
@@ -548,7 +562,7 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
       const candidate = candidates[index]!;
       const activeSession = session && activeCandidateIndex === index
         ? session
-        : await createSession(candidate);
+        : await createSession(candidate, consumer);
       activeCandidateIndex = index;
       selectedModel = candidate.id;
       try {
@@ -594,13 +608,25 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
     },
 
     async complete(text, completeOpts) {
-      if (!adapters.complete) {
+      if (adapters.complete) {
+        lastAssistantText = await adapters.complete.complete(text, completeOpts, meta);
+        adapterMessages = assistantMessage(lastAssistantText);
+        return lastAssistantText;
+      }
+      if (
+        completeOpts?.model !== undefined ||
+        completeOpts?.maxTokens !== undefined ||
+        completeOpts?.fallbackModels !== undefined
+      ) {
         throw new Error(
-          "pi-workflows: complete adapter not configured — provide a CompleteAdapter via RunOpts.adapters.complete",
+          "pi-workflows: complete options require a CompleteAdapter via RunOpts.adapters.complete",
         );
       }
-      lastAssistantText = await adapters.complete.complete(text, completeOpts, meta);
-      adapterMessages = assistantMessage(lastAssistantText);
+      // Intentional fallback: when a CompleteAdapter is not configured,
+      // `ctx.complete()` can still use the stage AgentSession for simple text
+      // completions. Completion-specific options require the dedicated adapter.
+      await promptWithFallback(text, undefined, "complete");
+      lastAssistantText = lastAssistantTextFromSession(session, lastAssistantText) ?? "";
       return lastAssistantText;
     },
 

package/dist/builtin/workflows/src/runs/shared/graph-inference.ts

@@ -36,6 +36,37 @@ export class GraphFrontierTracker {
     return parents;
   }
 
+  /**
+   * Snapshot the current frontier without registering or mutating a stage.
+   *
+   * Use this when an already-spawned stage needs its parents refreshed before
+   * it starts; `onSpawn` must only be called for the initial `ctx.stage()`
+   * invocation that creates the graph node.
+   */
+  currentParents(): string[] {
+    return Array.from(this.frontier);
+  }
+
+  /**
+   * Replace the recorded parents for a stage before it settles.
+   *
+   * Continuation replay uses source-run topology as authoritative: a replayed
+   * stage may spawn with provisional parents inferred from the continuation's
+   * current frontier, then install the translated source parents before the
+   * stage is recorded or settled.
+   */
+  replaceParents(stageId: string, parentIds: readonly string[]): void {
+    const parents = Array.from(parentIds);
+    this.stageParents.set(stageId, parents);
+    const node = this.nodes.get(stageId);
+    if (node !== undefined) {
+      this.nodes.set(stageId, {
+        ...node,
+        parentIds: Object.freeze(parents),
+      });
+    }
+  }
+
   /**
    * Call when the stage's Promise settles.
    * Removes the stage's parents from the frontier and adds stageId to frontier.

package/dist/builtin/workflows/src/runs/shared/prompt-callsite.ts

@@ -0,0 +1,98 @@
+/**
+ * Prompt replay keys include a normalized workflow-author callsite so two
+ * `ctx.ui.*` prompts with identical descriptors can still replay the matching
+ * answer after continuation. Runtime/framework frames are filtered out; the
+ * selected frame is hashed by the executor and never persisted in raw form.
+ */
+
+import { relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface PromptCallsiteFrame {
+  readonly normalizedPath: string;
+  readonly lineNumber: string;
+  readonly columnNumber: string;
+}
+
+const PACKAGED_WORKFLOW_RUNTIME_ROOTS = [
+  "/dist/builtin/workflows/src/",
+  "/node_modules/@bastani/workflows/src/",
+] as const;
+
+function normalizeSlashes(path: string): string {
+  return path.replace(/\\/g, "/");
+}
+
+export function normalizeStackPath(framePath: string): string {
+  let normalized = framePath;
+  if (normalized.startsWith("file://")) {
+    try {
+      normalized = fileURLToPath(normalized);
+    } catch {
+      try {
+        normalized = decodeURIComponent(new URL(normalized).pathname);
+      } catch {
+        // Keep the original string; it will only be hashed, not persisted raw.
+      }
+    }
+  }
+
+  normalized = normalizeSlashes(normalized).replace(/^\/([A-Za-z]:\/)/, "$1");
+
+  const cwd = normalizeSlashes(process.cwd());
+  if (normalized.startsWith(`${cwd}/`)) {
+    normalized = normalizeSlashes(relative(process.cwd(), normalized));
+  }
+
+  return normalized;
+}
+
+function currentModuleRuntimeRoot(): string | undefined {
+  const modulePath = normalizeStackPath(fileURLToPath(import.meta.url));
+  const markers = ["packages/workflows/src/", ...PACKAGED_WORKFLOW_RUNTIME_ROOTS.map((root) => root.slice(1))];
+  for (const marker of markers) {
+    const index = modulePath.indexOf(marker);
+    if (index >= 0) return modulePath.slice(0, index + marker.length);
+  }
+  return undefined;
+}
+
+const CURRENT_WORKFLOW_RUNTIME_ROOT = currentModuleRuntimeRoot();
+
+export function isWorkflowRuntimeFrame(normalizedPath: string): boolean {
+  const path = normalizeSlashes(normalizedPath);
+  if (CURRENT_WORKFLOW_RUNTIME_ROOT !== undefined && path.startsWith(CURRENT_WORKFLOW_RUNTIME_ROOT)) {
+    return true;
+  }
+  const comparable = path.startsWith("/") ? path : `/${path}`;
+  return PACKAGED_WORKFLOW_RUNTIME_ROOTS.some((runtimeRoot) => comparable.includes(runtimeRoot));
+}
+
+export function parsePromptStackFrame(stackLine: string): PromptCallsiteFrame | undefined {
+  const line = stackLine.trim();
+  if (line.length === 0) return undefined;
+  if (line.includes("node:internal") || line.includes("bun:") || line.includes("(native:")) return undefined;
+
+  const match = line.match(/(\S+):(\d+):(\d+)\)?$/);
+  if (!match) return undefined;
+  const [, rawFramePath, lineNumber, columnNumber] = match;
+  if (rawFramePath === undefined || lineNumber === undefined || columnNumber === undefined) return undefined;
+
+  const normalizedPath = normalizeStackPath(rawFramePath.replace(/^\(/, ""));
+  return { normalizedPath, lineNumber, columnNumber };
+}
+
+export function normalizedPromptCallsiteFrame(stackLine: string): string | undefined {
+  const frame = parsePromptStackFrame(stackLine);
+  if (frame === undefined) return undefined;
+  if (isWorkflowRuntimeFrame(frame.normalizedPath)) return undefined;
+  return `${frame.normalizedPath}:${frame.lineNumber}:${frame.columnNumber}`;
+}
+
+export function selectPromptCallsiteFrame(stack: string): string | undefined {
+  return stack
+    .split("\n")
+    .slice(1)
+    .map(normalizedPromptCallsiteFrame)
+    .find((candidate): candidate is string => candidate !== undefined);
+}

package/dist/builtin/workflows/src/shared/persistence-restore.ts

@@ -278,10 +278,12 @@ function _buildStageSnapshots(
   return [...stageMap.values()];
 }
 
-function replayMetadata(payload: Record<string, unknown>): Pick<StageSnapshot, "replayedFromStageId" | "replayed"> {
+function replayMetadata(payload: Record<string, unknown>): Pick<StageSnapshot, "replayKey" | "replayedFromStageId" | "replayed"> {
+  const replayKey = payload["replayKey"];
   const replayedFromStageId = payload["replayedFromStageId"];
   const replayed = payload["replayed"];
   return {
+    ...(typeof replayKey === "string" ? { replayKey } : {}),
     ...(typeof replayedFromStageId === "string" ? { replayedFromStageId } : {}),
     ...(typeof replayed === "boolean" ? { replayed } : {}),
   };

package/dist/builtin/workflows/src/shared/persistence-session-entries.ts

@@ -42,6 +42,7 @@ export interface StageStartPayload {
   readonly name: string;
   readonly parentIds: readonly string[];
   readonly model?: string;
+  readonly replayKey?: string;
   readonly replayedFromStageId?: string;
   readonly replayed?: boolean;
   readonly ts: number;
@@ -64,6 +65,7 @@ export interface StageEndPayload {
   readonly failureKind?: string;
   readonly failureMessage?: string;
   readonly skippedReason?: string;
+  readonly replayKey?: string;
   readonly replayedFromStageId?: string;
   readonly replayed?: boolean;
 }
@@ -113,6 +115,7 @@ export function appendStageStart(api: PersistenceAPI, payload: StageStartPayload
     name: payload.name,
     parentIds: [...payload.parentIds],
     ...(payload.model !== undefined ? { model: payload.model } : {}),
+    ...(payload.replayKey !== undefined ? { replayKey: payload.replayKey } : {}),
     ...(payload.replayedFromStageId !== undefined ? { replayedFromStageId: payload.replayedFromStageId } : {}),
     ...(payload.replayed !== undefined ? { replayed: payload.replayed } : {}),
     ts: payload.ts,
@@ -147,6 +150,7 @@ export function appendStageEnd(
     ...(payload.failureKind !== undefined ? { failureKind: payload.failureKind } : {}),
     ...(payload.failureMessage !== undefined ? { failureMessage: payload.failureMessage } : {}),
     ...(payload.skippedReason !== undefined ? { skippedReason: payload.skippedReason } : {}),
+    ...(payload.replayKey !== undefined ? { replayKey: payload.replayKey } : {}),
     ...(payload.replayedFromStageId !== undefined ? { replayedFromStageId: payload.replayedFromStageId } : {}),
     ...(payload.replayed !== undefined ? { replayed: payload.replayed } : {}),
   });

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

@@ -63,7 +63,12 @@ export interface StageSnapshot {
   readonly id: string;
   readonly name: string;
   status: StageStatus;
-  readonly parentIds: readonly string[];
+  /**
+   * Parent stage ids. Treat as immutable from consumer code; the executor may
+   * replace the frozen array before a stage starts when late topology inference
+   * refreshes parents, so do not cache this reference across store updates.
+   */
+  parentIds: readonly string[];
   startedAt?: number;
   endedAt?: number;
   durationMs?: number;
@@ -75,6 +80,12 @@ export interface StageSnapshot {
   failureMessage?: string;
   /** Reason for stages skipped by fail-fast/cascade handling. */
   skippedReason?: string;
+  /** Stable continuation replay identity, separate from display name. */
+  replayKey?: string;
+  /** Snapshot-safe prompt answer availability marker; never contains the raw answer. */
+  promptAnswerState?: "available" | "unavailable" | "ambiguous";
+  /** Snapshot-safe descriptor of the prompt UI shown by this stage; never contains the raw answer. */
+  promptFootprint?: PendingPrompt;
   /** Source stage id when this stage was replayed during failed-run continuation. */
   replayedFromStageId?: string;
   /** True when provider work was skipped by continuation replay. */

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

@@ -5,6 +5,7 @@
 
 import type {
   PendingPrompt,
+  PromptKind,
   RunSnapshot,
   StageSnapshot,
   StageNotice,
@@ -43,6 +44,23 @@ export interface RunEndMetadata {
   readonly resumable?: boolean;
 }
 
+export interface PromptAnswerRecord {
+  readonly runId: string;
+  readonly stageId: string;
+  readonly promptId: string;
+  readonly kind: PromptKind;
+  readonly value: unknown;
+  readonly answeredAt: number;
+}
+
+export interface ResolveStagePendingPromptOptions {
+  /**
+   * Whether to retain the response in the live-only prompt answer ledger for
+   * continuation replay. Abort/default resolutions should set this to false.
+   */
+  readonly recordAnswer?: boolean;
+}
+
 export interface Store {
   runs(): readonly RunSnapshot[];
   notices(): readonly WorkflowNotice[];
@@ -118,9 +136,20 @@ export interface Store {
     stageId: string,
     promptId: string,
     response: unknown,
+    options?: ResolveStagePendingPromptOptions,
   ): boolean;
   /** Wait for a stage/node-scoped HIL prompt to resolve. */
   awaitStagePendingPrompt(runId: string, stageId: string, promptId: string): Promise<unknown>;
+  /**
+   * Return the live-only prompt answer record for a completed prompt stage, if
+   * still available. The returned value may contain secrets and must never be
+   * logged, serialized, or copied into snapshots/persistence. Answers remain
+   * resident in memory until explicitly cleared, the run is removed, or the
+   * store is cleared.
+   */
+  getStagePromptAnswer(runId: string, stageId: string): PromptAnswerRecord | undefined;
+  /** Clear the live-only prompt answer record for a stage. Primarily used by tests/cleanup. */
+  clearStagePromptAnswer(runId: string, stageId: string): void;
   /**
    * Record Pi/pi SDK session metadata for a stage after lazy
    * attach. The serializable snapshot tracks this so post-mortem reopen
@@ -188,6 +217,7 @@ export function createStore(): Store {
   const _runs: RunSnapshot[] = [];
   const _notices: WorkflowNotice[] = [];
   const _listeners: Set<(snap: StoreSnapshot) => void> = new Set();
+  const _stagePromptAnswers = new Map<string, PromptAnswerRecord>();
   let _version = 0;
 
   /**
@@ -230,6 +260,10 @@ export function createStore(): Store {
     entry.reject(new Error(reason));
   }
 
+  function stagePromptAnswerKey(runId: string, stageId: string): string {
+    return JSON.stringify([runId, stageId]);
+  }
+
   function rejectStagePrompt(stage: StageSnapshot, reason: string): void {
     const prompt = stage.pendingPrompt;
     if (!prompt) return;
@@ -334,8 +368,10 @@ export function createStore(): Store {
       existing.failureKind = stage.failureKind;
       existing.failureMessage = stage.failureMessage;
       existing.skippedReason = stage.skippedReason;
-      existing.replayedFromStageId = stage.replayedFromStageId;
-      existing.replayed = stage.replayed;
+      if (stage.replayKey !== undefined) existing.replayKey = stage.replayKey;
+      if (stage.promptAnswerState !== undefined) existing.promptAnswerState = stage.promptAnswerState;
+      if (stage.replayedFromStageId !== undefined) existing.replayedFromStageId = stage.replayedFromStageId;
+      if (stage.replayed !== undefined) existing.replayed = stage.replayed;
       delete existing.awaitingInputSince;
       rejectStagePrompt(existing, `pi-workflows: stage ${stage.id} ended before prompt resolved`);
       _version++;
@@ -399,6 +435,9 @@ export function createStore(): Store {
         rejectPrompt(pending.id, `pi-workflows: run ${runId} was removed before prompt resolved`);
       }
       rejectAllStagePrompts(run, `pi-workflows: run ${runId} was removed before prompt resolved`);
+      for (const stage of run.stages) {
+        _stagePromptAnswers.delete(stagePromptAnswerKey(runId, stage.id));
+      }
       _runs.splice(index, 1);
       for (let i = _notices.length - 1; i >= 0; i--) {
         if (_notices[i]?.runId === runId) _notices.splice(i, 1);
@@ -485,6 +524,7 @@ export function createStore(): Store {
       if (isTerminalStageStatus(stage.status)) return false;
       if (stage.pendingPrompt !== undefined) return false;
       stage.pendingPrompt = { ...prompt };
+      stage.promptFootprint = { ...prompt };
       stage.status = "awaiting_input";
       stage.awaitingInputSince = prompt.createdAt;
       _version++;
@@ -497,6 +537,7 @@ export function createStore(): Store {
       stageId: string,
       promptId: string,
       response: unknown,
+      options: ResolveStagePendingPromptOptions = {},
     ): boolean {
       const run = findRun(runId);
       if (!run) return false;
@@ -504,6 +545,20 @@ export function createStore(): Store {
       if (!stage) return false;
       const pending = stage.pendingPrompt;
       if (!pending || pending.id !== promptId) return false;
+      if (options.recordAnswer !== false) {
+        _stagePromptAnswers.set(stagePromptAnswerKey(runId, stageId), {
+          runId,
+          stageId,
+          promptId,
+          kind: pending.kind,
+          value: response,
+          answeredAt: Date.now(),
+        });
+        stage.promptAnswerState = "available";
+      } else {
+        _stagePromptAnswers.delete(stagePromptAnswerKey(runId, stageId));
+        delete stage.promptAnswerState;
+      }
       stage.pendingPrompt = undefined;
       if (stage.status === "awaiting_input") {
         stage.status = "running";
@@ -544,6 +599,24 @@ export function createStore(): Store {
       });
     },
 
+    getStagePromptAnswer(runId: string, stageId: string): PromptAnswerRecord | undefined {
+      return _stagePromptAnswers.get(stagePromptAnswerKey(runId, stageId));
+    },
+
+    clearStagePromptAnswer(runId: string, stageId: string): void {
+      const removed = _stagePromptAnswers.delete(stagePromptAnswerKey(runId, stageId));
+      const run = findRun(runId);
+      const stage = run ? findStage(run, stageId) : undefined;
+      const clearAvailabilityMarker = stage?.promptAnswerState === "available";
+      if (clearAvailabilityMarker) {
+        delete stage.promptAnswerState;
+      }
+      if (removed || clearAvailabilityMarker) {
+        _version++;
+        notify();
+      }
+    },
+
     recordStageSession(
       runId: string,
       stageId: string,
@@ -742,7 +815,7 @@ export function createStore(): Store {
     },
 
     clear(): void {
-      if (_runs.length === 0 && _notices.length === 0 && _resolvers.size === 0) return;
+      if (_runs.length === 0 && _notices.length === 0 && _resolvers.size === 0 && _stagePromptAnswers.size === 0) return;
       _runs.length = 0;
       _notices.length = 0;
       // Reject any outstanding HIL waiters so background promises terminate
@@ -752,6 +825,7 @@ export function createStore(): Store {
         entry.reject(new Error("pi-workflows: store cleared"));
       }
       _resolvers.clear();
+      _stagePromptAnswers.clear();
       _version++;
       notify();
     },

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

@@ -250,7 +250,8 @@ export class GraphView implements Component {
     }
 
     const previousFocusedStageId = this.cachedLayout[this.focusedIndex]?.stage.id;
-    const nextLayout = computeLayout(run.stages, { orientation: "vertical" });
+    const graphStages = this._graphStages(run);
+    const nextLayout = computeLayout(graphStages, { orientation: "vertical" });
     this.cachedLayout = nextLayout;
 
     let focusNeedsReveal = this.pendingEnsureFocusedVisible;
@@ -289,6 +290,21 @@ export class GraphView implements Component {
     this._syncPromptState(run.pendingPrompt);
   }
 
+  private _graphStages(run: RunSnapshot): StageSnapshot[] {
+    const hasStagePrompt = run.stages.some((stage) => stage.pendingPrompt !== undefined);
+    if (!hasStagePrompt) return [...run.stages];
+    return run.stages.filter((stage) => {
+      // Prompt-node injection can leave unstarted author stages in the store
+      // while the prompt node owns focus; hide only these inert placeholders.
+      const isUnstartedPlaceholder =
+        stage.status === "pending" &&
+        stage.startedAt === undefined &&
+        stage.pendingPrompt === undefined &&
+        stage.toolEvents.length === 0;
+      return !isUnstartedPlaceholder;
+    });
+  }
+
   /**
    * Mirror the run's `pendingPrompt` into a UI working state. A new prompt
    * id resets the state (caret + buffer); a cleared prompt drops the state