@cueai/omni-reader-mcp 1.5.1 → 1.5.3

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.5.1 setup
+npx -y @cueai/omni-reader-mcp@1.5.3 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.5.1 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
-npx -y @cueai/omni-reader-mcp@1.5.1 setup --client cursor --add-root /absolute/minimum/root --yes --json
-npx -y @cueai/omni-reader-mcp@1.5.1 setup --client claude-desktop --allowed-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.5.3 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.5.3 setup --client cursor --add-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.5.3 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,9 +82,39 @@ mode explicitly with `--headless` (alias `--non-interactive`): no `--yes` is req
 stdin is never read:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.5.1 setup --client cursor --allowed-root /absolute/minimum/root --headless --json
+npx -y @cueai/omni-reader-mcp@1.5.3 setup --client cursor --allowed-root /absolute/minimum/root --headless --json
 ```
 
+## Windows configuration
+
+On Windows, `npx` on the command line is actually `npx.cmd` — a batch-file wrapper, not
+an executable. An MCP client that launches the server with a bare `npx` command and no
+shell therefore fails immediately with `MCP error -32000: Connection closed` before the
+server even starts. This is a launcher-shape problem, not an Omni problem: the same
+entry works unchanged on macOS and Linux.
+
+If the agent reports `Connection closed` right after connecting on Windows, use one of
+the runnable forms below. From 1.5.2 on, `setup` writes the first form automatically on
+Windows and migrates an entry that 1.5.1's `setup` wrote (the bare `npx` shape) to it
+automatically; the second is the most robust when you configure by hand.
+
+1. **`cmd` + `npx` (what `setup` writes on Windows)** — `cmd.exe` is a real executable,
+   so a client's no-shell spawn works:
+   ```json
+   { "command": "cmd", "args": ["/d", "/c", "npx", "-y", "@cueai/omni-reader-mcp@1.5.3"] }
+   ```
+2. **`node` + the package entry (most robust)** — skips `npx` entirely; the absolute
+   path must be a stable install you control:
+   ```json
+   { "command": "node", "args": ["C:\\path\\to\\node_modules\\@cueai\\omni-reader-mcp\\dist\\index.js"] }
+   ```
+   A deliberate local `npm install @cueai/omni-reader-mcp@1.5.3` gives you that stable
+   path. Do not point the entry at an `_npx` cache directory — its hash subdirectory
+   changes between installs.
+3. **Never use a session/timestamp directory** — such paths are cleaned up, and the
+   connection silently breaks at the next session. Re-run `setup` or install into a
+   stable directory instead.
+
 ## Cache and journal isolation
 
 The local parse cache and operation journal default to the user-level cache directory
@@ -221,30 +251,54 @@ satisfies the constraints.
 ## Commands
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.5.1 doctor
-npx -y @cueai/omni-reader-mcp@1.5.1 doctor --json
-npx -y @cueai/omni-reader-mcp@1.5.1 clean
-npx -y @cueai/omni-reader-mcp@1.5.1 uninstall --yes --json
+npx -y @cueai/omni-reader-mcp@1.5.3 doctor
+npx -y @cueai/omni-reader-mcp@1.5.3 doctor --json
+npx -y @cueai/omni-reader-mcp@1.5.3 clean
+npx -y @cueai/omni-reader-mcp@1.5.3 uninstall --yes --json
 ```
 
 Running the pinned version without a command starts the stdio MCP server:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.5.1
