@theokit/sdk 1.5.0

package/dist/internal/llm/model-identifier.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Model identifier parsing (T1.2 follow-up, ADR D182 zero-config UX).
+ *
+ * SDK callers pass model strings like:
+ *   - `"ollama/llama3.2:3b"`             → provider="ollama", name="llama3.2:3b"
+ *   - `"anthropic/claude-3-5-sonnet"`    → provider="anthropic", name="claude-3-5-sonnet"
+ *   - `"openrouter/meta-llama/llama-3"`  → provider="openrouter", name="meta-llama/llama-3"
+ *   - `"claude-sonnet-4-6"`              → provider=undefined, name="claude-sonnet-4-6"
+ *
+ * The first `/` separates the provider from the rest. Models with embedded
+ * slashes (e.g. OpenRouter routing) keep the remainder intact. Tag suffixes
+ * (`:latest`, `:3b`) are preserved as part of the name — Ollama expects them.
+ *
+ * **Returns `undefined` provider** when no `/` is present so callers can
+ * fall back to env-var detection. Empty/whitespace components are treated
+ * as no-prefix.
+ *
+ * Aligned with OpenClaw `extensions/ollama/src/discovery-shared.ts`
+ * (`OLLAMA_PROVIDER_ID = "ollama"`) and Hermes `hermes_cli/providers.py`
+ * (ALIASES table, `normalize_provider`).
+ *
+ * @internal
+ */
+export declare function parseModelId(modelId: string | undefined): ParsedModelId;

package/dist/internal/llm/ollama-native.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Ollama native API client (T8.1 follow-up, ADR D191).
+ *
+ * Targets Ollama's native `/api/chat` endpoint with NDJSON streaming.
+ * Critical for **tool calling** — per OpenClaw upstream warning, the
+ * OpenAI-compat `/v1/chat/completions` endpoint BREAKS tool calling in
+ * Ollama (models emit raw tool JSON as text instead of structured
+ * `tool_calls` blocks). Mirrors OpenClaw `extensions/ollama/src/stream.ts`.
+ *
+ * @internal
+ */
+import type { LlmClient, LlmEvent, LlmFinish, LlmRequest } from "./types.js";
+export interface OllamaNativeClientOptions {
+    /** Optional API key for Ollama Cloud / reverse-proxy. Local Ollama ignores `Authorization`. */
+    apiKey?: string;
+    /** Base URL. Default `http://localhost:11434`. `/v1` suffix is stripped automatically. */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+export declare class OllamaNativeClient implements LlmClient {
+    private readonly options;
+    readonly name = "ollama";
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: OllamaNativeClientOptions);
+    stream(request: LlmRequest, signal: AbortSignal): AsyncGenerator<LlmEvent, LlmFinish, void>;
+}

package/dist/internal/llm/openai.d.ts

@@ -0,0 +1,9 @@
+import type { LlmClient, LlmEvent, LlmFinish, LlmRequest } from "./types.js";
+export declare class OpenAIClient implements LlmClient {
+    private readonly options;
+    readonly name = "openai";
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: OpenAIClientOptions);
+    stream(request: LlmRequest, signal: AbortSignal): AsyncGenerator<LlmEvent, LlmFinish, void>;
+}

package/dist/internal/llm/pool-aware-client.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `LlmClient` wrapper that pools multiple API keys for the same
+ * provider and rotates on HTTP 429/402/401 (ADRs D123-D133).
+ *
+ * Composition wrapper (D127) — wraps a builder that produces a real
+ * `LlmClient` for a given API key. The wrapper picks a key via the
+ * pool, instantiates the real client, attempts the stream, and on a
+ * pre-stream error decides retry-vs-rotate per the decision matrix.
+ *
+ * Once `yield*` starts (first event received), rotation is impossible —
+ * partial output would corrupt the stream. Same contract as
+ * `FallbackLlmClient` (D2).
+ *
+ * @internal
+ */
+export {};

