@warlock.js/ai 4.2.11 → 4.4.0

package/esm/contracts/orchestrator/orchestrator-execute-options.type.d.mts

@@ -0,0 +1,44 @@
+import { Message } from "../conversation-message.type.mjs";
+import { OrchestratorEventHandlers } from "./orchestrator-event.type.mjs";
+
+//#region ../@warlock.js/ai/src/contracts/orchestrator/orchestrator-execute-options.type.d.ts
+/**
+ * Per-call options for `orchestrator.execute(input, options)` (design
+ * §15.4).
+ *
+ * `sessionId` names the session this turn acts on (no implicit "current
+ * session" — §18.1). `history` is required in v1: the framework never
+ * persists messages itself (Path 2 only, §7), so the dev passes the
+ * prior turns each call. `state` is a partial seed/patch shallow-merged
+ * into the loaded session state. `context` is the request-scoped bag,
+ * frozen at intake.
+ *
+ * `TState` defaults to `Record<string, unknown>` so callers that don't
+ * parameterize still get a usable `Partial<TState>` patch type.
+ */
+type OrchestratorExecuteOptions<TState = Record<string, unknown>> = {
+  /** Required — names the session this turn acts on. */sessionId: string; /** Required — prior conversation turns (Path 2; framework never persists). */
+  history: Message[]; /** Partial seed/patch shallow-merged into the loaded session state. */
+  state?: Partial<TState>; /** Request-scoped bag — frozen + shallow-copied at intake. */
+  context?: Record<string, unknown>;
+  signal?: AbortSignal; /** Per-call event handlers — tier 3 of the 3-tier model. */
+  on?: OrchestratorEventHandlers; /** Bypass the drift check for this call. */
+  force?: boolean;
+};
+/**
+ * Options for `orchestrator.resume(sessionId, options)` (design §15.4).
+ *
+ * Resume re-supplies request-scoped `context` (NOT persisted — §9.1)
+ * and rehydrates state from the checkpoint. No `history` field: a
+ * resume continues an interrupted turn from its persisted snapshot
+ * rather than opening a fresh turn.
+ */
+type OrchestratorResumeOptions = {
+  /** Request-scoped bag re-supplied for the resumed turn. */context?: Record<string, unknown>;
+  signal?: AbortSignal;
+  on?: OrchestratorEventHandlers; /** Bypass the drift check on resume. */
+  force?: boolean;
+};
+//#endregion
+export { OrchestratorExecuteOptions, OrchestratorResumeOptions };
+//# sourceMappingURL=orchestrator-execute-options.type.d.mts.map

package/esm/contracts/orchestrator/orchestrator-execute-options.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator-execute-options.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/orchestrator/orchestrator-execute-options.type.ts"],"mappings":";;;;;;AAiBA;;;;;;;;;;;;KAAY,0BAAA,UAAoC,MAAA;EAAA,sDAE9C,SAAA,UAEA;EAAA,OAAA,EAAS,OAAA,IAET;EAAA,KAAA,GAAQ,OAAA,CAAQ,MAAA,GAAA;EAEhB,OAAA,GAAU,MAAA;EACV,MAAA,GAAS,WAAA,EAAT;EAEA,EAAA,GAAK,yBAAA,EAAL;EAEA,KAAA;AAAA;;AAAK;AAWP;;;;;;KAAY,yBAAA;EAIoB,2DAF9B,OAAA,GAAU,MAAA;EACV,MAAA,GAAS,WAAA;EACT,EAAA,GAAK,yBAAA,EADI;EAGT,KAAA;AAAA"}

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

