Add AI provider layer with Claude Agent SDK integration

[backnotprop]

Summary

This PR introduces a complete AI provider abstraction layer for Plannotator, enabling AI-powered features (inline chat, plan Q&A, code review assistance) across all review surfaces. It includes a pluggable provider architecture, the first concrete implementation (Claude Agent SDK), HTTP endpoints for streaming responses, and comprehensive test coverage.

Key Changes

• Core Types (types.ts): Defined abstract interfaces for AI providers, sessions, messages, and context modes (plan-review, code-review, annotate). Supports forking from parent agent sessions to maintain conversation history.

• Provider Registry (provider.ts): Implemented a pluggable provider registry with factory pattern support. Allows runtime registration/unregistration of providers and dynamic provider creation from configuration.

• Session Manager (session-manager.ts): Built in-memory session tracking with LRU eviction, parent-child session lineage tracking, and metadata for UI display (timestamps, mode, labels).

• Context Builders (context.ts): Created system prompt and fork preamble generators that translate Plannotator review state into AI-friendly context. Includes content truncation to respect context windows.

• HTTP Endpoints (endpoints.ts): Implemented provider-agnostic REST endpoints:

  • POST /api/ai/session — Create or fork sessions
  • POST /api/ai/query — Stream responses via Server-Sent Events
  • POST /api/ai/abort — Cancel in-flight queries
  • GET /api/ai/sessions — List active sessions
  • GET /api/ai/capabilities — Check provider availability

• Claude Agent SDK Provider (providers/claude-agent-sdk.ts): First concrete provider implementation supporting:

  • Fresh session creation with Plannotator system prompts
  • Forking from parent Claude Code sessions with full history preservation
  • Session resumption by ID
  • Streaming text deltas and tool use messages
  • Read-only tool access (Read, Glob, Grep, WebSearch) for safe inline chat
  • Dynamic SDK import to avoid hard dependency in non-Claude environments

• Comprehensive Tests (ai.test.ts): 407 lines of test coverage including:

  • Session manager lifecycle and eviction
  • Context prompt building for all modes
  • Provider registry operations
  • Full HTTP endpoint flow (create → query → stream)
  • Error handling and edge cases

Notable Implementation Details

• Provider-agnostic design: HTTP endpoints and context builders work with any AIProvider implementation, enabling future providers (OpenCode, etc.) without changes to core infrastructure.

• Fork semantics: Forked sessions inherit parent conversation history while receiving Plannotator review context, enabling contextual questions like "why did you change this function?"

• Streaming architecture: Uses Server-Sent Events (SSE) for real-time response streaming with proper error handling and completion signaling.

• Optional peer dependency: Claude Agent SDK is a peer dependency with dynamic import, allowing the package to be used in environments where the SDK isn't installed.

• Session lineage tracking: Maintains parent-child relationships for forked sessions, enabling UI features like "show related conversations."

• Cost-bounded inline chat: Default configuration limits agentic turns and provides budget controls to keep inline chat fast and cost-effective.