@warlock.js/ai 4.1.1

package/esm/contracts/workflow/retry-config.type.d.mts

@@ -0,0 +1,19 @@
+//#region ../../@warlock.js/ai/src/contracts/workflow/retry-config.type.d.ts
+/**
+ * Backoff strategy for step retries.
+ *
+ * - `"none"` — immediate retry, no delay
+ * - `"linear"` — attempt N waits `N * 500ms` (capped at 30s)
+ * - `"exponential"` — 500ms, 1s, 2s, 4s, ... (capped at 30s)
+ * - custom `(attempt) => ms` — full control (attempt is 1-based)
+ */
+type RetryBackoff = "none" | "linear" | "exponential" | ((attempt: number) => number);
+type RetryConfig = {
+  /** Total attempts including the first. Default 1 (no retry). */attempts: number; /** Backoff strategy between attempts. Default `"exponential"`. */
+  backoff?: RetryBackoff; /** Per-error predicate; return false to skip remaining attempts. */
+  retryOn?: (error: unknown, attempt: number) => boolean; /** Hook fired before each retry (not the first attempt). */
+  onRetry?: (attempt: number, error: unknown) => void;
+};
+//#endregion
+export { RetryBackoff, RetryConfig };
+//# sourceMappingURL=retry-config.type.d.mts.map

package/esm/contracts/workflow/retry-config.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-config.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/workflow/retry-config.type.ts"],"mappings":";;AAQA;;;;AAIqB;AAErB;;KANY,YAAA,yCAIN,OAAe;AAAA,KAET,WAAA;EAEV,gEAAA,QAAA,UAEU;EAAV,OAAA,GAAU,YAAY,EAEX;EAAX,OAAA,IAAW,KAAA,WAAgB,OAAA,sBAE3B;EAAA,OAAA,IAAW,OAAA,UAAiB,KAAA;AAAA"}

package/esm/contracts/workflow/step.contract.d.mts

