@aikirun/workflow 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -1,13 +1,13 @@
 import { WorkflowId, WorkflowVersionId } from '@aikirun/types/workflow';
 import { Client, Logger, ApiClient } from '@aikirun/types/client';
 import { INTERNAL } from '@aikirun/types/symbols';
-import { WorkflowRun, WorkflowRunStatus, WorkflowRunStateCompleted, WorkflowRunStateInComplete, WorkflowRunState, WorkflowRunId, WorkflowOptions } from '@aikirun/types/workflow-run';
+import { WorkflowRun, TerminalWorkflowRunStatus, WorkflowRunState, WorkflowRunId, WorkflowOptions } from '@aikirun/types/workflow-run';
 import { SleepParams, SleepResult } from '@aikirun/types/sleep';
-import { DurationObject } from '@aikirun/types/duration';
 import { EventSendOptions, EventWaitOptions, EventWaitState } from '@aikirun/types/event';
+import { DurationObject } from '@aikirun/types/duration';
 import { TaskPath } from '@aikirun/types/task';
 import { WorkflowRunStateRequest, TaskStateRequest } from '@aikirun/types/workflow-run-api';
-import { SerializableInput } from '@aikirun/types/error';
+import { Serializable } from '@aikirun/types/error';
 
 type NonEmptyArray<T> = [T, ...T[]];
 
