@zvec/zvec-grep 0.1.5 → 0.1.7

package/README_CN.md

@@ -3,302 +3,211 @@
 </p>
 
 <div align="center">
+  <p>
+    <a href="./docs/08-roadmap.md"><img src="https://img.shields.io/badge/status-work%20in%20progress-F59E0B?style=for-the-badge" alt="项目开发中" /></a>
+  </p>
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://zvec.oss-cn-hongkong.aliyuncs.com/logo/github_log_2.svg" />
-    <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/logo/github_logo_1.svg" width="400" alt="zvec logo" />
+    <source media="(prefers-color-scheme: dark)" srcset="./.github/assets/zg-logo-dark.svg">
+    <img src="./.github/assets/zg-logo.svg" width="150" alt="zg logo" />
   </picture>
+  <p><strong>Know the words—or don’t. Just zg.</strong></p>
+  <p>面向人与 Agent 的本地优先统一检索层。</p>
+
+  <p>
+    <a href="https://www.npmjs.com/package/@zvec/zvec-grep"><img src="https://img.shields.io/npm/v/@zvec/zvec-grep.svg" alt="npm 版本" /></a>
+    <a href="https://github.com/zvec-ai/zvec-grep/actions/workflows/ci.yml"><img src="https://github.com/zvec-ai/zvec-grep/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="Apache 2.0 许可证" /></a>
+    <img src="https://img.shields.io/badge/node-%3E%3D22-blue.svg" alt="Node.js 22 或更新版本" />
+  </p>
+
+  <p>
+    <a href="#tour">🎬 <strong>功能演示</strong></a> |
+    <a href="#features">💫 <strong>核心特性</strong></a> |
+    <a href="#try-it-yourself">🚀 <strong>动手体验</strong></a> |
+    <a href="./docs/README.md">📚 <strong>文档</strong></a> |
+    <a href="#benchmarks">📊 <strong>性能测试</strong></a> |
+    <a href="#community">🤝 <strong>社区</strong></a>
+  </p>
 </div>
 
-<p align="center">
-  <a href="https://www.npmjs.com/package/@zvec/zvec-grep"><img src="https://img.shields.io/npm/v/@zvec/zvec-grep.svg" alt="npm 版本"/></a>
-  <a href="https://github.com/zvec-ai/zvec-grep/actions/workflows/ci.yml"><img src="https://github.com/zvec-ai/zvec-grep/actions/workflows/ci.yml/badge.svg" alt="CI"/></a>
-  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="许可证"/></a>
-  <img src="https://img.shields.io/badge/node-%3E%3D22-blue.svg" alt="Node.js >=22"/>
-  <img src="https://img.shields.io/badge/CLI-zg-2ea44f.svg" alt="zg CLI"/>
-</p>
-
-<p align="center">
-  <a href="#quickstart">🚀 <strong>快速开始</strong></a> |
-  <a href="#features">💫 <strong>核心特性</strong></a> |
-  <a href="#installation">📦 <strong>安装</strong></a> |
-  <a href="#models">🧠 <strong>模型</strong></a> |
-  <a href="#library-api">🛠️ <strong>库 API</strong></a>
-</p>
-
-**zvec-grep** 是基于 Zvec 构建的、面向 agent 的代码库混合检索工具。它为仓库维护本地语义索引，融合向量检索与全文检索，并默认输出节省 token 的结果；当人在终端里阅读时，也可以切换到更完整的展示模式。
-
-命令非常短：
-
-```bash
-zg query "where query auto update happens"
-```
-
-> [!IMPORTANT]
-> **命令接口**
->
-> - **混合代码检索**：可以用自然语言、精确关键词，或两者组合来搜索代码。
-> - **明确的索引生命周期**：新仓库必须显式运行 `zg index --embedding <model>`；agent 不会静默创建索引。
-> - **自动刷新**：已有匿名索引会在普通查询前自动检查并增量更新。
-> - **节省 Token 的输出**：agent 默认输出 `--preview none`；`--human` 默认展示完整源码 preview。
-> - **无索引文本搜索**：`zg query --rg` 提供托管的 ripgrep 搜索，不需要先建索引。
-
-## <a id="features"></a>💫 核心特性
-
-- **语义 + 词法检索**：融合向量检索和全文检索，适合源码、文档、测试、脚本和配置。
-- **仓库本地索引**：匿名索引存放在 `<repo>/.zvec-grep/`，索引状态跟随仓库。
-- **Agent 友好输出**：默认按文件分组，并尽量减少源码 preview，降低上下文成本。
-- **人类阅读模式**：加 `--human` 后更适合终端阅读，并默认展示完整 preview。
-- **托管 ripgrep 通道**：`zg query --rg` 支持常见 `rg` 参数，未建索引仓库也能使用。
-- **显式模型选择**：第一次建索引必须指定模型，例如 `local/embeddinggemma-300m`、`local/qwen3-embedding-0.6b` 或 `qwen/text-embedding-v4`。
-- **Schema 复用**：已有索引再次运行 `zg index` 会复用保存的 embedding schema，除非你显式切换模型。
-- **MCP Server**：运行 `zg serve --mcp`，向 MCP 客户端暴露索引搜索和无索引文本搜索工具；建索引和状态查看仍由 CLI 提供。
-- **库 API**：Node.js 工具、agent 或 MCP server 可以直接使用 `createZvecGrep()`。
-
-## <a id="installation"></a>📦 安装
-
-从 npm 安装 CLI：
-
-```bash
-npm install -g @zvec/zvec-grep
-zg version
-```
-
-也可以不全局安装，直接运行：
-
-```bash
-npx @zvec/zvec-grep help
-```
-
-从最新源码构建，并将 `zg` 安装为全局命令：
-
-```bash
-git clone https://github.com/zvec-ai/zvec-grep.git
-cd zvec-grep
-npm ci
-npm run build
-npm install -g .
-zg version
-```
-
-运行 stdio MCP server：
-
-```bash
-zg serve --mcp
-```
-
-安装 Codex MCP 集成：
-
-```bash
-zg install --target codex --yes
-```
-
-Codex MCP 工具调用默认超时为 600 秒，可在安装时通过 `--mcp-tool-timeout <秒数>` 覆盖。
+**zg**（**z**vec-**g**rep）将 ripgrep、BM25 与向量检索统一在一个
+[本地优先的检索入口](./docs/05-architecture.md)中。既可以由人在终端中搜索，
+也可以让 Agent 根据问题选择合适的本地检索方式。
 
