dsh-locator 0.12.1 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.14.0 — 2026-11-14
+
+* **Capability adapter (Wave 3, part 1)**: new tools `capability_search(intent, kinds?, riskMax?, ...)` and `capability_preflight(capability, argsJson?)` index the **live** DSH registries — tool definitions (including `mcp__<server>__<tool>` entries) and the skill catalog — and add intent matching, inferred risk (read/write/exec plus approval/sandbox hints), argument-schema validation and side-effect reporting. It reads `ctx.tools.definitions()` / `ctx.skills.list()`; it does not duplicate discovery and has no embedding dependency.
+* Snapshot cache (60 s) and graceful degradation: a missing skill service or registry produces warnings instead of breaking the tool.
+* `171 tests`; six engine binaries rebuilt at 0.14.0.
+* Deferred and explicitly documented: refs persistence plus URL/spill/attachment refs and the panel ref chip (Wave 2), the panel capability view (Wave 3 UI), and tenant/enterprise packaging (blocked on a real dsh-ee instance and credentials).
+
+## 0.13.0 — 2026-11-14
+
+* **Authorization fix**: `locator_find` no longer lets `sessionId`, `scope: "all"` or `pathPrefix` bypass the caller's identity. An explicit session id is allowed only for the caller session or sessions whose immutable `cwd` equals the caller cwd (the same rule as DSH's session-query tools); `pathPrefix` must resolve inside the configured roots; `scope: "all"` still searches every indexed file but keeps session documents inside the caller's authorized set unless the new `allowCrossWorkspaceSessions: true` is configured.
+* **Workspace scope for name search**: `locator_search` now defaults to the caller cwd when that cwd is inside an indexed root (`scope: "all"` searches every configured root; a cwd outside the roots falls back to the indexed roots and says so in `scopeFallback`).
+* **Citable evidence refs**: every `locator_search`/`locator_find` hit now carries `ref` (`dsh-session:` URI for session messages, `ref://file?...&sha256=` for files) plus `provenance`, `freshness` (fresh/stale/missing/unknown) and `permissions`. New tools `locator_resolve` (metadata + bounded, authorized excerpt) and `locator_cite` (markdown/mention/json citations) make hits quotable instead of just paths.
+* Session cwd is recorded in the content index (`sources.cwd`, additive migration; first refresh re-reads session logs only, never the 6.6 GB file index) to drive the authorization rule.
+* `164 tests`; six engine binaries rebuilt at 0.13.0.
+
 ## 0.12.1 — 2026-11-14
 
 * Panel: **root filter** for multi-root installs (files, dirs and content hits narrow to the selected root; the route re-authorizes the requested prefix against the configured roots), **CSV/JSON export** of the currently loaded/filtered rows, **recent-query suggestions** in the `Ctrl+F` find bar, and an **archived-sessions** checkbox that includes archived logs for one query.

package/README-es.md

@@ -247,6 +247,7 @@ Cada campo es un campo de configuración de Schemastery; sobrescribe la entrada
 | `contentRefreshMs` | `300000` | Cadencia de actualización incremental del contenido; `0` la desactiva. |
 | `contentIncludeArchived` | `false` | Incluir sesiones archivadas en las búsquedas normales (se indexan igualmente; el panel puede incluirlas por consulta). |
 | `contentIndexToolResults` | `false` | Indexar el texto de `tool/result` como documentos de sesión propios (cambiarlo solo reconstruye sesiones). |
+| `allowCrossWorkspaceSessions` | `false` | Si `scope: "all"` puede leer sesiones de otros workspaces (por defecto se autoriza por cwd del llamador). |
 | `contentActiveSessionDelayMs` | `120000` | Indexar un log de sesión solo tras este tiempo de calma. |
 | `contentSessionDirs` | `[]` | Directorios de sesión adicionales; vacío = `$DSH_HOME/sessions`. |
 | `contentExcludes` | nombres de dependencias/toolchains | Segmentos o subcadenas de ruta que omite el índice de contenido; el de nombres sí los cubre. |
