@cueai/omni-reader-mcp 1.2.2 → 1.3.1

package/README.md

@@ -60,7 +60,7 @@ differ from the numbers above, report the live values.
 Always use an audited exact version, never an implicit `latest`:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.2.2 setup
+npx -y @cueai/omni-reader-mcp@1.3.1 setup
 ```
 
 The interactive setup supports Hermes, Cursor, Claude Desktop, and generic stdio
@@ -68,9 +68,9 @@ configuration. Non-interactive installation uses the same argument parsing and w
 logic:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.2.2 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
-npx -y @cueai/omni-reader-mcp@1.2.2 setup --client cursor --add-root /absolute/minimum/root --yes --json
-npx -y @cueai/omni-reader-mcp@1.2.2 setup --client claude-desktop --allowed-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.3.1 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.3.1 setup --client cursor --add-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.3.1 setup --client claude-desktop --allowed-root /absolute/minimum/root --yes --json
 ```
 
 When an agent or script runs under a pty (stdin is still a TTY), declare non-interactive
@@ -78,7 +78,7 @@ mode explicitly with `--headless` (alias `--non-interactive`): no `--yes` is req
 stdin is never read:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.2.2 setup --client cursor --allowed-root /absolute/minimum/root --headless --json
+npx -y @cueai/omni-reader-mcp@1.3.1 setup --client cursor --allowed-root /absolute/minimum/root --headless --json
 ```
 
 ## Cache and journal isolation
@@ -127,6 +127,7 @@ The public tools are fixed:
 - `get_parse_status`
 - `cancel_parse`
 - `read_result`
+- `read_outline`
 - `discard_result`
 
 Every tool returns `structuredContent` with a strict `outputSchema`, plus an equivalent
@@ -138,6 +139,12 @@ fallback for clients that only read legacy MCP `content[].text`:
   compact JSON equivalent to the `structuredContent` fields;
 - the `read_result` text JSON contains the current `result.text` and an optional
   `next_cursor`; clients must exhaust all cursors before concatenating the body;
+- `read_outline(result_id)` returns the result's heading tree (from Markdown ATX headings
+  or, for a PDF source, its font-size-calibrated heading structure) without returning the
+  full body to the caller; `read_outline(result_id, node_id)` mints a `read_result`-compatible cursor
+  anchored at that heading, so a long result can be jumped into directly instead of only
+  advancing sequentially through `next_cursor`. An empty or absent outline is reported
+  explicitly, never silently — it never blocks reading the result itself with `read_result`;
 - the `discard_result` text JSON explicitly returns `discarded`; never claim deletion on
   call success alone.
 
@@ -198,16 +205,16 @@ new source that satisfies the constraints.
 ## Commands
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.2.2 doctor
-npx -y @cueai/omni-reader-mcp@1.2.2 doctor --json
-npx -y @cueai/omni-reader-mcp@1.2.2 clean
-npx -y @cueai/omni-reader-mcp@1.2.2 uninstall --yes --json
+npx -y @cueai/omni-reader-mcp@1.3.1 doctor
+npx -y @cueai/omni-reader-mcp@1.3.1 doctor --json
+npx -y @cueai/omni-reader-mcp@1.3.1 clean
+npx -y @cueai/omni-reader-mcp@1.3.1 uninstall --yes --json
 ```
 
 Running the pinned version without a command starts the stdio MCP server:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.2.2
