@cueai/omni-reader-mcp 1.2.0 → 1.2.2

package/README.md

@@ -23,9 +23,10 @@ summarization, Q&A, field extraction — rather than stopping at "parse done".
 ## Requirements
 
 - Node.js 20.12 or newer.
-- Cue API Key: <https://cuecue.cn/api-key>.
-- New accounts receive free credits to try; the current grant and daily allowance follow
-  the server-side onboarding policy and the `doctor` output.
+- Cue API Key: <https://cuecue.cn/hub/api-key>.
+- New accounts can try Omni without paying; see [Free credits](#free-credits) below. The
+  server-side onboarding policy and the `doctor` output are the live authority for current
+  allowances.
 - Configure `CUE_API_KEY` in the agent's secret store or local environment.
   **Never paste the API Key into a conversation.**
 
@@ -38,12 +39,28 @@ 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.
 
+## Free credits
+
+As of 2026-08-14:
+
+- every account receives 10 free credits daily — roughly 150 pages of ordinary documents,
+  75 pages of scanned images or charts, 30 minutes of audio, or 4 minutes of video;
+- new accounts receive a one-time 50-credit gift when obtaining `CUE_API_KEY` (60 credits
+  available on day one, including the daily grant);
+- inviting a new user who registers gives both the inviter and the invitee 50 credits, with
+  no invite limit; when an invited user subscribes, the inviter additionally receives 10% of
+  the invitee's first-month credit quota as a bonus.
+
+When available, the `doctor` output reports the live first-registration gift and daily grant;
+referral rules and conversion ratios follow the server-side onboarding policy. If live values
+differ from the numbers above, report the live values.
+
 ## Installation and configuration
 
 Always use an audited exact version, never an implicit `latest`:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.2.0 setup
+npx -y @cueai/omni-reader-mcp@1.2.2 setup
 ```
 
 The interactive setup supports Hermes, Cursor, Claude Desktop, and generic stdio
@@ -51,9 +68,9 @@ configuration. Non-interactive installation uses the same argument parsing and w
 logic:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.2.0 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
-npx -y @cueai/omni-reader-mcp@1.2.0 setup --client cursor --add-root /absolute/minimum/root --yes --json
-npx -y @cueai/omni-reader-mcp@1.2.0 setup --client claude-desktop --allowed-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.2.2 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.2.2 setup --client cursor --add-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.2.2 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
@@ -61,7 +78,7 @@ mode explicitly with `--headless` (alias `--non-interactive`): no `--yes` is req
 stdin is never read:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.2.0 setup --client cursor --allowed-root /absolute/minimum/root --headless --json
+npx -y @cueai/omni-reader-mcp@1.2.2 setup --client cursor --allowed-root /absolute/minimum/root --headless --json
 ```
 
 ## Cache and journal isolation
@@ -181,16 +198,16 @@ new source that satisfies the constraints.
 ## Commands
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.2.0 doctor
-npx -y @cueai/omni-reader-mcp@1.2.0 doctor --json
-npx -y @cueai/omni-reader-mcp@1.2.0 clean
-npx -y @cueai/omni-reader-mcp@1.2.0 uninstall --yes --json
+npx -y @cueai/omni-reader-mcp@1.2.2 doctor
+npx -y @cueai/omni-reader-mcp@1.2.2 doctor --json
+npx -y @cueai/omni-reader-mcp@1.2.2 clean
+npx -y @cueai/omni-reader-mcp@1.2.2 uninstall --yes --json
 ```
 
 Running the pinned version without a command starts the stdio MCP server:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.2.0
+npx -y @cueai/omni-reader-mcp@1.2.2
 ```
 
 `doctor --json` returns package/npm/client adapter, Key present/absent, allowed-root
@@ -199,12 +216,12 @@ status; it never prints the Key, private source paths, or content.
 
 ## Uninstall and rollback
 
-`uninstall --yes --json` removes only the currently trusted 1.2.0 Bridge entry; when a
+`uninstall --yes --json` removes only a trusted 1.2.1 or 1.2.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.
 
-To roll back from 1.1.1:
+To roll back from 1.2.2:
 
 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

@@ -7,6 +7,10 @@ export interface AgentConfigEnvironment {
     readonly env?: Readonly<Record<string, string | undefined>>;
 }
 export type AgentConfigStatus = "configured" | "not configured" | "invalid or unreadable";
+export interface AgentConfigInspection {
+    readonly status: AgentConfigStatus;
+    readonly version?: string;
+}
 interface JsonPreviousEntry {
     readonly format: "json";
     readonly value: unknown;
@@ -40,6 +44,7 @@ export declare function buildAgentEntry(target: AgentTarget, extraRoots: readonl
 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>;
+export declare function inspectAgentConfigDetails(configPath: string, environment?: AgentConfigEnvironment, target?: NativeAgentTarget): Promise<AgentConfigInspection>;
 export declare function inspectAgentConfig(configPath: string, environment?: AgentConfigEnvironment, target?: NativeAgentTarget): Promise<AgentConfigStatus>;
 export declare function detectAgentTargets(environment: AgentConfigEnvironment): Promise<NativeAgentTarget[]>;
 export declare function configContainsOmni(configPath: string): Promise<boolean>;

package/dist/cli/agent-config.js

@@ -4,7 +4,9 @@ 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.2.1";
 const LEGACY_PACKAGE_SPEC = "@cueai/omni-reader-mcp";
+const TRUSTED_EXACT_PACKAGE_SPECS = new Set([PREVIOUS_PACKAGE_SPEC, PACKAGE_SPEC]);
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -543,7 +545,8 @@ function isExpectedOmniEntry(target, value) {
         !Array.isArray(args) ||
         args.length !== 2 ||
         args[0] !== "-y" ||
-        args[1] !== PACKAGE_SPEC)
+        typeof args[1] !== "string" ||
+        !TRUSTED_EXACT_PACKAGE_SPECS.has(args[1]))
         return false;
     const keys = Object.keys(value).sort();
     if (value.env === undefined) {
@@ -579,6 +582,12 @@ function isExpectedOmniEntry(target, value) {
         && keys[1] === "command"
         && keys[2] === "env";
 }
+function expectedBridgeVersion(target, value) {
+    if (!isExpectedOmniEntry(target, value))
+        return undefined;
+    const packageSpec = value.args[1];
+    return packageSpec === PREVIOUS_PACKAGE_SPEC ? "1.2.1" : BRIDGE_RELEASE_VERSION;
+}
 function isLegacyBridgeEntry(target, value) {
     if (!isRecord(value) || value.command !== "npx")
         return false;
@@ -586,7 +595,8 @@ function isLegacyBridgeEntry(target, value) {
     if (!Array.isArray(args) ||
         args.length !== 2 ||
         args[0] !== "-y" ||
-        (args[1] !== LEGACY_PACKAGE_SPEC && args[1] !== PACKAGE_SPEC))
+        typeof args[1] !== "string" ||
+        (args[1] !== LEGACY_PACKAGE_SPEC && !TRUSTED_EXACT_PACKAGE_SPECS.has(args[1])))
         return false;
     if (value.env === undefined)
         return target !== "hermes";
@@ -742,6 +752,7 @@ export async function prepareAgentConfig(target, extraRoots, environment) {
         environment,
         reload: reloadInstruction("hermes"),
         format,
+        serializedBefore: loaded.serialized,
         serializedAfter,
         previousEntry,
     };
@@ -786,9 +797,11 @@ async function atomicReplace(filePath, content) {
         await handle.sync();
         await handle.close();
         handle = undefined;
+        await chmod(temporaryPath, 0o600);
         await rename(temporaryPath, filePath);
-        await chmod(filePath, 0o600);
-        await syncDirectory(directory);
+        // Rename is the commit point. Do not throw afterward: callers cannot safely
+        // roll back a committed user-config write without racing an external editor.
+        await syncDirectory(directory).catch(() => undefined);
     }
     finally {
         await handle?.close();
@@ -912,6 +925,17 @@ export async function verifyPreparedAgentConfig(prepared) {
         throw fileError("The Agent configuration changed after preview; no changes were written.");
     }
 }
+async function restoreTrustedBackup(backupPath, backup) {
+    if (backup !== undefined) {
+        await atomicReplace(backupPath, `${JSON.stringify(backup, null, 2)}\n`);
+        return;
+    }
+    await unlink(backupPath).catch((error) => {
+        if (error.code !== "ENOENT")
+            throw error;
+    });
+    await syncDirectory(path.dirname(backupPath));
+}
 export async function writePreparedAgentConfig(prepared) {
     if (prepared.configPath === undefined ||
         prepared.environment === undefined ||
@@ -919,36 +943,56 @@ export async function writePreparedAgentConfig(prepared) {
         prepared.serializedAfter === undefined)
         return;
     await withConfigLock(prepared.configPath, prepared.environment, async () => {
-        const current = await readConfig(prepared.configPath);
+        const configPath = prepared.configPath;
+        const current = await readConfig(configPath);
         if (current.fingerprint !== prepared.sourceFingerprint) {
             throw fileError("The Agent configuration changed after preview; no changes were written.");
         }
         const backup = trustedBackup(prepared);
-        const backupPath = agentBackupPath(prepared.configPath);
-        const existingBackup = await readTrustedBackup(prepared.configPath);
-        if (existingBackup === undefined) {
-            await atomicReplace(backupPath, `${JSON.stringify(backup, null, 2)}\n`);
-        }
-        else {
-            const currentEntryMatches = await configHasExpectedEntry(prepared.target, current);
-            if (currentEntryMatches && existingBackup.target === prepared.target) {
-                const updatedBackup = {
+        const backupPath = agentBackupPath(configPath);
+        const existingBackup = await readTrustedBackup(configPath);
+        let replacementBackup = backup;
+        if (existingBackup !== undefined) {
+            const currentEntry = expectedConfigEntry(prepared.target, current);
+            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.");
+                }
+                replacementBackup = {
                     ...existingBackup,
                     bridge_entry_digest: entryDigest(prepared.entry),
                 };
-                if (JSON.stringify(updatedBackup) !== JSON.stringify(existingBackup)) {
-                    await atomicReplace(backupPath, `${JSON.stringify(updatedBackup, null, 2)}\n`);
-                }
             }
             else if (JSON.stringify(existingBackup) !== JSON.stringify(backup)) {
                 throw fileError("A conflicting trusted Omni backup already exists; no changes were written.");
             }
+            else {
+                replacementBackup = existingBackup;
+            }
         }
-        const immediatelyBeforeWrite = await readConfig(prepared.configPath);
-        if (immediatelyBeforeWrite.fingerprint !== current.fingerprint) {
-            throw fileError("The Agent configuration changed during setup; no changes were written.");
+        const backupNeedsWrite = existingBackup === undefined ||
+            JSON.stringify(replacementBackup) !== JSON.stringify(existingBackup);
+        try {
+            if (backupNeedsWrite) {
+                await atomicReplace(backupPath, `${JSON.stringify(replacementBackup, null, 2)}\n`);
+            }
+            const immediatelyBeforeWrite = await readConfig(configPath);
+            if (immediatelyBeforeWrite.fingerprint !== current.fingerprint) {
+                throw fileError("The Agent configuration changed during setup; no changes were written.");
+            }
+            await atomicReplace(configPath, prepared.serializedAfter);
+        }
+        catch (error) {
+            try {
+                if (backupNeedsWrite) {
+                    await restoreTrustedBackup(backupPath, existingBackup);
+                }
+            }
+            catch {
+                throw fileError("The Agent configuration write failed and trusted rollback state could not be restored.");
+            }
+            throw error;
         }
-        await atomicReplace(prepared.configPath, prepared.serializedAfter);
     });
 }
 function jsonConfigEntry(value) {
@@ -956,49 +1000,64 @@ function jsonConfigEntry(value) {
         return undefined;
     return onlyOmniEntry(value.mcpServers).value;
 }
-async function configHasExpectedEntry(target, loaded) {
+function expectedConfigEntry(target, loaded) {
     if (target === "hermes") {
         const document = parseHermesDocument(loaded.serialized);
         const entry = hermesOmniEntry(document);
-        return entry !== undefined && isExpectedOmniEntry(target, parseHermesEntry(entry));
+        if (entry === undefined)
+            return undefined;
+        const value = parseHermesEntry(entry);
+        return isExpectedOmniEntry(target, value) ? value : undefined;
     }
     assertNoDuplicateJsonOmniEntries(loaded.serialized);
-    const value = parseJsonConfig(loaded);
-    return isExpectedOmniEntry(target, jsonConfigEntry(value));
+    const value = jsonConfigEntry(parseJsonConfig(loaded));
+    return isExpectedOmniEntry(target, value) ? value : undefined;
 }
-export async function inspectAgentConfig(configPath, environment, target) {
+async function configHasExpectedEntry(target, loaded) {
+    return expectedConfigEntry(target, loaded) !== undefined;
+}
+export async function inspectAgentConfigDetails(configPath, environment, target) {
     try {
         if (environment !== undefined)
             await validateUserConfigPath(configPath, environment);
         const loaded = await readConfig(configPath);
         if (!loaded.existed)
-            return "not configured";
+            return { status: "not configured" };
         const resolvedTarget = target ?? (configPath.endsWith("config.yaml") ? "hermes" : "cursor");
         if (resolvedTarget === "hermes") {
             const document = parseHermesDocument(loaded.serialized);
             const entry = hermesOmniEntry(document);
             if (entry === undefined)
-                return "not configured";
+                return { status: "not configured" };
             const value = parseHermesEntry(entry);
-            if (isExpectedOmniEntry("hermes", value))
-                return "configured";
-            return isCanonicalRemoteEntry(value) ? "not configured" : "invalid or unreadable";
+            const version = expectedBridgeVersion("hermes", value);
+            if (version !== undefined)
+                return { status: "configured", version };
+            return {
+                status: isCanonicalRemoteEntry(value) ? "not configured" : "invalid or unreadable",
+            };
         }
         assertNoDuplicateJsonOmniEntries(loaded.serialized);
         const value = parseJsonConfig(loaded);
         if (!isRecord(value.mcpServers))
-            return "not configured";
+            return { status: "not configured" };
         const entry = onlyOmniEntry(value.mcpServers).value;
         if (entry === undefined)
-            return "not configured";
-        if (isExpectedOmniEntry(resolvedTarget, entry))
-            return "configured";
-        return isCanonicalRemoteEntry(entry) ? "not configured" : "invalid or unreadable";
+            return { status: "not configured" };
+        const version = expectedBridgeVersion(resolvedTarget, entry);
+        if (version !== undefined)
+            return { status: "configured", version };
+        return {
+            status: isCanonicalRemoteEntry(entry) ? "not configured" : "invalid or unreadable",
+        };
     }
     catch {
-        return "invalid or unreadable";
+        return { status: "invalid or unreadable" };
     }
 }
+export async function inspectAgentConfig(configPath, environment, target) {
+    return (await inspectAgentConfigDetails(configPath, environment, target)).status;
+}
 export async function detectAgentTargets(environment) {
     const detected = [];
     for (const target of ["hermes", "cursor", "claude-desktop"]) {
@@ -1056,6 +1115,15 @@ export async function rollbackPreparedAgentConfig(prepared) {
         if (!current.existed || current.serialized !== prepared.serializedAfter) {
             throw fileError("The Agent configuration changed before rollback; automatic rollback stopped.");
         }
+        const backupPath = agentBackupPath(prepared.configPath);
+        const backup = await readTrustedBackup(prepared.configPath);
+        const predecessor = prepared.existed
+            ? expectedConfigEntry(prepared.target, {
+                existed: true,
+                serialized: prepared.serializedBefore,
+                fingerprint: prepared.sourceFingerprint ?? "unused",
+            })
+            : undefined;
         if (prepared.existed) {
             await atomicReplace(prepared.configPath, prepared.serializedBefore);
         }
@@ -1063,10 +1131,22 @@ export async function rollbackPreparedAgentConfig(prepared) {
             await unlink(prepared.configPath);
             await syncDirectory(path.dirname(prepared.configPath));
         }
-        await unlink(agentBackupPath(prepared.configPath)).catch((error) => {
-            if (error.code !== "ENOENT")
-                throw error;
-        });
+        if (backup !== undefined &&
+            predecessor !== undefined &&
+            backup.target === prepared.target &&
+            backup.source_fingerprint !== prepared.sourceFingerprint) {
+            const restoredBackup = {
+                ...backup,
+                bridge_entry_digest: entryDigest(predecessor),
+            };
+            await atomicReplace(backupPath, `${JSON.stringify(restoredBackup, null, 2)}\n`);
+        }
+        else {
+            await unlink(backupPath).catch((error) => {
+                if (error.code !== "ENOENT")
+                    throw error;
+            });
+        }
         await syncDirectory(path.dirname(prepared.configPath));
     });
 }

package/dist/cli/doctor.js

@@ -1,9 +1,9 @@
 import { constants as fsConstants } from "node:fs";
 import { lstat, open, readdir } from "node:fs/promises";
 import path from "node:path";
-import { BRIDGE_RELEASE_VERSION, DEFAULT_CUBE_BASE_URL, GRANTED_STREAM_PROTOCOL_VERSION, MAX_FILE_BYTES, CUBE_GRANT_PROTOCOL_VERSION, } from "../constants.js";
+import { DEFAULT_CUBE_BASE_URL, GRANTED_STREAM_PROTOCOL_VERSION, MAX_FILE_BYTES, CUBE_GRANT_PROTOCOL_VERSION, } from "../constants.js";
 import { API_KEY_URL, getOnboardingPolicyWithTimeout, onboardingGuidance, } from "../onboarding-policy.js";
-import { agentConfigPath, inspectAgentConfig, } from "./agent-config.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";
 function isHealthBody(value) {
@@ -137,13 +137,9 @@ async function clientAdapterFacts(options) {
         ["claude_desktop", "claude-desktop"],
     ]) {
         const configPath = agentConfigPath(target, options);
-        const status = configPath === undefined
-            ? "not configured"
-            : await inspectAgentConfig(configPath, options, target);
-        result[label] = {
-            status,
-            ...(status === "configured" ? { version: BRIDGE_RELEASE_VERSION } : {}),
-        };
+        result[label] = configPath === undefined
+            ? { status: "not configured" }
+            : await inspectAgentConfigDetails(configPath, options, target);
     }
     return result;
 }

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.2.0";
+export declare const BRIDGE_RELEASE_VERSION = "1.2.2";
 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.2.0";
+export const BRIDGE_RELEASE_VERSION = "1.2.2";
 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/onboarding-policy.d.ts

@@ -1,10 +1,13 @@
 export declare const ONBOARDING_POLICY_URL = "https://cuecue.cn/api/v1/billing/public/onboarding-policy";
-export declare const API_KEY_URL = "https://cuecue.cn/api-key";
+export declare const API_KEY_URL = "https://cuecue.cn/hub/api-key";
+export declare const LEGACY_API_KEY_URL = "https://cuecue.cn/api-key";
+type ApiKeyUrl = typeof API_KEY_URL | typeof LEGACY_API_KEY_URL;
 export interface OnboardingPolicy {
-    readonly apiKeyUrl: typeof API_KEY_URL;
+    readonly apiKeyUrl: ApiKeyUrl;
     readonly firstRegistrationCredits: number;
     readonly freeDailyCredits: number;
 }
 export declare function getOnboardingPolicy(fetchImpl: typeof fetch, signal: AbortSignal): Promise<OnboardingPolicy | undefined>;
 export declare function onboardingGuidance(policy: OnboardingPolicy | undefined): string;
 export declare function getOnboardingPolicyWithTimeout(fetchImpl: typeof fetch, timeoutMs?: number): Promise<OnboardingPolicy | undefined>;
+export {};

package/dist/onboarding-policy.js

@@ -1,5 +1,6 @@
 export const ONBOARDING_POLICY_URL = "https://cuecue.cn/api/v1/billing/public/onboarding-policy";
-export const API_KEY_URL = "https://cuecue.cn/api-key";
+export const API_KEY_URL = "https://cuecue.cn/hub/api-key";
+export const LEGACY_API_KEY_URL = "https://cuecue.cn/api-key";
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -9,12 +10,16 @@ function boundedCredits(value) {
 function normalizeOnboardingPolicy(value) {
     if (!isRecord(value))
         return undefined;
-    if (value.api_key_url !== API_KEY_URL ||
+    const apiKeyUrl = value.api_key_url;
+    const accepted = apiKeyUrl === API_KEY_URL || apiKeyUrl === LEGACY_API_KEY_URL;
+    if (!accepted ||
         !boundedCredits(value.first_registration) ||
         !boundedCredits(value.free_daily))
         return undefined;
     return {
-        apiKeyUrl: API_KEY_URL,
+        // Preserve the server's actual accepted URL so a legacy-serving backend
+        // keeps working until it flips to the Hub path.
+        apiKeyUrl: apiKeyUrl,
         firstRegistrationCredits: value.first_registration,
         freeDailyCredits: value.free_daily,
     };

package/dist/protocol.js

@@ -64,7 +64,12 @@ export const cancelParseSchema = z
 export const readResultSchema = z
     .object({
     result_id: resultIdSchema,
-    cursor: z.string().min(1).max(2048).optional(),
+    cursor: z
+        .string()
+        .min(1)
+        .max(2048)
+        .describe("Pass the previous result's next_cursor as this cursor.")
+        .optional(),
     max_bytes: z.number().int().min(1).max(RESULT_CHUNK_MAX_BYTES).optional(),
 })
     .strict();

package/dist/remote-client.js

@@ -1,6 +1,7 @@
 import { LATEST_PROTOCOL_VERSION } from "@modelcontextprotocol/sdk/types.js";
 import { parseReaderCapabilities, selectUrlProfile, } from "./capabilities.js";
 import { BRIDGE_RELEASE_VERSION, REMOTE_CAPABILITIES_CUSTOM_FIELD, REMOTE_OMNI_MCP_URL, } from "./constants.js";
+import { API_KEY_URL } from "./onboarding-policy.js";
 import { OmniBridgeError } from "./errors.js";
 import { parseResultSchema } from "./result-contract.js";
 import { classifySource } from "./source.js";
@@ -185,8 +186,29 @@ function decodeEnvelope(value, requestId) {
         throw protocolError();
     }
     const result = envelope.result;
+    let candidate = result.structuredContent;
+    if (candidate === undefined) {
+        const content = result.content;
+        if (!Array.isArray(content) || content.length !== 1) {
+            throw protocolError();
+        }
+        const item = content[0];
+        if (item === null
+            || typeof item !== "object"
+            || Array.isArray(item)
+            || item.type !== "text"
+            || typeof item.text !== "string") {
+            throw protocolError();
+        }
+        try {
+            candidate = JSON.parse(item.text);
+        }
+        catch {
+            throw protocolError();
+        }
+    }
     try {
-        return parseResultSchema.parse(result.structuredContent);
+        return parseResultSchema.parse(candidate);
     }
     catch {
         throw protocolError();
@@ -206,7 +228,7 @@ export class HttpRemoteOmniClient {
                 code: "API_KEY_REQUIRED",
                 message: "A Cue API Key is required for Omni parsing.",
                 failureScope: "authentication",
-                userAction: "Create or configure an API Key at https://cuecue.cn/api-key without pasting it into chat.",
+                userAction: `Create or configure an API Key at ${API_KEY_URL} without pasting it into chat.`,
                 operationCreated: false,
                 retryable: false,
             });
@@ -301,7 +323,10 @@ export class HttpRemoteOmniClient {
                 retryable: false,
             });
         }
-        let args = { source: classified.source };
+        let args = {
+            source: classified.source,
+            wait: false,
+        };
         if (detail === "grounded" || detail === "layout") {
             // D2-D Task 14: the URL profile is obtained and selected BEFORE any
             // non-text tools/call is constructed. Detail is sent only for a valid
@@ -309,7 +334,7 @@ export class HttpRemoteOmniClient {
             // UNSUPPORTED_DETAIL and zero tools/call requests.
             const capabilities = await this.initializeCapabilities(signal);
             selectUrlProfile(capabilities, detail);
-            args = { source: classified.source, detail };
+            args = { source: classified.source, detail, wait: false };
         }
         return this.#call("parse", args, clientRequestId, signal);
     }

package/dist/result-contract.d.ts

@@ -70,11 +70,19 @@ export type ParseResult = {
     status: "canceled";
     operation_id: string;
     cleanup_deadline?: string;
+    billing?: {
+        credits_charged: number;
+        credits_remaining: number;
+    };
     data_handling: DataHandling;
 } | {
     status: "expired";
     operation_id: string;
     requires_user_confirmation: true;
+    billing?: {
+        credits_charged: number;
+        credits_remaining: number;
+    };
 };
 export declare const stableErrorSchema: z.ZodObject<{
     ok: z.ZodLiteral<false>;

package/dist/result-contract.js

@@ -2,6 +2,11 @@ import { z } from "zod";
 import { RESULT_BUNDLE_PROTOCOL_VERSION } from "./protocol.js";
 const operationIdSchema = z.string().min(1).max(128);
 const resultIdSchema = z.string().regex(/^result_[A-Za-z0-9_-]{16,64}$/u);
+const nextCursorSchema = z
+    .string()
+    .min(1)
+    .max(2048)
+    .describe("Pass this value as cursor in the next read_result call.");
 const constraintsSchema = z
     .object({
     max_bytes: z.number().int().nonnegative().optional(),
@@ -76,7 +81,7 @@ const artifactResultSchema = z
     result_bytes: z.number().int().nonnegative(),
     expires_at: z.string().datetime({ offset: true }),
     preview: z.string(),
-    next_cursor: z.string().min(1).max(2048),
+    next_cursor: nextCursorSchema,
 })
     .strict();
 const billingSchema = z
@@ -105,7 +110,7 @@ const contentStorageSchema = z.discriminatedUnion("kind", [
     z
         .object({
         kind: z.literal("artifact"),
-        next_cursor: z.string().min(1).max(2048),
+        next_cursor: nextCursorSchema,
         preview: z.string().optional(),
     })
         .strict(),
@@ -120,7 +125,7 @@ const groundingStorageSchema = z.discriminatedUnion("kind", [
     z
         .object({
         kind: z.literal("artifact"),
-        next_cursor: z.string().min(1).max(2048),
+        next_cursor: nextCursorSchema,
     })
         .strict(),
 ]);
@@ -218,6 +223,7 @@ export const parseResultSchema = z.discriminatedUnion("status", [
         status: z.literal("canceled"),
         operation_id: operationIdSchema,
         cleanup_deadline: z.string().datetime({ offset: true }).optional(),
+        billing: billingSchema.optional(),
         data_handling: dataHandlingSchema,
     })
         .strict(),
@@ -226,6 +232,7 @@ export const parseResultSchema = z.discriminatedUnion("status", [
         status: z.literal("expired"),
         operation_id: operationIdSchema,
         requires_user_confirmation: z.literal(true),
+        billing: billingSchema.optional(),
     })
         .strict(),
 ]);
@@ -235,7 +242,7 @@ const resultChunkSchema = z
     result_bytes: z.number().int().nonnegative(),
     expires_at: z.string().datetime({ offset: true }),
     text: z.string(),
-    next_cursor: z.string().min(1).max(2048).optional(),
+    next_cursor: nextCursorSchema.optional(),
 })
     .strict();
 // v3 part read (D2-D item 9): closed chunk with part/media type/offset/
@@ -253,7 +260,7 @@ const bundlePartReadChunkSchema = z
         offset: z.number().int().nonnegative(),
         decoded_bytes: z.number().int().nonnegative(),
         text: z.string(),
-        next_cursor: z.string().min(1).max(2048).optional(),
+        next_cursor: nextCursorSchema.optional(),
         expires_at: z.string().datetime({ offset: true }),
     })
         .strict(),
@@ -266,7 +273,7 @@ const bundlePartReadChunkSchema = z
         offset: z.number().int().nonnegative(),
         decoded_bytes: z.number().int().nonnegative(),
         text: z.string(),
-        next_cursor: z.string().min(1).max(2048).optional(),
+        next_cursor: nextCursorSchema.optional(),
         expires_at: z.string().datetime({ offset: true }),
     })
         .strict(),

package/dist/tools.js

@@ -452,7 +452,7 @@ export function registerOmniTools(server, dependencies, taskStore) {
         },
     }, (args, extra) => callCancel(args.operation_id, extra, dependencies));
     server.registerTool("read_result", {
-        description: "Read one UTF-8 chunk from a Bridge-created local result artifact.",
+        description: "Read one UTF-8 chunk from a Bridge-created local result artifact. Pass each returned next_cursor as cursor in the next call until it is absent.",
         inputSchema: readResultSchema,
         outputSchema: readResultToolOutputSchema,
         annotations: {

package/package.json

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