@bastani/atomic 0.7.17 → 0.8.0-0

package/dist/builtin/workflows/src/runs/shared/concurrency.ts

@@ -0,0 +1,76 @@
+/**
+ * ConcurrencyLimiter — simple semaphore for per-run stage concurrency.
+ *
+ * Limits how many stage methods can execute simultaneously within a single run.
+ * Callers `await limiter.acquire()` before starting, then call `release()` in a
+ * finally block when done. The `run()` helper composes both automatically.
+ */
+
+export class ConcurrencyLimiter {
+  private _running = 0;
+  private readonly _queue: Array<() => void> = [];
+
+  constructor(readonly limit: number) {
+    if (!Number.isInteger(limit) || limit < 1) {
+      throw new RangeError(`ConcurrencyLimiter: limit must be a positive integer, got ${limit}`);
+    }
+  }
+
+  /** Current number of in-flight tasks. */
+  get running(): number {
+    return this._running;
+  }
+
+  /** Number of tasks waiting for a slot. */
+  get queued(): number {
+    return this._queue.length;
+  }
+
+  /**
+   * Acquire a slot.  Resolves immediately when capacity is available; otherwise
+   * queues the caller until a slot is released.
+   */
+  acquire(): Promise<void> {
+    if (this._running < this.limit) {
+      this._running++;
+      return Promise.resolve();
+    }
+    return new Promise<void>((resolve) => {
+      this._queue.push(resolve);
+    });
+  }
+
+  /**
+   * Release a slot.  If callers are queued, the next one is unblocked.
+   */
+  release(): void {
+    const next = this._queue.shift();
+    if (next !== undefined) {
+      // Keep _running the same — we're handing the slot directly to the next waiter.
+      next();
+    } else {
+      this._running--;
+    }
+  }
+
+  /**
+   * Convenience wrapper: acquires a slot, runs `fn`, releases on completion.
+   * Rethrows any error thrown by `fn` after releasing.
+   */
+  async run<T>(fn: () => Promise<T>): Promise<T> {
+    await this.acquire();
+    try {
+      return await fn();
+    } finally {
+      this.release();
+    }
+  }
+}
+
+/**
+ * Create a per-run ConcurrencyLimiter from a resolved config value.
+ * Falls back to the library default (4) when `defaultConcurrency` is absent.
+ */
+export function createRunLimiter(defaultConcurrency?: number): ConcurrencyLimiter {
+  return new ConcurrencyLimiter(defaultConcurrency ?? 4);
+}

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

@@ -0,0 +1,69 @@
+/**
+ * GraphFrontierTracker — infers DAG parents from JavaScript execution order.
+ *
+ * Algorithm:
+ * - Maintain `frontier: Set<string>` — settled stage IDs not yet consumed as parents
+ * - At onSpawn(stageId): snapshot current frontier as parents, store in stageParents
+ * - At onSettle(stageId): remove stage's parents from frontier, add stageId to frontier
+ * - getParents(stageId): return recorded parents
+ */
+
+export interface StageNode {
+  readonly id: string;
+  readonly name: string;
+  readonly parentIds: readonly string[];
+}
+
+export class GraphFrontierTracker {
+  private frontier: Set<string> = new Set();
+  private stageParents: Map<string, string[]> = new Map();
+  private nodes: Map<string, StageNode> = new Map();
+
+  /**
+   * Call when ctx.stage(name) is invoked.
+   * Returns the inferred parent IDs (snapshot of current frontier).
+   */
+  onSpawn(stageId: string, stageName: string): string[] {
+    const parents = Array.from(this.frontier);
+    this.stageParents.set(stageId, parents);
+
+    this.nodes.set(stageId, {
+      id: stageId,
+      name: stageName,
+      parentIds: Object.freeze(parents),
+    });
+
+    return parents;
+  }
+
+  /**
+   * Call when the stage's Promise settles.
+   * Removes the stage's parents from the frontier and adds stageId to frontier.
+   */
+  onSettle(stageId: string): void {
+    const parents = this.stageParents.get(stageId) ?? [];
+    // Remove parents from frontier (they are now consumed)
+    for (const parentId of parents) {
+      this.frontier.delete(parentId);
+    }
+    // Add this stage to the frontier
+    this.frontier.add(stageId);
+  }
+
+  /** Get all recorded nodes as an array. */
+  getNodes(): StageNode[] {
+    return Array.from(this.nodes.values());
+  }
+
+  /** Get parent IDs for a stage. */
+  getParents(stageId: string): string[] {
+    return this.stageParents.get(stageId) ?? [];
+  }
+
+  /** Reset to initial state. */
+  reset(): void {
+    this.frontier.clear();
+    this.stageParents.clear();
+    this.nodes.clear();
+  }
+}

