@diyor28/context 1.0.0

package/src/policies/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Policy configuration exports.
+ */
+
+export * from './default-policy.js';

package/src/providers/anthropic-compiler.ts

@@ -0,0 +1,294 @@
+/**
+ * Anthropic compiler: Pure compilation to Anthropic message format.
+ *
+ * Features:
+ * - System messages with prompt caching
+ * - Cache breakpoint resolution ("after last matching block")
+ * - Diagnostics for cache configuration
+ */
+
+import type { ContextBlock } from '../types/block.js';
+import type { ContextPolicy } from '../types/policy.js';
+import type { CompiledContext, AnthropicCompiledContext } from '../types/compiled.js';
+import type { BlockCodec } from '../types/codec.js';
+import { getProviderCapabilities } from './capabilities.js';
+
+/**
+ * Cache breakpoint selector for Anthropic prompt caching.
+ */
+export interface CacheBreakpointSelector {
+  /** Block kind to match */
+  kind?: string;
+
+  /** Codec ID to match */
+  codecId?: string;
+
+  /** Tag to match */
+  tag?: string;
+
+  /** Source to match */
+  source?: string;
+}
+
+/**
+ * Cache breakpoint diagnostic.
+ */
+export interface CacheBreakpointDiagnostic {
+  /** Diagnostic level */
+  level: 'error' | 'warning' | 'info';
+
+  /** Diagnostic message */
+  message: string;
+
+  /** Matched blocks count */
+  matchedBlocks?: number;
+
+  /** Breakpoint position (if resolved) */
+  position?: number;
+}
+
+/**
+ * Anthropic compilation options.
+ */
+export interface AnthropicCompilationOptions {
+  /** Cache breakpoint selector (omit = no caching) */
+  cacheBreakpoint?: CacheBreakpointSelector;
+
+  /** Codec registry for rendering */
+  codecRegistry: Map<string, BlockCodec<unknown>>;
+}
+
+/**
+ * Compile context to Anthropic message format.
+ * Pure function: same inputs → identical outputs.
+ *
+ * @param blocks - Ordered blocks from ContextView
+ * @param policy - Context policy
+ * @param options - Compilation options
+ * @returns Anthropic compiled context
+ */
+export function compileAnthropicContext(
+  blocks: ContextBlock[],
+  policy: ContextPolicy,
+  options: AnthropicCompilationOptions
+): AnthropicCompiledContext {
+  const capabilities = getProviderCapabilities('anthropic');
+
+  // Separate system blocks from message blocks
+  const systemBlocks = blocks.filter((b) => b.meta.kind === 'pinned');
+  const messageBlocks = blocks.filter((b) => b.meta.kind !== 'pinned');
+
+  // Compile system messages
+  const systemMessages = compileSystemMessages(
+    systemBlocks,
+    options.codecRegistry,
+    options.cacheBreakpoint
+  );
+
+  // Compile message blocks
+  const messages = compileMessages(messageBlocks, options.codecRegistry);
+
+  // Calculate tokens (simplified - would use actual estimator in production)
+  const estimatedTokens = blocks.length * 100; // Placeholder
+
+  return {
+    provider: 'anthropic',
+    modelId: policy.modelId,
+    messages,
+    system: systemMessages.length > 0 ? systemMessages : undefined,
+    estimatedTokens,
+    blocks,
+    meta: {
+      compiledAt: Math.floor(Date.now() / 1000),
+      contextWindow: policy.contextWindow,
+      completionReserve: policy.completionReserve,
+      availableTokens: policy.contextWindow - policy.completionReserve,
+      overflowed: false,
+      compacted: false,
+      truncated: false,
+      tokensByKind: {},
+    },
+  };
+}
+
+/**
+ * Compile system messages with optional prompt caching.
+ *
+ * @param blocks - System blocks
+ * @param codecRegistry - Codec registry
+ * @param cacheBreakpoint - Cache breakpoint selector
+ * @returns Anthropic system messages
+ */
+function compileSystemMessages(
+  blocks: ContextBlock[],
+  codecRegistry: Map<string, BlockCodec<unknown>>,
+  cacheBreakpoint?: CacheBreakpointSelector
+): Array<{
+  type: 'text';
+  text: string;
+  cache_control?: { type: 'ephemeral' };
+}> {
+  if (blocks.length === 0) {
+    return [];
+  }
+
+  const messages: Array<{
+    type: 'text';
+    text: string;
+    cache_control?: { type: 'ephemeral' };
+  }> = [];
+
+  // Resolve cache breakpoint position
+  let cacheBreakpointPos = -1;
+  const diagnostics: CacheBreakpointDiagnostic[] = [];
+
+  if (cacheBreakpoint) {
+    const result = resolveCacheBreakpoint(blocks, cacheBreakpoint);
+    cacheBreakpointPos = result.position;
+    diagnostics.push(...result.diagnostics);
+  }
+
+  // Compile each system block
+  for (let i = 0; i < blocks.length; i++) {
+    const block = blocks[i];
+    const codec = codecRegistry.get(block.meta.codecId);
+
+    if (!codec) {
+      console.warn(`[Anthropic] Codec not found: ${block.meta.codecId}`);
+      continue;
+    }
+
+    const rendered = codec.render(block);
+    const anthropicContent = rendered.anthropic as any;
+
+    // Add cache control if this is the breakpoint
+    const isCacheBreakpoint = i === cacheBreakpointPos;
+
+    messages.push({
+      type: 'text',
+      text: anthropicContent.text || JSON.stringify(anthropicContent),
+      ...(isCacheBreakpoint && { cache_control: { type: 'ephemeral' } }),
+    });
+  }
+
+  return messages;
+}
+
+/**
+ * Compile message blocks to Anthropic message format.
+ *
+ * @param blocks - Message blocks
+ * @param codecRegistry - Codec registry
+ * @returns Anthropic messages
+ */
+function compileMessages(
+  blocks: ContextBlock[],
+  codecRegistry: Map<string, BlockCodec<unknown>>
+): Array<{
+  role: 'user' | 'assistant';
+  content: unknown;
+}> {
+  const messages: Array<{
+    role: 'user' | 'assistant';
+    content: unknown;
+  }> = [];
+
+  for (const block of blocks) {
+    const codec = codecRegistry.get(block.meta.codecId);
+
+    if (!codec) {
+      console.warn(`[Anthropic] Codec not found: ${block.meta.codecId}`);
+      continue;
+    }
+
+    const rendered = codec.render(block);
+    const anthropicContent = rendered.anthropic as any;
+
+    // Handle different block kinds
+    if (block.meta.kind === 'history') {
+      // History blocks are already in message format
+      if (Array.isArray(anthropicContent)) {
+        messages.push(...anthropicContent);
+      }
+    } else if (block.meta.kind === 'turn') {
+      // Turn blocks are user messages
+      messages.push({
+        role: 'user',
+        content: anthropicContent.content || anthropicContent,
+      });
+    } else {
+      // Other blocks (reference, memory, state, tool_output) as user messages
+      messages.push({
+        role: 'user',
+        content: typeof anthropicContent === 'string'
+          ? anthropicContent
+          : JSON.stringify(anthropicContent),
+      });
+    }
+  }
+
+  return messages;
+}
+
+/**
+ * Resolve cache breakpoint position using "after last matching block" strategy.
+ *
+ * @param blocks - System blocks
+ * @param selector - Cache breakpoint selector
+ * @returns Resolved position and diagnostics
+ */
+function resolveCacheBreakpoint(
+  blocks: ContextBlock[],
+  selector: CacheBreakpointSelector
+): {
+  position: number;
+  diagnostics: CacheBreakpointDiagnostic[];
+} {
+  const diagnostics: CacheBreakpointDiagnostic[] = [];
+
+  // Find all matching blocks
+  const matchedIndices: number[] = [];
+
+  for (let i = 0; i < blocks.length; i++) {
+    const block = blocks[i];
+
+    const matches =
+      (selector.kind === undefined || block.meta.kind === selector.kind) &&
+      (selector.codecId === undefined || block.meta.codecId === selector.codecId) &&
+      (selector.tag === undefined || block.meta.tags?.includes(selector.tag)) &&
+      (selector.source === undefined || block.meta.source === selector.source);
+
+    if (matches) {
+      matchedIndices.push(i);
+    }
+  }
+
+  // Apply "after last matching block" rule
+  if (matchedIndices.length === 0) {
+    diagnostics.push({
+      level: 'warning',
+      message: 'No blocks matched cache breakpoint selector',
+      matchedBlocks: 0,
+    });
+    return { position: -1, diagnostics };
+  }
+
+  if (matchedIndices.length > 10) {
+    diagnostics.push({
+      level: 'warning',
+      message: `Many blocks matched (${matchedIndices.length}), using last match`,
+      matchedBlocks: matchedIndices.length,
+    });
+  }
+
+  const lastMatchIndex = matchedIndices[matchedIndices.length - 1];
+
+  diagnostics.push({
+    level: 'info',
+    message: `Cache breakpoint resolved to block ${lastMatchIndex}`,
+    matchedBlocks: matchedIndices.length,
+    position: lastMatchIndex,
+  });
+
+  return { position: lastMatchIndex, diagnostics };
+}

