dsh-xray 0.5.0 → 0.7.0

package/README.md

@@ -6,6 +6,8 @@
   <a href="https://www.npmjs.com/package/dsh-xray"><img src="https://img.shields.io/npm/v/dsh-xray?style=flat-square&color=00d4aa" alt="npm"></a>
   <a href="https://github.com/alloevil/dsh-xray/actions/workflows/check.yml"><img src="https://img.shields.io/github/actions/workflow/status/alloevil/dsh-xray/check.yml?style=flat-square&label=CI" alt="CI"></a>
   <a href="./LICENSE"><img src="https://img.shields.io/npm/l/dsh-xray?style=flat-square" alt="license"></a>
+  <a href="https://scorecard.dev/viewer/?uri=github.com/alloevil/dsh-xray"><img src="https://api.securityscorecards.dev/projects/github.com/alloevil/dsh-xray/badge?style=flat-square" alt="OpenSSF Scorecard"></a>
+  <a href="https://codecov.io/gh/alloevil/dsh-xray"><img src="https://img.shields.io/codecov/c/github/alloevil/dsh-xray?style=flat-square" alt="coverage"></a>
   <img src="https://img.shields.io/badge/language-JavaScript-f7df1e?style=flat-square&logo=javascript&logoColor=black" alt="JavaScript">
 </p>
 
@@ -27,7 +29,7 @@
 
 **dsh-xray does.**
 
-> **Status: 0.4.x — static + runtime imaging with context-cost attribution.** Static commands work even when dsh cannot boot; `deps`/`health`/`cost`/`shadow` and the agent tool need the plugin mounted.
+> Static commands work even when dsh cannot boot; `deps`/`health`/`cost`/`shadow` and the agent tool need the plugin mounted.
 
 ---
 
@@ -79,6 +81,13 @@ Per-plugin fiber lifecycle state, startup failures, transition history.
 ### 🤖 Agent Self-Introspection
 The `xray_composition` tool lets agents inspect their own capability set.
 
+### 🖥️ Web Panel
+Mounted in `dsh web`, the plugin serves a zero-dependency panel at **`/xray`** — summary, health, deps (with the disable-cascade table), cost, and shadow views, live from the running composition. JSON endpoints under `/xray/api/*` serve the same data.
+
+The package also ships a client half (`dsh.client` declaration + `exports["./client"]`): the host discovers it automatically and mounts an **X-ray tab beside Chat / Trajectory** in every session, rendering the same five views natively in the GUI with the host's design tokens. The standalone `/xray` page stays available as the degradation path — it only needs the web server, not the client-module pipeline it helps diagnose.
+
+![The /xray panel: deps view with the disable-cascade table](./assets/panel-deps.webp)
+
 What every request actually carries — prompt sections observed at assembly, blended with tool schemas:
 
 ```console
@@ -131,10 +140,31 @@ Mounted in the tree, dsh-xray registers an `xray_composition` tool (`view: summa
   <img src="./assets/section-install.svg" width="100%" alt="Install">
 </p>
 
+Two ways to use it — they're independent:
+
+**1. Static CLI only** (no install into dsh; works even when dsh cannot boot):
+
+```sh
+npx dsh-xray attribute        # requires Node >= 22
+```
+
+**2. Mount the plugin** (adds the runtime commands, the `/xray` panel, and the agent tool):
+
 ```sh
 dsh plugin --profile web add dsh-xray
+# bundle plugins take effect on the next start — restart dsh web
 ```
 
+Verify it took:
+
+```sh
+dsh --profile web --dump-config | grep dsh-xray   # row present in the composed tree
+npx dsh-xray health                               # reads the runtime snapshot
+# then open http://localhost:3080/xray for the live panel
+```
+
+Uninstall: `dsh plugin --profile web remove dsh-xray`.
+
 All commands take `--profile <name>` (default `web`) and `--json`.
 
 | Command | Behavior |

package/README.zh.md

