@warlock.js/ai 4.1.1

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

@@ -0,0 +1,140 @@
+import { AIError } from "../../errors/ai-error.mjs";
+import { AgentResult } from "../result/agent-result.type.mjs";
+import { ToolInvokeResult } from "../../tool/tool.mjs";
+import { MiddlewareExecuteContext, MiddlewareToolContext, MiddlewareTripContext } from "./middleware-context.type.mjs";
+import { ModelResponse } from "../model.contract.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/middleware/middleware.contract.d.ts
+/**
+ * `execute`-level hook map. Wraps the entire `agent.execute()` call.
+ *
+ * - `before` — fires once at the start of the run. Throw to abort the
+ *   whole execution before any model call is made (e.g. budget pre-check,
+ *   hard deny based on a ctx flag).
+ * - `after`  — fires once at the end of a successful run with the final
+ *   `AgentResult`. Optional return value replaces the result. Does not
+ *   fire when the run errored — use `onError` for that path.
+ * - `onError`— fires once when the run aborted with an error. Optional
+ *   return value recovers: the engine treats the returned `AgentResult`
+ *   as the real outcome and clears the error. `void` / omitted rethrow.
+ */
+type AgentMiddlewareExecuteHooks = {
+  before?(ctx: MiddlewareExecuteContext): void | Promise<void>;
+  after?(ctx: MiddlewareExecuteContext, result: AgentResult<unknown>): void | AgentResult<unknown> | Promise<void | AgentResult<unknown>>;
+  onError?(ctx: MiddlewareExecuteContext, error: AIError): void | AgentResult<unknown> | Promise<void | AgentResult<unknown>>;
+};
+/**
+ * `trip`-level hook map. Wraps each model round-trip individually.
+ *
+ * - `before` — fires just before `model.complete()` / `model.stream()`.
+ *   Return a `ModelResponse` to short-circuit the call entirely
+ *   (semantic cache hit, offline fixture replay). Throw to abort the
+ *   trip with a typed error (guardrail input rejection).
+ * - `after`  — fires immediately after a successful model response.
+ *   Optional `ModelResponse` return replaces the response before the
+ *   engine builds its `LLMTrip` record or dispatches tool calls.
+ * - `onError`— fires when the model call threw. Return a `ModelResponse`
+ *   to recover (fallback chain), or `void` to propagate the error up.
+ */
+type AgentMiddlewareTripHooks = {
+  before?(ctx: MiddlewareTripContext): void | ModelResponse | Promise<void | ModelResponse>;
+  after?(ctx: MiddlewareTripContext, response: ModelResponse): void | ModelResponse | Promise<void | ModelResponse>;
+  onError?(ctx: MiddlewareTripContext, error: AIError): void | ModelResponse | Promise<void | ModelResponse>;
+};
+/**
+ * `tool`-level hook map. Wraps each tool dispatch individually.
+ *
+ * - `before` — fires just before the wrapped `tool.invoke()`. Return a
+ *   `ToolInvokeResult` to short-circuit (cached tool response, hard
+ *   rate-limit rejection). Throw to abort the agent with a typed error.
+ * - `after`  — fires after a successful tool invocation. Optional
+ *   `ToolInvokeResult` return replaces the result before the engine
+ *   records it into `toolCalls` / the next trip's messages.
+ * - `onError`— fires when the tool threw synchronously (rare — `invoke`
+ *   itself never throws; this covers catastrophic runtime crashes in
+ *   the pipeline wrap). Return a `ToolInvokeResult` to recover.
+ */
+type AgentMiddlewareToolHooks = {
+  before?(ctx: MiddlewareToolContext): void | ToolInvokeResult<unknown> | Promise<void | ToolInvokeResult<unknown>>;
+  after?(ctx: MiddlewareToolContext, result: ToolInvokeResult<unknown>): void | ToolInvokeResult<unknown> | Promise<void | ToolInvokeResult<unknown>>;
+  onError?(ctx: MiddlewareToolContext, error: AIError): void | ToolInvokeResult<unknown> | Promise<void | ToolInvokeResult<unknown>>;
+};
+/**
+ * Agent-level middleware — a composable interceptor that wraps agent
+ * execution at one or more of three granularities: the whole
+ * `agent.execute()` call (`execute`), each LLM round-trip (`trip`),
+ * and each tool dispatch (`tool`).
+ *
+ * **Role.** The single authoring surface for cross-cutting concerns
+ * around an agent: budgets, guardrails, semantic cache, observability
+ * exports, fallback chains. One middleware = one config object.
+ * Middleware declares **any subset** of the three level hook maps; the
+ * pipeline skips levels a given middleware doesn't care about.
+ *
+ * **Ordering.** Registration order defines execution order: for every
+ * level, `before` hooks run top-down through the array, `after` and
+ * `onError` hooks run bottom-up (onion model — same mental picture as
+ * Koa / Express middleware). No priority numbers. The canonical
+ * install order documented in the subskill is:
+ * `[cache, budget, guardrail, observability]`.
+ *
+ * **Abort vs. synthetic-return.** Middleware has two ways to change
+ * behavior. Throwing an `AIError` aborts the wrapped operation (the
+ * error surfaces on `result.error` — `execute()` still never throws).
+ * Returning a value from a `before` hook short-circuits the wrapped
+ * operation with that value as its result, skipping the real work
+ * and running `after` hooks in reverse as if the wrapped operation
+ * had produced the value itself. Cache hits use the short-circuit
+ * path; budgets and guardrails use the throw path.
+ *
+ * **State.** Middleware never holds mutable state in closure — a
+ * single middleware object may be registered on multiple agents, or
+ * invoked by concurrent `execute()` calls on the same agent. Use
+ * `ctx.state` (fresh per execution) for any cross-hook bookkeeping.
+ *
+ * **Type independence.** Middleware is never generic over the agent's
+ * `TOutput`. A budget or guardrail must be reusable across every
+ * agent in the app, so all level hooks see `AgentResult<unknown>` and
+ * `AgentExecuteOptions<unknown>`. Output-specific logic belongs in
+ * the caller or in a purpose-built middleware for that agent.
+ *
+ * @example
+ * const budget: AgentMiddleware = {
+ *   name: "budget",
+ *   execute: {
+ *     before(ctx) { ctx.state.set("budget.used", 0); },
+ *   },
+ *   trip: {
+ *     after(ctx, response) {
+ *       const used = (ctx.state.get("budget.used") as number) + response.usage.total;
+ *       ctx.state.set("budget.used", used);
+ *       if (used > 1_000) throw new BudgetExceededError("token cap", { limit: 1_000, actual: used, unit: "tokens" });
+ *     },
+ *   },
+ * };
+ *
+ * const myAgent = agent({
+ *   model,
+ *   middleware: [budget],
+ * });
+ */
+type AgentMiddleware = {
+  /**
+   * Stable identifier for this middleware — used in logs, as the
+   * state-bag namespace prefix, and in the canonical install-order
+   * documentation. Should be kebab-case.
+   */
+  name: string;
+  /**
+   * Optional per-middleware log kill-switch. `false` silences the
+   * pipeline's `debug`-level trace for this middleware only; other
+   * middlewares in the same pipeline continue logging. Default `true`.
+   */
+  log?: boolean;
+  execute?: AgentMiddlewareExecuteHooks;
+  trip?: AgentMiddlewareTripHooks;
+  tool?: AgentMiddlewareToolHooks;
+};
+//#endregion
+export { AgentMiddleware, AgentMiddlewareExecuteHooks, AgentMiddlewareToolHooks, AgentMiddlewareTripHooks };
+//# sourceMappingURL=middleware.contract.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/middleware/middleware.contract.ts"],"mappings":";;;;;;;;;;AAuBA;;;;;;;;;;KAAY,2BAAA;EACV,MAAA,EAAQ,GAAA,EAAK,wBAAA,UAAkC,OAAA;EAC/C,KAAA,EACE,GAAA,EAAK,wBAAA,EACL,MAAA,EAAQ,WAAA,mBACA,WAAA,YAAuB,OAAA,QAAe,WAAA;EAChD,OAAA,EACE,GAAA,EAAK,wBAAA,EACL,KAAA,EAAO,OAAA,UACC,WAAA,YAAuB,OAAA,QAAe,WAAA;AAAA;;;;;;;;;;;;;;KAgBtC,wBAAA;EACV,MAAA,EACE,GAAA,EAAK,qBAAA,UACG,aAAA,GAAgB,OAAA,QAAe,aAAA;EACzC,KAAA,EACE,GAAA,EAAK,qBAAA,EACL,QAAA,EAAU,aAAA,UACF,aAAA,GAAgB,OAAA,QAAe,aAAA;EACzC,OAAA,EACE,GAAA,EAAK,qBAAA,EACL,KAAA,EAAO,OAAA,UACC,aAAA,GAAgB,OAAA,QAAe,aAAA;AAAA;;;;;;AA3BkB;AAgB7D;;;;;;;KA2BY,wBAAA;EACV,MAAA,EACE,GAAA,EAAK,qBAAA,UAGH,gBAAA,YACA,OAAA,QAAe,gBAAA;EACnB,KAAA,EACE,GAAA,EAAK,qBAAA,EACL,MAAA,EAAQ,gBAAA,mBAGN,gBAAA,YACA,OAAA,QAAe,gBAAA;EACnB,OAAA,EACE,GAAA,EAAK,qBAAA,EACL,KAAA,EAAO,OAAA,UAGL,gBAAA,YACA,OAAA,QAAe,gBAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AApCmC;AAgBxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAkFY,eAAA;EAzER;;;;;EA+EF,IAAA;EAzEE;;;;;EA+EF,GAAA;EACA,OAAA,GAAU,2BAAA;EACV,IAAA,GAAO,wBAAA;EACP,IAAA,GAAO,wBAAA;AAAA"}

