@warlock.js/ai 4.1.1

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

@@ -0,0 +1,26 @@
+import { AIError } from "../../errors/ai-error.mjs";
+import { Usage } from "./usage.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/result/base-result.type.d.ts
+/**
+ * Minimal shape every execution result satisfies. Used as the upper
+ * bound on `ExecutableContract`'s `TResult` generic so the contract
+ * can promise the fields every caller needs regardless of which
+ * primitive ran.
+ *
+ * Timing metadata now lives on each primitive's `report` field (see
+ * `ExecutionReport`); `duration` was removed from this base to avoid
+ * two sources of truth.
+ *
+ * @example
+ * function summarize(result: BaseResult) {
+ *   console.log(`${result.usage.total} tokens, ${result.error ? "failed" : "ok"}`);
+ * }
+ */
+type BaseResult = {
+  /** Typed AI error if the execution failed, undefined on success. */error?: AIError; /** Aggregated token usage across the execution. */
+  usage: Usage;
+};
+//#endregion
+export { BaseResult };
+//# sourceMappingURL=base-result.type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"base-result.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/result/base-result.type.ts"],"mappings":";;;;;;AAkBA;;;;;;;;;AAIc;;;;KAJF,UAAA;sEAEV,KAAA,GAAQ,OAAA;EAER,KAAA,EAAO,KAAK;AAAA"}

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

@@ -0,0 +1,40 @@
+import { AIError } from "../../errors/ai-error.mjs";
+import { Usage } from "./usage.type.mjs";
+import { BaseReport } from "./base-report.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/result/execute-result.type.d.ts
+/**
+ * Unified result envelope returned by every executable primitive —
+ * `tool.invoke()`, `agent.execute()`, `workflow.execute()`,
+ * `supervisor.execute()`. Per-primitive result types
+ * (`AgentResult`, `WorkflowResult`, `SupervisorResult`,
+ * `ToolInvokeResult`) all satisfy this shape and add their own
+ * discriminator / domain-specific fields.
+ *
+ * `usage` and `report` are **required** on every invocation, including
+ * leaf tools — the framework synthesizes a trivial report for tools
+ * (type `"tool"`, empty children, zero usage, real timing) so
+ * consumers never have to nil-check the presence of a report.
+ *
+ * Recursion happens inside `report.children[]` — parent walks the
+ * report tree top-down to see every child executable that ran.
+ *
+ * @example
+ * const { data, usage, report, error } = await executable.execute(input);
+ *
+ * if (error) {
+ *   logger.error(error.code, { runId: report.runId, duration: report.duration });
+ *   return;
+ * }
+ *
+ * console.log(`spent ${usage.total} tokens across ${report.children.length} children`);
+ */
+type ExecuteResult<TData = unknown> = {
+  /** Typed output if the execution succeeded. */data?: TData; /** Typed AI error if the execution failed, undefined on success. */
+  error?: AIError; /** Rolled-up usage (own + sum of children). Always present. */
+  usage: Usage; /** Recursive execution report — `report.children[]` carries nested executables. */
+  report: BaseReport;
+};
+//#endregion
+export { ExecuteResult };
+//# sourceMappingURL=execute-result.type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"execute-result.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/result/execute-result.type.ts"],"mappings":";;;;;;;AA8BA;;;;;;;;;;;;;;;;;;;AAQoB;;;;;KARR,aAAA;iDAEV,IAAA,GAAO,KAAA;EAEP,KAAA,GAAQ,OAAA;EAER,KAAA,EAAO,KAAA;EAEP,MAAA,EAAQ,UAAA;AAAA"}

package/esm/contracts/result/execution-report.type.d.mts

