@cueai/omni-reader-mcp 1.6.0 → 1.7.0

package/dist/operation-manager.js

@@ -36,6 +36,78 @@ function managerError(code, message, facts = {}) {
         retryable: facts.retryable ?? false,
     });
 }
+function journalIntegrityError(message, record) {
+    return managerError("JOURNAL_INTEGRITY_FAILED", message, record === undefined
+        ? {}
+        : {
+            operationCreated: record.operationId !== null,
+            fileUploaded: record.fileUploaded,
+            parserStarted: record.parserStarted,
+            billed: record.billed,
+            contentReleased: record.contentReleased,
+        });
+}
+function isBillingProfile(profile) {
+    return profile === "omni.direct_text_billing.v1"
+        || profile === "omni.direct_grounding_billing.v1";
+}
+function toJournalBilling(billing) {
+    return {
+        creditsCharged: billing.credits_charged,
+        creditsRemaining: billing.credits_remaining,
+    };
+}
+function toWireBilling(billing) {
+    return {
+        credits_charged: billing.creditsCharged,
+        credits_remaining: billing.creditsRemaining,
+    };
+}
+function resultBilling(result) {
+    if (result.status === "completed"
+        || result.status === "cleanup_pending"
+        || result.status === "canceled"
+        || result.status === "expired") {
+        return result.billing ?? null;
+    }
+    return null;
+}
+function projectBilling(result, billing) {
+    if (billing === null
+        || (result.status !== "completed"
+            && result.status !== "cleanup_pending"
+            && result.status !== "canceled"
+            && result.status !== "expired")) {
+        return result;
+    }
+    return { ...result, billing };
+}
+function requireWireBillingForSettledProfile(profile, billed, billing) {
+    if (!isBillingProfile(profile))
+        return billing ?? undefined;
+    if (!billed && billing !== null) {
+        throw journalIntegrityError("An unbilled direct terminal carries billing facts.");
+    }
+    if (billed && billing === null) {
+        throw journalIntegrityError("New-profile settlement billing is missing.");
+    }
+    return billing ?? undefined;
+}
+function assertDirectTerminalSnapshot(profile, snapshot) {
+    if (!isBillingProfile(profile))
+        return;
+    if ((snapshot.directProfile ?? null) !== profile) {
+        throw journalIntegrityError("IIIS changed the selected direct profile.");
+    }
+    if (snapshot.status === "CANCELED"
+        || snapshot.status === "FAILED"
+        || snapshot.status === "UNSUPPORTED"
+        || snapshot.status === "SETTLEMENT_DENIED") {
+        if (snapshot.billed || snapshot.contentReleased || snapshot.billing !== null) {
+            throw journalIntegrityError("A canceled or failed direct-v5 operation is not strictly uncharged.");
+        }
+    }
+}
 function canonicalValue(value) {
     if (value === null || typeof value === "string" || typeof value === "boolean") {
         return value;
@@ -162,6 +234,7 @@ function resultFromRecord(record) {
             status: "expired",
             operation_id: record.operationId,
             requires_user_confirmation: true,
+            ...(record.billing === null ? {} : { billing: toWireBilling(record.billing) }),
         };
     }
     if (record.state === "CANCELED") {
@@ -170,6 +243,7 @@ function resultFromRecord(record) {
             status: "canceled",
             operation_id: record.operationId,
             ...(cleanupDeadline === null ? {} : { cleanup_deadline: cleanupDeadline }),
+            ...(record.billing === null ? {} : { billing: toWireBilling(record.billing) }),
             data_handling: recordDataHandling(record),
         };
     }
@@ -188,6 +262,7 @@ function resultFromRecord(record) {
         return {
             status: "cleanup_pending",
             operation_id: record.operationId,
+            ...(record.billing === null ? {} : { billing: toWireBilling(record.billing) }),
             cleanup_deadline: record.resultExpiresAt ?? record.expiresAt ?? new Date(0).toISOString(),
             data_handling: recordDataHandling(record),
         };
@@ -364,6 +439,37 @@ export class OperationManager {
             throw structured;
         }
     }
+    async #bindResultBilling(record, result) {
+        const billing = resultBilling(result);
+        if (billing === null)
+            return record;
+        const latest = await this.#journal.loadByRequestId(record.clientRequestId) ?? record;
+        const directProfile = latest.sourceKind === "url" ? null : latest.directProfile;
+        if (latest.sourceKind === "local" && directProfile === null) {
+            throw journalIntegrityError("A local terminal carries billing without a saved direct profile.", latest);
+        }
+        return this.#journal.bindSettlementFacts(latest.clientRequestId, {
+            directProfile,
+            billing: toJournalBilling(billing),
+        });
+    }
+    async #normalizeResultBilling(record, result) {
+        const bound = await this.#bindResultBilling(record, result);
+        const billing = resultBilling(result)
+            ?? (bound.billing === null ? null : toWireBilling(bound.billing));
+        if (isBillingProfile(bound.directProfile)) {
+            if (result.status === "failed" || result.status === "canceled") {
+                if (bound.billed || bound.billing !== null || bound.contentReleased) {
+                    throw journalIntegrityError("A failed or canceled direct-v5 terminal is not strictly uncharged.", bound);
+                }
+            }
+            else if (result.status === "completed"
+                || (result.status === "cleanup_pending" && result.result !== undefined)) {
+                requireWireBillingForSettledProfile(bound.directProfile, bound.billed, billing);
+            }
+        }
+        return projectBilling(result, billing);
+    }
     async #present(record, canonicalResult) {
         if (canonicalResult.status === "processing")
             return canonicalResult;
