dsh-xray 0.4.1 → 0.6.0

package/README.md

@@ -27,7 +27,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.
+> **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.
 
 ---
 
@@ -79,6 +79,9 @@ 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.
+
 What every request actually carries — prompt sections observed at assembly, blended with tool schemas:
 
 ```console

package/README.zh.md

@@ -10,7 +10,7 @@
 
 [English](./README.md)
 
-> **状态:0.4.x — 静态 + 运行时成像,含上下文成本归因。** 静态命令在 dsh 起不来时照样能用;`deps`/`health`/`cost`/`shadow` 和 agent 工具需要插件已挂载。
+> **状态:0.6.x — 静态 + 运行时成像、上下文成本归因、Web 面板。** 静态命令在 dsh 起不来时照样能用;`deps`/`health`/`cost`/`shadow` 和 agent 工具需要插件已挂载。
 
 `dsh --dump-config` 只给你原始组合树,插件面板只给你平铺列表。它们都不回答:这个插件*为什么*在这、停用它会*连带瘫掉什么*、它在*悄悄消耗什么*。dsh-xray 回答这些。
 
@@ -91,6 +91,10 @@ 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。
+
 ## 安全立场
 
 dsh-xray 只读不执行。patch 文件里的 loader `!!js` 表达式解析为不透明标记、绝不求值;CLI 从不执行插件代码(`audit` 是对源码文本的模式扫描);挂载的插件只写 `$DSH_HOME/xray/` 目录。详见 [SECURITY.md](./SECURITY.md)。

package/bin/xray.js

@@ -12,6 +12,7 @@ function parseArgs(argv) {
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--profile' || a === '-p') args.profile = argv[++i];
+    else if (a === '--against') args.against = argv[++i];
     else if (a === '--json') args.json = true;
     else args._.push(a);
   }
@@ -118,7 +119,44 @@ function cmdDiff(args) {
 function cmdSnapshot(args) {
   const data = collectStatic(args.profile);
   const { dump } = tryDump(args.profile);
-  console.log(JSON.stringify(model.snapshot(data, dump), null, 2));
+  const current = model.snapshot(data, dump);
+  const againstFile = args.against;
+  if (!againstFile) return console.log(JSON.stringify(current, null, 2));
+
+  const fs = require('node:fs');
+  const { compareSnapshots } = require('../lib/compare.js');
+  const saved = JSON.parse(fs.readFileSync(againstFile, 'utf8'));
+  const result = compareSnapshots(saved, current);
+  if (args.json) return console.log(JSON.stringify(result, null, 2));
+
+  if (result.identical) {
+    return console.log(`composition identical to snapshot from ${result.savedAt}`);
+  }
+  console.log(`composition drifted from snapshot (${result.savedAt}):`);
+  for (const b of result.changes.bundles) {
+    if (b.change === 'added') console.log(`  bundle + ${b.name}@${b.version}`);
+    else if (b.change === 'removed') console.log(`  bundle - ${b.name}`);
+    else
+      console.log(
+        `  bundle ~ ${b.name}: ${b.change} ${b.from.version ?? b.from.patchHash} → ${b.to.version ?? b.to.patchHash}`,
+      );
+  }
+  for (const p of result.changes.patches) {
+    console.log(
+      `  patch ${p.change === 'added' ? '+' : p.change === 'removed' ? '-' : '~'} ${p.kind}${p.change === 'content' ? `: ${p.from} → ${p.to}` : ''}`,
+    );
+  }
+  for (const p of result.changes.packages) {
+    if (p.change === 'added') console.log(`  package + ${p.name}@${p.version}`);
+    else if (p.change === 'removed') console.log(`  package - ${p.name}`);
+    else console.log(`  package ~ ${p.name}: ${p.from} → ${p.to}`);
+  }
+  if (result.changes.composed) {
+    console.log(
+      `  composed tree hash: ${result.changes.composed.from} → ${result.changes.composed.to}`,
+    );
+  }
+  process.exitCode = 1;
 }
 
 function readRuntimeSnapshot() {
@@ -266,7 +304,7 @@ Commands:
   attribute   which layer introduced each row, and who patched it since
   conflicts   rows whose fields have multiple writers, and who wins
   diff        declared (static layers) vs actual (dump-config) tree
-  snapshot    content-addressed lockfile of the effective composition
+  snapshot    content-addressed lockfile; --against <file> diffs a saved one
   deps        service dependency graph from the live runtime snapshot
   health      plugin lifecycle health from the live runtime snapshot
   cost        estimated context-token cost of each model-facing tool schema

package/lib/collect/static.js

@@ -109,6 +109,41 @@ function collectStatic(profileName) {
     });
   }
 
+  // Repository plugins: the third-party plugin-console mechanism mounts
+  // `.dsh-plugin` directories under the harness home; each carries its own
+  // patch file. Not dsh core — absence is normal.
+  const repoRoot = path.join(home, '.dsh-plugin');
+  if (fs.existsSync(repoRoot)) {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(repoRoot, { withFileTypes: true }).filter((e) => e.isDirectory());
+    } catch {
+      /* unreadable repository root: skip */
+    }
+    for (const e of entries) {
+      const dir = path.join(repoRoot, e.name);
+      const pkg = readJson(path.join(dir, 'package.json'));
+      const rel = pkg?.dsh?.bundle?.patch;
+      if (!rel) continue;
+      const file = path.join(dir, rel);
+      if (!fs.existsSync(file)) {
+        warnings.push(`repository plugin ${e.name}: patch missing (${rel})`);
+        continue;
+      }
+      const text = fs.readFileSync(file, 'utf8');
+      const { value, error } = parseYaml(text, file);
+      if (error) warnings.push(error);
+      layers.push({
+        kind: 'repository',
+        name: pkg.name ?? e.name,
+        version: pkg.version ?? null,
+        file,
+        entries: Array.isArray(value) ? value : [],
+        text,
+      });
+    }
+  }
+
   // Out-of-tree plugins: profile dependencies carrying a `dsh` field.
   const packages = [];
   for (const dep of Object.keys(manifest.dependencies ?? {})) {

package/lib/compare.js

@@ -0,0 +1,74 @@
+// Snapshot comparison: current composition vs a saved lockfile.
+
+function indexBy(list, key) {
+  const m = new Map();
+  for (const item of list ?? []) m.set(item[key], item);
+  return m;
+}
+
+/**
+ * F9b: compare a live snapshot against a saved one (`xray snapshot > lock.json`).
+ * Returns per-category changes; `identical` is true only when everything matches.
+ */
+function compareSnapshots(saved, current) {
+  if (saved?.schema !== 'dsh-xray/snapshot@1') {
+    throw new Error(`not a dsh-xray snapshot: schema=${saved?.schema ?? 'missing'}`);
+  }
+  const changes = { bundles: [], patches: [], packages: [], composed: null };
+
+  const savedBundles = indexBy(saved.bundles, 'name');
+  const currentBundles = indexBy(current.bundles, 'name');
+  for (const [name, b] of currentBundles) {
+    const old = savedBundles.get(name);
+    if (!old) changes.bundles.push({ name, change: 'added', version: b.version });
+    else if (old.version !== b.version || old.patchHash !== b.patchHash) {
+      changes.bundles.push({
+        name,
+        change: old.version !== b.version ? 'version' : 'patch-content',
+        from: { version: old.version, patchHash: old.patchHash },
+        to: { version: b.version, patchHash: b.patchHash },
+      });
+    }
+  }
+  for (const name of savedBundles.keys()) {
+    if (!currentBundles.has(name)) changes.bundles.push({ name, change: 'removed' });
+  }
+
+  const savedPatches = indexBy(saved.patches, 'kind');
+  const currentPatches = indexBy(current.patches, 'kind');
+  for (const [kind, p] of currentPatches) {
+    const old = savedPatches.get(kind);
+    if (!old) changes.patches.push({ kind, change: 'added' });
+    else if (old.hash !== p.hash)
+      changes.patches.push({ kind, change: 'content', from: old.hash, to: p.hash });
+  }
+  for (const kind of savedPatches.keys()) {
+    if (!currentPatches.has(kind)) changes.patches.push({ kind, change: 'removed' });
+  }
+
+  const savedPkgs = indexBy(saved.packages, 'name');
+  const currentPkgs = indexBy(current.packages, 'name');
+  for (const [name, p] of currentPkgs) {
+    const old = savedPkgs.get(name);
+    if (!old) changes.packages.push({ name, change: 'added', version: p.version });
+    else if (old.version !== p.version) {
+      changes.packages.push({ name, change: 'version', from: old.version, to: p.version });
+    }
+  }
+  for (const name of savedPkgs.keys()) {
+    if (!currentPkgs.has(name)) changes.packages.push({ name, change: 'removed' });
+  }
+
+  if (saved.composedHash && current.composedHash && saved.composedHash !== current.composedHash) {
+    changes.composed = { from: saved.composedHash, to: current.composedHash };
+  }
+
+  const identical =
+    !changes.bundles.length &&
+    !changes.patches.length &&
+    !changes.packages.length &&
+    !changes.composed;
+  return { identical, savedAt: saved.createdAt, profile: saved.profile, changes };
+}
+
+module.exports = { compareSnapshots };

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({

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.4.1",
+  "version": "0.6.0",
   "description": "X-ray for your DeepSeek Harness — see what's actually loaded, why, and what it costs you.",
   "repository": {
     "type": "git",