@cueai/omni-reader-mcp 1.5.2 → 1.5.4

package/README.md

@@ -43,6 +43,14 @@ Bridge reads only these product configuration variables at runtime:
 authorizes; colon-separated on macOS/Linux, semicolon-separated on Windows. The current
 agent workspace remains the default allowed scope.
 
+## How parsing works
+
+For a local file, Bridge requests a Cube parse grant and uses the returned controlled
+granted-data-plane URL to upload the file and stream the result. A `BRIDGE_UPGRADE_REQUIRED`
+error means the running Bridge release is not accepted for direct local-file parsing —
+install `@cueai/omni-reader-mcp@1.5.4` using the official setup instructions, then retry the
+same parse. Always run `doctor --json` first when diagnosing a parse failure.
+
 ## Free credits
 
 As of 2026-08-14:
@@ -64,7 +72,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.4 setup
 ```
 
 The interactive setup supports Hermes, Cursor, Claude Desktop, and generic stdio
@@ -72,9 +80,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.4 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.5.4 setup --client cursor --add-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.5.4 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 +90,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.4 setup --client cursor --allowed-root /absolute/minimum/root --headless --json
 ```
 
 ## Windows configuration
@@ -101,14 +109,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.4"] }
    ```
 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.4` 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
@@ -136,7 +144,9 @@ project-overlap check; mutual containment with a project directory remains forbi
 1. show the user-scope configuration target and changes;
 2. write a single, exact-version `omni-reader` facade;
 3. use a private lock, trusted backup, and atomic replacement;
-4. verify the Omni secure parse environment;
+4. verify the Cue API Key, Cube control reachability, and client configuration
+   (setup does not claim to verify the granted data plane or the ability to parse —
+   only a real local-file parse proves that);
 5. restore the previous configuration when verification fails;
 6. prompt the corresponding agent to reload or restart.
 
@@ -251,47 +261,60 @@ 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.4 doctor
+npx -y @cueai/omni-reader-mcp@1.5.4 doctor --json
+npx -y @cueai/omni-reader-mcp@1.5.4 clean
+npx -y @cueai/omni-reader-mcp@1.5.4 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.4
 ```
 
 `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.
+safety status, the authenticated Cube control/configuration facts, artifacts, cache
+mode, onboarding, and reload status; it never prints the Key, private source paths,
+or content. The `endpoints.direct_upload` field is a fact about the release, not a
+probe: the granted data plane is reached only through a Cube grant and is never
+definitively "available" until a real local-file parse validates the route.
+
 
 ## 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.4 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 |
+| `BRIDGE_UPGRADE_REQUIRED` | before upload | this Bridge release is too old; install `@cueai/omni-reader-mcp@1.5.4` via the official setup, 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 control-plane and configuration 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. `doctor` does not probe the granted data plane: only a
+real local-file parse proves it end-to-end. 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.3 or 1.5.4 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.4:
 
 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,12 +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.3";
 const PREVIOUS_PACKAGE_SPEC = `@cueai/omni-reader-mcp@${PREVIOUS_RELEASE_VERSION}`;
-const LEGACY_PACKAGE_SPEC = "@cueai/omni-reader-mcp";
+// 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 TRUSTED_EXACT_PACKAGE_SPECS = new Set([PREVIOUS_PACKAGE_SPEC, PACKAGE_SPEC]);
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -146,10 +150,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 +166,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,26 +632,21 @@ 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) => {
-        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]));
-    };
-    if (!isRecord(value))
-        return false;
-    const shapeOk = platform === "win32"
-        ? (legacyNpx(value) || entryInvocationMatches(value, platform))
-        : legacyNpx(value);
-    if (!shapeOk)
+    // Defer the entire invocation-shape decision to the single platform policy:
+    // exact pinned {1.5.3 previous, 1.5.4 current} plus the exact Windows 1.5.1
+    // bare-npx migration source. The historical platform-agnostic acceptance of a
+    // bare unpinned `npx -y @cueai/omni-reader-mcp` is removed: it widened the
+    // frozen trust set to a floating latest on every OS, which expectedBridgeVersion
+    // already rejects but the predecessor gate still admitted.
+    if (!isRecord(value) || !entryInvocationMatches(value, platform))
         return false;
     if (value.env === undefined)
         return target !== "hermes";