@@ -0,0 +1,129 @@
+import { StreamContract } from "../stream/stream.contract.mjs";
+import { ToolContract } from "../../tool/tool.mjs";
+import { SupervisorInput } from "../supervisor/supervisor-input.type.mjs";
+import { OrchestratorResult } from "../result/orchestrator-result.type.mjs";
+import { OrchestratorCommands } from "./orchestrator-commands.type.mjs";
+import { OrchestratorEvent, OrchestratorEventHandler, OrchestratorEventName } from "./orchestrator-event.type.mjs";
+import { OrchestratorExecuteOptions, OrchestratorResumeOptions } from "./orchestrator-execute-options.type.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region ../@warlock.js/ai/src/contracts/orchestrator/orchestrator.contract.d.ts
+/**
+ * How a wrapped orchestrator scopes its session when invoked as a tool
+ * (design §13.1).
+ *
+ * - `"fresh"` (default) — every tool invocation gets a brand-new
+ *   `sessionId`; no continuity across calls. Safe default.
+ * - `"shared"` — the wrapped orchestrator participates in the parent's
+ *   session; the `sessionId` is supplied via the tool's `inputSchema`
+ *   payload. Expert escape hatch for nested-conversation use cases.
+ */
+type OrchestratorSessionScope = "fresh" | "shared";
+/**
+ * Context overrides for a specific session.
+ *
+ * @deprecated Obsolete v2 forward-declaration. The locked v1
+ * orchestrator has no stateful session object and no `session()`
+ * method — sessions are owned via a `sessionId` string passed per call
+ * (`OrchestratorExecuteOptions.sessionId`, §18.1). Request-scoped
+ * overrides are now `OrchestratorExecuteOptions.context`. Retained
+ * unchanged for one minor for non-breaking compatibility; do not use in
+ * new code.
+ */
+type SessionContextOverrides = {
+  [key: string]: unknown;
+};
+/**
+ * Options accepted by `orchestrator.asTool()` (design §13). Mirrors
+ * `SupervisorAsToolOptions` and adds `sessionScope` so the parent can
+ * choose whether each tool call opens a fresh session or shares one.
+ *
+ * `inputSchema` types the tool's `input` payload — the orchestrator
+ * receives the coerced payload as its `execute(input)` argument.
+ */
+type OrchestratorAsToolOptions<TToolInput = string> = {
+  name?: string;
+  description?: string;
+  inputSchema: StandardSchemaV1<TToolInput>; /** Session continuity for tool calls. Default `"fresh"`. */
+  sessionScope?: OrchestratorSessionScope;
+};
+/**
+ * Runtime handle returned by `ai.orchestrator(config)` (design §15.3) —
+ * a session-state manager wrapped around a supervisor. The v1 capstone
+ * of the 4-primitive ladder (agent → workflow → supervisor →
+ * orchestrator).
+ *
+ * The session is owned via `sessionId` passed per call (§18.1) — there
+ * is no stateful session object and no implicit "current session".
+ * Every method names the session it acts on. `execute` and `stream`
+ * run one turn; `resume` continues an interrupted turn from its
+ * persisted checkpoint; `command` invokes a typed built-in (e.g.
+ * `compact`); `asTool` exposes the orchestrator to an outer agent.
+ *
+ * Implements the 3-tier event subscription model (definition →
+ * instance → per-call). Child `supervisor.*` / `agent.*` events bubble
+ * up unmodified under their own identity (§14.2).
+ *
+ * @example
+ * const supportBot = ai.orchestrator<SessionState>({
+ *   name: "refund-support",
+ *   intents: { classify, lookup, process, compose },
+ *   route: (ctx) => (ctx.iteration === 0 ? "classify" : END),
+ * });
+ *
+ * const result = await supportBot.execute(message, { sessionId, history });
+ * if (result.report.status === "awaiting-input") {
+ *   // session continues — wait for the next user turn
+ * }
+ */
+interface OrchestratorContract<TOutput = unknown, TState = TOutput> {
+  /** Stable identifier — mirrors the config's `name`. */
+  readonly name: string;
+  /** Structural fingerprint of the orchestrator definition (§10.1). */
+  readonly signature: string;
+  /** Dev-curated version string, or `undefined` when none was declared. */
+  readonly version: string | undefined;
+  /**
+   * Run one turn end-to-end against the named session. Returns the
+   * per-turn `OrchestratorResult`. Never throws on runtime failure —
+   * errors surface via `result.error`; drift / config misuse throw.
+   */
+  execute(input: SupervisorInput, options: OrchestratorExecuteOptions<TState>): Promise<OrchestratorResult<TOutput>>;
+  /**
+   * Stream the turn's lifecycle events in real time. `result` resolves
+   * to the same value `execute()` would produce; child agent/supervisor
+   * streaming bubbles up under its own namespace.
+   */
+  stream(input: SupervisorInput, options: OrchestratorExecuteOptions<TState>): StreamContract<OrchestratorResult<TOutput>, OrchestratorEvent>;
+  /**
+   * Resume an interrupted turn from its persisted checkpoint. Returns
+   * `null` when there is nothing to resume for the session. Throws
+   * `OrchestratorDriftError` on signature drift unless `{ force: true }`.
+   */
+  resume(sessionId: string, options?: OrchestratorResumeOptions): Promise<OrchestratorResult<TOutput> | null>;
+  /**
+   * Invoke a typed built-in command (design §11). v1 ships `compact`;
+   * user commands attach via module augmentation of
+   * `OrchestratorCommands`.
+   */
+  command<K extends keyof OrchestratorCommands>(name: K, args: OrchestratorCommands[K]["args"]): Promise<OrchestratorCommands[K]["result"]>;
+  /**
+   * Wrap this orchestrator as a `ToolContract` so an outer agent can
+   * invoke it inside its tool-call loop. `sessionScope` controls
+   * session continuity across calls (§13.1).
+   */
+  asTool<TToolInput = string>(options: OrchestratorAsToolOptions<TToolInput>): ToolContract<TToolInput, TOutput>;
+  /**
+   * Subscribe an instance-level handler — tier 2 of the 3-tier model.
+   * Returns an unsubscribe function equivalent to `off(event, handler)`.
+   */
+  on<K extends OrchestratorEventName>(event: K, handler: OrchestratorEventHandler<K>): () => void;
+  /**
+   * Remove a previously-subscribed instance-level handler. No-op when
+   * the handler was never registered or already removed.
+   */
+  off<K extends OrchestratorEventName>(event: K, handler: OrchestratorEventHandler<K>): void;
+}
+//#endregion
+export { OrchestratorAsToolOptions, OrchestratorContract, OrchestratorSessionScope, SessionContextOverrides };
+//# sourceMappingURL=orchestrator.contract.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/orchestrator/orchestrator.contract.ts"],"mappings":";;;;;;;;;;;;AA0BA;;;;AAAoC;AAapC;;;KAbY,wBAAA;AAcE;AAWd;;;;;;;;;;AAXc,KADF,uBAAA;EAAA,CACT,GAAW;AAAA;;;;;AAgB2B;AAgCzC;;;KArCY,yBAAA;EACV,IAAA;EACA,WAAA;EACA,WAAA,EAAa,gBAAA,CAAiB,UAAA,GAkDA;EAhD9B,YAAA,GAAe,wBAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAgCA,oBAAA,6BAAiD,OAAA;EAwErD;EAAA,SAtEF,IAAA;EAsE0B;EAAA,SApE1B,SAAA;EAJ8C;EAAA,SAM9C,OAAA;EAJA;;;;;EAWT,OAAA,CACE,KAAA,EAAO,eAAA,EACP,OAAA,EAAS,0BAAA,CAA2B,MAAA,IACnC,OAAA,CAAQ,kBAAA,CAAmB,OAAA;EADnB;;;;;EAQX,MAAA,CACE,KAAA,EAAO,eAAA,EACP,OAAA,EAAS,0BAAA,CAA2B,MAAA,IACnC,cAAA,CAAe,kBAAA,CAAmB,OAAA,GAAU,iBAAA;EAH/C;;;;;EAUA,MAAA,CACE,SAAA,UACA,OAAA,GAAU,yBAAA,GACT,OAAA,CAAQ,kBAAA,CAAmB,OAAA;EAV3B;;;;;EAiBH,OAAA,iBAAwB,oBAAA,EACtB,IAAA,EAAM,CAAA,EACN,IAAA,EAAM,oBAAA,CAAqB,CAAA,YAC1B,OAAA,CAAQ,oBAAA,CAAqB,CAAA;EAXpB;;;;;EAkBZ,MAAA,sBACE,OAAA,EAAS,yBAAA,CAA0B,UAAA,IAClC,YAAA,CAAa,UAAA,EAAY,OAAA;EAZpB;;;;EAkBR,EAAA,WAAa,qBAAA,EACX,KAAA,EAAO,CAAA,EACP,OAAA,EAAS,wBAAA,CAAyB,CAAA;EAlBP;;;;EAyB7B,GAAA,WAAc,qBAAA,EACZ,KAAA,EAAO,CAAA,EACP,OAAA,EAAS,wBAAA,CAAyB,CAAA;AAAA"}

