@warlock.js/ai 4.2.11 → 4.3.0

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

@@ -0,0 +1,65 @@
+import { AIErrorCode } from "../errors/error-code.type.mjs";
+import { ModelContract } from "./model.contract.mjs";
+
+//#region ../@warlock.js/ai/src/contracts/fallback-model.contract.d.ts
+/**
+ * Predicate deciding whether a thrown error should advance the fallback
+ * chain to the next model. Receives the original error verbatim (an
+ * `AIError` subclass when the failure came from a provider adapter, or
+ * any thrown value otherwise) and returns `true` to fall over, `false`
+ * to re-throw immediately.
+ *
+ * @example
+ * fallbackModel([primary, backup], {
+ *   retryOn: (error) => error instanceof ProviderError,
+ * });
+ */
+type FallbackRetryPredicate = (error: unknown) => boolean;
+/**
+ * Tuning knobs for {@link fallbackModel}. Both forms of `retryOn` are
+ * additive over the built-in transient-failure default (rate-limit,
+ * timeout, and generic 5xx provider errors); omit it entirely to use
+ * that default unchanged.
+ */
+type FallbackModelOptions = {
+  /**
+   * Which failures advance the chain. Either an explicit allow-list of
+   * stable {@link AIErrorCode} strings, or a predicate for arbitrary
+   * branching. Absent = the built-in transient set
+   * (`PROVIDER_RATE_LIMIT`, `PROVIDER_TIMEOUT`, `PROVIDER_ERROR`).
+   *
+   * Non-transient failures (auth, invalid-request, context-length,
+   * content-filter) are NEVER retried by default — falling over on a
+   * bad API key or an oversized prompt only burns the budget on every
+   * downstream model, since the same input fails identically.
+   */
+  retryOn?: AIErrorCode[] | FallbackRetryPredicate;
+};
+/**
+ * Diagnostic record of one model that the fallback chain tried and that
+ * failed with a chain-advancing error. Exposed on the wrapper's
+ * `lastAttempts` getter so callers can see exactly which providers were
+ * burned before the chain produced a response (or re-threw the final
+ * error).
+ */
+type FallbackAttempt = {
+  /** Model identifier that failed (`ModelContract.name`). */modelName: string; /** Provider the failed model belonged to (`ModelContract.provider`). */
+  provider: string; /** The error that triggered the fall-over to the next model. */
+  error: unknown;
+};
+/**
+ * The `ModelContract` returned by `fallbackModel()`: a fully usable
+ * model that additionally exposes which wrapped models failed (and why)
+ * during the most recent call.
+ */
+interface FallbackModelContract extends ModelContract {
+  /**
+   * Models that failed with a chain-advancing error during the most
+   * recent `complete()` / `stream()` call, in attempt order. Empty when
+   * the primary model succeeded outright. Overwritten on each call.
+   */
+  readonly lastAttempts: FallbackAttempt[];
+}
+//#endregion
+export { FallbackAttempt, FallbackModelContract, FallbackModelOptions, FallbackRetryPredicate };
+//# sourceMappingURL=fallback-model.contract.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fallback-model.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/contracts/fallback-model.contract.ts"],"mappings":";;;;;;AAeA;;;;AAAoD;AAQpD;;;;;KARY,sBAAA,IAA0B,KAAc;;;AAoBF;AAUlD;;;KAtBY,oBAAA;EAwBV;;;;AAIK;AAQP;;;;;;EAxBE,OAAA,GAAU,WAAA,KAAgB,sBAAsB;AAAA;AA8BV;;;;;;;AAAA,KApB5B,eAAA;6DAEV,SAAA;EAEA,QAAA;EAEA,KAAA;AAAA;;;;;;UAQe,qBAAA,SAA8B,aAAa;;;;;;WAMjD,YAAA,EAAc,eAAA;AAAA"}

package/esm/contracts/index.d.mts

