Compress Before You Prompt: How a 74K-Star Token-First Architecture Is Making AI Coding Agents Smarter, Cheaper, and Actually Honest

┌─────────────────────────────────────────────────────────────────┐
│                    AI Coding Agent Runtime                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌──────────┐    ┌──────────────┐    ┌───────────────────────┐  │
│  │  Raw     │───▶│  Compression │───▶│  Token Budget         │  │
│  │  Codebase│    │  Pipeline    │    │  Allocator             │  │
│  └──────────┘    └──────────────┘    └───────────┬───────────┘  │
│       │                    │                      │              │
│       │                    ▼                      ▼              │
│       │            ┌──────────────┐    ┌───────────────────────┐ │
│       │            │  AST Parser  │    │  Context Assembly     │ │
│       │            │  + Indexer   │    │  + Prompt Builder     │ │
│       │            └──────────────┘    └───────────┬───────────┘ │
│       │                                             │             │
│       │                                             ▼             │
│       │                                    ┌───────────────┐     │
│       │                                    │  LLM Backend  │     │
│       │                                    │  (Any Model)  │     │
│       │                                    └───────────────┘     │
│       ▼                                                         │
│  ┌──────────┐                                                   │
│  │  Git /   │                                                   │
│  │  FS      │                                                   │
│  └──────────┘                                                   │
└─────────────────────────────────────────────────────────────────┘

// Original: 187 tokens
export async function processUserData(
  userId: string,
  options: ProcessOptions = {
    includeHistory: false,
    maxRecords: 100,
    timeout: 5000
  }: ProcessOptions
): Promise<UserDataResponse> {
  if (!userId) {
    throw new Error('User ID is required');
  }
  
  const user = await userService.findById(userId);
  if (!user) {
    throw new Error(`User not found: ${userId}`);
  }
  
  const records = await recordService.getRecent(userId, options.maxRecords);
  
  return {
    id: user.id,
    name: user.name,
    email: user.email,
    records: records.map(r => ({
      id: r.id,
      timestamp: r.timestamp,
      value: r.value
    })),
    processedAt: new Date().toISOString()
  };
}

// Compressed: 42 tokens
fn processUserData(userId: string, options?: ProcessOptions) -> UserDataResponse
  deps: userService.findById, recordService.getRecent
  throws: Error(userId required), Error(user not found)
  returns: {id, name, email, records[{id,timestamp,value}], processedAt}
  defaults: includeHistory=false, maxRecords=100, timeout=5000

{
  "module": "src/services/userService.ts",
  "exports": [
    {
      "name": "findById",
      "signature": "(id: string) => Promise<User | null>",
      "sideEffects": ["db.query"]
    },
    {
      "name": "createUser",
      "signature": "(data: CreateUserInput) => Promise<User>",
      "sideEffects": ["db.insert", "eventBus.emit"]
    }
  ],
  "imports": ["src/models/User.ts", "src/db/connection.ts"],
  "tokenCountOriginal": 890,
  "tokenCountCompressed": 95
}

// Turn 1-3 (raw): ~3,200 tokens
User: Can you refactor the auth module to use JWT instead of sessions?
Agent: I'll start by examining the current auth implementation...
[agent reads 3 files, proposes changes, applies patches]

// After compression: ~340 tokens
[Turns 1-3 Summary] Refactored auth from session-based to JWT.
Modified: auth/middleware.ts (JWT validation), auth/routes.ts (token extraction),
auth/models.ts (added TokenPayload interface). Removed: sessionStore.ts.
Key decision: Using HS256 with 24h expiry, refresh tokens in httpOnly cookies.

{
  "totalBudget": 4096,
  "allocation": {
    "reasoning": 512,
    "code": 2560,
    "explanation": 768,
    "metadata": 256
  }
}

# Simplified representation of the compression pipeline
from dataclasses import dataclass
from typing import Literal