package/esm/contracts/orchestrator/session.contract.d.mts

@@ -0,0 +1,26 @@
+import { SessionSendResult } from "../result/session-send-result.type.mjs";
+
+//#region ../@warlock.js/ai/src/contracts/orchestrator/session.contract.d.ts
+/**
+ * A stateful session that routes messages through agents, workflows, or
+ * supervisors.
+ *
+ * @deprecated Obsolete v2 forward-declaration. The locked v1
+ * orchestrator (design §15) has NO stateful session object and no
+ * `send()` method. A turn is run via
+ * `orchestrator.execute(input, { sessionId, history })`, which returns
+ * an {@link OrchestratorResult} — see
+ * `../result/orchestrator-result.type`. Retained unchanged for one
+ * minor for non-breaking compatibility; do not use in new code.
+ */
+interface SessionContract {
+  /**
+   * Send a message to the session and receive a result.
+   *
+   * @deprecated Use `orchestrator.execute(input, options)` instead.
+   */
+  send(message: string): Promise<SessionSendResult>;
+}
+//#endregion
+export { SessionContract };
+//# sourceMappingURL=session.contract.d.mts.map

package/esm/contracts/orchestrator/session.contract.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/orchestrator/session.contract.ts"],"mappings":";;;;;AAcA;;;;;;;;;AAMkD;UANjC,eAAA;;;;;;EAMf,IAAA,CAAK,OAAA,WAAkB,OAAO,CAAC,iBAAA;AAAA"}