@@ -0,0 +1,50 @@
+import { BaseReport, ReportStatus } from "./base-report.type.mjs";
+import { LLMTrip } from "./llm-trip.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/result/execution-report.type.d.ts
+/**
+ * Terminal status alias retained for backwards-compatibility with
+ * existing imports. Use {@link ReportStatus} directly for new code —
+ * both point at the same unified union across every primitive.
+ */
+type ExecutionStatus = ReportStatus;
+/**
+ * Alias kept for callers referencing the pre-3.1 shared timing block.
+ * Structurally a {@link BaseReport} — use that for new code.
+ */
+type ExecutionReport = BaseReport;
+/**
+ * Agent-specific execution report — {@link BaseReport} plus the LLM
+ * trip history for a single `agent.execute()` call.
+ *
+ * Tool dispatches that previously lived under `toolCalls[]` are now
+ * reported as child `BaseReport` nodes on
+ * {@link BaseReport.children} — filter by `type === "tool"` to isolate
+ * leaf tool calls, or walk the full tree to see every nested
+ * executable. Trips stay here because they describe the agent's
+ * **internal** turn structure (LLM round-trips), not child executions.
+ *
+ * @example
+ * const { report } = await agent.execute("hi");
+ * console.log(report.status, report.duration, report.trips.length);
+ *
+ * const toolCalls = report.children.filter((c) => c.type === "tool");
+ * const nestedAgents = report.children.filter((c) => c.type === "agent");
+ */
+type AgentReport = BaseReport & {
+  /**
+   * Identity of the model the agent ran against. Captured from the
+   * `ModelContract` at result-build time so consumers can attribute
+   * cost, latency, and behavior to the right upstream — especially
+   * useful when the same provider package fronts multiple labels
+   * (e.g. `openai` vs `openrouter` vs `azure` via the OpenAI adapter).
+   */
+  model: {
+    name: string;
+    provider: string;
+  }; /** Every LLM round-trip that happened during execution. */
+  trips: LLMTrip[];
+};
+//#endregion
+export { AgentReport, ExecutionReport, ExecutionStatus };
+//# sourceMappingURL=execution-report.type.d.mts.map

package/esm/contracts/result/execution-report.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-report.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/result/execution-report.type.ts"],"mappings":";;;;;;AAQA;;;KAAY,eAAA,GAAkB,YAAY;AAAA;AAM1C;;;AAN0C,KAM9B,eAAA,GAAkB,UAAU;AAAA;AAoBxC;;;;;;;;;;;AAUgB;;;;;;AA9BwB,KAoB5B,WAAA,GAAc,UAAA;;;;;;;;EAQxB,KAAA;IAAS,IAAA;IAAc,QAAA;EAAA;EAEvB,KAAA,EAAO,OAAO;AAAA"}

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

@@ -0,0 +1,14 @@
+import { ModelPricing } from "./model-pricing.type.mjs";
+import { Usage } from "./usage.type.mjs";
+import { BaseResult } from "./base-result.type.mjs";
+import { AttemptEntry } from "./attempt-entry.type.mjs";
+import { BaseReport, REPORT_SCHEMA_VERSION, ReportStatus, ReportType } from "./base-report.type.mjs";
+import { ToolCall } from "./tool-call.type.mjs";
+import { LLMTrip } from "./llm-trip.type.mjs";
+import { AgentReport, ExecutionReport, ExecutionStatus } from "./execution-report.type.mjs";
+import { AgentResult } from "./agent-result.type.mjs";
+import { ExecuteResult } from "./execute-result.type.mjs";
+import { StepSnapshot } from "./step-result.type.mjs";
+import { WorkflowReport, WorkflowResult } from "./workflow-result.type.mjs";
+import { SupervisorReport, SupervisorResult, SupervisorTerminatedBy } from "./supervisor-result.type.mjs";
+import { SessionSendResult } from "./session-send-result.type.mjs";

package/esm/contracts/result/llm-trip.type.d.mts

@@ -0,0 +1,36 @@
+import { AIError } from "../../errors/ai-error.mjs";
+import { Usage } from "./usage.type.mjs";
+import { FinishReason } from "../finish-reason.type.mjs";
+import { ToolCall } from "./tool-call.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/result/llm-trip.type.d.ts
+/**
+ * A single LLM round-trip within an agent execution.
+ * An agent may make multiple trips when tools are called.
+ *
+ * @example
+ * const trip: LLMTrip = {
+ *   index: 0,
+ *   input: "Search for the latest AI news",
+ *   output: "I'll search for that...",
+ *   finishReason: "tool_calls",
+ *   duration: 850,
+ *   usage: { input: 120, output: 45, total: 165 },
+ *   toolCalls: [{ tripIndex: 0, name: "searchWeb", input: {...}, duration: 300 }],
+ * };
+ */
+type LLMTrip = {
+  /** 0-indexed position of this trip in the execution sequence */index: number; /** The prompt/input sent to the LLM for this trip */
+  input: string; /** The raw text output from the LLM */
+  output: string; /** Why the LLM stopped generating */
+  finishReason: FinishReason; /** ISO-8601 timestamp when this trip's model call started */
+  startedAt: string; /** ISO-8601 timestamp when this trip finished (post tool dispatch) */
+  endedAt: string; /** Duration of this trip in milliseconds */
+  duration: number; /** Token usage for this trip */
+  usage: Usage; /** Tool calls made during this trip, if any */
+  toolCalls?: ToolCall[]; /** Typed AI error that occurred during this trip, if any */
+  error?: AIError;
+};
+//#endregion
+export { LLMTrip };
+//# sourceMappingURL=llm-trip.type.d.mts.map

