@warlock.js/ai 4.1.1

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

@@ -0,0 +1,162 @@
+import { AIError } from "../../errors/ai-error.mjs";
+import { Usage } from "../result/usage.type.mjs";
+import { Next } from "../supervisor/next.type.mjs";
+import { IterationSnapshot } from "../supervisor/iteration-snapshot.type.mjs";
+import { SupervisorInput } from "../supervisor/supervisor-input.type.mjs";
+import { EvaluateResult } from "../supervisor/evaluate-context.type.mjs";
+import { SupervisorResult } from "../result/supervisor-result.type.mjs";
+//#region ../../@warlock.js/ai/src/contracts/events/supervisor-events.type.d.ts
+/** Fires once at the start of every `supervisor.execute()` call. */
+type SupervisorStartingPayload = {
+  supervisorName: string;
+  input: SupervisorInput;
+};
+/** Fires at the top of each iteration, before routing decides. */
+type SupervisorIterationStartingPayload = {
+  iteration: number;
+};
+/** Router mode only — emitted just before the router agent is invoked. */
+type SupervisorRouterDecidingPayload = {
+  iteration: number;
+};
+/** Emitted after the route callback or router agent resolves. */
+type SupervisorRouterDecidedPayload = {
+  iteration: number;
+  next: Next;
+  reasoning?: string;
+  durationMs: number;
+};
+/** A dispatched agent/workflow is about to start this iteration. */
+type SupervisorAgentStartingPayload = {
+  iteration: number;
+  intent: string;
+  input: string;
+};
+/**
+ * Child-agent streaming token bubbled up through the supervisor so UI
+ * consumers can render per-agent output in real time without wiring
+ * into every child agent individually.
+ */
+type SupervisorAgentStreamingPayload = {
+  iteration: number;
+  intent: string;
+  delta: string;
+};
+/** A dispatched branch completed successfully. */
+type SupervisorAgentCompletedPayload = {
+  iteration: number;
+  intent: string;
+  output: unknown;
+  usage: {
+    input: number;
+    output: number;
+    total: number;
+  };
+  duration: number;
+};
+/**
+ * A dispatched branch failed. Siblings continue — the supervisor
+ * captures the error on the branch snapshot and lets `evaluate`
+ * (or the default termination logic) decide the response.
+ */
+type SupervisorAgentFailedPayload = {
+  iteration: number;
+  intent: string;
+  error: AIError;
+};
+/**
+ * Classifier (Phase 7 / decisions §37) is about to run on iter 0.
+ * Fires once per fresh run when `SupervisorConfig.classifier` is
+ * configured.
+ */
+type SupervisorClassifierStartingPayload = {
+  iteration: 0;
+};
+/**
+ * Classifier streamed a token. Fires only when the classifier is
+ * an LLM agent AND the supervisor is being streamed at the top
+ * level. Distinct from `supervisor.agent.streaming` so UI consumers
+ * can render classifier tokens (or hide them) separately from
+ * dispatched specialist tokens.
+ */
+type SupervisorClassifierStreamingPayload = {
+  delta: string;
+};
+/**
+ * Classifier settled — `output` carries the final classifier output
+ * (post-refine if a refine hook was configured); `intent` is the
+ * dispatched intent name (absent when refine returned `END`);
+ * `refined` indicates whether the refine hook changed the output.
+ */
+type SupervisorClassifierCompletedPayload = {
+  output: {
+    intent?: string;
+    reasoning?: string;
+    confidence?: number;
+  };
+  intent?: string;
+  refined: boolean;
+  halted: boolean;
+  duration: number;
+  usage?: Usage;
+};
+/**
+ * Classifier failed (the agent / callback threw, or refine threw,
+ * or refine returned an invalid intent). Run aborts with this error
+ * surfaced on `result.error`.
+ */
+type SupervisorClassifierFailedPayload = {
+  error: AIError;
+};
+/**
+ * Receptionist agent emitted a token. Fires only when an `ackAgent`
+ * is configured AND iteration 0 is in progress. Semantically distinct
+ * from `supervisor.agent.streaming` so UIs can render ack tokens as
+ * the user-facing first reply without filtering by intent name.
+ */
+type SupervisorAckStreamingPayload = {
+  delta: string;
+};
+/**
+ * Receptionist agent settled. Fires once per run when an `ackAgent`
+ * is configured. `output` is the raw agent output (pre-strip-merge);
+ * `error` is set when the ack agent failed (run continues either way).
+ */
+type SupervisorAckCompletedPayload = {
+  output?: unknown;
+  usage?: Usage;
+  duration: number;
+  error?: AIError;
+};
+/** The `evaluate` callback returned — verdict may be `undefined`. */
+type SupervisorEvaluateVerdictPayload = {
+  iteration: number;
+  verdict: EvaluateResult;
+};
+/**
+ * An iteration settled — `snapshot` is the frozen forensic record
+ * written to history and (when `store` is set) the KV snapshot.
+ */
+type SupervisorIterationCompletedPayload = {
+  iteration: number;
+  snapshot: IterationSnapshot;
+};
+/** The run was aborted via `AbortSignal`. */
+type SupervisorCancelledPayload = {
+  cancelledAt: string;
+  reason?: string;
+};
+/** The run terminated successfully — result is the final value. */
+type SupervisorCompletedPayload<TOutput = unknown> = {
+  result: SupervisorResult<TOutput>;
+};
+/**
+ * The run terminated with a typed error surfaced on `result.error`.
+ * Cancellation emits `supervisor.cancelled` instead.
+ */
+type SupervisorErrorPayload = {
+  error: AIError;
+};
+//#endregion
+export { SupervisorAckCompletedPayload, SupervisorAckStreamingPayload, SupervisorAgentCompletedPayload, SupervisorAgentFailedPayload, SupervisorAgentStartingPayload, SupervisorAgentStreamingPayload, SupervisorCancelledPayload, SupervisorClassifierCompletedPayload, SupervisorClassifierFailedPayload, SupervisorClassifierStartingPayload, SupervisorClassifierStreamingPayload, SupervisorCompletedPayload, SupervisorErrorPayload, SupervisorEvaluateVerdictPayload, SupervisorIterationCompletedPayload, SupervisorIterationStartingPayload, SupervisorRouterDecidedPayload, SupervisorRouterDecidingPayload, SupervisorStartingPayload };
+//# sourceMappingURL=supervisor-events.type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-events.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/events/supervisor-events.type.ts"],"mappings":";;;;;;;;;KAWY,yBAAA;EACV,cAAA;EACA,KAAA,EAAO,eAAe;AAAA;;KAIZ,kCAAA;EAAuC,SAAS;AAAA;;KAGhD,+BAAA;EAAoC,SAAS;AAAA;;KAG7C,8BAAA;EACV,SAAA;EACA,IAAA,EAAM,IAAI;EACV,SAAA;EACA,UAAA;AAAA;AAV0D;AAAA,KAchD,8BAAA;EACV,SAAA;EACA,MAAA;EACA,KAAA;AAAA;AAXF;;;;;AAAA,KAmBY,+BAAA;EACV,SAAA;EACA,MAAA;EACA,KAAA;AAAA;AAlBU;AAAA,KAsBA,+BAAA;EACV,SAAA;EACA,MAAA;EACA,MAAA;EACA,KAAA;IAAS,KAAA;IAAe,MAAA;IAAgB,KAAA;EAAA;EACxC,QAAA;AAAA;;;;;;KAQU,4BAAA;EACV,SAAA;EACA,MAAA;EACA,KAAA,EAAO,OAAO;AAAA;;;;;;KAQJ,mCAAA;EAAwC,SAAS;AAAA;;;AAnBnD;AAQV;;;;KAoBY,oCAAA;EACV,KAAK;AAAA;;;AAlBS;AAQhB;;;KAmBY,oCAAA;EACV,MAAA;IAAU,MAAA;IAAiB,SAAA;IAAoB,UAAA;EAAA;EAC/C,MAAA;EACA,OAAA;EACA,MAAA;EACA,QAAA;EACA,KAAA,GAAQ,KAAK;AAAA;;;;;;KAQH,iCAAA;EACV,KAAA,EAAO,OAAO;AAAA;;;AATD;AAQf;;;KAUY,6BAAA;EACV,KAAK;AAAA;;;;AAAA;AAQP;KAAY,6BAAA;EACV,MAAA;EACA,KAAA,GAAQ,KAAA;EACR,QAAA;EACA,KAAA,GAAQ,OAAO;AAAA;;KAIL,gCAAA;EACV,SAAA;EACA,OAAA,EAAS,cAAc;AAAA;AAFzB;;;;AAAA,KASY,mCAAA;EACV,SAAA;EACA,QAAA,EAAU,iBAAiB;AAAA;AATJ;AAAA,KAab,0BAAA;EACV,WAAA;EACA,MAAM;AAAA;;KAII,0BAAA;EACV,MAAA,EAAQ,gBAAgB,CAAC,OAAA;AAAA;AAXE;AAI7B;;;AAJ6B,KAkBjB,sBAAA;EAA2B,KAAA,EAAO,OAAO;AAAA"}

