@elizaos/app-core 2.0.0-alpha.85 → 2.0.0-beta.2

package/services/local-inference/cache-bridge.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Cache bridge for the local-inference path.
+ *
+ * Translates the runtime's `ProviderCachePlan` (a provider-neutral cache
+ * plan emitted by `@elizaos/core`'s `buildProviderCachePlan`) into
+ * concrete behaviour for the two local backends:
+ *
+ *   1. Out-of-process llama-server (DFlash / buun-llama-cpp): stable
+ *      slot-id derivation + on-disk slot KV save/restore directory layout
+ *      + TTL-based eviction by mtime.
+ *   2. In-process node-llama-cpp: a session pool (see
+ *      `session-pool.ts`) keyed by `promptCacheKey`.
+ *
+ * This module is pure logic — no llama-server process management, no
+ * node-llama-cpp imports. All filesystem state is rooted under
+ * `local-inference/llama-cache/` so cleanup is easy and explicit.
+ */
+/**
+ * TTLs for cached prefix data, mirroring the cloud-side semantics:
+ *   - `short`: roughly the "default" Anthropic ephemeral cache window.
+ *   - `long`: roughly the "1h" Anthropic ephemeral cache window.
+ *   - `extended`: the OpenAI 24h prompt-cache retention window.
+ *
+ * Values are in milliseconds. Eviction uses file mtime, not access time,
+ * so a slot that is read repeatedly without being rewritten still ages
+ * out — which matches how llama-server writes the slot file each turn.
+ */
+export interface CacheTtls {
+    short: number;
+    long: number;
+    extended?: number;
+}
+export declare const DEFAULT_CACHE_TTLS: CacheTtls;
+/**
+ * Root directory for all local llama-cache state. Anything inside is
+ * Eliza-owned and safe to delete to reset the cache.
+ */
+export declare function llamaCacheRoot(): string;
+/**
+ * Per-model-hash cache directory. Slot save files for one model never
+ * collide with another model's; switching active model does not need to
+ * wipe the cache.
+ */
+export declare function cacheRoot(modelHash: string): string;
+/**
+ * llama-server `--slot-save-path` argument: the directory llama-server
+ * writes per-slot KV state into when a request includes
+ * `cache_prompt: true`. One directory per model hash.
+ */
+export declare function slotSavePath(modelHash: string): string;
+/**
+ * Stable model-fingerprint hash. Combines the absolute paths of the
+ * target / drafter GGUFs and the cache-type knobs so two distinct
+ * configurations don't share a slot directory.
+ */
+export declare function buildModelHash(input: {
+    targetModelPath: string;
+    drafterModelPath?: string | null;
+    cacheTypeK?: string | null;
+    cacheTypeV?: string | null;
+    /** Optional extra discriminator (context size, parallel, etc.). */
+    extra?: string | null;
+}): string;
+/**
+ * Map a `promptCacheKey` to a llama-server slot id in [0, parallel).
+ *
+ * llama-server's `--parallel N` flag pre-allocates N decoding slots and
+ * accepts a `slot_id` integer in `[0, N-1]` on each request. By hashing
+ * the cache key into that range we get:
+ *
+ *   - The same prefix hash always lands on the same slot, so the in-RAM
+ *     KV cache from the previous turn is reused.
+ *   - Different prefix hashes spread across slots and don't fight for
+ *     the same KV memory.
+ *
+ * Pass `parallel <= 0` to disable slot pinning (returns -1, the
+ * llama-server "any free slot" sentinel).
+ */
+export declare function deriveSlotId(promptCacheKey: string, parallel: number): number;
+/**
+ * Convert the runtime-side `CacheTTL` enum + OpenAI extended retention
+ * hint into a concrete TTL in milliseconds. This is what the eviction
+ * sweep uses when deciding whether a slot file is still live.
+ */
+export declare function ttlMsForKey(ttl: "short" | "long" | "extended" | undefined, ttls?: CacheTtls): number;
+/**
+ * Sweep the slot-save directory and delete files older than the longest
+ * configured TTL. Mtime is the watermark; llama-server rewrites the slot
+ * file on every save, so a slot that's actively used keeps a fresh mtime.
+ *
+ * Returns the number of files deleted. Missing directories are not
+ * errors — eviction on a clean install just no-ops.
+ */
+export declare function evictExpired(rootDir: string, ttls?: CacheTtls, now?: number): Promise<number>;
+export interface CacheStatsEntry {
+    file: string;
+    sizeBytes: number;
+    mtimeMs: number;
+    ageMs: number;
+}
+/**
+ * Snapshot of the on-disk slot-save directory. Used by the public
+ * `getLocalCacheStats()` debugging endpoint.
+ */
+export declare function readCacheStats(rootDir: string, now?: number): Promise<CacheStatsEntry[]>;
+/**
+ * Resolve `promptCacheKey` from a `providerOptions` payload as emitted
+ * by `buildProviderCachePlan`. The runtime stuffs it under
+ * `providerOptions.eliza.promptCacheKey`. Returns `null` when the key is
+ * missing or not a non-empty string — callers fall back to the default
+ * "_default" session in that case.
+ */
+export declare function extractPromptCacheKey(providerOptions: unknown): string | null;
+/**
+ * Resolve `prefixHash` from `providerOptions.eliza.prefixHash`. Mirrors
+ * `extractPromptCacheKey` — returns null when missing or not a non-empty
+ * string. The prefix hash covers ONLY the stable prompt prefix (system
+ * prompt + tool definitions + large constant context), so a runtime
+ * timestamp in the unstable tail does not invalidate it.
+ *
+ * Local backends prefer this over `promptCacheKey` when available because
+ * it gives the strongest "same prefix → same slot" guarantee: two
+ * conversations with byte-identical stable prefixes will land on the same
+ * slot regardless of how their tail content differs.
+ */
+export declare function extractPrefixHash(providerOptions: unknown): string | null;
+/**
+ * Stable annotation describing a single segment of the prompt as it was
+ * emitted by the runtime planner. The cache-bridge consumes this to
+ * compute a stable-prefix-only hash for slot pinning, without having to
+ * look at the (timestamp-laden) tail.
+ *
+ * Mirrors `PromptSegment` in @elizaos/core/src/types/model.ts but is kept
+ * standalone so the cache-bridge can be imported by the local-inference
+ * backends without a hard dep on `@elizaos/core`.
+ */
+export interface AnnotatedPromptSegment {
+    content: string;
+    stable: boolean;
+}
+/**
+ * Hash the longest stable prefix of `segments`. Stops at the first
+ * unstable segment, so a runtime timestamp in the unstable tail never
+ * shifts the hash. Returns `null` when no stable segment exists, signaling
+ * to the caller that prefix-cache reuse cannot be derived purely from the
+ * prompt structure (fall back to the prompt-cache-key path instead).
+ *
+ * The hash is sha256-truncated to 16 hex chars, matching `buildModelHash`
+ * — short enough for log lines, wide enough that collision is not a
+ * realistic concern for any plausible number of concurrent prefixes.
+ */
+export declare function hashStablePrefix(segments: readonly AnnotatedPromptSegment[]): string | null;
+/**
+ * Extract the per-segment stable annotations from a `providerOptions`
+ * payload. The runtime emits these as `providerOptions.eliza.promptSegments`
+ * when a structured prompt is available — local backends use it to compute
+ * `hashStablePrefix` directly, without having to re-parse the prompt text.
+ *
+ * Returns `null` when the field is absent or malformed; callers fall back
+ * to `extractPromptCacheKey` / `extractPrefixHash`.
+ */
+export declare function extractAnnotatedSegments(providerOptions: unknown): AnnotatedPromptSegment[] | null;
+/**
+ * Resolve the conversation handle id from a `providerOptions` payload.
+ * The runtime stuffs it under `providerOptions.eliza.conversationId` when
+ * the calling context represents a long-lived conversation (chat handler,
+ * planner loop). When present, local backends should use it as the
+ * primary slot key — it's stable across turns regardless of prompt
+ * content drift, which gives the strongest possible cache reuse for
+ * agentic loops.
+ */
+export declare function extractConversationId(providerOptions: unknown): string | null;
+/**
+ * Resolve the stable per-call cache key for the local backends. Order of
+ * precedence:
+ *   1. Conversation id — strongest signal, identical across turns.
+ *   2. Annotated stable-prefix hash — survives unstable-tail drift.
+ *   3. `prefixHash` from the runtime cache plan — already stable-only via
+ *      `cachePrefixSegments` upstream.
+ *   4. `promptCacheKey` (`v5:<prefixHash>`) — back-compat fallback.
+ * Returns null when none are available.
+ */
+export declare function resolveLocalCacheKey(providerOptions: unknown): string | null;
+//# sourceMappingURL=cache-bridge.d.ts.map

