@cueai/omni-reader-mcp 1.1.3 → 1.2.1

package/dist/result-contract.d.ts

@@ -102,13 +102,13 @@ export declare const stableErrorSchema: z.ZodObject<{
         supported_extensions?: string[] | undefined;
     }>>;
 }, "strict", z.ZodTypeAny, {
+    code: string;
+    message: string;
     billed: boolean;
     retryable: boolean;
-    code: string;
     file_uploaded: boolean;
     content_released: boolean;
     parser_started: boolean;
-    message: string;
     ok: false;
     operation_created: boolean;
     failure_scope?: "source" | "local_capability" | "authentication" | "billing" | "service" | "parser" | "operation" | "cleanup" | "bridge" | undefined;
@@ -121,13 +121,13 @@ export declare const stableErrorSchema: z.ZodObject<{
         supported_extensions?: string[] | undefined;
     } | undefined;
 }, {
+    code: string;
+    message: string;
     billed: boolean;
     retryable: boolean;
-    code: string;
     file_uploaded: boolean;
     content_released: boolean;
     parser_started: boolean;
-    message: string;
     ok: false;
     operation_created: boolean;
     failure_scope?: "source" | "local_capability" | "authentication" | "billing" | "service" | "parser" | "operation" | "cleanup" | "bridge" | undefined;
@@ -190,7 +190,401 @@ export declare const progressDetailSchema: z.ZodEffects<z.ZodObject<{
     total: number;
     completed: number;
 }>;
+export declare const bundleDescriptorSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"bundle">;
+    result_id: z.ZodString;
+    detail: z.ZodEnum<["grounded", "layout"]>;
+    bundle_protocol_version: z.ZodLiteral<"omni.result_bundle.v1">;
+    bundle_digest: z.ZodString;
+    bundle_bytes: z.ZodNumber;
+    expires_at: z.ZodString;
+    parts: z.ZodObject<{
+        content: z.ZodObject<{
+            part: z.ZodLiteral<"content">;
+            media_type: z.ZodLiteral<"text/markdown; charset=utf-8">;
+            result_bytes: z.ZodNumber;
+            digest: z.ZodString;
+            storage: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                text: z.ZodString;
+            }, "strict", z.ZodTypeAny, {
+                text: string;
+                kind: "inline";
+            }, {
+                text: string;
+                kind: "inline";
+            }>, z.ZodObject<{
+                kind: z.ZodLiteral<"artifact">;
+                next_cursor: z.ZodString;
+                preview: z.ZodOptional<z.ZodString>;
+            }, "strict", z.ZodTypeAny, {
+                kind: "artifact";
+                next_cursor: string;
+                preview?: string | undefined;
+            }, {
+                kind: "artifact";
+                next_cursor: string;
+                preview?: string | undefined;
+            }>]>;
+        }, "strict", z.ZodTypeAny, {
+            part: "content";
+            result_bytes: number;
+            media_type: "text/markdown; charset=utf-8";
+            digest: string;
+            storage: {
+                text: string;
+                kind: "inline";
+            } | {
+                kind: "artifact";
+                next_cursor: string;
+                preview?: string | undefined;
+            };
+        }, {
+            part: "content";
+            result_bytes: number;
+            media_type: "text/markdown; charset=utf-8";
+            digest: string;
+            storage: {
+                text: string;
+                kind: "inline";
+            } | {
+                kind: "artifact";
+                next_cursor: string;
+                preview?: string | undefined;
+            };
+        }>;
+        grounding: z.ZodObject<{
+            part: z.ZodLiteral<"grounding">;
+            media_type: z.ZodLiteral<"application/vnd.cue.omni-grounding+json; version=1">;
+            result_bytes: z.ZodNumber;
+            digest: z.ZodString;
+            storage: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                value: z.ZodUnknown;
+            }, "strict", z.ZodTypeAny, {
+                kind: "inline";
+                value?: unknown;
+            }, {
+                kind: "inline";
+                value?: unknown;
+            }>, z.ZodObject<{
+                kind: z.ZodLiteral<"artifact">;
+                next_cursor: z.ZodString;
+            }, "strict", z.ZodTypeAny, {
+                kind: "artifact";
+                next_cursor: string;
+            }, {
+                kind: "artifact";
+                next_cursor: string;
+            }>]>;
+        }, "strict", z.ZodTypeAny, {
+            part: "grounding";
+            result_bytes: number;
+            media_type: "application/vnd.cue.omni-grounding+json; version=1";
+            digest: string;
+            storage: {
+                kind: "inline";
+                value?: unknown;
+            } | {
+                kind: "artifact";
+                next_cursor: string;
+            };
+        }, {
+            part: "grounding";
+            result_bytes: number;
+            media_type: "application/vnd.cue.omni-grounding+json; version=1";
+            digest: string;
+            storage: {
+                kind: "inline";
+                value?: unknown;
+            } | {
+                kind: "artifact";
+                next_cursor: string;
+            };
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        content: {
+            part: "content";
+            result_bytes: number;
+            media_type: "text/markdown; charset=utf-8";
+            digest: string;
+            storage: {
+                text: string;
+                kind: "inline";
+            } | {
+                kind: "artifact";
+                next_cursor: string;
+                preview?: string | undefined;
+            };
+        };
+        grounding: {
+            part: "grounding";
+            result_bytes: number;
+            media_type: "application/vnd.cue.omni-grounding+json; version=1";
+            digest: string;
+            storage: {
+                kind: "inline";
+                value?: unknown;
+            } | {
+                kind: "artifact";
+                next_cursor: string;
+            };
+        };
+    }, {
+        content: {
+            part: "content";
+            result_bytes: number;
+            media_type: "text/markdown; charset=utf-8";
+            digest: string;
+            storage: {
+                text: string;
+                kind: "inline";
+            } | {
+                kind: "artifact";
+                next_cursor: string;
+                preview?: string | undefined;
+            };
+        };
+        grounding: {
+            part: "grounding";
+            result_bytes: number;
+            media_type: "application/vnd.cue.omni-grounding+json; version=1";
+            digest: string;
+            storage: {
+                kind: "inline";
+                value?: unknown;
+            } | {
+                kind: "artifact";
+                next_cursor: string;
+            };
+        };
+    }>;
+}, "strict", z.ZodTypeAny, {
+    detail: "grounded" | "layout";
+    result_id: string;
+    expires_at: string;
+    kind: "bundle";
+    bundle_protocol_version: "omni.result_bundle.v1";
+    bundle_digest: string;
+    bundle_bytes: number;
+    parts: {
+        content: {
+            part: "content";
+            result_bytes: number;
+            media_type: "text/markdown; charset=utf-8";
+            digest: string;
+            storage: {
+                text: string;
+                kind: "inline";
+            } | {
+                kind: "artifact";
+                next_cursor: string;
+                preview?: string | undefined;
+            };
+        };
+        grounding: {
+            part: "grounding";
+            result_bytes: number;
+            media_type: "application/vnd.cue.omni-grounding+json; version=1";
+            digest: string;
+            storage: {
+                kind: "inline";
+                value?: unknown;
+            } | {
+                kind: "artifact";
+                next_cursor: string;
+            };
+        };
+    };
+}, {
+    detail: "grounded" | "layout";
+    result_id: string;
+    expires_at: string;
+    kind: "bundle";
+    bundle_protocol_version: "omni.result_bundle.v1";
+    bundle_digest: string;
+    bundle_bytes: number;
+    parts: {
+        content: {
+            part: "content";
+            result_bytes: number;
+            media_type: "text/markdown; charset=utf-8";
+            digest: string;
+            storage: {
+                text: string;
+                kind: "inline";
+            } | {
+                kind: "artifact";
+                next_cursor: string;
+                preview?: string | undefined;
+            };
+        };
+        grounding: {
+            part: "grounding";
+            result_bytes: number;
+            media_type: "application/vnd.cue.omni-grounding+json; version=1";
+            digest: string;
+            storage: {
+                kind: "inline";
+                value?: unknown;
+            } | {
+                kind: "artifact";
+                next_cursor: string;
+            };
+        };
+    };
+}>;
 export declare const parseResultSchema: z.ZodTypeAny;