package/esm/contracts/events/usage-event.type.d.mts

@@ -0,0 +1,39 @@
+import { Usage } from "../result/usage.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/events/usage-event.type.d.ts
+/**
+ * Per-trip telemetry payload for the `onUsage` agent hook (T1 of the
+ * 2026-05-08 ai-usage/runs/state/cart plan).
+ *
+ * Fired once after every LLM round-trip — including the trip that
+ * caused a tool call, the continuation trip after the tool result,
+ * and any repair trips. Cost-ledger code subscribes here to write one
+ * row per trip with stable identity (`runId` + `tripIndex`) so usage
+ * rows can be joined back to a parent `ai_runs` row written by the
+ * `onComplete` hook.
+ *
+ * Provider identity is split: `model.name` is the upstream model
+ * identifier (e.g. `gpt-4o-mini`); `model.provider` is the SDK label
+ * (`openai`, `openrouter`, `anthropic`). Both are stable across the
+ * agent run — they reflect the model the agent was constructed with.
+ *
+ * `usage.cachedTokens`, when populated, is the subset of `usage.input`
+ * served from the provider's prompt cache. Costs price it separately
+ * from full-rate input tokens.
+ *
+ * Hook handlers may be sync or async. Errors thrown inside the hook
+ * are swallowed so consumer bugs cannot crash the agent loop.
+ */
+type UsageEvent = {
+  /** Run-scoped identifier (matches `AgentResult.report.runId`). */runId: string; /** 0-indexed position of this trip within the run. */
+  tripIndex: number; /** Model identity for this trip. */
+  model: {
+    name: string;
+    provider: string;
+  }; /** Token counts for this trip. */
+  usage: Usage; /** Wall-clock timestamp the trip ended (ISO 8601 string). */
+  timestamp: string;
+};
+//#endregion
+export { UsageEvent };
+//# sourceMappingURL=usage-event.type.d.mts.map

