@cueai/omni-reader-mcp 1.5.5 → 1.7.0

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.4";
+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.4 previous, 1.5.5 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/cli/arguments.d.ts

@@ -7,18 +7,22 @@ export interface SetupArguments {
     readonly headless: boolean;
     readonly json: boolean;
 }
+export interface DoctorArguments {
+    readonly json: boolean;
+    readonly configPath?: string;
+    readonly serverName?: string;
+}
 export type ParsedCommand = {
     readonly command: "server";
 } | {
     readonly command: "help";
 } | {
     readonly command: "version";
-} | {
+} | ({
+    readonly command: "doctor";
+} & DoctorArguments) | {
     readonly command: "setup";
     readonly arguments: SetupArguments;
-} | {
-    readonly command: "doctor";
-    readonly json: boolean;
 } | {
     readonly command: "clean";
 } | {

package/dist/cli/arguments.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { PathNormalizationError, normalizePlatformPath, } from "../path-normalization.js";
 import { parseAgentTarget } from "./agent-config.js";
 export class CliUsageError extends Error {
     exitCode = 2;
@@ -10,6 +11,26 @@ export class CliUsageError extends Error {
 function pathsFor(platform) {
     return platform === "win32" ? path.win32 : path.posix;
 }
+function normalizeAbsoluteCliPath(raw, flag, platform) {
+    if (raw.length === 0 || raw.includes("\0")) {
+        throw new CliUsageError(`${flag} requires one valid absolute path.`);
+    }
+    let normalizedInput;
+    try {
+        normalizedInput = normalizePlatformPath(raw, platform);
+    }
+    catch (error) {
+        if (error instanceof PathNormalizationError) {
+            throw new CliUsageError(error.message);
+        }
+        throw error;
+    }
+    const paths = pathsFor(platform);
+    if (!paths.isAbsolute(normalizedInput)) {
+        throw new CliUsageError(`${flag} requires an absolute path.`);
+    }
+    return paths.normalize(normalizedInput);
+}
 function requireNoArguments(command, values) {
     if (values.length > 0)
         throw new CliUsageError(`${command} does not accept arguments.`);
@@ -35,7 +56,6 @@ function parseSetupArguments(values, platform) {
     let headless = false;
     let json = false;
     const seen = new Set();
-    const paths = pathsFor(platform);
     for (let index = 0; index < values.length; index += 1) {
         const flag = values[index];
         if (!["--client", "--allowed-root", "--add-root", "--yes", "--headless", "--non-interactive", "--json"].includes(flag)) {
@@ -71,10 +91,7 @@ function parseSetupArguments(values, platform) {
             client = parsed;
             continue;
         }
-        if (!paths.isAbsolute(raw)) {
-            throw new CliUsageError(`${flag} requires an absolute path.`);
-        }
-        const normalized = paths.normalize(raw);
+        const normalized = normalizeAbsoluteCliPath(raw, flag, platform);
         if (flag === "--allowed-root")
             allowedRoot = normalized;
         if (flag === "--add-root")
@@ -92,6 +109,45 @@ function parseSetupArguments(values, platform) {
         json,
     };
 }
+function parseDoctorArguments(values, platform) {
+    let json = false;
+    let configPath;
+    let serverName;
+    const seen = new Set();
+    for (let index = 0; index < values.length; index += 1) {
+        const flag = values[index];
+        if (!["--json", "--config-path", "--server-name"].includes(flag)) {
+            throw new CliUsageError(`Unknown doctor flag: ${flag}`);
+        }
+        if (seen.has(flag))
+            throw new CliUsageError(`Duplicate doctor flag: ${flag}`);
+        seen.add(flag);
+        if (flag === "--json") {
+            json = true;
+            continue;
+        }
+        const raw = values[index + 1];
+        if (raw === undefined || raw.startsWith("--")) {
+            throw new CliUsageError(`${flag} requires a value.`);
+        }
+        index += 1;
+        if (flag === "--config-path") {
+            configPath = normalizeAbsoluteCliPath(raw, flag, platform);
+            continue;
+        }
+        if (raw.length === 0 || raw.includes("\0")) {
+            throw new CliUsageError("--server-name requires one valid entry name.");
+        }
+        serverName = raw;
+    }
+    if ((configPath === undefined) !== (serverName === undefined)) {
+        throw new CliUsageError("--config-path and --server-name must be provided together.");
+    }
+    return {
+        json,
+        ...(configPath === undefined ? {} : { configPath, serverName: serverName }),
+    };
+}
 export function parseCliArguments(argv, platform = process.platform) {
     if (argv.length === 0)
         return { command: "server" };
@@ -108,8 +164,7 @@ export function parseCliArguments(argv, platform = process.platform) {
         return { command: "setup", arguments: parseSetupArguments(values, platform) };
     }
     if (command === "doctor") {
-        const flags = parseBooleanFlags("doctor", values, new Set(["--json"]));
-        return { command: "doctor", json: flags.has("--json") };
+        return { command: "doctor", ...parseDoctorArguments(values, platform) };
     }
     if (command === "clean") {
         requireNoArguments("clean", values);

package/dist/cli/config-inspection.d.ts

@@ -0,0 +1,59 @@
+import { type BigIntStats } from "node:fs";
+export interface ConfigInspectionHandle {
+    stat(options: {
+        bigint: true;
+    }): Promise<BigIntStats>;
+    read(buffer: Buffer, offset: number, length: number, position: number): Promise<{
+        bytesRead: number;
+        buffer: Buffer;
+    }>;
+    close(): Promise<void>;
+}
+export interface ConfigInspectionFileSystem {
+    lstat(candidate: string): Promise<BigIntStats>;
+    open(candidate: string, flags: number): Promise<ConfigInspectionHandle>;
+}
+export declare class ConfigInspectionError extends Error {
+    readonly code: string;
+    readonly constraints?: {
+        readonly max_bytes: number;
+    };
+    constructor(code: string, message: string, constraints?: {
+        readonly max_bytes: number;
+    });
+}
+export type ConfigEntryStatus = "present" | "missing" | "invalid";
+export type ConfigTransportShape = "local_command" | "remote_url" | "unknown";
+export type ConfiguredApiKeyStatus = "literal_present" | "reference_present" | "absent" | "unknown";
+export type AllowedRootSafety = "safe" | "unsafe" | "unknown";
+export type CommandCategory = "package_runner" | "shell" | "runtime" | "executable";
+export interface ExplicitConfigInspection {
+    readonly inspection_scope: "explicit_config";
+    readonly entry: {
+        readonly status: ConfigEntryStatus;
+    };
+    readonly transport: {
+        readonly shape: ConfigTransportShape;
+        readonly command?: {
+            readonly basename: string;
+            readonly category: CommandCategory;
+        };
+    };
+    readonly package_version?: string;
+    readonly api_key: {
+        readonly status: ConfiguredApiKeyStatus;
+    };
+    readonly allowed_roots: {
+        readonly count: number;
+        readonly safety: Exclude<AllowedRootSafety, "unknown">;
+    } | {
+        readonly safety: "unknown";
+    };
+}
+export interface InspectExplicitConfigOptions {
+    readonly configPath: string;
+    readonly serverName: string;
+    readonly platform?: NodeJS.Platform;
+    readonly fileSystem?: ConfigInspectionFileSystem;
+}
+export declare function inspectExplicitConfig(options: InspectExplicitConfigOptions): Promise<ExplicitConfigInspection>;