@cueai/omni-reader-mcp 1.1.2 → 1.2.0

package/README.md

@@ -1,87 +1,110 @@
 # @cueai/omni-reader-mcp
 
-Omni Bridge 是 Agent 中统一的本地 stdio facade。用户只需提供来源，Bridge 通过同一个 `parse(source)` 自动处理 HTTPS URL 或已授权目录中的本地文件，无需选择“本地/远程”“上传/URL”或内部服务。
+Omni Bridge is the unified local stdio facade for agents. The user provides only the
+source; Bridge handles an HTTPS URL or a local file inside an authorized directory
+through the same `parse(source)` call — no "local/remote", "upload/URL", or internal
+service choice.
 
-## 用户旅程
+## User journey
 
-直接告诉 Agent 来源和后续任务：
+Tell the agent the source and the follow-up task:
 
 ```text
-用 Omni 解析 ./report.pdf
-用 Omni 解析 https://example.com/report.pdf
-用 Omni 解析 ./report.pdf 并总结营收变化
+Parse ./report.pdf with Omni
+Parse https://example.com/report.pdf with Omni
+Parse ./report.pdf with Omni and summarize the revenue changes
 ```
 
-URL 不要求安装 Bridge。本地文件首次使用时，Agent 应先说明最小目录授权、数据处理方式并取得确认，再安装固定版本 Bridge。解析完成后，Agent 应继续摘要、问答或字段抽取等原始任务，而不是止于“解析完成”。
+URLs never require installing Bridge. For local files, the agent should first explain the
+minimal directory authorization and data handling and obtain confirmation, then install
+a pinned Bridge version. After parsing completes, the agent continues the original task —
+summarization, Q&A, field extraction — rather than stopping at "parse done".
 
-## 要求
+## Requirements
 
-- Node.js 20.12 或更新版本。
-- Cue API Key：<https://cuecue.cn/api-key>。
-- 新账号有免费积分可体验；当前赠送和每日额度以服务端 onboarding policy 与 `doctor` 输出为准。
-- 请在 Agent 的安全密钥或本机环境设置中配置 `CUE_API_KEY`。**请勿把 API Key 粘贴到对话中。**
+- Node.js 20.12 or newer.
+- Cue API Key: <https://cuecue.cn/api-key>.
+- New accounts receive free credits to try; the current grant and daily allowance follow
+  the server-side onboarding policy and the `doctor` output.
+- Configure `CUE_API_KEY` in the agent's secret store or local environment.
+  **Never paste the API Key into a conversation.**
 
-Bridge 运行时只使用以下产品配置：
+Bridge reads only these product configuration variables at runtime:
 
 - `CUE_API_KEY`
 - `OMNI_ALLOWED_ROOTS`
 
-`OMNI_ALLOWED_ROOTS` 只用于用户明确授权的额外绝对目录；macOS/Linux 使用冒号分隔，Windows 使用分号分隔。当前 Agent workspace 仍是默认允许范围。
+`OMNI_ALLOWED_ROOTS` is only for additional absolute directories the user explicitly
+authorizes; colon-separated on macOS/Linux, semicolon-separated on Windows. The current
+agent workspace remains the default allowed scope.
 
-## 安装与配置
+## Installation and configuration
 
-始终使用已审核的精确版本，不使用隐式 `latest`：
+Always use an audited exact version, never an implicit `latest`:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.1.2 setup
+npx -y @cueai/omni-reader-mcp@1.2.0 setup
 ```
 
-交互 setup 支持 Hermes、Cursor、Claude Desktop 和通用 stdio 配置。非交互安装使用同一参数解析和写入逻辑：
+The interactive setup supports Hermes, Cursor, Claude Desktop, and generic stdio
+configuration. Non-interactive installation uses the same argument parsing and write
+logic:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.1.2 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
-npx -y @cueai/omni-reader-mcp@1.1.2 setup --client cursor --add-root /absolute/minimum/root --yes --json
-npx -y @cueai/omni-reader-mcp@1.1.2 setup --client claude-desktop --allowed-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.2.0 setup --client hermes --allowed-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.2.0 setup --client cursor --add-root /absolute/minimum/root --yes --json
+npx -y @cueai/omni-reader-mcp@1.2.0 setup --client claude-desktop --allowed-root /absolute/minimum/root --yes --json
 ```
 