package/esm/contracts/events/usage-event.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-event.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/events/usage-event.type.ts"],"mappings":";;;;;AAyBA;;;;;;;;;;;;;AAUW;;;;;;;;KAVC,UAAA;oEAEV,KAAA;EAEA,SAAA;EAEA,KAAA;IAAS,IAAA;IAAc,QAAA;EAAA;EAEvB,KAAA,EAAO,KAAK;EAEZ,SAAA;AAAA"}

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

@@ -0,0 +1,51 @@
+import { WorkflowResult } from "../result/workflow-result.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/events/workflow-events.type.d.ts
+type WorkflowStartingPayload = {
+  workflowName: string;
+  input: unknown;
+};
+type WorkflowStepStartingPayload = {
+  step: string;
+};
+type WorkflowStepStreamingPayload = {
+  step: string;
+  delta: string;
+};
+type WorkflowStepCompletedPayload = {
+  step: string;
+  output: unknown;
+  duration: number;
+};
+type WorkflowStepSkippedPayload = {
+  step: string;
+};
+type WorkflowStepRetryingPayload = {
+  step: string;
+  attempt: number;
+  totalAttempts: number;
+  lastError: unknown;
+};
+type WorkflowStepFailedPayload = {
+  step: string;
+  error: unknown;
+  attempts: number;
+};
+type WorkflowLoopWarningPayload = {
+  step: string;
+  enteredCount: number;
+  lastGoto: string | null;
+};
+type WorkflowCancelledPayload = {
+  cancelledAt: string;
+  reason: string;
+};
+type WorkflowCompletedPayload = {
+  result: WorkflowResult<unknown>;
+};
+type WorkflowErrorPayload = {
+  error: unknown;
+};
+//#endregion
+export { WorkflowCancelledPayload, WorkflowCompletedPayload, WorkflowErrorPayload, WorkflowLoopWarningPayload, WorkflowStartingPayload, WorkflowStepCompletedPayload, WorkflowStepFailedPayload, WorkflowStepRetryingPayload, WorkflowStepSkippedPayload, WorkflowStepStartingPayload, WorkflowStepStreamingPayload };
+//# sourceMappingURL=workflow-events.type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-events.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/events/workflow-events.type.ts"],"mappings":";;;KAEY,uBAAA;EACV,YAAA;EACA,KAAK;AAAA;AAAA,KAGK,2BAAA;EAAgC,IAAI;AAAA;AAAA,KAEpC,4BAAA;EAAiC,IAAA;EAAc,KAAK;AAAA;AAAA,KAEpD,4BAAA;EACV,IAAA;EACA,MAAA;EACA,QAAA;AAAA;AAAA,KAGU,0BAAA;EAA+B,IAAI;AAAA;AAAA,KAEnC,2BAAA;EACV,IAAA;EACA,OAAA;EACA,aAAA;EACA,SAAA;AAAA;AAAA,KAGU,yBAAA;EACV,IAAA;EACA,KAAA;EACA,QAAA;AAAA;AAAA,KAGU,0BAAA;EACV,IAAA;EACA,YAAA;EACA,QAAA;AAAA;AAAA,KAGU,wBAAA;EACV,WAAA;EACA,MAAM;AAAA;AAAA,KAGI,wBAAA;EAA6B,MAAA,EAAQ,cAAc;AAAA;AAAA,KAEnD,oBAAA;EAAyB,KAAK;AAAA"}

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