@@ -0,0 +1,189 @@
+import { AIError } from "../../errors/ai-error.mjs";
+import { AgentContract } from "../agent/agent.contract.mjs";
+import { NextStepResult } from "./next-step-result.type.mjs";
+import { RetryConfig } from "./retry-config.type.mjs";
+import { WorkflowContext } from "./workflow-context.type.mjs";
+import { AgentExecuteOptions } from "../agent/agent-options.type.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region ../../@warlock.js/ai/src/contracts/workflow/step.contract.d.ts
+/**
+ * Step-local event payloads. Fired on per-step `on: { ... }` handlers
+ * in addition to the workflow-level `workflow.step.*` events — useful
+ * when you want a handler scoped to one step only.
+ */
+type StepLocalEvents = {
+  /** Before the step's lifecycle starts (after `skip` evaluates false). */starting: {
+    step: string;
+  }; /** Fired before every retry attempt (not the first). */
+  retrying: {
+    step: string;
+    attempt: number;
+    totalAttempts: number;
+    lastError: unknown;
+  }; /** Fired once after all retry attempts are exhausted. */
+  failed: {
+    step: string;
+    error: unknown;
+    attempts: number;
+  }; /** Fired when the step completes successfully. */
+  completed: {
+    step: string;
+    output: unknown;
+    duration: number;
+  };
+};
+/**
+ * Input built by `input(ctx)` when the step has an `agent`. Carries
+ * the prompt string plus any per-call agent options (history,
+ * attachments, placeholders, per-call output schema, etc.).
+ */
+type StepAgentInput = AgentExecuteOptions<unknown> & {
+  /** Prompt text passed to `agent.execute(prompt, options)`. */prompt: string;
+};
+/**
+ * Output extraction spec. `extract(ctx)` reads from `ctx.agentResult`
+ * (for agent steps), the step's `run()` return value, or `ctx.state`
+ * and produces the value stored at `step.output` in the snapshot.
+ *
+ * If `schema` is supplied, the extracted value is validated against it;
+ * validation failures throw `SchemaValidationError` and trip the
+ * step's retry logic (a retryable failure).
+ */
+type StepOutputSpec<TOutput = unknown, TInput = unknown, TState = Record<string, unknown>, TContext = unknown> = {
+  extract: (ctx: WorkflowContext<TInput, TState, TContext>) => TOutput | Promise<TOutput>;
+  schema?: StandardSchemaV1<TOutput>;
+};
+/**
+ * Static declaration of a single workflow step.
+ *
+ * **Step kind.** Exactly one of `run`, `agent`, or `parallel` must be
+ * set. `input` is required when `agent` is set. The step factory
+ * (`ai.step`) throws a `WorkflowError` at authoring time when these
+ * invariants are broken.
+ *
+ * **Lifecycle order (happy path).**
+ * ```
+ * skip? → before? → (run | agent | parallel) → output?.extract (+ schema) → after?
+ *                                                                            ↓
+ *                                                                         nextStep?
+ * ```
+ * Retry wraps the middle block (`before → run|agent → output → after`);
+ * `skip` / `nextStep` / `onCancel` sit outside the retry loop.
+ */
+type StepDefinition<TInput = unknown, TState = Record<string, unknown>, TContext = unknown> = {
+  /**
+   * Unique step name. Must be unique within the workflow (including
+   * across parallel children). Used as the key in `ctx.steps` and
+   * `report.steps`, as the routing target for `{ goto: "..." }`, and
+   * as the identifier in every event payload.
+   */
+  name: string;
+  /**
+   * Skip guard. Evaluated BEFORE `before`. Returns `true` to bypass
+   * the step entirely — `before` / `run` / `agent` / `output` / `after`
+   * are never invoked, the snapshot is marked `{ skipped: true,
+   * status: "skipped" }`, and `nextStep` still fires so routing can
+   * react to the skip.
+   */
+  skip?: (ctx: WorkflowContext<TInput, TState, TContext>) => boolean | Promise<boolean>;
+  /**
+   * Pre-work hook. Runs inside the retry loop before `run` / `agent`.
+   * Mutate `ctx.state` here for setup (fetching prerequisites, setting
+   * derived values, validating preconditions). A throw fails the
+   * attempt and triggers retry (if configured).
+   */
+  before?: (ctx: WorkflowContext<TInput, TState, TContext>) => void | Promise<void>;
+  /**
+   * Core work for non-agent steps. Receives the context and may return
+   * any value; the return value is exposed to `output.extract` via
+   * `ctx.agentResult`. Mutually exclusive with `agent` and `parallel`.
+   */
+  run?: (ctx: WorkflowContext<TInput, TState, TContext>) => unknown;
+  /**
+   * Agent to execute for this step. Mutually exclusive with `run` and
+   * `parallel`. The agent receives `input(ctx)`'s prompt (and any
+   * options from the same call); its `AgentResult` is stored on
+   * `ctx.agentResult` for downstream `output.extract` / `after` use
+   * and aggregated into `report.steps[name].executionResult`.
+   */
+  agent?: AgentContract<unknown>;
+  /**
+   * Builds the prompt + per-call options for `agent`. Required when
+   * `agent` is set. Runs once per retry attempt so the prompt can
+   * incorporate fresh context (e.g., loop-back feedback on
+   * `ctx.state.qaFeedback`).
+   */
+  input?: (ctx: WorkflowContext<TInput, TState, TContext>) => StepAgentInput | Promise<StepAgentInput>;
+  /**
+   * Output extraction spec. Runs after `run` / `agent`. Without this
+   * the step's `output` in the snapshot is `undefined`. A throw (or
+   * schema validation failure) fails the attempt and triggers retry.
+   */
+  output?: StepOutputSpec<unknown, TInput, TState, TContext>;
+  /**
+   * Post-work hook. Runs inside the retry loop AFTER `output.extract`.
+   * Intended for side effects (save to DB, send notification, fire
+   * webhook). A throw fails the attempt and triggers retry — so keep
+   * `after` work idempotent.
+   */
+  after?: (ctx: WorkflowContext<TInput, TState, TContext>) => void | Promise<void>;
+  /**
+   * Step-level routing. Runs OUTSIDE the retry loop, once per step
+   * completion — but ONLY for `completed` and `skipped` outcomes. A
+   * step whose retries are exhausted (`failed`) bypasses `nextStep`
+   * and goes through `onFailure` (if defined) or halts the workflow.
+   * Return `{ goto, end, void }` — step-level wins over workflow-level;
+   * `void` falls through. Errors here are NOT retried: routing is
+   * authoritative, so a throw terminates the workflow with
+   * `RoutingError`.
+   */
+  nextStep?: (ctx: WorkflowContext<TInput, TState, TContext>) => NextStepResult | Promise<NextStepResult>;
+  /**
+   * Failure-routing hook. Runs OUTSIDE the retry loop, once after all
+   * retry attempts are exhausted, before the workflow halts. Return:
+   * - `{ goto: "name" }` to redirect to a recovery step (workflow
+   *   continues; final status becomes `completed` if recovery succeeds)
+   * - `{ end: true }` to terminate cleanly without an error
+   * - `void` (or omit) to halt the workflow with the original
+   *   `StepFailedError` — same as if no `onFailure` were defined
+   *
+   * The step's snapshot retains `status: "failed"` and `error` for
+   * forensic trace even when `onFailure` recovers the run. Errors
+   * thrown from `onFailure` are NOT retried — they terminate the
+   * workflow with `RoutingError` (mirrors `nextStep`).
+   */
+  onFailure?: (ctx: WorkflowContext<TInput, TState, TContext>, error: AIError) => NextStepResult | Promise<NextStepResult>;
+  /**
+   * Cancellation cleanup. Runs best-effort when the workflow is
+   * aborted while this step is in-flight. Typical use: release a
+   * reservation, flush a partial write, cancel an external job. Errors
+   * thrown from `onCancel` are swallowed + logged — never rethrown.
+   */
+  onCancel?: (ctx: WorkflowContext<TInput, TState, TContext>) => void | Promise<void>;
+  /**
+   * Retry configuration. Overrides workflow-level `defaultRetry`.
+   * `false` disables retry entirely. See `RetryConfig` for backoff
+   * options. Retry wraps `before → run|agent → output → after`;
+   * `AbortError` short-circuits the loop.
+   */
+  retry?: RetryConfig | false;
+  /**
+   * Parallel children — run concurrently, share `ctx.state`
+   * (last-write-wins). Mutually exclusive with `run` and `agent`.
+   * The parent's snapshot is atomic: written only after every child
+   * settles. Children are addressable at both `ctx.steps.<child>` and
+   * `ctx.steps.<parent>.steps.<child>`.
+   */
+  parallel?: StepDefinition<TInput, TState, TContext>[];
+  /**
+   * Per-step event handlers — fires alongside the workflow-level
+   * `workflow.step.*` events. Scope is step-local (no `workflow.`
+   * prefix); payload includes the step name for symmetry with the
+   * workflow-level events.
+   */
+  on?: Partial<{ [K in keyof StepLocalEvents]: (payload: StepLocalEvents[K]) => void }>;
+};
+//#endregion
+export { StepAgentInput, StepDefinition, StepLocalEvents, StepOutputSpec };
+//# sourceMappingURL=step.contract.d.mts.map

