om-memory-system 3.4.0-next.21 → 3.4.0-next.26

package/dist/services/memory-key-source.d.ts

@@ -0,0 +1,35 @@
+import { restrictToCurrentUser } from "./private-path.js";
+/** How the External API card supplies `memoryApiKey`; a pasted value never leaves this module. */
+export type MemoryKeySourceRequest = {
+    source: "env";
+    name: string;
+} | {
+    source: "file";
+    path: string;
+} | {
+    source: "paste";
+    name: string;
+    value: string;
+    replace?: boolean;
+};
+export declare class MemoryKeySourceError extends Error {
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+export declare const secretsDirectory: () => string;
+/** Check a request's shape; error messages never include the pasted value. */
+export declare function parseMemoryKeySource(body: unknown): MemoryKeySourceRequest;
+/**
+ * Turn a key source into an `env://` or `file://` reference. A pasted key is
+ * written to `~/.config/omms/secrets/<name>.key`, readable only by the user,
+ * and replaces an existing file only when the request confirms it.
+ */
+export declare function storeMemoryKeySource(request: MemoryKeySourceRequest, options?: {
+    directory?: string;
+    platform?: NodeJS.Platform;
+    restrict?: typeof restrictToCurrentUser;
+}): Promise<{
+    reference: string;
+    source: "env" | "file";
+    path?: string;
+}>;

package/dist/services/memory-key-source.js

@@ -0,0 +1,123 @@
+import { randomUUID } from "node:crypto";
+import { promises as fs, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { restrictToCurrentUser } from "./private-path.js";
+export class MemoryKeySourceError extends Error {
+    status;
+    constructor(message, status = 400) {
+        super(message);
+        this.status = status;
+        this.name = "MemoryKeySourceError";
+    }
+}
+export const secretsDirectory = () => join(homedir(), ".config", "omms", "secrets");
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const KEY_FILE_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+function expandHome(path) {
+    if (path === "~")
+        return homedir();
+    if (path.startsWith("~/") || path.startsWith("~\\"))
+        return join(homedir(), path.slice(2));
+    return path;
+}
+/** Check a request's shape; error messages never include the pasted value. */
+export function parseMemoryKeySource(body) {
+    const request = (body ?? {});
+    if (request.source === "env") {
+        if (typeof request.name !== "string" || !ENV_NAME.test(request.name)) {
+            throw new MemoryKeySourceError("Enter a variable name such as ZAI_API_KEY");
+        }
+        return { source: "env", name: request.name };
+    }
+    if (request.source === "file") {
+        if (typeof request.path !== "string" || !request.path.trim()) {
+            throw new MemoryKeySourceError("Enter the path of a key file");
+        }
+        return { source: "file", path: request.path.trim() };
+    }
+    if (request.source === "paste") {
+        if (typeof request.name !== "string" || !KEY_FILE_NAME.test(request.name)) {
+            throw new MemoryKeySourceError("Name the key file with letters, digits, dashes, or underscores");
+        }
+        if (typeof request.value !== "string" || !request.value.trim()) {
+            throw new MemoryKeySourceError("Paste the key");
+        }
+        return {
+            source: "paste",
+            name: request.name,
+            value: request.value,
+            replace: request.replace === true,
+        };
+    }
+    throw new MemoryKeySourceError("Choose a key source");
+}
+/**
+ * Turn a key source into an `env://` or `file://` reference. A pasted key is
+ * written to `~/.config/omms/secrets/<name>.key`, readable only by the user,
+ * and replaces an existing file only when the request confirms it.
+ */
+export async function storeMemoryKeySource(request, options = {}) {
+    if (request.source === "env")
+        return { reference: `env://${request.name}`, source: "env" };
+    if (request.source === "file") {
+        const path = expandHome(request.path);
+        let isFile;
+        try {
+            isFile = isAbsolute(path) && statSync(path).isFile();
+        }
+        catch {
+            isFile = false;
+        }
+        if (!isFile)
+            throw new MemoryKeySourceError("The key file does not exist");
+        return { reference: `file://${path}`, source: "file", path };
+    }
+    const directory = options.directory ?? secretsDirectory();
+    const platform = options.platform ?? process.platform;
+    const restrict = options.restrict ?? restrictToCurrentUser;
+    await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    try {
+        restrict(directory, 0o700, platform);
+    }
+    catch {
+        throw new MemoryKeySourceError("The secrets folder could not be made private", 500);
+    }
+    const path = join(directory, `${request.name}.key`);
+    const content = `${request.value.trim()}\n`;
+    if (!request.replace) {
+        try {
+            await fs.writeFile(path, content, { flag: "wx", mode: 0o600 });
+        }
+        catch (error) {
+            if (error.code === "EEXIST") {
+                throw new MemoryKeySourceError(`A key file named ${request.name}.key exists. Confirm to replace it.`, 409);
+            }
+            throw new MemoryKeySourceError("The key file could not be written", 500);
+        }
+        try {
+            restrict(path, 0o600, platform);
+        }
+        catch {
+            // Never leave a key readable by others: remove it so a retry starts clean.
+            await fs.rm(path, { force: true });
+            throw new MemoryKeySourceError("The key file could not be made private", 500);
+        }
+    }
+    else {
+        const temp = join(directory, `.${randomUUID()}.tmp`);
+        try {
+            await fs.writeFile(temp, content, { flag: "wx", mode: 0o600 });
+            restrict(temp, 0o600, platform);
+            await fs.rename(temp, path);
+        }
+        catch {
+            throw new MemoryKeySourceError("The key file could not be written", 500);
+        }
+        finally {
+            await fs.rm(temp, { force: true });
+        }
+    }
+    // A replaced file was made private as the temp file before it moved into place.
+    return { reference: `file://${path}`, source: "file", path };
+}

package/dist/services/package-version.d.ts

@@ -0,0 +1,2 @@
+/** This package's version, found by walking up to its `package.json` from source or `dist/`. */
+export declare function packageVersion(from?: string): string;

package/dist/services/package-version.js

@@ -0,0 +1,21 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** This package's version, found by walking up to its `package.json` from source or `dist/`. */
+export function packageVersion(from = import.meta.url) {
+    let dir = dirname(fileURLToPath(from));
+    for (;;) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+            if (pkg.name === "om-memory-system" && pkg.version)
+                return pkg.version;
+        }
+        catch {
+            /* Try the parent. */
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return "unknown";
+        dir = parent;
+    }
+}

package/dist/services/private-path.d.ts

@@ -0,0 +1,13 @@
+type WindowsAclRunner = (command: string, args: string[], options: {
+    env: NodeJS.ProcessEnv;
+    timeout: number;
+    windowsHide: boolean;
+    stdio: "ignore";
+}) => void;
+/**
+ * Restrict a path to the current user: `chmod` on macOS and Linux, and on
+ * Windows an access list with inheritance removed and one full-control rule
+ * for the owner, who must be the current user.
+ */
+export declare function restrictToCurrentUser(path: string, mode: number, platform?: NodeJS.Platform, run?: WindowsAclRunner): void;
+export {};

package/dist/services/private-path.js

@@ -0,0 +1,54 @@
+import { execFileSync } from "node:child_process";
+import { chmodSync } from "node:fs";
+const WINDOWS_USER_ONLY_ACL = `$ErrorActionPreference = 'Stop'
+$path = $env:OMMS_PRIVATE_PATH
+$isDirectory = [System.IO.Directory]::Exists($path)
+$acl = if ($isDirectory) {
+  [System.IO.Directory]::GetAccessControl($path)
+} else {
+  [System.IO.File]::GetAccessControl($path)
+}
+$currentUser = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
+$owner = $acl.GetOwner([System.Security.Principal.SecurityIdentifier])
+if ($owner.Value -ne $currentUser.Value) {
+  throw 'Path has a different owner'
+}
+$acl.SetAccessRuleProtection($true, $false)
+foreach ($rule in @($acl.Access)) {
+  [void]$acl.RemoveAccessRuleSpecific($rule)
+}
+$inheritance = if ($isDirectory) {
+  [System.Security.AccessControl.InheritanceFlags]'ContainerInherit, ObjectInherit'
+} else {
+  [System.Security.AccessControl.InheritanceFlags]::None
+}
+$rule = [System.Security.AccessControl.FileSystemAccessRule]::new(
+  $currentUser,
+  [System.Security.AccessControl.FileSystemRights]::FullControl,
+  $inheritance,
+  [System.Security.AccessControl.PropagationFlags]::None,
+  [System.Security.AccessControl.AccessControlType]::Allow
+)
+$acl.AddAccessRule($rule)
+if ($isDirectory) {
+  [System.IO.Directory]::SetAccessControl($path, $acl)
+} else {
+  [System.IO.File]::SetAccessControl($path, $acl)
+}`;
+/**
+ * Restrict a path to the current user: `chmod` on macOS and Linux, and on
+ * Windows an access list with inheritance removed and one full-control rule
+ * for the owner, who must be the current user.
+ */
+export function restrictToCurrentUser(path, mode, platform = process.platform, run = execFileSync) {
+    if (platform !== "win32") {
+        chmodSync(path, mode);
+        return;
+    }
+    run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", WINDOWS_USER_ONLY_ACL], {
+        env: { ...process.env, OMMS_PRIVATE_PATH: path },
+        timeout: 10_000,
+        windowsHide: true,
+        stdio: "ignore",
+    });
+}

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

