@vibe-lang/runtime 0.2.5

package/src/parser.ts

@@ -0,0 +1,2 @@
+// Re-export from new location for backwards compatibility
+export * from './parser/index';

package/src/runtime/ai/cache-chunking.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'bun:test';
+import { chunkContextForCaching } from './cache-chunking';
+
+describe('chunkContextForCaching', () => {
+  it('returns empty chunks for empty context', () => {
+    const result = chunkContextForCaching('');
+    expect(result.chunks).toEqual([]);
+    expect(result.cacheBreakpointIndex).toBe(-1);
+  });
+
+  it('returns empty chunks for whitespace-only context', () => {
+    const result = chunkContextForCaching('   \n\n   ');
+    expect(result.chunks).toEqual([]);
+    expect(result.cacheBreakpointIndex).toBe(-1);
+  });
+
+  it('creates single chunk for small context', () => {
+    const context = '- name: Alice\n- age: 30';
+    const result = chunkContextForCaching(context);
+    expect(result.chunks.length).toBe(1);
+    expect(result.chunks[0].content).toBe(context);
+    expect(result.cacheBreakpointIndex).toBe(-1); // No 2nd-to-last with single chunk
+  });
+
+  it('creates multiple chunks when context exceeds threshold', () => {
+    // Create context that exceeds 5000 tokens (~20000 chars)
+    const largeLine = '- data: ' + 'x'.repeat(10000); // ~2500 tokens
+    const context = [largeLine, largeLine, largeLine].join('\n'); // ~7500 tokens total
+
+    const result = chunkContextForCaching(context);
+    expect(result.chunks.length).toBeGreaterThan(1);
+  });
+
+  it('sets cache breakpoint on 2nd-to-last chunk', () => {
+    // Create context that will produce exactly 2 chunks
+    const largeLine = '- data: ' + 'x'.repeat(10000);
+    const context = [largeLine, largeLine].join('\n');
+
+    const result = chunkContextForCaching(context);
+    expect(result.chunks.length).toBe(2);
+    expect(result.cacheBreakpointIndex).toBe(0); // 2nd-to-last of 2 = index 0
+  });
+
+  it('sets cache breakpoint correctly for 3 chunks', () => {
+    // Create context that will produce 3 chunks
+    const largeLine = '- data: ' + 'x'.repeat(10000);
+    const context = [largeLine, largeLine, largeLine].join('\n');
+
+    const result = chunkContextForCaching(context);
+    expect(result.chunks.length).toBe(3);
+    expect(result.cacheBreakpointIndex).toBe(1); // 2nd-to-last of 3 = index 1
+  });
+
+  it('preserves line content in chunks', () => {
+    const lines = ['- a: 1', '- b: 2', '- c: 3'];
+    const context = lines.join('\n');
+
+    const result = chunkContextForCaching(context);
+    expect(result.chunks.length).toBe(1);
+    expect(result.chunks[0].content).toBe(context);
+  });
+
+  it('estimates token count approximately', () => {
+    // 400 chars should be ~100 tokens (4 chars/token)
+    const context = 'x'.repeat(400);
+    const result = chunkContextForCaching(context);
+    expect(result.chunks[0].tokenEstimate).toBe(100);
+  });
+});

package/src/runtime/ai/cache-chunking.ts

@@ -0,0 +1,73 @@
+// Anthropic prompt caching utilities
+// Splits context into chunks for progressive caching
+
+const TARGET_CHUNK_TOKENS = 5000;
+const CHARS_PER_TOKEN = 4; // Rough estimate for token counting
+
+/** A chunk of context content with estimated token count */
+export interface CacheChunk {
+  content: string;
+  tokenEstimate: number;
+}
+
+/** Chunked context ready for Anthropic API with cache breakpoint info */
+export interface ChunkedContext {
+  chunks: CacheChunk[];
+  cacheBreakpointIndex: number; // Which chunk gets cache_control (-1 if none)
+}
+
+/**
+ * Estimate token count for a string using character-based heuristic.
+ */
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+
+/**
+ * Split formatted context text into chunks of ~5000 tokens each.
+ * Splits by line boundaries (each context entry is on its own line).
+ * Accumulates lines until hitting threshold, then starts new chunk.
+ * Cache breakpoint is placed on 2nd-to-last chunk to allow latest chunk to change.
+ */
+export function chunkContextForCaching(contextText: string): ChunkedContext {
+  const trimmed = contextText.trim();
+  if (!trimmed) {
+    return { chunks: [], cacheBreakpointIndex: -1 };
+  }
+
+  const lines = trimmed.split('\n');
+  const chunks: CacheChunk[] = [];
+  let currentLines: string[] = [];
+  let currentTokens = 0;
+
+  for (const line of lines) {
+    const lineTokens = estimateTokens(line);
+
+    // If adding this line exceeds threshold and we have content, start new chunk
+    if (currentTokens + lineTokens > TARGET_CHUNK_TOKENS && currentLines.length > 0) {
+      chunks.push({
+        content: currentLines.join('\n'),
+        tokenEstimate: currentTokens,
+      });
+      currentLines = [];
+      currentTokens = 0;
+    }
+
+    currentLines.push(line);
+    currentTokens += lineTokens;
+  }
+
+  // Push final chunk if we have content
+  if (currentLines.length > 0) {
+    chunks.push({
+      content: currentLines.join('\n'),
+      tokenEstimate: currentTokens,
+    });
+  }
+
+  // Cache breakpoint on 2nd-to-last chunk (or -1 if < 2 chunks)
+  // This allows the last chunk to change without invalidating the cache
+  const cacheBreakpointIndex = chunks.length >= 2 ? chunks.length - 2 : -1;
+
+  return { chunks, cacheBreakpointIndex };
+}