@@ -18,46 +18,66 @@ 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 { EvalCase, EvalCaseResult, EvalJudge, EvalOptions, EvalReport, EvalScore, EvalScorer, EvalScorerContext } from "./agent/eval.type.mjs";
 import { AgentContract, AgentEventHandler } from "./agent/agent.contract.mjs";
 import { END, EndSentinel } from "./end.type.mjs";
+import { SupervisorReport, SupervisorResult, SupervisorTerminatedBy } from "./result/supervisor-result.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 { SupervisorInput } from "./supervisor/supervisor-input.type.mjs";
+import { SupervisorSnapshot, SupervisorSnapshotStatus } from "./supervisor/supervisor-snapshot.type.mjs";
+import { PgClientLike, RedisClientLike, SnapshotStore } from "./orchestrator/snapshot-store.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 { WorkflowSnapshot } from "./workflow/workflow-snapshot.type.mjs";
 import { WorkflowDefinition, WorkflowEventHandler, WorkflowEventHandlers, WorkflowExecuteOptions, WorkflowInstance, WorkflowResumeOptions, WorkflowRunOptions } from "./workflow/workflow.contract.mjs";
+import { ModelCallOptions, ModelCapabilities, ModelContract, ModelResponse, ModelStreamChunk, ReasoningEffort } from "./model.contract.mjs";
+import { SupervisorExecuteOptions, SupervisorResumeOptions } from "./supervisor/supervisor-execute-options.type.mjs";
+import { MiddlewareState } from "./middleware/middleware-state.type.mjs";
+import { MiddlewareAgentRef, MiddlewareExecuteContext, MiddlewareModelRef, MiddlewareSupervisorContext, MiddlewareSupervisorRef, MiddlewareToolContext, MiddlewareTripContext } from "./middleware/middleware-context.type.mjs";
+import { AgentMiddleware, AgentMiddlewareExecuteHooks, AgentMiddlewareSupervisorHooks, AgentMiddlewareToolHooks, AgentMiddlewareTripHooks } from "./middleware/middleware.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 { Next } from "./supervisor/next.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 { EvaluateBranchResult, EvaluateContext, EvaluateResult } from "./supervisor/evaluate-context.type.mjs";
+import { AckSnapshot, AgentBranchSnapshot, DecisionSource, IterationDecision, IterationSnapshot } from "./supervisor/iteration-snapshot.type.mjs";
+import { CompactionResult, OrchestratorAwaitingStatus, OrchestratorReport, OrchestratorReportStatus, OrchestratorReportType, OrchestratorResult, TurnSnapshot } from "./result/orchestrator-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 { MemoryItem, MemoryTier, RecalledMemory } from "./memory/memory-item.type.mjs";
+import { RecallOptions } from "./memory/recall-options.type.mjs";
+import { MemoryContract } from "./memory/memory.contract.mjs";
+import { MemoryConfig, SemanticMemoryConfig } from "./memory/memory-config.type.mjs";
+import { CheckpointRecord, CheckpointStore } from "./orchestrator/checkpoint-store.contract.mjs";
+import { OrchestratorCommands } from "./orchestrator/orchestrator-commands.type.mjs";
+import { OrchestratorEvent, OrchestratorEventHandler, OrchestratorEventHandlers, OrchestratorEventMap, OrchestratorEventName } from "./orchestrator/orchestrator-event.type.mjs";
+import { OrchestratorExecuteOptions, OrchestratorResumeOptions } from "./orchestrator/orchestrator-execute-options.type.mjs";
+import { OrchestratorAsToolOptions, OrchestratorContract, OrchestratorSessionScope, SessionContextOverrides } from "./orchestrator/orchestrator.contract.mjs";
+import { OrchestratorConfig, OrchestratorMemoryConfig, SummarizeCallback, SummarizeConfig } from "./orchestrator/orchestrator-config.type.mjs";
+import { SessionContract } from "./orchestrator/session.contract.mjs";
+import { PlannerCapability } from "./planner/planner-capability.type.mjs";
+import { PlannerConfig } from "./planner/planner-config.type.mjs";
+import { PlannerExecuteOptions } from "./planner/planner-execute-options.type.mjs";
+import { PlannerPlan, PlannerStep } from "./planner/planner-plan.type.mjs";
+import { PlannerReport, PlannerReportType, PlannerResult, PlannerStepSnapshot } from "./planner/planner-result.type.mjs";
+import { PlannerContract } from "./planner/planner.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/memory/index.d.mts