+npx -y @cueai/omni-reader-mcp@1.5.3
 ```
 
 `doctor --json` returns package/npm/client adapter, Key present/absent, allowed-root
 safety status, endpoint compatibility, artifacts, cache mode, onboarding, and reload
 status; it never prints the Key, private source paths, or content.
 
+## Network diagnostics
+
+Run `npx -y @cueai/omni-reader-mcp@1.5.3 doctor --json` first. Diagnose failures by
+stage instead of guessing an endpoint:
+
+| Code | Stage | Meaning |
+|---|---|---|
+| `CUBE_UNAVAILABLE` | before upload | the control plane could not create a parse grant |
+| `PRINCIPAL_CONCURRENCY_LIMIT` | before upload | the principal already has the maximum active parses; wait for `retry_after`, then retry the same parse |
+| `IIIS_UNAVAILABLE` | after grant creation | the granted upload stage could not complete |
+| `CUBE_PROTOCOL_ERROR` | control-plane response | the response did not match the required contract |
+| `MCP error -32000: Connection closed` | before Bridge starts | the client launcher shape is invalid; see Windows configuration |
+
+Use only the compatibility and endpoint facts reported by `doctor`. Do not guess or
+publish service hosts or ports, hard-code IP addresses, modify hosts files, or probe an
+endpoint copied from logs. If an enterprise network policy blocks a required connection,
+provide the redacted `doctor --json` result to support for the applicable egress
+requirements.
+
+If the secure parse environment is reachable but a specific public URL fails to parse
+(`parse_timeout` / parse failed) while it works in a browser, that is a fetch-layer
+condition of the source — not a Bridge configuration problem — and it affects the URL
+the same way from every client.
+
 ## Uninstall and rollback
 
-`uninstall --yes --json` removes only a trusted 1.5.0 or 1.5.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.
+`uninstall --yes --json` removes only a trusted 1.5.2 or 1.5.3 Bridge entry, plus
+the exact broken bare-`npx` Windows entry written by 1.5.1. 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.5.1:
+To roll back from 1.5.3:
 
 1. stop recommending or installing that version;
 2. run `uninstall --yes --json` to restore the trusted URL-only entry;

package/dist/cli/agent-config.d.ts

@@ -41,6 +41,7 @@ export declare function agentConfigPath(target: AgentTarget, environment: AgentC
 export declare function agentBackupPath(configPath: string): string;
 export declare function displayConfigPath(configPath: string, environment: AgentConfigEnvironment): string;
 export declare function buildAgentEntry(target: AgentTarget, extraRoots: readonly string[], platform: NodeJS.Platform): Record<string, unknown>;
+export declare function expectedBridgeVersion(target: AgentTarget, value: unknown, platform: NodeJS.Platform): string | undefined;
 export declare function prepareAgentConfig(target: AgentTarget, extraRoots: readonly string[], environment: AgentConfigEnvironment): Promise<PreparedAgentConfig>;
 export declare function verifyPreparedAgentConfig(prepared: PreparedAgentConfig): Promise<void>;
 export declare function writePreparedAgentConfig(prepared: PreparedAgentConfig): Promise<void>;

package/dist/cli/agent-config.js

@@ -4,11 +4,16 @@ 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}`;
-// 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.5.0";
+// The release that the current version is a trusted upgrade from: normal upgrade,
+// uninstall, and rollback recognize exactly {previous, current}. Bump this to the
+// version we just published when BRIDGE_RELEASE_VERSION advances.
+const PREVIOUS_RELEASE_VERSION = "1.5.2";
 const PREVIOUS_PACKAGE_SPEC = `@cueai/omni-reader-mcp@${PREVIOUS_RELEASE_VERSION}`;