-Agent/脚本在 pty 下运行（stdin 仍是 TTY）时，用 `--headless`（别名 `--non-interactive`）显式声明非交互，无需 `--yes` 且绝不读 stdin：
+When an agent or script runs under a pty (stdin is still a TTY), declare non-interactive
+mode explicitly with `--headless` (alias `--non-interactive`): no `--yes` is required and
+stdin is never read:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.1.2 setup --client cursor --allowed-root /absolute/minimum/root --headless --json
+npx -y @cueai/omni-reader-mcp@1.2.0 setup --client cursor --allowed-root /absolute/minimum/root --headless --json
 ```
 
-## 缓存与 journal 隔离
+## Cache and journal isolation
 
-本地解析缓存与操作 journal 默认位于用户级缓存目录（macOS `~/Library/Caches/cue/omni-reader-mcp`、Windows `%LOCALAPPDATA%\Cue\omni-reader-mcp\Cache`、Linux `~/.cache/cue/omni-reader-mcp`）。若 Agent 的文件监视器（如 WorkBuddy）锁定该目录下的文件导致写入失败，设置 `OMNI_CACHE_DIR` 将缓存与 journal 一起隔离到不被监视的目录：
+The local parse cache and operation journal default to the user-level cache directory
+(macOS `~/Library/Caches/cue/omni-reader-mcp`, Windows
+`%LOCALAPPDATA%\Cue\omni-reader-mcp\Cache`, Linux `~/.cache/cue/omni-reader-mcp`). If the
+agent's file watcher (e.g. WorkBuddy) locks files under that directory and writes fail,
+set `OMNI_CACHE_DIR` to isolate cache and journal together into a directory that is not
+watched:
 
 ```sh
 export OMNI_CACHE_DIR=/var/cache/omni-reader
 ```
 
-显式 `OMNI_CACHE_DIR` 不会被项目重叠检查改写到临时目录；仍禁止与项目目录互相包含。
+An explicit `OMNI_CACHE_DIR` is never rewritten to a temporary directory by the
+project-overlap check; mutual containment with a project directory remains forbidden.
 
-setup 会：
+`setup` will:
 
-1. 展示 user-scope 配置目标和变更；
-2. 写入单一、精确版本的 `omni-reader` facade；
-3. 使用私有 lock、可信备份和原子替换；
-4. 验证 Omni 安全解析环境；
-5. 验证失败时恢复原配置；
-6. 提示对应 Agent reload 或 restart。
+1. show the user-scope configuration target and changes;
+2. write a single, exact-version `omni-reader` facade;
+3. use a private lock, trusted backup, and atomic replacement;
+4. verify the Omni secure parse environment;
+5. restore the previous configuration when verification fails;
+6. prompt the corresponding agent to reload or restart.
 
-配置不会写入 API Key 明文。Hermes 使用原生的独立 `command`、`args` 和安全环境变量引用。
+Configuration never writes the API Key in plaintext. Hermes uses native separate
+`command`, `args`, and safe environment variable references.
 
-## Agent 调用规则
+## Agent calling rules
 
-Agent 将用户提供的来源字符串直接传给 `parse(source)`：
+Agents pass the user-provided source string directly to `parse(source)`:
 
-- 只有 HTTP(S) 被视为 URL；普通字符串按本地路径处理。
-- Do not read, attach, base64-encode, or insert the file content into the conversation before calling Omni.
-- 不使用 `file://`、localhost 或公共临时上传站点作为回退。
-- 安装 Bridge 或扩大 allowed root 前必须确认。
-- 状态恢复优先使用已有 `operation_id`；不得为超时重复上传或重复创建解析。
+- Only HTTP(S) is treated as a URL; a plain string is treated as a local path.
+- Do not read, attach, base64-encode, or insert the file content into the conversation
+  before calling Omni.
+- Do not use `file://`, localhost, or public temporary upload sites as a fallback.
+- Confirm before installing Bridge or widening the allowed roots.
+- Prefer the existing `operation_id` for status recovery; never re-upload or duplicate a
+  parse for a timeout.
 
