@cueai/omni-reader-mcp 1.2.1 → 1.3.0

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.1 setup
+npx -y @cueai/omni-reader-mcp@1.3.0 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.1 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
-npx -y @cueai/omni-reader-mcp@1.2.1 setup --client cursor --add-root /absolute/minimum/root --yes --json
-npx -y @cueai/omni-reader-mcp@1.2.1 setup --client claude-desktop --allowed-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.3.0 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.3.0 setup --client cursor --add-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.3.0 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.1 setup --client cursor --allowed-root /absolute/minimum/root --headless --json
+npx -y @cueai/omni-reader-mcp@1.3.0 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.1 doctor
-npx -y @cueai/omni-reader-mcp@1.2.1 doctor --json
-npx -y @cueai/omni-reader-mcp@1.2.1 clean
-npx -y @cueai/omni-reader-mcp@1.2.1 uninstall --yes --json
+npx -y @cueai/omni-reader-mcp@1.3.0 doctor
+npx -y @cueai/omni-reader-mcp@1.3.0 doctor --json
+npx -y @cueai/omni-reader-mcp@1.3.0 clean
+npx -y @cueai/omni-reader-mcp@1.3.0 uninstall --yes --json
 ```
 
 Running the pinned version without a command starts the stdio MCP server:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.2.1
+npx -y @cueai/omni-reader-mcp@1.3.0
 ```
 
 `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 the currently trusted 1.2.1 Bridge entry; when a
+`uninstall --yes --json` removes only a trusted 1.2.2 or 1.3.0 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.1.1:
+To roll back from 1.3.0:
 
 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.d.ts

@@ -7,6 +7,10 @@ export interface AgentConfigEnvironment {
     readonly env?: Readonly<Record<string, string | undefined>>;
 }
 export type AgentConfigStatus = "configured" | "not configured" | "invalid or unreadable";
+export interface AgentConfigInspection {
+    readonly status: AgentConfigStatus;
+    readonly version?: string;
+}
 interface JsonPreviousEntry {
     readonly format: "json";
     readonly value: unknown;
@@ -40,6 +44,7 @@ export declare function buildAgentEntry(target: AgentTarget, extraRoots: readonl
 export declare function prepareAgentConfig(target: AgentTarget, extraRoots: readonly string[], environment: AgentConfigEnvironment): Promise<PreparedAgentConfig>;
 export declare function verifyPreparedAgentConfig(prepared: PreparedAgentConfig): Promise<void>;
 export declare function writePreparedAgentConfig(prepared: PreparedAgentConfig): Promise<void>;
+export declare function inspectAgentConfigDetails(configPath: string, environment?: AgentConfigEnvironment, target?: NativeAgentTarget): Promise<AgentConfigInspection>;
 export declare function inspectAgentConfig(configPath: string, environment?: AgentConfigEnvironment, target?: NativeAgentTarget): Promise<AgentConfigStatus>;
 export declare function detectAgentTargets(environment: AgentConfigEnvironment): Promise<NativeAgentTarget[]>;
 export declare function configContainsOmni(configPath: string): Promise<boolean>;

package/dist/cli/agent-config.js

@@ -4,7 +4,9 @@ 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.2";
 const LEGACY_PACKAGE_SPEC = "@cueai/omni-reader-mcp";
+const TRUSTED_EXACT_PACKAGE_SPECS = new Set([PREVIOUS_PACKAGE_SPEC, PACKAGE_SPEC]);
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -543,7 +545,8 @@ function isExpectedOmniEntry(target, value) {
         !Array.isArray(args) ||
         args.length !== 2 ||
         args[0] !== "-y" ||
-        args[1] !== PACKAGE_SPEC)
+        typeof args[1] !== "string" ||
+        !TRUSTED_EXACT_PACKAGE_SPECS.has(args[1]))
         return false;
     const keys = Object.keys(value).sort();
     if (value.env === undefined) {
@@ -579,6 +582,12 @@ function isExpectedOmniEntry(target, value) {
         && keys[1] === "command"
         && keys[2] === "env";
 }
+function expectedBridgeVersion(target, value) {
+    if (!isExpectedOmniEntry(target, value))
+        return undefined;
+    const packageSpec = value.args[1];
+    return packageSpec === PREVIOUS_PACKAGE_SPEC ? "1.2.2" : BRIDGE_RELEASE_VERSION;
+}
 function isLegacyBridgeEntry(target, value) {
     if (!isRecord(value) || value.command !== "npx")
         return false;
@@ -586,7 +595,8 @@ function isLegacyBridgeEntry(target, value) {
     if (!Array.isArray(args) ||
         args.length !== 2 ||
         args[0] !== "-y" ||
-        (args[1] !== LEGACY_PACKAGE_SPEC && args[1] !== PACKAGE_SPEC))
+        typeof args[1] !== "string" ||
+        (args[1] !== LEGACY_PACKAGE_SPEC && !TRUSTED_EXACT_PACKAGE_SPECS.has(args[1])))
         return false;
     if (value.env === undefined)
         return target !== "hermes";
@@ -742,6 +752,7 @@ export async function prepareAgentConfig(target, extraRoots, environment) {
         environment,
         reload: reloadInstruction("hermes"),
         format,
+        serializedBefore: loaded.serialized,
         serializedAfter,
         previousEntry,
     };
@@ -786,9 +797,11 @@ async function atomicReplace(filePath, content) {
         await handle.sync();
         await handle.close();
         handle = undefined;
+        await chmod(temporaryPath, 0o600);
         await rename(temporaryPath, filePath);
-        await chmod(filePath, 0o600);
-        await syncDirectory(directory);
+        // Rename is the commit point. Do not throw afterward: callers cannot safely
+        // roll back a committed user-config write without racing an external editor.
+        await syncDirectory(directory).catch(() => undefined);
     }
     finally {
         await handle?.close();
@@ -912,6 +925,17 @@ export async function verifyPreparedAgentConfig(prepared) {
         throw fileError("The Agent configuration changed after preview; no changes were written.");
     }
 }
+async function restoreTrustedBackup(backupPath, backup) {
+    if (backup !== undefined) {
+        await atomicReplace(backupPath, `${JSON.stringify(backup, null, 2)}\n`);
+        return;
+    }
+    await unlink(backupPath).catch((error) => {
+        if (error.code !== "ENOENT")
+            throw error;
+    });
+    await syncDirectory(path.dirname(backupPath));
+}
 export async function writePreparedAgentConfig(prepared) {
     if (prepared.configPath === undefined ||
         prepared.environment === undefined ||
@@ -919,36 +943,56 @@ export async function writePreparedAgentConfig(prepared) {
         prepared.serializedAfter === undefined)
         return;
     await withConfigLock(prepared.configPath, prepared.environment, async () => {
-        const current = await readConfig(prepared.configPath);
+        const configPath = prepared.configPath;
+        const current = await readConfig(configPath);
         if (current.fingerprint !== prepared.sourceFingerprint) {
             throw fileError("The Agent configuration changed after preview; no changes were written.");
         }
         const backup = trustedBackup(prepared);
-        const backupPath = agentBackupPath(prepared.configPath);
-        const existingBackup = await readTrustedBackup(prepared.configPath);
-        if (existingBackup === undefined) {
-            await atomicReplace(backupPath, `${JSON.stringify(backup, null, 2)}\n`);
-        }
-        else {
-            const currentEntryMatches = await configHasExpectedEntry(prepared.target, current);
-            if (currentEntryMatches && existingBackup.target === prepared.target) {
-                const updatedBackup = {
+        const backupPath = agentBackupPath(configPath);
+        const existingBackup = await readTrustedBackup(configPath);
+        let replacementBackup = backup;
+        if (existingBackup !== undefined) {
+            const currentEntry = expectedConfigEntry(prepared.target, current);
+            if (currentEntry !== undefined && existingBackup.target === prepared.target) {
+                if (existingBackup.bridge_entry_digest !== entryDigest(currentEntry)) {
+                    throw fileError("A conflicting trusted Omni backup already exists; no changes were written.");
+                }
+                replacementBackup = {
                     ...existingBackup,
                     bridge_entry_digest: entryDigest(prepared.entry),
                 };
-                if (JSON.stringify(updatedBackup) !== JSON.stringify(existingBackup)) {
-                    await atomicReplace(backupPath, `${JSON.stringify(updatedBackup, null, 2)}\n`);
-                }
             }
             else if (JSON.stringify(existingBackup) !== JSON.stringify(backup)) {
                 throw fileError("A conflicting trusted Omni backup already exists; no changes were written.");
             }
+            else {
+                replacementBackup = existingBackup;
+            }
         }
-        const immediatelyBeforeWrite = await readConfig(prepared.configPath);
-        if (immediatelyBeforeWrite.fingerprint !== current.fingerprint) {
-            throw fileError("The Agent configuration changed during setup; no changes were written.");
+        const backupNeedsWrite = existingBackup === undefined ||
+            JSON.stringify(replacementBackup) !== JSON.stringify(existingBackup);
+        try {
+            if (backupNeedsWrite) {
+                await atomicReplace(backupPath, `${JSON.stringify(replacementBackup, null, 2)}\n`);
+            }
+            const immediatelyBeforeWrite = await readConfig(configPath);
+            if (immediatelyBeforeWrite.fingerprint !== current.fingerprint) {
+                throw fileError("The Agent configuration changed during setup; no changes were written.");
+            }
+            await atomicReplace(configPath, prepared.serializedAfter);
+        }
+        catch (error) {
+            try {
+                if (backupNeedsWrite) {
+                    await restoreTrustedBackup(backupPath, existingBackup);
+                }
+            }
+            catch {
+                throw fileError("The Agent configuration write failed and trusted rollback state could not be restored.");
+            }
+            throw error;
         }
-        await atomicReplace(prepared.configPath, prepared.serializedAfter);
     });
 }
 function jsonConfigEntry(value) {
@@ -956,49 +1000,64 @@ function jsonConfigEntry(value) {
         return undefined;
     return onlyOmniEntry(value.mcpServers).value;
 }
-async function configHasExpectedEntry(target, loaded) {
+function expectedConfigEntry(target, loaded) {
     if (target === "hermes") {
         const document = parseHermesDocument(loaded.serialized);
         const entry = hermesOmniEntry(document);
-        return entry !== undefined && isExpectedOmniEntry(target, parseHermesEntry(entry));
+        if (entry === undefined)
+            return undefined;
+        const value = parseHermesEntry(entry);
+        return isExpectedOmniEntry(target, value) ? value : undefined;
     }
     assertNoDuplicateJsonOmniEntries(loaded.serialized);
-    const value = parseJsonConfig(loaded);
-    return isExpectedOmniEntry(target, jsonConfigEntry(value));
+    const value = jsonConfigEntry(parseJsonConfig(loaded));
+    return isExpectedOmniEntry(target, value) ? value : undefined;
 }
-export async function inspectAgentConfig(configPath, environment, target) {
+async function configHasExpectedEntry(target, loaded) {
+    return expectedConfigEntry(target, loaded) !== undefined;
+}
+export async function inspectAgentConfigDetails(configPath, environment, target) {
     try {
         if (environment !== undefined)
             await validateUserConfigPath(configPath, environment);
         const loaded = await readConfig(configPath);
         if (!loaded.existed)
-            return "not configured";
+            return { status: "not configured" };
         const resolvedTarget = target ?? (configPath.endsWith("config.yaml") ? "hermes" : "cursor");
         if (resolvedTarget === "hermes") {
             const document = parseHermesDocument(loaded.serialized);
             const entry = hermesOmniEntry(document);
             if (entry === undefined)
-                return "not configured";
+                return { status: "not configured" };
             const value = parseHermesEntry(entry);
-            if (isExpectedOmniEntry("hermes", value))
-                return "configured";
-            return isCanonicalRemoteEntry(value) ? "not configured" : "invalid or unreadable";
+            const version = expectedBridgeVersion("hermes", value);
+            if (version !== undefined)
+                return { status: "configured", version };
+            return {
+                status: isCanonicalRemoteEntry(value) ? "not configured" : "invalid or unreadable",
+            };
         }
         assertNoDuplicateJsonOmniEntries(loaded.serialized);
         const value = parseJsonConfig(loaded);
         if (!isRecord(value.mcpServers))
-            return "not configured";
+            return { status: "not configured" };
         const entry = onlyOmniEntry(value.mcpServers).value;
         if (entry === undefined)
-            return "not configured";
-        if (isExpectedOmniEntry(resolvedTarget, entry))
-            return "configured";
-        return isCanonicalRemoteEntry(entry) ? "not configured" : "invalid or unreadable";
+            return { status: "not configured" };
+        const version = expectedBridgeVersion(resolvedTarget, entry);
+        if (version !== undefined)
+            return { status: "configured", version };
+        return {
+            status: isCanonicalRemoteEntry(entry) ? "not configured" : "invalid or unreadable",
+        };
     }
     catch {
-        return "invalid or unreadable";
+        return { status: "invalid or unreadable" };
     }
 }
+export async function inspectAgentConfig(configPath, environment, target) {
+    return (await inspectAgentConfigDetails(configPath, environment, target)).status;
+}
 export async function detectAgentTargets(environment) {
     const detected = [];
     for (const target of ["hermes", "cursor", "claude-desktop"]) {
@@ -1056,6 +1115,15 @@ export async function rollbackPreparedAgentConfig(prepared) {
         if (!current.existed || current.serialized !== prepared.serializedAfter) {
             throw fileError("The Agent configuration changed before rollback; automatic rollback stopped.");
         }
+        const backupPath = agentBackupPath(prepared.configPath);
+        const backup = await readTrustedBackup(prepared.configPath);
+        const predecessor = prepared.existed
+            ? expectedConfigEntry(prepared.target, {
+                existed: true,
+                serialized: prepared.serializedBefore,
+                fingerprint: prepared.sourceFingerprint ?? "unused",
+            })
+            : undefined;
         if (prepared.existed) {
             await atomicReplace(prepared.configPath, prepared.serializedBefore);
         }
@@ -1063,10 +1131,22 @@ export async function rollbackPreparedAgentConfig(prepared) {
             await unlink(prepared.configPath);
             await syncDirectory(path.dirname(prepared.configPath));
         }
-        await unlink(agentBackupPath(prepared.configPath)).catch((error) => {
-            if (error.code !== "ENOENT")
-                throw error;
-        });
+        if (backup !== undefined &&
+            predecessor !== undefined &&
+            backup.target === prepared.target &&
+            backup.source_fingerprint !== prepared.sourceFingerprint) {
+            const restoredBackup = {
+                ...backup,
+                bridge_entry_digest: entryDigest(predecessor),
+            };
+            await atomicReplace(backupPath, `${JSON.stringify(restoredBackup, null, 2)}\n`);
+        }
+        else {
+            await unlink(backupPath).catch((error) => {
+                if (error.code !== "ENOENT")
+                    throw error;
+            });
+        }
         await syncDirectory(path.dirname(prepared.configPath));
     });
 }

package/dist/cli/doctor.js

@@ -1,9 +1,9 @@
 import { constants as fsConstants } from "node:fs";
 import { lstat, open, readdir } from "node:fs/promises";
 import path from "node:path";
-import { BRIDGE_RELEASE_VERSION, DEFAULT_CUBE_BASE_URL, GRANTED_STREAM_PROTOCOL_VERSION, MAX_FILE_BYTES, CUBE_GRANT_PROTOCOL_VERSION, } from "../constants.js";
+import { DEFAULT_CUBE_BASE_URL, GRANTED_STREAM_PROTOCOL_VERSION, MAX_FILE_BYTES, CUBE_GRANT_PROTOCOL_VERSION, } from "../constants.js";
 import { API_KEY_URL, getOnboardingPolicyWithTimeout, onboardingGuidance, } from "../onboarding-policy.js";
-import { agentConfigPath, inspectAgentConfig, } from "./agent-config.js";
+import { agentConfigPath, inspectAgentConfigDetails, } from "./agent-config.js";
 const CUBE_HEALTH_PATH = "/api/omni-reader/direct-upload/v1/health";
 const GRANTED_UPLOAD_HEALTH_URL = "https://cubefile.ai.iiis.co:9443/omni/granted/health";
 function isHealthBody(value) {
@@ -137,13 +137,9 @@ async function clientAdapterFacts(options) {
         ["claude_desktop", "claude-desktop"],
     ]) {
         const configPath = agentConfigPath(target, options);
-        const status = configPath === undefined
-            ? "not configured"
-            : await inspectAgentConfig(configPath, options, target);
-        result[label] = {
-            status,
-            ...(status === "configured" ? { version: BRIDGE_RELEASE_VERSION } : {}),
-        };
+        result[label] = configPath === undefined
+            ? { status: "not configured" }
+            : await inspectAgentConfigDetails(configPath, options, target);
     }
     return result;
 }

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.1";
+export declare const BRIDGE_RELEASE_VERSION = "1.3.0";
 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.1";
+export const BRIDGE_RELEASE_VERSION = "1.3.0";
 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/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

@@ -64,10 +64,25 @@ export const cancelParseSchema = z
 export const readResultSchema = z
     .object({
     result_id: resultIdSchema,
-    cursor: z.string().min(1).max(2048).optional(),
+    cursor: z
+        .string()
+        .min(1)
+        .max(2048)
+        .describe("Pass the previous result's next_cursor as this cursor.")
+        .optional(),
     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/remote-client.js

@@ -186,8 +186,29 @@ function decodeEnvelope(value, requestId) {
         throw protocolError();
     }
     const result = envelope.result;
+    let candidate = result.structuredContent;
+    if (candidate === undefined) {
+        const content = result.content;
+        if (!Array.isArray(content) || content.length !== 1) {
+            throw protocolError();
+        }
+        const item = content[0];
+        if (item === null
+            || typeof item !== "object"
+            || Array.isArray(item)
+            || item.type !== "text"
+            || typeof item.text !== "string") {
+            throw protocolError();
+        }
+        try {
+            candidate = JSON.parse(item.text);
+        }
+        catch {
+            throw protocolError();
+        }
+    }
     try {
-        return parseResultSchema.parse(result.structuredContent);
+        return parseResultSchema.parse(candidate);
     }
     catch {
         throw protocolError();
@@ -302,7 +323,10 @@ export class HttpRemoteOmniClient {
                 retryable: false,
             });
         }
-        let args = { source: classified.source };
+        let args = {
+            source: classified.source,
+            wait: false,
+        };
         if (detail === "grounded" || detail === "layout") {
             // D2-D Task 14: the URL profile is obtained and selected BEFORE any
             // non-text tools/call is constructed. Detail is sent only for a valid
@@ -310,7 +334,7 @@ export class HttpRemoteOmniClient {
             // UNSUPPORTED_DETAIL and zero tools/call requests.
             const capabilities = await this.initializeCapabilities(signal);
             selectUrlProfile(capabilities, detail);
-            args = { source: classified.source, detail };
+            args = { source: classified.source, detail, wait: false };
         }
         return this.#call("parse", args, clientRequestId, signal);
     }

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";
@@ -70,11 +71,30 @@ export type ParseResult = {
     status: "canceled";
     operation_id: string;
     cleanup_deadline?: string;
+    billing?: {
+        credits_charged: number;
+        credits_remaining: number;
+    };
     data_handling: DataHandling;
 } | {
     status: "expired";
     operation_id: string;
     requires_user_confirmation: true;
+    billing?: {
+        credits_charged: number;
+        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>;
@@ -586,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,7 +1,45 @@
 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
+    .string()
+    .min(1)
+    .max(2048)
+    .describe("Pass this value as cursor in the next read_result call.");
 const constraintsSchema = z
     .object({
     max_bytes: z.number().int().nonnegative().optional(),
@@ -76,7 +114,7 @@ const artifactResultSchema = z
     result_bytes: z.number().int().nonnegative(),
     expires_at: z.string().datetime({ offset: true }),
     preview: z.string(),
-    next_cursor: z.string().min(1).max(2048),
+    next_cursor: nextCursorSchema,
 })
     .strict();
 const billingSchema = z
@@ -105,7 +143,7 @@ const contentStorageSchema = z.discriminatedUnion("kind", [
     z
         .object({
         kind: z.literal("artifact"),
-        next_cursor: z.string().min(1).max(2048),
+        next_cursor: nextCursorSchema,
         preview: z.string().optional(),
     })
         .strict(),
@@ -120,7 +158,7 @@ const groundingStorageSchema = z.discriminatedUnion("kind", [
     z
         .object({
         kind: z.literal("artifact"),
-        next_cursor: z.string().min(1).max(2048),
+        next_cursor: nextCursorSchema,
     })
         .strict(),
 ]);
@@ -218,6 +256,7 @@ export const parseResultSchema = z.discriminatedUnion("status", [
         status: z.literal("canceled"),
         operation_id: operationIdSchema,
         cleanup_deadline: z.string().datetime({ offset: true }).optional(),
+        billing: billingSchema.optional(),
         data_handling: dataHandlingSchema,
     })
         .strict(),
@@ -226,6 +265,7 @@ export const parseResultSchema = z.discriminatedUnion("status", [
         status: z.literal("expired"),
         operation_id: operationIdSchema,
         requires_user_confirmation: z.literal(true),
+        billing: billingSchema.optional(),
     })
         .strict(),
 ]);
@@ -235,7 +275,7 @@ const resultChunkSchema = z
     result_bytes: z.number().int().nonnegative(),
     expires_at: z.string().datetime({ offset: true }),
     text: z.string(),
-    next_cursor: z.string().min(1).max(2048).optional(),
+    next_cursor: nextCursorSchema.optional(),
 })
     .strict();
 // v3 part read (D2-D item 9): closed chunk with part/media type/offset/
@@ -253,7 +293,7 @@ const bundlePartReadChunkSchema = z
         offset: z.number().int().nonnegative(),
         decoded_bytes: z.number().int().nonnegative(),
         text: z.string(),
-        next_cursor: z.string().min(1).max(2048).optional(),
+        next_cursor: nextCursorSchema.optional(),
         expires_at: z.string().datetime({ offset: true }),
     })
         .strict(),
@@ -266,7 +306,7 @@ const bundlePartReadChunkSchema = z
         offset: z.number().int().nonnegative(),
         decoded_bytes: z.number().int().nonnegative(),
         text: z.string(),
-        next_cursor: z.string().min(1).max(2048).optional(),
+        next_cursor: nextCursorSchema.optional(),
         expires_at: z.string().datetime({ offset: true }),
     })
         .strict(),
@@ -287,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) {
@@ -452,7 +482,7 @@ export function registerOmniTools(server, dependencies, taskStore) {
         },
     }, (args, extra) => callCancel(args.operation_id, extra, dependencies));
     server.registerTool("read_result", {
-        description: "Read one UTF-8 chunk from a Bridge-created local result artifact.",
+        description: "Read one UTF-8 chunk from a Bridge-created local result artifact. Pass each returned next_cursor as cursor in the next call until it is absent.",
         inputSchema: readResultSchema,
         outputSchema: readResultToolOutputSchema,
         annotations: {
@@ -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.1",
+  "version": "1.3.0",
   "description": "Local stdio MCP bridge for direct Omni document parsing",
   "type": "module",
   "license": "UNLICENSED",