@theokit/sdk 0.0.0-compat-580-20260905204608

package/dist/internal/mcp/oauth.d.ts

@@ -0,0 +1,19 @@
+/**
+ * OAuth 2.1 PKCE flow runner for MCP HTTP servers. See ADR D41.
+ *
+ * @internal
+ */
+import type { McpOAuthConfig } from "../../types/mcp.js";
+import { type OAuthTokens } from "./token-storage.js";
+/**
+ * Refresh an access token using `refresh_token`. Throws on failure.
+ *
+ */
+export declare function refreshAccessToken(serverName: string, clientId: string, refreshToken: string, oauth: McpOAuthConfig): Promise<OAuthTokens>;
+/**
+ * Run the full PKCE flow. Generates verifier+challenge+state, opens the
+ * authorization URL (browser or manual print), waits for the callback
+ * (localhost or stdin), exchanges code for tokens.
+ *
+ */
+export declare function runPkceFlow(serverName: string, clientId: string, scopes: string[] | undefined, oauth: McpOAuthConfig): Promise<OAuthTokens>;

package/dist/internal/mcp/token-storage.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The OAuth tokens held for one MCP server. See ADR D41.
+ *
+ * Persisted per server name by `setTokens` and returned unchanged by `getTokens`. Where it lands
+ * depends on what is installed: `keytar` puts the serialized bundle in the OS keychain, and
+ * without it the bundle is written to a JSON file at mode 0600 inside a 0700 directory — in
+ * PLAINTEXT, keyed by server name alongside every other server's tokens. Nothing here encrypts it.
+ *
+ * `refreshToken` is the field that matters most and the field that is optional. When present it
+ * outlives `accessToken` and can mint new ones, so a leaked store is a persistent compromise of
+ * the account rather than a temporary one. When absent, an expired access token means re-running
+ * the authorization flow.
+ *
+ * `expiresAt` and `obtainedAt` are both epoch milliseconds and both describe the ACCESS token —
+ * when it stops working, and when this bundle was issued. Nothing records when the refresh token
+ * expires, so a refresh rejected because the grant itself lapsed is only discovered at the token
+ * endpoint.
+ *
+ * The value is not validated on read: whatever JSON was stored is cast to this shape, so a
+ * hand-edited or truncated store yields an object whose fields may be missing rather than an
+ * error.
+ *
+ * `scope` records what the token was granted, as the server returned it. It is stored for
+ * inspection; nothing in this module enforces it.
+ *
+ * @public — re-exported from `@theokit/sdk/mcp-auth`, and therefore under semver.
+ */
+export interface OAuthTokens {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt: number;
+    scope?: string;
+    obtainedAt: number;
+}
+/**
+ * Persist tokens for `serverName`. Tries keychain first, falls back to file
+ * with chmod 600 (POSIX). Idempotent.
+ *
+ */
+export declare function setTokens(serverName: string, tokens: OAuthTokens): Promise<void>;
+/**
+ * Retrieve tokens for `serverName`. Returns undefined if absent.
+ *
+ */
+export declare function getTokens(serverName: string): Promise<OAuthTokens | undefined>;
+/**
+ * Serialize concurrent refresh attempts per server (EC-9). If a refresh is
+ * already in flight for the same `serverName`, the second caller awaits
+ * the same Promise.
+ *
+ */
+export declare function lockedRefresh(serverName: string, refreshFn: () => Promise<OAuthTokens>): Promise<OAuthTokens>;

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

@@ -0,0 +1,10 @@
+import type { ActiveMemoryResult } from "./active-memory-types.js";
+export declare class ActiveMemoryCache {
+    private readonly opts;
+    private readonly map;
+    constructor(opts?: ActiveMemoryCacheOptions);
+    get(userText: string, queryMode: string, tenantCtx?: TenantContext): ActiveMemoryResult | undefined;
+    set(userText: string, queryMode: string, result: ActiveMemoryResult, tenantCtx?: TenantContext): void;
+    size(): number;
+    private now;
+}

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

@@ -0,0 +1,8 @@
+import type { MemorySearchHit } from "./index-manager-contract.js";
+export type ActiveMemoryStatus = "ok" | "timeout" | "skipped" | "no-recall" | "error";
+export interface ActiveMemoryResult {
+    summary: string | undefined;
+    durationMs: number;
+    status: ActiveMemoryStatus;
+    hits: ReadonlyArray<MemorySearchHit>;
+}

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