@@ -0,0 +1,25 @@
+import { BaseResult } from "./result/base-result.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/executable.contract.d.ts
+/**
+ * Shared contract for all executable AI primitives (agent, workflow, supervisor).
+ * All three implement this interface with their specific result types.
+ *
+ * @example
+ * // An agent implements ExecutableContract<string, AgentExecuteOptions, AgentResult<TOutput>>
+ * const result = await agent.execute("Summarize this document");
+ *
+ * @example
+ * // A workflow implements ExecutableContract<WorkflowInput, WorkflowOptions, WorkflowResult>
+ * const result = await workflow.execute({ topic: "AI trends" });
+ */
+interface ExecutableContract<TInput, TOptions, TResult extends BaseResult> {
+  /**
+   * Execute the primitive with the given input and options.
+   * Returns a promise that resolves to the typed result.
+   */
+  execute(input: TInput, options?: TOptions): Promise<TResult>;
+}
+//#endregion
+export { ExecutableContract };
+//# sourceMappingURL=executable.contract.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"executable.contract.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/contracts/executable.contract.ts"],"mappings":";;;;;AAcA;;;;;;;;;;UAAiB,kBAAA,mCAGC,UAAA;EADhB;;;;EAOA,OAAA,CAAQ,KAAA,EAAO,MAAA,EAAQ,OAAA,GAAU,QAAA,GAAW,OAAA,CAAQ,OAAA;AAAA"}

package/esm/contracts/finish-reason.type.d.mts