@@ -402,6 +403,18 @@ DeepSeek Harness
 
 El motor es un único proceso Go y respeta las variables estándar `GOMEMLIMIT` y `GOGC` (o `memoryLimitMB` en la configuración). Un índice de 1,2–1,5 M de entradas alcanza varios cientos de MB de RSS con el GC por defecto; usa `GOMEMLIMIT=600MiB` (límite blando, el runtime cambia CPU por memoria) o `GOGC=50` cuando el host vaya justo de RAM. Ninguno cambia el formato de la instantánea. En la instalación en vivo usada para las cifras anteriores, el proceso anfitrión de DSH (incluida la caché de páginas de la base de contenido) rondaba los 700 MB de RSS con el índice construido, y la latencia del host en reposo se mantenía en p50 2 ms.
 
+## Notas de actualización 0.14.0
+
+- **Adaptador de capacidades**: `capability_search` (encontrar "quién puede hacer esto" desde una intención) y `capability_preflight` (visibilidad, validación del esquema de argumentos, aprobación/sandbox y efectos secundarios) leen el registro de herramientas en vivo (incluidas acciones MCP) y el catálogo de skills. Sin descubrimiento duplicado ni embeddings; refresco cada 60 s.
+- Primera parte de Wave 3; la vista de capacidades en el panel, el empaquetado multi-tenant/empresa y los refs persistentes de Wave 2 quedan para versiones posteriores.
+
+## Notas de actualización 0.13.0
+
+- **Corrección de autorización**: `locator_find` ya no permite que `sessionId`, `scope:"all"` o `pathPrefix` eludan la identidad del llamador. Un id de sesión explícito solo se acepta para la sesión del llamador o sesiones cuyo `cwd` inmutable coincide (misma regla que las herramientas session-query de DSH); `pathPrefix` debe resolver dentro de los roots configurados; `scope:"all"` sigue buscando todos los archivos pero limita las sesiones al conjunto autorizado salvo `allowCrossWorkspaceSessions: true`.
+- **Ámbito workspace en búsqueda por nombre**: `locator_search` usa por defecto el cwd del llamador cuando está dentro de un root indexado (`scope:"all"` busca todos los roots; un cwd fuera de los roots vuelve a los roots indexados e informa `scopeFallback`).
+- **Refs de evidencia citables**: cada acierto incluye `ref` (URI `dsh-session:` para mensajes, `ref://file?...&sha256=` para archivos), `provenance`, `freshness` y `permissions`; nuevas `locator_resolve` (metadatos + extracto acotado autorizado) y `locator_cite` (markdown/mention/json).
+- El cwd de la sesión se guarda en el índice (`sources.cwd`, migración aditiva; la primera actualización tras el upgrade reconstruye solo documentos de sesión).
+
 ## Notas de actualización 0.12.1
 
 - Panel: **filtro por raíz** cuando hay varias raíces (archivos, carpetas y contenido se limitan a la raíz elegida; la ruta revalida que el prefijo esté bajo una raíz configurada); **exportación CSV/JSON** de los resultados cargados/filtrados; la barra `Ctrl+F` recuerda **búsquedas recientes** con sugerencias nativas del navegador.

package/README-hi.md

@@ -248,6 +248,7 @@ Web GUI में कहीं भी `Ctrl+Shift+F` दबाएँ, या स
 | `contentRefreshMs` | `300000` | कंटेंट इंक्रीमेंटल रिफ़्रेश अंतराल; `0` बंद। |
 | `contentIncludeArchived` | `false` | सामान्य खोजों में आर्काइव सेशन शामिल करें (वे हर हाल में इंडेक्स होते हैं; पैनल प्रति क्वेरी शामिल कर सकता है)। |
 | `contentIndexToolResults` | `false` | `tool/result` टेक्स्ट को अलग session दस्तावेज़ों के रूप में इंडेक्स करें (बदलने पर केवल session rebuild)। |
