@bastani/atomic 0.8.23 → 0.8.24-alpha.1

package/dist/builtin/workflows/builtin/ralph.ts

@@ -432,50 +432,46 @@ async function runRalphWorkflow(
   let iterationsCompleted = 0;
 
   const plannerModelConfig = {
-    model: "openai/gpt-5.5",
+    model: "openai/gpt-5.5:xhigh",
     fallbackModels: [
-      "openai-codex/gpt-5.5",
-      "github-copilot/gpt-5.5",
-      "anthropic/claude-opus-4-8",
-      "github-copilot/claude-opus-4.7",
+      "openai-codex/gpt-5.5:xhigh",
+      "github-copilot/gpt-5.5:xhigh",
+      "anthropic/claude-opus-4-8:xhigh",
+      "github-copilot/claude-opus-4.8:medium",
     ],
-    thinkingLevel: "high" as const,
     excludedTools: ["ask_user_question"],
   };
 
   const orchestratorModelConfig = {
-    model: "openai/gpt-5.5",
+    model: "openai/gpt-5.5:medium",
     fallbackModels: [
-      "openai-codex/gpt-5.5",
-      "github-copilot/gpt-5.5",
-      "anthropic/claude-sonnet-4-6",
-      "github-copilot/claude-sonnet-4.6",
+      "openai-codex/gpt-5.5:medium",
+      "github-copilot/gpt-5.5:medium",
+      "anthropic/claude-sonnet-4-6:medium",
+      "github-copilot/claude-sonnet-4.6:medium",
     ],
-    thinkingLevel: "medium" as const,
     excludedTools: ["ask_user_question"],
   };
 
   const simplifierModelConfig = {
-    model: "openai/gpt-5.5",
+    model: "openai/gpt-5.5:medium",
     fallbackModels: [
-      "openai-codex/gpt-5.5",
-      "github-copilot/gpt-5.5",
-      "anthropic/claude-sonnet-4-6",
-      "github-copilot/claude-sonnet-4.6",
+      "openai-codex/gpt-5.5:medium",
+      "github-copilot/gpt-5.5:medium",
+      "anthropic/claude-sonnet-4-6:medium",
+      "github-copilot/claude-sonnet-4.6:medium",
     ],
-    thinkingLevel: "medium" as const,
     excludedTools: ["ask_user_question"],
   };
 
   const reviewerModelConfig = {
-    model: "openai/gpt-5.5",
+    model: "openai/gpt-5.5:xhigh",
     fallbackModels: [
-      "openai-codex/gpt-5.5",
-      "github-copilot/gpt-5.5",
-      "anthropic/claude-opus-4-8",
-      "github-copilot/claude-opus-4.7",
+      "openai-codex/gpt-5.5:xhigh",
+      "github-copilot/gpt-5.5:xhigh",
+      "anthropic/claude-opus-4-8:xhigh",
+      "github-copilot/claude-opus-4.8:medium",
     ],
-    thinkingLevel: "high" as const,
     excludedTools: ["ask_user_question"],
     customTools: [reviewDecisionTool],
   };

package/dist/builtin/workflows/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/workflows",
-  "version": "0.8.23",
+  "version": "0.8.24-alpha.1",
   "private": true,
   "description": "Atomic extension for multi-stage workflow authoring and execution.",
   "contributors": [
@@ -13,11 +13,20 @@
     "bun": ">=1.3.14"
   },
   "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "types": "./src/authoring.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./builtin": "./builtin/index.ts",
-    "./builtin/*": "./builtin/*.ts"
+    ".": {
+      "types": "./src/authoring.ts",
+      "default": "./src/index.ts"
+    },
+    "./builtin": {
+      "types": "./builtin/index.d.ts",
+      "default": "./builtin/index.ts"
+    },
+    "./builtin/*": {
+      "types": "./builtin/*.d.ts",
+      "default": "./builtin/*.ts"
+    }
   },
   "repository": {
     "type": "git",
@@ -39,6 +48,7 @@
   "files": [
     "src/**/*.ts",
     "builtin/**/*.ts",
+    "builtin/**/*.d.ts",
     "skills/**/*",
     "prompts/**/*",
     "themes/*.json",

package/dist/builtin/workflows/src/authoring.ts

@@ -0,0 +1,410 @@
+/*
+ * Type-only package authoring surface for standalone workflow packages.
+ *
+ * package.json points the root "types" condition here so authors can import
+ * defineWorkflow and Type without pulling the Atomic runtime/extension graph into
+ * their TypeScript program. Runtime loading still uses src/index.ts.
+ */
+
+import type {
+  TAny,
+  TArray,
+  TArrayOptions,
+  TBigInt,
+  TBoolean,
+  TEnum,
+  TEnumValue,
+  TInteger,
+  TIntersect,
+  TIntersectOptions,
+  TLiteral,
+  TLiteralValue,
+  TNever,
+  TNull,
+  TNumber,
+  TNumberOptions,
+  TOmit,
+  TObject,
+  TObjectOptions,
+  TPartial,
+  TPick,
+  TRecordAction,
+  TRequired,
+  TSchema,
+  TSchemaOptions,
+  TString,
+  TStringOptions,
+  TTuple,
+  TTupleOptions,
+  TUndefined,
+  TUnion,
+  TUnknown,
+  TVoid,
+  Type as TypeboxType,
+  TKeysToIndexer,
+} from "typebox";
+
+type PreserveOptions<T extends TSchema, O extends TSchemaOptions> = T & O;
+type TypeScriptEnumLike = Record<string, string | number>;
+type TypeScriptEnumValues<T extends TypeScriptEnumLike> = Extract<T[keyof T], TEnumValue>[];
+
+export declare const Type: Omit<
+  typeof TypeboxType,
+  | "Any"
+  | "Array"
+  | "BigInt"
+  | "Boolean"
+  | "Enum"
+  | "Integer"
+  | "Intersect"
+  | "Literal"
+  | "Never"
+  | "Null"
+  | "Number"
+  | "Omit"
+  | "Partial"
+  | "Pick"
+  | "Object"
+  | "Record"
+  | "Required"
+  | "String"
+  | "Tuple"
+  | "Undefined"
+  | "Union"
+  | "Unknown"
+  | "Void"
+> & {
+  Any<const O extends TSchemaOptions>(options: O): PreserveOptions<TAny, O>;
+  Any(): TAny;
+  Array<Type extends TSchema, const O extends TArrayOptions>(items: Type, options: O): PreserveOptions<TArray<Type>, O>;
+  Array<Type extends TSchema>(items: Type): TArray<Type>;
+  BigInt<const O extends TSchemaOptions>(options: O): PreserveOptions<TBigInt, O>;
+  BigInt(): TBigInt;
+  Boolean<const O extends TSchemaOptions>(options: O): PreserveOptions<TBoolean, O>;
+  Boolean(): TBoolean;
+  Enum<Values extends TEnumValue[], const O extends TSchemaOptions>(values: readonly [...Values], options: O): PreserveOptions<TEnum<Values>, O>;
+  Enum<Values extends TEnumValue[]>(values: readonly [...Values]): TEnum<Values>;
+  Enum<Enum extends TypeScriptEnumLike, const O extends TSchemaOptions>(value: Enum, options: O): PreserveOptions<TEnum<TypeScriptEnumValues<Enum>>, O>;
+  Enum<Enum extends TypeScriptEnumLike>(value: Enum): TEnum<TypeScriptEnumValues<Enum>>;
+  Integer<const O extends TNumberOptions>(options: O): PreserveOptions<TInteger, O>;
+  Integer(): TInteger;
+  Intersect<Types extends TSchema[], const O extends TIntersectOptions>(types: [...Types], options: O): PreserveOptions<TIntersect<Types>, O>;
+  Intersect<Types extends TSchema[]>(types: [...Types]): TIntersect<Types>;
+  Literal<const Value extends TLiteralValue, const O extends TSchemaOptions>(value: Value, options: O): PreserveOptions<TLiteral<Value>, O>;
+  Literal<const Value extends TLiteralValue>(value: Value): TLiteral<Value>;
+  Never<const O extends TSchemaOptions>(options: O): PreserveOptions<TNever, O>;
+  Never(): TNever;
+  Null<const O extends TSchemaOptions>(options: O): PreserveOptions<TNull, O>;
+  Null(): TNull;
+  Number<const O extends TNumberOptions>(options: O): PreserveOptions<TNumber, O>;
+  Number(): TNumber;
+  Omit<Type extends TSchema, Indexer extends PropertyKey[], const O extends TSchemaOptions>(type: Type, indexer: readonly [...Indexer], options: O): PreserveOptions<TOmit<Type, TKeysToIndexer<Indexer>>, O>;
+  Omit<Type extends TSchema, Indexer extends PropertyKey[]>(type: Type, indexer: readonly [...Indexer]): TOmit<Type, TKeysToIndexer<Indexer>>;
+  Omit<Type extends TSchema, Indexer extends TSchema, const O extends TSchemaOptions>(type: Type, indexer: Indexer, options: O): PreserveOptions<TOmit<Type, Indexer>, O>;
+  Omit<Type extends TSchema, Indexer extends TSchema>(type: Type, indexer: Indexer): TOmit<Type, Indexer>;
+  Partial<Type extends TSchema, const O extends TSchemaOptions>(type: Type, options: O): PreserveOptions<TPartial<Type>, O>;
+  Partial<Type extends TSchema>(type: Type): TPartial<Type>;
+  Pick<Type extends TSchema, Indexer extends PropertyKey[], const O extends TSchemaOptions>(type: Type, indexer: readonly [...Indexer], options: O): PreserveOptions<TPick<Type, TKeysToIndexer<Indexer>>, O>;
+  Pick<Type extends TSchema, Indexer extends PropertyKey[]>(type: Type, indexer: readonly [...Indexer]): TPick<Type, TKeysToIndexer<Indexer>>;
+  Pick<Type extends TSchema, Indexer extends TSchema, const O extends TSchemaOptions>(type: Type, indexer: Indexer, options: O): PreserveOptions<TPick<Type, Indexer>, O>;
+  Pick<Type extends TSchema, Indexer extends TSchema>(type: Type, indexer: Indexer): TPick<Type, Indexer>;
+  Object<Properties extends Record<PropertyKey, TSchema>, const O extends TObjectOptions>(properties: Properties, options: O): PreserveOptions<TObject<Properties>, O>;
+  Object<Properties extends Record<PropertyKey, TSchema>>(properties: Properties): TObject<Properties>;
+  Record<Key extends TSchema, Value extends TSchema, const O extends TObjectOptions>(key: Key, value: Value, options: O): PreserveOptions<TRecordAction<Key, Value>, O>;
+  Record<Key extends TSchema, Value extends TSchema>(key: Key, value: Value): TRecordAction<Key, Value>;
+  Required<Type extends TSchema, const O extends TSchemaOptions>(type: Type, options: O): PreserveOptions<TRequired<Type>, O>;
+  Required<Type extends TSchema>(type: Type): TRequired<Type>;
+  String<const O extends TStringOptions>(options: O): PreserveOptions<TString, O>;
+  String(): TString;
+  Tuple<Types extends TSchema[], const O extends TTupleOptions>(types: [...Types], options: O): PreserveOptions<TTuple<Types>, O>;
+  Tuple<Types extends TSchema[]>(types: [...Types]): TTuple<Types>;
+  Undefined<const O extends TSchemaOptions>(options: O): PreserveOptions<TUndefined, O>;
+  Undefined(): TUndefined;
+  Union<Types extends TSchema[], const O extends TSchemaOptions>(anyOf: [...Types], options: O): PreserveOptions<TUnion<Types>, O>;
+  Union<Types extends TSchema[]>(anyOf: [...Types]): TUnion<Types>;
+  Unknown<const O extends TSchemaOptions>(options: O): PreserveOptions<TUnknown, O>;
+  Unknown(): TUnknown;
+  Void<const O extends TSchemaOptions>(options: O): PreserveOptions<TVoid, O>;
+  Void(): TVoid;
+};
+export type { Static, TSchema } from "typebox";
+
+export type {
+  AgentSessionAdapter,
+  CompleteAdapter,
+  CompleteStageOpts,
+  GitWorktreeSetupOptions,
+  GitWorktreeSetupResult,
+  PromptAdapter,
+  PromptOptions,
+  ResolvedInputs,
+  RunResult,
+  RunStatus,
+  StageAdapters,
+  StageStatus,
+  StageOptions,
+  StageContext,
+  StageSnapshot,
+  StageExecutionMeta,
+  StageMcpOptions,
+  StageOutputOptions,
+  StagePromptOptions,
+  StageSessionCreateOptions,
+  StageSessionCreateResult,
+  StageSessionRuntime,
+  WorkflowAction,
+  WorkflowArtifact,
+  WorkflowChainOptions,
+  WorkflowChainStep,
+  WorkflowChildResult,
+  WorkflowContextMode,
+  WorkflowControlEvent,
+  WorkflowCustomToolDefinition,
+  WorkflowDetails,
+  WorkflowDetailsMode,
+  WorkflowDetailsStatus,
+  WorkflowDirectOptions,
+  WorkflowDirectTaskItem,
+  WorkflowExecutionMode,
+  WorkflowExecutionPolicy,
+  WorkflowInputBindings,
+  WorkflowInputSchema,
+  WorkflowInputSchemaMap,
+  WorkflowInputValues,
+  WorkflowIntercomSummary,
+  WorkflowMaxOutput,
+  WorkflowMcpPort,
+  WorkflowModelAttempt,
+  WorkflowModelCatalogPort,
+  WorkflowModelFallbackFields,
+  WorkflowModelInfo,
+  WorkflowModelUsage,
+  WorkflowModelValue,
+  WorkflowOutputMode,
+  WorkflowOutputSchema,
+  WorkflowOutputSchemaMap,
+  WorkflowOutputValues,
+  WorkflowParallelChainStep,
+  WorkflowParallelOptions,
+  WorkflowPersistencePort,
+  WorkflowProgressSummary,
+  WorkflowRunChildOptions,
+  WorkflowRunOutput,
+  WorkflowRuntimeConfig,
+  WorkflowSerializableObject,
+  WorkflowSerializablePrimitive,
+  WorkflowSerializableValue,
+  WorkflowSharedTaskDefaults,
+  WorkflowTaskContext,
+  WorkflowTaskContextInput,
+  WorkflowTaskOptions,
+  WorkflowTaskResult,
+  WorkflowTaskSessionFields,
+  WorkflowTaskSessionOptions,
+  WorkflowTaskStep,
+  WorkflowThinkingLevel,
+  WorkflowUIAdapter,
+  WorkflowUIContext,
+  WorkflowWorktreeInputBinding,
+} from "./shared/authoring-contract.js";
+
+import type * as AuthoringContract from "./shared/authoring-contract.js";
+
+import type {
+  GitWorktreeSetupOptions,
+  GitWorktreeSetupResult,
+  ResolvedInputs,
+  RunResult,
+  RunStatus,
+  StageSnapshot,
+  WorkflowDefinition as WorkflowContractDefinition,
+  WorkflowDetails,
+  WorkflowDirectOptions,
+  WorkflowDirectTaskItem,
+  WorkflowExecutionPolicy,
+  WorkflowInputValues,
+  WorkflowOutputValues,
+  WorkflowSerializableObject,
+  WorkflowChainStep,
+} from "./shared/authoring-contract.js";
+
+// Type-only nominal brand for standalone package typings. Runtime discovery uses
+// the package-internal WeakSet in define-workflow.ts rather than a symbol field.
+declare const workflowDefinitionBrand: unique symbol;
+type WorkflowDefinitionBrand = { readonly [workflowDefinitionBrand]: true };
+
+export interface WorkflowDefinition<
+  TInputs extends WorkflowInputValues = WorkflowInputValues,
+  TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
+  TRunInputs extends WorkflowInputValues = TInputs,
+  TDefinitionBrand extends object = WorkflowDefinitionBrand,
+> extends WorkflowContractDefinition<TInputs, TOutputs, TRunInputs, TDefinitionBrand>, WorkflowDefinitionBrand {}
+
+export type WorkflowRunContext<TInputs extends WorkflowInputValues = WorkflowInputValues> = AuthoringContract.WorkflowRunContext<TInputs, WorkflowDefinitionBrand>;
+export type WorkflowRunFn<
+  TInputs extends WorkflowInputValues = WorkflowInputValues,
+  TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
+> = AuthoringContract.WorkflowRunFn<TInputs, TOutputs, WorkflowDefinitionBrand>;
+
+export type AnyWorkflowDefinition = WorkflowDefinition<WorkflowInputValues, WorkflowOutputValues, WorkflowInputValues>;
+
+export type WorkflowBuilder<
+  TInputs extends WorkflowInputValues = {},
+  TOutputs extends WorkflowOutputValues = {},
+  TRunInputs extends WorkflowInputValues = TInputs,
+> = AuthoringContract.WorkflowBuilder<TInputs, TOutputs, TRunInputs, WorkflowDefinitionBrand, WorkflowDefinition<TInputs, TOutputs, TRunInputs>>;
+
+export type CompletedWorkflowBuilder<
+  TInputs extends WorkflowInputValues = {},
+  TOutputs extends WorkflowOutputValues = {},
+  TRunInputs extends WorkflowInputValues = TInputs,
+> = AuthoringContract.CompletedWorkflowBuilder<TInputs, TOutputs, TRunInputs, WorkflowDefinitionBrand, WorkflowDefinition<TInputs, TOutputs, TRunInputs>>;
+
+export type RunContinuationOpts = AuthoringContract.RunContinuationOpts;
+export type WorkflowParentRunLink = AuthoringContract.WorkflowParentRunLink;
+export type RunOpts = Omit<AuthoringContract.RunOpts, "registry"> & { readonly registry?: WorkflowRegistry };
+
+export declare const INTERACTIVE_WORKFLOW_POLICY: WorkflowExecutionPolicy;
+export declare const NON_INTERACTIVE_WORKFLOW_POLICY: WorkflowExecutionPolicy;
+export declare function run<TInputs extends WorkflowInputValues, TOutputs extends WorkflowOutputValues, TRunInputs extends WorkflowInputValues = TInputs>(
+  definition: WorkflowDefinition<TInputs, TOutputs, TRunInputs>,
+  inputs: Readonly<NoInfer<TRunInputs>>,
+  opts?: RunOpts,
+): Promise<RunResult<TOutputs>>;
+export declare function runTask(task: WorkflowDirectTaskItem, runOptions?: RunOpts): Promise<WorkflowDetails>;
+export declare function runTask(task: WorkflowDirectTaskItem, options?: WorkflowDirectOptions, runOptions?: RunOpts): Promise<WorkflowDetails>;
+export declare function runParallel(tasks: readonly WorkflowDirectTaskItem[], options?: WorkflowDirectOptions, runOptions?: RunOpts): Promise<WorkflowDetails>;
+export declare function runChain(steps: readonly WorkflowChainStep[], options?: WorkflowDirectOptions, runOptions?: RunOpts): Promise<WorkflowDetails>;
+export declare function resolveInputs<TInputs extends WorkflowInputValues>(
+  schema: Readonly<Record<keyof TInputs & string, TSchema>>,
+  provided: Partial<TInputs>,
+): ResolvedInputs<TInputs>;
+export declare function setupGitWorktree(options: GitWorktreeSetupOptions): GitWorktreeSetupResult;
+
+export interface WorkflowRegistry {
+  register<TInputs extends WorkflowInputValues, TOutputs extends WorkflowOutputValues>(
+    definition: WorkflowDefinition<TInputs, TOutputs>,
+  ): WorkflowRegistry;
+  merge(other: WorkflowRegistry): WorkflowRegistry;
+  get(name: string): AnyWorkflowDefinition | undefined;
+  has(name: string): boolean;
+  remove(name: string): WorkflowRegistry;
+  names(): string[];
+  all(): AnyWorkflowDefinition[];
+}
+
+/**
+ * @deprecated Removed imperative workflow API. This runtime value only throws
+ * a migration error; author workflows with defineWorkflow(...).compile().
+ */
+export declare const runWorkflow: never;
+export declare function defineWorkflow(name: string): WorkflowBuilder;
+export declare function createRegistry<TDefinitions extends readonly AnyWorkflowDefinition[] = readonly AnyWorkflowDefinition[]>(
+  initial?: TDefinitions,
+): WorkflowRegistry;
+export declare function normalizeWorkflowName(name: string): string;
+export declare function workflowNamesEqual(a: string, b: string): boolean;
+
+export declare class GraphFrontierTracker {
+  onSpawn(stageId: string, stageName: string): string[];
+  currentParents(): string[];
+  replaceParents(stageId: string, parentIds: readonly string[]): void;
+  onSettle(stageId: string): void;
+  getNodes(): StageNode[];
+  getParents(stageId: string): string[];
+  reset(): void;
+}
+export interface StageNode extends WorkflowSerializableObject {
+  readonly id: string;
+  readonly name: string;
+  readonly parentIds: readonly string[];
+}
+export type NoticeLevel = "info" | "warning" | "error";
+export type PromptKind = "input" | "confirm" | "select" | "editor";
+
+export interface PendingPrompt extends WorkflowSerializableObject {
+  readonly id: string;
+  readonly kind: PromptKind;
+  readonly message: string;
+  readonly choices?: readonly string[];
+  readonly initial?: string;
+  readonly createdAt: number;
+}
+
+export interface ToolEvent {
+  readonly name: string;
+  readonly input?: Record<string, unknown>;
+  readonly output?: string;
+  readonly startedAt?: number;
+  readonly endedAt?: number;
+}
+
+export interface WorkflowNotice extends WorkflowSerializableObject {
+  readonly id: string;
+  readonly runId?: string;
+  readonly stageId?: string;
+  readonly level: NoticeLevel;
+  readonly message: string;
+  readonly createdAt: number;
+  readonly requiresAck?: boolean;
+  readonly ackedAt?: number;
+}
+
+export interface WorkflowOverlayAdapter {
+  show(notice: WorkflowNotice): void;
+  hide(): void;
+}
+
+export interface RunSnapshot {
+  readonly id: string;
+  readonly name: string;
+  readonly status: RunStatus;
+  readonly stages: readonly StageSnapshot[];
+  readonly startedAt: number;
+  readonly endedAt?: number;
+  readonly durationMs?: number;
+  readonly result?: WorkflowOutputValues;
+  readonly error?: string;
+  readonly pendingPrompt?: PendingPrompt;
+}
+
+export interface StoreSnapshot {
+  readonly runs: readonly RunSnapshot[];
+  readonly notices: readonly WorkflowNotice[];
+  readonly version: number;
+}
+
+export interface Store {
+  runs(): readonly RunSnapshot[];
+  notices(): readonly WorkflowNotice[];
+  activeRunId(): string | null;
+  recordRunStart(run: RunSnapshot): void;
+  recordStageStart(runId: string, stage: StageSnapshot): void;
+  recordToolStart(runId: string, stageId: string, evt: ToolEvent): void;
+  recordToolEnd(runId: string, stageId: string, evt: ToolEvent): void;
+  recordStageEnd(runId: string, stage: StageSnapshot): void;
+  recordRunEnd(runId: string, status: RunStatus, result?: WorkflowOutputValues, error?: string): boolean;
+  removeRun(runId: string): boolean;
+  recordNotice(notice: WorkflowNotice): void;
+  ackNotice(id: string): boolean;
+}
+
+export declare function createStore(): Store;
+export declare const store: Store;
+
+export interface ActiveRunEntry {
+  readonly controller: AbortController;
+  readonly children: readonly AbortController[];
+}
+
+export interface CancellationRegistry {
+  register(runId: string, controller: AbortController): void;
+  registerChild(runId: string, controller: AbortController): void;
+  abort(runId: string, reason?: unknown): boolean;
+  abortAll(reason?: unknown): number;
+  unregister(runId: string): void;
+  isAborted(runId: string): boolean;
+}
+
+export declare function createCancellationRegistry(): CancellationRegistry;
+export declare const cancellationRegistry: CancellationRegistry;

package/dist/builtin/workflows/src/extension/workflow-module-loader.ts

@@ -8,26 +8,17 @@
 
 import { createJiti } from "jiti/static";
 import * as workflowsSdkSurface from "../sdk-surface.js";
+import { isBrandedWorkflowDefinition } from "../workflows/define-workflow.js";
 import deepResearchCodebase from "../../builtin/deep-research-codebase.js";
 import goal from "../../builtin/goal.js";
 import openClaudeDesign from "../../builtin/open-claude-design.js";
 import ralph from "../../builtin/ralph.js";
 
-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 WORKFLOWS_MODULE_SPECIFIER = "@bastani/workflows";
 const WORKFLOWS_BUILTIN_MODULE_SPECIFIER = `${WORKFLOWS_MODULE_SPECIFIER}/builtin`;
-// 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 discovery.ts and would otherwise reintroduce a cycle.
+// Keep this in sync with index.ts through sdk-surface.ts.
 const WORKFLOWS_SDK_MODULE: Record<string, unknown> = {
   ...workflowsSdkSurface,
-  runWorkflow,
 };
 const WORKFLOWS_BUILTIN_MODULE: Record<string, unknown> = {
   deepResearchCodebase,
@@ -104,7 +95,10 @@ export function validateWorkflowDefinitionShape(value: unknown): string | null {
   const d = value as Record<string, unknown>;
 
   if (d["__piWorkflow"] !== true) {
-    return "missing or incorrect __piWorkflow sentinel (expected true)";
+    return "missing or incorrect __piWorkflow sentinel (expected true); export a workflow from defineWorkflow(...).compile()";
+  }
+  if (!isBrandedWorkflowDefinition(value)) {
+    return "workflow definition is not produced by defineWorkflow(...).compile(); hand-rolled __piWorkflow objects are not supported";
   }
   if (typeof d["name"] !== "string" || (d["name"] as string).trim().length === 0) {
     return "name must be a non-empty string";

package/dist/builtin/workflows/src/extension/workflow-schema.ts

@@ -42,7 +42,7 @@ const StageSessionOptionProperties = {
   agentDir: Type.Optional(Type.String()),
   authStorage: Type.Optional(SdkSessionOptionSchema("authStorage")),
   modelRegistry: Type.Optional(SdkSessionOptionSchema("modelRegistry")),
-  model: Type.Optional(Type.Unsafe<WorkflowModelValue>({})),
+  model: Type.Optional(Type.Unsafe<WorkflowModelValue>({ description: "Primary model id or SDK model object. String ids may include a reasoning suffix, e.g. openai/gpt-5:high; valid levels: off|minimal|low|medium|high|xhigh." })),
   thinkingLevel: Type.Optional(SdkSessionOptionSchema("thinkingLevel")),
   scopedModels: Type.Optional(Type.Array(SdkSessionOptionArrayElementSchema("scopedModels"))),
   noTools: Type.Optional(Type.Unsafe<NonNullable<CreateAgentSessionOptions["noTools"]>>({
@@ -54,7 +54,8 @@ const StageSessionOptionProperties = {
   sessionManager: Type.Optional(SdkSessionOptionSchema("sessionManager")),
   settingsManager: Type.Optional(SdkSessionOptionSchema("settingsManager")),
   sessionStartEvent: Type.Optional(SdkSessionOptionSchema("sessionStartEvent")),
-  fallbackModels: Type.Optional(Type.Array(Type.String())),
+  fallbackModels: Type.Optional(Type.Array(Type.String({ description: "Fallback model id; may include a reasoning suffix like :low or :off." }))),
+  fallbackThinkingLevels: Type.Optional(Type.Array(Type.String({ description: "Deprecated compatibility helper aligned to fallbackModels; ignored when the fallback model has a :level suffix." }))),
   mcp: Type.Optional(McpOptionsSchema),
   sessionDir: Type.Optional(Type.String()),
   context: Type.Optional(Type.Union([Type.Literal("fresh"), Type.Literal("fork")])),

package/dist/builtin/workflows/src/index.ts

@@ -7,9 +7,4 @@
 // virtual SDK used by workflow discovery stays in lockstep with this entry.
 export * from "./sdk-surface.js";
 
-// runWorkflow is exported here only: workflow-runner imports discovery.ts, so
-// discovery provides a lazy wrapper instead of importing this entry eagerly.
-export { runWorkflow } from "./runs/shared/workflow-runner.js";
-export type { WorkflowOptions, WorkflowRunOptions } from "./runs/shared/workflow-runner.js";
-
 // Note: `Type` / `Static` / `TSchema` are re-exported via ./sdk-surface.js.