package/esm/contracts/model-tool-call-request.type.d.mts

@@ -0,0 +1,58 @@
+//#region ../../@warlock.js/ai/src/contracts/model-tool-call-request.type.d.ts
+/**
+ * A raw tool call request returned by the model during a complete() call or
+ * emitted as a chunk during stream(). Agents look up the tool by `name` and
+ * correlate the eventual tool-result message back to the model using `id`.
+ *
+ * @example
+ * const req: ModelToolCallRequest = {
+ *   id: "call_abc123",
+ *   name: "searchWeb",
+ *   input: { query: "warlock.js docs" },
+ * };
+ */
+type ModelToolCallRequest = {
+  /** Provider-generated id; agent echoes it on the matching tool-result message */id: string; /** Registered tool name the model wants to invoke */
+  name: string; /** Arguments the model produced for the tool */
+  input: unknown;
+  /**
+   * Provenance marker stamped by the framework, NOT the provider.
+   * Present only when the agent's stream-time tool-call guard
+   * synthesized this request from a JSON envelope the model emitted as
+   * literal text in the content channel. Absent means the provider
+   * emitted a structured tool call (the normal path).
+   *
+   * Consumers branch on this for:
+   * - **Telemetry**: dashboards measure per-model leak rate as
+   *   `recovered / total`. High rates are a strong signal to drop the
+   *   model from the rotation.
+   * - **Cost auditing**: recovered calls cost the same as real ones
+   *   in terms of tool execution, but the *prompt tokens* that produced
+   *   them were wasted on text the user couldn't see. Worth tracking.
+   *
+   * The framework treats it as informational only — recovered calls
+   * dispatch through the same path as real ones with no behavioral
+   * difference.
+   */
+  recoveredFrom?: "stream-text";
+  /**
+   * Opaque, provider-specific data the adapter must round-trip back to
+   * the provider on the *next* request for this tool call to remain
+   * valid. The framework treats it as a black box: it never reads or
+   * mutates the contents — it only guarantees the object survives from
+   * the model response, through the assistant history message, back
+   * into the adapter's next request.
+   *
+   * Concrete need: Gemini "thinking" models attach a `thoughtSignature`
+   * to every `functionCall` part and **reject the follow-up request
+   * with a 400** if it is missing. Anthropic extended-thinking
+   * signatures are the same shape of problem. Vendor-neutral by
+   * design — only the owning adapter knows the keys.
+   *
+   * Absent for providers (OpenAI, Bedrock, Ollama) that need no echo.
+   */
+  providerMetadata?: Record<string, unknown>;
+};
+//#endregion
+export { ModelToolCallRequest };
+//# sourceMappingURL=model-tool-call-request.type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"model-tool-call-request.type.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/contracts/model-tool-call-request.type.ts"],"mappings":";;AAYA;;;;;;;;;;;KAAY,oBAAA;mFAEV,EAAA;EAEA,IAAA;EAEA,KAAA;;;;;;;;;;;;;;;;;;;;EAoBA,aAAA;;;;;;;;;;;;;;;;;EAiBA,gBAAA,GAAmB,MAAM;AAAA"}

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

