---

💡 Why dsh-context-economy?

LLM context windows are finite and expensive. Dumping entire 2,000-line source files into prompts exhausts token budgets and severely degrades the model's reasoning capabilities.

dsh-context-economy provides an ultra-compact code reading layer:

• 💰 80–93% Output Token Reduction: Queries return minimal path:line pointers with brief context; oversized matches spill cleanly to disk.
• 🌐 PageRank Dependency Topology: Analyzes project imports (adapted from Aider's repomap algorithm) to prioritize central, high-frequency hub files (hotspots).
• 🔬 Byte-Level Window Slicing (project_slice_read): Reads specific byte windows with regex find and tail tracking — built for huge single-line JS bundles and deep JSON.
• 📊 Persistent Savings Accounting (project_savings): Automatically tracks token savings per turn against naive full-read baselines.

---

🚀 Quick Start

Installation

# In your DSH plugin environment
dev_inject_plugin @dsh-external/dsh-context-economy

Typical Usage Flow

1. Find symbols with PageRank: project_symbols_find query="AuthHandler" ranking=true
2. Inspect dependency hotspots: project_imports direction="hotspots"
3. Query accumulated token savings: project_savings

---

🧩 DSH Power Suite

This plugin is part of the DSH Agent Power Suite — 4 modular, zero-hard-dependency plugins forming a complete closed-loop developer workflow:

flowchart LR
    M["🧠 dsh-local-memory<br>(1. Remember rules & prefs)"] --> E["⚡ dsh-context-economy<br>(2. Save 80%+ tokens reading code)"]
    E --> A["🛡️ dsh-evidence<br>(3. Tamper-proof audit receipts)"]
    A --> S["🔍 dsh-session-index<br>(4. CJK search & bookmarks)"]
    S --> M

    style M fill:#e8f4fd,stroke:#2b7de9,stroke-width:2px
    style E fill:#eef9f2,stroke:#1e8e3e,stroke-width:2px
    style A fill:#fef7e0,stroke:#f29900,stroke-width:2px
    style S fill:#f3e8fd,stroke:#8430ce,stroke-width:2px

Plugin	Role in Suite	Synergy with Context Economy
⚡ dsh-context-economy	Context Economy (Current)	Provides index-backed pointer reading and topology to slash token expenditure.
🧠 dsh-local-memory	Memory Layer	Frees up prompt tokens, leaving abundant budget for persistent memory snapshots.
🛡️ dsh-evidence	Audit & Receipts	Benchmark runs (savings-bench) generate verifiable evidence bundles registered into Evidence.
🔍 dsh-session-index	Session Search	Compact pointer output generates 80%+ smaller session logs, reducing search index load.

---

📖 Deep Dive & Reference

🛠️ Available Tools (8 Tools)

Tool	Description
project_index_status	View index stats, heal history, and manually refresh working-tree reconciliation.
project_symbols_find	Locate symbols by name/substring with optional PageRank ordering.
project_imports	Inspect in/out import edges, top-k hotspots, and orphans.
project_files	Cached fast glob listing relative project paths.
project_slice_read	Precision byte slicing with window / tail modes and ReDoS-protected regex find.
project_json_read	Bounded streaming scan of top-level JSON keys without full JSON.parse memory spikes.
project_cost_probe	Single-shot comparison probe between tool output and naive full-file reading.
project_savings	Query accumulated token savings ledger (grouped by tool/root with trend analysis).

🏗️ Architecture & Self-Healing

• Incremental Self-Healing Index: Tracks mtime + size to re-scan only modified files on demand without persistent daemon threads.
• Top-Level JSON Scanner: 64KB chunk-based depth scanner preventing OOM on massive configuration files.
• PageRank Algorithm: Power-iteration algorithm with $\alpha=0.85$ and strict convergence tolerances.

🧪 Building & Testing

npm run typecheck
npm run check:dsh-contract
npm test
npm run pack:check

---