@@ -0,0 +1,4 @@
+import { MemoryItem, MemoryTier, RecalledMemory } from "./memory-item.type.mjs";
+import { RecallOptions } from "./recall-options.type.mjs";
+import { MemoryContract } from "./memory.contract.mjs";
+import { MemoryConfig, SemanticMemoryConfig } from "./memory-config.type.mjs";

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

@@ -0,0 +1,150 @@
+import { EmbedderContract } from "../embedder.contract.mjs";
+import { MemoryTier } from "./memory-item.type.mjs";
+import { CacheDriver } from "@warlock.js/cache";
+
+//#region ../@warlock.js/ai/src/contracts/memory/memory-config.type.d.ts
+/**
+ * Semantic-tier wiring for `memory(config)`.
+ *
+ * Mirrors the `semanticCache` middleware's delegation model: memory does
+ * NOT implement similarity search itself — it stores embeddings in a
+ * `@warlock.js/cache` driver and retrieves them via the driver's native
+ * `.similar()`. Supply the embedder that turns text into vectors and the
+ * store that indexes them.
+ *
+ * Dev / test environments pass `new MemoryCacheDriver()` (zero config,
+ * O(N) scan). Production picks a driver with a real ANN index — `pg`
+ * with pgvector, `redis` with RediSearch. Drivers without similarity
+ * support throw `CacheUnsupportedError` from `set({ vector })` /
+ * `similar()`.
+ */
+type SemanticMemoryConfig = {
+  /** Embedder used to vectorize remembered text and recall queries. */embedder: EmbedderContract;
+  /**
+   * Vector-capable cache driver from `@warlock.js/cache`. Falls back to
+   * `ai.config({ defaultStore })` when omitted; the factory throws at
+   * construction when neither is available.
+   */
+  store?: CacheDriver<any, any>;
+  /**
+   * Namespace prefix applied to every key the semantic tier writes. Lets
+   * multiple memory instances share one driver without collision.
+   * Default `"ai.memory"`.
+   */
+  namespace?: string;
+};
+/**
+ * Episodic-tier wiring for `memory(config)`.
+ *
+ * Like the semantic tier, episodic memory is embedder-backed and stores
+ * its vectors in a `@warlock.js/cache` driver — it adds a per-entry
+ * timestamp and blends **recency** into the recall score so recent
+ * episodes outrank stale ones at equal similarity.
+ */
+type EpisodicMemoryConfig = {
+  /** Embedder used to vectorize remembered episodes and recall queries. */embedder: EmbedderContract;
+  /**
+   * Vector-capable cache driver. Falls back to `ai.config({ defaultStore })`
+   * when omitted; the factory throws at construction when neither exists.
+   */
+  store?: CacheDriver<any, any>;
+  /**
+   * Namespace prefix for every key this tier writes. Default
+   * `"ai.memory.episodic"`. Keep distinct from sibling tiers when sharing
+   * one driver.
+   */
+  namespace?: string;
+  /**
+   * How much recency counts versus similarity in the blended score, in
+   * `[0, 1]`. `0` = pure similarity (semantic-style); higher favors
+   * recent episodes. Default `0.3`.
+   */
+  recencyWeight?: number;
+  /**
+   * Age at which an episode's recency contribution halves, in
+   * milliseconds. Default 7 days. Larger = slower decay.
+   */
+  halfLifeMs?: number;
+  /**
+   * Clock used to stamp + age episodes. Defaults to `Date.now`. Override
+   * for deterministic tests or replay.
+   */
+  now?: () => number;
+};
+/**
+ * Procedural-tier wiring for `memory(config)`.
+ *
+ * Embedder-backed like the semantic tier, but blends **reinforcement**
+ * into the recall score: re-remembering a procedure increments its use
+ * count, so well-worn procedures outrank one-offs at equal similarity.
+ */
+type ProceduralMemoryConfig = {
+  /** Embedder used to vectorize remembered procedures and recall queries. */embedder: EmbedderContract;
+  /**
+   * Vector-capable cache driver. Falls back to `ai.config({ defaultStore })`
+   * when omitted; the factory throws at construction when neither exists.
+   */
+  store?: CacheDriver<any, any>;
+  /**
+   * Namespace prefix for every key this tier writes. Default
+   * `"ai.memory.procedural"`. Keep distinct from sibling tiers when
+   * sharing one driver.
+   */
+  namespace?: string;
+  /**
+   * How much reinforcement counts versus similarity in the blended score,
+   * in `[0, 1]`. `0` = pure similarity; higher favors well-used
+   * procedures. Default `0.3`.
+   */
+  reinforcementWeight?: number;
+};
+/**
+ * Configuration for the `memory(config)` factory.
+ *
+ * At least one tier must be enabled. The working tier is on by default
+ * (`working: true`); the semantic, episodic, and procedural tiers each
+ * activate only when their config is supplied. Enabling neither is a
+ * construction-time error — a memory with no tiers can't store or recall
+ * anything.
+ */
+type MemoryConfig = {
+  /** Stable identifier — used in logs and as the working-tier scope key. */name?: string;
+  /**
+   * Enable the in-run working tier. Default `true`. Set `false` to build
+   * a semantic-only memory.
+   */
+  working?: boolean;
+  /**
+   * Enable + wire the semantic recall tier. Omit for a working-only
+   * memory.
+   */
+  semantic?: SemanticMemoryConfig;
+  /**
+   * Enable + wire the episodic tier — durable, recency-blended recall of
+   * timestamped events. Omit to leave it off.
+   */
+  episodic?: EpisodicMemoryConfig;
+  /**
+   * Enable + wire the procedural tier — durable, reinforcement-blended
+   * recall of learned how-tos. Omit to leave it off.
+   */
+  procedural?: ProceduralMemoryConfig;
+  /**
+   * Tier a `remember(...)` item lands in when it doesn't name its own
+   * `tier`. Default `"working"`. Must reference an enabled tier.
+   */
+  defaultTier?: MemoryTier;
+  /**
+   * Default number of memories `recall(...)` returns when the call
+   * doesn't override `k`. Default `5`.
+   */
+  k?: number;
+  /**
+   * Default minimum semantic similarity for a recall hit, in `[0, 1]`.
+   * Default `0.7`. Ignored by the working tier.
+   */
+  threshold?: number;
+};
+//#endregion
+export { EpisodicMemoryConfig, MemoryConfig, ProceduralMemoryConfig, SemanticMemoryConfig };
+//# sourceMappingURL=memory-config.type.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory-config.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/memory/memory-config.type.ts"],"mappings":";;;;;;;AAmBA;;;;;;;;;;AAcW;AAWX;;KAzBY,oBAAA;EAgCS,qEA9BnB,QAAA,EAAU,gBAAA;EAyBA;;;;;EAnBV,KAAA,GAAQ,WAAW;EA8CnB;;AAAG;AAUL;;EAlDE,SAAA;AAAA;;;;;;;;AAqEmB;KA1DT,oBAAA;EAsEY,yEApEtB,QAAA,EAAU,gBAAA;EAgFC;;;;EA3EX,KAAA,GAAQ,WAAW;EA0FK;;;;;EApFxB,SAAA;EA0EW;;;;;EApEX,aAAA;EAwFA;;AAAS;;EAnFT,UAAA;;;;;EAKA,GAAA;AAAA;;;;;;;;KAUU,sBAAA;6EAEV,QAAA,EAAU,gBAAA;;;;;EAKV,KAAA,GAAQ,WAAW;;;;;;EAMnB,SAAA;;;;;;EAMA,mBAAA;AAAA;;;;;;;;;;KAYU,YAAA;4EAEV,IAAA;;;;;EAKA,OAAA;;;;;EAKA,QAAA,GAAW,oBAAA;;;;;EAKX,QAAA,GAAW,oBAAA;;;;;EAKX,UAAA,GAAa,sBAAA;;;;;EAKb,WAAA,GAAc,UAAA;;;;;EAKd,CAAA;;;;;EAKA,SAAA;AAAA"}

