📦 @goodandready/dsh-context-lens

⚡ Overview

dsh-context-lens optimizes the context window and token budget of DeepSeek Harness agents.

Large context windows are expensive, prone to model distraction, and vulnerable to rate limits. When agents inspect multi-file codebases or run bulky test suites, thousands of tokens are wasted on boilerplate function bodies, passing test logs, and build artifacts.

dsh-context-lens introduces active path focusing, AST structural code skeletonization (JS/TS/Python/Go), and fast O(n) heuristic log compression, shrinking context consumption by up to 85% while keeping 100% of essential architectural interfaces and failure traces.

graph LR
    subgraph RawContext [Bulky Workspace & Terminal Streams]
        Code[📁 Multi-File Codebase: Full Function Bodies] --> LensEngine[dsh-context-lens Compression Engine]
        Logs[📋 Test & Build Logs: Thousands of Noise Lines] --> LensEngine
    end

    subgraph LensEngine [Context Lens Processing Pipelines]
        LensEngine --> Focus{Active Focus Check}
        Focus -->|Focused Target| RawKeep[Full Implementation Preserved]
        Focus -->|Surrounding Workspace| AST[AST Skeletonizer: Types, Classes, Signatures]
        LensEngine --> LogFilter[Heuristic Log Condenser: Stack Traces & Errors]
    end

    subgraph Savings [Token Economy & Agent Reasoning]
        AST --> Agent[🤖 DSH Agent: Ultra-Compact High-Speed Context]
        RawKeep --> Agent
        LogFilter --> Agent
        Agent --> Tracker[📊 Live Token Budget Savings Tracker]
    end

    style RawContext fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
    style LensEngine fill:#181825,stroke:#cba6f7,stroke-width:2px,color:#cdd6f4
    style Savings fill:#11111b,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4

✨ Key Capabilities & Modules

1. 🧬 Multi-Language AST Code Skeletonizer (lib/ast/skeletonizer.js)

• Automatically extracts structural interfaces, function signatures, classes, types, and exports across TypeScript, JavaScript, Python, Go, Rust, and Java;
• Supports pub async fn, async fn, pub(crate) and pub(super) in Rust;
• Retains JSDoc, docstrings, and structural comments preceding definitions;
• Drops internal function implementations, loops, and repetitive boilerplate while preserving indentation and export declarations;
• Allows the agent to understand entire multi-package repository architectures without loading tens of thousands of implementation tokens.

2. 🗜️ Fast Heuristic Log Condenser (lib/compression/log-compressor.js)

• High-performance $O(n)$ heuristic line filter for test runners and build tools (Jest, Vitest, Pytest, Go test, NPM, Webpack, Cargo, Maven/Gradle);
• Strips terminal ANSI escape color sequences before evaluating regex patterns;
• Automatically filters out passing test noise (PASS, ✓, ok) and build notices;
• Retains critical error lines, stack traces, assertion failures (Expected ... Received ...), and failure context windows;
• 3 Aggressiveness Modes: raw, balanced, and aggressive.

3. 🎯 Active Path Focus Scoping (context_lens_focus)

• Dynamically sets a list of active files or directories currently being edited;
• Files outside the focus list are automatically presented to the agent as lightweight AST skeletons.

4. 📊 Token Savings Tracking & Dashboard (lib/tokens/tracker.js & lib/client.js)

• Measures exact token counts before and after compression;
• Calculates cumulative session token savings and displays live efficiency percentage badges in the DSH interface;
• Enforces Token Budget Guard limits with alert warnings when exceeding 90% budget.

🛠️ Agent Tools Reference (4 Tools)

📦 Quick Installation

dsh plugin --profile web add @goodandready/dsh-context-lens

[!IMPORTANT] Restart DSH Web UI after installation (systemctl --user restart dsh-web) to activate context compression tools.

⚙️ Configuration Reference (settings.yaml)

dsh-context-lens:
  compressionMode: balanced        # 'raw', 'balanced', or 'aggressive'
  astSkeletonMaxDepth: 3          # Maximum depth level for AST signature traversal (1..10)
  tokenSavingsTracking: true      # Track and display live token savings
  autoCompressThreshold: 4000     # Auto-compression character threshold (0 to disable)
  budgetLimit: 100000             # Session token budget limit
  autoCollapse: true              # Auto-collapse UI when budget is nearly exhausted

📝 Version History

v0.1.10

• Fix: Register session header chip in conversation.session.header.utilities (order: 7).
• Fix: Ensure chip is always visible (◐ Lens on initial session, ◐ <N>% when savings available, ⚠ on low budget).
• Feature: Interactive dropdown Popover on chip click: token savings breakdown, budget progress bar, recent operations, and refresh button.

v0.1.9

• Fix: Remove obsolete kernel modules from client injects for DSH 0.1.2-rc.1 compatibility.

v0.1.8

• Fix: Support both text and log parameter names in context_lens_compress_log.
• Fix: Cross-platform path resolution in unit tests on Windows (fileURLToPath).
• Fix: Dynamic propagation of budgetLimit configuration into token tracker.
• Fix: ANSI terminal escape sequence stripping for colored logs.
• Fix: Expanded Rust syntax support (pub async fn, pub(crate)) and proper # comment prefix for Python.

📄 License

MIT © GooDAnDReaDY

Changed in v0.1.11

Audit fixes (#33–#47, #18):

• Auto-compress no longer forces balanced; uses configured compressionMode.
• budgetLimit stops token counting after the limit (matches settings description).
• Focus state is per-session (sessionId), not process-global.
• Settings card exposes budgetLimit, autoCollapse, autoCompressThreshold; low-budget shows a warning instead of force-closing the card.
• Client betterSidebar inject is optional; preview uses server /dsh-context-lens/compress-preview.
• Python imports kept in skeletons; Java locals no longer mistaken for signatures.
• Shared estimateTokens helper; unused dsh-credentials peer removed.

Changed in v0.1.12

#43: extract shared StatusPanel used by LensTab and HeaderChip popover (budget bar, history, refresh).

Changed in v0.1.13

• Fix (#50): Guard optional betterSidebar tab registration via ctx.inject(['betterSidebar'], ...) instead of direct property access on Cordis context proxy, resolving cannot get property "betterSidebar" without inject on client boot.
• Fix (#50): Safely guard _ctx.settingsScope access in PluginCard with try/catch to prevent proxy property errors.
• Test: Added regression test suite simulating strict Cordis Context Proxy behavior.

Changed in v0.1.14

• Fix (#52): Multiline AST signature parsing in skeletonizer.js for TypeScript, JavaScript, Rust, and Go with complex parameter types and return annotations.
• Feature (#52): Registered context_lens_reset tool to allow resetting tracker statistics and history at the start of new tasks.
• Quality & UX (#52): Dynamic RU/EN locale detection in HeaderChip, LensTab, and StatusPanel via ctx.locale for seamless UI integration.
• Perf & Stability (#52): Adaptive polling in HeaderChip pausing on hidden tabs (visibilitychange) and polling actively (4s) only when popover is open.
• Reliability (#52): Atomic settings save (scope.patch / scope.setAll) in PluginCard with graceful fallback.