@@ -0,0 +1,56 @@
+import type { CircuitBreaker } from "../retry/circuit-breaker.js";
+import { type TelemetryHandle } from "../telemetry/tracer.js";
+import type { ActiveMemoryCache } from "./active-memory-cache.js";
+import type { ActiveMemoryQueryMode, ActiveMemoryResult, ActiveMemoryStatus } from "./active-memory-types.js";
+import type { MemoryIndex } from "./memory-index.js";
+import { type MemoryRoot } from "./storage/memory-root.js";
+export type { ActiveMemoryQueryMode, ActiveMemoryResult, ActiveMemoryStatus };
+export interface RunActiveMemoryArgs {
+    userText: string;
+    priorMessages: ReadonlyArray<{
+        role: "user" | "assistant";
+        text: string;
+    }>;
+    index: MemoryIndex | undefined;
+    options: ActiveMemoryOptions;
+    /** Per-agent circuit breaker (Phase 8). */
+    breaker?: CircuitBreaker;
+    /** Per-agent result cache (Phase 8). */
+    cache?: ActiveMemoryCache;
+    /** Workspace root for transcript persistence. */
+    cwd?: string;
+    /**
+     * The memory root the caller already resolved. Falls back to the project store, which is right
+     * for a caller that has no `memory.directory` and wrong for one that does — so an agent passes
+     * its own (#463).
+     */
+    memoryRoot?: MemoryRoot;
+    /** When true, write transcript JSON under `<memory root>/transcripts/active-memory/`. */
+    persistTranscripts?: boolean;
+    /** Stable key the breaker + cache key by (default `default`). */
+    agentKey?: string;
+    /** Run id for transcript file naming. */
+    runId?: string;
+    /**
+     * T0.1 — optional telemetry handle. When provided AND telemetry is enabled,
+     * `memory.recall` span is emitted with `{ userId, namespace, scope, queryMode,
+     * hits, status }` attrs and `theokit_memory_recall_duration_ms` histogram is
+     * recorded with the same dimension keys. T4.9 will pin `userId/namespace/scope`
+     * to the cache-key invariant (cross-tenant leak fix).
+     */
+    telemetry?: TelemetryHandle;
+    /** User id surfaced as a memory.recall span attr for cross-tenant tracing. */
+    userId?: string;
+    /** Memory namespace (e.g. `default`, `<orgId>`) for span/histogram dimensions. */
+    namespace?: string;
+    /** Memory scope (`session` / `user` / `global`) for span/histogram dimensions. */
+    scope?: string;
+    /**
+     * T4.7 — AbortSignal propagation. When the caller's signal aborts,
+     * the active-memory recall exits early with `status: "skipped"` and
+     * summary `undefined`. Prevents long-running embedding calls from
+     * blocking agent.dispose() or user-initiated cancellation.
+     */
+    signal?: AbortSignal;
+}
+export declare function runActiveMemory(args: RunActiveMemoryArgs): Promise<ActiveMemoryResult>;

package/dist/internal/memory/adapters/azure-openai-embedding.d.cts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const azureOpenAiMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

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

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const azureOpenAiMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/catalog.d.cts

@@ -0,0 +1 @@
+export {};

package/dist/internal/memory/adapters/catalog.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/internal/memory/adapters/cohere-embedding.d.cts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const cohereMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

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

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const cohereMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/deepinfra-embedding.d.cts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const deepinfraMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

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

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const deepinfraMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/gemini-embedding.d.cts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const geminiMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

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

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const geminiMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/index.cjs