package/esm/contracts/memory/memory-item.type.d.mts

@@ -0,0 +1,64 @@
+//#region ../@warlock.js/ai/src/contracts/memory/memory-item.type.d.ts
+/**
+ * The four memory tiers shipped in 4.3.0.
+ *
+ * - `"working"` — in-run scratch the orchestrator threads across turns.
+ *   Volatile, unscored, retrieved in insertion order (recency proxy).
+ * - `"semantic"` — durable *facts*, stored as embeddings in a
+ *   `@warlock.js/cache` driver, retrieved by cosine similarity.
+ * - `"episodic"` — durable *events*: a timestamped log retrieved by
+ *   similarity **blended with recency**, so recent episodes outrank stale
+ *   ones at equal relevance.
+ * - `"procedural"` — durable *how-tos*: learned procedures retrieved by
+ *   similarity **blended with reinforcement**, so a procedure remembered
+ *   (re-affirmed) more often outranks a one-off at equal relevance.
+ *
+ * `working` + `semantic` need no extra wiring (semantic needs an embedder
+ * + store); `episodic` and `procedural` are embedder-backed like
+ * semantic. Decay / forgetting (TTL-based relevance falloff, eviction)
+ * remains DEFERRED. The union widened from the v1 `working | semantic`
+ * pair to add the two new tiers — a non-breaking change, since every
+ * prior value is still valid.
+ */
+type MemoryTier = "working" | "semantic" | "episodic" | "procedural";
+/**
+ * A single unit a caller hands to `memory.remember(...)`.
+ *
+ * `text` is the only required field — it is what gets embedded for the
+ * semantic tier and what is surfaced back on recall. `tier` selects the
+ * destination; omit it to fall back to the factory's `defaultTier`.
+ *
+ * `id` lets a caller address an entry for later overwrite / dedup. When
+ * absent the factory derives a stable id from the text so re-remembering
+ * identical text updates in place rather than duplicating.
+ *
+ * `metadata` is an opaque bag round-tripped verbatim onto the recalled
+ * memory — use it for source ids, timestamps, tags, or anything the
+ * consumer wants back alongside the text.
+ */
+type MemoryItem = {
+  /** Natural-language content. Embedded for semantic recall; surfaced verbatim on retrieval. */text: string; /** Destination tier. Defaults to the factory's `defaultTier` when omitted. */
+  tier?: MemoryTier; /** Caller-owned identifier for overwrite / dedup. Derived from `text` when omitted. */
+  id?: string; /** Opaque metadata round-tripped onto the recalled memory unchanged. */
+  metadata?: Record<string, unknown>;
+};
+/**
+ * A memory returned from `memory.recall(...)`, carrying the relevance
+ * `score` the retrieval assigned it.
+ *
+ * `score` is in `[0, 1]` for every tier so a consumer can sort a mixed
+ * recall set on one field without special-casing the tier: cosine
+ * similarity for `semantic`, a recency proxy for `working` (most-recent =
+ * 1), similarity blended with recency for `episodic`, and similarity
+ * blended with reinforcement for `procedural`.
+ */
+type RecalledMemory = {
+  /** Stable id of the stored memory. */id: string; /** The remembered text, surfaced for injection into context. */
+  text: string; /** Which tier produced this hit. */
+  tier: MemoryTier; /** Relevance in `[0, 1]` — cosine similarity (semantic) or recency proxy (working). */
+  score: number; /** Opaque metadata stored alongside the memory, returned verbatim. */
+  metadata?: Record<string, unknown>;
+};
+//#endregion
+export { MemoryItem, MemoryTier, RecalledMemory };
+//# sourceMappingURL=memory-item.type.d.mts.map

