feat(compaction): Hybrid compaction pipeline with deterministic extraction + LLM

[thijs-hakkenberg]

Description

This PR introduces a novel hybrid compaction approach that significantly improves session continuation quality by combining deterministic extraction with targeted LLM semantic analysis.

Problem

The current compaction implementation uses a generic freeform LLM prompt that often loses critical details:

• File paths and modifications get omitted or summarized incorrectly
• Error resolution status is lost
• Agent context and constraints disappear after compaction
• No quality validation of compaction output

Solution

A hybrid pipeline that runs sequentially for optimal token efficiency:

┌─────────────────────────────────────────────────────────────┐ │ HYBRID PIPELINE │ ├─────────────────────────────────────────────────────────────┤ │ Phase 1: Deterministic Extraction │ │ ├── Files read/modified/created (from tool calls) │ │ ├── Errors detected + resolution status │ │ └── Tool usage summary │ ├─────────────────────────────────────────────────────────────┤ │ Phase 2: Context Condensation │ │ └── Build compact representation (~90% token reduction) │ ├─────────────────────────────────────────────────────────────┤ │ Phase 3: LLM Extraction (with condensed context) │ │ ├── Session intent │ │ ├── Current state │ │ ├── Key decisions + rationale │ │ ├── Pending tasks │ │ └── Critical context │ ├─────────────────────────────────────────────────────────────┤ │ Phase 4: Quality Validation (optional) │ │ └── Score completeness + information retention │ └─────────────────────────────────────────────────────────────┘

Key Features

• Enabled by default - Works out of the box, no configuration needed
• Token efficient - Deterministic extraction runs first, LLM receives condensed context instead of full message history
• Structured output - JSON schema ensures consistent, parseable compaction results
• Quality validation - Optional threshold-based quality gate with detailed scoring
• Agent context preservation - Extracts constraints from system prompts to maintain agent personality
• Backward compatible - Falls back to legacy compaction via config flag

New Files

packages/opencode/src/session/compaction/ ├── schema.ts # Zod schemas for structured template ├── extractors.ts # Deterministic file/error/tool extraction ├── llm-extractor.ts # Prompt builder + response parser ├── quality.ts # Completeness & retention scoring ├── pipeline.ts # Pipeline orchestrator └── index.ts # Module exports

packages/opencode/test/session/ └── compaction-hybrid.test.ts # Comprehensive test suite

Configuration

{ "compaction": { "hybrid": { "enabled": true, // default: true "preserve_agent_context": true, // default: true "quality_threshold": 0.7 // optional (0-1) } } }

Example Output

Session Compaction

Generated: 2025-01-06T12:00:00.000Z

Session Intent

Implement user authentication with JWT tokens

Artifacts

Files Read

• /src/auth/middleware.ts
• /src/config/jwt.ts

Files Modified

• /src/routes/auth.ts: Added login and logout endpoints

Files Created

• /src/auth/jwt-service.ts

Tool Usage Summary

• Read: 5x (5/5 successful)
• Edit: 3x (3/3 successful)
• Bash: 2x (2/2 successful)

Decisions Made

• Use JWT tokens: Stateless authentication, better for horizontal scaling

Current State

Login endpoint complete, working on refresh token implementation

Pending Tasks

• [ ] Add refresh token endpoint
• [ ] Write integration tests

Key Context

Express.js backend with PostgreSQL. User requested no external auth providers.

---

Compression: 94.2% (50000 → 2900 tokens)

Testing

• Comprehensive test suite with 50+ test cases
• Tests for schema validation, extractors, LLM parsing, quality scoring, and full pipeline
• Developed using TDD (test-driven development)

Breaking Changes

None. Hybrid compaction is additive and enabled by default. Can be disabled via compaction.hybrid.enabled: false.

---

To run tests locally: bun test packages/opencode/test/session/compaction-hybrid.test.ts