@@ -0,0 +1,164 @@
+import { ModelToolCallRequest } from "./model-tool-call-request.type.mjs";
+import { Message } from "./conversation-message.type.mjs";
+import { ModelPricing } from "./result/model-pricing.type.mjs";
+import { Usage } from "./result/usage.type.mjs";
+import { FinishReason } from "./finish-reason.type.mjs";
+import { ToolConfig } from "./tool.contract.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/model.contract.d.ts
+/**
+ * Options passed to model.complete() or model.stream().
+ *
+ * `tools` is first-class so every model implementation is responsible for
+ * converting the vendor-neutral ToolConfig into its own provider format
+ * (OpenAI functions, Anthropic tools, etc.).
+ *
+ * @example
+ * await model.complete(messages, {
+ *   temperature: 0.2,
+ *   maxTokens: 1000,
+ *   tools: [weatherTool, searchTool],
+ * });
+ */
+type ModelCallOptions = {
+  temperature?: number;
+  maxTokens?: number; /** Tools to expose to the LLM on this call. Each model converts to its provider format. */
+  tools?: ToolConfig<unknown, unknown>[];
+  /**
+   * JSON Schema the response must match. Adapters that declare
+   * `capabilities.structuredOutput` forward this to the provider's native
+   * structured-output mechanism (OpenAI `response_format: json_schema`,
+   * Anthropic tool-use trick, etc.). Adapters without native support may
+   * ignore this field — the agent still injects a soft JSON instruction
+   * into the system prompt as a fallback.
+   */
+  responseSchema?: Record<string, unknown>;
+  /**
+   * Cancellation handle. Adapters that wire it into their HTTP client
+   * (OpenAI SDK, fetch) will abort the in-flight request when
+   * `signal.aborted` flips. Adapters without support may ignore it;
+   * the agent still honors the signal at trip boundaries regardless.
+   */
+  signal?: AbortSignal; /** Additional provider-specific options */
+  [key: string]: unknown;
+};
+/**
+ * Declarative feature flags a `ModelContract` may expose so the agent can
+ * short-circuit redundant work when the provider already enforces a
+ * behavior natively.
+ *
+ * @example
+ * class OpenAIModel implements ModelContract {
+ *   public readonly capabilities: ModelCapabilities = { structuredOutput: true };
+ * }
+ */
+type ModelCapabilities = {
+  /**
+   * True when the adapter forwards `ModelCallOptions.responseSchema` to
+   * the provider's native structured-output mechanism and the provider
+   * guarantees a matching response at the token level. When true, the
+   * agent skips the soft "respond in JSON" system-prompt injection.
+   */
+  structuredOutput?: boolean;
+  /**
+   * True when the adapter accepts `ContentPart` entries of type
+   * `"image"` in user messages and the provider can interpret them
+   * (vision models). When false/absent and the caller passes image
+   * attachments, the agent throws upfront rather than silently
+   * dropping them at the wire layer.
+   */
+  vision?: boolean;
+};
+/**
+ * Full response from a non-streaming model call.
+ *
+ * @example
+ * const response: ModelResponse = {
+ *   content: "Here is the answer...",
+ *   finishReason: "stop",
+ *   usage: { input: 120, output: 80, total: 200 },
+ * };
+ */
+type ModelResponse = {
+  content: string;
+  finishReason: FinishReason;
+  usage: Usage; /** Tool calls requested by the model, present when finishReason is "tool_calls" */
+  toolCalls?: ModelToolCallRequest[];
+};
+/**
+ * A single chunk emitted during a streaming model call.
+ *
+ * @example
+ * for await (const chunk of model.stream(messages)) {
+ *   if (chunk.type === "delta") process.stdout.write(chunk.content);
+ *   else if (chunk.type === "done") console.log(chunk.usage.total, "tokens");
+ * }
+ */
+type ModelStreamChunk = {
+  type: "delta";
+  content: string;
+} | {
+  type: "tool-call";
+  id: string;
+  name: string;
+  input: unknown;
+  /**
+   * Opaque provider round-trip data for this call — see
+   * `ModelToolCallRequest.providerMetadata`. The agent copies it
+   * verbatim onto the assembled `ModelToolCallRequest` so streamed
+   * tool calls round-trip identically to non-streamed ones.
+   */
+  providerMetadata?: Record<string, unknown>;
+} | {
+  type: "done";
+  finishReason: FinishReason;
+  usage: Usage;
+};
+/**
+ * Contract every SDK model instance must implement.
+ * Created by SDKAdapterContract.model() — internally holds the SDK client
+ * so agents only need to pass the model, not the SDK.
+ *
+ * @example
+ * const model = ai.openai.model({ name: "gpt-4o", temperature: 0.7 });
+ * const response = await model.complete(messages);
+ *
+ * @example
+ * for await (const chunk of model.stream(messages)) {
+ *   if (chunk.type === "delta") process.stdout.write(chunk.content);
+ * }
+ */
+interface ModelContract {
+  /** Model identifier (e.g. "gpt-4o", "claude-3-5-sonnet-20241022") */
+  readonly name: string;
+  /** Provider this model belongs to (e.g. "openai", "anthropic") */
+  readonly provider: string;
+  /**
+   * Optional feature flags so callers (notably the agent) can skip work
+   * the provider already handles natively. Absent = treat every flag as
+   * `false`.
+   */
+  readonly capabilities?: ModelCapabilities;
+  /**
+   * Per-million-token USD pricing. When set, the framework computes
+   * `Usage.costUSD` at emit time for every trip / tool / report node
+   * touching this model. Resolution: per-model `pricing` (here) >
+   * SDK-level `pricing[name]` registry > undefined (no cost computed).
+   *
+   * Critical for multi-tenant projects where pricing is contract-
+   * specific or runtime-resolved — pass per-model when you need to
+   * override the SDK registry for a single agent.
+   */
+  readonly pricing?: ModelPricing;
+  /**
+   * Send messages and receive a full response once generation is complete.
+   */
+  complete(messages: Message[], options?: ModelCallOptions): Promise<ModelResponse>;
+  /**
+   * Send messages and stream the response chunk by chunk.
+   */
+  stream(messages: Message[], options?: ModelCallOptions): AsyncIterable<ModelStreamChunk>;
+}
+//#endregion
+export { ModelCallOptions, ModelCapabilities, ModelContract, ModelResponse, ModelStreamChunk };
+//# sourceMappingURL=model.contract.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"model.contract.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/contracts/model.contract.ts"],"mappings":";;;;;;;;;;AAqBA;;;;;;;;;;;;KAAY,gBAAA;EACV,WAAA;EACA,SAAA,WAkBS;EAhBT,KAAA,GAAQ,UAAA;EAkBI;AAAA;AAad;;;;AAeQ;AAaR;EAlDE,cAAA,GAAiB,MAAA;;;;;;;EAOjB,MAAA,GAAS,WAAA,EA6CT;EAAA,CA3CC,GAAA;AAAA;;;;;AA8C+B;AAYlC;;;;;KA7CY,iBAAA;EA4DgD;;;;;;EArD1D,gBAAA;EA4CI;;;;;;;EApCJ,MAAM;AAAA;AA6CoD;AAgB5D;;;;;;;;;AAhB4D,KAhChD,aAAA;EACV,OAAA;EACA,YAAA,EAAc,YAAA;EACd,KAAA,EAAO,KAAA,EA6E+D;EA3EtE,SAAA,GAAY,oBAAA;AAAA;;;;;;;;;;KAYF,gBAAA;EACN,IAAA;EAAe,OAAA;AAAA;EAEf,IAAA;EACA,EAAA;EACA,IAAA;EACA,KAAA;EAyDqD;;;AAA8B;;;EAlDnF,gBAAA,GAAmB,MAAA;AAAA;EAEnB,IAAA;EAAc,YAAA,EAAc,YAAA;EAAc,KAAA,EAAO,KAAA;AAAA;;;;;;;;;;;;;;;UAgBtC,aAAA;;WAEN,IAAA;;WAEA,QAAA;;;;;;WAMA,YAAA,GAAe,iBAAA;;;;;;;;;;;WAYf,OAAA,GAAU,YAAA;;;;EAKnB,QAAA,CAAS,QAAA,EAAU,OAAA,IAAW,OAAA,GAAU,gBAAA,GAAmB,OAAA,CAAQ,aAAA;;;;EAKnE,MAAA,CAAO,QAAA,EAAU,OAAA,IAAW,OAAA,GAAU,gBAAA,GAAmB,aAAA,CAAc,gBAAA;AAAA"}

