@bastani/atomic 0.8.21-0 → 0.8.22-0

package/dist/builtin/workflows/src/extension/discovery.ts

@@ -20,17 +20,18 @@
  *   const result = await discoverWorkflows({ cwd: process.cwd(), homeDir: os.homedir() });
  */
 
-import { existsSync } from "node:fs";
 import { readdir, stat } from "node:fs/promises";
-import { createRequire } from "node:module";
 import { join, resolve, extname, isAbsolute } from "node:path";
-import { CONFIG_DIR_NAMES, getProjectConfigPaths, isBunBinary } from "@bastani/atomic";
-import { createJiti } from "jiti/static";
+import { CONFIG_DIR_NAMES, getProjectConfigPaths } from "@bastani/atomic";
 import type { WorkflowDefinition } from "../shared/types.js";
-import * as workflowsSdkSurface from "../sdk-surface.js";
 import { createRegistry } from "../workflows/registry.js";
 import type { WorkflowRegistry } from "../workflows/registry.js";
 import * as bundledManifest from "../../builtin/index.js";
+import {
+  collectWorkflowModuleCandidates,
+  loadWorkflowModule,
+  validateWorkflowDefinitionShape as validateDefinitionShape,
+} from "./workflow-module-loader.js";
 
 // ---------------------------------------------------------------------------
 // Public types