package/esm/contracts/workflow/step.contract.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/workflow/step.contract.ts"],"mappings":";;;;;;;;;;;;AAaA;;KAAY,eAAA;EAAe,yEAEzB,QAAA;IAAY,IAAA;EAAA,GAGV;EADF,QAAA;IACE,IAAA;IACA,OAAA;IACA,aAAA;IACA,SAAA;EAAA,GAGsC;EAAxC,MAAA;IAAU,IAAA;IAAc,KAAA;IAAgB,QAAA;EAAA,GAEY;EAApD,SAAA;IAAa,IAAA;IAAc,MAAA;IAAiB,QAAA;EAAA;AAAA;;;;;;KAQlC,cAAA,GAAiB,mBAAmB;EAqBvC,8DAnBP,MAAM;AAAA;;;;;;;;;;KAYI,cAAA,+CAGD,MAAA;EAGT,OAAA,GACE,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,MAClC,OAAA,GAAU,OAAA,CAAQ,OAAA;EACvB,MAAA,GAAS,gBAAA,CAAiB,OAAA;AAAA;;;;;;;;;;;AAAO;AAoBnC;;;;;;KAAY,cAAA,4BAED,MAAA;EAkBI;;;;;;EATb,IAAA;EAwB4B;;;;;;;EAf5B,IAAA,IAAQ,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,gBAAwB,OAAA;EAgCvD;;;;;;EAxBd,MAAA,IAAU,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,aAAqB,OAAA;EA+B3D;;;;;EAxBT,GAAA,IAAO,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA;EA4CX;;;;;;;EAnCjC,KAAA,GAAQ,aAAA;EAoDuB;;;;;;EA5C/B,KAAA,IAAS,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,MAAc,cAAA,GAAiB,OAAA,CAAQ,cAAA;EAsDpD;;;;;EA/CjC,MAAA,GAAS,cAAA,UAAwB,MAAA,EAAQ,MAAA,EAAQ,QAAA;EAgEvB;;;;;;EAxD1B,KAAA,IAAS,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,aAAqB,OAAA;EAgE9D;;;;;;;;;;EApDL,QAAA,IAAY,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,MAAc,cAAA,GAAiB,OAAA,CAAQ,cAAA;EA3DnD;;;;;;;;;;;;;;EA2ErC,SAAA,IACE,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,GACrC,KAAA,EAAO,OAAA,KACJ,cAAA,GAAiB,OAAA,CAAQ,cAAA;EA/Dc;;;;;;EAuE5C,QAAA,IAAY,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,aAAqB,OAAA;EAtDhC;;;;;;EA8DtC,KAAA,GAAQ,WAAA;EAvDC;;;;;;;EAgET,QAAA,GAAW,cAAA,CAAe,MAAA,EAAQ,MAAA,EAAQ,QAAA;EAxDI;;;;;;EAgE9C,EAAA,GAAK,OAAA,eACS,eAAA,IAAmB,OAAA,EAAS,eAAA,CAAgB,CAAA;AAAA"}

package/esm/contracts/workflow/workflow-context.type.d.mts

@@ -0,0 +1,45 @@
+import { AgentResult } from "../result/agent-result.type.mjs";
+import { StepSnapshot } from "../result/step-result.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/workflow/workflow-context.type.d.ts
+/**
+ * Context threaded through every step lifecycle phase.
+ *
+ * Invariants:
+ * - `input` is deep-frozen and never changes
+ * - `context` is deep-frozen and never changes — request-scoped
+ *   envelope (tenancy, current user, locale, traceId). Supplied via
+ *   `execute({ context })` / `resume({ context })`. NOT persisted in
+ *   snapshots; resume callers must pass it fresh. Defaults to `{}`
+ *   when the caller omits it, so readers never need a guard.
+ * - `steps` is a frozen map of completed step snapshots
+ * - `state` is mutable during a step; frozen into `steps[name].state`
+ *   when the step completes
+ * - `agentResult` is framework-owned — set when the current step has
+ *   an `agent`, reset between steps
+ *
+ * `input` vs `context` — quick rule: if the field defines *what* to
+ * process, it's `input` (durable cause; replayed verbatim on resume).
+ * If it defines *who's running it* / *what request scope this is*,
+ * it's `context` (per-execution envelope; supplied fresh on resume).
+ */
+type WorkflowContext<TInput = unknown, TState = Record<string, unknown>, TContext = unknown> = {
+  readonly input: TInput;
+  readonly context: TContext;
+  readonly steps: Readonly<Record<string, StepSnapshot>>;
+  state: TState;
+  readonly agentResult?: AgentResult<unknown>;
+  readonly runId: string;
+  readonly signal?: AbortSignal;
+  /**
+   * Workflow start time as a `Date`. Stable across resume — on a
+   * resumed run this reflects the *original* start, not the resume
+   * moment. Use `Date.now() - ctx.startedAt.getTime()` for elapsed
+   * time, or `ctx.startedAt.toISOString()` when you need the string
+   * form (matches `report.startedAt`).
+   */
+  readonly startedAt: Date;
+};
+//#endregion
+export { WorkflowContext };
+//# sourceMappingURL=workflow-context.type.d.mts.map

