om-memory-system 6.2.0-next.243 → 6.3.0

package/dist/services/openrouter-providers.js

@@ -0,0 +1,147 @@
+/**
+ * The providers that serve one OpenRouter model, each with a data policy label.
+ * It reads two public OpenRouter lists without an API key: the model's endpoints
+ * and the zero data retention (ZDR) endpoints. `fetch` and the clock come in as
+ * arguments, so the module needs no config and tests need no network.
+ */
+const BASE = "https://openrouter.ai/api/v1";
+const ZDR_TTL_MS = 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 10_000;
+const MODEL_ID = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._:-]+$/;
+/** From least private to most private is unknown, safety, zdr. */
+const PRIVACY_RANK = { unknown: 0, safety: 1, zdr: 2 };
+/** True for `author/slug` model IDs. Dot-only parts are refused so the URL cannot climb out of /models/. */
+export function isModelId(value) {
+    return (typeof value === "string" &&
+        MODEL_ID.test(value) &&
+        value.split("/").every((part) => !/^\.+$/.test(part)));
+}
+class ListError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+    }
+}
+const text = (value) => typeof value === "string" && value.trim() ? value : undefined;
+/** A per-token price string such as "0.000000256" as US dollars per 1M tokens. Missing, non-numeric or negative gives undefined. */
+function pricePerMillion(value) {
+    if (typeof value !== "string" || !value.trim())
+        return undefined;
+    const perToken = Number(value);
+    if (!Number.isFinite(perToken) || perToken < 0)
+        return undefined;
+    return Math.round(perToken * 1_000_000 * 1e6) / 1e6;
+}
+const lowest = (a, b) => a === undefined ? b : b === undefined ? a : Math.min(a, b);
+export function createOpenRouterProviders(deps) {
+    const timeoutMs = deps.timeoutMs ?? FETCH_TIMEOUT_MS;
+    let zdrCache;
+    /** One keyless GET. Returns undefined for a 404, so the caller can name the model. */
+    async function getJson(url) {
+        let response;
+        try {
+            response = await deps.fetch(url, {
+                method: "GET",
+                headers: { Accept: "application/json" },
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (error) {
+            const name = error instanceof Error ? error.name : "";
+            if (name === "TimeoutError" || name === "AbortError") {
+                throw new ListError("timeout", "OpenRouter did not answer within 10 seconds.");
+            }
+            throw new ListError("unreachable", "OpenRouter could not be reached.");
+        }
+        if (response.status === 404)
+            return undefined;
+        if (!response.ok) {
+            throw new ListError("unreachable", `OpenRouter answered with status ${response.status}.`);
+        }
+        try {
+            return await response.json();
+        }
+        catch {
+            throw new ListError("unreachable", "OpenRouter sent a reply that could not be read.");
+        }
+    }
+    /** `model_id` + `tag` -> safety_retention for every ZDR endpoint. Cached for an hour. */
+    async function zdrFlags() {
+        if (zdrCache && deps.now() - zdrCache.at < ZDR_TTL_MS)
+            return zdrCache.flags;
+        const body = (await getJson(`${BASE}/endpoints/zdr`));
+        if (!body || !Array.isArray(body.data)) {
+            throw new ListError("unreachable", "OpenRouter sent a zero data retention list in an unknown form.");
+        }
+        const flags = new Map();
+        for (const row of body.data) {
+            const model = text(row?.model_id);
+            const tag = text(row?.tag);
+            // A missing or non-boolean flag is not stored, so the endpoint stays `unknown`.
+            if (model && tag && typeof row.safety_retention === "boolean") {
+                flags.set(`${model}\n${tag}`, row.safety_retention);
+            }
+        }
+        // Only a good answer is cached, so a failed fetch is tried again on the next request.
+        zdrCache = { at: deps.now(), flags };
+        return flags;
+    }
+    async function list(model) {
+        try {
+            const [body, flags] = await Promise.all([
+                getJson(`${BASE}/models/${model.split("/").map(encodeURIComponent).join("/")}/endpoints`),
+                zdrFlags(),
+            ]);
+            const endpoints = body?.data?.endpoints;
+            if (body === undefined || (Array.isArray(endpoints) && endpoints.length === 0)) {
+                throw new ListError("unknown-model", "OpenRouter has no providers for that model.");
+            }
+            if (!Array.isArray(endpoints)) {
+                throw new ListError("unreachable", "OpenRouter sent a provider list in an unknown form.");
+            }
+            const bySlug = new Map();
+            // Lowest input and output price per slug, found independently across its endpoints.
+            const prices = new Map();
+            for (const endpoint of endpoints) {
+                const tag = text(endpoint?.tag);
+                const name = text(endpoint?.provider_name);
+                const slug = tag ? tag.split("/")[0] : name?.toLowerCase();
+                if (!slug)
+                    continue;
+                const modelId = text(endpoint?.model_id);
+                const flag = tag && modelId ? flags.get(`${modelId}\n${tag}`) : undefined;
+                const policy = flag === undefined ? "unknown" : flag ? "safety" : "zdr";
+                const pricing = endpoint?.pricing;
+                const lows = prices.get(slug) ?? {};
+                lows.input = lowest(lows.input, pricePerMillion(pricing?.prompt));
+                lows.output = lowest(lows.output, pricePerMillion(pricing?.completion));
+                prices.set(slug, lows);
+                const seen = bySlug.get(slug);
+                if (!seen) {
+                    bySlug.set(slug, { slug, name: name ?? slug, policy });
+                }
+                else if (PRIVACY_RANK[policy] < PRIVACY_RANK[seen.policy]) {
+                    seen.policy = policy;
+                }
+            }
+            // A price needs both values. A slug with only one of them shows no price.
+            for (const [slug, row] of bySlug) {
+                const { input, output } = prices.get(slug) ?? {};
+                if (input !== undefined && output !== undefined)
+                    row.price = { input, output };
+            }
+            const providers = [...bySlug.values()].sort((a, b) => a.name.localeCompare(b.name));
+            if (providers.length === 0) {
+                throw new ListError("unknown-model", "OpenRouter has no providers for that model.");
+            }
+            return { ok: true, providers };
+        }
+        catch (error) {
+            if (error instanceof ListError)
+                return { ok: false, reason: error.reason, error: error.message };
+            return { ok: false, reason: "unreachable", error: "OpenRouter could not be reached." };
+        }
+    }
+    return { list };
+}

package/dist/services/openrouter-routes.d.ts

@@ -0,0 +1,9 @@
+import type { RouteResult } from "./chat/chat-routes.js";
+/**
+ * The OpenRouter routing routes of the External API card: the provider list of a
+ * model with data policy labels, and the save of `memoryExtraParams.provider`.
+ * Returns undefined for paths it does not own.
+ */
+export declare function routeOpenRouter(path: string, method: string, url: URL, readBody: () => Promise<any>, ctx: {
+    cwd: string;
+}): Promise<RouteResult | undefined>;

package/dist/services/openrouter-routes.js

@@ -0,0 +1,77 @@
+import { log } from "./logger.js";
+import { createOpenRouterModels } from "./openrouter-models.js";
+import { createOpenRouterProviders, isModelId } from "./openrouter-providers.js";
+import { isOpenRouterUrl, parseRouting, removeProviderEdits, routingEdits, } from "./openrouter-routing-config.js";
+const PROVIDERS_PATH = "/api/settings/external-api/openrouter-providers";
+const MODELS_PATH = "/api/settings/external-api/openrouter-models";
+const ROUTING_PATH = "/api/settings/external-api/openrouter-routing";
+/** Reads `globalThis.fetch` at call time, so a test can replace it. */
+const providers = createOpenRouterProviders({
+    fetch: (input, init) => globalThis.fetch(input, init),
+    now: () => Date.now(),
+});
+const models = createOpenRouterModels({
+    fetch: (input, init) => globalThis.fetch(input, init),
+    now: () => Date.now(),
+});
+const NOT_OPENROUTER = "Save the OpenRouter endpoint first. Routing applies only to an OpenRouter API URL.";
+const fail = (status, error) => ({ status, body: { error } });
+/**
+ * The OpenRouter routing routes of the External API card: the provider list of a
+ * model with data policy labels, and the save of `memoryExtraParams.provider`.
+ * Returns undefined for paths it does not own.
+ */
+export async function routeOpenRouter(path, method, url, readBody, ctx) {
+    if (path === PROVIDERS_PATH && method === "GET") {
+        const model = url.searchParams.get("model");
+        if (!isModelId(model)) {
+            return fail(400, "Enter a model ID in the form author/model, for example deepseek/deepseek-chat");
+        }
+        return { status: 200, body: await providers.list(model) };
+    }
+    if (path === MODELS_PATH && method === "GET") {
+        return { status: 200, body: await models.list() };
+    }
+    if (path === ROUTING_PATH && method === "POST") {
+        const body = await readBody();
+        if (typeof body?.revision !== "string")
+            return fail(400, "Revision required");
+        // `routing: null` removes the whole provider object. `{}` clears the managed fields only.
+        const removeAll = body.routing === null;
+        const parsed = removeAll ? { ok: true, routing: {} } : parseRouting(body.routing);
+        if (!parsed.ok)
+            return fail(400, parsed.error);
+        const { writeGlobalConfigKeys, ConfigConflictError } = await import("./global-config-writer.js");
+        let provider;
+        let revision;
+        try {
+            ({ revision } = await writeGlobalConfigKeys({}, body.revision, {
+                only: new Set(["memoryExtraParams", "memoryExtraParams.provider"]),
+                derive: (current) => {
+                    // A clearing save is always allowed, so a stale provider can go after a switch of endpoint.
+                    if (Object.keys(parsed.routing).length > 0 && !isOpenRouterUrl(current.memoryApiUrl)) {
+                        throw new Error(NOT_OPENROUTER);
+                    }
+                    if (removeAll)
+                        return removeProviderEdits(current.memoryExtraParams);
+                    const result = routingEdits(current.memoryExtraParams, parsed.routing);
+                    provider = result.provider;
+                    return result.edits;
+                },
+            }));
+        }
+        catch (error) {
+            return fail(error instanceof ConfigConflictError ? 409 : 400, error instanceof Error ? error.message : "Routing not saved");
+        }
+        // The file is already saved; a reload problem must not report the save as failed.
+        try {
+            const { refreshConfigIfChanged } = await import("../config.js");
+            refreshConfigIfChanged(ctx.cwd);
+        }
+        catch (error) {
+            log("Routing saved, but reloading settings failed", { error: error instanceof Error ? error.message : String(error) }, "error");
+        }
+        return { status: 200, body: { revision, provider: provider ?? null } };
+    }
+    return undefined;
+}

package/dist/services/openrouter-routing-config.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Pure rules for the OpenRouter routing card: check the posted routing, and
+ * turn it into config edits that keep every field the card does not manage.
+ */
+/** The `provider` fields the card owns. Any other field (for example `sort`) is left alone. */
+export declare const MANAGED_PROVIDER_KEYS: readonly ["order", "only", "allow_fallbacks", "data_collection", "zdr"];
+export type RoutingResult = {
+    ok: true;
+    routing: Record<string, unknown>;
+} | {
+    ok: false;
+    error: string;
+};
+/** Check the posted `routing` object. An empty `order` or `only` list is dropped, since it restricts nothing. */
+export declare function parseRouting(input: unknown): RoutingResult;
+/** True when the URL's host is exactly `openrouter.ai`. Routing applies only to that endpoint. */
+export declare function isOpenRouterUrl(value: unknown): boolean;
+/**
+ * The provider object after the save: the saved object without the five managed
+ * fields, plus the posted ones. `undefined` means no provider is left.
+ */
+export declare function mergeProvider(saved: unknown, routing: Record<string, unknown>): Record<string, unknown> | undefined;
+/**
+ * Config edits that remove the whole `provider` object, managed fields or not, and
+ * `memoryExtraParams` when nothing else is in it.
+ */
+export declare function removeProviderEdits(savedExtraParams: unknown): Record<string, unknown>;
+/**
+ * Config edits for `memoryExtraParams.provider`. The nested write keeps the other
+ * members and the file's comments. When no provider is left and nothing else is in
+ * `memoryExtraParams`, the whole key goes. Returns the edits and the new provider.
+ */
+export declare function routingEdits(savedExtraParams: unknown, routing: Record<string, unknown>): {
+    edits: Record<string, unknown>;
+    provider: Record<string, unknown> | undefined;
+};
+/**
+ * Keep the global `memoryExtraParams.provider` when a project file sets `memoryExtraParams`.
+ * The project object replaces the global one as a whole, which would drop a privacy choice
+ * such as `zdr`. Like the endpoint and the key, the routing is global. A project keeps its
+ * other members. Pure on purpose: callers pass the file configs and a log function, and
+ * `CONFIG` is never imported here, because many tests stub `src/config.js`.
+ */
+export declare function keepGlobalProvider(globalConfig: {
+    memoryExtraParams?: unknown;
+}, projectOverrides: {
+    memoryExtraParams?: unknown;
+}, log?: (message: string) => void): void;

package/dist/services/openrouter-routing-config.js

@@ -0,0 +1,143 @@
+/**
+ * Pure rules for the OpenRouter routing card: check the posted routing, and
+ * turn it into config edits that keep every field the card does not manage.
+ */
+/** The `provider` fields the card owns. Any other field (for example `sort`) is left alone. */
+export const MANAGED_PROVIDER_KEYS = [
+    "order",
+    "only",
+    "allow_fallbacks",
+    "data_collection",
+    "zdr",
+];
+// A provider slug (`deepinfra`) or a full endpoint slug with up to two more segments, such as
+// `google-vertex/us-east5` or `baseten/fp4/us`. OpenRouter accepts both in `order` and `only`.
+const SEGMENT = "[a-z0-9][a-z0-9._-]{0,63}";
+const SLUG = new RegExp(`^${SEGMENT}(?:/${SEGMENT}){0,2}$`, "i");
+const MAX_SLUGS = 20;
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function slugList(name, value) {
+    if (!Array.isArray(value))
+        return `${name} must be a list of provider slugs`;
+    if (value.length > MAX_SLUGS)
+        return `${name} can list at most ${MAX_SLUGS} providers`;
+    const seen = new Set();
+    for (const entry of value) {
+        if (typeof entry !== "string" || !SLUG.test(entry)) {
+            return `${name} has a provider slug that is not valid (letters, digits, dot, dash and underscore, with a slash between parts)`;
+        }
+        const key = entry.toLowerCase();
+        if (seen.has(key))
+            return `${name} lists a provider more than once`;
+        seen.add(key);
+    }
+    return value;
+}
+/** Check the posted `routing` object. An empty `order` or `only` list is dropped, since it restricts nothing. */
+export function parseRouting(input) {
+    if (!isPlainObject(input))
+        return { ok: false, error: "routing must be an object" };
+    const routing = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (key === "data_collection") {
+            if (value !== "deny")
+                return { ok: false, error: 'data_collection can only be "deny"' };
+            routing[key] = value;
+        }
+        else if (key === "zdr") {
+            if (value !== true)
+                return { ok: false, error: "zdr can only be true" };
+            routing[key] = value;
+        }
+        else if (key === "allow_fallbacks") {
+            if (value !== false)
+                return { ok: false, error: "allow_fallbacks can only be false" };
+            routing[key] = value;
+        }
+        else if (key === "order" || key === "only") {
+            const list = slugList(key, value);
+            if (typeof list === "string")
+                return { ok: false, error: list };
+            if (list.length > 0)
+                routing[key] = list;
+        }
+        else {
+            return { ok: false, error: `routing has a field that is not supported: ${key}` };
+        }
+    }
+    return { ok: true, routing };
+}
+/** True when the URL's host is exactly `openrouter.ai`. Routing applies only to that endpoint. */
+export function isOpenRouterUrl(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        return new URL(value).hostname === "openrouter.ai";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The provider object after the save: the saved object without the five managed
+ * fields, plus the posted ones. `undefined` means no provider is left.
+ */
+export function mergeProvider(saved, routing) {
+    const merged = isPlainObject(saved) ? { ...saved } : {};
+    for (const key of MANAGED_PROVIDER_KEYS)
+        delete merged[key];
+    Object.assign(merged, routing);
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+/**
+ * Config edits that remove the whole `provider` object, managed fields or not, and
+ * `memoryExtraParams` when nothing else is in it.
+ */
+export function removeProviderEdits(savedExtraParams) {
+    const extra = isPlainObject(savedExtraParams) ? savedExtraParams : undefined;
+    const others = extra ? Object.keys(extra).filter((key) => key !== "provider") : [];
+    if (!extra || others.length === 0) {
+        return savedExtraParams === undefined ? {} : { memoryExtraParams: undefined };
+    }
+    return { "memoryExtraParams.provider": undefined };
+}
+/**
+ * Config edits for `memoryExtraParams.provider`. The nested write keeps the other
+ * members and the file's comments. When no provider is left and nothing else is in
+ * `memoryExtraParams`, the whole key goes. Returns the edits and the new provider.
+ */
+export function routingEdits(savedExtraParams, routing) {
+    const extra = isPlainObject(savedExtraParams) ? savedExtraParams : undefined;
+    const provider = mergeProvider(extra?.provider, routing);
+    if (provider) {
+        // A saved value that is not an object cannot hold a nested key, so it is replaced.
+        return {
+            edits: extra
+                ? { "memoryExtraParams.provider": provider }
+                : { memoryExtraParams: { provider } },
+            provider,
+        };
+    }
+    return { edits: removeProviderEdits(savedExtraParams), provider };
+}
+/**
+ * Keep the global `memoryExtraParams.provider` when a project file sets `memoryExtraParams`.
+ * The project object replaces the global one as a whole, which would drop a privacy choice
+ * such as `zdr`. Like the endpoint and the key, the routing is global. A project keeps its
+ * other members. Pure on purpose: callers pass the file configs and a log function, and
+ * `CONFIG` is never imported here, because many tests stub `src/config.js`.
+ */
+export function keepGlobalProvider(globalConfig, projectOverrides, log) {
+    const provider = isPlainObject(globalConfig.memoryExtraParams)
+        ? globalConfig.memoryExtraParams.provider
+        : undefined;
+    if (!isPlainObject(provider) || !("memoryExtraParams" in projectOverrides))
+        return;
+    const own = isPlainObject(projectOverrides.memoryExtraParams)
+        ? projectOverrides.memoryExtraParams
+        : {};
+    if ("provider" in own) {
+        log?.("Project config cannot change memoryExtraParams.provider; the global routing is used");
+    }
+    projectOverrides.memoryExtraParams = { ...own, provider };
+}

package/dist/services/retrieval-rerank.d.ts

@@ -24,6 +24,8 @@ export interface RerankedSearchOptions {
     maxMemories: number;
     similarityThreshold: number;
     kind?: MemoryKind;
+    /** Drop reranked candidates below `similarityThreshold` before the limit (memorisation recall). */
+    thresholdAfterRerank?: boolean;
 }
 export interface RerankedSearchDeps {
     search: SearchAcrossShards;

package/dist/services/retrieval-rerank.js

@@ -15,7 +15,10 @@ export async function rerankedSearch(options, settings, deps) {
         return { results: [], warnings, reranked: false };
     try {
         const { ordered } = await rerankDocuments(settings, options.queryText, candidates, deps.fetchImpl);
-        return { results: ordered.slice(0, options.maxMemories), warnings, reranked: true };
+        const kept = options.thresholdAfterRerank
+            ? ordered.filter((result) => result.similarity >= options.similarityThreshold)
+            : ordered;
+        return { results: kept.slice(0, options.maxMemories), warnings, reranked: true };
     }
     catch (error) {
         // Metadata only: the code, the elapsed time, and the candidate count.

package/dist/services/settings-snapshot.d.ts

@@ -18,6 +18,7 @@ export declare function getSettingsSnapshot(directory: string): {
         resolvesInWebApp: boolean;
         warning: string | null;
     };
+    openrouterProvider: Record<string, unknown> | null;
     effective: {
         opencode: import("./ai/live-model-choice.js").AutoCaptureProviderStatus;
         pi: import("./ai/live-model-choice.js").PiLiveModelChoice;

package/dist/services/settings-snapshot.js

@@ -126,6 +126,9 @@ function nestedSetting(path, defaultValue, global, project) {
         hasGlobal,
     };
 }
+const plainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value
+    : null;
 export function getSettingsSnapshot(directory) {
     const global = readSettingsFile(getGlobalConfigSourcePath());
     const project = readSettingsFile(projectFile(directory));
@@ -218,6 +221,8 @@ export function getSettingsSnapshot(directory) {
         secrets,
         fallback: { model: CONFIG.memoryModel ?? null, configured: isExternalModelReady(CONFIG) },
         externalKey: memoryKeyStatus(global.memoryApiKey),
+        // The OpenRouter routing card reads the saved `provider` object of memoryExtraParams.
+        openrouterProvider: plainObject(plainObject(global.memoryExtraParams)?.provider),
         effective: {
             opencode: getAutoCaptureProviderStatus(CONFIG),
             pi: resolvePiLiveModel(CONFIG),

package/dist/services/tag-migration.d.ts

@@ -0,0 +1,48 @@
+import { type ProviderErrorKind } from "./ai/provider-error-kind.js";
+import type { buildMemoryProviderConfig } from "./ai/provider-config.js";
+import type { AIProviderType } from "./ai/session/session-types.js";
+export interface ApiResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+export type TagMigrationConfig = Parameters<typeof buildMemoryProviderConfig>[0] & {
+    memoryProvider: AIProviderType;
+};
+/**
+ * One batch's answer. `error` and `errorKind` describe the failure that stopped the run,
+ * or else the first failure of the run.
+ */
+export interface TagMigrationBatch {
+    processed: number;
+    total: number;
+    hasMore: boolean;
+    tagged: number;
+    failed: number;
+    errorKind?: ProviderErrorKind;
+    error?: string;
+}
+interface MigrationProgress {
+    processed: number;
+    total: number;
+    currentBatch: number;
+    totalBatches: number;
+    isComplete: boolean;
+    tagged: number;
+    errors: string[];
+    errorKind?: ProviderErrorKind;
+}
+export declare function handleDetectTagMigration(): Promise<ApiResponse<{
+    needsMigration: boolean;
+    count: number;
+}>>;
+export declare function handleGetTagMigrationProgress(): Promise<ApiResponse<MigrationProgress>>;
+/**
+ * Tag the memories that have no tags, a few per request. Only untagged
+ * memories are touched: tagged ones keep their vectors. A memory that fails
+ * is recorded and passed over, so one bad row cannot stall the run. An error
+ * that fails every memory the same way (no credit, a rejected key) ends the
+ * run at once, so a later run starts over with every untagged memory.
+ */
+export declare function runTagMigrationBatch(config: TagMigrationConfig, batchSize?: number): Promise<ApiResponse<TagMigrationBatch>>;
+export {};