dsh-xray 0.6.0 → 0.7.1

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.6.x — static + runtime imaging, context-cost attribution, and a web panel.** 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.
 
 ---
 
@@ -82,6 +84,10 @@ 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
@@ -134,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.6.x — 静态 + 运行时成像、上下文成本归因、Web 面板。** 静态命令在 dsh 起不来时照样能用;`deps`/`health`/`cost`/`shadow` 和 agent 工具需要插件已挂载。
+> 静态命令在 dsh 起不来时照样能用;`deps`/`health`/`cost`/`shadow` 和 agent 工具需要插件已挂载。
 
 `dsh --dump-config` 只给你原始组合树,插件面板只给你平铺列表。它们都不回答:这个插件*为什么*在这、停用它会*连带瘫掉什么*、它在*悄悄消耗什么*。dsh-xray 回答这些。
 
@@ -95,6 +105,10 @@ orphan overrides (silently skipped) (1)
 
 在 `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)。
@@ -103,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,355 @@
+// 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:hover{background:var(--dsw-alias-interactive-bg-hover)}',
+      // active view: the host's own tab-active family (state-business-*) —
+      // visible in both themes, unlike brand-primary which resolves to
+      // near-white in dark mode (white-on-white active buttons).
+      '.xray-nav button.active{color:var(--dsw-alias-state-business-primary);background:var(--dsw-alias-state-business-tertiary);border-color:var(--dsw-alias-state-business-primary);font-weight:600}',
+      // min-height pads the short views (summary is 4 rows, deps dozens) so
+      // switching between them moves the layout as little as possible;
+      // .xray-stale dims outgoing content while the next payload is in flight.
+      '.xray-body{min-height:320px}',
+      '.xray-stale{opacity:.45;transition:opacity .15s;pointer-events:none}',
+      '.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-state-error-primary,#f85149)}',
+      '.xray-ok{color:var(--dsw-alias-state-success-primary,#3fb950)}',
+      '.xray-muted{color:var(--dsw-alias-label-tertiary)}',
+      '.xray-bar{background:var(--dsw-alias-state-business-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. During the switch the previous view's content stays
+      // up (dimmed) and is replaced in one paint when the payload lands, so
+      // the layout changes once per click instead of collapsing to a
+      // one-line loading row and re-expanding.
+      const [state, setState] = react.useState({ phase: 'loading', for: 'summary' });
+      react.useEffect(() => {
+        let alive = true;
+        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]);
+      // Render whatever payload we HAVE (state.for), not the view the user
+      // just requested — the stale content keeps the scaffold stable while
+      // the fresh payload is in flight.
+      const settled = state.phase !== 'loading';
+      let body;
+      if (!settled) 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[state.for](state.data);
+        } catch (err) {
+          body = h(
+            'p',
+            { className: 'xray-warn' },
+            `render failed: ${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
+      }
+      const stale = settled && state.for !== view;
+      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,
+            ),
+          ),
+        ),
+        h('div', { className: stale ? 'xray-body xray-stale' : 'xray-body' }, 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

@@ -156,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-xray",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "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": {