package/esm/contracts/orchestrator/snapshot-store.contract.d.mts

@@ -0,0 +1,89 @@
+import { SupervisorSnapshot } from "../supervisor/supervisor-snapshot.type.mjs";
+
+//#region ../@warlock.js/ai/src/contracts/orchestrator/snapshot-store.contract.d.ts
+/**
+ * Minimal `pg`-compatible client surface the pg snapshot/checkpoint
+ * stores depend on (orchestrator.md §8.4). Both `pg.Pool` and
+ * `pg.Client` satisfy it — the stores only ever call `query`.
+ *
+ * `@warlock.js/ai` takes NO peer dep on `pg`; the dev installs it and
+ * passes the client in. Mirrors `@warlock.js/cache`'s `PgClientLike`
+ * so a single pool can back both the cache and the orchestrator
+ * stores. Declared here for the deferred Phase-2 pg drivers.
+ */
+type PgClientLike = {
+  query(text: string, params?: unknown[]): Promise<{
+    rows: unknown[];
+  }>;
+};
+/**
+ * Minimal `redis`-compatible client surface the redis snapshot/
+ * checkpoint stores depend on (orchestrator.md §8.4).
+ *
+ * `@warlock.js/ai` takes NO peer dep on `redis`; the dev installs it
+ * and passes the client in. Declared here for the deferred Phase-2
+ * redis drivers.
+ */
+type RedisClientLike = {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
+  del(key: string): Promise<number>;
+};
+/**
+ * Durable store for the internal supervisor run state of an
+ * `iterate: true` orchestrator turn (orchestrator.md §8.2).
+ *
+ * Its payload is the existing {@link SupervisorSnapshot} envelope
+ * (§8.1 — "same shape as supervisor's existing snapshot envelope"):
+ * the store is keyed by the supervisor `runId` and round-trips the
+ * whole snapshot, so a crashed mid-turn iteration can resume.
+ * **Promoted** from the historical `CacheDriver` path for naming
+ * consistency — the `CacheDriver` overload stays for one deprecated
+ * minor (§8.1).
+ *
+ * Distinct from
+ * {@link import("./checkpoint-store.contract").CheckpointStore}, which
+ * persists cross-turn session state. Implementations:
+ * `ai.snapshot.{memory,pg,redis}()`. The memory impl ships in v1;
+ * pg/redis follow. Schema is never auto-migrated — {@link
+ * SnapshotStore.schema} returns a DDL string the dev runs themselves
+ * (§8.5).
+ *
+ * Generic over the persisted snapshot shape. Defaults to
+ * {@link SupervisorSnapshot} so every existing reference resolves
+ * exactly as before; the workflow engine parameterizes it with
+ * `WorkflowSnapshot`. The only structural requirement is a `runId`
+ * string — the store derives its key from it.
+ */
+interface SnapshotStore<TSnapshot extends {
+  runId: string;
+} = SupervisorSnapshot> {
+  /**
+   * Load the snapshot for a `runId`, or `undefined` when no in-flight
+   * run is recorded.
+   */
+  load(runId: string): Promise<TSnapshot | undefined>;
+  /**
+   * Persist a snapshot. The key is derived from `snapshot.runId` — the
+   * store owns its own keying/prefix.
+   */
+  save(snapshot: TSnapshot): Promise<void>;
+  /**
+   * Delete the snapshot for a `runId`.
+   */
+  delete(runId: string): Promise<void>;
+  /**
+   * List the run ids the store knows, optionally filtered by a prefix.
+   * Optional — stores that can't enumerate omit it.
+   */
+  list?(prefix?: string): Promise<string[]>;
+  /**
+   * Return the DDL string for this store's backing table. The dev runs
+   * it through their migration tool; the framework never auto-migrates
+   * (§8.5).
+   */
+  schema(): string;
+}
+//#endregion
+export { PgClientLike, RedisClientLike, SnapshotStore };
+//# sourceMappingURL=snapshot-store.contract.d.mts.map