package/src/providers/capabilities.ts

@@ -0,0 +1,144 @@
+/**
+ * Provider capabilities and feature detection.
+ */
+
+import type { Provider } from '../types/policy.js';
+
+/**
+ * Provider capabilities.
+ */
+export interface ProviderCapabilities {
+  /** Provider identifier */
+  provider: Provider;
+
+  /** Supports prompt caching */
+  supportsPromptCaching: boolean;
+
+  /** Supports structured outputs */
+  supportsStructuredOutputs: boolean;
+
+  /** Supports tool/function calling */
+  supportsToolCalling: boolean;
+
+  /** Supports vision (image inputs) */
+  supportsVision: boolean;
+
+  /** Maximum context window (tokens) */
+  maxContextWindow: number;
+
+  /** Maximum output tokens */
+  maxOutputTokens: number;
+
+  /** Message format details */
+  messageFormat: {
+    /** Supports system messages */
+    supportsSystemMessages: boolean;
+
+    /** System message location */
+    systemMessageLocation: 'inline' | 'separate' | 'none';
+
+    /** Role names */
+    roles: {
+      system?: string;
+      user: string;
+      assistant: string;
+      tool?: string;
+    };
+  };
+
+  /** Cache breakpoint configuration */
+  caching?: {
+    /** Minimum tokens for caching */
+    minTokensForCaching: number;
+
+    /** Cache TTL (seconds) */
+    cacheTTL: number;
+
+    /** Breakpoint selector strategy */
+    breakpointStrategy: 'after_last_match' | 'manual';
+  };
+}
+
+/**
+ * Get capabilities for a provider.
+ *
+ * @param provider - Provider identifier
+ * @returns Provider capabilities
+ */
+export function getProviderCapabilities(provider: Provider): ProviderCapabilities {
+  switch (provider) {
+    case 'anthropic':
+      return {
+        provider: 'anthropic',
+        supportsPromptCaching: true,
+        supportsStructuredOutputs: true,
+        supportsToolCalling: true,
+        supportsVision: true,
+        maxContextWindow: 200000,
+        maxOutputTokens: 64000,
+        messageFormat: {
+          supportsSystemMessages: true,
+          systemMessageLocation: 'separate',
+          roles: {
+            system: 'system',
+            user: 'user',
+            assistant: 'assistant',
+            tool: 'user',
+          },
+        },
+        caching: {
+          minTokensForCaching: 1024,
+          cacheTTL: 300,
+          breakpointStrategy: 'after_last_match',
+        },
+      };
+
+    case 'openai':
+      return {
+        provider: 'openai',
+        supportsPromptCaching: false,
+        supportsStructuredOutputs: true,
+        supportsToolCalling: true,
+        supportsVision: true,
+        maxContextWindow: 128000,
+        maxOutputTokens: 16000,
+        messageFormat: {
+          supportsSystemMessages: true,
+          systemMessageLocation: 'inline',
+          roles: {
+            system: 'system',
+            user: 'user',
+            assistant: 'assistant',
+            tool: 'tool',
+          },
+        },
+      };
+
+    case 'gemini':
+      return {
+        provider: 'gemini',
+        supportsPromptCaching: true,
+        supportsStructuredOutputs: true,
+        supportsToolCalling: true,
+        supportsVision: true,
+        maxContextWindow: 1000000,
+        maxOutputTokens: 64000,
+        messageFormat: {
+          supportsSystemMessages: true,
+          systemMessageLocation: 'separate',
+          roles: {
+            user: 'user',
+            assistant: 'model',
+          },
+        },
+        caching: {
+          minTokensForCaching: 32000,
+          cacheTTL: 300,
+          breakpointStrategy: 'after_last_match',
+        },
+      };
+
+    default:
+      throw new Error(`Unknown provider: ${provider}`);
+  }
+}