+export declare const bundlePartReadSchema: z.ZodObject<{
+    status: z.ZodLiteral<"completed">;
+    result: z.ZodEffects<z.ZodDiscriminatedUnion<"part", [z.ZodObject<{
+        part: z.ZodLiteral<"content">;
+        media_type: z.ZodLiteral<"text/markdown; charset=utf-8">;
+        result_id: z.ZodString;
+        result_bytes: z.ZodNumber;
+        offset: z.ZodNumber;
+        decoded_bytes: z.ZodNumber;
+        text: z.ZodString;
+        next_cursor: z.ZodOptional<z.ZodString>;
+        expires_at: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        text: string;
+        result_id: string;
+        offset: number;
+        part: "content";
+        expires_at: string;
+        result_bytes: number;
+        media_type: "text/markdown; charset=utf-8";
+        decoded_bytes: number;
+        next_cursor?: string | undefined;
+    }, {
+        text: string;
+        result_id: string;
+        offset: number;
+        part: "content";
+        expires_at: string;
+        result_bytes: number;
+        media_type: "text/markdown; charset=utf-8";
+        decoded_bytes: number;
+        next_cursor?: string | undefined;
+    }>, z.ZodObject<{
+        part: z.ZodLiteral<"grounding">;
+        media_type: z.ZodLiteral<"application/vnd.cue.omni-grounding+json; version=1">;
+        result_id: z.ZodString;
+        result_bytes: z.ZodNumber;
+        offset: z.ZodNumber;
+        decoded_bytes: z.ZodNumber;
+        text: z.ZodString;
+        next_cursor: z.ZodOptional<z.ZodString>;
+        expires_at: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        text: string;
+        result_id: string;
+        offset: number;
+        part: "grounding";
+        expires_at: string;
+        result_bytes: number;
+        media_type: "application/vnd.cue.omni-grounding+json; version=1";
+        decoded_bytes: number;
+        next_cursor?: string | undefined;
+    }, {
+        text: string;
+        result_id: string;
+        offset: number;
+        part: "grounding";
+        expires_at: string;
+        result_bytes: number;
+        media_type: "application/vnd.cue.omni-grounding+json; version=1";
+        decoded_bytes: number;
+        next_cursor?: string | undefined;
+    }>]>, {
+        text: string;
+        result_id: string;
+        offset: number;
+        part: "content";
+        expires_at: string;
+        result_bytes: number;
+        media_type: "text/markdown; charset=utf-8";
+        decoded_bytes: number;
+        next_cursor?: string | undefined;
+    } | {
+        text: string;
+        result_id: string;
+        offset: number;
+        part: "grounding";
+        expires_at: string;
+        result_bytes: number;
+        media_type: "application/vnd.cue.omni-grounding+json; version=1";
+        decoded_bytes: number;
+        next_cursor?: string | undefined;
+    }, {
+        text: string;
+        result_id: string;
+        offset: number;
+        part: "content";
+        expires_at: string;
+        result_bytes: number;
+        media_type: "text/markdown; charset=utf-8";
+        decoded_bytes: number;
+        next_cursor?: string | undefined;
+    } | {
+        text: string;
+        result_id: string;
+        offset: number;
+        part: "grounding";
+        expires_at: string;
+        result_bytes: number;
+        media_type: "application/vnd.cue.omni-grounding+json; version=1";
+        decoded_bytes: number;
+        next_cursor?: string | undefined;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    status: "completed";
+    result: {
+        text: string;
+        result_id: string;
+        offset: number;
+        part: "content";
+        expires_at: string;
+        result_bytes: number;
+        media_type: "text/markdown; charset=utf-8";
+        decoded_bytes: number;
+        next_cursor?: string | undefined;
+    } | {
+        text: string;
+        result_id: string;
+        offset: number;
+        part: "grounding";
+        expires_at: string;
+        result_bytes: number;
+        media_type: "application/vnd.cue.omni-grounding+json; version=1";
+        decoded_bytes: number;
+        next_cursor?: string | undefined;
+    };
+}, {
+    status: "completed";
+    result: {
+        text: string;
+        result_id: string;
+        offset: number;
+        part: "content";
+        expires_at: string;
+        result_bytes: number;
+        media_type: "text/markdown; charset=utf-8";
+        decoded_bytes: number;
+        next_cursor?: string | undefined;
+    } | {
+        text: string;
+        result_id: string;
+        offset: number;
+        part: "grounding";
+        expires_at: string;
+        result_bytes: number;
+        media_type: "application/vnd.cue.omni-grounding+json; version=1";
+        decoded_bytes: number;
+        next_cursor?: string | undefined;
+    };
+}>;
 export declare const readResultOutputSchema: z.ZodTypeAny;
 export declare const discardResultOutputSchema: z.ZodTypeAny;
 export declare const parseToolOutputSchema: z.ZodTypeAny;

package/dist/result-contract.js

@@ -1,4 +1,5 @@
 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 constraintsSchema = z
@@ -84,6 +85,80 @@ const billingSchema = z
     credits_remaining: z.number().nonnegative(),
 })
     .strict();
