@cueai/omni-reader-mcp 1.3.3 → 1.4.1

package/README.md

@@ -64,7 +64,7 @@ differ from the numbers above, report the live values.
 Always use an audited exact version, never an implicit `latest`:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.3.3 setup
+npx -y @cueai/omni-reader-mcp@1.4.1 setup
 ```
 
 The interactive setup supports Hermes, Cursor, Claude Desktop, and generic stdio
@@ -72,9 +72,9 @@ configuration. Non-interactive installation uses the same argument parsing and w
 logic:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.3.3 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
-npx -y @cueai/omni-reader-mcp@1.3.3 setup --client cursor --add-root /absolute/minimum/root --yes --json
-npx -y @cueai/omni-reader-mcp@1.3.3 setup --client claude-desktop --allowed-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.4.1 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.4.1 setup --client cursor --add-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.4.1 setup --client claude-desktop --allowed-root /absolute/minimum/root --yes --json
 ```
 
 When an agent or script runs under a pty (stdin is still a TTY), declare non-interactive
@@ -82,7 +82,7 @@ mode explicitly with `--headless` (alias `--non-interactive`): no `--yes` is req
 stdin is never read:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.3.3 setup --client cursor --allowed-root /absolute/minimum/root --headless --json
+npx -y @cueai/omni-reader-mcp@1.4.1 setup --client cursor --allowed-root /absolute/minimum/root --headless --json
 ```
 
 ## Cache and journal isolation
@@ -133,6 +133,7 @@ The public tools are fixed:
 - `read_result`
 - `read_outline`
 - `discard_result`
+- `save_result`
 
 Every tool returns `structuredContent` with a strict `outputSchema`, plus an equivalent
 fallback for clients that only read legacy MCP `content[].text`:
@@ -150,7 +151,11 @@ fallback for clients that only read legacy MCP `content[].text`:
   advancing sequentially through `next_cursor`. An empty or absent outline is reported
   explicitly, never silently — it never blocks reading the result itself with `read_result`;
 - the `discard_result` text JSON explicitly returns `discarded`; never claim deletion on
-  call success alone.
+  call success alone;
+- the `save_result` text JSON contains the written file `path` and `bytes` count; there is
+  no path argument — the file is always named from `result_id` inside the Bridge cache's
+  export directory, so it cannot be pointed at an arbitrary location; calling it again for
+  the same result overwrites the same file.
 
 This gives clients that do not render `structuredContent` the operation/result handles
 and the full body without changing the contract for structured-capable clients.
@@ -188,7 +193,11 @@ Both URL and local files use mandatory no-store semantics and enter the
   **24 hours**; this is a different class of data from the remote 10-minute delivery
   window;
 - `read_result` reads local results in chunks; `discard_result` deletes a specific result
-  immediately; `clean` removes Bridge-created local artifacts and expired records.
+  immediately; `clean` removes Bridge-created local artifacts and expired records;
+- `save_result` writes a result's complete content to a stable file under the Bridge cache's
+  export directory and returns its path; exports are independent of the 24-hour cache sweep,
+  so discarding the cached artifact or letting retention expire does not remove an export the
+  user asked to keep.
 
 Status queries, result reads, and discards never create a new parse or usage event.
 `cancel_parse` reports only the real settlement state confirmed by the server and never
@@ -212,16 +221,16 @@ satisfies the constraints.
 ## Commands
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.3.3 doctor
-npx -y @cueai/omni-reader-mcp@1.3.3 doctor --json
-npx -y @cueai/omni-reader-mcp@1.3.3 clean
-npx -y @cueai/omni-reader-mcp@1.3.3 uninstall --yes --json
+npx -y @cueai/omni-reader-mcp@1.4.1 doctor
+npx -y @cueai/omni-reader-mcp@1.4.1 doctor --json
+npx -y @cueai/omni-reader-mcp@1.4.1 clean
+npx -y @cueai/omni-reader-mcp@1.4.1 uninstall --yes --json
 ```
 
 Running the pinned version without a command starts the stdio MCP server:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.3.3
