Context Window as a First-Class Resource: Resizing Strategies for AI Coding Agents Across Multi-File Sessions

// TypeScript: Budget controller node for LangGraph-style agent
interface ContextBudget {
  maxTokens: number;
  warningThreshold: number; // e.g. 0.75
  currentUsage: number;
}

interface EditMemory {
  filePath: string;
  diffSummary: string;
  interfaceContract: string;
  editRationale: string;
  timestamp: number;
}

async function budgetControllerNode(
  state: AgentState,
  budget: ContextBudget,
  memoryStore: VectorStore
): Promise<AgentState> {
  const usageRatio = budget.currentUsage / budget.maxTokens;

  if (usageRatio >= budget.warningThreshold) {
    // Evict completed file contexts to vector store
    const completedEdits = state.editHistory.filter(e => e.status === 'complete');
    
    for (const edit of completedEdits) {
      const memory: EditMemory = {
        filePath: edit.filePath,
        diffSummary: await summarizeDiff(edit.diff),
        interfaceContract: extractExports(edit.finalContent),
        editRationale: edit.rationale,
        timestamp: Date.now()
      };
      await memoryStore.upsert(edit.filePath, memory);
    }

    // Retain only: current file + direct deps + task goal
    return {
      ...state,
      activeContext: trimToHotContext(state),
      editHistory: state.editHistory.filter(e => e.status === 'active')
    };
  }

  return state;
}

// TypeScript: Token budget allocator for prompt assembly
const TOKEN_BUDGET: Record<string, number> = {
  systemPrompt: 512,
  taskDescription: 256,
  fileContent: 6144,
  editHistory: 1024,
  toolResults: 512,
  reserved: 512  // model output headroom
};

const CONTEXT_WINDOW = 8192; // local model hard limit

interface PromptSlot {
  name: keyof typeof TOKEN_BUDGET;
  content: string;
  tokenCount: number;
}

function assemblePrompt(slots: PromptSlot[]): { prompt: string; utilization: number } {
  let totalTokens = 0;
  const assembled: string[] = [];

  for (const slot of slots) {
    const budget = TOKEN_BUDGET[slot.name];
    if (slot.tokenCount > budget) {
      // Compress before including
      const compressed = compressToTokenBudget(slot.content, budget);
      assembled.push(compressed.text);
      totalTokens += compressed.tokenCount;
    } else {
      assembled.push(slot.content);
      totalTokens += slot.tokenCount;
    }
  }

  const utilization = totalTokens / CONTEXT_WINDOW;
  // Emit to observability layer
  metrics.gauge('agent.context.utilization', utilization);

  return { prompt: assembled.join('\n\n'), utilization };
}

// TypeScript: Context lifecycle manager with auto-reset triggers
type ResetTrigger = 'task-phase-complete' | 'file-scope-change' | 'token-threshold' | 'human-override';

interface ContextCheckpoint {
  trigger: ResetTrigger;
  phaseSummary: string;
  retainedSlots: string[];
  evictedToMemory: string[];
  timestamp: number;
}

class ContextLifecycleManager {
  constructor(
    private memoryStore: VectorStore,
    private tokenThreshold: number = 0.8
  ) {}

  async handleEvent(
    trigger: ResetTrigger,
    state: AgentState
  ): Promise<{ newState: AgentState; checkpoint: ContextCheckpoint }> {
    
    const toEvict = this.selectForEviction(state, trigger);
    const toRetain = this.selectHotContext(state, trigger);

    // Persist evicted context with semantic indexing
    await Promise.all(
      toEvict.map(slot => 
        this.memoryStore.upsert(slot.key, slot.content, {
          taskId: state.taskId,
          trigger,
          timestamp: Date.now()
        })
      )
    );

    const checkpoint: ContextCheckpoint = {
      trigger,
      phaseSummary: await this.summarizePhase(state),
      retainedSlots: toRetain.map(s => s.key),
      evictedToMemory: toEvict.map(s => s.key),
      timestamp: Date.now()
    };

    // Emit checkpoint event for observability
    events.emit('context.checkpoint', checkpoint);

    return { 
      newState: { ...state, activeSlots: toRetain },
      checkpoint 
    };
  }