package/esm/contracts/result/llm-trip.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-trip.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/result/llm-trip.type.ts"],"mappings":";;;;;;;;AAoBA;;;;;;;;;;;;;KAAY,OAAA;EAUV,gEARA,KAAA,UAYA;EAVA,KAAA,UAYO;EAVP,MAAA,UAYY;EAVZ,YAAA,EAAc,YAAA,EAYN;EAVR,SAAA,UAUe;EARf,OAAA;EAEA,QAAA;EAEA,KAAA,EAAO,KAAA;EAEP,SAAA,GAAY,QAAA;EAEZ,KAAA,GAAQ,OAAA;AAAA"}

package/esm/contracts/result/model-pricing.type.d.mts

@@ -0,0 +1,51 @@
+//#region ../../@warlock.js/ai/src/contracts/result/model-pricing.type.d.ts
+/**
+ * Per-million-token USD pricing for a model. All values are in USD per
+ * 1,000,000 tokens — the industry-standard unit. Used by the framework
+ * to compute `Usage.costUSD` at emit time, so stored reports carry
+ * historical cost (not re-derived against today's pricing).
+ *
+ * **Optionality.** Every field except `input` / `output` is optional.
+ * `cachedInput` / `cachedOutput` are populated only when the provider
+ * actually meters them (OpenAI prompt-cache hits, Anthropic cache
+ * reads / writes). Leave undefined for adapters that don't report a
+ * cache channel — cost falls back to full-rate pricing for those
+ * tokens.
+ *
+ * **Where it lives.** Two declaration sites, both optional:
+ *
+ * 1. `SDK.pricing` — a registry keyed by model name. One source of
+ *    truth per provider; matches how providers publish pricing tables.
+ * 2. `model({ pricing })` — per-model override at instantiation. Wins
+ *    over the SDK-level entry. Critical for multi-tenant projects
+ *    where pricing is contract-specific or runtime-resolved.
+ *
+ * Resolution order: per-model > SDK registry > undefined (no cost
+ * computed).
+ *
+ * @example
+ * const pricing: ModelPricing = {
+ *   input: 0.15,
+ *   output: 0.6,
+ *   cachedInput: 0.075,
+ * };
+ */
+type ModelPricing = {
+  /** USD per 1M input tokens. */input: number; /** USD per 1M output tokens. */
+  output: number;
+  /**
+   * USD per 1M input tokens served from the provider's prompt cache.
+   * Typically a fraction of `input`. Falls back to `input` when
+   * undefined.
+   */
+  cachedInput?: number;
+  /**
+   * USD per 1M tokens written to the provider's prompt cache.
+   * Anthropic charges a small premium on cache-write tokens; OpenAI
+   * does not. Falls back to `output` when undefined.
+   */
+  cachedOutput?: number;
+};
+//#endregion
+export { ModelPricing };
+//# sourceMappingURL=model-pricing.type.d.mts.map

package/esm/contracts/result/model-pricing.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-pricing.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/result/model-pricing.type.ts"],"mappings":";;AA+BA;;;;;;;;;AAgBc;;;;;;;;;;;;;;;;;;;;;KAhBF,YAAA;iCAEV,KAAA;EAEA,MAAA;;;;;;EAMA,WAAA;;;;;;EAMA,YAAA;AAAA"}

package/esm/contracts/result/session-send-result.type.d.mts