+// v3 bundle descriptor (D2-D item 7): closed keyed-parts object. Top-level and
+// nested objects are all additionalProperties=false; `parts` must have exact
+// keys `content` and `grounding`. Storage is a closed discriminated union:
+// content inline exact keys {kind,text}; grounding inline exact keys
+// {kind,value}; content artifact exact keys {kind,next_cursor} plus optional
+// preview; grounding artifact exact keys {kind,next_cursor} with
+// preview/text/value forbidden.
+const sha256DigestSchema = z.string().regex(/^sha256:[0-9a-f]{64}$/u);
+const contentMediaTypeSchema = z.literal("text/markdown; charset=utf-8");
+const groundingMediaTypeSchema = z.literal("application/vnd.cue.omni-grounding+json; version=1");
+const contentStorageSchema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("inline"),
+        text: z.string(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("artifact"),
+        next_cursor: z.string().min(1).max(2048),
+        preview: z.string().optional(),
+    })
+        .strict(),
+]);
+const groundingStorageSchema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("inline"),
+        value: z.unknown(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("artifact"),
+        next_cursor: z.string().min(1).max(2048),
+    })
+        .strict(),
+]);
+const contentPartDescriptorSchema = z
+    .object({
+    part: z.literal("content"),
+    media_type: contentMediaTypeSchema,
+    result_bytes: z.number().int().nonnegative(),
+    digest: sha256DigestSchema,
+    storage: contentStorageSchema,
+})
+    .strict();
+const groundingPartDescriptorSchema = z
+    .object({
+    part: z.literal("grounding"),
+    media_type: groundingMediaTypeSchema,
+    result_bytes: z.number().int().nonnegative(),
+    digest: sha256DigestSchema,
+    storage: groundingStorageSchema,
+})
+    .strict();
+export const bundleDescriptorSchema = z
+    .object({
+    kind: z.literal("bundle"),
+    result_id: resultIdSchema,
+    detail: z.enum(["grounded", "layout"]),
+    bundle_protocol_version: z.literal(RESULT_BUNDLE_PROTOCOL_VERSION),
+    bundle_digest: sha256DigestSchema,
+    bundle_bytes: z.number().int().nonnegative(),
+    expires_at: z.string().datetime({ offset: true }),
+    parts: z
+        .object({
+        content: contentPartDescriptorSchema,
+        grounding: groundingPartDescriptorSchema,
+    })
+        .strict(),
+})
+    .strict();
 const localResultCacheSchema = z
     .object({
     expires_at: z.string().datetime({ offset: true }),
@@ -114,7 +189,11 @@ export const parseResultSchema = z.discriminatedUnion("status", [
         .object({
         status: z.literal("completed"),
         operation_id: operationIdSchema,
-        result: z.union([inlineResultSchema, artifactResultSchema]),
+        result: z.union([
+            inlineResultSchema,
+            artifactResultSchema,
+            bundleDescriptorSchema,
+        ]),
         billing: billingSchema.optional(),
         data_handling: dataHandlingSchema,
         local_result_cache: localResultCacheSchema.optional(),
@@ -124,7 +203,11 @@ export const parseResultSchema = z.discriminatedUnion("status", [
         .object({
         status: z.literal("cleanup_pending"),
         operation_id: operationIdSchema,
-        result: z.union([inlineResultSchema, artifactResultSchema]).optional(),
+        result: z.union([
+            inlineResultSchema,
+            artifactResultSchema,
+            bundleDescriptorSchema,
+        ]).optional(),
         cleanup_deadline: z.string().datetime({ offset: true }),
         data_handling: dataHandlingSchema,
     })
@@ -155,8 +238,53 @@ const resultChunkSchema = z
     next_cursor: z.string().min(1).max(2048).optional(),
 })
     .strict();
+// v3 part read (D2-D item 9): closed chunk with part/media type/offset/
+// decoded bytes. Content always carries the Markdown media type, grounding
+// always the grounding media type; `decoded_bytes` equals the UTF-8 byte
+// length of `text`. `next_cursor` appears only on non-final chunks.
+const bundlePartReadChunkSchema = z
+    .discriminatedUnion("part", [
+    z
+        .object({
+        part: z.literal("content"),
+        media_type: contentMediaTypeSchema,
+        result_id: resultIdSchema,
+        result_bytes: z.number().int().nonnegative(),
+        offset: z.number().int().nonnegative(),
+        decoded_bytes: z.number().int().nonnegative(),
+        text: z.string(),
+        next_cursor: z.string().min(1).max(2048).optional(),
+        expires_at: z.string().datetime({ offset: true }),
+    })
+        .strict(),
+    z
+        .object({
+        part: z.literal("grounding"),
+        media_type: groundingMediaTypeSchema,
+        result_id: resultIdSchema,
+        result_bytes: z.number().int().nonnegative(),
+        offset: z.number().int().nonnegative(),
+        decoded_bytes: z.number().int().nonnegative(),
+        text: z.string(),
+        next_cursor: z.string().min(1).max(2048).optional(),
+        expires_at: z.string().datetime({ offset: true }),
+    })
+        .strict(),
+])
+    .refine((value) => Buffer.byteLength(value.text, "utf8") === value.decoded_bytes, { message: "decoded_bytes must equal the UTF-8 byte length of text" });
+export const bundlePartReadSchema = z
+    .object({
+    status: z.literal("completed"),
+    result: bundlePartReadChunkSchema,
+})
+    .strict();
 export const readResultOutputSchema = z.discriminatedUnion("status", [
-    z.object({ status: z.literal("completed"), result: resultChunkSchema }).strict(),
+    z
+        .object({
+        status: z.literal("completed"),
+        result: z.union([resultChunkSchema, bundlePartReadChunkSchema]),
+    })
+        .strict(),
     failedResultSchema,
 ]);
 export const discardResultOutputSchema = z.discriminatedUnion("status", [
@@ -186,7 +314,11 @@ export const parseToolOutputSchema = z
     next_action: z.literal("check_status").optional(),
     poll_after_seconds: z.number().int().positive().optional(),
     can_cancel: z.boolean().optional(),
-    result: z.union([inlineResultSchema, artifactResultSchema]).optional(),
+    result: z.union([
+        inlineResultSchema,
+        artifactResultSchema,
+        bundleDescriptorSchema,
+    ]).optional(),
     billing: billingSchema.optional(),
     data_handling: dataHandlingSchema.optional(),
     local_result_cache: localResultCacheSchema.optional(),
@@ -198,7 +330,7 @@ export const parseToolOutputSchema = z
 export const readResultToolOutputSchema = z
     .object({
     status: z.enum(["completed", "failed"]),
-    result: resultChunkSchema.optional(),
+    result: z.union([resultChunkSchema, bundlePartReadChunkSchema]).optional(),
     error: stableErrorSchema.optional(),
 })
     .strict();
@@ -210,15 +342,41 @@ export const discardResultToolOutputSchema = z
     error: stableErrorSchema.optional(),
 })
     .strict();
+function storageText(result) {
+    const parts = result.parts;
+    if (parts === null || typeof parts !== "object" || Array.isArray(parts)) {
+        return undefined;
+    }
+    const content = parts.content;
+    if (content === null || typeof content !== "object" || Array.isArray(content)) {
+        return undefined;
+    }
+    const storage = content.storage;
+    if (storage === null || typeof storage !== "object" || Array.isArray(storage)) {
+        return undefined;
+    }
+    const record = storage;
+    if (record.kind !== "inline" || typeof record.text !== "string") {
+        return undefined;
+    }
+    return record.text;
+}
+// Content-only fallback (D2-D item 17): inline bundle content falls back to
+// the exact Markdown bytes only; artifact content falls back to the complete
+// compact descriptor JSON. Grounding JSON is never appended to plain Markdown.
 function textFallback(value) {
     if (value.status === "completed") {
         const result = value.result;
-        if (result !== null
-            && typeof result === "object"
-            && !Array.isArray(result)
-            && result.kind === "inline"
-            && typeof result.text === "string") {
-            return result.text;
+        if (result !== null && typeof result === "object" && !Array.isArray(result)) {
+            const record = result;
+            if (record.kind === "inline" && typeof record.text === "string") {
+                return record.text;
+            }
+            if (record.kind === "bundle") {
+                const inlineText = storageText(record);
+                if (inlineText !== undefined)
+                    return inlineText;
+            }
         }
     }
     return JSON.stringify(value);

package/dist/server.d.ts

@@ -1,3 +1,20 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CAPABILITIES_PROTOCOL_VERSION, DIRECT_GROUNDING_PROFILE, URL_GROUNDING_PROFILE } from "./constants.js";
 import { type OmniToolDependencies } from "./tools.js";
+export interface ReaderCapabilitiesAdvertisement {
+    readonly protocol_version: typeof CAPABILITIES_PROTOCOL_VERSION;
+    readonly expires_at: string;
+    readonly direct_profiles: readonly [typeof DIRECT_GROUNDING_PROFILE];
+    readonly url_profiles: readonly [typeof URL_GROUNDING_PROFILE];
+}
+export declare function buildReaderCapabilitiesAdvertisement(now: Date, ttlSeconds: number): ReaderCapabilitiesAdvertisement;
+/** OMNI_CAPABILITIES_ENABLED gate, default off; a malformed value fails fast. */
+export declare function capabilitiesEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** OMNI_CAPABILITIES_TTL_SECONDS, default 300; malformed/non-positive values fall back. */
+export declare function capabilitiesTtlSeconds(env?: NodeJS.ProcessEnv): number;
+/**
+ * The advertisement to include in an initialize result, or null when the flag is off
+ * (the custom field must be absent — the server never emits a partial value).
+ */
+export declare function readerCapabilitiesAdvertisement(now?: Date): ReaderCapabilitiesAdvertisement | null;
 export declare function createOmniMcpServer(dependencies: OmniToolDependencies): McpServer;