package/dist/builtin/workflows/src/runs/shared/model-fallback.ts

@@ -0,0 +1,293 @@
+import type { CreateAgentSessionOptions } from "@earendil-works/pi-coding-agent";
+import type {
+  WorkflowModelCatalogPort,
+  WorkflowModelInfo,
+  WorkflowModelValue,
+} from "../../shared/types.js";
+
+export interface WorkflowResolvedModelCandidate {
+  readonly id: string;
+  readonly value: WorkflowModelValue;
+}
+
+interface ModelResolutionFailure {
+  readonly input: string;
+  readonly reason: string;
+}
+
+export class WorkflowModelValidationError extends Error {
+  readonly failures: readonly ModelResolutionFailure[];
+
+  constructor(failures: readonly ModelResolutionFailure[]) {
+    super(formatModelValidationError(failures));
+    this.name = "WorkflowModelValidationError";
+    this.failures = failures;
+  }
+}
+
+function formatModelValidationError(failures: readonly ModelResolutionFailure[]): string {
+  const lines = [
+    "workflows: model validation failed before starting workflow.",
+    "Unavailable or ambiguous models:",
+  ];
+  for (const failure of failures) {
+    lines.push(`- ${failure.input} (${failure.reason})`);
+  }
+  return lines.join("\n");
+}
+
+function isModelObject(value: WorkflowModelValue): value is NonNullable<CreateAgentSessionOptions["model"]> {
+  return typeof value !== "string";
+}
+
+export function workflowModelId(value: WorkflowModelValue | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? undefined : trimmed;
+  }
+  return `${String(value.provider)}/${value.id}`;
+}
+
+function normalizeInfo(info: WorkflowModelInfo): WorkflowModelInfo {
+  const fullId = info.fullId.trim().length > 0 ? info.fullId : `${info.provider}/${info.id}`;
+  return { ...info, fullId };
+}
+
+function uniqueByFullId(models: readonly WorkflowModelInfo[]): WorkflowModelInfo[] {
+  const seen = new Set<string>();
+  const result: WorkflowModelInfo[] = [];
+  for (const info of models.map(normalizeInfo)) {
+    if (seen.has(info.fullId)) continue;
+    seen.add(info.fullId);
+    result.push(info);
+  }
+  return result;
+}
+
+function resolveStringModel(
+  rawInput: string,
+  availableModels: readonly WorkflowModelInfo[] | undefined,
+  preferredProvider: string | undefined,
+): WorkflowResolvedModelCandidate | ModelResolutionFailure {
+  const input = rawInput.trim();
+  if (!input) return { input: rawInput, reason: "empty model id" };
+
+  if (availableModels === undefined) {
+    return { id: input, value: input };
+  }
+
+  const models = uniqueByFullId(availableModels);
+  const explicit = models.find((model) => model.fullId === input);
+  if (explicit !== undefined) {
+    return { id: explicit.fullId, value: explicit.model ?? explicit.fullId };
+  }
+
+  if (input.includes("/")) {
+    return { input, reason: "not available" };
+  }
+
+  const byBareId = models.filter((model) => model.id === input);
+  if (byBareId.length === 0) {
+    return { input, reason: "not available" };
+  }
+  if (byBareId.length === 1) {
+    const only = byBareId[0]!;
+    return { id: only.fullId, value: only.model ?? only.fullId };
+  }
+
+  const preferred = preferredProvider === undefined
+    ? undefined
+    : byBareId.find((model) => model.provider === preferredProvider);
+  if (preferred !== undefined) {
+    return { id: preferred.fullId, value: preferred.model ?? preferred.fullId };
+  }
+
+  return {
+    input,
+    reason: `ambiguous: ${byBareId.map((model) => model.fullId).join(", ")}; specify provider/model`,
+  };
+}
+
+function resolveModelValue(
+  value: WorkflowModelValue,
+  availableModels: readonly WorkflowModelInfo[] | undefined,
+  preferredProvider: string | undefined,
+): WorkflowResolvedModelCandidate | ModelResolutionFailure {
+  if (isModelObject(value)) {
+    return { id: workflowModelId(value)!, value };
+  }
+  return resolveStringModel(value, availableModels, preferredProvider);
+}
+
+function isFailure(value: WorkflowResolvedModelCandidate | ModelResolutionFailure): value is ModelResolutionFailure {
+  return "reason" in value;
+}
+
+export function buildModelCandidates(input: {
+  readonly primaryModel?: WorkflowModelValue;
+  readonly fallbackModels?: readonly string[];
+  readonly currentModel?: WorkflowModelValue;
+  readonly availableModels?: readonly WorkflowModelInfo[];
+  readonly preferredProvider?: string;
+}): WorkflowResolvedModelCandidate[] {
+  const rawValues: WorkflowModelValue[] = [];
+  if (input.primaryModel !== undefined) rawValues.push(input.primaryModel);
+  rawValues.push(...(input.fallbackModels ?? []));
+  if (input.currentModel !== undefined) rawValues.push(input.currentModel);
+
+  const failures: ModelResolutionFailure[] = [];
+  const seen = new Set<string>();
+  const candidates: WorkflowResolvedModelCandidate[] = [];
+  for (const value of rawValues) {
+    const resolved = resolveModelValue(value, input.availableModels, input.preferredProvider);
+    if (isFailure(resolved)) {
+      failures.push(resolved);
+      continue;
+    }
+    if (seen.has(resolved.id)) continue;
+    seen.add(resolved.id);
+    candidates.push(resolved);
+  }
+
+  if (failures.length > 0) throw new WorkflowModelValidationError(failures);
+  return candidates;
+}
+
+export function buildModelCandidateIds(input: Parameters<typeof buildModelCandidates>[0]): string[] {
+  return buildModelCandidates(input).map((candidate) => candidate.id);
+}
+
+function catalogUnavailableWarning(): string {
+  return "workflows: model catalog unavailable; using the current selected model for fallback validation.";
+}
+
+export async function buildModelCandidatesFromCatalog(input: {
+  readonly primaryModel?: WorkflowModelValue;
+  readonly fallbackModels?: readonly string[];
+  readonly catalog?: WorkflowModelCatalogPort;
+}): Promise<WorkflowResolvedModelCandidate[]> {
+  const hasExplicitModel = input.primaryModel !== undefined || (input.fallbackModels?.length ?? 0) > 0;
+  if (!hasExplicitModel) return [];
+
+  if (input.catalog === undefined) {
+    return buildModelCandidates({
+      primaryModel: input.primaryModel,
+      fallbackModels: input.fallbackModels,
+    });
+  }
+
+  try {
+    const availableModels = await input.catalog.listModels();
+    return buildModelCandidates({
+      primaryModel: input.primaryModel,
+      fallbackModels: input.fallbackModels,
+      currentModel: input.catalog.currentModel,
+      availableModels,
+      preferredProvider: input.catalog.preferredProvider,
+    });
+  } catch (err) {
+    if (input.catalog.currentModel === undefined) {
+      throw err;
+    }
+    input.catalog.recordWarning?.(catalogUnavailableWarning());
+    return buildModelCandidates({ currentModel: input.catalog.currentModel });
+  }
+}
+
+export async function validateWorkflowModels(input: {
+  readonly requests: readonly {
+    readonly model?: WorkflowModelValue;
+    readonly fallbackModels?: readonly string[];
+  }[];
+  readonly catalog?: WorkflowModelCatalogPort;
+}): Promise<readonly string[]> {
+  const relevant = input.requests.filter(
+    (request) => request.model !== undefined || (request.fallbackModels?.length ?? 0) > 0,
+  );
+  if (relevant.length === 0) return [];
+
+  const warnings: string[] = [];
+  const recordWarning = (warning: string): void => {
+    warnings.push(warning);
+    input.catalog?.recordWarning?.(warning);
+  };
+
+  const failures: ModelResolutionFailure[] = [];
+  const availableModels = input.catalog === undefined ? undefined : await input.catalog.listModels().catch(() => undefined);
+  if (input.catalog !== undefined && availableModels === undefined) {
+    if (input.catalog.currentModel !== undefined) {
+      recordWarning(catalogUnavailableWarning());
+      return warnings;
+    }
+    throw new WorkflowModelValidationError([{ input: "model catalog", reason: "unavailable and no current model is configured" }]);
+  }
+
+  for (const request of relevant) {
+    try {
+      buildModelCandidates({
+        primaryModel: request.model,
+        fallbackModels: request.fallbackModels,
+        currentModel: input.catalog?.currentModel,
+        availableModels,
+        preferredProvider: input.catalog?.preferredProvider,
+      });
+    } catch (err) {
+      if (err instanceof WorkflowModelValidationError) failures.push(...err.failures);
+      else throw err;
+    }
+  }
+
+  if (failures.length > 0) throw new WorkflowModelValidationError(failures);
+  return warnings;
+}
+
+const RETRYABLE_MODEL_FAILURE_PATTERNS: readonly RegExp[] = [
+  /rate\s*limit/i,
+  /too\s*many\s*requests/i,
+  /\b429\b/,
+  /quota/i,
+  /billing/i,
+  /credit/i,
+  /auth(?:entication|orization)?/i,
+  /api\s*key/i,
+  /token\s*expired/i,
+  /forbidden/i,
+  /model.*(?:unavailable|disabled|not\s*found|unknown)/i,
+  /(?:unavailable|disabled|not\s*found|unknown).*model/i,
+  /overloaded/i,
+  /temporarily\s*unavailable/i,
+  /service\s*unavailable/i,
+  /network/i,
+  /fetch/i,
+  /socket/i,
+  /upstream/i,
+  /timeout/i,
+  /timed\s*out/i,
+  /\b50[234]\b/,
+];
+
+const NON_RETRYABLE_FAILURE_PATTERNS: readonly RegExp[] = [
+  /command failed/i,
+  /tests? failed/i,
+  /shell/i,
+  /missing file/i,
+  /no such file/i,
+  /completion guard/i,
+  /cancel/i,
+  /abort/i,
+  /interrupted/i,
+];
+
+export function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+
+export function isRetryableModelFailure(error: string | Error | undefined): boolean {
+  if (error === undefined) return false;
+  const message = typeof error === "string" ? error : error.message;
+  if (!message.trim()) return false;
+  if (NON_RETRYABLE_FAILURE_PATTERNS.some((pattern) => pattern.test(message))) return false;
+  return RETRYABLE_MODEL_FAILURE_PATTERNS.some((pattern) => pattern.test(message));
+}

