@theokit/sdk-memory 0.3.1 → 0.3.3

package/dist/internal/active-memory/active-memory-cache.d.ts

@@ -21,6 +21,24 @@ export interface ActiveMemoryCacheOptions {
     capacity?: number;
     now?: () => number;
 }
+/**
+ * A bounded, TTL-expiring cache of recall results, so two identical sends in
+ * quick succession run one search.
+ *
+ * Entries expire `ttlMs` after they were written (default 15s) and are dropped
+ * on the read that finds them expired. A read that hits also moves the entry to
+ * the most-recent position, so eviction under pressure removes the
+ * least-recently-read entry rather than the oldest write.
+ *
+ * The key covers the query text, the query mode, and the tenant triple
+ * (`namespace`, `userId`, `scope`) joined by NUL bytes. Passing no tenant
+ * context is allowed and hashes as three empty strings — safe only when the
+ * process serves a single tenant.
+ *
+ * Not process-wide: construct one per agent. Nothing here expires in the
+ * background, so an untouched entry occupies its slot until it is read or
+ * evicted.
+ */
 export declare class ActiveMemoryCache {
     private readonly opts;
     private readonly map;

package/dist/internal/active-memory/active-memory-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"active-memory-cache.d.ts","sourceRoot":"","sources":["../../../src/internal/active-memory/active-memory-cache.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,wBAAwB;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAUD,qBAAa,iBAAiB;IAGhB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAiC;gBAExB,IAAI,GAAE,wBAA6B;IAEhE,GAAG,CACD,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,aAAa,GACxB,kBAAkB,GAAG,SAAS;IAcjC,GAAG,CACD,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,kBAAkB,EAC1B,SAAS,CAAC,EAAE,aAAa,GACxB,IAAI;IAYP,IAAI,IAAI,MAAM;IAId,OAAO,CAAC,GAAG;CAGZ;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}
+{"version":3,"file":"active-memory-cache.d.ts","sourceRoot":"","sources":["../../../src/internal/active-memory/active-memory-cache.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,wBAAwB;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAUD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,iBAAiB;IAGhB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAiC;gBAExB,IAAI,GAAE,wBAA6B;IAEhE,GAAG,CACD,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,aAAa,GACxB,kBAAkB,GAAG,SAAS;IAcjC,GAAG,CACD,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,kBAAkB,EAC1B,SAAS,CAAC,EAAE,aAAa,GACxB,IAAI;IAYP,IAAI,IAAI,MAAM;IAId,OAAO,CAAC,GAAG;CAGZ;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/internal/active-memory/active-memory-types.d.ts

@@ -19,8 +19,33 @@
  * @internal
  */
 import type { MemorySearchHit } from "../index/index-manager-contract.js";
+/**
+ * How the recall query is built from the conversation.
+ *
+ * `message` uses only the incoming user text. `recent` (the default) prepends
+ * the last few user turns, so a follow-up like "and the other one?" still
+ * carries its subject. `full` prepends every prior user turn, which broadens
+ * recall but lets an old topic dominate a long conversation. Assistant turns are
+ * never included in any mode.
+ */
 export type ActiveMemoryQueryMode = "message" | "recent" | "full";
+/**
+ * Outcome of one recall attempt.
+ *
+ * `ok` is the only status that carries a summary. `no-recall` means the search
+ * ran and matched nothing, or the built query was empty. `skipped` means no
+ * search was attempted at all — recall disabled, no index, or the circuit
+ * breaker open. `timeout` means the search outlived `timeoutMs`, and `error`
+ * that it threw. The four non-`ok` statuses are reported, never thrown: recall
+ * failing must not fail the agent run.
+ */
 export type ActiveMemoryStatus = "ok" | "timeout" | "skipped" | "no-recall" | "error";
+/**
+ * Result of one recall attempt. `summary` is set only when `status` is `ok`, and
+ * is the text the system-prompt pipeline injects. `hits` carries the underlying
+ * matches so a caller can render its own block instead. `durationMs` covers the
+ * search only, and is 0 on the `skipped` paths.
+ */
 export interface ActiveMemoryResult {
     summary: string | undefined;
     durationMs: number;

package/dist/internal/active-memory/active-memory-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"active-memory-types.d.ts","sourceRoot":"","sources":["../../../src/internal/active-memory/active-memory-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAE1E,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;AAElE,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,OAAO,CAAC;AAEtF,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,IAAI,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;CACtC"}
+{"version":3,"file":"active-memory-types.d.ts","sourceRoot":"","sources":["../../../src/internal/active-memory/active-memory-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAE1E;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;AAElE;;;;;;;;;GASG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,OAAO,CAAC;AAEtF;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,IAAI,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;CACtC"}

package/dist/internal/active-memory/active-memory.d.ts

@@ -21,43 +21,34 @@
  * iter 44-75; 2 inlined adapters added: adapter-http-error iter 73
  * + adapter-catalog renamed iter 74).
  *
- * **Cross-package telemetry contract:** sdk-core's `internal/telemetry/`
- * is not part of the public surface. sdk-memory inlines minimal
- * structural mirrors of `OTelSpan` + `TelemetryHandle` here AND the
- * 2 constant strings the file uses (`memory.recall` span name +
- * `theokit_memory_recall_duration_ms` histogram name). The runtime
- * still receives + emits the canonical types via consumer call sites
- * — the structural mirrors only satisfy this file's local type
- * checking. When sdk-core exposes telemetry types publicly, these
- * mirrors MUST be replaced with the canonical imports.
+ * **Cross-package telemetry contract:** `OTelSpan` and `TelemetryHandle`
+ * are now imported from `@theokit/sdk`, which exports them since #295.
+ * This file previously inlined structural mirrors of both, with a note
+ * that they MUST be replaced once sdk-core made them public — and by
+ * the time anyone looked, the mirrors had drifted: they narrowed
+ * `setAttributes` to reject the `undefined` values the canonical type
+ * accepts, and declared `end()` without its `endTime` parameter. That
+ * is how a structural mirror fails: quietly, with both sides compiling.
+ *
+ * The 2 constant strings (`memory.recall` span name +
+ * `theokit_memory_recall_duration_ms` histogram name) are still inlined
+ * below, because sdk-core's `span-names.ts` remains private. They are
+ * values rather than types, so exporting them is a separate decision
+ * with a real bundle cost — unlike these two, which erase at build time.
  *
  * @internal
  */
+import type { TelemetryHandle } from "@theokit/sdk";
 import type { CircuitBreaker } from "../circuit-breaker.js";
 import type { MemoryIndex } from "../index/memory-index.js";
 import type { ActiveMemoryCache } from "./active-memory-cache.js";
 import type { ActiveMemoryQueryMode, ActiveMemoryResult, ActiveMemoryStatus } from "./active-memory-types.js";
 export type { ActiveMemoryQueryMode, ActiveMemoryResult, ActiveMemoryStatus };
-interface OTelSpan {
-    setAttribute(key: string, value: string | number | boolean): void;
-    setAttributes(attrs: Record<string, string | number | boolean>): void;
-    addEvent(name: string, attrs?: Record<string, string | number | boolean>): void;
-    setStatus(status: {
-        code: number;
-        message?: string;
-    }): void;
-    recordException(exception: unknown): void;
-    end(): void;
-    spanContext(): {
-        traceId: string;
-        spanId: string;
-    };
-    isRecording(): boolean;
-}
-interface TelemetryHandle {
-    startSpan(name: string, attrs?: Record<string, string | number | boolean>): OTelSpan;
-    recordHistogram(name: string, value: number, attrs?: Record<string, string | number | boolean>): void;
-}
+/**
+ * Tuning for one recall attempt. Recall is off unless `enabled` is exactly
+ * `true`, so an options object that omits it disables recall rather than
+ * enabling it with defaults.
+ */
 export interface ActiveMemoryOptions {
     /** Whether active recall is enabled. Default `false`. */
     enabled?: boolean;
@@ -70,6 +61,16 @@ export interface ActiveMemoryOptions {
     /** Number of recent user turns to include in `queryMode === "recent"`. Default `2`. */
     recentUserTurns?: number;
 }
+/**
+ * Everything {@link runActiveMemory} needs for one attempt. Only `userText`,
+ * `priorMessages`, `index` and `options` are required; the rest add breaker,
+ * cache, transcript persistence and telemetry, each of which is inert when
+ * omitted.
+ *
+ * `index` is accepted as `undefined` on purpose — an agent with memory
+ * configured but no index open is a normal state, and it produces a `skipped`
+ * result rather than an error.
+ */
 export interface RunActiveMemoryArgs {
     userText: string;
     priorMessages: ReadonlyArray<{
@@ -104,5 +105,29 @@ export interface RunActiveMemoryArgs {
     /** Memory scope (`session` / `user` / `global`) for span/histogram dimensions. */
     scope?: string;
 }
+/**
+ * Run one blocking recall before the system prompt is assembled, and report what
+ * happened. Never throws for a recall failure: a search that times out or
+ * rejects comes back as a `timeout` or `error` status with no summary, and the
+ * agent run continues without memory.
+ *
+ * The order of the short-circuits decides what a caller sees. Recall disabled or
+ * no index gives `skipped` with no search. An open circuit breaker gives
+ * `skipped` too. A cache hit returns the earlier result as-is, which means it
+ * also returns that result's `status` and `durationMs` — a cached `no-recall`
+ * looks exactly like a fresh one. An empty query gives `no-recall`.
+ *
+ * Only a real search reaches the breaker: `timeout` records a timeout, `ok` and
+ * `no-recall` record a success, and `error` records neither, so a provider that
+ * keeps throwing will not trip the breaker.
+ *
+ * `timeoutMs` bounds how long this waits, not how long the search runs — the
+ * underlying `index.search` is left running when the timer wins. The search asks
+ * the index for at most 5 hits regardless of options.
+ *
+ * Cache entries are keyed by tenant as well as by query text, so two callers
+ * with the same question and different `userId` / `namespace` / `scope` never
+ * share an entry.
+ */
 export declare function runActiveMemory(args: RunActiveMemoryArgs): Promise<ActiveMemoryResult>;
 //# sourceMappingURL=active-memory.d.ts.map

package/dist/internal/active-memory/active-memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"active-memory.d.ts","sourceRoot":"","sources":["../../../src/internal/active-memory/active-memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,OAAO,KAAK,EAAE,iBAAiB,EAAiB,MAAM,0BAA0B,CAAC;AAIjF,OAAO,KAAK,EACV,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,CAAC;AAU9E,UAAU,QAAQ;IAChB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IAClE,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC;IAChF,SAAS,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5D,eAAe,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1C,GAAG,IAAI,IAAI,CAAC;IACZ,WAAW,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,WAAW,IAAI,OAAO,CAAC;CACxB;AAED,UAAU,eAAe;IACvB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,QAAQ,CAAC;IACrF,eAAe,CACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAChD,IAAI,CAAC;CACT;AAED,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uDAAuD;IACvD,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uFAAuF;IACvF,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3E,KAAK,EAAE,WAAW,GAAG,SAAS,CAAC;IAC/B,OAAO,EAAE,mBAAmB,CAAC;IAC7B,2CAA2C;IAC3C,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,wCAAwC;IACxC,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AASD,wBAAsB,eAAe,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsD5F"}
+{"version":3,"file":"active-memory.d.ts","sourceRoot":"","sources":["../../../src/internal/active-memory/active-memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAY,eAAe,EAAE,MAAM,cAAc,CAAC;AAE9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,OAAO,KAAK,EAAE,iBAAiB,EAAiB,MAAM,0BAA0B,CAAC;AAIjF,OAAO,KAAK,EACV,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,CAAC;AAmB9E;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uDAAuD;IACvD,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uFAAuF;IACvF,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3E,KAAK,EAAE,WAAW,GAAG,SAAS,CAAC;IAC/B,OAAO,EAAE,mBAAmB,CAAC;IAC7B,2CAA2C;IAC3C,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,wCAAwC;IACxC,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AASD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsD5F"}

package/dist/internal/adapter-http-error.d.ts

@@ -58,6 +58,24 @@ interface MapOpenAiErrorArgs {
     headers: Headers | undefined;
     endpoint: string;
 }
+/**
+ * Turn a failed OpenAI-shaped HTTP response into the typed error the SDK throws.
+ * Builds the error, it does not throw it.
+ *
+ * The HTTP status picks the class: 401 and 403 give an `AuthenticationError`,
+ * 429 a `RateLimitError`, 400 a `ConfigurationError`, 408 and 5xx a
+ * `NetworkError`, and anything else an `UnknownAgentError`.
+ *
+ * The `code` on the metadata is finer than the class and is read from
+ * `body.error.code` (or `.type`) first, so a 400 that names a context-window
+ * problem carries `context_too_long` rather than `invalid_request`. A body code
+ * naming an exhausted quota, and HTTP 402, both map to `quota_exceeded` — note
+ * that a 402 keeps that code while still producing an `UnknownAgentError`,
+ * because no status branch claims it.
+ *
+ * The raw body rides along on the metadata, truncated to about 2KB and passed
+ * through secret redaction, so it is safe to log.
+ */
 export declare function mapOpenAICompatibleError(args: MapOpenAiErrorArgs): TheokitAgentError;
 export {};
 //# sourceMappingURL=adapter-http-error.d.ts.map

package/dist/internal/adapter-http-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter-http-error.d.ts","sourceRoot":"","sources":["../../src/internal/adapter-http-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,aAAa,EAGlB,KAAK,iBAAiB,EAEvB,MAAM,qBAAqB,CAAC;AAM7B;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAOhF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAKlD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,aAAa,CAWhB;AAED,UAAU,kBAAkB;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,kBAAkB,GAAG,iBAAiB,CA6BpF"}
+{"version":3,"file":"adapter-http-error.d.ts","sourceRoot":"","sources":["../../src/internal/adapter-http-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,aAAa,EAGlB,KAAK,iBAAiB,EAEvB,MAAM,qBAAqB,CAAC;AAM7B;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAOhF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAKlD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,aAAa,CAWhB;AAED,UAAU,kBAAkB;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,kBAAkB,GAAG,iBAAiB,CA6BpF"}

package/dist/internal/circuit-breaker.d.ts

@@ -20,6 +20,23 @@ interface KeyState {
     consecutiveTimeouts: number;
     cooldownUntilMs: number;
 }
+/**
+ * Stops calling a recall path that keeps timing out.
+ *
+ * After `maxTimeouts` consecutive timeouts on a key (default 3) the breaker
+ * opens and {@link CircuitBreaker.shouldSkip} reports `true` until `cooldownMs`
+ * has elapsed (default 60s). The first `shouldSkip` after the cooldown closes
+ * the breaker and resets the counter, so it re-opens only after another full run
+ * of timeouts.
+ *
+ * It counts timeouts, not failures. An error recorded by neither
+ * `recordTimeout` nor `recordSuccess` leaves the counter where it was, so a call
+ * path that throws rather than hanging will never trip it.
+ *
+ * State is per key and held in this instance, which is what keeps two agents in
+ * one process from sharing a counter. Construct one per agent and pass a stable
+ * key.
+ */
 export declare class CircuitBreaker {
     private readonly opts;
     private readonly states;

package/dist/internal/circuit-breaker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../src/internal/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,UAAU,QAAQ;IAChB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;CACzB;AAKD,qBAAa,cAAc;IAGb,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;gBAEzB,IAAI,GAAE,qBAA0B;IAE7D,6EAA6E;IAC7E,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAWhC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAOhC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAShC,+CAA+C;IAC/C,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC;IAIxC,OAAO,CAAC,GAAG;CAGZ"}
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../src/internal/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,UAAU,QAAQ;IAChB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;CACzB;AAKD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,cAAc;IAGb,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;gBAEzB,IAAI,GAAE,qBAA0B;IAE7D,6EAA6E;IAC7E,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAWhC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAOhC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAShC,+CAA+C;IAC/C,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC;IAIxC,OAAO,CAAC,GAAG;CAGZ"}

package/dist/internal/dreaming/dreaming-diary.d.ts

@@ -31,8 +31,35 @@ export interface DiaryEntry {
     clustersCreated: number;
     notesWritten: number;
 }
+/** Path to the dream diary, `<memory root>/dream-diary.md`. Pure path computation. */
 export declare function diaryPath(cwd: string): string;
+/**
+ * Render one entry as the markdown block {@link appendDiaryEntry} writes: an h2
+ * heading carrying the ISO timestamp, then a bullet list of the counts, prefixed
+ * by the first eight hex characters of {@link entryHash}.
+ */
 export declare function renderDiaryEntry(entry: DiaryEntry): string;
+/**
+ * Append one entry to the dream diary, creating the file with a `# Dream Diary`
+ * header when it does not exist yet. The whole file is rewritten through an
+ * atomic replace, so a crash mid-write leaves the previous diary intact rather
+ * than a truncated one.
+ *
+ * The parent directory is not created here. Call this against a workspace whose
+ * memory directory already exists — a dreaming sweep does, because it has just
+ * read `MEMORY.md` from it.
+ *
+ * Appending is unconditional: passing an entry that was already written adds a
+ * second block. The hash identifies repeated content, it does not suppress it.
+ */
 export declare function appendDiaryEntry(cwd: string, entry: DiaryEntry): Promise<void>;
+/**
+ * A sha256 over the five counts of an entry, as a hex string.
+ *
+ * The timestamp is deliberately NOT part of the hash, so two sweeps that changed
+ * nothing produce the same hash at different times — that is the signal the
+ * diary is meant to carry. It also means the hash does not identify an entry
+ * uniquely.
+ */
 export declare function entryHash(entry: DiaryEntry): string;
 //# sourceMappingURL=dreaming-diary.d.ts.map

package/dist/internal/dreaming/dreaming-diary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dreaming-diary.d.ts","sourceRoot":"","sources":["../../../src/internal/dreaming/dreaming-diary.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAc1D;AAED,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAUpF;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAYnD"}
+{"version":3,"file":"dreaming-diary.d.ts","sourceRoot":"","sources":["../../../src/internal/dreaming/dreaming-diary.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,sFAAsF;AACtF,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAc1D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAUpF;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAYnD"}

package/dist/internal/dreaming/dreaming-phases.d.ts

@@ -27,10 +27,21 @@ export interface DedupResult {
     kept: MemoryFact[];
     duplicatesRemoved: number;
 }
+/**
+ * A group of facts the REM phase judged related. `representativeText` is the
+ * text of the longest member, used as the cluster's heading in the consolidated
+ * note — longest, not most central, so it is a readable label rather than a
+ * centroid. `members` includes that fact as well.
+ */
 export interface Cluster {
     representativeText: string;
     members: ReadonlyArray<MemoryFact>;
 }
+/**
+ * What {@link remPhase} produced. Every input fact appears in exactly one
+ * cluster, so a fact related to nothing comes back as a cluster of one — the
+ * count is not a count of *interesting* groupings.
+ */
 export interface ClusterResult {
     clusters: Cluster[];
 }

package/dist/internal/dreaming/dreaming-phases.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dreaming-phases.d.ts","sourceRoot":"","sources":["../../../src/internal/dreaming/dreaming-phases.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,OAAO;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAKD,mFAAmF;AACnF,wBAAsB,UAAU,CAC9B,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,EAChC,SAAS,EAAE,gBAAgB,EAC3B,SAAS,GAAE,MAAgC,GAC1C,OAAO,CAAC,WAAW,CAAC,CActB;AAQD,6EAA6E;AAC7E,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,EAChC,SAAS,EAAE,gBAAgB,EAC3B,SAAS,GAAE,MAAkC,EAC7C,gBAAgB,GAAE,MAAoC,GACrD,OAAO,CAAC,aAAa,CAAC,CASxB;AAoCD,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAavF"}
+{"version":3,"file":"dreaming-phases.d.ts","sourceRoot":"","sources":["../../../src/internal/dreaming/dreaming-phases.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;CACpC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAKD,mFAAmF;AACnF,wBAAsB,UAAU,CAC9B,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,EAChC,SAAS,EAAE,gBAAgB,EAC3B,SAAS,GAAE,MAAgC,GAC1C,OAAO,CAAC,WAAW,CAAC,CActB;AAWD,6EAA6E;AAC7E,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,EAChC,SAAS,EAAE,gBAAgB,EAC3B,SAAS,GAAE,MAAkC,EAC7C,gBAAgB,GAAE,MAAoC,GACrD,OAAO,CAAC,aAAa,CAAC,CAQxB;AAoCD,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAavF"}

package/dist/internal/dreaming/dreaming-run.d.ts

@@ -8,8 +8,12 @@ import type { EmbeddingRuntime } from "../embedding/embedding-adapter.js";
  *   3. **deep** — write a `notes/dreamed-<ts>.md` per sweep with consolidated
  *                  clusters; append a diary entry.
  *
- * All file writes go through `replaceFileAtomic` (EC-3) and the entire sweep
- * holds the per-cwd mutex so a `Remember:` append can't race it.
+ * All file writes go through `replaceFileAtomic` (EC-3). The sweep holds a
+ * mutex for the whole run, so two sweeps over the same workspace serialize.
+ * Note the key is `dream:<cwd>`, while `appendFactToMarkdown` locks on the
+ * memory directory — different keys, so a concurrent `Remember:` append is NOT
+ * excluded by this lock. It cannot corrupt a file (each write is atomic), but a
+ * fact appended after the sweep read `MEMORY.md` is simply not in the sweep.
  *
  * Iter 60 (Stage 3 source-move #17): hybrid copy from sdk-core's
  * `internal/memory/dreaming/run.ts`. sdk-core retains its copy for
@@ -36,6 +40,18 @@ export interface DreamingOptions {
     /** Test hook — fixed timestamp for the run. */
     now?: () => number;
 }
+/**
+ * What one sweep did. `skipped` means `MEMORY.md` held no facts; `error` means
+ * the sweep threw and the counts are all zero.
+ *
+ * `factsAfter` is the count that survived in-memory deduplication, not a new
+ * size for `MEMORY.md` — the sweep does not rewrite it, so the duplicates it
+ * counted are still on disk and will be counted again next time. `notesWritten`
+ * is 0 or 1: one consolidated note per sweep, holding every cluster.
+ *
+ * `diaryEntryHash` is currently always `undefined`, on every path including
+ * success, even though the diary entry itself is written with a hash.
+ */
 export interface DreamingResult {
     status: "ok" | "skipped" | "error";
     factsBefore: number;
@@ -45,5 +61,21 @@ export interface DreamingResult {
     notesWritten: number;
     diaryEntryHash: string | undefined;
 }
+/**
+ * Run one consolidation sweep over `MEMORY.md`: drop near-duplicate facts,
+ * cluster what is left, write a consolidated note under `notes/`, and append a
+ * diary entry.
+ *
+ * Every fact is embedded on each sweep, and clustering compares every pair, so
+ * cost grows with the square of the corpus. That is why the REM phase looks at
+ * the first 500 facts only.
+ *
+ * Never rejects: a failure is written to stderr and reported as
+ * `status: "error"`, so a sweep scheduled inside an agent run cannot break it.
+ *
+ * The sweep is read-only with respect to `MEMORY.md`. It produces a note beside
+ * it and leaves the fact list untouched, which means running it twice produces
+ * two notes over the same facts.
+ */
 export declare function runDreamingSweep(options: DreamingOptions): Promise<DreamingResult>;
 //# sourceMappingURL=dreaming-run.d.ts.map

package/dist/internal/dreaming/dreaming-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dreaming-run.d.ts","sourceRoot":"","sources":["../../../src/internal/dreaming/dreaming-run.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAK1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,gBAAgB,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAElF"}
+{"version":3,"file":"dreaming-run.d.ts","sourceRoot":"","sources":["../../../src/internal/dreaming/dreaming-run.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAK1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,gBAAgB,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAElF"}

package/dist/internal/embedding/azure-openai-embedding.d.ts

@@ -17,5 +17,27 @@ import type { MemoryEmbeddingProviderAdapter } from "./embedding-adapter.js";
  * @internal
  */
 export declare const DEFAULT_AZURE_OPENAI_EMBEDDING_MODEL = "text-embedding-3-small";
+/**
+ * Azure OpenAI embeddings. Same models as the OpenAI adapter, addressed the
+ * Azure way, and the one adapter whose configuration is not just "set a key".
+ *
+ * Two things differ from every other adapter here. `model` names your Azure
+ * DEPLOYMENT, not an OpenAI model id — it is substituted into the path
+ * (`/openai/deployments/{model}/embeddings`) rather than sent in the body. And
+ * `AZURE_OPENAI_ENDPOINT` must be set to your resource URL, without the
+ * `/openai/...` suffix; the built-in default is a placeholder that resolves
+ * nowhere, so leaving it unset fails at the network rather than at
+ * configuration.
+ *
+ * Authentication uses the `api-key` header, which is what an Azure resource key
+ * expects; Entra ID bearer tokens are not supported by this adapter. Reads
+ * `AZURE_OPENAI_API_KEY`. The API version is pinned to `2024-02-01`.
+ *
+ * The deployment name still has to appear in the dimension table
+ * (`text-embedding-3-small`, `-3-large`, `ada-002`), so a deployment named
+ * anything else is refused with `embedding_unknown_model` — pass `model` as the
+ * matching id and point the base URL at the right deployment, or add the name to
+ * the table.
+ */
 export declare const azureOpenAiMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;
 //# sourceMappingURL=azure-openai-embedding.d.ts.map

package/dist/internal/embedding/azure-openai-embedding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"azure-openai-embedding.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/azure-openai-embedding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAK7E;;;;;;;;;;;;;;;;GAgBG;AAEH,eAAO,MAAM,oCAAoC,2BAA2B,CAAC;AAQ7E,eAAO,MAAM,yCAAyC,EAAE,8BA2BvD,CAAC"}
+{"version":3,"file":"azure-openai-embedding.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/azure-openai-embedding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAK7E;;;;;;;;;;;;;;;;GAgBG;AAEH,eAAO,MAAM,oCAAoC,2BAA2B,CAAC;AAQ7E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,yCAAyC,EAAE,8BA2BvD,CAAC"}

package/dist/internal/embedding/cohere-embedding.d.ts

@@ -1,7 +1,8 @@
 import type { MemoryEmbeddingProviderAdapter } from "./embedding-adapter.js";
 /**
- * Cohere embedding adapter — `POST /v2/embed` at `https://api.cohere.com`, which carries the
- * OpenAI-compatible `{ model, input }` request shape.
+ * Cohere embedding adapter — `POST /v2/embed` at `https://api.cohere.com`. Despite living beside
+ * the OpenAI-compatible adapters, this endpoint is NOT OpenAI-shaped in either direction; the
+ * `dialect` below is what makes it work.
  *
  * Honors `COHERE_API_KEY`.
  *
@@ -10,5 +11,20 @@ import type { MemoryEmbeddingProviderAdapter } from "./embedding-adapter.js";
  * @internal
  */
 export declare const DEFAULT_COHERE_EMBEDDING_MODEL = "embed-english-v3.0";
+/**
+ * Cohere embeddings. Priority 30, so it is auto-selected ahead of OpenAI when
+ * both keys are present.
+ *
+ * Cohere does not speak the OpenAI wire, and this adapter supplies a dialect for
+ * it: the request names its payload `texts`, the response returns
+ * `{embeddings: {float: [...]}}`, and `input_type` is sent as
+ * `search_document`. That last choice matters — Cohere's v3 models embed
+ * documents and queries into different spaces, and this runtime always embeds as
+ * a document, including the query side of a search. Expect somewhat weaker
+ * retrieval than a Cohere-native setup that embeds queries as `search_query`.
+ *
+ * Reads `COHERE_API_KEY`; no base-URL environment override is declared. The
+ * light models are 384 dimensions and the others 1024.
+ */
 export declare const cohereMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;
 //# sourceMappingURL=cohere-embedding.d.ts.map

package/dist/internal/embedding/cohere-embedding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cohere-embedding.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/cohere-embedding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAK7E;;;;;;;;;GASG;AAEH,eAAO,MAAM,8BAA8B,uBAAuB,CAAC;AASnE,eAAO,MAAM,oCAAoC,EAAE,8BAgClD,CAAC"}
+{"version":3,"file":"cohere-embedding.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/cohere-embedding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAK7E;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,8BAA8B,uBAAuB,CAAC;AASnE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,oCAAoC,EAAE,8BAgClD,CAAC"}

package/dist/internal/embedding/deepinfra-embedding.d.ts

@@ -14,5 +14,18 @@ import type { MemoryEmbeddingProviderAdapter } from "./embedding-adapter.js";
  * @internal
  */
 export declare const DEFAULT_DEEPINFRA_EMBEDDING_MODEL = "BAAI/bge-large-en-v1.5";
+/**
+ * Open-weight embedding models (BGE, E5, GTE, MiniLM) hosted by DeepInfra.
+ * Reach for it when you want a specific open model — particularly a multilingual
+ * one — behind a hosted API rather than running it yourself.
+ *
+ * Its endpoint is `/v1/openai/embeddings`, not the canonical `/v1/embeddings`;
+ * the wire format is otherwise OpenAI-shaped. Reads `DEEPINFRA_API_KEY` and
+ * honours `DEEPINFRA_API_BASE_URL`. Priority 13.
+ *
+ * Dimensions vary sharply across the ten models it knows (384 to 1024), and
+ * switching between them invalidates an existing vector index — the index drops
+ * every vector and re-embeds on the next sync.
+ */
 export declare const deepinfraMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;
 //# sourceMappingURL=deepinfra-embedding.d.ts.map

package/dist/internal/embedding/deepinfra-embedding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deepinfra-embedding.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/deepinfra-embedding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAK7E;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,iCAAiC,2BAA2B,CAAC;AAe1E,eAAO,MAAM,uCAAuC,EAAE,8BAmBrD,CAAC"}
+{"version":3,"file":"deepinfra-embedding.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/deepinfra-embedding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAK7E;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,iCAAiC,2BAA2B,CAAC;AAe1E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uCAAuC,EAAE,8BAmBrD,CAAC"}

package/dist/internal/embedding/embedding-adapter.d.ts

@@ -16,11 +16,21 @@ export interface MemoryEmbeddingProviderAdapter {
     readonly transport: "local" | "remote";
     /** Auth provider id used to resolve API keys (mirrors peer-project). */
     readonly authProviderId?: string;
-    /** Higher priority = auto-select this provider first when multiple are available. */
+    /**
+     * Ranking hint — higher means "prefer this one" — for a provider auto-selection that is NOT
+     * implemented. Nothing reads this field today: the provider is the one the caller names in
+     * `embedding: { provider }`, and omitting it builds no embedding runtime at all. Kept because
+     * the values are pinned by tests and mirrored in sdk-core's catalog.
+     */
     readonly autoSelectPriority?: number;
     /** Factory — instantiate a per-agent runtime. */
     create(options: CreateAdapterOptions): Promise<EmbeddingRuntime>;
 }
+/**
+ * Per-call overrides handed to {@link MemoryEmbeddingProviderAdapter.create}.
+ * Every field is optional; the adapter falls back to its own defaults and to
+ * the environment variables it declares.
+ */
 export interface CreateAdapterOptions {
     /** Override the adapter's `defaultModel`. */
     model?: string;
@@ -30,9 +40,19 @@ export interface CreateAdapterOptions {
     baseUrl?: string;
     /** Inject a fetch implementation (tests use this to stub HTTP). */
     fetch?: typeof fetch;
-    /** Optional cache instance (else a default LRU is created). */
+    /** Override the embedding cache. Defaults to a process-wide LRU shared by every runtime. */
     cache?: EmbeddingCache;
 }
+/**
+ * A live embedding provider, bound to one model. `dimension` is fixed at
+ * creation from the adapter's model table, which is what lets the SQLite vec0
+ * table and the Lance schema be created with the right width before the first
+ * vector arrives.
+ *
+ * `embed` resolves to one vector per input, in the same order. Whitespace-only
+ * inputs come back as an all-zero vector rather than an error, and downstream
+ * cosine similarity treats a zero-norm vector as similarity 0.
+ */
 export interface EmbeddingRuntime {
     readonly id: string;
     readonly model: string;
@@ -42,12 +62,26 @@ export interface EmbeddingRuntime {
     /** Observability — cache hit/miss + call counts. */
     stats(): EmbeddingRuntimeStats;
 }
+/**
+ * Counters accumulated by a runtime since it was created. `httpCalls` counts
+ * every request sent, including the ones that were retried, so `httpCalls`
+ * minus `retries` is the number of distinct batches attempted.
+ */
 export interface EmbeddingRuntimeStats {
     cacheHits: number;
     cacheMisses: number;
     httpCalls: number;
     retries: number;
 }
+/**
+ * The cache contract the shared runtime writes through. Keys are opaque — the
+ * runtime derives them from the model id and the text — so an implementation
+ * only has to behave like a bounded map.
+ *
+ * Pass one explicitly through {@link CreateAdapterOptions.cache} when entries
+ * must not be shared: the default is a single process-wide LRU, so two runtimes
+ * created in the same process see each other's entries.
+ */
 export interface EmbeddingCache {
     get(key: string): number[] | undefined;
     set(key: string, value: number[]): void;

package/dist/internal/embedding/embedding-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embedding-adapter.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/embedding-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,8BAA8B;IAC7C,sFAAsF;IACtF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,QAAQ,CAAC;IACvC,wEAAwE;IACxE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,qFAAqF;IACrF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,iDAAiD;IACjD,MAAM,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAClE;AAED,MAAM,WAAW,oBAAoB;IACnC,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,oFAAoF;IACpF,KAAK,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACzD,oDAAoD;IACpD,KAAK,IAAI,qBAAqB,CAAC;CAChC;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;IACvC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACxC,oCAAoC;IACpC,IAAI,IAAI,MAAM,CAAC;CAChB"}
+{"version":3,"file":"embedding-adapter.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/embedding-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,8BAA8B;IAC7C,sFAAsF;IACtF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,QAAQ,CAAC;IACvC,wEAAwE;IACxE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,iDAAiD;IACjD,MAAM,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAClE;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,4FAA4F;IAC5F,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,oFAAoF;IACpF,KAAK,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACzD,oDAAoD;IACpD,KAAK,IAAI,qBAAqB,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;IACvC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACxC,oCAAoC;IACpC,IAAI,IAAI,MAAM,CAAC;CAChB"}

package/dist/internal/embedding/gemini-embedding.d.ts

@@ -14,5 +14,14 @@ import type { MemoryEmbeddingProviderAdapter } from "./embedding-adapter.js";
  * @internal
  */
 export declare const DEFAULT_GEMINI_EMBEDDING_MODEL = "text-embedding-004";
+/**
+ * Google Gemini embeddings through Google's OpenAI-compatible surface at
+ * `/v1beta/openai/embeddings`. Gemini's native embedding endpoint
+ * (`/v1beta/models/{model}:embedContent`) has a different shape and is
+ * deliberately not used, so this composes with the shared runtime like the rest.
+ *
+ * Both known models are 768 dimensions. Reads `GEMINI_API_KEY`; no base-URL
+ * environment override is declared. Priority 30.
+ */
 export declare const geminiMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;
 //# sourceMappingURL=gemini-embedding.d.ts.map

package/dist/internal/embedding/gemini-embedding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gemini-embedding.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/gemini-embedding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAK7E;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,8BAA8B,uBAAuB,CAAC;AAOnE,eAAO,MAAM,oCAAoC,EAAE,8BAoBlD,CAAC"}
+{"version":3,"file":"gemini-embedding.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/gemini-embedding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAK7E;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,8BAA8B,uBAAuB,CAAC;AAOnE;;;;;;;;GAQG;AACH,eAAO,MAAM,oCAAoC,EAAE,8BAoBlD,CAAC"}

package/dist/internal/embedding/jina-embedding.d.ts

@@ -9,5 +9,14 @@ import type { MemoryEmbeddingProviderAdapter } from "./embedding-adapter.js";
  * @internal
  */
 export declare const DEFAULT_JINA_EMBEDDING_MODEL = "jina-embeddings-v3";
+/**
+ * Jina AI embeddings, over the standard OpenAI wire. Highest auto-select
+ * priority in the catalog (35), so it wins over OpenAI when both keys are
+ * present.
+ *
+ * Default `jina-embeddings-v3` at 1024 dimensions; the v2 models are 768 and
+ * 512. Reads `JINA_API_KEY`. No base-URL environment override is declared —
+ * point it elsewhere by passing `baseUrl` to `create`.
+ */
 export declare const jinaMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;
 //# sourceMappingURL=jina-embedding.d.ts.map

package/dist/internal/embedding/jina-embedding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jina-embedding.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/jina-embedding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAK7E;;;;;;;;GAQG;AAEH,eAAO,MAAM,4BAA4B,uBAAuB,CAAC;AAQjE,eAAO,MAAM,kCAAkC,EAAE,8BAiBhD,CAAC"}
+{"version":3,"file":"jina-embedding.d.ts","sourceRoot":"","sources":["../../../src/internal/embedding/jina-embedding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAK7E;;;;;;;;GAQG;AAEH,eAAO,MAAM,4BAA4B,uBAAuB,CAAC;AAQjE;;;;;;;;GAQG;AACH,eAAO,MAAM,kCAAkC,EAAE,8BAiBhD,CAAC"}