  private selectHotContext(state: AgentState, trigger: ResetTrigger): ContextSlot[] {
    // Always retain: current task goal, active file, direct interface deps
    const hot = ['taskGoal', 'currentFile', 'directDeps'];
    return state.activeSlots.filter(s => hot.includes(s.key));
  }
}

// TypeScript: Comprehension gate for human-in-the-loop context grounding
interface ComprehensionCheck {
  agentActionSummary: string;
  engineerResponse: string;
  divergenceScore: number; // 0 = aligned, 1 = fully diverged
}

async function comprehensionGateNode(
  state: AgentState,
  humanInterface: HumanInTheLoopAdapter
): Promise<AgentState> {
  
  const actionSummary = await summarizeLastAgentActions(
    state.recentActions,
    { maxTokens: 200, format: 'plain-language' }
  );

  // Ask engineer to describe what happened — not approve it
  const engineerResponse = await humanInterface.prompt(
    `In your own words, what did the agent just change and why?\n\nAgent did: ${actionSummary}`
  );

  const divergence = await scoreDivergence(
    actionSummary,
    engineerResponse
  );

  // Emit for observability — track divergence trends over session
  metrics.gauge('agent.comprehension.divergence', divergence, {
    sessionId: state.sessionId,
    taskPhase: state.currentPhase
  });

  if (divergence > 0.6) {
    // Inject structured catch-up summary before proceeding
    return {
      ...state,
      activeContext: await injectCatchUpSummary(state),
      flags: [...state.flags, 'comprehension-reset-triggered']
    };
  }

  return state;
}

// TypeScript: Feedback-driven context budget tuner
interface TaskOutcome {
  taskId: string;
  contextConfig: Record<string, number>;
  coherenceScore: number; // 0-1, human or eval-rated
  tokenUtilization: number;
  filesEdited: number;
  editDepth: 'shallow' | 'deep' | 'cross-module';
}

// Safe tunable parameters — explicitly scoped
const TUNABLE_PARAMS = new Set([
  'fileContent', 'editHistory', 'toolResults'
  // NOT: tool_permissions, memory_access_scope, routing_config
]);

async function tuneContextBudgets(
  recentOutcomes: TaskOutcome[],
  currentBudgets: Record<string, number>
): Promise<Record<string, number>> {
  
  const deepEditOutcomes = recentOutcomes.filter(
    o => o.editDepth === 'cross-module'
  );

  if (deepEditOutcomes.length < 5) return currentBudgets; // insufficient data

  const avgCoherence = deepEditOutcomes.reduce(
    (sum, o) => sum + o.coherenceScore, 0
  ) / deepEditOutcomes.length;

  const updatedBudgets = { ...currentBudgets };

  if (avgCoherence < 0.6) {
    // Cross-module edits losing coherence — expand edit history slot
    for (const param of TUNABLE_PARAMS) {
      if (param === 'editHistory') {
        updatedBudgets[param] = Math.min(
          updatedBudgets[param] * 1.25,
          2048 // hard ceiling
        );
      }
    }
    events.emit('context.budget.tuned', { reason: 'low-coherence-cross-module', updatedBudgets });
  }

  return updatedBudgets;
}

// TypeScript: Pre-prompt context filter for security-scoped content
const SENSITIVE_PATTERNS: RegExp[] = [
  /\.env(\..*)?$/,
  /terraform\.tfstate/,
  /secrets\.(yaml|json|toml)/,
  /kubeconfig/,
  /\.aws\/credentials/
];

const INFRA_PATTERNS: RegExp[] = [
  /\.(tf|tfvars)$/,
  /kubernetes\//,
  /\.github\/workflows\//,
  /docker-compose/
];

interface FilteredContent {
  content: string | null; // null = fully redacted
  classification: 'source' | 'infra-metadata-only' | 'redacted';
  auditEntry: { filePath: string; reason: string } | null;
}