package/dist/builtin/workflows/src/runs/shared/validate-inputs.ts

@@ -0,0 +1,83 @@
+/**
+ * validateInputs — check a parsed input bag against a workflow's declared
+ * input schema. Used by slash-command and programmatic SDK dispatch paths to
+ * reject malformed input payloads before dispatch.
+ *
+ * Reports:
+ *   - unknown input keys (catches typos like "propmt")
+ *   - wrong-typed values (number/boolean/string/text/select)
+ *   - select values not in the declared choices
+ *   - missing required inputs
+ *
+ * Does NOT coerce: "true" is not a boolean, "3" is not a number. JSON parsing
+ * upstream already preserves types — string-typed values reaching this point
+ * are user mistakes worth surfacing.
+ */
+
+import type { WorkflowInputSchema } from "../../shared/types.js";
+
+export interface ValidationError {
+  key: string;
+  reason: string;
+}
+
+export function validateInputs(
+  schema: Readonly<Record<string, WorkflowInputSchema>>,
+  inputs: Record<string, unknown>,
+): ValidationError[] {
+  const errors: ValidationError[] = [];
+
+  for (const key of Object.keys(inputs)) {
+    if (!(key in schema)) {
+      errors.push({ key, reason: "unknown input key (not declared by this workflow)" });
+    }
+  }
+
+  for (const [key, def] of Object.entries(schema)) {
+    const value = inputs[key];
+
+    if (value === undefined) {
+      if (def.required === true) {
+        errors.push({ key, reason: "required input is missing" });
+      }
+      continue;
+    }
+
+    switch (def.type) {
+      case "text":
+      case "string":
+        if (typeof value !== "string") {
+          errors.push({ key, reason: `expected string, got ${typeName(value)}` });
+        }
+        break;
+      case "number":
+        if (typeof value !== "number" || Number.isNaN(value)) {
+          errors.push({ key, reason: `expected number, got ${typeName(value)}` });
+        }
+        break;
+      case "boolean":
+        if (typeof value !== "boolean") {
+          errors.push({ key, reason: `expected boolean, got ${typeName(value)}` });
+        }
+        break;
+      case "select": {
+        const allowed = def.choices.join(", ");
+        if (typeof value !== "string") {
+          errors.push({ key, reason: `expected one of [${allowed}], got ${typeName(value)}` });
+        } else if (!def.choices.includes(value)) {
+          errors.push({ key, reason: `must be one of [${allowed}]` });
+        }
+        break;
+      }
+    }
+  }
+
+  return errors;
+}
+
+function typeName(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "number" && Number.isNaN(value)) return "NaN";
+  return typeof value;
+}

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

