@vibe-lang/runtime 0.2.5

package/src/runtime/ai/formatters.ts

@@ -0,0 +1,316 @@
+// Message formatting utilities for AI providers
+
+import type { ToolSchema } from '../tools/types';
+
+/** Message structure for AI providers */
+export interface Message {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+/**
+ * Build system message with Vibe processing instructions.
+ */
+export function buildSystemMessage(): string {
+  return `You are an AI assistant integrated into the Vibe programming language runtime.
+Your responses will be used programmatically in the execution flow.
+Be concise and precise. Follow any type constraints exactly.
+When context is provided, use it to inform your response.`;
+}
+
+/**
+ * Build context message from formatted context text.
+ * Returns null if context is empty.
+ */
+export function buildContextMessage(contextText: string): string | null {
+  const trimmed = contextText.trim();
+  if (!trimmed) return null;
+
+  return `Here is the current program context:\n\n${trimmed}`;
+}
+
+/**
+ * Format a JsonSchema as a readable type string.
+ * Examples: "string", "number", "{name: string, age: number}", "string[]"
+ */
+function formatJsonSchemaType(schema: ToolSchema['parameters'][0]['type']): string {
+  if (schema.type === 'array') {
+    const itemType = schema.items ? formatJsonSchemaType(schema.items) : 'any';
+    return `${itemType}[]`;
+  }
+
+  if (schema.type === 'object' && schema.properties) {
+    const props = Object.entries(schema.properties)
+      .map(([name, propSchema]) => `${name}: ${formatJsonSchemaType(propSchema)}`)
+      .join(', ');
+    return `{${props}}`;
+  }
+
+  return schema.type;
+}
+
+/**
+ * Build system message describing available tools.
+ * Returns null if no tools are provided.
+ */
+export function buildToolSystemMessage(tools: ToolSchema[]): string | null {
+  if (!tools.length) return null;
+
+  const toolList = tools
+    .map((t) => {
+      // Format: name(param: type, param: type)
+      const signature = t.parameters
+        .map((p) => `${p.name}: ${formatJsonSchemaType(p.type)}`)
+        .join(', ');
+
+      const lines: string[] = [`- ${t.name}(${signature})`];
+
+      // Add tool description
+      if (t.description) {
+        lines.push(`    ${t.description}`);
+      }
+
+      // Add parameter descriptions if any exist
+      const paramDescs = t.parameters.filter((p) => p.description);
+      if (paramDescs.length > 0) {
+        lines.push('    Parameters:');
+        for (const p of paramDescs) {
+          lines.push(`      ${p.name}: ${p.description}`);
+        }
+      }
+
+      return lines.join('\n');
+    })
+    .join('\n');
+
+  return `You have access to the following tools:\n${toolList}\n\nCall tools when needed to complete the task.`;
+}
+
+/**
+ * Build the prompt message.
+ * Type instructions are no longer needed since we use tool-based returns.
+ */
+export function buildPromptMessage(prompt: string): string {
+  return prompt;
+}
+
+/**
+ * Build messages array for chat-style APIs (OpenAI, Anthropic).
+ * Returns: [system, tools?, context?, prompt]
+ */
+export function buildMessages(
+  prompt: string,
+  contextText: string,
+  tools?: ToolSchema[]
+): Message[] {
+  const messages: Message[] = [
+    { role: 'system', content: buildSystemMessage() },
+  ];
+
+  // Add tool descriptions as second system message
+  if (tools?.length) {
+    const toolMessage = buildToolSystemMessage(tools);
+    if (toolMessage) {
+      messages.push({ role: 'system', content: toolMessage });
+    }
+  }
+
+  const contextMessage = buildContextMessage(contextText);
+  if (contextMessage) {
+    messages.push({ role: 'user', content: contextMessage });
+  }
+
+  messages.push({ role: 'user', content: prompt });
+
+  return messages;
+}
+
+/**
+ * Extract text content from various API response formats.
+ */
+export function extractTextContent(response: unknown): string {
+  // Anthropic format: { content: [{ type: "text", text: "..." }] }
+  if (hasProperty(response, 'content') && Array.isArray(response.content)) {
+    const textBlock = response.content.find(
+      (block: unknown) => hasProperty(block, 'type') && block.type === 'text'
+    );
+    if (textBlock && hasProperty(textBlock, 'text')) {
+      return String(textBlock.text);
+    }
+  }
+
+  // OpenAI format: { choices: [{ message: { content: "..." } }] }
+  if (hasProperty(response, 'choices') && Array.isArray(response.choices)) {
+    const first = response.choices[0];
+    if (hasProperty(first, 'message') && hasProperty(first.message, 'content')) {
+      return String(first.message.content);
+    }
+  }
+
+  // Google format: { candidates: [{ content: { parts: [{ text: "..." }] } }] }
+  if (hasProperty(response, 'candidates') && Array.isArray(response.candidates)) {
+    const first = response.candidates[0];
+    if (hasProperty(first, 'content') && hasProperty(first.content, 'parts')) {
+      const parts = first.content.parts as unknown[];
+      const textPart = parts.find((p: unknown) => hasProperty(p, 'text'));
+      if (textPart && hasProperty(textPart, 'text')) {
+        return String(textPart.text);
+      }
+    }
+  }
+
+  throw new Error('Unable to extract text content from response');
+}
+
+/**
+ * Type guard for checking if an object has a property.
+ */
+function hasProperty<K extends string>(
+  obj: unknown,
+  key: K
+): obj is Record<K, unknown> {
+  return typeof obj === 'object' && obj !== null && key in obj;
+}
+
+/**
+ * Extract usage information from various API response formats.
+ */
+export function extractUsage(
+  response: unknown
+): { inputTokens: number; outputTokens: number } | undefined {
+  // Anthropic format: { usage: { input_tokens, output_tokens } }
+  if (hasProperty(response, 'usage') && hasProperty(response.usage, 'input_tokens')) {
+    const usage = response.usage as Record<string, unknown>;
+    return {
+      inputTokens: Number(usage.input_tokens),
+      outputTokens: Number(usage.output_tokens ?? 0),
+    };
+  }
+
+  // OpenAI format: { usage: { prompt_tokens, completion_tokens } }
+  if (hasProperty(response, 'usage') && hasProperty(response.usage, 'prompt_tokens')) {
+    const usage = response.usage as Record<string, unknown>;
+    return {
+      inputTokens: Number(usage.prompt_tokens),
+      outputTokens: Number(usage.completion_tokens ?? 0),
+    };
+  }
+
+  // Google format: { usageMetadata: { promptTokenCount, candidatesTokenCount } }
+  if (hasProperty(response, 'usageMetadata')) {
+    const meta = response.usageMetadata as Record<string, unknown>;
+    return {
+      inputTokens: Number(meta.promptTokenCount ?? 0),
+      outputTokens: Number(meta.candidatesTokenCount ?? 0),
+    };
+  }
+
+  return undefined;
+}
+
+/**
+ * Scope parameter for vibe code generation.
+ */
+export interface VibeScopeParam {
+  name: string;
+  type: string;
+  value: unknown;
+}
+
+/**
+ * Build system message for vibe code generation.
+ * Instructs the AI to generate a valid Vibe function.
+ */
+export function buildVibeSystemMessage(scopeParams: VibeScopeParam[]): string {
+  const paramList = scopeParams
+    .map(p => `  - ${p.name}: ${p.type}`)
+    .join('\n');
+
+  return `You are generating a Vibe programming language function.
+
+REQUIREMENTS:
+1. Generate EXACTLY ONE function declaration
+2. No markdown, no explanations, no code fences - ONLY the function code
+3. The function will receive these parameters from the calling scope:
+${paramList || '  (none)'}
+
+4. Use ONLY these parameters - no other variables are accessible
+5. The function must have a return statement
+
+VIBE SYNTAX REFERENCE:
+- Types: text, number, boolean, json, arrays (text[], number[])
+- Variables: let x = value, const x = value
+- Control flow: if/else, for x in array, while (condition)
+- AI calls: vibe "prompt" model default (use the model parameter)
+- TS blocks: ts(params) { return jsCode; }
+- Return: return value
+
+IMPORTANT - FUNCTION SIGNATURE:
+- The FIRST parameter must always be 'model' (the AI model to use)
+- Additional parameters are the scope variables listed above
+- Example: function myFunc(model, x, y): text { ... }
+
+RESTRICTIONS:
+- You can ONLY use function parameters and locally-created variables
+- No access to external functions or global variables
+- For AI calls, use the 'model' parameter: vibe "prompt" model default
+
+EXAMPLE:
+function processData(model, items: text[], count: number): text {
+  let result = ""
+  for item in items {
+    result = result + item
+  }
+  return result
+}
+
+Generate ONLY the function code.`;
+}
+
+/**
+ * Build user prompt for vibe code generation.
+ */
+export function buildVibePromptMessage(userPrompt: string, scopeParams: VibeScopeParam[]): string {
+  const paramContext = scopeParams
+    .map(p => `${p.name} (${p.type}) = ${formatVibeValue(p.value)}`)
+    .join('\n');
+
+  const contextSection = paramContext
+    ? `\nAvailable parameters and their current values:\n${paramContext}\n`
+    : '';
+
+  return `Task: ${userPrompt}${contextSection}
+Generate a function that accomplishes this task using only the available parameters.`;
+}
+
+/**
+ * Format a value for display in vibe context.
+ */
+function formatVibeValue(value: unknown): string {
+  if (value === null || value === undefined) return 'null';
+  if (typeof value === 'string') {
+    if (value.length > 50) return `"${value.substring(0, 50)}..."`;
+    return `"${value}"`;
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '[]';
+    if (value.length > 3) return `[${formatVibeValue(value[0])}, ... (${value.length} items)]`;
+    return `[${value.map(formatVibeValue).join(', ')}]`;
+  }
+  return JSON.stringify(value).substring(0, 50);
+}
+
+/**
+ * Build messages array for vibe code generation.
+ * Returns: [system, prompt]
+ */
+export function buildVibeMessages(
+  userPrompt: string,
+  scopeParams: VibeScopeParam[]
+): Message[] {
+  return [
+    { role: 'system', content: buildVibeSystemMessage(scopeParams) },
+    { role: 'user', content: buildVibePromptMessage(userPrompt, scopeParams) },
+  ];
+}

package/src/runtime/ai/index.ts

@@ -0,0 +1,38 @@
+// AI Module - Re-exports
+
+// Types
+export type {
+  AIProviderType,
+  TargetType,
+  ModelConfig,
+  AIRequest,
+  AIResponse,
+  ProviderExecutor,
+  RetryOptions,
+} from './types';
+export { AIError } from './types';
+
+// Client
+export {
+  executeAI,
+  detectProvider,
+  getProviderExecutor,
+  buildAIRequest,
+  type VibeModelValue,
+} from './client';
+
+// Providers
+export { executeOpenAI, OPENAI_CONFIG } from './providers/openai';
+export { executeAnthropic, ANTHROPIC_CONFIG } from './providers/anthropic';
+export { executeGoogle } from './providers/google';
+
+// Utilities
+export { withRetry, isRetryableError, calculateDelay, createAIErrorFromResponse } from './retry';
+export {
+  buildSystemMessage,
+  buildContextMessage,
+  buildPromptMessage,
+  buildMessages,
+  extractTextContent,
+  extractUsage,
+} from './formatters';

package/src/runtime/ai/language-ref.ts

@@ -0,0 +1,38 @@
+// Language reference loader for AI context
+// Loads and caches the Vibe language reference document
+
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+let cachedLanguageRef: string | null = null;
+
+/**
+ * Get the Vibe language reference document content.
+ * Cached after first load.
+ */
+export function getLanguageReference(): string {
+  if (cachedLanguageRef !== null) {
+    return cachedLanguageRef;
+  }
+
+  try {
+    // Navigate from src/runtime/ai/ to docs/
+    const currentDir = dirname(fileURLToPath(import.meta.url));
+    const docsPath = join(currentDir, '..', '..', '..', 'docs', 'language-reference.md');
+    cachedLanguageRef = readFileSync(docsPath, 'utf-8');
+    return cachedLanguageRef;
+  } catch {
+    // If file not found (e.g., in bundled distribution), return empty
+    cachedLanguageRef = '';
+    return cachedLanguageRef;
+  }
+}
+
+/**
+ * Clear the cached language reference.
+ * Useful for testing.
+ */
+export function clearLanguageRefCache(): void {
+  cachedLanguageRef = null;
+}

package/src/runtime/ai/providers/anthropic.ts

@@ -0,0 +1,253 @@
+// Anthropic Provider Implementation using official SDK
+
+import Anthropic from '@anthropic-ai/sdk';
+import type { AIRequest, AIResponse, AIToolCall, ThinkingLevel } from '../types';
+import { AIError } from '../types';
+import { buildSystemMessage, buildPromptMessage, buildToolSystemMessage } from '../formatters';
+import { chunkContextForCaching } from '../cache-chunking';
+import { toAnthropicTools } from '../tool-schema';
+
+/** Anthropic provider configuration */
+export const ANTHROPIC_CONFIG = {
+  defaultUrl: 'https://api.anthropic.com',
+};
+
+/** Beta headers */
+const EXTENDED_THINKING_BETA = 'interleaved-thinking-2025-05-14';
+
+/** Map thinking level to Anthropic budget_tokens */
+const THINKING_BUDGET_MAP: Record<ThinkingLevel, number> = {
+  none: 0,
+  low: 1024,      // Minimum required
+  medium: 4096,
+  high: 10240,
+  max: 32768,
+};
+
+/**
+ * Execute an AI request using the Anthropic SDK.
+ */
+export async function executeAnthropic(request: AIRequest): Promise<AIResponse> {
+  const { prompt, contextText, model, tools, previousToolCalls, toolResults, messages: overrideMessages } = request;
+
+  // Create Anthropic client
+  const client = new Anthropic({
+    apiKey: model.apiKey,
+    baseURL: model.url ?? ANTHROPIC_CONFIG.defaultUrl,
+  });
+
+  // If messages are provided (e.g., for vibe), use simplified path
+  if (overrideMessages) {
+    return executeWithOverrideMessages(client, model, overrideMessages);
+  }
+
+  // Build system messages
+  const systemMessage = buildSystemMessage();
+  const toolSystemMessage = tools?.length ? buildToolSystemMessage(tools) : null;
+
+  // Build prompt message
+  const promptMessage = buildPromptMessage(prompt);
+
+  // Chunk context for progressive caching
+  const { chunks, cacheBreakpointIndex } = chunkContextForCaching(contextText);
+
+  // Build initial user messages: context chunks + prompt
+  const initialUserMessages: Record<string, unknown>[] = [
+    // Context chunks as separate messages (if any)
+    ...chunks.map((chunk, i) => ({
+      role: 'user' as const,
+      content: i === 0 ? `Here is the current program context:\n\n${chunk.content}` : chunk.content,
+      // Cache control on 2nd-to-last chunk to allow latest chunk to change
+      ...(i === cacheBreakpointIndex ? { cache_control: { type: 'ephemeral' as const } } : {}),
+    })),
+    // Prompt is always last (never cached)
+    { role: 'user' as const, content: promptMessage },
+  ];
+
+  // Build conversation messages including tool results if this is a follow-up
+  let allMessages = initialUserMessages;
+  if (previousToolCalls?.length && toolResults?.length) {
+    // Add assistant message with tool_use blocks
+    const assistantContent = previousToolCalls.map(call => ({
+      type: 'tool_use' as const,
+      id: call.id,
+      name: call.toolName,
+      input: call.args,
+    }));
+
+    // Add user message with tool_result blocks
+    const toolResultContent = toolResults.map(result => ({
+      type: 'tool_result' as const,
+      tool_use_id: result.toolCallId,
+      content: result.error
+        ? `Error: ${result.error}`
+        : (typeof result.result === 'string' ? result.result : JSON.stringify(result.result)),
+    }));
+
+    allMessages = [
+      ...initialUserMessages,
+      { role: 'assistant' as const, content: assistantContent },
+      { role: 'user' as const, content: toolResultContent },
+    ];
+  }
+
+  try {
+    // Build system array with optional tool descriptions
+    const systemBlocks = [
+      {
+        type: 'text',
+        text: systemMessage,
+        cache_control: { type: 'ephemeral' },
+      },
+    ];
+    if (toolSystemMessage) {
+      systemBlocks.push({
+        type: 'text',
+        text: toolSystemMessage,
+        cache_control: { type: 'ephemeral' },
+      });
+    }
+
+    // Build request params with cache control on system message
+    const params: Record<string, unknown> = {
+      model: model.name,
+      max_tokens: 16384, // Increased to support thinking tokens
+      system: systemBlocks,
+      messages: allMessages,
+    };
+
+    // Add tools if provided
+    if (tools?.length) {
+      params.tools = toAnthropicTools(tools);
+    }
+
+    // Add extended thinking if level specified and not 'none'
+    const thinkingLevel = model.thinkingLevel as ThinkingLevel | undefined;
+    const thinkingBudget = thinkingLevel ? THINKING_BUDGET_MAP[thinkingLevel] : 0;
+    if (thinkingBudget > 0) {
+      params.thinking = {
+        type: 'enabled',
+        budget_tokens: thinkingBudget,
+      };
+    }
+
+    // Make API request - use beta endpoint for extended thinking
+    // Response type is Message (non-streaming since we don't pass stream: true)
+    const response = thinkingBudget > 0
+      ? await client.beta.messages.create({
+          ...params,
+          betas: [EXTENDED_THINKING_BETA],
+        } as Parameters<typeof client.beta.messages.create>[0])
+      : await client.messages.create(params as unknown as Parameters<typeof client.messages.create>[0]);
+
+    // Cast to Message type (we know it's not streaming)
+    const message = response as Anthropic.Message;
+
+    // Extract text content from response
+    const textBlock = message.content.find((block): block is Anthropic.TextBlock => block.type === 'text');
+    const content = textBlock?.text ?? '';
+
+    // Extract tool_use blocks
+    const toolUseBlocks = message.content.filter(
+      (block): block is Anthropic.ToolUseBlock => block.type === 'tool_use'
+    );
+    let toolCalls: AIToolCall[] | undefined;
+    if (toolUseBlocks.length > 0) {
+      toolCalls = toolUseBlocks.map((block) => ({
+        id: block.id,
+        toolName: block.name,
+        args: block.input as Record<string, unknown>,
+      }));
+    }
+
+    // Determine stop reason
+    const stopReason =
+      message.stop_reason === 'tool_use'
+        ? 'tool_use'
+        : message.stop_reason === 'max_tokens'
+          ? 'length'
+          : 'end';
+
+    // Extract usage including cache and thinking tokens
+    const rawUsage = message.usage as unknown as Record<string, unknown> | undefined;
+    const usage = rawUsage
+      ? {
+          inputTokens: Number(rawUsage.input_tokens ?? 0),
+          outputTokens: Number(rawUsage.output_tokens ?? 0),
+          cachedInputTokens: rawUsage.cache_read_input_tokens ? Number(rawUsage.cache_read_input_tokens) : undefined,
+          cacheCreationTokens: rawUsage.cache_creation_input_tokens ? Number(rawUsage.cache_creation_input_tokens) : undefined,
+          thinkingTokens: rawUsage.thinking_tokens ? Number(rawUsage.thinking_tokens) : undefined,
+        }
+      : undefined;
+
+    // For text responses, parsedValue is just the content
+    // For typed responses, the value comes from return tool calls (handled by tool-loop)
+    return { content, parsedValue: content, usage, toolCalls, stopReason };
+  } catch (error) {
+    if (error instanceof Anthropic.APIError) {
+      const isRetryable = error.status === 429 || (error.status ?? 0) >= 500;
+      throw new AIError(
+        `Anthropic API error (${error.status}): ${error.message}`,
+        error.status,
+        isRetryable
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Execute with override messages (used by vibe for custom system prompt).
+ * Simpler path without context chunking, caching, or structured output.
+ */
+async function executeWithOverrideMessages(
+  client: Anthropic,
+  model: AIRequest['model'],
+  messages: Array<{ role: 'system' | 'user' | 'assistant'; content: string }>
+): Promise<AIResponse> {
+  // Separate system messages from user/assistant messages
+  const systemMessages = messages.filter(m => m.role === 'system');
+  const conversationMessages = messages.filter(m => m.role !== 'system');
+
+  // Build system content
+  const systemContent = systemMessages.map(m => m.content).join('\n\n');
+
+  try {
+    const response = await client.messages.create({
+      model: model.name,
+      max_tokens: 4096,
+      system: systemContent,
+      messages: conversationMessages.map(m => ({
+        role: m.role as 'user' | 'assistant',
+        content: m.content,
+      })),
+    });
+
+    // Extract text content
+    const textBlock = response.content.find(
+      (block): block is Anthropic.TextBlock => block.type === 'text'
+    );
+    const content = textBlock?.text ?? '';
+
+    // Extract usage
+    const rawUsage = response.usage as unknown as Record<string, unknown> | undefined;
+    const usage = rawUsage
+      ? {
+          inputTokens: Number(rawUsage.input_tokens ?? 0),
+          outputTokens: Number(rawUsage.output_tokens ?? 0),
+        }
+      : undefined;
+
+    return { content, parsedValue: content, usage, toolCalls: [], stopReason: 'end' };
+  } catch (error) {
+    if (error instanceof Anthropic.APIError) {
+      const isRetryable = error.status === 429 || (error.status ?? 0) >= 500;
+      throw new AIError(
+        `Anthropic API error (${error.status}): ${error.message}`,
+        error.status,
+        isRetryable
+      );
+    }
+    throw error;
+  }
+}