@cueai/omni-reader-mcp 1.5.2 → 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.2 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.2 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
-npx -y @cueai/omni-reader-mcp@1.5.2 setup --client cursor --add-root /absolute/minimum/root --yes --json
-npx -y @cueai/omni-reader-mcp@1.5.2 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,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.5.2 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
@@ -101,14 +101,14 @@ 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.2"] }
+   { "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.2` gives you that stable
+   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
@@ -251,16 +251,16 @@ satisfies the constraints.
 ## Commands
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.5.2 doctor
-npx -y @cueai/omni-reader-mcp@1.5.2 doctor --json
-npx -y @cueai/omni-reader-mcp@1.5.2 clean
-npx -y @cueai/omni-reader-mcp@1.5.2 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.2
+npx -y @cueai/omni-reader-mcp@1.5.3
 ```
 
 `doctor --json` returns package/npm/client adapter, Key present/absent, allowed-root
@@ -269,29 +269,36 @@ status; it never prints the Key, private source paths, or content.
 
 ## Network diagnostics
 
-Bridge connects to the Omni parse API at `https://cubefile.ai.iiis.co:9443`. When a
-connection fails, run `doctor` first — its endpoint-compatibility check covers the
-API reachability from your machine. The common symptoms:
+Run `npx -y @cueai/omni-reader-mcp@1.5.3 doctor --json` first. Diagnose failures by
+stage instead of guessing an endpoint:
 
-| Symptom | Most likely cause | Check |
+| Code | Stage | Meaning |
 |---|---|---|
-| `MCP error -32000: Connection closed` on Windows | launcher shape (see Windows configuration) | `doctor` package/client rows |
-| `CUBE_PROTOCOL_ERROR` or connection refused/timeout on connect | the hostname resolves to a private address on your network, or the route cannot reach the public endpoint | `nslookup cubefile.ai.iiis.co` — the public record is `122.200.68.28` |
-| Works in the browser / on another machine but not this one | a local hosts-file override hides a DNS or route problem | check `/etc/hosts` (or `C:\Windows\System32\drivers\etc\hosts`) for a `cubefile.ai.iiis.co` line; test `curl --noproxy '*' -w '%{remote_ip}\n' https://cubefile.ai.iiis.co:9443/omni/health` |
-
-If the API is reachable but a specific public URL fails to parse (`parse_timeout` /
-parse failed) while it works in your browser, that is a fetch-layer condition of the
-source on the parse API side — not a Bridge configuration problem — and it affects the
-URL the same way from every client.
+| `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.1 or 1.5.2 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.2:
+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.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.1";
+// 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) {
@@ -146,10 +151,9 @@ function entryPackageSpec(entry, platform) {
 /**
  * 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. On Windows the
- * previous release's bare-`npx` shape is additionally recognized as the migration
- * source — 1.5.1's setup wrote it there and it can never run, but upgrade and
- * uninstall must still identify it as a trusted entry so 1.5.2 can replace it.
+ * 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;
@@ -163,12 +167,12 @@ function entryInvocationMatches(entry, platform) {
             && args[3] === "-y"
             && typeof args[4] === "string"
             && TRUSTED_EXACT_PACKAGE_SPECS.has(args[4]);
-        const previousNpxForm = entry.command === "npx"
+        const migrationNpxForm = entry.command === "npx"
             && Array.isArray(args)
             && args.length === 2
             && args[0] === "-y"
-            && args[1] === PREVIOUS_PACKAGE_SPEC;
-        return cmdForm || previousNpxForm;
+            && args[1] === WINDOWS_BARE_NPX_MIGRATION_SPEC;
+        return cmdForm || migrationNpxForm;
     }
     return entry.command === "npx"
         && Array.isArray(args)
@@ -629,25 +633,27 @@ export function expectedBridgeVersion(target, value, platform) {
     if (!isExpectedOmniEntry(target, value, platform))
         return undefined;
     const packageSpec = entryPackageSpec(value, platform);
-    return packageSpec === PREVIOUS_PACKAGE_SPEC ? PREVIOUS_RELEASE_VERSION : BRIDGE_RELEASE_VERSION;
+    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) {
-    // The legacy npx form (what every pre-1.5.2 setup wrote, incl. on Windows) plus, on
-    // Windows, the current cmd form — both are recognizable Bridge entries.
-    const legacyNpx = (entry) => {
+    // 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"
-            && typeof args[1] === "string"
-            && (args[1] === LEGACY_PACKAGE_SPEC || TRUSTED_EXACT_PACKAGE_SPECS.has(args[1]));
+            && args[1] === LEGACY_PACKAGE_SPEC;
     };
     if (!isRecord(value))
         return false;
-    const shapeOk = platform === "win32"
-        ? (legacyNpx(value) || entryInvocationMatches(value, platform))
-        : legacyNpx(value);
+    const shapeOk = legacyUnpinnedNpx(value) || entryInvocationMatches(value, platform);
     if (!shapeOk)
         return false;
     if (value.env === undefined)

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.2";
+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.2";
+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.2",
+  "version": "1.5.3",
   "description": "Local stdio MCP bridge for direct Omni document parsing",
   "type": "module",
   "license": "UNLICENSED",