package/esm/contracts/orchestrator/snapshot-store.contract.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-store.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/orchestrator/snapshot-store.contract.ts"],"mappings":";;;;;AAYA;;;;;;;;KAAY,YAAA;EACV,KAAA,CAAM,IAAA,UAAc,MAAA,eAAqB,OAAO;IAAG,IAAA;EAAA;AAAA;;;;;;;;;KAWzC,eAAA;EACV,GAAA,CAAI,GAAA,WAAc,OAAA;EAClB,GAAA,CAAI,GAAA,UAAa,KAAA,aAAkB,IAAA,cAAkB,OAAA;EACrD,GAAA,CAAI,GAAA,WAAc,OAAA;AAAA;;;;;;AAAO;AA6B3B;;;;;;;;;;;;;;;;;;;;UAAiB,aAAA;EAAkC,KAAA;AAAA,IAAkB,kBAAA;EAgBnE;;;;EAXA,IAAA,CAAK,KAAA,WAAgB,OAAA,CAAQ,SAAA;EAiBL;;;AAOlB;EAlBN,IAAA,CAAK,QAAA,EAAU,SAAA,GAAY,OAAA;;;;EAK3B,MAAA,CAAO,KAAA,WAAgB,OAAA;;;;;EAMvB,IAAA,EAAM,MAAA,YAAkB,OAAA;;;;;;EAOxB,MAAA;AAAA"}

package/esm/contracts/planner/index.d.mts

@@ -0,0 +1,6 @@
+import { PlannerCapability } from "./planner-capability.type.mjs";
+import { PlannerConfig } from "./planner-config.type.mjs";
+import { PlannerExecuteOptions } from "./planner-execute-options.type.mjs";
+import { PlannerPlan, PlannerStep } from "./planner-plan.type.mjs";
+import { PlannerReport, PlannerReportType, PlannerResult, PlannerStepSnapshot } from "./planner-result.type.mjs";
+import { PlannerContract } from "./planner.contract.mjs";

package/esm/contracts/planner/planner-capability.type.d.mts

@@ -0,0 +1,39 @@
+import { BaseResult } from "../result/base-result.type.mjs";
+import { ExecutableContract } from "../executable.contract.mjs";
+
+//#region ../@warlock.js/ai/src/contracts/planner/planner-capability.type.d.ts
+/**
+ * A single capability the planner may reference in a generated plan.
+ *
+ * **Role.** Adapts an arbitrary executable primitive (an
+ * `AgentContract`, `WorkflowInstance`, `SupervisorContract`,
+ * `ToolContract`, or anything satisfying {@link ExecutableContract})
+ * into a uniform unit the planner can describe to the LLM and dispatch
+ * during plan execution. The `name` is the stable handle the LLM
+ * references in each plan step; the `description` is what the LLM reads
+ * to decide WHEN to use it.
+ *
+ * **Why a wrapper and not the bare executable?** Two reasons. The LLM
+ * needs a `name` + `description` pair regardless of whether the
+ * underlying primitive carries one, and the planner needs a single
+ * `execute(input)` entry point with a `string` input contract so plan
+ * steps stay uniform across heterogeneous capabilities.
+ */
+type PlannerCapability = {
+  /** Stable handle the LLM references in each plan step. Unique per planner. */name: string;
+  /**
+   * What this capability does — the "when would the planner pick this?"
+   * line. Injected verbatim into the plan-generation prompt so the LLM
+   * can select capabilities sensibly.
+   */
+  description: string;
+  /**
+   * The underlying executable. Dispatched with the step's resolved
+   * `string` input during plan execution; its `usage` and `report`
+   * roll up into the planner's unified result.
+   */
+  executable: ExecutableContract<string, unknown, BaseResult>;
+};
+//#endregion
+export { PlannerCapability };
+//# sourceMappingURL=planner-capability.type.d.mts.map

package/esm/contracts/planner/planner-capability.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-capability.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/planner/planner-capability.type.ts"],"mappings":";;;;;;AAoBA;;;;;;;;;;AAc4D;;;;;KAdhD,iBAAA;gFAEV,IAAA;;;;;;EAMA,WAAA;;;;;;EAMA,UAAA,EAAY,kBAAkB,kBAAkB,UAAA;AAAA"}

package/esm/contracts/planner/planner-config.type.d.mts

