@cueai/omni-reader-mcp 1.6.0 → 1.7.0

package/README.md

@@ -28,7 +28,7 @@ rather than stopping at "parse done".
 
 - Node.js 20.12 or newer.
 - Cue API Key: <https://cuecue.cn/hub/api-key>.
-- New accounts can try Omni without paying; see [Free credits](#free-credits) below. The
+- New accounts can try Omni without paying; see [Free credits](#billing-and-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.
@@ -48,17 +48,37 @@ agent workspace remains the default allowed scope.
 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.6.0` using the official setup instructions, then retry the
+install `@cueai/omni-reader-mcp@1.7.0` using the official setup instructions, then retry the
 same parse. Always run `doctor --json` first when diagnosing a parse failure.
 
-## Free credits
+## Billing and free credits
 
-The server-side onboarding policy is the authority for the current first-registration gift
-and daily grant. When reachable, `doctor` reports those live policy values; when unavailable,
-it reports that status instead of copying a stale number.
+The server-side [onboarding policy](https://cuecue.cn/api/v1/billing/public/onboarding-policy)
+is the authority for the current first-registration gift and daily grant. When reachable,
+`doctor` reports those live policy values; when unavailable, it reports that status instead
+of copying a stale number.
+
+A terminal URL or local-file result may carry the operation-local settlement snapshot:
+
+```json
+{
+  "billing": {
+    "credits_charged": 0.134,
+    "credits_remaining": 42.866
+  }
+}
+```
+
+The numbers above illustrate the response shape, not a price quote. The settled result is authoritative.
+`credits_charged` is the amount deducted for that operation and
+`credits_remaining` is the balance in the same immutable settlement snapshot. Bridge never
+replaces it with a later balance lookup. Processing results have no billing block. New direct
+canceled, failed, unsupported, or denied terminals are uncharged and carry no billing block.
+Navigation and status calls preserve the same settled facts without creating another usage or
+settlement identity.
 
 Bridge does not publish static document-page or media-duration conversions. Rates can change,
-and Phase 1 has no public rate response carrying an `effective_at` timestamp. Use only current
+and there is no public rate response carrying an `effective_at` timestamp. Use only current
 authoritative billing/policy facts rather than estimating a charge from copied arithmetic.
 
 ## Installation and configuration
@@ -66,7 +86,7 @@ authoritative billing/policy facts rather than estimating a charge from copied a
 Always use an audited exact version, never an implicit `latest`:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.6.0 setup
+npx -y @cueai/omni-reader-mcp@1.7.0 setup
 ```
 
 The interactive setup supports Hermes, Cursor, Claude Desktop, and generic stdio
@@ -74,9 +94,9 @@ configuration. Non-interactive installation uses the same argument parsing and w
 logic:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.6.0 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
-npx -y @cueai/omni-reader-mcp@1.6.0 setup --client cursor --add-root /absolute/minimum/root --yes --json
-npx -y @cueai/omni-reader-mcp@1.6.0 setup --client claude-desktop --allowed-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.7.0 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.7.0 setup --client cursor --add-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.7.0 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
@@ -84,7 +104,7 @@ mode explicitly with `--headless` (alias `--non-interactive`): no `--yes` is req
 stdin is never read:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.6.0 setup --client cursor --allowed-root /absolute/minimum/root --headless --json
+npx -y @cueai/omni-reader-mcp@1.7.0 setup --client cursor --allowed-root /absolute/minimum/root --headless --json
 ```
 
 ## Windows configuration
@@ -103,14 +123,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.6.0"] }
+   { "command": "cmd", "args": ["/d", "/c", "npx", "-y", "@cueai/omni-reader-mcp@1.7.0"] }
    ```
 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.6.0` gives you that stable
+   A deliberate local `npm install @cueai/omni-reader-mcp@1.7.0` 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
@@ -149,6 +169,8 @@ Configuration never writes the API Key in plaintext. Hermes uses native separate
 
 ## Agent calling rules
 
+`parse` is the only first-call entry for both HTTP(S) URLs and local paths. Agents choose continuation tools automatically from the structured result instead of presenting a tool menu to the user.
+
 Agents pass the user-provided source string directly to `parse(source)`:
 
 - Only HTTP(S) is treated as a URL; a plain string is treated as a local path.
@@ -184,15 +206,15 @@ Safe fallbacks are:
 - Process cwd versus active workspace unknown → do not widen authorization; use cwd and
   explicit roots until the client provides evidence.
 
-The public tools are fixed:
+The physical protocol surfaces stay fixed even though the user sees one Omni Reader:
+
+- The remote-only connector advertises `parse`, `get_parse_status`, and `cancel_parse`.
+- Bridge advertises those same three plus the local-artifact continuation tools
+  `read_result`, `read_outline`, `discard_result`, and `save_result`.
 
-- `parse`
-- `get_parse_status`
-- `cancel_parse`
-- `read_result`
-- `read_outline`
-- `discard_result`
-- `save_result`
+`parse` remains the sole first call. The other six Bridge tools are continuation and
+lifecycle primitives selected from structured operation/result state; they are not modes
+for the user to choose.
 
 Every tool returns `structuredContent` with a strict `outputSchema`, plus an equivalent
 fallback for clients that only read legacy MCP `content[].text`:
@@ -209,6 +231,8 @@ fallback for clients that only read legacy MCP `content[].text`:
   anchored at that heading, so a long result can be jumped into directly instead of only
   advancing sequentially through `next_cursor`. An empty or absent outline is reported
   explicitly, never silently — it never blocks reading the result itself with `read_result`;
+- Text output remains Markdown and may contain headings, lists, GFM tables, and raw HTML tables.
+  It omits grounding/layout sidecars, not all textual structure. An empty outline means no recognized headings; it does not mean the text has no structure;
 - the `discard_result` text JSON explicitly returns `discarded`; never claim deletion on
   call success alone;
 - the `save_result` text JSON contains the written file `path` and `bytes` count; there is
@@ -280,16 +304,16 @@ satisfies the constraints.
 ## Commands
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.6.0 doctor
-npx -y @cueai/omni-reader-mcp@1.6.0 doctor --json
-npx -y @cueai/omni-reader-mcp@1.6.0 clean
-npx -y @cueai/omni-reader-mcp@1.6.0 uninstall --yes --json
+npx -y @cueai/omni-reader-mcp@1.7.0 doctor
+npx -y @cueai/omni-reader-mcp@1.7.0 doctor --json
+npx -y @cueai/omni-reader-mcp@1.7.0 clean
+npx -y @cueai/omni-reader-mcp@1.7.0 uninstall --yes --json
 ```
 
 Running the pinned version without a command starts the stdio MCP server:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.6.0
+npx -y @cueai/omni-reader-mcp@1.7.0
 ```
 
 Default `doctor --json` reports `inspection_scope: "current_process_env"`: its Key and
@@ -297,7 +321,7 @@ allowed-root facts describe the doctor process, not a separately running agent c
 inspect one caller-selected JSON entry without scanning or writing configuration, use:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.6.0 doctor --json --config-path /absolute/client-config.json --server-name omni-reader
+npx -y @cueai/omni-reader-mcp@1.7.0 doctor --json --config-path /absolute/client-config.json --server-name omni-reader
 ```
 
 The optional `explicit_config` block reports only closed redacted facts: entry/transport
@@ -315,14 +339,17 @@ definitively "available" until a real local-file parse validates the route.
 
 ## Network diagnostics
 
-Run `npx -y @cueai/omni-reader-mcp@1.6.0 doctor --json` first. Diagnose failures by
+Run `npx -y @cueai/omni-reader-mcp@1.7.0 doctor --json` first. Diagnose failures by
 stage instead of guessing an endpoint:
 
 | Failure | Stage | Meaning |
 |---|---|---|
 | `CUBE_UNAVAILABLE` | before upload | the control plane could not create a parse grant |
+| `DIRECT_UPLOAD_UNAVAILABLE` | before upload | the service's direct-upload route is unavailable; this is not an account restriction, and HTTP 403 is the account-entitlement signal |
+| `DETAIL_CAPABILITIES_UNAVAILABLE` | before grant | this service does not currently advertise grounded/layout parsing; use text only when Markdown without grounding/layout sidecars is acceptable |
+| `UNSUPPORTED_DETAIL` | before upload | the requested parsing representation/profile is unavailable; do not retry unchanged or describe the account as text-only |
 | `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.6.0` via the official setup, then retry the same parse |
+| `BRIDGE_UPGRADE_REQUIRED` | before upload | this Bridge release is too old; install `@cueai/omni-reader-mcp@1.7.0` via the official setup, then retry the same parse |
 | a secure upload-stage failure | after grant creation | the file was granted, but the secure upload stage did 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 |
@@ -341,16 +368,16 @@ the same way from every client.
 
 ## Uninstall and rollback
 
-`uninstall --yes --json` removes only a trusted 1.5.5 or 1.6.0 Bridge entry, plus
+`uninstall --yes --json` removes only a trusted 1.6.0 or 1.7.0 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.6.0 to 1.5.5:
+To roll back from 1.7.0 to 1.6.0:
 
-1. stop recommending or installing 1.6.0;
+1. stop recommending or installing 1.7.0;
 2. run `uninstall --yes --json` to restore the trusted URL-only entry;
-3. if the local facade is still required, run `npx -y @cueai/omni-reader-mcp@1.5.5 setup`;
+3. if the local facade is still required, run `npx -y @cueai/omni-reader-mcp@1.6.0 setup`;
 4. for already-uploaded operations, continue using status recovery so settlement and
    cleanup complete;
 5. keep local results, or have the user explicitly run `discard_result` / `clean`.

package/dist/capabilities.d.ts

@@ -1,6 +1,9 @@
 import { z } from "zod";
+import { type OmniSourceKind } from "./errors.js";
 export declare const READER_CAPABILITIES_PROTOCOL = "omni.reader_capabilities.v1";
+export declare const READER_CAPABILITIES_V2_PROTOCOL = "omni.reader_capabilities.v2";
 export type RequestedDetail = "grounded" | "layout";
+export type RequestedDirectDetailV2 = "text" | RequestedDetail;
 declare const directProfileSchema: z.ZodObject<{
     profile: z.ZodLiteral<"omni.direct_grounding.v1">;
     grant_protocol: z.ZodLiteral<"omni.parse_grant.v3">;
@@ -78,15 +81,139 @@ declare const urlProfileSchema: z.ZodObject<{
     details: ["grounded", "layout"];
     max_result_bytes: 16777216;
 }>;
+export declare const DIRECT_TEXT_BILLING_PROFILE: {
+    readonly profile: "omni.direct_text_billing.v1";
+    readonly grant_protocol: "omni.parse_grant.v4";
+    readonly stream_protocol: "omni.granted_parse_stream.v3";
+    readonly operation_protocol: "omni.direct_operation.v3";
+    readonly settlement_protocol: "omni.grant_settlement.v5";
+    readonly release_protocol: "omni.release_decision.v3";
+    readonly settlement_journal_protocol: "omni.direct_settlement_journal.v3";
+    readonly usage_protocol: "omni_parse_usage.v2";
+    readonly billing_protocol: "omni_billing.v2";
+    readonly bridge_protocol: "omni.local_bridge_tools.v5";
+    readonly details: readonly ["text"];
+    readonly max_result_bytes: 268435456;
+};
+export declare const DIRECT_GROUNDING_BILLING_PROFILE: {
+    readonly profile: "omni.direct_grounding_billing.v1";
+    readonly grant_protocol: "omni.parse_grant.v4";
+    readonly stream_protocol: "omni.granted_parse_stream.v3";
+    readonly operation_protocol: "omni.direct_operation.v3";
+    readonly settlement_protocol: "omni.grant_settlement.v5";
+    readonly release_protocol: "omni.release_decision.v3";
+    readonly settlement_journal_protocol: "omni.direct_settlement_journal.v3";
+    readonly usage_protocol: "omni_parse_usage.v2";
+    readonly billing_protocol: "omni_billing.v2";
+    readonly bridge_protocol: "omni.local_bridge_tools.v5";
+    readonly bundle_protocol: "omni.result_bundle.v1";
+    readonly grounding_schema: "omni.grounding.v1";
+    readonly details: readonly ["grounded", "layout"];
+    readonly max_result_bytes: 67108864;
+};
+declare const directProfileV2Schema: z.ZodDiscriminatedUnion<"profile", [z.ZodObject<{
+    profile: z.ZodLiteral<"omni.direct_text_billing.v1">;
+    grant_protocol: z.ZodLiteral<"omni.parse_grant.v4">;
+    stream_protocol: z.ZodLiteral<"omni.granted_parse_stream.v3">;
+    operation_protocol: z.ZodLiteral<"omni.direct_operation.v3">;
+    settlement_protocol: z.ZodLiteral<"omni.grant_settlement.v5">;
+    release_protocol: z.ZodLiteral<"omni.release_decision.v3">;
+    settlement_journal_protocol: z.ZodLiteral<"omni.direct_settlement_journal.v3">;
+    usage_protocol: z.ZodLiteral<"omni_parse_usage.v2">;
+    billing_protocol: z.ZodLiteral<"omni_billing.v2">;
+    bridge_protocol: z.ZodLiteral<"omni.local_bridge_tools.v5">;
+    details: z.ZodTuple<[z.ZodLiteral<"text">], null>;
+    max_result_bytes: z.ZodLiteral<268435456>;
+}, "strict", z.ZodTypeAny, {
+    profile: "omni.direct_text_billing.v1";
+    grant_protocol: "omni.parse_grant.v4";
+    stream_protocol: "omni.granted_parse_stream.v3";
+    operation_protocol: "omni.direct_operation.v3";
+    settlement_protocol: "omni.grant_settlement.v5";
+    release_protocol: "omni.release_decision.v3";
+    settlement_journal_protocol: "omni.direct_settlement_journal.v3";
+    usage_protocol: "omni_parse_usage.v2";
+    billing_protocol: "omni_billing.v2";
+    bridge_protocol: "omni.local_bridge_tools.v5";
+    details: ["text"];
+    max_result_bytes: 268435456;
+}, {
+    profile: "omni.direct_text_billing.v1";
+    grant_protocol: "omni.parse_grant.v4";
+    stream_protocol: "omni.granted_parse_stream.v3";
+    operation_protocol: "omni.direct_operation.v3";
+    settlement_protocol: "omni.grant_settlement.v5";
+    release_protocol: "omni.release_decision.v3";
+    settlement_journal_protocol: "omni.direct_settlement_journal.v3";
+    usage_protocol: "omni_parse_usage.v2";
+    billing_protocol: "omni_billing.v2";
+    bridge_protocol: "omni.local_bridge_tools.v5";
+    details: ["text"];
+    max_result_bytes: 268435456;
+}>, z.ZodObject<{
+    profile: z.ZodLiteral<"omni.direct_grounding_billing.v1">;
+    grant_protocol: z.ZodLiteral<"omni.parse_grant.v4">;
+    stream_protocol: z.ZodLiteral<"omni.granted_parse_stream.v3">;
+    operation_protocol: z.ZodLiteral<"omni.direct_operation.v3">;
+    settlement_protocol: z.ZodLiteral<"omni.grant_settlement.v5">;
+    release_protocol: z.ZodLiteral<"omni.release_decision.v3">;
+    settlement_journal_protocol: z.ZodLiteral<"omni.direct_settlement_journal.v3">;
+    usage_protocol: z.ZodLiteral<"omni_parse_usage.v2">;
+    billing_protocol: z.ZodLiteral<"omni_billing.v2">;
+    bridge_protocol: z.ZodLiteral<"omni.local_bridge_tools.v5">;
+    bundle_protocol: z.ZodLiteral<"omni.result_bundle.v1">;
+    grounding_schema: z.ZodLiteral<"omni.grounding.v1">;
+    details: z.ZodTuple<[z.ZodLiteral<"grounded">, z.ZodLiteral<"layout">], null>;
+    max_result_bytes: z.ZodLiteral<67108864>;
+}, "strict", z.ZodTypeAny, {
+    profile: "omni.direct_grounding_billing.v1";
+    grant_protocol: "omni.parse_grant.v4";
+    stream_protocol: "omni.granted_parse_stream.v3";
+    operation_protocol: "omni.direct_operation.v3";
+    settlement_protocol: "omni.grant_settlement.v5";
+    release_protocol: "omni.release_decision.v3";
+    settlement_journal_protocol: "omni.direct_settlement_journal.v3";
+    usage_protocol: "omni_parse_usage.v2";
+    billing_protocol: "omni_billing.v2";
+    bridge_protocol: "omni.local_bridge_tools.v5";
+    bundle_protocol: "omni.result_bundle.v1";
+    grounding_schema: "omni.grounding.v1";
+    details: ["grounded", "layout"];
+    max_result_bytes: 67108864;
+}, {
+    profile: "omni.direct_grounding_billing.v1";
+    grant_protocol: "omni.parse_grant.v4";
+    stream_protocol: "omni.granted_parse_stream.v3";
+    operation_protocol: "omni.direct_operation.v3";
+    settlement_protocol: "omni.grant_settlement.v5";
+    release_protocol: "omni.release_decision.v3";
+    settlement_journal_protocol: "omni.direct_settlement_journal.v3";
+    usage_protocol: "omni_parse_usage.v2";
+    billing_protocol: "omni_billing.v2";
+    bridge_protocol: "omni.local_bridge_tools.v5";
+    bundle_protocol: "omni.result_bundle.v1";
+    grounding_schema: "omni.grounding.v1";
+    details: ["grounded", "layout"];
+    max_result_bytes: 67108864;
+}>]>;
 export type DirectProfileV1 = z.infer<typeof directProfileSchema>;
 export type UrlProfileV1 = z.infer<typeof urlProfileSchema>;
+export type DirectProfileV2 = z.infer<typeof directProfileV2Schema>;
+export type DirectProfile = DirectProfileV1["profile"] | DirectProfileV2["profile"];
 export interface ReaderCapabilitiesV1 {
     readonly protocol_version: typeof READER_CAPABILITIES_PROTOCOL;
     readonly expires_at: Date;
     readonly direct_profiles: readonly DirectProfileV1[];
     readonly url_profiles: readonly UrlProfileV1[];
 }
+export interface ReaderCapabilitiesV2 {
+    readonly protocol_version: typeof READER_CAPABILITIES_V2_PROTOCOL;
+    readonly expires_at: Date;
+    readonly direct_profiles: readonly DirectProfileV2[];
+}
 export declare function parseReaderCapabilities(value: unknown, now: Date): ReaderCapabilitiesV1;
-export declare function selectDirectProfile(value: ReaderCapabilitiesV1, detail: RequestedDetail): DirectProfileV1;
-export declare function selectUrlProfile(value: ReaderCapabilitiesV1, detail: RequestedDetail): UrlProfileV1;
+export declare function selectDirectProfile(value: ReaderCapabilitiesV1, detail: RequestedDetail, sourceKind?: OmniSourceKind): DirectProfileV1;
+export declare function selectUrlProfile(value: ReaderCapabilitiesV1, detail: RequestedDetail, sourceKind?: OmniSourceKind): UrlProfileV1;
+export declare function parseReaderCapabilitiesV2(value: unknown, now: Date): ReaderCapabilitiesV2;
+export declare function selectDirectProfileV2(value: ReaderCapabilitiesV2, detail: RequestedDirectDetailV2, sourceKind?: OmniSourceKind): DirectProfileV2;
 export {};

package/dist/capabilities.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
-import { OmniBridgeError } from "./errors.js";
+import { OmniBridgeError, unsupportedDetailError, } from "./errors.js";
 export const READER_CAPABILITIES_PROTOCOL = "omni.reader_capabilities.v1";
+export const READER_CAPABILITIES_V2_PROTOCOL = "omni.reader_capabilities.v2";
 // Closed consumer-side schema for `omni.reader_capabilities.v1` (D2-D item 4).
 // Objects/arrays are closed: profile names and every tuple member are exact
 // literals, `details` is the exact ordered tuple ["grounded", "layout"], and a
@@ -40,6 +41,74 @@ const urlProfileSchema = z
     max_result_bytes: z.literal(16777216),
 })
     .strict();
+export const DIRECT_TEXT_BILLING_PROFILE = {
+    profile: "omni.direct_text_billing.v1",
+    grant_protocol: "omni.parse_grant.v4",
+    stream_protocol: "omni.granted_parse_stream.v3",
+    operation_protocol: "omni.direct_operation.v3",
+    settlement_protocol: "omni.grant_settlement.v5",
+    release_protocol: "omni.release_decision.v3",
+    settlement_journal_protocol: "omni.direct_settlement_journal.v3",
+    usage_protocol: "omni_parse_usage.v2",
+    billing_protocol: "omni_billing.v2",
+    bridge_protocol: "omni.local_bridge_tools.v5",
+    details: ["text"],
+    max_result_bytes: 268435456,
+};
+export const DIRECT_GROUNDING_BILLING_PROFILE = {
+    profile: "omni.direct_grounding_billing.v1",
+    grant_protocol: "omni.parse_grant.v4",
+    stream_protocol: "omni.granted_parse_stream.v3",
+    operation_protocol: "omni.direct_operation.v3",
+    settlement_protocol: "omni.grant_settlement.v5",
+    release_protocol: "omni.release_decision.v3",
+    settlement_journal_protocol: "omni.direct_settlement_journal.v3",
+    usage_protocol: "omni_parse_usage.v2",
+    billing_protocol: "omni_billing.v2",
+    bridge_protocol: "omni.local_bridge_tools.v5",
+    bundle_protocol: "omni.result_bundle.v1",
+    grounding_schema: "omni.grounding.v1",
+    details: ["grounded", "layout"],
+    max_result_bytes: 67108864,
+};
+const directTextBillingProfileSchema = z
+    .object({
+    profile: z.literal(DIRECT_TEXT_BILLING_PROFILE.profile),
+    grant_protocol: z.literal(DIRECT_TEXT_BILLING_PROFILE.grant_protocol),
+    stream_protocol: z.literal(DIRECT_TEXT_BILLING_PROFILE.stream_protocol),
+    operation_protocol: z.literal(DIRECT_TEXT_BILLING_PROFILE.operation_protocol),
+    settlement_protocol: z.literal(DIRECT_TEXT_BILLING_PROFILE.settlement_protocol),
+    release_protocol: z.literal(DIRECT_TEXT_BILLING_PROFILE.release_protocol),
+    settlement_journal_protocol: z.literal(DIRECT_TEXT_BILLING_PROFILE.settlement_journal_protocol),
+    usage_protocol: z.literal(DIRECT_TEXT_BILLING_PROFILE.usage_protocol),
+    billing_protocol: z.literal(DIRECT_TEXT_BILLING_PROFILE.billing_protocol),
+    bridge_protocol: z.literal(DIRECT_TEXT_BILLING_PROFILE.bridge_protocol),
+    details: z.tuple([z.literal("text")]),
+    max_result_bytes: z.literal(DIRECT_TEXT_BILLING_PROFILE.max_result_bytes),
+})
+    .strict();
+const directGroundingBillingProfileSchema = z
+    .object({
+    profile: z.literal(DIRECT_GROUNDING_BILLING_PROFILE.profile),
+    grant_protocol: z.literal(DIRECT_GROUNDING_BILLING_PROFILE.grant_protocol),
+    stream_protocol: z.literal(DIRECT_GROUNDING_BILLING_PROFILE.stream_protocol),
+    operation_protocol: z.literal(DIRECT_GROUNDING_BILLING_PROFILE.operation_protocol),
+    settlement_protocol: z.literal(DIRECT_GROUNDING_BILLING_PROFILE.settlement_protocol),
+    release_protocol: z.literal(DIRECT_GROUNDING_BILLING_PROFILE.release_protocol),
+    settlement_journal_protocol: z.literal(DIRECT_GROUNDING_BILLING_PROFILE.settlement_journal_protocol),
+    usage_protocol: z.literal(DIRECT_GROUNDING_BILLING_PROFILE.usage_protocol),
+    billing_protocol: z.literal(DIRECT_GROUNDING_BILLING_PROFILE.billing_protocol),
+    bridge_protocol: z.literal(DIRECT_GROUNDING_BILLING_PROFILE.bridge_protocol),
+    bundle_protocol: z.literal(DIRECT_GROUNDING_BILLING_PROFILE.bundle_protocol),
+    grounding_schema: z.literal(DIRECT_GROUNDING_BILLING_PROFILE.grounding_schema),
+    details: z.tuple([z.literal("grounded"), z.literal("layout")]),
+    max_result_bytes: z.literal(DIRECT_GROUNDING_BILLING_PROFILE.max_result_bytes),
+})
+    .strict();
+const directProfileV2Schema = z.discriminatedUnion("profile", [
+    directTextBillingProfileSchema,
+    directGroundingBillingProfileSchema,
+]);
 const readerCapabilitiesSchema = z
     .object({
     protocol_version: z.literal(READER_CAPABILITIES_PROTOCOL),
@@ -48,6 +117,13 @@ const readerCapabilitiesSchema = z
     url_profiles: z.array(urlProfileSchema),
 })
     .strict();
+const readerCapabilitiesV2Schema = z
+    .object({
+    protocol_version: z.literal(READER_CAPABILITIES_V2_PROTOCOL),
+    expires_at: z.string().datetime({ offset: true }),
+    direct_profiles: z.array(directProfileV2Schema).length(2),
+})
+    .strict();
 function invalidCapabilities() {
     return new OmniBridgeError({
         code: "INVALID_READER_CAPABILITIES",
@@ -61,20 +137,6 @@ function invalidCapabilities() {
         retryable: false,
     });
 }
-function unsupportedDetail() {
-    return new OmniBridgeError({
-        code: "UNSUPPORTED_DETAIL",
-        message: "This Omni service does not support the requested output detail.",
-        failureScope: "service",
-        userAction: "Use plain Markdown output for this source.",
-        operationCreated: false,
-        fileUploaded: false,
-        parserStarted: false,
-        billed: false,
-        contentReleased: false,
-        retryable: false,
-    });
-}
 export function parseReaderCapabilities(value, now) {
     let parsed;
     try {
@@ -109,15 +171,56 @@ export function parseReaderCapabilities(value, now) {
         url_profiles: parsed.url_profiles,
     };
 }
-export function selectDirectProfile(value, detail) {
+export function selectDirectProfile(value, detail, sourceKind) {
     const profile = value.direct_profiles.find((candidate) => candidate.details.includes(detail));
     if (profile === undefined)
-        throw unsupportedDetail();
+        throw unsupportedDetailError(sourceKind);
     return profile;
 }
-export function selectUrlProfile(value, detail) {
+export function selectUrlProfile(value, detail, sourceKind) {
     const profile = value.url_profiles.find((candidate) => candidate.details.includes(detail));
     if (profile === undefined)
-        throw unsupportedDetail();
+        throw unsupportedDetailError(sourceKind);
+    return profile;
+}
+export function parseReaderCapabilitiesV2(value, now) {
+    let parsed;
+    try {
+        parsed = readerCapabilitiesV2Schema.parse(value);
+    }
+    catch {
+        throw invalidCapabilities();
+    }
+    const expiresAt = new Date(parsed.expires_at);
+    if (Number.isNaN(expiresAt.getTime()) ||
+        expiresAt.getTime() <= now.getTime()) {
+        throw invalidCapabilities();
+    }
+    const profileOrder = new Map([
+        [DIRECT_TEXT_BILLING_PROFILE.profile, 0],
+        [DIRECT_GROUNDING_BILLING_PROFILE.profile, 1],
+    ]);
+    const seen = new Set();
+    let previousOrder = -1;
+    for (const profile of parsed.direct_profiles) {
+        const order = profileOrder.get(profile.profile);
+        if (order === undefined ||
+            seen.has(profile.profile) ||
+            order <= previousOrder) {
+            throw invalidCapabilities();
+        }
+        seen.add(profile.profile);
+        previousOrder = order;
+    }
+    return {
+        protocol_version: parsed.protocol_version,
+        expires_at: expiresAt,
+        direct_profiles: parsed.direct_profiles,
+    };
+}
+export function selectDirectProfileV2(value, detail, sourceKind) {
+    const profile = value.direct_profiles.find((candidate) => candidate.details.includes(detail));
+    if (profile === undefined)
+        throw unsupportedDetailError(sourceKind);
     return profile;
 }

package/dist/cli/agent-config.js

@@ -7,7 +7,7 @@ const PACKAGE_SPEC = `@cueai/omni-reader-mcp@${BRIDGE_RELEASE_VERSION}`;
 // 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.5";
+const PREVIOUS_RELEASE_VERSION = "1.6.0";
 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
@@ -641,7 +641,7 @@ export function expectedBridgeVersion(target, value, platform) {
 }
 function isLegacyBridgeEntry(target, value, platform) {
     // Defer the entire invocation-shape decision to the single platform policy:
-    // exact pinned {1.5.5 previous, 1.6.0 current} plus the exact Windows 1.5.1
+    // exact pinned {1.6.0 previous, 1.7.0 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

package/dist/constants.d.ts

@@ -6,14 +6,18 @@ 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://omni-upload.cuecue.cn/omni/granted/";
-export declare const BRIDGE_RELEASE_VERSION = "1.6.0";
+export declare const BRIDGE_RELEASE_VERSION = "1.7.0";
 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;
 export declare const STATUS_POLL_AFTER_SECONDS = 5;
 export declare const DELIVERY_TTL_SECONDS = 600;
+export declare const CAPABILITIES_V1_PATH = "/api/omni-reader/capabilities/v1";
+export declare const CAPABILITIES_V2_PATH = "/api/omni-reader/capabilities/v2";
 export declare const CUBE_CAPABILITIES_PATH = "/api/omni-reader/capabilities/v1";
 export declare const REMOTE_CAPABILITIES_CUSTOM_FIELD = "cue.omni-reader";
+export declare const SERVER_NEGOTIATED_BRIDGE_PROTOCOL_V1 = "omni.local_bridge_tools.v3";
+export declare const SERVER_NEGOTIATED_BRIDGE_PROTOCOL_V2 = "omni.local_bridge_tools.v5";
 export declare const SERVER_NEGOTIATED_BRIDGE_PROTOCOL_VERSION = "omni.local_bridge_tools.v3";
 export declare const CAPABILITIES_PROTOCOL_VERSION = "omni.reader_capabilities.v1";
 export declare const CAPABILITIES_ENABLED_ENV = "OMNI_CAPABILITIES_ENABLED";

package/dist/constants.js

@@ -6,15 +6,19 @@ 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://omni-upload.cuecue.cn/omni/granted/";
-export const BRIDGE_RELEASE_VERSION = "1.6.0";
+export const BRIDGE_RELEASE_VERSION = "1.7.0";
 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;
 export const STATUS_POLL_AFTER_SECONDS = 5;
 export const DELIVERY_TTL_SECONDS = 600;
-export const CUBE_CAPABILITIES_PATH = "/api/omni-reader/capabilities/v1";
+export const CAPABILITIES_V1_PATH = "/api/omni-reader/capabilities/v1";
+export const CAPABILITIES_V2_PATH = "/api/omni-reader/capabilities/v2";
+export const CUBE_CAPABILITIES_PATH = CAPABILITIES_V1_PATH;
 export const REMOTE_CAPABILITIES_CUSTOM_FIELD = "cue.omni-reader";
-export const SERVER_NEGOTIATED_BRIDGE_PROTOCOL_VERSION = "omni.local_bridge_tools.v3";
+export const SERVER_NEGOTIATED_BRIDGE_PROTOCOL_V1 = "omni.local_bridge_tools.v3";
+export const SERVER_NEGOTIATED_BRIDGE_PROTOCOL_V2 = "omni.local_bridge_tools.v5";
+export const SERVER_NEGOTIATED_BRIDGE_PROTOCOL_VERSION = SERVER_NEGOTIATED_BRIDGE_PROTOCOL_V1;
 // ── omni.reader_capabilities.v1 advertisement (D2-D item 4) ────────────────────────────────
 // The direct profile's 14 exact literal fields mirror the pinned cube-mcp accepted set
 // (contracts/cube-mcp/omni-capabilities/v1); the URL profile's 9 fields belong to the

package/dist/cube-client.d.ts

@@ -1,5 +1,5 @@
 import { BRIDGE_RELEASE_VERSION } from "./constants.js";
-import { type ReaderCapabilitiesV1 } from "./capabilities.js";
+import { type DirectProfile, type ReaderCapabilitiesV1, type ReaderCapabilitiesV2, type RequestedDirectDetailV2 } from "./capabilities.js";
 import { OperationJournal } from "./operation-journal.js";
 declare const BRIDGE_PACKAGE = "@cueai/omni-reader-mcp";
 export interface GrantRequestInput {
@@ -21,6 +21,8 @@ export interface GrantedOperation {
     readonly expiresAt: string;
     readonly maxBytes: number;
     readonly protocolVersion: string;
+    readonly directProfile: DirectProfile | null;
+    readonly requestedDetail: RequestedDirectDetailV2;
 }
 export interface CubeGrantClientOptions {
     readonly journal: OperationJournal;
@@ -46,6 +48,7 @@ export declare class CubeGrantClient {
     #private;
     constructor(options: CubeGrantClientOptions);
     getCapabilities(signal?: AbortSignal): Promise<ReaderCapabilitiesV1>;
+    getCapabilitiesV2(signal?: AbortSignal): Promise<ReaderCapabilitiesV2 | null>;
     createGrant(input: GrantRequestInput, clientRequestId: string, signal?: AbortSignal, options?: {
         journal?: boolean;
     }): Promise<GrantedOperation>;