package/esm/contracts/workflow/workflow-context.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-context.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/workflow/workflow-context.type.ts"],"mappings":";;;;;;AAwBA;;;;;;;;;;;;;;;;;;;KAAY,eAAA,4BAED,MAAA;EAAA,SAGA,KAAA,EAAO,MAAA;EAAA,SACP,OAAA,EAAS,QAAA;EAAA,SACT,KAAA,EAAO,QAAA,CAAS,MAAA,SAAe,YAAA;EACxC,KAAA,EAAO,MAAA;EAAA,SACE,WAAA,GAAc,WAAA;EAAA,SACd,KAAA;EAAA,SACA,MAAA,GAAS,WAAA;EAHlB;;;;;;;EAAA,SAWS,SAAA,EAAW,IAAA;AAAA"}

package/esm/contracts/workflow/workflow-snapshot.type.d.mts

@@ -0,0 +1,24 @@
+import { ExecutionStatus } from "../result/execution-report.type.mjs";
+import { StepSnapshot } from "../result/step-result.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/workflow/workflow-snapshot.type.d.ts
+/**
+ * Serializable workflow state written to the configured `KVStore`
+ * after every step completion.
+ */
+type WorkflowSnapshot = {
+  runId: string;
+  workflowName: string;
+  signature: string;
+  version?: string;
+  input: unknown;
+  state: Record<string, unknown>;
+  steps: Record<string, StepSnapshot>; /** Resolved next step name; null when the workflow has ended. */
+  next: string | null;
+  status: ExecutionStatus | "running";
+  startedAt: string;
+  savedAt: string;
+};
+//#endregion
+export { WorkflowSnapshot };
+//# sourceMappingURL=workflow-snapshot.type.d.mts.map

package/esm/contracts/workflow/workflow-snapshot.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-snapshot.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/workflow/workflow-snapshot.type.ts"],"mappings":";;;;;;AAOA;;KAAY,gBAAA;EACV,KAAA;EACA,YAAA;EACA,SAAA;EACA,OAAA;EACA,KAAA;EACA,KAAA,EAAO,MAAA;EACP,KAAA,EAAO,MAAA,SAAe,YAAA,GALtB;EAOA,IAAA;EACA,MAAA,EAAQ,eAAA;EACR,SAAA;EACA,OAAA;AAAA"}

package/esm/contracts/workflow/workflow.contract.d.mts