@@ -0,0 +1,78 @@
+import { AgentContract } from "../agent/agent.contract.mjs";
+import { ModelContract } from "../model.contract.mjs";
+import { SystemPromptContract } from "../system-prompt.contract.mjs";
+import { PlannerCapability } from "./planner-capability.type.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region ../@warlock.js/ai/src/contracts/planner/planner-config.type.d.ts
+/**
+ * Factory config for `ai.planner(config)`.
+ *
+ * The planner asks an LLM to GENERATE an ordered plan over the
+ * registered `capabilities`, then executes that plan step-by-step
+ * through each capability's own `execute()`. It is itself an
+ * executable — composes into agents, supervisors, and orchestrators
+ * through the same `ExecutableContract` surface.
+ *
+ * Exactly one of `model` or `planner` must be supplied as the
+ * plan-generation brain: `model` builds an internal planning agent
+ * automatically; `planner` lets the dev bring a fully-configured agent
+ * (custom system prompt, middleware, output guard) to do the planning.
+ *
+ * @example
+ * const research = ai.planner({
+ *   name: "research-assistant",
+ *   model: ai.openai.model({ name: "gpt-4o" }),
+ *   capabilities: [
+ *     { name: "search", description: "Search the web", executable: searchAgent },
+ *     { name: "summarize", description: "Summarize text", executable: summarizer },
+ *   ],
+ *   maxSteps: 6,
+ * });
+ *
+ * const { data, report } = await research.execute("Compare React vs Vue in 2026");
+ */
+type PlannerConfig<TOutput = unknown> = {
+  /** Stable identifier — used in logs, events, signature, report `name`. */name: string; /** Dev-curated version string. Metadata only — never parsed. */
+  version?: string;
+  /**
+   * Model used to build the internal planning agent that GENERATES the
+   * plan. Mutually exclusive with `planner`.
+   */
+  model?: ModelContract;
+  /**
+   * Bring-your-own planning agent. Its `execute()` is asked for the
+   * structured plan (the planner supplies the plan schema as the
+   * agent's `output`). Mutually exclusive with `model`.
+   */
+  planner?: AgentContract<unknown>;
+  /**
+   * Extra instruction prepended to the plan-generation prompt
+   * (`model` mode only — ignored when `planner` is supplied, since the
+   * dev's agent owns its own prompt).
+   */
+  systemPrompt?: SystemPromptContract | string;
+  /**
+   * The capabilities the plan may reference. The planner injects each
+   * one's `name` + `description` into the plan-generation prompt and
+   * dispatches the chosen capability per step.
+   */
+  capabilities: PlannerCapability[];
+  /**
+   * Hard cap on the number of plan steps the planner will execute. A
+   * generated plan longer than this is truncated to the cap (the
+   * dropped tail is recorded as `skipped` on the report). Defaults to
+   * 10. Must be >= 1.
+   */
+  maxSteps?: number;
+  /**
+   * Final-output schema. When set, the planner validates the last
+   * completed step's output against it before populating
+   * `result.data`. Omit to pass the final step's raw output through
+   * untyped.
+   */
+  output?: StandardSchemaV1<TOutput>;
+};
+//#endregion
+export { PlannerConfig };
+//# sourceMappingURL=planner-config.type.d.mts.map

package/esm/contracts/planner/planner-config.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-config.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/planner/planner-config.type.ts"],"mappings":";;;;;;;;;AAiCA;;;;;;;;;;;;;;;;;;;;;;;;;KAAY,aAAA;EAyCuB,0EAvCjC,IAAA;EAEA,OAAA;;;;;EAKA,KAAA,GAAQ,aAAA;;;;;;EAMR,OAAA,GAAU,aAAA;;;;;;EAMV,YAAA,GAAe,oBAAA;;;;;;EAMf,YAAA,EAAc,iBAAA;;;;;;;EAOd,QAAA;;;;;;;EAOA,MAAA,GAAS,gBAAA,CAAiB,OAAA;AAAA"}

package/esm/contracts/planner/planner-execute-options.type.d.mts

@@ -0,0 +1,43 @@
+import { Placeholders } from "../placeholders.type.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region ../@warlock.js/ai/src/contracts/planner/planner-execute-options.type.d.ts
+/**
+ * Options accepted by `planner.execute(goal, options?)`.
+ *
+ * Every field is optional — `planner.execute(goal)` runs end-to-end
+ * with the planner's configured defaults.
+ */
+type PlannerExecuteOptions<TOutput = unknown> = {
+  /** Stable run-id for this execution. Generated when absent. */runId?: string;
+  /**
+   * Placeholder values injected into the plan-generation prompt's
+   * `{{mustache}}` slots (`model` mode only).
+   */
+  placeholders?: Placeholders;
+  /**
+   * Per-call override of the configured `output` schema. When set, the
+   * planner validates the final step output against this instead of
+   * the factory-level `output`.
+   */
+  output?: StandardSchemaV1<TOutput>;
+  /**
+   * Cancellation handle. When `signal.aborted` becomes true the planner
+   * short-circuits at the next step boundary and returns with
+   * `report.status === "cancelled"` and `result.error` set to a
+   * `PlannerCancelledError`. The signal is also threaded into every
+   * in-flight capability dispatch — mid-step abort is best-effort and
+   * depends on the child primitive honoring it.
+   */
+  signal?: AbortSignal;
+  /**
+   * Caller-supplied identifier that groups multiple `execute()` calls
+   * into one conceptual session. Mirrored onto every report node this
+   * run produces (and every nested executable it dispatches) so flat
+   * trace queries don't need to walk the tree.
+   */
+  sessionId?: string;
+};
+//#endregion
+export { PlannerExecuteOptions };
+//# sourceMappingURL=planner-execute-options.type.d.mts.map

