@bastani/atomic 0.9.0-alpha.1 → 0.9.0-alpha.2

package/dist/builtin/workflows/src/authoring/typebox-defaults.ts

@@ -0,0 +1,217 @@
+import type * as TypeBox from "typebox";
+import type {
+  TAny,
+  TArray,
+  TArrayOptions,
+  TBoolean,
+  TEnum,
+  TEnumValue,
+  TInteger,
+  TIntersect,
+  TIntersectOptions,
+  TLiteral,
+  TLiteralValue,
+  TNull,
+  TNumber,
+  TNumberOptions,
+  TObject,
+  TObjectOptions,
+  TOmit,
+  TPartial,
+  TPick,
+  TProperties,
+  TRequired,
+  TSchema,
+  TSchemaOptions,
+  TString,
+  TStringOptions,
+  TTuple,
+  TTupleOptions,
+  TTypeScriptEnumLike,
+  TTypeScriptEnumToEnumValues,
+  TUnion,
+  TUnknown,
+} from "typebox";
+import type { WorkflowSerializableValue } from "../shared/authoring-contract.js";
+
+type TypeBoxDefaultOptions<TOptions> = TOptions & {
+  readonly default: WorkflowSerializableValue;
+};
+
+type TypeBoxDefaulted<TOptions extends { readonly default: WorkflowSerializableValue }> = {
+  readonly default: TOptions["default"];
+};
+
+type TypeBoxKeysToLiterals<
+  TKeys extends readonly PropertyKey[],
+  TResult extends TLiteral[] = [],
+> = TKeys extends readonly [infer TLeft extends PropertyKey, ...infer TRight extends PropertyKey[]]
+  ? TLeft extends TLiteralValue
+    ? TypeBoxKeysToLiterals<TRight, [...TResult, TLiteral<TLeft>]>
+    : TypeBoxKeysToLiterals<TRight, TResult>
+  : TResult;
+
+type TypeBoxKeysToIndexer<TKeys extends readonly PropertyKey[]> = TUnion<TypeBoxKeysToLiterals<TKeys>>;
+
+type TypeBoxRecord<TKey extends TSchema, TValue extends TSchema> = ReturnType<typeof TypeBox.Type.Record<TKey, TValue>>;
+
+declare module "typebox" {
+  export namespace Type {
+    export function Any<const TOptions extends TypeBoxDefaultOptions<TSchemaOptions>>(
+      options: TOptions,
+    ): TAny & TypeBoxDefaulted<TOptions>;
+
+    export function Unknown<const TOptions extends TypeBoxDefaultOptions<TSchemaOptions>>(
+      options: TOptions,
+    ): TUnknown & TypeBoxDefaulted<TOptions>;
+
+    export function String<const TOptions extends TypeBoxDefaultOptions<TStringOptions>>(
+      options: TOptions,
+    ): TString & TypeBoxDefaulted<TOptions>;
+
+    export function Number<const TOptions extends TypeBoxDefaultOptions<TNumberOptions>>(
+      options: TOptions,
+    ): TNumber & TypeBoxDefaulted<TOptions>;
+
+    export function Integer<const TOptions extends TypeBoxDefaultOptions<TNumberOptions>>(
+      options: TOptions,
+    ): TInteger & TypeBoxDefaulted<TOptions>;
+
+    export function Boolean<const TOptions extends TypeBoxDefaultOptions<TSchemaOptions>>(
+      options: TOptions,
+    ): TBoolean & TypeBoxDefaulted<TOptions>;
+
+    export function Literal<
+      const TValue extends TLiteralValue,
+      const TOptions extends TypeBoxDefaultOptions<TSchemaOptions>,
+    >(
+      value: TValue,
+      options: TOptions,
+    ): TLiteral<TValue> & TypeBoxDefaulted<TOptions>;
+
+    export function Enum<
+      const TValues extends TEnumValue[],
+      const TOptions extends TypeBoxDefaultOptions<TSchemaOptions>,
+    >(
+      values: readonly [...TValues],
+      options: TOptions,
+    ): TEnum<TValues> & TypeBoxDefaulted<TOptions>;
+    export function Enum<
+      const TEnumLike extends TTypeScriptEnumLike,
+      const TOptions extends TypeBoxDefaultOptions<TSchemaOptions>,
+    >(
+      value: TEnumLike,
+      options: TOptions,
+    ): TEnum<TTypeScriptEnumToEnumValues<TEnumLike>> & TypeBoxDefaulted<TOptions>;
+
+    export function Array<
+      const TItem extends TSchema,
+      const TOptions extends TypeBoxDefaultOptions<TArrayOptions>,
+    >(
+      items: TItem,
+      options: TOptions,
+    ): TArray<TItem> & TypeBoxDefaulted<TOptions>;
+
+    export function Object<
+      const TSchemaProperties extends TProperties,
+      const TOptions extends TypeBoxDefaultOptions<TObjectOptions>,
+    >(
+      properties: TSchemaProperties,
+      options: TOptions,
+    ): TObject<TSchemaProperties> & TypeBoxDefaulted<TOptions>;
+
+    export function Partial<
+      const TType extends TSchema,
+      const TOptions extends TypeBoxDefaultOptions<TSchemaOptions>,
+    >(
+      type: TType,
+      options: TOptions,
+    ): TPartial<TType> & TypeBoxDefaulted<TOptions>;
+
+    export function Pick<
+      const TType extends TSchema,
+      const TIndexer extends PropertyKey[],
+      const TOptions extends TypeBoxDefaultOptions<TSchemaOptions>,
+    >(
+      type: TType,
+      indexer: readonly [...TIndexer],
+      options: TOptions,
+    ): TPick<TType, TypeBoxKeysToIndexer<TIndexer>> & TypeBoxDefaulted<TOptions>;
+    export function Pick<
+      const TType extends TSchema,
+      const TIndexer extends TSchema,
+      const TOptions extends TypeBoxDefaultOptions<TSchemaOptions>,
+    >(
+      type: TType,
+      indexer: TIndexer,
+      options: TOptions,
+    ): TPick<TType, TIndexer> & TypeBoxDefaulted<TOptions>;
+
+    export function Omit<
+      const TType extends TSchema,
+      const TIndexer extends PropertyKey[],
+      const TOptions extends TypeBoxDefaultOptions<TSchemaOptions>,
+    >(
+      type: TType,
+      indexer: readonly [...TIndexer],
+      options: TOptions,
+    ): TOmit<TType, TypeBoxKeysToIndexer<TIndexer>> & TypeBoxDefaulted<TOptions>;
+    export function Omit<
+      const TType extends TSchema,
+      const TIndexer extends TSchema,
+      const TOptions extends TypeBoxDefaultOptions<TSchemaOptions>,
+    >(
+      type: TType,
+      indexer: TIndexer,
+      options: TOptions,
+    ): TOmit<TType, TIndexer> & TypeBoxDefaulted<TOptions>;
+
+    export function Required<
+      const TType extends TSchema,
+      const TOptions extends TypeBoxDefaultOptions<TSchemaOptions>,
+    >(
+      type: TType,
+      options: TOptions,
+    ): TRequired<TType> & TypeBoxDefaulted<TOptions>;
+
+    export function Union<
+      const TTypes extends TSchema[],
+      const TOptions extends TypeBoxDefaultOptions<TSchemaOptions>,
+    >(
+      anyOf: [...TTypes],
+      options: TOptions,
+    ): TUnion<TTypes> & TypeBoxDefaulted<TOptions>;
+
+    export function Intersect<
+      const TTypes extends TSchema[],
+      const TOptions extends TypeBoxDefaultOptions<TIntersectOptions>,
+    >(
+      types: [...TTypes],
+      options: TOptions,
+    ): TIntersect<TTypes> & TypeBoxDefaulted<TOptions>;
+
+    export function Record<
+      const TKey extends TSchema,
+      const TValue extends TSchema,
+      const TOptions extends TypeBoxDefaultOptions<TObjectOptions>,
+    >(
+      key: TKey,
+      value: TValue,
+      options: TOptions,
+    ): TypeBoxRecord<TKey, TValue> & TypeBoxDefaulted<TOptions>;
+
+    export function Tuple<
+      const TTypes extends TSchema[],
+      const TOptions extends TypeBoxDefaultOptions<TTupleOptions>,
+    >(
+      types: [...TTypes],
+      options: TOptions,
+    ): TTuple<TTypes> & TypeBoxDefaulted<TOptions>;
+
+    export function Null<const TOptions extends TypeBoxDefaultOptions<TSchemaOptions>>(
+      options: TOptions,
+    ): TNull & TypeBoxDefaulted<TOptions>;
+  }
+}
+
+export {};

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