package/esm/contracts/placeholders.type.d.mts

@@ -0,0 +1,23 @@
+//#region ../../@warlock.js/ai/src/contracts/placeholders.type.d.ts
+/**
+ * A map of placeholder keys to their replacement values.
+ * Supports nested access via dot notation in {{mustache}} templates.
+ *
+ * Syntax:
+ * - `{{key}}` — simple replacement
+ * - `{{ctx.city}}` — nested access
+ * - `{{lang|English}}` — with default value
+ *
+ * @example
+ * const placeholders: Placeholders = {
+ *   name: "Hasan",
+ *   ctx: { city: "Cairo", country: "Egypt" },
+ *   lang: "Arabic",
+ * };
+ * // Template: "Hello {{name}}, welcome from {{ctx.city}}. Language: {{lang|English}}"
+ * // Resolved: "Hello Hasan, welcome from Cairo. Language: Arabic"
+ */
+type Placeholders = Record<string, unknown>;
+//#endregion
+export { Placeholders };
+//# sourceMappingURL=placeholders.type.d.mts.map

package/esm/contracts/placeholders.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholders.type.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/contracts/placeholders.type.ts"],"mappings":";;AAkBA;;;;AAAiC;;;;;;;;;;;;;KAArB,YAAA,GAAe,MAAM"}

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