@@ -0,0 +1,29 @@
+import { AIError } from "../../errors/ai-error.mjs";
+import { Usage } from "./usage.type.mjs";
+import { AgentResult } from "./agent-result.type.mjs";
+import { WorkflowResult } from "./workflow-result.type.mjs";
+import { SupervisorResult } from "./supervisor-result.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/result/session-send-result.type.d.ts
+/**
+ * Result returned by SessionContract.send().
+ * Narrows executionResult by checking the `type` discriminant.
+ *
+ * @example
+ * const result = await session.send("Analyze this dataset");
+ * if (result.executionResult.type === "agent") {
+ *   console.log(result.executionResult.report.trips.length, "trips");
+ * } else if (result.executionResult.type === "workflow") {
+ *   console.log(Object.keys(result.executionResult.steps), "steps ran");
+ * }
+ */
+type SessionSendResult = {
+  /** Final text response to display to the user */response: string; /** Whether the session is complete (no more turns expected) */
+  done: boolean; /** Typed AI error if the session turn failed */
+  error?: AIError; /** Full execution result — narrow by `.executionResult.type` */
+  executionResult: AgentResult<unknown> | SupervisorResult<unknown> | WorkflowResult<unknown>; /** Aggregated token usage for this turn */
+  usage: Usage;
+};
+//#endregion
+export { SessionSendResult };
+//# sourceMappingURL=session-send-result.type.d.mts.map

package/esm/contracts/result/session-send-result.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-send-result.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/result/session-send-result.type.ts"],"mappings":";;;;;;;;;AAkBA;;;;;;;;;;KAAY,iBAAA;EAIV,iDAFA,QAAA,UAIQ;EAFR,IAAA,WAKI;EAHJ,KAAA,GAAQ,OAAA,EAKJ;EAHJ,eAAA,EACI,WAAA,YACA,gBAAA,YACA,cAAA,WAEG;EAAP,KAAA,EAAO,KAAA;AAAA"}

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

@@ -0,0 +1,43 @@
+import { AIError } from "../../errors/ai-error.mjs";
+import { Usage } from "./usage.type.mjs";
+import { AttemptEntry } from "./attempt-entry.type.mjs";
+import { AgentReport } from "./execution-report.type.mjs";
+import { AgentResult } from "./agent-result.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/result/step-result.type.d.ts
+/**
+ * Frozen snapshot of a completed workflow step, stored under
+ * `WorkflowReport.steps[name]` and `ctx.steps[name]`.
+ *
+ * For agent-backed steps, three forensic fields are surfaced at the
+ * top level for easy inspection:
+ *
+ * - `agentReport` — trips, tool calls, status, timing for the agent
+ *   call that produced this step's output. Mirrors
+ *   `executionResult.report` but is directly reachable without
+ *   narrowing the union.
+ * - `agentUsage` — token counts for this step in isolation. Sum of
+ *   all `steps[*].agentUsage` equals the workflow-level `usage`.
+ * - `executionResult` — the full `AgentResult` (or custom `run`
+ *   return value). Use this when you need `data` / `text` / `error`
+ *   alongside the report.
+ */
+type StepSnapshot = Readonly<{
+  output: unknown;
+  skipped: boolean;
+  status: "completed" | "skipped" | "failed";
+  startedAt: string;
+  endedAt: string;
+  duration: number;
+  attempts: number;
+  attemptHistory: AttemptEntry[];
+  error?: AIError;
+  state: Readonly<Record<string, unknown>>; /** Full agent result when the step ran an agent; absent for `run` / skipped / parallel steps. */
+  executionResult?: AgentResult<unknown>; /** Shortcut: `executionResult.report` when present. */
+  agentReport?: AgentReport; /** Shortcut: `executionResult.usage` when present. */
+  agentUsage?: Usage; /** Nested children for parallel steps. */
+  steps?: Record<string, StepSnapshot>;
+}>;
+//#endregion
+export { StepSnapshot };
+//# sourceMappingURL=step-result.type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"step-result.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/result/step-result.type.ts"],"mappings":";;;;;;;;AAyBA;;;;;;;;;;;;;;;;KAAY,YAAA,GAAe,QAAA;EACzB,MAAA;EACA,OAAA;EACA,MAAA;EACA,SAAA;EACA,OAAA;EACA,QAAA;EACA,QAAA;EACA,cAAA,EAAgB,YAAA;EAChB,KAAA,GAAQ,OAAA;EACR,KAAA,EAAO,QAAA,CAAS,MAAA,oBAAhB;EAEA,eAAA,GAAkB,WAAA,WAFF;EAIhB,WAAA,GAAc,WAAA,EAFI;EAIlB,UAAA,GAAa,KAAA,EAFC;EAId,KAAA,GAAQ,MAAA,SAAe,YAAA;AAAA"}

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

