@bastani/atomic 0.8.4-0 → 0.8.5-0

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

@@ -112,6 +112,8 @@ export interface InternalStageContext extends StageContext {
    * `undefined` keys when the session has not yet been created.
    */
   __sessionMeta(): { sessionId: string | undefined; sessionFile: string | undefined };
+  /** Internal: live coding-agent session when the adapter returned one. */
+  __agentSession(): AgentSession | undefined;
   /** Internal: selected/effective model and fallback attempt metadata. */
   __modelFallbackMeta(): StageModelFallbackMeta;
   /**
@@ -194,6 +196,20 @@ function lastAssistantTextFromMessages(messages: AgentSession["messages"]): stri
   return undefined;
 }
 
+function asAgentSession(activeSession: StageSessionRuntime | undefined): AgentSession | undefined {
+  if (!activeSession) return undefined;
+  const candidate = activeSession as StageSessionRuntime & Partial<Pick<AgentSession, "state" | "sessionManager" | "modelRegistry" | "getContextUsage">>;
+  if (
+    candidate.state !== undefined &&
+    candidate.sessionManager !== undefined &&
+    candidate.modelRegistry !== undefined &&
+    typeof candidate.getContextUsage === "function"
+  ) {
+    return candidate as AgentSession;
+  }
+  return undefined;
+}
+
 function lastAssistantTextFromSession(
   activeSession: StageSessionRuntime | undefined,
   fallback: string | undefined,
@@ -369,17 +385,25 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
     deferred: PromiseWithResolvers<{ message?: string }>;
   } | null = null;
 
-  // Wire the executor's abort signal to the pause deferred so a kill
-  // (or other forced abort) doesn't leave a paused stage hanging on a
-  // resume signal that will never arrive.
+  // Wire the executor's abort signal to the live SDK session and pause
+  // deferred so a kill (or other forced abort) doesn't leave a paused stage
+  // hanging on a resume signal that will never arrive. Re-use the abort
+  // reason instead of manufacturing a stage-specific error; shutdown/kill is
+  // expected cancellation and should not surface as a noisy per-stage failure.
   if (signal) {
+    const abortReason = (): Error | DOMException | string => {
+      const reason = signal.reason;
+      if (reason instanceof Error || reason instanceof DOMException || typeof reason === "string") {
+        return reason;
+      }
+      return new DOMException("workflow killed", "AbortError");
+    };
     const onAbort = (): void => {
+      void session?.abort().catch(() => {});
       if (!pauseRequest) return;
       const req = pauseRequest;
       pauseRequest = null;
-      req.deferred.reject(
-        new Error(`pi-workflows: stage "${stageName}" aborted while paused`),
-      );
+      req.deferred.reject(abortReason());
     };
     if (signal.aborted) onAbort();
     else signal.addEventListener("abort", onAbort, { once: true });
@@ -475,8 +499,22 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
     // accumulated assistant text when resume carries no message.
     let nextText: string | undefined = initialText;
     while (nextText !== undefined) {
+      const pendingPauseBeforePrompt = pauseRequest;
+      if (pendingPauseBeforePrompt) {
+        const { message } = await pendingPauseBeforePrompt.deferred.promise;
+        nextText = message;
+        if (nextText === undefined) return;
+        continue;
+      }
       try {
         await activeSession.prompt(nextText, sdkOptions);
+        const pendingPauseAfterPrompt = pauseRequest;
+        if (pendingPauseAfterPrompt) {
+          const { message } = await pendingPauseAfterPrompt.deferred.promise;
+          nextText = message;
+          if (nextText === undefined) return;
+          continue;
+        }
         nextText = undefined;
       } catch (err) {
         if (pauseRequest) {
@@ -669,6 +707,10 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
       };
     },
 
+    __agentSession() {
+      return asAgentSession(session);
+    },
+
     __modelFallbackMeta() {
       const attemptedModels = modelAttempts.map((attempt) => attempt.model);
       const model = selectedModel ?? workflowModelId(session?.model);
@@ -682,7 +724,13 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
 
     async __requestPause() {
       if (pauseRequest) return;
-      pauseRequest = { deferred: Promise.withResolvers<{ message?: string }>() };
+      const deferred = Promise.withResolvers<{ message?: string }>();
+      // A shutdown may reject this deferred when no prompt awaiter is actively
+      // observing it (for example a paused pending live stream). Keep the
+      // original promise for real waiters, but mark expected cancellation as
+      // observed so app-exit cleanup stays quiet.
+      void deferred.promise.catch(() => {});
+      pauseRequest = { deferred };
       // Best-effort: stop the current Pi op so the awaiter races abort.
       // The executor's `runTrackedStageCall` re-issues the call once
       // `__resume()` settles `pauseRequest.deferred`.

package/dist/builtin/workflows/src/runs/shared/workflow-runner.ts

@@ -1,11 +1,12 @@
 /**
  * Programmatic workflow runner.
  *
- * This helper executes a named workflow from an explicit definition object.
+ * This helper executes named workflows and direct workflow task definitions
+ * from an explicit object that mirrors the workflow tool surface.
  */
 
 import { homedir } from "node:os";
-import { run, type RunOpts as ExecutorRunOptions } from "../foreground/executor.js";
+import { run, runChain, runParallel, runTask, type RunOpts as ExecutorRunOptions } from "../foreground/executor.js";
 import { buildRuntimeAdapters, type RuntimeAdapterBuildOptions, type RuntimeWiringSurface } from "../../extension/wiring.js";
 import { discoverWorkflows } from "../../extension/discovery.js";
 import { createStore } from "../../shared/store.js";
@@ -14,15 +15,38 @@ import { validateInputs, type ValidationError } from "./validate-inputs.js";
 import type { CreateAgentSessionOptions } from "@bastani/atomic";
 import type { StageSessionRuntime } from "../foreground/stage-runner.js";
 import type {
+  StageOptions,
+  WorkflowChainStep,
   WorkflowDetails,
   WorkflowDetailsStatus,
+  WorkflowDirectOptions,
+  WorkflowDirectTaskItem,
   WorkflowInputSchema,
+  WorkflowMaxOutput,
+  WorkflowOutputMode,
 } from "../../shared/types.js";
 
-export interface WorkflowDefinition {
-  mode: "workflow";
-  workflow: string;
+export interface WorkflowDefinition extends StageOptions {
+  mode?: "workflow" | "named" | "single" | "parallel" | "chain";
+  workflow?: string;
   inputs?: Record<string, unknown>;
+  /** Direct single-task mode, or root task text for direct chain/parallel execution. */
+  task?: WorkflowDirectTaskItem | string;
+  /** Direct top-level parallel mode. */
+  tasks?: readonly WorkflowDirectTaskItem[];
+  /** Direct sequential/parallel chain mode. */
+  chain?: readonly WorkflowChainStep[];
+  chainName?: string;
+  concurrency?: number;
+  failFast?: boolean;
+  /** Chain-only shared artifact directory for relative reads, outputs, and worktree diffs. */
+  chainDir?: string;
+  reads?: readonly string[] | false;
+  output?: string | false;
+  outputMode?: WorkflowOutputMode;
+  worktree?: boolean;
+  maxOutput?: WorkflowMaxOutput;
+  artifacts?: boolean;
 }
 
 export type WorkflowRunOptions = Omit<ExecutorRunOptions, "adapters" | "store">;
@@ -37,7 +61,10 @@ export interface WorkflowOptions {
   stubAgent?: boolean;
 }
 
-function runOptionsWithAdapters(options: WorkflowOptions): ExecutorRunOptions {
+function runOptionsWithAdapters(
+  options: WorkflowOptions,
+  definition?: WorkflowDefinition,
+): ExecutorRunOptions {
   const adapterOptions = options.stubAgent === true
     ? {
         ...options.adapterOptions,
@@ -45,8 +72,26 @@ function runOptionsWithAdapters(options: WorkflowOptions): ExecutorRunOptions {
       }
     : options.adapterOptions;
 
+  const argConcurrency =
+    typeof definition?.concurrency === "number" && Number.isFinite(definition.concurrency)
+      ? Math.max(1, Math.floor(definition.concurrency))
+      : undefined;
+  const config = argConcurrency === undefined
+    ? options.runOptions?.config
+    : {
+        maxDepth: options.runOptions?.config?.maxDepth ?? 4,
+        defaultConcurrency: argConcurrency,
+        persistRuns: options.runOptions?.config?.persistRuns ?? true,
+        statusFile: options.runOptions?.config?.statusFile ?? false,
+        ...(options.runOptions?.config?.statusFilePath !== undefined
+          ? { statusFilePath: options.runOptions.config.statusFilePath }
+          : {}),
+        resumeInFlight: options.runOptions?.config?.resumeInFlight ?? ("ask" as const),
+      };
+
   return {
     ...options.runOptions,
+    ...(config !== undefined ? { config } : {}),
     adapters: buildRuntimeAdapters(options.pi ?? {}, adapterOptions),
     store: createStore(),
   };
@@ -97,19 +142,77 @@ async function createStubAgentSession(
   return { session };
 }
 
+function withoutUndefinedProperties<T extends object>(value: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, field]) => field !== undefined),
+  ) as Partial<T>;
+}
+
+function directOptions(definition: WorkflowDefinition): WorkflowDirectOptions {
+  const {
+    mode: _mode,
+    workflow: _workflow,
+    inputs: _inputs,
+    task,
+    tasks: _tasks,
+    chain: _chain,
+    chainName,
+    concurrency,
+    failFast,
+    chainDir,
+    reads,
+    output,
+    outputMode,
+    worktree,
+    maxOutput,
+    artifacts,
+    ...stageOptions
+  } = definition;
+
+  return {
+    ...withoutUndefinedProperties(stageOptions),
+    ...(typeof task === "string" ? { task } : {}),
+    ...(typeof chainName === "string" ? { chainName } : {}),
+    ...(typeof concurrency === "number" ? { concurrency } : {}),
+    ...(typeof failFast === "boolean" ? { failFast } : {}),
+    ...(typeof chainDir === "string" ? { chainDir } : {}),
+    ...(reads !== undefined ? { reads } : {}),
+    ...(output !== undefined ? { output } : {}),
+    ...(outputMode !== undefined ? { outputMode } : {}),
+    ...(typeof worktree === "boolean" ? { worktree } : {}),
+    ...(maxOutput !== undefined ? { maxOutput } : {}),
+    ...(typeof artifacts === "boolean" ? { artifacts } : {}),
+  };
+}
+
+function hasDirectExecutionMode(definition: WorkflowDefinition): boolean {
+  return (
+    definition.mode === "single" ||
+    definition.mode === "parallel" ||
+    definition.mode === "chain" ||
+    (definition.task !== undefined && typeof definition.task === "object") ||
+    Array.isArray(definition.tasks) ||
+    Array.isArray(definition.chain)
+  );
+}
+
 async function runNamedWorkflow(
   definition: WorkflowDefinition,
   options: WorkflowOptions,
   runOptions: ExecutorRunOptions,
 ): Promise<WorkflowDetails> {
+  const workflowName = definition.workflow;
+  if (typeof workflowName !== "string" || workflowName.length === 0) {
+    throw new Error('Workflow definition must include "workflow" for named workflow execution.');
+  }
   const discovery = await discoverWorkflows({
     cwd: options.cwd ?? process.cwd(),
     homeDir: options.homeDir ?? homedir(),
   });
-  const workflow = discovery.registry.get(definition.workflow);
+  const workflow = discovery.registry.get(workflowName);
   if (workflow === undefined) {
     const available = discovery.registry.names();
-    throw new Error(`Workflow not found: "${definition.workflow}". Available: ${available.length > 0 ? available.join(", ") : "(none)"}`);
+    throw new Error(`Workflow not found: "${workflowName}". Available: ${available.length > 0 ? available.join(", ") : "(none)"}`);
   }
   const inputs = definition.inputs ?? {};
   const errors = validateInputs(workflow.inputs, inputs);
@@ -161,10 +264,43 @@ function toWorkflowDetailsStatus(status: string): WorkflowDetailsStatus {
   }
 }
 
+async function runDirectWorkflow(
+  definition: WorkflowDefinition,
+  runOptions: ExecutorRunOptions,
+): Promise<WorkflowDetails> {
+  const options = directOptions(definition);
+
+  if (Array.isArray(definition.chain) || definition.mode === "chain") {
+    if (!Array.isArray(definition.chain)) {
+      throw new Error('Direct chain workflow definitions must include "chain".');
+    }
+    return runChain(definition.chain, options, runOptions);
+  }
+
+  if (Array.isArray(definition.tasks) || definition.mode === "parallel") {
+    if (!Array.isArray(definition.tasks)) {
+      throw new Error('Direct parallel workflow definitions must include "tasks".');
+    }
+    return runParallel(definition.tasks, options, runOptions);
+  }
+
+  if (typeof definition.task === "object") {
+    return runTask(definition.task, options, runOptions);
+  }
+
+  if (typeof definition.task === "string" && definition.mode === "single") {
+    return runTask({ name: "task", task: definition.task }, options, runOptions);
+  }
+
+  throw new Error('Direct workflow definitions must include "task", "tasks", or "chain".');
+}
+
 export async function runWorkflow(
   definition: WorkflowDefinition,
   options: WorkflowOptions = {},
 ): Promise<WorkflowDetails> {
-  const runOptions = runOptionsWithAdapters(options);
-  return runNamedWorkflow(definition, options, runOptions);
+  const runOptions = runOptionsWithAdapters(options, definition);
+  return hasDirectExecutionMode(definition)
+    ? runDirectWorkflow(definition, runOptions)
+    : runNamedWorkflow(definition, options, runOptions);
 }

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

@@ -39,6 +39,12 @@ export interface Store {
     result?: Record<string, unknown>,
     error?: string,
   ): boolean;
+  /**
+   * Remove a run from live workflow history/status. Any pending HIL prompt
+   * waiter is rejected because the workflow will not resume through that path.
+   * Returns `true` when a run was removed, `false` when the id is unknown.
+   */
+  removeRun(runId: string): boolean;
   recordNotice(notice: WorkflowNotice): void;
   /**
    * Acknowledges a notice by id.
@@ -303,6 +309,29 @@ export function createStore(): Store {
       return true;
     },
 
+    removeRun(runId: string): boolean {
+      const index = _runs.findIndex((r) => r.id === runId);
+      if (index < 0) return false;
+      const run = _runs[index]!;
+      const pending = run.pendingPrompt;
+      if (pending) {
+        const entry = _resolvers.get(pending.id);
+        if (entry) {
+          _resolvers.delete(pending.id);
+          entry.reject(
+            new Error(`pi-workflows: run ${runId} was removed before prompt resolved`),
+          );
+        }
+      }
+      _runs.splice(index, 1);
+      for (let i = _notices.length - 1; i >= 0; i--) {
+        if (_notices[i]?.runId === runId) _notices.splice(i, 1);
+      }
+      _version++;
+      notify();
+      return true;
+    },
+
     recordNotice(notice: WorkflowNotice): void {
       _notices.push(notice);
       _version++;

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

@@ -264,14 +264,35 @@ export interface WorkflowTaskStep extends WorkflowTaskOptions {
   name: string;
 }
 
-export interface WorkflowChainOptions {
+export interface WorkflowSharedTaskDefaults extends StageOptions {
+  /** Optional default output artifact path for steps that do not set one. */
+  output?: string | false;
+  /** Default output mode for steps that do not set one. */
+  outputMode?: WorkflowOutputMode;
+  /** Files the task should read before responding; relative paths resolve via chainDir for chains, otherwise cwd. */
+  reads?: readonly string[] | false;
+  /** Workflow-owned isolation flag; not forwarded to createAgentSession(). */
+  worktree?: boolean;
+  /** Default output truncation limits for steps that do not set one. */
+  maxOutput?: WorkflowMaxOutput;
+  /** Whether to include debug artifacts such as sessions and worktree diffs. */
+  artifacts?: boolean;
+}
+
+export interface WorkflowChainOptions extends WorkflowSharedTaskDefaults {
   /** Shared/root task used for `{task}` in chain steps. */
   task?: string;
+  /** Shared artifact directory for relative reads, outputs, and worktree diffs. */
+  chainDir?: string;
 }
 