+// Preserve the one evidenced two-release migration exception: 1.5.1 setup wrote a
+// bare `npx` launcher on Windows, so later setup/uninstall versions must still be able
+// to identify and replace that otherwise-unrunnable entry. 1.5.2 already writes `cmd`.
+const WINDOWS_BARE_NPX_MIGRATION_VERSION = "1.5.1";
+const WINDOWS_BARE_NPX_MIGRATION_SPEC = `@cueai/omni-reader-mcp@${WINDOWS_BARE_NPX_MIGRATION_VERSION}`;
 const LEGACY_PACKAGE_SPEC = "@cueai/omni-reader-mcp";
 const TRUSTED_EXACT_PACKAGE_SPECS = new Set([PREVIOUS_PACKAGE_SPEC, PACKAGE_SPEC]);
 function isRecord(value) {
@@ -116,10 +121,14 @@ export function displayConfigPath(configPath, environment) {
     return configPath;
 }
 export function buildAgentEntry(target, extraRoots, platform) {
-    const entry = {
-        command: "npx",
-        args: ["-y", PACKAGE_SPEC],
-    };
+    // On Windows `npx` is `npx.cmd` — a batch wrapper a client cannot spawn without a
+    // shell (spawn("npx") → ENOENT, spawn("npx.cmd") → EINVAL). `cmd /d /c npx ...` is a
+    // real executable, so a no-shell spawn works (`/d` skips the AutoRun registry command,
+    // whose stdout would corrupt the MCP stdio frames); macOS/Linux keep the bare `npx`
+    // form.
+    const entry = platform === "win32"
+        ? { command: "cmd", args: ["/d", "/c", "npx", "-y", PACKAGE_SPEC] }
+        : { command: "npx", args: ["-y", PACKAGE_SPEC] };
     const env = {};
     if (target === "hermes")
         env.CUE_API_KEY = "${CUE_API_KEY}";
@@ -130,6 +139,48 @@ export function buildAgentEntry(target, extraRoots, platform) {
         entry.env = env;
     return entry;
 }
+/** The exact package spec at the invocation's spec position, given its platform shape. */
+function entryPackageSpec(entry, platform) {
+    const args = entry.args;
+    if (!Array.isArray(args))
+        return undefined;
+    if (platform !== "win32")
+        return args[1];
+    return entry.command === "npx" ? args[1] : args[4];
+}
+/**
+ * Matches the trusted invocation shape for the platform: `cmd /d /c npx -y <spec>` on
+ * Windows (runnable by a no-shell spawn; `/d` skips the AutoRun command whose stdout
+ * would corrupt MCP stdio frames), `npx -y <spec>` everywhere else. Windows also keeps
+ * the exact 1.5.1 bare-`npx` migration source: that release wrote an unrunnable entry,
+ * while 1.5.2 and later write `cmd` and therefore need no widening exception.
+ */
+function entryInvocationMatches(entry, platform) {
+    const args = entry.args;
+    if (platform === "win32") {
+        const cmdForm = entry.command === "cmd"
+            && Array.isArray(args)
+            && args.length === 5
+            && args[0] === "/d"
+            && args[1] === "/c"
+            && args[2] === "npx"
+            && args[3] === "-y"
+            && typeof args[4] === "string"
+            && TRUSTED_EXACT_PACKAGE_SPECS.has(args[4]);
+        const migrationNpxForm = entry.command === "npx"
+            && Array.isArray(args)
+            && args.length === 2
+            && args[0] === "-y"
+            && args[1] === WINDOWS_BARE_NPX_MIGRATION_SPEC;
+        return cmdForm || migrationNpxForm;
+    }
+    return entry.command === "npx"
+        && Array.isArray(args)
+        && args.length === 2
+        && args[0] === "-y"
+        && typeof args[1] === "string"
+        && TRUSTED_EXACT_PACKAGE_SPECS.has(args[1]);
+}
 function configFormat(target) {
     return target === "hermes" ? "hermes-yaml" : "json";
 }
@@ -500,7 +551,7 @@ function yamlEntry(entry, newline) {
     const args = entry.args;
     const lines = [
         "  omni-reader:",
-        "    command: npx",
+        `    command: ${entry.command}`,
         "    args:",
         ...args.map((argument) => `      - ${JSON.stringify(argument)}`),
     ];
@@ -541,16 +592,8 @@ function entryDigest(entry) {
     };
     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" ||
-        typeof args[1] !== "string" ||
-        !TRUSTED_EXACT_PACKAGE_SPECS.has(args[1]))
+function isExpectedOmniEntry(target, value, platform) {
+    if (!isRecord(value) || !entryInvocationMatches(value, platform))
         return false;
     const keys = Object.keys(value).sort();
     if (value.env === undefined) {
@@ -586,21 +629,32 @@ function isExpectedOmniEntry(target, value) {
         && keys[1] === "command"
         && keys[2] === "env";
 }
-function expectedBridgeVersion(target, value) {
-    if (!isExpectedOmniEntry(target, value))
+export function expectedBridgeVersion(target, value, platform) {
+    if (!isExpectedOmniEntry(target, value, platform))
         return undefined;
-    const packageSpec = value.args[1];
-    return packageSpec === PREVIOUS_PACKAGE_SPEC ? PREVIOUS_RELEASE_VERSION : BRIDGE_RELEASE_VERSION;
-}
-function isLegacyBridgeEntry(target, value) {
-    if (!isRecord(value) || value.command !== "npx")
+    const packageSpec = entryPackageSpec(value, platform);
+    if (packageSpec === PREVIOUS_PACKAGE_SPEC)
+        return PREVIOUS_RELEASE_VERSION;
+    if (packageSpec === WINDOWS_BARE_NPX_MIGRATION_SPEC) {
+        return WINDOWS_BARE_NPX_MIGRATION_VERSION;
+    }
+    return BRIDGE_RELEASE_VERSION;
+}
+function isLegacyBridgeEntry(target, value, platform) {
+    // Keep the historical unpinned package form recognizable for setup migration;
+    // every exact-version form delegates to the single platform policy above.
+    const legacyUnpinnedNpx = (entry) => {
+        const args = entry.args;
+        return entry.command === "npx"
+            && Array.isArray(args)
+            && args.length === 2
+            && args[0] === "-y"
+            && args[1] === LEGACY_PACKAGE_SPEC;
+    };
+    if (!isRecord(value))
         return false;
-    const args = value.args;
-    if (!Array.isArray(args) ||
-        args.length !== 2 ||
-        args[0] !== "-y" ||
-        typeof args[1] !== "string" ||
-        (args[1] !== LEGACY_PACKAGE_SPEC && !TRUSTED_EXACT_PACKAGE_SPECS.has(args[1])))
+    const shapeOk = legacyUnpinnedNpx(value) || entryInvocationMatches(value, platform);
+    if (!shapeOk)
         return false;
     if (value.env === undefined)
         return target !== "hermes";
@@ -640,12 +694,12 @@ function hermesOmniEntry(document, displayPath) {
     }
     return entry;
 }
-function previousJsonEntry(value, displayPath) {
+function previousJsonEntry(value, displayPath, platform) {
     if (value === undefined)
         return null;
     if (isCanonicalRemoteEntry(value))
         return { format: "json", value };
-    if (isLegacyBridgeEntry("cursor", value))
+    if (isLegacyBridgeEntry("cursor", value, platform))
         return null;
     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, "
@@ -663,7 +717,7 @@ function hermesCredentialsAreReferences(serialized) {
     }
     return true;
 }
-function previousHermesEntry(entry, displayPath) {
+function previousHermesEntry(entry, displayPath, platform) {
     if (entry === undefined)
         return null;
     const value = parseHermesEntry(entry);
@@ -675,7 +729,7 @@ function previousHermesEntry(entry, displayPath) {
         }
         return { format: "hermes-yaml", serialized: entry.serialized };
     }
-    if (isLegacyBridgeEntry("hermes", value))
+    if (isLegacyBridgeEntry("hermes", value, platform))
         return null;
     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, "
@@ -710,7 +764,7 @@ export async function prepareAgentConfig(target, extraRoots, environment) {
         }
         const servers = existingServers ?? {};
         const existing = onlyOmniEntry(servers, displayPath);
-        const previousEntry = previousJsonEntry(existing.value, displayPath);
+        const previousEntry = previousJsonEntry(existing.value, displayPath, environment.platform);
         const afterValue = {
             ...value,
             mcpServers: {
@@ -737,7 +791,7 @@ export async function prepareAgentConfig(target, extraRoots, environment) {
     }
     const document = parseHermesDocument(loaded.serialized);
     const existing = hermesOmniEntry(document, displayPath);
-    const previousEntry = previousHermesEntry(existing, displayPath);
+    const previousEntry = previousHermesEntry(existing, displayPath, environment.platform);
     const serializedAfter = replaceHermesEntry(loaded.serialized, document, yamlEntry(entry, document.newline));
     return {
         target: "hermes",
@@ -964,7 +1018,7 @@ export async function writePreparedAgentConfig(prepared) {
         const existingBackup = await readTrustedBackup(configPath);
         let replacementBackup = backup;
         if (existingBackup !== undefined) {
-            const currentEntry = expectedConfigEntry(prepared.target, current);
+            const currentEntry = expectedConfigEntry(prepared.target, current, prepared.environment?.platform ?? "darwin");
             if (currentEntry !== undefined && existingBackup.target === prepared.target) {
                 if (existingBackup.bridge_entry_digest !== entryDigest(currentEntry)) {
                     throw fileError("A conflicting trusted Omni backup already exists; no changes were written.");
@@ -1011,21 +1065,21 @@ function jsonConfigEntry(value) {
         return undefined;
     return onlyOmniEntry(value.mcpServers, "the Agent configuration").value;
 }
-function expectedConfigEntry(target, loaded) {
+function expectedConfigEntry(target, loaded, platform) {
     if (target === "hermes") {
         const document = parseHermesDocument(loaded.serialized);
         const entry = hermesOmniEntry(document, "the Hermes configuration");
         if (entry === undefined)
             return undefined;
         const value = parseHermesEntry(entry);
-        return isExpectedOmniEntry(target, value) ? value : undefined;
+        return isExpectedOmniEntry(target, value, platform) ? value : undefined;
     }
     assertNoDuplicateJsonOmniEntries(loaded.serialized);
     const value = jsonConfigEntry(parseJsonConfig(loaded));
-    return isExpectedOmniEntry(target, value) ? value : undefined;
+    return isExpectedOmniEntry(target, value, platform) ? value : undefined;
 }
-async function configHasExpectedEntry(target, loaded) {
-    return expectedConfigEntry(target, loaded) !== undefined;
+async function configHasExpectedEntry(target, loaded, platform) {
+    return expectedConfigEntry(target, loaded, platform) !== undefined;
 }
 export async function inspectAgentConfigDetails(configPath, environment, target) {
     try {
@@ -1041,7 +1095,7 @@ export async function inspectAgentConfigDetails(configPath, environment, target)
             if (entry === undefined)
                 return { status: "not configured" };
             const value = parseHermesEntry(entry);
-            const version = expectedBridgeVersion("hermes", value);
+            const version = expectedBridgeVersion("hermes", value, environment?.platform ?? "darwin");
             if (version !== undefined)
                 return { status: "configured", version };
             return {
@@ -1055,7 +1109,7 @@ export async function inspectAgentConfigDetails(configPath, environment, target)
         const entry = onlyOmniEntry(value.mcpServers, configPath).value;
         if (entry === undefined)
             return { status: "not configured" };
-        const version = expectedBridgeVersion(resolvedTarget, entry);
+        const version = expectedBridgeVersion(resolvedTarget, entry, environment?.platform ?? "darwin");
         if (version !== undefined)
             return { status: "configured", version };
         return {
@@ -1133,7 +1187,7 @@ export async function rollbackPreparedAgentConfig(prepared) {
                 existed: true,
                 serialized: prepared.serializedBefore,
                 fingerprint: prepared.sourceFingerprint ?? "unused",
-            })
+            }, prepared.environment?.platform ?? "darwin")
             : undefined;
         if (prepared.existed) {
             await atomicReplace(prepared.configPath, prepared.serializedBefore);
@@ -1192,11 +1246,11 @@ export async function uninstallAgentConfig(target, environment) {
         return undefined;
     await validateUserConfigPath(configPath, environment);
     const initial = await readConfig(configPath);
-    if (!initial.existed || !await configHasExpectedEntry(target, initial))
+    if (!initial.existed || !await configHasExpectedEntry(target, initial, environment.platform))
         return undefined;
     return await withConfigLock(configPath, environment, async () => {
         const current = await readConfig(configPath);
-        if (!await configHasExpectedEntry(target, current)) {
+        if (!await configHasExpectedEntry(target, current, environment.platform)) {
             throw fileError("The Agent configuration changed before uninstall; no changes were written.");
         }
         const currentEntry = target === "hermes"

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.5.1";
+export declare const BRIDGE_RELEASE_VERSION = "1.5.3";
 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.5.1";
+export const BRIDGE_RELEASE_VERSION = "1.5.3";
 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/cube-client.js

@@ -25,6 +25,16 @@ const grantResponseSchema = z
     protocol_version: z.enum([CUBE_GRANT_PROTOCOL_VERSION, "omni.parse_grant.v2"]),
 })
     .strict();
+const principalConcurrencyErrorSchema = z
+    .object({
+    code: z.literal("PRINCIPAL_CONCURRENCY_LIMIT"),
+    message: z.literal("The maximum number of concurrent parsing operations is already active."),
+    file_uploaded: z.literal(false),
+    billed: z.literal(false),
+    content_released: z.literal(false),
+    retryable: z.literal(true),
+})
+    .strict();
 // Closed v3 grant response: the exact tuple of the selected direct profile is
 // required before the upload phase may start. The tuple is re-checked against
 // the profile after schema parsing so a drifting server cannot slip through.
@@ -47,7 +57,7 @@ const grantResponseV3Schema = z
     approved_result_max_bytes: z.literal(67108864),
 })
     .strict();
-function bridgeError(code, message, retryable) {
+function bridgeError(code, message, retryable, options = {}) {
     return new OmniBridgeError({
         code,
         message,
@@ -57,6 +67,9 @@ function bridgeError(code, message, retryable) {
         billed: false,
         contentReleased: false,
         retryable,
+        ...(options.failureScope === undefined ? {} : { failureScope: options.failureScope }),
+        ...(options.userAction === undefined ? {} : { userAction: options.userAction }),
+        ...(options.retryAfter === undefined ? {} : { retryAfter: options.retryAfter }),
     });
 }
 function grantRequestBody(input, profile) {
@@ -137,6 +150,33 @@ function responseError(status) {
     }
     return bridgeError("CUBE_UNAVAILABLE", "Cube could not create the parse grant. Retry this same grant request later.", status >= 500);
 }
+function retryAfterSeconds(response) {
+    const value = response.headers.get("retry-after");
+    if (value === null || !/^\d+$/u.test(value))
+        return undefined;
+    const seconds = Number(value);
+    return Number.isSafeInteger(seconds) && seconds > 0 ? seconds : undefined;
+}
+async function grantResponseError(response) {
+    const retryAfter = retryAfterSeconds(response);
+    if (response.status === 429 && retryAfter !== undefined) {
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            return responseError(response.status);
+        }
+        if (principalConcurrencyErrorSchema.safeParse(body).success) {
+            return bridgeError("PRINCIPAL_CONCURRENCY_LIMIT", "The maximum number of concurrent parsing operations is already active.", true, {
+                failureScope: "service",
+                userAction: "Wait for retry_after seconds, then retry the same local-file parse.",
+                retryAfter,
+            });
+        }
+    }
+    return responseError(response.status);
+}
 export class CubeGrantClient {
     #journal;
     #apiKey;
@@ -256,7 +296,7 @@ export class CubeGrantClient {
             throw bridgeError("CUBE_UNAVAILABLE", "Cube could not create the parse grant. Retry this same grant request later.", true);
         }
         if (!response.ok) {
-            throw responseError(response.status);
+            throw await grantResponseError(response);
         }
         // The v3 response tuple is required before this promise resolves: the
         // upload phase can only start after the negotiated representation is

package/package.json

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