@dataclass
class CompressedFunction:
    name: str
    params: list[tuple[str, str]]  # (name, type)
    return_type: str
    dependencies: list[str]        # external calls
    side_effects: list[str]       # mutations, I/O
    errors: list[str]             # thrown errors
    complexity: Literal["trivial", "moderate", "complex"]

    def to_prompt_tokens(self) -> str:
        """Serialize to minimal token representation."""
        params_str = ", ".join(f"{n}: {t}" for n, t in self.params)
        parts = [f"fn {self.name}({params_str}) -> {self.return_type}"]
        if self.dependencies:
            parts.append(f"  calls: {', '.join(self.dependencies)}")
        if self.side_effects:
            parts.append(f"  mutates: {', '.join(self.side_effects)}")
        if self.errors:
            parts.append(f"  throws: {', '.join(self.errors)}")
        parts.append(f"  complexity: {self.complexity}")
        return "\n".join(parts)


def compress_file(source: str, language: str, budget: int) -> str:
    """
    Compress a source file to fit within token budget.
    
    Strategy: lossless for public interfaces, lossy for internals.
    Priority order: exported > used-by-current-task > private > unused
    """
    ast = parse_ast(source, language)
    
    # Phase 1: Extract all symbols with metadata
    symbols = extract_symbols(ast)
    
    # Phase 2: Score each symbol by relevance
    for sym in symbols:
        sym.score = compute_relevance(sym, current_task_context)
    
    # Phase 3: Greedy selection within budget
    symbols.sort(key=lambda s: s.score, reverse=True)
    selected = []
    used_tokens = 0
    for sym in symbols:
        cost = estimate_tokens(sym.to_prompt_tokens())
        if used_tokens + cost <= budget:
            selected.append(sym)
            used_tokens += cost
    
    # Phase 4: If under budget, expand top-scoring symbols
    remaining = budget - used_tokens
    for sym in selected:
        if remaining <= 0:
            break
        expanded_cost = estimate_tokens(sym.to_full_source())
        if expanded_cost <= remaining:
            sym.expanded = True
            remaining -= expanded_cost
    
    return serialize(selected)