@@ -0,0 +1,30 @@
+'use strict';
+
+var chunkD6POWE7E_cjs = require('../../../chunk-D6POWE7E.cjs');
+var chunkGHX4P3V2_cjs = require('../../../chunk-GHX4P3V2.cjs');
+require('../../../chunk-24SYBZPL.cjs');
+require('../../../chunk-QOGNZMHD.cjs');
+require('../../../chunk-MUUQ2WFJ.cjs');
+require('../../../chunk-7A6535RA.cjs');
+require('../../../chunk-SA6K24NB.cjs');
+require('../../../chunk-I2PWY7VM.cjs');
+require('../../../chunk-KTTHHYEW.cjs');
+require('../../../chunk-J7J7J2GN.cjs');
+require('../../../chunk-6LHQPOMI.cjs');
+
+
+
+Object.defineProperty(exports, "createOpenAiCompatibleRuntime", {
+  enumerable: true,
+  get: function () { return chunkD6POWE7E_cjs.createOpenAiCompatibleRuntime; }
+});
+Object.defineProperty(exports, "LruEmbeddingCache", {
+  enumerable: true,
+  get: function () { return chunkGHX4P3V2_cjs.LruEmbeddingCache; }
+});
+Object.defineProperty(exports, "globalEmbeddingCache", {
+  enumerable: true,
+  get: function () { return chunkGHX4P3V2_cjs.globalEmbeddingCache; }
+});
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/internal/memory/adapters/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs"}

package/dist/internal/memory/adapters/index.d.cts

@@ -0,0 +1,18 @@
+/**
+ * theokit#160 — the ONE embedding runtime, shared with `@theokit/sdk-memory`.
+ *
+ * The satellite used to carry a full copy of `createOpenAiCompatibleRuntime`, and the peer's catalog
+ * REPLACES core's at runtime when installed — so the copy that ran was not the copy most people
+ * read. That duplication produced theokit#128 (four adapters present in one copy, missing from the
+ * other, for two months), and every fix since had to be applied twice by hand: the `{model}` path
+ * substitution, then all three provider dialects.
+ *
+ * This is the shared leaf both packages now import. Semver-exempt, exactly like the
+ * `internal/persistence` and `internal/security` sub-paths that exist for the same reason: extracted
+ * packages need primitives that are not part of the stable public contract.
+ *
+ * Semver-exempt: NOT part of the stable `@theokit/sdk` API. The sub-path IS declared in
+ * `package.json` `exports`, so the names below must survive into the published declarations.
+ */
+export { globalEmbeddingCache, LruEmbeddingCache } from "../embedding-cache.js";
+export { createOpenAiCompatibleRuntime, type EmbeddingDialect, type OpenAiCompatibleConfig, } from "./openai-compatible.js";

package/dist/internal/memory/adapters/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * theokit#160 — the ONE embedding runtime, shared with `@theokit/sdk-memory`.
+ *
+ * The satellite used to carry a full copy of `createOpenAiCompatibleRuntime`, and the peer's catalog
+ * REPLACES core's at runtime when installed — so the copy that ran was not the copy most people
+ * read. That duplication produced theokit#128 (four adapters present in one copy, missing from the
+ * other, for two months), and every fix since had to be applied twice by hand: the `{model}` path
+ * substitution, then all three provider dialects.
+ *
+ * This is the shared leaf both packages now import. Semver-exempt, exactly like the
+ * `internal/persistence` and `internal/security` sub-paths that exist for the same reason: extracted
+ * packages need primitives that are not part of the stable public contract.
+ *
+ * Semver-exempt: NOT part of the stable `@theokit/sdk` API. The sub-path IS declared in
+ * `package.json` `exports`, so the names below must survive into the published declarations.
+ */
+export { globalEmbeddingCache, LruEmbeddingCache } from "../embedding-cache.js";
+export { createOpenAiCompatibleRuntime, type EmbeddingDialect, type OpenAiCompatibleConfig, } from "./openai-compatible.js";

package/dist/internal/memory/adapters/index.js

@@ -0,0 +1,13 @@
+export { createOpenAiCompatibleRuntime } from '../../../chunk-55GB6JYQ.js';
+export { LruEmbeddingCache, globalEmbeddingCache } from '../../../chunk-H73MEMQB.js';
+import '../../../chunk-XB4GI5RZ.js';
+import '../../../chunk-24MGQDK3.js';
+import '../../../chunk-FD2UT76F.js';
+import '../../../chunk-EH6XD3FY.js';
+import '../../../chunk-UKMBRMGT.js';
+import '../../../chunk-4MMWFSCD.js';
+import '../../../chunk-G7BLGBRN.js';
+import '../../../chunk-ALUN2B4W.js';
+import '../../../chunk-CZJ6Q7CW.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/internal/memory/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/internal/memory/adapters/jina-embedding.d.cts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const jinaMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

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

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const jinaMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/mistral-embedding.d.cts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const mistralMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/mistral-embedding.d.ts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const mistralMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/ollama-embedding.d.cts