@@ -419,8 +525,9 @@ export class OperationManager {
         if (TERMINAL_STATES.has(record.state)) {
             const recovered = await this.#driver.result?.(record, signal);
             if (recovered !== undefined) {
-                this.#results.set(operationId, recovered);
-                return this.#present(record, recovered);
+                const normalized = await this.#normalizeResultBilling(record, recovered);
+                this.#results.set(operationId, normalized);
+                return this.#present(record, normalized);
             }
             return this.#present(record, resultFromRecord(record));
         }
@@ -491,7 +598,7 @@ export class OperationManager {
             return record;
         const updated = await this.#applyUpdate(record, update);
         if (update.result !== undefined && updated.operationId !== null) {
-            this.#results.set(updated.operationId, update.result);
+            this.#results.set(updated.operationId, await this.#normalizeResultBilling(updated, update.result));
         }
         return updated;
     }
@@ -505,7 +612,7 @@ export class OperationManager {
         if (!isExecution(start)) {
             const updated = await this.#applyUpdate(record, start);
             if (start.result !== undefined && updated.operationId !== null) {
-                this.#results.set(updated.operationId, start.result);
+                this.#results.set(updated.operationId, await this.#normalizeResultBilling(updated, start.result));
             }
             return updated;
         }
@@ -517,16 +624,17 @@ export class OperationManager {
         let managed;
         const settled = start.completed.then(async (completion) => {
             const current = await this.#journal.loadByOperationId(operationId);
-            if (current !== null && !TERMINAL_STATES.has(current.state)) {
-                await this.#applyUpdate(current, completion.update);
-            }
-            if (completion.result.status !== "processing") {
-                this.#results.set(operationId, completion.result);
+            const updated = current !== null && !TERMINAL_STATES.has(current.state)
+                ? await this.#applyUpdate(current, completion.update)
+                : current ?? initial;
+            const normalized = await this.#normalizeResultBilling(updated, completion.result);
+            if (normalized.status !== "processing") {
+                this.#results.set(operationId, normalized);
             }
             else {
                 this.#results.delete(operationId);
             }
-            return completion.result;
+            return normalized;
         }).catch(async (error) => {
             const structured = error instanceof OmniBridgeError
                 ? error
@@ -620,7 +728,9 @@ export class OperationManager {
         return record;
     }
     async #applyUpdate(record, update) {
-        let current = record;
+        let current = update.result === undefined
+            ? record
+            : await this.#bindResultBilling(record, update.result);
         for (let attempt = 0; attempt < 4; attempt += 1) {
             try {
                 return await this.#journal.transition(current.clientRequestId, current.state, update.state, update.patch ?? {});
@@ -967,11 +1077,12 @@ function localResultCache(local) {
         expiresAt: local.expiresAt,
     });
 }
-function completedLocalParse(local) {
+function completedLocalParse(local, billing) {
     return {
         status: "completed",
         operation_id: local.operationId,
         result: localResultValue(local),
+        ...(billing === undefined ? {} : { billing }),
         data_handling: {
             processing_copy: "deleted",
             temporary_data: "deleted",
@@ -982,11 +1093,12 @@ function completedLocalParse(local) {
         local_result_cache: localResultCache(local),
     };
 }
-function cleanupPendingParse(local, cleanupDeadline) {
+function cleanupPendingParse(local, cleanupDeadline, billing) {
     return {
         status: "cleanup_pending",
         operation_id: local.operationId,
         result: localResultValue(local),
+        ...(billing === undefined ? {} : { billing }),
         cleanup_deadline: cleanupDeadline,
         data_handling: {
             processing_copy: "pending",
@@ -1016,6 +1128,7 @@ function recoveredRemoteParse(record, local) {
             status: "cleanup_pending",
             operation_id: record.operationId,
             result: localResultValue(local),
+            ...(record.billing === null ? {} : { billing: toWireBilling(record.billing) }),
             cleanup_deadline: record.resultExpiresAt ?? record.expiresAt ?? new Date(0).toISOString(),
             data_handling: recordDataHandling(record),
             local_result_cache: localResultCache(local),
@@ -1025,6 +1138,7 @@ function recoveredRemoteParse(record, local) {
         status: "completed",
         operation_id: record.operationId,
         result: localResultValue(local),
+        ...(record.billing === null ? {} : { billing: toWireBilling(record.billing) }),
         data_handling: recordDataHandling(record),
         local_result_cache: localResultCache(local),
     };
@@ -1077,7 +1191,9 @@ function safeOperationStage(status, fallback) {
         return "canceled";
     if (status === "EXPIRED" || status === "DELIVERY_EXPIRED")
         return "expired";
-    if (status === "FAILED" || status === "SETTLEMENT_DENIED")
+    if (status === "FAILED"
+        || status === "UNSUPPORTED"
+        || status === "SETTLEMENT_DENIED")
         return "failed";
     return safeJournalStage(fallback);
 }
@@ -1116,6 +1232,23 @@ function requireBundleResult(retention) {
     }
     return retention.bundleResult();
 }
+async function requireExpectedBundleDetail(local, expectedDetail, retention) {
+    if (local.kind === "bundle" && local.detail === expectedDetail)
+        return local;
+    try {
+        await retention.abort();
+    }
+    catch {
+        // Preserve the exact-detail protocol failure over best-effort local cleanup.
+    }
+    throw managerError("IIIS_INVALID_RESPONSE", "IIIS returned a result for a different representation detail.", {
+        operationCreated: true,
+        fileUploaded: true,
+        parserStarted: true,
+        billed: false,
+        contentReleased: false,
+    });
+}
 export function createLocalParseOperationManager(options) {
     const now = options.now ?? (() => new Date());
     const openFile = options.openFile ?? openAllowedFile;
@@ -1287,6 +1420,9 @@ export function createLocalParseOperationManager(options) {
                     output: "markdown",
                     ...(representation.detail === "text" ? {} : { detail: representation.detail }),
                 }, input.clientRequestId, input.signal, { journal: false });
+                if (isBillingProfile(granted.directProfile)) {
+                    await options.journal.bindDirectProfile(input.clientRequestId, granted.directProfile);
+                }
             }
             catch (error) {
                 await opened.close().catch(() => undefined);
@@ -1348,9 +1484,17 @@ export function createLocalParseOperationManager(options) {
                 await (context?.progress ?? NOOP_PROGRESS).report(value, total, message, latestProgress ?? undefined);
             },
         };
+        const expectedDetail = granted?.requestedDetail ?? representation.detail;
+        if (expectedDetail !== representation.detail) {
+            await opened?.close().catch(() => undefined);
+            opened = undefined;
+            throw managerError("CUBE_PROTOCOL_ERROR", "Cube returned a grant for a different representation detail.", { operationCreated: true });
+        }
         const operation = {
             operationId,
             operationToken,
+            directProfile: granted?.directProfile ?? recovery?.directProfile ?? null,
+            expectedDetail,
             ...(granted === undefined || opened === undefined
                 ? {}
                 : {
@@ -1395,18 +1539,19 @@ export function createLocalParseOperationManager(options) {
                     recovery?.state === "ACK_PENDING" ||
                     recovery?.state === "CLEANUP_PENDING";
                 let local;
+                let released;
                 if (deliveryRecovery && recovery.resultId !== null) {
                     local = await recoverLocalArtifact(recovery);
                 }
                 else {
                     if (deliveryRecovery) {
-                        await options.iiisClient.downloadResult(operation, progress);
+                        released = await options.iiisClient.downloadResult(operation, progress);
                     }
                     else if (recovery?.state === "UPLOADING" || recovery?.state === "PROCESSING") {
-                        await options.iiisClient.recoverAndWait(operation);
+                        released = await options.iiisClient.recoverAndWait(operation);
                     }
                     else {
-                        await options.iiisClient.uploadAndWait(operation);
+                        released = await options.iiisClient.uploadAndWait(operation);
                     }
                     // Non-text results require the durable BundleLocalResult (both named
                     // parts verified and fsynced); ACK_PENDING is persisted only after
@@ -1415,6 +1560,27 @@ export function createLocalParseOperationManager(options) {
                         ? requireBundleResult(retention)
                         : retention.result();
                 }
+                if (representation.detail !== "text") {
+                    local = await requireExpectedBundleDetail(local, representation.detail, retention);
+                }
+                const directProfile = released?.directProfile
+                    ?? recovery?.directProfile
+                    ?? operation.directProfile
+                    ?? null;
+                if (released?.directProfile !== undefined
+                    && released.directProfile !== (operation.directProfile ?? null)) {
+                    throw journalIntegrityError("IIIS changed the selected direct profile.", recovery);
+                }
+                const recoveredBilling = recovery?.billing === null || recovery?.billing === undefined
+                    ? null
+                    : toWireBilling(recovery.billing);
+                const wireBilling = requireWireBillingForSettledProfile(directProfile, true, released?.billing ?? recoveredBilling);
+                if (wireBilling !== undefined) {
+                    await options.journal.bindSettlementFacts(input.clientRequestId, {
+                        directProfile,
+                        billing: toJournalBilling(wireBilling),
+                    });
+                }
                 const cleanupDeadline = recovery?.resultExpiresAt ?? new Date(now().getTime() + DELIVERY_TTL_SECONDS * 1000).toISOString();
                 const resultPatch = {
                     fileUploaded: true,
@@ -1465,7 +1631,7 @@ export function createLocalParseOperationManager(options) {
                             deliveryResult: "deleted_after_ack",
                         },
                     },
-                    result: completedLocalParse(local),
+                    result: completedLocalParse(local, wireBilling),
                 };
             }
             catch (error) {
@@ -1489,6 +1655,7 @@ export function createLocalParseOperationManager(options) {
                             result: processingParse(operationId, stage, latestPercent, confirmed.contentReleased === true),
                         };
                     }
+                    assertDirectTerminalSnapshot(operation.directProfile ?? null, inspected);
                     const patch = {
                         ...confirmed,
                         fileUploaded: confirmed.fileUploaded === true || inspected.fileUploaded,
@@ -1528,7 +1695,9 @@ export function createLocalParseOperationManager(options) {
                             },
                         };
                     }
-                    if (inspected.status === "FAILED" || inspected.status === "SETTLEMENT_DENIED") {
+                    if (inspected.status === "FAILED"
+                        || inspected.status === "UNSUPPORTED"
+                        || inspected.status === "SETTLEMENT_DENIED") {
                         const failed = managerError(inspected.status, `The Omni operation ended with status ${inspected.status}.`, {
                             operationCreated: true,
                             fileUploaded: patch.fileUploaded,
@@ -1584,12 +1753,14 @@ export function createLocalParseOperationManager(options) {
                         state: "FAILED",
                         patch: {
                             ...failurePatch(stable),
-                            // The ACK checkpoint may already have recorded a settled charge
-                            // (snapshot.patch at :1751 carries resultPatch's billed fact).
-                            // Never regress it — assertStableTransition blocks true->false —
-                            // the charge happened; this failure is about the local artifact,
-                            // not the settlement.
-                            billed: checkpointBilled || stable.billed,
+                            // Recovery starts from persisted monotonic facts. A protocol
+                            // rejection cannot make a confirmed upload, parser start,
+                            // settlement, or release become false merely because the invalid
+                            // response itself was not trusted.
+                            fileUploaded: recovery?.fileUploaded === true || stable.fileUploaded,
+                            parserStarted: recovery?.parserStarted === true || stable.parserStarted,
+                            billed: checkpointBilled || recovery?.billed === true || stable.billed,
+                            contentReleased: recovery?.contentReleased === true || stable.contentReleased,
                         },
                     },
                     result: {
@@ -1702,6 +1873,8 @@ export function createLocalParseOperationManager(options) {
             const operation = {
                 operationId: record.operationId,
                 operationToken: record.operationToken,
+                directProfile: record.directProfile,
+                expectedDetail: record.detail,
                 retention: {
                     async reset() { },
                     async begin() { },
@@ -1714,6 +1887,7 @@ export function createLocalParseOperationManager(options) {
             const inspected = options.iiisClient.cancelOperation === undefined
                 ? await options.iiisClient.inspectOperation(operation)
                 : await options.iiisClient.cancelOperation(operation);
+            assertDirectTerminalSnapshot(operation.directProfile ?? null, inspected);
             const patch = {
                 fileUploaded: inspected.fileUploaded,
                 parserStarted: inspected.parserStarted,
@@ -1747,7 +1921,9 @@ export function createLocalParseOperationManager(options) {
                     },
                 };
             }
-            if (inspected.status === "FAILED" || inspected.status === "SETTLEMENT_DENIED") {
+            if (inspected.status === "FAILED"
+                || inspected.status === "UNSUPPORTED"
+                || inspected.status === "SETTLEMENT_DENIED") {
                 return {
                     state: "FAILED",
                     patch: { ...patch, errorCode: inspected.status },
@@ -1773,7 +1949,7 @@ export function createLocalParseOperationManager(options) {
             if (record.operationId === null || record.state !== "COMPLETED")
                 return undefined;
             if (record.sourceKind === "local" && record.resultId !== null) {
-                return completedLocalParse(await recoverLocalArtifact(record));
+                return completedLocalParse(await recoverLocalArtifact(record), record.billing === null ? undefined : toWireBilling(record.billing));
             }
             if (record.sourceKind === "url" && record.resultId !== null) {
                 try {

package/dist/protocol.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
-export declare const LOCAL_BRIDGE_PROTOCOL_VERSION = "omni.local_bridge_tools.v4";
-export declare const OPERATION_JOURNAL_VERSION = 4;
+export declare const LOCAL_BRIDGE_PROTOCOL_VERSION = "omni.local_bridge_tools.v5";
+export declare const OPERATION_JOURNAL_VERSION = 5;
 export declare const BUNDLE_CURSOR_VERSION = 2;
 export declare const RESULT_BUNDLE_PROTOCOL_VERSION = "omni.result_bundle.v1";
 export declare const GROUNDING_SCHEMA_VERSION = "omni.grounding.v1";

package/dist/protocol.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { RESULT_CHUNK_MAX_BYTES, STATUS_LONG_POLL_MAX_MS } from "./constants.js";
-export const LOCAL_BRIDGE_PROTOCOL_VERSION = "omni.local_bridge_tools.v4";
-export const OPERATION_JOURNAL_VERSION = 4;
+export const LOCAL_BRIDGE_PROTOCOL_VERSION = "omni.local_bridge_tools.v5";
+export const OPERATION_JOURNAL_VERSION = 5;
 export const BUNDLE_CURSOR_VERSION = 2;
 // Canonical bundle/grounding literals carried by non-text representations.
 export const RESULT_BUNDLE_PROTOCOL_VERSION = "omni.result_bundle.v1";
@@ -21,6 +21,7 @@ export function normalizeRepresentation(detail) {
     };
 }
 export const MACHINE_INSTRUCTIONS = [
+    "Use parse as the only first call for both HTTP(S) URLs and local paths; do not ask the user to choose a local, remote, upload, or URL mode.",
     "Pass the user-provided source string directly to parse.",
     "Treat only HTTP(S) as URL; ordinary paths require the local Bridge.",
     "Never read, attach, base64-encode, or insert local source content before calling Omni.",
@@ -32,6 +33,9 @@ export const MACHINE_INSTRUCTIONS = [
     "Do not promise background notification when the client lacks task support.",
     "Do not claim deletion before cleanup is confirmed.",
     "Report authoritative unit progress when present; never treat partial output as final.",
+    "Choose continuation tools from the structured result; do not present the Bridge tool menu to the user.",
+    "Text output is Markdown and may retain headings, lists, GFM tables, or raw HTML tables; it lacks grounding/layout sidecars, not all structure.",
+    "An empty outline means no recognized headings, not that the text has no structure.",
     "Answer directly → use inline text when present; otherwise read_result",
     "Find one section → read_outline, then pass its cursor to read_result",
     "Read all content → read_result until next_cursor is absent",

package/dist/remote-client.js

@@ -2,7 +2,7 @@ import { LATEST_PROTOCOL_VERSION } from "@modelcontextprotocol/sdk/types.js";
 import { parseReaderCapabilities, selectUrlProfile, } from "./capabilities.js";
 import { BRIDGE_RELEASE_VERSION, REMOTE_CAPABILITIES_CUSTOM_FIELD, REMOTE_OMNI_MCP_URL, } from "./constants.js";
 import { API_KEY_URL } from "./onboarding-policy.js";
-import { OmniBridgeError } from "./errors.js";
+import { OmniBridgeError, unsupportedDetailError } from "./errors.js";
 import { parseResultSchema } from "./result-contract.js";
 import { classifySource } from "./source.js";
 const INITIALIZE_REQUEST_ID = "initialize";
@@ -108,16 +108,6 @@ function protocolError() {
         retryable: false,
     });
 }
-function unsupportedDetail() {
-    return remoteError({
-        code: "UNSUPPORTED_DETAIL",
-        message: "This remote Omni service does not support the requested output detail.",
-        failureScope: "service",
-        userAction: "Use plain Markdown output for this source.",
-        operationCreated: false,
-        retryable: false,
-    });
-}
 // Extracts exactly `result.capabilities.experimental["cue.omni-reader"]` from
 // an MCP initialize envelope; returns undefined when the exact custom field is
 // absent (server did not declare the capability), throws on contract
@@ -351,7 +341,7 @@ export class HttpRemoteOmniClient {
         }
         const custom = initializeCustomCapability(envelope, INITIALIZE_REQUEST_ID);
         if (custom === undefined) {
-            throw unsupportedDetail();
+            throw unsupportedDetailError("url");
         }
         let capabilities;
         try {
@@ -388,7 +378,7 @@ export class HttpRemoteOmniClient {
             // non-text v3 call; a missing/mismatched profile fails closed with
             // UNSUPPORTED_DETAIL and zero tools/call requests.
             const capabilities = await this.initializeCapabilities(signal);
-            selectUrlProfile(capabilities, detail);
+            selectUrlProfile(capabilities, detail, "url");
             args = { source: classified.source, detail, wait: false };
         }
         return this.#call("parse", args, clientRequestId, signal);