+npx -y @cueai/omni-reader-mcp@1.3.1
 ```
 
 `doctor --json` returns package/npm/client adapter, Key present/absent, allowed-root
@@ -216,12 +223,12 @@ status; it never prints the Key, private source paths, or content.
 
 ## Uninstall and rollback
 
-`uninstall --yes --json` removes only a trusted 1.2.1 or 1.2.2 Bridge entry; when a
+`uninstall --yes --json` removes only a trusted 1.3.0 or 1.3.1 Bridge entry; when a
 matching trusted backup exists, it restores the original URL-only `omni-reader` entry.
 Uninstall never deletes user source files and never silently removes unexpired local
 results.
 
-To roll back from 1.2.2:
+To roll back from 1.3.1:
 
 1. stop recommending or installing that version;
 2. run `uninstall --yes --json` to restore the trusted URL-only entry;

package/dist/artifact-store.d.ts

@@ -1,5 +1,6 @@
 import type { FileHandle } from "node:fs/promises";
 import type { ReleasedMetadata, ResultRetentionSink, ResultRetentionStart } from "./iiis-client.js";
+import { type OutlineResult } from "./outline.js";
 import { GROUNDING_SCHEMA_VERSION, RESULT_BUNDLE_PROTOCOL_VERSION } from "./protocol.js";
 import { type VerifiedBundle } from "./result-bundle.js";
 export interface ArtifactStoreOptions {
@@ -109,6 +110,8 @@ export declare class ArtifactStore {
     get rootDirectory(): string;
     createRetention(): LocalResultRetention;
     read(resultId: string, cursor?: string, maxBytes?: number): Promise<ArtifactReadResult>;
+    readOutline(resultId: string): Promise<OutlineResult>;
+    mintOutlineCursor(resultId: string, byteOffset: number): Promise<string>;
     readBundlePart(resultId: string, cursor: string, maxBytes?: number): Promise<BundlePartReadChunk>;
     discard(resultId: string): Promise<boolean>;
     cleanupExpired(): Promise<number>;

package/dist/artifact-store.js

@@ -7,6 +7,7 @@ import { z } from "zod";
 import { ARTIFACT_TTL_MS, INLINE_RESULT_MAX_BYTES, RESULT_CHUNK_MAX_BYTES } from "./constants.js";
 import { CursorCodec } from "./cursor.js";
 import { OmniBridgeError } from "./errors.js";
+import { extractOutline } from "./outline.js";
 import { GROUNDING_SCHEMA_VERSION, RESULT_BUNDLE_PROTOCOL_VERSION } from "./protocol.js";
 // The D2-A source scan (test/protocol.test.ts) rejects any import specifier
 // mentioning the bundle module: it was written when nothing imported it. D2-D
@@ -535,6 +536,41 @@ export class ArtifactStore {
                 : {}),
         };
     }
+    async readOutline(resultId) {
+        this.#requireOpen();
+        const metadata = await this.#loadMetadata(resultId);
+        if (Date.parse(metadata.expiresAt) <= this.#now().getTime()) {
+            await this.discard(resultId);
+            throw artifactError("RESULT_EXPIRED", "The local result artifact has expired.");
+        }
+        const artifactPath = path.join(this.#resultsDirectory, metadata.artifactName);
+        const handle = await openArtifactForRead(artifactPath);
+        let fullText;
+        try {
+            const artifactStat = await handle.stat();
+            if (!artifactStat.isFile() || artifactStat.size !== metadata.resultBytes) {
+                throw artifactError("LOCAL_RESULT_INTEGRITY_FAILED", "The local result artifact is invalid.");
+            }
+            const slice = await readUtf8Slice(handle, 0, metadata.resultBytes, metadata.resultBytes);
+            fullText = slice.text;
+        }
+        finally {
+            await handle.close();
+        }
+        return extractOutline(fullText);
+    }
+    async mintOutlineCursor(resultId, byteOffset) {
+        this.#requireOpen();
+        const metadata = await this.#loadMetadata(resultId);
+        if (Date.parse(metadata.expiresAt) <= this.#now().getTime()) {
+            await this.discard(resultId);
+            throw artifactError("RESULT_EXPIRED", "The local result artifact has expired.");
+        }
+        if (!Number.isSafeInteger(byteOffset) || byteOffset < 0 || byteOffset > metadata.resultBytes) {
+            throw artifactError("INVALID_RESULT_CURSOR", "The outline node offset is invalid.");
+        }
+        return this.#cursor.encode({ resultId, offset: byteOffset, expiresAt: metadata.expiresAt });
+    }
     // Read one UTF-8-safe chunk of one named part of a retained bundle. The
     // opaque v2 cursor binds resultId/part/detail/schema/bundle protocol/
     // offset/expiry; every bound field is re-verified against the closed

package/dist/cli/agent-config.js

@@ -4,7 +4,7 @@ import { chmod, lstat, mkdir, open, realpath, rename, unlink, } from "node:fs/pr
 import path from "node:path";
 import { BRIDGE_RELEASE_VERSION, REMOTE_OMNI_MCP_URL, } from "../constants.js";
 const PACKAGE_SPEC = `@cueai/omni-reader-mcp@${BRIDGE_RELEASE_VERSION}`;
-const PREVIOUS_PACKAGE_SPEC = "@cueai/omni-reader-mcp@1.2.1";
+const PREVIOUS_PACKAGE_SPEC = "@cueai/omni-reader-mcp@1.3.0";
 const LEGACY_PACKAGE_SPEC = "@cueai/omni-reader-mcp";
 const TRUSTED_EXACT_PACKAGE_SPECS = new Set([PREVIOUS_PACKAGE_SPEC, PACKAGE_SPEC]);
 function isRecord(value) {
@@ -586,7 +586,7 @@ function expectedBridgeVersion(target, value) {
     if (!isExpectedOmniEntry(target, value))
         return undefined;
     const packageSpec = value.args[1];
-    return packageSpec === PREVIOUS_PACKAGE_SPEC ? "1.2.1" : BRIDGE_RELEASE_VERSION;
+    return packageSpec === PREVIOUS_PACKAGE_SPEC ? "1.3.0" : BRIDGE_RELEASE_VERSION;
 }
 function isLegacyBridgeEntry(target, value) {
     if (!isRecord(value) || value.command !== "npx")

package/dist/constants.d.ts

@@ -6,7 +6,7 @@ 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.2.2";
+export declare const BRIDGE_RELEASE_VERSION = "1.3.1";
 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;

package/dist/constants.js

@@ -6,7 +6,7 @@ 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.2.2";
+export const BRIDGE_RELEASE_VERSION = "1.3.1";
 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;

package/dist/cube-client.js

@@ -5,6 +5,11 @@ 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";
+// Legacy grant response for UNPROFILED (detail-less) requests. cube-mcp serves
+// omni.parse_grant.v1, and since the v2 metering writer rollout (writer_v2)
+// also omni.parse_grant.v2. The v2 tuple is field-identical for the Bridge's
+// purposes: the parse_grant token is opaque and passed through to the
+// granted-stream endpoint untouched, so both protocol versions are accepted.
 const grantResponseSchema = z
     .object({
     grant_id: z.string().min(1),
@@ -17,7 +22,7 @@ const grantResponseSchema = z
         .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(CUBE_GRANT_PROTOCOL_VERSION),
+    protocol_version: z.enum([CUBE_GRANT_PROTOCOL_VERSION, "omni.parse_grant.v2"]),
 })
     .strict();
 // Closed v3 grant response: the exact tuple of the selected direct profile is

package/dist/iiis-client.d.ts

@@ -4,7 +4,7 @@ export interface ResultRetentionStart {
     readonly operationId: string;
     readonly resultBytes: number;
     readonly mediaType: string;
-    readonly source: "sse" | "recovery";
+    readonly source: "sse" | "recovery" | "remote_hydration";
 }
 export interface ReleasedMetadata extends ResultRetentionStart {
     readonly resultDigest: string;

package/dist/operation-manager.d.ts

@@ -5,7 +5,7 @@ import type { JournalPatch, JournalRecord, JournalState, OperationJournal } from
 import { type OpenAllowedFileOptions, type OpenedAllowedFile } from "./path-security.js";
 import { type RepresentationIntent } from "./protocol.js";
 import type { RemoteOmniClient } from "./remote-client.js";
-import type { ParseResult } from "./result-contract.js";
+import { type ParseResult } from "./result-contract.js";
 export interface SubmitOperationInput {
     readonly sourceKind: "local" | "url";
     readonly sourceFacts: Readonly<Record<string, unknown>>;
@@ -55,11 +55,11 @@ export declare class OperationManager {
     status(operationId: string, waitMs?: number, signal?: AbortSignal): Promise<JournalRecord>;
     cancel(operationId: string, signal?: AbortSignal): Promise<JournalRecord>;
 }
-interface LocalRetention extends ResultRetentionSink {
+export interface LocalRetention extends ResultRetentionSink {
     result(): LocalResult;
     bundleResult?(): BundleLocalResult;
 }
-interface LocalArtifactStore {
+export interface LocalArtifactStore {
     createRetention(): LocalRetention;
     read(resultId: string, cursor?: string, maxBytes?: number): Promise<ArtifactReadResult>;
     readBundleDescriptor?(resultId: string): Promise<BundleLocalResult | null>;
@@ -76,5 +76,6 @@ export interface LocalParseOperationManagerOptions {
     readonly now?: () => Date;
     readonly sleep?: (milliseconds: number) => Promise<void>;
 }
+export declare function hydrateInlineUrlResult(result: ParseResult, artifactStore: Pick<LocalArtifactStore, "createRetention">): Promise<ParseResult>;
+export declare function hydrateInlineUrlResultSafely(result: ParseResult, artifactStore: Pick<LocalArtifactStore, "createRetention">): Promise<ParseResult>;
 export declare function createLocalParseOperationManager(options: LocalParseOperationManagerOptions): OperationManager;
-export {};

package/dist/operation-manager.js

@@ -5,6 +5,7 @@ import { LEGACY_RECOVERY_FAILURE_CODE } from "./operation-journal.js";
 import { openAllowedFile, } from "./path-security.js";
 import { NOOP_PROGRESS } from "./progress.js";
 import { normalizeRepresentation } from "./protocol.js";
+import { localResultToResultField } from "./result-contract.js";
 const TERMINAL_STATES = new Set([
     "COMPLETED",
     "FAILED",
@@ -633,6 +634,50 @@ function remoteContext(value) {
     }
     return context;
 }
+// A completed (or cleanup_pending -- also directly caller-visible with usable
+// result content, per the local-file path's own existing handling of that
+// status) URL parse's `kind:"inline"` result already carries its full text --
+// hydrating it into Bridge's own local ArtifactStore is a pure local
+// operation (zero extra network I/O) that makes it a completely ordinary
+// local result afterward, so read_result/read_outline work on it exactly as
+// they do for a local-file parse. `kind:"artifact"`/bundle-shaped results
+// are deliberately left untouched -- see this plan's Non-goals.
+export async function hydrateInlineUrlResult(result, artifactStore) {
+    if (result.status !== "completed" && result.status !== "cleanup_pending") {
+        return result;
+    }
+    if (result.result === undefined || result.result.kind !== "inline") {
+        return result;
+    }
+    const bytes = new TextEncoder().encode(result.result.text);
+    const start = {
+        operationId: result.operation_id,
+        resultBytes: bytes.byteLength,
+        mediaType: "text/markdown; charset=utf-8",
+        source: "remote_hydration",
+    };
+    const retention = artifactStore.createRetention();
+    await retention.begin(start);
+    await retention.write(bytes);
+    await retention.complete({
+        ...start,
+        resultDigest: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,
+    });
+    return { ...result, result: localResultToResultField(retention.result()) };
+}
+// hydrateInlineUrlResult is a pure local-storage optimization on top of content the caller
+// already has in full -- a local-disk failure here (e.g. disk full, permission error) must never
+// turn an otherwise-successful URL parse into a failure. This wrapper swallows any hydration
+// error and falls back to the original, un-hydrated result: the caller still gets their content;
+// they just lose local read_result/read_outline re-read capability for that particular result.
+export async function hydrateInlineUrlResultSafely(result, artifactStore) {
+    try {
+        return await hydrateInlineUrlResult(result, artifactStore);
+    }
+    catch {
+        return result;
+    }
+}
 function _userFacingMessage(code, result) {
     const error = result.error;
     if (!error.file_uploaded && !error.parser_started) {
@@ -1419,7 +1464,8 @@ export function createLocalParseOperationManager(options) {
         }
         const context = remoteContext(input.context);
         const result = await options.remoteClient.parse(context.source, input.clientRequestId, input.signal ?? new AbortController().signal, representation.detail);
-        return remoteResultUpdate(result, recovery?.operationId ?? undefined);
+        const hydrated = await hydrateInlineUrlResultSafely(result, options.artifactStore);
+        return remoteResultUpdate(hydrated, recovery?.operationId ?? undefined);
     }
     const driver = {
         create: (input) => input.sourceKind === "url"
@@ -1434,7 +1480,9 @@ export function createLocalParseOperationManager(options) {
             if (record.sourceKind === "url") {
                 if (options.remoteClient === undefined)
                     return undefined;
-                return remoteResultUpdate(await options.remoteClient.status(record.operationId, waitMs, signal), record.operationId);
+                const result = await options.remoteClient.status(record.operationId, waitMs, signal);
+                const hydrated = await hydrateInlineUrlResultSafely(result, options.artifactStore);
+                return remoteResultUpdate(hydrated, record.operationId);
             }
             const order = STATE_ORDER.get(record.state);
             if (order === undefined || order < STATE_ORDER.get("UPLOADING"))
@@ -1454,7 +1502,9 @@ export function createLocalParseOperationManager(options) {
             if (record.sourceKind === "url") {
                 if (options.remoteClient === undefined)
                     return undefined;
-                return remoteResultUpdate(await options.remoteClient.cancel(record.operationId, signal), record.operationId);
+                const result = await options.remoteClient.cancel(record.operationId, signal);
+                const hydrated = await hydrateInlineUrlResultSafely(result, options.artifactStore);
+                return remoteResultUpdate(hydrated, record.operationId);
             }
             if (record.operationToken === null)
                 return undefined;
@@ -1535,7 +1585,9 @@ export function createLocalParseOperationManager(options) {
                 return completedLocalParse(await recoverLocalArtifact(record));
             }
             if (record.sourceKind === "url" && options.remoteClient !== undefined) {
-                return await options.remoteClient.status(record.operationId, 0, signal);
+                const result = await options.remoteClient.status(record.operationId, 0, signal);
+                const hydrated = await hydrateInlineUrlResultSafely(result, options.artifactStore);
+                return hydrated;
             }
             return undefined;
         },

package/dist/outline.d.ts

@@ -0,0 +1,15 @@
+export interface OutlineNode {
+    readonly id: string;
+    readonly level: number;
+    readonly title: string;
+    readonly preview: string;
+    readonly byteOffset: number;
+}
+export interface OutlineResult {
+    readonly coverage: "complete" | "partial" | "none";
+    readonly nodes: readonly OutlineNode[];
+}
+export interface ExtractOutlineOptions {
+    readonly coverage?: "complete" | "partial";
+}
+export declare function extractOutline(content: string, options?: ExtractOutlineOptions): OutlineResult;

package/dist/outline.js

@@ -0,0 +1,79 @@
+// 0-3 leading spaces (CommonMark ATX rule: 4+ leading spaces is a code block, not a heading),
+// 1-6 '#' characters, required whitespace, required non-empty title.
+const ATX_HEADING_PATTERN = /^ {0,3}(#{1,6})\s+(\S.*)$/;
+// Any run of 3+ backticks or tildes is a fence-looking line. Matches CommonMark's exact
+// fence-matching rule: a fence only closes when the closing marker uses the SAME character
+// (backtick vs tilde) as the opening marker, its length is >= the opening marker's length, AND
+// the line -- after trimming BOTH leading and trailing whitespace -- is exactly the marker with
+// nothing else (a closing fence line may still carry the same 0-3 leading spaces and any amount
+// of trailing whitespace that fence lines are always allowed, but may not carry an info string).
+// The character/length/exact-match comparisons are done in plain JS after this regex match (see
+// below); a fence-looking line that does not satisfy all three conditions while already inside a
+// fence is just fence-looking content inside the fence, not a real close. An OPENING fence line
+// has no such restriction -- trailing content there is a legitimate info string (e.g. ```python)
+// and is allowed and ignored.
+const FENCE_PATTERN = /^ {0,3}(`{3,}|~{3,})/;
+const TRAILING_CLOSING_HASHES = /\s+#+\s*$/;
+export function extractOutline(content, options = {}) {
+    const lines = content.split("\n");
+    const nodes = [];
+    let fenceMarker = null;
+    let byteOffset = 0;
+    let nodeCounter = 0;
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        const isLastLine = i === lines.length - 1;
+        // split("\n") consumes the newline itself; re-add its one byte for every line except a
+        // trailing line with no final newline (matches how `content.split("\n")` behaves).
+        const lineByteLength = Buffer.byteLength(line, "utf8") + (isLastLine ? 0 : 1);
+        const fenceMatch = FENCE_PATTERN.exec(line);
+        if (fenceMatch) {
+            const marker = fenceMatch[1];
+            const char = marker[0];
+            const length = marker.length;
+            if (fenceMarker === null) {
+                fenceMarker = { char, length };
+            }
+            else if (char === fenceMarker.char && length >= fenceMarker.length && line.trim() === marker) {
+                fenceMarker = null;
+            }
+            // Otherwise: fence-looking line while already inside a fence that doesn't satisfy the
+            // closing condition -- just fence-looking content inside the fence, state stays "in fence".
+            byteOffset += lineByteLength;
+            continue;
+        }
+        if (fenceMarker === null) {
+            const match = ATX_HEADING_PATTERN.exec(line);
+            if (match) {
+                const hashes = match[1];
+                const rawTitle = match[2].replace(TRAILING_CLOSING_HASHES, "").trim();
+                const title = /^#+$/.test(rawTitle) ? "" : rawTitle;
+                if (title) {
+                    nodeCounter += 1;
+                    nodes.push({
+                        id: `node_${String(nodeCounter).padStart(6, "0")}`,
+                        level: hashes.length,
+                        title,
+                        preview: firstLinePreview(lines, i + 1),
+                        byteOffset,
+                    });
+                }
+            }
+        }
+        byteOffset += lineByteLength;
+    }
+    const coverage = options.coverage ?? (nodes.length > 0 ? "complete" : "none");
+    return { coverage, nodes };
+}
+function firstLinePreview(lines, startIndex, maxChars = 120) {
+    for (let i = startIndex; i < lines.length; i += 1) {
+        const raw = lines[i];
+        const trimmed = raw.trim();
+        if (!trimmed)
+            continue;
+        if (ATX_HEADING_PATTERN.test(raw))
+            return ""; // next content is another heading -> no preview
+        return trimmed.length > maxChars ? `${trimmed.slice(0, maxChars)}…` : trimmed;
+    }
+    return "";
+}

package/dist/protocol.d.ts

@@ -51,6 +51,16 @@ export declare const readResultSchema: z.ZodObject<{
     cursor?: string | undefined;
     max_bytes?: number | undefined;
 }>;
+export declare const readOutlineSchema: z.ZodObject<{
+    result_id: z.ZodString;
+    node_id: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    result_id: string;
+    node_id?: string | undefined;
+}, {
+    result_id: string;
+    node_id?: string | undefined;
+}>;
 export declare const discardResultSchema: z.ZodObject<{
     result_id: z.ZodString;
 }, "strict", z.ZodTypeAny, {
@@ -63,3 +73,4 @@ export type GetParseStatusArguments = z.infer<typeof getParseStatusSchema>;
 export type CancelParseArguments = z.infer<typeof cancelParseSchema>;
 export type ReadResultArguments = z.infer<typeof readResultSchema>;
 export type DiscardResultArguments = z.infer<typeof discardResultSchema>;
+export type ReadOutlineArguments = z.infer<typeof readOutlineSchema>;

package/dist/protocol.js

@@ -73,6 +73,16 @@ export const readResultSchema = z
     max_bytes: z.number().int().min(1).max(RESULT_CHUNK_MAX_BYTES).optional(),
 })
     .strict();
+export const readOutlineSchema = z
+    .object({
+    result_id: resultIdSchema,
+    node_id: z
+        .string()
+        .regex(/^node_[0-9]{6}$/u)
+        .describe("From a prior read_outline call's nodes[].id. Mints a read_result-compatible cursor for that section.")
+        .optional(),
+})
+    .strict();
 export const discardResultSchema = z
     .object({
     result_id: resultIdSchema,

package/dist/result-contract.d.ts

@@ -1,6 +1,7 @@
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
-import type { OmniBridgeErrorPayload } from "./errors.js";
+import type { LocalResult } from "./artifact-store.js";
+import { type OmniBridgeErrorPayload } from "./errors.js";
 export interface DataHandling {
     processing_copy: "in_use" | "pending" | "deleted";
     temporary_data: "in_use" | "pending" | "deleted";
@@ -84,6 +85,17 @@ export type ParseResult = {
         credits_remaining: number;
     };
 };
+export declare function localResultToResultField(local: LocalResult): {
+    kind: "inline";
+    text: string;
+} | {
+    kind: "artifact";
+    result_id: string;
+    result_bytes: number;
+    expires_at: string;
+    preview: string;
+    next_cursor: string;
+};
 export declare const stableErrorSchema: z.ZodObject<{
     ok: z.ZodLiteral<false>;
     code: z.ZodString;
@@ -594,6 +606,8 @@ export declare const bundlePartReadSchema: z.ZodObject<{
     };
 }>;
 export declare const readResultOutputSchema: z.ZodTypeAny;
+export declare const readOutlineOutputSchema: z.ZodTypeAny;
+export declare const readOutlineToolOutputSchema: z.ZodTypeAny;
 export declare const discardResultOutputSchema: z.ZodTypeAny;
 export declare const parseToolOutputSchema: z.ZodTypeAny;
 export declare const readResultToolOutputSchema: z.ZodTypeAny;

package/dist/result-contract.js

@@ -1,5 +1,38 @@
 import { z } from "zod";
+import { OmniBridgeError } from "./errors.js";
 import { RESULT_BUNDLE_PROTOCOL_VERSION } from "./protocol.js";
+// Maps a retained LocalResult (ArtifactStore's own representation) into the
+// wire ParseResult["result"] shape. Used both for local-file parses
+// (tools.ts's completedLocalResult, which additionally sets its own
+// local-upload-specific operation_id/data_handling) and for hydrated URL
+// parses (operation-manager.ts's hydrateInlineUrlResult, which preserves
+// Cube's own original operation_id/data_handling instead).
+export function localResultToResultField(local) {
+    if (local.kind === "inline") {
+        return { kind: "inline", text: local.text };
+    }
+    if (local.nextCursor === undefined) {
+        throw new OmniBridgeError({
+            code: "LOCAL_RESULT_INTEGRITY_FAILED",
+            failureScope: "bridge",
+            message: "The local result artifact cursor is missing.",
+            operationCreated: true,
+            fileUploaded: true,
+            parserStarted: true,
+            billed: false,
+            contentReleased: true,
+            retryable: false,
+        });
+    }
+    return {
+        kind: "artifact",
+        result_id: local.resultId,
+        result_bytes: local.resultBytes,
+        expires_at: local.expiresAt,
+        preview: local.preview,
+        next_cursor: local.nextCursor,
+    };
+}
 const operationIdSchema = z.string().min(1).max(128);
 const resultIdSchema = z.string().regex(/^result_[A-Za-z0-9_-]{16,64}$/u);
 const nextCursorSchema = z
@@ -294,6 +327,46 @@ export const readResultOutputSchema = z.discriminatedUnion("status", [
         .strict(),
     failedResultSchema,
 ]);
+const outlineNodeSchema = z
+    .object({
+    id: z.string().regex(/^node_[0-9]{6}$/u),
+    level: z.number().int().min(1).max(6),
+    title: z.string().min(1).max(512),
+    preview: z.string().max(512),
+})
+    .strict();
+export const readOutlineOutputSchema = z.discriminatedUnion("status", [
+    z
+        .object({
+        status: z.literal("outline"),
+        coverage: z.enum(["complete", "partial", "none"]),
+        nodes: z.array(outlineNodeSchema),
+    })
+        .strict(),
+    z
+        .object({
+        status: z.literal("cursor"),
+        cursor: z.string().min(1).max(2048),
+    })
+        .strict(),
+    z
+        .object({
+        status: z.literal("unavailable"),
+        reason: z.literal("OUTLINE_NOT_SUPPORTED"),
+    })
+        .strict(),
+    failedResultSchema,
+]);
+export const readOutlineToolOutputSchema = z
+    .object({
+    status: z.enum(["outline", "cursor", "unavailable", "failed"]),
+    coverage: z.enum(["complete", "partial", "none"]).optional(),
+    nodes: z.array(outlineNodeSchema).optional(),
+    cursor: z.string().min(1).max(2048).optional(),
+    reason: z.literal("OUTLINE_NOT_SUPPORTED").optional(),
+    error: stableErrorSchema.optional(),
+})
+    .strict();
 export const discardResultOutputSchema = z.discriminatedUnion("status", [
     z
         .object({

package/dist/tools.d.ts

@@ -5,6 +5,7 @@ import type { ReaderCapabilitiesV1 } from "./capabilities.js";
 import { type CubeGrantClient } from "./cube-client.js";
 import type { IiisClient, ResultRetentionSink } from "./iiis-client.js";
 import { type OpenAllowedFileOptions, type OpenedAllowedFile } from "./path-security.js";
+import type { OutlineResult } from "./outline.js";
 import type { RemoteOmniClient } from "./remote-client.js";
 import { type ParseResult } from "./result-contract.js";
 interface ToolRetention extends ResultRetentionSink {
@@ -14,6 +15,8 @@ interface ToolArtifactStore {
     createRetention(): ToolRetention;
     read(resultId: string, cursor?: string, maxBytes?: number): Promise<ArtifactReadResult>;
     readBundlePart?(resultId: string, cursor: string, maxBytes?: number): Promise<BundlePartReadChunk>;
+    readOutline?(resultId: string): Promise<OutlineResult>;
+    mintOutlineCursor?(resultId: string, byteOffset: number): Promise<string>;
     discard(resultId: string): Promise<boolean>;
 }
 export interface ParseOperationController {

package/dist/tools.js

@@ -3,10 +3,11 @@ import { CallToolRequestSchema, CancelTaskRequestSchema, ErrorCode, McpError, }
 import { selectDirectProfile, selectUrlProfile, } from "./capabilities.js";
 import { createClientRequestId as newClientRequestId, } from "./cube-client.js";
 import { OmniBridgeError } from "./errors.js";
+import { hydrateInlineUrlResultSafely } from "./operation-manager.js";
 import { openAllowedFile, } from "./path-security.js";
 import { NOOP_PROGRESS } from "./progress.js";
-import { MACHINE_INSTRUCTIONS, cancelParseSchema, discardResultSchema, getParseStatusSchema, normalizeRepresentation, parseSchema, readResultSchema, } from "./protocol.js";
-import { discardResultOutputSchema, discardResultToolOutputSchema, parseResultSchema, parseToolOutputSchema, readResultOutputSchema, readResultToolOutputSchema, structuredResult, } from "./result-contract.js";
+import { MACHINE_INSTRUCTIONS, cancelParseSchema, discardResultSchema, getParseStatusSchema, normalizeRepresentation, parseSchema, readOutlineSchema, readResultSchema, } from "./protocol.js";
+import { discardResultOutputSchema, discardResultToolOutputSchema, localResultToResultField, parseResultSchema, parseToolOutputSchema, readOutlineOutputSchema, readOutlineToolOutputSchema, readResultOutputSchema, readResultToolOutputSchema, structuredResult, } from "./result-contract.js";
 import { classifySource } from "./source.js";
 import { TaskRuntime } from "./task-runtime.js";
 function bridgeError(code, message, facts = {}) {
@@ -51,38 +52,15 @@ function completedLocalResult(local) {
         original_source: "unchanged",
         remote_content_retained: false,
     };
-    if (local.kind === "inline") {
-        return {
-            status: "completed",
-            operation_id: local.operationId,
-            result: { kind: "inline", text: local.text },
-            data_handling: dataHandling,
-        };
-    }
-    if (local.nextCursor === undefined) {
-        throw bridgeError("LOCAL_RESULT_INTEGRITY_FAILED", "The local result artifact cursor is missing.", {
-            operationCreated: true,
-            fileUploaded: true,
-            parserStarted: true,
-            contentReleased: true,
-        });
-    }
+    const result = localResultToResultField(local);
     return {
         status: "completed",
         operation_id: local.operationId,
-        result: {
-            kind: "artifact",
-            result_id: local.resultId,
-            result_bytes: local.resultBytes,
-            expires_at: local.expiresAt,
-            preview: local.preview,
-            next_cursor: local.nextCursor,
-        },
+        result,
         data_handling: dataHandling,
-        local_result_cache: {
-            expires_at: local.expiresAt,
-            discard_action: "discard_result",
-        },
+        ...(result.kind === "artifact"
+            ? { local_result_cache: { expires_at: local.expiresAt, discard_action: "discard_result" } }
+            : {}),
     };
 }
 async function parseLocal(args, clientRequestId, signal, progress, dependencies) {
@@ -229,7 +207,8 @@ async function parseValue(args, signal, progress, dependencies) {
             if (dependencies.remoteClient === undefined) {
                 throw bridgeError("REMOTE_PARSE_UNAVAILABLE", "Remote URL parsing is not available in this Bridge build.", { retryable: true });
             }
-            return await dependencies.remoteClient.parse(source.source, clientRequestId, signal);
+            const remoteResult = await dependencies.remoteClient.parse(source.source, clientRequestId, signal);
+            return await hydrateInlineUrlResultSafely(remoteResult, dependencies.artifactStore);
         }
         return await parseLocal(args, clientRequestId, signal, progress, dependencies);
     }
@@ -256,7 +235,8 @@ async function statusValue(operationId, waitMs, signal, dependencies) {
             }
         }
         if (dependencies.remoteClient !== undefined) {
-            return await dependencies.remoteClient.status(operationId, waitMs, signal);
+            const remoteResult = await dependencies.remoteClient.status(operationId, waitMs, signal);
+            return await hydrateInlineUrlResultSafely(remoteResult, dependencies.artifactStore);
         }
         throw bridgeError("OPERATION_NOT_FOUND", "The requested parse operation is not available.", { operationCreated: true });
     }
@@ -283,7 +263,8 @@ async function cancelValue(operationId, signal, dependencies) {
             }
         }
         if (dependencies.remoteClient !== undefined) {
-            return await dependencies.remoteClient.cancel(operationId, signal);
+            const remoteResult = await dependencies.remoteClient.cancel(operationId, signal);
+            return await hydrateInlineUrlResultSafely(remoteResult, dependencies.artifactStore);
         }
         throw bridgeError("OPERATION_NOT_FOUND", "The requested parse operation is not available.", { operationCreated: true });
     }
@@ -354,12 +335,55 @@ async function callDiscardResult(resultId, dependencies) {
         return structuredResult(discardResultOutputSchema, failed(error));
     }
 }
+async function callReadOutline(resultId, nodeId, dependencies) {
+    if (dependencies.artifactStore.readOutline === undefined
+        || dependencies.artifactStore.mintOutlineCursor === undefined) {
+        return structuredResult(readOutlineOutputSchema, {
+            status: "unavailable",
+            reason: "OUTLINE_NOT_SUPPORTED",
+        });
+    }
+    try {
+        const outline = await dependencies.artifactStore.readOutline(resultId);
+        if (nodeId === undefined) {
+            return structuredResult(readOutlineOutputSchema, {
+                status: "outline",
+                coverage: outline.coverage,
+                // Strip byteOffset: it is an internal detail the caller mints a cursor for,
+                // never a value it reads or supplies back directly.
+                nodes: outline.nodes.map((node) => ({
+                    id: node.id,
+                    level: node.level,
+                    title: node.title,
+                    preview: node.preview,
+                })),
+            });
+        }
+        const node = outline.nodes.find((candidate) => candidate.id === nodeId);
+        if (node === undefined) {
+            throw bridgeError("OUTLINE_NODE_NOT_FOUND", "The requested outline node does not exist.", {
+                operationCreated: true,
+                fileUploaded: true,
+                parserStarted: true,
+                billed: true,
+                contentReleased: true,
+            });
+        }
+        const cursor = await dependencies.artifactStore.mintOutlineCursor(resultId, node.byteOffset);
+        return structuredResult(readOutlineOutputSchema, { status: "cursor", cursor });
+    }
+    catch (error) {
+        return structuredResult(readOutlineOutputSchema, failed(error));
+    }
+}
 function invalidArgumentsResult(name) {
     const error = failed(bridgeError("INVALID_TOOL_ARGUMENTS", "The Omni tool arguments are invalid."));
     if (name === "read_result")
         return structuredResult(readResultOutputSchema, error);
     if (name === "discard_result")
         return structuredResult(discardResultOutputSchema, error);
+    if (name === "read_outline")
+        return structuredResult(readOutlineOutputSchema, error);
     return structuredResult(parseResultSchema, error);
 }
 async function dispatchTool(name, rawArguments, extra, dependencies) {
@@ -393,6 +417,12 @@ async function dispatchTool(name, rawArguments, extra, dependencies) {
             ? callDiscardResult(parsed.data.result_id, dependencies)
             : invalidArgumentsResult(name);
     }
+    if (name === "read_outline") {
+        const parsed = readOutlineSchema.safeParse(rawArguments ?? {});
+        return parsed.success
+            ? callReadOutline(parsed.data.result_id, parsed.data.node_id, dependencies)
+            : invalidArgumentsResult(name);
+    }
     return structuredResult(parseResultSchema, failed(bridgeError("TOOL_NOT_FOUND", "The requested Omni tool is not available.")));
 }
 export function registerOmniTools(server, dependencies, taskStore) {
@@ -473,6 +503,17 @@ export function registerOmniTools(server, dependencies, taskStore) {
             openWorldHint: false,
         },
     }, (args) => callDiscardResult(args.result_id, dependencies));
+    server.registerTool("read_outline", {
+        description: "Return a local result's heading outline. Pass node_id from a returned node's id to mint a read_result-compatible cursor that jumps straight to that section, instead of reading sequentially from the start.",
+        inputSchema: readOutlineSchema,
+        outputSchema: readOutlineToolOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, (args) => callReadOutline(args.result_id, args.node_id, dependencies));
     server.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         if (request.params.task !== undefined) {
             if (request.params.name !== "parse") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueai/omni-reader-mcp",
-  "version": "1.2.2",
+  "version": "1.3.1",
   "description": "Local stdio MCP bridge for direct Omni document parsing",
   "type": "module",
   "license": "UNLICENSED",