@@ -0,0 +1,34 @@
+/**
+ * Ollama embedding adapter (T3.1, ADR D183).
+ *
+ * Targets Ollama's OpenAI-compatible `/v1/embeddings` endpoint and reuses
+ * the shared `createOpenAiCompatibleRuntime` factory. The differentiating
+ * bits:
+ *
+ *  - `authType: "none"` — Ollama local ignores `Authorization`. Sentinel
+ *    `"ollama-local"` is passed as apiKey to satisfy the factory contract
+ *    (mirrors peer-project `OLLAMA_DEFAULT_API_KEY = "ollama-local"`).
+ *  - `OLLAMA_HOST` overrides the default `http://localhost:11434`.
+ *  - `OLLAMA_API_KEY` (optional) overrides the sentinel for Ollama Cloud
+ *    or reverse-proxy auth setups.
+ *  - Default model: `nomic-embed-text` (768 dim, ~274MB). User can opt
+ *    into `all-minilm` (384 dim, ~45MB) or any other locally-installed
+ *    embedding model.
+ *
+ * EC-B MUST FIX (edge-case review 2026-05-21): empty text is rejected
+ * upstream in the shared factory (`classifyEntry` short-circuits to a
+ * zero vector). That behavior is acceptable here because the zero
+ * vector is identical for any empty input — downstream similarity
+ * calcs ignore zero-norm vectors via the existing `cosineSimilarity`
+ * guard. No additional fail-fast needed.
+ *
+ * EC-A MUST FIX (edge-case review 2026-05-21): dimension is locked
+ * by the `DIMENSION_BY_MODEL` table; an unknown model id throws
+ * `ConfigurationError(code: "embedding_unknown_model")` per the
+ * factory's EC-4 contract. Future model versions with different
+ * dimensions are added to the table here without breaking changes.
+ *
+ * @internal
+ */
+export declare const DEFAULT_OLLAMA_EMBEDDING_MODEL = "nomic-embed-text";
+export declare const ollamaMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/ollama-embedding.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Ollama embedding adapter (T3.1, ADR D183).
+ *
+ * Targets Ollama's OpenAI-compatible `/v1/embeddings` endpoint and reuses
+ * the shared `createOpenAiCompatibleRuntime` factory. The differentiating
+ * bits:
+ *
+ *  - `authType: "none"` — Ollama local ignores `Authorization`. Sentinel
+ *    `"ollama-local"` is passed as apiKey to satisfy the factory contract
+ *    (mirrors peer-project `OLLAMA_DEFAULT_API_KEY = "ollama-local"`).
+ *  - `OLLAMA_HOST` overrides the default `http://localhost:11434`.
+ *  - `OLLAMA_API_KEY` (optional) overrides the sentinel for Ollama Cloud
+ *    or reverse-proxy auth setups.
+ *  - Default model: `nomic-embed-text` (768 dim, ~274MB). User can opt
+ *    into `all-minilm` (384 dim, ~45MB) or any other locally-installed
+ *    embedding model.
+ *
+ * EC-B MUST FIX (edge-case review 2026-05-21): empty text is rejected
+ * upstream in the shared factory (`classifyEntry` short-circuits to a
+ * zero vector). That behavior is acceptable here because the zero
+ * vector is identical for any empty input — downstream similarity
+ * calcs ignore zero-norm vectors via the existing `cosineSimilarity`
+ * guard. No additional fail-fast needed.
+ *
+ * EC-A MUST FIX (edge-case review 2026-05-21): dimension is locked
+ * by the `DIMENSION_BY_MODEL` table; an unknown model id throws
+ * `ConfigurationError(code: "embedding_unknown_model")` per the
+ * factory's EC-4 contract. Future model versions with different
+ * dimensions are added to the table here without breaking changes.
+ *
+ * @internal
+ */
+export declare const DEFAULT_OLLAMA_EMBEDDING_MODEL = "nomic-embed-text";
+export declare const ollamaMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/openai-compatible.d.cts

