@cueai/omni-reader-mcp 1.0.2 → 1.1.1

package/dist/cli/agent-config.js

@@ -1,7 +1,10 @@
 import { createHash, randomBytes } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
-import { chmod, lstat, mkdir, open, rename, } from "node:fs/promises";
+import { chmod, lstat, mkdir, open, realpath, rename, unlink, } from "node:fs/promises";
 import path from "node:path";
+import { BRIDGE_RELEASE_VERSION, REMOTE_OMNI_MCP_URL, } from "../constants.js";
+const PACKAGE_SPEC = `@cueai/omni-reader-mcp@${BRIDGE_RELEASE_VERSION}`;
+const LEGACY_PACKAGE_SPEC = "@cueai/omni-reader-mcp";
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -13,17 +16,70 @@ function fileError(message) {
 function pathModule(platform) {
     return platform === "win32" ? path.win32 : path.posix;
 }
+function containsPath(parent, child, paths) {
+    const relative = paths.relative(parent, child);
+    return relative === "" || (relative !== ".." &&
+        !relative.startsWith(`..${paths.sep}`) &&
+        !paths.isAbsolute(relative));
+}
+function normalizedOmniName(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]/gu, "") === "omnireader";
+}
+function redactSecrets(value) {
+    if (Array.isArray(value))
+        return value.map(redactSecrets);
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => [
+        key,
+        /authorization|api[_-]?key|token|secret|password/iu.test(key)
+            ? "[redacted]"
+            : redactSecrets(child),
+    ]));
+}
+function safeCredentialReferences(value) {
+    if (!isRecord(value))
+        return true;
+    for (const [key, child] of Object.entries(value)) {
+        if (/authorization|api[_-]?key|token|secret|password/iu.test(key)) {
+            if (child !== "${CUE_API_KEY}" &&
+                child !== "Bearer ${CUE_API_KEY}")
+                return false;
+            continue;
+        }
+        if (Array.isArray(child)) {
+            if (!child.every((item) => !isRecord(item) || safeCredentialReferences(item)))
+                return false;
+        }
+        else if (isRecord(child) && !safeCredentialReferences(child)) {
+            return false;
+        }
+    }
+    return true;
+}
+function assertNoLiteralApiKey(serialized, environment) {
+    const apiKey = environment.env?.CUE_API_KEY;
+    if (apiKey !== undefined && apiKey.length > 0 && serialized.includes(apiKey)) {
+        throw fileError("The Agent configuration contains a literal API key; no changes were written.");
+    }
+}
 export function parseAgentTarget(value) {
     const normalized = value.trim().toLowerCase();
+    if (normalized === "hermes")
+        return "hermes";
     if (normalized === "cursor")
         return "cursor";
-    if (normalized === "claude desktop" || normalized === "claude" || normalized === "claude-desktop") {
+    if (normalized === "claude desktop" ||
+        normalized === "claude" ||
+        normalized === "claude-desktop")
         return "claude-desktop";
-    }
     return "generic";
 }
 export function agentConfigPath(target, environment) {
     const paths = pathModule(environment.platform);
+    if (target === "hermes") {
+        return paths.join(environment.homeDirectory, ".hermes", "config.yaml");
+    }
     if (target === "cursor") {
         return paths.join(environment.homeDirectory, ".cursor", "mcp.json");
     }
@@ -40,31 +96,73 @@ export function agentConfigPath(target, environment) {
     }
     return undefined;
 }
