@warlock.js/ai 4.8.1 → 4.9.0

package/esm/memory/episodic-memory.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"episodic-memory.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/memory/episodic-memory.ts"],"sourcesContent":["import type { CacheDriver, CacheSimilarHit } from \"@warlock.js/cache\";\nimport type { EmbedderContract } from \"../contracts/embedder.contract\";\nimport type {\n  MemoryItem,\n  RecalledMemory,\n} from \"../contracts/memory/memory-item.type\";\nimport { deriveMemoryId } from \"./derive-id\";\n\n/**\n * Shape persisted per episode. `ts` is the wall-clock time the episode\n * was remembered — the basis for the recency half of the blended recall\n * score. The vector lives in the driver's index (via `set({ vector })`),\n * so it is not duplicated here.\n */\ntype StoredEpisode = {\n  id: string;\n  text: string;\n  ts: number;\n  metadata?: Record<string, unknown>;\n};\n\n/**\n * How many extra candidates to pull from `similar()` before re-ranking by\n * the recency-blended score and slicing to `k`. Recency can promote a\n * slightly-less-similar-but-recent episode past a stale exact match, so\n * the raw top-`k` by similarity alone would miss it — overscan, then\n * re-rank.\n */\nconst RECALL_OVERSCAN = 5;\n\n/**\n * Episodic recall tier (memory core M2).\n *\n * Holds a durable, timestamped log of *what happened* — events/episodes —\n * and retrieves the ones most relevant to a query, **blended with\n * recency** so recent episodes outrank stale ones at equal similarity.\n * That recency weighting is the whole difference from the {@link\n * import(\"./semantic-memory\").SemanticMemory} tier (pure similarity over\n * timeless facts): episodic memory is time-anchored.\n *\n * Like the semantic tier it delegates the similarity search to the\n * `@warlock.js/cache` driver's `similar()` and never implements ANN\n * itself; it adds a stored `ts` per entry and a decay curve at recall.\n * The blended `score` stays in `[0, 1]` so a consumer can merge episodic\n * hits with the other tiers and sort on one field.\n *\n * Internal to the `memory()` factory — never exported on the package\n * surface.\n */\nexport class EpisodicMemory {\n  public constructor(\n    private readonly embedder: EmbedderContract,\n    private readonly store: CacheDriver<any, any>,\n    private readonly namespace: string,\n    private readonly recencyWeight: number,\n    private readonly halfLifeMs: number,\n    private readonly now: () => number,\n  ) {}\n\n  /**\n   * Embed the episode text and index it under a namespaced, id-derived\n   * key, stamping the current time. Re-remembering the same id overwrites\n   * the prior entry (and refreshes its timestamp).\n   */\n  public async remember(item: MemoryItem): Promise<void> {\n    const id = item.id ?? deriveMemoryId(item.text);\n    const { vector } = await this.embedder.embed(item.text);\n\n    const value: StoredEpisode = {\n      id,\n      text: item.text,\n      ts: this.now(),\n      metadata: item.metadata,\n    };\n\n    await this.store.set(this.keyFor(id), value, { vector });\n  }\n\n  /**\n   * Embed `query`, pull the nearest episodes clearing the similarity\n   * `threshold`, then re-rank each by a recency-blended score before\n   * returning the top `k`. The similarity floor still gates relevance —\n   * recency only reorders episodes that already cleared it, it never\n   * surfaces an irrelevant-but-recent one.\n   */\n  public async recall(\n    query: string,\n    k: number,\n    threshold: number,\n  ): Promise<RecalledMemory[]> {\n    const { vector } = await this.embedder.embed(query);\n\n    const hits = await this.store.similar<StoredEpisode>(vector, {\n      topK: Math.max(k * RECALL_OVERSCAN, k),\n      threshold,\n    });\n\n    const prefix = `${this.namespace}.`;\n    const now = this.now();\n\n    return hits\n      .filter((hit: CacheSimilarHit<StoredEpisode>) =>\n        hit.key.startsWith(prefix),\n      )\n      .map((hit: CacheSimilarHit<StoredEpisode>) => ({\n        id: hit.value.id,\n        text: hit.value.text,\n        tier: \"episodic\" as const,\n        score: this.blend(hit.score, hit.value.ts, now),\n        metadata: hit.value.metadata,\n      }))\n      .sort((first, second) => second.score - first.score)\n      .slice(0, k);\n  }\n\n  /** Drop every episode written under this instance's namespace. */\n  public async clear(): Promise<void> {\n    await this.store.removeNamespace(this.namespace);\n  }\n\n  /**\n   * Combine raw similarity with an exponential recency decay:\n   * `(1 - w)·similarity + w·0.5^(age / halfLife)`. A just-remembered\n   * episode contributes a recency of `1`; one `halfLife` old, `0.5`;\n   * older trends toward `0`. With `recencyWeight` 0 the score is pure\n   * similarity (an opt-out back to semantic-style ranking).\n   */\n  private blend(similarity: number, ts: number, now: number): number {\n    const ageMs = Math.max(0, now - ts);\n    const recency = 0.5 ** (ageMs / this.halfLifeMs);\n\n    return (1 - this.recencyWeight) * similarity + this.recencyWeight * recency;\n  }\n\n  /**\n   * Namespaced key for an entry. Mirrors the semantic tier's dot\n   * separator so the prefix used here matches the `hit.key` the driver\n   * returns from `similar()`.\n   */\n  private keyFor(id: string): string {\n    return `${this.namespace}.${id}`;\n  }\n}\n"],"mappings":";;;;;;;;;;AA4BA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;AAqBxB,IAAa,iBAAb,MAA4B;CAC1B,AAAO,YACL,AAAiB,UACjB,AAAiB,OACjB,AAAiB,WACjB,AAAiB,eACjB,AAAiB,YACjB,AAAiB,KACjB;EANiB;EACA;EACA;EACA;EACA;EACA;CAChB;;;;;;CAOH,MAAa,SAAS,MAAiC;EACrD,MAAM,KAAK,KAAK,MAAM,eAAe,KAAK,IAAI;EAC9C,MAAM,EAAE,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK,IAAI;EAEtD,MAAM,QAAuB;GAC3B;GACA,MAAM,KAAK;GACX,IAAI,KAAK,IAAI;GACb,UAAU,KAAK;EACjB;EAEA,MAAM,KAAK,MAAM,IAAI,KAAK,OAAO,EAAE,GAAG,OAAO,EAAE,OAAO,CAAC;CACzD;;;;;;;;CASA,MAAa,OACX,OACA,GACA,WAC2B;EAC3B,MAAM,EAAE,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK;EAElD,MAAM,OAAO,MAAM,KAAK,MAAM,QAAuB,QAAQ;GAC3D,MAAM,KAAK,IAAI,IAAI,iBAAiB,CAAC;GACrC;EACF,CAAC;EAED,MAAM,SAAS,GAAG,KAAK,UAAU;EACjC,MAAM,MAAM,KAAK,IAAI;EAErB,OAAO,KACJ,QAAQ,QACP,IAAI,IAAI,WAAW,MAAM,CAC3B,CAAC,CACA,KAAK,SAAyC;GAC7C,IAAI,IAAI,MAAM;GACd,MAAM,IAAI,MAAM;GAChB,MAAM;GACN,OAAO,KAAK,MAAM,IAAI,OAAO,IAAI,MAAM,IAAI,GAAG;GAC9C,UAAU,IAAI,MAAM;EACtB,EAAE,CAAC,CACF,MAAM,OAAO,WAAW,OAAO,QAAQ,MAAM,KAAK,CAAC,CACnD,MAAM,GAAG,CAAC;CACf;;CAGA,MAAa,QAAuB;EAClC,MAAM,KAAK,MAAM,gBAAgB,KAAK,SAAS;CACjD;;;;;;;;CASA,AAAQ,MAAM,YAAoB,IAAY,KAAqB;EAEjE,MAAM,UAAU,OADF,KAAK,IAAI,GAAG,MAAM,EACJ,IAAI,KAAK;EAErC,QAAQ,IAAI,KAAK,iBAAiB,aAAa,KAAK,gBAAgB;CACtE;;;;;;CAOA,AAAQ,OAAO,IAAoB;EACjC,OAAO,GAAG,KAAK,UAAU,GAAG;CAC9B;AACF"}
+{"version":3,"file":"episodic-memory.mjs","names":[],"sources":["../../../../../../../ai/src/memory/episodic-memory.ts"],"sourcesContent":["import type { CacheDriver, CacheSimilarHit } from \"@warlock.js/cache\";\nimport type { EmbedderContract } from \"../contracts/embedder.contract\";\nimport type {\n  MemoryItem,\n  RecalledMemory,\n} from \"../contracts/memory/memory-item.type\";\nimport { deriveMemoryId } from \"./derive-id\";\n\n/**\n * Shape persisted per episode. `ts` is the wall-clock time the episode\n * was remembered — the basis for the recency half of the blended recall\n * score. The vector lives in the driver's index (via `set({ vector })`),\n * so it is not duplicated here.\n */\ntype StoredEpisode = {\n  id: string;\n  text: string;\n  ts: number;\n  metadata?: Record<string, unknown>;\n};\n\n/**\n * How many extra candidates to pull from `similar()` before re-ranking by\n * the recency-blended score and slicing to `k`. Recency can promote a\n * slightly-less-similar-but-recent episode past a stale exact match, so\n * the raw top-`k` by similarity alone would miss it — overscan, then\n * re-rank.\n */\nconst RECALL_OVERSCAN = 5;\n\n/**\n * Episodic recall tier (memory core M2).\n *\n * Holds a durable, timestamped log of *what happened* — events/episodes —\n * and retrieves the ones most relevant to a query, **blended with\n * recency** so recent episodes outrank stale ones at equal similarity.\n * That recency weighting is the whole difference from the {@link\n * import(\"./semantic-memory\").SemanticMemory} tier (pure similarity over\n * timeless facts): episodic memory is time-anchored.\n *\n * Like the semantic tier it delegates the similarity search to the\n * `@warlock.js/cache` driver's `similar()` and never implements ANN\n * itself; it adds a stored `ts` per entry and a decay curve at recall.\n * The blended `score` stays in `[0, 1]` so a consumer can merge episodic\n * hits with the other tiers and sort on one field.\n *\n * Internal to the `memory()` factory — never exported on the package\n * surface.\n */\nexport class EpisodicMemory {\n  public constructor(\n    private readonly embedder: EmbedderContract,\n    private readonly store: CacheDriver<any, any>,\n    private readonly namespace: string,\n    private readonly recencyWeight: number,\n    private readonly halfLifeMs: number,\n    private readonly now: () => number,\n  ) {}\n\n  /**\n   * Embed the episode text and index it under a namespaced, id-derived\n   * key, stamping the current time. Re-remembering the same id overwrites\n   * the prior entry (and refreshes its timestamp).\n   */\n  public async remember(item: MemoryItem): Promise<void> {\n    const id = item.id ?? deriveMemoryId(item.text);\n    const { vector } = await this.embedder.embed(item.text);\n\n    const value: StoredEpisode = {\n      id,\n      text: item.text,\n      ts: this.now(),\n      metadata: item.metadata,\n    };\n\n    await this.store.set(this.keyFor(id), value, { vector });\n  }\n\n  /**\n   * Embed `query`, pull the nearest episodes clearing the similarity\n   * `threshold`, then re-rank each by a recency-blended score before\n   * returning the top `k`. The similarity floor still gates relevance —\n   * recency only reorders episodes that already cleared it, it never\n   * surfaces an irrelevant-but-recent one.\n   */\n  public async recall(\n    query: string,\n    k: number,\n    threshold: number,\n  ): Promise<RecalledMemory[]> {\n    const { vector } = await this.embedder.embed(query);\n\n    const hits = await this.store.similar<StoredEpisode>(vector, {\n      topK: Math.max(k * RECALL_OVERSCAN, k),\n      threshold,\n    });\n\n    const prefix = `${this.namespace}.`;\n    const now = this.now();\n\n    return hits\n      .filter((hit: CacheSimilarHit<StoredEpisode>) =>\n        hit.key.startsWith(prefix),\n      )\n      .map((hit: CacheSimilarHit<StoredEpisode>) => ({\n        id: hit.value.id,\n        text: hit.value.text,\n        tier: \"episodic\" as const,\n        score: this.blend(hit.score, hit.value.ts, now),\n        metadata: hit.value.metadata,\n      }))\n      .sort((first, second) => second.score - first.score)\n      .slice(0, k);\n  }\n\n  /** Drop every episode written under this instance's namespace. */\n  public async clear(): Promise<void> {\n    await this.store.removeNamespace(this.namespace);\n  }\n\n  /**\n   * Combine raw similarity with an exponential recency decay:\n   * `(1 - w)·similarity + w·0.5^(age / halfLife)`. A just-remembered\n   * episode contributes a recency of `1`; one `halfLife` old, `0.5`;\n   * older trends toward `0`. With `recencyWeight` 0 the score is pure\n   * similarity (an opt-out back to semantic-style ranking).\n   */\n  private blend(similarity: number, ts: number, now: number): number {\n    const ageMs = Math.max(0, now - ts);\n    const recency = 0.5 ** (ageMs / this.halfLifeMs);\n\n    return (1 - this.recencyWeight) * similarity + this.recencyWeight * recency;\n  }\n\n  /**\n   * Namespaced key for an entry. Mirrors the semantic tier's dot\n   * separator so the prefix used here matches the `hit.key` the driver\n   * returns from `similar()`.\n   */\n  private keyFor(id: string): string {\n    return `${this.namespace}.${id}`;\n  }\n}\n"],"mappings":";;;;;;;;;;AA4BA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;AAqBxB,IAAa,iBAAb,MAA4B;CAC1B,AAAO,YACL,AAAiB,UACjB,AAAiB,OACjB,AAAiB,WACjB,AAAiB,eACjB,AAAiB,YACjB,AAAiB,KACjB;EANiB;EACA;EACA;EACA;EACA;EACA;CAChB;;;;;;CAOH,MAAa,SAAS,MAAiC;EACrD,MAAM,KAAK,KAAK,MAAM,eAAe,KAAK,IAAI;EAC9C,MAAM,EAAE,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK,IAAI;EAEtD,MAAM,QAAuB;GAC3B;GACA,MAAM,KAAK;GACX,IAAI,KAAK,IAAI;GACb,UAAU,KAAK;EACjB;EAEA,MAAM,KAAK,MAAM,IAAI,KAAK,OAAO,EAAE,GAAG,OAAO,EAAE,OAAO,CAAC;CACzD;;;;;;;;CASA,MAAa,OACX,OACA,GACA,WAC2B;EAC3B,MAAM,EAAE,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK;EAElD,MAAM,OAAO,MAAM,KAAK,MAAM,QAAuB,QAAQ;GAC3D,MAAM,KAAK,IAAI,IAAI,iBAAiB,CAAC;GACrC;EACF,CAAC;EAED,MAAM,SAAS,GAAG,KAAK,UAAU;EACjC,MAAM,MAAM,KAAK,IAAI;EAErB,OAAO,KACJ,QAAQ,QACP,IAAI,IAAI,WAAW,MAAM,CAC3B,CAAC,CACA,KAAK,SAAyC;GAC7C,IAAI,IAAI,MAAM;GACd,MAAM,IAAI,MAAM;GAChB,MAAM;GACN,OAAO,KAAK,MAAM,IAAI,OAAO,IAAI,MAAM,IAAI,GAAG;GAC9C,UAAU,IAAI,MAAM;EACtB,EAAE,CAAC,CACF,MAAM,OAAO,WAAW,OAAO,QAAQ,MAAM,KAAK,CAAC,CACnD,MAAM,GAAG,CAAC;CACf;;CAGA,MAAa,QAAuB;EAClC,MAAM,KAAK,MAAM,gBAAgB,KAAK,SAAS;CACjD;;;;;;;;CASA,AAAQ,MAAM,YAAoB,IAAY,KAAqB;EAEjE,MAAM,UAAU,OADF,KAAK,IAAI,GAAG,MAAM,EACJ,IAAI,KAAK;EAErC,QAAQ,IAAI,KAAK,iBAAiB,aAAa,KAAK,gBAAgB;CACtE;;;;;;CAOA,AAAQ,OAAO,IAAoB;EACjC,OAAO,GAAG,KAAK,UAAU,GAAG;CAC9B;AACF"}

package/esm/memory/memory.d.mts

@@ -1,7 +1,7 @@
 import { MemoryContract } from "../contracts/memory/memory.contract.mjs";
 import { MemoryConfig } from "../contracts/memory/memory-config.type.mjs";
 