function filterForAgentContext(
  filePath: string,
  rawContent: string
): FilteredContent {
  
  if (SENSITIVE_PATTERNS.some(p => p.test(filePath))) {
    return {
      content: null,
      classification: 'redacted',
      auditEntry: { filePath, reason: 'sensitive-credential-pattern' }
    };
  }

  if (INFRA_PATTERNS.some(p => p.test(filePath))) {
    // Pass structural metadata, not values
    return {
      content: extractStructuralMetadata(rawContent),
      classification: 'infra-metadata-only',
      auditEntry: { filePath, reason: 'infra-content-stripped' }
    };
  }

  return { content: rawContent, classification: 'source', auditEntry: null };
}

// TypeScript: Dependency-first retrieval planner
interface RetrievalPlan {
  steps: RetrievalStep[];
  contextSlotPriority: Record<string, 'hot' | 'warm' | 'evict-after-use'>;
}

interface RetrievalStep {
  order: number;
  toolName: 'fetch_interface_contracts' | 'fetch_file_content' | 'fetch_call_graph';
  target: string;
  summarizeBeforeInjection: boolean;
}

async function buildRetrievalPlan(
  targetFile: string,
  dependencyGraph: DependencyGraph
): Promise<RetrievalPlan> {
  
  const directDeps = dependencyGraph.getDirectDependencies(targetFile);
  const affectedConsumers = dependencyGraph.getConsumers(targetFile);

  const steps: RetrievalStep[] = [
    // Step 1: Interface contracts FIRST — hot context
    ...directDeps.map((dep, i) => ({
      order: i,
      toolName: 'fetch_interface_contracts' as const,
      target: dep,
      summarizeBeforeInjection: false // contracts are already compact
    })),
    // Step 2: Target file content — warm context
    {
      order: directDeps.length,
      toolName: 'fetch_file_content' as const,
      target: targetFile,
      summarizeBeforeInjection: false
    },
    // Step 3: Consumer call patterns — summarized before injection
    ...affectedConsumers.map((consumer, i) => ({
      order: directDeps.length + 1 + i,
      toolName: 'fetch_call_graph' as const,
      target: consumer,
      summarizeBeforeInjection: true // compress usage patterns
    }))
  ];

  return {
    steps,
    contextSlotPriority: {
      interfaceContracts: 'hot',
      fileContent: 'evict-after-use',
      callGraphSummaries: 'warm'
    }
  };
}

// TypeScript: AST-based code chunker with metadata enrichment
import { parse } from '@typescript-eslint/parser';

interface CodeChunk {
  id: string;
  filePath: string;
  chunkType: 'function' | 'class' | 'interface' | 'module-summary';
  content: string;
  tokenEstimate: number;
  metadata: {
    exportedSymbols: string[];
    inboundCallSites: string[];
    lastEditTimestamp: number;
    naturalLanguageSummary: string;
  };
}

async function chunkFileByAST(
  filePath: string,
  sourceCode: string,
  summarizer: (code: string) => Promise<string>
): Promise<CodeChunk[]> {
  
  const ast = parse(sourceCode, { loc: true, range: true });
  const chunks: CodeChunk[] = [];

  for (const node of ast.body) {
    if (node.type === 'FunctionDeclaration' || 
        node.type === 'ClassDeclaration' ||
        node.type === 'TSInterfaceDeclaration') {
      
      const content = sourceCode.slice(node.range![0], node.range![1]);
      const name = 'id' in node ? node.id?.name ?? 'anonymous' : 'unknown';

      chunks.push({
        id: `${filePath}::${name}`,
        filePath,
        chunkType: node.type === 'ClassDeclaration' ? 'class' : 
                   node.type === 'TSInterfaceDeclaration' ? 'interface' : 'function',
        content,
        tokenEstimate: Math.ceil(content.length / 4),
        metadata: {
          exportedSymbols: extractExportedSymbols(node),
          inboundCallSites: [], // populated by cross-file analysis pass
          lastEditTimestamp: Date.now(),
          naturalLanguageSummary: await summarizer(content)
        }
      });
    }
  }

  return chunks;
}