package/dist/internal/llm/router.d.ts

@@ -0,0 +1,17 @@
+import type { CredentialPoolStrategy } from "./credential-pool-types.js";
+import type { LlmClient } from "./types.js";
+export interface ProviderRouterOptions {
+    primary: ProviderName;
+    fallback?: ProviderName[];
+    /** Credential pools per provider (ADRs D123-D133). Optional. */
+    apiKeys?: Record<string, string[]>;
+    /** Pool rotation strategy per provider. Optional; default `"fill_first"`. */
+    credentialPoolStrategy?: Record<string, CredentialPoolStrategy>;
+}
+export declare function resolveProviderChainAsync(options: ProviderRouterOptions): Promise<LlmClient[]>;
+/**
+ * Sync variant. Kept for backward compat with existing callers that
+ * already invoked discovery upfront (e.g., via Agent.create initialization).
+ * Builtins are still eagerly registered.
+ */
+export declare function resolveProviderChain(options: ProviderRouterOptions): LlmClient[];

package/dist/internal/llm/sse.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Minimal Server-Sent-Events parser. Consumes a fetch `Response` body
+ * stream and yields `{ event, data }` records as they arrive. Used by
+ * both the Anthropic and OpenAI streaming clients — neither vendor sends
+ * binary SSE so a simple text decoder is enough.
+ *
+ * @internal
+ */
+export declare function parseSseStream(body: ReadableStream<Uint8Array> | null, signal: AbortSignal): AsyncGenerator<SseRecord, void, void>;