package/services/local-inference/cache-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-bridge.d.ts","sourceRoot":"","sources":["../../../../../../src/services/local-inference/cache-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,kBAAkB,EAAE,SAIhC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE;IACpC,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,GAAG,MAAM,CAYT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAU7E;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,EAC9C,IAAI,GAAE,SAA8B,GACnC,MAAM,CAIR;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,SAA8B,EACpC,GAAG,GAAE,MAAmB,GACvB,OAAO,CAAC,MAAM,CAAC,CA6BjB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAmB,GACvB,OAAO,CAAC,eAAe,EAAE,CAAC,CA2B5B;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,eAAe,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAO7E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,eAAe,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAOzE;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,SAAS,sBAAsB,EAAE,GAC1C,MAAM,GAAG,IAAI,CAYf;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,eAAe,EAAE,OAAO,GACvB,sBAAsB,EAAE,GAAG,IAAI,CAejC;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,eAAe,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAO7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,eAAe,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAW5E"}

package/services/local-inference/cache-bridge.js

@@ -0,0 +1,333 @@
+/**
+ * Cache bridge for the local-inference path.
+ *
+ * Translates the runtime's `ProviderCachePlan` (a provider-neutral cache
+ * plan emitted by `@elizaos/core`'s `buildProviderCachePlan`) into
+ * concrete behaviour for the two local backends:
+ *
+ *   1. Out-of-process llama-server (DFlash / buun-llama-cpp): stable
+ *      slot-id derivation + on-disk slot KV save/restore directory layout
+ *      + TTL-based eviction by mtime.
+ *   2. In-process node-llama-cpp: a session pool (see
+ *      `session-pool.ts`) keyed by `promptCacheKey`.
+ *
+ * This module is pure logic — no llama-server process management, no
+ * node-llama-cpp imports. All filesystem state is rooted under
+ * `local-inference/llama-cache/` so cleanup is easy and explicit.
+ */
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { localInferenceRoot } from "./paths";
+export const DEFAULT_CACHE_TTLS = {
+    short: 5 * 60 * 1000,
+    long: 60 * 60 * 1000,
+    extended: 24 * 60 * 60 * 1000,
+};
+/**
+ * Root directory for all local llama-cache state. Anything inside is
+ * Eliza-owned and safe to delete to reset the cache.
+ */
+export function llamaCacheRoot() {
+    return path.join(localInferenceRoot(), "llama-cache");
+}
+/**
+ * Per-model-hash cache directory. Slot save files for one model never
+ * collide with another model's; switching active model does not need to
+ * wipe the cache.
+ */
+export function cacheRoot(modelHash) {
+    if (!modelHash) {
+        throw new Error("[cache-bridge] cacheRoot requires a non-empty modelHash");
+    }
+    return path.join(llamaCacheRoot(), modelHash);
+}
+/**
+ * llama-server `--slot-save-path` argument: the directory llama-server
+ * writes per-slot KV state into when a request includes
+ * `cache_prompt: true`. One directory per model hash.
+ */
+export function slotSavePath(modelHash) {
+    return cacheRoot(modelHash);
+}
+/**
+ * Stable model-fingerprint hash. Combines the absolute paths of the
+ * target / drafter GGUFs and the cache-type knobs so two distinct
+ * configurations don't share a slot directory.
+ */
+export function buildModelHash(input) {
+    const hash = createHash("sha256");
+    hash.update(input.targetModelPath);
+    hash.update("
");
+    hash.update(input.drafterModelPath ?? "");
+    hash.update("
");
+    hash.update(input.cacheTypeK ?? "");
+    hash.update("
");
+    hash.update(input.cacheTypeV ?? "");
+    hash.update("
");
+    hash.update(input.extra ?? "");
+    return hash.digest("hex").slice(0, 16);
+}
+/**
+ * Map a `promptCacheKey` to a llama-server slot id in [0, parallel).
+ *
+ * llama-server's `--parallel N` flag pre-allocates N decoding slots and
+ * accepts a `slot_id` integer in `[0, N-1]` on each request. By hashing
+ * the cache key into that range we get:
+ *
+ *   - The same prefix hash always lands on the same slot, so the in-RAM
+ *     KV cache from the previous turn is reused.
+ *   - Different prefix hashes spread across slots and don't fight for
+ *     the same KV memory.
+ *
+ * Pass `parallel <= 0` to disable slot pinning (returns -1, the
+ * llama-server "any free slot" sentinel).
+ */
+export function deriveSlotId(promptCacheKey, parallel) {
+    if (!Number.isFinite(parallel) || parallel <= 0)
+        return -1;
+    if (!promptCacheKey)
+        return -1;
+    const integerParallel = Math.max(1, Math.floor(parallel));
+    if (integerParallel === 1)
+        return 0;
+    const digest = createHash("sha256").update(promptCacheKey).digest();
+    // Read first 4 bytes as an unsigned big-endian int. Plenty of entropy
+    // for parallel ≤ 64.
+    const value = digest.readUInt32BE(0);
+    return value % integerParallel;
+}
+/**
+ * Convert the runtime-side `CacheTTL` enum + OpenAI extended retention
+ * hint into a concrete TTL in milliseconds. This is what the eviction
+ * sweep uses when deciding whether a slot file is still live.
+ */
+export function ttlMsForKey(ttl, ttls = DEFAULT_CACHE_TTLS) {
+    if (ttl === "long")
+        return ttls.long;
+    if (ttl === "extended")
+        return ttls.extended ?? ttls.long;
+    return ttls.short;
+}
+/**
+ * Sweep the slot-save directory and delete files older than the longest
+ * configured TTL. Mtime is the watermark; llama-server rewrites the slot
+ * file on every save, so a slot that's actively used keeps a fresh mtime.
+ *
+ * Returns the number of files deleted. Missing directories are not
+ * errors — eviction on a clean install just no-ops.
+ */
+export async function evictExpired(rootDir, ttls = DEFAULT_CACHE_TTLS, now = Date.now()) {
+    const horizon = Math.max(ttls.short, ttls.long, ttls.extended ?? 0);
+    let entries;
+    try {
+        entries = await fs.readdir(rootDir);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return 0;
+        throw err;
+    }
+    let deleted = 0;
+    for (const entry of entries) {
+        const full = path.join(rootDir, entry);
+        let stat;
+        try {
+            stat = await fs.stat(full);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile())
+            continue;
+        if (now - stat.mtimeMs > horizon) {
+            try {
+                await fs.unlink(full);
+                deleted += 1;
+            }
+            catch {
+                // Best-effort cleanup; another process may already have removed it.
+            }
+        }
+    }
+    return deleted;
+}
+/**
+ * Snapshot of the on-disk slot-save directory. Used by the public
+ * `getLocalCacheStats()` debugging endpoint.
+ */
+export async function readCacheStats(rootDir, now = Date.now()) {
+    let entries;
+    try {
+        entries = await fs.readdir(rootDir);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const out = [];
+    for (const entry of entries) {
+        const full = path.join(rootDir, entry);
+        let stat;
+        try {
+            stat = await fs.stat(full);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile())
+            continue;
+        out.push({
+            file: entry,
+            sizeBytes: stat.size,
+            mtimeMs: stat.mtimeMs,
+            ageMs: Math.max(0, now - stat.mtimeMs),
+        });
+    }
+    out.sort((left, right) => left.file.localeCompare(right.file));
+    return out;
+}
+/**
+ * Resolve `promptCacheKey` from a `providerOptions` payload as emitted
+ * by `buildProviderCachePlan`. The runtime stuffs it under
+ * `providerOptions.eliza.promptCacheKey`. Returns `null` when the key is
+ * missing or not a non-empty string — callers fall back to the default
+ * "_default" session in that case.
+ */
+export function extractPromptCacheKey(providerOptions) {
+    if (!providerOptions || typeof providerOptions !== "object")
+        return null;
+    const eliza = providerOptions.eliza;
+    if (!eliza || typeof eliza !== "object")
+        return null;
+    const raw = eliza.promptCacheKey;
+    if (typeof raw !== "string" || raw.length === 0)
+        return null;
+    return raw;
+}
+/**
+ * Resolve `prefixHash` from `providerOptions.eliza.prefixHash`. Mirrors
+ * `extractPromptCacheKey` — returns null when missing or not a non-empty
+ * string. The prefix hash covers ONLY the stable prompt prefix (system
+ * prompt + tool definitions + large constant context), so a runtime
+ * timestamp in the unstable tail does not invalidate it.
+ *
+ * Local backends prefer this over `promptCacheKey` when available because
+ * it gives the strongest "same prefix → same slot" guarantee: two
+ * conversations with byte-identical stable prefixes will land on the same
+ * slot regardless of how their tail content differs.
+ */
+export function extractPrefixHash(providerOptions) {
+    if (!providerOptions || typeof providerOptions !== "object")
+        return null;
+    const eliza = providerOptions.eliza;
+    if (!eliza || typeof eliza !== "object")
+        return null;
+    const raw = eliza.prefixHash;
+    if (typeof raw !== "string" || raw.length === 0)
+        return null;
+    return raw;
+}
+/**
+ * Hash the longest stable prefix of `segments`. Stops at the first
+ * unstable segment, so a runtime timestamp in the unstable tail never
+ * shifts the hash. Returns `null` when no stable segment exists, signaling
+ * to the caller that prefix-cache reuse cannot be derived purely from the
+ * prompt structure (fall back to the prompt-cache-key path instead).
+ *
+ * The hash is sha256-truncated to 16 hex chars, matching `buildModelHash`
+ * — short enough for log lines, wide enough that collision is not a
+ * realistic concern for any plausible number of concurrent prefixes.
+ */
+export function hashStablePrefix(segments) {
+    if (segments.length === 0)
+        return null;
+    const hash = createHash("sha256");
+    let consumed = 0;
+    for (const segment of segments) {
+        if (!segment.stable)
+            break;
+        hash.update(segment.content);
+        hash.update("
");
+        consumed += 1;
+    }
+    if (consumed === 0)
+        return null;
+    return hash.digest("hex").slice(0, 16);
+}
+/**
+ * Extract the per-segment stable annotations from a `providerOptions`
+ * payload. The runtime emits these as `providerOptions.eliza.promptSegments`
+ * when a structured prompt is available — local backends use it to compute
+ * `hashStablePrefix` directly, without having to re-parse the prompt text.
+ *
+ * Returns `null` when the field is absent or malformed; callers fall back
+ * to `extractPromptCacheKey` / `extractPrefixHash`.
+ */
+export function extractAnnotatedSegments(providerOptions) {
+    if (!providerOptions || typeof providerOptions !== "object")
+        return null;
+    const eliza = providerOptions.eliza;
+    if (!eliza || typeof eliza !== "object")
+        return null;
+    const raw = eliza.promptSegments;
+    if (!Array.isArray(raw))
+        return null;
+    const out = [];
+    for (const entry of raw) {
+        if (!entry || typeof entry !== "object")
+            return null;
+        const content = entry.content;
+        const stable = entry.stable;
+        if (typeof content !== "string" || typeof stable !== "boolean")
+            return null;
+        out.push({ content, stable });
+    }
+    return out;
+}
+/**
+ * Resolve the conversation handle id from a `providerOptions` payload.
+ * The runtime stuffs it under `providerOptions.eliza.conversationId` when
+ * the calling context represents a long-lived conversation (chat handler,
+ * planner loop). When present, local backends should use it as the
+ * primary slot key — it's stable across turns regardless of prompt
+ * content drift, which gives the strongest possible cache reuse for
+ * agentic loops.
+ */
+export function extractConversationId(providerOptions) {
+    if (!providerOptions || typeof providerOptions !== "object")
+        return null;
+    const eliza = providerOptions.eliza;
+    if (!eliza || typeof eliza !== "object")
+        return null;
+    const raw = eliza.conversationId;
+    if (typeof raw !== "string" || raw.length === 0)
+        return null;
+    return raw;
+}
+/**
+ * Resolve the stable per-call cache key for the local backends. Order of
+ * precedence:
+ *   1. Conversation id — strongest signal, identical across turns.
+ *   2. Annotated stable-prefix hash — survives unstable-tail drift.
+ *   3. `prefixHash` from the runtime cache plan — already stable-only via
+ *      `cachePrefixSegments` upstream.
+ *   4. `promptCacheKey` (`v5:<prefixHash>`) — back-compat fallback.
+ * Returns null when none are available.
+ */
+export function resolveLocalCacheKey(providerOptions) {
+    const conversationId = extractConversationId(providerOptions);
+    if (conversationId)
+        return `conv:${conversationId}`;
+    const segments = extractAnnotatedSegments(providerOptions);
+    if (segments) {
+        const hashed = hashStablePrefix(segments);
+        if (hashed)
+            return `seg:${hashed}`;
+    }
+    const prefixHash = extractPrefixHash(providerOptions);
+    if (prefixHash)
+        return `pfx:${prefixHash}`;
+    return extractPromptCacheKey(providerOptions);
+}

package/services/local-inference/catalog.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Eliza-curated local model catalog.
+ *
+ * Eliza-1 is the only default-eligible model line. There is exactly one
+ * default per device tier (`lite-0_6b`, `mobile-1_7b`, `desktop-9b`,
+ * `pro-27b`, `server-h200`). The recommendation engine picks one of
+ * these tiers based on hardware. See
+ * `/Users/shawwalters/eliza-workspace/milady/eliza/packages/inference/AGENTS.md`
+ * §2 for the binding tier matrix.
+ *
+ * HF-search results from outside `elizalabs/eliza-1-*` MUST never be
+ * marked default-eligible (handled by `hf-search.ts`, which produces
+ * entries that are absent from `DEFAULT_ELIGIBLE_MODEL_IDS`).
+ *
+ * When upstream naming conventions drift, update `ggufFile` here — we
+ * rely on the exact filename for resolved-URL construction in the
+ * downloader.
+ */
+import { type Eliza1Tier } from "./manifest";
+import type { CatalogModel } from "./types";
+/**
+ * Eliza-1 tier identifiers, in tier-matrix order. Derived from the
+ * manifest module's `ELIZA_1_TIERS` so the bundle tier list and the
+ * catalog model-id list never drift.
+ */
+export type Eliza1TierId = `eliza-1-${Eliza1Tier}`;
+export declare const ELIZA_1_TIER_IDS: ReadonlyArray<Eliza1TierId>;
+/**
+ * The model id the engine auto-loads on first run when no preference is
+ * set. Resolves to the `mobile-1_7b` tier — the smallest Eliza-1 tier
+ * that fits the broadest range of hardware (modern phone or laptop).
+ * Hosts that can't fit `mobile-1_7b` get the `lite-0_6b` fallback via
+ * the recommendation ladder.
+ */
+export declare const FIRST_RUN_DEFAULT_MODEL_ID: Eliza1TierId;
+/**
+ * The single source of truth for default-eligibility. Only Eliza-1
+ * tiers are default-eligible. The recommendation engine MUST refuse to
+ * surface anything outside this set as a default; HF-search results
+ * MUST never appear here.
+ */
+export declare const DEFAULT_ELIGIBLE_MODEL_IDS: ReadonlySet<string>;
+export declare function isDefaultEligibleId(id: string): boolean;
+/** Compatibility export for callers that need the Eliza-1 model id set. */
+export declare const ELIZA_1_PLACEHOLDER_IDS: ReadonlySet<string>;
+export declare const MODEL_CATALOG: CatalogModel[];
+export declare function findCatalogModel(id: string): CatalogModel | undefined;
+/**
+ * Construct the HuggingFace resolve URL for a given catalog entry.
+ *
+ * Respects `ELIZA_HF_BASE_URL` when set so self-hosted HF mirrors and the
+ * downloader e2e test suite can redirect all downloads without touching
+ * the catalog.
+ */
+export declare function buildHuggingFaceResolveUrlForPath(model: CatalogModel, filePath: string): string;
+export declare function buildHuggingFaceResolveUrl(model: CatalogModel): string;
+//# sourceMappingURL=catalog.d.ts.map

package/services/local-inference/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../../../../src/services/local-inference/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAsB,MAAM,SAAS,CAAC;AAEhE;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,UAAU,EAAE,CAAC;AAEnD,eAAO,MAAM,gBAAgB,EAAE,aAAa,CAAC,YAAY,CAExD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,EAAE,YAAoC,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,MAAM,CAE1D,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,2EAA2E;AAC3E,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAEvD,CAAC;AA4EF,eAAO,MAAM,aAAa,EAAE,YAAY,EAsJvC,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAErE;AAED;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,MAAM,GACf,MAAM,CAWR;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAEtE"}