+npx -y @cueai/omni-reader-mcp@1.4.1
 ```
 
 `doctor --json` returns package/npm/client adapter, Key present/absent, allowed-root
@@ -230,12 +239,12 @@ status; it never prints the Key, private source paths, or content.
 
 ## Uninstall and rollback
 
-`uninstall --yes --json` removes only a trusted 1.3.2 or 1.3.3 Bridge entry; when a
+`uninstall --yes --json` removes only a trusted 1.4.0 or 1.4.1 Bridge entry; when a
 matching trusted backup exists, it restores the original URL-only `omni-reader` entry.
 Uninstall never deletes user source files and never silently removes unexpired local
 results.
 
-To roll back from 1.3.3:
+To roll back from 1.4.1:
 
 1. stop recommending or installing that version;
 2. run `uninstall --yes --json` to restore the trusted URL-only entry;

package/dist/artifact-store.d.ts

@@ -112,6 +112,10 @@ export declare class ArtifactStore {
     read(resultId: string, cursor?: string, maxBytes?: number): Promise<ArtifactReadResult>;
     readOutline(resultId: string): Promise<OutlineResult>;
     mintOutlineCursor(resultId: string, byteOffset: number): Promise<string>;
+    exportResult(resultId: string): Promise<{
+        path: string;
+        bytes: number;
+    }>;
     readBundlePart(resultId: string, cursor: string, maxBytes?: number): Promise<BundlePartReadChunk>;
     discard(resultId: string): Promise<boolean>;
     cleanupExpired(): Promise<number>;

package/dist/artifact-store.js

@@ -1,6 +1,6 @@
 import { createHash, randomBytes } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
-import { chmod, link, lstat, mkdir, open, readdir, realpath, rename, rmdir, unlink, } from "node:fs/promises";
+import { chmod, link, lstat, mkdir, open, readdir, realpath, rename, rmdir, unlink, writeFile, } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { z } from "zod";
@@ -571,6 +571,85 @@ export class ArtifactStore {
         }
         return this.#cursor.encode({ resultId, offset: byteOffset, expiresAt: metadata.expiresAt });
     }
+    // The full content text in one read, regardless of storage shape (a flat
+    // v1 artifact, or a v2 bundle's "content" part). save_result's only
+    // consumer: read_result's chunked/cursor contract stays the single way an
+    // MCP caller streams a result; this exists purely to materialize the same
+    // bytes onto disk in one pass instead of looping next_cursor internally.
+    async #readFullText(resultId) {
+        this.#requireOpen();
+        let metadata;
+        try {
+            metadata = await this.#loadMetadata(resultId);
+        }
+        catch (error) {
+            if (error instanceof OmniBridgeError
+                && error.code === "RESULT_NOT_FOUND"
+                && await this.#hasBundleDirectory(resultId)) {
+                return this.#readFullBundleContent(resultId);
+            }
+            throw error;
+        }
+        if (Date.parse(metadata.expiresAt) <= this.#now().getTime()) {
+            await this.discard(resultId);
+            throw artifactError("RESULT_EXPIRED", "The local result artifact has expired.");
+        }
+        const artifactPath = path.join(this.#resultsDirectory, metadata.artifactName);
+        const handle = await openArtifactForRead(artifactPath);
+        try {
+            const artifactStat = await handle.stat();
+            if (!artifactStat.isFile() || artifactStat.size !== metadata.resultBytes) {
+                throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The local result artifact is invalid.");
+            }
+            const slice = await readUtf8Slice(handle, 0, metadata.resultBytes, metadata.resultBytes);
+            return { text: slice.text, resultBytes: metadata.resultBytes, expiresAt: metadata.expiresAt };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async #readFullBundleContent(resultId) {
+        const manifest = await this.#loadBundleManifest(resultId);
+        if (Date.parse(manifest.expires_at) <= this.#now().getTime()) {
+            await this.discard(resultId);
+            throw artifactError("RESULT_EXPIRED", "The local result artifact has expired.");
+        }
+        const part = manifest.parts.content;
+        if (part === undefined) {
+            throw artifactError("RESULT_NOT_FOUND", "The requested local result was not found.");
+        }
+        const source = part.storage.kind === "inline"
+            ? Buffer.from(part.storage.text, "utf8")
+            : await readPrivateFile(path.join(this.#resultsDirectory, resultId, "content.data"), "LOCAL_RESULT_INTEGRITY_FAILED", "The local bundle part is missing.");
+        if (source.length !== part.result_bytes) {
+            throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The local bundle part is invalid.");
+        }
+        const computedDigest = `sha256:${createHash("sha256").update(source).digest("hex")}`;
+        if (computedDigest !== part.digest) {
+            throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The local bundle part is invalid.");
+        }
+        return { text: source.toString("utf8"), resultBytes: part.result_bytes, expiresAt: manifest.expires_at };
+    }
+    // Materializes a result's complete content onto a stable, predictable
+    // path -- no caller-supplied destination, deliberately: result_id is
+    // already validated against RESULT_ID_PATTERN, so using it verbatim as the
+    // export filename carries no path-traversal or injection surface, unlike a
+    // free-form path argument would. Overwrites on repeat calls (idempotent,
+    // not an error) so re-exporting after a result changes never leaves a
+    // stale file silently in place.
+    async exportResult(resultId) {
+        this.#requireOpen();
+        if (!RESULT_ID_PATTERN.test(resultId)) {
+            throw artifactError("RESULT_NOT_FOUND", "The requested local result was not found.");
+        }
+        const { text } = await this.#readFullText(resultId);
+        const exportsDirectory = path.join(this.#rootDirectory, "exports");
+        await mkdir(exportsDirectory, { recursive: true, mode: 0o700 });
+        const exportPath = path.join(exportsDirectory, `${resultId}.md`);
+        const bytes = Buffer.from(text, "utf8");
+        await writeFile(exportPath, bytes, { mode: 0o600 });
+        return { path: exportPath, bytes: bytes.byteLength };
+    }
     // Read one UTF-8-safe chunk of one named part of a retained bundle. The
     // opaque v2 cursor binds resultId/part/detail/schema/bundle protocol/
     // offset/expiry; every bound field is re-verified against the closed

package/dist/cli/agent-config.js

@@ -4,7 +4,11 @@ import { chmod, lstat, mkdir, open, realpath, rename, unlink, } from "node:fs/pr
 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 PREVIOUS_PACKAGE_SPEC = "@cueai/omni-reader-mcp@1.3.2";
+// The release that the current version is a trusted upgrade from: uninstall and
+// rollback recognize exactly {previous, current} and nothing else. Bump this to
+// the version we just published when BRIDGE_RELEASE_VERSION advances.
+const PREVIOUS_RELEASE_VERSION = "1.4.0";
+const PREVIOUS_PACKAGE_SPEC = `@cueai/omni-reader-mcp@${PREVIOUS_RELEASE_VERSION}`;
 const LEGACY_PACKAGE_SPEC = "@cueai/omni-reader-mcp";
 const TRUSTED_EXACT_PACKAGE_SPECS = new Set([PREVIOUS_PACKAGE_SPEC, PACKAGE_SPEC]);
 function isRecord(value) {
@@ -586,7 +590,7 @@ function expectedBridgeVersion(target, value) {
     if (!isExpectedOmniEntry(target, value))
         return undefined;
     const packageSpec = value.args[1];
-    return packageSpec === PREVIOUS_PACKAGE_SPEC ? "1.3.2" : BRIDGE_RELEASE_VERSION;
+    return packageSpec === PREVIOUS_PACKAGE_SPEC ? PREVIOUS_RELEASE_VERSION : BRIDGE_RELEASE_VERSION;
 }
 function isLegacyBridgeEntry(target, value) {
     if (!isRecord(value) || value.command !== "npx")
@@ -614,36 +618,38 @@ function isCanonicalRemoteEntry(value) {
         && value.args === undefined
         && safeCredentialReferences(value);
 }
-function onlyOmniEntry(servers) {
+function onlyOmniEntry(servers, displayPath) {
     const keys = Object.keys(servers).filter(normalizedOmniName);
     if (keys.length > 1) {
-        throw fileError("The Agent configuration contains duplicate Omni entries; no changes were written.");
+        throw fileError(`${displayPath} 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.");
+        throw fileError(`${displayPath} contains a conflicting Omni entry named ${JSON.stringify(key)}; no changes were written.`);
     }
     return key === undefined ? {} : { key, value: servers[key] };
 }