@@ -0,0 +1,17 @@
+//#region ../../@warlock.js/ai/src/contracts/finish-reason.type.d.ts
+/**
+ * Reasons the LLM stopped generating. Shared across model responses,
+ * streaming chunks, and LLM trip records.
+ *
+ * @example
+ * const reason: FinishReason = "stop";
+ *
+ * @example
+ * if (response.finishReason === "tool_calls") {
+ *   // Execute requested tools and continue the trip loop
+ * }
+ */
+type FinishReason = "stop" | "tool_calls" | "length" | "error";
+//#endregion
+export { FinishReason };
+//# sourceMappingURL=finish-reason.type.d.mts.map

package/esm/contracts/finish-reason.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finish-reason.type.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/contracts/finish-reason.type.ts"],"mappings":";;AAYA;;;;AAAwB;;;;;;;KAAZ,YAAA"}

package/esm/contracts/index.d.mts

@@ -0,0 +1,63 @@
+import { Attachment, AttachmentSource, ResolvedAttachment, StorageFileShape } from "./attachment.type.mjs";
+import { ContentPart, ImageSource } from "./content-part.type.mjs";
+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 { BaseResult } from "./result/base-result.type.mjs";
+import { AttemptEntry } from "./result/attempt-entry.type.mjs";
+import { BaseReport, REPORT_SCHEMA_VERSION, ReportStatus, ReportType } from "./result/base-report.type.mjs";
+import { FinishReason } from "./finish-reason.type.mjs";
+import { ToolCall } from "./result/tool-call.type.mjs";
+import { LLMTrip } from "./result/llm-trip.type.mjs";
+import { AgentReport, ExecutionReport, ExecutionStatus } from "./result/execution-report.type.mjs";
+import { AgentResult } from "./result/agent-result.type.mjs";
+import { AgentCompletedPayload, AgentErrorPayload, AgentStartingPayload, AgentStreamingPayload, AgentToolCalledPayload, AgentToolCallingFailedPayload, AgentToolCallingPayload, AgentTripCompletedPayload, AgentTripStartedPayload, ToolEventMeta } from "./events/agent-events.type.mjs";
+import { EventIdentity, WithoutIdentity } from "./events/event-identity.type.mjs";
+import { ExecuteResult } from "./result/execute-result.type.mjs";
+import { ExecutableContract } from "./executable.contract.mjs";
+import { StreamEvent, StreamEventBody } from "./stream/stream-event.type.mjs";
+import { StreamContract } from "./stream/stream.contract.mjs";
+import { AgentContract, AgentEventHandler } from "./agent/agent.contract.mjs";
+import { END, EndSentinel } from "./end.type.mjs";
+import { StepSnapshot } from "./result/step-result.type.mjs";
+import { WorkflowReport, WorkflowResult } from "./result/workflow-result.type.mjs";
+import { ToolConfig, ToolContext, ToolMeta, ToolMode } from "./tool.contract.mjs";
+import { NextStepResult } from "./workflow/next-step-result.type.mjs";
+import { RetryBackoff, RetryConfig } from "./workflow/retry-config.type.mjs";
+import { WorkflowContext } from "./workflow/workflow-context.type.mjs";
+import { StepAgentInput, StepDefinition, StepLocalEvents, StepOutputSpec } from "./workflow/step.contract.mjs";
+import { WorkflowDefinition, WorkflowEventHandler, WorkflowEventHandlers, WorkflowExecuteOptions, WorkflowInstance, WorkflowResumeOptions, WorkflowRunOptions } from "./workflow/workflow.contract.mjs";
+import { Placeholders } from "./placeholders.type.mjs";
+import { InstructionContract, PersonaContract, SystemPromptBlockContract, SystemPromptContract } from "./system-prompt.contract.mjs";
+import { Next } from "./supervisor/next.type.mjs";
+import { AckSnapshot, AgentBranchSnapshot, DecisionSource, IterationDecision, IterationSnapshot } from "./supervisor/iteration-snapshot.type.mjs";
+import { SupervisorInput } from "./supervisor/supervisor-input.type.mjs";
+import { EvaluateBranchResult, EvaluateContext, EvaluateResult } from "./supervisor/evaluate-context.type.mjs";
+import { RouteContext } from "./supervisor/route-context.type.mjs";
+import { AckCallback, AckConfig, AckEntry, AckRunEntry } from "./supervisor/ack-entry.type.mjs";
+import { DispatchRawResult, IntentCallback, IntentEntry, IntentRunEntry, SupervisorIntentValue } from "./supervisor/intent-entry.type.mjs";
+import { RouterEntry } from "./supervisor/router-entry.type.mjs";
+import { SupervisorConfig, SupervisorEventHandler, SupervisorEventHandlers } from "./supervisor/supervisor-config.type.mjs";
+import { SupervisorExecuteOptions, SupervisorResumeOptions } from "./supervisor/supervisor-execute-options.type.mjs";
+import { SupervisorStreamEvent } from "./supervisor/supervisor-stream-event.type.mjs";
+import { SupervisorAsToolOptions, SupervisorContract } from "./supervisor/supervisor.contract.mjs";
+import { DispatchContext, IntentRunner, IntentRunnerMap } from "./supervisor/dispatch-context.type.mjs";
+import { ClassifierAgentEntry, ClassifierCallback, ClassifierConfig, ClassifierContext, ClassifierOutput, ClassifierRefineContext, ClassifierRefineResult, ClassifierRunEntry, ClassifierSnapshot } from "./supervisor/classifier-context.type.mjs";
+import { SupervisorReport, SupervisorResult, SupervisorTerminatedBy } from "./result/supervisor-result.type.mjs";
+import { SessionSendResult } from "./result/session-send-result.type.mjs";
+import { SupervisorSnapshot, SupervisorSnapshotStatus } from "./supervisor/supervisor-snapshot.type.mjs";
+import { SupervisorAgentCompletedPayload, SupervisorAgentFailedPayload, SupervisorAgentStartingPayload, SupervisorAgentStreamingPayload, SupervisorCancelledPayload, SupervisorCompletedPayload, SupervisorErrorPayload, SupervisorEvaluateVerdictPayload, SupervisorIterationCompletedPayload, SupervisorIterationStartingPayload, SupervisorRouterDecidedPayload, SupervisorRouterDecidingPayload, SupervisorStartingPayload } from "./events/supervisor-events.type.mjs";
+import { WorkflowCancelledPayload, WorkflowCompletedPayload, WorkflowErrorPayload, WorkflowLoopWarningPayload, WorkflowStartingPayload, WorkflowStepCompletedPayload, WorkflowStepFailedPayload, WorkflowStepRetryingPayload, WorkflowStepSkippedPayload, WorkflowStepStartingPayload, WorkflowStepStreamingPayload } from "./events/workflow-events.type.mjs";
+import { AgentEventMap, SupervisorEventMap, WorkflowEventMap } from "./events/event-map.type.mjs";
+import { StreamingToolGuardConfig } from "./streaming-tool-guard-config.type.mjs";
+import { AgentExecuteOptions } from "./agent/agent-options.type.mjs";
+import { EmbedderConfig, EmbedderContract, EmbeddingBatchResult, EmbeddingResult, EmbeddingUsage } from "./embedder.contract.mjs";
+import { MiddlewareState } from "./middleware/middleware-state.type.mjs";
+import { MiddlewareAgentRef, MiddlewareExecuteContext, MiddlewareModelRef, MiddlewareToolContext, MiddlewareTripContext } from "./middleware/middleware-context.type.mjs";
+import { ModelCallOptions, ModelCapabilities, ModelContract, ModelResponse, ModelStreamChunk } from "./model.contract.mjs";
+import { AgentMiddleware, AgentMiddlewareExecuteHooks, AgentMiddlewareToolHooks, AgentMiddlewareTripHooks } from "./middleware/middleware.contract.mjs";
+import { ModelConfig, SDKAdapterContract } from "./sdk-adapter.contract.mjs";
+import { WorkflowSnapshot } from "./workflow/workflow-snapshot.type.mjs";
+import { CompleteEvent } from "./events/complete-event.type.mjs";
+import { UsageEvent } from "./events/usage-event.type.mjs";

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