@@ -11,14 +11,31 @@ export declare function getSettingsSnapshot(directory: string): {
         [k: string]: {
             set: boolean;
             source: string | null;
+            reference: string | null;
         };
     };
     fallback: {
         model: string | null;
         configured: boolean;
     };
+    externalKey: {
+        source: string | null;
+        reference: string | null;
+        resolvesInWebApp: boolean;
+        warning: string | null;
+    };
     effective: {
         opencode: import("./ai/live-model-choice.js").AutoCaptureProviderStatus;
         pi: import("./ai/live-model-choice.js").PiLiveModelChoice;
     };
 };
+/**
+ * Where `memoryApiKey` comes from and whether it resolves in this web
+ * server's own process. The key value itself is never returned.
+ */
+export declare function memoryKeyStatus(raw: unknown, resolved?: string | undefined): {
+    source: string | null;
+    reference: string | null;
+    resolvesInWebApp: boolean;
+    warning: string | null;
+};

package/dist/services/settings-snapshot.js

@@ -16,6 +16,20 @@ const editable = [
     "opencodeBackfillModel",
     "piBackfillModel",
     "webServerAutoStart",
+    "memoryProvider",
+    "memoryApiUrl",
+    "memoryModel",
+    "importPathMaps",
+];
+/** Keys a project config cannot override, so the page always shows the global value. */
+const globalOnly = [
+    "autoBackfill",
+    "opencodeBackfillModel",
+    "piBackfillModel",
+    "webServerAutoStart",
+    "memoryProvider",
+    "memoryApiUrl",
+    "importPathMaps",
 ];
 function readSettingsFile(path) {
     if (!path)
@@ -39,13 +53,7 @@ export function getSettingsSnapshot(directory) {
         const projectOverrides = Object.hasOwn(project, key) &&
             (key === "captureTrace"
                 ? project[key] === false
-                : !key.endsWith("RetentionDays") &&
-                    ![
-                        "autoBackfill",
-                        "opencodeBackfillModel",
-                        "piBackfillModel",
-                        "webServerAutoStart",
-                    ].includes(key));
+                : !key.endsWith("RetentionDays") && !globalOnly.includes(key));
         const source = projectOverrides
             ? "project"
             : Object.hasOwn(global, key)
@@ -56,17 +64,20 @@ export function getSettingsSnapshot(directory) {
     }));
     const secrets = Object.fromEntries(["memoryApiKey", "embeddingApiKey", "webServerApiToken", "webServerAuthPassword"].map((key) => {
         const raw = global[key];
+        const source = typeof raw === "string"
+            ? raw.startsWith("env://")
+                ? "env"
+                : raw.startsWith("file://")
+                    ? "file"
+                    : "literal"
+            : null;
         return [
             key,
             {
                 set: typeof raw === "string" && raw.length > 0,
-                source: typeof raw === "string"
-                    ? raw.startsWith("env://")
-                        ? "env"
-                        : raw.startsWith("file://")
-                            ? "file"
-                            : "literal"
-                    : null,
+                source,
+                // The variable name or file path, never a literal value.
+                reference: memoryKeyStatus(raw).reference,
             },
         ];
     }));