def semantic_chunk(ast: AST, target_tokens: int) -> list[Chunk]:
    """
    Split code into semantically coherent chunks.
    Never splits across function/class boundaries.
    Groups related symbols into single chunks.
    """
    nodes = ast.body  # top-level declarations
    chunks = []
    current_chunk = Chunk()
    
    for node in nodes:
        node_tokens = estimate_tokens(node)
        
        # Check if adding this node would exceed budget
        if current_chunk.token_count + node_tokens > target_tokens:
            if current_chunk.nodes:
                chunks.append(current_chunk)
                current_chunk = Chunk()
        
        # Special handling for large classes
        if isinstance(node, ClassNode) and node_tokens > target_tokens:
            chunks.append(chunk_large_class(node, target_tokens))
            continue
        
        current_chunk.add(node)
    
    if current_chunk.nodes:
        chunks.append(current_chunk)
    
    # Merge adjacent small chunks (avoid fragmentation)
    chunks = merge_small_chunks(chunks, min_tokens=target_tokens // 3)
    
    return chunks

def compute_relevance(chunk: Chunk, query: str, context: TaskContext) -> float:
    """
    Multi-signal relevance scoring for context selection.
    Returns float in [0.0, 1.0].
    """
    signals = {}
    
    # Signal 1: Direct symbol match (highest weight)
    if any(sym in query for sym in chunk.exported_symbols):
        signals['direct_match'] = 0.9
    
    # Signal 2: Import graph proximity
    distance = shortest_import_path(chunk.module, context.target_module)
    signals['import_proximity'] = max(0, 1.0 - distance * 0.3)
    
    # Signal 3: Embedding similarity (semantic)
    signals['semantic'] = cosine_similarity(
        embed(chunk.compressed_repr),
        embed(query)
    )
    
    # Signal 4: Recent modification (temporal relevance)
    if chunk.last_modified_hours < 24:
        signals['recency'] = 0.3
    
    # Signal 5: Git blame overlap with modified files
    if chunk.file in context.modified_files:
        signals['modified'] = 0.7
    
    # Weighted combination
    weights = {
        'direct_match': 0.30,
        'import_proximity': 0.25,
        'semantic': 0.20,
        'recency': 0.10,
        'modified': 0.15
    }
    
    score = sum(signals.get(k, 0) * w for k, w in weights.items())
    return min(1.0, score)

# Model hallucination example (traditional agent)
from myapp.utils import parse_config  # DOES NOT EXIST
result = process_data(config)          # process_data doesn't accept config param

# What the model actually sees (compressed but complete):

Available functions in scope:
  fn parseConfig(path: string) -> AppConfig  [src/config/parser.ts]
  fn loadEnv(file?: string) -> Record<string,string>  [src/config/env.ts]
  fn process_data(input: InputData, opts?: ProcessOpts) -> Output  [src/core/engine.ts]
  
  NOTE: These are ALL exported functions in the dependency graph.
  If you need a function not listed here, it does not exist.

HONESTY CONTRACT:
1. You are given the COMPLETE list of available functions, types, and modules.
2. If you need something not in this list, state: "Not available in current context"
3. Never invent function names, parameters, or import paths.
4. If uncertain whether something exists, request clarification.
5. Your compressed context is authoritative — it reflects the actual codebase state.

class TokenBudgetAllocator:
    def __init__(self, model_max_context: int, cost_per_token: float, budget_limit: float):
        self.max_context = model_max_context
        self.cost_per_token = cost_per_token
        self.budget_limit = budget_limit
        
        # Fixed allocations
        self.system_prompt_tokens = 2048
        self.safety_margin = 512  # room for model reasoning
        
        # Dynamic allocation (the interesting part)
        self.available = model_max_context - self.system_prompt_tokens - self.safety_margin
        
    def allocate(self, components: list[ContextComponent]) -> dict[str, int]:
        """
        Distribute available tokens across context components
        using utility-maximizing allocation.
        """
        # Score each component by utility density (info per token)
        for comp in components:
            comp.utility_density = comp.expected_usefulness / comp.token_cost
            comp.compressed_cost = comp.token_cost / comp.compression_ratio
        
        # Greedy allocation by utility density
        components.sort(key=lambda c: c.utility_density, reverse=True)
        
        allocation = {}
        remaining = self.available
        
        for comp in components:
            # Allocate compressed version first
            comp_allocation = min(comp.compressed_cost, remaining)
            allocation[comp.name] = int(comp_allocation)
            remaining -= comp_allocation
            
            if remaining <= 0:
                break
        
        # Validate against cost budget
        total_cost = sum(
            allocation[c.name] * c.cost_per_token
            for c in components
        )
        if total_cost > self.budget_limit:
            # Scale down proportionally, preserving highest-utility components
            scale = self.budget_limit / total_cost
            for comp in components:
                allocation[comp.name] = int(allocation[comp.name] * scale)
        
        return allocation

// src/compression/ast-parser.ts
import { parse, Node, FunctionDeclaration, ClassDeclaration, ExportStatement } from 'typescript';

export interface CompressedSymbol {
  name: string;
  kind: 'function' | 'class' | 'interface' | 'const' | 'enum';
  signature: string;
  dependencies: string[];
  isExported: boolean;
  tokenCostOriginal: number;
  tokenCostCompressed: number;
}

export function extractSymbols(source: string, fileName: string): CompressedSymbol[] {
  const sf = parse(source, { fileName });
  const symbols: CompressedSymbol[] = [];
  
  sf.forEachChild(node => {
    if (isExportStatement(node)) {
      node.forEachChild(inner => handleExported(inner, symbols));
    } else if (isFunctionDeclaration(node) || isClassDeclaration(node)) {
      handleExported(node, symbols);
    } else if (isVariableStatement(node)) {
      // Check if it's an exported const
      if (hasModifier(node, 'export')) {
        handleExported(node, symbols);
      }
    }
  });
  
  return symbols;
}

function handleExported(
  node: Node,
  symbols: CompressedSymbol[]
): void {
  if (isFunctionDeclaration(node)) {
    const fn = node as FunctionDeclaration;
    const params = fn.parameters?.map(p => 
      `${p.name.getText()}: ${p.type?.getText() || 'any'}`
    ) || [];
    const returnType = fn.type?.getText() || 'void';
    
    // Extract called functions
    const deps = extractCalledFunctions(fn.body);
    
    symbols.push({
      name: fn.name.getText(),
      kind: 'function',
      signature: `${fn.name.getText()}(${params.join(', ')}) -> ${returnType}`,
      dependencies: deps,
      isExported: true,
      tokenCostOriginal: countTokens(fn.getText()),
      tokenCostCompressed: countTokens(formatCompressedSymbol(symbols[symbols.length - 1]))
    });
  }
  // ... handle classes, interfaces, etc.
}

function extractCalledFunctions(body: Node): string[] {
  const called = new Set<string>();
  
  function visit(node: Node) {
    if (isCallExpression(node)) {
      const expr = node.expression;
      if (isIdentifier(expr)) {
        called.add(expr.text);
      } else if (isPropertyAccessExpression(expr)) {
        called.add(expr.getText());
      }
    }
    node.forEachChild(visit);
  }
  
  visit(body);
  return [...called];
}

// src/compression/engine.ts
import { extractSymbols, CompressedSymbol } from './ast-parser';
import { estimateTokenCount } from './tokenizer';

export interface CompressionResult {
  compressed: string;
  originalTokens: number;
  compressedTokens: number;
  ratio: number;
  symbolsIncluded: number;
  symbolsOmitted: number;
}

export class CompressionEngine {
  private compressionProfile: CompressionProfile;
  
  constructor(profile: CompressionProfile) {
    this.compressionProfile = profile;
  }
  
  compress(
    source: string,
    options: {
      budget: number;
      focusSymbols?: string[];
      includeDependencies?: boolean;
    }
  ): CompressionResult {
    const symbols = extractSymbols(source, options.fileName || 'unknown');
    const originalTokens = estimateTokenCount(source);
    
    // Score symbols by relevance
    const scored = symbols.map(sym => ({
      symbol: sym,
      score: this.scoreSymbol(sym, options.focusSymbols || [])
    }));
    
    // Sort by score, then greedily allocate budget
    scored.sort((a, b) => b.score - a.score);
    
    const included: CompressedSymbol[] = [];
    let usedTokens = 0;
    
    for (const { symbol } of scored) {
      const compressed = this.formatSymbol(symbol);
      const cost = estimateTokenCount(compressed);
      
      if (usedTokens + cost <= options.budget) {
        included.push(symbol);
        usedTokens += cost;
      }
    }
    
    // Build output
    const compressed = included.map(s => this.formatSymbol(s)).join('\n');
    const compressedTokens = estimateTokenCount(compressed);
    
    return {
      compressed,
      originalTokens,
      compressedTokens,
      ratio: originalTokens / compressedTokens,
      symbolsIncluded: included.length,
      symbolsOmitted: symbols.length - included.length
    };
  }
  
  private scoreSymbol(sym: CompressedSymbol, focus: string[]): number {
    let score = 0;
    
    if (sym.isExported) score += 0.5;
    if (focus.includes(sym.name)) score += 1.0;
    if (sym.kind === 'function') score += 0.3;
    if (sym.kind === 'interface') score += 0.4;
    
    // Penalize huge symbols (likely complex internals)
    const complexityPenalty = Math.min(
      0.5,
      sym.tokenCostOriginal / 1000
    );
    score -= complexityPenalty;
    
    return score;
  }
  
  private formatSymbol(sym: CompressedSymbol): string {
    const prefix = sym.isExported ? 'export ' : '';
    let result = `${prefix}${sym.kind} ${sym.signature}`;
    
    if (sym.dependencies.length > 0) {
      result += `\n  // calls: ${sym.dependencies.join(', ')}`;
    }
    
    return result;
  }
}

// src/agent/context-builder.ts
import { CompressionEngine } from '../compression/engine';
import { TokenBudgetAllocator } from '../budget/allocator';

export class ContextBuilder {
  private compressor: CompressionEngine;
  private allocator: TokenBudgetAllocator;
  private dependencyGraph: DependencyGraph;
  
  async buildContext(
    task: string,
    modifiedFiles: string[],
    model: string
  ): Promise<AssembledContext> {
    const modelConfig = getModelConfig(model);
    
    // Step 1: Identify relevant modules via dependency graph
    const relevantModules = this.dependencyGraph.getTransitiveDependencies(
      modifiedFiles,
      { depth: 2 }
    );
    
    // Step 2: Allocate token budget across components
    const budget = this.allocator.allocate({
      task,
      modifiedFiles,
      relevantModules,
      totalBudget: modelConfig.maxContext - 2048 // reserve for system prompt
    });
    
    // Step 3: Compress each component within its allocation
    const compressed = await Promise.all(
      relevantModules.map(mod => {
        const source = this.readFile(mod.path);
        return this.compressor.compress(source, {
          budget: budget[mod.path] || 500,
          focusSymbols: this.extractFocusSymbols(task, mod.path)
        });
      })
    );
    
    // Step 4: Assemble final context
    return {
      systemPrompt: this.buildSystemPrompt(compressed),
      totalTokensUsed: compressed.reduce((sum, c) => sum + c.compressedTokens, 0),
      compressionRatio: this.computeOverallRatio(compressed),
      honestyGuarantees: this.generateHonestyContract(compressed)
    };
  }
}

// Adaptive compression: detect when full fidelity is needed
function detectCompressionLevel(task: string, context: TaskContext): CompressionLevel {
  if (/(debug|race|off-by-one|deadlock|memory leak)/i.test(task)) {
    return 'minimal'; // Near-full source
  }
  if (/(refactor|rename|add endpoint|new feature)/i.test(task)) {
    return 'aggressive'; // Heavy compression OK
  }
  if (/(optimize|performance|throughput|latency)/i.test(task)) {
    return 'moderate'; // Keep implementation details
  }
  return 'standard'; // Default balanced compression
}

// A minimal token-first agent in ~100 lines
import { parse } from 'typescript';
import OpenAI from 'openai';

const client = new OpenAI();

async function tokenFirstAgent(task: string, codebase: Map<string, string>) {
  // Step 1: Compress all files to signatures
  const compressed = new Map<string, string>();
  
  for (const [path, source] of codebase) {
    const sf = parse(source, { fileName: path });
    const symbols: string[] = [];
    
    sf.forEachChild(node => {
      const text = node.getText();
      // Keep only exported declarations' signatures
      if (text.startsWith('export ')) {
        // Truncate to first 200 chars (signature area)
        const signature = text.split('\n').slice(0, 5).join('\n');
        symbols.push(signature);
      }
    });
    
    compressed.set(path, symbols.join('\n'));
  }
  
  // Step 2: Build compressed context
  const context = [...compressed.entries()]
    .map(([path, sigs]) => `// ${path}\n${sigs}`)
    .join('\n\n');
  
  // Step 3: Call model with compressed context
  const response = await client.chat.completions.create({
    model: 'gpt-4',
    messages: [
      {
        role: 'system',
        content: `
You have access to the following codebase interfaces:

${context}

HONESTY RULES:
- These are the ONLY available functions/classes in scope
- If you need something not listed, say it's not available
- Never invent function names or import paths
- Request clarification if uncertain
        `.	rim()
      },
      { role: 'user', content: task }
    ]
  });
  
  return response.choices[0].message.content;
}