package/src/runtime/ai/client.ts

@@ -0,0 +1,109 @@
+// AI Client - Main orchestration for AI API calls
+
+import type { AIProviderType, AIRequest, AIResponse, TargetType, ModelConfig, ProviderExecutor } from './types';
+import type { VibeToolValue } from '../tools/types';
+import { withRetry } from './retry';
+import { executeOpenAI } from './providers/openai';
+import { executeAnthropic } from './providers/anthropic';
+import { executeGoogle } from './providers/google';
+
+/**
+ * Detect provider from URL.
+ * Returns 'openai' as default for unknown/custom endpoints.
+ */
+export function detectProvider(url: string | null): AIProviderType {
+  if (!url) return 'openai';
+
+  const u = url.toLowerCase();
+  if (u.includes('anthropic')) return 'anthropic';
+  if (u.includes('google') || u.includes('generativelanguage')) return 'google';
+  return 'openai';
+}
+
+/**
+ * Get the provider executor function for a given provider type.
+ */
+export function getProviderExecutor(provider: AIProviderType): ProviderExecutor {
+  switch (provider) {
+    case 'anthropic':
+      return executeAnthropic;
+    case 'google':
+      return executeGoogle;
+    case 'openai':
+    default:
+      return executeOpenAI;
+  }
+}
+
+/**
+ * Build an AI request from the given parameters.
+ */
+export function buildAIRequest(
+  model: ModelConfig,
+  prompt: string,
+  contextText: string,
+  operationType: 'do' | 'vibe',
+  targetType: TargetType
+): AIRequest {
+  return {
+    operationType,
+    prompt,
+    contextText,
+    targetType,
+    model,
+  };
+}
+
+/** Model value as stored in runtime locals */
+export interface VibeModelValue {
+  __vibeModel: true;
+  name: string | null;
+  apiKey: string | null;
+  url: string | null;
+  provider?: AIProviderType | null;
+  maxRetriesOnError?: number | null;
+  tools?: VibeToolValue[];  // Tools available to this model for AI calls
+}
+
+/**
+ * Execute an AI request with the appropriate provider.
+ * Handles provider detection, request building, and retry logic.
+ */
+export async function executeAI(
+  modelValue: VibeModelValue,
+  prompt: string,
+  contextText: string,
+  operationType: 'do' | 'vibe',
+  targetType: TargetType
+): Promise<AIResponse> {
+  // Validate model config
+  if (!modelValue.name) {
+    throw new Error('Model name is required');
+  }
+  if (!modelValue.apiKey) {
+    throw new Error('API key is required');
+  }
+
+  // Determine provider (explicit or auto-detect)
+  const provider: AIProviderType =
+    (modelValue.provider as AIProviderType) ?? detectProvider(modelValue.url);
+
+  // Build model config
+  const model: ModelConfig = {
+    name: modelValue.name,
+    apiKey: modelValue.apiKey,
+    url: modelValue.url,
+    provider,
+    maxRetriesOnError: modelValue.maxRetriesOnError ?? undefined,
+  };
+
+  // Build request
+  const request = buildAIRequest(model, prompt, contextText, operationType, targetType);
+
+  // Get provider executor
+  const execute = getProviderExecutor(provider);
+
+  // Execute with retry logic
+  const maxRetries = modelValue.maxRetriesOnError ?? 3;
+  return withRetry(() => execute(request), { maxRetries });
+}

package/src/runtime/ai/context.ts