@@ -75,9 +86,35 @@ export function getSettingsSnapshot(directory) {
         settings,
         secrets,
         fallback: { model: CONFIG.memoryModel ?? null, configured: isExternalModelReady(CONFIG) },
+        externalKey: memoryKeyStatus(global.memoryApiKey),
         effective: {
             opencode: getAutoCaptureProviderStatus(CONFIG),
             pi: resolvePiLiveModel(CONFIG),
         },
     };
 }
+/**
+ * Where `memoryApiKey` comes from and whether it resolves in this web
+ * server's own process. The key value itself is never returned.
+ */
+export function memoryKeyStatus(raw, resolved = CONFIG.memoryApiKey) {
+    const source = typeof raw !== "string" || !raw
+        ? null
+        : raw.startsWith("env://")
+            ? "env"
+            : raw.startsWith("file://")
+                ? "file"
+                : "literal";
+    return {
+        source,
+        reference: source === "env"
+            ? raw.slice("env://".length)
+            : source === "file"
+                ? raw.slice("file://".length)
+                : null,
+        resolvesInWebApp: Boolean(resolved),
+        warning: source === "env"
+            ? "A login web app does not see variables set only in a shell profile; a key file works everywhere."
+            : null,
+    };
+}

package/dist/services/turso/vector-search.d.ts