+export function agentBackupPath(configPath) {
+    return `${configPath}.omni-reader.backup.json`;
+}
 export function displayConfigPath(configPath, environment) {
     const paths = pathModule(environment.platform);
     const relative = paths.relative(environment.homeDirectory, configPath);
-    if (relative !== "" && relative !== ".." && !relative.startsWith(`..${paths.sep}`)) {
+    if (relative !== "" &&
+        relative !== ".." &&
+        !relative.startsWith(`..${paths.sep}`)) {
         return `~/${relative.split(paths.sep).join("/")}`;
     }
     return configPath;
 }
-export function buildAgentEntry(extraRoots, platform) {
+export function buildAgentEntry(target, extraRoots, platform) {
     const entry = {
         command: "npx",
-        args: ["-y", "@cueai/omni-reader-mcp"],
+        args: ["-y", PACKAGE_SPEC],
     };
+    const env = {};
+    if (target === "hermes")
+        env.CUE_API_KEY = "${CUE_API_KEY}";
     if (extraRoots.length > 0) {
-        entry.env = {
-            OMNI_ALLOWED_ROOTS: extraRoots.join(platform === "win32" ? ";" : ":"),
-        };
+        env.OMNI_ALLOWED_ROOTS = extraRoots.join(platform === "win32" ? ";" : ":");
     }
+    if (Object.keys(env).length > 0)
+        entry.env = env;
     return entry;
 }
-function containsPath(parent, child, paths) {
-    const relative = paths.relative(parent, child);
-    return relative === "" || (relative !== ".." && !relative.startsWith(`..${paths.sep}`));
+function configFormat(target) {
+    return target === "hermes" ? "hermes-yaml" : "json";
+}
+function reloadInstruction(target) {
+    if (target === "hermes")
+        return "Run /reload-mcp in Hermes.";
+    if (target === "cursor")
+        return "Reload the Cursor window.";
+    if (target === "claude-desktop")
+        return "Restart Claude Desktop.";
+    return "Reload the Agent MCP configuration.";
+}
+async function pathDetails(filePath) {
+    try {
+        return await lstat(filePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
 }
-async function validateUserConfigPath(configPath, environment) {
+async function validateAuxiliaryPaths(configPath, allowLock) {
+    for (const [kind, candidate] of [
+        ["lock", `${configPath}.omni-reader.lock`],
+        ["backup", agentBackupPath(configPath)],
+    ]) {
+        const details = await pathDetails(candidate);
+        if (details === undefined)
+            continue;
+        if (details.isSymbolicLink() || !details.isFile()) {
+            throw fileError(`The Agent configuration ${kind} path is unsafe; no changes were written.`);
+        }
+        if (kind === "lock" && !allowLock) {
+            throw fileError("Another Omni setup is updating this Agent configuration; retry after it finishes.");
+        }
+    }
+}
+async function validateUserConfigPath(configPath, environment, allowLock = false) {
     const paths = pathModule(environment.platform);
     const homeDirectory = paths.resolve(environment.homeDirectory);
     const userRoots = [homeDirectory];
@@ -76,39 +174,56 @@ async function validateUserConfigPath(configPath, environment) {
     if (userRoot === undefined) {
         throw fileError("The Agent configuration path is outside the user profile; no changes were written.");
     }
+    let canonicalUserRoot;
+    try {
+        canonicalUserRoot = await realpath(userRoot);
+    }
+    catch {
+        throw fileError("The Agent user profile could not be resolved safely; no changes were written.");
+    }
+    const rootDetails = await lstat(userRoot);
+    if (!rootDetails.isDirectory() || rootDetails.isSymbolicLink()) {
+        throw fileError("The Agent user profile is unsafe; no changes were written.");
+    }
     const relativeParent = paths.relative(userRoot, paths.dirname(resolvedConfigPath));
     const components = relativeParent === "" ? [] : relativeParent.split(paths.sep);
     let current = userRoot;
-    for (const component of ["", ...components]) {
-        if (component !== "")
-            current = paths.join(current, component);
-        try {
-            const details = await lstat(current);
-            if (!details.isDirectory() || details.isSymbolicLink()) {
-                throw fileError("The Agent configuration path contains an unsafe directory; no changes were written.");
-            }
-        }
-        catch (error) {
-            if (error.code === "ENOENT")
-                break;
-            throw error;
+    let nearestExisting = userRoot;
+    for (const component of components) {
+        current = paths.join(current, component);
+        const details = await pathDetails(current);
+        if (details === undefined)
+            break;
+        if (!details.isDirectory() || details.isSymbolicLink()) {
+            throw fileError("The Agent configuration path contains an unsafe directory; no changes were written.");
         }
+        nearestExisting = current;
     }
-    try {
-        const details = await lstat(resolvedConfigPath);
-        if (!details.isFile() || details.isSymbolicLink()) {
+    const canonicalExisting = await realpath(nearestExisting);
+    if (!containsPath(canonicalUserRoot, canonicalExisting, paths)) {
+        throw fileError("The Agent configuration path escapes the user profile; no changes were written.");
+    }
+    const configDetails = await pathDetails(resolvedConfigPath);
+    if (configDetails !== undefined) {
+        if (!configDetails.isFile() || configDetails.isSymbolicLink()) {
             throw fileError("The existing Agent configuration is unsafe; no changes were written.");
         }
+        const canonicalConfig = await realpath(resolvedConfigPath);
+        if (!containsPath(canonicalUserRoot, canonicalConfig, paths)) {
+            throw fileError("The Agent configuration path escapes the user profile; no changes were written.");
+        }
     }
-    catch (error) {
-        if (error.code !== "ENOENT")
-            throw error;
-    }
+    await validateAuxiliaryPaths(resolvedConfigPath, allowLock);
 }
-function configFingerprint(loaded) {
-    if (!loaded.existed || loaded.serialized === undefined)
-        return "missing";
-    return `sha256:${createHash("sha256").update(loaded.serialized).digest("hex")}`;
+function configFingerprint(serialized, details) {
+    const digest = createHash("sha256").update(serialized, "utf8").digest("hex");
+    return [
+        `dev=${details.dev}`,
+        `ino=${details.ino}`,
+        `size=${details.size}`,
+        `mtime_ms=${details.mtimeMs}`,
+        `sha256:${digest}`,
+    ].join(";");
 }
 async function readConfig(configPath) {
     let handle;
@@ -117,37 +232,438 @@ async function readConfig(configPath) {
     }
     catch (error) {
         const code = error.code;
-        if (code === "ENOENT")
-            return { existed: false, value: {} };
+        if (code === "ENOENT") {
+            return { existed: false, serialized: "", fingerprint: "missing" };
+        }
         if (code === "ELOOP" || code === "EMLINK") {
             throw fileError("The existing Agent configuration is unsafe; no changes were written.");
         }
         throw fileError("The existing Agent configuration could not be read.");
     }
-    let serialized;
     try {
         const details = await handle.stat();
         if (!details.isFile()) {
             throw fileError("The existing Agent configuration is unsafe; no changes were written.");
         }
-        serialized = await handle.readFile("utf8");
+        const serialized = await handle.readFile("utf8");
+        return {
+            existed: true,
+            serialized,
+            fingerprint: configFingerprint(serialized, details),
+        };
     }
     finally {
         await handle.close();
     }
+}
+function parseJsonConfig(loaded) {
+    if (!loaded.existed)
+        return {};
     try {
-        const parsed = JSON.parse(serialized);
+        const parsed = JSON.parse(loaded.serialized);
         if (!isRecord(parsed))
             throw new Error("configuration is not an object");
-        return { existed: true, value: parsed, serialized };
+        return parsed;
     }
     catch {
         throw fileError("The existing Agent configuration is malformed JSON; no changes were written.");
     }
 }
+function jsonStringToken(serialized, start) {
+    let escaped = false;
+    for (let index = start + 1; index < serialized.length; index += 1) {
+        const character = serialized[index];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (character === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (character === '"') {
+            const token = serialized.slice(start, index + 1);
+            const value = JSON.parse(token);
+            if (typeof value !== "string")
+                throw new Error("invalid JSON string");
+            return { value, end: index + 1 };
+        }
+    }
+    throw new Error("unterminated JSON string");
+}
+function skipJsonWhitespace(serialized, start) {
+    let index = start;
+    while (/\s/u.test(serialized[index] ?? ""))
+        index += 1;
+    return index;
+}
+function mcpServerObjectRange(serialized) {
+    for (let index = 0; index < serialized.length; index += 1) {
+        if (serialized[index] !== '"')
+            continue;
+        const token = jsonStringToken(serialized, index);
+        index = token.end - 1;
+        if (token.value !== "mcpServers")
+            continue;
+        let cursor = skipJsonWhitespace(serialized, token.end);
+        if (serialized[cursor] !== ":")
+            continue;
+        cursor = skipJsonWhitespace(serialized, cursor + 1);
+        if (serialized[cursor] !== "{")
+            continue;
+        const start = cursor;
+        let depth = 0;
+        for (; cursor < serialized.length; cursor += 1) {
+            if (serialized[cursor] === '"') {
+                cursor = jsonStringToken(serialized, cursor).end - 1;
+                continue;
+            }
+            if (serialized[cursor] === "{")
+                depth += 1;
+            if (serialized[cursor] === "}" && --depth === 0) {
+                return { start, end: cursor + 1 };
+            }
+        }
+    }
+    return undefined;
+}
+function assertNoDuplicateJsonOmniEntries(serialized) {
+    const range = mcpServerObjectRange(serialized);
+    if (range === undefined)
+        return;
+    let depth = 0;
+    let count = 0;
+    for (let index = range.start; index < range.end; index += 1) {
+        const character = serialized[index];
+        if (character === '"') {
+            const token = jsonStringToken(serialized, index);
+            if (depth === 1) {
+                const cursor = skipJsonWhitespace(serialized, token.end);
+                if (serialized[cursor] === ":" && normalizedOmniName(token.value))
+                    count += 1;
+            }
+            index = token.end - 1;
+            continue;
+        }
+        if (character === "{" || character === "[")
+            depth += 1;
+        if (character === "}" || character === "]")
+            depth -= 1;
+    }
+    if (count > 1) {
+        throw fileError("The Agent configuration contains duplicate Omni entries; no changes were written.");
+    }
+}
+function sourceLines(serialized) {
+    const lines = [];
+    let start = 0;
+    while (start < serialized.length) {
+        const newline = serialized.indexOf("\n", start);
+        const end = newline === -1 ? serialized.length : newline + 1;
+        lines.push({ start, end, text: serialized.slice(start, end).replace(/\r?\n$/u, "") });
+        start = end;
+    }
+    return lines;
+}
+function parseYamlName(value) {
+    const trimmed = value.trim();
+    if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (typeof parsed === "string")
+                return parsed;
+        }
+        catch {
+            // Rejected below.
+        }
+    }
+    if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+        return trimmed.slice(1, -1).replace(/''/gu, "'");
+    }
+    if (/^[A-Za-z0-9_.-]+$/u.test(trimmed))
+        return trimmed;
+    throw fileError("The Hermes MCP configuration uses an unsupported server name; no changes were written.");
+}
+function parseHermesDocument(serialized) {
+    const lines = sourceLines(serialized);
+    const newline = serialized.includes("\r\n") ? "\r\n" : "\n";
+    const allBlockHeaders = lines.filter((line) => /^mcp_servers:/u.test(line.text));
+    const blockHeaders = allBlockHeaders.filter((line) => /^mcp_servers:\s*(?:#.*)?$/u.test(line.text));
+    if (allBlockHeaders.length !== blockHeaders.length) {
+        throw fileError("The Hermes mcp_servers setting must use a block mapping; no changes were written.");
+    }
+    if (blockHeaders.length > 1) {
+        throw fileError("The Hermes configuration contains duplicate mcp_servers blocks; no changes were written.");
+    }
+    if (blockHeaders.length === 0)
+        return { entries: [], newline };
+    const blockHeader = blockHeaders[0];
+    const headerIndex = lines.indexOf(blockHeader);
+    let blockEnd = serialized.length;
+    for (let index = headerIndex + 1; index < lines.length; index += 1) {
+        const text = lines[index].text;
+        if (/^[^\s#][^:]*:/u.test(text)) {
+            blockEnd = lines[index].start;
+            break;
+        }
+    }
+    const entries = [];
+    const headers = [];
+    for (let index = headerIndex + 1; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (line.start >= blockEnd)
+            break;
+        const match = /^  (\S(?:.*\S)?):\s*(?:#.*)?$/u.exec(line.text);
+        if (match !== null)
+            headers.push({ name: parseYamlName(match[1]), start: line.start });
+    }
+    for (let index = 0; index < headers.length; index += 1) {
+        const header = headers[index];
+        const end = headers[index + 1]?.start ?? blockEnd;
+        entries.push({
+            name: header.name,
+            start: header.start,
+            end,
+            serialized: serialized.slice(header.start, end),
+        });
+    }
+    return {
+        blockStart: blockHeader.start,
+        blockEnd,
+        entries,
+        newline,
+    };
+}
+function parseYamlScalar(value) {
+    const trimmed = value.trim();
+    if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            throw fileError("The Hermes Omni entry contains invalid YAML; no changes were written.");
+        }
+    }
+    if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+        return trimmed.slice(1, -1).replace(/''/gu, "'");
+    }
+    if (trimmed === "true")
+        return true;
+    if (trimmed === "false")
+        return false;
+    return trimmed;
+}
+function parseHermesEntry(entry) {
+    const lines = sourceLines(entry.serialized).map((line) => line.text);
+    const value = {};
+    for (let index = 1; index < lines.length; index += 1) {
+        const match = /^    ([A-Za-z_][A-Za-z0-9_-]*):(?:\s*(.*))?$/u.exec(lines[index]);
+        if (match === null)
+            continue;
+        const key = match[1];
+        const scalar = match[2] ?? "";
+        if (key === "args" && scalar === "") {
+            const args = [];
+            while (index + 1 < lines.length) {
+                const item = /^      -\s+(.+)$/u.exec(lines[index + 1]);
+                if (item === null)
+                    break;
+                args.push(parseYamlScalar(item[1]));
+                index += 1;
+            }
+            value.args = args;
+            continue;
+        }
+        if (key === "env" && scalar === "") {
+            const env = {};
+            while (index + 1 < lines.length) {
+                const item = /^      ([A-Za-z_][A-Za-z0-9_]*):\s+(.+)$/u.exec(lines[index + 1]);
+                if (item === null)
+                    break;
+                env[item[1]] = parseYamlScalar(item[2]);
+                index += 1;
+            }
+            value.env = env;
+            continue;
+        }
+        value[key] = parseYamlScalar(scalar);
+    }
+    return value;
+}
+function yamlEntry(entry, newline) {
+    const args = entry.args;
+    const lines = [
+        "  omni-reader:",
+        "    command: npx",
+        "    args:",
+        ...args.map((argument) => `      - ${JSON.stringify(argument)}`),
+    ];
+    if (isRecord(entry.env)) {
+        lines.push("    env:");
+        for (const [key, value] of Object.entries(entry.env)) {
+            lines.push(`      ${key}: ${JSON.stringify(value)}`);
+        }
+    }
+    return `${lines.join(newline)}${newline}`;
+}
+function replaceHermesEntry(serialized, document, replacement) {
+    const existing = document.entries.find((entry) => entry.name === "omni-reader");
+    if (existing !== undefined) {
+        return serialized.slice(0, existing.start) + replacement + serialized.slice(existing.end);
+    }
+    if (document.blockEnd !== undefined) {
+        return serialized.slice(0, document.blockEnd) + replacement + serialized.slice(document.blockEnd);
+    }
+    const separator = serialized.length === 0 || serialized.endsWith("\n") ? "" : document.newline;
+    return `${serialized}${separator}mcp_servers:${document.newline}${replacement}`;
+}
+function removeHermesEntry(serialized, document, replacement) {
+    const existing = document.entries.find((entry) => entry.name === "omni-reader");
+    if (existing === undefined)
+        return serialized;
+    return serialized.slice(0, existing.start)
+        + (replacement ?? "")
+        + serialized.slice(existing.end);
+}
+function entryDigest(entry) {
+    const identity = {
+        command: entry.command,
+        args: entry.args,
+        ...(isRecord(entry.env) && entry.env.CUE_API_KEY !== undefined
+            ? { cue_api_key_reference: entry.env.CUE_API_KEY }
+            : {}),
+    };
+    return `sha256:${createHash("sha256").update(JSON.stringify(identity), "utf8").digest("hex")}`;
+}
+function isExpectedOmniEntry(target, value) {
+    if (!isRecord(value))
+        return false;
+    const args = value.args;
+    if (value.command !== "npx" ||
+        !Array.isArray(args) ||
+        args.length !== 2 ||
+        args[0] !== "-y" ||
+        args[1] !== PACKAGE_SPEC)
+        return false;
+    const keys = Object.keys(value).sort();
+    if (value.env === undefined) {
+        return target !== "hermes"
+            && keys.length === 2
+            && keys[0] === "args"
+            && keys[1] === "command";
+    }
+    if (!isRecord(value.env))
+        return false;
+    const envKeys = Object.keys(value.env).sort();
+    if (target === "hermes") {
+        if (value.env.CUE_API_KEY !== "${CUE_API_KEY}")
+            return false;
+        if (value.env.OMNI_ALLOWED_ROOTS !== undefined &&
+            (typeof value.env.OMNI_ALLOWED_ROOTS !== "string" || value.env.OMNI_ALLOWED_ROOTS.length === 0))
+            return false;
+        if (envKeys.length < 1 ||
+            envKeys.length > 2 ||
+            envKeys[0] !== "CUE_API_KEY" ||
+            (envKeys.length === 2 && envKeys[1] !== "OMNI_ALLOWED_ROOTS"))
+            return false;
+    }
+    else {
+        if (envKeys.length !== 1 ||
+            envKeys[0] !== "OMNI_ALLOWED_ROOTS" ||
+            typeof value.env.OMNI_ALLOWED_ROOTS !== "string" ||
+            value.env.OMNI_ALLOWED_ROOTS.length === 0)
+            return false;
+    }
+    return keys.length === 3
+        && keys[0] === "args"
+        && keys[1] === "command"
+        && keys[2] === "env";
+}
+function isLegacyBridgeEntry(target, value) {
+    if (!isRecord(value) || value.command !== "npx")
+        return false;
+    const args = value.args;
+    if (!Array.isArray(args) ||
+        args.length !== 2 ||
+        args[0] !== "-y" ||
+        (args[1] !== LEGACY_PACKAGE_SPEC && args[1] !== PACKAGE_SPEC))
+        return false;
+    if (value.env === undefined)
+        return target !== "hermes";
+    if (!isRecord(value.env) || !safeCredentialReferences(value.env))
+        return false;
+    const allowed = target === "hermes"
+        ? new Set(["CUE_API_KEY", "OMNI_ALLOWED_ROOTS"])
+        : new Set(["OMNI_ALLOWED_ROOTS"]);
+    return Object.keys(value.env).every((key) => allowed.has(key));
+}
+function isCanonicalRemoteEntry(value) {
+    return isRecord(value)
+        && value.url === REMOTE_OMNI_MCP_URL
+        && value.command === undefined
+        && value.args === undefined
+        && safeCredentialReferences(value);
+}
+function onlyOmniEntry(servers) {
+    const keys = Object.keys(servers).filter(normalizedOmniName);
+    if (keys.length > 1) {
+        throw fileError("The Agent configuration contains duplicate Omni entries; no changes were written.");
+    }
+    const key = keys[0];
+    if (key !== undefined && key !== "omni-reader") {
+        throw fileError("The Agent configuration contains a conflicting Omni entry; no changes were written.");
+    }
+    return key === undefined ? {} : { key, value: servers[key] };
+}
+function hermesOmniEntry(document) {
+    const entries = document.entries.filter((entry) => normalizedOmniName(entry.name));
+    if (entries.length > 1) {
+        throw fileError("The Hermes configuration contains duplicate Omni entries; no changes were written.");
+    }
+    const entry = entries[0];
+    if (entry !== undefined && entry.name !== "omni-reader") {
+        throw fileError("The Hermes configuration contains a conflicting Omni entry; no changes were written.");
+    }
+    return entry;
+}
+function previousJsonEntry(value) {
+    if (value === undefined)
+        return null;
+    if (isCanonicalRemoteEntry(value))
+        return { format: "json", value };
+    if (isLegacyBridgeEntry("cursor", value))
+        return null;
+    throw fileError("The existing Omni entry is not a trusted remote or Bridge configuration; no changes were written.");
+}
+function hermesCredentialsAreReferences(serialized) {
+    for (const line of sourceLines(serialized)) {
+        const match = /^\s+([A-Za-z_][A-Za-z0-9_-]*):\s+(.+)$/u.exec(line.text);
+        if (match === null ||
+            !/authorization|api[_-]?key|token|secret|password/iu.test(match[1]))
+            continue;
+        const value = parseYamlScalar(match[2]);
+        if (value !== "${CUE_API_KEY}" && value !== "Bearer ${CUE_API_KEY}")
+            return false;
+    }
+    return true;
+}
+function previousHermesEntry(entry) {
+    if (entry === undefined)
+        return null;
+    const value = parseHermesEntry(entry);
+    if (isCanonicalRemoteEntry(value)) {
+        if (!hermesCredentialsAreReferences(entry.serialized)) {
+            throw fileError("The Hermes Omni entry contains a literal credential; no changes were written.");
+        }
+        return { format: "hermes-yaml", serialized: entry.serialized };
+    }
+    if (isLegacyBridgeEntry("hermes", value))
+        return null;
+    throw fileError("The existing Hermes Omni entry is not a trusted remote or Bridge configuration; no changes were written.");
+}
 export async function prepareAgentConfig(target, extraRoots, environment) {
+    const entry = buildAgentEntry(target, extraRoots, environment.platform);
     const configPath = agentConfigPath(target, environment);
-    const entry = buildAgentEntry(extraRoots, environment.platform);
     if (configPath === undefined) {
         return {
             target: "generic",
@@ -156,31 +672,78 @@ export async function prepareAgentConfig(target, extraRoots, environment) {
             before: {},
             after: { mcpServers: { "omni-reader": entry } },
             entry,
+            reload: reloadInstruction("generic"),
         };
     }
+    const nativeTarget = target;
     await validateUserConfigPath(configPath, environment);
     const loaded = await readConfig(configPath);
-    const existingServers = loaded.value.mcpServers;
-    if (existingServers !== undefined && !isRecord(existingServers)) {
-        throw fileError("The existing mcpServers setting is not an object; no changes were written.");
-    }
-    const after = {
-        ...loaded.value,
-        mcpServers: {
-            ...(existingServers ?? {}),
-            "omni-reader": entry,
-        },
-    };
+    assertNoLiteralApiKey(loaded.serialized, environment);
+    const format = configFormat(nativeTarget);
+    if (format === "json") {
+        assertNoDuplicateJsonOmniEntries(loaded.serialized);
+        const value = parseJsonConfig(loaded);
+        const existingServers = value.mcpServers;
+        if (existingServers !== undefined && !isRecord(existingServers)) {
+            throw fileError("The existing mcpServers setting is not an object; no changes were written.");
+        }
+        const servers = existingServers ?? {};
+        const existing = onlyOmniEntry(servers);
+        const previousEntry = previousJsonEntry(existing.value);
+        const afterValue = {
+            ...value,
+            mcpServers: {
+                ...servers,
+                "omni-reader": entry,
+            },
+        };
+        return {
+            target: nativeTarget,
+            configPath,
+            displayPath: displayConfigPath(configPath, environment),
+            existed: loaded.existed,
+            before: redactSecrets(value),
+            after: redactSecrets(afterValue),
+            entry,
+            sourceFingerprint: loaded.fingerprint,
+            environment,
+            reload: reloadInstruction(nativeTarget),
+            format,
+            serializedBefore: loaded.serialized,
+            serializedAfter: `${JSON.stringify(afterValue, null, 2)}\n`,
+            previousEntry,
+        };
+    }
+    const document = parseHermesDocument(loaded.serialized);
+    const existing = hermesOmniEntry(document);
+    const previousEntry = previousHermesEntry(existing);
+    const serializedAfter = replaceHermesEntry(loaded.serialized, document, yamlEntry(entry, document.newline));
     return {
-        target,
+        target: "hermes",
         configPath,
         displayPath: displayConfigPath(configPath, environment),
         existed: loaded.existed,
-        before: loaded.value,
-        after,
+        before: {
+            format: "hermes-yaml",
+            other_settings: "preserved",
+            omni_reader: existing === undefined
+                ? "not configured"
+                : isCanonicalRemoteEntry(parseHermesEntry(existing))
+                    ? "remote"
+                    : "bridge",
+        },
+        after: {
+            format: "hermes-yaml",
+            other_settings: "preserved",
+            mcp_servers: { "omni-reader": entry },
+        },
         entry,
-        sourceFingerprint: configFingerprint(loaded),
+        sourceFingerprint: loaded.fingerprint,
         environment,
+        reload: reloadInstruction("hermes"),
+        format,
+        serializedAfter,
+        previousEntry,
     };
 }
 async function syncDirectory(directory) {
@@ -198,14 +761,27 @@ async function syncDirectory(directory) {
         await handle?.close();
     }
 }
+async function ensureConfigDirectory(directory) {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const details = await lstat(directory);
+    if (!details.isDirectory() || details.isSymbolicLink()) {
+        throw fileError("The Agent configuration directory is unsafe; no changes were written.");
+    }
+}
 async function atomicReplace(filePath, content) {
     const directory = path.dirname(filePath);
-    await mkdir(directory, { recursive: true, mode: 0o700 });
-    await chmod(directory, 0o700);
+    await ensureConfigDirectory(directory);
+    const existing = await pathDetails(filePath);
+    if (existing !== undefined && (existing.isSymbolicLink() || !existing.isFile())) {
+        throw fileError("The Agent configuration target is unsafe; no changes were written.");
+    }
     const temporaryPath = path.join(directory, `.${path.basename(filePath)}.${randomBytes(18).toString("base64url")}.tmp`);
     let handle;
     try {
-        handle = await open(temporaryPath, "wx", 0o600);
+        handle = await open(temporaryPath, fsConstants.O_WRONLY |
+            fsConstants.O_CREAT |
+            fsConstants.O_EXCL |
+            fsConstants.O_NOFOLLOW, 0o600);
         await handle.writeFile(content, "utf8");
         await handle.sync();
         await handle.close();
@@ -216,20 +792,28 @@ async function atomicReplace(filePath, content) {
     }
     finally {
         await handle?.close();
-        await import("node:fs/promises").then(({ unlink }) => unlink(temporaryPath).catch(() => undefined));
+        await unlink(temporaryPath).catch(() => undefined);
     }
 }
-async function withConfigLock(configPath, action) {
+async function withConfigLock(configPath, environment, action) {
     const directory = path.dirname(configPath);
-    await mkdir(directory, { recursive: true, mode: 0o700 });
-    await chmod(directory, 0o700);
+    await validateUserConfigPath(configPath, environment);
+    await ensureConfigDirectory(directory);
+    await validateUserConfigPath(configPath, environment);
     const lockPath = `${configPath}.omni-reader.lock`;
     let handle;
     try {
-        handle = await open(lockPath, "wx", 0o600);
+        handle = await open(lockPath, fsConstants.O_WRONLY |
+            fsConstants.O_CREAT |
+            fsConstants.O_EXCL |
+            fsConstants.O_NOFOLLOW, 0o600);
     }
     catch (error) {
         if (error.code === "EEXIST") {
+            const details = await pathDetails(lockPath);
+            if (details?.isSymbolicLink() === true || details !== undefined && !details.isFile()) {
+                throw fileError("The Agent configuration lock path is unsafe; no changes were written.");
+            }
             throw fileError("Another Omni setup is updating this Agent configuration; retry after it finishes.");
         }
         throw error;
@@ -237,76 +821,179 @@ async function withConfigLock(configPath, action) {
     try {
         await handle.writeFile(`${process.pid}\n`, "utf8");
         await handle.sync();
+        await validateUserConfigPath(configPath, environment, true);
         return await action();
     }
     finally {
         await handle.close();
-        await import("node:fs/promises").then(({ unlink }) => unlink(lockPath).catch(() => undefined));
+        await unlink(lockPath).catch(() => undefined);
         await syncDirectory(directory);
     }
 }
+function trustedBackup(prepared) {
+    return {
+        version: 1,
+        target: prepared.target,
+        source_fingerprint: prepared.sourceFingerprint,
+        bridge_entry_digest: entryDigest(prepared.entry),
+        previous_entry: prepared.previousEntry ?? null,
+    };
+}
+function parsePreviousEntry(value) {
+    if (value === null)
+        return null;
+    if (!isRecord(value))
+        return undefined;
+    if (value.format === "json" && "value" in value) {
+        return { format: "json", value: value.value };
+    }
+    if (value.format === "hermes-yaml" && typeof value.serialized === "string") {
+        return { format: "hermes-yaml", serialized: value.serialized };
+    }
+    return undefined;
+}
+function parseTrustedBackup(value) {
+    if (!isRecord(value))
+        return undefined;
+    const previous = parsePreviousEntry(value.previous_entry);
+    if (value.version !== 1 ||
+        !["hermes", "cursor", "claude-desktop"].includes(String(value.target)) ||
+        typeof value.source_fingerprint !== "string" ||
+        typeof value.bridge_entry_digest !== "string" ||
+        previous === undefined)
+        return undefined;
+    return {
+        version: 1,
+        target: value.target,
+        source_fingerprint: value.source_fingerprint,
+        bridge_entry_digest: value.bridge_entry_digest,
+        previous_entry: previous,
+    };
+}
+async function readTrustedBackup(configPath) {
+    const backupPath = agentBackupPath(configPath);
+    let handle;
+    try {
+        handle = await open(backupPath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw fileError("The trusted Omni backup is unsafe or unreadable.");
+    }
+    try {
+        const details = await handle.stat();
+        if (!details.isFile() ||
+            (process.platform !== "win32" && (details.mode & 0o077) !== 0)) {
+            throw fileError("The trusted Omni backup has unsafe permissions.");
+        }
+        const parsed = parseTrustedBackup(JSON.parse(await handle.readFile("utf8")));
+        if (parsed === undefined)
+            throw new Error("invalid backup");
+        return parsed;
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AgentConfigError")
+            throw error;
+        throw fileError("The trusted Omni backup is malformed.");
+    }
+    finally {
+        await handle.close();
+    }
+}
 export async function verifyPreparedAgentConfig(prepared) {
-    if (prepared.configPath === undefined
-        || prepared.environment === undefined
-        || prepared.sourceFingerprint === undefined)
+    if (prepared.configPath === undefined ||
+        prepared.environment === undefined ||
+        prepared.sourceFingerprint === undefined)
         return;
     await validateUserConfigPath(prepared.configPath, prepared.environment);
     const current = await readConfig(prepared.configPath);
-    if (configFingerprint(current) !== prepared.sourceFingerprint) {
+    if (current.fingerprint !== prepared.sourceFingerprint) {
         throw fileError("The Agent configuration changed after preview; no changes were written.");
     }
 }
 export async function writePreparedAgentConfig(prepared) {
-    if (prepared.configPath === undefined)
+    if (prepared.configPath === undefined ||
+        prepared.environment === undefined ||
+        prepared.sourceFingerprint === undefined ||
+        prepared.serializedAfter === undefined)
         return;
-    await withConfigLock(prepared.configPath, async () => {
-        await verifyPreparedAgentConfig(prepared);
+    await withConfigLock(prepared.configPath, prepared.environment, async () => {
         const current = await readConfig(prepared.configPath);
-        if (prepared.existed && current.serialized !== undefined) {
-            await atomicReplace(`${prepared.configPath}.bak`, current.serialized);
+        if (current.fingerprint !== prepared.sourceFingerprint) {
+            throw fileError("The Agent configuration changed after preview; no changes were written.");
+        }
+        const backup = trustedBackup(prepared);
+        const backupPath = agentBackupPath(prepared.configPath);
+        const existingBackup = await readTrustedBackup(prepared.configPath);
+        if (existingBackup === undefined) {
+            await atomicReplace(backupPath, `${JSON.stringify(backup, null, 2)}\n`);
+        }
+        else {
+            const currentEntryMatches = await configHasExpectedEntry(prepared.target, current);
+            if (currentEntryMatches && existingBackup.target === prepared.target) {
+                const updatedBackup = {
+                    ...existingBackup,
+                    bridge_entry_digest: entryDigest(prepared.entry),
+                };
+                if (JSON.stringify(updatedBackup) !== JSON.stringify(existingBackup)) {
+                    await atomicReplace(backupPath, `${JSON.stringify(updatedBackup, null, 2)}\n`);
+                }
+            }
+            else if (JSON.stringify(existingBackup) !== JSON.stringify(backup)) {
+                throw fileError("A conflicting trusted Omni backup already exists; no changes were written.");
+            }
         }
-        await atomicReplace(prepared.configPath, `${JSON.stringify(prepared.after, null, 2)}\n`);
+        const immediatelyBeforeWrite = await readConfig(prepared.configPath);
+        if (immediatelyBeforeWrite.fingerprint !== current.fingerprint) {
+            throw fileError("The Agent configuration changed during setup; no changes were written.");
+        }
+        await atomicReplace(prepared.configPath, prepared.serializedAfter);
     });
 }
-function isExpectedOmniEntry(value) {
-    if (!isRecord(value))
-        return false;
-    const keys = Object.keys(value).sort();
-    const args = value.args;
-    if (value.command !== "npx"
-        || !Array.isArray(args)
-        || args.length !== 2
-        || args[0] !== "-y"
-        || args[1] !== "@cueai/omni-reader-mcp")
-        return false;
-    if (value.env === undefined) {
-        return keys.length === 2 && keys[0] === "args" && keys[1] === "command";
+function jsonConfigEntry(value) {
+    if (!isRecord(value.mcpServers))
+        return undefined;
+    return onlyOmniEntry(value.mcpServers).value;
+}
+async function configHasExpectedEntry(target, loaded) {
+    if (target === "hermes") {
+        const document = parseHermesDocument(loaded.serialized);
+        const entry = hermesOmniEntry(document);
+        return entry !== undefined && isExpectedOmniEntry(target, parseHermesEntry(entry));
     }
-    if (!isRecord(value.env))
-        return false;
-    const envKeys = Object.keys(value.env);
-    return keys.length === 3
-        && keys[0] === "args"
-        && keys[1] === "command"
-        && keys[2] === "env"
-        && envKeys.length === 1
-        && envKeys[0] === "OMNI_ALLOWED_ROOTS"
-        && typeof value.env.OMNI_ALLOWED_ROOTS === "string"
-        && value.env.OMNI_ALLOWED_ROOTS.length > 0;
+    assertNoDuplicateJsonOmniEntries(loaded.serialized);
+    const value = parseJsonConfig(loaded);
+    return isExpectedOmniEntry(target, jsonConfigEntry(value));
 }
-export async function inspectAgentConfig(configPath, environment) {
+export async function inspectAgentConfig(configPath, environment, target) {
     try {
         if (environment !== undefined)
             await validateUserConfigPath(configPath, environment);
         const loaded = await readConfig(configPath);
         if (!loaded.existed)
             return "not configured";
-        if (!isRecord(loaded.value.mcpServers))
+        const resolvedTarget = target ?? (configPath.endsWith("config.yaml") ? "hermes" : "cursor");
+        if (resolvedTarget === "hermes") {
+            const document = parseHermesDocument(loaded.serialized);
+            const entry = hermesOmniEntry(document);
+            if (entry === undefined)
+                return "not configured";
+            const value = parseHermesEntry(entry);
+            if (isExpectedOmniEntry("hermes", value))
+                return "configured";
+            return isCanonicalRemoteEntry(value) ? "not configured" : "invalid or unreadable";
+        }
+        assertNoDuplicateJsonOmniEntries(loaded.serialized);
+        const value = parseJsonConfig(loaded);
+        if (!isRecord(value.mcpServers))
             return "not configured";
-        const entry = loaded.value.mcpServers["omni-reader"];
+        const entry = onlyOmniEntry(value.mcpServers).value;
         if (entry === undefined)
             return "not configured";
-        return isExpectedOmniEntry(entry) ? "configured" : "invalid or unreadable";
+        if (isExpectedOmniEntry(resolvedTarget, entry))
+            return "configured";
+        return isCanonicalRemoteEntry(entry) ? "not configured" : "invalid or unreadable";
     }
     catch {
         return "invalid or unreadable";
@@ -314,7 +1001,7 @@ export async function inspectAgentConfig(configPath, environment) {
 }
 export async function detectAgentTargets(environment) {
     const detected = [];
-    for (const target of ["cursor", "claude-desktop"]) {
+    for (const target of ["hermes", "cursor", "claude-desktop"]) {
         const configPath = agentConfigPath(target, environment);
         if (configPath === undefined)
             continue;
@@ -333,3 +1020,119 @@ export async function detectAgentTargets(environment) {
 export async function configContainsOmni(configPath) {
     return await inspectAgentConfig(configPath) === "configured";
 }
+export async function configuredAllowedRoots(target, environment) {
+    const configPath = agentConfigPath(target, environment);
+    if (configPath === undefined || target === "generic")
+        return [];
+    await validateUserConfigPath(configPath, environment);
+    const loaded = await readConfig(configPath);
+    if (!loaded.existed)
+        return [];
+    let entry;
+    if (target === "hermes") {
+        const hermesEntry = hermesOmniEntry(parseHermesDocument(loaded.serialized));
+        entry = hermesEntry === undefined ? undefined : parseHermesEntry(hermesEntry);
+    }
+    else {
+        assertNoDuplicateJsonOmniEntries(loaded.serialized);
+        entry = jsonConfigEntry(parseJsonConfig(loaded));
+    }
+    if (!isRecord(entry) || !isRecord(entry.env))
+        return [];
+    const roots = entry.env.OMNI_ALLOWED_ROOTS;
+    if (typeof roots !== "string" || roots.length === 0)
+        return [];
+    const separator = environment.platform === "win32" ? ";" : ":";
+    return roots.split(separator).filter((root) => root.length > 0);
+}
+export async function rollbackPreparedAgentConfig(prepared) {
+    if (prepared.configPath === undefined ||
+        prepared.environment === undefined ||
+        prepared.serializedBefore === undefined ||
+        prepared.serializedAfter === undefined)
+        return;
+    await withConfigLock(prepared.configPath, prepared.environment, async () => {
+        const current = await readConfig(prepared.configPath);
+        if (!current.existed || current.serialized !== prepared.serializedAfter) {
+            throw fileError("The Agent configuration changed before rollback; automatic rollback stopped.");
+        }
+        if (prepared.existed) {
+            await atomicReplace(prepared.configPath, prepared.serializedBefore);
+        }
+        else {
+            await unlink(prepared.configPath);
+            await syncDirectory(path.dirname(prepared.configPath));
+        }
+        await unlink(agentBackupPath(prepared.configPath)).catch((error) => {
+            if (error.code !== "ENOENT")
+                throw error;
+        });
+        await syncDirectory(path.dirname(prepared.configPath));
+    });
+}
+function restoreJsonEntry(serialized, previous) {
+    const loaded = { existed: true, serialized, fingerprint: "unused" };
+    const value = parseJsonConfig(loaded);
+    const servers = isRecord(value.mcpServers) ? { ...value.mcpServers } : {};
+    delete servers["omni-reader"];
+    if (previous?.format === "json")
+        servers["omni-reader"] = previous.value;
+    return `${JSON.stringify({ ...value, mcpServers: servers }, null, 2)}\n`;
+}
+function restoreHermesEntry(serialized, previous) {
+    const document = parseHermesDocument(serialized);
+    return removeHermesEntry(serialized, document, previous?.format === "hermes-yaml" ? previous.serialized : undefined);
+}
+function trustedRemotePrevious(previous) {
+    if (previous === null)
+        return null;
+    if (previous.format === "json") {
+        return isCanonicalRemoteEntry(previous.value) ? previous : null;
+    }
+    const document = parseHermesDocument(`mcp_servers:\n${previous.serialized}`);
+    const entry = hermesOmniEntry(document);
+    return entry !== undefined && isCanonicalRemoteEntry(parseHermesEntry(entry))
+        ? previous
+        : null;
+}
+export async function uninstallAgentConfig(target, environment) {
+    const configPath = agentConfigPath(target, environment);
+    if (configPath === undefined)
+        return undefined;
+    await validateUserConfigPath(configPath, environment);
+    const initial = await readConfig(configPath);
+    if (!initial.existed || !await configHasExpectedEntry(target, initial))
+        return undefined;
+    return await withConfigLock(configPath, environment, async () => {
+        const current = await readConfig(configPath);
+        if (!await configHasExpectedEntry(target, current)) {
+            throw fileError("The Agent configuration changed before uninstall; no changes were written.");
+        }
+        const currentEntry = target === "hermes"
+            ? parseHermesEntry(hermesOmniEntry(parseHermesDocument(current.serialized)))
+            : jsonConfigEntry(parseJsonConfig(current));
+        const backup = await readTrustedBackup(configPath);
+        const matchingBackup = backup !== undefined
+            && backup.target === target
+            && backup.bridge_entry_digest === entryDigest(currentEntry)
+            ? backup
+            : undefined;
+        const previous = matchingBackup === undefined
+            ? null
+            : trustedRemotePrevious(matchingBackup.previous_entry);
+        const serializedAfter = target === "hermes"
+            ? restoreHermesEntry(current.serialized, previous)
+            : restoreJsonEntry(current.serialized, previous);
+        const immediatelyBeforeWrite = await readConfig(configPath);
+        if (immediatelyBeforeWrite.fingerprint !== current.fingerprint) {
+            throw fileError("The Agent configuration changed during uninstall; no changes were written.");
+        }
+        await atomicReplace(configPath, serializedAfter);
+        await unlink(agentBackupPath(configPath)).catch((error) => {
+            if (error.code !== "ENOENT")
+                throw error;
+        });
+        await syncDirectory(path.dirname(configPath));
+        return { target, restoredRemote: previous !== null };
+    });
+}