-export interface WorkflowParallelOptions {
+export interface WorkflowParallelOptions extends WorkflowSharedTaskDefaults {
   /** Shared fallback task for parallel steps without their own task. */
   task?: string;
+  /** Maximum number of parallel steps to schedule concurrently. */
+  concurrency?: number;
+  /** Stop scheduling additional steps after the first failure. Default: true. */
+  failFast?: boolean;
 }
 
 export type WorkflowOutputMode = "inline" | "file-only";
@@ -379,7 +400,6 @@ export interface WorkflowTaskSessionFields {
   output?: string | false;
   outputMode?: WorkflowOutputMode;
   reads?: readonly string[] | false;
-  progress?: boolean;
   /** Workflow-owned isolation flag; not forwarded to createAgentSession(). */
   worktree?: boolean;
   maxOutput?: WorkflowMaxOutput;
@@ -412,10 +432,11 @@ export interface WorkflowDirectOptions extends StageOptions {
   chainName?: string;
   concurrency?: number;
   failFast?: boolean;
+  /** Chain-only shared artifact directory for relative reads, outputs, and worktree diffs. */
   chainDir?: string;
+  reads?: readonly string[] | false;
   output?: string | false;
   outputMode?: WorkflowOutputMode;
-  progress?: boolean;
   worktree?: boolean;
   maxOutput?: WorkflowMaxOutput;
   artifacts?: boolean;

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

@@ -21,6 +21,59 @@ interface Cell {
   fg: string | null;
 }
 
+type Dir = "u" | "d" | "l" | "r";
+
+function dirsForGlyph(ch: string): Set<Dir> {
+  switch (ch) {
+    case "│":
+      return new Set(["u", "d"]);
+    case "─":
+      return new Set(["l", "r"]);
+    case "╭":
+    case "┌":
+      return new Set(["d", "r"]);
+    case "╮":
+    case "┐":
+      return new Set(["d", "l"]);
+    case "╰":
+    case "└":
+      return new Set(["u", "r"]);
+    case "╯":
+    case "┘":
+      return new Set(["u", "l"]);
+    case "├":
+      return new Set(["u", "d", "r"]);
+    case "┤":
+      return new Set(["u", "d", "l"]);
+    case "┬":
+      return new Set(["d", "l", "r"]);
+    case "┴":
+      return new Set(["u", "l", "r"]);
+    case "┼":
+      return new Set(["u", "d", "l", "r"]);
+    default:
+      return new Set();
+  }
+}
+
+function glyphForDirs(dirs: Set<Dir>): string {
+  const has = (...want: Dir[]) => want.every((d) => dirs.has(d));
+  if (has("u", "d", "l", "r")) return "┼";
+  if (has("u", "d", "r")) return "├";
+  if (has("u", "d", "l")) return "┤";
+  if (has("d", "l", "r")) return "┬";
+  if (has("u", "l", "r")) return "┴";
+  if (has("u", "d")) return "│";
+  if (has("l", "r")) return "─";
+  if (has("d", "r")) return "┌";
+  if (has("d", "l")) return "┐";
+  if (has("u", "r")) return "└";
+  if (has("u", "l")) return "┘";
+  if (has("u") || has("d")) return "│";
+  if (has("l") || has("r")) return "─";
+  return " ";
+}
+
 export class GraphCanvas {
   /** rowIdx → colIdx → Cell. Sparse — empty cells render as a single space. */
   private rows: Map<number, Map<number, Cell>> = new Map();
@@ -39,6 +92,20 @@ export class GraphCanvas {
     if (col > this.maxCol) this.maxCol = col;
   }
 
+  getCell(row: number, col: number): string | null {
+    return this.rows.get(row)?.get(col)?.ch ?? null;
+  }
+
+  mergeCell(row: number, col: number, dirs: readonly Dir[], fg: string | null): void {
+    if (row < 0 || col < 0) return;
+    const existing = this.getCell(row, col);
+    const merged = new Set<Dir>([
+      ...(existing == null ? [] : dirsForGlyph(existing)),
+      ...dirs,
+    ]);
+    this.setCell(row, col, glyphForDirs(merged), fg);
+  }
+
   /**
    * Paint a single character cell, but only if the target cell is empty.
    * Used by the edge plotter so a corner glyph never clobbers a node-card
@@ -58,13 +125,13 @@ export class GraphCanvas {
   hline(row: number, fromCol: number, toCol: number, fg: string | null): void {
     const lo = Math.min(fromCol, toCol);
     const hi = Math.max(fromCol, toCol);
-    for (let c = lo; c <= hi; c++) this.setCellIfEmpty(row, c, "─", fg);
+    for (let c = lo; c <= hi; c++) this.mergeCell(row, c, ["l", "r"], fg);
   }
 
   vline(col: number, fromRow: number, toRow: number, fg: string | null): void {
     const lo = Math.min(fromRow, toRow);
     const hi = Math.max(fromRow, toRow);
-    for (let r = lo; r <= hi; r++) this.setCellIfEmpty(r, col, "│", fg);
+    for (let r = lo; r <= hi; r++) this.mergeCell(r, col, ["u", "d"], fg);
   }
 
   /** Materialise the canvas as one ANSI-styled string per row. */