@cueai/omni-reader-mcp 1.1.3 → 1.2.0

package/dist/capabilities.js

@@ -0,0 +1,123 @@
+import { z } from "zod";
+import { OmniBridgeError } from "./errors.js";
+export const READER_CAPABILITIES_PROTOCOL = "omni.reader_capabilities.v1";
+// 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
+// profile is advertised atomically — never assembled by cross-producting
+// independent lists. Direct-profile literal values mirror the pinned
+// cube-mcp `omni.cube_direct_profiles.v1` accepted set
+// (contracts/cube-mcp/omni-capabilities/v1); the URL profile belongs to the
+// URL-operation control plane per the same contract README.
+const directProfileSchema = z
+    .object({
+    profile: z.literal("omni.direct_grounding.v1"),
+    grant_protocol: z.literal("omni.parse_grant.v3"),
+    stream_protocol: z.literal("omni.granted_parse_stream.v2"),
+    operation_protocol: z.literal("omni.direct_operation.v2"),
+    settlement_protocol: z.literal("omni.grant_settlement.v4"),
+    release_protocol: z.literal("omni.release_decision.v2"),
+    settlement_journal_protocol: z.literal("omni.direct_settlement_journal.v2"),
+    usage_protocol: z.literal("omni_parse_usage.v2"),
+    billing_protocol: z.literal("omni_billing.v2"),
+    bridge_protocol: z.literal("omni.local_bridge_tools.v3"),
+    bundle_protocol: z.literal("omni.result_bundle.v1"),
+    grounding_schema: z.literal("omni.grounding.v1"),
+    details: z.tuple([z.literal("grounded"), z.literal("layout")]),
+    max_result_bytes: z.literal(67108864),
+})
+    .strict();
+const urlProfileSchema = z
+    .object({
+    profile: z.literal("omni.url_grounding.v1"),
+    operation_protocol: z.literal("omni.url_operation.v3"),
+    usage_protocol: z.literal("omni_parse_usage.v2"),
+    billing_protocol: z.literal("omni_billing.v2"),
+    bridge_protocol: z.literal("omni.local_bridge_tools.v3"),
+    bundle_protocol: z.literal("omni.result_bundle.v1"),
+    grounding_schema: z.literal("omni.grounding.v1"),
+    details: z.tuple([z.literal("grounded"), z.literal("layout")]),
+    max_result_bytes: z.literal(16777216),
+})
+    .strict();
+const readerCapabilitiesSchema = z
+    .object({
+    protocol_version: z.literal(READER_CAPABILITIES_PROTOCOL),
+    expires_at: z.string().datetime({ offset: true }),
+    direct_profiles: z.array(directProfileSchema),
+    url_profiles: z.array(urlProfileSchema),
+})
+    .strict();
+function invalidCapabilities() {
+    return new OmniBridgeError({
+        code: "INVALID_READER_CAPABILITIES",
+        message: "The reader capability advertisement is invalid or expired.",
+        failureScope: "service",
+        operationCreated: false,
+        fileUploaded: false,
+        parserStarted: false,
+        billed: false,
+        contentReleased: false,
+        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 {
+        parsed = readerCapabilitiesSchema.parse(value);
+    }
+    catch {
+        throw invalidCapabilities();
+    }
+    // A capability is only cachable up to its exact parsed expiry; an expired or
+    // unparseable `expires_at` advertisement is invalid at negotiation time.
+    const expiresAt = new Date(parsed.expires_at);
+    if (Number.isNaN(expiresAt.getTime()) ||
+        expiresAt.getTime() <= now.getTime()) {
+        throw invalidCapabilities();
+    }
+    // Profiles are advertised atomically; duplicate profile names are invalid.
+    const seen = new Set();
+    for (const profile of parsed.direct_profiles) {
+        if (seen.has(profile.profile))
+            throw invalidCapabilities();
+        seen.add(profile.profile);
+    }
+    for (const profile of parsed.url_profiles) {
+        if (seen.has(profile.profile))
+            throw invalidCapabilities();
+        seen.add(profile.profile);
+    }
+    return {
+        protocol_version: parsed.protocol_version,
+        expires_at: expiresAt,
+        direct_profiles: parsed.direct_profiles,
+        url_profiles: parsed.url_profiles,
+    };
+}
+export function selectDirectProfile(value, detail) {
+    const profile = value.direct_profiles.find((candidate) => candidate.details.includes(detail));
+    if (profile === undefined)
+        throw unsupportedDetail();
+    return profile;
+}
+export function selectUrlProfile(value, detail) {
+    const profile = value.url_profiles.find((candidate) => candidate.details.includes(detail));
+    if (profile === undefined)
+        throw unsupportedDetail();
+    return profile;
+}

package/dist/constants.d.ts

@@ -6,9 +6,42 @@ 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.1.3";
+export declare const BRIDGE_RELEASE_VERSION = "1.2.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 CUBE_CAPABILITIES_PATH = "/api/omni-reader/capabilities/v1";
+export declare const REMOTE_CAPABILITIES_CUSTOM_FIELD = "cue.omni-reader";
+export declare const CAPABILITIES_PROTOCOL_VERSION = "omni.reader_capabilities.v1";
+export declare const CAPABILITIES_ENABLED_ENV = "OMNI_CAPABILITIES_ENABLED";
+export declare const CAPABILITIES_TTL_SECONDS_ENV = "OMNI_CAPABILITIES_TTL_SECONDS";
+export declare const CAPABILITIES_DEFAULT_TTL_SECONDS = 300;
+export declare const DIRECT_GROUNDING_PROFILE: {
+    readonly profile: "omni.direct_grounding.v1";
+    readonly grant_protocol: "omni.parse_grant.v3";
+    readonly stream_protocol: "omni.granted_parse_stream.v2";
+    readonly operation_protocol: "omni.direct_operation.v2";
+    readonly settlement_protocol: "omni.grant_settlement.v4";
+    readonly release_protocol: "omni.release_decision.v2";
+    readonly settlement_journal_protocol: "omni.direct_settlement_journal.v2";
+    readonly usage_protocol: "omni_parse_usage.v2";
+    readonly billing_protocol: "omni_billing.v2";
+    readonly bridge_protocol: "omni.local_bridge_tools.v3";
+    readonly bundle_protocol: "omni.result_bundle.v1";
+    readonly grounding_schema: "omni.grounding.v1";
+    readonly details: readonly ["grounded", "layout"];
+    readonly max_result_bytes: 67108864;
+};
+export declare const URL_GROUNDING_PROFILE: {
+    readonly profile: "omni.url_grounding.v1";
+    readonly operation_protocol: "omni.url_operation.v3";
+    readonly usage_protocol: "omni_parse_usage.v2";
+    readonly billing_protocol: "omni_billing.v2";
+    readonly bridge_protocol: "omni.local_bridge_tools.v3";
+    readonly bundle_protocol: "omni.result_bundle.v1";
+    readonly grounding_schema: "omni.grounding.v1";
+    readonly details: readonly ["grounded", "layout"];
+    readonly max_result_bytes: 16777216;
+};

package/dist/constants.js

@@ -6,9 +6,47 @@ 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.1.3";
+export const BRIDGE_RELEASE_VERSION = "1.2.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 REMOTE_CAPABILITIES_CUSTOM_FIELD = "cue.omni-reader";
+// ── 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
+// URL-operation control plane. Profiles are advertised atomically — never assembled by
+// cross-producting independent lists.
+export const CAPABILITIES_PROTOCOL_VERSION = "omni.reader_capabilities.v1";
+export const CAPABILITIES_ENABLED_ENV = "OMNI_CAPABILITIES_ENABLED";
+export const CAPABILITIES_TTL_SECONDS_ENV = "OMNI_CAPABILITIES_TTL_SECONDS";
+export const CAPABILITIES_DEFAULT_TTL_SECONDS = 300;
+export const DIRECT_GROUNDING_PROFILE = {
+    profile: "omni.direct_grounding.v1",
+    grant_protocol: "omni.parse_grant.v3",
+    stream_protocol: "omni.granted_parse_stream.v2",
+    operation_protocol: "omni.direct_operation.v2",
+    settlement_protocol: "omni.grant_settlement.v4",
+    release_protocol: "omni.release_decision.v2",
+    settlement_journal_protocol: "omni.direct_settlement_journal.v2",
+    usage_protocol: "omni_parse_usage.v2",
+    billing_protocol: "omni_billing.v2",
+    bridge_protocol: "omni.local_bridge_tools.v3",
+    bundle_protocol: "omni.result_bundle.v1",
+    grounding_schema: "omni.grounding.v1",
+    details: ["grounded", "layout"],
+    max_result_bytes: 67108864,
+};
+export const URL_GROUNDING_PROFILE = {
+    profile: "omni.url_grounding.v1",
+    operation_protocol: "omni.url_operation.v3",
+    usage_protocol: "omni_parse_usage.v2",
+    billing_protocol: "omni_billing.v2",
+    bridge_protocol: "omni.local_bridge_tools.v3",
+    bundle_protocol: "omni.result_bundle.v1",
+    grounding_schema: "omni.grounding.v1",
+    details: ["grounded", "layout"],
+    max_result_bytes: 16777216,
+};

package/dist/cube-client.d.ts

@@ -1,4 +1,5 @@
 import { BRIDGE_RELEASE_VERSION } from "./constants.js";
+import { type ReaderCapabilitiesV1 } from "./capabilities.js";
 import { OperationJournal } from "./operation-journal.js";
 declare const BRIDGE_PACKAGE = "@cueai/omni-reader-mcp";
 export interface GrantRequestInput {
@@ -7,6 +8,7 @@ export interface GrantRequestInput {
     readonly fileExtension: string;
     readonly noStore: boolean;
     readonly output: "markdown";
+    readonly detail?: "grounded" | "layout";
 }
 export interface GrantedOperation {
     readonly clientRequestId: string;
@@ -43,6 +45,7 @@ export declare function createClientRequestId(): string;
 export declare class CubeGrantClient {
     #private;
     constructor(options: CubeGrantClientOptions);
+    getCapabilities(signal?: AbortSignal): Promise<ReaderCapabilitiesV1>;
     createGrant(input: GrantRequestInput, clientRequestId: string, signal?: AbortSignal, options?: {
         journal?: boolean;
     }): Promise<GrantedOperation>;

package/dist/cube-client.js

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { z } from "zod";
-import { BRIDGE_RELEASE_VERSION, CUBE_GRANT_PROTOCOL_VERSION, DEFAULT_CUBE_BASE_URL, MAX_FILE_BYTES, } from "./constants.js";
+import { BRIDGE_RELEASE_VERSION, CUBE_CAPABILITIES_PATH, CUBE_GRANT_PROTOCOL_VERSION, DEFAULT_CUBE_BASE_URL, MAX_FILE_BYTES, } from "./constants.js";
+import { parseReaderCapabilities, selectDirectProfile, } from "./capabilities.js";
 import { OmniBridgeError } from "./errors.js";
 const GRANT_PATH = "/api/omni-reader/direct-upload/v1/parse-grants";
 const BRIDGE_PACKAGE = "@cueai/omni-reader-mcp";
@@ -19,6 +20,28 @@ const grantResponseSchema = z
     protocol_version: z.literal(CUBE_GRANT_PROTOCOL_VERSION),
 })
     .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.
+const grantResponseV3Schema = z
+    .object({
+    grant_id: z.string().min(1),
+    operation_id: z.string().min(1),
+    parse_grant: z.string().min(1),
+    operation_token: z.string().min(1),
+    upload_url: z
+        .string()
+        .url()
+        .refine((value) => new URL(value).protocol === "https:"),
+    expires_at: z.string().datetime({ offset: true }),
+    max_bytes: z.literal(MAX_FILE_BYTES),
+    protocol_version: z.literal("omni.parse_grant.v3"),
+    stream_protocol_version: z.literal("omni.granted_parse_stream.v2"),
+    bundle_protocol_version: z.literal("omni.result_bundle.v1"),
+    detail: z.enum(["grounded", "layout"]),
+    approved_result_max_bytes: z.literal(67108864),
+})
+    .strict();
 function bridgeError(code, message, retryable) {
     return new OmniBridgeError({
         code,
@@ -31,17 +54,18 @@ function bridgeError(code, message, retryable) {
         retryable,
     });
 }
-function grantRequestBody(input) {
+function grantRequestBody(input, profile) {
     if (!Number.isSafeInteger(input.contentLength) ||
         input.contentLength < 0 ||
         input.contentLength > MAX_FILE_BYTES ||
         !/^[^\s;/]+\/[^\s;]+$/u.test(input.contentType) ||
         !/^\.[a-z0-9]{1,10}$/u.test(input.fileExtension) ||
         typeof input.noStore !== "boolean" ||
-        input.output !== "markdown") {
+        input.output !== "markdown" ||
+        (input.detail !== undefined && input.detail !== "grounded" && input.detail !== "layout")) {
         throw bridgeError("INVALID_GRANT_REQUEST", "The local file metadata is invalid for a parse grant.", false);
     }
-    return {
+    const base = {
         content_length: input.contentLength,
         content_type: input.contentType,
         file_extension: input.fileExtension,
@@ -52,6 +76,32 @@ function grantRequestBody(input) {
             version: BRIDGE_RELEASE_VERSION,
         },
     };
+    if (profile === undefined)
+        return base;
+    return {
+        ...base,
+        protocol_version: profile.grant_protocol,
+        stream_protocol_version: profile.stream_protocol,
+        operation_protocol_version: profile.operation_protocol,
+        settlement_protocol_version: profile.settlement_protocol,
+        release_protocol_version: profile.release_protocol,
+        settlement_journal_protocol_version: profile.settlement_journal_protocol,
+        usage_schema_version: profile.usage_protocol,
+        billing_contract_version: profile.billing_protocol,
+        grounding_schema_version: profile.grounding_schema,
+        bundle_protocol_version: profile.bundle_protocol,
+        detail: input.detail,
+        approved_result_max_bytes: profile.max_result_bytes,
+    };
+}
+function requireV3GrantTuple(parsed, profile, detail) {
+    if (parsed.protocol_version !== profile.grant_protocol ||
+        parsed.stream_protocol_version !== profile.stream_protocol ||
+        parsed.bundle_protocol_version !== profile.bundle_protocol ||
+        parsed.detail !== detail ||
+        parsed.approved_result_max_bytes !== profile.max_result_bytes) {
+        throw bridgeError("CUBE_PROTOCOL_ERROR", "Cube returned a parse grant outside the negotiated representation.", false);
+    }
 }
 export function grantRequestHash(body) {
     return `sha256:${createHash("sha256")
@@ -86,7 +136,9 @@ export class CubeGrantClient {
     #journal;
     #apiKey;
     #grantUrl;
+    #capabilitiesUrl;
     #fetch;
+    #capabilitiesCache;
     constructor(options) {
         this.#journal = options.journal;
         this.#apiKey =
@@ -101,13 +153,79 @@ export class CubeGrantClient {
             throw bridgeError("INSECURE_CUBE_BASE_URL", "The Cube control endpoint must use HTTPS without embedded credentials.", false);
         }
         this.#grantUrl = new URL(GRANT_PATH, baseUrl).toString();
+        this.#capabilitiesUrl = new URL(CUBE_CAPABILITIES_PATH, baseUrl).toString();
         this.#fetch = options.fetchImpl ?? fetch;
     }
+    // Preflight for any non-text grant request (D2-D item 4): authenticated
+    // HTTPS GET of the capabilities endpoint, body validated through the closed
+    // `omni.reader_capabilities.v1` schema, and cached only until the exact
+    // parsed `expires_at`. The cache is keyed by this client's fixed
+    // capabilities endpoint; a different endpoint means a different client.
+    async getCapabilities(signal) {
+        if (this.#apiKey.length === 0) {
+            throw bridgeError("MISSING_CUE_API_KEY", "Set CUE_API_KEY before using local Omni document parsing.", false);
+        }
+        const now = Date.now();
+        const cached = this.#capabilitiesCache;
+        if (cached !== undefined && cached.expiresAt > now) {
+            return cached.value;
+        }
+        let response;
+        try {
+            response = await this.#fetch(this.#capabilitiesUrl, {
+                method: "GET",
+                headers: {
+                    authorization: `Bearer ${this.#apiKey}`,
+                    accept: "application/json",
+                },
+                signal,
+            });
+        }
+        catch {
+            if (signal?.aborted) {
+                throw bridgeError("CAPABILITIES_REQUEST_CANCELED", "The capabilities request was canceled.", false);
+            }
+            throw bridgeError("CUBE_UNAVAILABLE", "Cube could not provide reader capabilities. Retry the same request later.", true);
+        }
+        if (!response.ok) {
+            throw responseError(response.status);
+        }
+        let capabilities;
+        try {
+            capabilities = parseReaderCapabilities(await response.json(), new Date(now));
+        }
+        catch {
+            throw bridgeError("CUBE_PROTOCOL_ERROR", "Cube returned invalid reader capability profiles.", false);
+        }
+        this.#capabilitiesCache = {
+            expiresAt: capabilities.expires_at.getTime(),
+            value: capabilities,
+        };
+        return capabilities;
+    }
+    // The exact direct profile for a non-text detail, obtained through the
+    // authenticated capabilities preflight and selected atomically from the
+    // closed advertisement; missing or mismatched profiles throw
+    // UNSUPPORTED_DETAIL before any grant request is constructed.
+    async #directProfileFor(detail, signal) {
+        const capabilities = await this.getCapabilities(signal);
+        return selectDirectProfile(capabilities, detail);
+    }
     async createGrant(input, clientRequestId, signal, options = {}) {
         if (this.#apiKey.length === 0) {
             throw bridgeError("MISSING_CUE_API_KEY", "Set CUE_API_KEY before using local Omni document parsing.", false);
         }
-        const body = grantRequestBody(input);
+        // D2-D Task 14: for any non-text grant the exact direct profile is
+        // obtained and selected BEFORE the request is constructed or journal state
+        // is written; without one exact compatible profile the request fails
+        // closed with UNSUPPORTED_DETAIL and no unknown-field request is sent.
+        const detail = input.detail === "grounded" || input.detail === "layout"
+            ? input.detail
+            : undefined;
+        const profile = detail === undefined
+            ? undefined
+            : await this.#directProfileFor(detail, signal);
+        const body = grantRequestBody(input, profile);
         const serializedBody = JSON.stringify(body);
         const requestHash = grantRequestHash(body);
         if (options.journal !== false) {
@@ -135,12 +253,26 @@ export class CubeGrantClient {
         if (!response.ok) {
             throw responseError(response.status);
         }
+        // The v3 response tuple is required before this promise resolves: the
+        // upload phase can only start after the negotiated representation is
+        // confirmed by the server.
         let parsed;
-        try {
-            parsed = grantResponseSchema.parse(await response.json());
+        if (profile !== undefined) {
+            try {
+                parsed = grantResponseV3Schema.parse(await response.json());
+            }
+            catch {
+                throw bridgeError("CUBE_PROTOCOL_ERROR", "Cube returned a parse grant outside the negotiated representation.", false);
+            }
+            requireV3GrantTuple(parsed, profile, detail);
         }
-        catch {
-            throw bridgeError("CUBE_PROTOCOL_ERROR", "Cube returned an invalid parse grant response.", false);
+        else {
+            try {
+                parsed = grantResponseSchema.parse(await response.json());
+            }
+            catch {
+                throw bridgeError("CUBE_PROTOCOL_ERROR", "Cube returned an invalid parse grant response.", false);
+            }
         }
         if (options.journal !== false) {
             await this.#journal.markGrantIssued(clientRequestId, {

package/dist/cursor.d.ts

@@ -1,8 +1,18 @@
+import { GROUNDING_SCHEMA_VERSION, RESULT_BUNDLE_PROTOCOL_VERSION } from "./protocol.js";
 export interface CursorPayload {
     readonly resultId: string;
     readonly offset: number;
     readonly expiresAt: string;
 }
+export interface BundleCursorPayload {
+    readonly resultId: string;
+    readonly part: "content" | "grounding";
+    readonly detail: "grounded" | "layout";
+    readonly groundingSchemaVersion: typeof GROUNDING_SCHEMA_VERSION;
+    readonly bundleProtocolVersion: typeof RESULT_BUNDLE_PROTOCOL_VERSION;
+    readonly offset: number;
+    readonly expiresAt: string;
+}
 export interface CursorCodecOptions {
     readonly now?: () => Date;
 }
@@ -11,4 +21,6 @@ export declare class CursorCodec {
     constructor(key: Uint8Array, options?: CursorCodecOptions);
     encode(payload: CursorPayload): string;
     decode(cursor: string): CursorPayload;
+    encodeBundle(payload: BundleCursorPayload): string;
+    decodeBundle(cursor: string): BundleCursorPayload;
 }

package/dist/cursor.js

@@ -1,5 +1,6 @@
 import { createHmac, timingSafeEqual } from "node:crypto";
 import { OmniBridgeError } from "./errors.js";
+import { BUNDLE_CURSOR_VERSION, GROUNDING_SCHEMA_VERSION, RESULT_BUNDLE_PROTOCOL_VERSION, } from "./protocol.js";
 const CURSOR_VERSION = 1;
 const BASE64URL_PATTERN = /^[A-Za-z0-9_-]+$/;
 const RESULT_ID_PATTERN = /^result_[A-Za-z0-9_-]{16,64}$/;
@@ -34,6 +35,8 @@ export class CursorCodec {
         this.#key = Buffer.from(key);
         this.#now = options.now ?? (() => new Date());
     }
+    // v1 cursors remain the legacy text artifact cursor; a v2 payload is
+    // rejected here so a bundle cursor can never read a text result.
     encode(payload) {
         this.#validatePayload(payload);
         const encoded = Buffer.from(JSON.stringify({
@@ -46,19 +49,59 @@ export class CursorCodec {
         return `cursor_${encoded}.${signature}`;
     }
     decode(cursor) {
-        if (typeof cursor !== "string" || cursor.length > 2048 || !cursor.startsWith("cursor_")) {
+        const encoded = this.#unseal(cursor);
+        let value;
+        try {
+            value = JSON.parse(decodeBase64Url(encoded).toString("utf8"));
+        }
+        catch (error) {
+            if (error instanceof OmniBridgeError)
+                throw error;
             throw cursorError("INVALID_RESULT_CURSOR", "The result cursor is invalid.");
         }
-        const components = cursor.slice("cursor_".length).split(".");
-        if (components.length !== 2) {
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
             throw cursorError("INVALID_RESULT_CURSOR", "The result cursor is invalid.");
         }
-        const [encoded, encodedSignature] = components;
-        const signature = decodeBase64Url(encodedSignature);
-        const expected = createHmac("sha256", this.#key).update(encoded).digest();
-        if (signature.length !== expected.length || !timingSafeEqual(signature, expected)) {
+        const record = value;
+        if (Object.keys(record).sort().join(",") !== "expiresAt,offset,resultId,version"
+            || record.version !== CURSOR_VERSION
+            || typeof record.resultId !== "string"
+            || !RESULT_ID_PATTERN.test(record.resultId)
+            || typeof record.offset !== "number"
+            || !Number.isSafeInteger(record.offset)
+            || record.offset < 0
+            || typeof record.expiresAt !== "string"
+            || !Number.isFinite(Date.parse(record.expiresAt))) {
             throw cursorError("INVALID_RESULT_CURSOR", "The result cursor is invalid.");
         }
+        if (Date.parse(record.expiresAt) <= this.#now().getTime()) {
+            throw cursorError("RESULT_CURSOR_EXPIRED", "The result cursor has expired.");
+        }
+        return {
+            resultId: record.resultId,
+            offset: record.offset,
+            expiresAt: record.expiresAt,
+        };
+    }
+    // v2 cursors carry the exact bound field set; a v1 payload is rejected so
+    // a legacy text cursor can never select a bundle part.
+    encodeBundle(payload) {
+        this.#validateBundlePayload(payload);
+        const encoded = Buffer.from(JSON.stringify({
+            version: BUNDLE_CURSOR_VERSION,
+            resultId: payload.resultId,
+            part: payload.part,
+            detail: payload.detail,
+            groundingSchemaVersion: payload.groundingSchemaVersion,
+            bundleProtocolVersion: payload.bundleProtocolVersion,
+            offset: payload.offset,
+            expiresAt: payload.expiresAt,
+        }), "utf8").toString("base64url");
+        const signature = createHmac("sha256", this.#key).update(encoded).digest("base64url");
+        return `cursor_${encoded}.${signature}`;
+    }
+    decodeBundle(cursor) {
+        const encoded = this.#unseal(cursor);
         let value;
         try {
             value = JSON.parse(decodeBase64Url(encoded).toString("utf8"));
@@ -72,10 +115,15 @@ export class CursorCodec {
             throw cursorError("INVALID_RESULT_CURSOR", "The result cursor is invalid.");
         }
         const record = value;
-        if (Object.keys(record).sort().join(",") !== "expiresAt,offset,resultId,version"
-            || record.version !== CURSOR_VERSION
+        if (Object.keys(record).sort().join(",") !==
+            "bundleProtocolVersion,detail,expiresAt,groundingSchemaVersion,offset,part,resultId,version"
+            || record.version !== BUNDLE_CURSOR_VERSION
             || typeof record.resultId !== "string"
             || !RESULT_ID_PATTERN.test(record.resultId)
+            || (record.part !== "content" && record.part !== "grounding")
+            || (record.detail !== "grounded" && record.detail !== "layout")
+            || record.groundingSchemaVersion !== GROUNDING_SCHEMA_VERSION
+            || record.bundleProtocolVersion !== RESULT_BUNDLE_PROTOCOL_VERSION
             || typeof record.offset !== "number"
             || !Number.isSafeInteger(record.offset)
             || record.offset < 0
@@ -88,10 +136,30 @@ export class CursorCodec {
         }
         return {
             resultId: record.resultId,
+            part: record.part,
+            detail: record.detail,
+            groundingSchemaVersion: record.groundingSchemaVersion,
+            bundleProtocolVersion: record.bundleProtocolVersion,
             offset: record.offset,
             expiresAt: record.expiresAt,
         };
     }
+    #unseal(cursor) {
+        if (typeof cursor !== "string" || cursor.length > 2048 || !cursor.startsWith("cursor_")) {
+            throw cursorError("INVALID_RESULT_CURSOR", "The result cursor is invalid.");
+        }
+        const components = cursor.slice("cursor_".length).split(".");
+        if (components.length !== 2) {
+            throw cursorError("INVALID_RESULT_CURSOR", "The result cursor is invalid.");
+        }
+        const [encoded, encodedSignature] = components;
+        const signature = decodeBase64Url(encodedSignature);
+        const expected = createHmac("sha256", this.#key).update(encoded).digest();
+        if (signature.length !== expected.length || !timingSafeEqual(signature, expected)) {
+            throw cursorError("INVALID_RESULT_CURSOR", "The result cursor is invalid.");
+        }
+        return encoded;
+    }
     #validatePayload(payload) {
         if (!RESULT_ID_PATTERN.test(payload.resultId)
             || !Number.isSafeInteger(payload.offset)
@@ -100,4 +168,16 @@ export class CursorCodec {
             throw new Error("cursor payload is invalid");
         }
     }
+    #validateBundlePayload(payload) {
+        if (!RESULT_ID_PATTERN.test(payload.resultId)
+            || (payload.part !== "content" && payload.part !== "grounding")
+            || (payload.detail !== "grounded" && payload.detail !== "layout")
+            || payload.groundingSchemaVersion !== GROUNDING_SCHEMA_VERSION
+            || payload.bundleProtocolVersion !== RESULT_BUNDLE_PROTOCOL_VERSION
+            || !Number.isSafeInteger(payload.offset)
+            || payload.offset < 0
+            || !Number.isFinite(Date.parse(payload.expiresAt))) {
+            throw new Error("bundle cursor payload is invalid");
+        }
+    }
 }