@@ -0,0 +1,142 @@
+import { ExecutableContract } from "../executable.contract.mjs";
+import { WorkflowResult } from "../result/workflow-result.type.mjs";
+import { ToolContract } from "../../tool/tool.mjs";
+import { NextStepResult } from "./next-step-result.type.mjs";
+import { RetryConfig } from "./retry-config.type.mjs";
+import { WorkflowContext } from "./workflow-context.type.mjs";
+import { StepDefinition, StepOutputSpec } from "./step.contract.mjs";
+import { WorkflowEventMap } from "../events/event-map.type.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+import { CacheDriver } from "@warlock.js/cache";
+
+//#region ../../@warlock.js/ai/src/contracts/workflow/workflow.contract.d.ts
+type WorkflowEventHandler<K extends keyof WorkflowEventMap> = (payload: WorkflowEventMap[K]) => void;
+type WorkflowEventHandlers = Partial<{ [K in keyof WorkflowEventMap]: WorkflowEventHandler<K> }>;
+/**
+ * Per-run options for `workflow.execute()`. Carries runtime knobs —
+ * everything here is per-call, not per-factory.
+ */
+type WorkflowRunOptions<TContext = unknown> = {
+  /** Caller-chosen runId. Auto-generated (`wf_<rand>`) when omitted. */runId?: string; /** Cancellation handle — between-step + in-flight agent abort. */
+  signal?: AbortSignal; /** Per-execution event handlers (layer 3 of the 3-tier model). */
+  on?: WorkflowEventHandlers;
+  /**
+   * Request-scoped envelope exposed as `ctx.context` to every step.
+   * Frozen, never persisted in snapshots — resume callers must
+   * supply it fresh. Use for tenancy (`organizationId`), the current
+   * user, locale, traceId — anything that scopes the run without
+   * being part of the durable input. Defaults to `{}` when omitted.
+   */
+  context?: TContext;
+  /**
+   * Opaque caller-supplied identifier that groups multiple `execute()`
+   * calls into one conceptual user session / request. Mirrored onto
+   * every report node this run produces — including child steps and
+   * agents dispatched by steps — so flat queries don't need to walk
+   * the tree.
+   */
+  sessionId?: string;
+};
+/**
+ * Combined-object form accepted by the single-argument overload of
+ * `workflow.execute(options)`. Equivalent to `execute(input, options)`
+ * with `input` bundled in.
+ */
+type WorkflowExecuteOptions<TInput = unknown, TContext = unknown> = WorkflowRunOptions<TContext> & {
+  input: TInput;
+};
+type WorkflowResumeOptions<TContext = unknown> = WorkflowRunOptions<TContext> & {
+  /** Bypass signature drift check. Use when you know the workflow
+   *  definition change is safe for in-flight snapshots. */
+  force?: boolean;
+};
+type WorkflowDefinition<TInput = unknown, TOutput = unknown, TState = Record<string, unknown>, TContext = unknown> = {
+  name: string;
+  /**
+   * Short natural-language summary of what the workflow does. Surfaced
+   * to `ai.supervisor()`'s router prompt and to `workflow.asTool()` as
+   * the default tool description.
+   */
+  description?: string;
+  version?: string;
+  steps: StepDefinition<TInput, TState, TContext>[];
+  /**
+   * Optional durable store enabling `workflow.resume(runId)`. Accepts
+   * any `@warlock.js/cache` driver — `MemoryCacheDriver` for
+   * dev/tests, `RedisCacheDriver` / `PgCacheDriver` for production.
+   *
+   * Falls back to `ai.config({ defaultStore })` when omitted. When
+   * neither is set, `resume()` throws and snapshot writes silently
+   * skip (current behavior preserved).
+   */
+  snapshotStore?: CacheDriver<any, any>;
+  /**
+   * Default retry applied to every step that doesn't supply its own
+   * `retry`. `undefined` (omitted) means "no retry" — resolves to
+   * `{ attempts: 1 }` at runtime. `false` also means no retry; use
+   * it to be explicit when you want to lock out retries even for
+   * steps that set their own `retry`.
+   *
+   * Resolution precedence: `step.retry` → `defaultRetry` → `{ attempts: 1 }`.
+   */
+  defaultRetry?: RetryConfig | false;
+  maxSteps?: number;
+  loopWarnAfter?: number;
+  nextStep?: (stepName: string, ctx: WorkflowContext<TInput, TState, TContext>) => NextStepResult | Promise<NextStepResult>;
+  output?: StepOutputSpec<TOutput, TInput, TState, TContext>;
+  on?: WorkflowEventHandlers;
+};
+/**
+ * Runtime handle returned by `ai.workflow(def)`. Implements the
+ * 3-tier event subscription model (factory → instance → per-call)
+ * and satisfies `ExecutableContract` so orchestrators / supervisors
+ * can invoke any primitive with one uniform signature.
+ */
+interface WorkflowInstance<TInput = unknown, TOutput = unknown, TState = Record<string, unknown>, TContext = unknown> extends ExecutableContract<TInput, WorkflowRunOptions<TContext>, WorkflowResult<TOutput>> {
+  readonly name: string;
+  readonly description?: string;
+  readonly signature: string;
+  readonly version?: string;
+  /**
+   * Run the workflow. Two interchangeable call shapes:
+   *
+   * ```ts
+   * wf.execute(input);                         // minimal
+   * wf.execute(input, { runId, signal, on }); // canonical — mirrors agent.execute
+   * wf.execute({ input, runId, signal, on }); // single-object — ergonomic alt
+   * ```
+   *
+   * Runtime picks the combined form when exactly one argument is
+   * passed and it is a plain object carrying an `input` property. If
+   * your real `input` has a top-level `input` key, prefer the
+   * two-arg form to avoid ambiguity.
+   */
+  execute(input: TInput, options?: WorkflowRunOptions<TContext>): Promise<WorkflowResult<TOutput>>;
+  execute(options: WorkflowExecuteOptions<TInput, TContext>): Promise<WorkflowResult<TOutput>>;
+  resume(runId: string, options?: WorkflowResumeOptions<TContext>): Promise<WorkflowResult<TOutput>>;
+  on<K extends keyof WorkflowEventMap>(event: K, handler: WorkflowEventHandler<K>): () => void;
+  off<K extends keyof WorkflowEventMap>(event: K, handler: WorkflowEventHandler<K>): void;
+  /**
+   * Wrap this workflow as a `ToolContract` so an agent can invoke it
+   * inside its tool-call loop. The tool's `name` mirrors the workflow's
+   * `name` (must be set — anonymous workflows throw `WorkflowError`),
+   * its `input` is the supplied schema, and its `execute()` runs
+   * `workflow.execute(input)`. Workflow errors surface to the agent as
+   * `ToolExecutionError` with `cause` set to the original
+   * `WorkflowError` subclass.
+   *
+   * @example
+   * const wrapped = wf.asTool({
+   *   description: "Run support-ticket triage",
+   *   inputSchema: ticketSchema,
+   * });
+   * const a = ai.agent({ model, tools: [wrapped] });
+   */
+  asTool<TToolInput = TInput>(options: {
+    description?: string;
+    inputSchema: StandardSchemaV1<TToolInput>;
+  }): ToolContract<TToolInput, TOutput>;
+}
+//#endregion
+export { WorkflowDefinition, WorkflowEventHandler, WorkflowEventHandlers, WorkflowExecuteOptions, WorkflowInstance, WorkflowResumeOptions, WorkflowRunOptions };
+//# sourceMappingURL=workflow.contract.d.mts.map