package/esm/contracts/memory/memory-item.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-item.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/memory/memory-item.type.ts"],"mappings":";;AAqBA;;;;AAAsB;AAiBtB;;;;;;;;;;;AAQmB;AAanB;;;KAtCY,UAAA;;;;;;;;;AAgDO;;;;;;;KA/BP,UAAA;gGAEV,IAAA;EAEA,IAAA,GAAO,UAAA;EAEP,EAAA;EAEA,QAAA,GAAW,MAAM;AAAA;;;;;;;;;;;KAaP,cAAA;wCAEV,EAAA;EAEA,IAAA;EAEA,IAAA,EAAM,UAAA;EAEN,KAAA;EAEA,QAAA,GAAW,MAAM;AAAA"}

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

@@ -0,0 +1,87 @@
+import { MemoryItem, MemoryTier, RecalledMemory } from "./memory-item.type.mjs";
+import { RecallOptions } from "./recall-options.type.mjs";
+
+//#region ../@warlock.js/ai/src/contracts/memory/memory.contract.d.ts
+/**
+ * Provider-neutral contract for an agent memory store (memory core M1).
+ *
+ * **Role.** A single store that holds and retrieves what an agent /
+ * orchestrator should remember across turns. Four tiers ship in 4.3.0:
+ *
+ * - **working** — in-run scratch the orchestrator threads across turns
+ *   of one session. Volatile, unscored, recalled in insertion order.
+ * - **semantic** — durable *facts* stored as embeddings in a
+ *   `@warlock.js/cache` driver, retrieved by cosine similarity via the
+ *   driver's `.similar()` (the same delegation the `semanticCache`
+ *   middleware uses).
+ * - **episodic** — durable *events*: a timestamped log retrieved by
+ *   similarity blended with recency, so recent episodes outrank stale
+ *   ones at equal relevance.
+ * - **procedural** — durable *how-tos*: learned procedures retrieved by
+ *   similarity blended with reinforcement, so a procedure re-affirmed
+ *   more often outranks a one-off.
+ *
+ * `recall()` returns {@link RecalledMemory}[] — scored entries the
+ * caller injects into the model context (system prefix, a synthesized
+ * "what you remember" block, etc.). Memory never mutates the prompt
+ * itself; surfacing the recalled text is the consumer's call so the
+ * injection point stays explicit.
+ *
+ * **Still deferred.** Decay / forgetting (TTL-based relevance falloff,
+ * eviction policies) is not yet implemented; the four tiers above are the
+ * full 4.3.0 surface. The `episodic` and `procedural` tiers were added in
+ * 4.3.0 as a non-breaking widening of the {@link MemoryTier} union.
+ *
+ * Front it with the `memory(config)` factory — callers never `new` an
+ * implementation.
+ *
+ * @example
+ * import { ai } from "@warlock.js/ai";
+ * import { MemoryCacheDriver } from "@warlock.js/cache";
+ *
+ * const store = new MemoryCacheDriver();
+ * store.setOptions({});
+ *
+ * const mem = ai.memory({
+ *   semantic: {
+ *     embedder: openai.embedder({ name: "text-embedding-3-small" }),
+ *     store,
+ *   },
+ * });
+ *
+ * await mem.remember({ text: "User prefers metric units.", tier: "semantic" });
+ * const hits = await mem.recall("which units does the user like?", { k: 3 });
+ */
+interface MemoryContract {
+  /** Stable identifier — surfaced in logs and used as the working-tier scope key. */
+  readonly name: string;
+  /**
+   * Store one or more memories. Each item lands in its own `tier` (or
+   * the factory's `defaultTier` when unset). Items addressed to the
+   * semantic tier are embedded and indexed; working-tier items are
+   * appended to the in-run buffer.
+   *
+   * Re-remembering an item whose id (explicit or text-derived) already
+   * exists overwrites it in place rather than duplicating.
+   */
+  remember(items: MemoryItem | MemoryItem[]): Promise<void>;
+  /**
+   * Retrieve the memories most relevant to `query`, scored and ordered
+   * by descending relevance. Queries every enabled tier by default;
+   * `options.tier` narrows to one. `options.k` caps the result count,
+   * `options.threshold` raises the semantic-similarity floor.
+   *
+   * Returns an empty array when nothing clears the threshold — never
+   * throws on "no hits".
+   */
+  recall(query: string, options?: RecallOptions): Promise<RecalledMemory[]>;
+  /**
+   * Forget memories. With no argument, clears every tier. With a `tier`,
+   * clears just that tier — e.g. `clear("working")` at the end of a
+   * session while leaving durable semantic recall intact.
+   */
+  clear(tier?: MemoryTier): Promise<void>;
+}
+//#endregion
+export { MemoryContract };
+//# sourceMappingURL=memory.contract.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/memory/memory.contract.ts"],"mappings":";;;;;;AAqDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BmC;;;;;;;;;;;;;;;;;;UA/BlB,cAAA;;WAEN,IAAA;;;;;;;;;;EAWT,QAAA,CAAS,KAAA,EAAO,UAAA,GAAa,UAAA,KAAe,OAAA;;;;;;;;;;EAW5C,MAAA,CAAO,KAAA,UAAe,OAAA,GAAU,aAAA,GAAgB,OAAA,CAAQ,cAAA;;;;;;EAOxD,KAAA,CAAM,IAAA,GAAO,UAAA,GAAa,OAAA;AAAA"}