@@ -0,0 +1,168 @@
+// Unified AI Context System
+// Single source of truth for what gets sent to AI models and logged
+//
+// Architecture:
+//   buildAIContext(state) → AIContext (structured)
+//        ↓                      ↓
+//   formatForProvider()    formatForLog()
+//        ↓                      ↓
+//   Provider API call      Human-readable log
+
+import type { RuntimeState, ContextEntry } from '../types';
+import type { ToolSchema } from '../tools/types';
+import type { TargetType, ModelConfig } from './types';
+import { buildGlobalContext, formatContextForAI } from '../context';
+// Import formatters for consistent message building
+import {
+  buildSystemMessage as buildSystemMessageImpl,
+  buildToolSystemMessage as buildToolSystemMessageImpl,
+  buildPromptMessage as buildPromptMessageImpl,
+} from './formatters';
+
+/**
+ * Message in the AI conversation.
+ * Represents a single message sent to or received from the model.
+ */
+export interface AIMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+  /** For assistant messages with tool calls */
+  toolCalls?: Array<{
+    id: string;
+    toolName: string;
+    args: Record<string, unknown>;
+  }>;
+  /** For user messages with tool results */
+  toolResults?: Array<{
+    toolCallId: string;
+    result?: unknown;
+    error?: string;
+  }>;
+}
+
+/**
+ * Complete AI context for a single interaction.
+ * This is the single source of truth for:
+ * - What gets sent to the AI model
+ * - What gets logged for debugging
+ */
+export interface AIContext {
+  /** Operation type */
+  operationType: 'do' | 'vibe';
+
+  /** Model being used */
+  model: ModelConfig;
+
+  /** Target type for response parsing */
+  targetType: TargetType;
+
+  /** Available tools (if any) */
+  tools?: ToolSchema[];
+
+  /** The complete message sequence to send to the model */
+  messages: AIMessage[];
+
+  /** Structured execution context (for detailed logging) */
+  executionContext: ContextEntry[];
+}
+
+/**
+ * Build the complete AI context from runtime state.
+ * This is the SINGLE SOURCE OF TRUTH for what gets sent to the model.
+ */
+export function buildAIContext(
+  state: RuntimeState,
+  model: ModelConfig,
+  prompt: string,
+  targetType: TargetType,
+  tools?: ToolSchema[],
+  previousToolCalls?: Array<{ id: string; toolName: string; args: Record<string, unknown> }>,
+  toolResults?: Array<{ toolCallId: string; result?: unknown; error?: string }>
+): AIContext {
+  const operationType = state.pendingAI?.type ?? 'do';
+
+  // Build structured execution context from state
+  const executionContext = buildGlobalContext(state);
+  const formattedContext = formatContextForAI(executionContext);
+
+  // Build the message sequence
+  const messages: AIMessage[] = [];
+
+  // 1. System message
+  messages.push({
+    role: 'system',
+    content: buildSystemMessage(),
+  });
+
+  // 2. Tool system message (if tools available)
+  if (tools && tools.length > 0) {
+    messages.push({
+      role: 'system',
+      content: buildToolSystemMessage(tools),
+    });
+  }
+
+  // 3. Context message (if there's execution context)
+  if (formattedContext.text) {
+    messages.push({
+      role: 'user',
+      content: `Here is the current program context:\n\n${formattedContext.text}`,
+    });
+  }
+
+  // 4. Current prompt
+  messages.push({
+    role: 'user',
+    content: buildPromptMessage(prompt, targetType),
+  });
+
+  // 5. Previous tool calls and results (for multi-turn)
+  if (previousToolCalls?.length && toolResults?.length) {
+    messages.push({
+      role: 'assistant',
+      content: '', // Content comes from tool calls
+      toolCalls: previousToolCalls,
+    });
+    messages.push({
+      role: 'user',
+      content: '', // Content comes from tool results
+      toolResults: toolResults,
+    });
+  }
+
+  return {
+    operationType,
+    model,
+    targetType,
+    tools,
+    messages,
+    executionContext,
+  };
+}
+
+/**
+ * Build the base system message.
+ * Delegates to formatters.ts for consistent formatting.
+ */
+function buildSystemMessage(): string {
+  return buildSystemMessageImpl();
+}
+
+/**
+ * Build the tool system message describing available tools.
+ * Delegates to formatters.ts for consistent formatting.
+ */
+function buildToolSystemMessage(tools: ToolSchema[]): string {
+  return buildToolSystemMessageImpl(tools) ?? '';
+}
+
+/**
+ * Build the prompt message with type instructions if needed.
+ * Delegates to formatters.ts for consistent formatting.
+ */
+function buildPromptMessage(prompt: string, _targetType: TargetType): string {
+  return buildPromptMessageImpl(prompt);
+}
+
+// Re-export formatters for backward compatibility
+export { buildSystemMessage, buildToolSystemMessage, buildPromptMessage };