dsh-xray 0.9.1 → 0.10.0

package/README.md

@@ -13,6 +13,8 @@
 
 <p align="center">
   <strong>X-ray for your <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a></strong> — see what's actually loaded, why, and what it costs you.
+  <br>
+  <em>LLM context-cost observability: token attribution per plugin, prompt-section and tool-schema pricing, skill catalog tax, dependency cascades.</em>
 </p>
 
 <p align="center">

package/README.zh.md

@@ -12,6 +12,8 @@
 
 <p align="center">
   <strong>给 <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a> 拍 X 光</strong>——看清到底加载了什么、为什么在那、以及它悄悄花掉了你什么。
+  <br>
+  <em>LLM 上下文成本可观测:按插件归因 token、prompt section 与工具 schema 计价、skill catalog 常驻税、依赖停用级联。</em>
 </p>
 
 <p align="center">

package/lib/client.js

@@ -68,7 +68,7 @@ window.__ModuleLoader__.load({
     //#endregion
 
     //#region tiny view primitives
-    const VIEWS = ['summary', 'health', 'deps', 'cost', 'shadow', 'skills'];
+    const VIEWS = ['summary', 'health', 'deps', 'cost', 'shadow', 'skills', 'requests'];
     const NS = 'xray';
 
     /** English messages (also the key vocabulary; zh mirrors every key). */
@@ -169,6 +169,26 @@ window.__ModuleLoader__.load({
         'no skill observation yet — the skills service is absent or discovery has not run',
       'skills.yes': 'yes',
       'skills.userOnly': 'user-only',
+      'intro.requests':
+        'One bill per LLM call, newest first: system + tool schemas + history + tool results. ⚡ = the system/tools prefix matched the previous request (cache-friendly); ✂ = the prefix changed. Δ is the total against the previous request.',
+      'col.seq': '#',
+      'col.when': 'when',
+      'col.purpose': 'purpose',
+      'col.total': 'total',
+      'col.system': 'system',
+      'col.toolSchemas2': 'tools',
+      'col.history': 'history',
+      'col.results': 'results',
+      'col.prefix': 'prefix',
+      'col.delta': 'Δ',
+      'tip.total': 'Estimated tokens of the whole request payload (~4 chars/token)',
+      'tip.history': 'Conversation messages (user + assistant), excluding tool results',
+      'tip.results': 'Tool-result messages, aggregated per tool (hover a cell for the top tools)',
+      'tip.prefix':
+        'Whether system prompt + tool schemas were byte-identical to the previous request in this session (⚡ cache-friendly, ✂ prefix broken)',
+      'requests.none': 'no requests observed yet — send one agent message first',
+      'requests.session': 'session {id} ({n} request(s))',
+      'requests.chat': 'chat',
       'entry.loading': 'loading entry…',
       'entry.stats': '{chars} chars · ~{tokens} tokens ({estimator})',
       'entry.close': 'close',
@@ -264,6 +284,26 @@ window.__ModuleLoader__.load({
       'skills.none': '尚无 skill 观测——skills 服务缺失或发现未运行',
       'skills.yes': '是',
       'skills.userOnly': '仅用户',
+      'intro.requests':
+        '每次 LLM 调用一张账单,最新在前:system + 工具 schema + 历史 + 工具结果。⚡ = system/工具前缀与上一请求逐字节一致(缓存友好);✂ = 前缀变了。Δ 为相对上一请求的总量增减。',
+      'col.seq': '#',
+      'col.when': '时间',
+      'col.purpose': '用途',
+      'col.total': '总量',
+      'col.system': 'system',
+      'col.toolSchemas2': '工具',
+      'col.history': '历史',
+      'col.results': '结果',
+      'col.prefix': '前缀',
+      'col.delta': 'Δ',
+      'tip.total': '整个请求负载的估算 tokens(约 4 字符/token)',
+      'tip.history': '对话消息(user + assistant),不含工具结果',
+      'tip.results': '工具结果消息,按工具聚合(悬停单元格看 top 工具)',
+      'tip.prefix':
+        'system prompt + 工具 schema 是否与本会话上一请求逐字节一致(⚡ 缓存友好,✂ 前缀击穿)',
+      'requests.none': '尚未观测到请求——先发送一条 agent 消息',
+      'requests.session': '会话 {id}({n} 个请求)',
+      'requests.chat': 'chat',
       'entry.loading': '正在加载条目…',
       'entry.stats': '{chars} 字符 · 约 {tokens} tokens({estimator})',
       'entry.close': '关闭',
@@ -701,6 +741,69 @@ window.__ModuleLoader__.load({
                 ),
               }),
             ),
+
+      requests: (d, t) =>
+        !d.available
+          ? h('p', { className: 'xray-muted' }, t('requests.none'))
+          : h(
+              react.Fragment,
+              null,
+              d.sessions.map((session) =>
+                h(
+                  react.Fragment,
+                  { key: session.sessionId },
+                  h(
+                    'div',
+                    { className: 'xray-h3' },
+                    fill(t('requests.session'), {
+                      id: String(session.sessionId).slice(0, 12),
+                      n: session.requests.length,
+                    }),
+                  ),
+                  h(Table, {
+                    t,
+                    headers: [
+                      'seq',
+                      'when',
+                      'purpose',
+                      'total',
+                      'system',
+                      'toolSchemas2',
+                      'history',
+                      'results',
+                      'prefix',
+                      'delta',
+                    ],
+                    rows: session.requests.map((r) => {
+                      const top = (r.toolResultRows ?? [])
+                        .slice(0, 3)
+                        .map((row) => `${row.name} ~${row.tokens}`)
+                        .join(', ');
+                      return Row(`${session.sessionId}/${r.seq}`, [
+                        { cls: 'xray-num', text: String(r.seq) },
+                        { cls: 'xray-muted', text: new Date(r.at).toTimeString().slice(0, 8) },
+                        r.purpose
+                          ? h('span', { className: 'xray-muted' }, r.purpose)
+                          : t('requests.chat'),
+                        { cls: 'xray-num', text: `~${r.total}` },
+                        { cls: 'xray-num', text: String(r.system) },
+                        { cls: 'xray-num', text: String(r.toolSchemas) },
+                        { cls: 'xray-num', text: String(r.history) },
+                        h('span', { className: 'xray-num', title: top }, String(r.toolResults)),
+                        r.prefixStable === null ? '—' : r.prefixStable ? '⚡' : '✂',
+                        {
+                          cls: 'xray-num',
+                          text:
+                            r.deltaTotal === null
+                              ? '—'
+                              : `${r.deltaTotal >= 0 ? '+' : ''}${r.deltaTotal}`,
+                        },
+                      ]);
+                    }),
+                  }),
+                ),
+              ),
+            ),
     };
     //#endregion
 

package/lib/collect/requests.js

@@ -0,0 +1,151 @@
+// Request ledger: observe the `llm/stream` waterfall and record ONE
+// classified bill per LLM call — system prompt, tool schemas, conversation
+// history, tool results — plus prefix stability. Purely observational: the
+// options object passes through `next()` untouched, and nothing but counts,
+// names, and hashes is retained (never message text).
+//
+// Every request in the process flows through here: main sessions, subagents,
+// compaction and title calls (tagged by `purpose`). Entries bucket per
+// sessionId in a bounded ring so one fan-out cannot evict another session's
+// history.
+
+const crypto = require('node:crypto');
+
+/** Rough token estimate mirroring collect/runtime.js (~4 chars/token). */
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+
+/** Serialize one content block to its model-facing text size, recursively. */
+function blockChars(block) {
+  if (!block || typeof block !== 'object') return 0;
+  switch (block.type) {
+    case 'text':
+    case 'reasoning':
+      return String(block.text ?? '').length;
+    case 'image':
+      // Images are billed by the provider in provider units; approximate by
+      // the transported payload size so the ledger at least ranks them.
+      return String(block.data ?? block.url ?? '').length;
+    case 'tool-call':
+      return String(block.name ?? '').length + String(block.arguments ?? '').length;
+    case 'tool-result':
+      return (block.content ?? []).reduce((sum, inner) => sum + blockChars(inner), 0);
+    default:
+      try {
+        return JSON.stringify(block).length;
+      } catch {
+        return 0;
+      }
+  }
+}
+
+/** Short content hash for prefix-stability comparison (never stored text). */
+function digest(text) {
+  return crypto.createHash('sha256').update(text).digest('hex').slice(0, 12);
+}
+
+/**
+ * Classify one GenerateOptions into the ledger entry. Tool results resolve
+ * their tool name through the preceding assistant tool-call blocks.
+ */
+function classify(options) {
+  const system = String(options.system ?? '');
+  const toolsJson = JSON.stringify(options.tools ?? []);
+  const callNames = new Map(); // callId -> tool name
+  let historyChars = 0;
+  let historyMessages = 0;
+  let userMessages = 0;
+  let assistantMessages = 0;
+  const toolResults = new Map(); // tool name -> {count, chars}
+  for (const message of options.messages ?? []) {
+    const content = message.content ?? [];
+    for (const block of content) {
+      if (block?.type === 'tool-call') callNames.set(block.id, block.name);
+    }
+    const isToolResult =
+      message.source?.kind === 'tool' || content.some((b) => b?.type === 'tool-result');
+    const chars = content.reduce((sum, block) => sum + blockChars(block), 0);
+    if (isToolResult) {
+      let name = 'unknown';
+      for (const block of content) {
+        if (block?.type === 'tool-result') {
+          name = callNames.get(block.toolCallId) ?? 'unknown';
+          break;
+        }
+      }
+      const row = toolResults.get(name) ?? { count: 0, chars: 0 };
+      row.count += 1;
+      row.chars += chars;
+      toolResults.set(name, row);
+    } else {
+      historyChars += chars;
+      historyMessages += 1;
+      if (message.role === 'user') userMessages += 1;
+      else if (message.role === 'assistant') assistantMessages += 1;
+    }
+  }
+  const toolResultRows = [...toolResults.entries()]
+    .map(([name, row]) => ({
+      name,
+      count: row.count,
+      tokens: estimateTokens(' '.repeat(row.chars)),
+    }))
+    .sort((a, b) => b.tokens - a.tokens);
+  const toolResultTokens = toolResultRows.reduce((sum, r) => sum + r.tokens, 0);
+  const entry = {
+    at: Date.now(),
+    provider: options.provider ?? null,
+    model: options.model ?? null,
+    purpose: options.purpose ?? null,
+    system: estimateTokens(system),
+    toolSchemas: estimateTokens(toolsJson),
+    toolCount: (options.tools ?? []).length,
+    history: estimateTokens(' '.repeat(historyChars)),
+    historyMessages,
+    userMessages,
+    assistantMessages,
+    toolResults: toolResultTokens,
+    toolResultRows: toolResultRows.slice(0, 8),
+    prefixDigest: digest(system + '\u0000' + toolsJson),
+  };
+  entry.total = entry.system + entry.toolSchemas + entry.history + entry.toolResults;
+  return entry;
+}
+
+/**
+ * Install the ledger observer.
+ * @param ctx - the mounted plugin's context.
+ * @param options - { maxPerSession } ring bound (default 50).
+ * @returns { sessions, dispose } — sessions: Map<sessionId, entries[]>.
+ */
+function installRequestLedger(ctx, options = {}) {
+  const maxPerSession = options.maxPerSession ?? 50;
+  const sessions = new Map(); // sessionId -> [entry, ...] (oldest first)
+  const dispose = ctx.on('llm/stream', (generateOptions, next) => {
+    try {
+      const key = String(generateOptions.sessionId ?? 'unscoped');
+      const entry = classify(generateOptions);
+      const ring = sessions.get(key) ?? [];
+      const prev = ring[ring.length - 1];
+      entry.prefixStable = prev === undefined ? null : prev.prefixDigest === entry.prefixDigest;
+      entry.deltaTotal = prev === undefined ? null : entry.total - prev.total;
+      ring.push(entry);
+      if (ring.length > maxPerSession) ring.shift();
+      sessions.set(key, ring);
+      // Bound the session table itself: keep the most recently active 20.
+      if (sessions.size > 20) {
+        const oldest = [...sessions.entries()].sort(
+          (a, b) => (a[1][a[1].length - 1]?.at ?? 0) - (b[1][b[1].length - 1]?.at ?? 0),
+        )[0];
+        if (oldest) sessions.delete(oldest[0]);
+      }
+    } catch {
+      /* the ledger must never break a model call */
+    }
+    return next();
+  });
+  return { sessions, dispose };
+}
+
+module.exports = { installRequestLedger, classify, blockChars };

package/lib/index.js

@@ -9,7 +9,15 @@ const {
   estimateTokens,
 } = require('./collect/runtime.js');
 const { installSectionAttribution } = require('./collect/attribution.js');
-const { serviceGraph, health, shadowing, contextCost, skillCost } = require('./model.js');
+const { installRequestLedger } = require('./collect/requests.js');
+const {
+  serviceGraph,
+  health,
+  shadowing,
+  contextCost,
+  skillCost,
+  requestLedger,
+} = require('./model.js');
 
 const name = 'dsh-xray';
 
@@ -36,6 +44,7 @@ function apply(ctx) {
   let lastAssembly = null; // latest system-prompt assembly observation
   let attribution = null; // section name -> plugin name (live table)
   let skillCatalog = null; // latest skill-cost observation (async, throttled)
+  let ledger = null; // per-session request ledger (llm/stream observer)
   let skillRefreshing = false;
   const refreshSkills = (lookup) => {
     // Discovery hits the filesystem and is scope/cwd-sensitive: the
@@ -66,6 +75,7 @@ function apply(ctx) {
       snap.sectionOwners = attribution ? Object.fromEntries(attribution.table) : {};
       snap.toolOwners = attribution ? Object.fromEntries(attribution.toolTable) : {};
       snap.skillCatalog = skillCatalog;
+      snap.requestLedger = ledger ? Object.fromEntries(ledger.sessions) : {};
       fs.mkdirSync(dir, { recursive: true });
       const tmp = `${file}.tmp`;
       fs.writeFileSync(tmp, JSON.stringify(snap, null, 2));
@@ -125,12 +135,15 @@ function apply(ctx) {
     // Section attribution: diff-based name->plugin table over
     // system-prompt/change (see collect/attribution.js for the strategy).
     attribution = installSectionAttribution(ctx);
+    ledger = installRequestLedger(ctx);
     return [
       disposeStatus,
       disposeAssemble,
       () => {
         attribution.dispose();
         attribution = null;
+        ledger.dispose();
+        ledger = null;
       },
       () => {
         clearTimeout(timer);
@@ -153,6 +166,7 @@ function apply(ctx) {
         snap.sectionOwners = attribution ? Object.fromEntries(attribution.table) : {};
         snap.toolOwners = attribution ? Object.fromEntries(attribution.toolTable) : {};
         snap.skillCatalog = skillCatalog;
+        snap.requestLedger = ledger ? Object.fromEntries(ledger.sessions) : {};
         return snap;
       };
       wctx.effect(
@@ -175,6 +189,7 @@ function apply(ctx) {
               cost: () => contextCost(freshSnap()),
               shadow: () => shadowing(freshSnap()),
               skills: () => skillCost(freshSnap()),
+              requests: () => requestLedger(freshSnap()),
             },
             // Entry text is computed per request from the live registries and
             // never persisted — the audit answer to "what exactly is ~N tokens?".
@@ -219,7 +234,8 @@ function apply(ctx) {
           parameters: {
             view: {
               type: 'string',
-              description: 'summary | deps | health | cost | shadow | skills (default summary)',
+              description:
+                'summary | deps | health | cost | shadow | skills | requests (default summary)',
             },
           },
           output: {
@@ -233,11 +249,13 @@ function apply(ctx) {
             snap.sectionOwners = attribution ? Object.fromEntries(attribution.table) : {};
             snap.toolOwners = attribution ? Object.fromEntries(attribution.toolTable) : {};
             snap.skillCatalog = skillCatalog;
+            snap.requestLedger = ledger ? Object.fromEntries(ledger.sessions) : {};
             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);
             if (args.view === 'skills') return skillCost(snap);
+            if (args.view === 'requests') return requestLedger(snap);
             return {
               plugins: snap.plugins.length,
               unhealthy: health(snap).unhealthy.length,

package/lib/model.js

@@ -377,6 +377,41 @@ function skillCost(snap) {
   };
 }
 
+/** F11: per-request ledger — one classified bill per LLM call, newest
+ * first, with prefix-stability and delta markers. The time axis the static
+ * cost view lacks. */
+function requestLedger(snap) {
+  const observed = snap.requestLedger;
+  if (!observed || Object.keys(observed).length === 0)
+    return { available: false, sessions: [], capturedAt: snap.capturedAt };
+  const sessions = Object.entries(observed)
+    .map(([sessionId, entries]) => ({
+      sessionId,
+      lastAt: entries[entries.length - 1]?.at ?? 0,
+      requests: entries
+        .slice()
+        .reverse()
+        .map((e, i, arr) => ({
+          seq: entries.length - i,
+          at: e.at,
+          purpose: e.purpose,
+          provider: e.provider,
+          model: e.model,
+          total: e.total,
+          system: e.system,
+          toolSchemas: e.toolSchemas,
+          history: e.history,
+          toolResults: e.toolResults,
+          toolResultRows: e.toolResultRows,
+          historyMessages: e.historyMessages,
+          prefixStable: e.prefixStable,
+          deltaTotal: e.deltaTotal,
+        })),
+    }))
+    .sort((a, b) => b.lastAt - a.lastAt);
+  return { available: true, sessions, capturedAt: snap.capturedAt };
+}
+
 module.exports = {
   replayLayers,
   attribute,
@@ -388,4 +423,5 @@ module.exports = {
   shadowing,
   contextCost,
   skillCost,
+  requestLedger,
 };

package/lib/panel.js

@@ -38,7 +38,7 @@ const PAGE = `<!doctype html>
 <div id="status"></div>
 <div id="content"></div>
 <script>
-const views = ['summary', 'health', 'deps', 'cost', 'shadow', 'skills'];
+const views = ['summary', 'health', 'deps', 'cost', 'shadow', 'skills', 'requests'];
 const esc = (s) => String(s ?? '').replace(/[&<>]/g, (c) => ({'&':'&amp;','<':'&lt;','>':'&gt;'}[c]));
 const escAttr = (s) => esc(s).replace(/"/g, '&quot;');
 
@@ -50,6 +50,7 @@ const INTRO = {
   cost: 'What every LLM request carries before your message: prompt sections + tool schemas, attributed to the plugin that registered each. "By plugin" is each plugin\\'s per-request context tax.',
   shadow: 'Same-name registrations. A service provided by two plugins means one silently wins — usually intended (an override), occasionally a conflict.',
   skills: 'What each skill costs: its catalog line rides every request once any model-invocable skill exists; its body is billed only when loaded. Pricing only — to enable/disable skills, use a skill manager.',
+  requests: 'One bill per LLM call, newest first: system + tool schemas + history + tool results. \u26a1 = the system/tools prefix matched the previous request (cache-friendly); \u2702 = the prefix changed. \u0394 is the total against the previous request.',
 };
 
 // Hover glossary: term -> plain-language meaning (native title tooltips).
@@ -69,6 +70,10 @@ const TIPS = {
   catalog: 'Tokens of this skill's line in the durable session catalog, carried on every request',
   body: 'Tokens of the full rendered skill body, billed per load and then resident in history',
   invocable: 'Whether the model may load this skill itself; user-only skills stay out of the catalog',
+  total: 'Estimated tokens of the whole request payload (~4 chars/token)',
+  history: 'Conversation messages (user + assistant), excluding tool results',
+  results: 'Tool-result messages, aggregated per tool below each row',
+  prefix: 'Whether system prompt + tool schemas were byte-identical to the previous request in this session',
 };
 const th = (h) => '<th' + (TIPS[h] ? ' title="' + escAttr(TIPS[h]) + '"' : '') + '>' + esc(h) + '</th>';
 const intro = (v) => '<p class="muted" style="margin:0 0 10px">' + INTRO[v] + '</p>';
@@ -181,6 +186,30 @@ const renderers = {
       + '</td><td>' + (s.modelInvocable ? '<span class="ok">yes</span>' : '<span class="muted">user-only</span>') + '</td></tr>'));
     return html;
   },
+  requests(d) {
+    if (!d.available) return '<p class="muted">no requests observed yet — send one agent message first</p>';
+    let html = '';
+    for (const session of d.sessions) {
+      html += '<h3 style="margin:12px 0 4px">session ' + esc(String(session.sessionId).slice(0, 12))
+        + ' <span class="muted">(' + session.requests.length + ' request(s))</span></h3>';
+      html += table(['#', 'when', 'purpose', 'total', 'system', 'tools', 'history', 'results', 'prefix', 'Δ'],
+        session.requests.map((r) => {
+          const when = new Date(r.at).toTimeString().slice(0, 8);
+          const purpose = r.purpose ?? 'chat';
+          const prefix = r.prefixStable === null ? '—' : r.prefixStable ? '⚡' : '✂';
+          const delta = r.deltaTotal === null ? '—'
+            : (r.deltaTotal >= 0 ? '+' : '') + r.deltaTotal;
+          const top = (r.toolResultRows ?? []).slice(0, 3).map((t) => esc(t.name) + ' ~' + t.tokens).join(', ');
+          return '<tr><td class="num">' + r.seq + '</td><td class="muted">' + when
+            + '</td><td>' + (purpose === 'chat' ? 'chat' : '<span class="muted">' + esc(purpose) + '</span>')
+            + '</td><td class="num">~' + r.total + '</td><td class="num">' + r.system
+            + '</td><td class="num">' + r.toolSchemas + '</td><td class="num">' + r.history
+            + '</td><td class="num" title="' + escAttr(top) + '">' + r.toolResults
+            + '</td><td>' + prefix + '</td><td class="num">' + delta + '</td></tr>';
+        }));
+    }
+    return html;
+  },
 };
 
 async function render() {

package/package.json

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