package/esm/contracts/workflow/workflow.contract.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/workflow/workflow.contract.ts"],"mappings":";;;;;;;;;;;;KAWY,oBAAA,iBAAqC,gBAAA,KAC/C,OAAA,EAAS,gBAAA,CAAiB,CAAA;AAAA,KAGhB,qBAAA,GAAwB,OAAA,eACtB,gBAAA,GAAmB,oBAAA,CAAqB,CAAA;;;;;KAO1C,kBAAA;EAXiB,sEAa3B,KAAA,WAd+C;EAgB/C,MAAA,GAAS,WAAA,EAfiB;EAiB1B,EAAA,GAAK,qBAAA;EAjBuB;AAAA;AAG9B;;;;;EAsBE,OAAA,GAAU,QAAA;EAtBwB;;;;;;;EA8BlC,SAAA;AAAA;AA7BqD;AAOvD;;;;AAPuD,KAqC3C,sBAAA,yCAGR,kBAAA,CAAmB,QAAA;EACrB,KAAA,EAAO,MAAA;AAAA;AAAA,KAGG,qBAAA,uBACV,kBAAkB,CAAC,QAAA;EAtCU;;EAyC3B,KAAA;AAAA;AAAA,KAGQ,kBAAA,+CAGD,MAAA;EAGT,IAAA;EApCA;;;;AAQS;EAkCT,WAAA;EACA,OAAA;EACA,KAAA,EAAO,cAAA,CAAe,MAAA,EAAQ,MAAA,EAAQ,QAAA;EAzBjB;;;;;;;;;EAmCrB,aAAA,GAAgB,WAAA;EAlCT;;AAAM;AAGf;;;;;;EAyCE,YAAA,GAAe,WAAA;EACf,QAAA;EACA,aAAA;EACA,QAAA,IACE,QAAA,UACA,GAAA,EAAK,eAAA,CAAgB,MAAA,EAAQ,MAAA,EAAQ,QAAA,MAClC,cAAA,GAAiB,OAAA,CAAQ,cAAA;EAC9B,MAAA,GAAS,cAAA,CAAe,OAAA,EAAS,MAAA,EAAQ,MAAA,EAAQ,QAAA;EACjD,EAAA,GAAK,qBAAA;AAAA;;;;;;;UASU,gBAAA,+CAGN,MAAA,+CAED,kBAAA,CACR,MAAA,EACA,kBAAA,CAAmB,QAAA,GACnB,cAAA,CAAe,OAAA;EAAA,SAEN,IAAA;EAAA,SACA,WAAA;EAAA,SACA,SAAA;EAAA,SACA,OAAA;EAxBJ;;;;;;;;;;;;;;EAwCL,OAAA,CACE,KAAA,EAAO,MAAA,EACP,OAAA,GAAU,kBAAA,CAAmB,QAAA,IAC5B,OAAA,CAAQ,cAAA,CAAe,OAAA;EAC1B,OAAA,CACE,OAAA,EAAS,sBAAA,CAAuB,MAAA,EAAQ,QAAA,IACvC,OAAA,CAAQ,cAAA,CAAe,OAAA;EAE1B,MAAA,CACE,KAAA,UACA,OAAA,GAAU,qBAAA,CAAsB,QAAA,IAC/B,OAAA,CAAQ,cAAA,CAAe,OAAA;EAE1B,EAAA,iBAAmB,gBAAA,EAAkB,KAAA,EAAO,CAAA,EAAG,OAAA,EAAS,oBAAA,CAAqB,CAAA;EAC7E,GAAA,iBAAoB,gBAAA,EAAkB,KAAA,EAAO,CAAA,EAAG,OAAA,EAAS,oBAAA,CAAqB,CAAA;EAhF9E;;;;;;;;;;;;;;;;EAkGA,MAAA,cAAoB,MAAA,EAAQ,OAAA;IAC1B,WAAA;IACA,WAAA,EAAa,gBAAA,CAAiB,UAAA;EAAA,IAC5B,YAAA,CAAa,UAAA,EAAY,OAAA;AAAA"}

package/esm/errors/agent-cancelled-error.d.mts

@@ -0,0 +1,49 @@
+import { ErrorCategory } from "./error-category.type.mjs";
+import { AIErrorOptions } from "./ai-error.mjs";
+import { AgentExecutionError } from "./agent-execution-error.mjs";
+
+//#region ../../@warlock.js/ai/src/errors/agent-cancelled-error.d.ts
+/**
+ * Payload for {@link AgentCancelledError}. `cancelledAt` is the
+ * ISO-8601 timestamp at which the abort was observed; `reason`
+ * carries the value the caller supplied to `controller.abort(reason)`
+ * when present.
+ */
+type AgentCancelledErrorOptions = AIErrorOptions & {
+  cancelledAt?: string;
+  reason?: string;
+};
+/**
+ * Agent run was cancelled via `AbortSignal` before it could finish.
+ * Between-trip cancellation is guaranteed; mid-trip cancellation is
+ * best-effort (the signal is threaded into the provider adapter's
+ * HTTP client when supported).
+ *
+ * Surfaced on `result.error` rather than thrown — `agent.execute()`
+ * still returns with `report.status = "cancelled"` and partial trip
+ * history intact. Consumers branch on the class (not the message) to
+ * distinguish caller-initiated stops from other failures.
+ *
+ * **Why split from `AgentExecutionError`.** Cancellation is a
+ * different operational signal from "the agent crashed" — retry
+ * policy and dashboards typically want different behavior for each.
+ * Keeping cancellation in its own class lets the category
+ * (`"cancelled"`) be set declaratively per type instead of inferred
+ * from a `context.cancelled === true` flag.
+ *
+ * @example
+ * const result = await agent.execute(input, { signal });
+ * if (result.error instanceof AgentCancelledError) {
+ *   // caller pulled the plug — don't retry, surface a "stopped" UI
+ *   return { status: "cancelled" };
+ * }
+ */
+declare class AgentCancelledError extends AgentExecutionError {
+  static readonly defaultCategory: ErrorCategory;
+  readonly cancelledAt?: string;
+  readonly reason?: string;
+  constructor(message: string, options?: AgentCancelledErrorOptions);
+}
+//#endregion
+export { AgentCancelledError, AgentCancelledErrorOptions };
+//# sourceMappingURL=agent-cancelled-error.d.mts.map