@@ -28,46 +28,87 @@ type PathFromObjectInternal<T, IncludeArrayKeys extends boolean> = And<[
 type ExtractObjectType<T> = T extends object ? T : never;
 type TypeOfValueAtPath<T extends object, Path extends PathFromObject<T>> = Path extends keyof T ? T[Path] : Path extends `${infer First}.${infer Rest}` ? First extends keyof T ? undefined extends T[First] ? Rest extends PathFromObject<ExtractObjectType<T[First]>> ? TypeOfValueAtPath<ExtractObjectType<T[First]>, Rest> | undefined : never : Rest extends PathFromObject<ExtractObjectType<T[First]>> ? TypeOfValueAtPath<ExtractObjectType<T[First]>, Rest> : never : never : never;
 
-declare function workflowRunHandle<Input, Output, TEventsDefinition extends EventsDefinition>(client: Client, id: WorkflowRunId, eventsDefinition?: TEventsDefinition, logger?: Logger): Promise<WorkflowRunHandle<Input, Output, TEventsDefinition>>;
-declare function workflowRunHandle<Input, Output, TEventsDefinition extends EventsDefinition>(client: Client, run: WorkflowRun<Input, Output>, eventsDefinition?: TEventsDefinition, logger?: Logger): Promise<WorkflowRunHandle<Input, Output, TEventsDefinition>>;
-interface WorkflowRunHandle<Input, Output, TEventsDefinition extends EventsDefinition = EventsDefinition> {
+declare function workflowRunHandle<Input, Output, AppContext, TEventsDefinition extends EventsDefinition>(client: Client<AppContext>, id: WorkflowRunId, eventsDefinition?: TEventsDefinition, logger?: Logger): Promise<WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
+declare function workflowRunHandle<Input, Output, AppContext, TEventsDefinition extends EventsDefinition>(client: Client<AppContext>, run: WorkflowRun<Input, Output>, eventsDefinition?: TEventsDefinition, logger?: Logger): Promise<WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
+interface WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition extends EventsDefinition = EventsDefinition> {
     run: Readonly<WorkflowRun<Input, Output>>;
     events: EventSenders<TEventsDefinition>;
     refresh: () => Promise<void>;
-    wait<S extends WorkflowRunStatus>(condition: {
-        type: "status";
-        status: S;
-    }, options: WorkflowRunWaitOptions): Promise<{
-        success: false;
-        cause: "timeout" | "aborted";
-    } | {
-        success: true;
-        state: S extends "completed" ? WorkflowRunStateCompleted<Output> : WorkflowRunStateInComplete;
-    }>;
-    wait(condition: {
-        type: "event";
-        event: string;
-    }, options: WorkflowRunWaitOptions): Promise<{
-        success: false;
-        cause: "timeout" | "aborted";
-    } | {
-        success: true;
-        state: WorkflowRunState<Output>;
-    }>;
+    /**
+     *  Waits for the child workflow run to reach a terminal status by polling.
+     *
+     * Returns a result object:
+     * - `{ success: true, state }` - workflow reached the expected status
+     * - `{ success: false, cause }` - workflow did not reach status
+     *
+     * Possible failure causes:
+     * - `"run_terminated"` - workflow reached a terminal state other than expected
+     * - `"timeout"` - timeout elapsed (only when timeout option provided)
+     * - `"aborted"` - abort signal triggered (only when abortSignal option provided)
+     *
+     * @param status - The target status to wait for
+     * @param options - Optional configuration for polling interval, timeout, and abort signal
+     *
+     * @example
+     * // Wait indefinitely until completed or the workflow reaches another terminal state
+     * const result = await handle.waitForStatus("completed");
+     * if (result.success) {
+     *   console.log(result.state.output);
+     * } else {
+     *   console.log(`Workflow terminated: ${result.cause}`);
+     * }
+     *
+     * @example
+     * // Wait with a timeout
+     * const result = await handle.waitForStatus("completed", {
+     *   timeout: { seconds: 30 }
+     * });
+     * if (result.success) {
+     *   console.log(result.state.output);
+     * } else if (result.cause === "timeout") {
+     *   console.log("Timed out waiting for completion");
+     * }
+     *
+     * @example
+     * // Wait with an abort signal
+     * const controller = new AbortController();
+     * const result = await handle.waitForStatus("completed", {
+     *   abortSignal: controller.signal
+     * });
+     * if (!result.success) {
+     *   console.log(`Wait ended: ${result.cause}`);
+     * }
+     */
+    waitForStatus<Status extends TerminalWorkflowRunStatus>(status: Status, options?: WorkflowRunWaitOptions<false, false>): Promise<WorkflowRunWaitResult<Status, Output, false, false>>;
+    waitForStatus<Status extends TerminalWorkflowRunStatus>(status: Status, options: WorkflowRunWaitOptions<true, false>): Promise<WorkflowRunWaitResult<Status, Output, true, false>>;
+    waitForStatus<Status extends TerminalWorkflowRunStatus>(status: Status, options: WorkflowRunWaitOptions<false, true>): Promise<WorkflowRunWaitResult<Status, Output, false, true>>;
+    waitForStatus<Status extends TerminalWorkflowRunStatus>(status: Status, options: WorkflowRunWaitOptions<true, true>): Promise<WorkflowRunWaitResult<Status, Output, true, true>>;
     cancel: (reason?: string) => Promise<void>;
     pause: () => Promise<void>;
     resume: () => Promise<void>;
+    awake: () => Promise<void>;
     [INTERNAL]: {
+        client: Client<AppContext>;
         transitionState: (state: WorkflowRunStateRequest) => Promise<void>;
         transitionTaskState: (taskPath: TaskPath, taskState: TaskStateRequest) => Promise<void>;
         assertExecutionAllowed: () => void;
     };
 }
-interface WorkflowRunWaitOptions {
-    maxDurationMs: number;
-    pollIntervalMs?: number;
-    abortSignal?: AbortSignal;
+interface WorkflowRunWaitOptions<Timed extends boolean, Abortable extends boolean> {
+    interval?: DurationObject;
+    timeout?: Timed extends true ? DurationObject : never;
+    abortSignal?: Abortable extends true ? AbortSignal : never;
 }
+type WorkflowRunWaitResultSuccess<Status extends TerminalWorkflowRunStatus, Output> = Extract<WorkflowRunState<Output>, {
+    status: Status;
+}>;
+type WorkflowRunWaitResult<Status extends TerminalWorkflowRunStatus, Output, Timed extends boolean, Abortable extends boolean> = {
+    success: false;
+    cause: "run_terminated" | (Timed extends true ? "timeout" : never) | (Abortable extends true ? "aborted" : never);
+} | {
+    success: true;
+    state: WorkflowRunWaitResultSuccess<Status, Output>;
+};
 
 /**
  * Defines an event type that can be sent to and waited for by workflows.
@@ -90,6 +131,7 @@ interface WorkflowRunWaitOptions {
  * });
  * ```
  */
+declare function event(): EventDefinition<undefined>;
 declare function event<Data>(params?: EventParams<Data>): EventDefinition<Data>;
 interface EventParams<Data> {
     schema?: Schema<Data>;
@@ -107,19 +149,25 @@ type EventWaiters<TEventsDefinition extends EventsDefinition> = {
     [K in keyof TEventsDefinition]: EventWaiter<EventData<TEventsDefinition[K]>>;
 };
 interface EventWaiter<Data> {
-    wait(options?: EventWaitOptions<undefined>): Promise<EventWaitState<Data, false>>;
-    wait(options: EventWaitOptions<DurationObject>): Promise<EventWaitState<Data, true>>;
+    wait(options?: EventWaitOptions<false>): Promise<EventWaitState<Data, false>>;
+    wait(options: EventWaitOptions<true>): Promise<EventWaitState<Data, true>>;
 }
 type EventSenders<TEventsDefinition extends EventsDefinition> = {
     [K in keyof TEventsDefinition]: EventSender<EventData<TEventsDefinition[K]>>;
 };
 interface EventSender<Data> {
-    send: (data: Data, options?: EventSendOptions) => Promise<void>;
+    send: (...args: Data extends undefined ? [data?: Data, options?: EventSendOptions] : [data: Data, options?: EventSendOptions]) => Promise<void>;
+}
+type EventMulticasters<TEventsDefinition extends EventsDefinition> = {
+    [K in keyof TEventsDefinition]: EventMulticaster<EventData<TEventsDefinition[K]>>;
+};
+interface EventMulticaster<Data> {
+    send: <AppContext>(client: Client<AppContext>, runId: string | string[], data: Data, options?: EventSendOptions) => Promise<void>;
 }
-declare function createEventWaiters<TEventsDefinition extends EventsDefinition>(handle: WorkflowRunHandle<unknown, unknown, TEventsDefinition>, eventsDefinition: TEventsDefinition, logger: Logger): EventWaiters<TEventsDefinition>;
+declare function createEventWaiters<TEventsDefinition extends EventsDefinition>(handle: WorkflowRunHandle<unknown, unknown, unknown, TEventsDefinition>, eventsDefinition: TEventsDefinition, logger: Logger): EventWaiters<TEventsDefinition>;
 declare function createEventSenders<TEventsDefinition extends EventsDefinition>(api: ApiClient, workflowRunId: string, eventsDefinition: TEventsDefinition, logger: Logger, onSend: (run: WorkflowRun<unknown, unknown>) => void): EventSenders<TEventsDefinition>;
 
-interface WorkflowRunContext<Input, Output, TEventDefinition extends EventsDefinition> {
+interface WorkflowRunContext<Input, AppContext, TEventDefinition extends EventsDefinition> {
     id: WorkflowRunId;
     workflowId: WorkflowId;
     workflowVersionId: WorkflowVersionId;
@@ -128,47 +176,98 @@ interface WorkflowRunContext<Input, Output, TEventDefinition extends EventsDefin
     sleep: (params: SleepParams) => Promise<SleepResult>;
     events: EventWaiters<TEventDefinition>;
     [INTERNAL]: {
-        handle: WorkflowRunHandle<Input, Output, TEventDefinition>;
+        handle: WorkflowRunHandle<Input, unknown, AppContext, TEventDefinition>;
         options: {
             spinThresholdMs: number;
         };
     };
 }
 
+type ChildWorkflowRunHandle<Input, Output, AppContext, TEventsDefinition extends EventsDefinition = EventsDefinition> = Omit<WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>, "waitForStatus"> & {
+    /**
+     * Waits for the child workflow run to reach a terminal status.
+     *
+     * This method suspends the parent workflow until the child reaches the expected terminal status
+     * or the optional timeout elapses.
+     *
+     * When the parent resumes, the result is deterministically replayed from stored wait results.
+     *
+     * Returns a result object:
+     * - `{ success: true, state }` - child reached the expected status
+     * - `{ success: false, cause }` - child did not reach status
+     *
+     * Possible failure causes:
+     * - `"run_terminated"` - child reached a different terminal state than expected
+     * - `"timeout"` - timeout elapsed (only when timeout option provided)
+     *
+     * @param status - The target terminal status to wait for
+     * @param options - Optional configuration with timeout
+     *
+     * @example
+     * // Wait indefinitely for child to complete
+     * const result = await childHandle.waitForStatus("completed");
+     * if (result.success) {
+     *   console.log(result.state.output);
+     * } else {
+     *   console.log(`Child terminated: ${result.cause}`);
+     * }
+     *
+     * @example
+     * // Wait with a timeout
+     * const result = await childHandle.waitForStatus("completed", {
+     *   timeout: { minutes: 5 }
+     * });
+     * if (!result.success && result.cause === "timeout") {
+     *   console.log("Child workflow took too long");
+     * }
+     */
+    waitForStatus<Status extends TerminalWorkflowRunStatus>(status: Status, options?: ChildWorkflowRunWaitOptions<false>): Promise<WorkflowRunWaitResult<Status, Output, false, false>>;
+    waitForStatus<Status extends TerminalWorkflowRunStatus>(status: Status, options: ChildWorkflowRunWaitOptions<true>): Promise<WorkflowRunWaitResult<Status, Output, true, false>>;
+};
+interface ChildWorkflowRunWaitOptions<Timed extends boolean> {
+    timeout?: Timed extends true ? DurationObject : never;
+}
+
 interface WorkflowVersionParams<Input, Output, AppContext, TEventsDefinition extends EventsDefinition> {
+    handler: (input: Input, run: Readonly<WorkflowRunContext<Input, AppContext, TEventsDefinition>>, context: AppContext) => Promise<Output>;
     events?: TEventsDefinition;
     opts?: WorkflowOptions;
-    handler: (input: Input, run: Readonly<WorkflowRunContext<Input, Output, TEventsDefinition>>, context: AppContext) => Promise<Output>;
 }
 interface WorkflowBuilder<Input, Output, AppContext, TEventsDefinition extends EventsDefinition> {
     opt<Path extends PathFromObject<WorkflowOptions>>(path: Path, value: TypeOfValueAtPath<WorkflowOptions, Path>): WorkflowBuilder<Input, Output, AppContext, TEventsDefinition>;
     start: WorkflowVersion<Input, Output, AppContext, TEventsDefinition>["start"];
+    startAsChild: WorkflowVersion<Input, Output, AppContext, TEventsDefinition>["startAsChild"];
 }
 interface WorkflowVersion<Input, Output, AppContext, TEventsDefinition extends EventsDefinition = EventsDefinition> {
     id: WorkflowId;
     versionId: WorkflowVersionId;
+    events: EventMulticasters<TEventsDefinition>;
     with(): WorkflowBuilder<Input, Output, AppContext, TEventsDefinition>;
-    start: (client: Client<AppContext>, ...args: Input extends null ? [] : [Input]) => Promise<WorkflowRunHandle<Input, Output, TEventsDefinition>>;
-    getHandle: (client: Client<AppContext>, runId: WorkflowRunId) => Promise<WorkflowRunHandle<Input, Output, TEventsDefinition>>;
+    start: (client: Client<AppContext>, ...args: Input extends null ? [] : [Input]) => Promise<WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
+    startAsChild: <ParentInput, ParentEventsDefinition extends EventsDefinition>(parentRun: WorkflowRunContext<ParentInput, AppContext, ParentEventsDefinition>, ...args: Input extends null ? [] : [Input]) => Promise<ChildWorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
+    getHandle: (client: Client<AppContext>, runId: WorkflowRunId) => Promise<WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
     [INTERNAL]: {
         eventsDefinition: TEventsDefinition;
-        handler: (input: Input, run: WorkflowRunContext<Input, Output, TEventsDefinition>, context: AppContext) => Promise<void>;
+        handler: (input: Input, run: WorkflowRunContext<Input, AppContext, TEventsDefinition>, context: AppContext) => Promise<void>;
     };
 }
 declare class WorkflowVersionImpl<Input, Output, AppContext, TEventsDefinition extends EventsDefinition> implements WorkflowVersion<Input, Output, AppContext, TEventsDefinition> {
     readonly id: WorkflowId;
     readonly versionId: WorkflowVersionId;
     private readonly params;
+    readonly events: EventMulticasters<TEventsDefinition>;
     readonly [INTERNAL]: WorkflowVersion<Input, Output, AppContext, TEventsDefinition>[typeof INTERNAL];
     constructor(id: WorkflowId, versionId: WorkflowVersionId, params: WorkflowVersionParams<Input, Output, AppContext, TEventsDefinition>);
     with(): WorkflowBuilder<Input, Output, AppContext, TEventsDefinition>;
-    start(client: Client<AppContext>, ...args: Input extends null ? [] : [Input]): Promise<WorkflowRunHandle<Input, Output, TEventsDefinition>>;
-    getHandle(client: Client<AppContext>, runId: WorkflowRunId): Promise<WorkflowRunHandle<Input, Output, TEventsDefinition>>;
+    start(client: Client<AppContext>, ...args: Input extends null ? [] : [Input]): Promise<WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
+    startAsChild<ParentInput>(parentRun: WorkflowRunContext<ParentInput, AppContext, EventsDefinition>, ...args: Input extends null ? [] : [Input]): Promise<ChildWorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
+    getHandle(client: Client<AppContext>, runId: WorkflowRunId): Promise<WorkflowRunHandle<Input, Output, AppContext, TEventsDefinition>>;
     private handler;
     private tryExecuteWorkflow;
     private assertRetryAllowed;
     private createFailedState;
     private createAwaitingRetryState;
+    private getPath;
 }
 
 declare function workflowRegistry(): WorkflowRegistry;
@@ -186,7 +285,7 @@ interface WorkflowRegistry {
 interface SleeperOptions {
     spinThresholdMs: number;
 }
-declare function createSleeper(handle: WorkflowRunHandle<unknown, unknown>, logger: Logger, options: SleeperOptions): (params: SleepParams) => Promise<SleepResult>;
+declare function createSleeper(handle: WorkflowRunHandle<unknown, unknown, unknown>, logger: Logger, options: SleeperOptions): (params: SleepParams) => Promise<SleepResult>;
 
 /**
  * Defines a durable workflow with versioning and multiple task execution.
@@ -241,11 +340,11 @@ interface WorkflowParams {
 }
 interface Workflow {
     id: WorkflowId;
-    v: <Input extends SerializableInput = null, Output = void, AppContext = null, TEventsDefinition extends EventsDefinition = Record<string, never>>(versionId: string, params: WorkflowVersionParams<Input, Output, AppContext, TEventsDefinition>) => WorkflowVersion<Input, Output, AppContext, TEventsDefinition>;
+    v: <Input extends Serializable, Output extends Serializable, AppContext = null, TEventsDefinition extends EventsDefinition = Record<string, never>>(versionId: string, params: WorkflowVersionParams<Input, Output, AppContext, TEventsDefinition>) => WorkflowVersion<Input, Output, AppContext, TEventsDefinition>;
     [INTERNAL]: {
         getAllVersions: () => WorkflowVersion<unknown, unknown, unknown>[];
         getVersion: (versionId: WorkflowVersionId) => WorkflowVersion<unknown, unknown, unknown> | undefined;
     };
 }
 
-export { type EventDefinition, type EventSender, type EventSenders, type EventWaiter, type EventWaiters, type Workflow, type WorkflowParams, type WorkflowRegistry, type WorkflowRunContext, type WorkflowRunHandle, type WorkflowRunWaitOptions, type WorkflowVersion, WorkflowVersionImpl, type WorkflowVersionParams, createEventSenders, createEventWaiters, createSleeper, event, workflow, workflowRegistry, workflowRunHandle };
+export { type EventMulticaster, type EventMulticasters, type EventSender, type EventSenders, type EventWaiter, type EventWaiters, type Workflow, type WorkflowParams, type WorkflowRegistry, type WorkflowRunContext, type WorkflowRunHandle, type WorkflowRunWaitOptions, type WorkflowVersion, WorkflowVersionImpl, type WorkflowVersionParams, createEventSenders, createEventWaiters, createSleeper, event, workflow, workflowRegistry, workflowRunHandle };

package/dist/index.js

@@ -77,6 +77,14 @@ function delay(ms, options) {
   });
 }
 
+// ../../lib/crypto/hash.ts
+async function sha256(input) {
+  const data = new TextEncoder().encode(input);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
 // ../../lib/duration/convert.ts
 var MS_PER_SECOND = 1e3;
 var MS_PER_MINUTE = 60 * MS_PER_SECOND;
@@ -136,6 +144,25 @@ function createSerializableError(error) {
   };
 }
 
+// ../../lib/json/stable-stringify.ts
+function stableStringify(value) {
+  if (value === null || value === void 0) {
+    return JSON.stringify(value);
+  }
+  if (typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+  const keys = Object.keys(value).sort();
+  const pairs = keys.map((key) => {
+    const val = value[key];
+    return `${JSON.stringify(key)}:${stableStringify(val)}`;
+  });
+  return `{${pairs.join(",")}}`;
+}
+
 // ../../lib/object/overrider.ts
 function set(obj, path, value) {
   const keys = path.split(".");
@@ -279,9 +306,10 @@ function createEventWaiters(handle, eventsDefinition, logger) {
 function createEventWaiter(handle, eventId, schema, logger) {
   let nextEventIndex = 0;
   async function wait(options) {
+    await handle.refresh();
     const events = handle.run.eventsQueue[eventId]?.events ?? [];
-    if (nextEventIndex < events.length) {
-      const event2 = events[nextEventIndex];
+    const event2 = events[nextEventIndex];
+    if (event2) {
       nextEventIndex++;
       if (event2.status === "timeout") {
         logger.debug("Timed out waiting for event");
@@ -333,7 +361,8 @@ function createEventSenders(api, workflowRunId, eventsDefinition, logger, onSend
 }
 function createEventSender(api, workflowRunId, eventId, schema, logger, onSend) {
   return {
-    async send(data, options) {
+    async send(...args) {
+      const [data, options] = args;
       if (schema) {
         schema.parse(data);
       }
@@ -350,35 +379,66 @@ function createEventSender(api, workflowRunId, eventId, schema, logger, onSend)
     }
   };
 }
+function createEventMulticasters(eventsDefinition) {
+  const senders = {};
+  for (const [eventId, eventDefinition] of Object.entries(eventsDefinition)) {
+    const sender = createEventMulticaster(eventId, eventDefinition.schema);
+    senders[eventId] = sender;
+  }
+  return senders;
+}
+function createEventMulticaster(eventId, schema) {
+  return {
+    async send(client, runId, data, options) {
+      if (schema) {
+        schema.parse(data);
+      }
+      const runIds = Array.isArray(runId) ? runId : [runId];
+      await client.api.workflowRun.multicastEventV1({
+        ids: runIds,
+        eventId,
+        data,
+        options
+      });
+    }
+  };
+}
 
 // run/handle.ts
 import { INTERNAL as INTERNAL2 } from "@aikirun/types/symbols";
 import {
+  isTerminalWorkflowRunStatus,
   WorkflowRunNotExecutableError
 } from "@aikirun/types/workflow-run";
 async function workflowRunHandle(client, runOrId, eventsDefinition, logger) {
   const run = typeof runOrId !== "string" ? runOrId : (await client.api.workflowRun.getByIdV1({ id: runOrId })).run;
   return new WorkflowRunHandleImpl(
-    client.api,
+    client,
     run,
     eventsDefinition ?? {},
-    logger ?? client.logger.child({ "aiki.workflowRunId": run.id })
+    logger ?? client.logger.child({
+      "aiki.workflowId": run.workflowId,
+      "aiki.workflowVersionId": run.workflowVersionId,
+      "aiki.workflowRunId": run.id
+    })
   );
 }
 var WorkflowRunHandleImpl = class {
-  constructor(api, _run, eventsDefinition, logger) {
-    this.api = api;
+  constructor(client, _run, eventsDefinition, logger) {
     this._run = _run;
     this.logger = logger;
-    this.events = createEventSenders(this.api, this._run.id, eventsDefinition, this.logger, (run) => {
+    this.api = client.api;
+    this.events = createEventSenders(client.api, this._run.id, eventsDefinition, this.logger, (run) => {
       this._run = run;
     });
     this[INTERNAL2] = {
+      client,
       transitionState: this.transitionState.bind(this),
       transitionTaskState: this.transitionTaskState.bind(this),
       assertExecutionAllowed: this.assertExecutionAllowed.bind(this)
     };
   }
+  api;
   events;
   [INTERNAL2];
   get run() {
@@ -388,59 +448,62 @@ var WorkflowRunHandleImpl = class {
     const { run: currentRun } = await this.api.workflowRun.getByIdV1({ id: this.run.id });
     this._run = currentRun;
   }
-  // TODO: instead polling the current state, use the transition history
-  // because it is entirely possible for a workflow to flash though a state
+  // TODO: instead checking the current state, use the transition history
+  // because it is possible for a workflow to flash though a state
   // and the handle will never know that the workflow hit that state
-  async wait(condition, options) {
-    if (options.abortSignal?.aborted) {
-      throw new Error("Wait operation aborted");
-    }
-    const delayMs = options.pollIntervalMs ?? 1e3;
-    const maxAttempts = Math.ceil(options.maxDurationMs / delayMs);
-    switch (condition.type) {
-      case "status": {
-        if (options.abortSignal !== void 0) {
-          const maybeResult2 = await withRetry(
-            async () => {
-              await this.refresh();
-              return this.run.state;
-            },
-            { type: "fixed", maxAttempts, delayMs },
-            {
-              abortSignal: options.abortSignal,
-              shouldRetryOnResult: (state) => Promise.resolve(state.status !== condition.status)
-            }
-          ).run();
-          if (maybeResult2.state === "timeout" || maybeResult2.state === "aborted") {
-            return { success: false, cause: maybeResult2.state };
-          }
-          return {
-            success: true,
-            state: maybeResult2.result
-          };
-        }
-        const maybeResult = await withRetry(
-          async () => {
-            await this.refresh();
-            return this.run.state;
-          },
-          { type: "fixed", maxAttempts, delayMs },
-          { shouldRetryOnResult: (state) => Promise.resolve(state.status !== condition.status) }
-        ).run();
-        if (maybeResult.state === "timeout") {
-          return { success: false, cause: maybeResult.state };
-        }
+  async waitForStatus(status, options) {
+    return this.waitForStatusByPolling(status, options);
+  }
+  async waitForStatusByPolling(expectedStatus, options) {
+    if (options?.abortSignal?.aborted) {
+      return {
+        success: false,
+        cause: "aborted"
+      };
+    }
+    const delayMs = options?.interval ? toMilliseconds(options.interval) : 1e3;
+    const maxAttempts = options?.timeout ? Math.ceil(toMilliseconds(options.timeout) / delayMs) : Number.POSITIVE_INFINITY;
+    const retryStrategy = { type: "fixed", maxAttempts, delayMs };
+    const loadState = async () => {
+      await this.refresh();
+      return this.run.state;
+    };
+    const isNeitherExpectedNorTerminal = (state) => Promise.resolve(state.status !== expectedStatus && !isTerminalWorkflowRunStatus(state.status));
+    if (!Number.isFinite(maxAttempts) && !options?.abortSignal) {
+      const maybeResult2 = await withRetry(loadState, retryStrategy, {
+        shouldRetryOnResult: isNeitherExpectedNorTerminal
+      }).run();
+      if (maybeResult2.state === "timeout") {
+        throw new Error("Something's wrong, this should've never timed out");
+      }
+      if (await isNeitherExpectedNorTerminal(maybeResult2.result)) {
         return {
-          success: true,
-          state: maybeResult.result
+          success: false,
+          cause: "run_terminated"
         };
       }
-      case "event": {
-        throw new Error("Event-based waiting is not yet implemented");
+      return {
+        success: true,
+        state: maybeResult2.result
+      };
+    }
+    const maybeResult = options?.abortSignal ? await withRetry(loadState, retryStrategy, {
+      abortSignal: options.abortSignal,
+      shouldRetryOnResult: isNeitherExpectedNorTerminal
+    }).run() : await withRetry(loadState, retryStrategy, { shouldRetryOnResult: isNeitherExpectedNorTerminal }).run();
+    if (maybeResult.state === "completed") {
+      if (await isNeitherExpectedNorTerminal(maybeResult.result)) {
+        return {
+          success: false,
+          cause: "run_terminated"
+        };
       }
-      default:
-        return condition;
+      return {
+        success: true,
+        state: maybeResult.result
+      };
     }
+    return { success: false, cause: maybeResult.state };
   }
   async cancel(reason) {
     return this.transitionState({ status: "cancelled", reason });
@@ -451,8 +514,11 @@ var WorkflowRunHandleImpl = class {
   async resume() {
     return this.transitionState({ status: "scheduled", scheduledInMs: 0, reason: "resume" });
   }
+  async awake() {
+    return this.transitionState({ status: "scheduled", scheduledInMs: 0, reason: "awake" });
+  }
   async transitionState(targetState) {
-    if (targetState.status === "scheduled" && (targetState.reason === "new" || targetState.reason === "resume") || targetState.status === "paused" || targetState.status === "cancelled") {
+    if (targetState.status === "scheduled" && (targetState.reason === "new" || targetState.reason === "resume" || targetState.reason === "awake") || targetState.status === "paused" || targetState.status === "cancelled") {
       const { run: run2 } = await this.api.workflowRun.transitionStateV1({
         type: "pessimistic",
         id: this.run.id,
@@ -540,35 +606,121 @@ function createSleeper(handle, logger, options) {
 }
 
 // workflow.ts
-import { INTERNAL as INTERNAL5 } from "@aikirun/types/symbols";
+import { INTERNAL as INTERNAL6 } from "@aikirun/types/symbols";
 
 // workflow-version.ts
-import { INTERNAL as INTERNAL4 } from "@aikirun/types/symbols";
+import { INTERNAL as INTERNAL5 } from "@aikirun/types/symbols";
 import { TaskFailedError } from "@aikirun/types/task";
 import {
   WorkflowRunFailedError as WorkflowRunFailedError2,
+  WorkflowRunSuspendedError as WorkflowRunSuspendedError4
+} from "@aikirun/types/workflow-run";
+
+// run/handle-child.ts
+import { INTERNAL as INTERNAL4 } from "@aikirun/types/symbols";
+import {
+  isTerminalWorkflowRunStatus as isTerminalWorkflowRunStatus2,
   WorkflowRunSuspendedError as WorkflowRunSuspendedError3
 } from "@aikirun/types/workflow-run";
+async function childWorkflowRunHandle(client, path, run, parentRun, logger, eventsDefinition) {
+  const handle = await workflowRunHandle(client, run, eventsDefinition, logger);
+  return {
+    run: handle.run,
+    events: handle.events,
+    refresh: handle.refresh.bind(handle),
+    waitForStatus: createStatusWaiter(path, handle, parentRun, logger),
+    cancel: handle.cancel.bind(handle),
+    pause: handle.pause.bind(handle),
+    resume: handle.resume.bind(handle),
+    awake: handle.awake.bind(handle),
+    [INTERNAL4]: handle[INTERNAL4]
+  };
+}
+function createStatusWaiter(path, handle, parentRun, logger) {
+  let nextWaitIndex = 0;
+  async function waitForStatus(expectedStatus, options) {
+    const parentRunHandle = parentRun[INTERNAL4].handle;
+    const waitResults = parentRunHandle.run.childWorkflowRuns[path]?.statusWaitResults ?? [];
+    const waitResult = waitResults[nextWaitIndex];
+    if (waitResult) {
+      nextWaitIndex++;
+      if (waitResult.status === "timeout") {
+        logger.debug("Timed out waiting for child workflow status", { "aiki.expectedStatus": expectedStatus });
+        return {
+          success: false,
+          cause: "timeout"
+        };
+      }
+      if (waitResult.childWorkflowRunState.status === expectedStatus) {
+        return {
+          success: true,
+          state: waitResult.childWorkflowRunState
+        };
+      }
+      if (isTerminalWorkflowRunStatus2(waitResult.childWorkflowRunState.status)) {
+        logger.debug("Child workflow run reached termnial state");
+        return {
+          success: false,
+          cause: "run_terminated"
+        };
+      }
+    }
+    const { state } = handle.run;
+    if (state.status === expectedStatus) {
+      return {
+        success: true,
+        state
+      };
+    }
+    if (isTerminalWorkflowRunStatus2(state.status)) {
+      logger.debug("Child workflow run reached termnial state");
+      return {
+        success: false,
+        cause: "run_terminated"
+      };
+    }
+    const timeoutInMs = options?.timeout && toMilliseconds(options.timeout);
+    await parentRunHandle[INTERNAL4].transitionState({
+      status: "awaiting_child_workflow",
+      childWorkflowRunPath: path,
+      childWorkflowRunStatus: expectedStatus,
+      timeoutInMs
+    });
+    throw new WorkflowRunSuspendedError3(parentRun.id);
+  }
+  return waitForStatus;
+}
+
+// workflow-version.ts
 var WorkflowVersionImpl = class _WorkflowVersionImpl {
   constructor(id, versionId, params) {
     this.id = id;
     this.versionId = versionId;
     this.params = params;
-    this[INTERNAL4] = {
-      eventsDefinition: this.params.events ?? {},
+    const eventsDefinition = this.params.events ?? {};
+    this.events = createEventMulticasters(eventsDefinition);
+    this[INTERNAL5] = {
+      eventsDefinition,
       handler: this.handler.bind(this)
     };
   }
-  [INTERNAL4];
+  events;
+  [INTERNAL5];
   with() {
     const optsOverrider = objectOverrider(this.params.opts ?? {});
-    const createBuilder = (optsBuilder) => ({
-      opt: (path, value) => createBuilder(optsBuilder.with(path, value)),
-      start: (client, ...args) => new _WorkflowVersionImpl(this.id, this.versionId, { ...this.params, opts: optsBuilder.build() }).start(
-        client,
-        ...args
-      )
-    });
+    const createBuilder = (optsBuilder) => {
+      return {
+        opt: (path, value) => createBuilder(optsBuilder.with(path, value)),
+        start: (client, ...args) => new _WorkflowVersionImpl(this.id, this.versionId, {
+          ...this.params,
+          opts: optsBuilder.build()
+        }).start(client, ...args),
+        startAsChild: (parentRun, ...args) => new _WorkflowVersionImpl(this.id, this.versionId, {
+          ...this.params,
+          opts: optsBuilder.build()
+        }).startAsChild(parentRun, ...args)
+      };
+    };
     return createBuilder(optsOverrider());
   }
   async start(client, ...args) {
@@ -578,24 +730,73 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
       input: isNonEmptyArray(args) ? args[0] : null,
       options: this.params.opts
     });
-    return workflowRunHandle(client, run, this[INTERNAL4].eventsDefinition);
+    return workflowRunHandle(client, run, this[INTERNAL5].eventsDefinition);
+  }
+  async startAsChild(parentRun, ...args) {
+    const parentRunHandle = parentRun[INTERNAL5].handle;
+    parentRunHandle[INTERNAL5].assertExecutionAllowed();
+    const { client } = parentRunHandle[INTERNAL5];
+    const input = isNonEmptyArray(args) ? args[0] : null;
+    const childRunPath = await this.getPath(input);
+    const existingChildRunId = parentRunHandle.run.childWorkflowRuns[childRunPath]?.id;
+    if (existingChildRunId) {
+      const { run: existingChildRun } = await client.api.workflowRun.getByIdV1({ id: existingChildRunId });
+      const logger2 = parentRun.logger.child({
+        "aiki.childWorkflowId": existingChildRun.workflowId,
+        "aiki.childWorkflowVersionId": existingChildRun.workflowVersionId,
+        "aiki.childWorkflowRunId": existingChildRun.id
+      });
+      return childWorkflowRunHandle(
+        client,
+        childRunPath,
+        existingChildRun,
+        parentRun,
+        logger2,
+        this[INTERNAL5].eventsDefinition
+      );
+    }
+    const { run: newChildRun } = await client.api.workflowRun.createV1({
+      workflowId: this.id,
+      workflowVersionId: this.versionId,
+      input,
+      path: childRunPath,
+      parentWorkflowRunId: parentRun.id,
+      options: {
+        ...this.params.opts,
+        idempotencyKey: childRunPath
+      }
+    });
+    parentRunHandle.run.childWorkflowRuns[childRunPath] = { id: newChildRun.id, statusWaitResults: [] };
+    const logger = parentRun.logger.child({
+      "aiki.childWorkflowId": newChildRun.workflowId,
+      "aiki.childWorkflowVersionId": newChildRun.workflowVersionId,
+      "aiki.childWorkflowRunId": newChildRun.id
+    });
+    return childWorkflowRunHandle(
+      client,
+      childRunPath,
+      newChildRun,
+      parentRun,
+      logger,
+      this[INTERNAL5].eventsDefinition
+    );
   }
   async getHandle(client, runId) {
-    return workflowRunHandle(client, runId, this[INTERNAL4].eventsDefinition);
+    return workflowRunHandle(client, runId, this[INTERNAL5].eventsDefinition);
   }
   async handler(input, run, context) {
     const { logger } = run;
-    const { handle } = run[INTERNAL4];
-    handle[INTERNAL4].assertExecutionAllowed();
+    const { handle } = run[INTERNAL5];
+    handle[INTERNAL5].assertExecutionAllowed();
     const retryStrategy = this.params.opts?.retry ?? { type: "never" };
     const state = handle.run.state;
     if (state.status === "queued" && state.reason === "retry") {
       await this.assertRetryAllowed(handle, retryStrategy, logger);
     }
     logger.info("Starting workflow");
-    await handle[INTERNAL4].transitionState({ status: "running" });
+    await handle[INTERNAL5].transitionState({ status: "running" });
     const output = await this.tryExecuteWorkflow(input, run, context, retryStrategy);
-    await handle[INTERNAL4].transitionState({ status: "completed", output });
+    await handle[INTERNAL5].transitionState({ status: "completed", output });
     logger.info("Workflow complete");
   }
   async tryExecuteWorkflow(input, run, context, retryStrategy) {
@@ -603,15 +804,15 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
       try {
         return await this.params.handler(input, run, context);
       } catch (error) {
-        if (error instanceof WorkflowRunSuspendedError3) {
+        if (error instanceof WorkflowRunSuspendedError4 || error instanceof WorkflowRunFailedError2) {
           throw error;
         }
-        const { handle } = run[INTERNAL4];
+        const { handle } = run[INTERNAL5];
         const attempts = handle.run.attempts;
         const retryParams = getRetryParams(attempts, retryStrategy);
         if (!retryParams.retriesLeft) {
           const failedState = this.createFailedState(error);
-          await handle[INTERNAL4].transitionState(failedState);
+          await handle[INTERNAL5].transitionState(failedState);
           const logMeta2 = {};
           for (const [key, value] of Object.entries(failedState)) {
             logMeta2[`aiki.${key}`] = value;
@@ -623,7 +824,7 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
           throw new WorkflowRunFailedError2(run.id, attempts);
         }
         const awaitingRetryState = this.createAwaitingRetryState(error, retryParams.delayMs);
-        await handle[INTERNAL4].transitionState(awaitingRetryState);
+        await handle[INTERNAL5].transitionState(awaitingRetryState);
         const logMeta = {};
         for (const [key, value] of Object.entries(awaitingRetryState)) {
           logMeta[`aiki.${key}`] = value;
@@ -633,7 +834,7 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
           "aiki.delayMs": retryParams.delayMs,
           ...logMeta
         });
-        throw new WorkflowRunSuspendedError3(run.id);
+        throw new WorkflowRunSuspendedError4(run.id);
       }
     }
   }
@@ -644,7 +845,7 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
       logger.error("Workflow retry not allowed", { "aiki.attempts": attempts });
       const error = new WorkflowRunFailedError2(id, attempts);
       const serializableError = createSerializableError(error);
-      await handle[INTERNAL4].transitionState({
+      await handle[INTERNAL5].transitionState({
         status: "failed",
         cause: "self",
         error: serializableError
@@ -684,6 +885,11 @@ var WorkflowVersionImpl = class _WorkflowVersionImpl {
       error: serializableError
     };
   }
+  async getPath(input) {
+    const inputHash = await sha256(stableStringify(input));
+    const path = this.params.opts?.idempotencyKey ? `${this.id}/${this.versionId}/${inputHash}/${this.params.opts.idempotencyKey}` : `${this.id}/${this.versionId}/${inputHash}`;
+    return path;
+  }
 };
 
 // workflow.ts
@@ -692,11 +898,11 @@ function workflow(params) {
 }
 var WorkflowImpl = class {
   id;
-  [INTERNAL5];
+  [INTERNAL6];
   workflowVersions = /* @__PURE__ */ new Map();
   constructor(params) {
     this.id = params.id;
-    this[INTERNAL5] = {
+    this[INTERNAL6] = {
       getAllVersions: this.getAllVersions.bind(this),
       getVersion: this.getVersion.bind(this)
     };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@aikirun/workflow",
-	"version": "0.6.0",
+	"version": "0.7.0",
 	"description": "Workflow SDK for Aiki - define durable workflows with tasks, sleeps, waits, and event handling",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -18,7 +18,7 @@
 		"build": "tsup"
 	},
 	"dependencies": {
-		"@aikirun/types": "0.6.0"
+		"@aikirun/types": "0.7.0"
 	},
 	"publishConfig": {
 		"access": "public"