@@ -0,0 +1,3 @@
+import { MiddlewareState } from "./middleware-state.type.mjs";
+import { MiddlewareAgentRef, MiddlewareExecuteContext, MiddlewareModelRef, MiddlewareToolContext, MiddlewareTripContext } from "./middleware-context.type.mjs";
+import { AgentMiddleware, AgentMiddlewareExecuteHooks, AgentMiddlewareToolHooks, AgentMiddlewareTripHooks } from "./middleware.contract.mjs";

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

@@ -0,0 +1,99 @@
+import { ModelToolCallRequest } from "../model-tool-call-request.type.mjs";
+import { Message } from "../conversation-message.type.mjs";
+import { ToolMode } from "../tool.contract.mjs";
+import { AgentExecuteOptions } from "../agent/agent-options.type.mjs";
+import { MiddlewareState } from "./middleware-state.type.mjs";
+
+//#region ../../@warlock.js/ai/src/contracts/middleware/middleware-context.type.d.ts
+/**
+ * Minimal identity shape of the agent the middleware is wrapping.
+ * Middleware never mutates the agent itself, so it sees only the
+ * fields it can usefully branch on — name (for logs, per-agent
+ * allow-lists) and whether the name was auto-synthesized.
+ */
+type MiddlewareAgentRef = {
+  readonly name: string;
+  readonly isAnonymous: boolean;
+};
+/**
+ * Minimal identity shape of the model the agent is wrapping.
+ * Surface just enough for middleware to branch on (budget uses
+ * provider/model to look up pricing, semantic cache uses model name
+ * in its namespace key). Never includes the live adapter instance.
+ */
+type MiddlewareModelRef = {
+  readonly name: string;
+  readonly provider?: string;
+};
+/**
+ * Context passed to the outermost (`execute`) middleware phase —
+ * fires once around the entire `agent.execute()` call.
+ *
+ * **Role.** Gives middleware the stable identity of the run (agent,
+ * input, options) and the shared-state bag all downstream hooks will
+ * see. Anything cumulative-across-trips lives here: total token
+ * count, wall-clock budget, per-session rate limit counters.
+ *
+ * All fields are `readonly` — middleware reads them freely but does
+ * not reassign. State mutations go through `ctx.state` so there is
+ * exactly one mutable surface and it is explicit at the call site.
+ */
+type MiddlewareExecuteContext = {
+  readonly agent: MiddlewareAgentRef;
+  readonly model: MiddlewareModelRef;
+  readonly input: string;
+  readonly options: AgentExecuteOptions<unknown> | undefined;
+  readonly state: MiddlewareState;
+  readonly signal?: AbortSignal;
+};
+/**
+ * Context passed to per-LLM-trip middleware hooks — fires once per
+ * round trip the agent makes to the model.
+ *
+ * **Role.** Lets middleware intercept individual model calls:
+ * guardrails inspect the outbound `messages` / inbound response,
+ * semantic cache short-circuits a trip entirely by returning a
+ * synthetic `ModelResponse` from `trip.before`.
+ *
+ * Extends `MiddlewareExecuteContext` so anything a `before(execute)`
+ * hook stashed in `state` is still visible here — the whole point of
+ * threading one `state` reference through all levels.
+ */
+type MiddlewareTripContext = MiddlewareExecuteContext & {
+  readonly tripIndex: number;
+  readonly messages: ReadonlyArray<Message>;
+};
+/**
+ * Context passed to per-tool-call middleware hooks — fires once per
+ * tool the model asks the agent to invoke.
+ *
+ * **Role.** Lets middleware wrap individual tool dispatches:
+ * rate-limit a specific tool, validate inputs beyond the schema,
+ * short-circuit with a cached tool response. Exposes the originating
+ * `ModelToolCallRequest` so middleware can log/inspect the exact
+ * args the model produced.
+ *
+ * Extends `MiddlewareTripContext` so tool hooks can branch on the
+ * surrounding trip context when useful (e.g. "skip rate-limit on
+ * repair trips").
+ */
+type MiddlewareToolContext = MiddlewareTripContext & {
+  readonly tool: {
+    readonly name: string;
+    readonly description?: string;
+    /**
+     * Result-feedback mode of the tool being dispatched. `"feedback"`
+     * (default) for standard round-trip tools; `"silent"` for
+     * fire-and-forget side-effect tools whose result is not fed back
+     * to the model. Exposed so middleware (cost accounting, logging,
+     * telemetry) can branch on tool semantics — e.g. skip the
+     * post-tool-call usage projection for silent terminal trips since
+     * the loop ends there.
+     */
+    readonly mode?: ToolMode;
+  };
+  readonly request: ModelToolCallRequest;
+};
+//#endregion
+export { MiddlewareAgentRef, MiddlewareExecuteContext, MiddlewareModelRef, MiddlewareToolContext, MiddlewareTripContext };
+//# sourceMappingURL=middleware-context.type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"middleware-context.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/middleware/middleware-context.type.ts"],"mappings":";;;;;;;;;AAYA;;;;KAAY,kBAAA;EAAA,SACD,IAAA;EAAA,SACA,WAAW;AAAA;;AAWH;AAgBnB;;;;KAlBY,kBAAA;EAAA,SACD,IAAA;EAAA,SACA,QAAQ;AAAA;;;;;;;;;;;;;;KAgBP,wBAAA;EAAA,SACD,KAAA,EAAO,kBAAA;EAAA,SACP,KAAA,EAAO,kBAAA;EAAA,SACP,KAAA;EAAA,SACA,OAAA,EAAS,mBAAA;EAAA,SACT,KAAA,EAAO,eAAA;EAAA,SACP,MAAA,GAAS,WAAA;AAAA;;;;;;;;;AAkBsB;AAiB1C;;;;KAnBY,qBAAA,GAAwB,wBAAA;EAAA,SACzB,SAAA;EAAA,SACA,QAAA,EAAU,aAAA,CAAc,OAAA;AAAA;;;;;;;;;;AAgCK;;;;;KAf5B,qBAAA,GAAwB,qBAAA;EAAA,SACzB,IAAA;IAAA,SACE,IAAA;IAAA,SACA,WAAA;;;;;;;;;;aAUA,IAAA,GAAO,QAAA;EAAA;EAAA,SAET,OAAA,EAAS,oBAAA;AAAA"}