@@ -0,0 +1,96 @@
+import type { CreateAdapterOptions, EmbeddingRuntime } from "../embedding-adapter.js";
+/**
+ * What one provider adapter tells {@link createOpenAiCompatibleRuntime} about
+ * its wire: where to POST, which environment variables carry the key and the
+ * base URL, which model to use by default, and how wide each model's vectors
+ * are.
+ *
+ * `id` is the provider id that ends up on errors and on
+ * `EmbeddingRuntime.id`, and is also the identity the SQLite vector index stores
+ * — changing it invalidates the vectors already on disk.
+ *
+ * `apiKeyEnv` is required, `baseUrlEnv` is not: a provider that declares no
+ * base-URL variable can only be redirected by passing `baseUrl` explicitly.
+ * Leave `dialect` unset for anything that speaks the OpenAI embedding wire.
+ */
+export interface OpenAiCompatibleConfig {
+    id: string;
+    defaultBaseUrl: string;
+    apiKeyEnv: string;
+    baseUrlEnv?: string;
+    defaultModel: string;
+    /**
+     * Dimension hint by model id. The chosen model MUST be in this table —
+     * unknown models throw `ConfigurationError(code: "embedding_unknown_model")`
+     * (EC-4 fix). This prevents vec0 virtual-table dimension mismatches that
+     * surface as cryptic errors downstream.
+     */
+    dimensionByModel: Record<string, number>;
+    /**
+     * Path component appended to `baseUrl` for the embeddings endpoint.
+     * Default `"/v1/embeddings"` (OpenAI canonical). REPLACES the default —
+     * does NOT concatenate. Used by DeepInfra (`"/v1/openai/embeddings"`),
+     * etc. (EC-2 fix).
+     */
+    embeddingsPath?: string;
+    /**
+     * theokit#159 — per-provider deviations from the OpenAI wire.
+     *
+     * The runtime was rigidly OpenAI-shaped: one auth header, one body, one response shape. Three of
+     * the ten catalog providers do not speak it, so every call they made was rejected — Azure
+     * authenticates with an `api-key` header and puts the deployment in the path, Cohere's `/v2/embed`
+     * takes `texts` and answers `{embeddings:{float}}`. Advertising a provider that cannot work is
+     * worse than not advertising it.
+     *
+     * Every hook is optional and its default is exactly the previous behaviour, so the seven
+     * providers that DO speak OpenAI are untouched.
+     */
+    dialect?: EmbeddingDialect;
+}
+/**
+ * theokit#159 — the three points where a provider may deviate from the OpenAI embedding wire.
+ *
+ * Deliberately three narrow hooks rather than a general "transform the request" seam: these are the
+ * only axes on which the supported providers actually differ, and a wider seam would invite
+ * per-provider logic that belongs in the adapter.
+ */
+export interface EmbeddingDialect {
+    /** Replaces `authorization: Bearer <key>`. */
+    authHeaders?: (apiKey: string) => Record<string, string>;
+    /** Replaces the `{ model, input }` request body. */
+    body?: (model: string, inputs: ReadonlyArray<string>) => Record<string, unknown>;
+    /** Replaces reading vectors from `json.data[].embedding`. Return `undefined` when unparseable. */
+    vectors?: (json: unknown) => number[][] | undefined;
+}
+/**
+ * Build an {@link EmbeddingRuntime} for a provider that speaks the OpenAI
+ * embedding wire — or, through `cfg.dialect`, one that deviates from it in a
+ * known way. Every adapter in the memory catalog is a thin call to this.
+ *
+ * Resolution order for each setting is explicit option, then environment
+ * variable, then the config default. Two things are checked before any request
+ * is sent, so a misconfiguration fails at creation rather than at first search:
+ * a missing or empty key rejects with an `AuthenticationError` carrying
+ * `embedding_missing_api_key`, and a model absent from `dimensionByModel`
+ * rejects with a `ConfigurationError` carrying `embedding_unknown_model`. The
+ * second check exists because the vector index is created at a fixed width — an
+ * unknown dimension would surface much later as a vec0 mismatch.
+ *
+ * `{model}` in `embeddingsPath` is replaced with the URL-encoded model, which is
+ * how Azure addresses a deployment in the path. `embeddingsPath` replaces the
+ * default `/v1/embeddings` rather than being appended to it.
+ *
+ * The returned `embed` batches at 100 texts per request and runs at most 3
+ * requests concurrently, preserving input order. Whitespace-only inputs never
+ * reach the network and come back as an all-zero vector. Results are cached by
+ * model and text; the cache defaults to a process-wide LRU of 5000 entries, so
+ * pass `options.cache` when runtimes must not share entries.
+ *
+ * Failed requests retry up to twice on 429 and 5xx with a 50ms-per-attempt
+ * linear backoff. Anything else, and a retry budget that runs out, throws the
+ * typed error the OpenAI-compatible mapper builds from the status and body. A
+ * response that parses but carries no vectors throws a `NetworkError` with
+ * `embedding_invalid_response`. There is no request timeout here — cancellation
+ * is the caller's to impose.
+ */
+export declare function createOpenAiCompatibleRuntime(cfg: OpenAiCompatibleConfig, options: CreateAdapterOptions): Promise<EmbeddingRuntime>;