@@ -0,0 +1,86 @@
+import { BaseResult } from "./base-result.type.mjs";
+import { BaseReport } from "./base-report.type.mjs";
+import { AckSnapshot, IterationSnapshot } from "../supervisor/iteration-snapshot.type.mjs";
+import { ClassifierSnapshot } from "../supervisor/classifier-context.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/result/supervisor-result.type.d.ts
+/**
+ * How the supervisor decided to stop iterating. Recorded so log and
+ * dashboard queries can slice "ended because router said END" from
+ * "ran out of iterations" from "user aborted" without re-reading the
+ * error object.
+ */
+type SupervisorTerminatedBy = "router" | "route" | "classifier" | "evaluate" | "max-iterations" | "cancelled" | "error";
+/**
+ * Supervisor-specific execution report. Extends {@link BaseReport}
+ * with supervisor-only fields — iteration count, termination reason,
+ * per-iteration snapshots — while sharing the canonical timing,
+ * status, usage, and recursive `children[]` block with every other
+ * primitive.
+ *
+ * `snapshots` remains the primary iteration-granularity debug artifact
+ * — every routing decision, every dispatch, every evaluate verdict.
+ * The cross-cutting view of "which executables ran underneath" lives
+ * on {@link BaseReport.children}, which duplicates nothing: it's the
+ * reports of the child agents/workflows dispatched across iterations.
+ */
+type SupervisorReport = BaseReport & {
+  supervisorName: string; /** Structural fingerprint — same value exposed on the instance. */
+  signature: string;
+  terminatedBy: SupervisorTerminatedBy; /** How many iterations ran (including the terminal one). */
+  iterations: number; /** ISO-8601 timestamp when a cancellation was observed, if any. */
+  cancelledAt?: string;
+  snapshots: IterationSnapshot[];
+  /**
+   * Receptionist (`ackAgent`) forensic record. Present only when an
+   * ack agent was configured AND the run started fresh (resumes don't
+   * re-fire ack). The ack agent's full report node also lives under
+   * `children[]` like any other dispatched agent.
+   */
+  ack?: AckSnapshot;
+  /**
+   * Classifier (Phase 7 / decisions §37) forensic record. Present
+   * only when `SupervisorConfig.classifier` was configured AND the
+   * run started fresh (resumes don't re-fire classifier). Sibling of
+   * `ack` — full forensic detail regardless of what strip-merged
+   * into state. Distinct from the children list — classifier runs
+   * are not also pushed onto `children[]`.
+   */
+  classifier?: ClassifierSnapshot;
+};
+/**
+ * Result returned by `supervisor.execute()` and resolved by
+ * `stream.result`. Canonical destructure —
+ * `const { data, report, usage, error } = await supervisor.execute(...)` —
+ * mirrors agent and workflow so nested composition feels uniform.
+ *
+ * `data` populates only on successful completion of a supervisor
+ * configured with `output`. On failure or cancellation it is
+ * `undefined`; `error` carries the typed cause and `report.status`
+ * narrows further.
+ *
+ * `usage` is rolled up from every child executable this supervisor
+ * ran (router agent, dispatched agents/workflows, evaluate agent) —
+ * see {@link BaseReport} rollup semantics.
+ *
+ * @example
+ * const { data, report, usage, error } = await supervisor.execute(input);
+ *
+ * if (error) {
+ *   logger.error(error.code, {
+ *     terminatedBy: report.terminatedBy,
+ *     iterations: report.iterations,
+ *   });
+ *   return;
+ * }
+ *
+ * return { answer: data, cost: usage.total, turns: report.iterations };
+ */
+type SupervisorResult<TOutput = unknown> = BaseResult & {
+  /** Discriminant for narrowing `SessionSendResult.executionResult`. */type: "supervisor";
+  data?: TOutput;
+  report: SupervisorReport;
+};
+//#endregion
+export { SupervisorReport, SupervisorResult, SupervisorTerminatedBy };
+//# sourceMappingURL=supervisor-result.type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-result.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/result/supervisor-result.type.ts"],"mappings":";;;;;;;;AAWA;;;;KAAY,sBAAA;AAsBZ;;;;;;;;;;;;;AAAA,KAAY,gBAAA,GAAmB,UAAA;EAC7B,cAAA,UAKA;EAHA,SAAA;EACA,YAAA,EAAc,sBAAA,EAKH;EAHX,UAAA,UAUM;EARN,WAAA;EACA,SAAA,EAAW,iBAAA;EAgBoB;AAAA;AA+BjC;;;;EAxCE,GAAA,GAAM,WAAA;EA4CE;;;;;;;;EAnCR,UAAA,GAAa,kBAAA;AAAA;;AAmCW;;;;;;;;;;;;;;;;;;;;;;;;;;;KAJd,gBAAA,sBAAsC,UAAA;wEAEhD,IAAA;EACA,IAAA,GAAO,OAAA;EACP,MAAA,EAAQ,gBAAA;AAAA"}