-//#region ../@warlock.js/ai/src/memory/memory.d.ts
+//#region ../ai/src/memory/memory.d.ts
 /**
  * Create an agent memory store (memory core M2).
  *

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

@@ -1 +1 @@
-{"version":3,"file":"memory.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/memory/memory.ts"],"mappings":";;;;;;AA0DA;;;;;;;;AAAiE;;;;;;;;;;;;;;;;;;;;;;;;iBAAjD,MAAA,CAAO,MAAA,GAAQ,YAAA,GAAoB,cAAc"}
+{"version":3,"file":"memory.d.mts","names":[],"sources":["../../../../../../../ai/src/memory/memory.ts"],"mappings":";;;;;;AA0DA;;;;;;;;AAAiE;;;;;;;;;;;;;;;;;;;;;;;;iBAAjD,MAAA,CAAO,MAAA,GAAQ,YAAA,GAAoB,cAAc"}

package/esm/memory/memory.mjs

@@ -4,7 +4,7 @@ import { ProceduralMemory } from "./procedural-memory.mjs";
 import { SemanticMemory } from "./semantic-memory.mjs";
 import { WorkingMemory } from "./working-memory.mjs";
 
-//#region ../@warlock.js/ai/src/memory/memory.ts
+//#region ../ai/src/memory/memory.ts
 const DEFAULT_NAME = "memory";
 const DEFAULT_SEMANTIC_NAMESPACE = "ai.memory.semantic";
 const DEFAULT_EPISODIC_NAMESPACE = "ai.memory.episodic";

package/esm/memory/memory.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"memory.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/memory/memory.ts"],"sourcesContent":["import { resolveDefaultStore } from \"../config\";\nimport type { MemoryConfig } from \"../contracts/memory/memory-config.type\";\nimport type {\n  MemoryItem,\n  MemoryTier,\n  RecalledMemory,\n} from \"../contracts/memory/memory-item.type\";\nimport type { MemoryContract } from \"../contracts/memory/memory.contract\";\nimport type { RecallOptions } from \"../contracts/memory/recall-options.type\";\nimport { EpisodicMemory } from \"./episodic-memory\";\nimport { ProceduralMemory } from \"./procedural-memory\";\nimport { SemanticMemory } from \"./semantic-memory\";\nimport { WorkingMemory } from \"./working-memory\";\n\nconst DEFAULT_NAME = \"memory\";\nconst DEFAULT_SEMANTIC_NAMESPACE = \"ai.memory.semantic\";\nconst DEFAULT_EPISODIC_NAMESPACE = \"ai.memory.episodic\";\nconst DEFAULT_PROCEDURAL_NAMESPACE = \"ai.memory.procedural\";\nconst DEFAULT_K = 5;\nconst DEFAULT_THRESHOLD = 0.7;\nconst DEFAULT_RECENCY_WEIGHT = 0.3;\nconst DEFAULT_HALF_LIFE_MS = 7 * 24 * 60 * 60 * 1000;\nconst DEFAULT_REINFORCEMENT_WEIGHT = 0.3;\n\n/**\n * Create an agent memory store (memory core M2).\n *\n * Wires up to four tiers behind the {@link MemoryContract}: **working**\n * (in-run scratch, recency), **semantic** (durable facts by cosine\n * similarity), **episodic** (durable events, similarity blended with\n * recency), and **procedural** (durable how-tos, similarity blended with\n * reinforcement). The working tier is on by default; the other three each\n * activate only when their config is supplied. The three vector tiers\n * mirror how `semanticCache` delegates similarity to the cache driver's\n * `.similar()`.\n *\n * Resolution happens once here, at construction (loud), rather than per\n * call (silent until first use): a vector-tier config with no `store` and\n * no `ai.config({ defaultStore })` throws now; enabling no tier at all\n * throws now.\n *\n * Decay / forgetting (TTL-based falloff, eviction) remains deferred.\n *\n * @example\n * import { ai } from \"@warlock.js/ai\";\n * import { MemoryCacheDriver } from \"@warlock.js/cache\";\n *\n * const store = new MemoryCacheDriver();\n * store.setOptions({});\n *\n * const mem = ai.memory({\n *   semantic: { embedder, store },\n *   defaultTier: \"semantic\",\n * });\n *\n * await mem.remember({ text: \"User prefers concise answers.\" });\n * const hits = await mem.recall(\"how should I respond?\", { k: 3 });\n */\nexport function memory(config: MemoryConfig = {}): MemoryContract {\n  const name = config.name ?? DEFAULT_NAME;\n  const workingEnabled = config.working ?? true;\n  const defaultK = config.k ?? DEFAULT_K;\n  const defaultThreshold = config.threshold ?? DEFAULT_THRESHOLD;\n\n  const working = workingEnabled ? new WorkingMemory() : undefined;\n\n  const semantic = config.semantic\n    ? buildSemanticTier(config.semantic, name)\n    : undefined;\n\n  const episodic = config.episodic\n    ? buildEpisodicTier(config.episodic, name)\n    : undefined;\n\n  const procedural = config.procedural\n    ? buildProceduralTier(config.procedural, name)\n    : undefined;\n\n  const tiers: Tiers = { working, semantic, episodic, procedural };\n\n  if (!working && !semantic && !episodic && !procedural) {\n    throw new Error(\n      `memory(\"${name}\"): no tier enabled — enable \\`working\\` (default) or pass a \\`semantic\\` / \\`episodic\\` / \\`procedural\\` config; a memory with no tiers can neither store nor recall`,\n    );\n  }\n\n  const defaultTier: MemoryTier = config.defaultTier ?? \"working\";\n\n  assertTierEnabled(defaultTier, tiers, name);\n\n  return {\n    name,\n    async remember(items: MemoryItem | MemoryItem[]): Promise<void> {\n      const list = Array.isArray(items) ? items : [items];\n\n      const writes: Promise<void>[] = [];\n\n      for (const item of list) {\n        const tier = item.tier ?? defaultTier;\n\n        assertTierEnabled(tier, tiers, name);\n\n        if (tier === \"working\") {\n          working!.remember(item);\n\n          continue;\n        }\n\n        if (tier === \"semantic\") {\n          writes.push(semantic!.remember(item));\n\n          continue;\n        }\n\n        if (tier === \"episodic\") {\n          writes.push(episodic!.remember(item));\n\n          continue;\n        }\n\n        writes.push(procedural!.remember(item));\n      }\n\n      await Promise.all(writes);\n    },\n    async recall(\n      query: string,\n      options: RecallOptions = {},\n    ): Promise<RecalledMemory[]> {\n      const k = options.k ?? defaultK;\n      const threshold = options.threshold ?? defaultThreshold;\n\n      if (options.tier) {\n        assertTierEnabled(options.tier, tiers, name);\n      }\n\n      const wants = (tier: MemoryTier): boolean =>\n        !options.tier || options.tier === tier;\n\n      const [workingHits, semanticHits, episodicHits, proceduralHits] =\n        await Promise.all([\n          working && wants(\"working\")\n            ? Promise.resolve(working.recall(k))\n            : Promise.resolve([] as RecalledMemory[]),\n          semantic && wants(\"semantic\")\n            ? semantic.recall(query, k, threshold)\n            : Promise.resolve([] as RecalledMemory[]),\n          episodic && wants(\"episodic\")\n            ? episodic.recall(query, k, threshold)\n            : Promise.resolve([] as RecalledMemory[]),\n          procedural && wants(\"procedural\")\n            ? procedural.recall(query, k, threshold)\n            : Promise.resolve([] as RecalledMemory[]),\n        ]);\n\n      return [\n        ...workingHits,\n        ...semanticHits,\n        ...episodicHits,\n        ...proceduralHits,\n      ]\n        .sort((first, second) => second.score - first.score)\n        .slice(0, k);\n    },\n    async clear(tier?: MemoryTier): Promise<void> {\n      const clears: Promise<void>[] = [];\n\n      if (working && (!tier || tier === \"working\")) {\n        working.clear();\n      }\n\n      if (semantic && (!tier || tier === \"semantic\")) {\n        clears.push(semantic.clear());\n      }\n\n      if (episodic && (!tier || tier === \"episodic\")) {\n        clears.push(episodic.clear());\n      }\n\n      if (procedural && (!tier || tier === \"procedural\")) {\n        clears.push(procedural.clear());\n      }\n\n      await Promise.all(clears);\n    },\n  };\n}\n\n/** The four tier instances a `memory()` composes; `undefined` when off. */\ntype Tiers = {\n  working: WorkingMemory | undefined;\n  semantic: SemanticMemory | undefined;\n  episodic: EpisodicMemory | undefined;\n  procedural: ProceduralMemory | undefined;\n};\n\n/**\n * Resolve the semantic tier's store (explicit `store` wins, else the\n * global `ai.config({ defaultStore })`) and build the tier. Throws at\n * construction when neither is available — the same loud-now contract\n * `semanticCache` follows.\n */\nfunction buildSemanticTier(\n  semanticConfig: NonNullable<MemoryConfig[\"semantic\"]>,\n  name: string,\n): SemanticMemory {\n  const store = semanticConfig.store ?? resolveDefaultStore();\n\n  if (!store) {\n    throw new Error(\n      `memory(\"${name}\"): semantic tier has no store — pass \\`semantic.store\\` or call \\`ai.config({ defaultStore })\\` at app boot before constructing the memory`,\n    );\n  }\n\n  return new SemanticMemory(\n    semanticConfig.embedder,\n    store,\n    semanticConfig.namespace ?? DEFAULT_SEMANTIC_NAMESPACE,\n  );\n}\n\n/**\n * Resolve the episodic tier's store (explicit `store` wins, else the\n * global default) and build the tier with its recency knobs. Throws at\n * construction when neither store is available — the same loud-now\n * contract the semantic tier follows.\n */\nfunction buildEpisodicTier(\n  episodicConfig: NonNullable<MemoryConfig[\"episodic\"]>,\n  name: string,\n): EpisodicMemory {\n  const store = episodicConfig.store ?? resolveDefaultStore();\n\n  if (!store) {\n    throw new Error(\n      `memory(\"${name}\"): episodic tier has no store — pass \\`episodic.store\\` or call \\`ai.config({ defaultStore })\\` at app boot before constructing the memory`,\n    );\n  }\n\n  return new EpisodicMemory(\n    episodicConfig.embedder,\n    store,\n    episodicConfig.namespace ?? DEFAULT_EPISODIC_NAMESPACE,\n    episodicConfig.recencyWeight ?? DEFAULT_RECENCY_WEIGHT,\n    episodicConfig.halfLifeMs ?? DEFAULT_HALF_LIFE_MS,\n    episodicConfig.now ?? (() => Date.now()),\n  );\n}\n\n/**\n * Resolve the procedural tier's store and build the tier with its\n * reinforcement knob. Throws at construction when no store is available.\n */\nfunction buildProceduralTier(\n  proceduralConfig: NonNullable<MemoryConfig[\"procedural\"]>,\n  name: string,\n): ProceduralMemory {\n  const store = proceduralConfig.store ?? resolveDefaultStore();\n\n  if (!store) {\n    throw new Error(\n      `memory(\"${name}\"): procedural tier has no store — pass \\`procedural.store\\` or call \\`ai.config({ defaultStore })\\` at app boot before constructing the memory`,\n    );\n  }\n\n  return new ProceduralMemory(\n    proceduralConfig.embedder,\n    store,\n    proceduralConfig.namespace ?? DEFAULT_PROCEDURAL_NAMESPACE,\n    proceduralConfig.reinforcementWeight ?? DEFAULT_REINFORCEMENT_WEIGHT,\n  );\n}\n\n/**\n * Guard that a tier referenced by config / a call is actually enabled,\n * failing fast with an actionable message instead of a downstream\n * `undefined` dereference.\n */\nfunction assertTierEnabled(tier: MemoryTier, tiers: Tiers, name: string): void {\n  if (tier === \"working\" && !tiers.working) {\n    throw new Error(\n      `memory(\"${name}\"): working tier is disabled — set \\`working: true\\` (the default) to use it`,\n    );\n  }\n\n  if (tier === \"semantic\" && !tiers.semantic) {\n    throw new Error(\n      `memory(\"${name}\"): semantic tier is not configured — pass \\`semantic\\` config to use it`,\n    );\n  }\n\n  if (tier === \"episodic\" && !tiers.episodic) {\n    throw new Error(\n      `memory(\"${name}\"): episodic tier is not configured — pass \\`episodic\\` config to use it`,\n    );\n  }\n\n  if (tier === \"procedural\" && !tiers.procedural) {\n    throw new Error(\n      `memory(\"${name}\"): procedural tier is not configured — pass \\`procedural\\` config to use it`,\n    );\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"memory.mjs","names":[],"sources":["../../../../../../../ai/src/memory/memory.ts"],"sourcesContent":["import { resolveDefaultStore } from \"../config\";\nimport type { MemoryConfig } from \"../contracts/memory/memory-config.type\";\nimport type {\n  MemoryItem,\n  MemoryTier,\n  RecalledMemory,\n} from \"../contracts/memory/memory-item.type\";\nimport type { MemoryContract } from \"../contracts/memory/memory.contract\";\nimport type { RecallOptions } from \"../contracts/memory/recall-options.type\";\nimport { EpisodicMemory } from \"./episodic-memory\";\nimport { ProceduralMemory } from \"./procedural-memory\";\nimport { SemanticMemory } from \"./semantic-memory\";\nimport { WorkingMemory } from \"./working-memory\";\n\nconst DEFAULT_NAME = \"memory\";\nconst DEFAULT_SEMANTIC_NAMESPACE = \"ai.memory.semantic\";\nconst DEFAULT_EPISODIC_NAMESPACE = \"ai.memory.episodic\";\nconst DEFAULT_PROCEDURAL_NAMESPACE = \"ai.memory.procedural\";\nconst DEFAULT_K = 5;\nconst DEFAULT_THRESHOLD = 0.7;\nconst DEFAULT_RECENCY_WEIGHT = 0.3;\nconst DEFAULT_HALF_LIFE_MS = 7 * 24 * 60 * 60 * 1000;\nconst DEFAULT_REINFORCEMENT_WEIGHT = 0.3;\n\n/**\n * Create an agent memory store (memory core M2).\n *\n * Wires up to four tiers behind the {@link MemoryContract}: **working**\n * (in-run scratch, recency), **semantic** (durable facts by cosine\n * similarity), **episodic** (durable events, similarity blended with\n * recency), and **procedural** (durable how-tos, similarity blended with\n * reinforcement). The working tier is on by default; the other three each\n * activate only when their config is supplied. The three vector tiers\n * mirror how `semanticCache` delegates similarity to the cache driver's\n * `.similar()`.\n *\n * Resolution happens once here, at construction (loud), rather than per\n * call (silent until first use): a vector-tier config with no `store` and\n * no `ai.config({ defaultStore })` throws now; enabling no tier at all\n * throws now.\n *\n * Decay / forgetting (TTL-based falloff, eviction) remains deferred.\n *\n * @example\n * import { ai } from \"@warlock.js/ai\";\n * import { MemoryCacheDriver } from \"@warlock.js/cache\";\n *\n * const store = new MemoryCacheDriver();\n * store.setOptions({});\n *\n * const mem = ai.memory({\n *   semantic: { embedder, store },\n *   defaultTier: \"semantic\",\n * });\n *\n * await mem.remember({ text: \"User prefers concise answers.\" });\n * const hits = await mem.recall(\"how should I respond?\", { k: 3 });\n */\nexport function memory(config: MemoryConfig = {}): MemoryContract {\n  const name = config.name ?? DEFAULT_NAME;\n  const workingEnabled = config.working ?? true;\n  const defaultK = config.k ?? DEFAULT_K;\n  const defaultThreshold = config.threshold ?? DEFAULT_THRESHOLD;\n\n  const working = workingEnabled ? new WorkingMemory() : undefined;\n\n  const semantic = config.semantic\n    ? buildSemanticTier(config.semantic, name)\n    : undefined;\n\n  const episodic = config.episodic\n    ? buildEpisodicTier(config.episodic, name)\n    : undefined;\n\n  const procedural = config.procedural\n    ? buildProceduralTier(config.procedural, name)\n    : undefined;\n\n  const tiers: Tiers = { working, semantic, episodic, procedural };\n\n  if (!working && !semantic && !episodic && !procedural) {\n    throw new Error(\n      `memory(\"${name}\"): no tier enabled — enable \\`working\\` (default) or pass a \\`semantic\\` / \\`episodic\\` / \\`procedural\\` config; a memory with no tiers can neither store nor recall`,\n    );\n  }\n\n  const defaultTier: MemoryTier = config.defaultTier ?? \"working\";\n\n  assertTierEnabled(defaultTier, tiers, name);\n\n  return {\n    name,\n    async remember(items: MemoryItem | MemoryItem[]): Promise<void> {\n      const list = Array.isArray(items) ? items : [items];\n\n      const writes: Promise<void>[] = [];\n\n      for (const item of list) {\n        const tier = item.tier ?? defaultTier;\n\n        assertTierEnabled(tier, tiers, name);\n\n        if (tier === \"working\") {\n          working!.remember(item);\n\n          continue;\n        }\n\n        if (tier === \"semantic\") {\n          writes.push(semantic!.remember(item));\n\n          continue;\n        }\n\n        if (tier === \"episodic\") {\n          writes.push(episodic!.remember(item));\n\n          continue;\n        }\n\n        writes.push(procedural!.remember(item));\n      }\n\n      await Promise.all(writes);\n    },\n    async recall(\n      query: string,\n      options: RecallOptions = {},\n    ): Promise<RecalledMemory[]> {\n      const k = options.k ?? defaultK;\n      const threshold = options.threshold ?? defaultThreshold;\n\n      if (options.tier) {\n        assertTierEnabled(options.tier, tiers, name);\n      }\n\n      const wants = (tier: MemoryTier): boolean =>\n        !options.tier || options.tier === tier;\n\n      const [workingHits, semanticHits, episodicHits, proceduralHits] =\n        await Promise.all([\n          working && wants(\"working\")\n            ? Promise.resolve(working.recall(k))\n            : Promise.resolve([] as RecalledMemory[]),\n          semantic && wants(\"semantic\")\n            ? semantic.recall(query, k, threshold)\n            : Promise.resolve([] as RecalledMemory[]),\n          episodic && wants(\"episodic\")\n            ? episodic.recall(query, k, threshold)\n            : Promise.resolve([] as RecalledMemory[]),\n          procedural && wants(\"procedural\")\n            ? procedural.recall(query, k, threshold)\n            : Promise.resolve([] as RecalledMemory[]),\n        ]);\n\n      return [\n        ...workingHits,\n        ...semanticHits,\n        ...episodicHits,\n        ...proceduralHits,\n      ]\n        .sort((first, second) => second.score - first.score)\n        .slice(0, k);\n    },\n    async clear(tier?: MemoryTier): Promise<void> {\n      const clears: Promise<void>[] = [];\n\n      if (working && (!tier || tier === \"working\")) {\n        working.clear();\n      }\n\n      if (semantic && (!tier || tier === \"semantic\")) {\n        clears.push(semantic.clear());\n      }\n\n      if (episodic && (!tier || tier === \"episodic\")) {\n        clears.push(episodic.clear());\n      }\n\n      if (procedural && (!tier || tier === \"procedural\")) {\n        clears.push(procedural.clear());\n      }\n\n      await Promise.all(clears);\n    },\n  };\n}\n\n/** The four tier instances a `memory()` composes; `undefined` when off. */\ntype Tiers = {\n  working: WorkingMemory | undefined;\n  semantic: SemanticMemory | undefined;\n  episodic: EpisodicMemory | undefined;\n  procedural: ProceduralMemory | undefined;\n};\n\n/**\n * Resolve the semantic tier's store (explicit `store` wins, else the\n * global `ai.config({ defaultStore })`) and build the tier. Throws at\n * construction when neither is available — the same loud-now contract\n * `semanticCache` follows.\n */\nfunction buildSemanticTier(\n  semanticConfig: NonNullable<MemoryConfig[\"semantic\"]>,\n  name: string,\n): SemanticMemory {\n  const store = semanticConfig.store ?? resolveDefaultStore();\n\n  if (!store) {\n    throw new Error(\n      `memory(\"${name}\"): semantic tier has no store — pass \\`semantic.store\\` or call \\`ai.config({ defaultStore })\\` at app boot before constructing the memory`,\n    );\n  }\n\n  return new SemanticMemory(\n    semanticConfig.embedder,\n    store,\n    semanticConfig.namespace ?? DEFAULT_SEMANTIC_NAMESPACE,\n  );\n}\n\n/**\n * Resolve the episodic tier's store (explicit `store` wins, else the\n * global default) and build the tier with its recency knobs. Throws at\n * construction when neither store is available — the same loud-now\n * contract the semantic tier follows.\n */\nfunction buildEpisodicTier(\n  episodicConfig: NonNullable<MemoryConfig[\"episodic\"]>,\n  name: string,\n): EpisodicMemory {\n  const store = episodicConfig.store ?? resolveDefaultStore();\n\n  if (!store) {\n    throw new Error(\n      `memory(\"${name}\"): episodic tier has no store — pass \\`episodic.store\\` or call \\`ai.config({ defaultStore })\\` at app boot before constructing the memory`,\n    );\n  }\n\n  return new EpisodicMemory(\n    episodicConfig.embedder,\n    store,\n    episodicConfig.namespace ?? DEFAULT_EPISODIC_NAMESPACE,\n    episodicConfig.recencyWeight ?? DEFAULT_RECENCY_WEIGHT,\n    episodicConfig.halfLifeMs ?? DEFAULT_HALF_LIFE_MS,\n    episodicConfig.now ?? (() => Date.now()),\n  );\n}\n\n/**\n * Resolve the procedural tier's store and build the tier with its\n * reinforcement knob. Throws at construction when no store is available.\n */\nfunction buildProceduralTier(\n  proceduralConfig: NonNullable<MemoryConfig[\"procedural\"]>,\n  name: string,\n): ProceduralMemory {\n  const store = proceduralConfig.store ?? resolveDefaultStore();\n\n  if (!store) {\n    throw new Error(\n      `memory(\"${name}\"): procedural tier has no store — pass \\`procedural.store\\` or call \\`ai.config({ defaultStore })\\` at app boot before constructing the memory`,\n    );\n  }\n\n  return new ProceduralMemory(\n    proceduralConfig.embedder,\n    store,\n    proceduralConfig.namespace ?? DEFAULT_PROCEDURAL_NAMESPACE,\n    proceduralConfig.reinforcementWeight ?? DEFAULT_REINFORCEMENT_WEIGHT,\n  );\n}\n\n/**\n * Guard that a tier referenced by config / a call is actually enabled,\n * failing fast with an actionable message instead of a downstream\n * `undefined` dereference.\n */\nfunction assertTierEnabled(tier: MemoryTier, tiers: Tiers, name: string): void {\n  if (tier === \"working\" && !tiers.working) {\n    throw new Error(\n      `memory(\"${name}\"): working tier is disabled — set \\`working: true\\` (the default) to use it`,\n    );\n  }\n\n  if (tier === \"semantic\" && !tiers.semantic) {\n    throw new Error(\n      `memory(\"${name}\"): semantic tier is not configured — pass \\`semantic\\` config to use it`,\n    );\n  }\n\n  if (tier === \"episodic\" && !tiers.episodic) {\n    throw new Error(\n      `memory(\"${name}\"): episodic tier is not configured — pass \\`episodic\\` config to use it`,\n    );\n  }\n\n  if (tier === \"procedural\" && !tiers.procedural) {\n    throw new Error(\n      `memory(\"${name}\"): procedural tier is not configured — pass \\`procedural\\` config to use it`,\n    );\n  }\n}\n"],"mappings":"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"}

package/esm/memory/procedural-memory.mjs

@@ -1,6 +1,6 @@
 import { deriveMemoryId } from "./derive-id.mjs";
 