@@ -0,0 +1,170 @@
+/**
+ * Programmatic workflow runner.
+ *
+ * This helper executes a named workflow from an explicit definition object.
+ */
+
+import { homedir } from "node:os";
+import { run, 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";
+import { renderInputsSchema } from "../../shared/render-inputs-schema.js";
+import { validateInputs, type ValidationError } from "./validate-inputs.js";
+import type { CreateAgentSessionOptions } from "@earendil-works/pi-coding-agent";
+import type { StageSessionRuntime } from "../foreground/stage-runner.js";
+import type {
+  WorkflowDetails,
+  WorkflowDetailsStatus,
+  WorkflowInputSchema,
+} from "../../shared/types.js";
+
+export interface WorkflowDefinition {
+  mode: "workflow";
+  workflow: string;
+  inputs?: Record<string, unknown>;
+}
+
+export type WorkflowRunOptions = Omit<ExecutorRunOptions, "adapters" | "store">;
+
+export interface WorkflowOptions {
+  cwd?: string;
+  homeDir?: string;
+  pi?: RuntimeWiringSurface;
+  adapterOptions?: RuntimeAdapterBuildOptions;
+  runOptions?: WorkflowRunOptions;
+  /** Use a deterministic in-memory agent session when no adapter is supplied. */
+  stubAgent?: boolean;
+}
+
+function runOptionsWithAdapters(options: WorkflowOptions): ExecutorRunOptions {
+  const adapterOptions = options.stubAgent === true
+    ? {
+        ...options.adapterOptions,
+        createAgentSession: options.adapterOptions?.createAgentSession ?? createStubAgentSession,
+      }
+    : options.adapterOptions;
+
+  return {
+    ...options.runOptions,
+    adapters: buildRuntimeAdapters(options.pi ?? {}, adapterOptions),
+    store: createStore(),
+  };
+}
+
+async function createStubAgentSession(
+  _options?: CreateAgentSessionOptions,
+): Promise<{ session: StageSessionRuntime }> {
+  let lastAssistantText: string | undefined;
+  const session: StageSessionRuntime = {
+    async prompt(text: string): Promise<string> {
+      lastAssistantText = `stub:workflow:${text}`;
+      return lastAssistantText;
+    },
+    async steer(_text: string): Promise<void> {},
+    async followUp(_text: string): Promise<void> {},
+    subscribe(): () => void {
+      return () => {};
+    },
+    sessionFile: undefined,
+    sessionId: `workflow-stub-${crypto.randomUUID()}`,
+    async setModel(_model): Promise<void> {},
+    setThinkingLevel(_level): void {},
+    async cycleModel() {
+      return undefined;
+    },
+    cycleThinkingLevel() {
+      return undefined;
+    },
+    agent: Object.create(null) as StageSessionRuntime["agent"],
+    model: undefined,
+    thinkingLevel: "off",
+    messages: [] as StageSessionRuntime["messages"],
+    isStreaming: false as StageSessionRuntime["isStreaming"],
+    async navigateTree(): ReturnType<StageSessionRuntime["navigateTree"]> {
+      return { cancelled: true };
+    },
+    async compact(): ReturnType<StageSessionRuntime["compact"]> {
+      return { summary: "", firstKeptEntryId: "", tokensBefore: 0 };
+    },
+    abortCompaction(): void {},
+    async abort(): Promise<void> {},
+    dispose(): void {},
+    getLastAssistantText(): string | undefined {
+      return lastAssistantText;
+    },
+  };
+  return { session };
+}
+
+async function runNamedWorkflow(
+  definition: WorkflowDefinition,
+  options: WorkflowOptions,
+  runOptions: ExecutorRunOptions,
+): Promise<WorkflowDetails> {
+  const discovery = await discoverWorkflows({
+    cwd: options.cwd ?? process.cwd(),
+    homeDir: options.homeDir ?? homedir(),
+  });
+  const workflow = discovery.registry.get(definition.workflow);
+  if (workflow === undefined) {
+    const available = discovery.registry.names();
+    throw new Error(`Workflow not found: "${definition.workflow}". Available: ${available.length > 0 ? available.join(", ") : "(none)"}`);
+  }
+  const inputs = definition.inputs ?? {};
+  const errors = validateInputs(workflow.inputs, inputs);
+  if (errors.length > 0) {
+    throw new Error(formatWorkflowValidationFailure(workflow.name, workflow.inputs, errors));
+  }
+  const result = await run(workflow, inputs, runOptions);
+  return {
+    action: "run",
+    mode: "named",
+    runId: result.runId,
+    status: toWorkflowDetailsStatus(result.status),
+    output: result.result,
+    error: result.error,
+    progress: {
+      completed: result.stages.filter((stage) => stage.status === "completed").length,
+      total: result.stages.length,
+    },
+  };
+}
+
+function formatWorkflowValidationFailure(
+  workflowName: string,
+  schema: Readonly<Record<string, WorkflowInputSchema>>,
+  errors: ValidationError[],
+): string {
+  const entries = Object.entries(schema).map(([name, definition]) => ({
+    name,
+    type: definition.type,
+    description: definition.description,
+    required: definition.required,
+    default: "default" in definition ? definition.default : undefined,
+  }));
+  const lines = errors.map((error) => `  - ${error.key}: ${error.reason}`);
+  return `Invalid inputs for "${workflowName}":\n${lines.join("\n")}\n\n${renderInputsSchema(workflowName, entries)}`;
+}
+
+function toWorkflowDetailsStatus(status: string): WorkflowDetailsStatus {
+  switch (status) {
+    case "completed":
+    case "failed":
+    case "killed":
+      return status;
+    case "running":
+    case "pending":
+      return "running";
+    default:
+      return "failed";
+  }
+}
+
+export async function runWorkflow(
+  definition: WorkflowDefinition,
+  options: WorkflowOptions = {},
+): Promise<WorkflowDetails> {
+  const runOptions = runOptionsWithAdapters(options);
+  return runNamedWorkflow(definition, options, runOptions);
+}