-公开工具固定为：
+The public tools are fixed:
 
 - `parse`
 - `get_parse_status`
@@ -89,66 +112,102 @@ Agent 将用户提供的来源字符串直接传给 `parse(source)`：
 - `read_result`
 - `discard_result`
 
-每个工具都返回 `structuredContent` 和严格 `outputSchema`。
+Every tool returns `structuredContent` with a strict `outputSchema`, plus an equivalent
+fallback for clients that only read legacy MCP `content[].text`:
 
-## 前台、后台和进度
+- when `parse` completes and the result is inlineable, text returns the full Markdown
+  directly;
+- for processing, artifact, cleanup, cancel, expired, and failure states, text returns
+  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;
+- the `discard_result` text JSON explicitly returns `discarded`; never claim deletion on
+  call success alone.
 
-每次解析的前台预算固定为 **15 秒**：
+This gives clients that do not render `structuredContent` the operation/result handles
+and the full body without changing the contract for structured-capable clients.
 
-- 15 秒内完成：直接返回完整结果。
-- 超过 15 秒：返回可恢复的 processing operation。
-- 客户端明确请求且支持 MCP Tasks 时，Bridge 使用 task。
-- 其他客户端使用 `get_parse_status` 的有界轮询；不承诺客户端不支持的主动通知。
+## Foreground, background, and progress
 
-processing/task 状态只包含 operation、stage、百分比和可选权威单位进度。可用单位仅为 `page`、`sheet`、`slide`、`frame`、`segment`。状态中不包含结果正文、预览、Markdown、页面图片、裁剪图片或累计部分输出。
+The foreground budget of every parse is fixed at **15 seconds**:
 
-## 数据处理与保留
+- completes within 15 seconds: the full result is returned directly;
+- exceeds 15 seconds: a recoverable processing operation is returned;
+- when the client explicitly requests it and supports MCP Tasks, Bridge uses a task;
+- other clients use bounded polling of `get_parse_status`; proactive notifications that
+  the client does not support are not promised.
 
-URL 和本地文件都使用强制 no-store 语义并进入 **Omni 安全解析环境**：
+processing/task status contains only the operation, stage, percentage, and an optional
+authoritative unit progress. Available units are only `page`, `sheet`, `slide`, `frame`,
+`segment`. Status never contains the result body, previews, Markdown, page images, crop
+images, or accumulated partial output.
 
-- 用户电脑上的原始本地文件保持 unchanged；URL 来源也不会被修改或删除。
-- Omni 创建的处理副本和临时数据在完成后主动清理。
-- 加密交付数据在 ACK 后删除；未确认 ACK 时最迟在 **10 分钟**交付窗口到期。
-- 只有远端 ACK 和清理已确认后才返回 `completed`。
-- 本地结果已保留但远端清理仍不确定时返回 `cleanup_pending`，不会提前声称已删除。
-- 超过 64 KiB 的结果可以保存在用户私有 Bridge cache，最长 **24 小时**；这与远端 10 分钟交付窗口是两类不同数据。
-- `read_result` 分块读取本地结果；`discard_result` 可立即删除指定结果；`clean` 清理 Bridge 创建的本地 artifact 和到期记录。
+## Data handling and retention
 
-状态查询、结果读取和丢弃不会创建新的解析或 usage event。`cancel_parse` 只报告服务端确认的真实结算状态，不会自行造成第二次计费。
+Both URL and local files use mandatory no-store semantics and enter the
+**Omni secure parse environment**:
 
