@cueai/omni-reader-mcp 1.5.5 → 1.6.0

package/dist/cli/config-inspection.js

@@ -0,0 +1,307 @@
+import { constants } from "node:fs";
+import { lstat as nodeLstat, open as nodeOpen, } from "node:fs/promises";
+import path from "node:path";
+import { PathNormalizationError, normalizePlatformPath, } from "../path-normalization.js";
+const MAX_CONFIG_BYTES = 1_048_576;
+const EXACT_PACKAGE_SPEC = /^@cueai\/omni-reader-mcp@(\d+\.\d+\.\d+)$/u;
+const REFERENCE_VALUES = new Set([
+    "${CUE_API_KEY}",
+    "Bearer ${CUE_API_KEY}",
+]);
+const NODE_FILE_SYSTEM = {
+    lstat: (candidate) => nodeLstat(candidate, { bigint: true }),
+    open: (candidate, flags) => nodeOpen(candidate, flags),
+};
+export class ConfigInspectionError extends Error {
+    code;
+    constraints;
+    constructor(code, message, constraints) {
+        super(message);
+        this.name = "ConfigInspectionError";
+        this.code = code;
+        if (constraints !== undefined)
+            this.constraints = constraints;
+    }
+}
+function pathsFor(platform) {
+    return platform === "win32" ? path.win32 : path.posix;
+}
+function inspectionError(code, message, constraints) {
+    return new ConfigInspectionError(code, message, constraints);
+}
+function normalizedAbsolutePath(value, platform) {
+    if (value.length === 0 || value.includes("\0")) {
+        throw inspectionError("INVALID_CONFIG_PATH", "Provide one absolute JSON configuration path.");
+    }
+    let normalized;
+    try {
+        normalized = normalizePlatformPath(value, platform);
+    }
+    catch (error) {
+        if (error instanceof PathNormalizationError) {
+            throw inspectionError(error.code, error.message);
+        }
+        throw error;
+    }
+    const paths = pathsFor(platform);
+    if (!paths.isAbsolute(normalized)) {
+        throw inspectionError("INVALID_CONFIG_PATH", "Provide one absolute JSON configuration path.");
+    }
+    return paths.normalize(normalized);
+}
+function validateServerName(value) {
+    if (value.length === 0 || value.includes("\0")) {
+        throw inspectionError("INVALID_SERVER_NAME", "Provide one exact MCP server entry name.");
+    }
+}
+function requireSafeRegularFile(details) {
+    if (details.isSymbolicLink() || !details.isFile()) {
+        throw inspectionError("CONFIG_FILE_UNSAFE", "The selected configuration must be one regular file, not a symlink.");
+    }
+}
+function requireAllowedSize(details) {
+    if (details.size > BigInt(MAX_CONFIG_BYTES)) {
+        throw inspectionError("CONFIG_FILE_TOO_LARGE", "The selected configuration exceeds the 1 MiB inspection limit.", { max_bytes: MAX_CONFIG_BYTES });
+    }
+}
+async function readBoundedConfig(handle) {
+    const buffer = Buffer.allocUnsafe(MAX_CONFIG_BYTES + 1);
+    let total = 0;
+    while (total < buffer.byteLength) {
+        const remaining = buffer.byteLength - total;
+        const { bytesRead } = await handle.read(buffer, total, remaining, total);
+        if (bytesRead === 0)
+            break;
+        if (!Number.isInteger(bytesRead) || bytesRead < 0 || bytesRead > remaining) {
+            throw inspectionError("CONFIG_FILE_UNREADABLE", "The selected configuration file could not be inspected.");
+        }
+        total += bytesRead;
+    }
+    if (total > MAX_CONFIG_BYTES) {
+        throw inspectionError("CONFIG_FILE_TOO_LARGE", "The selected configuration exceeds the 1 MiB inspection limit.", { max_bytes: MAX_CONFIG_BYTES });
+    }
+    return buffer.subarray(0, total);
+}
+function requireSameFile(before, after) {
+    if (before.dev !== after.dev ||
+        before.ino !== after.ino ||
+        before.size !== after.size ||
+        before.mtimeNs !== after.mtimeNs ||
+        before.ctimeNs !== after.ctimeNs) {
+        throw inspectionError("CONFIG_FILE_CHANGED", "The selected configuration changed during inspection. Retry after changes stop.");
+    }
+}
+function fileAccessError(error) {
+    if (error instanceof ConfigInspectionError)
+        return error;
+    const code = error?.code;
+    if (code === "ENOENT" || code === "ENOTDIR") {
+        return inspectionError("CONFIG_FILE_NOT_FOUND", "The selected configuration file does not exist.");
+    }
+    if (code === "ELOOP") {
+        return inspectionError("CONFIG_FILE_UNSAFE", "The selected configuration must be one regular file, not a symlink.");
+    }
+    return inspectionError("CONFIG_FILE_UNREADABLE", "The selected configuration file could not be inspected.");
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function unknownInspection(status) {
+    return {
+        inspection_scope: "explicit_config",
+        entry: { status },
+        transport: { shape: "unknown" },
+        api_key: { status: "unknown" },
+        allowed_roots: { safety: "unknown" },
+    };
+}
+function commandBasename(command) {
+    const normalized = command.replaceAll("\\", "/");
+    const basename = normalized.slice(normalized.lastIndexOf("/") + 1).trim();
+    return basename.length === 0 ? undefined : basename;
+}
+function commandCategory(basename) {
+    const normalized = basename.toLowerCase().replace(/\.(?:cmd|exe)$/u, "");
+    if (["npx", "npm", "pnpm", "yarn", "bun"].includes(normalized)) {
+        return "package_runner";
+    }
+    if (["cmd", "powershell", "pwsh", "sh", "bash", "zsh"].includes(normalized)) {
+        return "shell";
+    }
+    if (["node", "deno", "python", "python3"].includes(normalized)) {
+        return "runtime";
+    }
+    return "executable";
+}
+function transportFacts(entry) {
+    const command = typeof entry.command === "string" && entry.command.length > 0
+        ? entry.command
+        : undefined;
+    const url = typeof entry.url === "string" && entry.url.length > 0
+        ? entry.url
+        : undefined;
+    if ((command === undefined) === (url === undefined)) {
+        return { shape: "unknown" };
+    }
+    if (url !== undefined)
+        return { shape: "remote_url" };
+    const basename = commandBasename(command);
+    return basename === undefined
+        ? { shape: "local_command" }
+        : {
+            shape: "local_command",
+            command: { basename, category: commandCategory(basename) },
+        };
+}
+function exactPackageVersion(entry) {
+    if (!Array.isArray(entry.args))
+        return undefined;
+    for (const argument of entry.args) {
+        if (typeof argument !== "string")
+            continue;
+        const match = EXACT_PACKAGE_SPEC.exec(argument);
+        if (match !== null)
+            return match[1];
+    }
+    return undefined;
+}
+function credentialCandidates(entry) {
+    const candidates = [];
+    let malformedContainer = false;
+    if (Object.hasOwn(entry, "env")) {
+        if (!isRecord(entry.env)) {
+            malformedContainer = true;
+        }
+        else {
+            for (const [key, value] of Object.entries(entry.env)) {
+                if (key.toUpperCase() === "CUE_API_KEY")
+                    candidates.push(value);
+            }
+        }
+    }
+    if (Object.hasOwn(entry, "headers")) {
+        if (!isRecord(entry.headers)) {
+            malformedContainer = true;
+        }
+        else {
+            for (const [key, value] of Object.entries(entry.headers)) {
+                if (key.toLowerCase() === "authorization")
+                    candidates.push(value);
+            }
+        }
+    }
+    return { candidates, malformedContainer };
+}
+function configuredApiKeyStatus(entry) {
+    const { candidates, malformedContainer } = credentialCandidates(entry);
+    if (candidates.length === 0)
+        return malformedContainer ? "unknown" : "absent";
+    let hasReference = false;
+    let hasUnknown = malformedContainer;
+    for (const candidate of candidates) {
+        if (typeof candidate !== "string" || candidate.length === 0) {
+            hasUnknown = true;
+            continue;
+        }
+        if (REFERENCE_VALUES.has(candidate)) {
+            hasReference = true;
+            continue;
+        }
+        if (/[$%{}]/u.test(candidate)) {
+            hasUnknown = true;
+            continue;
+        }
+        return "literal_present";
+    }
+    if (hasUnknown)
+        return "unknown";
+    return hasReference ? "reference_present" : "unknown";
+}
+function allowedRootFacts(entry, platform) {
+    if (!Object.hasOwn(entry, "env"))
+        return { count: 0, safety: "safe" };
+    if (!isRecord(entry.env))
+        return { safety: "unknown" };
+    const rootValue = entry.env.OMNI_ALLOWED_ROOTS;
+    if (rootValue === undefined)
+        return { count: 0, safety: "safe" };
+    if (typeof rootValue !== "string")
+        return { safety: "unknown" };
+    if (rootValue.length === 0)
+        return { count: 0, safety: "safe" };
+    const paths = pathsFor(platform);
+    const roots = rootValue
+        .split(paths.delimiter)
+        .filter((root) => root.length > 0);
+    if (roots.length === 0)
+        return { count: 0, safety: "safe" };
+    const safe = roots.every((root) => {
+        if (root.includes("\0"))
+            return false;
+        try {
+            return paths.isAbsolute(normalizePlatformPath(root, platform));
+        }
+        catch {
+            return false;
+        }
+    });
+    return { count: roots.length, safety: safe ? "safe" : "unsafe" };
+}
+function inspectParsedConfig(value, serverName, platform) {
+    if (!isRecord(value))
+        return unknownInspection("invalid");
+    if (!Object.hasOwn(value, "mcpServers"))
+        return unknownInspection("missing");
+    if (!isRecord(value.mcpServers))
+        return unknownInspection("invalid");
+    if (!Object.hasOwn(value.mcpServers, serverName))
+        return unknownInspection("missing");
+    const selected = value.mcpServers[serverName];
+    if (!isRecord(selected))
+        return unknownInspection("invalid");
+    const packageVersion = exactPackageVersion(selected);
+    return {
+        inspection_scope: "explicit_config",
+        entry: { status: "present" },
+        transport: transportFacts(selected),
+        ...(packageVersion === undefined ? {} : { package_version: packageVersion }),
+        api_key: { status: configuredApiKeyStatus(selected) },
+        allowed_roots: allowedRootFacts(selected, platform),
+    };
+}
+export async function inspectExplicitConfig(options) {
+    const platform = options.platform ?? process.platform;
+    validateServerName(options.serverName);
+    const configPath = normalizedAbsolutePath(options.configPath, platform);
+    const fileSystem = options.fileSystem ?? NODE_FILE_SYSTEM;
+    let handle;
+    try {
+        const before = await fileSystem.lstat(configPath);
+        requireSafeRegularFile(before);
+        requireAllowedSize(before);
+        handle = await fileSystem.open(configPath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        const opened = await handle.stat({ bigint: true });
+        requireSafeRegularFile(opened);
+        requireSameFile(before, opened);
+        requireAllowedSize(opened);
+        const serialized = await readBoundedConfig(handle);
+        const after = await handle.stat({ bigint: true });
+        requireSafeRegularFile(after);
+        requireSameFile(opened, after);
+        requireAllowedSize(after);
+        let parsed;
+        try {
+            parsed = JSON.parse(serialized.toString("utf8"));
+        }
+        catch {
+            return unknownInspection("invalid");
+        }
+        return inspectParsedConfig(parsed, options.serverName, platform);
+    }
+    catch (error) {
+        throw fileAccessError(error);
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}

package/dist/cli/doctor.d.ts

@@ -1,4 +1,5 @@
 import { type AgentConfigEnvironment } from "./agent-config.js";
+import { type ExplicitConfigInspection } from "./config-inspection.js";
 export type VersionCheck = {
     readonly status: "current";
     readonly installed: string;
@@ -29,8 +30,14 @@ export interface DoctorOptions extends AgentConfigEnvironment {
     readonly nodeVersion?: string;
     readonly npmVersion?: string;
     readonly packageVersion?: string;
+    readonly explicitConfig?: {
+        readonly configPath: string;
+        readonly serverName: string;
+    };
 }
 export interface DoctorReport {
+    readonly inspection_scope: "current_process_env";
+    readonly explicit_config?: ExplicitConfigInspection;
     readonly package_version: string;
     readonly version_check: VersionCheck;
     readonly node_version: string;

package/dist/cli/doctor.js

@@ -3,7 +3,9 @@ import { lstat, open, readdir } from "node:fs/promises";
 import path from "node:path";
 import { DEFAULT_CUBE_BASE_URL, MAX_FILE_BYTES, CUBE_GRANT_PROTOCOL_VERSION, } from "../constants.js";
 import { API_KEY_URL, getOnboardingPolicyWithTimeout, onboardingGuidance, } from "../onboarding-policy.js";
+import { normalizePlatformPath, PathNormalizationError, } from "../path-normalization.js";
 import { agentConfigPath, inspectAgentConfigDetails, } from "./agent-config.js";
+import { inspectExplicitConfig, } from "./config-inspection.js";
 const CUBE_HEALTH_PATH = "/api/omni-reader/direct-upload/v1/health";
 const NPM_LATEST_URL = "https://registry.npmjs.org/@cueai/omni-reader-mcp/latest";
 // Local-file parsing reaches the data plane only through the controlled origin
@@ -188,7 +190,16 @@ function allowedRootFacts(options) {
     const roots = value.split(separator).filter((root) => root.length > 0);
     return {
         count: roots.length,
-        safe: roots.length > 0 && roots.every((root) => paths.isAbsolute(root)),
+        safe: roots.length > 0 && roots.every((root) => {
+            try {
+                return paths.isAbsolute(normalizePlatformPath(root, options.platform));
+            }
+            catch (error) {
+                if (error instanceof PathNormalizationError)
+                    return false;
+                throw error;
+            }
+        }),
     };
 }
 async function clientAdapterFacts(options) {
@@ -207,7 +218,7 @@ async function clientAdapterFacts(options) {
 }
 export async function runDoctor(options) {
     const packageVersion = options.packageVersion ?? "unknown";
-    const [clientAdapters, artifacts, onboarding, latestPublishedVersion] = await Promise.all([
+    const [clientAdapters, artifacts, onboarding, latestPublishedVersion, explicitConfig,] = await Promise.all([
         clientAdapterFacts(options),
         artifactFacts(options.artifactRoot),
         getOnboardingPolicyWithTimeout(options.fetchImpl),
@@ -218,6 +229,12 @@ export async function runDoctor(options) {
         SEMVER_PATTERN.test(packageVersion)
             ? fetchLatestPublishedVersion(options.fetchImpl)
             : Promise.resolve(undefined),
+        options.explicitConfig === undefined
+            ? Promise.resolve(undefined)
+            : inspectExplicitConfig({
+                ...options.explicitConfig,
+                platform: options.platform,
+            }),
     ]);
     let urlControl = "skipped (Cue API Key absent)";
     if (options.env.CUE_API_KEY) {
@@ -235,6 +252,8 @@ export async function runDoctor(options) {
     // status stays "not probed" until the first real local-file parse validates it.
     const directUpload = RELAY_DATA_PLANE_STATUS;
     return {
+        inspection_scope: "current_process_env",
+        ...(explicitConfig === undefined ? {} : { explicit_config: explicitConfig }),
         package_version: packageVersion,
         version_check: SEMVER_PATTERN.test(packageVersion)
             ? versionCheckFacts(packageVersion, latestPublishedVersion)
@@ -278,6 +297,7 @@ function packageLine(versionCheck) {
 }
 export function renderDoctor(report) {
     const lines = [
+        `inspection_scope=${report.inspection_scope}`,
         `Node: ${report.node_version}`,
         `npm: ${report.npm_version}`,
         packageLine(report.version_check),
@@ -291,6 +311,21 @@ export function renderDoctor(report) {
     ]) {
         lines.push(`${label} config: ${report.client_adapters[key].status}`);
     }
+    if (report.explicit_config !== undefined) {
+        const explicit = report.explicit_config;
+        lines.push(`explicit_config.inspection_scope=${explicit.inspection_scope}`);
+        lines.push(`Explicit config entry: ${explicit.entry.status}`);
+        lines.push(`Explicit config transport: ${explicit.transport.shape}`);
+        if (explicit.transport.command !== undefined) {
+            lines.push(`Explicit config command: ${explicit.transport.command.category} `
+                + `(${explicit.transport.command.basename})`);
+        }
+        lines.push(`Explicit config package version: ${explicit.package_version ?? "unknown"}`);
+        lines.push(`Explicit config API key: ${explicit.api_key.status}`);
+        lines.push(`Explicit config allowed roots: ${"count" in explicit.allowed_roots
+            ? explicit.allowed_roots.count
+            : "unknown"} (${explicit.allowed_roots.safety})`);
+    }
     lines.push(`Omni control protocol: ${report.endpoints.url_control}`);
     if (report.endpoints.url_control === "unavailable or incompatible") {
         lines.push("  WARNING: URL parsing will fail until this is reachable.");

package/dist/cli/setup.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { BRIDGE_RELEASE_VERSION } from "../constants.js";
+import { PathNormalizationError, normalizePlatformPath, } from "../path-normalization.js";
 import { getOnboardingPolicyWithTimeout, onboardingGuidance, } from "../onboarding-policy.js";
 import { CliUsageError } from "./arguments.js";
 import { configuredAllowedRoots, detectAgentTargets, parseAgentTarget, prepareAgentConfig, rollbackPreparedAgentConfig, verifyPreparedAgentConfig, writePreparedAgentConfig, } from "./agent-config.js";
@@ -16,10 +17,20 @@ function parseExtraRoots(input, environment) {
             : value.startsWith(`~${paths.sep}`)
                 ? paths.join(environment.homeDirectory, value.slice(2))
                 : value;
-        if (!paths.isAbsolute(expanded)) {
+        let normalizedInput;
+        try {
+            normalizedInput = normalizePlatformPath(expanded, environment.platform);
+        }
+        catch (error) {
+            if (error instanceof PathNormalizationError) {
+                throw new CliUsageError(error.message);
+            }
+            throw error;
+        }
+        if (!paths.isAbsolute(normalizedInput)) {
             throw new CliUsageError("Every additional allowed root must be an absolute path.");
         }
-        return paths.normalize(expanded);
+        return paths.normalize(normalizedInput);
     });
 }
 async function interactiveArguments(options) {

package/dist/constants.d.ts

@@ -6,7 +6,7 @@ export declare const CUBE_GRANT_PROTOCOL_VERSION = "omni.parse_grant.v1";
 export declare const GRANTED_STREAM_PROTOCOL_VERSION = "omni.granted_parse_stream.v1";
 export declare const DEFAULT_CUBE_BASE_URL = "https://mcp.cuecue.cn";
 export declare const DEFAULT_IIIS_GRANTED_BASE_URL = "https://omni-upload.cuecue.cn/omni/granted/";
-export declare const BRIDGE_RELEASE_VERSION = "1.5.5";
+export declare const BRIDGE_RELEASE_VERSION = "1.6.0";
 export declare const REMOTE_OMNI_MCP_URL = "https://mcp.cuecue.cn/api/omni-reader/mcp/";
 export declare const FOREGROUND_BUDGET_MS = 15000;
 export declare const STATUS_LONG_POLL_MAX_MS = 20000;
@@ -14,6 +14,7 @@ export declare const STATUS_POLL_AFTER_SECONDS = 5;
 export declare const DELIVERY_TTL_SECONDS = 600;
 export declare const CUBE_CAPABILITIES_PATH = "/api/omni-reader/capabilities/v1";
 export declare const REMOTE_CAPABILITIES_CUSTOM_FIELD = "cue.omni-reader";
+export declare const SERVER_NEGOTIATED_BRIDGE_PROTOCOL_VERSION = "omni.local_bridge_tools.v3";
 export declare const CAPABILITIES_PROTOCOL_VERSION = "omni.reader_capabilities.v1";
 export declare const CAPABILITIES_ENABLED_ENV = "OMNI_CAPABILITIES_ENABLED";
 export declare const CAPABILITIES_TTL_SECONDS_ENV = "OMNI_CAPABILITIES_TTL_SECONDS";

package/dist/constants.js

@@ -6,7 +6,7 @@ export const CUBE_GRANT_PROTOCOL_VERSION = "omni.parse_grant.v1";
 export const GRANTED_STREAM_PROTOCOL_VERSION = "omni.granted_parse_stream.v1";
 export const DEFAULT_CUBE_BASE_URL = "https://mcp.cuecue.cn";
 export const DEFAULT_IIIS_GRANTED_BASE_URL = "https://omni-upload.cuecue.cn/omni/granted/";
-export const BRIDGE_RELEASE_VERSION = "1.5.5";
+export const BRIDGE_RELEASE_VERSION = "1.6.0";
 export const REMOTE_OMNI_MCP_URL = "https://mcp.cuecue.cn/api/omni-reader/mcp/";
 export const FOREGROUND_BUDGET_MS = 15_000;
 export const STATUS_LONG_POLL_MAX_MS = 20_000;
@@ -14,6 +14,7 @@ export const STATUS_POLL_AFTER_SECONDS = 5;
 export const DELIVERY_TTL_SECONDS = 600;
 export const CUBE_CAPABILITIES_PATH = "/api/omni-reader/capabilities/v1";
 export const REMOTE_CAPABILITIES_CUSTOM_FIELD = "cue.omni-reader";
+export const SERVER_NEGOTIATED_BRIDGE_PROTOCOL_VERSION = "omni.local_bridge_tools.v3";
 // ── omni.reader_capabilities.v1 advertisement (D2-D item 4) ────────────────────────────────
 // The direct profile's 14 exact literal fields mirror the pinned cube-mcp accepted set
 // (contracts/cube-mcp/omni-capabilities/v1); the URL profile's 9 fields belong to the
@@ -33,7 +34,7 @@ export const DIRECT_GROUNDING_PROFILE = {
     settlement_journal_protocol: "omni.direct_settlement_journal.v2",
     usage_protocol: "omni_parse_usage.v2",
     billing_protocol: "omni_billing.v2",
-    bridge_protocol: "omni.local_bridge_tools.v3",
+    bridge_protocol: SERVER_NEGOTIATED_BRIDGE_PROTOCOL_VERSION,
     bundle_protocol: "omni.result_bundle.v1",
     grounding_schema: "omni.grounding.v1",
     details: ["grounded", "layout"],
@@ -44,7 +45,7 @@ export const URL_GROUNDING_PROFILE = {
     operation_protocol: "omni.url_operation.v3",
     usage_protocol: "omni_parse_usage.v2",
     billing_protocol: "omni_billing.v2",
-    bridge_protocol: "omni.local_bridge_tools.v3",
+    bridge_protocol: SERVER_NEGOTIATED_BRIDGE_PROTOCOL_VERSION,
     bundle_protocol: "omni.result_bundle.v1",
     grounding_schema: "omni.grounding.v1",
     details: ["grounded", "layout"],

package/dist/cursor.d.ts

@@ -16,6 +16,10 @@ export interface BundleCursorPayload {
 export interface CursorCodecOptions {
     readonly now?: () => Date;
 }
+export declare class CursorCodecError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
 export declare class CursorCodec {
     #private;
     constructor(key: Uint8Array, options?: CursorCodecOptions);

package/dist/cursor.js

@@ -1,20 +1,18 @@
 import { createHmac, timingSafeEqual } from "node:crypto";
-import { OmniBridgeError } from "./errors.js";
 import { BUNDLE_CURSOR_VERSION, GROUNDING_SCHEMA_VERSION, RESULT_BUNDLE_PROTOCOL_VERSION, } from "./protocol.js";
 const CURSOR_VERSION = 1;
 const BASE64URL_PATTERN = /^[A-Za-z0-9_-]+$/;
 const RESULT_ID_PATTERN = /^result_[A-Za-z0-9_-]{16,64}$/;
+export class CursorCodecError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "CursorCodecError";
+        this.code = code;
+    }
+}
 function cursorError(code, message) {
-    return new OmniBridgeError({
-        code,
-        message,
-        operationCreated: true,
-        fileUploaded: true,
-        parserStarted: true,
-        billed: true,
-        contentReleased: true,
-        retryable: false,
-    });
+    return new CursorCodecError(code, message);
 }
 function decodeBase64Url(value) {
     if (!BASE64URL_PATTERN.test(value)) {
@@ -55,7 +53,7 @@ export class CursorCodec {
             value = JSON.parse(decodeBase64Url(encoded).toString("utf8"));
         }
         catch (error) {
-            if (error instanceof OmniBridgeError)
+            if (error instanceof CursorCodecError)
                 throw error;
             throw cursorError("INVALID_RESULT_CURSOR", "The result cursor is invalid.");
         }
@@ -107,7 +105,7 @@ export class CursorCodec {
             value = JSON.parse(decodeBase64Url(encoded).toString("utf8"));
         }
         catch (error) {
-            if (error instanceof OmniBridgeError)
+            if (error instanceof CursorCodecError)
                 throw error;
             throw cursorError("INVALID_RESULT_CURSOR", "The result cursor is invalid.");
         }

package/dist/index.js

@@ -26,6 +26,7 @@ function helpText() {
         "No arguments start the stdio MCP server.",
         "setup   Configure a supported user-scope Agent",
         "doctor  Check local configuration and protocol health",
+        "        [--json] [--config-path <absolute-json-path> --server-name <entry>]",
         "clean   Delete Bridge-created local artifacts and expired records",
         "uninstall Restore a trusted URL-only Agent entry without deleting artifacts",
         "",
@@ -99,7 +100,7 @@ export async function startStdioServer(options = {}) {
         fetchImpl: options.fetchImpl,
         operationBaseUrl: options.iiisOperationBaseUrl,
     });
-    const extraRoots = splitAllowedRoots(env.OMNI_ALLOWED_ROOTS);
+    const extraRoots = splitAllowedRoots(env.OMNI_ALLOWED_ROOTS, platform);
     const remoteClient = new HttpRemoteOmniClient({
         apiKey: env.CUE_API_KEY,
         fetchImpl: options.fetchImpl,
@@ -200,6 +201,14 @@ export async function runCli(args, options = {}) {
                 fetchImpl,
                 npmVersion: options.npmVersion ?? await installedNpmVersion(env),
                 packageVersion,
+                ...(parsed.configPath === undefined
+                    ? {}
+                    : {
+                        explicitConfig: {
+                            configPath: parsed.configPath,
+                            serverName: parsed.serverName,
+                        },
+                    }),
             });
             write(parsed.json
                 ? `${JSON.stringify(report)}\n`

package/dist/operation-journal.d.ts

@@ -3,6 +3,7 @@ export type JournalState = "CREATED" | "GRANT_PENDING" | "GRANT_ISSUED" | "UPLOA
 export type JournalProgressUnit = "page" | "sheet" | "slide" | "frame" | "segment";
 export type JournalCleanupState = "not_created" | "in_use" | "pending" | "deleted";
 export type JournalDeliveryState = "not_created" | "pending" | "deleted_after_ack";
+export type JournalResultDelivery = "auto" | "artifact";
 export interface JournalProgress {
     readonly unit: JournalProgressUnit;
     readonly completed: number;
@@ -22,6 +23,7 @@ export interface JournalRecord {
     readonly detail: JournalDetail;
     readonly groundingSchemaVersion: JournalGroundingSchemaVersion;
     readonly bundleProtocolVersion: JournalBundleProtocolVersion;
+    readonly resultDeliveryEffective: JournalResultDelivery;
     readonly operationId: string | null;
     readonly operationToken: string | null;
     readonly uploadUrl: string | null;
@@ -85,9 +87,10 @@ export declare class OperationJournal {
     constructor(options?: OperationJournalOptions);
     requestIdentityHmac(canonicalIdentityJson: string): Promise<string>;
     sourceLocatorHmac(sourceLocator: string): Promise<string>;
-    beginIntent(clientRequestId: string, canonicalIdentityJson: string, sourceKind?: JournalSourceKind, sourceLocator?: string | null, representation?: RepresentationIntent): Promise<JournalRecord>;
+    beginIntent(clientRequestId: string, canonicalIdentityJson: string, sourceKind?: JournalSourceKind, sourceLocator?: string | null, representation?: RepresentationIntent, resultDelivery?: JournalResultDelivery): Promise<JournalRecord>;
     migrateLegacyRecord(clientRequestId: string, canonicalIdentityJson: string, sourceLocator?: string | null): Promise<JournalRecord | null>;
     transition(clientRequestId: string, expectedState: JournalState, nextState: JournalState, patch: JournalPatch): Promise<JournalRecord>;
+    strengthenResultDelivery(clientRequestId: string, requested: JournalResultDelivery): Promise<JournalRecord>;
     loadByRequestId(clientRequestId: string): Promise<JournalRecord | null>;
     loadByOperationId(operationId: string): Promise<JournalRecord | null>;
     loadLatestByRequestIdentityHmac(requestIdentityHmac: string): Promise<JournalRecord | null>;