@bastani/atomic 0.8.23 → 0.8.24-alpha.2

package/dist/builtin/workflows/src/runs/foreground/executor.ts

@@ -7,6 +7,7 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
 import { CONFIG_DIR_NAME, createAskUserQuestionToolDefinition, isCodexFastModeCandidateModelId } from "@bastani/atomic";
 import { stageUiBroker } from "../../shared/stage-ui-broker.js";
+import { isBrandedWorkflowDefinition, stampWorkflowDefinition } from "../../workflows/define-workflow.js";
 import { buildStagePromptAdapter } from "../../shared/stage-prompt.js";
 import type {
   WorkflowDefinition,
@@ -43,6 +44,7 @@ import type {
   WorkflowSerializableValue,
 } from "../../shared/types.js";
 import type { InternalStageContext, StageAdapters } from "./stage-runner.js";
+import type * as AuthoringContract from "../../shared/authoring-contract.js";
 import type {
   RunStatus,
   StageNotice,
@@ -102,7 +104,7 @@ export interface RunContinuationOpts {
   readonly resumeFromStageId: string;
 }
 
-export interface RunOpts {
+export interface RunOpts extends Omit<AuthoringContract.RunOpts, "adapters" | "store" | "cancellation" | "overlay" | "registry" | "stageControlRegistry" | "continuation" | "onRunStart" | "onStageStart" | "onStageEnd" | "onRunEnd"> {
   adapters?: StageAdapters;
   /** Invocation working directory exposed to workflow definitions as ctx.cwd. */
   cwd?: string;
@@ -1152,7 +1154,7 @@ function defineDirectWorkflow(
   name: string,
   runFn: WorkflowDefinition["run"],
 ): WorkflowDefinition {
-  return Object.freeze({
+  const definition = {
     __piWorkflow: true,
     name,
     normalizedName: name,
@@ -1160,7 +1162,10 @@ function defineDirectWorkflow(
     inputs: Object.freeze({}),
     outputs: DIRECT_WORKFLOW_OUTPUTS,
     run: runFn,
-  });
+  } as WorkflowDefinition;
+  // Stamp before freezing so the WeakSet brand can be attached.
+  stampWorkflowDefinition(definition);
+  return Object.freeze(definition);
 }
 
 /**
@@ -1805,19 +1810,24 @@ function workflowChildSerializationMessage(err: unknown): string {
 }
 
 function isWorkflowDefinition(value: unknown): value is WorkflowDefinition {
-  if (value === null || typeof value !== "object") return false;
+  if (!isBrandedWorkflowDefinition(value)) return false;
   const record = value as Partial<WorkflowDefinition>;
   return record.__piWorkflow === true &&
     typeof record.name === "string" && record.name.trim().length > 0 &&
     typeof record.normalizedName === "string" && record.normalizedName.trim().length > 0 &&
     typeof record.run === "function" &&
-    // Compiled definitions always set `inputs: {}`; guard it so a handcrafted
-    // object that passes the sentinel still fails here with the clear "requires
-    // a compiled workflow definition" error rather than crashing later inside
-    // resolveAndValidateInputs(child.inputs, ...) on `Object.entries(undefined)`.
     typeof record.inputs === "object" && record.inputs !== null;
 }
 
+function workflowDefinitionRequirementMessage(callSite: string, value: unknown): string {
+  // isWorkflowDefinition already failed; this extra sentinel check narrows the
+  // diagnostic for forged legacy literals versus unrelated values.
+  if (value !== null && typeof value === "object" && (value as { __piWorkflow?: unknown }).__piWorkflow === true) {
+    return `atomic-workflows: ${callSite} requires a compiled workflow definition produced by defineWorkflow(...).compile(); hand-rolled __piWorkflow objects are not supported`;
+  }
+  return `atomic-workflows: ${callSite} requires a compiled workflow definition`;
+}
+
 function cloneWorkflowChildReplaySnapshot(snapshot: WorkflowChildReplaySnapshot): WorkflowChildReplaySnapshot {
   return {
     alias: snapshot.alias,
@@ -1859,6 +1869,10 @@ export async function run<TInputs extends WorkflowInputValues>(
   inputs: Readonly<Record<string, unknown>>,
   opts: RunOpts = {},
 ): Promise<RunResult> {
+  if (!isWorkflowDefinition(def)) {
+    throw new Error(workflowDefinitionRequirementMessage("run(definition, inputs)", def));
+  }
+
   const activeStore = opts.store ?? defaultStore;
   const adapters = opts.adapters ?? {};
   if (opts.usePromptNodesForUi === true && opts.ui !== undefined) {
@@ -3221,7 +3235,7 @@ export async function run<TInputs extends WorkflowInputValues>(
       // declared output contract is validated dynamically by the child run and
       // selectWorkflowOutputs, so the typed result is reconstructed via casts.
       if (!isWorkflowDefinition(child)) {
-        throw new Error("atomic-workflows: ctx.workflow(definition) requires a compiled workflow definition");
+        throw new Error(workflowDefinitionRequirementMessage("ctx.workflow(definition)", child));
       }
       const childName = child.normalizedName;
       const boundaryName = options.stageName ?? `workflow:${childName}`;

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

@@ -64,7 +64,7 @@ export interface StageSessionRuntime {
   getLastAssistantText?: () => string | undefined;
 }
 
-export type StageSessionCreateOptions = CreateAgentSessionOptions & Pick<StageOptions, "mcp" | "fallbackModels">;
+export type StageSessionCreateOptions = CreateAgentSessionOptions & Pick<StageOptions, "mcp" | "fallbackModels" | "fallbackThinkingLevels">;
 
 type WorkflowFastModeSettings = {
   readonly chat: boolean;
@@ -169,6 +169,7 @@ function stripWorkflowOnlyOptions(options: StageOptions | undefined): CreateAgen
   const {
     mcp: _mcp,
     fallbackModels: _fallbackModels,
+    fallbackThinkingLevels: _fallbackThinkingLevels,
     context,
     forkFromSessionFile,
     sessionDir,
@@ -549,6 +550,7 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
       candidatesPromise = buildModelCandidatesFromCatalog({
         primaryModel: stageOptions?.model,
         fallbackModels: stageOptions?.fallbackModels,
+        fallbackThinkingLevels: stageOptions?.fallbackThinkingLevels,
         catalog: modelCatalog,
       });
     }
@@ -557,7 +559,13 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
 
   function stageOptionsForCandidate(candidate: WorkflowResolvedModelCandidate | undefined): StageOptions | undefined {
     if (candidate === undefined) return stageOptions;
-    return { ...(stageOptions ?? {}), model: candidate.value, fallbackModels: undefined };
+    return {
+      ...(stageOptions ?? {}),
+      model: candidate.value,
+      ...(candidate.reasoningLevel !== undefined ? { thinkingLevel: candidate.reasoningLevel } : {}),
+      fallbackModels: undefined,
+      fallbackThinkingLevels: undefined,
+    };
   }
 
   let sessionSettingsManager: WorkflowFastModeSettingsManager | undefined;
@@ -591,6 +599,25 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
     return { session: created };
   }
 
+  function effectiveCandidateReasoning(candidate: WorkflowResolvedModelCandidate): StageOptions["thinkingLevel"] | undefined {
+    return candidate.reasoningLevel ?? stageOptions?.thinkingLevel;
+  }
+
+  function modelAttemptReasoning(candidate: WorkflowResolvedModelCandidate): Pick<WorkflowModelAttempt, "reasoningLevel"> {
+    const reasoningLevel = effectiveCandidateReasoning(candidate);
+    return reasoningLevel !== undefined ? { reasoningLevel } : {};
+  }
+
+  function applyCandidateThinking(candidate: WorkflowResolvedModelCandidate | undefined): void {
+    pendingThinkingLevel = candidate === undefined
+      ? stageOptions?.thinkingLevel
+      : effectiveCandidateReasoning(candidate);
+  }
+
+  function candidateLabel(candidate: WorkflowResolvedModelCandidate): string {
+    return candidate.reasoningLevel !== undefined ? `${candidate.id}:${candidate.reasoningLevel}` : candidate.id;
+  }
+
   function attachSession(created: StageSessionRuntime | StageSessionCreateResult): StageSessionRuntime {
     const result = normalizeSessionCreateResult(created);
     session = result.session;
@@ -612,6 +639,7 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
     candidate: WorkflowResolvedModelCandidate | undefined,
     consumer: AgentSessionConsumer,
   ): Promise<StageSessionRuntime> {
+    applyCandidateThinking(candidate);
     const created = adapters.agentSession
       ? await adapters.agentSession.create(stripWorkflowOnlyOptions(stageOptionsForCandidate(candidate)) as StageSessionCreateOptions, {
         ...meta,
@@ -716,16 +744,16 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
       notifyModelFallbackMetaChange();
       try {
         await promptWithPauseResume(activeSession, text, sdkOptions);
-        modelAttempts.push({ model: candidate.id, success: true });
+        modelAttempts.push({ model: candidate.id, success: true, ...modelAttemptReasoning(candidate) });
         return;
       } catch (err) {
         const message = errorMessage(err);
-        modelAttempts.push({ model: candidate.id, success: false, error: message });
+        modelAttempts.push({ model: candidate.id, success: false, ...modelAttemptReasoning(candidate), error: message });
         if (signal?.aborted || !isRetryableModelFailure(message) || index === candidates.length - 1) {
           throw err;
         }
         const nextCandidate = candidates[index + 1]!;
-        modelWarnings.push(`[fallback] ${candidate.id} failed: ${message}. Retrying with ${nextCandidate.id}.`);
+        modelWarnings.push(`[fallback] ${candidateLabel(candidate)} failed: ${message}. Retrying with ${candidateLabel(nextCandidate)}.`);
         await disposeCurrentSession();
         index += 1;
       }

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

@@ -3,11 +3,38 @@ import type {
   WorkflowModelCatalogPort,
   WorkflowModelInfo,
   WorkflowModelValue,
+  WorkflowThinkingLevel,
 } from "../../shared/types.js";
 
 export interface WorkflowResolvedModelCandidate {
   readonly id: string;
   readonly value: WorkflowModelValue;
+  readonly reasoningLevel?: WorkflowThinkingLevel;
+}
+
+function makeCandidate(
+  id: string,
+  value: WorkflowModelValue,
+  level: WorkflowThinkingLevel | undefined,
+): WorkflowResolvedModelCandidate {
+  return level !== undefined ? { id, value, reasoningLevel: level } : { id, value };
+}
+
+const WORKFLOW_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const satisfies readonly WorkflowThinkingLevel[];
+const WORKFLOW_THINKING_LEVEL_SET: ReadonlySet<string> = new Set(WORKFLOW_THINKING_LEVELS);
+
+export function splitReasoningSuffix(model: string): { readonly baseModel: string; readonly level?: WorkflowThinkingLevel } {
+  const index = model.lastIndexOf(":");
+  if (index < 0) return { baseModel: model };
+  const suffix = model.slice(index + 1);
+  if (WORKFLOW_THINKING_LEVEL_SET.has(suffix)) {
+    return { baseModel: model.slice(0, index), level: suffix as WorkflowThinkingLevel };
+  }
+  return { baseModel: model };
+}
+
+function candidateKey(candidate: WorkflowResolvedModelCandidate): string {
+  return `${candidate.id}::${candidate.reasoningLevel ?? ""}`;
 }
 
 interface ModelResolutionFailure {
@@ -72,35 +99,46 @@ function resolveStringModel(
 ): WorkflowResolvedModelCandidate | ModelResolutionFailure {
   const input = rawInput.trim();
   if (!input) return { input: rawInput, reason: "empty model id" };
+  const { baseModel, level } = splitReasoningSuffix(input);
 
   if (availableModels === undefined) {
-    return { id: input, value: input };
+    return makeCandidate(baseModel, baseModel, level);
   }
 
   const models = uniqueByFullId(availableModels);
-  const explicit = models.find((model) => model.fullId === input);
+  const explicit = models.find((model) => model.fullId === baseModel);
   if (explicit !== undefined) {
-    return { id: explicit.fullId, value: explicit.model ?? explicit.fullId };
+    return makeCandidate(explicit.fullId, explicit.model ?? explicit.fullId, level);
   }
 
-  if (input.includes("/")) {
-    return { input, reason: "not available" };
+  if (baseModel.includes("/")) {
+    // Trust an explicit provider/model id even when the live catalog does not
+    // list it, mirroring the subagent resolver (resolveModelCandidate's
+    // `if (model.includes("/")) return model;`). The workflow catalog
+    // (ctx.modelRegistry.getAvailable()) can legitimately be a partial view
+    // (auth/provider gating, freshly added models), so treating an absent
+    // fully-qualified id as a hard failure made buildModelCandidates throw and
+    // collapse the whole ordered candidate list down to just the user's
+    // currentModel — discarding the workflow's defined primary and fallbacks.
+    // Pass it through with the reasoning suffix split off; the runtime fallback
+    // loop skips it only if the SDK genuinely cannot create a session for it.
+    return makeCandidate(baseModel, baseModel, level);
   }
 
-  const byBareId = models.filter((model) => model.id === input);
+  const byBareId = models.filter((model) => model.id === baseModel);
   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 };
+    return makeCandidate(only.fullId, only.model ?? only.fullId, level);
   }
 
   const preferred = preferredProvider === undefined
     ? undefined
     : byBareId.find((model) => model.provider === preferredProvider);
   if (preferred !== undefined) {
-    return { id: preferred.fullId, value: preferred.model ?? preferred.fullId };
+    return makeCandidate(preferred.fullId, preferred.model ?? preferred.fullId, level);
   }
 
   return {
@@ -127,13 +165,30 @@ function isFailure(value: WorkflowResolvedModelCandidate | ModelResolutionFailur
 export function buildModelCandidates(input: {
   readonly primaryModel?: WorkflowModelValue;
   readonly fallbackModels?: readonly string[];
+  readonly fallbackThinkingLevels?: 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 ?? []));
+  for (const [index, fallback] of (input.fallbackModels ?? []).entries()) {
+    // Trim once up front so the suffix split, the validation error input, and the
+    // compat concatenation all operate on the same value. Concatenating the raw
+    // (untrimmed) fallback would push trailing whitespace into the interior of
+    // `id:level`, which `resolveStringModel` can no longer trim away.
+    const trimmedFallback = fallback.trim();
+    const split = splitReasoningSuffix(trimmedFallback);
+    const compatLevel = input.fallbackThinkingLevels?.[index];
+    if (split.level === undefined && compatLevel !== undefined) {
+      if (!WORKFLOW_THINKING_LEVEL_SET.has(compatLevel)) {
+        throw new WorkflowModelValidationError([{ input: trimmedFallback, reason: `invalid fallbackThinkingLevels[${index}] "${compatLevel}"; expected one of ${WORKFLOW_THINKING_LEVELS.join(", ")}` }]);
+      }
+      rawValues.push(`${trimmedFallback}:${compatLevel}`);
+    } else {
+      rawValues.push(trimmedFallback);
+    }
+  }
   if (input.currentModel !== undefined) rawValues.push(input.currentModel);
 
   const failures: ModelResolutionFailure[] = [];
@@ -145,8 +200,9 @@ export function buildModelCandidates(input: {
       failures.push(resolved);
       continue;
     }
-    if (seen.has(resolved.id)) continue;
-    seen.add(resolved.id);
+    const key = candidateKey(resolved);
+    if (seen.has(key)) continue;
+    seen.add(key);
     candidates.push(resolved);
   }
 
@@ -165,6 +221,7 @@ function catalogUnavailableWarning(): string {
 export async function buildModelCandidatesFromCatalog(input: {
   readonly primaryModel?: WorkflowModelValue;
   readonly fallbackModels?: readonly string[];
+  readonly fallbackThinkingLevels?: readonly string[];
   readonly catalog?: WorkflowModelCatalogPort;
 }): Promise<WorkflowResolvedModelCandidate[]> {
   const hasExplicitModel = input.primaryModel !== undefined || (input.fallbackModels?.length ?? 0) > 0;
@@ -174,6 +231,7 @@ export async function buildModelCandidatesFromCatalog(input: {
     return buildModelCandidates({
       primaryModel: input.primaryModel,
       fallbackModels: input.fallbackModels,
+      fallbackThinkingLevels: input.fallbackThinkingLevels,
     });
   }
 
@@ -182,6 +240,7 @@ export async function buildModelCandidatesFromCatalog(input: {
     return buildModelCandidates({
       primaryModel: input.primaryModel,
       fallbackModels: input.fallbackModels,
+      fallbackThinkingLevels: input.fallbackThinkingLevels,
       currentModel: input.catalog.currentModel,
       availableModels,
       preferredProvider: input.catalog.preferredProvider,
@@ -199,6 +258,7 @@ export async function validateWorkflowModels(input: {
   readonly requests: readonly {
     readonly model?: WorkflowModelValue;
     readonly fallbackModels?: readonly string[];
+    readonly fallbackThinkingLevels?: readonly string[];
   }[];
   readonly catalog?: WorkflowModelCatalogPort;
 }): Promise<readonly string[]> {
@@ -230,6 +290,7 @@ export async function validateWorkflowModels(input: {
       buildModelCandidates({
         primaryModel: request.model,
         fallbackModels: request.fallbackModels,
+        fallbackThinkingLevels: request.fallbackThinkingLevels,
         currentModel: input.catalog?.currentModel,
         availableModels,
         preferredProvider: input.catalog?.preferredProvider,

package/dist/builtin/workflows/src/sdk-surface.ts

@@ -2,12 +2,22 @@
  * Non-cyclic public SDK surface for @bastani/workflows.
  *
  * Keep public runtime exports here when they are safe to load during workflow
- * discovery. The package root re-exports this module and adds runWorkflow,
- * which is intentionally excluded because workflow-runner imports discovery.ts.
+ * discovery. The package root re-exports this module directly.
  */
 
 export { defineWorkflow } from "./workflows/define-workflow.js";
 
+const REMOVED_RUN_WORKFLOW_MESSAGE =
+  "@bastani/workflows no longer exports runWorkflow; author workflows with defineWorkflow(...).compile()";
+
+/**
+ * @deprecated Removed imperative workflow API. Kept as a runtime migration
+ * stub so older workflow modules fail at the call site with a clear message.
+ */
+export const runWorkflow: never = (() => {
+  throw new Error(REMOVED_RUN_WORKFLOW_MESSAGE);
+}) as never;
+
 // TypeBox authoring surface so jiti-loaded workflows can `import { Type } from
 // "@bastani/workflows"` (the virtual module is built from this file).
 export { Type } from "typebox";