dsh-xray 0.1.2 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alloevil
+
+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

@@ -4,7 +4,7 @@ X-ray for your [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harnes
 
 [中文](./README.zh.md)
 
-> **Status: 0.1.x — static imaging.** The CLI works today, even when dsh cannot boot. Runtime imaging (dependency graph, health, context cost) lands in 0.2.0.
+> **Status: 0.2.x — static + runtime imaging.** Static commands work even when dsh cannot boot; `deps`/`health` and the agent tool need the plugin mounted.
 
 `dsh --dump-config` shows you the composed tree. The plugin panel shows you a flat list. Neither tells you *why* a plugin is there, *what breaks* if you disable it, or *what it silently costs you*. dsh-xray does.
 
@@ -15,29 +15,35 @@ npx dsh-xray attribute   # which layer introduced each row, and who patched it s
 npx dsh-xray conflicts   # rows whose fields have multiple writers, and who wins
 npx dsh-xray diff        # declared (static layers) vs actual (dump-config) tree
 npx dsh-xray snapshot    # content-addressed lockfile of the effective composition
+npx dsh-xray deps [svc]  # service dependency graph: providers, consumers, disable-cascade
+npx dsh-xray health      # plugin lifecycle health: failed fibers, pending injects, transitions
 ```
 
-All commands take `--profile <name>` (default `web`) and `--json`. `diff` exits `1` when the trees disagree — orphan patch rows silently skipped by dsh, installed-but-inactive plugins, disabled-state mismatches. `attribute`, `conflicts`, and `snapshot` are fully static: they work even when dsh cannot start.
+All commands take `--profile <name>` (default `web`) and `--json`. `diff` exits `1` when the trees disagree; `health` exits `1` when any plugin is unhealthy. `attribute`, `conflicts`, and `snapshot` are fully static: they work even when dsh cannot start. `deps` and `health` read the runtime snapshot the mounted plugin maintains at `$DSH_HOME/xray/runtime.json`.
+
+## Agent tool
+
+Mounted in the tree, dsh-xray registers an `xray_composition` tool (`view: summary | deps | health`), so an agent can answer "what capabilities do I have / what plugin provides X / why is Y unavailable" about itself.
 
 ## Capabilities
 
 Diagnostic imaging for a running composition — complementary to [dsh-doctor](https://www.npmjs.com/package/dsh-doctor) (rescue & recovery).
 
-Shipped in 0.1.x:
+Shipped in 0.2.x:
 
 - **Layer attribution** — which layer introduced each active plugin: kernel bundle, profile dependency, `cordis.patch.yml` insert, or repository source
 - **Declared vs. actual diff** — installed-but-inactive, uninstalled-but-lingering patch rows
 - **Conflict detection** — plugins patching the same config row, and which one silently wins
 - **Composition snapshot** — export the effective composition as a lockfile; reproduce it elsewhere
+- **Service dependency graph** — who provides and consumes each service; what cascades if you disable X (`deps`)
+- **Runtime health** — per-plugin fiber lifecycle state, startup failures, transition history (`health`)
+- **Agent self-introspection** — the `xray_composition` tool lets agents inspect their own capability set
 
 Planned:
 
-- **Service dependency graph** — who `inject`s whose service; what cascades if you disable X
-- **Runtime health** — per-plugin scope state: activation failures, stacks, load time, HMR reloads
 - **Capability audit** — what installed plugins actually touch: network egress, shell, filesystem, env; permission diff across updates
 - **Command/tool shadowing** — plugins registering the same command/tool, and which one silently wins
 - **Context cost** — tokens each plugin injects into agent context: tool schemas, prompt sections, skills
-- **Agent self-introspection** — expose the composition as a tool so agents know what capabilities they have
 
 ## Install
 

package/README.zh.md

@@ -4,7 +4,7 @@
 
 [English](./README.md)
 
-> **状态:0.1.x — 静态成像。** CLI 现在就能用,即使 dsh 起不来。运行时成像(依赖图、健康状态、上下文成本)在 0.2.0 落地。
+> **状态:0.2.x — 静态 + 运行时成像。** 静态命令在 dsh 起不来时照样能用;`deps`/`health` 和 agent 工具需要插件已挂载。
 
 `dsh --dump-config` 只给你原始组合树,插件面板只给你平铺列表。它们都不回答:这个插件*为什么*在这、停用它会*连带瘫掉什么*、它在*悄悄消耗什么*。dsh-xray 回答这些。
 
@@ -15,29 +15,35 @@ npx dsh-xray attribute   # 每一行由哪层引入、之后被谁 patch 过
 npx dsh-xray conflicts   # 哪些行的字段有多个写者、最终谁赢
 npx dsh-xray diff        # 声明(静态层)vs 实际(dump-config)组合树
 npx dsh-xray snapshot    # 当前生效组合的内容寻址 lockfile
+npx dsh-xray deps [svc]  # 服务依赖图:提供者、消费者、停用级联
+npx dsh-xray health      # 插件生命周期健康:失败 fiber、等待中的注入、状态迁移史
 ```
 
-所有命令支持 `--profile <name>`(默认 `web`)和 `--json`。`diff` 在两棵树不一致时以退出码 `1` 结束——被 dsh 静默跳过的 orphan patch 行、装了但未生效的插件、disabled 状态不匹配。`attribute`、`conflicts`、`snapshot` 是纯静态的:dsh 起不来时照样能跑。
+所有命令支持 `--profile <name>`(默认 `web`)和 `--json`。`diff` 在两棵树不一致时退出码 `1`;`health` 在有插件不健康时退出码 `1`。`attribute`、`conflicts`、`snapshot` 是纯静态的:dsh 起不来时照样能跑。`deps` 和 `health` 读取已挂载插件维护在 `$DSH_HOME/xray/runtime.json` 的运行时快照。
+
+## Agent 工具
+
+挂载进树后,dsh-xray 注册 `xray_composition` 工具(`view: summary | deps | health`),agent 可以自答"我有哪些能力 / 哪个插件提供 X / 为什么 Y 不可用"。
 
 ## 能力
 
 对运行中组合树的诊断成像——与 [dsh-doctor](https://www.npmjs.com/package/dsh-doctor)(救援与恢复)互补。
 
-0.1.x 已交付:
+0.2.x 已交付:
 
 - **来源归因** — 每个活跃插件来自哪一层:内核 bundle / profile 依赖 / `cordis.patch.yml` insert / repository 源
 - **声明 vs 实际 diff** — 装了但没生效、卸了但残留 patch 行
 - **冲突检测** — 多个插件 patch 同一配置行时,谁静默赢了
 - **组合快照** — 把当前生效组合导出为 lockfile,异地一键复现
+- **服务依赖图** — 每个服务谁提供、谁消费;停用 X 会级联影响什么(`deps`)
+- **运行时健康** — 每个插件的 fiber 生命周期状态、启动失败、状态迁移史(`health`)
+- **Agent 自省** — `xray_composition` 工具让 agent 检视自己的能力集
 
 规划中:
 
-- **服务依赖图** — 谁 `inject` 了谁的服务;停用 X 会级联影响什么
-- **运行时健康** — 每个插件的 scope 状态:激活失败与堆栈、加载耗时、HMR 重载次数
 - **能力审计** — 已装插件实际触碰什么:网络外发、shell、文件系统、环境变量;更新前后权限 diff
 - **命令/工具重名检测** — 注册同名命令/工具时,谁静默覆盖谁
 - **上下文成本** — 每个插件往 agent 上下文注入多少 token:工具 schema、prompt 片段、skill 文档
-- **Agent 自省** — 把组合信息暴露为 tool,让 agent 知道自己有哪些能力
 
 ## 安装
 

package/bin/xray.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-'use strict';
+
 // dsh-xray CLI. Static analysis works even when dsh cannot boot;
 // commands needing the composed tree degrade with a clear notice.
 
@@ -22,7 +22,10 @@ function tryDump(profile) {
   try {
     return { dump: collectDump(profile), error: null };
   } catch (err) {
-    return { dump: null, error: `dump-config unavailable (${err.message.split('\n')[0]}); static-only mode` };
+    return {
+      dump: null,
+      error: `dump-config unavailable (${err.message.split('\n')[0]}); static-only mode`,
+    };
   }
 }
 
@@ -42,7 +45,9 @@ function cmdAttribute(args) {
     console.log(`${pad(row.id, 28)} ${pad(row.origin?.layer, 32)}${over}${flags}`);
   }
   if (result.orphans.length) {
-    console.log(`\n! ${result.orphans.length} orphan override(s) targeting nonexistent rows (silently skipped by dsh):`);
+    console.log(
+      `\n! ${result.orphans.length} orphan override(s) targeting nonexistent rows (silently skipped by dsh):`,
+    );
     for (const o of result.orphans) console.log(`  ${o.id}  in ${o.file}`);
   }
   for (const w of result.warnings) console.log(`! ${w}`);
@@ -56,7 +61,9 @@ function cmdConflicts(args) {
   for (const c of result) {
     console.log(`${c.id}`);
     for (const f of c.fields) {
-      console.log(`  .${f.field}: ${f.writers.map((w) => w.layer).join(' → ')}  (winner: ${f.winner})`);
+      console.log(
+        `  .${f.field}: ${f.writers.map((w) => w.layer).join(' → ')}  (winner: ${f.winner})`,
+      );
     }
   }
 }
@@ -64,7 +71,11 @@ function cmdConflicts(args) {
 function cmdDiff(args) {
   const data = collectStatic(args.profile);
   const { dump, error } = tryDump(args.profile);
-  if (error) { console.error(`! ${error}`); process.exitCode = 1; return; }
+  if (error) {
+    console.error(`! ${error}`);
+    process.exitCode = 1;
+    return;
+  }
   const result = model.diff(data, dump);
   if (args.json) return console.log(JSON.stringify(result, null, 2));
 
@@ -74,12 +85,32 @@ function cmdDiff(args) {
     for (const it of items) console.log(`  ${fmt(it)}`);
   };
   section('declared but not in boot tree', result.missingFromActual, (r) => `${r.id} (${r.name})`);
-  section('in boot tree but undeclared', result.missingFromDeclared, (r) => `${r.id} (${r.name}) — dump says: ${r.provenance}`);
-  section('disabled-state mismatch', result.disabledMismatch, (r) => `${r.id}: declared=${r.declared} actual=${r.actual}`);
-  section('orphan overrides (silently skipped)', result.orphanOverrides, (r) => `${r.id} in ${r.file}`);
-  section('installed but inactive packages', result.inactivePackages, (r) => `${r.name}@${r.version}`);
-  const total = result.missingFromActual.length + result.missingFromDeclared.length
-    + result.disabledMismatch.length + result.orphanOverrides.length + result.inactivePackages.length;
+  section(
+    'in boot tree but undeclared',
+    result.missingFromDeclared,
+    (r) => `${r.id} (${r.name}) — dump says: ${r.provenance}`,
+  );
+  section(
+    'disabled-state mismatch',
+    result.disabledMismatch,
+    (r) => `${r.id}: declared=${r.declared} actual=${r.actual}`,
+  );
+  section(
+    'orphan overrides (silently skipped)',
+    result.orphanOverrides,
+    (r) => `${r.id} in ${r.file}`,
+  );
+  section(
+    'installed but inactive packages',
+    result.inactivePackages,
+    (r) => `${r.name}@${r.version}`,
+  );
+  const total =
+    result.missingFromActual.length +
+    result.missingFromDeclared.length +
+    result.disabledMismatch.length +
+    result.orphanOverrides.length +
+    result.inactivePackages.length;
   if (total === 0) console.log('declared and actual trees agree');
   else process.exitCode = 1;
 }
@@ -90,11 +121,70 @@ function cmdSnapshot(args) {
   console.log(JSON.stringify(model.snapshot(data, dump), null, 2));
 }
 
+function readRuntimeSnapshot() {
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const { xrayDir } = require('../lib/index.js');
+  const file = path.join(xrayDir(), 'runtime.json');
+  if (!fs.existsSync(file)) {
+    throw new Error(
+      `no runtime snapshot at ${file} — mount the plugin first: dsh plugin --profile web add dsh-xray`,
+    );
+  }
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function cmdDeps(args) {
+  const snap = readRuntimeSnapshot();
+  const result = model.serviceGraph(snap);
+  if (args.json) return console.log(JSON.stringify(result, null, 2));
+
+  const filter = args._[1];
+  for (const [service, node] of Object.entries(result.services)) {
+    if (filter && service !== filter) continue;
+    console.log(`${service}`);
+    console.log(`  provided by: ${node.providers.join(', ') || '(nobody)'}`);
+    if (node.consumers.length) console.log(`  consumed by: ${node.consumers.join(', ')}`);
+  }
+  if (!filter && Object.keys(result.cascade).length) {
+    console.log('\n# disable-cascade (transitive consumers of each provider):');
+    for (const [plugin, affected] of Object.entries(result.cascade)) {
+      console.log(
+        `  ${plugin} → ${affected.length} plugin(s): ${affected.slice(0, 6).join(', ')}${affected.length > 6 ? ', …' : ''}`,
+      );
+    }
+  }
+  if (result.unsatisfied.length) {
+    console.log(`\n! ${result.unsatisfied.length} unsatisfied inject(s):`);
+    for (const u of result.unsatisfied) console.log(`  ${u.plugin} wants ${u.service}`);
+  }
+}
+
+function cmdHealth(args) {
+  const snap = readRuntimeSnapshot();
+  const result = model.health(snap);
+  if (args.json) return console.log(JSON.stringify(result, null, 2));
+  console.log(
+    `captured ${result.capturedAt}: ${result.healthy.length} healthy, ${result.unhealthy.length} unhealthy`,
+  );
+  for (const p of result.unhealthy) {
+    console.log(`\n${p.name}`);
+    for (const f of p.fibers)
+      console.log(`  fiber ${f.uid}: ${f.state}${f.error ? ` (${f.error})` : ''}`);
+    for (const t of p.transitions.slice(-5)) {
+      console.log(`  ${new Date(t.at).toISOString()} ${t.state}`);
+    }
+  }
+  if (result.unhealthy.length) process.exitCode = 1;
+}
+
 const commands = {
   attribute: cmdAttribute,
   conflicts: cmdConflicts,
   diff: cmdDiff,
   snapshot: cmdSnapshot,
+  deps: cmdDeps,
+  health: cmdHealth,
 };
 
 const args = parseArgs(process.argv.slice(2));
@@ -108,7 +198,11 @@ 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 of the effective composition
+  deps        service dependency graph from the live runtime snapshot
+  health      plugin lifecycle health from the live runtime snapshot
+
+deps/health need the plugin mounted: dsh plugin --profile web add dsh-xray`);
   process.exit(args._[0] ? 2 : 0);
 }
 try {

package/lib/collect/dump.js

@@ -1,4 +1,3 @@
-'use strict';
 // Dump collector: runs `dsh --profile <p> --dump-config` and parses the
 // composed tree, preserving dsh's own provenance comments (`# == <layer>`),
 // which annotate the row group that follows them.

package/lib/collect/runtime.js

@@ -0,0 +1,106 @@
+// Runtime collector: snapshots the live Cordis registry from inside a
+// mounted plugin. Output is plain JSON, written for the CLI to read.
+
+/** Normalize an inject declaration (array | object | null) to a name list. */
+function injectNames(inject) {
+  if (!inject) return [];
+  if (Array.isArray(inject)) return [...inject];
+  // Object form may carry a prototype chain (class-inherited); walk own+proto keys.
+  const names = new Set();
+  for (let o = inject; o && o !== Object.prototype; o = Object.getPrototypeOf(o)) {
+    for (const k of Object.keys(o)) names.add(k);
+  }
+  return [...names];
+}
+
+function provideNames(provide) {
+  if (!provide) return [];
+  return Array.isArray(provide) ? [...provide] : [provide];
+}
+
+// Cordis Fiber.State enum (vendor/cordis/src/fiber.ts): numeric values.
+const STATE_NAMES = ['PENDING', 'LOADING', 'ACTIVE', 'FAILED', 'DISPOSED', 'UNLOADING'];
+
+function stateName(state) {
+  return STATE_NAMES[state] ?? String(state);
+}
+
+/** Serialize one fiber defensively: never let a bad fiber break the snapshot. */
+function fiberInfo(fiber) {
+  const info = { uid: null, state: null, error: null, effects: [] };
+  try {
+    info.uid = fiber.uid;
+    info.state = stateName(fiber.state);
+  } catch (err) {
+    info.error = `state unreadable: ${err.message}`;
+  }
+  try {
+    const effects = fiber.getEffects?.();
+    if (Array.isArray(effects)) {
+      info.effects = effects.map((e) => summarizeEffect(e)).filter(Boolean);
+    }
+  } catch (err) {
+    info.error = info.error ?? `effects unreadable: ${err.message}`;
+  }
+  return info;
+}
+
+function summarizeEffect(meta, depth = 0) {
+  if (!meta || depth > 3) return null;
+  const out = { label: meta.label ?? null };
+  const children = Array.isArray(meta.children)
+    ? meta.children.map((c) => summarizeEffect(c, depth + 1)).filter(Boolean)
+    : [];
+  if (children.length) out.children = children;
+  return out;
+}
+
+/**
+ * Snapshot every registered plugin runtime plus the service store.
+ * @param ctx a live Cordis context (any fiber's ctx reaches the shared registry)
+ */
+function snapshotRegistry(ctx) {
+  const plugins = [];
+  for (const runtime of ctx.registry.values()) {
+    const cb = runtime.callback;
+    plugins.push({
+      name: runtime.name ?? cb?.name ?? null,
+      inject: injectNames(cb?.inject),
+      provide: provideNames(cb?.provide),
+      fibers: [...runtime.fibers].map(fiberInfo),
+    });
+  }
+
+  // Service implementations live in the root reflect store (Impl records),
+  // not on plugin callbacks: Service subclasses provide via ctx.provide().
+  // The store is keyed by isolation-label symbols; values are Impl records.
+  const services = [];
+  try {
+    const store = ctx.root?.reflect?.store ?? ctx.reflect?.store;
+    if (store) {
+      for (const key of [...Object.getOwnPropertySymbols(store), ...Object.keys(store)]) {
+        const impl = store[key];
+        if (!impl?.name) continue;
+        let provider = null;
+        try {
+          provider = impl.fiber?.name ?? null;
+        } catch {
+          /* disposed fiber */
+        }
+        services.push({ name: impl.name, provider });
+      }
+    }
+  } catch {
+    /* reflect layout changed; plugins alone still work */
+  }
+
+  return {
+    schema: 'dsh-xray/runtime@1',
+    capturedAt: new Date().toISOString(),
+    registrySize: ctx.registry.size,
+    plugins,
+    services,
+  };
+}
+
+module.exports = { snapshotRegistry, injectNames, provideNames, stateName };

package/lib/collect/static.js

@@ -1,4 +1,3 @@
-'use strict';
 // Static collector: reads the layer stack from DSH_HOME without running dsh.
 // Layers, in application order: each profile bundle's patch, the profile's
 // cordis.patch.yml, the home-level cordis.patch.yml.
@@ -100,7 +99,14 @@ function collectStatic(profileName) {
     const text = fs.readFileSync(file, 'utf8');
     const { value, error } = parseYaml(text, file);
     if (error) warnings.push(error);
-    layers.push({ kind, name: kind, version: null, file, entries: Array.isArray(value) ? value : [], text });
+    layers.push({
+      kind,
+      name: kind,
+      version: null,
+      file,
+      entries: Array.isArray(value) ? value : [],
+      text,
+    });
   }
 
   // Out-of-tree plugins: profile dependencies carrying a `dsh` field.

package/lib/index.js

@@ -1,18 +1,130 @@
-'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { snapshotRegistry, stateName } = require('./collect/runtime.js');
+const { serviceGraph, health } = require('./model.js');
 
 const name = 'dsh-xray';
 
+function xrayDir() {
+  const home = process.env.DSH_HOME || path.join(os.homedir(), '.dsh');
+  return path.join(home, 'xray');
+}
+
 /**
  * dsh-xray — X-ray for your DeepSeek Harness.
  *
- * 0.1.x: static imaging ships in the CLI (bin/xray.js) — layer attribution,
- * declared-vs-actual diff, conflict detection, composition snapshot.
- * This Cordis entry is a mount point; runtime imaging (dependency graph,
- * health, context cost, agent self-introspection) lands here in 0.2.0.
+ * Mounted in the tree, this plugin:
+ * 1. writes a runtime snapshot to $DSH_HOME/xray/runtime.json (throttled,
+ *    refreshed on every fiber status change) for the CLI to read;
+ * 2. counts status transitions and HMR updates per plugin;
+ * 3. registers an `xray_composition` tool when `ctx.tools` is available,
+ *    so agents can introspect their own capability set.
  */
 function apply(ctx) {
-  ctx.logger(name).info('dsh-xray mounted; run `npx dsh-xray` for static composition imaging (runtime imaging lands in 0.2.0)');
+  const logger = ctx.logger(name);
+  const dir = xrayDir();
+  const file = path.join(dir, 'runtime.json');
+  const transitions = new Map(); // plugin name -> [{state, at}] ring buffer
+
+  let timer = null;
+  const writeSnapshot = () => {
+    timer = null;
+    try {
+      const snap = snapshotRegistry(ctx);
+      snap.transitions = Object.fromEntries(transitions);
+      fs.mkdirSync(dir, { recursive: true });
+      const tmp = `${file}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify(snap, null, 2));
+      fs.renameSync(tmp, file);
+    } catch (err) {
+      logger.warn(`snapshot write failed: ${err.message}`);
+    }
+  };
+  const schedule = () => {
+    if (!timer) timer = setTimeout(writeSnapshot, 1000);
+  };
+
+  ctx.effect(() => {
+    // internal/status fires on every fiber lifecycle transition.
+    const disposeStatus = ctx.on('internal/status', (fiber) => {
+      try {
+        const key = fiber.name ?? 'unknown';
+        if (!transitions.has(key)) transitions.set(key, []);
+        const log = transitions.get(key);
+        log.push({ state: stateName(fiber.state), at: Date.now() });
+        if (log.length > 20) log.shift();
+      } catch {
+        /* never break the host on a diagnostic path */
+      }
+      schedule();
+    });
+    schedule(); // initial snapshot
+    return [
+      disposeStatus,
+      () => {
+        clearTimeout(timer);
+        writeSnapshot(); // final state on unload
+      },
+    ];
+  }, 'xray-runtime-snapshot');
+
+  // Agent self-introspection tool: only when a tool registry exists
+  // (headless/web both have one; keep it optional so xray mounts anywhere).
+  ctx.plugin({
+    name: 'dsh-xray-tool',
+    inject: ['tools'],
+    apply: (tctx) => {
+      // Resolve dsh-tools through the profile's flat closure too: a `link:`
+      // installed plugin cannot see $DSH_HOME/profiles/node_modules from its
+      // own directory (the documented dual-anchor rule covers loader mounting,
+      // not require() from inside the plugin).
+      let defineTool;
+      try {
+        const home = process.env.DSH_HOME || path.join(os.homedir(), '.dsh');
+        const resolved = require.resolve('@deepseek-ai/dsh-tools', {
+          paths: [__dirname, path.join(home, 'profiles')],
+        });
+        ({ defineTool } = require(resolved));
+      } catch {
+        logger.info('dsh-tools not resolvable; xray_composition tool not registered');
+        return;
+      }
+      tctx.tools.register(
+        defineTool({
+          name: 'xray_composition',
+          description:
+            '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".',
+          parameters: {
+            view: {
+              type: 'string',
+              description: 'summary | deps | health (default summary)',
+            },
+          },
+          output: {
+            schema: { type: 'object', additionalProperties: true },
+            render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+          },
+          async execute(args) {
+            const snap = snapshotRegistry(ctx);
+            snap.transitions = Object.fromEntries(transitions);
+            if (args.view === 'deps') return serviceGraph(snap);
+            if (args.view === 'health') return health(snap);
+            return {
+              plugins: snap.plugins.length,
+              unhealthy: health(snap).unhealthy.length,
+              services: Object.keys(serviceGraph(snap).services).length,
+              capturedAt: snap.capturedAt,
+            };
+          },
+        }),
+      );
+    },
+  });
 }
 
-module.exports = { name, apply };
+module.exports = { name, apply, xrayDir };
 module.exports.default = module.exports;

package/lib/model.js

@@ -1,4 +1,3 @@
-'use strict';
 // Model layer: pure functions over collector output. No IO here.
 
 const crypto = require('node:crypto');
@@ -60,7 +59,8 @@ function attribute(staticData) {
       name: row.name ?? null,
       disabled: row.disabled === true,
       origin: origin ? { layer: origin.layer, kind: origin.kind } : null,
-      overrides: events.filter((e) => e.action === 'override')
+      overrides: events
+        .filter((e) => e.action === 'override')
         .map((e) => ({ layer: e.layer, kind: e.kind, fields: e.fields })),
     };
   });
@@ -125,8 +125,11 @@ function diff(staticData, dumpData) {
   // Installed out-of-tree plugins whose bundle patch rows never made it in.
   const inactivePackages = staticData.packages
     .filter((p) => p.dsh?.bundle)
-    .filter((p) => ![...declared.rows.values()].some((r) => r.name === p.name)
-      && !dumpData.rows.some((r) => r.name === p.name))
+    .filter(
+      (p) =>
+        ![...declared.rows.values()].some((r) => r.name === p.name) &&
+        !dumpData.rows.some((r) => r.name === p.name),
+    )
     .map((p) => ({ name: p.name, version: p.version }));
 
   return {
@@ -157,4 +160,91 @@ function snapshot(staticData, dumpData) {
   };
 }
 
-module.exports = { replayLayers, attribute, conflicts, diff, snapshot };
+/** F4: service dependency graph from a runtime snapshot. */
+function serviceGraph(snap) {
+  const services = {}; // service name -> { providers: [], consumers: [] }
+  const touch = (s) => (services[s] ??= { providers: [], consumers: [] });
+  // Primary source: the reflect store (Impl records — authoritative provider
+  // ownership). Callback `provide` fields are a fallback for older snapshots.
+  for (const s of snap.services ?? []) {
+    const node = touch(s.name);
+    if (s.provider && !node.providers.includes(s.provider)) node.providers.push(s.provider);
+  }
+  const providerOf = new Map(); // plugin name -> provided services
+  for (const p of snap.plugins) {
+    for (const s of p.provide) {
+      const node = touch(s);
+      if (!node.providers.includes(p.name)) node.providers.push(p.name);
+    }
+    for (const s of p.inject) touch(s).consumers.push(p.name);
+  }
+  for (const [name, node] of Object.entries(services)) {
+    for (const provider of node.providers) {
+      if (!providerOf.has(provider)) providerOf.set(provider, []);
+      providerOf.get(provider).push(name);
+    }
+  }
+  // Cascade: disabling a provider of service S affects every consumer of S,
+  // transitively through services those consumers themselves provide.
+  const cascade = {};
+  for (const [provider, provided] of providerOf) {
+    const affected = new Set();
+    const queue = [...provided];
+    const seen = new Set(queue);
+    while (queue.length) {
+      const s = queue.shift();
+      for (const consumer of services[s]?.consumers ?? []) {
+        if (consumer === provider || affected.has(consumer)) continue;
+        affected.add(consumer);
+        for (const next of providerOf.get(consumer) ?? []) {
+          if (!seen.has(next)) {
+            seen.add(next);
+            queue.push(next);
+          }
+        }
+      }
+    }
+    if (affected.size) cascade[provider] = [...affected].sort();
+  }
+  const unsatisfied = [];
+  for (const p of snap.plugins) {
+    for (const s of p.inject) {
+      if (!services[s] || services[s].providers.length === 0) {
+        unsatisfied.push({ plugin: p.name, service: s });
+      }
+    }
+  }
+  return { services, cascade, unsatisfied };
+}
+
+/** F5: unhealthy plugins from fiber states and transition history. */
+function health(snap) {
+  const healthy = [];
+  const waiting = [];
+  const unhealthy = [];
+  for (const p of snap.plugins) {
+    // FAILED = startup threw; a serialization error also counts. PENDING is
+    // normal (waiting for services) but surfaces as "waiting" for visibility.
+    const bad = p.fibers.filter((f) => f.error || f.state === 'FAILED');
+    const pending = p.fibers.filter((f) => f.state === 'PENDING');
+    const entry = {
+      name: p.name,
+      fibers: p.fibers.map((f) => ({ uid: f.uid, state: f.state, error: f.error })),
+      transitions: snap.transitions?.[p.name] ?? [],
+    };
+    if (bad.length) unhealthy.push(entry);
+    else if (pending.length) waiting.push(entry);
+    else healthy.push(entry);
+  }
+  return {
+    healthy: healthy.map((p) => p.name),
+    waiting: waiting.map((p) => ({
+      name: p.name,
+      inject: snap.plugins.find((x) => x.name === p.name)?.inject ?? [],
+    })),
+    unhealthy,
+    capturedAt: snap.capturedAt,
+  };
+}
+
+module.exports = { replayLayers, attribute, conflicts, diff, snapshot, serviceGraph, health };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-xray",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "X-ray for your DeepSeek Harness — see what's actually loaded, why, and what it costs you.",
   "repository": {
     "type": "git",
@@ -29,7 +29,10 @@
     "yaml": "^2.6.0"
   },
   "scripts": {
-    "test": "node --test tests/model.spec.js"
+    "test": "node --test tests/*.spec.js",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "check": "biome check . && node --test tests/*.spec.js"
   },
   "keywords": [
     "dsh-plugin",
@@ -54,5 +57,8 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.9"
   }
 }