@@ -0,0 +1,33 @@
+import { BaseResult } from "./base-result.type.mjs";
+import { AgentReport } from "./execution-report.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/result/agent-result.type.d.ts
+/**
+ * Result returned by `agent.execute()` and resolved by `stream.result`.
+ *
+ * **Canonical destructuring:** `const { data, text, report, usage, error }`.
+ *
+ * `report.trips` / `report.toolCalls` / `report.duration` hold
+ * everything the old top-level fields did — moving them under
+ * `report` leaves the root clean for the four things callers reach
+ * for constantly (`data`, `text`, `usage`, `error`).
+ *
+ * @example
+ * const { data, error, report, usage } = await agent.execute(input);
+ *
+ * if (error) {
+ *   logger.error(error.code, { duration: report.duration });
+ *   return;
+ * }
+ *
+ * return { answer: data, cost: usage.total, latency: report.duration };
+ */
+type AgentResult<TOutput = unknown> = BaseResult & {
+  /** Discriminant for narrowing `SessionSendResult.executionResult`. */type: "agent"; /** Typed structured output when the caller passed an `output` schema. */
+  data?: TOutput; /** Raw text from the final LLM trip. */
+  text?: string; /** Trips, tool calls, status, and timing for this execution. */
+  report: AgentReport;
+};
+//#endregion
+export { AgentResult };
+//# sourceMappingURL=agent-result.type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-result.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/result/agent-result.type.ts"],"mappings":";;;;;;AAuBA;;;;;;;;;;;;;;;;;AAQqB;KART,WAAA,sBAAiC,UAAA;wEAE3C,IAAA;EAEA,IAAA,GAAO,OAAA;EAEP,IAAA;EAEA,MAAA,EAAQ,WAAA;AAAA"}

package/esm/contracts/result/attempt-entry.type.d.mts

@@ -0,0 +1,40 @@
+import { AIError } from "../../errors/ai-error.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/result/attempt-entry.type.d.ts
+/**
+ * One row in an executable's retry history. Captures a single
+ * attempt's timing + outcome — populated wherever retry happens:
+ *
+ * - **Workflow** — per-step retry loop (native, see `step-runner.ts`),
+ *   surfaced at `StepSnapshot.attemptHistory`.
+ * - **Agent / Tool / Supervisor** — middleware-driven retries write
+ *   here via `MiddlewareState`; the executable surfaces them at
+ *   `BaseReport.attempts` so Panoptic / cost dashboards see the
+ *   real call count, not just the surviving success.
+ *
+ * The shape is intentionally minimal — start-end-duration + status +
+ * error. Richer per-attempt forensics (input snapshot, partial output)
+ * stay out of the universal contract; consumers that need them attach
+ * via `error.context` or middleware-specific extensions.
+ *
+ * @example
+ * const entry: AttemptEntry = {
+ *   index: 1,
+ *   startedAt: "2026-05-12T09:00:00.000Z",
+ *   endedAt:   "2026-05-12T09:00:00.450Z",
+ *   duration: 450,
+ *   status: "failed",
+ *   error: new ProviderRateLimitError("429"),
+ * };
+ */
+type AttemptEntry = {
+  /** 1-based attempt index. */index: number;
+  startedAt: string;
+  endedAt: string;
+  duration: number;
+  status: "success" | "failed";
+  error?: AIError;
+};
+//#endregion
+export { AttemptEntry };
+//# sourceMappingURL=attempt-entry.type.d.mts.map