@@ -0,0 +1,184 @@
+import { basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+  AuthoredWorkflowSpec as SharedAuthoredWorkflowSpec,
+  WorkflowInputsFromSchemas,
+  WorkflowOutputsFromSchemas,
+  WorkflowProvidedInputsFromSchemas,
+} from "../shared/workflow-authoring-types.js";
+import type {
+  WorkflowDefinition,
+  WorkflowInputBindings,
+  WorkflowInputSchemaMap,
+  WorkflowInputValues,
+  WorkflowOutputSchemaMap,
+  WorkflowOutputValues,
+  WorkflowRunContext,
+  WorkflowRunFn,
+  WorkflowWorktreeInputBinding,
+} from "../shared/types.js";
+import { normalizeWorkflowName } from "../workflows/identity.js";
+
+export type {
+  WorkflowInputsFromSchemas,
+  WorkflowOutputsFromSchemas,
+  WorkflowProvidedInputsFromSchemas,
+} from "../shared/workflow-authoring-types.js";
+
+const BRANDED_WORKFLOW_DEFINITIONS = new WeakSet<object>();
+
+export type AuthoredWorkflowSpec<
+  TInputs extends WorkflowInputSchemaMap = {},
+  TOutputs extends WorkflowOutputSchemaMap = WorkflowOutputSchemaMap,
+  TActualOutputs extends WorkflowOutputsFromSchemas<TOutputs> = WorkflowOutputsFromSchemas<TOutputs>,
+> = SharedAuthoredWorkflowSpec<
+  TInputs,
+  TOutputs,
+  TActualOutputs,
+  WorkflowRunContext<WorkflowInputsFromSchemas<TInputs>, WorkflowOutputsFromSchemas<TOutputs>>
+>;
+
+export type AuthoredWorkflowDefinition<
+  TInputs extends WorkflowInputSchemaMap,
+  TOutputs extends WorkflowOutputSchemaMap,
+> = WorkflowDefinition<
+  WorkflowInputsFromSchemas<TInputs>,
+  WorkflowOutputsFromSchemas<TOutputs>,
+  WorkflowProvidedInputsFromSchemas<TInputs>
+> & {
+  readonly outputs: Readonly<TOutputs>;
+};
+
+// Package-internal runtime brand. It deliberately is not exported through the
+// public SDK surface; workflow({...}) and executor-created direct workflows are
+// the only package code paths that can mint accepted runtime definitions.
+export function stampWorkflowDefinition<
+  TInputs extends WorkflowInputValues,
+  TOutputs extends WorkflowOutputValues,
+  TRunInputs extends WorkflowInputValues = TInputs,
+>(
+  definition: object,
+): WorkflowDefinition<TInputs, TOutputs, TRunInputs> {
+  BRANDED_WORKFLOW_DEFINITIONS.add(definition);
+  return definition as never as WorkflowDefinition<TInputs, TOutputs, TRunInputs>;
+}
+
+export function isBrandedWorkflowDefinition(value: object): value is WorkflowDefinition {
+  return BRANDED_WORKFLOW_DEFINITIONS.has(value);
+}
+
+function requireNonEmptyString(value: string, label: string): void {
+  if (value.trim().length === 0) {
+    throw new TypeError(`workflow: ${label} must be a non-empty string`);
+  }
+}
+
+function freezeSchemaMap<TSchemas extends WorkflowInputSchemaMap | WorkflowOutputSchemaMap>(
+  schemas: TSchemas,
+): Readonly<TSchemas> {
+  return Object.freeze({ ...schemas }) as Readonly<TSchemas>;
+}
+
+function stackFilePath(line: string): string | undefined {
+  const fileUrlMatch = line.match(/\(?((?:file:\/\/)[^\s)]+?\.[cm]?[jt]sx?):\d+:\d+\)?/);
+  const rawPath = fileUrlMatch?.[1]
+    ?? line.match(/\(?((?:\/|[A-Za-z]:[\\/])[^():]+?\.[cm]?[jt]sx?):\d+:\d+\)?/)?.[1];
+  if (rawPath === undefined) return undefined;
+  if (!rawPath.startsWith("file://")) return rawPath;
+  try {
+    return fileURLToPath(rawPath);
+  } catch {
+    return undefined;
+  }
+}
+
+function isWorkflowAuthoringImplementationFrame(filePath: string): boolean {
+  const normalized = filePath.replace(/\\/g, "/");
+  if (!/\/authoring\/workflow\.[cm]?[jt]sx?$/.test(normalized)) return false;
+  return normalized.includes("/packages/workflows/")
+    || normalized.includes("/node_modules/@bastani/workflows/")
+    || normalized.includes("/dist/builtin/workflows/")
+    || normalized.includes("/.atomic/agent/extensions/workflows/")
+    || normalized.includes("/.pi/agent/extensions/workflows/");
+}
+
+function workflowNameFromCaller(): string | undefined {
+  const stack = new Error().stack;
+  if (stack === undefined) return undefined;
+
+  for (const line of stack.split("\n")) {
+    const filePath = stackFilePath(line);
+    if (filePath === undefined) continue;
+    if (isWorkflowAuthoringImplementationFrame(filePath)) continue;
+    const base = basename(filePath.replace(/\\/g, "/")).replace(/\.[cm]?[jt]sx?$/, "");
+    if (base.length > 0) return base;
+  }
+
+  return undefined;
+}
+
+function resolveWorkflowName(name: string | undefined): string {
+  const resolved = name ?? workflowNameFromCaller();
+  if (resolved === undefined) {
+    throw new TypeError("workflow: name must be provided when caller filename cannot be inferred");
+  }
+  requireNonEmptyString(resolved, "name");
+  return resolved;
+}
+
+function freezeInputBindings(
+  binding: WorkflowWorktreeInputBinding | undefined,
+): WorkflowInputBindings | undefined {
+  if (binding === undefined) return undefined;
+  return Object.freeze({
+    worktree: Object.freeze({ ...binding }),
+  });
+}
+
+export function workflow<
+  const TInputs extends WorkflowInputSchemaMap = {},
+  const TOutputs extends WorkflowOutputSchemaMap = WorkflowOutputSchemaMap,
+  TActualOutputs extends WorkflowOutputsFromSchemas<TOutputs> = WorkflowOutputsFromSchemas<TOutputs>,
+>(
+  spec: AuthoredWorkflowSpec<TInputs, TOutputs, TActualOutputs>,
+): AuthoredWorkflowDefinition<TInputs, TOutputs> {
+  const specRun = spec.run;
+  if (typeof spec.description !== "string") {
+    throw new TypeError("workflow: description must be a string");
+  }
+  if (typeof specRun !== "function") {
+    throw new TypeError("workflow: run must be a function");
+  }
+  if (spec.outputs === undefined || spec.outputs === null || typeof spec.outputs !== "object" || Array.isArray(spec.outputs)) {
+    throw new TypeError("workflow: outputs must be a schema map");
+  }
+  if (spec.inputs !== undefined && (spec.inputs === null || typeof spec.inputs !== "object" || Array.isArray(spec.inputs))) {
+    throw new TypeError("workflow: inputs must be a schema map");
+  }
+
+  const name = resolveWorkflowName(spec.name);
+  const normalizedName = normalizeWorkflowName(name);
+  requireNonEmptyString(normalizedName, "normalized name");
+  const frozenInputs = freezeSchemaMap(spec.inputs ?? {} as TInputs);
+  const frozenOutputs = freezeSchemaMap(spec.outputs);
+  const inputBindings = freezeInputBindings(spec.worktreeFromInputs);
+  const run: WorkflowRunFn<WorkflowInputsFromSchemas<TInputs>, WorkflowOutputsFromSchemas<TOutputs>> = async (ctx) => specRun(ctx);
+
+  const definition = {
+    __piWorkflow: true,
+    name,
+    normalizedName,
+    description: spec.description,
+    inputs: frozenInputs,
+    outputs: frozenOutputs,
+    ...(inputBindings !== undefined ? { inputBindings } : {}),
+    run,
+  };
+
+  const branded = stampWorkflowDefinition<
+    WorkflowInputsFromSchemas<TInputs>,
+    WorkflowOutputsFromSchemas<TOutputs>,
+    WorkflowProvidedInputsFromSchemas<TInputs>
+  >(definition);
+  return Object.freeze(branded) as AuthoredWorkflowDefinition<TInputs, TOutputs>;
+}

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

