📦 @goodandready/dsh-context-lens

⚡ Overview & The Problem

Large codebase contexts and verbose build/test logs quickly fill the LLM context window, waste token budget, slow down inference, and cause agent hallucination.

dsh-context-lens solves this by providing:

1. Active Focus Scoping: Keeping full fidelity for files currently being edited, while collapsing surrounding workspace files into lightweight AST skeletons.
2. Multi-Language AST Skeletonization: Extracting structural types, classes, and method signatures across TypeScript, JavaScript, Python, Go, C/C++, Rust, and SQL, cutting raw code size by 70–85%.
3. Intelligent Terminal Log Compression: Stripping noisy passing test lines and build boilerplate while preserving critical error stack traces and failure windows, cutting log size by up to 90%.
4. Session Token Telemetry & Budget Guard: Live tracking of token savings with configurable budget alerts and visual indicators in the DSH Web UI.

graph LR
    subgraph RawContext [Raw Context Streams]
        Code[📁 Source Code: Lengthy Implementation Details] --> LensEngine[dsh-context-lens Engine]
        Logs[📋 Build/Test Logs: Verbose Success Noise] --> LensEngine
    end

    subgraph LensEngine [Context Processing Pipeline]
        LensEngine --> Focus{Focus Evaluator}
        Focus -->|Focused File| RawKeep[Full Code Details Retained]
        Focus -->|Surrounding Workspace| AST[AST Skeletonizer: Signatures & Types]
        LensEngine --> LogFilter[Log Condenser: Stack Traces & Errors Only]
    end

    subgraph Output [Optimized Agent Context]
        AST --> Agent[🤖 DSH Agent Context: Compact High-Value Prompt]
        RawKeep --> Agent
        LogFilter --> Agent
        Agent --> Tracker[📊 Live Token Telemetry & Budget Guard]
    end

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

✨ Full Feature Breakdown

1. 🧬 Multi-Language AST Structural Skeletonizer

• Supported Languages: TypeScript, JavaScript, Python, Go, C/C++, Rust, and SQL DDL.
• Structural Preservation: Retains imports, classes, structs, interfaces, exported types, function signatures, and doc comments while discarding inner implementation bodies.
• Multiline Signature Support: Seamlessly accumulates complex multiline generic arguments, return types, and parameter lists up to block delimiters.
• Pure Regex Implementation: Zero heavy native dependencies or binary parser overhead; runs lightning-fast across any platform.

2. 📋 Heuristic Test & Build Log Condenser

• Supported Test Runners & Tools: Jest, Vitest, Pytest, Go test, Cargo, Webpack, Vite, TSC, Maven, Gradle.
• Targeted Extraction: Identifies and preserves critical error messages, stack traces, assertion differences (Expected ... Received ...), and failure context windows.
• 3 Aggressiveness Modes:
  • raw: Removes simple noise lines while keeping general execution order.
  • balanced: Preserves failure sections with surrounding context windows (default).
  • aggressive: Extracts strictly error lines and stack frames.
• ANSI Stripping: Cleans terminal escape codes and color formatting before processing.

3. 🎯 Active Path Focus Scoping (context_lens_focus)

• Allows designating specific files or folders as active working targets for the current task.
• Files inside focus remain uncompressed; non-focused dependencies are automatically served as structural skeletons.
• Focus state is strictly scoped per session (sessionId) and can be inspected or cleared instantly via UI or API.

4. 📊 Token Savings Tracking & Budget Telemetry

• Calculates exact tokens before and after compression using accurate token estimation.
• Tracks cumulative tokens saved, compression ratio, and session budget percentage.
• Configurable warning threshold (budgetAlertPercent) dynamically alerts when the session budget approaches depletion.

5. 🖥️ Visual Surfaces & Dual Sidebar Integration

Context Lens shares the unified .cl-* design language and --dsw-alias-* token system with dsh-clinebot:

• Conversation Header Chip: Mounted in conversation.session.header.utilities (order: 7). Always displays efficiency badges (◐ Lens, ◐ <N>%, or ⚠ alert) with an interactive dropdown Popover showing savings details and recent operations.
• Dual Sidebar Compatibility: Supports both native DeepSeek Harness right sidebar (ctx.sidebarRightTabs + sidebar.right.pane.tab slot) and legacy dsh-better-sidebar with non-conflicting IDs.
• ErrorBoundary Protection: Every UI component (PluginCard, LensTab, StatusPanel) is isolated inside React error boundaries with instant retry buttons, preventing parent UI crashes.
• One-Click In-App Updater: Settings card displays live version checks against npm with a single-click update trigger.

🛠️ Agent Tools Reference (5 Tools)

All tools strictly conform to the DeepSeek Harness tool specification by providing output.render returning structured ContentBlock[] arrays ([{ type: 'text', text: ... }]), ensuring 100% session stability with core LLM stream processors.

🔌 HTTP API Reference

⚙️ Configuration Reference (settings.yaml)

Settings can be modified via settings.yaml or directly in the DSH Web UI under Settings → Plugins → Context Lens.

dsh-context-lens:
  compressionMode: balanced        # Log compression mode: '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
  budgetAlertPercent: 90          # Budget percentage threshold triggering warning badge (50..99)
  autoCollapse: true              # Display warning in UI when budget is nearly exhausted

📦 Quick Installation

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

[!TIP] After installation, reload the DSH Web UI or restart the service (systemctl --user restart dsh-web) to activate context compression tools.

📄 License

MIT © GooDAnDReaDY