-### ✅ 运行要求
+<a id="tour"></a>
 
-- Node.js 22 或更新版本
-- macOS、Linux 或 Windows
-- 使用索引检索时需要选择一个支持的 embedding 模型
+## 🎬 功能演示
 
-`zg query --rg` 不需要 embedding 模型，也不需要索引。
+<div align="center">
+  <img src="./.github/assets/zvec-grep-tour.gif" width="1000" alt="安装 Agent 集成、为工作区建索引并让 Agent 使用 zvec-grep 检索本地内容" />
+</div>
 
-## <a id="quickstart"></a>⚡ 快速开始
+只需安装一次集成并为工作区建索引，之后既可以在终端中搜索，也可以直接向
+Agent 提问。
 
-为仓库建索引，并显式指定 embedding 模型：
+<a id="features"></a>
 
-```bash
-zg index \
-  --embedding local/embeddinggemma-300m \
-  -g "src/**" \
-  -g "docs/**" \
-  -g "test/**" \
-  -g "!dist/**" \
-  -g "!node_modules/**" \
-  -g "!coverage/**"
-```
+## 💫 为什么选择 zg？
 
-查看索引状态：
+- **人与 Agent 开箱即用**：安装一次、索引一次，即可在 macOS、Linux 和
+  Windows 上通过 CLI 或 Agent 复用同一个工作区。
+- **不止关键词搜索**：先按语义发现内容、按相关性排序，再在需要时使用精确文本
+  或正则完成验证。
+- **多格式检索**：搜索源代码、文档和结构化数据，同时保留有用的内容结构与
+  来源位置。
+- **更少搜索，更少上下文**：经过排序并保留来源的结果，可以减少工具调用、
+  Token 消耗与无关噪声，更快找到所需证据。
+- **默认本地运行**：文件、索引与本地模型都留在本机；只有经过你的授权，远程
+  Embedding 服务才能接收数据。
 
-```bash
-zg status
-```
+<a id="try-it-yourself"></a>
 
-用自然语言搜索：
+## 🚀 动手体验
 
