dsh-context-toolkit 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chimneyQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+# dsh-context-toolkit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> [简体中文](./README.zh.md) | **English**
+
+A DeepSeek Harness bundle whose single job is **keeping bulk output out of the conversation**.
+
+It separates *raw bytes* from *conclusions*: commands run in a child process, files are analysed in a sandbox, and long material is filed into a local knowledge base — while the conversation receives only conclusions, excerpts and counts. A routing gate refuses, before execution, the calls that would inevitably flood the transcript.
+
+**No third-party runtime dependencies.** The knowledge base rides on Node's own `node:sqlite` (FTS5 included) and code execution uses interpreters already on the machine, so installing it pulls nothing else.
+
+## What it is for
+
+| Problem | What this does |
+|---|---|
+| A command prints thousands of lines; you only need a count | `ctk_execute` runs it in a child process and returns the answer |
+| A large file needs statistics, not a full read | `ctk_execute_file` keeps its bytes in the sandbox |
+| Many commands, one question | `ctk_batch_execute` answers in one call with per-command status |
+| A page or spec is read once and never reused | `ctk_index` files it; `ctk_search` pulls excerpts on demand |
+| `curl` / `wget` paste whole responses into the conversation | The routing gate refuses them and names the alternative |
+| You cannot tell how much was saved | `ctk_stats` reports the ledger; the settings page shows a live occupancy panel |
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `ctk_execute` | Run code in a sandboxed child process (javascript / esm / typescript / shell), return only the answer |
+| `ctk_execute_file` | Run code over a file for statistics or extraction; the file text stays in the sandbox |
+| `ctk_batch_execute` | Several commands in one call, per-command status, conclusions only |
+| `ctk_index` | File text or a file into the local FTS5 knowledge base |
+| `ctk_search` | Multi-query retrieval; excerpts are centred on the match |
+| `ctk_fetch_and_index` | Fetch pages → strip markup → file them |
+| `ctk_purge` | Delete filed material (requires `confirm: true`) |
+| `ctk_stats` | Savings ledger: refusals, sandbox bytes, filed bytes, call counts |
+| `ctk_doctor` | Self-check: interpreters really start, scratch dir writable, knowledge round-trip |
+| `ctk_context_report` | This conversation's context occupancy and composition |
+
+## Install
+
+From npm (recommended):
+
+```bash
+dsh plugin --profile desktop add dsh-context-toolkit
+```
+
+From GitHub:
+
+```bash
+dsh plugin --profile desktop add github:chimneyQ/dsh-context-toolkit
+```
+
+From a local checkout:
+
+```bash
+dsh plugin --profile desktop add D:\path\to\dsh-context-toolkit
+```
+
+Confirm `dsh-context-toolkit` appears in `dsh.profile.bundles` inside `<DSH_HOME>/profiles/desktop/package.json`.
+
+Remove:
+
+```bash
+dsh plugin --profile desktop remove dsh-context-toolkit
+```
+
+## Use it well
+
+**Reach for `ctk_*` first** whenever the work is analysis, counting, filtering or summarising — reading that output into the conversation is the exact problem this bundle exists to solve.
+
+```js
+// How many .log files, and how big in total?
+await ctk_execute({
+  language: 'javascript',
+  code: `
+    const fs = require('fs');
+    const dir = process.argv[2];
+    let n = 0, bytes = 0;
+    for (const f of fs.readdirSync(dir)) {
+      if (!f.endsWith('.log')) continue;
+      n++; bytes += fs.statSync(dir + '/' + f).size;
+    }
+    console.log(n + ' files, ' + bytes + ' bytes');
+  `
+});
+```
+
+File long material once, then pull sections:
+
+```js
+await ctk_index({ path: 'D:/specs/api.md' });          // the full text stays in the store
+await ctk_search({ queries: ['rate limit', 'auth'] });  // only the relevant excerpts come back
+```
+
+## Configuration
+
+| Key | Default | Meaning |
+|---|---|---|
+| `routing` | `true` | Master switch for the routing gate |
+| `denyCurlWget` | `true` | Block curl / wget outright |
+| `bashNudgeMinCommandBytes` | `4096` | Nudge threshold for long commands (0 disables) |
+| `maxReadBytesBeforeAsk` | `51200` | Nudge threshold for whole-file reads (0 disables) |
+| `trustedReadBasenames` | `package.json` etc. | Filenames exempt from the read nudge |
+| `compressNudgeTokens` | `120000` | Occupancy warning threshold (tokens) |
+| `searchLimit` | `5` | Excerpts per query in `ctk_search` |
+| `snippetChars` | `900` | Character ceiling per excerpt |
+| `fetchMaxBytes` | `2000000` | Per-page fetch ceiling |
+| `storageDir` | empty | Knowledge-base root; empty = `<DSH_HOME>/context-toolkit` |
+| `tools.*` | see below | Per-tool switches |
+
+Tool switches: `tools.execute`, `tools.executeFile`, `tools.batchExecute`, `tools.index`, `tools.search`, `tools.fetchAndIndex`, `tools.purge`, `tools.stats`, `tools.contextReport`, `tools.doctor` — all on by default.
+
+## Verify
+
+The offline suites need no DSH runtime:
+
+```bash
+node smoke.mjs        # 52 checks: contract, runtime discovery, tools, gate, knowledge base, observability
+node test-client.mjs  # 27 checks: browser-half contract and bilingual dictionary parity
+node test-package.mjs # 18 checks: publish manifest and the zero-dependency constraint
+```
+
+## Known limits
+
+- **Outbound fetching depends on this machine's network.** If host names resolve to a loopback address, `ctk_fetch_and_index` fails with that reason spelled out — not a bare "fetch failed" — and `ctk_index` is the way to file local material instead.
+- **`ctk_execute` timeouts are hard kills**: the child is terminated and `timedOut` is reported.
+- **A single run captures at most 256 KB**; anything beyond is counted but not retained. The text handed back is additionally capped at 4000 characters, so even a 1 MB single-line output cannot enter the conversation whole.
+- **The knowledge base deduplicates by path**: filing the same path again replaces the earlier copy.
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,130 @@
+# 上下文工具箱（dsh-context-toolkit）
+
+> **简体中文** | [English](./README.md)
+
+一个给 DeepSeek Harness 用的插件：**让大块输出不进对话**。
+
+它的做法是把"原始字节"和"结论"分开——命令在子进程里跑、文件在沙箱里分析、网页与长材料归档进本地知识库，对话里只留下结论、片段和计数。另有一道路由门禁，在工具调用前挡掉那些注定会灌满对话的操作。
+
+**零第三方运行时依赖**：知识库用 Node 自带的 `node:sqlite`（含 FTS5），跑码用系统已有的解释器，安装后不需要再拉任何包。
+
+## 它有什么用
+
+| 问题 | 这个插件的做法 |
+|---|---|
+| 跑个命令，输出几千行，只想知道"有几个" | `ctk_execute` 在子进程里跑，只把结论带回来 |
+| 读大文件做统计，不想把全文塞进上下文 | `ctk_execute_file` 让文件留在沙箱里 |
+| 一次要问很多条命令 | `ctk_batch_execute` 一条调用跑完，逐条报状态 |
+| 网页/长文档看完就废，下次还要重看 | `ctk_index` 归档，`ctk_search` 按需取片段 |
+| `curl` / `wget` 直接把整页灌进对话 | 路由门禁硬拦，并给出替代方案 |
+| 不知道到底省了多少 | `ctk_stats` 报台账；设置页有实时占用面板 |
+
+## 工具
+
+| 工具 | 用途 |
+|---|---|
+| `ctk_execute` | 在沙箱子进程里跑代码（javascript / esm / typescript / shell），只回结论 |
+| `ctk_execute_file` | 对某个文件跑代码做统计或抽取，文件原文不出沙箱 |
+| `ctk_batch_execute` | 一次跑多条命令，逐条状态，输出只有结论 |
+| `ctk_index` | 把文本或文件存进本地 FTS5 知识库 |
+| `ctk_search` | 多查询检索知识库，返回围绕命中词的片段 |
+| `ctk_fetch_and_index` | 抓网页 → 去标签转文本 → 直接入库 |
+| `ctk_purge` | 删除已归档内容（必须 `confirm: true`） |
+| `ctk_stats` | 节约台账：拦截次数、沙箱保留字节、归档字节、调用计数 |
+| `ctk_doctor` | 自检：解释器能否真启动、临时目录可写、知识库能否往返 |
+| `ctk_context_report` | 当前会话的上下文占用与构成 |
+
+## 安装
+
+从 npm 安装（推荐）：
+
+```bash
+dsh plugin --profile desktop add dsh-context-toolkit
+```
+
+从 GitHub 安装：
+
+```bash
+dsh plugin --profile desktop add github:chimneyQ/dsh-context-toolkit
+```
+
+本地 checkout 时可直接指定目录：
+
+```bash
+dsh plugin --profile desktop add D:\path\to\dsh-context-toolkit
+```
+
+装完确认 `<DSH_HOME>/profiles/desktop/package.json` 的 `dsh.profile.bundles` 里出现 `dsh-context-toolkit`。
+
+卸载：
+
+```bash
+dsh plugin --profile desktop remove dsh-context-toolkit
+```
+
+## 怎么用更划算
+
+**默认就该走 `ctk_*`**。尤其是要分析、计数、过滤、看摘要的场合——直接把输出读进对话是这套插件要解决的原始问题。
+
+```js
+// 想知道一个大目录里有多少 .log 文件、总共多大
+await ctk_execute({
+  language: 'javascript',
+  code: `
+    const fs = require('fs');
+    const dir = process.argv[2];
+    let n = 0, bytes = 0;
+    for (const f of fs.readdirSync(dir)) {
+      if (!f.endsWith('.log')) continue;
+      n++; bytes += fs.statSync(dir + '/' + f).size;
+    }
+    console.log(n + ' files, ' + bytes + ' bytes');
+  `
+});
+```
+
+长材料先归档，之后按需取：
+
+```js
+await ctk_index({ path: 'D:/specs/api.md' });          // 全文留在库里
+await ctk_search({ queries: ['rate limit', 'auth'] });  // 只取相关片段
+```
+
+## 配置
+
+| 键 | 默认 | 含义 |
+|---|---|---|
+| `routing` | `true` | 路由门禁总开关 |
+| `denyCurlWget` | `true` | 硬拦 curl / wget |
+| `bashNudgeMinCommandBytes` | `4096` | 超长命令的引导阈值（0 = 关闭） |
+| `maxReadBytesBeforeAsk` | `51200` | 大文件整读的引导阈值（0 = 关闭） |
+| `trustedReadBasenames` | `package.json` 等 | 不受整读门禁限制的文件名 |
+| `compressNudgeTokens` | `120000` | 占用提示阈值（tokens） |
+| `searchLimit` | `5` | `ctk_search` 每次查询的片段数上限 |
+| `snippetChars` | `900` | 每个片段的字符上限 |
+| `fetchMaxBytes` | `2000000` | 单页抓取上限 |
+| `storageDir` | 空 | 知识库根目录，空 = `<DSH_HOME>/context-toolkit` |
+| `tools.*` | 见下 | 逐个工具的开关 |
+
+工具开关：`tools.execute`、`tools.executeFile`、`tools.batchExecute`、`tools.index`、`tools.search`、`tools.fetchAndIndex`、`tools.purge`、`tools.stats`、`tools.contextReport`、`tools.doctor`，默认全部开启。
+
+## 校验
+
+离线套件不依赖 DSH 运行时：
+
+```bash
+node smoke.mjs        # 52 项：契约、运行时探测、三工具、门禁、知识库、观测
+node test-client.mjs  # 27 项：浏览器半体契约与双语字典一致性
+node test-package.mjs # 18 项：发布清单与零依赖约束
+```
+
+## 已知边界
+
+- **出站抓取受本机网络影响**：若本机把域名解析到回环地址，`ctk_fetch_and_index` 会失败并明确说明原因（而不是只报 "fetch failed"）；此时改用 `ctk_index` 归档本地材料。
+- **`ctk_execute` 的超时是硬杀**：超时会终止子进程并把 `timedOut` 标出来。
+- **单次捕获上限 256 KB**，超出部分只计数不保留；回给对话的文本另有 4000 字符硬帽，因此 1 MB 的单行输出也不会整段进入上下文。
+- **知识库按路径去重**：同一路径再次归档是替换，不是追加。
+
+## 许可
+
+MIT