-## 约束错误
+- the original local file on the user's machine stays unchanged; URL sources are never
+  modified or deleted;
+- processing copies and temporary data created by Omni are actively cleaned after
+  completion;
+- encrypted delivery data is deleted after ACK; without a confirmed ACK, at the latest
+  when the **10-minute** delivery window expires;
+- `completed` is returned only after the remote ACK and cleanup are confirmed;
+- `cleanup_pending` is returned when the local result is retained but remote cleanup is
+  still uncertain — never claim deletion prematurely;
+- results over 64 KiB may be kept in the user's private Bridge cache for up to
+  **24 hours**; this is a different class of data from the remote 10-minute delivery
+  window;
+- `read_result` reads local results in chunks; `discard_result` deletes a specific result
+  immediately; `clean` removes Bridge-created local artifacts and expired records.
 
-Bridge 在 grant、上传和计费前验证本地来源：
+Status queries, result reads, and discards never create a new parse or usage event.
+`cancel_parse` reports only the real settlement state confirmed by the server and never
+causes a second billing by itself.
 
-- `SOURCE_TOO_LARGE`：超过当前 256 MiB 上限，并返回机器可读 `constraints.max_bytes`。
-- `UNSUPPORTED_MEDIA_TYPE`：媒体类型不受支持，并返回当前权威 `supported_extensions`。
+## Constraint errors
 
-Agent 不应自动拆分、转码或上传公共站点；应请用户提供符合约束的新来源。
+Bridge validates the local source before grant, upload, and billing:
 
-## 命令
+- `SOURCE_TOO_LARGE`: exceeds the current 256 MiB cap, with machine-readable
+  `constraints.max_bytes`.
+- `UNSUPPORTED_MEDIA_TYPE`: unsupported media type, with the current authoritative
+  `supported_extensions`.
+
+Agents should not auto-split, transcode, or upload to public sites; ask the user for a
+new source that satisfies the constraints.
+
+## Commands
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.1.2 doctor
-npx -y @cueai/omni-reader-mcp@1.1.2 doctor --json
-npx -y @cueai/omni-reader-mcp@1.1.2 clean
-npx -y @cueai/omni-reader-mcp@1.1.2 uninstall --yes --json
+npx -y @cueai/omni-reader-mcp@1.2.0 doctor
+npx -y @cueai/omni-reader-mcp@1.2.0 doctor --json
+npx -y @cueai/omni-reader-mcp@1.2.0 clean
+npx -y @cueai/omni-reader-mcp@1.2.0 uninstall --yes --json
 ```
 
-不带命令运行固定版本会启动 stdio MCP server：
+Running the pinned version without a command starts the stdio MCP server:
 
 ```sh