@@ -12,7 +12,7 @@ export declare class TursoVectorSearch {
         warnings: string[];
     }>;
     deleteVector(db: TursoDb, memoryId: string): Promise<void>;
-    updateVector(db: TursoDb, memoryId: string, vector: Float32Array, tagsVector?: Float32Array): Promise<void>;
+    updateVector(db: TursoDb, memoryId: string, vector: Float32Array, tagsVector?: Float32Array, tags?: string): Promise<void>;
     listMemories(db: TursoDb, containerTag: string, limit: number): Promise<Record<string, unknown>[]>;
     getAllMemories(db: TursoDb): Promise<Record<string, unknown>[]>;
     getAllMemoriesWithExtractedVectors(db: TursoDb): Promise<Array<Record<string, unknown> & {

package/dist/services/turso/vector-search.js

@@ -263,9 +263,12 @@ export class TursoVectorSearch {
     async deleteVector(db, memoryId) {
         await db.run(`DELETE FROM memories WHERE id = ?`, [memoryId]);
     }
-    async updateVector(db, memoryId, vector, tagsVector) {
+    async updateVector(db, memoryId, vector, tagsVector, tags) {
         const contentVector = vectorToJson(vector);
-        if (tagsVector) {
+        if (tagsVector && tags !== undefined) {
+            await db.execute(`UPDATE memories SET tags = ?, vector = vector32(?), tags_vector = vector32(?) WHERE id = ?`, [tags, contentVector, vectorToJson(tagsVector), memoryId]);
+        }
+        else if (tagsVector) {
             await db.execute(`UPDATE memories SET vector = vector32(?), tags_vector = vector32(?) WHERE id = ?`, [contentVector, vectorToJson(tagsVector), memoryId]);
         }
         else {

package/dist/services/web-server.d.ts

@@ -36,8 +36,10 @@ export declare class WebServer {
     private takeoverFailures;
     private readonly maxFallbackPort;
     private settingsImportJobs?;
+    private backfillControlsInstance?;
     /** Run an import-page action; errors carry their own status and never file contents. */
     private importResponse;
+    private backfillControls;
     private importJobs;
     constructor(config: WebServerConfig);
     setOnTakeoverCallback(callback: () => Promise<void>): void;

package/dist/services/web-server.js

@@ -146,6 +146,7 @@ export class WebServer {
     takeoverFailures = 0;
     maxFallbackPort;
     settingsImportJobs;
+    backfillControlsInstance;
     /** Run an import-page action; errors carry their own status and never file contents. */
     async importResponse(action, status = 200) {
         try {
@@ -156,6 +157,10 @@ export class WebServer {
             return this.jsonResponse({ error: error instanceof Error ? error.message : "Import request failed" }, typeof code === "number" ? code : 400);
         }
     }
+    async backfillControls() {
+        const { BackfillControls } = await import("../importer/web-import-api.js");
+        return (this.backfillControlsInstance ??= new BackfillControls());
+    }
     async importJobs() {
         const { SettingsImportJobs } = await import("../importer/web-import-jobs.js");
         return (this.settingsImportJobs ??= new SettingsImportJobs());
@@ -422,6 +427,34 @@ export class WebServer {
                     opencode: await readBackfillStatus("opencode"),
                 });
             }
+            if (path === "/api/settings/backfill/runs" && method === "GET") {
+                return this.jsonResponse(await (await this.backfillControls()).status());
+            }
+            const backfillAction = /^\/api\/settings\/backfill\/(pi|opencode)\/(run|pause|resume)$/.exec(path);
+            if (backfillAction && method === "POST") {
+                const host = backfillAction[1];
+                const controls = await this.backfillControls();
+                const cwd = this.config.directory ?? process.cwd();
+                return this.importResponse(() => backfillAction[2] === "pause"
+                    ? controls.pause(host)
+                    : backfillAction[2] === "resume"
+                        ? controls.resume(host, cwd)
+                        : controls.runNow(host, cwd));
+            }
+            if (path === "/api/settings/version" && method === "GET") {
+                const [{ packageVersion }, { globalCommandVersion }] = await Promise.all([
+                    import("./package-version.js"),
+                    import("./global-version.js"),
+                ]);
+                const running = packageVersion();
+                const global = await globalCommandVersion();
+                return this.jsonResponse({
+                    running,
+                    global: global.version,
+                    globalPath: global.path,
+                    mismatch: global.version !== null && global.version !== running,
+                });
+            }
             if (path === "/api/settings/web-autostart" && method === "GET") {
                 const { webAutostartStatus } = await import("./web-autostart.js");
                 return this.jsonResponse(webAutostartStatus());
@@ -460,6 +493,45 @@ export class WebServer {
                 }
                 return this.jsonResponse(result);
             }
+            if (path === "/api/settings/external-api/key" && method === "POST") {
+                // The body can hold a pasted key: never log it, and never echo it back.
+                const body = (await req.json());
+                const { MemoryKeySourceError, parseMemoryKeySource, storeMemoryKeySource } = await import("./memory-key-source.js");
+                try {
+                    const request = parseMemoryKeySource(body);
+                    if (request.source === "paste" &&
+                        !isLoopbackHost(this.config.host) &&
+                        !auth?.isEnabled()) {
+                        return this.jsonResponse({ error: "Saving a key requires Basic Auth on network hosts" }, 403);
+                    }
+                    if (typeof body?.revision !== "string") {
+                        return this.jsonResponse({ error: "Revision required" }, 400);
+                    }
+                    const stored = await storeMemoryKeySource(request);
+                    const { writeGlobalConfigKeys } = await import("./global-config-writer.js");
+                    const result = await writeGlobalConfigKeys({ memoryApiKey: stored.reference }, body.revision);
+                    const { refreshConfigIfChanged } = await import("../config.js");
+                    refreshConfigIfChanged(this.config.directory ?? process.cwd());
+                    const { memoryKeyStatus } = await import("./settings-snapshot.js");
+                    return this.jsonResponse({ ...result, key: memoryKeyStatus(stored.reference) });
+                }
+                catch (error) {
+                    const status = error instanceof MemoryKeySourceError
+                        ? error.status
+                        : (error.status ?? 400);
+                    const message = error instanceof Error ? error.message : "Key source not saved";
+                    const secret = typeof body?.value === "string" ? body.value.trim() : "";
+                    return this.jsonResponse({ error: secret ? message.replaceAll(secret, "[redacted]") : message }, status);
+                }
+            }
+            if (path === "/api/settings/external-api/test" && method === "POST") {
+                const { testExternalApi } = await import("../importer/web-import-api.js");
+                return this.jsonResponse(await testExternalApi());
+            }
+            if (path === "/api/settings/import-maps" && method === "GET") {
+                const { directoryMapsView } = await import("../importer/web-import-api.js");
+                return this.jsonResponse(await directoryMapsView());
+            }
             if (path === "/api/settings/models" && method === "GET") {
                 const { listOpencodeSettingsModels, listPiSettingsModels } = await import("./settings-models.js");
                 const host = url.searchParams.get("host");
@@ -569,7 +641,8 @@ export class WebServer {
                 const page = parseInt(url.searchParams.get("page") || "1");
                 const pageSize = parseInt(url.searchParams.get("pageSize") || "20");
                 const includePrompts = url.searchParams.get("includePrompts") !== "false";
-                const result = await handleListMemories(tag, page, pageSize, includePrompts);
+                const keyword = url.searchParams.get("keyword") || undefined;
+                const result = await handleListMemories(tag, page, pageSize, includePrompts, keyword);
                 return this.jsonResponse(result);
             }
             if (path === "/api/memories" && method === "POST") {