@vibe-lang/runtime 0.2.5

package/src/runtime/ai/tool-loop.ts

@@ -0,0 +1,203 @@
+// Tool Execution Loop for AI-Initiated Tool Calling
+// Handles multi-turn conversations where AI calls tools
+
+import type { AIRequest, AIResponse, AIToolCall, AIToolResult } from './types';
+import type { VibeToolValue } from '../tools/types';
+import { isReturnToolCall } from './return-tools';
+
+/** Options for the tool execution loop */
+export interface ToolLoopOptions {
+  /** Maximum number of tool calling rounds (default: 10) */
+  maxRounds?: number;
+  /** Callback when a tool call is executed */
+  onToolCall?: (call: AIToolCall, result: unknown, error?: string) => void;
+  /** Expected return tool name (if set, AI must call this tool to return a value) */
+  expectedReturnTool?: string;
+}
+
+/** Result of the tool execution loop */
+export interface ToolLoopResult {
+  /** Final AI response */
+  response: AIResponse;
+  /** Tool execution rounds */
+  rounds: ToolRoundResult[];
+  /** All values from return tool calls (for multi-field destructuring) */
+  returnFieldResults?: unknown[];
+  /** Whether execution completed via return tool */
+  completedViaReturnTool?: boolean;
+}
+
+/** Result of a tool execution round */
+export interface ToolRoundResult {
+  /** The tool calls that were executed */
+  toolCalls: AIToolCall[];
+  /** The results of each tool call */
+  results: AIToolResult[];
+}
+
+/**
+ * Execute a single round of tool calls.
+ * Takes the tool calls from an AI response and executes them.
+ *
+ * @param toolCalls - Tool calls from the AI response
+ * @param tools - Array of available tools
+ * @param rootDir - Root directory for file operation sandboxing
+ * @param onToolCall - Optional callback for each tool execution
+ * @returns Results of all tool calls
+ */
+export async function executeToolCalls(
+  toolCalls: AIToolCall[],
+  tools: VibeToolValue[],
+  rootDir: string,
+  onToolCall?: (call: AIToolCall, result: unknown, error?: string) => void
+): Promise<AIToolResult[]> {
+  const results: AIToolResult[] = [];
+  const context = { rootDir };
+
+  // Build a lookup map for quick tool access
+  const toolMap = new Map(tools.map(t => [t.name, t]));
+
+  for (const call of toolCalls) {
+    const tool = toolMap.get(call.toolName);
+
+    if (!tool) {
+      const error = `Tool '${call.toolName}' not found`;
+      results.push({ toolCallId: call.id, error, duration: 0 });
+      onToolCall?.(call, undefined, error);
+      continue;
+    }
+
+    const startTime = Date.now();
+    try {
+      const result = await tool.executor(call.args, context);
+      const duration = Date.now() - startTime;
+      results.push({ toolCallId: call.id, result, duration });
+      onToolCall?.(call, result);
+    } catch (err) {
+      const duration = Date.now() - startTime;
+      const error = err instanceof Error ? err.message : String(err);
+      results.push({ toolCallId: call.id, error, duration });
+      onToolCall?.(call, undefined, error);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Execute an AI request with tool calling support.
+ * Continues making follow-up calls until the AI returns a final response.
+ *
+ * @param initialRequest - The initial AI request
+ * @param tools - Array of available tools (from model)
+ * @param rootDir - Root directory for file operation sandboxing
+ * @param executeProvider - Function to execute AI requests
+ * @param options - Tool loop options
+ * @returns Final AI response after all tool calls are complete
+ */
+export async function executeWithTools(
+  initialRequest: AIRequest,
+  tools: VibeToolValue[],
+  rootDir: string,
+  executeProvider: (request: AIRequest) => Promise<AIResponse>,
+  options: ToolLoopOptions = {}
+): Promise<ToolLoopResult> {
+  const { maxRounds = 10, onToolCall, expectedReturnTool } = options;
+  const rounds: ToolRoundResult[] = [];
+
+  let request = initialRequest;
+  let response = await executeProvider(request);
+  let roundCount = 0;
+  let returnFieldResults: unknown[] = [];
+  let completedViaReturnTool = false;
+
+  // Continue while there are tool calls to execute (or we need to retry for missing return tool)
+  while (roundCount < maxRounds) {
+    // Case 1: AI called tools
+    if (response.toolCalls?.length) {
+      roundCount++;
+
+      // Execute all tool calls in this round
+      const results = await executeToolCalls(response.toolCalls, tools, rootDir, onToolCall);
+
+      // Record this round
+      rounds.push({
+        toolCalls: response.toolCalls,
+        results,
+      });
+
+      // Collect all return tool results from this round
+      for (const call of response.toolCalls) {
+        if (isReturnToolCall(call.toolName)) {
+          const result = results.find((r) => r.toolCallId === call.id);
+          if (result && result.error === undefined) {
+            // Return tool succeeded - collect result
+            returnFieldResults.push(result.result);
+            completedViaReturnTool = true;
+          }
+          // If return tool errored, error flows back to AI for retry
+        }
+      }
+
+      // If we got return tool results, we're done (AI returns all fields in one round)
+      if (completedViaReturnTool) {
+        break;
+      }
+
+      // Make follow-up request with tool results
+      request = {
+        ...request,
+        previousToolCalls: response.toolCalls,
+        toolResults: results,
+      };
+      response = await executeProvider(request);
+    }
+    // Case 2: AI didn't call any tools but we expected a return tool
+    else if (expectedReturnTool && !completedViaReturnTool) {
+      roundCount++;
+
+      // Synthesize error to send back to AI
+      const errorResult: AIToolResult = {
+        toolCallId: 'missing-return-tool',
+        error: `You must call the ${expectedReturnTool} tool to return your answer. Do not respond with plain text.`,
+        duration: 0,
+      };
+      rounds.push({ toolCalls: [], results: [errorResult] });
+
+      // Make follow-up request with error
+      request = {
+        ...request,
+        previousToolCalls: [],
+        toolResults: [errorResult],
+      };
+      response = await executeProvider(request);
+    }
+    // Case 3: No tool calls and no expected return tool - we're done
+    else {
+      break;
+    }
+  }
+
+  // Warn if we hit max rounds
+  if (roundCount >= maxRounds && !completedViaReturnTool && expectedReturnTool) {
+    console.warn(
+      `Tool loop hit max rounds (${maxRounds}) without receiving expected return tool call`
+    );
+  } else if (roundCount >= maxRounds && response.toolCalls?.length) {
+    console.warn(`Tool loop hit max rounds (${maxRounds}), stopping with pending tool calls`);
+  }
+
+  return {
+    response,
+    rounds,
+    returnFieldResults: returnFieldResults.length > 0 ? returnFieldResults : undefined,
+    completedViaReturnTool,
+  };
+}
+
+/**
+ * Check if an AI response requires tool execution.
+ */
+export function requiresToolExecution(response: AIResponse): boolean {
+  return (response.toolCalls?.length ?? 0) > 0;
+}

package/src/runtime/ai/tool-schema.ts

@@ -0,0 +1,151 @@
+// Tool Schema Converters for AI Providers
+// Converts internal ToolSchema to provider-specific formats
+
+import type { ToolSchema, ToolParameterSchema, JsonSchema } from '../tools/types';
+
+// ============================================================================
+// Provider-specific tool types
+// ============================================================================
+
+/** OpenAI tool format */
+export interface OpenAITool {
+  type: 'function';
+  function: {
+    name: string;
+    description?: string;
+    parameters: {
+      type: 'object';
+      properties: Record<string, JsonSchema>;
+      required?: string[];
+    };
+  };
+}
+
+/** Anthropic tool format */
+export interface AnthropicTool {
+  name: string;
+  description?: string;
+  input_schema: {
+    type: 'object';
+    properties: Record<string, JsonSchema>;
+    required?: string[];
+  };
+}
+
+/** Google function declaration format */
+export interface GoogleFunctionDeclaration {
+  name: string;
+  description?: string;
+  parameters: {
+    type: 'object';
+    properties: Record<string, JsonSchema>;
+    required?: string[];
+  };
+}
+
+// ============================================================================
+// Conversion helpers
+// ============================================================================
+
+/**
+ * Convert tool parameters to JSON Schema properties object.
+ */
+function parametersToProperties(
+  params: ToolParameterSchema[]
+): { properties: Record<string, JsonSchema>; required: string[] } {
+  const properties: Record<string, JsonSchema> = {};
+  const required: string[] = [];
+
+  for (const param of params) {
+    const schema: JsonSchema = { ...param.type };
+    if (param.description) {
+      schema.description = param.description;
+    }
+    properties[param.name] = schema;
+
+    if (param.required) {
+      required.push(param.name);
+    }
+  }
+
+  return { properties, required };
+}
+
+// ============================================================================
+// Provider converters
+// ============================================================================
+
+/**
+ * Convert internal ToolSchema to OpenAI tool format.
+ */
+export function toOpenAITool(schema: ToolSchema): OpenAITool {
+  const { properties, required } = parametersToProperties(schema.parameters);
+
+  return {
+    type: 'function',
+    function: {
+      name: schema.name,
+      description: schema.description,
+      parameters: {
+        type: 'object',
+        properties,
+        required: required.length > 0 ? required : undefined,
+      },
+    },
+  };
+}
+
+/**
+ * Convert array of ToolSchema to OpenAI tools array.
+ */
+export function toOpenAITools(schemas: ToolSchema[]): OpenAITool[] {
+  return schemas.map(toOpenAITool);
+}
+
+/**
+ * Convert internal ToolSchema to Anthropic tool format.
+ */
+export function toAnthropicTool(schema: ToolSchema): AnthropicTool {
+  const { properties, required } = parametersToProperties(schema.parameters);
+
+  return {
+    name: schema.name,
+    description: schema.description,
+    input_schema: {
+      type: 'object',
+      properties,
+      required: required.length > 0 ? required : undefined,
+    },
+  };
+}
+
+/**
+ * Convert array of ToolSchema to Anthropic tools array.
+ */
+export function toAnthropicTools(schemas: ToolSchema[]): AnthropicTool[] {
+  return schemas.map(toAnthropicTool);
+}
+
+/**
+ * Convert internal ToolSchema to Google function declaration format.
+ */
+export function toGoogleFunctionDeclaration(schema: ToolSchema): GoogleFunctionDeclaration {
+  const { properties, required } = parametersToProperties(schema.parameters);
+
+  return {
+    name: schema.name,
+    description: schema.description,
+    parameters: {
+      type: 'object',
+      properties,
+      required: required.length > 0 ? required : undefined,
+    },
+  };
+}
+
+/**
+ * Convert array of ToolSchema to Google function declarations.
+ */
+export function toGoogleFunctionDeclarations(schemas: ToolSchema[]): GoogleFunctionDeclaration[] {
+  return schemas.map(toGoogleFunctionDeclaration);
+}

package/src/runtime/ai/types.ts

@@ -0,0 +1,113 @@
+// AI Module Type Definitions
+
+import type { AIProviderType } from '../../ast';
+import type { ToolSchema } from '../tools/types';
+
+// Re-export for convenience
+export type { AIProviderType };
+
+/** Target types for AI responses */
+export type TargetType = 'text' | 'json' | 'boolean' | 'number' | 'text[]' | 'json[]' | 'boolean[]' | 'number[]' | null;
+
+/** Thinking level for extended reasoning */
+export type ThinkingLevel = 'none' | 'low' | 'medium' | 'high' | 'max';
+
+/** Model configuration from Vibe model declaration */
+export interface ModelConfig {
+  name: string;
+  apiKey: string;
+  url: string | null;
+  provider?: AIProviderType;
+  maxRetriesOnError?: number;
+  thinkingLevel?: ThinkingLevel;
+}
+
+/** AI request for all providers */
+export interface AIRequest {
+  operationType: 'do' | 'vibe';
+  prompt: string;
+  contextText: string;
+  targetType: TargetType;
+  model: ModelConfig;
+  /** Available tools for function calling */
+  tools?: ToolSchema[];
+  /** Previous tool calls from AI response (for multi-turn) */
+  previousToolCalls?: AIToolCall[];
+  /** Tool results from previous call (for multi-turn) */
+  toolResults?: AIToolResult[];
+  /** Override messages (used by vibe for custom system prompt) */
+  messages?: Array<{ role: 'system' | 'user' | 'assistant'; content: string }>;
+}
+
+/** Detailed token usage from AI providers */
+export interface TokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+  // Cached tokens (prompt caching)
+  cachedInputTokens?: number;
+  // Tokens used to create cache (Anthropic)
+  cacheCreationTokens?: number;
+  // Reasoning/thinking tokens (OpenAI o1, Claude extended thinking)
+  thinkingTokens?: number;
+}
+
+/** Tool call parsed from AI response */
+export interface AIToolCall {
+  /** Provider-assigned ID for the tool call */
+  id: string;
+  /** Name of the tool to call */
+  toolName: string;
+  /** Arguments parsed from the tool call */
+  args: Record<string, unknown>;
+  /** Thought signature for Gemini 3 models (must be echoed back in follow-up) */
+  thoughtSignature?: string;
+}
+
+/** Tool result to send back in follow-up request */
+export interface AIToolResult {
+  /** ID of the tool call this result is for */
+  toolCallId: string;
+  /** Successful result value */
+  result?: unknown;
+  /** Error message if the tool call failed */
+  error?: string;
+  /** Execution duration in milliseconds */
+  duration?: number;
+}
+
+/** Why the model stopped generating */
+export type AIStopReason = 'end' | 'tool_use' | 'length' | 'content_filter';
+
+/** AI response from all providers */
+export interface AIResponse {
+  content: string;
+  parsedValue: unknown;
+  usage?: TokenUsage;
+  /** Tool calls from the model (if any) */
+  toolCalls?: AIToolCall[];
+  /** Why the model stopped generating */
+  stopReason?: AIStopReason;
+}
+
+/** Custom error for AI operations */
+export class AIError extends Error {
+  readonly statusCode?: number;
+  readonly isRetryable: boolean;
+
+  constructor(message: string, statusCode?: number, isRetryable = false) {
+    super(message);
+    this.name = 'AIError';
+    this.statusCode = statusCode;
+    this.isRetryable = isRetryable;
+  }
+}
+
+/** Provider executor function signature */
+export type ProviderExecutor = (request: AIRequest) => Promise<AIResponse>;
+
+/** Retry options */
+export interface RetryOptions {
+  maxRetries: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+}