package/dist/internal/memory/adapters/openai-compatible.d.ts

@@ -0,0 +1,96 @@
+import type { CreateAdapterOptions, EmbeddingRuntime } from "../embedding-adapter.js";
+/**
+ * What one provider adapter tells {@link createOpenAiCompatibleRuntime} about
+ * its wire: where to POST, which environment variables carry the key and the
+ * base URL, which model to use by default, and how wide each model's vectors
+ * are.
+ *
+ * `id` is the provider id that ends up on errors and on
+ * `EmbeddingRuntime.id`, and is also the identity the SQLite vector index stores
+ * — changing it invalidates the vectors already on disk.
+ *
+ * `apiKeyEnv` is required, `baseUrlEnv` is not: a provider that declares no
+ * base-URL variable can only be redirected by passing `baseUrl` explicitly.
+ * Leave `dialect` unset for anything that speaks the OpenAI embedding wire.
+ */
+export interface OpenAiCompatibleConfig {
+    id: string;
+    defaultBaseUrl: string;
+    apiKeyEnv: string;
+    baseUrlEnv?: string;
+    defaultModel: string;
+    /**
+     * Dimension hint by model id. The chosen model MUST be in this table —
+     * unknown models throw `ConfigurationError(code: "embedding_unknown_model")`
+     * (EC-4 fix). This prevents vec0 virtual-table dimension mismatches that
+     * surface as cryptic errors downstream.
+     */
+    dimensionByModel: Record<string, number>;
+    /**
+     * Path component appended to `baseUrl` for the embeddings endpoint.
+     * Default `"/v1/embeddings"` (OpenAI canonical). REPLACES the default —
+     * does NOT concatenate. Used by DeepInfra (`"/v1/openai/embeddings"`),
+     * etc. (EC-2 fix).
+     */
+    embeddingsPath?: string;
+    /**
+     * theokit#159 — per-provider deviations from the OpenAI wire.
+     *
+     * The runtime was rigidly OpenAI-shaped: one auth header, one body, one response shape. Three of
+     * the ten catalog providers do not speak it, so every call they made was rejected — Azure
+     * authenticates with an `api-key` header and puts the deployment in the path, Cohere's `/v2/embed`
+     * takes `texts` and answers `{embeddings:{float}}`. Advertising a provider that cannot work is
+     * worse than not advertising it.
+     *
+     * Every hook is optional and its default is exactly the previous behaviour, so the seven
+     * providers that DO speak OpenAI are untouched.
+     */
+    dialect?: EmbeddingDialect;
+}
+/**
+ * theokit#159 — the three points where a provider may deviate from the OpenAI embedding wire.
+ *
+ * Deliberately three narrow hooks rather than a general "transform the request" seam: these are the
+ * only axes on which the supported providers actually differ, and a wider seam would invite
+ * per-provider logic that belongs in the adapter.
+ */
+export interface EmbeddingDialect {
+    /** Replaces `authorization: Bearer <key>`. */
+    authHeaders?: (apiKey: string) => Record<string, string>;
+    /** Replaces the `{ model, input }` request body. */
+    body?: (model: string, inputs: ReadonlyArray<string>) => Record<string, unknown>;
+    /** Replaces reading vectors from `json.data[].embedding`. Return `undefined` when unparseable. */
+    vectors?: (json: unknown) => number[][] | undefined;
+}
+/**
+ * Build an {@link EmbeddingRuntime} for a provider that speaks the OpenAI
+ * embedding wire — or, through `cfg.dialect`, one that deviates from it in a
+ * known way. Every adapter in the memory catalog is a thin call to this.
+ *
+ * Resolution order for each setting is explicit option, then environment
+ * variable, then the config default. Two things are checked before any request
+ * is sent, so a misconfiguration fails at creation rather than at first search:
+ * a missing or empty key rejects with an `AuthenticationError` carrying
+ * `embedding_missing_api_key`, and a model absent from `dimensionByModel`
+ * rejects with a `ConfigurationError` carrying `embedding_unknown_model`. The
+ * second check exists because the vector index is created at a fixed width — an
+ * unknown dimension would surface much later as a vec0 mismatch.
+ *
+ * `{model}` in `embeddingsPath` is replaced with the URL-encoded model, which is
+ * how Azure addresses a deployment in the path. `embeddingsPath` replaces the
+ * default `/v1/embeddings` rather than being appended to it.
+ *
+ * The returned `embed` batches at 100 texts per request and runs at most 3
+ * requests concurrently, preserving input order. Whitespace-only inputs never
+ * reach the network and come back as an all-zero vector. Results are cached by
+ * model and text; the cache defaults to a process-wide LRU of 5000 entries, so
+ * pass `options.cache` when runtimes must not share entries.
+ *
+ * Failed requests retry up to twice on 429 and 5xx with a 50ms-per-attempt
+ * linear backoff. Anything else, and a retry budget that runs out, throws the
+ * typed error the OpenAI-compatible mapper builds from the status and body. A
+ * response that parses but carries no vectors throws a `NetworkError` with
+ * `embedding_invalid_response`. There is no request timeout here — cancellation
+ * is the caller's to impose.
+ */
+export declare function createOpenAiCompatibleRuntime(cfg: OpenAiCompatibleConfig, options: CreateAdapterOptions): Promise<EmbeddingRuntime>;