package/esm/contracts/result/attempt-entry.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt-entry.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/result/attempt-entry.type.ts"],"mappings":";;;;;AA4BA;;;;;;;;;;;;AAOiB;;;;;;;;;;;;KAPL,YAAA;+BAEV,KAAA;EACA,SAAA;EACA,OAAA;EACA,QAAA;EACA,MAAA;EACA,KAAA,GAAQ,OAAO;AAAA"}

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

@@ -0,0 +1,137 @@
+import { Usage } from "./usage.type.mjs";
+import { AttemptEntry } from "./attempt-entry.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/result/base-report.type.d.ts
+/**
+ * Wire-format version stamped on every root `BaseReport`. Bumped only
+ * when we make a BREAKING change to the report shape (field removed,
+ * required-ness flipped, semantics changed). Additive changes (new
+ * optional fields) do not bump.
+ *
+ * Panoptic and other downstream consumers branch on this to parse
+ * old stored reports with their original-shape rules.
+ *
+ * Current: **1** — initial Panoptic-readiness shape.
+ */
+declare const REPORT_SCHEMA_VERSION = 1;
+/**
+ * Discriminator for the kind of executable that produced a given
+ * {@link BaseReport}. Forms a closed union so consumers can narrow on
+ * the tree without string-matching on `name`.
+ */
+type ReportType = "tool" | "callback" | "agent" | "workflow" | "supervisor";
+/**
+ * Terminal status every executable primitive reports. Unified across
+ * tools, agents, workflows, and supervisors so dashboards and
+ * generic traversal helpers don't special-case per primitive.
+ *
+ * - `"completed"` — ran to natural end with a usable result.
+ * - `"failed"` — aborted mid-run or finished without a usable result
+ *   (crash, schema failure, max-trips, etc.). The
+ *   accompanying `error` on the envelope carries the typed cause.
+ * - `"cancelled"` — caller aborted before completion via `AbortSignal`.
+ * - `"max-iterations"` — supervisor-specific termination when the
+ *   iteration cap was hit without an explicit `END` / `satisfied`.
+ *   Harmless on non-supervisor reports; keeping it on the shared
+ *   union lets consumers write one `switch` for every status.
+ */
+type ReportStatus = "completed" | "failed" | "cancelled" | "max-iterations";
+/**
+ * Universal execution report shared by every primitive. Per-primitive
+ * report types extend this with their own domain-specific fields
+ * (agent trips, workflow steps, supervisor iteration snapshots) while
+ * keeping the root fields identical. Recursion happens through
+ * {@link BaseReport.children} — any executable this node invoked
+ * contributes its own full report here, producing a walkable tree of
+ * the entire run.
+ *
+ * **Usage rollup.** `usage` at every node equals this node's own cost
+ * plus the sum of each child's `usage`. Leaves (tools) contribute
+ * zero own-cost; composites contribute their direct LLM spend only,
+ * with children covering everything delegated.
+ *
+ * @example
+ * function totalCost(report: BaseReport): number {
+ *   return report.usage.total;
+ * }
+ *
+ * function walk(report: BaseReport, depth = 0): void {
+ *   console.log(`${"  ".repeat(depth)}${report.type} "${report.name}" — ${report.status}`);
+ *   for (const child of report.children) walk(child, depth + 1);
+ * }
+ */
+type BaseReport = {
+  /** Stable id for this execution node. Generated per `execute()`/`invoke()` call. */runId: string;
+  /**
+   * Run-id of the immediate parent execution node, when this node was
+   * invoked as part of a larger run (e.g. a tool dispatched by an
+   * agent; an agent dispatched by a supervisor; an inner primitive
+   * wrapped via `asTool()`). Absent on root nodes.
+   *
+   * Lets Panoptic and other flat-row consumers reconstruct the tree
+   * without traversing `children[]` in memory.
+   */
+  parentRunId?: string;
+  /**
+   * Run-id of the top-level execution this node belongs to. Equals
+   * `runId` on the root node, and is propagated downward to every
+   * descendant. Used to slice flat report tables back into per-run
+   * groupings.
+   */
+  rootRunId: string; /** Executable identity — the tool/agent/workflow/supervisor name. */
+  name: string;
+  /**
+   * Dev-curated version string mirrored from the primitive's config
+   * (`AgentConfig.version`, `ToolConfig.version`, etc.). Free-form —
+   * the framework neither parses nor compares it. Stored verbatim on
+   * every report so trip-archive queries can distinguish runs of
+   * "agent X v2.1" from "agent X v2.2" even when name + signature
+   * are identical.
+   *
+   * Stays `undefined` when the dev didn't declare one — never
+   * auto-defaulted.
+   */
+  version?: string;
+  /**
+   * Caller-supplied identifier that groups multiple `.execute()` calls
+   * into one conceptual user session / request. Propagated to every
+   * descendant report node so flat queries ("total spend for session
+   * X today") work without joining the tree.
+   *
+   * Threaded from `execute()` options on every primitive. Optional —
+   * absent when the caller didn't supply one.
+   */
+  sessionId?: string; /** Discriminator for the kind of executable that produced this report. */
+  type: ReportType; /** Terminal status of this execution. */
+  status: ReportStatus; /** ISO-8601 wall-clock timestamp when execution began. */
+  startedAt: string; /** ISO-8601 wall-clock timestamp when execution finished. */
+  endedAt: string; /** Monotonic duration in milliseconds — `performance.now()` delta. */
+  duration: number; /** Rolled-up usage: own cost + sum of `children[].usage`. */
+  usage: Usage;
+  /**
+   * Reports of every executable invoked by this node, in invocation
+   * order. Empty for leaves (pure tools) and for executables that
+   * didn't delegate work.
+   */
+  children: BaseReport[];
+  /**
+   * Retry history when middleware (or, for workflow steps, the engine
+   * itself) retried this node before it either succeeded or gave up.
+   * Absent when zero retries happened — keeps the common-case payload
+   * lean. The surviving (final) attempt is NOT duplicated here; its
+   * outcome is the report's own `status` / timing.
+   */
+  attempts?: AttemptEntry[];
+  /**
+   * Wire-format version of this report shape. Only present on root
+   * report nodes — implies the same version for the whole tree.
+   * Panoptic / archive consumers branch on this to parse old reports
+   * with their original-shape rules.
+   *
+   * Always equals {@link REPORT_SCHEMA_VERSION} at write time.
+   */
+  reportSchemaVersion?: number;
+};
+//#endregion
+export { BaseReport, REPORT_SCHEMA_VERSION, ReportStatus, ReportType };
+//# sourceMappingURL=base-report.type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"base-report.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/result/base-report.type.ts"],"mappings":";;;;;;AAcA;;;;AAAkC;AAOlC;;;;cAPa,qBAAA;AA6Bb;;;;AAAwB;AAAxB,KAtBY,UAAA;;;;;;;;;;;;;;;;KAsBA,YAAA;;;;;;;;;;;;;;;AA4GS;;;;;;;;;;KA9ET,UAAA;sFAEV,KAAA;;;;;;;;;;EAUA,WAAA;;;;;;;EAOA,SAAA;EAEA,IAAA;;;;;;;;;;;;EAYA,OAAA;;;;;;;;;;EAUA,SAAA;EAEA,IAAA,EAAM,UAAA;EAEN,MAAA,EAAQ,YAAA;EAER,SAAA;EAEA,OAAA;EAEA,QAAA;EAEA,KAAA,EAAO,KAAA;;;;;;EAMP,QAAA,EAAU,UAAA;;;;;;;;EAQV,QAAA,GAAW,YAAA;;;;;;;;;EASX,mBAAA;AAAA"}