package/client.js

@@ -0,0 +1,334 @@
+// dsh-context-toolkit — browser half: the settings page and the occupancy panel.
+//
+// The harness module loader expects exactly one __ModuleLoader__.load() with an id
+// and a factory. The server half renders nothing; every field staged here must
+// exist in the plugin's Config, and the panel reads the plugin's own HTTP route so
+// it keeps working while the host has not served the settings namespace.
+window.__ModuleLoader__.load({
+  id: "dsh-context-toolkit",
+  factory: (require) => {
+    var module = { exports: {} };
+    var exports = module.exports;
+    Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+    let React = require("react");
+    let jsxRuntime = require("react/jsx-runtime");
+    let P = require("@deepseek-ai/dsh-client-ui-primitives");
+    let jsx = jsxRuntime.jsx;
+    let jsxs = jsxRuntime.jsxs;
+
+    //#region locales
+    const zh = {"title":"上下文工具箱","description":"在沙箱里跑代码、把大块材料归档成可检索的本地知识库、并挡住会灌满对话的抓取与整读。附一张实时上下文占用面板。","hint":"下列开关即时生效，无需重启：门禁在每次工具调用前读取。","routing":"路由门禁","routingHint":"总开关。开启后，每次工具调用执行前都会经过门禁检查。","denyCurlWget":"硬拦 curl / wget","denyCurlWgetHint":"这两个工具的设计就是把整页内容塞进对话；拦掉，改用 ctk_fetch_and_index。","bashNudgeMinCommandBytes":"长命令引导阈值（字节）","bashNudgeMinCommandBytesHint":"命令超过这个长度时提示改用 ctk_batch_execute。填 0 表示不提示。","maxReadBytesBeforeAsk":"大文件整读引导阈值（字节）","maxReadBytesBeforeAskHint":"整读超过这个大小的文件时提示改用 ctk_execute_file。填 0 表示不提示。","trustedReadBasenames":"不受整读门禁限制的文件名","trustedReadBasenamesHint":"逗号分隔；这些文件即使很大也允许整读。","compressNudgeTokens":"占用提示阈值（tokens）","compressNudgeTokensHint":"表面占用达到此值时，占用报告给出压缩建议。填 0 表示不提示。","searchLimit":"检索返回条数上限","searchLimitHint":"ctk_search 每次查询返回的片段数上限。","snippetChars":"片段最大字符数","snippetCharsHint":"ctk_search 每个片段返回的字符上限，超出部分省略。","fetchMaxBytes":"单页抓取上限（字节）","fetchMaxBytesHint":"ctk_fetch_and_index 抓取单页的最大字节数，超出部分丢弃。","storageDir":"知识库根目录","storageDirHint":"留空 = <DSH_HOME>/context-toolkit。","toolsTitle":"工具开关","toolsHint":"逐个启用或停用 ctk_* 工具。","overridden":"已覆盖","reset":"恢复默认","readOnly":"本部署的设置为只读。","unavailable":"该插件当前未加载，暂时无法配置。","save":"保存","saving":"保存中…","saveFailed":"本部署没有接受这些值，已保留供你修改。","invalidNumber":"请填数字；留空表示使用默认值。","note":"门禁开关即时生效；工具开关改动后建议重开页面确认。","ctxTitle":"上下文情况","ctxLoading":"正在读取…","ctxReload":"刷新","ctxFailed":"读取失败：","ctxNoSession":"本会话暂无可测量的投影。","ctxStale":"以下为最近一次实测快照（{time}）：网页请求没有会话边界，实时值请在对话中调用 ctk_context_report。","ctxTotal":"总压力 {n} tokens","ctxSurface":"表面占用 {n} tokens","ctxBudget":"提示阈值 {n} tokens","ctxOver":"已超过提示阈值，建议把大块输出改走 ctk_execute / ctk_index。","ctxUnder":"低于提示阈值，暂不需要干预。","ctxSystem":"系统提示","ctxTools":"工具 schema","ctxMessages":"会话消息","ctxEstimated":"（估算）","ctxNodes":"占用大头（前 {n} 项）","ctxLedger":"本插件节约台账","ctxLedgerLine":"门禁已拦截 {n} 次，约 {bytes} 字节未进入上下文；沙箱保留 {sandbox} 字节；已注册 {tools} 个 ctk_* 工具。","ctxKnowledge":"知识库：{docs} 文档 / {chunks} 片段（{bytes} 字节）","ctxStorage":"知识库位置：{path}","tools.execute":"ctk_execute（在沙箱里跑代码，只把结论带回来）","tools.executeHint":"用于「只想要结论、不想让原始输出占满上下文」的分析型任务。","tools.executeFile":"ctk_execute_file（对某个文件跑代码，只回结论）","tools.executeFileHint":"适合读大文件后做统计或抽取，文件原文留在沙箱里。","tools.batchExecute":"ctk_batch_execute（一次跑多条命令，逐条状态）","tools.batchExecuteHint":"多条命令一次调用，只有结论回来。","tools.index":"ctk_index（把大块材料存进本地知识库）","tools.indexHint":"把长文档、日志、规范归档，之后用 ctk_search 按需取用。","tools.search":"ctk_search（按需检索知识库，取片段而非整份）","tools.searchHint":"知识库里已有的内容优先用它检索，不要整份读进来。","tools.fetchAndIndex":"ctk_fetch_and_index（抓网页并直接并入索引）","tools.fetchAndIndexHint":"抓整页网页又不让它淹没对话时用；curl/wget 会被门禁拦掉。","tools.purge":"ctk_purge（删除已索引内容，不可恢复）","tools.purgeHint":"清理知识库用；会永久删除，调用必须带 confirm:true。","tools.stats":"ctk_stats（节约台账与知识库用量）","tools.statsHint":"想知道这个插件省了多少、归档了多少时看它。","tools.doctor":"ctk_doctor（自检：运行时、临时目录、知识库往返）","tools.doctorHint":"出现异常（子进程跑不起来、索引失败）时先跑它定位。","tools.contextReport":"ctk_context_report（会话上下文占用报告）","tools.contextReportHint":"让模型可以主动查询本会话的上下文占用与构成。","restart":"需重启"};
+    const en = {"title":"Context Toolkit","description":"Run code in a sandbox, file large material into a local searchable knowledge base, and block the fetches and whole-file reads that flood a conversation. Ships a live context-occupancy panel.","hint":"These switches apply immediately, no restart: the gate is read before every tool call.","routing":"Routing gate","routingHint":"Master switch. When on, every tool call passes through the gate before running.","denyCurlWget":"Block curl / wget","denyCurlWgetHint":"Both exist to paste whole responses into the conversation; blocked here, use ctk_fetch_and_index instead.","bashNudgeMinCommandBytes":"Long-command nudge (bytes)","bashNudgeMinCommandBytesHint":"Commands longer than this get a nudge toward ctk_batch_execute. 0 disables it.","maxReadBytesBeforeAsk":"Whole-file read nudge (bytes)","maxReadBytesBeforeAskHint":"Reading a file larger than this gets a nudge toward ctk_execute_file. 0 disables it.","trustedReadBasenames":"Filenames exempt from the read nudge","trustedReadBasenamesHint":"Comma separated; these may be read whole however large they are.","compressNudgeTokens":"Occupancy warning (tokens)","compressNudgeTokensHint":"At this surface occupancy the report suggests compaction. 0 disables it.","searchLimit":"Search result limit","searchLimitHint":"How many excerpts ctk_search returns per query.","snippetChars":"Excerpt size (chars)","snippetCharsHint":"Character ceiling on each excerpt from ctk_search.","fetchMaxBytes":"Per-page fetch ceiling (bytes)","fetchMaxBytesHint":"ctk_fetch_and_index keeps at most this many bytes of each page.","storageDir":"Knowledge-base root","storageDirHint":"Empty = <DSH_HOME>/context-toolkit.","toolsTitle":"Tool switches","toolsHint":"Enable or disable individual ctk_* tools.","overridden":"overridden","reset":"reset","readOnly":"This deployment is read-only.","unavailable":"The plugin is not loaded right now; it cannot be configured.","save":"Save","saving":"Saving…","saveFailed":"This deployment did not accept those values; they are kept for you to edit.","invalidNumber":"Numbers only; blank means the default.","note":"Gate switches apply immediately; reopen the page to confirm tool-switch changes.","ctxTitle":"Context occupancy","ctxLoading":"Reading…","ctxReload":"Refresh","ctxFailed":"Read failed: ","ctxNoSession":"No measurable projection in this session yet.","ctxStale":"Snapshot from the last real measurement ({time}): a page request has no session boundary; ask ctk_context_report in the conversation for a live reading.","ctxTotal":"{n} tokens total","ctxSurface":"{n} tokens on the surface","ctxBudget":"warning at {n} tokens","ctxOver":"Above the warning threshold — route bulk output through ctk_execute / ctk_index.","ctxUnder":"Below the warning threshold; nothing to do.","ctxSystem":"System prompt","ctxTools":"Tool schemas","ctxMessages":"Conversation","ctxEstimated":" (estimated)","ctxNodes":"Biggest contributors (top {n})","ctxLedger":"This plugin's ledger","ctxLedgerLine":"The gate blocked {n} calls, about {bytes} bytes kept out of context; the sandbox kept out {sandbox} bytes; {tools} ctk_* tools registered.","ctxKnowledge":"Knowledge base: {docs} documents / {chunks} chunks ({bytes} bytes)","ctxStorage":"Knowledge base at {path}","tools.execute":"ctk_execute (run code in the sandbox, return only the answer)","tools.executeHint":"For analysis where you want the conclusion, not the raw output.","tools.executeFile":"ctk_execute_file (run code over a file, return only the answer)","tools.executeFileHint":"Read a big file, compute over it, keep its bytes in the sandbox.","tools.batchExecute":"ctk_batch_execute (many commands in one call, per-command status)","tools.batchExecuteHint":"One call for many commands; only conclusions come back.","tools.index":"ctk_index (file large material into the local knowledge base)","tools.indexHint":"Archive long docs, logs or specs, then pull sections with ctk_search.","tools.search":"ctk_search (retrieve excerpts on demand, not the whole thing)","tools.searchHint":"Prefer this for material already in the knowledge base.","tools.fetchAndIndex":"ctk_fetch_and_index (fetch a page straight into the index)","tools.fetchAndIndexHint":"When a whole page would flood the conversation; curl/wget are gated.","tools.purge":"ctk_purge (delete indexed content — permanent)","tools.purgeHint":"Clears the knowledge base; permanent, so the call must confirm:true.","tools.stats":"ctk_stats (this plugin's savings ledger and knowledge usage)","tools.statsHint":"How much this plugin saved, and how much it filed.","tools.doctor":"ctk_doctor (self-check: runtimes, scratch dir, knowledge round-trip)","tools.doctorHint":"Run it first when a child process or indexing misbehaves.","tools.contextReport":"ctk_context_report (session context occupancy report)","tools.contextReportHint":"Lets the model ask for this session context occupancy and composition.","restart":"needs a restart"};
+    //#endregion
+
+    /** Fill the {name} holes in a translated sentence. */
+    function fill(text, values) {
+      return String(text).replace(/\{(\w+)\}/g, (whole, name) => {
+        const v = values[name];
+        return v === undefined ? whole : String(v);
+      });
+    }
+
+    //#region fields
+    const FIELDS = [{"field":"routing","kind":"bool"},{"field":"denyCurlWget","kind":"bool"},{"field":"bashNudgeMinCommandBytes","kind":"number"},{"field":"maxReadBytesBeforeAsk","kind":"number"},{"field":"compressNudgeTokens","kind":"number"},{"field":"searchLimit","kind":"number"},{"field":"snippetChars","kind":"number"},{"field":"fetchMaxBytes","kind":"number"},{"field":"trustedReadBasenames","kind":"text"},{"field":"storageDir","kind":"text"}];
+    const TOOL_FIELDS = ["execute","executeFile","batchExecute","index","search","fetchAndIndex","purge","stats","contextReport","doctor"];
+    const STATUS_PATH = "/_dsh/context-toolkit/status";
+    //#endregion
+
+    //#region styles
+    const rowStyle = { display: "flex", alignItems: "center", justifyContent: "space-between", gap: "12px", padding: "10px 0" };
+    const labelStyle = { display: "flex", flexDirection: "column", gap: "2px" };
+    const nameStyle = { fontSize: "13px" };
+    const hintStyle = { fontSize: "12px", opacity: 0.7, maxWidth: "46em" };
+    const controlsStyle = { display: "flex", alignItems: "center", gap: "8px", flex: "0 0 auto" };
+    const resetStyle = { background: "transparent", border: "none", color: "inherit", opacity: 0.75, cursor: "pointer", fontSize: "12px", textDecoration: "underline", padding: 0 };
+    const sectionStyle = { marginTop: "18px", borderTop: "1px solid rgba(128,128,128,0.25)", paddingTop: "14px" };
+    const sectionTitleStyle = { fontSize: "13px", fontWeight: 600 };
+    const sectionHintStyle = { fontSize: "12px", opacity: 0.7, margin: "4px 0 8px", maxWidth: "46em" };
+    const panelStyle = { marginTop: "18px", border: "1px solid rgba(128,128,128,0.25)", borderRadius: "6px", padding: "12px 14px" };
+    const panelHeadStyle = { display: "flex", alignItems: "center", justifyContent: "space-between", gap: "10px", marginBottom: "6px" };
+    const statRowStyle = { display: "flex", alignItems: "center", gap: "10px", padding: "4px 0", fontSize: "12px" };
+    const statNameStyle = { flex: "0 0 9em" };
+    const barWrapStyle = { flex: "1 1 auto", height: "10px", background: "rgba(128,128,128,0.18)", borderRadius: "5px", overflow: "hidden", display: "flex" };
+    const statValueStyle = { flex: "0 0 8em", textAlign: "right", fontFamily: "monospace", fontSize: "11px", opacity: 0.85 };
+    const monoStyle = { fontFamily: "monospace", fontSize: "11px", opacity: 0.8 };
+    const smallButtonStyle = { background: "transparent", border: "1px solid rgba(128,128,128,0.4)", borderRadius: "4px", color: "inherit", cursor: "pointer", fontSize: "11px", padding: "2px 8px" };
+    const OVER_COLOR = "#bf8700";
+    const OK_COLOR = "#2ea043";
+    const BAR_COLOR = { system: "#8250df", tools: "#0969da", messages: "#2ea043" };
+    //#endregion
+
+    //#region BoolField
+    function BoolField(props) {
+      const t = props.t;
+      const fieldState = props.state[props.spec.field] === undefined ? {} : props.state[props.spec.field];
+      return jsxs("div", {
+        style: rowStyle,
+        children: [
+          jsxs("div", { key: "label", style: labelStyle, children: [
+            jsx("div", { key: "name", style: nameStyle, children: t(props.spec.field) }),
+            jsx("div", { key: "hint", style: hintStyle, children: t(props.spec.field + "Hint") })
+          ]}),
+          jsxs("div", { key: "controls", style: controlsStyle, children: [
+            fieldState.overridden === true
+              ? jsx("button", { key: "reset", type: "button", style: resetStyle, disabled: !props.state.writable, onClick: () => props.onReset(), children: t("reset") })
+              : null,
+            jsx(P.Switch, {
+              key: "switch",
+              checked: fieldState.text === "true",
+              disabled: !props.state.writable,
+              label: t(props.spec.field),
+              onChange: (next) => props.onEdit(next ? "true" : "false")
+            })
+          ]})
+        ]
+      });
+    }
+    //#endregion
+
+    //#region panel
+    /**
+     * A live read of this session's context occupancy.
+     *
+     * It reloads on mount and on demand — a settings page has no business polling
+     * forever. When the route can only offer a snapshot it says so, with the time,
+     * so an old number is never mistaken for a live one.
+     */
+    function ContextPanel(props) {
+      const t = props.t;
+      const [state, setState] = React.useState({ status: "loading", data: null, error: "" });
+      const load = React.useCallback(() => {
+        setState({ status: "loading", data: null, error: "" });
+        Promise.resolve()
+          .then(() => fetch(STATUS_PATH, { headers: { accept: "application/json" } }))
+          .then((res) => (res.ok ? res.json() : Promise.reject(new Error("HTTP " + res.status))))
+          .then((data) => setState({ status: "ready", data: data, error: "" }))
+          .catch((error) => setState({ status: "failed", data: null, error: String((error && error.message) || error) }));
+      }, []);
+      React.useEffect(() => { load(); }, [load]);
+
+      const children = [];
+      children.push(jsxs("div", { key: "head", style: panelHeadStyle, children: [
+        jsx("div", { key: "title", style: sectionTitleStyle, children: t("ctxTitle") }),
+        jsx("button", { key: "reload", type: "button", style: smallButtonStyle, onClick: load, children: t("ctxReload") })
+      ]}));
+
+      if (state.status === "loading") {
+        children.push(jsx("div", { key: "loading", style: hintStyle, children: t("ctxLoading") }));
+        return jsx("div", { "data-context-panel": true, style: panelStyle, children: children });
+      }
+      if (state.status === "failed") {
+        children.push(jsx("div", { key: "failed", style: hintStyle, children: t("ctxFailed") + state.error }));
+        return jsx("div", { "data-context-panel": true, style: panelStyle, children: children });
+      }
+
+      const data = state.data || {};
+      const context = data.context || {};
+      const ledger = data.ledger || {};
+
+      if (context.ok !== true) {
+        children.push(jsx("div", { key: "none", style: hintStyle, children: context.why ? t("ctxFailed") + context.why : t("ctxNoSession") }));
+      } else {
+        if (context.stale === true) {
+          children.push(jsx("div", { key: "stale", style: Object.assign({}, hintStyle, { color: OVER_COLOR }), children: fill(t("ctxStale"), { time: new Date(Number(context.at) || Date.now()).toLocaleTimeString() }) }));
+        }
+        const total = Number(context.totalTokens) || 0;
+        const surface = Number(context.surfaceTokens) || 0;
+        const budget = Number(context.budget) || 0;
+        children.push(jsx("div", { key: "totals", style: monoStyle, children: fill(t("ctxTotal"), { n: total }) + "  ·  " + fill(t("ctxSurface"), { n: surface }) + "  ·  " + fill(t("ctxBudget"), { n: budget }) }));
+        const over = context.overBudget === true;
+        children.push(jsx("div", { key: "verdict", style: Object.assign({}, hintStyle, { color: over ? OVER_COLOR : OK_COLOR }), children: over ? t("ctxOver") : t("ctxUnder") }));
+        const bd = context.breakdown;
+        if (bd && bd.total > 0) {
+          const rows = [
+            { key: "system", tokens: bd.system, label: t("ctxSystem") },
+            { key: "tools", tokens: bd.tools, label: t("ctxTools") },
+            { key: "messages", tokens: bd.messages, label: t("ctxMessages") }
+          ];
+          for (const row of rows) {
+            const pct = Math.round((row.tokens / bd.total) * 100);
+            children.push(jsxs("div", { key: "bd-" + row.key, style: statRowStyle, children: [
+              jsx("span", { key: "n", style: statNameStyle, children: row.label + (bd.estimated ? t("ctxEstimated") : "") }),
+              jsx("span", { key: "bar", style: barWrapStyle, children: jsx("span", { style: { width: pct + "%", background: BAR_COLOR[row.key] || "#8b949e", display: "block" } }) }),
+              jsx("span", { key: "v", style: statValueStyle, children: row.tokens + " (" + pct + "%)" })
+            ]}));
+          }
+        }
+        if (Array.isArray(context.nodes) && context.nodes.length > 0) {
+          const shown = context.nodes.slice(0, 10);
+          children.push(jsx("div", { key: "nodes-title", style: Object.assign({}, hintStyle, { marginTop: "10px" }), children: fill(t("ctxNodes"), { n: shown.length }) }));
+          children.push(jsx("div", { key: "nodes", children: shown.map((node, index) => jsxs("div", { key: "node-" + index, style: statRowStyle, children: [
+            jsx("span", { key: "n", style: statNameStyle, children: "seq " + node.seq + (node.system ? " [system]" : "") }),
+            jsx("span", { key: "v", style: statValueStyle, children: node.tokens + " tokens" })
+          ]})) }));
+        }
+      }
+
+      children.push(jsx("div", { key: "ledger-title", style: Object.assign({}, hintStyle, { marginTop: "12px" }), children: t("ctxLedger") }));
+      children.push(jsx("div", { key: "ledger", style: hintStyle, children: fill(t("ctxLedgerLine"), { n: Number(ledger.denied) || 0, bytes: Number(ledger.deniedBytes) || 0, sandbox: Number(ledger.bytesSandboxed) || 0, tools: Number(ledger.registered) || 0 }) }));
+      if (data.knowledge && typeof data.knowledge.documents === "number") {
+        children.push(jsx("div", { key: "kb", style: monoStyle, children: fill(t("ctxKnowledge"), { docs: data.knowledge.documents, chunks: data.knowledge.chunks, bytes: data.knowledge.bytes }) }));
+      }
+      if (typeof data.storage === "string" && data.storage !== "") {
+        children.push(jsx("div", { key: "storage", style: monoStyle, children: fill(t("ctxStorage"), { path: data.storage }) }));
+      }
+      return jsx("div", { "data-context-panel": true, style: panelStyle, children: children });
+    }
+    //#endregion
+
+    //#region card
+    function ToolkitCard(props) {
+      const t = props.t;
+      if (props.view === "summary") return t("description");
+      const state = props.useToolkitCard((snapshot) => snapshot);
+      const children = [];
+      children.push(jsx("p", { key: "hint", style: Object.assign({}, hintStyle, { margin: "0 0 6px" }), children: t("hint") }));
+
+      for (const spec of FIELDS) {
+        const fieldState = state[spec.field] === undefined ? {} : state[spec.field];
+        if (spec.kind === "bool") {
+          children.push(jsx(BoolField, { key: spec.field, t: t, state: state, spec: spec,
+            onEdit: (text) => props.edit(spec.field, text), onReset: () => props.resetField(spec.field) }));
+          continue;
+        }
+        children.push(jsx(P.SettingsValueField, {
+          key: spec.field,
+          id: "plugin-config-context-toolkit-" + spec.field,
+          label: t(spec.field),
+          hint: t(spec.field + "Hint"),
+          overriddenLabel: t("overridden"),
+          resetLabel: t("reset"),
+          invalidLabel: t("invalidNumber"),
+          numeric: spec.kind === "number",
+          disabled: !state.writable,
+          text: fieldState.text,
+          overridden: fieldState.overridden,
+          invalid: fieldState.invalid,
+          onEdit: (text) => props.edit(spec.field, text),
+          onReset: () => props.resetField(spec.field)
+        }));
+      }
+
+      children.push(jsxs("div", { key: "tools-head", style: sectionStyle, children: [
+        jsx("div", { key: "t", style: sectionTitleStyle, children: t("toolsTitle") }),
+        jsx("div", { key: "h", style: sectionHintStyle, children: t("toolsHint") })
+      ]}));
+      for (const name of TOOL_FIELDS) {
+        const field = "tools." + name;
+        children.push(jsx(BoolField, { key: field, t: t, state: state, spec: { field: field },
+          onEdit: (text) => props.edit(field, text), onReset: () => props.resetField(field) }));
+      }
+
+      // Rendered BESIDE the form, not inside it: the host's SettingsForm returns
+      // early — dropping every child — while the namespace is unserved, and the
+      // panel must survive exactly that state to be worth having.
+      const panel = jsx(ContextPanel, { key: "panel", t: t });
+      const note = jsx("p", { key: "note", style: Object.assign({}, hintStyle, { marginTop: "12px" }), children: t("note") });
+
+      return jsxs("div", { key: "context-toolkit-page", children: [
+        jsx(P.SettingsForm, {
+          key: "form",
+          labels: { unavailable: t("unavailable"), readOnly: t("readOnly"), saveFailed: t("saveFailed"), save: t("save"), saving: t("saving") },
+          state: state,
+          onSave: props.save,
+          onDiscard: props.discard,
+          children: children
+        }),
+        panel,
+        note
+      ]});
+    }
+    //#endregion
+
+    //#region controller
+    /** Dictionary namespace owned by this plugin. */
+    const NS = "settings.contextToolkit";
+    /** The plugin's own settings namespace (its bundle id). */
+    const CTX_MODE_NS = "dsh-context-toolkit";
+    const ToolkitCardController = class {
+      constructor(scope) {
+        const specs = [];
+        for (const spec of FIELDS) {
+          if (spec.kind === "number") specs.push(P.settingsNumberField(spec.field));
+          else if (spec.kind === "bool") specs.push({ field: spec.field, format: formatBoolean, parse: parseBoolean });
+          else specs.push({ field: spec.field, format: formatText, parse: parseText });
+        }
+        for (const name of TOOL_FIELDS) specs.push({ field: "tools." + name, format: formatBoolean, parse: parseBoolean });
+        this.form = new P.SettingsFormModel(scope, specs);
+        this.store = this.form.bind(() => this.projection());
+      }
+      projection() {
+        const snapshot = Object.assign({}, this.form.shell());
+        for (const spec of FIELDS) snapshot[spec.field] = this.form.field(spec.field);
+        for (const name of TOOL_FIELDS) snapshot["tools." + name] = this.form.field("tools." + name);
+        return snapshot;
+      }
+      inject() {
+        return Object.assign({ hooks: { toolkitCard: this.store } }, this.form.actions());
+      }
+      dispose() { this.form.dispose(); }
+    };
+
+    function formatBoolean(value) {
+      if (value === true) return "true";
+      if (value === false) return "false";
+      return "";
+    }
+    function parseBoolean(text) {
+      const trimmed = String(text).trim().toLowerCase();
+      if (trimmed === "") return { kind: "clear" };
+      if (trimmed === "true") return { kind: "set", value: true };
+      if (trimmed === "false") return { kind: "set", value: false };
+      return { kind: "invalid", message: "expected true or false" };
+    }
+    function formatText(value) {
+      if (typeof value === "string") return value;
+      if (Array.isArray(value)) return value.join(", ");
+      return "";
+    }
+    function parseText(text) {
+      const trimmed = String(text).trim();
+      if (trimmed === "") return { kind: "clear" };
+      return { kind: "set", value: trimmed };
+    }
+    //#endregion
+
+    //#region mount
+    /**
+     * Mount the settings page.
+     *
+     * Two host containers publish a slot this form can occupy:
+     *   - settings.section is the Settings shell navigation list;
+     *   - plugins.item is the Plugins panel card list, which renders the same
+     *     component as its card body.
+     *
+     * Registration is unconditional: gating it on the host having served our own
+     * namespace fails silently (no error, zero cells) and hides the entry, and the
+     * card already renders its own unavailable state when no form is served.
+     */
+    function apply(ctx) {
+      const t = ctx.locale.bind(NS);
+      ctx.effect(() => ctx.locale.register(NS, { zh: zh, en: en }), "context-toolkit: dictionaries");
+      const card = new ToolkitCardController(ctx.configForms.get(CTX_MODE_NS));
+      ctx.effect(() => () => { card.dispose(); }, "context-toolkit: form subscription");
+      const definition = (name, order) => ({
+        name: name,
+        id: "context-toolkit",
+        order: order,
+        label: () => t("title"),
+        locale: NS,
+        inject: () => card.inject()
+      });
+      ctx.slots.inject("settings.section", () => ctx.slots.register(definition("settings.section", 30), ToolkitCard));
+      ctx.slots.inject("plugins.item", () => ctx.slots.register(definition("plugins.item", 55), ToolkitCard));
+    }
+    /** Required services (cordis fiber inject). */
+    const inject = ["slots", "locale", "configForms"];
+    //#endregion
+
+    exports.NS = NS;
+    exports.apply = apply;
+    exports.inject = inject;
+    return module.exports;
+  }
+});

package/cordis.patch.yml

@@ -0,0 +1,14 @@
+# dsh-context-toolkit bundle patch
+#
+# Registers ctk_* tools natively through the harness tools service.
+# No child MCP process, no mcp__ prefix.
+#
+# Every value below is validated against the plugin's Config schema; the full
+# set of controls and their meaning is documented in README.md.
+- insert:
+    - id: dsh-context-toolkit
+      name: 'dsh-context-toolkit'
+      config:
+        routing: true
+        denyCurlWget: true
+        caPemPath: 'auto'