@cueai/omni-reader-mcp 1.5.5 → 1.6.0

package/dist/path-security.js

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

package/dist/protocol.d.ts

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

package/dist/protocol.js

@@ -1,11 +1,7 @@
 import { z } from "zod";
 import { RESULT_CHUNK_MAX_BYTES, STATUS_LONG_POLL_MAX_MS } from "./constants.js";
-export const LOCAL_BRIDGE_PROTOCOL_VERSION = "omni.local_bridge_tools.v3";
-// D2-D item 1: versioned persistence literals frozen with the v3 contract.
-// The journal record version and the bundle cursor version are bumped
-// together with the tool contract; legacy v2 journal records still recover
-// text operations unchanged and are never auto-upgraded.
-export const OPERATION_JOURNAL_VERSION = 3;
+export const LOCAL_BRIDGE_PROTOCOL_VERSION = "omni.local_bridge_tools.v4";
+export const OPERATION_JOURNAL_VERSION = 4;
 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";
@@ -36,6 +32,17 @@ 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.",
+    "Answer directly → use inline text when present; otherwise read_result",
+    "Find one section → read_outline, then pass its cursor to read_result",
+    "Read all content → read_result until next_cursor is absent",
+    "Deliver a file → save_result",
+    "Outline navigation does not require save_result.",
+    "Use result_delivery=artifact for saving, section navigation, multiple documents, or strict context control.",
+    "Use bounded concurrent independent parse calls for multiple sources; there is no batch_parse tool.",
+    "Discover MCP Tasks, MCP Roots, host tool timeout, and process cwd versus active workspace; do not guess client capabilities.",
+    "Tasks unknown → use ordinary parse and get_parse_status polling.",
+    "Roots unknown → use process cwd and explicitly configured roots only.",
+    "Host timeout unknown → retain the bounded 20-second status wait.",
     "After parsing, continue the user's original task.",
 ].join("\n");
 const operationIdSchema = z.string().regex(/^op_[A-Za-z0-9_-]{16,64}$/u);
@@ -60,6 +67,7 @@ const parseSchemaObject = z
         .refine((value) => !value.includes("\0"))
         .optional(),
     detail: z.enum(["text", "grounded", "layout"]).optional(),
+    result_delivery: z.enum(["auto", "artifact"]).optional(),
 })
     .strict();
 export const parseSchemaShape = parseSchemaObject.shape;
@@ -71,7 +79,11 @@ export function normalizeParseArguments(args) {
         // schema-validated input and guards misuse of the exported helper.
         throw new Error("parse arguments require exactly one of source or url");
     }