package/esm/contracts/planner/planner-execute-options.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-execute-options.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/planner/planner-execute-options.type.ts"],"mappings":";;;;;;AASA;;;;KAAY,qBAAA;EAaD,+DAXT,KAAA;EAoBoB;;;;EAfpB,YAAA,GAAe,YAAA;EAAA;;;;;EAMf,MAAA,GAAS,gBAAA,CAAiB,OAAA;EAgB1B;;AAAS;;;;;;EAPT,MAAA,GAAS,WAAA;;;;;;;EAOT,SAAA;AAAA"}

package/esm/contracts/planner/planner-plan.type.d.mts

@@ -0,0 +1,48 @@
+//#region ../@warlock.js/ai/src/contracts/planner/planner-plan.type.d.ts
+/**
+ * One step of an LLM-generated execution plan.
+ *
+ * **Role.** The unit the planner executes in order. Each step names a
+ * registered {@link PlannerCapability} (`capability`) and carries the
+ * concrete `input` the LLM resolved for that capability. The optional
+ * `id` / `dependsOn` fields let the LLM express a simple dependency
+ * note for human readability; the bounded-v1 planner executes steps
+ * strictly in array order and does NOT yet schedule on `dependsOn`
+ * (see {@link PlannerPlan} remarks).
+ */
+type PlannerStep = {
+  /**
+   * Stable id for this step within the plan — referenced by other
+   * steps' `dependsOn`. Optional; the planner falls back to the array
+   * index when absent.
+   */
+  id?: string; /** Name of the {@link PlannerCapability} this step dispatches. */
+  capability: string; /** Concrete input the LLM resolved for the capability's `execute()`. */
+  input: string; /** Free-form rationale the LLM produced for why this step exists. */
+  reason?: string;
+  /**
+   * Ids of steps this step conceptually depends on. Advisory only in
+   * bounded-v1 — recorded on the snapshot for forensics but not used
+   * to reorder or parallelize execution.
+   */
+  dependsOn?: string[];
+};
+/**
+ * The full ordered execution plan the planner's LLM produces before any
+ * capability runs.
+ *
+ * @remarks
+ * **Bounded v1.** Steps execute strictly in array order, one at a time.
+ * `dependsOn` is advisory metadata only — no DAG scheduling, no
+ * parallel fan-out, no mid-plan re-planning. Those are deferred (see
+ * the planner skill). The earlier steps' outputs are threaded into the
+ * later steps' prompt context so a downstream capability can build on
+ * what ran before it.
+ */
+type PlannerPlan = {
+  /** The ordered steps to execute. At least one. */steps: PlannerStep[]; /** Optional one-line LLM summary of the overall strategy. */
+  summary?: string;
+};
+//#endregion
+export { PlannerPlan, PlannerStep };
+//# sourceMappingURL=planner-plan.type.d.mts.map

package/esm/contracts/planner/planner-plan.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-plan.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/planner/planner-plan.type.ts"],"mappings":";;AAWA;;;;;;;;;;KAAY,WAAA;EAiCA;;;;;EA3BV,EAAA,WA+BA;EA7BA,UAAA,UA6BO;EA3BP,KAAA;EAEA,MAAA;;;;;;EAMA,SAAA;AAAA;;;;;;;;;;;;;KAeU,WAAA;oDAEV,KAAA,EAAO,WAAW;EAElB,OAAA;AAAA"}

package/esm/contracts/planner/planner-result.type.d.mts