package/esm/contracts/result/tool-call.type.d.mts

@@ -0,0 +1,44 @@
+import { AIError } from "../../errors/ai-error.mjs";
+import { BaseReport } from "./base-report.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/result/tool-call.type.d.ts
+/**
+ * Forensic record of a single leaf-tool dispatch inside an agent's
+ * execution. Structurally a {@link BaseReport} (`type: "tool"`) with
+ * agent-level enrichments — the originating LLM trip index, the raw
+ * input the model emitted, the concrete output returned, and the
+ * typed error if any.
+ *
+ * Because `ToolCall` is a `BaseReport`, it drops directly into
+ * `AgentReport.children[]` alongside nested agent/workflow/supervisor
+ * reports, keeping the recursive tree uniform. It also powers the
+ * live `agent.tool.called` event + stream payloads so subscribers see
+ * the same shape during execution as they read post-hoc.
+ *
+ * @example
+ * const toolCalls = agentReport.children.filter(
+ *   (c): c is ToolCall => c.type === "tool",
+ * );
+ * for (const call of toolCalls) {
+ *   console.log(call.name, call.tripIndex, call.input, call.output);
+ * }
+ */
+type ToolCall = BaseReport & {
+  /** Discriminator already fixed on BaseReport, narrowed to "tool" here. */type: "tool"; /** Which LLM trip triggered this tool call (0-indexed). */
+  tripIndex: number; /** Input passed to the tool (validated args from the model's request). */
+  input: unknown; /** Output returned by the tool (undefined if an error occurred). */
+  output?: unknown; /** Typed AI error thrown during dispatch (validation or execute), if any. */
+  error?: AIError;
+  /**
+   * Provenance marker copied from the originating
+   * `ModelToolCallRequest.recoveredFrom`. Present only when this
+   * dispatch came from the streaming tool-call guard recovering a
+   * leaked JSON envelope from the text channel; absent for real
+   * provider tool-calls. Telemetry consumers branch on this to compute
+   * per-model leak rate.
+   */
+  recoveredFrom?: "stream-text";
+};
+//#endregion
+export { ToolCall };
+//# sourceMappingURL=tool-call.type.d.mts.map

package/esm/contracts/result/tool-call.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-call.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/result/tool-call.type.ts"],"mappings":";;;;;;AAwBA;;;;;;;;;;;;;AAmBe;;;;;;KAnBH,QAAA,GAAW,UAAA;4EAErB,IAAA;EAEA,SAAA;EAEA,KAAA;EAEA,MAAA;EAEA,KAAA,GAAQ,OAAO;;;;;;;;;EASf,aAAA;AAAA"}

package/esm/contracts/result/usage.type.d.mts