-    return { source, detail: args.detail };
+    return {
+        source,
+        detail: args.detail,
+        resultDelivery: args.result_delivery ?? "auto",
+    };
 }
 export const getParseStatusSchema = z
     .object({

package/dist/result-contract.d.ts

@@ -2,6 +2,7 @@ import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import type { LocalResult } from "./artifact-store.js";
 import { type OmniBridgeErrorPayload } from "./errors.js";
+import { type ResultDelivery } from "./protocol.js";
 export interface DataHandling {
     processing_copy: "in_use" | "pending" | "deleted";
     temporary_data: "in_use" | "pending" | "deleted";
@@ -11,6 +12,25 @@ export interface DataHandling {
     original_source: "unchanged";
     remote_content_retained?: false;
 }
+export declare const FLAT_RESULT_ACTIONS: readonly ["read_result", "read_outline", "save_result", "discard_result"];
+export declare const LOCAL_ARTIFACT_RETENTION_WARNING: "LOCAL_ARTIFACT_RETENTION_FAILED";
+export interface FlatLocalResultCache {
+    readonly result_id: string;
+    readonly result_bytes: number;
+    readonly expires_at: string;
+    readonly available_actions: typeof FLAT_RESULT_ACTIONS;
+    readonly discard_action: "discard_result";
+}
+export interface LegacyBundleLocalResultCache {
+    readonly expires_at: string;
+    readonly discard_action: "discard_result";
+}
+export type LocalResultCache = FlatLocalResultCache | LegacyBundleLocalResultCache;
+export declare function createFlatLocalResultCache(input: {
+    readonly resultId: string;
+    readonly resultBytes: number;
+    readonly expiresAt: string;
+}): FlatLocalResultCache;
 export type ParseResult = {
     status: "processing";
     operation_id: string;
@@ -44,10 +64,8 @@ export type ParseResult = {
         credits_remaining: number;
     };
     data_handling: DataHandling;
-    local_result_cache?: {
-        expires_at: string;
-        discard_action: "discard_result";
-    };
+    local_result_cache?: LocalResultCache;
+    delivery_warning?: typeof LOCAL_ARTIFACT_RETENTION_WARNING;
 } | {
     status: "cleanup_pending";
     operation_id: string;
@@ -64,6 +82,8 @@ export type ParseResult = {
     };
     cleanup_deadline: string;
     data_handling: DataHandling;
+    local_result_cache?: LocalResultCache;
+    delivery_warning?: typeof LOCAL_ARTIFACT_RETENTION_WARNING;
 } | {
     status: "failed";
     error: OmniBridgeErrorPayload;
@@ -132,7 +152,7 @@ export declare const stableErrorSchema: z.ZodObject<{
     ok: false;
     operation_created: boolean;
     failure_scope?: "source" | "local_capability" | "authentication" | "billing" | "service" | "parser" | "operation" | "cleanup" | "bridge" | undefined;
-    source_kind?: "local" | "url" | undefined;
+    source_kind?: "url" | "local" | undefined;
     user_action?: string | undefined;
     request_id?: string | undefined;
     retry_after?: number | undefined;
@@ -151,7 +171,7 @@ export declare const stableErrorSchema: z.ZodObject<{
     ok: false;
     operation_created: boolean;
     failure_scope?: "source" | "local_capability" | "authentication" | "billing" | "service" | "parser" | "operation" | "cleanup" | "bridge" | undefined;
-    source_kind?: "local" | "url" | undefined;
+    source_kind?: "url" | "local" | undefined;
     user_action?: string | undefined;
     request_id?: string | undefined;
     retry_after?: number | undefined;
@@ -454,6 +474,25 @@ export declare const bundleDescriptorSchema: z.ZodObject<{
         };
     };
 }>;
+export declare const flatLocalResultCacheSchema: z.ZodObject<{
+    result_id: z.ZodString;
+    result_bytes: z.ZodNumber;
+    expires_at: z.ZodString;
+    available_actions: z.ZodTuple<[z.ZodLiteral<"read_result">, z.ZodLiteral<"read_outline">, z.ZodLiteral<"save_result">, z.ZodLiteral<"discard_result">], null>;
+    discard_action: z.ZodLiteral<"discard_result">;
+}, "strict", z.ZodTypeAny, {
+    result_id: string;
+    expires_at: string;
+    result_bytes: number;
+    available_actions: ["read_result", "read_outline", "save_result", "discard_result"];
+    discard_action: "discard_result";
+}, {
+    result_id: string;
+    expires_at: string;
+    result_bytes: number;
+    available_actions: ["read_result", "read_outline", "save_result", "discard_result"];
+    discard_action: "discard_result";
+}>;
 export declare const parseResultSchema: z.ZodTypeAny;
 export declare const bundlePartReadSchema: z.ZodObject<{
     status: z.ZodLiteral<"completed">;
@@ -614,4 +653,5 @@ export declare const parseToolOutputSchema: z.ZodTypeAny;
 export declare const readResultToolOutputSchema: z.ZodTypeAny;
 export declare const discardResultToolOutputSchema: z.ZodTypeAny;
 export declare const saveResultToolOutputSchema: z.ZodTypeAny;
+export declare function presentRetainedResult(result: ParseResult, resultDelivery: ResultDelivery, mintReadCursor: (resultId: string, byteOffset: number) => Promise<string>): Promise<ParseResult>;
 export declare function structuredResult(schema: z.ZodTypeAny, value: unknown): CallToolResult;

package/dist/result-contract.js

@@ -1,6 +1,22 @@
 import { z } from "zod";
 import { OmniBridgeError } from "./errors.js";
-import { RESULT_BUNDLE_PROTOCOL_VERSION } from "./protocol.js";
+import { RESULT_BUNDLE_PROTOCOL_VERSION, } from "./protocol.js";
+export const FLAT_RESULT_ACTIONS = [
+    "read_result",
+    "read_outline",
+    "save_result",
+    "discard_result",
+];
+export const LOCAL_ARTIFACT_RETENTION_WARNING = "LOCAL_ARTIFACT_RETENTION_FAILED";
+export function createFlatLocalResultCache(input) {
+    return {
+        result_id: input.resultId,
+        result_bytes: input.resultBytes,
+        expires_at: input.expiresAt,
+        available_actions: FLAT_RESULT_ACTIONS,
+        discard_action: "discard_result",
+    };
+}
 // 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
@@ -197,19 +213,38 @@ export const bundleDescriptorSchema = z
         .strict(),
 })
     .strict();
-const localResultCacheSchema = z
+export const flatLocalResultCacheSchema = z
     .object({
+    result_id: resultIdSchema,
+    result_bytes: z.number().int().nonnegative(),
     expires_at: z.string().datetime({ offset: true }),
+    available_actions: z.tuple([
+        z.literal("read_result"),
+        z.literal("read_outline"),
+        z.literal("save_result"),
+        z.literal("discard_result"),
+    ]),
     discard_action: z.literal("discard_result"),
 })
     .strict();
+const legacyBundleLocalResultCacheSchema = z
+    .object({
+    expires_at: z.string().datetime({ offset: true }),
+    discard_action: z.literal("discard_result"),
+})
+    .strict();
+const localResultCacheSchema = z.union([
+    flatLocalResultCacheSchema,
+    legacyBundleLocalResultCacheSchema,
+]);
+const deliveryWarningSchema = z.literal(LOCAL_ARTIFACT_RETENTION_WARNING);
 const failedResultSchema = z
     .object({
     status: z.literal("failed"),
     error: stableErrorSchema,
 })
     .strict();
-export const parseResultSchema = z.discriminatedUnion("status", [
+const parseResultDiscriminatedSchema = z.discriminatedUnion("status", [
     z
         .object({
         status: z.literal("processing"),
@@ -235,6 +270,7 @@ export const parseResultSchema = z.discriminatedUnion("status", [
         billing: billingSchema.optional(),
         data_handling: dataHandlingSchema,
         local_result_cache: localResultCacheSchema.optional(),
+        delivery_warning: deliveryWarningSchema.optional(),
     })
         .strict(),
     z
@@ -248,6 +284,8 @@ export const parseResultSchema = z.discriminatedUnion("status", [
         ]).optional(),
         cleanup_deadline: z.string().datetime({ offset: true }),
         data_handling: dataHandlingSchema,
+        local_result_cache: localResultCacheSchema.optional(),
+        delivery_warning: deliveryWarningSchema.optional(),
     })
         .strict(),
     failedResultSchema,
@@ -269,6 +307,41 @@ export const parseResultSchema = z.discriminatedUnion("status", [
     })
         .strict(),
 ]);
+export const parseResultSchema = parseResultDiscriminatedSchema
+    .superRefine((value, context) => {
+    if (value.status !== "completed" && value.status !== "cleanup_pending")
+        return;
+    const result = value.result;
+    const cache = value.local_result_cache;
+    if (cache !== undefined) {
+        const cacheMatches = result !== undefined && (result.kind === "bundle"
+            ? legacyBundleLocalResultCacheSchema.safeParse(cache).success
+            : flatLocalResultCacheSchema.safeParse(cache).success);
+        if (!cacheMatches) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["local_result_cache"],
+                message: "the local result cache does not match the result shape",
+            });
+        }
+    }
+    if (value.delivery_warning !== undefined) {
+        if (cache !== undefined) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["local_result_cache"],
+                message: "a retention warning cannot advertise a local result cache",
+            });
+        }
+        if (result === undefined || result.kind !== "inline") {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["delivery_warning"],
+                message: "a retention warning requires delivered inline content",
+            });
+        }
+    }
+});
 const resultChunkSchema = z
     .object({
     result_id: resultIdSchema,
@@ -419,6 +492,7 @@ export const parseToolOutputSchema = z
     billing: billingSchema.optional(),
     data_handling: dataHandlingSchema.optional(),
     local_result_cache: localResultCacheSchema.optional(),
+    delivery_warning: deliveryWarningSchema.optional(),
     cleanup_deadline: z.string().datetime({ offset: true }).optional(),
     error: stableErrorSchema.optional(),
     requires_user_confirmation: z.literal(true).optional(),
@@ -449,6 +523,47 @@ export const saveResultToolOutputSchema = z
     error: stableErrorSchema.optional(),
 })
     .strict();
