@cueai/omni-reader-mcp 1.5.5 → 1.7.0

package/dist/path-normalization.d.ts

@@ -0,0 +1,5 @@
+export declare class PathNormalizationError extends Error {
+    readonly code = "INVALID_WINDOWS_PATH";
+    constructor();
+}
+export declare function normalizePlatformPath(value: string, platform?: NodeJS.Platform): string;

package/dist/path-normalization.js

@@ -0,0 +1,25 @@
+import path from "node:path";
+const MSYS_DRIVE_PATH = /^\/([A-Za-z])(?:\/|$)/u;
+export class PathNormalizationError extends Error {
+    code = "INVALID_WINDOWS_PATH";
+    constructor() {
+        super("Use an absolute Windows drive path such as C:\\Reports or exact MSYS syntax such as /c/Reports.");
+        this.name = "PathNormalizationError";
+    }
+}
+export function normalizePlatformPath(value, platform = process.platform) {
+    if (platform !== "win32")
+        return value;
+    if (value.startsWith("//") || value.startsWith("\\\\"))
+        return value;
+    const match = MSYS_DRIVE_PATH.exec(value);
+    if (match !== null) {
+        const drive = match[1].toUpperCase();
+        const remainder = value.slice(match[0].length).replaceAll("/", "\\");
+        return path.win32.normalize(`${drive}:\\${remainder}`);
+    }
+    if (value.startsWith("/") || value.startsWith("\\")) {
+        throw new PathNormalizationError();
+    }
+    return value;
+}

package/dist/path-security.d.ts

@@ -9,6 +9,7 @@ export interface OpenAllowedFileOptions {
     workspace: string;
     extraRoots?: readonly string[];
     homeDirectory?: string;
+    platform?: NodeJS.Platform;
     fileSystem?: PathSecurityFileSystem;
 }
 export interface OpenedAllowedFile {
@@ -19,5 +20,5 @@ export interface OpenedAllowedFile {
     createReadStream(): ReadStream;
     close(): Promise<void>;
 }
-export declare function splitAllowedRoots(value: string | undefined): string[];
+export declare function splitAllowedRoots(value: string | undefined, platform?: NodeJS.Platform): string[];
 export declare function openAllowedFile(input: string, options: OpenAllowedFileOptions): Promise<OpenedAllowedFile>;

package/dist/path-security.js

@@ -5,6 +5,7 @@ import { homedir } from "node:os";
 import path from "node:path";
 import { MAX_FILE_BYTES } from "./constants.js";
 import { OmniBridgeError } from "./errors.js";
+import { PathNormalizationError, normalizePlatformPath, } from "./path-normalization.js";
 const CONTENT_TYPES = {
     ".pdf": "application/pdf",
     ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
@@ -92,29 +93,44 @@ function bridgeError(code, message, retryable, constraints) {
         ...(constraints === undefined ? {} : { constraints }),
     });
 }
+function pathsFor(platform) {
+    return platform === "win32" ? path.win32 : path.posix;
+}
 function validatePathText(value) {
     if (value.length === 0 || value.includes("\0")) {
         throw bridgeError("INVALID_LOCAL_PATH", "Provide one valid local file path.", false);
     }
 }
-function expandHomeOnly(value, homeDirectory) {
+function normalizedPath(value, platform) {
+    validatePathText(value);
+    try {
+        return normalizePlatformPath(value, platform);
+    }
+    catch (error) {
+        if (error instanceof PathNormalizationError) {
+            throw bridgeError(error.code, error.message, false);
+        }
+        throw error;
+    }
+}
+function expandHomeOnly(value, homeDirectory, paths) {
     if (value === "~") {
         return homeDirectory;
     }
     if (/^~[\\/]/u.test(value)) {
-        return path.join(homeDirectory, value.slice(2));
+        return paths.join(homeDirectory, value.slice(2));
     }
     return value;
 }
-function isInsideRoot(candidate, root) {
-    const relative = path.relative(root, candidate);
+function isInsideRoot(candidate, root, paths) {
+    const relative = paths.relative(root, candidate);
     return (relative === "" ||
         (relative !== ".." &&
-            !relative.startsWith(`..${path.sep}`) &&
-            !path.isAbsolute(relative)));
+            !relative.startsWith(`..${paths.sep}`) &&
+            !paths.isAbsolute(relative)));
 }