package/dist/internal/llm/stream-relay.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared streaming helpers for `LlmClient` wrappers
+ * (`FallbackLlmClient`, `PoolAwareLlmClient`).
+ *
+ * `tryFirstEvent` probes the first chunk of a stream to decide
+ * whether the handshake succeeded. If it raises an
+ * `AuthenticationError`/`RateLimitError`/`NetworkError`, the wrapper
+ * captures the typed error for routing (rotate vs fallback) WITHOUT
+ * starting the actual yield. Once the first event lands, the stream
+ * is committed and partial-output cannot be reverted.
+ *
+ * `relay` yields the prefetched first chunk and then forwards the
+ * remaining generator output verbatim.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/llm/types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Provider-agnostic LLM types used by the real agent loop. Each concrete
+ * provider client (`anthropic.ts`, `openai.ts`) accepts an `LlmRequest`
+ * and yields a stream of `LlmEvent`s plus a final `LlmFinish` shape that
+ * the agent loop converts into our `SDKMessage` events.
+ *
+ * @internal
+ */
+export interface LlmTextPart {
+    type: "text";
+    text: string;
+}
+export interface LlmToolCallPart {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+export interface LlmToolResultPart {
+    type: "tool_result";
+    toolUseId: string;
+    content: string;
+    isError?: boolean;
+}
+export type LlmContentPart = LlmTextPart | LlmToolCallPart | LlmToolResultPart;
+export interface LlmMessage {
+    role: "system" | "user" | "assistant";
+    content: LlmContentPart[];
+}
+export interface LlmRequest {
+    model: string;
+    system?: string;
+    messages: LlmMessage[];
+    tools?: LlmTool[];
+    maxTokens?: number;
+    temperature?: number;
+}
+export type LlmEvent = {
+    type: "text_delta";
+    text: string;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: "stop";
+    reason: LlmStopReason;
+} | {
+    type: "error";
+    message: string;
+};
+export type LlmStopReason = "end_turn" | "tool_use" | "max_tokens" | "stop_sequence" | "error";
+export interface LlmFinish {
+    stopReason: LlmStopReason;
+    text: string;
+    toolCalls: LlmToolCallPart[];
+    inputTokens?: number;
+    outputTokens?: number;
+    /** Cache read tokens (Anthropic prompt caching / OpenAI cached). ADR D376. */
+    cacheReadTokens?: number;
+    /** Cache creation tokens (Anthropic only). ADR D376. */
+    cacheWriteTokens?: number;
+    /** Reasoning tokens (OpenAI o-series). ADR D376. */
+    reasoningTokens?: number;
+}
+export interface LlmClient {
+    readonly name: string;
+    stream(request: LlmRequest, signal: AbortSignal): AsyncGenerator<LlmEvent, LlmFinish, void>;
+}

package/dist/internal/llm/vertex-anthropic.d.ts

@@ -0,0 +1,40 @@
+/**
+ * GCP Vertex AI client for Anthropic Messages (Adoption Roadmap #8; ADRs
+ * D292, D293).
+ *
+ * v1 uses `:rawPredict` (non-streaming). Streaming via `:streamRawPredict`
+ * with SSE follows the same shape but is gated behind a future iteration —
+ * v1 returns the full response as a single delta to keep the streaming
+ * interface contract.
+ *
+ * Body massage (D292):
+ *  - inject `anthropic_version: "vertex-2023-10-16"`
+ *  - strip `model` from body (goes in URL)
+ *  - strip `stream` from body
+ *
+ * Uses native `fetch` only — no `@anthropic-ai/vertex-sdk` (D294).
+ *
+ * @internal
+ */
+import type { LlmClient, LlmEvent, LlmFinish, LlmRequest } from "./types.js";
+export interface VertexAnthropicClientOptions {
+    /** When undefined, resolved lazily via `resolveVertexProjectId()`. */
+    projectId?: string;
+    /** When undefined, resolved lazily via `resolveVertexLocation()`. */
+    location?: string;
+    /**
+     * OAuth access token. When provided, used as-is. When empty/undefined,
+     * resolved lazily per request via `resolveVertexAccessToken()` (D288).
+     */
+    apiKey?: string;
+    fetch?: typeof fetch;
+}
+export declare class VertexAnthropicClient implements LlmClient {
+    private readonly options;
+    readonly name = "vertex_anthropic";
+    private readonly fetchImpl;
+    constructor(options: VertexAnthropicClientOptions);
+    private resolveProjectOrThrow;
+    private resolveTokenOrThrow;
+    stream(request: LlmRequest, signal: AbortSignal): AsyncGenerator<LlmEvent, LlmFinish, void>;
+}

package/dist/internal/llm/vertex-auth.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Vertex AI access token + config resolution (ADRs D288, D295).
+ *
+ * Uses `google-auth-library` (required peer dep) for ADC discovery:
+ *   1. `GOOGLE_APPLICATION_CREDENTIALS` env (path to Service Account JSON)
+ *   2. `gcloud auth application-default login` cached credentials
+ *   3. Metadata server (GCE/GKE/Cloud Run/Cloud Functions)
+ *   4. Workload Identity Federation (WIF; configured via Service Account JSON)
+ *
+ * EC-3 absorbed: differentiate "peer dep missing" (throws ConfigurationError
+ * with install hint) from "no credentials in ADC chain" (returns undefined
+ * so caller can throw a clearer downstream error).
+ *
+ * @internal
+ */
+interface GoogleAuthClient {
+    getAccessToken: () => Promise<{
+        token: string | null;
+    }>;
+}
+export declare function resolveVertexAccessToken(): Promise<string | undefined>;
+/** Resolve project id via env vars (env-only in v1). */
+export declare function resolveVertexProjectId(): string | undefined;
+/** Resolve Vertex location (region) from env; defaults to `us-central1`. */
+export declare function resolveVertexLocation(): string;
+/** Test seam — reset cached auth client. */
+export declare function __resetVertexAuth(): void;
+/** Test seam — inject a custom client for unit tests. */
+export declare function __setVertexAuthClientForTests(client: GoogleAuthClient | undefined): void;
+export {};

package/dist/internal/llm/vertex-gemini.d.ts

@@ -0,0 +1,28 @@
+/**
+ * GCP Vertex AI Gemini client (Adoption Roadmap #8; ADR D291).
+ *
+ * Uses the **OpenAI-compat** endpoint:
+ *   POST https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{P}/locations/{L}/endpoints/openapi/chat/completions
+ *
+ * Wraps `OpenAIClient` with the Vertex baseUrl + lazy OAuth token from
+ * `google-auth-library` (D288). Limitation: Vertex silently drops
+ * unsupported OpenAI params (D264-style trade-off, documented in docs.md).
+ *
+ * @internal
+ */
+import type { LlmClient, LlmEvent, LlmFinish, LlmRequest } from "./types.js";
+export interface VertexGeminiClientOptions {
+    /** When undefined, resolved lazily via `resolveVertexProjectId()`. */
+    projectId?: string;
+    /** When undefined, resolved lazily via `resolveVertexLocation()`. */
+    location?: string;
+    /** When non-empty, used as-is. Otherwise resolved lazily via ADC. */
+    apiKey?: string;
+    fetch?: typeof fetch;
+}
+export declare class VertexGeminiClient implements LlmClient {
+    private readonly options;
+    readonly name = "vertex_gemini";
+    constructor(options: VertexGeminiClientOptions);
+    stream(request: LlmRequest, signal: AbortSignal): AsyncGenerator<LlmEvent, LlmFinish, void>;
+}

package/dist/internal/llm/vertex-router.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Vertex AI dispatcher (Adoption Roadmap #8; ADRs D291, D292, D301).
+ *
+ * `selectTransport` doesn't see the model id (the credential resolution
+ * happens before request dispatch). This client inspects `request.model`
+ * at stream time and delegates to either `VertexGeminiClient` (OpenAI-compat
+ * for Gemini) or `VertexAnthropicClient` (`:rawPredict` for Claude).
+ *
+ * @internal
+ */
+import type { LlmClient, LlmEvent, LlmFinish, LlmRequest } from "./types.js";
+export interface VertexRouterClientOptions {
+    apiKey?: string;
+    fetch?: typeof fetch;
+}
+export declare class VertexRouterClient implements LlmClient {
+    private readonly options;
+    readonly name = "vertex";
+    constructor(options: VertexRouterClientOptions);
+    stream(request: LlmRequest, signal: AbortSignal): AsyncGenerator<LlmEvent, LlmFinish, void>;
+}

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

@@ -0,0 +1,16 @@
+import type { McpServerConfig } from "../../types/mcp.js";
+export interface McpToolCallResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}
+export interface McpClient {
+    readonly name: string;
+    initialize(): Promise<void>;
+    listTools(): Promise<McpTool[]>;
+    callTool(name: string, args: Record<string, unknown>): Promise<McpToolCallResult>;
+    close(): Promise<void>;
+}
+export declare function createMcpClient(name: string, config: McpServerConfig): McpClient;

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

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

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