+| `allowCrossWorkspaceSessions` | `false` | `scope:"all"` अन्य workspaces के session बॉडी पढ़ सके या नहीं (डिफ़ॉल्ट: कॉलर cwd से अधिकृत)। |
 | `contentActiveSessionDelayMs` | `120000` | सेशन लॉग इस अवधि तक शांत रहने पर इंडेक्स हो। |
 | `contentSessionDirs` | `[]` | अतिरिक्त सेशन डायरेक्टरी; खाली = `$DSH_HOME/sessions`। |
 | `contentExcludes` | डिपेंडेंसी/toolchain नाम | कंटेंट इंडेक्स में छोड़े जाने वाले पाथ हिस्से/सबस्ट्रिंग; नाम इंडेक्स उन्हें कवर करता है। |
@@ -403,6 +404,18 @@ DeepSeek Harness
 
 इंजन एक Go प्रोसेस है और मानक `GOMEMLIMIT` और `GOGC` (या कॉन्फ़िग में `memoryLimitMB`) मानता है। 1.2–1.5 M एंट्री का इंडेक्स डिफ़ॉल्ट GC के साथ कई सौ MB RSS तक जाता है; होस्ट पर RAM कम हो तो `GOMEMLIMIT=600MiB` (सॉफ़्ट सीमा, रनटाइम CPU देकर मेमोरी बचाता है) या `GOGC=50` रखें। इनसे स्नैपशॉट फ़ॉर्मेट नहीं बदलता। ऊपर के आँकड़ों वाले लाइव सेटअप में DSH होस्ट प्रोसेस (कंटेंट डेटाबेस पेज कैश सहित) इंडेक्स बने रहने पर लगभग 700 MB RSS पर था, और खाली बैठे होस्ट की देरी p50 2ms रही।
 
+## 0.14.0 अपग्रेड नोट्स
+
+- **क्षमता अनुकूलक (capability adapter)**: `capability_search` (स्वाभाविक भाषा में "यह कौन कर सकता है" खोजें) और `capability_preflight` (दृश्यता, argument schema जाँच, approval/sandbox आवश्यकताएँ, side effects) होस्ट के live tool registry (MCP actions सहित) और skill catalog से पढ़ते हैं। कोई दोहरा discovery या embedding नहीं; snapshot हर 60 s में ताज़ा।
+- यह Wave 3 का पहला भाग है; panel capability view, tenant/enterprise packaging और Wave 2 के refs persistence/URL·spill·attachment refs आगे के संस्करणों में।
+
+## 0.13.0 अपग्रेड नोट्स
+
+- **अधिकार सुधार**: `locator_find` अब `sessionId`, `scope:"all"` या `pathPrefix` को कॉलर की पहचान बायपास करने नहीं देता। स्पष्ट session id केवल कॉलर सत्र या जिनका अपरिवर्तनीय `cwd` कॉलर के बराबर है (DSH session-query नियम) के लिए मान्य है; `pathPrefix` कॉन्फ़िगर किए roots के अंदर होना चाहिए; `scope:"all"` सभी फ़ाइलें खोजता है पर सत्र पंक्तियाँ कॉलर के अधिकृत सेट तक सीमित रहती हैं जब तक `allowCrossWorkspaceSessions: true` न हो।
+- **नाम खोज में workspace स्कोप**: `locator_search` अब कॉलर cwd (जब वह किसी indexed root के अंदर हो) पर डिफ़ॉल्ट है; `scope:"all"` सभी roots खोजता है; cwd बाहर होने पर indexed roots पर फ़ॉलबैक और `scopeFallback` संकेत।
+- **उद्धरण योग्य refs**: हर hit में अब `ref` (`dsh-session:` URI सत्र संदेशों के लिए, `ref://file?...&sha256=` फ़ाइलों के लिए), `provenance`, `freshness`, `permissions` हैं; नए `locator_resolve` (मेटाडेटा + सीमित अधिकृत अंश) और `locator_cite` (markdown/mention/json)।
+- सत्र cwd इंडेक्स में दर्ज होता है (`sources.cwd`, additive माइग्रेशन; अपग्रेड के बाद पहला रिफ्रेश केवल session दस्तावेज़ rebuild करता है)।
+
 ## 0.12.1 अपग्रेड नोट्स
 
 - पैनल: कई roots होने पर **रूट फ़िल्टर** (फ़ाइलें, फ़ोल्डर और सामग्री चुने गए रूट तक सीमित; रूट वही जाँचता है कि prefix किसी कॉन्फ़िगर किए रूट के अंदर हो); लोड/फ़िल्टर किए गए परिणामों का **CSV/JSON निर्यात**; `Ctrl+F` खोज-पट्टी **हाल की क्वेरी** याद रखती है (ब्राउज़र के सुझाव)।