package/esm/contracts/memory/recall-options.type.d.mts

@@ -0,0 +1,33 @@
+import { MemoryTier } from "./memory-item.type.mjs";
+
+//#region ../@warlock.js/ai/src/contracts/memory/recall-options.type.d.ts
+/**
+ * Options for `memory.recall(query, options?)`.
+ *
+ * All fields are optional — the common call is `recall("some query")`,
+ * which uses the factory-configured `k` and threshold against every
+ * configured tier.
+ */
+type RecallOptions = {
+  /**
+   * Maximum number of memories to return. Overrides the factory's `k`
+   * for this call. The result is the top-`k` across whichever tiers are
+   * queried, ordered by descending `score`.
+   */
+  k?: number;
+  /**
+   * Restrict recall to a single tier. Omit to query every tier the
+   * factory was configured with (working first, then semantic) and
+   * merge the results.
+   */
+  tier?: MemoryTier;
+  /**
+   * Minimum semantic similarity for a hit, in `[0, 1]`. Overrides the
+   * factory's `threshold` for this call. Ignored by the working tier,
+   * which has no vector index.
+   */
+  threshold?: number;
+};
+//#endregion
+export { RecallOptions };
+//# sourceMappingURL=recall-options.type.d.mts.map

package/esm/contracts/memory/recall-options.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall-options.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/memory/recall-options.type.ts"],"mappings":";;;;;AASA;;;;;KAAY,aAAA;EAYH;;;AAME;;EAZT,CAAA;;;;;;EAMA,IAAA,GAAO,UAAU;;;;;;EAMjB,SAAA;AAAA"}

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