-//#region ../@warlock.js/ai/src/memory/procedural-memory.ts
+//#region ../ai/src/memory/procedural-memory.ts
 /**
 * Extra candidates pulled from `similar()` before re-ranking by the
 * reinforcement-blended score and slicing to `k` — reinforcement can

package/esm/memory/procedural-memory.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"procedural-memory.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/memory/procedural-memory.ts"],"sourcesContent":["import type { CacheDriver, CacheSimilarHit } from \"@warlock.js/cache\";\nimport type { EmbedderContract } from \"../contracts/embedder.contract\";\nimport type {\n  MemoryItem,\n  RecalledMemory,\n} from \"../contracts/memory/memory-item.type\";\nimport { deriveMemoryId } from \"./derive-id\";\n\n/**\n * Shape persisted per procedure. `uses` is the reinforcement counter —\n * how many times the procedure has been remembered/re-affirmed — and\n * feeds the reinforcement half of the blended recall score. The vector\n * lives in the driver's index, so it is not duplicated here.\n */\ntype StoredProcedure = {\n  id: string;\n  text: string;\n  uses: number;\n  metadata?: Record<string, unknown>;\n};\n\n/**\n * Extra candidates pulled from `similar()` before re-ranking by the\n * reinforcement-blended score and slicing to `k` — reinforcement can\n * promote a well-worn procedure past a slightly-closer one-off, which the\n * raw top-`k` by similarity would miss.\n */\nconst RECALL_OVERSCAN = 5;\n\n/**\n * Procedural recall tier (memory core M2).\n *\n * Holds durable *how-to* knowledge — learned procedures, policies, and\n * playbooks — and retrieves the ones relevant to a query, **blended with\n * reinforcement** so procedures that have proven themselves (remembered /\n * re-affirmed more often) outrank one-offs at equal similarity. That\n * reinforcement weighting is the difference from the semantic tier (which\n * treats every fact equally): procedural memory gets *stronger with use*.\n *\n * Reinforcement is explicit and side-effect-free on read: re-remembering\n * a procedure (same id, or same text → same derived id) increments its\n * `uses`, so a caller strengthens a procedure by remembering it again\n * after a successful application. Recall never mutates.\n *\n * Like the other vector tiers it delegates similarity to the\n * `@warlock.js/cache` driver's `similar()`. The blended `score` stays in\n * `[0, 1]` so procedural hits merge and sort alongside the other tiers.\n *\n * Internal to the `memory()` factory — never exported on the package\n * surface.\n */\nexport class ProceduralMemory {\n  public constructor(\n    private readonly embedder: EmbedderContract,\n    private readonly store: CacheDriver<any, any>,\n    private readonly namespace: string,\n    private readonly reinforcementWeight: number,\n  ) {}\n\n  /**\n   * Embed the procedure text and index it, incrementing its `uses` when\n   * it already exists (reinforcement) or seeding it at `1` when new.\n   * Metadata on a reinforcing write wins; an omitted metadata keeps the\n   * prior value rather than wiping it.\n   */\n  public async remember(item: MemoryItem): Promise<void> {\n    const id = item.id ?? deriveMemoryId(item.text);\n    const { vector } = await this.embedder.embed(item.text);\n\n    const existing = await this.store.get<StoredProcedure>(this.keyFor(id));\n    const uses = (existing?.uses ?? 0) + 1;\n\n    const value: StoredProcedure = {\n      id,\n      text: item.text,\n      uses,\n      metadata: item.metadata ?? existing?.metadata,\n    };\n\n    await this.store.set(this.keyFor(id), value, { vector });\n  }\n\n  /**\n   * Embed `query`, pull the nearest procedures clearing the similarity\n   * `threshold`, then re-rank each by a reinforcement-blended score and\n   * return the top `k`. The similarity floor still gates relevance;\n   * reinforcement only reorders procedures that already cleared it.\n   */\n  public async recall(\n    query: string,\n    k: number,\n    threshold: number,\n  ): Promise<RecalledMemory[]> {\n    const { vector } = await this.embedder.embed(query);\n\n    const hits = await this.store.similar<StoredProcedure>(vector, {\n      topK: Math.max(k * RECALL_OVERSCAN, k),\n      threshold,\n    });\n\n    const prefix = `${this.namespace}.`;\n\n    return hits\n      .filter((hit: CacheSimilarHit<StoredProcedure>) =>\n        hit.key.startsWith(prefix),\n      )\n      .map((hit: CacheSimilarHit<StoredProcedure>) => ({\n        id: hit.value.id,\n        text: hit.value.text,\n        tier: \"procedural\" as const,\n        score: this.blend(hit.score, hit.value.uses),\n        metadata: hit.value.metadata,\n      }))\n      .sort((first, second) => second.score - first.score)\n      .slice(0, k);\n  }\n\n  /** Drop every procedure written under this instance's namespace. */\n  public async clear(): Promise<void> {\n    await this.store.removeNamespace(this.namespace);\n  }\n\n  /**\n   * Combine raw similarity with a saturating reinforcement proxy:\n   * `(1 - w)·similarity + w·(uses / (uses + 1))`. A first-time procedure\n   * contributes `0.5`; each reinforcement nudges it toward `1` with\n   * diminishing returns. With `reinforcementWeight` 0 the score is pure\n   * similarity.\n   */\n  private blend(similarity: number, uses: number): number {\n    const reinforcement = uses / (uses + 1);\n\n    return (\n      (1 - this.reinforcementWeight) * similarity +\n      this.reinforcementWeight * reinforcement\n    );\n  }\n\n  /** Namespaced key for an entry — dot separator, matching `similar()` keys. */\n  private keyFor(id: string): string {\n    return `${this.namespace}.${id}`;\n  }\n}\n"],"mappings":";;;;;;;;;AA2BA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;AAwBxB,IAAa,mBAAb,MAA8B;CAC5B,AAAO,YACL,AAAiB,UACjB,AAAiB,OACjB,AAAiB,WACjB,AAAiB,qBACjB;EAJiB;EACA;EACA;EACA;CAChB;;;;;;;CAQH,MAAa,SAAS,MAAiC;EACrD,MAAM,KAAK,KAAK,MAAM,eAAe,KAAK,IAAI;EAC9C,MAAM,EAAE,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK,IAAI;EAEtD,MAAM,WAAW,MAAM,KAAK,MAAM,IAAqB,KAAK,OAAO,EAAE,CAAC;EACtE,MAAM,QAAQ,UAAU,QAAQ,KAAK;EAErC,MAAM,QAAyB;GAC7B;GACA,MAAM,KAAK;GACX;GACA,UAAU,KAAK,YAAY,UAAU;EACvC;EAEA,MAAM,KAAK,MAAM,IAAI,KAAK,OAAO,EAAE,GAAG,OAAO,EAAE,OAAO,CAAC;CACzD;;;;;;;CAQA,MAAa,OACX,OACA,GACA,WAC2B;EAC3B,MAAM,EAAE,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK;EAElD,MAAM,OAAO,MAAM,KAAK,MAAM,QAAyB,QAAQ;GAC7D,MAAM,KAAK,IAAI,IAAI,iBAAiB,CAAC;GACrC;EACF,CAAC;EAED,MAAM,SAAS,GAAG,KAAK,UAAU;EAEjC,OAAO,KACJ,QAAQ,QACP,IAAI,IAAI,WAAW,MAAM,CAC3B,CAAC,CACA,KAAK,SAA2C;GAC/C,IAAI,IAAI,MAAM;GACd,MAAM,IAAI,MAAM;GAChB,MAAM;GACN,OAAO,KAAK,MAAM,IAAI,OAAO,IAAI,MAAM,IAAI;GAC3C,UAAU,IAAI,MAAM;EACtB,EAAE,CAAC,CACF,MAAM,OAAO,WAAW,OAAO,QAAQ,MAAM,KAAK,CAAC,CACnD,MAAM,GAAG,CAAC;CACf;;CAGA,MAAa,QAAuB;EAClC,MAAM,KAAK,MAAM,gBAAgB,KAAK,SAAS;CACjD;;;;;;;;CASA,AAAQ,MAAM,YAAoB,MAAsB;EACtD,MAAM,gBAAgB,QAAQ,OAAO;EAErC,QACG,IAAI,KAAK,uBAAuB,aACjC,KAAK,sBAAsB;CAE/B;;CAGA,AAAQ,OAAO,IAAoB;EACjC,OAAO,GAAG,KAAK,UAAU,GAAG;CAC9B;AACF"}
+{"version":3,"file":"procedural-memory.mjs","names":[],"sources":["../../../../../../../ai/src/memory/procedural-memory.ts"],"sourcesContent":["import type { CacheDriver, CacheSimilarHit } from \"@warlock.js/cache\";\nimport type { EmbedderContract } from \"../contracts/embedder.contract\";\nimport type {\n  MemoryItem,\n  RecalledMemory,\n} from \"../contracts/memory/memory-item.type\";\nimport { deriveMemoryId } from \"./derive-id\";\n\n/**\n * Shape persisted per procedure. `uses` is the reinforcement counter —\n * how many times the procedure has been remembered/re-affirmed — and\n * feeds the reinforcement half of the blended recall score. The vector\n * lives in the driver's index, so it is not duplicated here.\n */\ntype StoredProcedure = {\n  id: string;\n  text: string;\n  uses: number;\n  metadata?: Record<string, unknown>;\n};\n\n/**\n * Extra candidates pulled from `similar()` before re-ranking by the\n * reinforcement-blended score and slicing to `k` — reinforcement can\n * promote a well-worn procedure past a slightly-closer one-off, which the\n * raw top-`k` by similarity would miss.\n */\nconst RECALL_OVERSCAN = 5;\n\n/**\n * Procedural recall tier (memory core M2).\n *\n * Holds durable *how-to* knowledge — learned procedures, policies, and\n * playbooks — and retrieves the ones relevant to a query, **blended with\n * reinforcement** so procedures that have proven themselves (remembered /\n * re-affirmed more often) outrank one-offs at equal similarity. That\n * reinforcement weighting is the difference from the semantic tier (which\n * treats every fact equally): procedural memory gets *stronger with use*.\n *\n * Reinforcement is explicit and side-effect-free on read: re-remembering\n * a procedure (same id, or same text → same derived id) increments its\n * `uses`, so a caller strengthens a procedure by remembering it again\n * after a successful application. Recall never mutates.\n *\n * Like the other vector tiers it delegates similarity to the\n * `@warlock.js/cache` driver's `similar()`. The blended `score` stays in\n * `[0, 1]` so procedural hits merge and sort alongside the other tiers.\n *\n * Internal to the `memory()` factory — never exported on the package\n * surface.\n */\nexport class ProceduralMemory {\n  public constructor(\n    private readonly embedder: EmbedderContract,\n    private readonly store: CacheDriver<any, any>,\n    private readonly namespace: string,\n    private readonly reinforcementWeight: number,\n  ) {}\n\n  /**\n   * Embed the procedure text and index it, incrementing its `uses` when\n   * it already exists (reinforcement) or seeding it at `1` when new.\n   * Metadata on a reinforcing write wins; an omitted metadata keeps the\n   * prior value rather than wiping it.\n   */\n  public async remember(item: MemoryItem): Promise<void> {\n    const id = item.id ?? deriveMemoryId(item.text);\n    const { vector } = await this.embedder.embed(item.text);\n\n    const existing = await this.store.get<StoredProcedure>(this.keyFor(id));\n    const uses = (existing?.uses ?? 0) + 1;\n\n    const value: StoredProcedure = {\n      id,\n      text: item.text,\n      uses,\n      metadata: item.metadata ?? existing?.metadata,\n    };\n\n    await this.store.set(this.keyFor(id), value, { vector });\n  }\n\n  /**\n   * Embed `query`, pull the nearest procedures clearing the similarity\n   * `threshold`, then re-rank each by a reinforcement-blended score and\n   * return the top `k`. The similarity floor still gates relevance;\n   * reinforcement only reorders procedures that already cleared it.\n   */\n  public async recall(\n    query: string,\n    k: number,\n    threshold: number,\n  ): Promise<RecalledMemory[]> {\n    const { vector } = await this.embedder.embed(query);\n\n    const hits = await this.store.similar<StoredProcedure>(vector, {\n      topK: Math.max(k * RECALL_OVERSCAN, k),\n      threshold,\n    });\n\n    const prefix = `${this.namespace}.`;\n\n    return hits\n      .filter((hit: CacheSimilarHit<StoredProcedure>) =>\n        hit.key.startsWith(prefix),\n      )\n      .map((hit: CacheSimilarHit<StoredProcedure>) => ({\n        id: hit.value.id,\n        text: hit.value.text,\n        tier: \"procedural\" as const,\n        score: this.blend(hit.score, hit.value.uses),\n        metadata: hit.value.metadata,\n      }))\n      .sort((first, second) => second.score - first.score)\n      .slice(0, k);\n  }\n\n  /** Drop every procedure written under this instance's namespace. */\n  public async clear(): Promise<void> {\n    await this.store.removeNamespace(this.namespace);\n  }\n\n  /**\n   * Combine raw similarity with a saturating reinforcement proxy:\n   * `(1 - w)·similarity + w·(uses / (uses + 1))`. A first-time procedure\n   * contributes `0.5`; each reinforcement nudges it toward `1` with\n   * diminishing returns. With `reinforcementWeight` 0 the score is pure\n   * similarity.\n   */\n  private blend(similarity: number, uses: number): number {\n    const reinforcement = uses / (uses + 1);\n\n    return (\n      (1 - this.reinforcementWeight) * similarity +\n      this.reinforcementWeight * reinforcement\n    );\n  }\n\n  /** Namespaced key for an entry — dot separator, matching `similar()` keys. */\n  private keyFor(id: string): string {\n    return `${this.namespace}.${id}`;\n  }\n}\n"],"mappings":";;;;;;;;;AA2BA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;AAwBxB,IAAa,mBAAb,MAA8B;CAC5B,AAAO,YACL,AAAiB,UACjB,AAAiB,OACjB,AAAiB,WACjB,AAAiB,qBACjB;EAJiB;EACA;EACA;EACA;CAChB;;;;;;;CAQH,MAAa,SAAS,MAAiC;EACrD,MAAM,KAAK,KAAK,MAAM,eAAe,KAAK,IAAI;EAC9C,MAAM,EAAE,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK,IAAI;EAEtD,MAAM,WAAW,MAAM,KAAK,MAAM,IAAqB,KAAK,OAAO,EAAE,CAAC;EACtE,MAAM,QAAQ,UAAU,QAAQ,KAAK;EAErC,MAAM,QAAyB;GAC7B;GACA,MAAM,KAAK;GACX;GACA,UAAU,KAAK,YAAY,UAAU;EACvC;EAEA,MAAM,KAAK,MAAM,IAAI,KAAK,OAAO,EAAE,GAAG,OAAO,EAAE,OAAO,CAAC;CACzD;;;;;;;CAQA,MAAa,OACX,OACA,GACA,WAC2B;EAC3B,MAAM,EAAE,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK;EAElD,MAAM,OAAO,MAAM,KAAK,MAAM,QAAyB,QAAQ;GAC7D,MAAM,KAAK,IAAI,IAAI,iBAAiB,CAAC;GACrC;EACF,CAAC;EAED,MAAM,SAAS,GAAG,KAAK,UAAU;EAEjC,OAAO,KACJ,QAAQ,QACP,IAAI,IAAI,WAAW,MAAM,CAC3B,CAAC,CACA,KAAK,SAA2C;GAC/C,IAAI,IAAI,MAAM;GACd,MAAM,IAAI,MAAM;GAChB,MAAM;GACN,OAAO,KAAK,MAAM,IAAI,OAAO,IAAI,MAAM,IAAI;GAC3C,UAAU,IAAI,MAAM;EACtB,EAAE,CAAC,CACF,MAAM,OAAO,WAAW,OAAO,QAAQ,MAAM,KAAK,CAAC,CACnD,MAAM,GAAG,CAAC;CACf;;CAGA,MAAa,QAAuB;EAClC,MAAM,KAAK,MAAM,gBAAgB,KAAK,SAAS;CACjD;;;;;;;;CASA,AAAQ,MAAM,YAAoB,MAAsB;EACtD,MAAM,gBAAgB,QAAQ,OAAO;EAErC,QACG,IAAI,KAAK,uBAAuB,aACjC,KAAK,sBAAsB;CAE/B;;CAGA,AAAQ,OAAO,IAAoB;EACjC,OAAO,GAAG,KAAK,UAAU,GAAG;CAC9B;AACF"}

package/esm/memory/semantic-memory.mjs

@@ -1,6 +1,6 @@
 import { deriveMemoryId } from "./derive-id.mjs";
 
-//#region ../@warlock.js/ai/src/memory/semantic-memory.ts
+//#region ../ai/src/memory/semantic-memory.ts
 /**
 * Semantic recall tier (memory core M1).
 *

package/esm/memory/semantic-memory.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"semantic-memory.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/memory/semantic-memory.ts"],"sourcesContent":["import type { CacheDriver, CacheSimilarHit } from \"@warlock.js/cache\";\nimport type { EmbedderContract } from \"../contracts/embedder.contract\";\nimport type {\n  MemoryItem,\n  RecalledMemory,\n} from \"../contracts/memory/memory-item.type\";\nimport { deriveMemoryId } from \"./derive-id\";\n\n/**\n * Shape persisted per semantic memory in the cache driver. The vector\n * itself is stored by the driver's own index (passed via\n * `set({ vector })`), so it is not duplicated in the value.\n */\ntype StoredMemory = {\n  id: string;\n  text: string;\n  metadata?: Record<string, unknown>;\n};\n\n/**\n * Semantic recall tier (memory core M1).\n *\n * Owns: embedding remembered text, writing it to a `@warlock.js/cache`\n * driver with `set({ vector })`, and retrieving by cosine similarity via\n * the driver's `similar()`. Does NOT own: the similarity algorithm or\n * the ANN index — those belong to the cache driver. This mirrors the\n * delegation model of `middleware/builtins/semantic-cache.ts`: memory is\n * embedding-agnostic and store-agnostic, gluing an {@link EmbedderContract}\n * to a {@link CacheDriver}.\n *\n * The driver may be shared across memory instances, so every key carries\n * the configured `namespace` and recall filters hits to that prefix —\n * foreign entries indexed by another instance never leak into a query.\n *\n * Internal to the `memory()` factory — never exported on the package\n * surface.\n */\nexport class SemanticMemory {\n  public constructor(\n    private readonly embedder: EmbedderContract,\n    private readonly store: CacheDriver<any, any>,\n    private readonly namespace: string,\n  ) {}\n\n  /**\n   * Embed the item's text and index it under a namespaced, id-derived\n   * key. Re-remembering the same id overwrites the prior vector +\n   * value (the driver upserts by key).\n   */\n  public async remember(item: MemoryItem): Promise<void> {\n    const id = item.id ?? deriveMemoryId(item.text);\n    const { vector } = await this.embedder.embed(item.text);\n\n    const value: StoredMemory = {\n      id,\n      text: item.text,\n      metadata: item.metadata,\n    };\n\n    await this.store.set(this.keyFor(id), value, { vector });\n  }\n\n  /**\n   * Embed `query`, ask the driver for the `k` nearest entries clearing\n   * `threshold`, and return those within this instance's namespace as\n   * scored {@link RecalledMemory}. Hits indexed under a different\n   * namespace (a shared driver) are filtered out.\n   */\n  public async recall(\n    query: string,\n    k: number,\n    threshold: number,\n  ): Promise<RecalledMemory[]> {\n    const { vector } = await this.embedder.embed(query);\n\n    const hits = await this.store.similar<StoredMemory>(vector, {\n      topK: k,\n      threshold,\n    });\n\n    const prefix = `${this.namespace}.`;\n\n    return hits\n      .filter((hit: CacheSimilarHit<StoredMemory>) =>\n        hit.key.startsWith(prefix),\n      )\n      .map((hit: CacheSimilarHit<StoredMemory>) => ({\n        id: hit.value.id,\n        text: hit.value.text,\n        tier: \"semantic\" as const,\n        score: hit.score,\n        metadata: hit.value.metadata,\n      }));\n  }\n\n  /** Drop every semantic entry written under this instance's namespace. */\n  public async clear(): Promise<void> {\n    await this.store.removeNamespace(this.namespace);\n  }\n\n  /**\n   * Namespaced key for an entry. The cache's `parseKey` normalizes `:`\n   * to `.`, so a dot separator keeps the prefix used here aligned with\n   * the `hit.key` the driver returns from `similar()`.\n   */\n  private keyFor(id: string): string {\n    return `${this.namespace}.${id}`;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAqCA,IAAa,iBAAb,MAA4B;CAC1B,AAAO,YACL,AAAiB,UACjB,AAAiB,OACjB,AAAiB,WACjB;EAHiB;EACA;EACA;CAChB;;;;;;CAOH,MAAa,SAAS,MAAiC;EACrD,MAAM,KAAK,KAAK,MAAM,eAAe,KAAK,IAAI;EAC9C,MAAM,EAAE,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK,IAAI;EAEtD,MAAM,QAAsB;GAC1B;GACA,MAAM,KAAK;GACX,UAAU,KAAK;EACjB;EAEA,MAAM,KAAK,MAAM,IAAI,KAAK,OAAO,EAAE,GAAG,OAAO,EAAE,OAAO,CAAC;CACzD;;;;;;;CAQA,MAAa,OACX,OACA,GACA,WAC2B;EAC3B,MAAM,EAAE,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK;EAElD,MAAM,OAAO,MAAM,KAAK,MAAM,QAAsB,QAAQ;GAC1D,MAAM;GACN;EACF,CAAC;EAED,MAAM,SAAS,GAAG,KAAK,UAAU;EAEjC,OAAO,KACJ,QAAQ,QACP,IAAI,IAAI,WAAW,MAAM,CAC3B,CAAC,CACA,KAAK,SAAwC;GAC5C,IAAI,IAAI,MAAM;GACd,MAAM,IAAI,MAAM;GAChB,MAAM;GACN,OAAO,IAAI;GACX,UAAU,IAAI,MAAM;EACtB,EAAE;CACN;;CAGA,MAAa,QAAuB;EAClC,MAAM,KAAK,MAAM,gBAAgB,KAAK,SAAS;CACjD;;;;;;CAOA,AAAQ,OAAO,IAAoB;EACjC,OAAO,GAAG,KAAK,UAAU,GAAG;CAC9B;AACF"}
+{"version":3,"file":"semantic-memory.mjs","names":[],"sources":["../../../../../../../ai/src/memory/semantic-memory.ts"],"sourcesContent":["import type { CacheDriver, CacheSimilarHit } from \"@warlock.js/cache\";\nimport type { EmbedderContract } from \"../contracts/embedder.contract\";\nimport type {\n  MemoryItem,\n  RecalledMemory,\n} from \"../contracts/memory/memory-item.type\";\nimport { deriveMemoryId } from \"./derive-id\";\n\n/**\n * Shape persisted per semantic memory in the cache driver. The vector\n * itself is stored by the driver's own index (passed via\n * `set({ vector })`), so it is not duplicated in the value.\n */\ntype StoredMemory = {\n  id: string;\n  text: string;\n  metadata?: Record<string, unknown>;\n};\n\n/**\n * Semantic recall tier (memory core M1).\n *\n * Owns: embedding remembered text, writing it to a `@warlock.js/cache`\n * driver with `set({ vector })`, and retrieving by cosine similarity via\n * the driver's `similar()`. Does NOT own: the similarity algorithm or\n * the ANN index — those belong to the cache driver. This mirrors the\n * delegation model of `middleware/builtins/semantic-cache.ts`: memory is\n * embedding-agnostic and store-agnostic, gluing an {@link EmbedderContract}\n * to a {@link CacheDriver}.\n *\n * The driver may be shared across memory instances, so every key carries\n * the configured `namespace` and recall filters hits to that prefix —\n * foreign entries indexed by another instance never leak into a query.\n *\n * Internal to the `memory()` factory — never exported on the package\n * surface.\n */\nexport class SemanticMemory {\n  public constructor(\n    private readonly embedder: EmbedderContract,\n    private readonly store: CacheDriver<any, any>,\n    private readonly namespace: string,\n  ) {}\n\n  /**\n   * Embed the item's text and index it under a namespaced, id-derived\n   * key. Re-remembering the same id overwrites the prior vector +\n   * value (the driver upserts by key).\n   */\n  public async remember(item: MemoryItem): Promise<void> {\n    const id = item.id ?? deriveMemoryId(item.text);\n    const { vector } = await this.embedder.embed(item.text);\n\n    const value: StoredMemory = {\n      id,\n      text: item.text,\n      metadata: item.metadata,\n    };\n\n    await this.store.set(this.keyFor(id), value, { vector });\n  }\n\n  /**\n   * Embed `query`, ask the driver for the `k` nearest entries clearing\n   * `threshold`, and return those within this instance's namespace as\n   * scored {@link RecalledMemory}. Hits indexed under a different\n   * namespace (a shared driver) are filtered out.\n   */\n  public async recall(\n    query: string,\n    k: number,\n    threshold: number,\n  ): Promise<RecalledMemory[]> {\n    const { vector } = await this.embedder.embed(query);\n\n    const hits = await this.store.similar<StoredMemory>(vector, {\n      topK: k,\n      threshold,\n    });\n\n    const prefix = `${this.namespace}.`;\n\n    return hits\n      .filter((hit: CacheSimilarHit<StoredMemory>) =>\n        hit.key.startsWith(prefix),\n      )\n      .map((hit: CacheSimilarHit<StoredMemory>) => ({\n        id: hit.value.id,\n        text: hit.value.text,\n        tier: \"semantic\" as const,\n        score: hit.score,\n        metadata: hit.value.metadata,\n      }));\n  }\n\n  /** Drop every semantic entry written under this instance's namespace. */\n  public async clear(): Promise<void> {\n    await this.store.removeNamespace(this.namespace);\n  }\n\n  /**\n   * Namespaced key for an entry. The cache's `parseKey` normalizes `:`\n   * to `.`, so a dot separator keeps the prefix used here aligned with\n   * the `hit.key` the driver returns from `similar()`.\n   */\n  private keyFor(id: string): string {\n    return `${this.namespace}.${id}`;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAqCA,IAAa,iBAAb,MAA4B;CAC1B,AAAO,YACL,AAAiB,UACjB,AAAiB,OACjB,AAAiB,WACjB;EAHiB;EACA;EACA;CAChB;;;;;;CAOH,MAAa,SAAS,MAAiC;EACrD,MAAM,KAAK,KAAK,MAAM,eAAe,KAAK,IAAI;EAC9C,MAAM,EAAE,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK,IAAI;EAEtD,MAAM,QAAsB;GAC1B;GACA,MAAM,KAAK;GACX,UAAU,KAAK;EACjB;EAEA,MAAM,KAAK,MAAM,IAAI,KAAK,OAAO,EAAE,GAAG,OAAO,EAAE,OAAO,CAAC;CACzD;;;;;;;CAQA,MAAa,OACX,OACA,GACA,WAC2B;EAC3B,MAAM,EAAE,WAAW,MAAM,KAAK,SAAS,MAAM,KAAK;EAElD,MAAM,OAAO,MAAM,KAAK,MAAM,QAAsB,QAAQ;GAC1D,MAAM;GACN;EACF,CAAC;EAED,MAAM,SAAS,GAAG,KAAK,UAAU;EAEjC,OAAO,KACJ,QAAQ,QACP,IAAI,IAAI,WAAW,MAAM,CAC3B,CAAC,CACA,KAAK,SAAwC;GAC5C,IAAI,IAAI,MAAM;GACd,MAAM,IAAI,MAAM;GAChB,MAAM;GACN,OAAO,IAAI;GACX,UAAU,IAAI,MAAM;EACtB,EAAE;CACN;;CAGA,MAAa,QAAuB;EAClC,MAAM,KAAK,MAAM,gBAAgB,KAAK,SAAS;CACjD;;;;;;CAOA,AAAQ,OAAO,IAAoB;EACjC,OAAO,GAAG,KAAK,UAAU,GAAG;CAC9B;AACF"}

package/esm/memory/working-memory.mjs

@@ -1,6 +1,6 @@
 import { deriveMemoryId } from "./derive-id.mjs";
 
-//#region ../@warlock.js/ai/src/memory/working-memory.ts
+//#region ../ai/src/memory/working-memory.ts
 /**
 * In-run working memory — the volatile scratch tier (memory core M1).
 *

package/esm/memory/working-memory.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"working-memory.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/memory/working-memory.ts"],"sourcesContent":["import type {\n  MemoryItem,\n  RecalledMemory,\n} from \"../contracts/memory/memory-item.type\";\nimport { deriveMemoryId } from \"./derive-id\";\n\n/**\n * In-run working memory — the volatile scratch tier (memory core M1).\n *\n * Owns: an insertion-ordered buffer of remembered items keyed by id,\n * with overwrite-in-place on a repeated id. Does NOT own: durability,\n * cross-process sharing, embeddings, or similarity — working memory is\n * a plain in-process buffer the orchestrator threads across the turns of\n * a single run.\n *\n * Recall here is not semantic: with no vector index, \"relevant\" reduces\n * to \"recent.\" `recall()` returns the most-recently-remembered items\n * first, each scored on a `[0, 1]` recency proxy so a caller can merge\n * working hits with semantic hits and sort on one `score` field.\n *\n * Internal to the `memory()` factory — never exported on the package\n * surface.\n */\nexport class WorkingMemory {\n  /**\n   * Id → text/metadata. A `Map` preserves insertion order, so iteration\n   * yields oldest-first; recall reverses it for most-recent-first.\n   */\n  private readonly entries = new Map<\n    string,\n    { text: string; metadata?: Record<string, unknown> }\n  >();\n\n  /**\n   * Append an item to the buffer (or overwrite the entry sharing its\n   * id). Re-inserting an existing id keeps its original position; delete\n   * + set would move it to the end and lie about recency, so the value\n   * is updated in place.\n   */\n  public remember(item: MemoryItem): void {\n    const id = item.id ?? deriveMemoryId(item.text);\n\n    this.entries.set(id, { text: item.text, metadata: item.metadata });\n  }\n\n  /**\n   * Return up to `k` most-recently-remembered items, newest first. The\n   * `score` is a linear recency proxy: the newest item scores `1`, the\n   * oldest of the returned slice trends toward `0`. Working memory\n   * ignores any similarity threshold — it has no vector to compare.\n   */\n  public recall(k: number): RecalledMemory[] {\n    const ordered = [...this.entries.entries()].reverse();\n    const slice = ordered.slice(0, Math.max(0, k));\n\n    return slice.map(([id, entry], index) => ({\n      id,\n      text: entry.text,\n      tier: \"working\" as const,\n      score: slice.length <= 1 ? 1 : 1 - index / slice.length,\n      metadata: entry.metadata,\n    }));\n  }\n\n  /** Drop every working-tier entry. */\n  public clear(): void {\n    this.entries.clear();\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAuBA,IAAa,gBAAb,MAA2B;;iCAKE,IAAI,IAG7B;;;;;;;;CAQF,AAAO,SAAS,MAAwB;EACtC,MAAM,KAAK,KAAK,MAAM,eAAe,KAAK,IAAI;EAE9C,KAAK,QAAQ,IAAI,IAAI;GAAE,MAAM,KAAK;GAAM,UAAU,KAAK;EAAS,CAAC;CACnE;;;;;;;CAQA,AAAO,OAAO,GAA6B;EAEzC,MAAM,QADU,CAAC,GAAG,KAAK,QAAQ,QAAQ,CAAC,CAAC,CAAC,QACxB,CAAC,CAAC,MAAM,GAAG,KAAK,IAAI,GAAG,CAAC,CAAC;EAE7C,OAAO,MAAM,KAAK,CAAC,IAAI,QAAQ,WAAW;GACxC;GACA,MAAM,MAAM;GACZ,MAAM;GACN,OAAO,MAAM,UAAU,IAAI,IAAI,IAAI,QAAQ,MAAM;GACjD,UAAU,MAAM;EAClB,EAAE;CACJ;;CAGA,AAAO,QAAc;EACnB,KAAK,QAAQ,MAAM;CACrB;AACF"}
+{"version":3,"file":"working-memory.mjs","names":[],"sources":["../../../../../../../ai/src/memory/working-memory.ts"],"sourcesContent":["import type {\n  MemoryItem,\n  RecalledMemory,\n} from \"../contracts/memory/memory-item.type\";\nimport { deriveMemoryId } from \"./derive-id\";\n\n/**\n * In-run working memory — the volatile scratch tier (memory core M1).\n *\n * Owns: an insertion-ordered buffer of remembered items keyed by id,\n * with overwrite-in-place on a repeated id. Does NOT own: durability,\n * cross-process sharing, embeddings, or similarity — working memory is\n * a plain in-process buffer the orchestrator threads across the turns of\n * a single run.\n *\n * Recall here is not semantic: with no vector index, \"relevant\" reduces\n * to \"recent.\" `recall()` returns the most-recently-remembered items\n * first, each scored on a `[0, 1]` recency proxy so a caller can merge\n * working hits with semantic hits and sort on one `score` field.\n *\n * Internal to the `memory()` factory — never exported on the package\n * surface.\n */\nexport class WorkingMemory {\n  /**\n   * Id → text/metadata. A `Map` preserves insertion order, so iteration\n   * yields oldest-first; recall reverses it for most-recent-first.\n   */\n  private readonly entries = new Map<\n    string,\n    { text: string; metadata?: Record<string, unknown> }\n  >();\n\n  /**\n   * Append an item to the buffer (or overwrite the entry sharing its\n   * id). Re-inserting an existing id keeps its original position; delete\n   * + set would move it to the end and lie about recency, so the value\n   * is updated in place.\n   */\n  public remember(item: MemoryItem): void {\n    const id = item.id ?? deriveMemoryId(item.text);\n\n    this.entries.set(id, { text: item.text, metadata: item.metadata });\n  }\n\n  /**\n   * Return up to `k` most-recently-remembered items, newest first. The\n   * `score` is a linear recency proxy: the newest item scores `1`, the\n   * oldest of the returned slice trends toward `0`. Working memory\n   * ignores any similarity threshold — it has no vector to compare.\n   */\n  public recall(k: number): RecalledMemory[] {\n    const ordered = [...this.entries.entries()].reverse();\n    const slice = ordered.slice(0, Math.max(0, k));\n\n    return slice.map(([id, entry], index) => ({\n      id,\n      text: entry.text,\n      tier: \"working\" as const,\n      score: slice.length <= 1 ? 1 : 1 - index / slice.length,\n      metadata: entry.metadata,\n    }));\n  }\n\n  /** Drop every working-tier entry. */\n  public clear(): void {\n    this.entries.clear();\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAuBA,IAAa,gBAAb,MAA2B;;iCAKE,IAAI,IAG7B;;;;;;;;CAQF,AAAO,SAAS,MAAwB;EACtC,MAAM,KAAK,KAAK,MAAM,eAAe,KAAK,IAAI;EAE9C,KAAK,QAAQ,IAAI,IAAI;GAAE,MAAM,KAAK;GAAM,UAAU,KAAK;EAAS,CAAC;CACnE;;;;;;;CAQA,AAAO,OAAO,GAA6B;EAEzC,MAAM,QADU,CAAC,GAAG,KAAK,QAAQ,QAAQ,CAAC,CAAC,CAAC,QACxB,CAAC,CAAC,MAAM,GAAG,KAAK,IAAI,GAAG,CAAC,CAAC;EAE7C,OAAO,MAAM,KAAK,CAAC,IAAI,QAAQ,WAAW;GACxC;GACA,MAAM,MAAM;GACZ,MAAM;GACN,OAAO,MAAM,UAAU,IAAI,IAAI,IAAI,QAAQ,MAAM;GACjD,UAAU,MAAM;EAClB,EAAE;CACJ;;CAGA,AAAO,QAAc;EACnB,KAAK,QAAQ,MAAM;CACrB;AACF"}

package/esm/middleware/builtins/budget-contract.type.d.mts

@@ -1,5 +1,5 @@
 import { MiddlewareExecuteContext } from "../../contracts/middleware/middleware-context.type.mjs";
-//#region ../@warlock.js/ai/src/middleware/builtins/budget-contract.type.d.ts
+//#region ../ai/src/middleware/builtins/budget-contract.type.d.ts
 /**
  * Which SLO dimension of a {@link BudgetContract} a breach belongs to.
  *

package/esm/middleware/builtins/budget-contract.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"budget-contract.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/builtins/budget-contract.type.ts"],"mappings":";;;;;AAYA;;;;AAAmC;AAkBnC;;KAlBY,uBAAA;;AAkB2B;AAUvC;;;;;;;;;;;AAQmC;AAenC;;KAjCY,2BAAA;;;;;;;;;KAUA,uBAAA;EA0BA,qCAxBV,SAAA,EAAW,uBAAA,EAwBM;EAtBjB,KAAA,UA4DwB;EA1DxB,MAAA,UAsFiC;EApFjC,IAAA,EAAM,2BAA2B;AAAA;;;;;;;AAoFA;;;;;;KArEvB,sBAAA,IACV,SAAA,EAAW,uBAAA,EACX,OAAA,EAAS,wBAAA,YACC,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAsCA,cAAA;;;;;EAKV,SAAA;;;;;;EAMA,UAAA;;;;;;EAMA,YAAA;;;;;;EAMA,WAAA,GAAc,2BAAA;;;;;EAKd,QAAA,GAAW,sBAAsB;AAAA"}
+{"version":3,"file":"budget-contract.type.d.mts","names":[],"sources":["../../../../../../../../ai/src/middleware/builtins/budget-contract.type.ts"],"mappings":";;;;;AAYA;;;;AAAmC;AAkBnC;;KAlBY,uBAAA;;AAkB2B;AAUvC;;;;;;;;;;;AAQmC;AAenC;;KAjCY,2BAAA;;;;;;;;;KAUA,uBAAA;EA0BA,qCAxBV,SAAA,EAAW,uBAAA,EAwBM;EAtBjB,KAAA,UA4DwB;EA1DxB,MAAA,UAsFiC;EApFjC,IAAA,EAAM,2BAA2B;AAAA;;;;;;;AAoFA;;;;;;KArEvB,sBAAA,IACV,SAAA,EAAW,uBAAA,EACX,OAAA,EAAS,wBAAA,YACC,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAsCA,cAAA;;;;;EAKV,SAAA;;;;;;EAMA,UAAA;;;;;;EAMA,YAAA;;;;;;EAMA,WAAA,GAAc,2BAAA;;;;;EAKd,QAAA,GAAW,sBAAsB;AAAA"}

package/esm/middleware/builtins/budget.d.mts

@@ -2,7 +2,7 @@ import { MiddlewareExecuteContext } from "../../contracts/middleware/middleware-
 import { AgentMiddleware } from "../../contracts/middleware/middleware.contract.mjs";
 import { BudgetContract, BudgetContractDimension, BudgetContractFallback, BudgetContractViolation, BudgetContractViolationMode } from "./budget-contract.type.mjs";
 
-//#region ../@warlock.js/ai/src/middleware/builtins/budget.d.ts
+//#region ../ai/src/middleware/builtins/budget.d.ts
 /**
  * Per-model pricing used to compute USD cost from token counts.
  * Caller-supplied — no bundled table. Keys are model names (the

package/esm/middleware/builtins/budget.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"budget.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/builtins/budget.ts"],"mappings":";;;;;;;;AA2BA;;;;KAAY,aAAA,GAAgB,MAAM;EAI9B,kCAAA,UAAA,UAEW;EAAX,WAAA;AAAA;;;;;KAQQ,aAAA;EAkBV;;;;;EAZA,SAAA;EAsCyB;AAAA;AAyB3B;;;EAzDE,UAAA;EAyDwD;AAoE1D;;;;EAvHE,OAAA,GAAU,aAAA;EAwHV;;;;AAEqB;AA8EvB;;EAhME,UAAA;EAgM6D;;;;;EA1L7D,IAAA;;;;;;;;;;;;EAYA,QAAA,GAAW,cAAc;AAAA;;;;;;KAyBf,oBAAA,GAAuB,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoE1C,wBAAA,CACd,KAAA,EAAO,wBAAA,WACP,IAAA,YACC,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8EP,MAAA,CAAO,OAAA,EAAS,aAAA,GAAgB,eAAe"}
+{"version":3,"file":"budget.d.mts","names":[],"sources":["../../../../../../../../ai/src/middleware/builtins/budget.ts"],"mappings":";;;;;;;;AA2BA;;;;KAAY,aAAA,GAAgB,MAAM;EAI9B,kCAAA,UAAA,UAEW;EAAX,WAAA;AAAA;;;;;KAQQ,aAAA;EAkBV;;;;;EAZA,SAAA;EAsCyB;AAAA;AAyB3B;;;EAzDE,UAAA;EAyDwD;AAoE1D;;;;EAvHE,OAAA,GAAU,aAAA;EAwHV;;;;AAEqB;AA8EvB;;EAhME,UAAA;EAgM6D;;;;;EA1L7D,IAAA;;;;;;;;;;;;EAYA,QAAA,GAAW,cAAc;AAAA;;;;;;KAyBf,oBAAA,GAAuB,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoE1C,wBAAA,CACd,KAAA,EAAO,wBAAA,WACP,IAAA,YACC,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8EP,MAAA,CAAO,OAAA,EAAS,aAAA,GAAgB,eAAe"}

package/esm/middleware/builtins/budget.mjs

@@ -2,7 +2,7 @@ import { BudgetExceededError } from "../../errors/budget-exceeded-error.mjs";
 import "../../errors/index.mjs";
 import { namespacedState } from "../utils/namespaced-state.mjs";
 
-//#region ../@warlock.js/ai/src/middleware/builtins/budget.ts
+//#region ../ai/src/middleware/builtins/budget.ts
 /**
 * The `BudgetUnit` to stamp on the thrown error per contract dimension.
 * Latency has no native unit — it borrows `"requests"` as the least-wrong

package/esm/middleware/builtins/budget.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"budget.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/builtins/budget.ts"],"sourcesContent":["import type {\n  AgentMiddleware,\n  MiddlewareExecuteContext,\n} from \"../../contracts/middleware\";\nimport { BudgetExceededError, type BudgetUnit } from \"../../errors\";\nimport { namespacedState } from \"../utils\";\nimport type {\n  BudgetContract,\n  BudgetContractDimension,\n  BudgetContractViolation,\n} from \"./budget-contract.type\";\n\nexport type {\n  BudgetContract,\n  BudgetContractDimension,\n  BudgetContractFallback,\n  BudgetContractViolation,\n  BudgetContractViolationMode,\n} from \"./budget-contract.type\";\n\n/**\n * Per-model pricing used to compute USD cost from token counts.\n * Caller-supplied — no bundled table. Keys are model names (the\n * `ModelContract.name` value); values are input / output token\n * prices expressed as **USD per 1K tokens** to match every major\n * provider's published pricing sheet.\n */\nexport type BudgetPricing = Record<\n  string,\n  {\n    /** USD per 1,000 input tokens. */\n    inputPer1K: number;\n    /** USD per 1,000 output tokens. */\n    outputPer1K: number;\n  }\n>;\n\n/**\n * Configuration for `budget()`. At least one of `maxTokens` or\n * `maxCostUSD` must be supplied — a budget with no cap is a no-op.\n */\nexport type BudgetOptions = {\n  /**\n   * Hard cap on cumulative total tokens (input + output, summed\n   * across every trip of the run). Inclusive — exceeding triggers\n   * the configured `onExceeded`.\n   */\n  maxTokens?: number;\n  /**\n   * Hard cap on cumulative USD cost. Requires `pricing` for the\n   * agent's configured model — without a pricing entry the USD check\n   * silently skips (tokens-only enforcement still applies).\n   */\n  maxCostUSD?: number;\n  /**\n   * Per-model pricing table used to compute USD cost. Only consulted\n   * when `maxCostUSD` is set. Model names must match the running\n   * agent's `ModelContract.name` exactly.\n   */\n  pricing?: BudgetPricing;\n  /**\n   * Behavior when a cap is breached. `\"abort\"` throws\n   * `BudgetExceededError` — surfaces on `result.error`, stops the\n   * run at the next trip boundary. `\"warn\"` logs a warning and\n   * lets the run continue (useful for observability-first rollouts\n   * before flipping the switch to abort). Default `\"abort\"`.\n   */\n  onExceeded?: \"abort\" | \"warn\";\n  /**\n   * Override the middleware name. Useful when two budgets coexist\n   * (e.g. a per-request cap plus a session-wide cap via different\n   * instances). Default `\"budget\"`.\n   */\n  name?: string;\n  /**\n   * Declarative SLO / cost contract enforced on top of (and\n   * independently of) the legacy `maxTokens` / `maxCostUSD` caps.\n   * Adds a wall-clock `maxLatencyMs` dimension and a per-contract\n   * `onViolation` reaction (`\"abort\"` hard-stops, `\"fallback\"` records\n   * a signal + fires `fallback` and lets the run continue). Omit to\n   * keep the classic budget behavior unchanged.\n   *\n   * Read a recorded fallback signal back with\n   * {@link readBudgetFallbackSignal}.\n   */\n  contract?: BudgetContract;\n};\n\ntype BudgetCounters = {\n  tokens: number;\n  costUSD: number;\n  warned: boolean;\n  /**\n   * Wall-clock epoch ms captured at `execute.before`. Used to derive\n   * cumulative run latency for the contract's `maxLatencyMs` clause.\n   */\n  startedAt: number;\n  /**\n   * Set once a `\"fallback\"` contract clause has fired, so the signal +\n   * callback are emitted at most once per run even if later trips keep\n   * breaching.\n   */\n  fallbackFired: boolean;\n};\n\n/**\n * Recorded contract fallback signal, stashed under the `<name>.fallback`\n * state key when a `\"fallback\"` clause trips. A fallback orchestrator\n * reads it via {@link readBudgetFallbackSignal} to decide how to degrade.\n */\nexport type BudgetFallbackSignal = BudgetContractViolation;\n\n/**\n * The `BudgetUnit` to stamp on the thrown error per contract dimension.\n * Latency has no native unit — it borrows `\"requests\"` as the least-wrong\n * operational measure, while the authoritative detail rides on the\n * error's `context.dimension`.\n */\nconst DIMENSION_UNIT: Record<BudgetContractDimension, BudgetUnit> = {\n  tokens: \"tokens\",\n  cost: \"usd\",\n  latency: \"requests\",\n};\n\nfunction breach(\n  limit: number,\n  actual: number,\n  unit: BudgetUnit,\n  name: string,\n): never {\n  throw new BudgetExceededError(\n    `budget \"${name}\" exceeded — ${actual} ${unit} (cap: ${limit})`,\n    { limit, actual, unit },\n  );\n}\n\nfunction breachContract(\n  name: string,\n  dimension: BudgetContractDimension,\n  limit: number,\n  actual: number,\n): never {\n  throw new BudgetExceededError(\n    `budget \"${name}\" contract exceeded — ${dimension} ${actual} (cap: ${limit})`,\n    {\n      limit,\n      actual,\n      unit: DIMENSION_UNIT[dimension],\n      context: { dimension, limit, actual, source: \"contract\" },\n    },\n  );\n}\n\n/**\n * Read the contract fallback signal recorded by a `budget()` middleware\n * running under `contract.onViolation: \"fallback\"`. Returns `undefined`\n * when no clause was breached.\n *\n * **Role.** The middleware cannot itself switch models on a soft breach,\n * so it records a typed {@link BudgetFallbackSignal} in the shared state\n * bag and lets the run continue. A fallback orchestrator (or the\n * `execute.after` hook of an outer middleware) reads it back here and\n * decides how to degrade the next run — cheaper model, cached answer,\n * truncated context.\n *\n * @param state - The middleware state bag (`ctx.state`).\n * @param name - The budget middleware's name. Default `\"budget\"`,\n *   matching `BudgetOptions.name`'s default.\n *\n * @example\n * const guard = budget({ contract: { maxCostUSD: 0.05, onViolation: \"fallback\" } });\n *\n * // In an outer middleware's execute.after, after the run:\n * const signal = readBudgetFallbackSignal(ctx.state);\n * if (signal?.dimension === \"cost\") {\n *   await rerunOnCheaperModel();\n * }\n */\nexport function readBudgetFallbackSignal(\n  state: MiddlewareExecuteContext[\"state\"],\n  name = \"budget\",\n): BudgetFallbackSignal | undefined {\n  return namespacedState<BudgetFallbackSignal>(\n    { state },\n    `${name}.fallback`,\n  ).get();\n}\n\n/**\n * Enforced token and / or USD budget for an agent run.\n *\n * **Role.** Guards against runaway tool loops, misconfigured\n * prompts, and unexpected provider price swings by capping\n * cumulative usage across every LLM trip of a single execution.\n * Aborts the run with a typed `BudgetExceededError` the moment a cap\n * is breached, rather than letting the damage grow trip by trip.\n *\n * **Scope.** Per-execution. A fresh counter is created at\n * `execute.before` and lives in the middleware state bag until the\n * run ends. Two concurrent `agent.execute()` calls on the same\n * agent therefore enforce the cap independently.\n *\n * **Token accounting.** After each successful trip, the middleware\n * adds `response.usage.total` to its running total and checks\n * against `maxTokens`. Synthetic trips (cache hits) contribute\n * `usage.total` as returned by the cache — cache middleware is\n * expected to surface zero usage on a hit, which naturally excludes\n * those trips from the budget.\n *\n * **USD accounting.** When `maxCostUSD` + `pricing[modelName]` are\n * both present, the middleware converts per-trip input / output\n * tokens to USD and accumulates. Missing pricing silently degrades\n * to tokens-only — explicit rather than guessing.\n *\n * **Warn mode.** `onExceeded: \"warn\"` logs a single warning the first\n * time a cap is breached and lets the run continue. Useful for\n * measuring real-world traffic against a proposed cap before flipping\n * to `\"abort\"` in production.\n *\n * **Contract / SLO mode.** Pass `contract` to enforce a declarative\n * service-level objective — `maxCostUSD`, `maxLatencyMs`, `maxTokens` —\n * on top of the legacy caps, with a single `onViolation` reaction:\n * `\"abort\"` hard-stops with `BudgetExceededError`; `\"fallback\"` records\n * a typed signal (read it via {@link readBudgetFallbackSignal}), fires\n * the optional `fallback` callback, and lets the run continue so an\n * outer layer can degrade gracefully. The contract's clauses are\n * evaluated independently of — and after — the top-level caps; the\n * top-level caps stay fully functional with or without a contract.\n *\n * @example\n * const budgetMiddleware = budget({ maxTokens: 50_000 });\n *\n * const myAgent = agent({\n *   model,\n *   middleware: [budgetMiddleware],\n * });\n *\n * @example\n * // With USD cap and custom pricing\n * const guard = budget({\n *   maxCostUSD: 0.5,\n *   pricing: {\n *     \"gpt-4o\": { inputPer1K: 0.005, outputPer1K: 0.015 },\n *   },\n * });\n *\n * @example\n * // SLO contract — soft-fallback on any breach\n * const sloGuard = budget({\n *   pricing: { \"gpt-4o\": { inputPer1K: 0.005, outputPer1K: 0.015 } },\n *   contract: {\n *     maxCostUSD: 0.05,\n *     maxLatencyMs: 8_000,\n *     maxTokens: 40_000,\n *     onViolation: \"fallback\",\n *     fallback: (violation) => routeToCheaperModel(violation.dimension),\n *   },\n * });\n */\nexport function budget(options: BudgetOptions): AgentMiddleware {\n  const name = options.name ?? \"budget\";\n  const onExceeded = options.onExceeded ?? \"abort\";\n  const hasTokenCap = typeof options.maxTokens === \"number\";\n  const hasCostCap = typeof options.maxCostUSD === \"number\";\n\n  const contract = options.contract;\n  const contractMode = contract?.onViolation ?? \"abort\";\n  const hasContractTokenCap = typeof contract?.maxTokens === \"number\";\n  const hasContractCostCap = typeof contract?.maxCostUSD === \"number\";\n  const hasContractLatencyCap = typeof contract?.maxLatencyMs === \"number\";\n  const contractNeedsCost = hasCostCap || hasContractCostCap;\n  // Warn once per model when a cost cap is configured but the running model\n  // has no pricing entry — without this the USD cap silently never enforces\n  // (costUSD stays 0), a fail-open the JSDoc on `maxCostUSD` documents.\n  const warnedUnpricedModels = new Set<string>();\n\n  return {\n    name,\n    execute: {\n      before(context) {\n        const counters = namespacedState<BudgetCounters>(context, name);\n        counters.set({\n          tokens: 0,\n          costUSD: 0,\n          warned: false,\n          startedAt: Date.now(),\n          fallbackFired: false,\n        });\n      },\n    },\n    trip: {\n      async after(context, response) {\n        const counters = namespacedState<BudgetCounters>(context, name).get();\n\n        if (!counters) {\n          return;\n        }\n\n        counters.tokens += response.usage.total;\n\n        if (contractNeedsCost) {\n          const pricing = options.pricing?.[context.model.name];\n\n          if (pricing) {\n            const tripCost =\n              (response.usage.input / 1000) * pricing.inputPer1K +\n              (response.usage.output / 1000) * pricing.outputPer1K;\n            counters.costUSD += tripCost;\n          } else if (!warnedUnpricedModels.has(context.model.name)) {\n            // A cost cap is set but no pricing matched the running model, so\n            // costUSD can never grow and the USD cap silently never fires.\n            // Surface the fail-open once per model instead of swallowing it.\n            warnedUnpricedModels.add(context.model.name);\n            console.warn(\n              `ai.middleware.budget(\"${name}\"): a USD cost cap is set but no pricing entry ` +\n                `matches the running model \"${context.model.name}\" — the cap cannot be enforced ` +\n                `for it. Add a pricing entry for \"${context.model.name}\" to options.pricing.`,\n            );\n          }\n        }\n\n        if (hasTokenCap && counters.tokens > options.maxTokens!) {\n          if (onExceeded === \"abort\") {\n            breach(options.maxTokens!, counters.tokens, \"tokens\", name);\n          }\n\n          if (!counters.warned) {\n            counters.warned = true;\n          }\n        }\n\n        if (hasCostCap && counters.costUSD > options.maxCostUSD!) {\n          if (onExceeded === \"abort\") {\n            breach(options.maxCostUSD!, counters.costUSD, \"usd\", name);\n          }\n\n          if (!counters.warned) {\n            counters.warned = true;\n          }\n        }\n\n        if (!contract) {\n          return;\n        }\n\n        if (hasContractTokenCap && counters.tokens > contract.maxTokens!) {\n          await enforceContract(\n            context,\n            counters,\n            name,\n            contractMode,\n            contract,\n            \"tokens\",\n            contract.maxTokens!,\n            counters.tokens,\n          );\n        }\n\n        if (hasContractCostCap && counters.costUSD > contract.maxCostUSD!) {\n          await enforceContract(\n            context,\n            counters,\n            name,\n            contractMode,\n            contract,\n            \"cost\",\n            contract.maxCostUSD!,\n            counters.costUSD,\n          );\n        }\n\n        if (hasContractLatencyCap) {\n          const elapsedMs = Date.now() - counters.startedAt;\n\n          if (elapsedMs > contract.maxLatencyMs!) {\n            await enforceContract(\n              context,\n              counters,\n              name,\n              contractMode,\n              contract,\n              \"latency\",\n              contract.maxLatencyMs!,\n              elapsedMs,\n            );\n          }\n        }\n      },\n    },\n  };\n}\n\n/**\n * Apply the contract's reaction to a single breached clause. `\"abort\"`\n * throws `BudgetExceededError` (stops the run); `\"fallback\"` records the\n * signal once, fires the callback, and returns so the run continues.\n *\n * The callback is invoked at most once per run (guarded by\n * `counters.fallbackFired`) and its rejections are swallowed — a buggy\n * fallback hook must never crash the agent.\n */\nasync function enforceContract(\n  context: MiddlewareExecuteContext,\n  counters: BudgetCounters,\n  name: string,\n  mode: NonNullable<BudgetContract[\"onViolation\"]>,\n  contract: BudgetContract,\n  dimension: BudgetContractDimension,\n  limit: number,\n  actual: number,\n): Promise<void> {\n  if (mode === \"abort\") {\n    breachContract(name, dimension, limit, actual);\n  }\n\n  if (counters.fallbackFired) {\n    return;\n  }\n\n  counters.fallbackFired = true;\n\n  const violation: BudgetContractViolation = {\n    dimension,\n    limit,\n    actual,\n    mode,\n  };\n\n  namespacedState<BudgetContractViolation>(context, `${name}.fallback`).set(\n    violation,\n  );\n\n  if (!contract.fallback) {\n    return;\n  }\n\n  try {\n    await contract.fallback(violation, context);\n  } catch {\n    // A fallback callback is a notification hook — its failure must\n    // never crash the run. Swallow deliberately.\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"budget.mjs","names":[],"sources":["../../../../../../../../ai/src/middleware/builtins/budget.ts"],"sourcesContent":["import type {\n  AgentMiddleware,\n  MiddlewareExecuteContext,\n} from \"../../contracts/middleware\";\nimport { BudgetExceededError, type BudgetUnit } from \"../../errors\";\nimport { namespacedState } from \"../utils\";\nimport type {\n  BudgetContract,\n  BudgetContractDimension,\n  BudgetContractViolation,\n} from \"./budget-contract.type\";\n\nexport type {\n  BudgetContract,\n  BudgetContractDimension,\n  BudgetContractFallback,\n  BudgetContractViolation,\n  BudgetContractViolationMode,\n} from \"./budget-contract.type\";\n\n/**\n * Per-model pricing used to compute USD cost from token counts.\n * Caller-supplied — no bundled table. Keys are model names (the\n * `ModelContract.name` value); values are input / output token\n * prices expressed as **USD per 1K tokens** to match every major\n * provider's published pricing sheet.\n */\nexport type BudgetPricing = Record<\n  string,\n  {\n    /** USD per 1,000 input tokens. */\n    inputPer1K: number;\n    /** USD per 1,000 output tokens. */\n    outputPer1K: number;\n  }\n>;\n\n/**\n * Configuration for `budget()`. At least one of `maxTokens` or\n * `maxCostUSD` must be supplied — a budget with no cap is a no-op.\n */\nexport type BudgetOptions = {\n  /**\n   * Hard cap on cumulative total tokens (input + output, summed\n   * across every trip of the run). Inclusive — exceeding triggers\n   * the configured `onExceeded`.\n   */\n  maxTokens?: number;\n  /**\n   * Hard cap on cumulative USD cost. Requires `pricing` for the\n   * agent's configured model — without a pricing entry the USD check\n   * silently skips (tokens-only enforcement still applies).\n   */\n  maxCostUSD?: number;\n  /**\n   * Per-model pricing table used to compute USD cost. Only consulted\n   * when `maxCostUSD` is set. Model names must match the running\n   * agent's `ModelContract.name` exactly.\n   */\n  pricing?: BudgetPricing;\n  /**\n   * Behavior when a cap is breached. `\"abort\"` throws\n   * `BudgetExceededError` — surfaces on `result.error`, stops the\n   * run at the next trip boundary. `\"warn\"` logs a warning and\n   * lets the run continue (useful for observability-first rollouts\n   * before flipping the switch to abort). Default `\"abort\"`.\n   */\n  onExceeded?: \"abort\" | \"warn\";\n  /**\n   * Override the middleware name. Useful when two budgets coexist\n   * (e.g. a per-request cap plus a session-wide cap via different\n   * instances). Default `\"budget\"`.\n   */\n  name?: string;\n  /**\n   * Declarative SLO / cost contract enforced on top of (and\n   * independently of) the legacy `maxTokens` / `maxCostUSD` caps.\n   * Adds a wall-clock `maxLatencyMs` dimension and a per-contract\n   * `onViolation` reaction (`\"abort\"` hard-stops, `\"fallback\"` records\n   * a signal + fires `fallback` and lets the run continue). Omit to\n   * keep the classic budget behavior unchanged.\n   *\n   * Read a recorded fallback signal back with\n   * {@link readBudgetFallbackSignal}.\n   */\n  contract?: BudgetContract;\n};\n\ntype BudgetCounters = {\n  tokens: number;\n  costUSD: number;\n  warned: boolean;\n  /**\n   * Wall-clock epoch ms captured at `execute.before`. Used to derive\n   * cumulative run latency for the contract's `maxLatencyMs` clause.\n   */\n  startedAt: number;\n  /**\n   * Set once a `\"fallback\"` contract clause has fired, so the signal +\n   * callback are emitted at most once per run even if later trips keep\n   * breaching.\n   */\n  fallbackFired: boolean;\n};\n\n/**\n * Recorded contract fallback signal, stashed under the `<name>.fallback`\n * state key when a `\"fallback\"` clause trips. A fallback orchestrator\n * reads it via {@link readBudgetFallbackSignal} to decide how to degrade.\n */\nexport type BudgetFallbackSignal = BudgetContractViolation;\n\n/**\n * The `BudgetUnit` to stamp on the thrown error per contract dimension.\n * Latency has no native unit — it borrows `\"requests\"` as the least-wrong\n * operational measure, while the authoritative detail rides on the\n * error's `context.dimension`.\n */\nconst DIMENSION_UNIT: Record<BudgetContractDimension, BudgetUnit> = {\n  tokens: \"tokens\",\n  cost: \"usd\",\n  latency: \"requests\",\n};\n\nfunction breach(\n  limit: number,\n  actual: number,\n  unit: BudgetUnit,\n  name: string,\n): never {\n  throw new BudgetExceededError(\n    `budget \"${name}\" exceeded — ${actual} ${unit} (cap: ${limit})`,\n    { limit, actual, unit },\n  );\n}\n\nfunction breachContract(\n  name: string,\n  dimension: BudgetContractDimension,\n  limit: number,\n  actual: number,\n): never {\n  throw new BudgetExceededError(\n    `budget \"${name}\" contract exceeded — ${dimension} ${actual} (cap: ${limit})`,\n    {\n      limit,\n      actual,\n      unit: DIMENSION_UNIT[dimension],\n      context: { dimension, limit, actual, source: \"contract\" },\n    },\n  );\n}\n\n/**\n * Read the contract fallback signal recorded by a `budget()` middleware\n * running under `contract.onViolation: \"fallback\"`. Returns `undefined`\n * when no clause was breached.\n *\n * **Role.** The middleware cannot itself switch models on a soft breach,\n * so it records a typed {@link BudgetFallbackSignal} in the shared state\n * bag and lets the run continue. A fallback orchestrator (or the\n * `execute.after` hook of an outer middleware) reads it back here and\n * decides how to degrade the next run — cheaper model, cached answer,\n * truncated context.\n *\n * @param state - The middleware state bag (`ctx.state`).\n * @param name - The budget middleware's name. Default `\"budget\"`,\n *   matching `BudgetOptions.name`'s default.\n *\n * @example\n * const guard = budget({ contract: { maxCostUSD: 0.05, onViolation: \"fallback\" } });\n *\n * // In an outer middleware's execute.after, after the run:\n * const signal = readBudgetFallbackSignal(ctx.state);\n * if (signal?.dimension === \"cost\") {\n *   await rerunOnCheaperModel();\n * }\n */\nexport function readBudgetFallbackSignal(\n  state: MiddlewareExecuteContext[\"state\"],\n  name = \"budget\",\n): BudgetFallbackSignal | undefined {\n  return namespacedState<BudgetFallbackSignal>(\n    { state },\n    `${name}.fallback`,\n  ).get();\n}\n\n/**\n * Enforced token and / or USD budget for an agent run.\n *\n * **Role.** Guards against runaway tool loops, misconfigured\n * prompts, and unexpected provider price swings by capping\n * cumulative usage across every LLM trip of a single execution.\n * Aborts the run with a typed `BudgetExceededError` the moment a cap\n * is breached, rather than letting the damage grow trip by trip.\n *\n * **Scope.** Per-execution. A fresh counter is created at\n * `execute.before` and lives in the middleware state bag until the\n * run ends. Two concurrent `agent.execute()` calls on the same\n * agent therefore enforce the cap independently.\n *\n * **Token accounting.** After each successful trip, the middleware\n * adds `response.usage.total` to its running total and checks\n * against `maxTokens`. Synthetic trips (cache hits) contribute\n * `usage.total` as returned by the cache — cache middleware is\n * expected to surface zero usage on a hit, which naturally excludes\n * those trips from the budget.\n *\n * **USD accounting.** When `maxCostUSD` + `pricing[modelName]` are\n * both present, the middleware converts per-trip input / output\n * tokens to USD and accumulates. Missing pricing silently degrades\n * to tokens-only — explicit rather than guessing.\n *\n * **Warn mode.** `onExceeded: \"warn\"` logs a single warning the first\n * time a cap is breached and lets the run continue. Useful for\n * measuring real-world traffic against a proposed cap before flipping\n * to `\"abort\"` in production.\n *\n * **Contract / SLO mode.** Pass `contract` to enforce a declarative\n * service-level objective — `maxCostUSD`, `maxLatencyMs`, `maxTokens` —\n * on top of the legacy caps, with a single `onViolation` reaction:\n * `\"abort\"` hard-stops with `BudgetExceededError`; `\"fallback\"` records\n * a typed signal (read it via {@link readBudgetFallbackSignal}), fires\n * the optional `fallback` callback, and lets the run continue so an\n * outer layer can degrade gracefully. The contract's clauses are\n * evaluated independently of — and after — the top-level caps; the\n * top-level caps stay fully functional with or without a contract.\n *\n * @example\n * const budgetMiddleware = budget({ maxTokens: 50_000 });\n *\n * const myAgent = agent({\n *   model,\n *   middleware: [budgetMiddleware],\n * });\n *\n * @example\n * // With USD cap and custom pricing\n * const guard = budget({\n *   maxCostUSD: 0.5,\n *   pricing: {\n *     \"gpt-4o\": { inputPer1K: 0.005, outputPer1K: 0.015 },\n *   },\n * });\n *\n * @example\n * // SLO contract — soft-fallback on any breach\n * const sloGuard = budget({\n *   pricing: { \"gpt-4o\": { inputPer1K: 0.005, outputPer1K: 0.015 } },\n *   contract: {\n *     maxCostUSD: 0.05,\n *     maxLatencyMs: 8_000,\n *     maxTokens: 40_000,\n *     onViolation: \"fallback\",\n *     fallback: (violation) => routeToCheaperModel(violation.dimension),\n *   },\n * });\n */\nexport function budget(options: BudgetOptions): AgentMiddleware {\n  const name = options.name ?? \"budget\";\n  const onExceeded = options.onExceeded ?? \"abort\";\n  const hasTokenCap = typeof options.maxTokens === \"number\";\n  const hasCostCap = typeof options.maxCostUSD === \"number\";\n\n  const contract = options.contract;\n  const contractMode = contract?.onViolation ?? \"abort\";\n  const hasContractTokenCap = typeof contract?.maxTokens === \"number\";\n  const hasContractCostCap = typeof contract?.maxCostUSD === \"number\";\n  const hasContractLatencyCap = typeof contract?.maxLatencyMs === \"number\";\n  const contractNeedsCost = hasCostCap || hasContractCostCap;\n  // Warn once per model when a cost cap is configured but the running model\n  // has no pricing entry — without this the USD cap silently never enforces\n  // (costUSD stays 0), a fail-open the JSDoc on `maxCostUSD` documents.\n  const warnedUnpricedModels = new Set<string>();\n\n  return {\n    name,\n    execute: {\n      before(context) {\n        const counters = namespacedState<BudgetCounters>(context, name);\n        counters.set({\n          tokens: 0,\n          costUSD: 0,\n          warned: false,\n          startedAt: Date.now(),\n          fallbackFired: false,\n        });\n      },\n    },\n    trip: {\n      async after(context, response) {\n        const counters = namespacedState<BudgetCounters>(context, name).get();\n\n        if (!counters) {\n          return;\n        }\n\n        counters.tokens += response.usage.total;\n\n        if (contractNeedsCost) {\n          const pricing = options.pricing?.[context.model.name];\n\n          if (pricing) {\n            const tripCost =\n              (response.usage.input / 1000) * pricing.inputPer1K +\n              (response.usage.output / 1000) * pricing.outputPer1K;\n            counters.costUSD += tripCost;\n          } else if (!warnedUnpricedModels.has(context.model.name)) {\n            // A cost cap is set but no pricing matched the running model, so\n            // costUSD can never grow and the USD cap silently never fires.\n            // Surface the fail-open once per model instead of swallowing it.\n            warnedUnpricedModels.add(context.model.name);\n            console.warn(\n              `ai.middleware.budget(\"${name}\"): a USD cost cap is set but no pricing entry ` +\n                `matches the running model \"${context.model.name}\" — the cap cannot be enforced ` +\n                `for it. Add a pricing entry for \"${context.model.name}\" to options.pricing.`,\n            );\n          }\n        }\n\n        if (hasTokenCap && counters.tokens > options.maxTokens!) {\n          if (onExceeded === \"abort\") {\n            breach(options.maxTokens!, counters.tokens, \"tokens\", name);\n          }\n\n          if (!counters.warned) {\n            counters.warned = true;\n          }\n        }\n\n        if (hasCostCap && counters.costUSD > options.maxCostUSD!) {\n          if (onExceeded === \"abort\") {\n            breach(options.maxCostUSD!, counters.costUSD, \"usd\", name);\n          }\n\n          if (!counters.warned) {\n            counters.warned = true;\n          }\n        }\n\n        if (!contract) {\n          return;\n        }\n\n        if (hasContractTokenCap && counters.tokens > contract.maxTokens!) {\n          await enforceContract(\n            context,\n            counters,\n            name,\n            contractMode,\n            contract,\n            \"tokens\",\n            contract.maxTokens!,\n            counters.tokens,\n          );\n        }\n\n        if (hasContractCostCap && counters.costUSD > contract.maxCostUSD!) {\n          await enforceContract(\n            context,\n            counters,\n            name,\n            contractMode,\n            contract,\n            \"cost\",\n            contract.maxCostUSD!,\n            counters.costUSD,\n          );\n        }\n\n        if (hasContractLatencyCap) {\n          const elapsedMs = Date.now() - counters.startedAt;\n\n          if (elapsedMs > contract.maxLatencyMs!) {\n            await enforceContract(\n              context,\n              counters,\n              name,\n              contractMode,\n              contract,\n              \"latency\",\n              contract.maxLatencyMs!,\n              elapsedMs,\n            );\n          }\n        }\n      },\n    },\n  };\n}\n\n/**\n * Apply the contract's reaction to a single breached clause. `\"abort\"`\n * throws `BudgetExceededError` (stops the run); `\"fallback\"` records the\n * signal once, fires the callback, and returns so the run continues.\n *\n * The callback is invoked at most once per run (guarded by\n * `counters.fallbackFired`) and its rejections are swallowed — a buggy\n * fallback hook must never crash the agent.\n */\nasync function enforceContract(\n  context: MiddlewareExecuteContext,\n  counters: BudgetCounters,\n  name: string,\n  mode: NonNullable<BudgetContract[\"onViolation\"]>,\n  contract: BudgetContract,\n  dimension: BudgetContractDimension,\n  limit: number,\n  actual: number,\n): Promise<void> {\n  if (mode === \"abort\") {\n    breachContract(name, dimension, limit, actual);\n  }\n\n  if (counters.fallbackFired) {\n    return;\n  }\n\n  counters.fallbackFired = true;\n\n  const violation: BudgetContractViolation = {\n    dimension,\n    limit,\n    actual,\n    mode,\n  };\n\n  namespacedState<BudgetContractViolation>(context, `${name}.fallback`).set(\n    violation,\n  );\n\n  if (!contract.fallback) {\n    return;\n  }\n\n  try {\n    await contract.fallback(violation, context);\n  } catch {\n    // A fallback callback is a notification hook — its failure must\n    // never crash the run. Swallow deliberately.\n  }\n}\n"],"mappings":"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"}

package/esm/middleware/builtins/guardrail.d.mts

@@ -1,6 +1,6 @@
 import { MiddlewareTripContext } from "../../contracts/middleware/middleware-context.type.mjs";
 import { AgentMiddleware } from "../../contracts/middleware/middleware.contract.mjs";
-//#region ../@warlock.js/ai/src/middleware/builtins/guardrail.d.ts
+//#region ../ai/src/middleware/builtins/guardrail.d.ts
 /**
  * Decision returned by a guardrail check function. `ok: true`
  * permits the call; `ok: false` rejects with a human-readable

package/esm/middleware/builtins/guardrail.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"guardrail.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/builtins/guardrail.ts"],"mappings":";;;;;;;AAaA;KAAY,oBAAA;EAAyB,EAAA;AAAA;EAAe,EAAA;EAAW,MAAA;AAAA;;AAAM;AASrE;;;;;KAAY,cAAA,IACV,IAAA,UACA,OAAA,EAAS,qBAAA,KACN,oBAAA,GAAuB,OAAA,CAAQ,oBAAA;;;;;;KAOxB,gBAAA;EAPP;;;;AAAmD;AAOxD;EAOE,UAAA,GAAa,cAAA;;;;;;;;;EASb,WAAA,GAAc,cAAc;EA8Cd;;;;;EAxCd,IAAA;AAAA;;AAwCmE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAArD,SAAA,CAAU,OAAA,EAAS,gBAAA,GAAmB,eAAe"}
+{"version":3,"file":"guardrail.d.mts","names":[],"sources":["../../../../../../../../ai/src/middleware/builtins/guardrail.ts"],"mappings":";;;;;;;AAaA;KAAY,oBAAA;EAAyB,EAAA;AAAA;EAAe,EAAA;EAAW,MAAA;AAAA;;AAAM;AASrE;;;;;KAAY,cAAA,IACV,IAAA,UACA,OAAA,EAAS,qBAAA,KACN,oBAAA,GAAuB,OAAA,CAAQ,oBAAA;;;;;;KAOxB,gBAAA;EAPP;;;;AAAmD;AAOxD;EAOE,UAAA,GAAa,cAAA;;;;;;;;;EASb,WAAA,GAAc,cAAc;EA8Cd;;;;;EAxCd,IAAA;AAAA;;AAwCmE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAArD,SAAA,CAAU,OAAA,EAAS,gBAAA,GAAmB,eAAe"}

package/esm/middleware/builtins/guardrail.mjs

@@ -2,7 +2,7 @@ import { GuardrailViolationError } from "../../errors/guardrail-violation-error.
 import "../../errors/index.mjs";
 import { extractUserText } from "../utils/extract-user-text.mjs";
 
-//#region ../@warlock.js/ai/src/middleware/builtins/guardrail.ts
+//#region ../ai/src/middleware/builtins/guardrail.ts
 /**
 * Pre/post content guardrail for an agent run.
 *

package/esm/middleware/builtins/guardrail.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"guardrail.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/builtins/guardrail.ts"],"sourcesContent":["import type {\n  AgentMiddleware,\n  MiddlewareTripContext,\n} from \"../../contracts/middleware\";\nimport type { ModelResponse } from \"../../contracts/model.contract\";\nimport { GuardrailViolationError } from \"../../errors\";\nimport { extractUserText } from \"../utils\";\n\n/**\n * Decision returned by a guardrail check function. `ok: true`\n * permits the call; `ok: false` rejects with a human-readable\n * `reason` surfaced on `GuardrailViolationError`.\n */\nexport type GuardrailCheckResult = { ok: true } | { ok: false; reason: string };\n\n/**\n * Synchronous or asynchronous check invoked against the outbound\n * prompt (`inputCheck`) or the inbound response (`outputCheck`).\n * Receives the raw text and the surrounding trip context so\n * consumers can classify, route to an external moderation API, or\n * branch on tripIndex / messages history.\n */\nexport type GuardrailCheck = (\n  text: string,\n  context: MiddlewareTripContext,\n) => GuardrailCheckResult | Promise<GuardrailCheckResult>;\n\n/**\n * Configuration for `guardrail()`.  At least one of `inputCheck` or\n * `outputCheck` must be supplied — a guardrail with no checks is a\n * no-op.\n */\nexport type GuardrailOptions = {\n  /**\n   * Run against the outbound prompt just before the model sees it.\n   * Fires every trip with the concatenated last user-message text.\n   * Rejection aborts the trip with a `GuardrailViolationError` whose\n   * `phase === \"input\"`.\n   */\n  inputCheck?: GuardrailCheck;\n  /**\n   * Run against the model's response text after the trip completes.\n   * Fires every trip with `response.content`. Rejection aborts with\n   * a `GuardrailViolationError` whose `phase === \"output\"`.\n   *\n   * Output checks run BEFORE any tool dispatch — a rejected response\n   * means the tool calls it requested are never invoked.\n   */\n  outputCheck?: GuardrailCheck;\n  /**\n   * Override the middleware name — surfaces on\n   * `GuardrailViolationError.guardrail` so operators can tell two\n   * guardrails apart in logs. Default `\"guardrail\"`.\n   */\n  name?: string;\n};\n\n/**\n * Pre/post content guardrail for an agent run.\n *\n * **Role.** Inspects outbound prompts and inbound responses against\n * caller-supplied policies, aborting the trip with a typed\n * `GuardrailViolationError` when either trips a check. Consumers\n * distinguish `\"input\"` vs `\"output\"` violations off `error.phase`\n * — the two failure modes have very different product responses\n * (block the user vs re-prompt the model).\n *\n * **Scope.** Per-trip. Fires on every round-trip the agent makes,\n * including repair attempts and tool-follow-up trips. Input checks\n * evaluate the last user-role message; output checks evaluate the\n * raw model response text before any tool call is dispatched.\n *\n * **Composition.** A single middleware instance can carry both\n * `inputCheck` and `outputCheck`, or two separate instances can be\n * registered (useful when input and output policies come from\n * different teams / services). Registration order determines which\n * guardrail's violation surfaces first — the short-circuit throws\n * from the innermost offending hook, and outer guardrails never run\n * after an abort.\n *\n * **Not a sanitizer.** The guardrail either passes a trip unchanged\n * or aborts it. Mutating the prompt / response in-place is out of\n * scope — use a bespoke middleware for content rewriting.\n *\n * @example\n * const policy = guardrail({\n *   inputCheck: async (text) =>\n *     text.includes(\"SSN\") ? { ok: false, reason: \"pii\" } : { ok: true },\n *   outputCheck: async (text) =>\n *     text.length > 10_000 ? { ok: false, reason: \"too-long\" } : { ok: true },\n * });\n *\n * const myAgent = agent({ model, middleware: [policy] });\n */\nexport function guardrail(options: GuardrailOptions): AgentMiddleware {\n  const name = options.name ?? \"guardrail\";\n  const { inputCheck, outputCheck } = options;\n\n  return {\n    name,\n    trip: {\n      async before(context) {\n        if (!inputCheck) {\n          return;\n        }\n\n        const prompt = extractUserText(context.messages);\n\n        if (!prompt) {\n          return;\n        }\n\n        const verdict = await inputCheck(prompt, context);\n\n        if (!verdict.ok) {\n          throw new GuardrailViolationError(\n            `guardrail \"${name}\" rejected input — ${verdict.reason}`,\n            { phase: \"input\", reason: verdict.reason, guardrail: name },\n          );\n        }\n      },\n      async after(context, response: ModelResponse) {\n        if (!outputCheck) {\n          return;\n        }\n\n        if (!response.content) {\n          return;\n        }\n\n        const verdict = await outputCheck(response.content, context);\n\n        if (!verdict.ok) {\n          throw new GuardrailViolationError(\n            `guardrail \"${name}\" rejected output — ${verdict.reason}`,\n            { phase: \"output\", reason: verdict.reason, guardrail: name },\n          );\n        }\n      },\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8FA,SAAgB,UAAU,SAA4C;CACpE,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,EAAE,YAAY,gBAAgB;CAEpC,OAAO;EACL;EACA,MAAM;GACJ,MAAM,OAAO,SAAS;IACpB,IAAI,CAAC,YACH;IAGF,MAAM,SAAS,gBAAgB,QAAQ,QAAQ;IAE/C,IAAI,CAAC,QACH;IAGF,MAAM,UAAU,MAAM,WAAW,QAAQ,OAAO;IAEhD,IAAI,CAAC,QAAQ,IACX,MAAM,IAAI,wBACR,cAAc,KAAK,qBAAqB,QAAQ,UAChD;KAAE,OAAO;KAAS,QAAQ,QAAQ;KAAQ,WAAW;IAAK,CAC5D;GAEJ;GACA,MAAM,MAAM,SAAS,UAAyB;IAC5C,IAAI,CAAC,aACH;IAGF,IAAI,CAAC,SAAS,SACZ;IAGF,MAAM,UAAU,MAAM,YAAY,SAAS,SAAS,OAAO;IAE3D,IAAI,CAAC,QAAQ,IACX,MAAM,IAAI,wBACR,cAAc,KAAK,sBAAsB,QAAQ,UACjD;KAAE,OAAO;KAAU,QAAQ,QAAQ;KAAQ,WAAW;IAAK,CAC7D;GAEJ;EACF;CACF;AACF"}
+{"version":3,"file":"guardrail.mjs","names":[],"sources":["../../../../../../../../ai/src/middleware/builtins/guardrail.ts"],"sourcesContent":["import type {\n  AgentMiddleware,\n  MiddlewareTripContext,\n} from \"../../contracts/middleware\";\nimport type { ModelResponse } from \"../../contracts/model.contract\";\nimport { GuardrailViolationError } from \"../../errors\";\nimport { extractUserText } from \"../utils\";\n\n/**\n * Decision returned by a guardrail check function. `ok: true`\n * permits the call; `ok: false` rejects with a human-readable\n * `reason` surfaced on `GuardrailViolationError`.\n */\nexport type GuardrailCheckResult = { ok: true } | { ok: false; reason: string };\n\n/**\n * Synchronous or asynchronous check invoked against the outbound\n * prompt (`inputCheck`) or the inbound response (`outputCheck`).\n * Receives the raw text and the surrounding trip context so\n * consumers can classify, route to an external moderation API, or\n * branch on tripIndex / messages history.\n */\nexport type GuardrailCheck = (\n  text: string,\n  context: MiddlewareTripContext,\n) => GuardrailCheckResult | Promise<GuardrailCheckResult>;\n\n/**\n * Configuration for `guardrail()`.  At least one of `inputCheck` or\n * `outputCheck` must be supplied — a guardrail with no checks is a\n * no-op.\n */\nexport type GuardrailOptions = {\n  /**\n   * Run against the outbound prompt just before the model sees it.\n   * Fires every trip with the concatenated last user-message text.\n   * Rejection aborts the trip with a `GuardrailViolationError` whose\n   * `phase === \"input\"`.\n   */\n  inputCheck?: GuardrailCheck;\n  /**\n   * Run against the model's response text after the trip completes.\n   * Fires every trip with `response.content`. Rejection aborts with\n   * a `GuardrailViolationError` whose `phase === \"output\"`.\n   *\n   * Output checks run BEFORE any tool dispatch — a rejected response\n   * means the tool calls it requested are never invoked.\n   */\n  outputCheck?: GuardrailCheck;\n  /**\n   * Override the middleware name — surfaces on\n   * `GuardrailViolationError.guardrail` so operators can tell two\n   * guardrails apart in logs. Default `\"guardrail\"`.\n   */\n  name?: string;\n};\n\n/**\n * Pre/post content guardrail for an agent run.\n *\n * **Role.** Inspects outbound prompts and inbound responses against\n * caller-supplied policies, aborting the trip with a typed\n * `GuardrailViolationError` when either trips a check. Consumers\n * distinguish `\"input\"` vs `\"output\"` violations off `error.phase`\n * — the two failure modes have very different product responses\n * (block the user vs re-prompt the model).\n *\n * **Scope.** Per-trip. Fires on every round-trip the agent makes,\n * including repair attempts and tool-follow-up trips. Input checks\n * evaluate the last user-role message; output checks evaluate the\n * raw model response text before any tool call is dispatched.\n *\n * **Composition.** A single middleware instance can carry both\n * `inputCheck` and `outputCheck`, or two separate instances can be\n * registered (useful when input and output policies come from\n * different teams / services). Registration order determines which\n * guardrail's violation surfaces first — the short-circuit throws\n * from the innermost offending hook, and outer guardrails never run\n * after an abort.\n *\n * **Not a sanitizer.** The guardrail either passes a trip unchanged\n * or aborts it. Mutating the prompt / response in-place is out of\n * scope — use a bespoke middleware for content rewriting.\n *\n * @example\n * const policy = guardrail({\n *   inputCheck: async (text) =>\n *     text.includes(\"SSN\") ? { ok: false, reason: \"pii\" } : { ok: true },\n *   outputCheck: async (text) =>\n *     text.length > 10_000 ? { ok: false, reason: \"too-long\" } : { ok: true },\n * });\n *\n * const myAgent = agent({ model, middleware: [policy] });\n */\nexport function guardrail(options: GuardrailOptions): AgentMiddleware {\n  const name = options.name ?? \"guardrail\";\n  const { inputCheck, outputCheck } = options;\n\n  return {\n    name,\n    trip: {\n      async before(context) {\n        if (!inputCheck) {\n          return;\n        }\n\n        const prompt = extractUserText(context.messages);\n\n        if (!prompt) {\n          return;\n        }\n\n        const verdict = await inputCheck(prompt, context);\n\n        if (!verdict.ok) {\n          throw new GuardrailViolationError(\n            `guardrail \"${name}\" rejected input — ${verdict.reason}`,\n            { phase: \"input\", reason: verdict.reason, guardrail: name },\n          );\n        }\n      },\n      async after(context, response: ModelResponse) {\n        if (!outputCheck) {\n          return;\n        }\n\n        if (!response.content) {\n          return;\n        }\n\n        const verdict = await outputCheck(response.content, context);\n\n        if (!verdict.ok) {\n          throw new GuardrailViolationError(\n            `guardrail \"${name}\" rejected output — ${verdict.reason}`,\n            { phase: \"output\", reason: verdict.reason, guardrail: name },\n          );\n        }\n      },\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8FA,SAAgB,UAAU,SAA4C;CACpE,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,EAAE,YAAY,gBAAgB;CAEpC,OAAO;EACL;EACA,MAAM;GACJ,MAAM,OAAO,SAAS;IACpB,IAAI,CAAC,YACH;IAGF,MAAM,SAAS,gBAAgB,QAAQ,QAAQ;IAE/C,IAAI,CAAC,QACH;IAGF,MAAM,UAAU,MAAM,WAAW,QAAQ,OAAO;IAEhD,IAAI,CAAC,QAAQ,IACX,MAAM,IAAI,wBACR,cAAc,KAAK,qBAAqB,QAAQ,UAChD;KAAE,OAAO;KAAS,QAAQ,QAAQ;KAAQ,WAAW;IAAK,CAC5D;GAEJ;GACA,MAAM,MAAM,SAAS,UAAyB;IAC5C,IAAI,CAAC,aACH;IAGF,IAAI,CAAC,SAAS,SACZ;IAGF,MAAM,UAAU,MAAM,YAAY,SAAS,SAAS,OAAO;IAE3D,IAAI,CAAC,QAAQ,IACX,MAAM,IAAI,wBACR,cAAc,KAAK,sBAAsB,QAAQ,UACjD;KAAE,OAAO;KAAU,QAAQ,QAAQ;KAAQ,WAAW;IAAK,CAC7D;GAEJ;EACF;CACF;AACF"}

package/esm/middleware/builtins/semantic-cache.d.mts

@@ -2,7 +2,7 @@ import { AgentMiddleware } from "../../contracts/middleware/middleware.contract.
 import { EmbedderContract } from "../../contracts/embedder.contract.mjs";
 import { CacheDriver } from "@warlock.js/cache";
 
-//#region ../@warlock.js/ai/src/middleware/builtins/semantic-cache.d.ts
+//#region ../ai/src/middleware/builtins/semantic-cache.d.ts
 /**
  * Configuration for `semanticCache()`.
  */

package/esm/middleware/builtins/semantic-cache.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"semantic-cache.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/builtins/semantic-cache.ts"],"mappings":";;;;;;;;KAWY,oBAAA;EAAoB,sEAE9B,QAAA,EAAU,gBAAA;EAaS;;;;;;;;;;AAuBf;AAkHN;EAzIE,KAAA,GAAQ,WAAW;;;;;EAKnB,SAAA;EAoI2E;AAAA;;;;;EA7H3E,KAAA;;;;;;EAMA,SAAA;;;;;EAKA,IAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkHc,aAAA,CAAc,OAAA,EAAS,oBAAA,GAAuB,eAAe"}
+{"version":3,"file":"semantic-cache.d.mts","names":[],"sources":["../../../../../../../../ai/src/middleware/builtins/semantic-cache.ts"],"mappings":";;;;;;;;KAWY,oBAAA;EAAoB,sEAE9B,QAAA,EAAU,gBAAA;EAaS;;;;;;;;;;AAuBf;AAkHN;EAzIE,KAAA,GAAQ,WAAW;;;;;EAKnB,SAAA;EAoI2E;AAAA;;;;;EA7H3E,KAAA;;;;;;EAMA,SAAA;;;;;EAKA,IAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkHc,aAAA,CAAc,OAAA,EAAS,oBAAA,GAAuB,eAAe"}

package/esm/middleware/builtins/semantic-cache.mjs

@@ -1,7 +1,7 @@
 import { extractUserText } from "../utils/extract-user-text.mjs";
 import { resolveDefaultStore } from "../../config.mjs";
 
-//#region ../@warlock.js/ai/src/middleware/builtins/semantic-cache.ts
+//#region ../ai/src/middleware/builtins/semantic-cache.ts
 const DEFAULT_NAMESPACE = "ai.cache";
 /**
 * Build a stable fingerprint for a prompt covering the full message

package/esm/middleware/builtins/semantic-cache.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"semantic-cache.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/builtins/semantic-cache.ts"],"sourcesContent":["import type { CacheDriver } from \"@warlock.js/cache\";\nimport { resolveDefaultStore } from \"../../config\";\nimport type { Message } from \"../../contracts/conversation-message.type\";\nimport type { EmbedderContract } from \"../../contracts/embedder.contract\";\nimport type { AgentMiddleware } from \"../../contracts/middleware\";\nimport type { ModelResponse } from \"../../contracts/model.contract\";\nimport { extractUserText } from \"../utils\";\n\n/**\n * Configuration for `semanticCache()`.\n */\nexport type SemanticCacheOptions = {\n  /** Embedder used to produce the query vector from the prompt text. */\n  embedder: EmbedderContract;\n  /**\n   * Vector-capable cache driver from `@warlock.js/cache`. Production\n   * deployments pick a driver with a real ANN index (`pg` with\n   * pgvector, `redis` with RediSearch). Dev / test environments use\n   * `new MemoryCacheDriver()` — zero config, correct, but O(N) per\n   * query. Drivers without similarity support throw\n   * `CacheUnsupportedError` from `set({ vector })` / `similar()`.\n   *\n   * Falls back to `ai.config({ defaultStore })` when omitted. When\n   * neither is set, the factory throws at construction time —\n   * semantic cache cannot operate without a store.\n   */\n  store?: CacheDriver<any, any>;\n  /**\n   * Minimum cosine similarity for a vector hit. Between 0 and 1 —\n   * 0.95 is a solid default for question-answering caches.\n   */\n  threshold: number;\n  /**\n   * Optional TTL in milliseconds. Entries whose `storedAt` is older\n   * than this are treated as misses on read and overwritten on the\n   * next write. Default: no expiry — entries live until the store\n   * evicts them (per its own TTL/eviction policy).\n   */\n  ttlMs?: number;\n  /**\n   * Namespace prefix applied to every key the cache writes. Lets\n   * multiple agents share one driver without collision. Default\n   * `\"ai.cache\"`.\n   */\n  namespace?: string;\n  /**\n   * Middleware name — also the state-bag key prefix inside a single\n   * execution. Default `\"semantic-cache\"`.\n   */\n  name?: string;\n};\n\ntype CachedEntry = {\n  response: ModelResponse;\n  storedAt: number;\n};\n\ntype PendingWrite = {\n  promptKey: string;\n  vector: number[];\n};\n\nconst DEFAULT_NAMESPACE = \"ai.cache\";\n\n/**\n * Build a stable fingerprint for a prompt covering the full message\n * list (system + history + user turn). Ensures two prompts sharing\n * the user text but differing in prior context do not collide on\n * the exact-match fast path.\n *\n * FNV-1a variant — cheap, collision-resistant enough for a cache,\n * dependency-free. NOT a cryptographic hash: collisions would\n * surface as wrong cache hits, not a security issue in the current\n * trust model.\n */\nfunction hashPrompt(messages: ReadonlyArray<Message>): string {\n  const serialized = messages\n    .map((message) => {\n      const role = message.role;\n      const content = Array.isArray(message.content)\n        ? message.content\n            .filter((part) => part.type === \"text\")\n            .map((part) => (part as { text: string }).text)\n            .join(\"|\")\n        : message.content;\n\n      return `${role}:${content}`;\n    })\n    .join(\"||\");\n\n  let hash = 0x811c9dc5;\n\n  for (let index = 0; index < serialized.length; index++) {\n    hash ^= serialized.charCodeAt(index);\n    hash = Math.imul(hash, 0x01000193);\n  }\n\n  return (hash >>> 0).toString(16);\n}\n\nfunction isFresh(entry: CachedEntry, ttlMs: number | undefined): boolean {\n  if (ttlMs === undefined) {\n    return true;\n  }\n\n  return Date.now() - entry.storedAt <= ttlMs;\n}\n\n/**\n * Semantic-similarity response cache for an agent run.\n *\n * **Role.** Skips LLM round-trips when the current prompt is\n * semantically close to one the agent has already answered. For\n * FAQ / support-style traffic this often eliminates 60–80% of\n * model calls — the production win is massive for cost and\n * latency.\n *\n * **Delegation to `@warlock.js/cache`.** This middleware does NOT\n * implement similarity search itself. It delegates to the supplied\n * `CacheDriver`. Production deployments pick a driver with an ANN\n * index (`pg` + pgvector, `redis` + RediSearch). Dev / test\n * environments pass `new MemoryCacheDriver()` — zero config, correct,\n * but O(N) per query. Drivers without similarity support throw\n * `CacheUnsupportedError` from `set({ vector })` / `similar()`.\n *\n * **Two-tier lookup.**\n * 1. *Exact-match key* — a cheap FNV hash over the entire message\n *    list. `store.get(hash)` returns the entry without an embedding\n *    round trip when the prompt hasn't changed at all.\n * 2. *Vector-match* — on exact-match miss, embed the prompt and\n *    call `store.similar(vector, { topK: 1, threshold })`. The\n *    driver uses its native similarity index; anything clearing\n *    `threshold` is returned as a hit.\n *\n * **Write-on-miss.** When both tiers miss, `trip.before` stashes\n * the prompt hash + vector in `ctx.state`; `trip.after` reads back\n * the pending entry and calls\n * `store.set(hash, entry, { vector })`. If an outer middleware\n * (guardrail) throws in `trip.after` before the cache's `trip.after`\n * runs, the pending entry is never written — bad responses stay out\n * of the cache **as long as the canonical install order is followed**\n * (cache outermost).\n *\n * **Synthetic-response on hit.** Returns a `ModelResponse` with\n * `usage: { input: 0, output: 0, total: 0 }` so budget /\n * observability correctly exclude the saved trip.\n *\n * @example\n * import { semanticCache } from \"@warlock.js/ai\";\n * import { MemoryCacheDriver } from \"@warlock.js/cache\";\n *\n * const store = new MemoryCacheDriver();\n * store.setOptions({});\n *\n * const cache = semanticCache({\n *   embedder: openai.embedder({ name: \"text-embedding-3-small\" }),\n *   store,\n *   threshold: 0.95,\n *   ttlMs: 60 * 60 * 1000,\n * });\n *\n * const myAgent = agent({ model, middleware: [cache] });\n */\nexport function semanticCache(options: SemanticCacheOptions): AgentMiddleware {\n  const name = options.name ?? \"semantic-cache\";\n  const namespace = options.namespace ?? DEFAULT_NAMESPACE;\n  const pendingKey = `${name}.pending`;\n\n  // Resolve the effective store at factory time, not per-call. Every\n  // subsequent hook closes over `store` so the resolution happens once.\n  // Throws now (loud, at construction) instead of later during the\n  // first trip (silent until the agent actually runs).\n  const store = options.store ?? resolveDefaultStore();\n\n  if (!store) {\n    throw new Error(\n      `semanticCache: no store supplied — pass \\`store\\` in options or call \\`ai.config({ defaultStore })\\` at app boot before constructing the middleware`,\n    );\n  }\n\n  // Cache's parseKey replaces \":\" with \".\" so the namespace boundary\n  // matches what `similar()` actually returns in `hit.key`. Using a\n  // dot here keeps prefix checks aligned with stored keys.\n  const keyFor = (hash: string): string => `${namespace}.${hash}`;\n\n  return {\n    name,\n    log: true,\n    trip: {\n      async before(context) {\n        // Only cache the first trip's response. Subsequent trips\n        // happen because the previous trip requested tool calls — the\n        // message list now carries tool results the original prompt\n        // never saw, so a semantic match on the unchanged user text\n        // would serve back the prior `tool_calls` response and loop\n        // the agent forever. The first turn is also the only one\n        // where a \"same question → same final answer\" caching story\n        // is sound.\n        if (context.tripIndex !== 0) {\n          return;\n        }\n\n        const promptText = extractUserText(context.messages);\n\n        if (!promptText) {\n          return;\n        }\n\n        const promptKey = hashPrompt(context.messages);\n        const scopedKey = keyFor(promptKey);\n\n        const exact = await store.get<CachedEntry>(scopedKey);\n\n        if (exact && isFresh(exact, options.ttlMs)) {\n          return toSyntheticResponse(exact.response);\n        }\n\n        const query = await options.embedder.embed(promptText);\n\n        const [hit] = await store.similar<CachedEntry>(query.vector, {\n          topK: 1,\n          threshold: options.threshold,\n        });\n\n        if (hit && isFresh(hit.value, options.ttlMs)) {\n          // Only return hits whose stored key is within this cache's\n          // namespace. Drivers shared across namespaces would otherwise\n          // leak foreign entries into queries.\n          if (hit.key.startsWith(`${namespace}.`)) {\n            return toSyntheticResponse(hit.value.response);\n          }\n        }\n\n        const pending: PendingWrite = { promptKey, vector: query.vector };\n        context.state.set(pendingKey, pending);\n\n        return;\n      },\n      async after(context, response) {\n        const pending = context.state.get(pendingKey) as PendingWrite | undefined;\n\n        if (!pending) {\n          return;\n        }\n\n        // Mid-stream tool-call responses must not be cached — the\n        // useful answer comes from the trip *after* the tool returns.\n        // Crucially, leave the pending entry in place so a later trip\n        // (the one that actually finishes with `stop`) can read it\n        // and write the final response under the *original* trip-0\n        // prompt key. Deleting here would orphan the pending and the\n        // post-tool answer would never make it into the store.\n        if (response.finishReason === \"tool_calls\") {\n          return;\n        }\n\n        context.state.delete(pendingKey);\n\n        const entry: CachedEntry = { response, storedAt: Date.now() };\n\n        await store.set(keyFor(pending.promptKey), entry, {\n          vector: pending.vector,\n        });\n\n        return;\n      },\n    },\n  };\n}\n\nfunction toSyntheticResponse(response: ModelResponse): ModelResponse {\n  return {\n    content: response.content,\n    finishReason: response.finishReason,\n    usage: { input: 0, output: 0, total: 0 },\n    toolCalls: response.toolCalls,\n  };\n}\n"],"mappings":";;;;AA8DA,MAAM,oBAAoB;;;;;;;;;;;;AAa1B,SAAS,WAAW,UAA0C;CAC5D,MAAM,aAAa,SAChB,KAAK,YAAY;EAShB,OAAO,GARM,QAAQ,KAQN,GAPC,MAAM,QAAQ,QAAQ,OAAO,IACzC,QAAQ,QACL,QAAQ,SAAS,KAAK,SAAS,MAAM,CAAC,CACtC,KAAK,SAAU,KAA0B,IAAI,CAAC,CAC9C,KAAK,GAAG,IACX,QAAQ;CAGd,CAAC,CAAC,CACD,KAAK,IAAI;CAEZ,IAAI,OAAO;CAEX,KAAK,IAAI,QAAQ,GAAG,QAAQ,WAAW,QAAQ,SAAS;EACtD,QAAQ,WAAW,WAAW,KAAK;EACnC,OAAO,KAAK,KAAK,MAAM,QAAU;CACnC;CAEA,QAAQ,SAAS,EAAC,CAAE,SAAS,EAAE;AACjC;AAEA,SAAS,QAAQ,OAAoB,OAAoC;CACvE,IAAI,UAAU,QACZ,OAAO;CAGT,OAAO,KAAK,IAAI,IAAI,MAAM,YAAY;AACxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,SAAgB,cAAc,SAAgD;CAC5E,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAM,aAAa,GAAG,KAAK;CAM3B,MAAM,QAAQ,QAAQ,SAAS,oBAAoB;CAEnD,IAAI,CAAC,OACH,MAAM,IAAI,MACR,qJACF;CAMF,MAAM,UAAU,SAAyB,GAAG,UAAU,GAAG;CAEzD,OAAO;EACL;EACA,KAAK;EACL,MAAM;GACJ,MAAM,OAAO,SAAS;IASpB,IAAI,QAAQ,cAAc,GACxB;IAGF,MAAM,aAAa,gBAAgB,QAAQ,QAAQ;IAEnD,IAAI,CAAC,YACH;IAGF,MAAM,YAAY,WAAW,QAAQ,QAAQ;IAC7C,MAAM,YAAY,OAAO,SAAS;IAElC,MAAM,QAAQ,MAAM,MAAM,IAAiB,SAAS;IAEpD,IAAI,SAAS,QAAQ,OAAO,QAAQ,KAAK,GACvC,OAAO,oBAAoB,MAAM,QAAQ;IAG3C,MAAM,QAAQ,MAAM,QAAQ,SAAS,MAAM,UAAU;IAErD,MAAM,CAAC,OAAO,MAAM,MAAM,QAAqB,MAAM,QAAQ;KAC3D,MAAM;KACN,WAAW,QAAQ;IACrB,CAAC;IAED,IAAI,OAAO,QAAQ,IAAI,OAAO,QAAQ,KAAK,GAIzC;SAAI,IAAI,IAAI,WAAW,GAAG,UAAU,EAAE,GACpC,OAAO,oBAAoB,IAAI,MAAM,QAAQ;IAC/C;IAGF,MAAM,UAAwB;KAAE;KAAW,QAAQ,MAAM;IAAO;IAChE,QAAQ,MAAM,IAAI,YAAY,OAAO;GAGvC;GACA,MAAM,MAAM,SAAS,UAAU;IAC7B,MAAM,UAAU,QAAQ,MAAM,IAAI,UAAU;IAE5C,IAAI,CAAC,SACH;IAUF,IAAI,SAAS,iBAAiB,cAC5B;IAGF,QAAQ,MAAM,OAAO,UAAU;IAE/B,MAAM,QAAqB;KAAE;KAAU,UAAU,KAAK,IAAI;IAAE;IAE5D,MAAM,MAAM,IAAI,OAAO,QAAQ,SAAS,GAAG,OAAO,EAChD,QAAQ,QAAQ,OAClB,CAAC;GAGH;EACF;CACF;AACF;AAEA,SAAS,oBAAoB,UAAwC;CACnE,OAAO;EACL,SAAS,SAAS;EAClB,cAAc,SAAS;EACvB,OAAO;GAAE,OAAO;GAAG,QAAQ;GAAG,OAAO;EAAE;EACvC,WAAW,SAAS;CACtB;AACF"}
+{"version":3,"file":"semantic-cache.mjs","names":[],"sources":["../../../../../../../../ai/src/middleware/builtins/semantic-cache.ts"],"sourcesContent":["import type { CacheDriver } from \"@warlock.js/cache\";\nimport { resolveDefaultStore } from \"../../config\";\nimport type { Message } from \"../../contracts/conversation-message.type\";\nimport type { EmbedderContract } from \"../../contracts/embedder.contract\";\nimport type { AgentMiddleware } from \"../../contracts/middleware\";\nimport type { ModelResponse } from \"../../contracts/model.contract\";\nimport { extractUserText } from \"../utils\";\n\n/**\n * Configuration for `semanticCache()`.\n */\nexport type SemanticCacheOptions = {\n  /** Embedder used to produce the query vector from the prompt text. */\n  embedder: EmbedderContract;\n  /**\n   * Vector-capable cache driver from `@warlock.js/cache`. Production\n   * deployments pick a driver with a real ANN index (`pg` with\n   * pgvector, `redis` with RediSearch). Dev / test environments use\n   * `new MemoryCacheDriver()` — zero config, correct, but O(N) per\n   * query. Drivers without similarity support throw\n   * `CacheUnsupportedError` from `set({ vector })` / `similar()`.\n   *\n   * Falls back to `ai.config({ defaultStore })` when omitted. When\n   * neither is set, the factory throws at construction time —\n   * semantic cache cannot operate without a store.\n   */\n  store?: CacheDriver<any, any>;\n  /**\n   * Minimum cosine similarity for a vector hit. Between 0 and 1 —\n   * 0.95 is a solid default for question-answering caches.\n   */\n  threshold: number;\n  /**\n   * Optional TTL in milliseconds. Entries whose `storedAt` is older\n   * than this are treated as misses on read and overwritten on the\n   * next write. Default: no expiry — entries live until the store\n   * evicts them (per its own TTL/eviction policy).\n   */\n  ttlMs?: number;\n  /**\n   * Namespace prefix applied to every key the cache writes. Lets\n   * multiple agents share one driver without collision. Default\n   * `\"ai.cache\"`.\n   */\n  namespace?: string;\n  /**\n   * Middleware name — also the state-bag key prefix inside a single\n   * execution. Default `\"semantic-cache\"`.\n   */\n  name?: string;\n};\n\ntype CachedEntry = {\n  response: ModelResponse;\n  storedAt: number;\n};\n\ntype PendingWrite = {\n  promptKey: string;\n  vector: number[];\n};\n\nconst DEFAULT_NAMESPACE = \"ai.cache\";\n\n/**\n * Build a stable fingerprint for a prompt covering the full message\n * list (system + history + user turn). Ensures two prompts sharing\n * the user text but differing in prior context do not collide on\n * the exact-match fast path.\n *\n * FNV-1a variant — cheap, collision-resistant enough for a cache,\n * dependency-free. NOT a cryptographic hash: collisions would\n * surface as wrong cache hits, not a security issue in the current\n * trust model.\n */\nfunction hashPrompt(messages: ReadonlyArray<Message>): string {\n  const serialized = messages\n    .map((message) => {\n      const role = message.role;\n      const content = Array.isArray(message.content)\n        ? message.content\n            .filter((part) => part.type === \"text\")\n            .map((part) => (part as { text: string }).text)\n            .join(\"|\")\n        : message.content;\n\n      return `${role}:${content}`;\n    })\n    .join(\"||\");\n\n  let hash = 0x811c9dc5;\n\n  for (let index = 0; index < serialized.length; index++) {\n    hash ^= serialized.charCodeAt(index);\n    hash = Math.imul(hash, 0x01000193);\n  }\n\n  return (hash >>> 0).toString(16);\n}\n\nfunction isFresh(entry: CachedEntry, ttlMs: number | undefined): boolean {\n  if (ttlMs === undefined) {\n    return true;\n  }\n\n  return Date.now() - entry.storedAt <= ttlMs;\n}\n\n/**\n * Semantic-similarity response cache for an agent run.\n *\n * **Role.** Skips LLM round-trips when the current prompt is\n * semantically close to one the agent has already answered. For\n * FAQ / support-style traffic this often eliminates 60–80% of\n * model calls — the production win is massive for cost and\n * latency.\n *\n * **Delegation to `@warlock.js/cache`.** This middleware does NOT\n * implement similarity search itself. It delegates to the supplied\n * `CacheDriver`. Production deployments pick a driver with an ANN\n * index (`pg` + pgvector, `redis` + RediSearch). Dev / test\n * environments pass `new MemoryCacheDriver()` — zero config, correct,\n * but O(N) per query. Drivers without similarity support throw\n * `CacheUnsupportedError` from `set({ vector })` / `similar()`.\n *\n * **Two-tier lookup.**\n * 1. *Exact-match key* — a cheap FNV hash over the entire message\n *    list. `store.get(hash)` returns the entry without an embedding\n *    round trip when the prompt hasn't changed at all.\n * 2. *Vector-match* — on exact-match miss, embed the prompt and\n *    call `store.similar(vector, { topK: 1, threshold })`. The\n *    driver uses its native similarity index; anything clearing\n *    `threshold` is returned as a hit.\n *\n * **Write-on-miss.** When both tiers miss, `trip.before` stashes\n * the prompt hash + vector in `ctx.state`; `trip.after` reads back\n * the pending entry and calls\n * `store.set(hash, entry, { vector })`. If an outer middleware\n * (guardrail) throws in `trip.after` before the cache's `trip.after`\n * runs, the pending entry is never written — bad responses stay out\n * of the cache **as long as the canonical install order is followed**\n * (cache outermost).\n *\n * **Synthetic-response on hit.** Returns a `ModelResponse` with\n * `usage: { input: 0, output: 0, total: 0 }` so budget /\n * observability correctly exclude the saved trip.\n *\n * @example\n * import { semanticCache } from \"@warlock.js/ai\";\n * import { MemoryCacheDriver } from \"@warlock.js/cache\";\n *\n * const store = new MemoryCacheDriver();\n * store.setOptions({});\n *\n * const cache = semanticCache({\n *   embedder: openai.embedder({ name: \"text-embedding-3-small\" }),\n *   store,\n *   threshold: 0.95,\n *   ttlMs: 60 * 60 * 1000,\n * });\n *\n * const myAgent = agent({ model, middleware: [cache] });\n */\nexport function semanticCache(options: SemanticCacheOptions): AgentMiddleware {\n  const name = options.name ?? \"semantic-cache\";\n  const namespace = options.namespace ?? DEFAULT_NAMESPACE;\n  const pendingKey = `${name}.pending`;\n\n  // Resolve the effective store at factory time, not per-call. Every\n  // subsequent hook closes over `store` so the resolution happens once.\n  // Throws now (loud, at construction) instead of later during the\n  // first trip (silent until the agent actually runs).\n  const store = options.store ?? resolveDefaultStore();\n\n  if (!store) {\n    throw new Error(\n      `semanticCache: no store supplied — pass \\`store\\` in options or call \\`ai.config({ defaultStore })\\` at app boot before constructing the middleware`,\n    );\n  }\n\n  // Cache's parseKey replaces \":\" with \".\" so the namespace boundary\n  // matches what `similar()` actually returns in `hit.key`. Using a\n  // dot here keeps prefix checks aligned with stored keys.\n  const keyFor = (hash: string): string => `${namespace}.${hash}`;\n\n  return {\n    name,\n    log: true,\n    trip: {\n      async before(context) {\n        // Only cache the first trip's response. Subsequent trips\n        // happen because the previous trip requested tool calls — the\n        // message list now carries tool results the original prompt\n        // never saw, so a semantic match on the unchanged user text\n        // would serve back the prior `tool_calls` response and loop\n        // the agent forever. The first turn is also the only one\n        // where a \"same question → same final answer\" caching story\n        // is sound.\n        if (context.tripIndex !== 0) {\n          return;\n        }\n\n        const promptText = extractUserText(context.messages);\n\n        if (!promptText) {\n          return;\n        }\n\n        const promptKey = hashPrompt(context.messages);\n        const scopedKey = keyFor(promptKey);\n\n        const exact = await store.get<CachedEntry>(scopedKey);\n\n        if (exact && isFresh(exact, options.ttlMs)) {\n          return toSyntheticResponse(exact.response);\n        }\n\n        const query = await options.embedder.embed(promptText);\n\n        const [hit] = await store.similar<CachedEntry>(query.vector, {\n          topK: 1,\n          threshold: options.threshold,\n        });\n\n        if (hit && isFresh(hit.value, options.ttlMs)) {\n          // Only return hits whose stored key is within this cache's\n          // namespace. Drivers shared across namespaces would otherwise\n          // leak foreign entries into queries.\n          if (hit.key.startsWith(`${namespace}.`)) {\n            return toSyntheticResponse(hit.value.response);\n          }\n        }\n\n        const pending: PendingWrite = { promptKey, vector: query.vector };\n        context.state.set(pendingKey, pending);\n\n        return;\n      },\n      async after(context, response) {\n        const pending = context.state.get(pendingKey) as PendingWrite | undefined;\n\n        if (!pending) {\n          return;\n        }\n\n        // Mid-stream tool-call responses must not be cached — the\n        // useful answer comes from the trip *after* the tool returns.\n        // Crucially, leave the pending entry in place so a later trip\n        // (the one that actually finishes with `stop`) can read it\n        // and write the final response under the *original* trip-0\n        // prompt key. Deleting here would orphan the pending and the\n        // post-tool answer would never make it into the store.\n        if (response.finishReason === \"tool_calls\") {\n          return;\n        }\n\n        context.state.delete(pendingKey);\n\n        const entry: CachedEntry = { response, storedAt: Date.now() };\n\n        await store.set(keyFor(pending.promptKey), entry, {\n          vector: pending.vector,\n        });\n\n        return;\n      },\n    },\n  };\n}\n\nfunction toSyntheticResponse(response: ModelResponse): ModelResponse {\n  return {\n    content: response.content,\n    finishReason: response.finishReason,\n    usage: { input: 0, output: 0, total: 0 },\n    toolCalls: response.toolCalls,\n  };\n}\n"],"mappings":";;;;AA8DA,MAAM,oBAAoB;;;;;;;;;;;;AAa1B,SAAS,WAAW,UAA0C;CAC5D,MAAM,aAAa,SAChB,KAAK,YAAY;EAShB,OAAO,GARM,QAAQ,KAQN,GAPC,MAAM,QAAQ,QAAQ,OAAO,IACzC,QAAQ,QACL,QAAQ,SAAS,KAAK,SAAS,MAAM,CAAC,CACtC,KAAK,SAAU,KAA0B,IAAI,CAAC,CAC9C,KAAK,GAAG,IACX,QAAQ;CAGd,CAAC,CAAC,CACD,KAAK,IAAI;CAEZ,IAAI,OAAO;CAEX,KAAK,IAAI,QAAQ,GAAG,QAAQ,WAAW,QAAQ,SAAS;EACtD,QAAQ,WAAW,WAAW,KAAK;EACnC,OAAO,KAAK,KAAK,MAAM,QAAU;CACnC;CAEA,QAAQ,SAAS,EAAC,CAAE,SAAS,EAAE;AACjC;AAEA,SAAS,QAAQ,OAAoB,OAAoC;CACvE,IAAI,UAAU,QACZ,OAAO;CAGT,OAAO,KAAK,IAAI,IAAI,MAAM,YAAY;AACxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,SAAgB,cAAc,SAAgD;CAC5E,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAM,aAAa,GAAG,KAAK;CAM3B,MAAM,QAAQ,QAAQ,SAAS,oBAAoB;CAEnD,IAAI,CAAC,OACH,MAAM,IAAI,MACR,qJACF;CAMF,MAAM,UAAU,SAAyB,GAAG,UAAU,GAAG;CAEzD,OAAO;EACL;EACA,KAAK;EACL,MAAM;GACJ,MAAM,OAAO,SAAS;IASpB,IAAI,QAAQ,cAAc,GACxB;IAGF,MAAM,aAAa,gBAAgB,QAAQ,QAAQ;IAEnD,IAAI,CAAC,YACH;IAGF,MAAM,YAAY,WAAW,QAAQ,QAAQ;IAC7C,MAAM,YAAY,OAAO,SAAS;IAElC,MAAM,QAAQ,MAAM,MAAM,IAAiB,SAAS;IAEpD,IAAI,SAAS,QAAQ,OAAO,QAAQ,KAAK,GACvC,OAAO,oBAAoB,MAAM,QAAQ;IAG3C,MAAM,QAAQ,MAAM,QAAQ,SAAS,MAAM,UAAU;IAErD,MAAM,CAAC,OAAO,MAAM,MAAM,QAAqB,MAAM,QAAQ;KAC3D,MAAM;KACN,WAAW,QAAQ;IACrB,CAAC;IAED,IAAI,OAAO,QAAQ,IAAI,OAAO,QAAQ,KAAK,GAIzC;SAAI,IAAI,IAAI,WAAW,GAAG,UAAU,EAAE,GACpC,OAAO,oBAAoB,IAAI,MAAM,QAAQ;IAC/C;IAGF,MAAM,UAAwB;KAAE;KAAW,QAAQ,MAAM;IAAO;IAChE,QAAQ,MAAM,IAAI,YAAY,OAAO;GAGvC;GACA,MAAM,MAAM,SAAS,UAAU;IAC7B,MAAM,UAAU,QAAQ,MAAM,IAAI,UAAU;IAE5C,IAAI,CAAC,SACH;IAUF,IAAI,SAAS,iBAAiB,cAC5B;IAGF,QAAQ,MAAM,OAAO,UAAU;IAE/B,MAAM,QAAqB;KAAE;KAAU,UAAU,KAAK,IAAI;IAAE;IAE5D,MAAM,MAAM,IAAI,OAAO,QAAQ,SAAS,GAAG,OAAO,EAChD,QAAQ,QAAQ,OAClB,CAAC;GAGH;EACF;CACF;AACF;AAEA,SAAS,oBAAoB,UAAwC;CACnE,OAAO;EACL,SAAS,SAAS;EAClB,cAAc,SAAS;EACvB,OAAO;GAAE,OAAO;GAAG,QAAQ;GAAG,OAAO;EAAE;EACvC,WAAW,SAAS;CACtB;AACF"}

package/esm/middleware/helpers/compose.d.mts

@@ -1,5 +1,5 @@
 import { AgentMiddleware } from "../../contracts/middleware/middleware.contract.mjs";
-//#region ../@warlock.js/ai/src/middleware/helpers/compose.d.ts
+//#region ../ai/src/middleware/helpers/compose.d.ts
 /**
  * Flatten one or more middleware sources into a single ordered
  * array suitable for `agent({ middleware: [...] })`.

package/esm/middleware/helpers/compose.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"compose.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/helpers/compose.ts"],"mappings":";;;;;AAsCA;;;;;;;;;;;;;;;;;AAEkB;;;;;;;;;;;;;;;;iBAFF,iBAAA,IACX,OAAA,EAAS,aAAA,CAAc,eAAA,GAAkB,aAAA,CAAc,eAAA,KACzD,eAAA"}
+{"version":3,"file":"compose.d.mts","names":[],"sources":["../../../../../../../../ai/src/middleware/helpers/compose.ts"],"mappings":";;;;;AAsCA;;;;;;;;;;;;;;;;;AAEkB;;;;;;;;;;;;;;;;iBAFF,iBAAA,IACX,OAAA,EAAS,aAAA,CAAc,eAAA,GAAkB,aAAA,CAAc,eAAA,KACzD,eAAA"}

package/esm/middleware/helpers/compose.mjs

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/middleware/helpers/compose.ts
+//#region ../ai/src/middleware/helpers/compose.ts
 /**
 * Flatten one or more middleware sources into a single ordered
 * array suitable for `agent({ middleware: [...] })`.

package/esm/middleware/helpers/compose.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"compose.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/helpers/compose.ts"],"sourcesContent":["import type { AgentMiddleware } from \"../../contracts/middleware\";\n\n/**\n * Flatten one or more middleware sources into a single ordered\n * array suitable for `agent({ middleware: [...] })`.\n *\n * **Role.** As middleware catalogs grow, agent configs accumulate\n * long arrays that mix \"always-on\" stacks (cache + budget + guardrail)\n * with per-concern extras (per-tool rate-limits, audit hooks). A\n * single `compose` call lets callers keep those sources as named\n * variables and flatten at the registration site.\n *\n * **Semantics.** Registration order is preserved across sources —\n * `compose(a, b, c)` produces `[...a, ...b, ...c]`. Because the\n * pipeline's onion is strictly registration-ordered, the flattened\n * order is the execution order. No de-duplication, no sorting, no\n * priority logic — that would hide bugs, not fix them.\n *\n * **Accepts arrays OR individual middlewares.** Both forms are\n * common in callsite code; the helper flattens either.\n *\n * @example\n * const standardStack = [\n *   ai.middleware.semanticCache({ ... }),\n *   ai.middleware.budget({ maxTokens: 20_000 }),\n *   ai.middleware.guardrail({ ... }),\n * ];\n *\n * const toolRateLimits = [\n *   toolRateLimit({ tool: \"search_web\", maxCalls: 3 }),\n *   toolRateLimit({ tool: \"expensive_api\", maxCalls: 1 }),\n * ];\n *\n * const myAgent = ai.agent({\n *   model,\n *   middleware: ai.middleware.compose(standardStack, toolRateLimits, auditMiddleware),\n * });\n */\nexport function composeMiddleware(\n  ...sources: ReadonlyArray<AgentMiddleware | ReadonlyArray<AgentMiddleware>>\n): AgentMiddleware[] {\n  const out: AgentMiddleware[] = [];\n\n  for (const source of sources) {\n    if (Array.isArray(source)) {\n      out.push(...source);\n      continue;\n    }\n\n    out.push(source as AgentMiddleware);\n  }\n\n  return out;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,SAAgB,kBACd,GAAG,SACgB;CACnB,MAAM,MAAyB,CAAC;CAEhC,KAAK,MAAM,UAAU,SAAS;EAC5B,IAAI,MAAM,QAAQ,MAAM,GAAG;GACzB,IAAI,KAAK,GAAG,MAAM;GAClB;EACF;EAEA,IAAI,KAAK,MAAyB;CACpC;CAEA,OAAO;AACT"}
+{"version":3,"file":"compose.mjs","names":[],"sources":["../../../../../../../../ai/src/middleware/helpers/compose.ts"],"sourcesContent":["import type { AgentMiddleware } from \"../../contracts/middleware\";\n\n/**\n * Flatten one or more middleware sources into a single ordered\n * array suitable for `agent({ middleware: [...] })`.\n *\n * **Role.** As middleware catalogs grow, agent configs accumulate\n * long arrays that mix \"always-on\" stacks (cache + budget + guardrail)\n * with per-concern extras (per-tool rate-limits, audit hooks). A\n * single `compose` call lets callers keep those sources as named\n * variables and flatten at the registration site.\n *\n * **Semantics.** Registration order is preserved across sources —\n * `compose(a, b, c)` produces `[...a, ...b, ...c]`. Because the\n * pipeline's onion is strictly registration-ordered, the flattened\n * order is the execution order. No de-duplication, no sorting, no\n * priority logic — that would hide bugs, not fix them.\n *\n * **Accepts arrays OR individual middlewares.** Both forms are\n * common in callsite code; the helper flattens either.\n *\n * @example\n * const standardStack = [\n *   ai.middleware.semanticCache({ ... }),\n *   ai.middleware.budget({ maxTokens: 20_000 }),\n *   ai.middleware.guardrail({ ... }),\n * ];\n *\n * const toolRateLimits = [\n *   toolRateLimit({ tool: \"search_web\", maxCalls: 3 }),\n *   toolRateLimit({ tool: \"expensive_api\", maxCalls: 1 }),\n * ];\n *\n * const myAgent = ai.agent({\n *   model,\n *   middleware: ai.middleware.compose(standardStack, toolRateLimits, auditMiddleware),\n * });\n */\nexport function composeMiddleware(\n  ...sources: ReadonlyArray<AgentMiddleware | ReadonlyArray<AgentMiddleware>>\n): AgentMiddleware[] {\n  const out: AgentMiddleware[] = [];\n\n  for (const source of sources) {\n    if (Array.isArray(source)) {\n      out.push(...source);\n      continue;\n    }\n\n    out.push(source as AgentMiddleware);\n  }\n\n  return out;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,SAAgB,kBACd,GAAG,SACgB;CACnB,MAAM,MAAyB,CAAC;CAEhC,KAAK,MAAM,UAAU,SAAS;EAC5B,IAAI,MAAM,QAAQ,MAAM,GAAG;GACzB,IAAI,KAAK,GAAG,MAAM;GAClB;EACF;EAEA,IAAI,KAAK,MAAyB;CACpC;CAEA,OAAO;AACT"}

package/esm/middleware/helpers/for-tool.d.mts

@@ -1,5 +1,5 @@
 import { AgentMiddleware } from "../../contracts/middleware/middleware.contract.mjs";
-//#region ../@warlock.js/ai/src/middleware/helpers/for-tool.d.ts
+//#region ../ai/src/middleware/helpers/for-tool.d.ts
 /**
  * Scope a middleware's `tool`-level hooks to only fire for a
  * specific tool name (or a set of names). `execute` and `trip`

package/esm/middleware/helpers/for-tool.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"for-tool.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/helpers/for-tool.ts"],"mappings":";;;;;AAmDA;;;;;;;;;;;;;;AAGkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAHF,OAAA,CACd,SAAA,WAAoB,aAAA,UACpB,UAAA,EAAY,eAAA,GACX,eAAA"}
+{"version":3,"file":"for-tool.d.mts","names":[],"sources":["../../../../../../../../ai/src/middleware/helpers/for-tool.ts"],"mappings":";;;;;AAmDA;;;;;;;;;;;;;;AAGkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAHF,OAAA,CACd,SAAA,WAAoB,aAAA,UACpB,UAAA,EAAY,eAAA,GACX,eAAA"}

package/esm/middleware/helpers/for-tool.mjs

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/middleware/helpers/for-tool.ts
+//#region ../ai/src/middleware/helpers/for-tool.ts
 /**
 * Scope a middleware's `tool`-level hooks to only fire for a
 * specific tool name (or a set of names). `execute` and `trip`