@cueai/omni-reader-mcp 1.1.2 → 1.2.0

package/dist/remote-client.js

@@ -1,7 +1,11 @@
-import { REMOTE_OMNI_MCP_URL } from "./constants.js";
+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 { OmniBridgeError } from "./errors.js";
 import { parseResultSchema } from "./result-contract.js";
 import { classifySource } from "./source.js";
+const INITIALIZE_REQUEST_ID = "initialize";
+const BRIDGE_CLIENT_NAME = "@cueai/omni-reader-mcp";
 function remoteError(options) {
     return new OmniBridgeError({
         code: options.code,
@@ -98,6 +102,53 @@ function protocolError() {
         retryable: false,
     });
 }
+function unsupportedDetail() {
+    return remoteError({
+        code: "UNSUPPORTED_DETAIL",
+        message: "This remote Omni service does not support the requested output detail.",
+        failureScope: "service",
+        userAction: "Use plain Markdown output for this source.",
+        operationCreated: false,
+        retryable: false,
+    });
+}
+// Extracts exactly `result.capabilities.experimental["cue.omni-reader"]` from
+// an MCP initialize envelope; returns undefined when the exact custom field is
+// absent (server did not declare the capability), throws on contract
+// violations. Support is never inferred from any other initialize field.
+function initializeCustomCapability(value, requestId) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw protocolError();
+    }
+    const envelope = value;
+    if (envelope.jsonrpc !== "2.0" ||
+        envelope.id !== requestId ||
+        envelope.error !== undefined) {
+        throw protocolError();
+    }
+    if (envelope.result === null ||
+        typeof envelope.result !== "object" ||
+        Array.isArray(envelope.result)) {
+        throw protocolError();
+    }
+    const capabilities = envelope.result.capabilities;
+    if (capabilities === undefined)
+        return undefined;
+    if (capabilities === null ||
+        typeof capabilities !== "object" ||
+        Array.isArray(capabilities)) {
+        throw protocolError();
+    }
+    const experimental = capabilities.experimental;
+    if (experimental === undefined)
+        return undefined;
+    if (experimental === null ||
+        typeof experimental !== "object" ||
+        Array.isArray(experimental)) {
+        throw protocolError();
+    }
+    return experimental[REMOTE_CAPABILITIES_CUSTOM_FIELD];
+}
 function jsonFromSse(body, requestId) {
     for (const event of body.split(/\r?\n\r?\n/u)) {
         const data = event
@@ -144,11 +195,101 @@ function decodeEnvelope(value, requestId) {
 export class HttpRemoteOmniClient {
     #apiKey;
     #fetch;
+    #capabilitiesCache;
     constructor(options) {
         this.#apiKey = options.apiKey;
         this.#fetch = options.fetchImpl ?? fetch;
     }
-    async parse(source, clientRequestId, signal) {
+    #requireApiKey() {
+        if (this.#apiKey === undefined || this.#apiKey.length === 0) {
+            throw remoteError({
+                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.",
+                operationCreated: false,
+                retryable: false,
+            });
+        }
+    }
+    // Preflight for any non-text tool call (D2-D item 4): sends the MCP
+    // initialize request, extracts only the exact
+    // `capabilities.experimental["cue.omni-reader"]` custom field, validates it
+    // through the closed `omni.reader_capabilities.v1` schema, and caches only
+    // until the exact parsed `expires_at`.
+    async initializeCapabilities(signal) {
+        this.#requireApiKey();
+        const now = Date.now();
+        const cached = this.#capabilitiesCache;
+        if (cached !== undefined && cached.expiresAt > now) {
+            return cached.value;
+        }
+        let response;
+        try {
+            response = await this.#fetch(REMOTE_OMNI_MCP_URL, {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${this.#apiKey}`,
+                    accept: "application/json",
+                    "cache-control": "no-store",
+                    "content-type": "application/json",
+                    "idempotency-key": INITIALIZE_REQUEST_ID,
+                },
+                body: JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: INITIALIZE_REQUEST_ID,
+                    method: "initialize",
+                    params: {
+                        protocolVersion: LATEST_PROTOCOL_VERSION,
+                        capabilities: {},
+                        clientInfo: {
+                            name: BRIDGE_CLIENT_NAME,
+                            version: BRIDGE_RELEASE_VERSION,
+                        },
+                    },
+                }),
+                signal,
+            });
+        }
+        catch (error) {
+            if (signal.aborted)
+                throw error;
+            throw remoteError({
+                code: "SERVICE_TEMPORARILY_UNAVAILABLE",
+                message: "Omni could not reach the remote parsing service.",
+                failureScope: "service",
+                userAction: "Retry with bounded backoff while preserving the same request identity.",
+                operationCreated: true,
+                retryable: true,
+            });
+        }
+        if (!response.ok)
+            throw responseError(response);
+        let envelope;
+        try {
+            envelope = JSON.parse(await response.text());
+        }
+        catch {
+            throw protocolError();
+        }
+        const custom = initializeCustomCapability(envelope, INITIALIZE_REQUEST_ID);
+        if (custom === undefined) {
+            throw unsupportedDetail();
+        }
+        let capabilities;
+        try {
+            capabilities = parseReaderCapabilities(custom, new Date(now));
+        }
+        catch {
+            throw protocolError();
+        }
+        this.#capabilitiesCache = {
+            expiresAt: capabilities.expires_at.getTime(),
+            value: capabilities,
+        };
+        return capabilities;
+    }
+    async parse(source, clientRequestId, signal, detail) {
         const classified = classifySource(source);
         if (classified.kind !== "url") {
             throw remoteError({
@@ -160,7 +301,17 @@ export class HttpRemoteOmniClient {
                 retryable: false,
             });
         }
-        return this.#call("parse", { source: classified.source }, clientRequestId, signal);
+        let args = { source: classified.source };
+        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
+            // non-text v3 call; a missing/mismatched profile fails closed with
+            // UNSUPPORTED_DETAIL and zero tools/call requests.
+            const capabilities = await this.initializeCapabilities(signal);
+            selectUrlProfile(capabilities, detail);
+            args = { source: classified.source, detail };
+        }
+        return this.#call("parse", args, clientRequestId, signal);
     }
     status(operationId, waitMs, signal) {
         return this.#call("get_parse_status", {
@@ -172,16 +323,7 @@ export class HttpRemoteOmniClient {
         return this.#call("cancel_parse", { operation_id: operationId }, `${operationId}:cancel`, signal);
     }
     async #call(name, args, requestId, signal) {
-        if (this.#apiKey === undefined || this.#apiKey.length === 0) {
-            throw remoteError({
-                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.",
-                operationCreated: false,
-                retryable: false,
-            });
-        }
+        this.#requireApiKey();
         let response;
         try {
             response = await this.#fetch(REMOTE_OMNI_MCP_URL, {

package/dist/result-bundle.d.ts

@@ -0,0 +1,21 @@
+export declare const BUNDLE_MEDIA_TYPE = "application/vnd.cue.omni-result-bundle+json; version=1";
+export declare const BUNDLE_CONTENT_MEDIA_TYPE = "text/markdown; charset=utf-8";
+export declare const BUNDLE_GROUNDING_MEDIA_TYPE = "application/vnd.cue.omni-grounding+json; version=1";
+export interface VerifiedBundle {
+    readonly detail: "grounded" | "layout";
+    readonly bundleBytes: number;
+    readonly bundleDigest: string;
+    readonly content: {
+        readonly bytes: Buffer;
+        readonly digest: string;
+        readonly mediaType: "text/markdown; charset=utf-8";
+    };
+    readonly grounding: {
+        readonly bytes: Buffer;
+        readonly digest: string;
+        readonly value: unknown;
+        readonly mediaType: "application/vnd.cue.omni-grounding+json; version=1";
+    };
+}
+export declare function canonicalJson(value: unknown): Buffer<ArrayBuffer>;
+export declare function verifyResultBundle(bytes: Buffer): VerifiedBundle;

package/dist/result-bundle.js

@@ -0,0 +1,320 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { OmniBridgeError } from "./errors.js";
+import { GROUNDING_SCHEMA_VERSION, RESULT_BUNDLE_PROTOCOL_VERSION } from "./protocol.js";
+// Frozen omni.result_bundle.v1 transport/part media types (contract README):
+// the bundle media type is transport metadata only and is never serialized
+// into the bundle value.
+export const BUNDLE_MEDIA_TYPE = "application/vnd.cue.omni-result-bundle+json; version=1";
+export const BUNDLE_CONTENT_MEDIA_TYPE = "text/markdown; charset=utf-8";
+export const BUNDLE_GROUNDING_MEDIA_TYPE = "application/vnd.cue.omni-grounding+json; version=1";
+const sha256DigestSchema = z.string().regex(/^sha256:[0-9a-f]{64}$/u);
+// Closed D1 omni.grounding.v1 sidecar schema, mirrored from the checked-in
+// contracts/omni-grounding/v1/schemas/grounding.schema.json (Draft 2020-12).
+// Objects are closed, anchors are exact literals, and every cross-field
+// constraint (safety oneOf, document completeness, segment layout by detail)
+// is enforced.
+const d1ContentSchema = z
+    .object({
+    media_type: z.literal("text/markdown; charset=utf-8"),
+    bytes: z.number().int().nonnegative(),
+    digest: sha256DigestSchema,
+})
+    .strict();
+const d1SafetySchema = z.union([
+    z
+        .object({
+        mode: z.literal("detect_only"),
+        availability: z.literal("unknown"),
+        reason: z.literal("native_report_absent"),
+    })
+        .strict(),
+    z
+        .object({
+        mode: z.literal("detect_only"),
+        availability: z.literal("reported"),
+        injections: z.number().int().nonnegative(),
+        hidden: z.number().int().nonnegative(),
+    })
+        .strict(),
+]);
+const d1IncompleteSchema = z.union([
+    z
+        .object({
+        kind: z.literal("page"),
+        basis: z.enum(["source_pdf_page_1_based", "rendered_pdf_page_1_based"]),
+        values: z.array(z.number().int().min(1)).min(1)
+            .refine((values) => new Set(values).size === values.length, { message: "values must be unique" }),
+        reason: z.literal("processing_timeout"),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("document"),
+        basis: z.literal("whole_input"),
+        reason: z.enum(["processing_incomplete", "member_inventory_unavailable"]),
+    })
+        .strict(),
+]);
+const d1TruncatedSchema = z
+    .object({
+    kind: z.literal("page"),
+    basis: z.enum(["source_pdf_page_1_based", "rendered_pdf_page_1_based"]),
+    count: z.number().int().min(1),
+    exact_values_available: z.literal(false),
+    reason: z.literal("content_truncated"),
+})
+    .strict();
+const d1DocumentSchema = z
+    .object({
+    format: z.string().min(1).max(64),
+    partial: z.boolean(),
+    incomplete: z.array(d1IncompleteSchema),
+    truncated: z.array(d1TruncatedSchema),
+    safety: d1SafetySchema,
+})
+    .strict()
+    .refine((document) => document.partial
+    ? document.incomplete.length > 0 || document.truncated.length > 0
+    : document.incomplete.length === 0 && document.truncated.length === 0, { message: "document completeness is inconsistent" });
+const d1SourcePageAnchorSchema = z
+    .object({
+    kind: z.literal("page"),
+    basis: z.literal("source_pdf_page_1_based"),
+    reliability: z.literal("reliable"),
+    value: z.number().int().min(1),
+})
+    .strict();
+const d1RenderedPageAnchorSchema = z
+    .object({
+    kind: z.literal("page"),
+    basis: z.literal("rendered_pdf_page_1_based"),
+    reliability: z.literal("conditional"),
+    value: z.number().int().min(1),
+})
+    .strict();
+const d1DocumentAnchorSchema = z
+    .object({
+    kind: z.literal("document"),
+    basis: z.literal("whole_document"),
+    reliability: z.literal("reliable_within_result"),
+})
+    .strict();
+const d1OrdinalAnchorSchema = z
+    .object({
+    kind: z.literal("ordinal"),
+    basis: z.literal("media_event_0_based"),
+    reliability: z.literal("reliable_within_result"),
+    value: z.number().int().min(0),
+})
+    .strict();
+const d1MemberAnchorSchema = z
+    .object({
+    kind: z.literal("archive_member"),
+    basis: z.literal("safe_flat_member_name"),
+    reliability: z.literal("reliable_within_result"),
+    value: z.string().min(1).max(512)
+        .regex(/^[^/\\\u0000\r\n]{1,512}$/u)
+        .refine((value) => value !== "." && value !== "..", { message: "member name is unsafe" }),
+})
+    .strict();
+const d1AnchorSchema = z.union([
+    d1SourcePageAnchorSchema,
+    d1RenderedPageAnchorSchema,
+    d1DocumentAnchorSchema,
+    d1OrdinalAnchorSchema,
+    d1MemberAnchorSchema,
+]);
+const d1GroundingSchema = z.union([
+    z
+        .object({
+        availability: z.literal("available"),
+        anchors: z.array(d1AnchorSchema).min(1),
+    })
+        .strict(),
+    z
+        .object({
+        availability: z.literal("unavailable"),
+        reason: z.enum(["no_reliable_source_anchor", "parser_did_not_preserve_anchor"]),
+        anchors: z.array(d1AnchorSchema).max(0),
+    })
+        .strict(),
+]);
+const d1LayoutItemSchema = z
+    .object({
+    text: z.string(),
+    bbox: z.tuple([z.number(), z.number(), z.number(), z.number()]),
+    font: z.string().optional(),
+    size: z.number().positive().optional(),
+    heading: z.number().int().min(1).max(6).optional(),
+})
+    .strict();
+const d1CoordinateSpaceSchema = z
+    .object({
+    basis: z.literal("parser_page_native"),
+    unit: z.literal("unknown"),
+    page_width: z.null(),
+    page_height: z.null(),
+    rotation_degrees: z.null(),
+})
+    .strict();
+const d1LayoutSchema = z.union([
+    z
+        .object({
+        availability: z.literal("available"),
+        reliability: z.literal("conditional"),
+        coordinate_space: d1CoordinateSpaceSchema,
+        items: z.array(d1LayoutItemSchema).min(1),
+    })
+        .strict(),
+    z
+        .object({
+        availability: z.literal("unavailable"),
+        reason: z.enum([
+            "ocr_geometry_not_produced",
+            "parser_did_not_produce_layout",
+            "unsupported_modality",
+            "layout_budget_exceeded",
+        ]),
+    })
+        .strict(),
+]);
+const d1ContentRangeSchema = z
+    .object({
+    start: z.number().int().nonnegative(),
+    end: z.number().int().nonnegative(),
+})
+    .strict();
+const d1SegmentSchema = z
+    .object({
+    segment_id: z.string().regex(/^segment_[0-9]{6}$/u),
+    content_range_utf8: d1ContentRangeSchema,
+    grounding: d1GroundingSchema,
+    layout: d1LayoutSchema.optional(),
+})
+    .strict();
+const d1ValueSchema = z
+    .object({
+    schema_version: z.literal(GROUNDING_SCHEMA_VERSION),
+    detail: z.enum(["grounded", "layout"]),
+    content: d1ContentSchema,
+    document: d1DocumentSchema,
+    segments: z.array(d1SegmentSchema),
+})
+    .strict()
+    .refine((value) => value.detail === "grounded"
+    ? value.segments.every((segment) => segment.layout === undefined)
+    : value.segments.every((segment) => segment.layout !== undefined), { message: "segment layout is inconsistent with detail" });
+// Closed omni.result_bundle.v1 envelope. `detail` must equal the embedded D1
+// sidecar detail (contract compatibility rule 1).
+const bundleSchema = z
+    .object({
+    protocol_version: z.literal(RESULT_BUNDLE_PROTOCOL_VERSION),
+    detail: z.enum(["grounded", "layout"]),
+    content: z
+        .object({
+        media_type: z.literal(BUNDLE_CONTENT_MEDIA_TYPE),
+        text: z.string(),
+    })
+        .strict(),
+    grounding: z
+        .object({
+        media_type: z.literal(BUNDLE_GROUNDING_MEDIA_TYPE),
+        value: d1ValueSchema,
+    })
+        .strict(),
+})
+    .strict()
+    .refine((bundle) => bundle.detail === bundle.grounding.value.detail, { message: "bundle detail must equal the D1 sidecar detail" });
+function contractError() {
+    return new OmniBridgeError({
+        code: "GROUNDING_CONTRACT_INVALID",
+        message: "The released result is not a valid omni.result_bundle.v1 bundle.",
+        operationCreated: true,
+        fileUploaded: true,
+        parserStarted: true,
+        billed: true,
+        contentReleased: true,
+        retryable: false,
+    });
+}
+// Canonical JSON: compact separators, recursively sorted keys, and no
+// non-finite numbers (allow_nan=false). JSON values parsed from text can
+// contain Infinity through 1e999-style tokens, which canonicalization rejects.
+export function canonicalJson(value) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value, (key, current) => {
+            if (typeof current === "number" && !Number.isFinite(current)) {
+                throw new Error("canonical JSON must not contain non-finite numbers");
+            }
+            if (current !== null && typeof current === "object" && !Array.isArray(current)) {
+                const record = current;
+                return Object.fromEntries(Object.keys(record).sort().map((name) => [name, record[name]]));
+            }
+            return current;
+        });
+    }
+    catch {
+        throw contractError();
+    }
+    if (serialized === undefined)
+        throw contractError();
+    return Buffer.from(serialized, "utf8");
+}
+// Strict canonical bundle verification:
+// 1. UTF-8 decode with fatal errors.
+// 2. Closed-key schema validation of the envelope and the D1 sidecar.
+// 3. Exact full byte comparison against the canonical reserialization. This
+//    rejects non-canonical wire bytes and, by construction, duplicate JSON
+//    keys at any nesting depth (JSON.parse collapses duplicates, so their
+//    canonical reserialization can never equal the input bytes).
+// 4. D1 content binding: grounding.value.content bytes/digest must equal the
+//    exact content part bytes (design rule 8).
+// The grounding part bytes are the canonical JSON of grounding.value alone,
+// never the {media_type, value} wrapper.
+export function verifyResultBundle(bytes) {
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw contractError();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw contractError();
+    }
+    let bundle;
+    try {
+        bundle = bundleSchema.parse(parsed);
+    }
+    catch {
+        throw contractError();
+    }
+    const canonical = canonicalJson(bundle);
+    if (!canonical.equals(bytes))
+        throw contractError();
+    const contentBytes = Buffer.from(bundle.content.text, "utf8");
+    const contentDigest = `sha256:${createHash("sha256").update(contentBytes).digest("hex")}`;
+    const bound = bundle.grounding.value.content;
+    if (bound.bytes !== contentBytes.length || bound.digest !== contentDigest) {
+        throw contractError();
+    }
+    const groundingBytes = canonicalJson(bundle.grounding.value);
+    return {
+        detail: bundle.detail,
+        bundleBytes: bytes.length,
+        bundleDigest: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,
+        content: { bytes: contentBytes, digest: contentDigest, mediaType: BUNDLE_CONTENT_MEDIA_TYPE },
+        grounding: {
+            bytes: groundingBytes,
+            digest: `sha256:${createHash("sha256").update(groundingBytes).digest("hex")}`,
+            value: bundle.grounding.value,
+            mediaType: BUNDLE_GROUNDING_MEDIA_TYPE,
+        },
+    };
+}