@@ -1,16 +1,26 @@
-# dsh-xray
-
-[![npm](https://img.shields.io/npm/v/dsh-xray)](https://www.npmjs.com/package/dsh-xray)
-[![CI](https://github.com/alloevil/dsh-xray/actions/workflows/check.yml/badge.svg)](https://github.com/alloevil/dsh-xray/actions/workflows/check.yml)
-[![license](https://img.shields.io/npm/l/dsh-xray)](./LICENSE)
-
-给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 拍 X 光——看清到底加载了什么、为什么在那、以及它悄悄花掉了你什么。
+<p align="center">
+  <img src="./assets/hero.svg" width="100%" alt="dsh-xray — 给你的 DeepSeek Harness 拍 X 光">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/dsh-xray"><img src="https://img.shields.io/npm/v/dsh-xray?style=flat-square&color=00d4aa" alt="npm"></a>
+  <a href="https://github.com/alloevil/dsh-xray/actions/workflows/check.yml"><img src="https://img.shields.io/github/actions/workflow/status/alloevil/dsh-xray/check.yml?style=flat-square&label=CI" alt="CI"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/dsh-xray?style=flat-square" alt="license"></a>
+  <a href="https://scorecard.dev/viewer/?uri=github.com/alloevil/dsh-xray"><img src="https://api.securityscorecards.dev/projects/github.com/alloevil/dsh-xray/badge?style=flat-square" alt="OpenSSF Scorecard"></a>
+  <a href="https://codecov.io/gh/alloevil/dsh-xray"><img src="https://img.shields.io/codecov/c/github/alloevil/dsh-xray?style=flat-square" alt="coverage"></a>
+</p>
+
+<p align="center">
+  <strong>给 <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a> 拍 X 光</strong>——看清到底加载了什么、为什么在那、以及它悄悄花掉了你什么。
+</p>
+
+<p align="center">
+  <a href="./README.md">English</a>
+</p>
 
 ![dsh-xray 演示](./docs/demo.svg)
 
-[English](./README.md)
-
-> **状态:0.4.x — 静态 + 运行时成像,含上下文成本归因。** 静态命令在 dsh 起不来时照样能用;`deps`/`health`/`cost`/`shadow` 和 agent 工具需要插件已挂载。
+> 静态命令在 dsh 起不来时照样能用;`deps`/`health`/`cost`/`shadow` 和 agent 工具需要插件已挂载。
 
 `dsh --dump-config` 只给你原始组合树,插件面板只给你平铺列表。它们都不回答:这个插件*为什么*在这、停用它会*连带瘫掉什么*、它在*悄悄消耗什么*。dsh-xray 回答这些。
 
@@ -91,6 +101,14 @@ orphan overrides (silently skipped) (1)
 
 挂载进树后,dsh-xray 注册 `xray_composition` 工具(`view: summary | deps | health | cost | shadow`),agent 可以自答"我有哪些能力 / 哪个插件提供 X / 为什么 Y 不可用"。
 
+## Web 面板
+
+在 `dsh web` 中挂载后,插件在 **`/xray`** 提供零依赖面板——summary、health、deps(含停用级联表)、cost、shadow 五个视图,数据实时来自运行中的组合树;`/xray/api/*` 提供同源 JSON。
+
+包同时携带 client 半(`dsh.client` 声明 + `exports["./client"]`):宿主自动发现并在每个会话中挂载 **与 Chat / Trajectory 并列的 X-ray 标签页**,用宿主设计变量原生渲染同样五个视图。独立的 `/xray` 页面保留为降级通道——它只依赖 web 服务器,不依赖它所诊断的 client-module 加载链路。
+
+![/xray 面板:deps 视图与停用级联表](./assets/panel-deps.webp)
+
 ## 安全立场
 
 dsh-xray 只读不执行。patch 文件里的 loader `!!js` 表达式解析为不透明标记、绝不求值;CLI 从不执行插件代码(`audit` 是对源码文本的模式扫描);挂载的插件只写 `$DSH_HOME/xray/` 目录。详见 [SECURITY.md](./SECURITY.md)。
@@ -99,26 +117,47 @@ dsh-xray 只读不执行。patch 文件里的 loader `!!js` 表达式解析为
 
 对运行中组合树的诊断成像——与 [dsh-doctor](https://www.npmjs.com/package/dsh-doctor)(救援与恢复)互补。
 
-0.4.x 已交付:
+已交付:
 
 - **来源归因** — 每个活跃插件来自哪一层:内核 bundle / profile 依赖 / `cordis.patch.yml` insert / repository 源
 - **声明 vs 实际 diff** — 装了但没生效、卸了但残留 patch 行
 - **冲突检测** — 多个插件 patch 同一配置行时,谁静默赢了
-- **组合快照** — 把当前生效组合导出为 lockfile,异地一键复现
+- **组合快照** — 把当前生效组合导出为 lockfile;`--against` 对比漂移
 - **服务依赖图** — 每个服务谁提供、谁消费;停用 X 会级联影响什么(`deps`)
 - **运行时健康** — 每个插件的 fiber 生命周期状态、启动失败、状态迁移史(`health`)
 - **Agent 自省** — `xray_composition` 工具让 agent 检视自己的能力集
-
 - **能力审计** — 对 out-of-tree 插件的启发式静态扫描:网络外发、shell、文件系统、环境变量、动态求值(`audit`)
 - **服务重名检测** — 被多个插件同时提供的服务,及每插件工具/命令注册数(`shadow`)
 - **上下文成本** — prompt sections(观测自 system-prompt/assemble)+ 工具 schema 的估算 token 占用(`cost`)
+- **Web 面板** — `/xray` 五视图,零依赖零构建
 
 ## 安装
 
+两条使用路径,互相独立:
+
+**1. 只用静态 CLI**(不装进 dsh;dsh 起不来时也能用):
+
+```sh
+npx dsh-xray attribute        # 需要 Node >= 22
+```
+
+**2. 挂载插件**(解锁运行时命令、`/xray` 面板和 agent 工具):
+
 ```sh
 dsh plugin --profile web add dsh-xray
+# bundle 插件重启后生效——重启 dsh web
 ```
 
+验证装好了:
+
+```sh
+dsh --profile web --dump-config | grep dsh-xray   # 组合树里有这一行
+npx dsh-xray health                               # 能读到运行时快照
+# 然后打开 http://localhost:3080/xray 看实时面板
+```
+
+卸载:`dsh plugin --profile web remove dsh-xray`。
+
 ## 许可证
 
 MIT

package/assets/hero.svg

@@ -117,7 +117,7 @@
   <!-- Status badge -->
   <g transform="translate(450, 250)">
     <rect x="-100" y="-12" width="200" height="24" rx="12" fill="#00d4aa" opacity="0.1" stroke="#00d4aa" stroke-width="0.5" stroke-opacity="0.3"/>
-    <text x="0" y="4" text-anchor="middle" fill="#00d4aa" font-family="'SF Mono', monospace" font-size="11">v0.2.x · static + runtime</text>
+    <text x="0" y="4" text-anchor="middle" fill="#00d4aa" font-family="'SF Mono', monospace" font-size="11">static + runtime imaging</text>
   </g>
 
   <!-- Feature pills -->

package/bin/xray.js

@@ -172,6 +172,10 @@ function readRuntimeSnapshot() {
   return JSON.parse(fs.readFileSync(file, 'utf8'));
 }
 
+function panelHint(args) {
+  if (!args.json) console.log('\nlive panel: http://localhost:3080/xray');
+}
+
 function cmdDeps(args) {
   const snap = readRuntimeSnapshot();
   const result = model.serviceGraph(snap);
@@ -196,6 +200,7 @@ function cmdDeps(args) {
     console.log(`\n! ${result.unsatisfied.length} unsatisfied inject(s):`);
     for (const u of result.unsatisfied) console.log(`  ${u.plugin} wants ${u.service}`);
   }
+  panelHint(args);
 }
 
 function cmdHealth(args) {
@@ -214,6 +219,7 @@ function cmdHealth(args) {
     }
   }
   if (result.unhealthy.length) process.exitCode = 1;
+  panelHint(args);
 }
 
 function cmdCost(args) {
@@ -241,6 +247,7 @@ function cmdCost(args) {
       `${pad(t.name, 32)} ${pad(`~${t.tokens}`, 8)} ${pad(`${t.share}%`, 7)} ${bar(t.share)}`,
     );
   }
+  panelHint(args);
 }
 
 function cmdShadow(args) {
@@ -258,6 +265,7 @@ function cmdShadow(args) {
     }
   }
   if (result.services.length) process.exitCode = 1;
+  panelHint(args);
 }
 
 function cmdAudit(args) {

package/docs/discussion-post-draft.md

@@ -0,0 +1,88 @@
+# dsh-xray — 给你的 Harness 拍 X 光:组合树归因、依赖级联、上下文成本
+
+(草稿 — 建议发到 deepseek-ai/deepseek-harness 的 Discussions · Show and tell 分类。
+发布前把口吻改成你自己的;英文版附在下半部分,可以只发中文或双语。)
+
+---
+
+大家好,我做了一个诊断类插件 **dsh-xray**,想解决我自己折腾 profile 时反复遇到的三个问题:
+
+1. `--dump-config` 打出 130 行,但**哪一行是谁引入的**?patch 改了不生效时,是 id 写错被静默跳过,还是被后面的层覆盖了?
+2. 想停用一个插件,**会连带瘫掉什么**?
+3. 装了一堆插件后,**每次请求的上下文里到底塞了多少东西**?
+
+## 它长什么样
+
+```console
+$ npx dsh-xray attribute
+# 130 rows in profile "web"
+hmr                @deepseek-ai/dsh-base   ← patched by dsh-web-app [disabled]
+session-query      @deepseek-ai/dsh-base   ← patched by dsh-web-app
+
+$ npx dsh-xray deps
+# disable-cascade (transitive consumers of each provider):
+  SessionStore → AgentLoop, ApiProxyService, JsonlSessionPersistence, … (11 plugins)
+  ToolRuntime  → AgentLoop, ApiProxyService, DynamicCordisRunnerService, PlanModeController
+
+$ npx dsh-xray cost
+~1625 tokens: 1 tool schema(s) ~121 + 19 prompt section(s) ~1504
+app:web-surface   ~248   15.3%   ████████
+tool:goal         ~184   11.3%   ██████
+```
+
+## 全部命令
+
+| 命令 | 回答的问题 |
+|---|---|
+| `attribute` | 每一行由哪层引入(bundle / profile patch / home patch / repository 源),之后被谁改过 |
+| `diff` | 声明 vs 实际:抓出被 dsh 静默跳过的 orphan patch 行、装了没生效的插件 |
+| `conflicts` | 同一字段多个写者,谁赢了 |
+| `deps` / `health` | 服务依赖图 + 停用级联;每个插件的 fiber 生命周期状态 |
+| `cost` | prompt sections(观测自 system-prompt/assemble)+ tool schemas 的 token 估算 |
+| `shadow` / `audit` | 多提供者服务;out-of-tree 插件的敏感触点静态扫描(网络/shell/fs/env/eval) |
+| `snapshot --against` | 组合树 lockfile 导出与漂移对比 |
+
+另外:
+
+- **`/xray` Web 面板**(dsh web 里直接开,零依赖零构建)
+- **`xray_composition` agent 工具** — agent 可以自查"我有哪些能力/为什么 Y 不可用"
+- 静态命令(attribute/conflicts/diff/snapshot/audit)**在 dsh 起不来时照样能跑**
+- 与恢复类工具(dsh-doctor 等)互补:它们负责"救回来",xray 负责"看清楚"
+
+## 安全立场
+
+只读不执行:patch 里的 `!!js` 解析为不透明标记、绝不求值;audit 是源码文本扫描,不运行插件代码;挂载后只写 `$DSH_HOME/xray/`。
+
+## 安装
+
+```sh
+dsh plugin --profile web add dsh-xray   # 挂载(面板 + agent 工具 + 运行时快照)
+npx dsh-xray attribute                  # 或者不挂载,直接用静态 CLI
+```
+
+- GitHub: https://github.com/alloevil/dsh-xray (MIT, CI on Node 22/24, 39 tests)
+- npm: https://www.npmjs.com/package/dsh-xray (发布带 GitHub Actions provenance)
+
+欢迎 issue / PR,特别想听:你们排查 profile 问题时还缺什么视角?
+
+---
+
+## English version
+
+Hi all — I built **dsh-xray**, a diagnostics plugin for three questions I kept hitting while hacking on profiles:
+
+1. `--dump-config` prints 130 rows, but **which layer introduced each one**? When a patch "doesn't take", is the id wrong (silently skipped) or overridden by a later layer?
+2. If I disable plugin X, **what breaks transitively**?
+3. After installing a pile of plugins, **what does every request actually carry** in context?
+
+Commands: `attribute` (per-row layer attribution), `diff` (declared vs actual — catches orphan patch rows), `conflicts` (last-writer-wins chains), `deps`/`health` (service graph with disable-cascade, fiber lifecycle), `cost` (prompt sections + tool schemas, estimated tokens), `shadow`/`audit` (multi-provider services, capability scan), `snapshot --against` (composition lockfile + drift).
+
+Plus a zero-dependency web panel at `/xray`, and an `xray_composition` tool so agents can introspect their own capability set. Static commands work even when dsh cannot boot. Read-only by design: `!!js` never evaluated, `audit` never executes plugin code.
+
+```sh
+dsh plugin --profile web add dsh-xray
+```
+
+GitHub: https://github.com/alloevil/dsh-xray · npm: https://www.npmjs.com/package/dsh-xray
+
+Feedback welcome — what else do you wish you could see when a profile misbehaves?

package/lib/client.js

@@ -0,0 +1,340 @@
+// dsh-xray browser half. React panel registered as one conversation view tab
+// (`conversation.view` list slot, beside Chat / Trajectory); data comes from
+// the same-origin /xray/api/* endpoints the node half already serves, so this
+// layer stays a thin renderer — every computation lives in lib/model.js.
+//
+// Skeleton note: authored directly in ModuleLoader factory form (plain
+// React.createElement, no build step) to prove the wiring; migrate to
+// src/client/*.tsx + tsdown once the surface stabilizes.
+window.__ModuleLoader__.load({
+  id: 'dsh-xray',
+  factory: (require) => {
+    const module = { exports: {} };
+    const exports = module.exports;
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+    const react = require('react');
+    const h = react.createElement;
+
+    //#region styles (host design tokens; auto-claimed by client-modules)
+    const css = [
+      '.xray-panel{max-width:920px;margin:0 auto;padding:16px 20px;font-size:13px;color:var(--dsw-alias-label-primary)}',
+      '.xray-sub{color:var(--dsw-alias-label-tertiary);margin:0 0 14px;font-size:12px}',
+      '.xray-nav{display:flex;gap:6px;flex-wrap:wrap;margin-bottom:12px}',
+      '.xray-nav button{font:inherit;font-size:12px;color:var(--dsw-alias-label-secondary);background:var(--dsw-alias-bg-layer-3);border:1px solid var(--dsw-alias-border-l2);border-radius:6px;padding:4px 10px;cursor:pointer}',
+      '.xray-nav button.active{color:#fff;background:var(--dsw-alias-brand-primary);border-color:var(--dsw-alias-brand-primary)}',
+      '.xray-table{border-collapse:collapse;width:100%;margin-top:6px}',
+      '.xray-table th,.xray-table td{text-align:left;padding:4px 10px;border-bottom:1px solid var(--dsw-alias-border-l2);vertical-align:top}',
+      '.xray-table th{color:var(--dsw-alias-label-tertiary);font-weight:normal}',
+      '.xray-num{text-align:right}',
+      '.xray-warn{color:var(--dsw-alias-label-error)}',
+      '.xray-ok{color:var(--dsw-alias-label-success,#7ee787)}',
+      '.xray-muted{color:var(--dsw-alias-label-tertiary)}',
+      '.xray-bar{background:var(--dsw-alias-brand-primary);height:10px;border-radius:2px;display:inline-block}',
+      '.xray-h3{font-size:13px;font-weight:600;margin:14px 0 4px}',
+    ].join('\n');
+    if (
+      typeof document !== 'undefined' &&
+      document.querySelector('style[data-plugin-css="dsh-xray/panel"]') === null
+    ) {
+      const tag = document.createElement('style');
+      tag.dataset.plugin = 'dsh-xray';
+      tag.dataset.pluginCss = 'dsh-xray/panel';
+      tag.textContent = css;
+      document.head.appendChild(tag);
+    }
+    //#endregion
+
+    //#region tiny view primitives
+    const VIEWS = ['summary', 'health', 'deps', 'cost', 'shadow'];
+    function Table({ headers, rows }) {
+      return h(
+        'table',
+        { className: 'xray-table' },
+        h(
+          'thead',
+          null,
+          h(
+            'tr',
+            null,
+            headers.map((head, i) => h('th', { key: i }, head)),
+          ),
+        ),
+        h('tbody', null, rows),
+      );
+    }
+    function Bar({ share }) {
+      return h('span', { className: 'xray-bar', style: { width: `${Math.max(2, share * 2)}px` } });
+    }
+    function Row(key, cells) {
+      return h(
+        'tr',
+        { key },
+        cells.map((cell, i) =>
+          h(
+            'td',
+            { key: i, className: cell?.cls ? cell.cls : void 0 },
+            cell && cell.cls !== void 0 ? cell.text : cell,
+          ),
+        ),
+      );
+    }
+    //#endregion
+
+    //#region per-view renderers (mirror lib/panel.js, as components)
+    const renderers = {
+      summary: (d) =>
+        h(
+          react.Fragment,
+          null,
+          h(Table, {
+            headers: ['metric', 'value'],
+            rows: [
+              Row('p', ['plugins mounted', { cls: 'xray-num', text: String(d.plugins) }]),
+              Row('u', [
+                'unhealthy',
+                {
+                  cls: `xray-num ${d.unhealthy ? 'xray-warn' : 'xray-ok'}`,
+                  text: String(d.unhealthy),
+                },
+              ]),
+              Row('s', ['services', { cls: 'xray-num', text: String(d.services) }]),
+              Row('t', [
+                'context tokens (tools + sections)',
+                { cls: 'xray-num', text: `~${d.toolSchemaTokens}` },
+              ]),
+            ],
+          }),
+          h('p', { className: 'xray-muted', style: { marginTop: 12 } }, `captured ${d.capturedAt}`),
+        ),
+
+      health: (d) =>
+        h(
+          react.Fragment,
+          null,
+          h(
+            'p',
+            null,
+            h('span', { className: 'xray-ok' }, `${d.healthy.length} healthy`),
+            d.waiting.length ? ` · ${d.waiting.length} waiting` : null,
+            d.unhealthy.length
+              ? h(
+                  react.Fragment,
+                  null,
+                  ' · ',
+                  h('span', { className: 'xray-warn' }, `${d.unhealthy.length} unhealthy`),
+                )
+              : null,
+          ),
+          d.unhealthy.length
+            ? h(Table, {
+                headers: ['plugin', 'fiber', 'state', 'error'],
+                rows: d.unhealthy.flatMap((p) =>
+                  p.fibers.map((f) =>
+                    Row(`${p.name}/${f.uid}`, [
+                      p.name,
+                      { cls: 'xray-num', text: String(f.uid) },
+                      { cls: 'xray-warn', text: f.state },
+                      f.error ?? '',
+                    ]),
+                  ),
+                ),
+              })
+            : null,
+          d.waiting.length
+            ? h(Table, {
+                headers: ['waiting plugin', 'wants'],
+                rows: d.waiting.map((p) => Row(p.name, [p.name, p.inject.join(', ')])),
+              })
+            : null,
+        ),
+
+      deps: (d) =>
+        h(
+          react.Fragment,
+          null,
+          d.unsatisfied.length
+            ? h('p', { className: 'xray-warn' }, `${d.unsatisfied.length} unsatisfied inject(s)`)
+            : null,
+          Object.keys(d.cascade).length
+            ? h(
+                react.Fragment,
+                null,
+                h('div', { className: 'xray-h3' }, 'disable-cascade'),
+                h(Table, {
+                  headers: ['provider', 'affects'],
+                  rows: Object.entries(d.cascade).map(([provider, affected]) =>
+                    Row(provider, [provider, affected.join(', ')]),
+                  ),
+                }),
+              )
+            : null,
+          h('div', { className: 'xray-h3' }, 'services'),
+          h(Table, {
+            headers: ['service', 'provided by', 'consumed by'],
+            rows: Object.entries(d.services).map(([name, node]) =>
+              Row(name, [name, node.providers.join(', ') || '—', node.consumers.join(', ') || '—']),
+            ),
+          }),
+        ),
+
+      cost: (d) =>
+        h(
+          react.Fragment,
+          null,
+          h(
+            'p',
+            null,
+            `~${d.totalTokens} tokens: ${d.toolCount} tool schema(s) ~${d.toolTokens} + ${d.sectionCount} prompt section(s) ~${d.sectionTokens}`,
+          ),
+          d.sections.length
+            ? h(
+                react.Fragment,
+                null,
+                h('div', { className: 'xray-h3' }, 'prompt sections'),
+                h(Table, {
+                  headers: ['section', 'tokens', 'share', ''],
+                  rows: d.sections.map((s) =>
+                    Row(s.name, [
+                      s.name,
+                      { cls: 'xray-num', text: `~${s.tokens}` },
+                      { cls: 'xray-num', text: `${s.share}%` },
+                      h(Bar, { share: s.share }),
+                    ]),
+                  ),
+                }),
+              )
+            : h(
+                'p',
+                { className: 'xray-muted' },
+                'no prompt assembly observed yet — send one agent message first',
+              ),
+          h('div', { className: 'xray-h3' }, 'tool schemas'),
+          h(Table, {
+            headers: ['tool', 'tokens', 'share', ''],
+            rows: d.tools.map((t) =>
+              Row(t.name, [
+                t.name,
+                { cls: 'xray-num', text: `~${t.tokens}` },
+                { cls: 'xray-num', text: `${t.share}%` },
+                h(Bar, { share: t.share }),
+              ]),
+            ),
+          }),
+        ),
+
+      shadow: (d) =>
+        h(
+          react.Fragment,
+          null,
+          d.services.length
+            ? h(Table, {
+                headers: ['service', 'providers'],
+                rows: d.services.map((s) =>
+                  Row(s.service, [
+                    s.service,
+                    { cls: 'xray-warn', text: s.providers.join(' AND ') },
+                  ]),
+                ),
+              })
+            : h('p', { className: 'xray-ok' }, 'no service is provided by more than one plugin'),
+          d.registrars.length
+            ? h(
+                react.Fragment,
+                null,
+                h('div', { className: 'xray-h3' }, 'registrars'),
+                h(Table, {
+                  headers: ['plugin', 'registrations'],
+                  rows: d.registrars.map((r) =>
+                    Row(r.plugin, [r.plugin, { cls: 'xray-num', text: String(r.registrations) }]),
+                  ),
+                }),
+              )
+            : null,
+        ),
+    };
+    //#endregion
+
+    //#region panel (one conversation.view tab)
+    function XrayPanel() {
+      const [view, setView] = react.useState('summary');
+      // `for` stamps which view the payload belongs to: a click flips `view`
+      // synchronously while `state` still carries the previous view's data —
+      // rendering that mismatch with the new renderer throws and unmounts
+      // the whole tab. Mismatch renders as loading instead.
+      const [state, setState] = react.useState({ phase: 'loading', for: 'summary' });
+      react.useEffect(() => {
+        let alive = true;
+        setState({ phase: 'loading', for: view });
+        fetch(`/xray/api/${view}`)
+          .then(async (res) => {
+            if (!res.ok) throw new Error(await res.text());
+            return res.json();
+          })
+          .then((data) => {
+            if (alive) setState({ phase: 'ready', for: view, data });
+          })
+          .catch((err) => {
+            if (alive)
+              setState({
+                phase: 'error',
+                for: view,
+                message: err instanceof Error ? err.message : String(err),
+              });
+          });
+        return () => {
+          alive = false;
+        };
+      }, [view]);
+      let body;
+      if (state.for !== view || state.phase === 'loading')
+        body = h('p', { className: 'xray-muted' }, `loading ${view}…`);
+      else if (state.phase === 'error') body = h('p', { className: 'xray-warn' }, state.message);
+      else {
+        // A diagnostic surface must never take itself down on one bad
+        // payload: render the failure, keep the tab and its nav alive.
+        try {
+          body = renderers[view](state.data);
+        } catch (err) {
+          body = h(
+            'p',
+            { className: 'xray-warn' },
+            `render failed: ${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
+      }
+      return h(
+        'div',
+        { className: 'xray-panel' },
+        h('p', { className: 'xray-sub' }, 'composition X-ray — live from this harness'),
+        h(
+          'nav',
+          { className: 'xray-nav' },
+          VIEWS.map((name) =>
+            h(
+              'button',
+              { key: name, className: name === view ? 'active' : '', onClick: () => setView(name) },
+              name,
+            ),
+          ),
+        ),
+        body,
+      );
+    }
+    //#endregion
+
+    const inject = ['slots'];
+    /** Mount the X-ray tab into the conversation view ring (beside Chat / Trajectory). */
+    function apply(ctx) {
+      ctx.slots.inject('conversation.view', () =>
+        ctx.slots.register(
+          { name: 'conversation.view', id: 'xray', order: 20, label: 'X-ray' },
+          XrayPanel,
+        ),
+      );
+    }
+
+    exports.apply = apply;
+    exports.inject = inject;
+    return module.exports;
+  },
+});

package/lib/index.js

@@ -91,6 +91,43 @@ function apply(ctx) {
     ];
   }, 'xray-runtime-snapshot');
 
+  // Web panel: mounts when the profile composes a webServer (dsh web).
+  // Headless profiles simply never activate this subplugin.
+  ctx.plugin({
+    name: 'dsh-xray-panel',
+    inject: ['webServer'],
+    apply: (wctx) => {
+      const { mountPanel } = require('./panel.js');
+      const freshSnap = () => {
+        const snap = snapshotRegistry(ctx);
+        snap.transitions = Object.fromEntries(transitions);
+        snap.promptAssembly = lastAssembly;
+        return snap;
+      };
+      wctx.effect(
+        () =>
+          mountPanel(wctx.webServer, {
+            summary: () => {
+              const snap = freshSnap();
+              return {
+                plugins: snap.plugins.length,
+                unhealthy: health(snap).unhealthy.length,
+                services: Object.keys(serviceGraph(snap).services).length,
+                toolSchemaTokens: contextCost(snap).totalTokens,
+                capturedAt: snap.capturedAt,
+              };
+            },
+            deps: () => serviceGraph(freshSnap()),
+            health: () => health(freshSnap()),
+            cost: () => contextCost(freshSnap()),
+            shadow: () => shadowing(freshSnap()),
+          }),
+        'xray-panel-routes',
+      );
+      logger.info('xray panel mounted at /xray');
+    },
+  });
+
   // Agent self-introspection tool: only when a tool registry exists
   // (headless/web both have one; keep it optional so xray mounts anywhere).
   ctx.plugin({
@@ -119,7 +156,8 @@ function apply(ctx) {
             'Introspect the live plugin composition of this harness: every mounted plugin, ' +
             'the services it requires (inject) and provides, its lifecycle state, and ' +
             'unhealthy plugins with their last transitions. Use to answer "what capabilities ' +
-            'do I have / what plugin provides X / why is Y unavailable".',
+            'do I have / what plugin provides X / why is Y unavailable". A human-browsable ' +
+            'panel with the same data is served at /xray on this harness.',
           parameters: {
             view: {
               type: 'string',

package/lib/panel.js

@@ -0,0 +1,213 @@
+// Self-contained web panel: one HTML page + JSON endpoints, mounted on the
+// host webServer. No client-module bundle, no React, no build step — the
+// model layer already computes everything; this only renders it.
+
+const PAGE = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>dsh-xray</title>
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; margin: 0; }
+  body { font: 13px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;
+         background: #0d1117; color: #e6edf3; padding: 24px; }
+  h1 { font-size: 16px; margin-bottom: 4px; }
+  .sub { color: #8b949e; margin-bottom: 20px; }
+  nav { display: flex; gap: 8px; margin-bottom: 16px; flex-wrap: wrap; }
+  nav button { background: #21262d; color: #e6edf3; border: 1px solid #30363d;
+               border-radius: 6px; padding: 5px 12px; cursor: pointer; font: inherit; }
+  nav button.active { background: #1f6feb; border-color: #1f6feb; }
+  table { border-collapse: collapse; width: 100%; margin-top: 8px; }
+  th, td { text-align: left; padding: 4px 10px; border-bottom: 1px solid #21262d; }
+  th { color: #8b949e; font-weight: normal; }
+  .num { text-align: right; }
+  .bar { background: #1f6feb; height: 10px; border-radius: 2px; display: inline-block; }
+  .warn { color: #f85149; }
+  .ok { color: #7ee787; }
+  .muted { color: #8b949e; }
+  #status { margin: 12px 0; color: #8b949e; }
+  .tag { background: #21262d; border-radius: 4px; padding: 1px 6px; margin-left: 6px; font-size: 11px; }
+</style>
+</head>
+<body>
+<h1>dsh-xray</h1>
+<div class="sub">composition X-ray — live from this harness</div>
+<nav id="nav"></nav>
+<div id="status"></div>
+<div id="content"></div>
+<script>
+const views = ['summary', 'health', 'deps', 'cost', 'shadow'];
+const esc = (s) => String(s ?? '').replace(/[&<>]/g, (c) => ({'&':'&amp;','<':'&lt;','>':'&gt;'}[c]));
+const nav = document.getElementById('nav');
+const content = document.getElementById('content');
+const status = document.getElementById('status');
+let active = 'summary';
+
+for (const v of views) {
+  const b = document.createElement('button');
+  b.textContent = v;
+  b.onclick = () => { active = v; render(); };
+  b.id = 'nav-' + v;
+  nav.appendChild(b);
+}
+
+function table(headers, rows) {
+  return '<table><tr>' + headers.map((h) => '<th>' + esc(h) + '</th>').join('') + '</tr>'
+    + rows.join('') + '</table>';
+}
+function bar(share) {
+  return '<span class="bar" style="width:' + Math.max(2, share * 2) + 'px"></span>';
+}
+
+const renderers = {
+  summary(d) {
+    return table(['metric', 'value'], [
+      '<tr><td>plugins mounted</td><td class="num">' + d.plugins + '</td></tr>',
+      '<tr><td>unhealthy</td><td class="num ' + (d.unhealthy ? 'warn' : 'ok') + '">' + d.unhealthy + '</td></tr>',
+      '<tr><td>services</td><td class="num">' + d.services + '</td></tr>',
+      '<tr><td>context tokens (tools + sections)</td><td class="num">~' + d.toolSchemaTokens + '</td></tr>',
+    ]) + '<p class="muted" style="margin-top:12px">captured ' + esc(d.capturedAt) + '</p>';
+  },
+  health(d) {
+    let html = '<p><span class="ok">' + d.healthy.length + ' healthy</span>'
+      + (d.waiting.length ? ' · ' + d.waiting.length + ' waiting' : '')
+      + (d.unhealthy.length ? ' · <span class="warn">' + d.unhealthy.length + ' unhealthy</span>' : '') + '</p>';
+    if (d.unhealthy.length) {
+      html += table(['plugin', 'fiber', 'state', 'error'], d.unhealthy.flatMap((p) =>
+        p.fibers.map((f) => '<tr><td>' + esc(p.name) + '</td><td class="num">' + f.uid
+          + '</td><td class="warn">' + esc(f.state) + '</td><td>' + esc(f.error ?? '') + '</td></tr>')));
+    }
+    if (d.waiting.length) {
+      html += table(['waiting plugin', 'wants'], d.waiting.map((p) =>
+        '<tr><td>' + esc(p.name) + '</td><td>' + esc(p.inject.join(', ')) + '</td></tr>'));
+    }
+    return html;
+  },
+  deps(d) {
+    const services = Object.entries(d.services).map(([name, node]) =>
+      '<tr><td>' + esc(name) + '</td><td>' + esc(node.providers.join(', ') || '—')
+      + '</td><td>' + esc(node.consumers.join(', ') || '—') + '</td></tr>');
+    let html = table(['service', 'provided by', 'consumed by'], services);
+    const cascade = Object.entries(d.cascade);
+    if (cascade.length) {
+      html = '<h3 style="margin:8px 0">disable-cascade</h3>'
+        + table(['provider', 'affects'], cascade.map(([p, a]) =>
+          '<tr><td>' + esc(p) + '</td><td>' + esc(a.join(', ')) + '</td></tr>'))
+        + '<h3 style="margin:16px 0 8px">services</h3>' + html;
+    }
+    if (d.unsatisfied.length) {
+      html = '<p class="warn">' + d.unsatisfied.length + ' unsatisfied inject(s)</p>' + html;
+    }
+    return html;
+  },
+  cost(d) {
+    let html = '<p>~' + d.totalTokens + ' tokens: ' + d.toolCount + ' tool schema(s) ~' + d.toolTokens
+      + ' + ' + d.sectionCount + ' prompt section(s) ~' + d.sectionTokens + '</p>';
+    if (d.sections.length) {
+      html += '<h3 style="margin:12px 0 4px">prompt sections</h3>'
+        + table(['section', 'tokens', 'share', ''], d.sections.map((s) =>
+          '<tr><td>' + esc(s.name) + '</td><td class="num">~' + s.tokens + '</td><td class="num">'
+          + s.share + '%</td><td>' + bar(s.share) + '</td></tr>'));
+    } else {
+      html += '<p class="muted">no prompt assembly observed yet — send one agent message first</p>';
+    }
+    html += '<h3 style="margin:12px 0 4px">tool schemas</h3>'
+      + table(['tool', 'tokens', 'share', ''], d.tools.map((t) =>
+        '<tr><td>' + esc(t.name) + '</td><td class="num">~' + t.tokens + '</td><td class="num">'
+        + t.share + '%</td><td>' + bar(t.share) + '</td></tr>'));
+    return html;
+  },
+  shadow(d) {
+    let html = d.services.length
+      ? table(['service', 'providers'], d.services.map((s) =>
+          '<tr><td>' + esc(s.service) + '</td><td class="warn">' + esc(s.providers.join(' AND ')) + '</td></tr>'))
+      : '<p class="ok">no service is provided by more than one plugin</p>';
+    if (d.registrars.length) {
+      html += '<h3 style="margin:12px 0 4px">registrars</h3>'
+        + table(['plugin', 'registrations'], d.registrars.map((r) =>
+          '<tr><td>' + esc(r.plugin) + '</td><td class="num">' + r.registrations + '</td></tr>'));
+    }
+    return html;
+  },
+};
+
+async function render() {
+  for (const v of views) document.getElementById('nav-' + v).className = v === active ? 'active' : '';
+  status.textContent = 'loading ' + active + '…';
+  try {
+    const res = await fetch('/xray/api/' + active);
+    if (!res.ok) throw new Error(await res.text());
+    const data = await res.json();
+    content.innerHTML = renderers[active](data);
+    status.textContent = '';
+  } catch (err) {
+    status.innerHTML = '<span class="warn">' + esc(err.message) + '</span>';
+    content.innerHTML = '';
+  }
+}
+render();
+setInterval(() => { if (active === 'health' || active === 'summary') render(); }, 5000);
+</script>
+</body>
+</html>`;
+
+function sendJson(response, code, value) {
+  const body = JSON.stringify(value);
+  response.writeHead(code, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+  });
+  response.end(body);
+}
+
+/**
+ * Mount the panel routes. `views` supplies fresh data per request:
+ * { summary, deps, health, cost, shadow } — each a () => object.
+ * Returns the disposers webServer.register produced.
+ */
+function mountPanel(webServer, views) {
+  const disposers = [];
+  disposers.push(
+    webServer.register({
+      kind: 'exact',
+      path: '/xray',
+      handler: (request, response) => {
+        if (request.method !== 'GET') {
+          response.writeHead(405, { allow: 'GET' });
+          response.end();
+          return;
+        }
+        response.writeHead(200, {
+          'content-type': 'text/html; charset=utf-8',
+          'cache-control': 'no-store',
+        });
+        response.end(PAGE);
+      },
+    }),
+  );
+  for (const [name, compute] of Object.entries(views)) {
+    disposers.push(
+      webServer.register({
+        kind: 'exact',
+        path: `/xray/api/${name}`,
+        handler: (request, response) => {
+          if (request.method !== 'GET') {
+            response.writeHead(405, { allow: 'GET' });
+            response.end();
+            return;
+          }
+          try {
+            sendJson(response, 200, compute());
+          } catch (err) {
+            sendJson(response, 500, { error: err.message });
+          }
+        },
+      }),
+    );
+  }
+  return disposers;
+}
+
+module.exports = { mountPanel, PAGE };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-xray",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "X-ray for your DeepSeek Harness — see what's actually loaded, why, and what it costs you.",
   "repository": {
     "type": "git",
@@ -15,6 +15,7 @@
   },
   "exports": {
     ".": "./lib/index.js",
+    "./client": "./lib/client.js",
     "./package.json": "./package.json",
     "./cordis.patch.yml": "./cordis.patch.yml"
   },
@@ -56,6 +57,14 @@
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ]
     }
   },
   "peerDependencies": {