package/README-pt.md

@@ -248,6 +248,7 @@ Cada campo é um campo de configuração do Schemastery; sobrescreva a entrada `
 | `contentRefreshMs` | `300000` | Cadência de atualização incremental do conteúdo; `0` desativa. |
 | `contentIncludeArchived` | `false` | Incluir sessões arquivadas nas buscas normais (são indexadas de qualquer forma; o painel pode incluí-las por consulta). |
 | `contentIndexToolResults` | `false` | Indexar o texto de `tool/result` como documentos de sessão próprios (alternar só reconstrói sessões). |
+| `allowCrossWorkspaceSessions` | `false` | Se `scope: "all"` pode ler sessões de outros workspaces (por padrão autoriza pelo cwd do chamador). |
 | `contentActiveSessionDelayMs` | `120000` | Indexar um log de sessão só após esse tempo de quietude. |
 | `contentSessionDirs` | `[]` | Diretórios de sessão extras; vazio = `$DSH_HOME/sessions`. |
 | `contentExcludes` | nomes de dependências/toolchains | Segmentos ou substrings de caminho ignorados pelo índice de conteúdo; o de nomes continua cobrindo. |
@@ -403,6 +404,18 @@ DeepSeek Harness
 
 O motor é um único processo Go e respeita as variáveis padrão `GOMEMLIMIT` e `GOGC` (ou `memoryLimitMB` na configuração). Um índice de 1,2–1,5 M de entradas chega a várias centenas de MB de RSS com o GC padrão; use `GOMEMLIMIT=600MiB` (limite suave, o runtime troca CPU por memória) ou `GOGC=50` quando o host estiver apertado de RAM. Nenhum altera o formato do snapshot. Na instalação ao vivo usada para os números acima, o processo anfitrião do DSH (incluindo o cache de páginas do banco de conteúdo) ficava por volta de 700 MB de RSS com o índice construído, e a latência do host ocioso permanecia em p50 2 ms.
 
+## Notas de atualização 0.14.0
+
+- **Adaptador de capacidades**: `capability_search` (encontrar "quem pode fazer isso" a partir de uma intenção) e `capability_preflight` (visibilidade, validação de schema dos argumentos, aprovação/sandbox e efeitos colaterais) leem o registro de ferramentas ao vivo (incluindo ações MCP) e o catálogo de skills. Sem descoberta duplicada e sem embeddings; atualização a cada 60 s.
+- Primeira parte da Wave 3; a visão de capacidades no painel, o empacotamento multi-tenant/empresa e os refs persistentes da Wave 2 ficam para versões futuras.
+
+## Notas de atualização 0.13.0
+
+- **Correção de autorização**: `locator_find` não deixa mais `sessionId`, `scope:"all"` ou `pathPrefix` contornarem a identidade do chamador. Um id de sessão explícito só é aceito para a sessão do chamador ou sessões cujo `cwd` imutável coincide (mesma regra das ferramentas session-query do DSH); `pathPrefix` deve resolver dentro dos roots configurados; `scope:"all"` continua buscando todos os arquivos mas limita as sessões ao conjunto autorizado, salvo `allowCrossWorkspaceSessions: true`.
+- **Escopo workspace na busca por nome**: `locator_search` usa o cwd do chamador quando ele está dentro de um root indexado (`scope:"all"` busca todos os roots; cwd fora dos roots volta aos roots indexados com `scopeFallback`).
+- **Refs de evidência citáveis**: cada acerto agora traz `ref` (URI `dsh-session:` para mensagens, `ref://file?...&sha256=` para arquivos), `provenance`, `freshness` e `permissions`; novas `locator_resolve` (metadados + trecho limitado autorizado) e `locator_cite` (markdown/mention/json).
+- O cwd da sessão é gravado no índice (`sources.cwd`, migração aditiva; a primeira atualização após o upgrade reconstrói apenas documentos de sessão).
+
 ## Notas de atualização 0.12.1
 
 - Painel: **filtro por raiz** quando há várias raízes (arquivos, pastas e conteúdo ficam limitados à raiz escolhida; a rota revalida que o prefixo está sob uma raiz configurada); **exportação CSV/JSON** dos resultados carregados/filtrados; a barra `Ctrl+F` lembra **buscas recentes** com sugestões nativas do navegador.