+export async function presentRetainedResult(result, resultDelivery, mintReadCursor) {
+    if (resultDelivery === "auto" ||
+        (result.status !== "completed" && result.status !== "cleanup_pending") ||
+        result.result === undefined) {
+        return result;
+    }
+    const current = result.result;
+    if (current.kind === "bundle" || current.kind === "artifact")
+        return result;
+    if (current.kind !== "inline")
+        return result;
+    const parsedCache = flatLocalResultCacheSchema.safeParse(result.local_result_cache);
+    if (!parsedCache.success) {
+        if (result.delivery_warning === LOCAL_ARTIFACT_RETENTION_WARNING)
+            return result;
+        throw new OmniBridgeError({
+            code: "LOCAL_RESULT_INTEGRITY_FAILED",
+            failureScope: "bridge",
+            message: "The retained inline result descriptor is unavailable.",
+            operationCreated: false,
+            fileUploaded: false,
+            parserStarted: false,
+            billed: false,
+            contentReleased: false,
+            retryable: false,
+        });
+    }
+    const cache = parsedCache.data;
+    const nextCursor = await mintReadCursor(cache.result_id, 0);
+    return {
+        ...result,
+        result: {
+            kind: "artifact",
+            result_id: cache.result_id,
+            result_bytes: cache.result_bytes,
+            expires_at: cache.expires_at,
+            preview: "",
+            next_cursor: nextCursor,
+        },
+    };
+}
 function storageText(result) {
     const parts = result.parts;
     if (parts === null || typeof parts !== "object" || Array.isArray(parts)) {

package/dist/task-runtime.d.ts

@@ -1,13 +1,14 @@
 import type { RequestTaskStore } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import type { NormalizedParseArguments } from "./protocol.js";
 import { type ParseResult } from "./result-contract.js";
 export interface TaskRuntimeOperations {
-    parse(source: string, signal: AbortSignal): Promise<ParseResult>;
+    parse(args: NormalizedParseArguments, signal: AbortSignal): Promise<ParseResult>;
     status(operationId: string, waitMs: number, signal: AbortSignal): Promise<ParseResult>;
     cancel(operationId: string, signal: AbortSignal): Promise<ParseResult>;
 }
 export declare class TaskRuntime {
     #private;
     constructor(operations: TaskRuntimeOperations);
-    start(taskId: string, source: string, store: RequestTaskStore): Promise<void>;
+    start(taskId: string, args: NormalizedParseArguments, store: RequestTaskStore): Promise<void>;
     cancel(taskId: string): Promise<void>;
 }

package/dist/task-runtime.js

@@ -39,7 +39,7 @@ export class TaskRuntime {
     constructor(operations) {
         this.#operations = operations;
     }
-    async start(taskId, source, store) {
+    async start(taskId, args, store) {
         if (this.#running.has(taskId)) {
             throw new Error(`Task ${taskId} is already running.`);
         }
@@ -48,7 +48,7 @@ export class TaskRuntime {
         };
         this.#running.set(taskId, running);
         try {
-            let result = await this.#operations.parse(source, running.controller.signal);
+            let result = await this.#operations.parse(args, running.controller.signal);
             while (result.status === "processing") {
                 running.operationId = result.operation_id;
                 if (await isCancelled(store, taskId)) {

package/dist/tools.d.ts

@@ -6,6 +6,7 @@ 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 NormalizedParseArguments } from "./protocol.js";
 import type { RemoteOmniClient } from "./remote-client.js";
 import { type ParseResult } from "./result-contract.js";
 interface ToolRetention extends ResultRetentionSink {
@@ -13,7 +14,9 @@ interface ToolRetention extends ResultRetentionSink {
 }
 interface ToolArtifactStore {
     createRetention(): ToolRetention;
+    preflightWrite?(): Promise<void>;
     read(resultId: string, cursor?: string, maxBytes?: number): Promise<ArtifactReadResult>;
+    mintReadCursor?(resultId: string, byteOffset: number): Promise<string>;
     readBundlePart?(resultId: string, cursor: string, maxBytes?: number): Promise<BundlePartReadChunk>;
     readOutline?(resultId: string): Promise<OutlineResult>;
     mintOutlineCursor?(resultId: string, byteOffset: number): Promise<string>;
@@ -29,6 +32,7 @@ export interface ParseOperationController {
         sourceFacts: Readonly<Record<string, unknown>>;
         clientRequestId: string;
         signal: AbortSignal;
+        resultDelivery: NormalizedParseArguments["resultDelivery"];
         context: unknown;
     }): Promise<ParseResult>;
     statusResult(operationId: string, waitMs: number | undefined, signal: AbortSignal): Promise<ParseResult>;