package/esm/contracts/result/base-report.type.mjs

@@ -0,0 +1,17 @@
+//#region ../../@warlock.js/ai/src/contracts/result/base-report.type.ts
+/**
+* Wire-format version stamped on every root `BaseReport`. Bumped only
+* when we make a BREAKING change to the report shape (field removed,
+* required-ness flipped, semantics changed). Additive changes (new
+* optional fields) do not bump.
+*
+* Panoptic and other downstream consumers branch on this to parse
+* old stored reports with their original-shape rules.
+*
+* Current: **1** — initial Panoptic-readiness shape.
+*/
+const REPORT_SCHEMA_VERSION = 1;
+
+//#endregion
+export { REPORT_SCHEMA_VERSION };
+//# sourceMappingURL=base-report.type.mjs.map

package/esm/contracts/result/base-report.type.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-report.type.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/result/base-report.type.ts"],"sourcesContent":["import type { AttemptEntry } from \"./attempt-entry.type\";\nimport type { Usage } from \"./usage.type\";\n\n/**\n * Wire-format version stamped on every root `BaseReport`. Bumped only\n * when we make a BREAKING change to the report shape (field removed,\n * required-ness flipped, semantics changed). Additive changes (new\n * optional fields) do not bump.\n *\n * Panoptic and other downstream consumers branch on this to parse\n * old stored reports with their original-shape rules.\n *\n * Current: **1** — initial Panoptic-readiness shape.\n */\nexport const REPORT_SCHEMA_VERSION = 1;\n\n/**\n * Discriminator for the kind of executable that produced a given\n * {@link BaseReport}. Forms a closed union so consumers can narrow on\n * the tree without string-matching on `name`.\n */\nexport type ReportType =\n  | \"tool\"\n  | \"callback\"\n  | \"agent\"\n  | \"workflow\"\n  | \"supervisor\";\n\n/**\n * Terminal status every executable primitive reports. Unified across\n * tools, agents, workflows, and supervisors so dashboards and\n * generic traversal helpers don't special-case per primitive.\n *\n * - `\"completed\"` — ran to natural end with a usable result.\n * - `\"failed\"` — aborted mid-run or finished without a usable result\n *   (crash, schema failure, max-trips, etc.). The\n *   accompanying `error` on the envelope carries the typed cause.\n * - `\"cancelled\"` — caller aborted before completion via `AbortSignal`.\n * - `\"max-iterations\"` — supervisor-specific termination when the\n *   iteration cap was hit without an explicit `END` / `satisfied`.\n *   Harmless on non-supervisor reports; keeping it on the shared\n *   union lets consumers write one `switch` for every status.\n */\nexport type ReportStatus =\n  | \"completed\"\n  | \"failed\"\n  | \"cancelled\"\n  | \"max-iterations\";\n\n/**\n * Universal execution report shared by every primitive. Per-primitive\n * report types extend this with their own domain-specific fields\n * (agent trips, workflow steps, supervisor iteration snapshots) while\n * keeping the root fields identical. Recursion happens through\n * {@link BaseReport.children} — any executable this node invoked\n * contributes its own full report here, producing a walkable tree of\n * the entire run.\n *\n * **Usage rollup.** `usage` at every node equals this node's own cost\n * plus the sum of each child's `usage`. Leaves (tools) contribute\n * zero own-cost; composites contribute their direct LLM spend only,\n * with children covering everything delegated.\n *\n * @example\n * function totalCost(report: BaseReport): number {\n *   return report.usage.total;\n * }\n *\n * function walk(report: BaseReport, depth = 0): void {\n *   console.log(`${\"  \".repeat(depth)}${report.type} \"${report.name}\" — ${report.status}`);\n *   for (const child of report.children) walk(child, depth + 1);\n * }\n */\nexport type BaseReport = {\n  /** Stable id for this execution node. Generated per `execute()`/`invoke()` call. */\n  runId: string;\n  /**\n   * Run-id of the immediate parent execution node, when this node was\n   * invoked as part of a larger run (e.g. a tool dispatched by an\n   * agent; an agent dispatched by a supervisor; an inner primitive\n   * wrapped via `asTool()`). Absent on root nodes.\n   *\n   * Lets Panoptic and other flat-row consumers reconstruct the tree\n   * without traversing `children[]` in memory.\n   */\n  parentRunId?: string;\n  /**\n   * Run-id of the top-level execution this node belongs to. Equals\n   * `runId` on the root node, and is propagated downward to every\n   * descendant. Used to slice flat report tables back into per-run\n   * groupings.\n   */\n  rootRunId: string;\n  /** Executable identity — the tool/agent/workflow/supervisor name. */\n  name: string;\n  /**\n   * Dev-curated version string mirrored from the primitive's config\n   * (`AgentConfig.version`, `ToolConfig.version`, etc.). Free-form —\n   * the framework neither parses nor compares it. Stored verbatim on\n   * every report so trip-archive queries can distinguish runs of\n   * \"agent X v2.1\" from \"agent X v2.2\" even when name + signature\n   * are identical.\n   *\n   * Stays `undefined` when the dev didn't declare one — never\n   * auto-defaulted.\n   */\n  version?: string;\n  /**\n   * Caller-supplied identifier that groups multiple `.execute()` calls\n   * into one conceptual user session / request. Propagated to every\n   * descendant report node so flat queries (\"total spend for session\n   * X today\") work without joining the tree.\n   *\n   * Threaded from `execute()` options on every primitive. Optional —\n   * absent when the caller didn't supply one.\n   */\n  sessionId?: string;\n  /** Discriminator for the kind of executable that produced this report. */\n  type: ReportType;\n  /** Terminal status of this execution. */\n  status: ReportStatus;\n  /** ISO-8601 wall-clock timestamp when execution began. */\n  startedAt: string;\n  /** ISO-8601 wall-clock timestamp when execution finished. */\n  endedAt: string;\n  /** Monotonic duration in milliseconds — `performance.now()` delta. */\n  duration: number;\n  /** Rolled-up usage: own cost + sum of `children[].usage`. */\n  usage: Usage;\n  /**\n   * Reports of every executable invoked by this node, in invocation\n   * order. Empty for leaves (pure tools) and for executables that\n   * didn't delegate work.\n   */\n  children: BaseReport[];\n  /**\n   * Retry history when middleware (or, for workflow steps, the engine\n   * itself) retried this node before it either succeeded or gave up.\n   * Absent when zero retries happened — keeps the common-case payload\n   * lean. The surviving (final) attempt is NOT duplicated here; its\n   * outcome is the report's own `status` / timing.\n   */\n  attempts?: AttemptEntry[];\n  /**\n   * Wire-format version of this report shape. Only present on root\n   * report nodes — implies the same version for the whole tree.\n   * Panoptic / archive consumers branch on this to parse old reports\n   * with their original-shape rules.\n   *\n   * Always equals {@link REPORT_SCHEMA_VERSION} at write time.\n   */\n  reportSchemaVersion?: number;\n};\n"],"mappings":";;;;;;;;;;;;AAcA,MAAa,wBAAwB"}