@@ -1,3 +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";
+import { MiddlewareAgentRef, MiddlewareExecuteContext, MiddlewareModelRef, MiddlewareSupervisorContext, MiddlewareSupervisorRef, MiddlewareToolContext, MiddlewareTripContext } from "./middleware-context.type.mjs";
+import { AgentMiddleware, AgentMiddlewareExecuteHooks, AgentMiddlewareSupervisorHooks, AgentMiddlewareToolHooks, AgentMiddlewareTripHooks } from "./middleware.contract.mjs";

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

@@ -1,8 +1,10 @@
 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 { SupervisorInput } from "../supervisor/supervisor-input.type.mjs";
+import { SupervisorExecuteOptions } from "../supervisor/supervisor-execute-options.type.mjs";
 import { MiddlewareState } from "./middleware-state.type.mjs";
+import { AgentExecuteOptions } from "../agent/agent-options.type.mjs";
 
 //#region ../@warlock.js/ai/src/contracts/middleware/middleware-context.type.d.ts
 /**
@@ -94,6 +96,44 @@ type MiddlewareToolContext = MiddlewareTripContext & {
   };
   readonly request: ModelToolCallRequest;
 };
+/**
+ * Minimal identity shape of the supervisor a `supervisor`-level
+ * middleware is wrapping. Middleware never mutates the supervisor
+ * itself, so it sees only the fields it can usefully branch on — the
+ * stable `name` (logs, per-supervisor allow-lists) and the structural
+ * `signature` (cache-key namespacing, drift-aware observability).
+ */
+type MiddlewareSupervisorRef = {
+  readonly name: string;
+  readonly signature: string;
+};
+/**
+ * Context passed to the `supervisor`-level middleware phase — fires
+ * once around the entire `supervisor.execute()` / `.stream()` /
+ * `.resume()` run, wrapping the iteration loop and final assembly.
+ *
+ * **Role.** The supervisor-level peer of {@link MiddlewareExecuteContext}.
+ * Gives middleware the stable identity of the run (supervisor, input,
+ * options) and a shared-state bag scoped to this one run. Anything
+ * cumulative across the whole supervisor lifecycle lives here:
+ * cross-iteration budgets, per-session rate-limit counters, audit
+ * correlation ids.
+ *
+ * Deliberately NOT an extension of {@link MiddlewareExecuteContext} —
+ * a supervisor has no single model, and its `input` is the wider
+ * `SupervisorInput` union (`string | Record<string, unknown>`), so the
+ * shapes diverge. The `state` bag is a fresh `Map` per run, matching
+ * the agent-level isolation guarantee.
+ *
+ * All fields are `readonly`; mutations go through `ctx.state`.
+ */
+type MiddlewareSupervisorContext = {
+  readonly supervisor: MiddlewareSupervisorRef;
+  readonly input: SupervisorInput;
+  readonly options: SupervisorExecuteOptions | undefined;
+  readonly state: MiddlewareState;
+  readonly signal?: AbortSignal;
+};
 //#endregion