package/esm/errors/agent-cancelled-error.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-cancelled-error.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/errors/agent-cancelled-error.ts"],"mappings":";;;;;;;AAUA;;;;KAAY,0BAAA,GAA6B,cAAc;EACrD,WAAA;EACA,MAAA;AAAA;AAAM;AA4BR;;;;;;;;;;;;;;;;;;AAM0E;;;;;;AAlClE,cA4BK,mBAAA,SAA4B,mBAAA;EAAA,gBAChB,eAAA,EAAiB,aAAA;EAAA,SAExB,WAAA;EAAA,SACA,MAAA;cAEG,OAAA,UAAiB,OAAA,GAAU,0BAAA;AAAA"}

package/esm/errors/agent-cancelled-error.mjs

@@ -0,0 +1,43 @@
+import { AgentExecutionError } from "./agent-execution-error.mjs";
+
+//#region ../../@warlock.js/ai/src/errors/agent-cancelled-error.ts
+/**
+* Agent run was cancelled via `AbortSignal` before it could finish.
+* Between-trip cancellation is guaranteed; mid-trip cancellation is
+* best-effort (the signal is threaded into the provider adapter's
+* HTTP client when supported).
+*
+* Surfaced on `result.error` rather than thrown — `agent.execute()`
+* still returns with `report.status = "cancelled"` and partial trip
+* history intact. Consumers branch on the class (not the message) to
+* distinguish caller-initiated stops from other failures.
+*
+* **Why split from `AgentExecutionError`.** Cancellation is a
+* different operational signal from "the agent crashed" — retry
+* policy and dashboards typically want different behavior for each.
+* Keeping cancellation in its own class lets the category
+* (`"cancelled"`) be set declaratively per type instead of inferred
+* from a `context.cancelled === true` flag.
+*
+* @example
+* const result = await agent.execute(input, { signal });
+* if (result.error instanceof AgentCancelledError) {
+*   // caller pulled the plug — don't retry, surface a "stopped" UI
+*   return { status: "cancelled" };
+* }
+*/
+var AgentCancelledError = class extends AgentExecutionError {
+	static {
+		this.defaultCategory = "cancelled";
+	}
+	constructor(message, options) {
+		super(message, options, "AGENT_CANCELLED");
+		this.name = "AgentCancelledError";
+		this.cancelledAt = options?.cancelledAt;
+		this.reason = options?.reason;
+	}
+};
+
+//#endregion
+export { AgentCancelledError };
+//# sourceMappingURL=agent-cancelled-error.mjs.map

package/esm/errors/agent-cancelled-error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-cancelled-error.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/errors/agent-cancelled-error.ts"],"sourcesContent":["import { AgentExecutionError } from \"./agent-execution-error\";\nimport type { AIErrorOptions } from \"./ai-error\";\nimport type { ErrorCategory } from \"./error-category.type\";\n\n/**\n * Payload for {@link AgentCancelledError}. `cancelledAt` is the\n * ISO-8601 timestamp at which the abort was observed; `reason`\n * carries the value the caller supplied to `controller.abort(reason)`\n * when present.\n */\nexport type AgentCancelledErrorOptions = AIErrorOptions & {\n  cancelledAt?: string;\n  reason?: string;\n};\n\n/**\n * Agent run was cancelled via `AbortSignal` before it could finish.\n * Between-trip cancellation is guaranteed; mid-trip cancellation is\n * best-effort (the signal is threaded into the provider adapter's\n * HTTP client when supported).\n *\n * Surfaced on `result.error` rather than thrown — `agent.execute()`\n * still returns with `report.status = \"cancelled\"` and partial trip\n * history intact. Consumers branch on the class (not the message) to\n * distinguish caller-initiated stops from other failures.\n *\n * **Why split from `AgentExecutionError`.** Cancellation is a\n * different operational signal from \"the agent crashed\" — retry\n * policy and dashboards typically want different behavior for each.\n * Keeping cancellation in its own class lets the category\n * (`\"cancelled\"`) be set declaratively per type instead of inferred\n * from a `context.cancelled === true` flag.\n *\n * @example\n * const result = await agent.execute(input, { signal });\n * if (result.error instanceof AgentCancelledError) {\n *   // caller pulled the plug — don't retry, surface a \"stopped\" UI\n *   return { status: \"cancelled\" };\n * }\n */\nexport class AgentCancelledError extends AgentExecutionError {\n  public static readonly defaultCategory: ErrorCategory = \"cancelled\";\n\n  public readonly cancelledAt?: string;\n  public readonly reason?: string;\n\n  public constructor(message: string, options?: AgentCancelledErrorOptions) {\n    super(message, options, \"AGENT_CANCELLED\");\n    this.name = \"AgentCancelledError\";\n    this.cancelledAt = options?.cancelledAt;\n    this.reason = options?.reason;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,IAAa,sBAAb,cAAyC,oBAAoB;;yBACH;;CAKxD,AAAO,YAAY,SAAiB,SAAsC;EACxE,MAAM,SAAS,SAAS,iBAAiB;EACzC,KAAK,OAAO;EACZ,KAAK,cAAc,SAAS;EAC5B,KAAK,SAAS,SAAS;CACzB;AACF"}