@@ -0,0 +1,57 @@
+import { ModelPricing } from "./model-pricing.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/result/usage.type.d.ts
+/**
+ * Token usage statistics for a single LLM call or aggregated across trips.
+ *
+ * `cachedTokens` is optional and represents the subset of `input` that
+ * was served from the provider's prompt cache (OpenAI's
+ * `prompt_tokens_details.cached_tokens`, Anthropic's
+ * `cache_read_input_tokens`). Cache-hit tokens are usually billed at
+ * a fraction of the full input rate — separate accounting lets cost
+ * code price them correctly. Defaults to 0 / undefined when the
+ * provider doesn't report it.
+ *
+ * @example
+ * const usage: Usage = {
+ *   input: 150,
+ *   output: 320,
+ *   total: 470,
+ *   cachedTokens: 120,
+ *   cost: { input: 0.0000045, output: 0.000192, cachedInput: 0.000009 },
+ * };
+ */
+type Usage = {
+  /** Number of input/prompt tokens consumed (includes cachedTokens). */input: number; /** Number of output/completion tokens generated. */
+  output: number; /** Total tokens (input + output). */
+  total: number;
+  /**
+   * Subset of `input` served from the provider's prompt cache. Billed
+   * at a discounted rate when cost is computed downstream. Optional —
+   * providers that don't report cache hits leave this undefined.
+   */
+  cachedTokens?: number;
+  /**
+   * Cost breakdown in USD, computed at emit time from `tokens × pricing[model]`
+   * when the model adapter declared a `ModelPricing`. Same shape as
+   * `ModelPricing` (input / output / cachedInput / cachedOutput) so
+   * dashboards can tell HOW the total was reached — what share was
+   * input vs output, how much the prompt cache saved — instead of
+   * looking at one opaque number.
+   *
+   * Captured as a historical fact so stored reports remain accurate
+   * even after the pricing table changes upstream.
+   *
+   * `undefined` when no pricing is available (legacy adapters, unknown
+   * model names, intentionally unpriced free-tier runs). Aggregators
+   * merge defined fields and leave undefined ones untouched, so an
+   * unpriced child cannot erase priced siblings.
+   *
+   * For a single scalar total, sum the populated fields:
+   * `(cost.input ?? 0) + (cost.output ?? 0) + (cost.cachedInput ?? 0) + (cost.cachedOutput ?? 0)`.
+   */
+  cost?: ModelPricing;
+};
+//#endregion
+export { Usage };
+//# sourceMappingURL=usage.type.d.mts.map

package/esm/contracts/result/usage.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/result/usage.type.ts"],"mappings":";;;;;AAsBA;;;;;;;;;;;AAgCqB;;;;;;;KAhCT,KAAA;wEAEV,KAAA;EAEA,MAAA;EAEA,KAAA;;;;;;EAMA,YAAA;;;;;;;;;;;;;;;;;;;;EAoBA,IAAA,GAAO,YAAY;AAAA"}

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

@@ -0,0 +1,45 @@
+import { AIError } from "../../errors/ai-error.mjs";
+import { BaseResult } from "./base-result.type.mjs";
+import { BaseReport } from "./base-report.type.mjs";
+import { StepSnapshot } from "./step-result.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/result/workflow-result.type.d.ts
+/**
+ * Workflow-specific execution report — {@link BaseReport} plus
+ * per-step snapshots and the final frozen `ctx.state`.
+ *
+ * `report.children[]` carries every executable (tool, agent,
+ * sub-workflow, supervisor) any step invoked, in invocation order.
+ * `report.steps` remains the authoritative record of workflow
+ * structure — one entry per defined step — while `children` gives
+ * the cross-cutting tree view shared with other primitives.
+ */
+type WorkflowReport = BaseReport & {
+  workflowName: string; /** Structural fingerprint — same value exposed on the workflow instance. */
+  signature: string; /** ISO-8601 timestamp when cancellation was observed, if any. */
+  cancelledAt?: string; /** Per-step snapshots keyed by step name. */
+  steps: Record<string, StepSnapshot>; /** Frozen final `ctx.state` at the moment the workflow terminated. */
+  state: Readonly<Record<string, unknown>>;
+};
+/**
+ * Result returned by `workflow.execute()` / `workflow.resume()`.
+ *
+ * Canonical destructuring (mirrors `AgentResult` and
+ * `SupervisorResult`):
+ *
+ *   `const { data, report, usage, error } = await workflow.execute(...)`
+ *
+ * `data` is populated only when the workflow was defined with an
+ * `output: { extract, schema? }` spec and completed successfully. On
+ * failure or cancellation it is `undefined`; read `error` and
+ * `report.status` instead.
+ */
+type WorkflowResult<TOutput = unknown> = BaseResult & {
+  type: "workflow";
+  data?: TOutput;
+  report: WorkflowReport;
+  error?: AIError;
+};
+//#endregion
+export { WorkflowReport, WorkflowResult };
+//# sourceMappingURL=workflow-result.type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-result.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/result/workflow-result.type.ts"],"mappings":";;;;;;;;AAeA;;;;;;;;KAAY,cAAA,GAAiB,UAAA;EAC3B,YAAA,UAD2B;EAG3B,SAAA;EAEA,WAAA,WAEA;EAAA,KAAA,EAAO,MAAA,SAAe,YAAA,GAAA;EAEtB,KAAA,EAAO,QAAA,CAAS,MAAA;AAAA;;;AAAM;AAgBxB;;;;;;;;;;KAAY,cAAA,sBAAoC,UAAA;EAC9C,IAAA;EACA,IAAA,GAAO,OAAA;EACP,MAAA,EAAQ,cAAA;EACR,KAAA,GAAQ,OAAA;AAAA"}