package/README.en.md

@@ -248,6 +248,7 @@ Every field is a Schemastery config field; override the `dsh-locator` entry in t
 | `contentRefreshMs` | `300000` | Incremental content refresh cadence; `0` disables it. |
 | `contentIncludeArchived` | `false` | Include archived sessions in ordinary searches (archived logs are indexed either way; the panel can include them per query). |
 | `contentIndexToolResults` | `false` | Index `tool/result` text as its own session documents (toggling rebuilds session documents only). |
+| `allowCrossWorkspaceSessions` | `false` | Whether `scope: "all"` may read session bodies from other workspaces (default: authorize by caller cwd). |
 | `contentActiveSessionDelayMs` | `120000` | Only index a session log after it has been quiet this long. |
 | `contentSessionDirs` | `[]` | Extra session directories; empty means `$DSH_HOME/sessions`. |
 | `contentExcludes` | dependency/toolchain names | Path segments or substrings the content index skips; the name index still covers them. |
@@ -403,6 +404,18 @@ DeepSeek Harness
 
 The engine is a single Go process and honours the standard `GOMEMLIMIT` and `GOGC` environment variables (or `memoryLimitMB` in the config). A 1.2–1.5 M-entry index peaks around several hundred MB of RSS with the default GC; set `GOMEMLIMIT=600MiB` (soft limit, the runtime trades CPU for memory) or `GOGC=50` when the host is tight on RAM. Neither changes the snapshot format. In the live setup used for the numbers above, the DSH host process (including the content database page cache) sat around 700 MB RSS with the content index built, and idle host latency stayed at p50 2 ms.
 
