@bushizhanghan/dsh-context-budget 0.0.0-stage → 0.1.0

package/LICENSE

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

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# dsh-context-budget — 上下文预算审计（DSH 插件）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> 每一轮对话，模型都被重新喂一遍同一堆东西：system prompt、AGENTS.md、60+ 个技能的目录、几十个工具的 schema、运行时快照。
+> 它们逐字节相同，**模型不需要再知道一遍**。这个插件就是来量这件事的。
+
+在真实机器的会话日志上实测：一个 34 轮的会话，注入上下文 **256k token，其中 37.4%（95.8k）是逐字节重复的内容**。
+system prompt 被重发 6 遍（16.8k token 白付），skill catalog 被重发 3 遍（12.7k token 白付）。
+这不是压缩能解决的问题——压缩省的是历史，这是**固定开销在复利**。
+
+## 安装
+
+```sh
+dsh plugin --profile desktop add @bushizhanghan/dsh-context-budget
+```
+
+重启 DSH 后生效。**只读**：从不写你的会话日志，也不调 LLM——每个数字都能从日志里手算复核。
+
+## Agent 工具
+
+| 工具 | 作用 |
+|---|---|
+| `ctx_budget` | 审计单个会话：每轮注入构成（system / AGENTS.md / skill catalog / tools / runtime / team / history），以及逐字节重复的纯浪费 |
+| `ctx_budget_sweep` | 扫描所有会话，按浪费量排序，看哪段对话的固定开销最重 |
+| `ctx_budget_skills` | 技能目录治理：每轮要为 60+ 个技能的描述付多少 token，哪些该懒加载 |
+| `ctx_budget_tools` | 工具 schema 膨胀：哪个插件的工具定义每轮占用最多上下文 |
+
+## 分类口径
+
+| 类别 | 来源 |
+|---|---|
+| `system` | `system/message`：组装好的 system prompt，每轮重建 |
+| `agents` | `user/message` + `source.kind = agent-instructions`：AGENTS.md 等工作区指令 |
+| `skills` | `user/message` + `source.kind = skill-catalog`：`<system-reminder>` 里的技能目录 |
+| `tools` | `request/header.data.header.tools`：实际发出的工具 schema 数组 |
+| `runtime` | `runtime-context` / `time-context` / `model-selection` |
+| `team` | `agent-teams` / `agent-message` / `subagent-settled` |
+| `history` | `user` / `compact-checkpoint`：真实对话与压缩检查点 |
+| `other` | 未识别的新注入面——**不静默丢弃**，这样未来 DSH 新增注入面会自己冒出来 |
+
+## 浪费判定
+
+一个块在第 N 轮和第 N+k 轮签名相同（长度 + 头 32 字符 + 尾 32 字符）即为重复。
+**第一次出现不是浪费**（模型总得看一遍），之后每次都是。历史不计入浪费——它是合法累积的。
+
+## 它在真实数据上发现了什么
+
+```
+context budget · session-88fbc2a8…: 34 turns, 68 request(s)
+  injected context total (est): 256079 tok
+  repeated unchanged content: 95792 tok (37.4% of injected)
+
+composition (est tokens, summed over turns)
+  system       105034  (33 block(s))
+  skills        63633  (16 block(s))
+  history       36098  (170 block(s))
+  tools         19486  (1 block(s))
+  team          18320  (40 block(s))
+  runtime       10765  (135 block(s))
+  agents         2355  (3 block(s))
+
+tool schema inflation (est tokens per turn)
+  plugin:agent-teams          5170  (18 tool(s))
+  tool:code_review            2325  (6 tool(s))
+  mcp:wincu                   2284  (10 tool(s))
+
+skill catalog: 59 skills, 5022 est tok per turn
+  academic-research-suite     133 tok  used 0x
+  scientific-toolkit-skill    133 tok  used 0x
+  wechat-miniprogram-design   133 tok  used 0x
+```
+
+三条可执行的结论：
+
+1. **AgentTeams 插件 18 个工具 = 5170 token/轮**，是最大的单一固定开销；其中多数在非团队会话里根本用不到。
+2. **59 个技能目录 = 5022 token/轮**，而实测整台机器被调用过的技能只有 7 个。最贵的 10 个技能从未被调用，却每轮全价付费。
+3. **system prompt 每轮 3370 token**，跨轮几乎不变——唯一真正在变的是 GUI URL 和工作目录两行。
+
+## 设计取舍
+
+- **先读日志再写规则。** 第一版假设会话日志是 UTF-8，在真实机器上 94 个会话全部解析失败——GUI 启动的会话是 **UTF-16LE 带 BOM**。现在按 BOM 嗅探，两种编码都见过。
+- **目录层级是 `<workspace>/session-<uuid>/`**，根和会话目录之间隔着一层 workspace，平铺扫描根目录什么都找不到。向下走两层。
+- **CJK 按 1 字符 = 1 token 算。** 这台机器上的会话以中文为主，按 4 字符 = 1 token 会把中文提示低估约 4 倍。
+- **`estimateTokens` 是估计值，报告里一律标 `est`。** 这个插件要的是**比例**——同一除数在比值里抵消。需要精确数字时用 `request/context` 的 `contextWindow` 做分母。
+- **懒加载规则故意保守**：只标记"本轮从未调用且描述 ≥ 60 token"的技能。用过一次的技能永不标记；没有使用信号的技能不猜测它已死（它可能在别的会话里被用）。
+- **未识别的 `source.kind` 归入 `other` 而不是丢弃**，否则未来 DSH 新增注入面会让审计数字悄悄变小而没人发现。
+
+## 测试
+
+```sh
+node --test test/
+```
+
+`test/engine.test.mjs` 一条规则一个测试（token 估计、CJK、分类映射、签名、重复判定、技能治理、工具分组、空会话不除零）。
+`test/integration.test.mjs` 用假 `ctx = { tools: { register } }` 启动插件，驱动全部 4 个工具打真实会话日志，
+并断言反向情况：不存在的会话/根目录必须返回 `ok: false`。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# dsh bundle layer: mount the context-budget plugin (lib/index.js).
+- insert:
+    - id: context-budget
+      name: '@bushizhanghan/dsh-context-budget'