package/esm/contracts/sdk-adapter.contract.d.mts

@@ -0,0 +1,77 @@
+import { ModelPricing } from "./result/model-pricing.type.mjs";
+import { EmbedderConfig, EmbedderContract } from "./embedder.contract.mjs";
+import { ModelContract } from "./model.contract.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/sdk-adapter.contract.d.ts
+/**
+ * Configuration passed to SDKAdapterContract.model() to create a model instance.
+ *
+ * @example
+ * const model = ai.openai.model({ name: "gpt-4o", temperature: 0.7 });
+ *
+ * @example
+ * // Per-model pricing override (multi-tenant projects where the
+ * // rate is contract-specific or runtime-resolved):
+ * openai.model({
+ *   name: "gpt-4o",
+ *   pricing: { input: 2.5, output: 10 },
+ * });
+ */
+type ModelConfig = {
+  /** Model identifier (e.g. "gpt-4o", "claude-3-5-sonnet-20241022") */name: string; /** Sampling temperature (0–2). Higher = more creative, lower = more focused */
+  temperature?: number; /** Maximum tokens to generate in the response */
+  maxTokens?: number;
+  /**
+   * Per-model USD pricing override. Wins over any SDK-level pricing
+   * registry — useful in multi-tenant projects where the rate is
+   * contract-specific or runtime-resolved. When omitted, the adapter
+   * falls back to its SDK-level registry (if any); when neither is
+   * configured, `Usage.cost` stays `undefined` (honest absence, not
+   * false zero).
+   */
+  pricing?: ModelPricing; /** Additional provider-specific configuration */
+  [key: string]: unknown;
+};
+/**
+ * What every SDK adapter factory returns.
+ * Becomes `ai.[sdkName]` on the AI namespace (e.g. `ai.openai`, `ai.anthropic`).
+ *
+ * @example
+ * // OpenAI adapter registered as ai.openai
+ * const model = ai.openai.model({ name: "gpt-4o" });
+ * const tokens = await ai.openai.count("Hello world", "gpt-4o");
+ *
+ * @example
+ * // Mock adapter for tests
+ * const mock = MockSDK();
+ * const model = mock.model({ name: "mock-model" });
+ */
+interface SDKAdapterContract {
+  /**
+   * Create a model instance with the given configuration.
+   * The returned ModelContract is passed to agents, tools, and other primitives.
+   */
+  model(config: ModelConfig): ModelContract;
+  /**
+   * Count the number of tokens in the given text.
+   * Implementation is deferred to each adapter package.
+   *
+   * @param text - The text to tokenize and count
+   * @param model - Optional model name; affects tokenizer selection for some providers
+   * @returns Promise resolving to the token count
+   */
+  count(text: string, model?: string): Promise<number>;
+  /**
+   * Create an embedder bound to this SDK's client. Optional — not every
+   * provider supports embeddings (e.g. a hypothetical Anthropic adapter
+   * today). Consumers should check for presence before calling.
+   *
+   * @example
+   * const embedder = openai.embedder({ name: "text-embedding-3-small" });
+   * const { vector } = await embedder.embed("Hello world");
+   */
+  embedder?(config: EmbedderConfig): EmbedderContract;
+}
+//#endregion
+export { ModelConfig, SDKAdapterContract };
+//# sourceMappingURL=sdk-adapter.contract.d.mts.map