@@ -1,76 +1,24 @@
-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;
-};
+import type { TSchema } from "typebox";
 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, WorkflowCustomUiComponent, WorkflowCustomUiFactory, WorkflowCustomUiKeybindings, WorkflowCustomUiOptions, WorkflowCustomUiOverlayHandle, WorkflowCustomUiOverlayOptions, WorkflowCustomUiTheme, WorkflowCustomUiTui, WorkflowDetails, WorkflowDetailsMode, WorkflowDetailsStatus, WorkflowDirectOptions, WorkflowDirectTaskItem, WorkflowExecutionMode, WorkflowExecutionPolicy, WorkflowExitOptions, WorkflowExitStatus, 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";
+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, WorkflowCustomUiComponent, WorkflowCustomUiFactory, WorkflowCustomUiKeybindings, WorkflowCustomUiOptions, WorkflowCustomUiOverlayHandle, WorkflowCustomUiOverlayOptions, WorkflowCustomUiTheme, WorkflowCustomUiTui, WorkflowDetails, WorkflowDetailsMode, WorkflowDetailsStatus, WorkflowDirectOptions, WorkflowDirectTaskItem, WorkflowExecutionMode, WorkflowExecutionPolicy, WorkflowExitOptions, WorkflowExitStatus, WorkflowInputBindings, WorkflowInputSchema, WorkflowInputSchemaMap, WorkflowInputValues, WorkflowIntercomSummary, WorkflowMaxOutput, WorkflowMcpPort, WorkflowModelAttempt, WorkflowModelCatalogPort, WorkflowModelFallbackFields, WorkflowModelInfo, WorkflowModelUsage, WorkflowModelValue, WorkflowOutputMode, WorkflowOutputSchema, WorkflowOutputSchemaMap, WorkflowOutputValues, WorkflowParallelChainStep, WorkflowParallelOptions, WorkflowPersistencePort, WorkflowProgressSummary, WorkflowRunChildArgs, WorkflowRunChildOptions, WorkflowRunChildOptionsArgument, 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";
+import type { AuthoredWorkflowSpec as SharedAuthoredWorkflowSpec, WorkflowInputsFromSchemas, WorkflowOutputsFromSchemas, WorkflowProvidedInputsFromSchemas } from "./shared/workflow-authoring-types.js";
+export type { WorkflowInputsFromSchemas, WorkflowOutputsFromSchemas, WorkflowProvidedInputsFromSchemas, } from "./shared/workflow-authoring-types.js";
+import type { GitWorktreeSetupOptions, GitWorktreeSetupResult, ResolvedInputs, RunResult, RunStatus, StageSnapshot, WorkflowDefinition as WorkflowContractDefinition, WorkflowDetails, WorkflowDirectOptions, WorkflowDirectTaskItem, WorkflowExecutionPolicy, WorkflowInputSchemaMap, WorkflowInputValues, WorkflowOutputSchemaMap, WorkflowOutputValues, WorkflowSerializableObject, WorkflowChainStep } from "./shared/authoring-contract.js";
 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 AuthoredWorkflowDefinition<TInputs extends WorkflowInputSchemaMap, TOutputs extends WorkflowOutputSchemaMap> = WorkflowDefinition<WorkflowInputsFromSchemas<TInputs>, WorkflowOutputsFromSchemas<TOutputs>, WorkflowProvidedInputsFromSchemas<TInputs>> & {
+    readonly outputs: Readonly<TOutputs>;
+};
 export type WorkflowRunContext<TInputs extends WorkflowInputValues = WorkflowInputValues, TOutputs extends WorkflowOutputValues = WorkflowOutputValues> = AuthoringContract.WorkflowRunContext<TInputs, WorkflowDefinitionBrand, TOutputs>;
 export type WorkflowRunFn<TInputs extends WorkflowInputValues = WorkflowInputValues, TOutputs extends WorkflowOutputValues = WorkflowOutputValues> = AuthoringContract.WorkflowRunFn<TInputs, TOutputs, WorkflowDefinitionBrand>;
