dsh-xray 0.2.0 → 0.3.0

package/README.md

@@ -17,19 +17,22 @@ 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
+npx dsh-xray cost        # estimated context-token cost per model-facing tool schema
+npx dsh-xray shadow      # services provided by multiple plugins
+npx dsh-xray audit       # static scan of out-of-tree plugins for sensitive touchpoints
 ```
 
 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.
+Mounted in the tree, dsh-xray registers an `xray_composition` tool (`view: summary | deps | health | cost | shadow`), 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.2.x:
+Shipped in 0.3.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
@@ -39,11 +42,9 @@ Shipped in 0.2.x:
 - **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:
-
-- **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
+- **Capability audit** — heuristic static scan of out-of-tree plugins: network egress, shell, filesystem, env, eval (`audit`)
+- **Service shadowing** — services claimed by multiple plugins, per-plugin tool/command registrations (`shadow`)
+- **Context cost** — estimated tokens each model-facing tool schema occupies (`cost`)
 
 ## Install
 

package/README.zh.md

@@ -17,19 +17,22 @@ npx dsh-xray diff        # 声明(静态层)vs 实际(dump-config)组合树
 npx dsh-xray snapshot    # 当前生效组合的内容寻址 lockfile
 npx dsh-xray deps [svc]  # 服务依赖图:提供者、消费者、停用级联
 npx dsh-xray health      # 插件生命周期健康:失败 fiber、等待中的注入、状态迁移史
+npx dsh-xray cost        # 每个模型可见工具 schema 的估算 token 占用
+npx dsh-xray shadow      # 被多个插件同时提供的服务
+npx dsh-xray audit       # 对 out-of-tree 插件做敏感触点静态扫描
 ```
 
 所有命令支持 `--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-xray 注册 `xray_composition` 工具(`view: summary | deps | health | cost | shadow`),agent 可以自答"我有哪些能力 / 哪个插件提供 X / 为什么 Y 不可用"。
 
 ## 能力
 
 对运行中组合树的诊断成像——与 [dsh-doctor](https://www.npmjs.com/package/dsh-doctor)(救援与恢复)互补。
 
-0.2.x 已交付:
+0.3.x 已交付:
 
 - **来源归因** — 每个活跃插件来自哪一层:内核 bundle / profile 依赖 / `cordis.patch.yml` insert / repository 源
 - **声明 vs 实际 diff** — 装了但没生效、卸了但残留 patch 行
@@ -39,11 +42,9 @@ npx dsh-xray health      # 插件生命周期健康:失败 fiber、等待中的
 - **运行时健康** — 每个插件的 fiber 生命周期状态、启动失败、状态迁移史(`health`)
 - **Agent 自省** — `xray_composition` 工具让 agent 检视自己的能力集
 
-规划中:
-
-- **能力审计** — 已装插件实际触碰什么:网络外发、shell、文件系统、环境变量;更新前后权限 diff
-- **命令/工具重名检测** — 注册同名命令/工具时,谁静默覆盖谁
-- **上下文成本** — 每个插件往 agent 上下文注入多少 token:工具 schema、prompt 片段、skill 文档
+- **能力审计** — 对 out-of-tree 插件的启发式静态扫描:网络外发、shell、文件系统、环境变量、动态求值(`audit`)
+- **服务重名检测** — 被多个插件同时提供的服务,及每插件工具/命令注册数(`shadow`)
+- **上下文成本** — 每个模型可见工具 schema 的估算 token 占用(`cost`)
 
 ## 安装
 

package/bin/xray.js

@@ -178,6 +178,57 @@ function cmdHealth(args) {
   if (result.unhealthy.length) process.exitCode = 1;
 }
 
+function cmdCost(args) {
+  const snap = readRuntimeSnapshot();
+  const result = model.contextCost(snap);
+  if (args.json) return console.log(JSON.stringify(result, null, 2));
+  console.log(
+    `~${result.totalTokens} tokens across ${result.toolCount} tool schema(s) (captured ${result.capturedAt})\n`,
+  );
+  for (const t of result.tools) {
+    const bar = '█'.repeat(Math.max(1, Math.round(t.share / 2)));
+    console.log(`${pad(t.name, 28)} ${pad(`~${t.tokens}`, 8)} ${pad(`${t.share}%`, 7)} ${bar}`);
+  }
+}
+
+function cmdShadow(args) {
+  const snap = readRuntimeSnapshot();
+  const result = model.shadowing(snap);
+  if (args.json) return console.log(JSON.stringify(result, null, 2));
+  if (!result.services.length) console.log('no service is provided by more than one plugin');
+  for (const s of result.services) {
+    console.log(`${s.service}: provided by ${s.providers.join(' AND ')}`);
+  }
+  if (result.registrars.length) {
+    console.log('\n# tool/command registrars:');
+    for (const r of result.registrars) {
+      console.log(`  ${r.plugin}: ${r.registrations} registration(s)`);
+    }
+  }
+  if (result.services.length) process.exitCode = 1;
+}
+
+function cmdAudit(args) {
+  const { collectAudit } = require('../lib/collect/audit.js');
+  const data = collectStatic(args.profile);
+  const result = collectAudit(data);
+  if (args.json) return console.log(JSON.stringify(result, null, 2));
+  if (!result.plugins.length) {
+    return console.log(
+      'no out-of-tree plugins installed (kernel bundles are the trusted baseline)',
+    );
+  }
+  for (const p of result.plugins) {
+    console.log(`${p.name}@${p.version} (${p.scannedFiles} file(s) scanned)`);
+    if (!p.categories.length) console.log('  no sensitive touchpoints detected');
+    for (const c of p.categories) {
+      console.log(
+        `  ${c.label}: ${c.files.slice(0, 3).join(', ')}${c.files.length > 3 ? ', …' : ''}`,
+      );
+    }
+  }
+}
+
 const commands = {
   attribute: cmdAttribute,
   conflicts: cmdConflicts,
@@ -185,6 +236,9 @@ const commands = {
   snapshot: cmdSnapshot,
   deps: cmdDeps,
   health: cmdHealth,
+  cost: cmdCost,
+  shadow: cmdShadow,
+  audit: cmdAudit,
 };
 
 const args = parseArgs(process.argv.slice(2));
@@ -201,8 +255,11 @@ Commands:
   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
+  cost        estimated context-token cost of each model-facing tool schema
+  shadow      services provided by multiple plugins, and per-plugin registrations
+  audit       static scan of out-of-tree plugins for sensitive touchpoints
 
-deps/health need the plugin mounted: dsh plugin --profile web add dsh-xray`);
+deps/health/cost/shadow need the plugin mounted: dsh plugin --profile web add dsh-xray`);
   process.exit(args._[0] ? 2 : 0);
 }
 try {

package/lib/collect/audit.js

@@ -0,0 +1,115 @@
+// Audit collector: static scan of installed plugin sources for sensitive
+// capability touchpoints. Heuristic by design — a flag means "this pattern
+// appears in the shipped code", not "this plugin is malicious".
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const CATEGORIES = [
+  {
+    id: 'network',
+    label: 'network egress',
+    patterns: [
+      /\bfetch\s*\(/,
+      /require\(['"](?:node:)?https?['"]\)/,
+      /from\s+['"](?:node:)?https?['"]/,
+      /\bWebSocket\b/,
+      /\baxios\b/,
+      /\bnode-fetch\b/,
+    ],
+  },
+  {
+    id: 'shell',
+    label: 'subprocess / shell',
+    patterns: [
+      /require\(['"](?:node:)?child_process['"]\)/,
+      /from\s+['"](?:node:)?child_process['"]/,
+      /\bexecSync|\bexecFile|\bspawnSync?\b/,
+      /\bnode-pty\b/,
+    ],
+  },
+  {
+    id: 'fs',
+    label: 'filesystem',
+    patterns: [
+      /require\(['"](?:node:)?fs(?:\/promises)?['"]\)/,
+      /from\s+['"](?:node:)?fs(?:\/promises)?['"]/,
+    ],
+  },
+  {
+    id: 'env',
+    label: 'environment variables',
+    patterns: [/\bprocess\.env\b/],
+  },
+  {
+    id: 'eval',
+    label: 'dynamic code evaluation',
+    patterns: [/\beval\s*\(/, /new\s+Function\s*\(/],
+  },
+];
+
+const SCAN_EXTENSIONS = new Set(['.js', '.cjs', '.mjs', '.ts']);
+const MAX_FILE_BYTES = 1024 * 1024;
+const MAX_FILES = 400;
+
+function* walkFiles(dir, depth = 0) {
+  if (depth > 6) return;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) yield* walkFiles(full, depth + 1);
+    else if (entry.isFile() && SCAN_EXTENSIONS.has(path.extname(entry.name))) yield full;
+  }
+}
+
+/** Scan one plugin package directory. Returns per-category file hits. */
+function auditPackage(dir) {
+  const hits = new Map(); // category id -> Set of relative files
+  let scanned = 0;
+  for (const file of walkFiles(dir)) {
+    if (++scanned > MAX_FILES) break;
+    let text;
+    try {
+      if (fs.statSync(file).size > MAX_FILE_BYTES) continue;
+      text = fs.readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    for (const cat of CATEGORIES) {
+      if (hits.get(cat.id)?.size >= 5) continue; // enough evidence
+      if (cat.patterns.some((p) => p.test(text))) {
+        if (!hits.has(cat.id)) hits.set(cat.id, new Set());
+        hits.get(cat.id).add(path.relative(dir, file));
+      }
+    }
+  }
+  return {
+    scannedFiles: scanned,
+    categories: CATEGORIES.filter((c) => hits.has(c.id)).map((c) => ({
+      id: c.id,
+      label: c.label,
+      files: [...hits.get(c.id)],
+    })),
+  };
+}
+
+/**
+ * Audit every out-of-tree plugin in a profile (kernel @deepseek-ai/* packages
+ * are the trusted baseline; auditing them adds noise, not signal).
+ */
+function collectAudit(staticData) {
+  const results = [];
+  for (const pkg of staticData.packages) {
+    if (!pkg.dir) continue;
+    results.push({ name: pkg.name, version: pkg.version, ...auditPackage(pkg.dir) });
+  }
+  return { schema: 'dsh-xray/audit@1', capturedAt: new Date().toISOString(), plugins: results };
+}
+
+module.exports = { collectAudit, auditPackage, CATEGORIES };

package/lib/collect/runtime.js

@@ -55,6 +55,27 @@ function summarizeEffect(meta, depth = 0) {
   return out;
 }
 
+/** Rough token estimate: ~4 chars per token for English/JSON. */
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+
+/** Capture the model-facing tool schemas (name/description/parameters). */
+function snapshotTools(ctx) {
+  try {
+    const tools = ctx.get?.('tools') ?? ctx.root?.tools;
+    const schemas = tools?.schemas?.();
+    if (!Array.isArray(schemas)) return [];
+    return schemas.map((s) => ({
+      name: s.name,
+      description: s.description ?? '',
+      tokens: estimateTokens(JSON.stringify(s)),
+    }));
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Snapshot every registered plugin runtime plus the service store.
  * @param ctx a live Cordis context (any fiber's ctx reaches the shared registry)
@@ -100,7 +121,15 @@ function snapshotRegistry(ctx) {
     registrySize: ctx.registry.size,
     plugins,
     services,
+    tools: snapshotTools(ctx),
   };
 }
 
-module.exports = { snapshotRegistry, injectNames, provideNames, stateName };
+module.exports = {
+  snapshotRegistry,
+  snapshotTools,
+  injectNames,
+  provideNames,
+  stateName,
+  estimateTokens,
+};

package/lib/index.js

@@ -2,7 +2,7 @@ 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 { serviceGraph, health, shadowing, contextCost } = require('./model.js');
 
 const name = 'dsh-xray';
 
@@ -101,7 +101,7 @@ function apply(ctx) {
           parameters: {
             view: {
               type: 'string',
-              description: 'summary | deps | health (default summary)',
+              description: 'summary | deps | health | cost | shadow (default summary)',
             },
           },
           output: {
@@ -113,10 +113,13 @@ function apply(ctx) {
             snap.transitions = Object.fromEntries(transitions);
             if (args.view === 'deps') return serviceGraph(snap);
             if (args.view === 'health') return health(snap);
+            if (args.view === 'cost') return contextCost(snap);
+            if (args.view === 'shadow') return shadowing(snap);
             return {
               plugins: snap.plugins.length,
               unhealthy: health(snap).unhealthy.length,
               services: Object.keys(serviceGraph(snap).services).length,
+              toolSchemaTokens: contextCost(snap).totalTokens,
               capturedAt: snap.capturedAt,
             };
           },

package/lib/model.js

@@ -247,4 +247,60 @@ function health(snap) {
   };
 }
 
-module.exports = { replayLayers, attribute, conflicts, diff, snapshot, serviceGraph, health };
+/** F7: same-name registrations where a later writer silently shadows. */
+function shadowing(snap) {
+  // Service ownership comes from the reflect store; callback `provide` is a
+  // secondary source. Cordis rejects same-layer duplicate tools itself, so
+  // what we surface is cross-source duplication: one service claimed by
+  // multiple plugins (isolation scopes make this legal — and invisible).
+  const out = { services: [], registrars: [] };
+  const providersByService = new Map();
+  for (const s of snap.services ?? []) {
+    if (!providersByService.has(s.name)) providersByService.set(s.name, []);
+    if (s.provider) providersByService.get(s.name).push(s.provider);
+  }
+  for (const p of snap.plugins) {
+    for (const s of p.provide) {
+      const list = providersByService.get(s) ?? [];
+      if (!list.includes(p.name)) providersByService.set(s, [...list, p.name]);
+    }
+  }
+  for (const [service, providers] of providersByService) {
+    if (providers.length > 1) out.services.push({ service, providers });
+  }
+  for (const p of snap.plugins) {
+    const registrations = p.fibers
+      .flatMap((f) => f.effects)
+      .filter((e) => /tools\.register|commands?\./.test(e?.label ?? '')).length;
+    if (registrations > 0) out.registrars.push({ plugin: p.name, registrations });
+  }
+  return out;
+}
+
+/** F8: estimated context cost of each model-facing tool schema. */
+function contextCost(snap) {
+  const tools = (snap.tools ?? []).slice().sort((a, b) => b.tokens - a.tokens);
+  const total = tools.reduce((sum, t) => sum + t.tokens, 0);
+  return {
+    totalTokens: total,
+    toolCount: tools.length,
+    tools: tools.map((t) => ({
+      name: t.name,
+      tokens: t.tokens,
+      share: total ? Math.round((t.tokens / total) * 1000) / 10 : 0,
+    })),
+    capturedAt: snap.capturedAt,
+  };
+}
+
+module.exports = {
+  replayLayers,
+  attribute,
+  conflicts,
+  diff,
+  snapshot,
+  serviceGraph,
+  health,
+  shadowing,
+  contextCost,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-xray",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "X-ray for your DeepSeek Harness — see what's actually loaded, why, and what it costs you.",
   "repository": {
     "type": "git",