@@ -0,0 +1,88 @@
+import { AIError } from "../../errors/ai-error.mjs";
+import { Usage } from "../result/usage.type.mjs";
+import { BaseReport } from "../result/base-report.type.mjs";
+import { ExecuteResult } from "../result/execute-result.type.mjs";
+import { PlannerPlan, PlannerStep } from "./planner-plan.type.mjs";
+
+//#region ../@warlock.js/ai/src/contracts/planner/planner-result.type.d.ts
+/**
+ * Discriminator literal the planner stamps onto its report's `type`
+ * field. A member of the shared
+ * {@link import("../result/base-report.type").ReportType} closed union.
+ *
+ * {@link PlannerReport} re-declares `type` as this literal by *overriding*
+ * it (`Omit<BaseReport, "type"> & { type: PlannerReportType }`) rather than
+ * intersecting (`BaseReport & { type: "planner" }`). Intersecting a single
+ * literal against `BaseReport.type` (the whole `ReportType` union) lets a
+ * strict TypeScript collapse the entire report to `never` ("property `type`
+ * has conflicting types in some constituents"); the `Omit` override sidesteps
+ * that while still producing the same `type: "planner"` for consumers.
+ */
+type PlannerReportType = "planner";
+/**
+ * Forensic record of a single executed plan step on
+ * {@link PlannerReport.executedSteps}.
+ *
+ * Mirrors the supervisor/orchestrator snapshot shape so a step reads
+ * uniformly. Frozen-friendly plain data — the dispatched capability's
+ * full report tree lives on `childReport` AND under
+ * {@link BaseReport.children}, matching the universal rollup invariant.
+ */
+type PlannerStepSnapshot = {
+  /** 0-based position of this step in the executed plan. */index: number; /** The plan step that drove this dispatch. */
+  step: PlannerStep; /** Terminal status of this step's capability dispatch. */
+  status: "completed" | "failed" | "skipped"; /** The capability's typed output when it completed, if any. */
+  output?: unknown; /** Typed failure cause when the step failed; undefined on success. */
+  error?: AIError;
+  startedAt: string;
+  endedAt: string;
+  duration: number;
+  usage: Usage; /** The dispatched capability's full report tree. */
+  childReport?: BaseReport;
+};
+/**
+ * Planner-specific execution report — {@link BaseReport} plus the
+ * generated plan, the per-step execution snapshots, and the planner's
+ * structural signature.
+ *
+ * `children[]` carries every capability dispatched during plan
+ * execution, in execution order — the cross-cutting tree view shared
+ * with every other primitive. `executedSteps` is the authoritative
+ * per-step record (one entry per step the planner attempted), and
+ * `plan` is the verbatim LLM output before any step ran.
+ */
+type PlannerReport = Omit<BaseReport, "type"> & {
+  type: PlannerReportType; /** Structural fingerprint — same value exposed on the planner instance. */
+  signature: string; /** The full plan the planner's LLM generated before execution began. */
+  plan?: PlannerPlan; /** Per-step forensic records, in execution order. */
+  executedSteps: PlannerStepSnapshot[]; /** ISO-8601 timestamp when cancellation was observed, if any. */
+  cancelledAt?: string;
+};
+/**
+ * Result returned by `planner.execute()`. Satisfies the unified
+ * {@link ExecuteResult} envelope — `usage` and `report` are the
+ * rolled-up totals across the plan-generation trip plus every executed
+ * step — and adds the planner discriminant.
+ *
+ * `data` holds the final step's typed output (or the planner's
+ * structured `output` when an `output` schema was configured). On
+ * failure or cancellation it is `undefined`; `error` carries the typed
+ * cause and `report.status` narrows further.
+ *
+ * @example
+ * const { data, report, usage, error } = await planner.execute(goal);
+ *
+ * if (error) {
+ *   logger.error(error.code, { steps: report.executedSteps.length });
+ *   return;
+ * }
+ *
+ * console.log(report.plan?.summary, usage.total);
+ */
+type PlannerResult<TOutput = unknown> = Omit<ExecuteResult<TOutput>, "report"> & {
+  /** Discriminant for narrowing a heterogeneous result union. */type: "planner";
+  report: PlannerReport;
+};
+//#endregion
+export { PlannerReport, PlannerReportType, PlannerResult, PlannerStepSnapshot };
+//# sourceMappingURL=planner-result.type.d.mts.map

package/esm/contracts/planner/planner-result.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-result.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/planner/planner-result.type.ts"],"mappings":";;;;;;;;;AAmBA;;;;AAA6B;AAW7B;;;;;;KAXY,iBAAA;;;;;;;;;;KAWA,mBAAA;EAYV,0DAVA,KAAA,UAYA;EAVA,IAAA,EAAM,WAAA,EAYN;EAVA,MAAA,sCAUwB;EARxB,MAAA,YAsBU;EApBV,KAAA,GAAQ,OAAA;EACR,SAAA;EACA,OAAA;EACA,QAAA;EACA,KAAA,EAAO,KAAA,EAqBA;EAnBP,WAAA,GAAc,UAAA;AAAA;;;;;;;;;;;;KAcJ,aAAA,GAAgB,IAAA,CAAK,UAAA;EAC/B,IAAA,EAAM,iBAAA,EAgCI;EA9BV,SAAA,UA8BuB;EA5BvB,IAAA,GAAO,WAAA,EA4B2C;EA1BlD,aAAA,EAAe,mBAAA,IA6BP;EA3BR,WAAA;AAAA;;;;;;;;;AA2BqB;;;;;;;;;;;;;KAHX,aAAA,sBAAmC,IAAA,CAAK,aAAA,CAAc,OAAA;iEAEhE,IAAA;EACA,MAAA,EAAQ,aAAA;AAAA"}