+## 0.14.0 upgrade notes
+
+- **Capability adapter**: `capability_search` (find "who can do this" from a natural-language intent) and `capability_preflight` (visibility, argument-schema validation, approval/sandbox requirements and side effects) read the host's live tool registry (including MCP actions) and skill catalog. No duplicate discovery and no embedding model; snapshots refresh every 60 s.
+- This is part 1 of Wave 3. The panel capability view, tenancy/enterprise packaging (needs a real dsh-ee instance and credentials) and the Wave 2 refs persistence/URL·spill·attachment refs remain future work.
+
+## 0.13.0 upgrade notes
+
+- **Authorization fix**: `locator_find` no longer lets `sessionId`, `scope: "all"` or `pathPrefix` bypass the caller identity. An explicit session id is allowed only for the caller session or sessions whose immutable `cwd` equals the caller cwd (same rule as DSH's session-query tools); `pathPrefix` must resolve inside the configured roots; `scope: "all"` still searches every indexed file but keeps session bodies inside the caller's authorized set unless `allowCrossWorkspaceSessions: true` is configured.
+- **Workspace scope for name search**: `locator_search` defaults to the caller cwd when it is inside an indexed root (`scope: "all"` searches every root; a cwd outside the roots falls back to the indexed roots and reports `scopeFallback`).
+- **Citable evidence refs**: every hit now carries `ref` (`dsh-session:` URIs for session messages, `ref://file?...&sha256=` for files), `provenance`, `freshness` and `permissions`; new `locator_resolve` (metadata + bounded authorized excerpt) and `locator_cite` (markdown/mention/json) turn hits into citations instead of bare paths.
+- Session cwd is recorded in the content index (`sources.cwd`, additive migration; the first refresh after upgrading rebuilds session documents only, never the 6.6 GB file index).
+
 ## 0.12.1 upgrade notes
 
 - Panel: a **root filter** when several roots are configured (files, dirs and content hits narrow to the selected root; the route re-checks that the prefix lives under a configured root); **CSV/JSON export** of the currently loaded/filtered results; the `Ctrl+F` find bar remembers **recent queries** through native input suggestions.

package/README.md

@@ -243,6 +243,7 @@ case:1  wholeword:1     区分大小写 / 全词匹配
 | `contentRefreshMs` | 300000 | 内容增量刷新周期；0 关闭自动刷新。 |
 | `contentIncludeArchived` | `false` | 是否在普通搜索中包含已归档会话（归档会话始终索引，面板可逐次勾选）。 |
 | `contentIndexToolResults` | `false` | 是否把 `tool/result` 文本作为独立会话文档入索引（切换只重建会话）。 |
+| `allowCrossWorkspaceSessions` | `false` | `scope:"all"` 是否可读其他 workspace 的会话正文（默认按调用方 cwd 授权）。 |
 | `contentActiveSessionDelayMs` | 120000 | 会话日志安静多久后才索引。 |
 | `contentSessionDirs` | `$DSH_HOME/sessions` | 额外的会话目录。 |
 | `contentExcludes` | 依赖/工具链目录 | 内容索引跳过的路径片段/子串；名称索引不受影响。 |
@@ -365,6 +366,18 @@ Go 引擎在 `engine/` 下，测试用 `cd engine && go test ./...`。macOS 的
 - 当前会话范围只覆盖已落定索引的会话消息（活跃会话约 2 分钟延迟）；实时查找用 `Ctrl+F`。会话内查找条只覆盖已加载窗口，更早历史需手动加载。
 - 会话内高亮依赖 CSS Custom Highlight API；不支持它的旧浏览器会退化为整行描边。
 
+## 0.14.0 更新
+
+- **能力索引适配器**：新增 `capability_search`（自然语言找“谁能做这件事”）与 `capability_preflight`（能力是否可见、参数是否符合 schema、需要什么审批/沙箱、有哪些副作用）；数据来自宿主已有的 tool registry（含 MCP 工具）与 skill catalog，不重复发现、不用 embedding，60s 自动刷新。
+- 本版是 Wave 3 的第一部分；面板能力页、租户/企业包，以及 Wave 2 的 refs 持久化/URL·spill·attachment ref 留待后续版本（企业包需 dsh-ee 实例与凭据）。
+
+## 0.13.0 更新
+
+- **授权修复**：`locator_find` 的 `sessionId`/`scope:"all"`/`pathPrefix` 不再绕过调用方身份——显式会话 id 只允许「当前会话」或「header.cwd 与调用方相同的会话」（与 DSH session-query 工具一致）；`pathPrefix` 必须落在已配置 root 内；`scope:"all"` 仍可搜全部文件，但会话正文默认限调用方授权集合（`allowCrossWorkspaceSessions: true` 可显式放开）。
+- **名称搜索默认 workspace**：`locator_search` 在 cwd 位于索引 root 内时默认只返回 cwd 下的命中（`scope:"all"` 搜全部 root；cwd 不在 root 内时退回索引 roots 并用 `scopeFallback` 说明）。
+- **可引用证据 ref**：`locator_search`/`locator_find` 的每条命中新增 `ref`（会话用 `dsh-session:` URI，文件用 `ref://file?...&sha256=`）、`provenance`、`freshness`、`permissions`；新增 `locator_resolve`（元数据+有界摘录，带授权）与 `locator_cite`（markdown/mention/json 引用），结果从"路径"升级为"可引用证据"。
+- 内容索引记录会话 `cwd`（`sources.cwd`，additive 迁移；升级后首次刷新只重建会话文档，不动 6.6GB 文件索引）。
+
 ## 0.12.1 更新
 
 - 面板：多 root 时新增**根目录筛选**（文件/目录/内容命中都按所选 root 过滤，服务端会校验该前缀确实在已配置 root 之下）；新增 **CSV/JSON 导出**当前已加载/过滤结果；`Ctrl+F` 查找条记住**最近查询**（浏览器原生输入建议）。

package/lib/capabilities.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Capability index: which tool/skill/MCP action can do a job, what it costs and
+ * what it may touch. This is a thin adapter over the DSH registries the host
+ * already keeps (tool definitions, skill catalog): it does not re-implement
+ * discovery, it adds intent matching, risk labels and a preflight check.
+ * @module dsh-locator/capabilities
+ */
+import type { ToolRunContext } from '@deepseek-ai/dsh-tools';
+/** One capability card. */
+export interface CapabilityCard {
+    id: string;
+    kind: 'tool' | 'mcp' | 'skill';
+    name: string;
+    summary: string;
+    input?: Record<string, unknown>;
+    tags: string[];
+    risk: {
+        level: 'read' | 'write' | 'exec';
+        actions: string[];
+        basis: 'schema' | 'name';
+    };
+    permission: {
+        approval: 'none' | 'ask';
+        sandbox: 'none' | 'write' | 'any';
+    };
+    state: 'available' | 'unknown';
+    source: 'tools' | 'skills';
+}
+/** One snapshot of the live capability surface. */
+export interface CapabilitySnapshot {
+    builtAt: number;
+    cards: CapabilityCard[];
+    warnings: string[];
+}
+/** Minimal shape of the host services this module reads. */
+export interface CapabilitySources {
+    tools?: {
+        definitions?: (scope?: unknown, toolSet?: unknown) => readonly unknown[];
+        get?: (name: string, scope?: unknown) => unknown;
+    } | undefined;
+    skills?: {
+        list?: (options?: Record<string, unknown>) => Promise<readonly unknown[]>;
+    } | undefined;
+}
+/** Tokenize one intent/name for the lexical scorer (letters, digits, CJK). */
+export declare function tokenize(text: string): string[];
+/** Infer risk/permission from a tool name, description and parameter schema. */
+export declare function inferRisk(name: string, description: string, parameters?: Record<string, unknown>): CapabilityCard['risk'] & {
+    permission: CapabilityCard['permission'];
+};
+/** Build one capability snapshot from the live host services. */
+export declare function buildCapabilitySnapshot(sources: CapabilitySources, scope?: unknown): Promise<CapabilitySnapshot>;
+/** Card projection returned by tools: drop the full input schema payload. */
+export declare function publicCard(card: CapabilityCard): Omit<CapabilityCard, 'input'>;
+/** One ranked capability hit. */
+export interface CapabilityHit {
+    card: CapabilityCard;
+    score: number;
+    why: string[];
+}
+/**
+ * Rank capability cards against an intent and optional filters.
+ * @param cards - snapshot cards.
+ * @param intent - what the caller wants to do.
+ * @param options - kind/risk filters and pagination.
+ * @returns ranked hits and the total before paging.
+ */
+export declare function searchCapabilities(cards: readonly CapabilityCard[], intent: string, options?: {
+    kinds?: readonly CapabilityCard['kind'][];
+    riskMax?: 'read' | 'write' | 'exec';
+    limit?: number;
+    offset?: number;
+    availableOnly?: boolean;
+}): {
+    hits: CapabilityHit[];
+    total: number;
+};
+/** One preflight result. */
+export interface PreflightResult {
+    ok: boolean;
+    card?: CapabilityCard;
+    admitted: boolean;
+    schema?: {
+        valid: boolean;
+        violations: string[];
+    };
+    requires: {
+        approval: 'none' | 'ask';
+        sandbox: 'none' | 'write' | 'any';
+    };
+    sideEffects: string[];
+    next: {
+        callable: boolean;
+        suggestion?: string;
+    };
+    error?: string;
+    warnings: string[];
+}
+/**
+ * Check whether one capability can be called with the given arguments right
+ * now: existence/visibility, argument schema, predicted approval/sandbox and
+ * side effects. It never executes the target.
+ */
+export declare function preflightCapability(snapshot: CapabilitySnapshot, target: string, args?: Record<string, unknown>, sources?: CapabilitySources, scope?: unknown): PreflightResult;
+/** Build `capability_search` and `capability_preflight` bound to the host registries. */
+export declare function makeCapabilityTools(sources: CapabilitySources): readonly [import("@deepseek-ai/dsh-tools").ToolDefinition, import("@deepseek-ai/dsh-tools").ToolDefinition];
+/** ToolRunContext re-export keeps the module self-describing for tests. */
+export type { ToolRunContext };
+//# sourceMappingURL=capabilities.d.ts.map

package/lib/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"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"}