-function requireInsideAnyRoot(candidate, roots) {
-    if (!roots.some((root) => isInsideRoot(candidate, root))) {
+function requireInsideAnyRoot(candidate, roots, paths) {
+    if (!roots.some((root) => isInsideRoot(candidate, root, paths))) {
         throw bridgeError("PATH_NOT_ALLOWED", "Move the file into the current workspace or add its parent directory to OMNI_ALLOWED_ROOTS.", false);
     }
 }
@@ -148,8 +164,8 @@ function redactedSourceFingerprint(fileStat) {
     ].map((value) => value.toString()).join(":");
     return `sha256:${createHash("sha256").update(identity, "utf8").digest("hex")}`;
 }
-function safeFileType(resolvedPath) {
-    const safeExtension = path.extname(resolvedPath).toLowerCase();
+function safeFileType(resolvedPath, paths) {
+    const safeExtension = paths.extname(resolvedPath).toLowerCase();
     if (!/^\.[a-z0-9]{1,10}$/u.test(safeExtension)) {
         throw bridgeError("UNSUPPORTED_MEDIA_TYPE", "The source media type is not supported.", false, { supported_extensions: SUPPORTED_EXTENSIONS });
     }
@@ -175,19 +191,20 @@ function fileAccessError(error) {
     }
     return bridgeError("FILE_NOT_READABLE", "Omni cannot read the local file. Check its permissions and try again.", false);
 }
-async function resolveAllowedRoots(options, fileSystem, homeDirectory) {
-    validatePathText(options.workspace);
-    const workspaceInput = path.resolve(expandHomeOnly(options.workspace, homeDirectory));
+async function resolveAllowedRoots(options, fileSystem, homeDirectory, platform, paths) {
+    const workspace = normalizedPath(options.workspace, platform);
+    const expandedWorkspace = expandHomeOnly(workspace, homeDirectory, paths);
+    const workspaceInput = paths.resolve(normalizedPath(expandedWorkspace, platform));
     const requestedRoots = [
         workspaceInput,
         ...(options.extraRoots ?? [])
             .filter((root) => root.length > 0)
             .map((root) => {
-            validatePathText(root);
-            const expanded = expandHomeOnly(root, homeDirectory);
-            return path.isAbsolute(expanded)
+            const normalizedRoot = normalizedPath(root, platform);
+            const expanded = normalizedPath(expandHomeOnly(normalizedRoot, homeDirectory, paths), platform);
+            return paths.isAbsolute(expanded)
                 ? expanded
-                : path.resolve(workspaceInput, expanded);
+                : paths.resolve(workspaceInput, expanded);
         }),
     ];
     try {
@@ -199,7 +216,7 @@ async function resolveAllowedRoots(options, fileSystem, homeDirectory) {
             }
             return resolved;
         }));
-        return [...new Set(roots)];
+        return { roots: [...new Set(roots)], workspaceInput };
     }
     catch (error) {
         if (error instanceof OmniBridgeError) {
@@ -208,21 +225,25 @@ async function resolveAllowedRoots(options, fileSystem, homeDirectory) {
         throw bridgeError("INVALID_ALLOWED_ROOT", "The workspace or an OMNI_ALLOWED_ROOTS entry is unavailable.", false);
     }
 }
-export function splitAllowedRoots(value) {
+export function splitAllowedRoots(value, platform = process.platform) {
     if (value === undefined || value.length === 0) {
         return [];
     }
-    return value.split(path.delimiter).filter((root) => root.length > 0);
+    return value
+        .split(pathsFor(platform).delimiter)
+        .filter((root) => root.length > 0);
 }
 export async function openAllowedFile(input, options) {
-    validatePathText(input);
+    const platform = options.platform ?? process.platform;
+    const paths = pathsFor(platform);
     const fileSystem = options.fileSystem ?? NODE_FILE_SYSTEM;
     const homeDirectory = options.homeDirectory ?? homedir();
-    const roots = await resolveAllowedRoots(options, fileSystem, homeDirectory);
-    const expanded = expandHomeOnly(input, homeDirectory);
-    const candidate = path.isAbsolute(expanded)
+    const normalizedInput = normalizedPath(input, platform);
+    const expanded = normalizedPath(expandHomeOnly(normalizedInput, homeDirectory, paths), platform);
+    const { roots, workspaceInput } = await resolveAllowedRoots(options, fileSystem, homeDirectory, platform, paths);
+    const candidate = paths.isAbsolute(expanded)
         ? expanded
-        : path.resolve(options.workspace, expanded);
+        : paths.resolve(workspaceInput, expanded);
     let resolved;
     try {
         resolved = await fileSystem.realpath(candidate);
@@ -230,7 +251,7 @@ export async function openAllowedFile(input, options) {
     catch (error) {
         throw fileAccessError(error);
     }
-    requireInsideAnyRoot(resolved, roots);
+    requireInsideAnyRoot(resolved, roots, paths);
     let handle;
     try {
         const pathStat = await fileSystem.stat(resolved);
@@ -244,11 +265,11 @@ export async function openAllowedFile(input, options) {
         requireSameFile(pathStat, before);
         const size = requireAllowedSize(before);
         const afterPath = await fileSystem.realpath(resolved);
-        requireInsideAnyRoot(afterPath, roots);
+        requireInsideAnyRoot(afterPath, roots, paths);
         const after = await fileSystem.stat(afterPath);
         requireRegularFile(after);
         requireSameFile(before, after);
-        const { safeExtension, contentType } = safeFileType(afterPath);
+        const { safeExtension, contentType } = safeFileType(afterPath, paths);
         const opened = new DescriptorBackedFile(handle, size, safeExtension, contentType, redactedSourceFingerprint(before));
         handle = undefined;
         return opened;

package/dist/protocol.d.ts

@@ -1,9 +1,10 @@
 import { z } from "zod";
-export declare const LOCAL_BRIDGE_PROTOCOL_VERSION = "omni.local_bridge_tools.v3";
-export declare const OPERATION_JOURNAL_VERSION = 3;
+export declare const LOCAL_BRIDGE_PROTOCOL_VERSION = "omni.local_bridge_tools.v5";
+export declare const OPERATION_JOURNAL_VERSION = 5;
 export declare const BUNDLE_CURSOR_VERSION = 2;
 export declare const RESULT_BUNDLE_PROTOCOL_VERSION = "omni.result_bundle.v1";
 export declare const GROUNDING_SCHEMA_VERSION = "omni.grounding.v1";
+export type ResultDelivery = "auto" | "artifact";
 export interface RepresentationIntent {
     readonly detail: "text" | "grounded" | "layout";
     readonly groundingSchemaVersion: "none" | "omni.grounding.v1";
@@ -15,31 +16,38 @@ export declare const parseSchemaShape: {
     source: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     url: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     detail: z.ZodOptional<z.ZodEnum<["text", "grounded", "layout"]>>;
+    result_delivery: z.ZodOptional<z.ZodEnum<["auto", "artifact"]>>;
 };
 export declare const parseSchema: z.ZodEffects<z.ZodObject<{
     source: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     url: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
     detail: z.ZodOptional<z.ZodEnum<["text", "grounded", "layout"]>>;
+    result_delivery: z.ZodOptional<z.ZodEnum<["auto", "artifact"]>>;
 }, "strict", z.ZodTypeAny, {
     source?: string | undefined;
     url?: string | undefined;
     detail?: "grounded" | "layout" | "text" | undefined;
+    result_delivery?: "auto" | "artifact" | undefined;
 }, {
     source?: string | undefined;
     url?: string | undefined;
     detail?: "grounded" | "layout" | "text" | undefined;
+    result_delivery?: "auto" | "artifact" | undefined;
 }>, {
     source?: string | undefined;
     url?: string | undefined;
     detail?: "grounded" | "layout" | "text" | undefined;
+    result_delivery?: "auto" | "artifact" | undefined;
 }, {
     source?: string | undefined;
     url?: string | undefined;
     detail?: "grounded" | "layout" | "text" | undefined;
+    result_delivery?: "auto" | "artifact" | undefined;
 }>;
 export interface NormalizedParseArguments {
     readonly source: string;
     readonly detail?: "text" | "grounded" | "layout";
+    readonly resultDelivery: ResultDelivery;
 }
 export declare function normalizeParseArguments(args: ParseArguments): NormalizedParseArguments;
 export declare const getParseStatusSchema: z.ZodObject<{

package/dist/protocol.js

@@ -1,11 +1,7 @@
 import { z } from "zod";
 import { RESULT_CHUNK_MAX_BYTES, STATUS_LONG_POLL_MAX_MS } from "./constants.js";
-export const LOCAL_BRIDGE_PROTOCOL_VERSION = "omni.local_bridge_tools.v3";
-// D2-D item 1: versioned persistence literals frozen with the v3 contract.
-// The journal record version and the bundle cursor version are bumped
-// together with the tool contract; legacy v2 journal records still recover
-// text operations unchanged and are never auto-upgraded.
-export const OPERATION_JOURNAL_VERSION = 3;
+export const LOCAL_BRIDGE_PROTOCOL_VERSION = "omni.local_bridge_tools.v5";
+export const OPERATION_JOURNAL_VERSION = 5;
 export const BUNDLE_CURSOR_VERSION = 2;
 // Canonical bundle/grounding literals carried by non-text representations.
 export const RESULT_BUNDLE_PROTOCOL_VERSION = "omni.result_bundle.v1";
@@ -25,6 +21,7 @@ export function normalizeRepresentation(detail) {
     };
 }
 export const MACHINE_INSTRUCTIONS = [
+    "Use parse as the only first call for both HTTP(S) URLs and local paths; do not ask the user to choose a local, remote, upload, or URL mode.",
     "Pass the user-provided source string directly to parse.",
     "Treat only HTTP(S) as URL; ordinary paths require the local Bridge.",
     "Never read, attach, base64-encode, or insert local source content before calling Omni.",
@@ -36,6 +33,20 @@ export const MACHINE_INSTRUCTIONS = [
     "Do not promise background notification when the client lacks task support.",
     "Do not claim deletion before cleanup is confirmed.",
     "Report authoritative unit progress when present; never treat partial output as final.",
+    "Choose continuation tools from the structured result; do not present the Bridge tool menu to the user.",
+    "Text output is Markdown and may retain headings, lists, GFM tables, or raw HTML tables; it lacks grounding/layout sidecars, not all structure.",
+    "An empty outline means no recognized headings, not that the text has no structure.",
+    "Answer directly → use inline text when present; otherwise read_result",
+    "Find one section → read_outline, then pass its cursor to read_result",
+    "Read all content → read_result until next_cursor is absent",
+    "Deliver a file → save_result",
+    "Outline navigation does not require save_result.",
+    "Use result_delivery=artifact for saving, section navigation, multiple documents, or strict context control.",
+    "Use bounded concurrent independent parse calls for multiple sources; there is no batch_parse tool.",
+    "Discover MCP Tasks, MCP Roots, host tool timeout, and process cwd versus active workspace; do not guess client capabilities.",
+    "Tasks unknown → use ordinary parse and get_parse_status polling.",
+    "Roots unknown → use process cwd and explicitly configured roots only.",
+    "Host timeout unknown → retain the bounded 20-second status wait.",
     "After parsing, continue the user's original task.",
 ].join("\n");
 const operationIdSchema = z.string().regex(/^op_[A-Za-z0-9_-]{16,64}$/u);
@@ -60,6 +71,7 @@ const parseSchemaObject = z
         .refine((value) => !value.includes("\0"))
         .optional(),
     detail: z.enum(["text", "grounded", "layout"]).optional(),
+    result_delivery: z.enum(["auto", "artifact"]).optional(),
 })
     .strict();
 export const parseSchemaShape = parseSchemaObject.shape;
@@ -71,7 +83,11 @@ export function normalizeParseArguments(args) {
         // schema-validated input and guards misuse of the exported helper.
         throw new Error("parse arguments require exactly one of source or url");
     }
-    return { source, detail: args.detail };
+    return {
+        source,
+        detail: args.detail,
+        resultDelivery: args.result_delivery ?? "auto",
+    };
 }
 export const getParseStatusSchema = z
     .object({

package/dist/remote-client.js

@@ -2,7 +2,7 @@ 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 { API_KEY_URL } from "./onboarding-policy.js";
-import { OmniBridgeError } from "./errors.js";
+import { OmniBridgeError, unsupportedDetailError } from "./errors.js";
 import { parseResultSchema } from "./result-contract.js";
 import { classifySource } from "./source.js";
 const INITIALIZE_REQUEST_ID = "initialize";
@@ -108,16 +108,6 @@ 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
@@ -351,7 +341,7 @@ export class HttpRemoteOmniClient {
         }
         const custom = initializeCustomCapability(envelope, INITIALIZE_REQUEST_ID);
         if (custom === undefined) {
-            throw unsupportedDetail();
+            throw unsupportedDetailError("url");
         }
         let capabilities;
         try {
@@ -388,7 +378,7 @@ export class HttpRemoteOmniClient {
             // 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);
+            selectUrlProfile(capabilities, detail, "url");
             args = { source: classified.source, detail, wait: false };
         }
         return this.#call("parse", args, clientRequestId, signal);