package/dist/cli/doctor.d.ts

@@ -19,7 +19,7 @@ export declare function fetchLatestPublishedVersion(fetchImpl: typeof fetch, tim
 export declare function versionCheckFacts(installed: string, latest: string | undefined): VersionCheck;
 export interface HealthResult {
     readonly cubeProtocol: string;
-    readonly iiisProtocol: string;
+    readonly relayStatus: "reporting-only";
 }
 export interface DoctorOptions extends AgentConfigEnvironment {
     readonly env: NodeJS.ProcessEnv;
@@ -70,7 +70,6 @@ export interface DoctorReport {
 }
 type AgentConfigStatusForReport = "configured" | "not configured" | "invalid or unreadable";
 export declare function checkCubeHealth(fetchImpl: typeof fetch, apiKey: string): Promise<string>;
-export declare function checkIiisHealth(fetchImpl: typeof fetch): Promise<string>;
 export declare function checkHealth(fetchImpl: typeof fetch, apiKey: string): Promise<HealthResult>;
 export declare function runDoctor(options: DoctorOptions): Promise<DoctorReport>;
 export declare function renderDoctor(report: DoctorReport): string[];

package/dist/cli/doctor.js

@@ -1,12 +1,18 @@
 import { constants as fsConstants } from "node:fs";
 import { lstat, open, readdir } from "node:fs/promises";
 import path from "node:path";
-import { DEFAULT_CUBE_BASE_URL, GRANTED_STREAM_PROTOCOL_VERSION, MAX_FILE_BYTES, CUBE_GRANT_PROTOCOL_VERSION, } from "../constants.js";
+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 { 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";
+// Local-file parsing reaches the data plane only through the controlled origin
+// returned by a Cube grant. There is no public relay /health endpoint to probe and
+// no compatibility claim to make from a retired direct path, so doctor reports a
+// static, zero-side-effect fact. It deliberately does NOT assert "available": the
+// granted data-plane route is validated only by the first real local-file parse,
+// so the status is explicitly "not probed" until then.
+const RELAY_DATA_PLANE_STATUS = "not probed (validated on the first real local-file parse)";
 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
@@ -95,19 +101,14 @@ export async function checkCubeHealth(fetchImpl, apiKey) {
     }
     return cube.protocol_version;
 }
-export async function checkIiisHealth(fetchImpl) {
-    const granted = await fetchHealth(fetchImpl, GRANTED_UPLOAD_HEALTH_URL);
-    if (!granted.enabled || granted.protocol_version !== GRANTED_STREAM_PROTOCOL_VERSION) {
-        throw new Error("Omni direct upload is disabled or incompatible");
-    }
-    return granted.protocol_version;
-}
 export async function checkHealth(fetchImpl, apiKey) {
-    const [cubeProtocol, iiisProtocol] = await Promise.all([
-        checkCubeHealth(fetchImpl, apiKey),
-        checkIiisHealth(fetchImpl),
-    ]);
-    return { cubeProtocol, iiisProtocol };
+    const cubeProtocol = await checkCubeHealth(fetchImpl, apiKey);
+    // Local-file parsing reaches the granted data-plane only through the controlled
+    // origin returned by a Cube grant, so there is no separate endpoint to probe and
+    // no compatibility claim to make from the retired direct path. Doctor reports a
+    // static, zero-side-effect fact that is explicitly NOT "available": the route is
+    // validated by the first real local-file parse.
+    return { cubeProtocol, relayStatus: "reporting-only" };
 }
 async function artifactExpiry(metadataPath, resultId) {
     let handle;
@@ -227,13 +228,12 @@ export async function runDoctor(options) {
             urlControl = "unavailable or incompatible";
         }
     }
-    let directUpload;
-    try {
-        directUpload = await checkIiisHealth(options.fetchImpl);
-    }
-    catch {
-        directUpload = "unavailable or incompatible";
-    }
+    // The granted data-plane has no public health endpoint; doctor makes no probe
+    // and reports a static fact so it never claims compatibility or availability from
+    // a retired path. This is deliberate: the only way to know local-file parsing
+    // works end-to-end is to run a real parse and inspect the grant response, so the
+    // status stays "not probed" until the first real local-file parse validates it.
+    const directUpload = RELAY_DATA_PLANE_STATUS;
     return {
         package_version: packageVersion,
         version_check: SEMVER_PATTERN.test(packageVersion)
@@ -295,10 +295,7 @@ export function renderDoctor(report) {
     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(`Omni granted data plane: ${report.endpoints.direct_upload}`);
     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/cli/setup.js

@@ -96,9 +96,9 @@ async function validateConfiguredEnvironment(options, prepared, apiKey) {
             await rollbackPreparedAgentConfig(prepared);
         }
         catch {
-            throw new Error("Omni 安全解析环境验证失败，且无法确认 Agent 配置已自动恢复；请停止重试并检查 user-scope 配置。");
+            throw new Error("Omni 控制面健康检查（Cue API Key / Cube 控制面）失败，且无法确认 Agent 配置已自动恢复；请停止重试并检查 user-scope 配置。");
         }
-        throw new Error("Omni 安全解析环境验证失败；原 Agent 配置已自动恢复。");
+        throw new Error("Omni 控制面健康检查（Cue API Key / Cube 控制面）失败；原 Agent 配置已自动恢复。");
     }
 }
 function writeSuccess(options, prepared, roots) {
@@ -139,7 +139,7 @@ export async function runSetup(options) {
             await checkHealth(options.fetchImpl, apiKey);
         }
         catch {
-            throw new Error("Omni 安全解析环境验证失败；未写入 Agent 配置。");
+            throw new Error("Omni 控制面健康检查（Cue API Key / Cube 控制面）失败；未写入 Agent 配置。");
         }
     }
     else {

package/dist/constants.d.ts

@@ -5,8 +5,8 @@ export declare const RESULT_CHUNK_MAX_BYTES = 65536;
 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 DEFAULT_IIIS_GRANTED_BASE_URL = "https://omni-upload.cuecue.cn/omni/granted/";
+export declare const BRIDGE_RELEASE_VERSION = "1.5.4";
 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

@@ -5,8 +5,8 @@ export const RESULT_CHUNK_MAX_BYTES = 65536;
 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 DEFAULT_IIIS_GRANTED_BASE_URL = "https://omni-upload.cuecue.cn/omni/granted/";
+export const BRIDGE_RELEASE_VERSION = "1.5.4";
 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,29 @@ 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();
+// The strict 426 Bridge-upgrade marker: exactly six closed fields, all literal.
+// Any drift (status, header, body, schema) falls through to the generic
+// nonretryable CUBE_UNAVAILABLE — never a new public code and never server text.
+const bridgeUpgradeRequiredSchema = z
+    .object({
+    code: z.literal("BRIDGE_UPGRADE_REQUIRED"),
+    message: z.literal("This Bridge release is not accepted for direct local-file parsing."),
+    file_uploaded: z.literal(false),
+    billed: z.literal(false),
+    content_released: z.literal(false),
+    retryable: z.literal(false),
+})
+    .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 +70,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 +80,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 +163,51 @@ 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) {
+    // The strict 426 marker is only recognized when there is exactly a 426 status,
+    // no Retry-After, and a body matching the six frozen literal fields. Any drift
+    // degrades through `responseError` to the generic nonretryable CUBE_UNAVAILABLE.
+    if (response.status === 426 && !response.headers.has("retry-after")) {
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            return responseError(response.status);
+        }
+        if (bridgeUpgradeRequiredSchema.safeParse(body).success) {
+            return bridgeError("BRIDGE_UPGRADE_REQUIRED", "This Bridge release is not accepted for direct local-file parsing.", false, {
+                failureScope: "service",
+                userAction: "Upgrade to @cueai/omni-reader-mcp@1.5.4 using the official Omni setup instructions, then retry the same local-file parse.",
+            });
+        }
+    }
+    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 +327,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/dist/iiis-client.js

@@ -88,6 +88,19 @@ function throwIfCanceled(input) {
     if (input.signal?.aborted)
         throw canceledAfterUpload();
 }
+// Cancel (without parsing or draining) a response body we are choosing not to
+// consume, so a drifting long body cannot leave a network stream or connection
+// alive after we return. Never adds an unbounded drain. User-abort precedence is
+// preserved by the callers: they re-check `throwIfCanceled` around this helper.
+function cancelResponseBody(response) {
+    try {
+        if (response.body !== null)
+            void response.body.cancel().catch(() => undefined);
+    }
+    catch {
+        // The body may already be cancelled/locked; nothing more to release.
+    }
+}
 function secureIiisUrl(value) {
     const url = new URL(value);
     if (url.protocol !== "https:" || url.username !== "" || url.password !== "") {
@@ -209,6 +222,71 @@ function parserProgress(done, total) {
         : 40;
 }
 async function errorFromResponse(response, input) {
+    // Strict post-grant 460 relay marker: status 460, Content-Length exactly 0,
+    // Cache-Control exactly no-store, no Content-Type, empty body. Only that exact
+    // tuple maps to PROTOCOL_MISMATCH (kept operationCreated=true, post-grant); any
+    // header/body/status drift maps to IIIS_UNAVAILABLE and never reflects server
+    // text. Stable L1 JSON errors below are unchanged.
+    if (response.status === 460) {
+        // Reject obvious header drift BEFORE consuming the body: only the exact
+        // {Content-Length: 0, Cache-Control: no-store, no Content-Type} header tuple
+        // is a candidate for the bodyless PROTOCOL_MISMATCH marker. Any header drift
+        // maps straight to IIIS_UNAVAILABLE without reading the body.
+        const exactHeaderMarker = response.headers.get("content-length") === "0"
+            && response.headers.get("cache-control") === "no-store"
+            && !response.headers.has("content-type");
+        if (!exactHeaderMarker) {
+            // Cancel the unconsumed body so a drifting long response cannot leave a
+            // connection alive; never parse or drain it.
+            cancelResponseBody(response);
+            // User-abort precedence: a cancellation during the request must surface as
+            // CANCELED_AFTER_UPLOAD_STARTED, not a generic transport failure.
+            if (input.signal?.aborted)
+                throw canceledAfterUpload();
+            return bridgeError("IIIS_UNAVAILABLE", "IIIS could not complete the parse request.", { retryable: false });
+        }
+        // Bounded emptiness probe: read a bounded single read (one chunk from the
+        // default reader), never an unbounded arrayBuffer. The default reader bounds
+        // total-body buffering but a first read may deliver >1 byte, so the chunk may
+        // be multi-byte — the probe only needs the first read, not BYOB. A null body
+        // is empty by inspection; otherwise peek the first chunk and close the reader.
+        // Bodyless is proven ONLY by a closed stream on the first read (done === true)
+        // — a zero-length non-final chunk is NOT bodyless (secret bytes may follow) and
+        // must degrade to IIIS_UNAVAILABLE. Re-check cancellation immediately after the
+        // await and again before classification so an abort during the probe maps to
+        // CANCELED_AFTER_UPLOAD_STARTED (operationCreated=true, post-grant).
+        let empty = true;
+        try {
+            if (response.body !== null) {
+                const reader = response.body.getReader();
+                try {
+                    const first = await reader.read();
+                    if (input.signal?.aborted)
+                        throw canceledAfterUpload();
+                    empty = first.done === true;
+                }
+                finally {
+                    reader.releaseLock();
+                }
+            }
+        }
+        catch (error) {
+            if (input.signal?.aborted)
+                throw canceledAfterUpload();
+            cancelResponseBody(response);
+            throw bridgeError("IIIS_UNAVAILABLE", "IIIS could not complete the parse request.", { retryable: false });
+        }
+        if (input.signal?.aborted)
+            throw canceledAfterUpload();
+        if (empty) {
+            return bridgeError("PROTOCOL_MISMATCH", "IIIS returned an invalid response contract.", { retryable: false });
+        }
+        // Non-bodyless stream: cancel the remainder (bounded, no drain) so secret bytes
+        // or a long body cannot linger on the wire. The one-byte probe already read the
+        // first chunk; cancel releases the rest without parsing or reflecting it.
+        cancelResponseBody(response);
+        return bridgeError("IIIS_UNAVAILABLE", "IIIS could not complete the parse request.", { retryable: false });
+    }
     try {
         const body = await response.json();
         if (isRecord(body) && typeof body.code === "string") {

package/package.json

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