opencode-dcp/opencode-dynamic-context-pruning

1. What this repo is

- This is a TypeScript plugin for OpenCode that manages conversation context by pruning, compressing, and summarizing messages before they are sent to the model.

- The core architectural boundary is between OpenCode’s session/message stream and DCP’s context-management layer, which rewrites context in a way that preserves session history semantics without deleting the original conversation.

2. Entry points and plugin wiring

- index.ts and tui.tsx are the main package entry surfaces.

- lib/hooks.ts is the runtime integration point where DCP attaches to OpenCode lifecycle events.

- lib/commands/* registers slash commands and manual controls, while lib/tui/* provides the interactive panel shown by /dcp.

3. Context-management pipeline

- The main pruning/compression flow lives under lib/compress/.

- pipeline.ts orchestrates the overall pass: inspect session state, choose targets, apply strategies, generate summaries, and emit replacements/placeholders.

- Supporting modules split the work into range selection, message lookup, protected content handling, timing, and state reconstruction.

4. Two compression modes

- The repo supports range mode and message mode.

- Range mode compresses contiguous spans of conversation into summaries; message mode compresses individual messages independently.

- This choice affects the shape of data that flows through the compression pipeline and how placeholders and nested summaries are produced.

5. Message model and transformation layer

- lib/messages/* contains the data-shaping logic that understands OpenCode message types, priorities, queries, pruning markers, sync behavior, and injected subagent results.

- This layer is responsible for turning raw session messages into DCP’s internal compression/pruning representation and back into the form OpenCode can consume.

6. Automatic pruning strategies

- lib/strategies/ contains non-compression cleanup passes such as deduplication and purge-errors.

- These are recalculated on compression-triggering events, so the pruning model is “recompute from session state” rather than incrementally mutating historical data.

- The readme’s “automatic cleanup” corresponds to this subsystem.

7. State, persistence, and caching

- lib/state/ tracks plugin runtime state, persistent configuration-derived state, and tool/result caches.

- This is where DCP remembers prior compression state, active summaries, and any bookkeeping needed across turns or restarts.

- The plugin appears designed to regenerate derived pruning results from durable state rather than relying only on in-memory history.

8. Configuration and policy boundaries

- lib/config.ts loads and merges config from global, custom, and project scopes described in the readme.

- dcp.schema.json defines the configuration schema used for validation and editor support.

- Policy modules such as lib/host-permissions.ts, lib/compress-permission.ts, and lib/auth.ts gate whether actions are allowed, need approval, or should be hidden entirely.

9. Prompt generation and override system

- lib/prompts/ holds the system prompt and the specialized prompts used for compression nudges and summaries.

- Prompt files are treated as first-class behavior inputs: the plugin can emit prompt text to steer the model toward compression at the right time.

- lib/prompts/store.ts plus the prompt override feature in the readme indicate a managed-defaults + user-overrides model.

10. Nudging and timing

- lib/compress/timing.ts, lib/messages/priority.ts, and the prompt modules work together to decide when the model should be reminded to compress.

- This is how DCP implements soft context thresholds, iteration-based nudges, and turn-based reminders rather than relying only on hard context limits.

- The result is proactive behavior: the model is encouraged to compress before the session becomes too large.

11. User interface and observability

- lib/tui/ implements the DCP panel: context view, stats, dialogs, and manual-mode controls.

- lib/ui/notification.ts and lib/logger.ts handle user-facing feedback and debug output.

- The UI is a control/visibility layer only; the actual pruning decisions still come from the compression and strategy subsystems.

12. Utilities, update path, and external behavior

- lib/update.ts supports auto-update behavior mentioned in the config.

- lib/token-utils.ts and related utilities support token counting and context-limit calculations.

- The scripts/ directory provides operational tooling for inspecting sessions, token usage, and cached DCP state, which is useful for debugging and validating the pruning behavior.

13. Tests as architecture clues

- The tests/ suite covers compression behavior, placeholder behavior, permissions, prompt generation, message IDs, token counting, and update logic.

- This strongly suggests the repo’s critical correctness boundary is deterministic transformation of session data, not network I/O or persistent server state.

14. Overall data flow

- OpenCode emits session events and tool calls.

- DCP hooks inspect those events, apply permissions and config, then run strategies and/or compression.

- The result is a rewritten context package with placeholders, summaries, and protected content preserved, plus optional notifications and TUI updates.

- The original session remains intact; DCP only changes what gets forwarded to the model.

15. Main architectural boundary to diagram

- The key box to draw is a middleware-like plugin layer sitting between OpenCode session history and LLM request context.

- Around that core are three supporting rings: policy/config, prompt/UI, and state/strategy subsystems.