package/esm/errors/agent-execution-error.d.mts

@@ -0,0 +1,32 @@
+import { AIErrorCode } from "./error-code.type.mjs";
+import { AIError, AIErrorOptions } from "./ai-error.mjs";
+
+//#region ../../@warlock.js/ai/src/errors/agent-execution-error.d.ts
+/**
+ * Base for agent runtime failures that aren't schema / tool / provider
+ * problems — runtime-structural issues inside the trip loop or
+ * authoring-time middleware misconfiguration. Two specialized
+ * subclasses cover the two non-generic cases:
+ *
+ * - {@link AgentCancelledError} (`AGENT_CANCELLED`) — caller-driven
+ *   abort via `AbortSignal`.
+ * - {@link AgentMaxTripsError} (`AGENT_MAX_TRIPS`) — trip loop hit
+ *   the `maxTrips` cap without a natural stop.
+ *
+ * Use the base class directly for anything else (unregistered tool
+ * dispatch, authoring-time middleware validation, surprise
+ * exceptions). The subclasses exist so consumers can branch on a
+ * dedicated `instanceof` / category without inferring from `context`
+ * flags or parsing the message.
+ *
+ * @example
+ * if (result.error?.code === "AGENT_EXEC_FAILED") {
+ *   logger.warn("unexpected agent failure", result.error.context);
+ * }
+ */
+declare class AgentExecutionError extends AIError {
+  constructor(message: string, options?: AIErrorOptions, code?: AIErrorCode);
+}
+//#endregion
+export { AgentExecutionError };
+//# sourceMappingURL=agent-execution-error.d.mts.map

package/esm/errors/agent-execution-error.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-execution-error.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/errors/agent-execution-error.ts"],"mappings":";;;;;;AAyBA;;;;;;;;;;;;;;;;AAI2C;;;;cAJ9B,mBAAA,SAA4B,OAAA;cAErC,OAAA,UACA,OAAA,GAAU,cAAA,EACV,IAAA,GAAM,WAAA;AAAA"}

package/esm/errors/agent-execution-error.mjs

@@ -0,0 +1,35 @@
+import { AIError } from "./ai-error.mjs";
+
+//#region ../../@warlock.js/ai/src/errors/agent-execution-error.ts
+/**
+* Base for agent runtime failures that aren't schema / tool / provider
+* problems — runtime-structural issues inside the trip loop or
+* authoring-time middleware misconfiguration. Two specialized
+* subclasses cover the two non-generic cases:
+*
+* - {@link AgentCancelledError} (`AGENT_CANCELLED`) — caller-driven
+*   abort via `AbortSignal`.
+* - {@link AgentMaxTripsError} (`AGENT_MAX_TRIPS`) — trip loop hit
+*   the `maxTrips` cap without a natural stop.
+*
+* Use the base class directly for anything else (unregistered tool
+* dispatch, authoring-time middleware validation, surprise
+* exceptions). The subclasses exist so consumers can branch on a
+* dedicated `instanceof` / category without inferring from `context`
+* flags or parsing the message.
+*
+* @example
+* if (result.error?.code === "AGENT_EXEC_FAILED") {
+*   logger.warn("unexpected agent failure", result.error.context);
+* }
+*/
+var AgentExecutionError = class extends AIError {
+	constructor(message, options, code = "AGENT_EXEC_FAILED") {
+		super(code, message, options);
+		this.name = "AgentExecutionError";
+	}
+};
+
+//#endregion
+export { AgentExecutionError };
+//# sourceMappingURL=agent-execution-error.mjs.map

package/esm/errors/agent-execution-error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-execution-error.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/errors/agent-execution-error.ts"],"sourcesContent":["import { AIError, type AIErrorOptions } from \"./ai-error\";\nimport type { AIErrorCode } from \"./error-code.type\";\n\n/**\n * Base for agent runtime failures that aren't schema / tool / provider\n * problems — runtime-structural issues inside the trip loop or\n * authoring-time middleware misconfiguration. Two specialized\n * subclasses cover the two non-generic cases:\n *\n * - {@link AgentCancelledError} (`AGENT_CANCELLED`) — caller-driven\n *   abort via `AbortSignal`.\n * - {@link AgentMaxTripsError} (`AGENT_MAX_TRIPS`) — trip loop hit\n *   the `maxTrips` cap without a natural stop.\n *\n * Use the base class directly for anything else (unregistered tool\n * dispatch, authoring-time middleware validation, surprise\n * exceptions). The subclasses exist so consumers can branch on a\n * dedicated `instanceof` / category without inferring from `context`\n * flags or parsing the message.\n *\n * @example\n * if (result.error?.code === \"AGENT_EXEC_FAILED\") {\n *   logger.warn(\"unexpected agent failure\", result.error.context);\n * }\n */\nexport class AgentExecutionError extends AIError {\n  public constructor(\n    message: string,\n    options?: AIErrorOptions,\n    code: AIErrorCode = \"AGENT_EXEC_FAILED\",\n  ) {\n    super(code, message, options);\n    this.name = \"AgentExecutionError\";\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,IAAa,sBAAb,cAAyC,QAAQ;CAC/C,AAAO,YACL,SACA,SACA,OAAoB,qBACpB;EACA,MAAM,MAAM,SAAS,OAAO;EAC5B,KAAK,OAAO;CACd;AACF"}