-export { MiddlewareAgentRef, MiddlewareExecuteContext, MiddlewareModelRef, MiddlewareToolContext, MiddlewareTripContext };
+export { MiddlewareAgentRef, MiddlewareExecuteContext, MiddlewareModelRef, MiddlewareSupervisorContext, MiddlewareSupervisorRef, MiddlewareToolContext, MiddlewareTripContext };
 //# sourceMappingURL=middleware-context.type.d.mts.map

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

@@ -1 +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"}
+{"version":3,"file":"middleware-context.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/contracts/middleware/middleware-context.type.ts"],"mappings":";;;;;;;;;;;AAcA;;;;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;AAUxC;;;;KAzBY,qBAAA,GAAwB,qBAAA;EAAA,SACzB,IAAA;IAAA,SACE,IAAA;IAAA,SACA,WAAA;IAgDU;;;;;;;;;IAAA,SAtCV,IAAA,GAAO,QAAA;EAAA;EAAA,SAET,OAAA,EAAS,oBAAA;AAAA;;;;;;AAwCW;;KA9BnB,uBAAA;EAAA,SACD,IAAA;EAAA,SACA,SAAS;AAAA;;;;;;;;;;;;;;;;;;;;;KAuBR,2BAAA;EAAA,SACD,UAAA,EAAY,uBAAA;EAAA,SACZ,KAAA,EAAO,eAAA;EAAA,SACP,OAAA,EAAS,wBAAA;EAAA,SACT,KAAA,EAAO,eAAA;EAAA,SACP,MAAA,GAAS,WAAA;AAAA"}