package/lib/engine.js

@@ -0,0 +1,590 @@
+// dsh-context-budget engine.
+//
+// The question this engine answers: of the context a model is handed on each
+// turn, how much of it does the model not need to know?
+//
+// Established by reading real session logs on this machine, not by guessing:
+//
+//   1. A DSH session log (session.v4.jsonl.zstd) is UTF-16LE when the session
+//      was started by the GUI and UTF-8 otherwise. Both shapes exist in the
+//      same sessions tree, so the loader sniffs the BOM instead of assuming.
+//   2. Per-turn injected context is spread over four event kinds:
+//        - system/message          the assembled system prompt (identity,
+//                                  team protocol, tool-usage rules, runtime
+//                                  facts). Rebuilt every turn.
+//        - user/message            injected instruction blocks, tagged by
+//                                  data.source.kind: agent-instructions
+//                                  (AGENTS.md), skill-catalog, runtime-context,
+//                                  time-context, agent-teams, model-selection, …
+//        - request/header          the tool schema array actually sent, with a
+//                                  data.reason (initial / change / resume).
+//        - request/context         provider/model/contextWindow, for the
+//                                  denominator of the budget.
+//   3. History (assistant/tool output) grows per turn; everything above is
+//      either rebuilt or resent byte-identically. So the audit measures, per
+//      turn: composition (how the budget splits), repetition (the same bytes
+//      resent), and provenance (which surface owns each byte).
+//
+// Pure functions, no ctx, no I/O: every function here takes data it was handed.
+// The session reader lives in engine.js too because it has no host
+// dependencies beyond `zstd` on PATH, which is the same dependency the other
+// audit plugins in this profile use.
+import { execFileSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+
+// =====================================================================
+// Session log reading
+// =====================================================================
+
+/**
+ * Load a session.v4.jsonl.zstd into ordered events.
+ *
+ * Encoding is sniffed, not assumed: GUI-started sessions are UTF-16LE with a
+ * BOM, CLI-started ones are plain UTF-8. Reading a UTF-16LE file as UTF-8
+ * yields a file where every JSON line fails to parse — which is exactly the
+ * bug this sniff prevents.
+ */
+export function loadSession(file) {
+  if (!file || !existsSync(file)) return { events: [], error: `not found: ${file}` }
+  let text
+  try {
+    const buf = execFileSync('zstd', ['-dc', file], { maxBuffer: 512 * 1024 * 1024 })
+    text = buf[0] === 0xff && buf[1] === 0xfe ? buf.toString('utf16le').slice(1) : buf.toString('utf8')
+  } catch (e) {
+    return { events: [], error: `cannot decompress (is zstd installed?): ${String(e.message).slice(0, 120)}` }
+  }
+  const events = []
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue
+    try {
+      events.push(JSON.parse(line))
+    } catch {}
+  }
+  events.sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0))
+  return { events, error: null }
+}
+
+// =====================================================================
+// Token estimation
+// =====================================================================
+
+/**
+ * Rough token count for a piece of text.
+ *
+ * Deliberately simple and monotone: 1 token ≈ 4 characters. It is an estimate,
+ * so every report that uses it says "est" — the point of this plugin is the
+ * *ratio* between surfaces and turns, and a constant divisor cancels out of a
+ * ratio. The one real-world correction is CJK, where a single character is a
+ * token on its own: counting CJK as 4 chars would understate Chinese-heavy
+ * prompts (this machine's sessions are mostly Chinese) by ~4x.
+ */
+export function estimateTokens(text) {
+  if (!text) return 0
+  const s = String(text)
+  let cjk = 0
+  for (const ch of s) {
+    const c = ch.codePointAt(0)
+    if ((c >= 0x2e80 && c <= 0x9fff) || (c >= 0xf900 && c <= 0xfaff) || (c >= 0xff00 && c <= 0xffef) || (c >= 0x3000 && c <= 0x303f)) cjk += 1
+  }
+  return Math.max(1, Math.ceil((s.length - cjk) / 4 + cjk))
+}
+
+/** Token estimate for a measured character count of ASCII-ish text (JSON schemas, ASCII lines). */
+export function tokensForChars(chars) {
+  const n = Number(chars)
+  if (!Number.isFinite(n) || n <= 0) return 0
+  return Math.ceil(n / 4)
+}
+
+// =====================================================================
+// Classification: which surface owns a block of injected text
+// =====================================================================
+
+// Category constants. Order matters only for stable report output.
+export const CATEGORIES = {
+  SYSTEM: 'system',
+  AGENTS: 'agents',
+  SKILLS: 'skills',
+  TOOLS: 'tools',
+  RUNTIME: 'runtime',
+  TEAM: 'team',
+  HISTORY: 'history',
+  OTHER: 'other',
+}
+
+/** user/message source.kind → category. Anything unlisted lands in OTHER. */
+const USER_KIND_CATEGORY = {
+  'agent-instructions': CATEGORIES.AGENTS,
+  'skill-catalog': CATEGORIES.SKILLS,
+  'runtime-context': CATEGORIES.RUNTIME,
+  'time-context': CATEGORIES.RUNTIME,
+  'agent-teams': CATEGORIES.TEAM,
+  'agent-message': CATEGORIES.TEAM,
+  'subagent-settled': CATEGORIES.TEAM,
+  'model-selection': CATEGORIES.RUNTIME,
+  user: CATEGORIES.HISTORY,
+  goal: CATEGORIES.OTHER,
+  'tool-jobs': CATEGORIES.OTHER,
+  'dsh-rewind': CATEGORIES.OTHER,
+  'user-approval': CATEGORIES.OTHER,
+  'compact-checkpoint': CATEGORIES.HISTORY,
+}
+
+/** Which user/message kinds are re-injected standing instructions rather than turns of conversation. */
+export function categoryOfUserKind(kind) {
+  return USER_KIND_CATEGORY[kind] ?? CATEGORIES.OTHER
+}
+
+/** Total character length of a message event's content. */
+export function contentChars(content) {
+  if (!Array.isArray(content)) return typeof content === 'string' ? content.length : 0
+  let n = 0
+  for (const p of content) {
+    if (typeof p === 'string') n += p.length
+    else if (p && typeof p === 'object' && typeof p.text === 'string') n += p.text.length
+  }
+  return n
+}
+
+/**
+ * Joined text of a message event's content.
+ *
+ * Every part that carries `text` counts, including `reasoning` parts: they are
+ * sent to the model, so they spend budget whether or not they are instructions.
+ */
+export function contentText(content) {
+  if (!Array.isArray(content)) return typeof content === 'string' ? content : ''
+  const out = []
+  for (const p of content) {
+    if (typeof p === 'string') out.push(p)
+    else if (p && typeof p === 'object' && typeof p.text === 'string') out.push(p.text)
+  }
+  return out.filter((s) => s !== '').join('\n')
+}
+
+// =====================================================================
+// Per-turn budget model
+// =====================================================================
+
+/**
+ * Build the per-turn budget model of a session.
+ *
+ * For each turn we record the bytes of every injected block, tagged with the
+ * category that owns it, plus a stable signature (first 64 chars + length) so
+ * two blocks can be compared for byte-identity without keeping the whole text
+ * in memory across turns.
+ *
+ * Returns { turns, categories, requests, toolSets } where `turns` is ordered by
+ * turn number.
+ */
+export function buildTurns(events) {
+  const turnOf = (ev) => (ev && ev.data && typeof ev.data.turn === 'number' ? ev.data.turn : null)
+  const byTurn = new Map()
+  const ensure = (n) => {
+    if (!byTurn.has(n)) byTurn.set(n, { turn: n, blocks: [], requests: 0, historyChars: 0, historyTokens: 0 })
+    return byTurn.get(n)
+  }
+  const push = (turn, block) => {
+    const t = ensure(turn)
+    t.blocks.push(block)
+  }
+
+  // system/message carries the assembled system prompt, but only inside its
+  // first turn is it new; the same text is resent every turn after. We record
+  // it per turn with a signature so the repetition analysis can prove it.
+  for (const ev of events) {
+    const t = String(ev.type || '')
+    const turn = turnOf(ev)
+    if (t === 'system/message') {
+      const text = contentText(ev.data?.message?.content)
+      push(turn ?? 0, {
+        category: CATEGORIES.SYSTEM,
+        chars: text.length,
+        tokens: estimateTokens(text),
+        signature: signature(text),
+        seq: ev.seq,
+        label: 'system prompt',
+      })
+    } else if (t === 'user/message') {
+      const d = ev.data || {}
+      const text = contentText(d.content)
+      const kind = d.source?.kind ?? 'user'
+      const cat = categoryOfUserKind(kind)
+      if (turn == null) {
+        // pre-turn injection (the first user message of a session)
+        push(0, block(kind, cat, text, ev.seq))
+        continue
+      }
+      if (cat === CATEGORIES.HISTORY) {
+        const t = ensure(turn)
+        t.historyChars = (t.historyChars || 0) + text.length
+        t.historyTokens = (t.historyTokens || 0) + estimateTokens(text)
+        continue
+      }
+      push(turn, block(kind, cat, text, ev.seq))
+    } else if (t === 'request/header') {
+      const tools = ev.data?.header?.tools
+      if (Array.isArray(tools)) {
+        const t = ensure(turn ?? 0)
+        t.requests += 1
+        // Keep the last (largest) schema set sent this turn: a request that
+        // changed its tools mid-turn is rare, and the newest set is the one
+        // the model was actually shown.
+        t.toolNames = tools.map((x) => x.name)
+        t.toolChars = JSON.stringify(tools).length
+        t.toolTokens = estimateTokens(JSON.stringify(tools))
+        t.toolSignature = signature(tools.map((x) => `${x.name}:${JSON.stringify(x.parameters ?? {})}`).join('|'))
+        t.reason = ev.data.reason ?? null
+      }
+    }
+  }
+
+  const turns = [...byTurn.values()].sort((a, b) => a.turn - b.turn)
+  return turns
+}
+
+function block(kind, category, text, seq) {
+  return {
+    kind,
+    category,
+    chars: text.length,
+    tokens: estimateTokens(text),
+    signature: signature(text),
+    seq,
+    label: labelFor(kind, text),
+  }
+}
+
+function labelFor(kind, text) {
+  if (kind === 'agent-instructions') {
+    const m = text.match(/Instructions from:\s*([^\n]+)/)
+    return m ? `instructions · ${m[1].trim()}` : 'instructions'
+  }
+  if (kind === 'skill-catalog') return 'skill catalog'
+  if (kind === 'runtime-context') return 'runtime context'
+  if (kind === 'time-context') return 'time context'
+  if (kind === 'model-selection') return 'model change notice'
+  if (kind === 'agent-teams' || kind === 'agent-message') return `team · ${kind}`
+  return kind
+}
+
+/** Stable short identity of a text: length + head + tail. Cheap and collision-safe enough for repetition detection. */
+export function signature(text) {
+  const s = String(text ?? '')
+  if (s.length === 0) return 'empty'
+  return `${s.length}:${s.slice(0, 32)}|${s.slice(-32)}`
+}
+
+/**
+ * Aggregate a turn list into a composition table.
+ *
+ * Returns { categories: { <cat>: {tokens, blocks} }, totalTokens, perTurn }.
+ */
+export function composition(turns) {
+  const categories = {}
+  let total = 0
+  const perTurn = []
+  const bump = (cat, tokens) => {
+    categories[cat] = categories[cat] || { tokens: 0, blocks: 0 }
+    categories[cat].tokens += tokens
+    categories[cat].blocks += 1
+  }
+  for (const t of turns) {
+    const row = { turn: t.turn, categories: {}, total: 0 }
+    for (const b of t.blocks) {
+      row.categories[b.category] = (row.categories[b.category] || 0) + b.tokens
+      bump(b.category, b.tokens)
+    }
+    if (t.toolTokens) {
+      row.categories[CATEGORIES.TOOLS] = (row.categories[CATEGORIES.TOOLS] || 0) + t.toolTokens
+      bump(CATEGORIES.TOOLS, t.toolTokens)
+    }
+    if (t.historyTokens) {
+      row.categories[CATEGORIES.HISTORY] = (row.categories[CATEGORIES.HISTORY] || 0) + t.historyTokens
+      bump(CATEGORIES.HISTORY, t.historyTokens)
+    }
+    row.total = Object.values(row.categories).reduce((a, b) => a + b, 0)
+    total += row.total
+    perTurn.push(row)
+  }
+  return { categories, totalTokens: total, perTurn }
+}
+
+// =====================================================================
+// Repetition: the pure-waste detector
+// =====================================================================
+
+/**
+ * Find injected content that is resent byte-identically.
+ *
+ * A block that appears in turn N and again in turn N+k with the same signature
+ * costs the same tokens again and teaches the model nothing new: that is the
+ * pure waste this plugin exists to quantify. The first occurrence is not waste
+ * (the model has to see it once); every later occurrence is.
+ *
+ * Returns { repeated: [{category,label,occurrences,tokensEach,wasteTokens,firstTurn,lastTurn}], wasteTokens, totalTokens }.
+ */
+export function detectRepetition(turns) {
+  const seen = new Map()
+  const order = []
+  for (const t of turns) {
+    for (const b of t.blocks) {
+      const key = `${b.category}\u0000${b.signature}`
+      if (!seen.has(key)) {
+        seen.set(key, { category: b.category, label: b.label, tokensEach: b.tokens, turns: [] })
+        order.push(key)
+      }
+      const rec = seen.get(key)
+      rec.turns.push(t.turn)
+    }
+  }
+  const repeated = []
+  let waste = 0
+  let total = 0
+  for (const key of order) {
+    const rec = seen.get(key)
+    total += rec.tokensEach * rec.turns.length
+    if (rec.turns.length > 1) {
+      const wasteTokens = rec.tokensEach * (rec.turns.length - 1)
+      waste += wasteTokens
+      repeated.push({
+        category: rec.category,
+        label: rec.label,
+        occurrences: rec.turns.length,
+        tokensEach: rec.tokensEach,
+        wasteTokens,
+        firstTurn: rec.turns[0],
+        lastTurn: rec.turns[rec.turns.length - 1],
+      })
+    }
+  }
+  repeated.sort((a, b) => b.wasteTokens - a.wasteTokens)
+  return { repeated, wasteTokens: waste, totalTokens: total }
+}
+
+/**
+ * Per-turn waste: how much of a turn's injected context is a repeat of
+ * something the model has already been sent.
+ *
+ * This is the number that matters for "why is this turn expensive": history is
+ * legitimately cumulative, but a system prompt, a skill catalog and a tool set
+ * resent unchanged are the same bytes paying rent again.
+ */
+export function perTurnWaste(turns) {
+  const seen = new Set()
+  const out = []
+  for (const t of turns) {
+    let repeatTokens = 0
+    let freshTokens = 0
+    for (const b of t.blocks) {
+      const key = `${b.category}\u0000${b.signature}`
+      if (seen.has(key)) repeatTokens += b.tokens
+      else {
+        freshTokens += b.tokens
+        seen.add(key)
+      }
+    }
+    out.push({ turn: t.turn, repeatTokens, freshTokens, requests: t.requests })
+  }
+  return out
+}
+
+// =====================================================================
+// Skill catalog
+// =====================================================================
+
+/** One skill line in a skill-catalog block: `- \`name\`: description`. */
+export function parseSkillCatalog(text) {
+  if (!text) return []
+  const out = []
+  for (const line of String(text).split('\n')) {
+    const m = line.match(/^- `([^`]+)`:\s*(.*)$/)
+    if (!m) continue
+    out.push({ name: m[1], description: m[2], chars: line.length })
+  }
+  return out
+}
+
+/**
+ * Skill-catalog governance.
+ *
+ * The catalog is injected as one block per turn, so every installed skill's
+ * description is paid for on every turn whether or not it is ever used. This
+ * measures that standing cost and ranks skills by description length, because
+ * length is the only signal available without an LLM: a 500-character
+ * description for a skill that is invoked once a month is a bad trade.
+ *
+ * `usage` maps skill name → number of `skill` tool calls observed in the
+ * session, so the report can separate "big and used" from "big and dead".
+ */
+/**
+ * Rank skills by the tokens their description costs on every turn.
+ *
+ * `skills` entries carry either `chars` (a measured line length, as produced by
+ * parseSkillCatalog) or just `description` (as supplied by a caller that has
+ * the catalog but not the line), so the cost is computed from whichever is
+ * present. `usage` maps skill name → number of `skill` tool calls observed, so
+ * the report can separate "big and used" from "big and dead".
+ */
+export function rankSkills(skills, usage = {}) {
+  return skills
+    .map((s) => {
+      const chars = typeof s.chars === 'number' ? s.chars : String(s.description ?? '').length
+      return {
+        name: s.name,
+        chars,
+        tokensPerTurn: tokensForChars(chars),
+        uses: Number(usage[s.name] || 0),
+      }
+    })
+    .sort((a, b) => b.tokensPerTurn - a.tokensPerTurn)
+}
+
+/**
+ * Which skills should be lazy-loaded.
+ *
+ * Rule: a skill whose description costs at least `minTokens` (default 60) on
+ * every turn and was never invoked in this session is a lazy-load candidate.
+ * That is deliberately conservative — it never flags a skill the session leaned
+ * on, and it ignores skills with no usage signal at all rather than guessing
+ * that an unused-looking skill is dead (it may be used in another session).
+ */
+export function lazyLoadCandidates(ranked, { minTokens = 60 } = {}) {
+  return ranked.filter((s) => s.uses === 0 && s.tokensPerTurn >= minTokens)
+}
+
+// =====================================================================
+// Tool schema inflation
+// =====================================================================
+
+/**
+ * Attribute tool-schema bytes to a plugin group.
+ *
+ * Tool names carry their owner: `mcp__<server>__<tool>` is an MCP server,
+ * `agent_teams_*` / `team_task_*` are the AgentTeams plugin, `dsh_ppt_*` is the
+ * ppt plugin, and everything else is a built-in. The grouping is a prefix rule,
+ * not a registry lookup, so it works on any machine without a plugin list.
+ */
+export function toolGroup(name) {
+  const n = String(name || '')
+  if (n.startsWith('mcp__')) {
+    const parts = n.split('__')
+    return `mcp:${parts[1] || 'unknown'}`
+  }
+  if (n.startsWith('agent_teams_') || n.startsWith('team_task_')) return 'plugin:agent-teams'
+  if (n.startsWith('dsh_ppt_')) return 'plugin:ppt-fusion'
+  if (n.startsWith('ctx_budget')) return 'plugin:context-budget'
+  const twoWords = n.split('_').slice(0, 2).join('_')
+  if (twoWords && twoWords !== n) return `tool:${twoWords}`
+  return `tool:${n || 'unknown'}`
+}
+
+/** Rank tool groups by the tokens their schemas cost per turn. */
+export function toolInflation(tools) {
+  const groups = new Map()
+  let total = 0
+  for (const t of tools || []) {
+    const chars = JSON.stringify(t).length
+    const g = toolGroup(t.name)
+    if (!groups.has(g)) groups.set(g, { group: g, tools: 0, chars: 0 })
+    const rec = groups.get(g)
+    rec.tools += 1
+    rec.chars += chars
+    total += chars
+  }
+  const rows = [...groups.values()].map((r) => ({ ...r, tokensPerTurn: tokensForChars(r.chars) }))
+  rows.sort((a, b) => b.tokensPerTurn - a.tokensPerTurn)
+  return { rows, totalChars: total, totalTokens: tokensForChars(total) }
+}
+
+// =====================================================================
+// Whole-session audit
+// =====================================================================
+
+/**
+ * Audit one session's context budget.
+ *
+ * Returns { ok, session, turns, composition, repetition, perTurn, skills,
+ * tools, report }.
+ */
+export function auditSession(events, { usage = {}, skills = [], tools = [] } = {}) {
+  const turns = buildTurns(events)
+  const comp = composition(turns)
+  const rep = detectRepetition(turns)
+  const perTurn = perTurnWaste(turns)
+  const inflated = toolInflation(tools)
+  const ranked = rankSkills(skills, usage)
+  const lazy = lazyLoadCandidates(ranked)
+
+  const turnCount = turns.length
+  const requests = turns.reduce((a, t) => a + t.requests, 0)
+  const wasteRatio = comp.totalTokens > 0 ? rep.wasteTokens / comp.totalTokens : 0
+  // The model actually used comes from the request the host sent, which is the
+  // authoritative record; model/selection is only the last UI change.
+  const model =
+    events.find((e) => e.type === 'request/header')?.data?.header?.config?.model ??
+    events.find((e) => e.type === 'model/selection')?.data?.model ??
+    null
+  const contextWindow = events.find((e) => e.type === 'request/context')?.data?.contextWindow ?? null
+
+  return {
+    ok: true,
+    session: {
+      events: events.length,
+      turns: turnCount,
+      requests,
+      model,
+      contextWindow,
+      cwd: events.find((e) => e.type === 'session')?.data?.cwd ?? null,
+    },
+    turns,
+    composition: comp,
+    repetition: rep,
+    perTurn,
+    skills: { ranked, lazy, total: skills.length, tokensPerTurn: ranked.reduce((a, s) => a + s.tokensPerTurn, 0) },
+    tools: inflated,
+    wasteRatio,
+  }
+}
+
+/** Render the human-readable report used as the tool's text output. */
+export function renderReport(result, { title }) {
+  const L = []
+  const head = title ? `${title}: ` : ''
+  L.push('')
+  L.push(`${head}${result.session.turns} turns, ${result.session.requests} request(s)`)
+  L.push(`  injected context total (est): ${result.composition.totalTokens} tok`)
+  L.push(`  repeated unchanged content: ${result.repetition.wasteTokens} tok (${(result.wasteRatio * 100).toFixed(1)}% of injected)`)
+  L.push('')
+  L.push('composition (est tokens, summed over turns)')
+  const cats = Object.entries(result.composition.categories).sort((a, b) => b[1].tokens - a[1].tokens)
+  for (const [cat, v] of cats) {
+    L.push(`  ${cat.padEnd(10)} ${String(v.tokens).padStart(8)}  (${v.blocks} block(s))`)
+  }
+  if (result.repetition.repeated.length) {
+    L.push('')
+    L.push('repeated unchanged content (waste)')
+    for (const r of result.repetition.repeated.slice(0, 8)) {
+      L.push(`  ${r.label}  ${r.occurrences}x  ${r.tokensEach} tok each  = ${r.wasteTokens} tok waste`)
+    }
+  }
+  if (result.tools.rows.length) {
+    L.push('')
+    L.push('tool schema inflation (est tokens per turn)')
+    for (const r of result.tools.rows.slice(0, 8)) {
+      L.push(`  ${r.group.padEnd(24)} ${String(r.tokensPerTurn).padStart(7)}  (${r.tools} tool(s))`)
+    }
+  }
+  if (result.skills.ranked.length) {
+    L.push('')
+    L.push(`skill catalog: ${result.skills.total} skills, ${result.skills.tokensPerTurn} est tok per turn`)
+    for (const s of result.skills.ranked.slice(0, 6)) {
+      L.push(`  ${s.name.padEnd(30)} ${String(s.tokensPerTurn).padStart(5)} tok  used ${s.uses}x`)
+    }
+    if (result.skills.lazy.length) {
+      L.push(`  lazy-load candidates: ${result.skills.lazy.slice(0, 10).map((s) => s.name).join(', ')}`)
+    }
+  }
+  L.push('')
+  return L.join('\n')
+}

package/lib/index.js

@@ -0,0 +1,300 @@
+// dsh-context-budget: agent tools over the per-turn context budget model.
+//
+// Four tools, one per question an operator actually asks:
+//
+//   ctx_budget        what is this turn's context made of, and how much of it
+//                     is the same bytes as last turn?
+//   ctx_budget_sweep  every session, ranked by waste.
+//   ctx_budget_skills the standing cost of the skill catalog, and which
+//                     skills should be lazy-loaded.
+//   ctx_budget_tools  which plugin's tool schemas cost the most per turn.
+//
+// Deterministic throughout: no LLM is called, so every number here can be
+// recomputed by hand from the session log.
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { existsSync, readdirSync } from 'node:fs'
+import {
+  auditSession,
+  buildTurns,
+  loadSession,
+  parseSkillCatalog,
+  renderReport,
+  toolInflation,
+  tokensForChars,
+} from './engine.js'
+
+export const name = 'context-budget'
+export const inject = ['tools']
+
+const Config = {
+  // Where DSH keeps session logs.
+  sessionsDir: '',
+  // Cap the number of sessions a sweep will read, so a large history cannot
+  // hang the tool. Override with a bigger number when you want the full sweep.
+  maxSessions: 30,
+}
+
+/** Resolve the sessions dir: explicit arg, config, or the default per-profile layout. */
+function resolveSessionsDir(dir) {
+  if (dir) return dir
+  if (Config.sessionsDir) return Config.sessionsDir
+  return join(homedir(), '.dsh', 'sessions')
+}
+
+/**
+ * Every session log under a sessions root.
+ *
+ * The layout is `<sessions>/<workspace-slug>/session-<uuid>/session.v4.jsonl.zstd`
+ * — a workspace level sits between the root and the session dirs, so a flat
+ * scan of the root finds nothing. Walk down to the session dirs and keep the
+ * workspace slug with each row.
+ */
+function listSessions(root, limit) {
+  if (!existsSync(root)) return []
+  const out = []
+  const walk = (dir, workspace, depth) => {
+    if (depth > 2 || out.length > (typeof limit === 'number' ? limit : 500)) return
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue
+      const full = join(dir, e.name)
+      const log = join(full, 'session.v4.jsonl.zstd')
+      if (existsSync(log)) {
+        out.push({ name: e.name, workspace, file: log })
+        continue
+      }
+      walk(full, e.name, depth + 1)
+    }
+  }
+  walk(root, '(root)', 0)
+  return typeof limit === 'number' ? out.slice(0, limit) : out
+}
+
+/** Accept a session path, a session dir, or a bare session id. */
+function resolveSessionFile(arg) {
+  if (!arg) return null
+  if (existsSync(arg) && arg.endsWith('.zstd')) return arg
+  const direct = join(arg, 'session.v4.jsonl.zstd')
+  if (existsSync(direct)) return direct
+  const byId = listSessions(resolveSessionsDir('')).find((s) => s.name === arg || s.name === `session-${arg}`)
+  return byId ? byId.file : null
+}
+
+/**
+ * The extra inputs the pure engine cannot see in the turn model: the raw skill
+ * catalog text and the tool schema array actually sent. Both come from the same
+ * events the engine already read, so no second pass over the file is needed.
+ */
+function extractInputs(events) {
+  let skills = []
+  let tools = []
+  let catalogSeen = null
+  for (const ev of events) {
+    if (ev.type === 'user/message' && ev.data?.source?.kind === 'skill-catalog' && catalogSeen === null) {
+      catalogSeen = ev.data.content.map((c) => c.text || '').join('\n')
+      skills = parseSkillCatalog(catalogSeen)
+    }
+    if (ev.type === 'request/header' && Array.isArray(ev.data?.header?.tools) && tools.length === 0) {
+      tools = ev.data.header.tools
+    }
+  }
+  return { skills, tools }
+}
+
+/** How many times each skill was actually invoked, from `skill` tool calls. */
+function extractSkillUsage(events) {
+  const usage = {}
+  for (const ev of events) {
+    if (ev.type !== 'tool/call' || ev.data?.name !== 'skill') continue
+    let args = {}
+    try {
+      args = JSON.parse(ev.data.arguments || '{}')
+    } catch {}
+    const n = args?.name
+    if (n) usage[n] = (usage[n] || 0) + 1
+  }
+  return usage
+}
+
+export function apply(ctx, config = {}) {
+  const cfg = { ...Config, ...config }
+  const OUTPUT_SCHEMA = { type: 'json' }
+  const outRender = (_args, value) => [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }]
+
+  const tools = [
+    {
+      name: 'ctx_budget',
+      description:
+        'Audit how one session spends its per-turn context budget: break down each turn into the surfaces that inject it (system prompt, AGENTS.md instructions, skill catalog, tool schemas, runtime context, team messages, history), then measure how much of it is the same content resent byte-identically — the part the model does not need to be told again. Also reports the model and context window for scale. Deterministic, no LLM. Returns {ok, session, composition, repetition, perTurn, skills, tools, wasteRatio, report}.',
+      parameters: {
+        type: 'object',
+        properties: {
+          session: { type: 'string', description: 'Path to a session.v4.jsonl.zstd file, a session directory, or a session id. Omit to audit the newest session.' },
+          dir: { type: 'string', description: 'Sessions root used to resolve a bare session id, and to pick the newest session when none is given. Defaults to ~/.dsh/sessions.' },
+        },
+      },
+      async execute(args) {
+        const root = resolveSessionsDir(args.dir)
+        let file = args.session ? resolveSessionFile(args.session) : null
+        if (args.session && !file) return { ok: false, error: `no session.v4.jsonl.zstd for ${args.session}` }
+        if (!file) {
+          const newest = listSessions(root, cfg.maxSessions).sort((a, b) => b.name.localeCompare(a.name))[0]
+          if (!newest) return { ok: false, error: `no sessions found under ${root}` }
+          file = newest.file
+        }
+        const { events, error } = loadSession(file)
+        if (error) return { ok: false, error }
+        if (events.length === 0) return { ok: false, error: 'session log is empty' }
+        const { skills, tools: toolSchemas } = extractInputs(events)
+        const result = auditSession(events, { skills, tools: toolSchemas, usage: extractSkillUsage(events) })
+        result.session.file = file
+        result.session.workspace = file.split(/[\\/]/).slice(-3, -2)[0] ?? null
+        result.report = renderReport(result, { title: `context budget · ${file}` })
+        return result
+      },
+    },
+    {
+      name: 'ctx_budget_sweep',
+      description:
+        'Sweep every session under a sessions root and rank them by how much of their injected context is repeated unchanged content, so the worst offenders are the first ones you look at. Read-only; a big history is capped by `limit` (default 30 newest). Returns {ok, sessions:[{name,workspace,turns,injectedTokens,wasteTokens,wasteRatio,topSurface}], totals}.',
+      parameters: {
+        type: 'object',
+        properties: {
+          dir: { type: 'string', description: 'Sessions root. Defaults to ~/.dsh/sessions.' },
+          limit: { type: 'integer', description: 'Max sessions to read (default 30).' },
+        },
+      },
+      async execute(args) {
+        const root = resolveSessionsDir(args.dir)
+        const sessions = listSessions(root, Math.max(1, Number(args.limit) || cfg.maxSessions))
+        if (sessions.length === 0) return { ok: false, error: `no sessions found under ${root}` }
+        const rows = []
+        for (const s of sessions) {
+          const { events, error } = loadSession(s.file)
+          if (error || events.length === 0) continue
+          const turns = buildTurns(events)
+          if (turns.length === 0) continue
+          const result = auditSession(events, extractInputs(events))
+          const top = Object.entries(result.composition.categories).sort((a, b) => b[1].tokens - a[1].tokens)[0]
+          rows.push({
+            name: s.name,
+            workspace: s.workspace,
+            turns: result.session.turns,
+            injectedTokens: result.composition.totalTokens,
+            wasteTokens: result.repetition.wasteTokens,
+            wasteRatio: result.wasteRatio,
+            topSurface: top ? `${top[0]} ${top[1].tokens}` : null,
+          })
+        }
+        rows.sort((a, b) => b.wasteTokens - a.wasteTokens)
+        const totals = rows.reduce(
+          (acc, r) => ({ injectedTokens: acc.injectedTokens + r.injectedTokens, wasteTokens: acc.wasteTokens + r.wasteTokens, turns: acc.turns + r.turns }),
+          { injectedTokens: 0, wasteTokens: 0, turns: 0 },
+        )
+        return { ok: true, sessions: rows, totals }
+      },
+    },
+    {
+      name: 'ctx_budget_skills',
+      description:
+        'Skill-catalog governance: how many tokens of skill descriptions the model reads on every single turn, ranked by cost, and which skills should be lazy-loaded (expensive to describe, rarely invoked). With 60+ skills installed the catalog is one of the largest standing costs in the prompt, and it is paid whether or not a skill is ever used. Returns {ok, skills:[{name,tokensPerTurn,uses}], tokensPerTurn, lazyLoad, turns}.',
+      parameters: {
+        type: 'object',
+        properties: {
+          session: { type: 'string', description: 'Path to a session.v4.jsonl.zstd file, a session directory, or a session id. Omit to audit the newest session.' },
+          dir: { type: 'string', description: 'Sessions root used to resolve a bare session id and to pick the newest session. Defaults to ~/.dsh/sessions.' },
+          maxSkills: { type: 'integer', description: 'How many skills to list at most (default 40).' },
+        },
+      },
+      async execute(args) {
+        const root = resolveSessionsDir(args.dir)
+        let file = args.session ? resolveSessionFile(args.session) : null
+        if (args.session && !file) return { ok: false, error: `no session.v4.jsonl.zstd for ${args.session}` }
+        if (!file) {
+          const newest = listSessions(root, cfg.maxSessions).sort((a, b) => b.name.localeCompare(a.name))[0]
+          if (!newest) return { ok: false, error: `no sessions found under ${root}` }
+          file = newest.file
+        }
+        const { events, error } = loadSession(file)
+        if (error) return { ok: false, error }
+        const { skills } = extractInputs(events)
+        if (skills.length === 0) return { ok: false, error: 'no skill catalog found in this session' }
+        const usage = extractSkillUsage(events)
+        const ranked = skills
+          .map((s) => ({ name: s.name, chars: s.chars, tokensPerTurn: tokensForChars(s.chars), uses: usage[s.name] || 0 }))
+          .sort((a, b) => b.tokensPerTurn - a.tokensPerTurn)
+        const max = Math.max(1, Number(args.maxSkills) || 40)
+        const lazy = ranked.filter((s) => s.uses === 0 && s.tokensPerTurn >= 60)
+        return {
+          ok: true,
+          file,
+          skills: ranked.slice(0, max),
+          totalSkills: ranked.length,
+          tokensPerTurn: ranked.reduce((a, s) => a + s.tokensPerTurn, 0),
+          lazyLoad: lazy.slice(0, max).map((s) => ({ name: s.name, tokensPerTurn: s.tokensPerTurn, uses: 0 })),
+          turns: events.filter((e) => e.type === 'turn/start').length,
+        }
+      },
+    },
+    {
+      name: 'ctx_budget_tools',
+      description:
+        'Tool-schema inflation: which tool group occupies the most context on every turn. Tool definitions are sent in full on every request, so a chatty MCP server or a plugin with wide parameters is a standing tax the model pays per turn. Groups are derived from tool-name prefixes (mcp__server__, plugin families, built-ins). Returns {ok, groups:[{group,tools,chars,tokensPerTurn}], totalTokensPerTurn, tools}.',
+      parameters: {
+        type: 'object',
+        properties: {
+          session: { type: 'string', description: 'Path to a session.v4.jsonl.zstd file, a session directory, or a session id. Omit to audit the newest session.' },
+          dir: { type: 'string', description: 'Sessions root used to resolve a bare session id and to pick the newest session. Defaults to ~/.dsh/sessions.' },
+          maxGroups: { type: 'integer', description: 'How many groups to list at most (default 20).' },
+        },
+      },
+      async execute(args) {
+        const root = resolveSessionsDir(args.dir)
+        let file = args.session ? resolveSessionFile(args.session) : null
+        if (args.session && !file) return { ok: false, error: `no session.v4.jsonl.zstd for ${args.session}` }
+        if (!file) {
+          const newest = listSessions(root, cfg.maxSessions).sort((a, b) => b.name.localeCompare(a.name))[0]
+          if (!newest) return { ok: false, error: `no sessions found under ${root}` }
+          file = newest.file
+        }
+        const { events, error } = loadSession(file)
+        if (error) return { ok: false, error }
+        const { tools } = extractInputs(events)
+        if (tools.length === 0) return { ok: false, error: 'no tool schemas found in this session' }
+        const inflated = toolInflation(tools)
+        const max = Math.max(1, Number(args.maxGroups) || 20)
+        return {
+          ok: true,
+          file,
+          groups: inflated.rows.slice(0, max),
+          toolCount: tools.length,
+          totalChars: inflated.totalChars,
+          totalTokensPerTurn: inflated.totalTokens,
+        }
+      },
+    },
+  ]
+
+  for (const t of tools) {
+    try {
+      ctx.tools.register({
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters,
+        output: { schema: OUTPUT_SCHEMA, render: outRender },
+        timeoutMs: 300_000,
+        isConcurrencySafe: () => true,
+        presentCall: (args) => ({ card: 'generic', title: t.name, kind: 'read', rawInput: args }),
+        execute: t.execute,
+      })
+    } catch (error) {
+      console.error(`[context-budget] ${t.name} registration skipped: ${error}`)
+    }
+  }
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@bushizhanghan/dsh-context-budget",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Audit where each turn's context budget goes: per-turn composition (AGENTS.md / skill catalog / tool schemas / runtime context / history), repeated injection of byte-identical content (pure waste), skill-catalog governance, and tool-schema inflation. Deterministic, no LLM. 上下文预算审计：每轮注入构成、重复注入浪费、技能目录治理、工具 schema 膨胀。",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./engine": "./lib/engine.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "cordis",
+    "cordis-plugin",
+    "context",
+    "tokens",
+    "budget",
+    "audit",
+    "agent-tools"
+  ],
+  "author": "bushizhanghan",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bushizhanghan/dsh-context-budget.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bushizhanghan/dsh-context-budget/issues"
+  },
+  "homepage": "https://github.com/bushizhanghan/dsh-context-budget#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "test": "node --test test/"
+  }
+}