-npx -y @cueai/omni-reader-mcp@1.1.2
+npx -y @cueai/omni-reader-mcp@1.2.0
 ```
 
-`doctor --json` 返回 package/npm/client adapter、Key present/absent、allowed-root 安全状态、endpoint compatibility、artifact、cache mode、onboarding 和 reload 状态；不会输出 Key、私有来源路径或内容。
+`doctor --json` returns package/npm/client adapter, Key present/absent, allowed-root
+safety status, endpoint compatibility, artifacts, cache mode, onboarding, and reload
+status; it never prints the Key, private source paths, or content.
 
-## 卸载与回滚
+## Uninstall and rollback
 
-`uninstall --yes --json` 只删除当前受信的 1.1.2 Bridge entry；存在匹配的可信备份时恢复原 URL-only `omni-reader` entry。卸载不会删除用户源文件，也不会静默删除未过期的本地结果。
+`uninstall --yes --json` removes only the currently trusted 1.2.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.
 
-需要回滚 1.1.1 时：
+To roll back from 1.1.1:
 
-1. 停止推荐或安装该版本；
-2. 运行 `uninstall --yes --json` 恢复可信 URL-only entry；
-3. 对已经上传的 operation 继续使用状态恢复，让结算和清理完成；
-4. 保留本地结果，或由用户显式运行 `discard_result` / `clean`。
+1. stop recommending or installing that version;
+2. run `uninstall --yes --json` to restore the trusted URL-only entry;
+3. for already-uploaded operations, continue using status recovery so settlement and
+   cleanup complete;
+4. keep local results, or have the user explicitly run `discard_result` / `clean`.

package/dist/artifact-store.d.ts

@@ -1,5 +1,7 @@
 import type { FileHandle } from "node:fs/promises";
 import type { ReleasedMetadata, ResultRetentionSink, ResultRetentionStart } from "./iiis-client.js";
+import { GROUNDING_SCHEMA_VERSION, RESULT_BUNDLE_PROTOCOL_VERSION } from "./protocol.js";
+import { type VerifiedBundle } from "./result-bundle.js";
 export interface ArtifactStoreOptions {
     readonly rootDirectory?: string;
     readonly projectDirectory?: string;
@@ -41,6 +43,59 @@ export interface ArtifactReadResult {
     readonly text: string;
     readonly nextCursor?: string;
 }
+export type BundlePartName = "content" | "grounding";
+export type BundleContentStorage = {
+    readonly kind: "inline";
+    readonly text: string;
+} | {
+    readonly kind: "artifact";
+    readonly nextCursor: string;
+};
+export type BundleGroundingStorage = {
+    readonly kind: "inline";
+    readonly value: unknown;
+} | {
+    readonly kind: "artifact";
+    readonly nextCursor: string;
+};
+export interface BundleLocalResult {
+    readonly kind: "bundle";
+    readonly operationId: string;
+    readonly resultId: string;
+    readonly detail: "grounded" | "layout";
+    readonly bundleBytes: number;
+    readonly bundleDigest: string;
+    readonly expiresAt: string;
+    readonly bundleProtocolVersion: typeof RESULT_BUNDLE_PROTOCOL_VERSION;
+    readonly groundingSchemaVersion: typeof GROUNDING_SCHEMA_VERSION;
+    readonly parts: {
+        readonly content: {
+            readonly part: "content";
+            readonly mediaType: "text/markdown; charset=utf-8";
+            readonly resultBytes: number;
+            readonly digest: string;
+            readonly storage: BundleContentStorage;
+        };
+        readonly grounding: {
+            readonly part: "grounding";
+            readonly mediaType: "application/vnd.cue.omni-grounding+json; version=1";
+            readonly resultBytes: number;
+            readonly digest: string;
+            readonly storage: BundleGroundingStorage;
+        };
+    };
+}
+export interface BundlePartReadChunk {
+    readonly resultId: string;
+    readonly part: BundlePartName;
+    readonly mediaType: "text/markdown; charset=utf-8" | "application/vnd.cue.omni-grounding+json; version=1";
+    readonly resultBytes: number;
+    readonly offset: number;
+    readonly decodedBytes: number;
+    readonly text: string;
+    readonly nextCursor?: string;
+    readonly expiresAt: string;
+}
 interface ArtifactFinalizeInput extends ReleasedMetadata {
     readonly resultId: string;
 }
@@ -54,10 +109,12 @@ export declare class ArtifactStore {
     get rootDirectory(): string;
     createRetention(): LocalResultRetention;
     read(resultId: string, cursor?: string, maxBytes?: number): Promise<ArtifactReadResult>;
+    readBundlePart(resultId: string, cursor: string, maxBytes?: number): Promise<BundlePartReadChunk>;
     discard(resultId: string): Promise<boolean>;
     cleanupExpired(): Promise<number>;
     close(): Promise<void>;
     _finalizeArtifact(temporaryPath: string, metadata: ArtifactFinalizeInput): Promise<ArtifactResult>;
+    _finalizeBundle(resultId: string, verified: VerifiedBundle, metadata: ReleasedMetadata): Promise<BundleLocalResult>;
     _newTemporaryArtifact(): Promise<{
         resultId: string;
         temporaryPath: string;
@@ -72,6 +129,7 @@ export declare class LocalResultRetention implements ResultRetentionSink {
     write(chunk: Uint8Array): Promise<void>;
     complete(metadata: ReleasedMetadata): Promise<void>;
     result(): LocalResult;
+    bundleResult(): BundleLocalResult;
     abort(): Promise<void>;
 }
 export {};