-```bash
-zg query "where query auto update happens"
-```
+需要 Node.js 22 或更新版本，以及已经完成配置的
+[OpenCode](https://opencode.ai/)。Agent 示例会显式选择免费模型，不依赖你配置的
+默认模型提供方。
 
-组合语义意图和精确锚点：
+### 1. 准备示例书架
 
 ```bash
-zg query "GPU fallback" --fts "usingCpuFallback" -g "src/**" -t ts --limit 5
-```
+npm install -g @zvec/zvec-grep
+zg install --target opencode --yes
 
-不依赖索引，做穷尽文本搜索：
+mkdir zg-mystery && cd zg-mystery
+curl -L https://www.gutenberg.org/files/11/11-0.txt -o alice-in-wonderland.txt
+curl -L https://www.gutenberg.org/files/345/345-0.txt -o dracula.txt
+curl -L https://www.gutenberg.org/files/84/84-0.txt -o frankenstein.txt
+curl -L https://www.gutenberg.org/files/834/834-0.txt -o sherlock-holmes.txt
 
-```bash
-zg query --rg -F "ZVEC_GREP_HOME" src
+zg index --embedding local/potion-retrieval-32m
 ```
 
-切换到适合人看的输出：
+这会创建一个包含四本公版小说的小书架，并使用 Potion Retrieval 在本地建立索引。
 
-```bash
-zg query --human "root local index discovery" --limit 3
-```
+安装时会立即启动共享 Daemon。默认 MCP 传输方式为 stdio：Agent 会运行
+`zg server --stdio`，电脑重启后该命令会再次安全启动或复用 Daemon。高级用户
+可以通过 `zg install --mcp-transport http` 保留 HTTP 直连，并自行使用
+`zg server on` 管理后续启动。
 
-在 MCP 客户端中可使用 `zvec_grep_search` 和 `zvec_grep_rg`。MCP 输入使用 JSON 友好的字段，例如 `include: ["src/**"]`；状态查看和建索引请使用 CLI 的 `zg status` 与 `zg index`。Codex installer 会向 `${CODEX_HOME:-$HOME/.codex}/config.toml` 和 `${CODEX_HOME:-$HOME/.codex}/AGENTS.md` 写入由 zvec-grep 管理的配置块。
+如需让安装后的 MCP 集成额外暴露 managed rg、index 和 status 工具，可使用
+`zg install --mcp-toolset full`；默认值为 `agent`。
 
-## <a id="models"></a>🧠 模型
+### 2. 选择检索方式
 
-本地模型通过 `node-llama-cpp` 运行，适合把代码检索留在本机：
+#### Agent：通过 OpenCode 提问
 
 ```bash
-zg index --embedding local/embeddinggemma-300m
-zg index --embedding local/qwen3-embedding-0.6b
+opencode run --model opencode/deepseek-v4-flash-free \
+  "An unseen creature left a few marks. What did the detective infer? Cite local evidence."
 ```
 
-在 Apple Silicon 上，本地构建默认使用更安静的 llama.cpp CMake 配置，避免无害的 OpenMP 和 ARM native 探测 warning。可以通过 `NODE_LLAMA_CPP_CMAKE_OPTION_<name>` 覆盖任意 llama.cpp CMake 选项，例如设置 `NODE_LLAMA_CPP_CMAKE_OPTION_GGML_NATIVE=ON` 重新启用 native CPU 优化。
+Prompt 中没有指定任何工具，OpenCode 会自主选择 zg。不同模型改写的
+Query 可能略有不同，一次典型的执行过程如下：
 
-远程 Qwen embedding 适合希望使用托管 embedding 服务，或不想在本机配置模型的场景：
+```text
+⚙ zvec_grep_zvec_grep_search {"root":".../zg-mystery","query":"An unseen creature left a few marks. What did the detective infer?","fts":["marks","unseen creature","inferred","detective"],"fuse":true}
+→ Read sherlock-holmes.txt [offset=5440, limit=120]
 
-```bash
-zg index \
-  --embedding qwen/text-embedding-v4 \
-  --api-key "$DASHSCOPE_API_KEY"
-```
-
-索引成功后，通过 CLI 显式传入的全局模型和 provider 参数会保存到 `~/.zvec-grep/config.json`，并使用仅当前用户可读写的权限。已经运行的 `zg` MCP server 会在下一次需要模型时读取新的远程 API key，不需要重启 Codex。只从环境变量读取、没有作为 CLI 参数显式传入的值不会被持久化。
-
-```json
-{
-  "version": 1,
-  "defaults": {
-    "embedding": "qwen/text-embedding-v4"
-  },
-  "providers": {
-    "qwen": {
-      "apiKey": "...",
-      "endpoint": "https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings"
-    }
-  }
-}
-```
+Answer:
+侦探是《驼背人》中的福尔摩斯。根据动物留下的脚印，他推断：
 
-配置优先级为：显式 CLI 或库参数、环境变量、全局配置、内置默认值。仓库 root 和文件选择规则仍保存在各仓库自己的 `.zvec-grep` 元数据中，不进入全局配置。
+- 它不是狗、猫、猴子或其他常见动物：脚印有五个肉垫和长爪，整个脚印
+  接近一把甜点勺大小（sherlock-holmes.txt:5479-5486）。
+- 它身体细长、四肢很短：身长接近两英尺，步幅却只有约三英寸
+  （sherlock-holmes.txt:5497-5502）。
+- 它是食肉动物，因为它爬上窗帘，试图接近金丝雀笼
+  （sherlock-holmes.txt:5509-5510）。
+- 它很可能属于鼬或白鼬一类，但体型异常大
+  （sherlock-holmes.txt:5514-5516）。
 
-对于已有索引，`zg index` 不传 `--embedding` 会复用索引里保存的 schema。只有在你明确想切换模型时，才使用 `--rebuild --embedding <model>`：
-
-```bash
-zg index --rebuild --embedding local/qwen3-embedding-0.6b
+福尔摩斯还推断，一名男子和它一起从窗户进入房间，离开时带走了钥匙
+（sherlock-holmes.txt:5464-5470, 5527-5528）。
 ```
 
-## 🔎 查询模式
+#### 用户：直接检索
 
-多个带引号的 query 会作为多个搜索组分别检索：
+不通过 Agent，直接搜索同一个书架：
 
 ```bash
-zg query "request validation" "error handling" --limit 5
+zg query --human "An unseen creature left a few marks. What did the detective infer?" --limit 3
 ```
 
-每个 route 参数只接收一个 query，并且可以重复使用。需要把所有搜索组合并成一个排序结果时，使用 `--fuse`：
-
-```bash
-zg query \
-  --hybrid "authentication flow" \
-  --fts "AuthService" \
-  --vector "where credentials are validated" \
-  --fuse \
-  --limit 10
-```
+zg 会从四本小说中对相关段落进行排序，并将 `sherlock-holmes.txt` 中的证据排在前面。
 
-尽早使用与 ripgrep 一致的路径和文件类型过滤，让结果保持聚焦。普通 glob 表示包含，以 `!` 开头的 glob 表示排除：
+<a id="benchmarks"></a>
 
-```bash
-zg query "cache invalidation" \
-  -g "src/**" \
-  -g "!test/**" \
-  -g "!tests/**" \
-  -g "!fixtures/**" \
-  -g "!dist/**" \
-  -t ts
-```
+## 📊 性能测试
 
-文件类型过滤会在 glob 过滤之后继续缩小范围。例如，`-g "docs/**" -t ts`
-只会选择 `docs` 目录下的 TypeScript 文件，而不是该目录里的所有文件。
+zg 是通用检索工具，目前的性能测试覆盖代码与文本检索。
 
-使用 `--preview` 控制索引结果的源码展示量：
+### 代码仓库检索
 
-```bash
-zg query "plugin lifecycle" --preview none
-zg query "plugin lifecycle" --preview short --limit 5
-zg query "plugin lifecycle" --preview full --limit 2
-```
+我们使用 [SWE-QA-Bench](https://github.com/peng-weihan/SWE-QA-Bench)，它要求
+Agent 在真实代码库中完成跨文件、多跳推理。
 
-查精确文本、符号、配置项或错误码时，使用 `--fts` 或 `--rg`：
+- **覆盖范围：**20 个检索密集型任务，覆盖论文中的 **What、Where、How、Why**
+  四个一级类别、8 种意图和 11 个代码仓库。
+- **Agent：**使用 **Claude Opus 5** 的 Claude Code。
+- **Embedding：**zg 方案使用 **Qwen3.7 Text Embedding**。
+- **测试方式：**每个任务、每种方案运行 3 次。
 
-```bash
-zg query "authentication flow" --fts "AuthService" --fts "ForbiddenError"
-zg query --rg -i -C 2 -g "*.ts" "needle text" src
-```
+| 方案 | 评审得分 /100 ↑ | 输入 Token ↓ | 工具调用 ↓ | 耗时（秒）↓ | 成本 ↓ |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| 原生工具 | 80.42 | 558,651 | 23.42 | 127.5 | $0.905 |
+| 原生工具 + zg | 81.92 | 294,262 | 9.70 | 79.7 | $0.558 |
+| 变化 | **+1.50 个百分点** | **−47.3%** | **−58.6%** | **−37.5%** | **−38.3%** |
 
-托管的 rg 模式支持常用的 ripgrep 匹配、上下文、文件类型、glob、ignore、
-深度、大小、符号链接、编码和正则引擎参数。结果格式由 zvec-grep 管理，
-因此 `--json`、`--count`、`--files`、`-l`、`-o`、`--replace` 和
-`--vimgrep` 等会改变输出形态的模式会被拒绝。`.git/**` 和
-`.zvec-grep/**` 始终保持排除。
+在 20 个任务 × 3 次运行中，zg 将评审得分提升了 1.50 分，同时将输入 Token
+减少 47.3%、工具调用减少 58.6%、执行时间减少 37.5%、成本减少 38.3%。
 
-## <a id="library-api"></a>🛠️ 库 API
+### 大规模文本检索
 
-```ts
-import { createZvecGrep } from "@zvec/zvec-grep";
+我们使用 [BrowseComp-Plus](https://github.com/texttron/BrowseComp-Plus)，它要求
+Agent 从固定网页语料库中检索多文档证据。测试包含 30 个问题，覆盖 10 个映射主题
+和三个证据广度级别，每种方案运行 3 次。
 
-const zvecGrep = await createZvecGrep({
-  root: process.cwd(),
-});
+| 方案 | 准确率 ↑ | 证据召回率 ↑ | 搜索调用 ↓ | 输入 Token ↓ | 耗时（秒）↓ | 成本 ↓ |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| Agent + BM25 | TBD | TBD | TBD | TBD | TBD | TBD |
+| Agent + zg | TBD | TBD | TBD | TBD | TBD | TBD |
+| 变化 | TBD | TBD | TBD | TBD | TBD | TBD |
 
-const result = await zvecGrep.context({
-  query: "ranking implementation",
-  limit: 5,
-});
+在 30 个问题 × 3 次运行中，zg 对准确率、证据召回率、搜索调用、输入 Token、
+执行时间和成本的影响尚待测试结果补充。
 
-for (const item of result.items) {
-  const location =
-    item.range.kind === "text"
-      ? `${item.file.relativePath}:${item.range.startLine}`
-      : item.file.relativePath;
-  console.log(location);
-}
+如需复现测试，请按照[性能测试指南](./benchmarks/README.md)准备环境、固定版本、
+任务清单、基线配置、运行命令和结果汇总。所有方案使用相同的 Agent、模型、Prompt、
+工具预算和三次运行协议。
 
-await zvecGrep.close();
-```
+## 📚 文档
 
-显式进行无索引文本搜索：
+| 指南 | 你可以完成什么 |
+| :--- | :--- |
+| [Agent 集成](./docs/01-agents.md) | 将 zg 接入 Codex、Claude Code、Cursor 或 OpenCode，并验证是否正常工作。 |
+| [CLI 指南](./docs/02-cli.md) | 在终端中搜索、索引和管理本地工作区。 |
+| [MCP 指南](./docs/03-mcp.md) | 了解 Agent 可以使用哪些 zg 工具，以及访问权限如何受到保护。 |
+| [检索 Pipeline](./docs/04-pipeline.md) | 选择索引范围、保持内容新鲜，并获得更好的检索结果。 |
+| [架构](./docs/05-architecture.md) | 了解 zg 如何处理查询，以及数据会保留在哪里。 |
+| [服务端与执行模式](./docs/06-server.md) | 在一次性命令和长期运行的本地服务之间选择。 |
+| [Embedding 模型](./docs/07-embedding.md) | 根据速度、检索质量、隐私和本机硬件选择合适的模型。 |
+| [Roadmap](./docs/08-roadmap.md) | 了解接下来的产品方向，并参与影响 zg 的优先级。 |
 
-```ts
-const result = await zvecGrep.context({
-  query: "ZVEC_GREP_HOME",
-  rg: true,
-});
-```
+<a id="community"></a>
 
-## 🤝 加入 Zvec 社区
+## 🤝 加入社区
 
 <div align="center">
 
-|                                                💬 钉钉群                                                |                                                 📱 微信群                                                 |                                                                       🎮 Discord                                                                        |                                             X (Twitter)                                              |
-| :-----------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------: |
-| <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/dingding.png" width="150" alt="钉钉二维码"/> | <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/wechat.png?v=6" width="150" alt="微信二维码"/> | [![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/rKddFBBu9z) | [![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/ZvecAI)](https://x.com/ZvecAI) |
-|                                                扫码加入                                                 |                                                 扫码加入                                                  |                                                                        点击加入                                                                         |                                               点击关注                                               |
+| 💬 钉钉群 | 📱 微信群 | 🎮 Discord | X (Twitter) |
+| :---: | :---: | :---: | :---: |
+| <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/dingding.png" width="150" alt="钉钉二维码"/> | <img src="https://zvec.oss-cn-hongkong.aliyuncs.com/qrcode/wechat.png?v1" width="150" alt="微信二维码"/> | [![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/rKddFBBu9z) | [![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/ZvecAI)](<https://x.com/ZvecAI>) |
+| 扫码加入 | 扫码加入 | 点击加入 | 点击关注 |
 
 </div>
 
 ## ❤️ 参与贡献
 
-欢迎提交 issue 和 pull request。请保持改动聚焦；如果改变行为，请补充测试，并运行：
-
-```bash
-npm run check
-```
+始终欢迎社区贡献——缺陷修复、新功能和文档改进都会让 zvec-grep 变得更好。
 
-Pull request 标题需遵循 Conventional Commits。
+请查阅我们的[贡献指南](./CONTRIBUTING.md)开始参与！

package/dist/authorization/index.d.ts

@@ -0,0 +1,7 @@
+export { RemoteEmbeddingAuthorizationManager } from "./manager.js";
+export { createRemoteEmbeddingOperationPermit, remoteEmbeddingAuthorizationGuard, withRemoteEmbeddingOperationPermit, } from "./operation.js";
+export { RemoteEmbeddingAuthorizationStore } from "./store.js";
+export { formatRemoteEmbeddingAuthorizationPrompt, remoteEmbeddingDisclosureData, type RemoteEmbeddingAuthorizationPromptInput, } from "./prompt.js";
+export { indexStatusIsFresh, planRemoteIndexAuthorization, planRemoteSearchAuthorization, searchUsesVector, } from "./planner.js";
+export { canonicalizeWorkspaceRoots, createRemoteEmbeddingTarget, remoteEmbeddingTargetFingerprint, workspaceFingerprint, } from "./target.js";
+export type { RemoteEmbeddingAuthorizationPlan, RemoteEmbeddingAuthorizationScope, RemoteEmbeddingAuthorizationStatus, RemoteEmbeddingDataDisclosure, RemoteEmbeddingOperation, RemoteEmbeddingOperationPermit, RemoteEmbeddingTarget, RemoteEmbeddingWorkspaceGrant, } from "./types.js";

package/dist/authorization/index.js

@@ -0,0 +1,7 @@
+export { RemoteEmbeddingAuthorizationManager } from "./manager.js";
+export { createRemoteEmbeddingOperationPermit, remoteEmbeddingAuthorizationGuard, withRemoteEmbeddingOperationPermit, } from "./operation.js";
+export { RemoteEmbeddingAuthorizationStore } from "./store.js";
+export { formatRemoteEmbeddingAuthorizationPrompt, remoteEmbeddingDisclosureData, } from "./prompt.js";
+export { indexStatusIsFresh, planRemoteIndexAuthorization, planRemoteSearchAuthorization, searchUsesVector, } from "./planner.js";
+export { canonicalizeWorkspaceRoots, createRemoteEmbeddingTarget, remoteEmbeddingTargetFingerprint, workspaceFingerprint, } from "./target.js";
+//# sourceMappingURL=index.js.map

package/dist/authorization/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/authorization/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mCAAmC,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EACL,oCAAoC,EACpC,iCAAiC,EACjC,kCAAkC,GACnC,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,iCAAiC,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EACL,wCAAwC,EACxC,6BAA6B,GAE9B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,kBAAkB,EAClB,4BAA4B,EAC5B,6BAA6B,EAC7B,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,0BAA0B,EAC1B,2BAA2B,EAC3B,gCAAgC,EAChC,oBAAoB,GACrB,MAAM,aAAa,CAAC"}

package/dist/authorization/manager.d.ts

@@ -0,0 +1,8 @@
+import { RemoteEmbeddingAuthorizationStore } from "./store.js";
+import type { RemoteEmbeddingAuthorizationPlan, RemoteEmbeddingAuthorizationScope, RemoteEmbeddingOperationPermit } from "./types.js";
+export declare class RemoteEmbeddingAuthorizationManager {
+    readonly store: RemoteEmbeddingAuthorizationStore;
+    constructor(store?: RemoteEmbeddingAuthorizationStore);
+    existingWorkspacePermit(plan: RemoteEmbeddingAuthorizationPlan): Promise<RemoteEmbeddingOperationPermit | undefined>;
+    grant(plan: RemoteEmbeddingAuthorizationPlan, scope: RemoteEmbeddingAuthorizationScope): Promise<RemoteEmbeddingOperationPermit>;
+}

package/dist/authorization/manager.js

@@ -0,0 +1,19 @@
+import { createRemoteEmbeddingOperationPermit } from "./operation.js";
+import { RemoteEmbeddingAuthorizationStore } from "./store.js";
+export class RemoteEmbeddingAuthorizationManager {
+    store;
+    constructor(store = new RemoteEmbeddingAuthorizationStore()) {
+        this.store = store;
+    }
+    async existingWorkspacePermit(plan) {
+        if (!(await this.store.hasGrant(plan.target)))
+            return undefined;
+        return createRemoteEmbeddingOperationPermit(plan.target, "workspace");
+    }
+    async grant(plan, scope) {
+        if (scope === "workspace")
+            await this.store.grant(plan.target);
+        return createRemoteEmbeddingOperationPermit(plan.target, scope);
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/authorization/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../src/authorization/manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oCAAoC,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EAAE,iCAAiC,EAAE,MAAM,YAAY,CAAC;AAO/D,MAAM,OAAO,mCAAmC;IACrC,KAAK,CAAoC;IAElD,YAAY,KAAK,GAAG,IAAI,iCAAiC,EAAE;QACzD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,uBAAuB,CAC3B,IAAsC;QAEtC,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAAE,OAAO,SAAS,CAAC;QAChE,OAAO,oCAAoC,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,KAAK,CACT,IAAsC,EACtC,KAAwC;QAExC,IAAI,KAAK,KAAK,WAAW;YAAE,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC/D,OAAO,oCAAoC,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAClE,CAAC;CACF"}

package/dist/authorization/operation.d.ts

@@ -0,0 +1,7 @@
+import { RemoteEmbeddingAuthorizationStore } from "./store.js";
+import { type RemoteEmbeddingAuthorizationScope, type RemoteEmbeddingOperationPermit, type RemoteEmbeddingRequest, type RemoteEmbeddingTarget } from "./types.js";
+export declare function createRemoteEmbeddingOperationPermit(target: RemoteEmbeddingTarget, scope: RemoteEmbeddingAuthorizationScope): RemoteEmbeddingOperationPermit;
+export declare function withRemoteEmbeddingOperationPermit<T>(permit: RemoteEmbeddingOperationPermit | undefined, operation: () => Promise<T>): Promise<T>;
+export declare function remoteEmbeddingAuthorizationGuard(options?: {
+    store?: RemoteEmbeddingAuthorizationStore;
+}): (request: RemoteEmbeddingRequest) => Promise<void>;

package/dist/authorization/operation.js

@@ -0,0 +1,50 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { EngineError } from "../engine/errors.js";
+import { RemoteEmbeddingAuthorizationStore } from "./store.js";
+import { REMOTE_EMBEDDING_CAPABILITY, } from "./types.js";
+const operationPermit = new AsyncLocalStorage();
+export function createRemoteEmbeddingOperationPermit(target, scope) {
+    return {
+        capability: REMOTE_EMBEDDING_CAPABILITY,
+        scope,
+        target,
+        issuedAt: Date.now(),
+        operationId: randomUUID(),
+    };
+}
+export async function withRemoteEmbeddingOperationPermit(permit, operation) {
+    if (!permit)
+        return await operation();
+    return await operationPermit.run(permit, operation);
+}
+export function remoteEmbeddingAuthorizationGuard(options = {}) {
+    const store = options.store ?? new RemoteEmbeddingAuthorizationStore();
+    return async (request) => {
+        const permit = operationPermit.getStore();
+        if (!permit ||
+            permit.capability !== REMOTE_EMBEDDING_CAPABILITY ||
+            permit.target.provider !== request.provider ||
+            permit.target.model !== request.model ||
+            permit.target.endpoint !== request.endpoint) {
+            throw authorizationRequiredError(request);
+        }
+        if (permit.scope === "workspace" &&
+            !(await store.hasGrant(permit.target))) {
+            throw authorizationRequiredError(request, "Workspace grant is missing, invalid, or revoked.");
+        }
+    };
+}
+function authorizationRequiredError(request, detail) {
+    return new EngineError("Remote Embedding authorization is required", {
+        code: "ZVEC_GREP.ENGINE.AUTH.REMOTE_EMBEDDING_REQUIRED",
+        context: [
+            `provider=${request.provider}`,
+            `model=${request.model}`,
+            `endpoint=${request.endpoint}`,
+            `purpose=${request.purpose}`,
+            ...(detail ? [`detail=${detail}`] : []),
+        ].join(" "),
+    });
+}
+//# sourceMappingURL=operation.js.map

package/dist/authorization/operation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation.js","sourceRoot":"","sources":["../../src/authorization/operation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,iCAAiC,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EACL,2BAA2B,GAK5B,MAAM,YAAY,CAAC;AAEpB,MAAM,eAAe,GAAG,IAAI,iBAAiB,EAAkC,CAAC;AAEhF,MAAM,UAAU,oCAAoC,CAClD,MAA6B,EAC7B,KAAwC;IAExC,OAAO;QACL,UAAU,EAAE,2BAA2B;QACvC,KAAK;QACL,MAAM;QACN,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE;QACpB,WAAW,EAAE,UAAU,EAAE;KAC1B,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kCAAkC,CACtD,MAAkD,EAClD,SAA2B;IAE3B,IAAI,CAAC,MAAM;QAAE,OAAO,MAAM,SAAS,EAAE,CAAC;IACtC,OAAO,MAAM,eAAe,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,iCAAiC,CAC/C,UAEI,EAAE;IAEN,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,IAAI,iCAAiC,EAAE,CAAC;IACvE,OAAO,KAAK,EAAE,OAAO,EAAE,EAAE;QACvB,MAAM,MAAM,GAAG,eAAe,CAAC,QAAQ,EAAE,CAAC;QAC1C,IACE,CAAC,MAAM;YACP,MAAM,CAAC,UAAU,KAAK,2BAA2B;YACjD,MAAM,CAAC,MAAM,CAAC,QAAQ,KAAK,OAAO,CAAC,QAAQ;YAC3C,MAAM,CAAC,MAAM,CAAC,KAAK,KAAK,OAAO,CAAC,KAAK;YACrC,MAAM,CAAC,MAAM,CAAC,QAAQ,KAAK,OAAO,CAAC,QAAQ,EAC3C,CAAC;YACD,MAAM,0BAA0B,CAAC,OAAO,CAAC,CAAC;QAC5C,CAAC;QACD,IACE,MAAM,CAAC,KAAK,KAAK,WAAW;YAC5B,CAAC,CAAC,MAAM,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EACtC,CAAC;YACD,MAAM,0BAA0B,CAC9B,OAAO,EACP,kDAAkD,CACnD,CAAC;QACJ,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,0BAA0B,CACjC,OAA+B,EAC/B,MAAe;IAEf,OAAO,IAAI,WAAW,CAAC,4CAA4C,EAAE;QACnE,IAAI,EAAE,iDAAiD;QACvD,OAAO,EAAE;YACP,YAAY,OAAO,CAAC,QAAQ,EAAE;YAC9B,SAAS,OAAO,CAAC,KAAK,EAAE;YACxB,YAAY,OAAO,CAAC,QAAQ,EAAE;YAC9B,WAAW,OAAO,CAAC,OAAO,EAAE;YAC5B,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,UAAU,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SACxC,CAAC,IAAI,CAAC,GAAG,CAAC;KACZ,CAAC,CAAC;AACL,CAAC"}

package/dist/authorization/planner.d.ts

@@ -0,0 +1,21 @@
+import type { NormalizedSearchInput } from "../mcp/input-normalization.js";
+import type { EmbeddingModelInfo } from "../engine/models/index.js";
+import type { ZvecGrepInfoResult } from "../engine/service/types.js";
+import { RemoteEmbeddingAuthorizationStore } from "./store.js";
+import type { RemoteEmbeddingAuthorizationPlan } from "./types.js";
+export declare function planRemoteIndexAuthorization(input: {
+    info: ZvecGrepInfoResult;
+    model: EmbeddingModelInfo;
+    rebuild?: boolean;
+    needsUpdate?: boolean;
+    store?: RemoteEmbeddingAuthorizationStore;
+}): Promise<RemoteEmbeddingAuthorizationPlan | undefined>;
+export declare function planRemoteSearchAuthorization(input: {
+    info: ZvecGrepInfoResult;
+    model: EmbeddingModelInfo;
+    search: NormalizedSearchInput;
+    runtimeNeedsReconciliation?: boolean;
+    store?: RemoteEmbeddingAuthorizationStore;
+}): Promise<RemoteEmbeddingAuthorizationPlan | undefined>;
+export declare function searchUsesVector(input: Pick<NormalizedSearchInput, "queries" | "routes">): boolean;
+export declare function indexStatusIsFresh(info: ZvecGrepInfoResult): boolean;