package/dist/internal/memory/adapters/openai-embedding.d.cts

@@ -0,0 +1,12 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+/**
+ * Vector width per OpenAI embedding model.
+ *
+ * Exported because Azure OpenAI HOSTS these same models, so the Azure adapter was carrying a
+ * byte-identical copy — and this table is a correctness gate, not a hint:
+ * `createOpenAiCompatibleRuntime` throws `embedding_unknown_model` for anything absent, and a wrong
+ * number produces a vec0 dimension mismatch that surfaces much later. Two copies meant adding the
+ * next model to one file silently broke the other provider.
+ */
+export declare const OPENAI_EMBEDDING_DIMENSIONS: Readonly<Record<string, number>>;
+export declare const openAiMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/openai-embedding.d.ts

@@ -0,0 +1,12 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+/**
+ * Vector width per OpenAI embedding model.
+ *
+ * Exported because Azure OpenAI HOSTS these same models, so the Azure adapter was carrying a
+ * byte-identical copy — and this table is a correctness gate, not a hint:
+ * `createOpenAiCompatibleRuntime` throws `embedding_unknown_model` for anything absent, and a wrong
+ * number produces a vec0 dimension mismatch that surfaces much later. Two copies meant adding the
+ * next model to one file silently broke the other provider.
+ */
+export declare const OPENAI_EMBEDDING_DIMENSIONS: Readonly<Record<string, number>>;
+export declare const openAiMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/openrouter-embedding.d.cts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const openRouterMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/openrouter-embedding.d.ts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const openRouterMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/voyage-embedding.d.cts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const voyageMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/voyage-embedding.d.ts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const voyageMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/corpus-sync.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The corpus walk: read every markdown file under the memory root, and re-chunk the ones that
+ * changed.
+ *
+ * One of the four concerns that shared `IndexManager`, and the one with the most distinct reason to
+ * change — "which files are in the corpus and when is one stale" is a question about the filesystem,
+ * not about search or about the schema. It takes a {@link MemoryIndexRepository} rather than a
+ * database, so it cannot reach past it into SQL.
+ *
+ * The staleness test is the content hash, NOT the mtime. mtime is written into `files` for
+ * observability; a file touched without being edited must not cost a re-chunk, and a file restored
+ * from a backup with an older mtime must not be skipped.
+ *
+ * @internal
+ */
+import type { MemoryIndexRepository } from "./index-repository.js";
+import type { MemoryRoot } from "./storage/memory-root.js";
+export interface CorpusSyncCounts {
+    readonly filesScanned: number;
+    readonly filesUpdated: number;
+    readonly chunksWritten: number;
+}
+export declare function syncCorpus(repo: MemoryIndexRepository, memoryRoot: MemoryRoot): Promise<CorpusSyncCounts>;