package/src/providers/gemini-compiler.ts

@@ -0,0 +1,272 @@
+/**
+ * Gemini compiler: Pure compilation to Gemini content format.
+ *
+ * Features:
+ * - Separate system instruction
+ * - User/model role mapping
+ * - Parts-based content structure
+ * - Caching support (for large contexts)
+ */
+
+import type { ContextBlock } from '../types/block.js';
+import type { ContextPolicy } from '../types/policy.js';
+import type { GeminiCompiledContext } from '../types/compiled.js';
+import type { BlockCodec } from '../types/codec.js';
+import { getProviderCapabilities } from './capabilities.js';
+
+/**
+ * Gemini compilation options.
+ */
+export interface GeminiCompilationOptions {
+  /** Codec registry for rendering */
+  codecRegistry: Map<string, BlockCodec<unknown>>;
+
+  /** Cache configuration (optional) */
+  caching?: {
+    /** Enable caching for large contexts */
+    enabled: boolean;
+
+    /** Minimum tokens for caching */
+    minTokens: number;
+  };
+}
+
+/**
+ * Compile context to Gemini content format.
+ * Pure function: same inputs → identical outputs.
+ *
+ * @param blocks - Ordered blocks from ContextView
+ * @param policy - Context policy
+ * @param options - Compilation options
+ * @returns Gemini compiled context
+ */
+export function compileGeminiContext(
+  blocks: ContextBlock[],
+  policy: ContextPolicy,
+  options: GeminiCompilationOptions
+): GeminiCompiledContext {
+  const capabilities = getProviderCapabilities('gemini');
+
+  // Separate system blocks from message blocks
+  const systemBlocks = blocks.filter((b) => b.meta.kind === 'pinned');
+  const messageBlocks = blocks.filter((b) => b.meta.kind !== 'pinned');
+
+  // Compile system instruction
+  const systemInstruction = compileSystemInstruction(systemBlocks, options.codecRegistry);
+
+  // Compile message blocks
+  const messages = compileMessages(messageBlocks, options.codecRegistry);
+
+  // Calculate tokens (simplified - would use actual estimator in production)
+  const estimatedTokens = blocks.length * 100; // Placeholder
+
+  return {
+    provider: 'gemini',
+    modelId: policy.modelId,
+    messages,
+    system: systemInstruction,
+    estimatedTokens,
+    blocks,
+    meta: {
+      compiledAt: Math.floor(Date.now() / 1000),
+      contextWindow: policy.contextWindow,
+      completionReserve: policy.completionReserve,
+      availableTokens: policy.contextWindow - policy.completionReserve,
+      overflowed: false,
+      compacted: false,
+      truncated: false,
+      tokensByKind: {},
+    },
+  };
+}
+
+/**
+ * Compile system instruction from system blocks.
+ * Gemini uses a single string for system instruction.
+ *
+ * @param blocks - System blocks
+ * @param codecRegistry - Codec registry
+ * @returns System instruction string (or undefined)
+ */
+function compileSystemInstruction(
+  blocks: ContextBlock[],
+  codecRegistry: Map<string, BlockCodec<unknown>>
+): string | undefined {
+  if (blocks.length === 0) {
+    return undefined;
+  }
+
+  const parts: string[] = [];
+
+  for (const block of blocks) {
+    const codec = codecRegistry.get(block.meta.codecId);
+
+    if (!codec) {
+      console.warn(`[Gemini] Codec not found: ${block.meta.codecId}`);
+      continue;
+    }
+
+    const rendered = codec.render(block);
+    const geminiContent = rendered.gemini;
+
+    // Extract text from rendered content
+    if (typeof geminiContent === 'string') {
+      parts.push(geminiContent);
+    } else {
+      parts.push(JSON.stringify(geminiContent));
+    }
+  }
+
+  return parts.join('\n\n');
+}
+
+/**
+ * Compile blocks to Gemini messages.
+ * Gemini uses user/model roles and parts-based content.
+ *
+ * @param blocks - Message blocks
+ * @param codecRegistry - Codec registry
+ * @returns Gemini messages
+ */
+function compileMessages(
+  blocks: ContextBlock[],
+  codecRegistry: Map<string, BlockCodec<unknown>>
+): Array<{
+  role: 'user' | 'model';
+  parts: unknown[];
+}> {
+  const messages: Array<{
+    role: 'user' | 'model';
+    parts: unknown[];
+  }> = [];
+
+  for (const block of blocks) {
+    const codec = codecRegistry.get(block.meta.codecId);
+
+    if (!codec) {
+      console.warn(`[Gemini] Codec not found: ${block.meta.codecId}`);
+      continue;
+    }
+
+    const rendered = codec.render(block);
+    const geminiContent = rendered.gemini as any;
+
+    // Handle different block kinds
+    if (block.meta.kind === 'history') {
+      // History blocks are already in message format
+      if (Array.isArray(geminiContent)) {
+        messages.push(...geminiContent);
+      } else {
+        messages.push(geminiContent);
+      }
+    } else if (block.meta.kind === 'turn') {
+      // Turn blocks are user messages
+      messages.push({
+        role: 'user',
+        parts: geminiContent.parts || [{ text: geminiContent }],
+      });
+    } else {
+      // Other blocks (reference, memory, state, tool_output) as user messages
+      const textContent = typeof geminiContent === 'string'
+        ? geminiContent
+        : JSON.stringify(geminiContent);
+
+      messages.push({
+        role: 'user',
+        parts: [{ text: textContent }],
+      });
+    }
+  }
+
+  // Ensure alternating user/model roles (required by Gemini)
+  return enforceAlternatingRoles(messages);
+}
+
+/**
+ * Enforce alternating user/model roles.
+ * Gemini requires strict alternation between user and model messages.
+ *
+ * @param messages - Input messages
+ * @returns Messages with enforced alternation
+ */
+function enforceAlternatingRoles(
+  messages: Array<{ role: 'user' | 'model'; parts: unknown[] }>
+): Array<{ role: 'user' | 'model'; parts: unknown[] }> {
+  const result: Array<{ role: 'user' | 'model'; parts: unknown[] }> = [];
+
+  let currentRole: 'user' | 'model' | null = null;
+  let currentParts: unknown[] = [];
+
+  for (const msg of messages) {
+    if (msg.role === currentRole) {
+      // Same role - merge parts
+      currentParts.push(...msg.parts);
+    } else {
+      // Different role - flush current message
+      if (currentRole !== null && currentParts.length > 0) {
+        result.push({ role: currentRole, parts: currentParts });
+      }
+
+      // Start new message
+      currentRole = msg.role;
+      currentParts = [...msg.parts];
+    }
+  }
+
+  // Flush final message
+  if (currentRole !== null && currentParts.length > 0) {
+    result.push({ role: currentRole, parts: currentParts });
+  }
+
+  return result;
+}
+
+/**
+ * Validate Gemini message sequence.
+ *
+ * @param messages - Gemini messages
+ * @returns Validation diagnostics
+ */
+export function validateGeminiMessages(
+  messages: Array<{ role: 'user' | 'model'; parts: unknown[] }>
+): Array<{ level: 'error' | 'warning'; message: string }> {
+  const diagnostics: Array<{ level: 'error' | 'warning'; message: string }> = [];
+
+  // Check for empty messages
+  if (messages.length === 0) {
+    diagnostics.push({
+      level: 'error',
+      message: 'Message array is empty',
+    });
+    return diagnostics;
+  }
+
+  // Check for strict alternation
+  let lastRole: 'user' | 'model' | null = null;
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+
+    if (msg.role === lastRole) {
+      diagnostics.push({
+        level: 'error',
+        message: `Consecutive ${msg.role} messages at index ${i} (Gemini requires strict alternation)`,
+      });
+    }
+
+    lastRole = msg.role;
+  }
+
+  // Check for empty parts
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+
+    if (msg.parts.length === 0) {
+      diagnostics.push({
+        level: 'error',
+        message: `Empty parts array at index ${i}`,
+      });
+    }
+  }
+
+  return diagnostics;
+}