-function hermesOmniEntry(document) {
+function hermesOmniEntry(document, displayPath) {
     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.");
+        throw fileError(`${displayPath} 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.");
+        throw fileError(`${displayPath} contains a conflicting Omni entry named ${JSON.stringify(entry.name)}; no changes were written.`);
     }
     return entry;
 }
-function previousJsonEntry(value) {
+function previousJsonEntry(value, displayPath) {
     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.");
+    throw fileError(`The existing "omni-reader" entry in ${displayPath} is not a trusted remote or Bridge `
+        + "configuration; no changes were written. Remove that entry manually, or restore a backup, "
+        + "then run setup again.");
 }
 function hermesCredentialsAreReferences(serialized) {
     for (const line of sourceLines(serialized)) {
@@ -657,19 +663,23 @@ function hermesCredentialsAreReferences(serialized) {
     }
     return true;
 }
-function previousHermesEntry(entry) {
+function previousHermesEntry(entry, displayPath) {
     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.");
+            throw fileError(`The "omni-reader" entry in ${displayPath} contains a literal credential; no changes `
+                + "were written. Replace the value with a ${CUE_API_KEY} reference, or remove the "
+                + "entry, then run setup again.");
         }
         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.");
+    throw fileError(`The existing "omni-reader" entry in ${displayPath} is not a trusted remote or Bridge `
+        + "configuration; no changes were written. Remove that entry manually, or restore a backup, "
+        + "then run setup again.");
 }
 export async function prepareAgentConfig(target, extraRoots, environment) {
     const entry = buildAgentEntry(target, extraRoots, environment.platform);
@@ -690,16 +700,17 @@ export async function prepareAgentConfig(target, extraRoots, environment) {
     const loaded = await readConfig(configPath);
     assertNoLiteralApiKey(loaded.serialized, environment);
     const format = configFormat(nativeTarget);
+    const displayPath = displayConfigPath(configPath, environment);
     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.");
+            throw fileError(`The existing mcpServers setting in ${displayPath} is not an object; no changes were written.`);
         }
         const servers = existingServers ?? {};
-        const existing = onlyOmniEntry(servers);
-        const previousEntry = previousJsonEntry(existing.value);
+        const existing = onlyOmniEntry(servers, displayPath);
+        const previousEntry = previousJsonEntry(existing.value, displayPath);
         const afterValue = {
             ...value,
             mcpServers: {
@@ -710,7 +721,7 @@ export async function prepareAgentConfig(target, extraRoots, environment) {
         return {
             target: nativeTarget,
             configPath,
-            displayPath: displayConfigPath(configPath, environment),
+            displayPath,
             existed: loaded.existed,
             before: redactSecrets(value),
             after: redactSecrets(afterValue),
@@ -725,13 +736,13 @@ export async function prepareAgentConfig(target, extraRoots, environment) {
         };
     }
     const document = parseHermesDocument(loaded.serialized);
-    const existing = hermesOmniEntry(document);
-    const previousEntry = previousHermesEntry(existing);
+    const existing = hermesOmniEntry(document, displayPath);
+    const previousEntry = previousHermesEntry(existing, displayPath);
     const serializedAfter = replaceHermesEntry(loaded.serialized, document, yamlEntry(entry, document.newline));
     return {
         target: "hermes",
         configPath,
-        displayPath: displayConfigPath(configPath, environment),
+        displayPath,
         existed: loaded.existed,
         before: {
             format: "hermes-yaml",
@@ -998,12 +1009,12 @@ export async function writePreparedAgentConfig(prepared) {
 function jsonConfigEntry(value) {
     if (!isRecord(value.mcpServers))
         return undefined;
-    return onlyOmniEntry(value.mcpServers).value;
+    return onlyOmniEntry(value.mcpServers, "the Agent configuration").value;
 }
 function expectedConfigEntry(target, loaded) {
     if (target === "hermes") {
         const document = parseHermesDocument(loaded.serialized);
-        const entry = hermesOmniEntry(document);
+        const entry = hermesOmniEntry(document, "the Hermes configuration");
         if (entry === undefined)
             return undefined;
         const value = parseHermesEntry(entry);
@@ -1026,7 +1037,7 @@ export async function inspectAgentConfigDetails(configPath, environment, target)
         const resolvedTarget = target ?? (configPath.endsWith("config.yaml") ? "hermes" : "cursor");
         if (resolvedTarget === "hermes") {
             const document = parseHermesDocument(loaded.serialized);
-            const entry = hermesOmniEntry(document);
+            const entry = hermesOmniEntry(document, configPath);
             if (entry === undefined)
                 return { status: "not configured" };
             const value = parseHermesEntry(entry);
@@ -1041,7 +1052,7 @@ export async function inspectAgentConfigDetails(configPath, environment, target)
         const value = parseJsonConfig(loaded);
         if (!isRecord(value.mcpServers))
             return { status: "not configured" };
-        const entry = onlyOmniEntry(value.mcpServers).value;
+        const entry = onlyOmniEntry(value.mcpServers, configPath).value;
         if (entry === undefined)
             return { status: "not configured" };
         const version = expectedBridgeVersion(resolvedTarget, entry);
@@ -1089,7 +1100,7 @@ export async function configuredAllowedRoots(target, environment) {
         return [];
     let entry;
     if (target === "hermes") {
-        const hermesEntry = hermesOmniEntry(parseHermesDocument(loaded.serialized));
+        const hermesEntry = hermesOmniEntry(parseHermesDocument(loaded.serialized), configPath);
         entry = hermesEntry === undefined ? undefined : parseHermesEntry(hermesEntry);
     }
     else {
@@ -1170,7 +1181,7 @@ function trustedRemotePrevious(previous) {
         return isCanonicalRemoteEntry(previous.value) ? previous : null;
     }
     const document = parseHermesDocument(`mcp_servers:\n${previous.serialized}`);
-    const entry = hermesOmniEntry(document);
+    const entry = hermesOmniEntry(document, "the Hermes configuration");
     return entry !== undefined && isCanonicalRemoteEntry(parseHermesEntry(entry))
         ? previous
         : null;
@@ -1189,7 +1200,7 @@ export async function uninstallAgentConfig(target, environment) {
             throw fileError("The Agent configuration changed before uninstall; no changes were written.");
         }
         const currentEntry = target === "hermes"
-            ? parseHermesEntry(hermesOmniEntry(parseHermesDocument(current.serialized)))
+            ? parseHermesEntry(hermesOmniEntry(parseHermesDocument(current.serialized), configPath))
             : jsonConfigEntry(parseJsonConfig(current));
         const backup = await readTrustedBackup(configPath);
         const matchingBackup = backup !== undefined

package/dist/cli/doctor.d.ts

@@ -1,4 +1,22 @@
 import { type AgentConfigEnvironment } from "./agent-config.js";
+export type VersionCheck = {
+    readonly status: "current";
+    readonly installed: string;
+    readonly latest: string;
+} | {
+    readonly status: "outdated";
+    readonly installed: string;
+    readonly latest: string;
+} | {
+    readonly status: "ahead";
+    readonly installed: string;
+    readonly latest: string;
+} | {
+    readonly status: "unavailable";
+    readonly installed: string;
+};
+export declare function fetchLatestPublishedVersion(fetchImpl: typeof fetch, timeoutMs?: number): Promise<string | undefined>;
+export declare function versionCheckFacts(installed: string, latest: string | undefined): VersionCheck;
 export interface HealthResult {
     readonly cubeProtocol: string;
     readonly iiisProtocol: string;
@@ -14,6 +32,7 @@ export interface DoctorOptions extends AgentConfigEnvironment {
 }
 export interface DoctorReport {
     readonly package_version: string;
+    readonly version_check: VersionCheck;
     readonly node_version: string;
     readonly npm_version: string;
     readonly client_adapters: Record<string, {

package/dist/cli/doctor.js

@@ -6,6 +6,67 @@ import { API_KEY_URL, getOnboardingPolicyWithTimeout, onboardingGuidance, } from
 import { agentConfigPath, inspectAgentConfigDetails, } from "./agent-config.js";
 const CUBE_HEALTH_PATH = "/api/omni-reader/direct-upload/v1/health";
 const GRANTED_UPLOAD_HEALTH_URL = "https://cubefile.ai.iiis.co:9443/omni/granted/health";
+const NPM_LATEST_URL = "https://registry.npmjs.org/@cueai/omni-reader-mcp/latest";
+const SEMVER_PATTERN = /^\d+\.\d+\.\d+$/;
+// Numeric semver comparison, not string equality: "1.3.9" < "1.3.10" lexically reverses
+// (string comparison would see "1.3.9" > "1.3.10"), and a local/dev build can legitimately
+// be numerically ahead of whatever npm currently has published as "latest".
+function compareSemver(a, b) {
+    const partsA = a.split(".").map(Number);
+    const partsB = b.split(".").map(Number);
+    for (let index = 0; index < 3; index += 1) {
+        const diff = partsA[index] - partsB[index];
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+function isNpmLatestBody(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    return typeof record.version === "string" && SEMVER_PATTERN.test(record.version);
+}
+// Mirrors getOnboardingPolicyWithTimeout's shape exactly: bounded timeout, strict
+// response validation, silent degrade to undefined on any failure -- a stale or
+// unreachable registry must never surface as a crash or a false version claim.
+export async function fetchLatestPublishedVersion(fetchImpl, timeoutMs = 3_000) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    timer.unref?.();
+    try {
+        const response = await fetchImpl(NPM_LATEST_URL, {
+            method: "GET",
+            headers: { accept: "application/json" },
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            return undefined;
+        const body = await response.json();
+        return isNpmLatestBody(body) ? body.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// "unavailable" is its own status, not a fallback to "current": the absence of a
+// reachable signal must never manufacture a false "you're up to date" claim. Likewise, an
+// installed version that isn't valid semver (e.g. this file's own "unknown" fallback) has
+// nothing meaningful to compare numerically -- report unavailable rather than guessing.
+export function versionCheckFacts(installed, latest) {
+    if (latest === undefined || !SEMVER_PATTERN.test(installed)) {
+        return { status: "unavailable", installed };
+    }
+    const comparison = compareSemver(installed, latest);
+    if (comparison === 0)
+        return { status: "current", installed, latest };
+    return comparison < 0
+        ? { status: "outdated", installed, latest }
+        : { status: "ahead", installed, latest };
+}
 function isHealthBody(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value))
         return false;
@@ -144,10 +205,18 @@ async function clientAdapterFacts(options) {
     return result;
 }
 export async function runDoctor(options) {
-    const [clientAdapters, artifacts, onboarding] = await Promise.all([
+    const packageVersion = options.packageVersion ?? "unknown";
+    const [clientAdapters, artifacts, onboarding, latestPublishedVersion] = await Promise.all([
         clientAdapterFacts(options),
         artifactFacts(options.artifactRoot),
         getOnboardingPolicyWithTimeout(options.fetchImpl),
+        // A non-semver packageVersion (the "unknown" fallback) has nothing meaningful to
+        // compare against -- skip the network round trip entirely rather than fetch a latest
+        // version we'd have no valid installed version to check it against. A valid-semver
+        // local/dev build IS worth checking (it may legitimately be ahead of npm's latest).
+        SEMVER_PATTERN.test(packageVersion)
+            ? fetchLatestPublishedVersion(options.fetchImpl)
+            : Promise.resolve(undefined),
     ]);
     let urlControl = "skipped (Cue API Key absent)";
     if (options.env.CUE_API_KEY) {
@@ -166,7 +235,10 @@ export async function runDoctor(options) {
         directUpload = "unavailable or incompatible";
     }
     return {
-        package_version: options.packageVersion ?? "unknown",
+        package_version: packageVersion,
+        version_check: SEMVER_PATTERN.test(packageVersion)
+            ? versionCheckFacts(packageVersion, latestPublishedVersion)
+            : { status: "unavailable", installed: packageVersion },
         node_version: options.nodeVersion ?? process.version,
         npm_version: options.npmVersion ?? "unavailable",
         client_adapters: clientAdapters,
@@ -192,11 +264,23 @@ export async function runDoctor(options) {
         reload_required: false,
     };
 }
+function packageLine(versionCheck) {
+    if (versionCheck.status === "current")
+        return `Package: ${versionCheck.installed} (up to date)`;
+    if (versionCheck.status === "outdated") {
+        return `Package: ${versionCheck.installed} (latest published: ${versionCheck.latest} — `
+            + `npx -y @cueai/omni-reader-mcp@${versionCheck.latest} setup to upgrade)`;
+    }
+    if (versionCheck.status === "ahead") {
+        return `Package: ${versionCheck.installed} (ahead of latest published ${versionCheck.latest} — local or dev build)`;
+    }
+    return `Package: ${versionCheck.installed} (latest published version unavailable)`;
+}
 export function renderDoctor(report) {
     const lines = [
         `Node: ${report.node_version}`,
         `npm: ${report.npm_version}`,
-        `Package: ${report.package_version}`,
+        packageLine(report.version_check),
         `Cue API Key: ${report.api_key.status}`,
         `Allowed roots: ${report.allowed_roots.count} (${report.allowed_roots.safe ? "safe" : "invalid"})`,
     ];
@@ -208,7 +292,13 @@ export function renderDoctor(report) {
         lines.push(`${label} config: ${report.client_adapters[key].status}`);
     }
     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.");
+    }
     lines.push(`Omni direct upload protocol: ${report.endpoints.direct_upload}`);
+    if (report.endpoints.direct_upload === "unavailable or incompatible") {
+        lines.push("  WARNING: local file parsing will fail until this is reachable.");
+    }
     lines.push(`Artifacts: ${report.artifacts.count} file(s), ${report.artifacts.bytes} byte(s)`);
     lines.push(`Artifact expiry: ${report.artifacts.earliest_expiry ?? (report.artifacts.count === 0 ? "none" : "unknown")}`);
     lines.push(`Cache: ${report.cache.mode}`);

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://cubefile.ai.iiis.co:9443/omni/granted/";
-export declare const BRIDGE_RELEASE_VERSION = "1.3.3";
+export declare const BRIDGE_RELEASE_VERSION = "1.4.1";
 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;

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://cubefile.ai.iiis.co:9443/omni/granted/";
-export const BRIDGE_RELEASE_VERSION = "1.3.3";
+export const BRIDGE_RELEASE_VERSION = "1.4.1";
 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;

package/dist/protocol.d.ts

@@ -68,9 +68,17 @@ export declare const discardResultSchema: z.ZodObject<{
 }, {
     result_id: string;
 }>;
+export declare const saveResultSchema: z.ZodObject<{
+    result_id: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    result_id: string;
+}, {
+    result_id: string;
+}>;
 export type ParseArguments = z.infer<typeof parseSchema>;
 export type GetParseStatusArguments = z.infer<typeof getParseStatusSchema>;
 export type CancelParseArguments = z.infer<typeof cancelParseSchema>;
 export type ReadResultArguments = z.infer<typeof readResultSchema>;
 export type DiscardResultArguments = z.infer<typeof discardResultSchema>;
 export type ReadOutlineArguments = z.infer<typeof readOutlineSchema>;
+export type SaveResultArguments = z.infer<typeof saveResultSchema>;

package/dist/protocol.js

@@ -88,3 +88,8 @@ export const discardResultSchema = z
     result_id: resultIdSchema,
 })
     .strict();
+export const saveResultSchema = z
+    .object({
+    result_id: resultIdSchema,
+})
+    .strict();

package/dist/remote-client.js

@@ -35,9 +35,14 @@ function responseError(response) {
     if (response.status === 401) {
         return remoteError({
             code: "API_KEY_INVALID",
-            message: "The Cue API Key is invalid or expired.",
+            // A 401 alone does not distinguish "this key value was checked and rejected" from
+            // "no key (or a malformed/unexpanded one) was actually sent" -- the client only knows
+            // the request was rejected as unauthorized, not why. Asserting the key itself "is
+            // invalid or expired" overclaims a diagnosis the client cannot make, and has misled a
+            // caller into telling a user to replace a key that was valid but never actually sent.
+            message: "Authentication was rejected (HTTP 401). This can mean the Cue API Key itself is invalid or expired, or that a valid key was not actually sent with the request.",
             failureScope: "authentication",
-            userAction: "Configure a valid Cue API Key without pasting it into chat.",
+            userAction: "Confirm a valid Cue API Key is actually being sent with this request (not just configured) before assuming the key value itself is wrong.",
             operationCreated: false,
             retryable: false,
         });

package/dist/result-contract.d.ts

@@ -609,7 +609,9 @@ export declare const readResultOutputSchema: z.ZodTypeAny;
 export declare const readOutlineOutputSchema: z.ZodTypeAny;
 export declare const readOutlineToolOutputSchema: z.ZodTypeAny;
 export declare const discardResultOutputSchema: z.ZodTypeAny;
+export declare const saveResultOutputSchema: z.ZodTypeAny;
 export declare const parseToolOutputSchema: z.ZodTypeAny;
 export declare const readResultToolOutputSchema: z.ZodTypeAny;
 export declare const discardResultToolOutputSchema: z.ZodTypeAny;
+export declare const saveResultToolOutputSchema: z.ZodTypeAny;
 export declare function structuredResult(schema: z.ZodTypeAny, value: unknown): CallToolResult;

package/dist/result-contract.js

@@ -377,6 +377,23 @@ export const discardResultOutputSchema = z.discriminatedUnion("status", [
         .strict(),
     failedResultSchema,
 ]);
+export const saveResultOutputSchema = z.discriminatedUnion("status", [
+    z
+        .object({
+        status: z.literal("completed"),
+        result_id: resultIdSchema,
+        path: z.string().min(1),
+        bytes: z.number().int().nonnegative(),
+    })
+        .strict(),
+    z
+        .object({
+        status: z.literal("unavailable"),
+        reason: z.literal("SAVE_NOT_SUPPORTED"),
+    })
+        .strict(),
+    failedResultSchema,
+]);
 export const parseToolOutputSchema = z
     .object({
     status: z.enum([
@@ -422,6 +439,16 @@ export const discardResultToolOutputSchema = z
     error: stableErrorSchema.optional(),
 })
     .strict();
+export const saveResultToolOutputSchema = z
+    .object({
+    status: z.enum(["completed", "unavailable", "failed"]),
+    result_id: resultIdSchema.optional(),
+    path: z.string().min(1).optional(),
+    bytes: z.number().int().nonnegative().optional(),
+    reason: z.literal("SAVE_NOT_SUPPORTED").optional(),
+    error: stableErrorSchema.optional(),
+})
+    .strict();
 function storageText(result) {
     const parts = result.parts;
     if (parts === null || typeof parts !== "object" || Array.isArray(parts)) {

package/dist/tools.d.ts

@@ -18,6 +18,10 @@ interface ToolArtifactStore {
     readOutline?(resultId: string): Promise<OutlineResult>;
     mintOutlineCursor?(resultId: string, byteOffset: number): Promise<string>;
     discard(resultId: string): Promise<boolean>;
+    exportResult?(resultId: string): Promise<{
+        path: string;
+        bytes: number;
+    }>;
 }
 export interface ParseOperationController {
     submitResult(input: {

package/dist/tools.js

@@ -6,8 +6,8 @@ import { OmniBridgeError } from "./errors.js";
 import { hydrateInlineUrlResultSafely } from "./operation-manager.js";
 import { openAllowedFile, } from "./path-security.js";
 import { NOOP_PROGRESS } from "./progress.js";
-import { MACHINE_INSTRUCTIONS, cancelParseSchema, discardResultSchema, getParseStatusSchema, normalizeRepresentation, parseSchema, readOutlineSchema, readResultSchema, } from "./protocol.js";
-import { discardResultOutputSchema, discardResultToolOutputSchema, localResultToResultField, parseResultSchema, parseToolOutputSchema, readOutlineOutputSchema, readOutlineToolOutputSchema, readResultOutputSchema, readResultToolOutputSchema, structuredResult, } from "./result-contract.js";
+import { MACHINE_INSTRUCTIONS, cancelParseSchema, discardResultSchema, getParseStatusSchema, normalizeRepresentation, parseSchema, readOutlineSchema, readResultSchema, saveResultSchema, } from "./protocol.js";
+import { discardResultOutputSchema, discardResultToolOutputSchema, localResultToResultField, parseResultSchema, parseToolOutputSchema, readOutlineOutputSchema, readOutlineToolOutputSchema, readResultOutputSchema, readResultToolOutputSchema, saveResultOutputSchema, saveResultToolOutputSchema, structuredResult, } from "./result-contract.js";
 import { classifySource } from "./source.js";
 import { TaskRuntime } from "./task-runtime.js";
 function bridgeError(code, message, facts = {}) {
@@ -376,6 +376,26 @@ async function callReadOutline(resultId, nodeId, dependencies) {
         return structuredResult(readOutlineOutputSchema, failed(error));
     }
 }
+async function callSaveResult(resultId, dependencies) {
+    if (dependencies.artifactStore.exportResult === undefined) {
+        return structuredResult(saveResultOutputSchema, {
+            status: "unavailable",
+            reason: "SAVE_NOT_SUPPORTED",
+        });
+    }
+    try {
+        const { path: exportPath, bytes } = await dependencies.artifactStore.exportResult(resultId);
+        return structuredResult(saveResultOutputSchema, {
+            status: "completed",
+            result_id: resultId,
+            path: exportPath,
+            bytes,
+        });
+    }
+    catch (error) {
+        return structuredResult(saveResultOutputSchema, failed(error));
+    }
+}
 function invalidArgumentsResult(name) {
     const error = failed(bridgeError("INVALID_TOOL_ARGUMENTS", "The Omni tool arguments are invalid."));
     if (name === "read_result")
@@ -384,6 +404,8 @@ function invalidArgumentsResult(name) {
         return structuredResult(discardResultOutputSchema, error);
     if (name === "read_outline")
         return structuredResult(readOutlineOutputSchema, error);
+    if (name === "save_result")
+        return structuredResult(saveResultOutputSchema, error);
     return structuredResult(parseResultSchema, error);
 }
 async function dispatchTool(name, rawArguments, extra, dependencies) {
@@ -423,6 +445,12 @@ async function dispatchTool(name, rawArguments, extra, dependencies) {
             ? callReadOutline(parsed.data.result_id, parsed.data.node_id, dependencies)
             : invalidArgumentsResult(name);
     }
+    if (name === "save_result") {
+        const parsed = saveResultSchema.safeParse(rawArguments ?? {});
+        return parsed.success
+            ? callSaveResult(parsed.data.result_id, dependencies)
+            : invalidArgumentsResult(name);
+    }
     return structuredResult(parseResultSchema, failed(bridgeError("TOOL_NOT_FOUND", "The requested Omni tool is not available.")));
 }
 export function registerOmniTools(server, dependencies, taskStore) {
@@ -514,6 +542,17 @@ export function registerOmniTools(server, dependencies, taskStore) {
             openWorldHint: false,
         },
     }, (args) => callReadOutline(args.result_id, args.node_id, dependencies));
+    server.registerTool("save_result", {
+        description: "Write a local result's complete content to a stable file on disk and return its path. There is no path argument: the file is always named from result_id inside the Bridge cache directory, so this cannot be pointed at an arbitrary location. Calling it again for the same result overwrites the same file.",
+        inputSchema: saveResultSchema,
+        outputSchema: saveResultToolOutputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, (args) => callSaveResult(args.result_id, dependencies));
     server.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         if (request.params.task !== undefined) {
             if (request.params.name !== "parse") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueai/omni-reader-mcp",
-  "version": "1.3.3",
+  "version": "1.4.1",
   "description": "Local stdio MCP bridge for direct Omni document parsing",
   "type": "module",
   "license": "UNLICENSED",