+type WorkflowRunInputArgument<TInputs extends WorkflowInputValues> = [keyof TInputs] extends [never] ? Readonly<Record<string, never>> : TInputs;
+export type AuthoredWorkflowSpec<TInputs extends WorkflowInputSchemaMap = {}, TOutputs extends WorkflowOutputSchemaMap = WorkflowOutputSchemaMap, TActualOutputs extends WorkflowOutputsFromSchemas<TOutputs> = WorkflowOutputsFromSchemas<TOutputs>> = SharedAuthoredWorkflowSpec<TInputs, TOutputs, TActualOutputs, WorkflowRunContext<WorkflowInputsFromSchemas<TInputs>, WorkflowOutputsFromSchemas<TOutputs>>>;
 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"> & {
@@ -78,7 +26,7 @@ export type RunOpts = Omit<AuthoringContract.RunOpts, "registry"> & {
 };
 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 run<TInputs extends WorkflowInputValues, TOutputs extends WorkflowOutputValues, TRunInputs extends WorkflowInputValues = TInputs>(definition: WorkflowDefinition<TInputs, TOutputs, TRunInputs>, inputs: Readonly<NoInfer<WorkflowRunInputArgument<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>;
@@ -86,7 +34,7 @@ export declare function runChain(steps: readonly WorkflowChainStep[], options?:
 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;
+    register<TInputs extends WorkflowInputValues, TOutputs extends WorkflowOutputValues, TRunInputs extends WorkflowInputValues = TInputs>(definition: WorkflowDefinition<TInputs, TOutputs, TRunInputs>): WorkflowRegistry;
     merge(other: WorkflowRegistry): WorkflowRegistry;
     get(name: string): AnyWorkflowDefinition | undefined;
     has(name: string): boolean;
@@ -96,10 +44,10 @@ export interface WorkflowRegistry {
 }
 /**
  * @deprecated Removed imperative workflow API. This runtime value only throws
- * a migration error; author workflows with defineWorkflow(...).compile().
+ * a migration error; author workflows with workflow({...}).
  */
 export declare const runWorkflow: never;
-export declare function defineWorkflow(name: string): WorkflowBuilder;
+export declare function workflow<const TInputs extends WorkflowInputSchemaMap = {}, const TOutputs extends WorkflowOutputSchemaMap = WorkflowOutputSchemaMap, TActualOutputs extends WorkflowOutputsFromSchemas<TOutputs> = WorkflowOutputsFromSchemas<TOutputs>>(spec: AuthoredWorkflowSpec<TInputs, TOutputs, TActualOutputs>): AuthoredWorkflowDefinition<TInputs, TOutputs>;
 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;

package/dist/builtin/workflows/src/engine/graph-inference.ts

@@ -0,0 +1,100 @@
+/**
+ * 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;
+  }
+
+  /**
+   * Snapshot the current frontier without registering or mutating a stage.
+   *
+   * Use this when an already-spawned stage needs its parents refreshed before
+   * it starts; `onSpawn` must only be called for the initial `ctx.stage()`
+   * invocation that creates the graph node.
+   */
+  currentParents(): string[] {
+    return Array.from(this.frontier);
+  }
+
+  /**
+   * Replace the recorded parents for a stage before it settles.
+   *
+   * Continuation replay uses source-run topology as authoritative: a replayed
+   * stage may spawn with provisional parents inferred from the continuation's
+   * current frontier, then install the translated source parents before the
+   * stage is recorded or settled.
+   */
+  replaceParents(stageId: string, parentIds: readonly string[]): void {
+    const parents = Array.from(parentIds);
+    this.stageParents.set(stageId, parents);
+    const node = this.nodes.get(stageId);
+    if (node !== undefined) {
+      this.nodes.set(stageId, {
+        ...node,
+        parentIds: Object.freeze(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/engine/options.ts

@@ -0,0 +1,40 @@
+import type { RunOpts } from "../runs/foreground/executor-types.js";
+
+export type EngineStageRuntimeOptions = Pick<
+  RunOpts,
+  | "continuation"
+  | "models"
+  | "executionMode"
+  | "defaultSessionDir"
+  | "persistence"
+  | "onStageStart"
+  | "onStageEnd"
+  | "confirmStageReadiness"
+  | "usePromptNodesForUi"
+>;
+
+export type EngineWorkflowBoundaryOptions = Pick<
+  RunOpts,
+  "persistence" | "onStageStart" | "onStageEnd"
+>;
+
+export type EngineChildRunOptions = Pick<
+  RunOpts,
+  | "adapters"
+  | "ui"
+  | "executionMode"
+  | "defaultSessionDir"
+  | "usePromptNodesForUi"
+  | "confirmStageReadiness"
+  | "store"
+  | "persistence"
+  | "mcp"
+  | "cancellation"
+  | "overlay"
+  | "config"
+  | "models"
+  | "registry"
+  | "stageControlRegistry"
+  | "onStageStart"
+  | "onStageEnd"
+>;