package/esm/contracts/middleware/middleware-state.type.d.mts

@@ -0,0 +1,34 @@
+//#region ../../@warlock.js/ai/src/contracts/middleware/middleware-state.type.d.ts
+/**
+ * Per-execution shared-state bag threaded through every middleware
+ * hook of every level (`execute`, `trip`, `tool`) for a single
+ * `agent.execute()` call.
+ *
+ * **Role.** Lets a single middleware accumulate state across hooks
+ * and across levels without relying on closure capture (which would
+ * leak between concurrent `execute()` calls on the same agent). Each
+ * middleware namespaces its reads/writes by its own `name` — the
+ * pipeline never inspects values.
+ *
+ * A fresh `Map` is constructed at `execute.before`-time and the same
+ * reference flows through every nested `trip` and `tool` hook, then
+ * is discarded at `execute.after` / `execute.onError`. Two concurrent
+ * executions of the same agent therefore get isolated bags.
+ *
+ * @example
+ * // Inside a budget middleware:
+ * execute: {
+ *   before(ctx) { ctx.state.set("budget.tokensUsed", 0); },
+ * },
+ * trip: {
+ *   after(ctx, response) {
+ *     const used = (ctx.state.get("budget.tokensUsed") as number) + response.usage.total;
+ *     ctx.state.set("budget.tokensUsed", used);
+ *     if (used > max) throw new BudgetExceededError(...);
+ *   },
+ * },
+ */
+type MiddlewareState = Map<string, unknown>;
+//#endregion
+export { MiddlewareState };
+//# sourceMappingURL=middleware-state.type.d.mts.map

package/esm/contracts/middleware/middleware-state.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware-state.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/middleware/middleware-state.type.ts"],"mappings":";;AA6BA;;;;AAAiC;;;;;;;;;;;;;;;;;;;;;;;;KAArB,eAAA,GAAkB,GAAG"}