@@ -0,0 +1,45 @@
+import type { ActiveMemoryCache } from "./active-memory-cache.js";
+import type { CircuitBreaker } from "./circuit-breaker.js";
+import type { MemorySearchHit } from "./index-manager.js";
+import type { MemoryIndex } from "./memory-index.js";
+export type ActiveMemoryStatus = "ok" | "timeout" | "skipped" | "no-recall" | "error";
+export interface ActiveMemoryResult {
+    summary: string | undefined;
+    durationMs: number;
+    status: ActiveMemoryStatus;
+    hits: ReadonlyArray<MemorySearchHit>;
+}
+export interface ActiveMemoryOptions {
+    /** Whether active recall is enabled. Default `false`. */
+    enabled?: boolean;
+    /** Query construction strategy. Default `"recent"`. */
+    queryMode?: ActiveMemoryQueryMode;
+    /** Hard timeout in ms. Default `15000`. */
+    timeoutMs?: number;
+    /** Max chars in the summary. Default `220`. */
+    maxSummaryChars?: number;
+    /** Number of recent user turns to include in `queryMode === "recent"`. Default `2`. */
+    recentUserTurns?: number;
+}
+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;
+    /** When true, write transcript JSON under .theokit/memory/transcripts/active-memory/. */
+    persistTranscripts?: boolean;
+    /** Stable key the breaker + cache key by (default `default`). */
+    agentKey?: string;
+    /** Run id for transcript file naming. */
+    runId?: string;
+}
+export declare function runActiveMemory(args: RunActiveMemoryArgs): Promise<ActiveMemoryResult>;

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

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

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/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.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 OpenClaw `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.ts

@@ -0,0 +1,23 @@
+import type { CreateAdapterOptions, EmbeddingRuntime } from "../embedding-adapter.js";
+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;
+}
+export declare function createOpenAiCompatibleRuntime(cfg: OpenAiCompatibleConfig, options: CreateAdapterOptions): Promise<EmbeddingRuntime>;

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

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const openAiMemoryEmbeddingProviderAdapter: 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.ts

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

package/dist/internal/memory/atomic-write.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @deprecated Import from `../persistence/atomic-write.js` instead.
+ * Maintained as re-export for backward compatibility (ADR D59).
+ *
+ * @internal
+ */
+export { atomicWriteJson, replaceFileAtomic } from "../persistence/atomic-write.js";

package/dist/internal/memory/chunk-markdown.d.ts

@@ -0,0 +1,2 @@
+import type { MemoryChunk } from "./types.js";
+export declare function chunkMarkdown(text: string, options?: ChunkMarkdownOptions): MemoryChunk[];

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

@@ -0,0 +1,22 @@
+/**
+ * Consecutive-timeout circuit breaker for Active Memory recall.
+ *
+ * Mirrors OpenClaw's `circuitBreakerMaxTimeouts` + `circuitBreakerCooldownMs`
+ * config: after N consecutive timeouts the breaker trips and `shouldSkip`
+ * returns `true` until `cooldownMs` has elapsed. A successful recall resets
+ * the counter immediately.
+ *
+ * Per-key isolation so two agents in the same process don't share a counter.
+ *
+ * @internal
+ */
+export declare class CircuitBreaker {
+    private readonly opts;
+    private readonly states;
+    constructor(opts?: CircuitBreakerOptions);
+    /** @returns true when the breaker is open and the call should be skipped. */
+    shouldSkip(key: string): boolean;
+    recordSuccess(key: string): void;
+    recordTimeout(key: string): void;
+    private now;
+}

package/dist/internal/memory/cwd-mutex.d.ts

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

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

@@ -0,0 +1,4 @@
+export declare function diaryPath(cwd: string): string;
+export declare function renderDiaryEntry(entry: DiaryEntry): string;
+export declare function appendDiaryEntry(cwd: string, entry: DiaryEntry): Promise<void>;
+export declare function entryHash(entry: DiaryEntry): string;

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

@@ -0,0 +1,15 @@
+import type { EmbeddingRuntime } from "../embedding-adapter.js";
+import type { MemoryFact } from "../types.js";
+export interface Cluster {
+    representativeText: string;
+    members: ReadonlyArray<MemoryFact>;
+}
+export interface ClusterResult {
+    clusters: Cluster[];
+}
+/** Light phase — drop facts whose embedding is too similar to one already kept. */
+export declare function lightPhase(facts: ReadonlyArray<MemoryFact>, embedding: EmbeddingRuntime, threshold?: number): Promise<DedupResult>;
+/** REM phase — single-link agglomerative clustering by cosine similarity. */
+export declare function remPhase(facts: ReadonlyArray<MemoryFact>, embedding: EmbeddingRuntime, threshold?: number): Promise<ClusterResult>;
+/** Deep phase — render consolidated markdown for the dreamed note. */
+export declare function deepPhase(clusters: ReadonlyArray<Cluster>, timestampMs: number): string;

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

@@ -0,0 +1,10 @@
+export interface DreamingResult {
+    status: "ok" | "skipped" | "error";
+    factsBefore: number;
+    factsAfter: number;
+    duplicatesRemoved: number;
+    clustersCreated: number;
+    notesWritten: number;
+    diaryEntryHash: string | undefined;
+}
+export declare function runDreamingSweep(options: DreamingOptions): Promise<DreamingResult>;

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

@@ -0,0 +1,42 @@
+/**
+ * Memory embedding provider adapter contract (ADR D3 of memory-system-openclaw-parity).
+ *
+ * Mirrors OpenClaw's `MemoryEmbeddingProviderAdapter` from
+ * `referencia/openclaw/extensions/openai/memory-embedding-adapter.ts` so
+ * adding a new provider becomes one new file under `adapters/`.
+ *
+ * @internal
+ */
+export interface CreateAdapterOptions {
+    /** Override the adapter's `defaultModel`. */
+    model?: string;
+    /** Override the API key (else resolved from env). */
+    apiKey?: string;
+    /** Override the HTTP base URL (else provider default). */
+    baseUrl?: string;
+    /** Inject a fetch implementation (tests use this to stub HTTP). */
+    fetch?: typeof fetch;
+    /** Optional cache instance (else a default LRU is created). */
+    cache?: EmbeddingCache;
+}
+export interface EmbeddingRuntime {
+    readonly id: string;
+    readonly model: string;
+    readonly dimension: number;
+    /** Embed N texts → N vectors of length `dimension`. Handles batching internally. */
+    embed(texts: ReadonlyArray<string>): Promise<number[][]>;
+    /** Observability — cache hit/miss + call counts. */
+    stats(): EmbeddingRuntimeStats;
+}
+export interface EmbeddingRuntimeStats {
+    cacheHits: number;
+    cacheMisses: number;
+    httpCalls: number;
+    retries: number;
+}
+export interface EmbeddingCache {
+    get(key: string): number[] | undefined;
+    set(key: string, value: number[]): void;
+    /** Total entries currently held. */
+    size(): number;
+}

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

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

package/dist/internal/memory/index-db.d.ts

@@ -0,0 +1,10 @@
+export interface OpenDbOptions {
+    filePath: string;
+    /**
+     * When true and opening fails with a corruption error, rename the file aside
+     * and create a fresh DB. Default true.
+     */
+    recoverCorrupt?: boolean;
+}
+export declare function openMemoryDb(opts: OpenDbOptions): Promise<MemoryDb>;
+export declare function defaultIndexPath(cwd: string): string;

package/dist/internal/memory/index-manager-dispatch.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Dispatch helpers for `IndexManager.open`. Extracted to keep
+ * `index-manager.ts` under the G8 400-LoC budget (lancedb-backend-ship-v1-1).
+ *
+ * @internal
+ */
+import type { MemoryBackend, OpenIndexOptions } from "./index-manager.js";
+import type { MemoryIndex } from "./memory-index.js";
+/** Valid backend identifiers — runtime guard against TS-narrowing escapes (EC-1). */
+export declare const VALID_BACKENDS: readonly MemoryBackend[];
+/**
+ * EC-1: runtime guard for `opts.backend`. TS union is compile-time only;
+ * consumers passing JS `as any` typos must hit a typed error, not silent
+ * SQLite fallback.
+ */
+export declare function assertValidBackend(backend: string): asserts backend is MemoryBackend;
+/**
+ * Lance-path open. Throws `lance_requires_embedding` when no embedding
+ * runtime is provided (Lance is vector-only — no FTS fallback).
+ * Surfaces `lance_backend_unavailable` from LanceIndex.open when peer
+ * dep is absent.
+ */
+export declare function openLanceIndex(opts: OpenIndexOptions): Promise<MemoryIndex>;