@@ -148,37 +149,13 @@ export interface DiscoveryResult {
 // Internal helpers
 // ---------------------------------------------------------------------------
 
-/**
- * Validate a candidate value as a WorkflowDefinition by shape only.
- *
- * Discovery intentionally does not invoke workflow run functions: user-authored
- * run bodies may perform filesystem, network, or other side effects before the
- * first ctx.stage()/ctx.task()/ctx.chain()/ctx.parallel() call. Runtime empty
- * graph validation remains the authoritative guard that a workflow creates at
- * least one stage when it is actually invoked.
- *
- * Returns null when valid, or a human-readable rejection reason string.
- */
-function validateDefinitionShape(value: unknown): string | null {
-  if (value === null || typeof value !== "object") {
-    return "export is not an object";
-  }
-  const d = value as Record<string, unknown>;
-
-  if (d["__piWorkflow"] !== true) {
-    return "missing or incorrect __piWorkflow sentinel (expected true)";
-  }
-  if (typeof d["name"] !== "string" || (d["name"] as string).trim().length === 0) {
-    return "name must be a non-empty string";
-  }
-  if (typeof d["normalizedName"] !== "string" || (d["normalizedName"] as string).trim().length === 0) {
-    return "normalizedName must be a non-empty string";
-  }
-  if (typeof d["run"] !== "function") {
-    return "run must be a function";
-  }
-  return null;
-}
+type WorkflowModuleCandidateRecord = {
+  readonly value: unknown;
+  readonly exportKey: string;
+  readonly kind: DiscoveryKind;
+  readonly filePath?: string;
+  readonly configuredName?: string;
+};
 
 /**
  * Validate DiscoveryConfig shape.
@@ -211,7 +188,7 @@ function validateConfig(config: unknown): string | null {
 
 /** Merge a batch of candidates into registry state, first-seen wins. */
 async function applyBatch(
-  candidates: Array<{ value: unknown; exportKey: string; kind: DiscoveryKind; filePath?: string; configuredName?: string }>,
+  candidates: WorkflowModuleCandidateRecord[],
   registry: WorkflowRegistry,
   sources: DiscoverySource[],
   diagnostics: DiscoveryDiagnostic[],
@@ -255,7 +232,7 @@ async function applyBatch(
 
 /** Merge bundled startup candidates with shape-only validation to keep startup seeding synchronous. */
 function applyBatchShapeOnly(
-  candidates: Array<{ value: unknown; exportKey: string; kind: DiscoveryKind; filePath?: string; configuredName?: string }>,
+  candidates: WorkflowModuleCandidateRecord[],
   registry: WorkflowRegistry,
   sources: DiscoverySource[],
   diagnostics: DiscoveryDiagnostic[],
@@ -312,98 +289,11 @@ async function scanWorkflowDir(dir: string): Promise<string[] | null> {
   }
 }
 
-/** Dynamically import a file and extract all WorkflowDefinition candidates.
- *
- * Strategy: try the default export first, then every named export.
- * Both are collected — a file may export multiple workflow definitions.
- * jiti loads package-authored .ts/.js/.mjs/.cjs files with the same
- * @bastani/workflows authoring import that project/user workflow files use.
- */
-type RunWorkflowFunction = typeof import("../runs/shared/workflow-runner.js").runWorkflow;
-
-const runWorkflow: RunWorkflowFunction = async (...args) => {
-  const { runWorkflow: actualRunWorkflow } = await import("../runs/shared/workflow-runner.js");
-  return actualRunWorkflow(...args);
-};
-
-const require = createRequire(import.meta.url);
-const WORKFLOWS_MODULE_SPECIFIER = "@bastani/workflows";
-// Keep this in sync with index.ts through sdk-surface.ts. runWorkflow stays as
-// a lazy wrapper because the public re-export comes from workflow-runner.ts,
-// which imports this discovery module and would otherwise reintroduce a cycle.
-const WORKFLOWS_SDK_MODULE: Record<string, unknown> = {
-  ...workflowsSdkSurface,
-  runWorkflow,
-};
-const WORKFLOWS_VIRTUAL_MODULES: Record<string, unknown> = {
-  [WORKFLOWS_MODULE_SPECIFIER]: WORKFLOWS_SDK_MODULE,
-};
-
-function resolveWorkflowsSdkAlias(): string {
-  // Resolve the package self-reference through package.json exports instead of
-  // pinning discovery.ts to the current src/extension -> src/index.ts layout.
-  const sdkEntry = require.resolve(WORKFLOWS_MODULE_SPECIFIER);
-  if (!existsSync(sdkEntry)) {
-    throw new Error(
-      `Unable to resolve ${WORKFLOWS_MODULE_SPECIFIER} SDK entry at ${sdkEntry}. ` +
-        "Check the package exports map for the workflows SDK entry.",
-    );
-  }
-  return sdkEntry;
-}
-
-const workflowModuleLoader = createJiti(import.meta.url, {
-  moduleCache: false,
-  // Keep workflow-file import semantics deterministic: jiti owns .ts/.js/.mjs/.cjs
-  // resolution instead of handing some imports back to native import().
-  tryNative: false,
-  ...(isBunBinary
-    ? { virtualModules: WORKFLOWS_VIRTUAL_MODULES }
-    : { alias: { [WORKFLOWS_MODULE_SPECIFIER]: resolveWorkflowsSdkAlias() } }),
-});
-
-function materializeModuleObject(mod: object): Record<string, unknown> {
-  const materialized: Record<string, unknown> = {};
-
-  // jiti's callable API can return an interop namespace proxy. Its own property
-  // descriptors contain the authored export values, but property access may apply
-  // default-export conveniences (and even expose a throwing inherited `then`
-  // getter for `export default null`). Copy own descriptors into a plain object
-  // so candidate collection sees the exact authored exports.
-  for (const key of Object.getOwnPropertyNames(mod)) {
-    const descriptor = Object.getOwnPropertyDescriptor(mod, key);
-    if (descriptor === undefined) continue;
-
-    const value = "value" in descriptor ? descriptor.value : descriptor.get?.call(mod);
-    Object.defineProperty(materialized, key, {
-      value,
-      enumerable: descriptor.enumerable,
-      configurable: true,
-      writable: true,
-    });
-  }
-
-  return materialized;
-}
-
-function normalizeWorkflowModule(mod: unknown): Record<string, unknown> {
-  if (mod !== null && typeof mod === "object") {
-    return materializeModuleObject(mod);
-  }
-  // CJS/default interop can return the exported value directly; wrap it so the
-  // candidate collector can handle it the same way as an ESM default export.
-  return { default: mod };
-}
-
-function loadWorkflowModule(filePath: string): Record<string, unknown> {
-  return normalizeWorkflowModule(workflowModuleLoader(filePath));
-}
-
 async function importWorkflowFile(
   filePath: string,
   kind: DiscoveryKind,
   diagnostics: DiscoveryDiagnostic[],
-): Promise<Array<{ value: unknown; exportKey: string; kind: DiscoveryKind; filePath: string }>> {
+): Promise<WorkflowModuleCandidateRecord[]> {
   let mod: Record<string, unknown>;
   try {
     mod = loadWorkflowModule(filePath);
@@ -417,22 +307,11 @@ async function importWorkflowFile(
     return [];
   }
 
-  const candidates: Array<{ value: unknown; exportKey: string; kind: DiscoveryKind; filePath: string }> = [];
-
-  // Default export first (RFC §5.12: check mod.default before named exports)
-  if ("default" in mod && mod["default"] !== undefined) {
-    candidates.push({ value: mod["default"], exportKey: "default", kind, filePath });
-  }
-
-  // Then all named exports (a file may export multiple workflow definitions)
-  for (const [key, val] of Object.entries(mod)) {
-    if (key === "default") continue;
-    if (val !== undefined) {
-      candidates.push({ value: val, exportKey: key, kind, filePath });
-    }
-  }
-
-  return candidates;
+  return collectWorkflowModuleCandidates(mod).map((candidate) => ({
+    ...candidate,
+    kind,
+    filePath,
+  }));
 }
 
 /** Load workflows from a scanned directory. */
@@ -440,11 +319,11 @@ async function loadFromDir(
   dir: string,
   kind: DiscoveryKind,
   diagnostics: DiscoveryDiagnostic[],
-): Promise<Array<{ value: unknown; exportKey: string; kind: DiscoveryKind; filePath: string }>> {
+): Promise<WorkflowModuleCandidateRecord[]> {
   const files = await scanWorkflowDir(dir);
   if (files === null) return [];
 
-  const all: Array<{ value: unknown; exportKey: string; kind: DiscoveryKind; filePath: string }> = [];
+  const all: WorkflowModuleCandidateRecord[] = [];
   for (const filePath of files) {
     const candidates = await importWorkflowFile(filePath, kind, diagnostics);
     all.push(...candidates);
@@ -458,8 +337,8 @@ async function loadFromPaths(
   kind: DiscoveryKind,
   baseCwd: string,
   diagnostics: DiscoveryDiagnostic[],
-): Promise<Array<{ value: unknown; exportKey: string; kind: DiscoveryKind; filePath: string; configuredName?: string }>> {
-  const all: Array<{ value: unknown; exportKey: string; kind: DiscoveryKind; filePath: string; configuredName?: string }> = [];
+): Promise<WorkflowModuleCandidateRecord[]> {
+  const all: WorkflowModuleCandidateRecord[] = [];
 
   // Normalise to [ { rawPath, configuredName? } ] regardless of input shape
   const entries: Array<{ rawPath: string; configuredName?: string }> = Array.isArray(pathsOrMap)

package/dist/builtin/workflows/src/extension/dispatcher.ts

@@ -9,14 +9,35 @@
 
 import type { WorkflowRegistry } from "../workflows/registry.js";
 import type { StageAdapters } from "../runs/foreground/stage-runner.js";
-import type { Store } from "../shared/store.js";
+import { store as defaultStore, type Store } from "../shared/store.js";
 import type { CancellationRegistry } from "../runs/background/cancellation-registry.js";
-import type { JobTracker } from "../runs/background/job-tracker.js";
-import { resolveInputs } from "../runs/foreground/executor.js";
+import { jobTracker as defaultJobTracker, type JobTracker } from "../runs/background/job-tracker.js";
+import { resolveAndValidateInputs } from "../runs/foreground/executor.js";
 import { runDetached } from "../runs/background/runner.js";
 import type { WorkflowToolResult, WorkflowInputEntry } from "./render-result.js";
+import { deriveInputFields, schemaIsRequired } from "../shared/schema-introspection.js";
 import type { WorkflowToolArgs } from "./index.js";
-import type { WorkflowPersistencePort, WorkflowMcpPort, WorkflowRuntimeConfig, WorkflowModelCatalogPort } from "../shared/types.js";
+import {
+  INTERACTIVE_WORKFLOW_POLICY,
+  type WorkflowExecutionPolicy,
+  type WorkflowPersistencePort,
+  type WorkflowMcpPort,
+  type WorkflowRuntimeConfig,
+  type WorkflowModelCatalogPort,
+} from "../shared/types.js";
+
+type WorkflowRunResult = Extract<WorkflowToolResult, { action: "run" }>;
+
+function failedRunResult(name: string | undefined, runId: string, error: string): WorkflowRunResult {
+  return {
+    action: "run",
+    name,
+    runId,
+    status: "failed",
+    error,
+    stages: [],
+  };
+}
 
 // ---------------------------------------------------------------------------
 // Options
@@ -44,6 +65,10 @@ export interface DispatcherOpts {
   config?: WorkflowRuntimeConfig;
   /** Optional model catalog forwarded to workflow runs for fallback resolution. */
   models?: WorkflowModelCatalogPort;
+  /** Runtime-derived interaction policy for this dispatch. */
+  policy?: WorkflowExecutionPolicy;
+  /** Invocation cwd used for workflow execution. */
+  cwd?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -75,7 +100,7 @@ export async function dispatch(
         description: def.description,
         inputs: Object.entries(def.inputs).map(([iname, schema]) => ({
           name: iname,
-          required: schema.required === true,
+          required: schemaIsRequired(schema),
         })),
       }));
       return { action: "list", items };
@@ -94,16 +119,7 @@ export async function dispatch(
           error: `Workflow not found: "${name}"`,
         };
       }
-      const inputSchema: WorkflowInputEntry[] = Object.entries(def.inputs).map(
-        ([iname, schema]) => ({
-          name: iname,
-          type: schema.type,
-          description: schema.description,
-          required: schema.required,
-          default: "default" in schema ? schema.default : undefined,
-          choices: schema.type === "select" ? schema.choices : undefined,
-        }),
-      );
+      const inputSchema: WorkflowInputEntry[] = deriveInputFields(def.inputs);
       return { action: "inputs", name, inputs: inputSchema };
     }
 
@@ -129,24 +145,24 @@ export async function dispatch(
         };
       }
 
+      const policy = opts.policy ?? INTERACTIVE_WORKFLOW_POLICY;
+
       // Pre-validate inputs against the workflow's declared schema. The
       // executor would otherwise throw the same TypeError deep inside the
       // background promise — silently from the caller's perspective. Catch
       // it here so the dispatch result names what's missing.
       try {
-        resolveInputs(def.inputs, inputs);
+        resolveAndValidateInputs(def.inputs, inputs, `workflow "${def.name}"`);
       } catch (err) {
-        return {
-          action: "run",
-          name: def.name,
-          runId: "",
-          status: "failed",
-          error: err instanceof Error ? err.message : String(err),
-          stages: [],
-        };
+        return failedRunResult(
+          def.name,
+          "",
+          err instanceof Error ? err.message : String(err),
+        );
       }
 
       const accepted = runDetached(def, inputs, {
+        registry: opts.registry,
         adapters: opts.adapters,
         store: opts.store,
         cancellation: opts.cancellation,
@@ -155,7 +171,39 @@ export async function dispatch(
         mcp: opts.mcp,
         config: opts.config,
         models: opts.models,
+        executionMode: policy.mode,
+        cwd: opts.cwd,
       });
+      if (policy.awaitTerminalRun === true) {
+        const tracker = opts.jobs ?? defaultJobTracker;
+        const job = tracker.get(accepted.runId);
+        if (!job) {
+          return failedRunResult(
+            accepted.name,
+            accepted.runId,
+            `Workflow run ${accepted.runId} was accepted but no live job was registered to await`,
+          );
+        }
+        await job.promise;
+        const activeStore = opts.store ?? defaultStore;
+        const snapshot = activeStore.runs().find((run) => run.id === accepted.runId);
+        if (!snapshot) {
+          return failedRunResult(
+            accepted.name,
+            accepted.runId,
+            `Workflow run ${accepted.runId} ended without a retained snapshot`,
+          );
+        }
+        return {
+          action: "run",
+          name: snapshot.name,
+          runId: snapshot.id,
+          status: snapshot.status,
+          result: snapshot.result,
+          error: snapshot.error,
+          stages: snapshot.stages.map((stage) => structuredClone(stage)),
+        };
+      }
       return {
         action: "run",
         name: accepted.name,