@providerprotocol/ai 0.0.9 → 0.0.11

package/src/core/llm.ts

@@ -23,7 +23,11 @@ import {
   isAssistantMessage,
 } from '../types/messages.ts';
 import { createTurn, aggregateUsage, emptyUsage } from '../types/turn.ts';
-import { createStreamResult } from '../types/stream.ts';
+import {
+  createStreamResult,
+  toolExecutionStart,
+  toolExecutionEnd,
+} from '../types/stream.ts';
 import { generateShortId } from '../utils/id.ts';
 
 /**
@@ -413,14 +417,21 @@ function executeStream<TParams>(
             );
           }
 
-          // Execute tools
+          // Execute tools with event emission
+          const toolEvents: StreamEvent[] = [];
           const results = await executeTools(
             response.message,
             tools,
             toolStrategy,
-            toolExecutions
+            toolExecutions,
+            (event) => toolEvents.push(event)
           );
 
+          // Yield tool execution events
+          for (const event of toolEvents) {
+            yield event;
+          }
+
           // Add tool results
           allMessages.push(new ToolResultMessage(results));
 
@@ -467,7 +478,8 @@ async function executeTools(
   message: AssistantMessage,
   tools: Tool[],
   toolStrategy: LLMOptions<unknown>['toolStrategy'],
-  executions: ToolExecution[]
+  executions: ToolExecution[],
+  onEvent?: (event: StreamEvent) => void
 ): Promise<ToolResult[]> {
   const toolCalls = message.toolCalls ?? [];
   const results: ToolResult[] = [];
@@ -476,7 +488,7 @@ async function executeTools(
   const toolMap = new Map(tools.map((t) => [t.name, t]));
 
   // Execute tools (in parallel)
-  const promises = toolCalls.map(async (call) => {
+  const promises = toolCalls.map(async (call, index) => {
     const tool = toolMap.get(call.toolName);
     if (!tool) {
       return {
@@ -488,6 +500,9 @@ async function executeTools(
 
     const startTime = Date.now();
 
+    // Emit start event
+    onEvent?.(toolExecutionStart(call.toolCallId, tool.name, startTime, index));
+
     // Notify strategy
     await toolStrategy?.onToolCall?.(tool, call.arguments);
 
@@ -495,6 +510,8 @@ async function executeTools(
     if (toolStrategy?.onBeforeCall) {
       const shouldRun = await toolStrategy.onBeforeCall(tool, call.arguments);
       if (!shouldRun) {
+        const endTime = Date.now();
+        onEvent?.(toolExecutionEnd(call.toolCallId, tool.name, 'Tool execution skipped', true, endTime, index));
         return {
           toolCallId: call.toolCallId,
           result: 'Tool execution skipped',
@@ -515,17 +532,20 @@ async function executeTools(
     }
 
     if (!approved) {
+      const endTime = Date.now();
       const execution: ToolExecution = {
         toolName: tool.name,
         toolCallId: call.toolCallId,
         arguments: call.arguments,
         result: 'Tool execution denied',
         isError: true,
-        duration: Date.now() - startTime,
+        duration: endTime - startTime,
         approved: false,
       };
       executions.push(execution);
 
+      onEvent?.(toolExecutionEnd(call.toolCallId, tool.name, 'Tool execution denied by approval handler', true, endTime, index));
+
       return {
         toolCallId: call.toolCallId,
         result: 'Tool execution denied by approval handler',
@@ -536,6 +556,7 @@ async function executeTools(
     // Execute tool
     try {
       const result = await tool.run(call.arguments);
+      const endTime = Date.now();
 
       await toolStrategy?.onAfterCall?.(tool, call.arguments, result);
 
@@ -545,17 +566,20 @@ async function executeTools(
         arguments: call.arguments,
         result,
         isError: false,
-        duration: Date.now() - startTime,
+        duration: endTime - startTime,
         approved,
       };
       executions.push(execution);
 
+      onEvent?.(toolExecutionEnd(call.toolCallId, tool.name, result, false, endTime, index));
+
       return {
         toolCallId: call.toolCallId,
         result,
         isError: false,
       };
     } catch (error) {
+      const endTime = Date.now();
       await toolStrategy?.onError?.(tool, call.arguments, error as Error);
 
       const errorMessage = error instanceof Error ? error.message : String(error);
@@ -566,11 +590,13 @@ async function executeTools(
         arguments: call.arguments,
         result: errorMessage,
         isError: true,
-        duration: Date.now() - startTime,
+        duration: endTime - startTime,
         approved,
       };
       executions.push(execution);
 
+      onEvent?.(toolExecutionEnd(call.toolCallId, tool.name, errorMessage, true, endTime, index));
+
       return {
         toolCallId: call.toolCallId,
         result: errorMessage,

package/src/openai/index.ts

@@ -20,6 +20,7 @@ export type {
   OpenAIAudioConfig,
   OpenAIWebSearchOptions,
   OpenAIWebSearchUserLocation,
+  OpenAICompletionsWebSearchUserLocation,
   // Built-in tool types
   OpenAIBuiltInTool,
   OpenAIWebSearchTool,

package/src/providers/openai/index.ts

@@ -156,6 +156,7 @@ export type {
   OpenAIAudioConfig,
   OpenAIWebSearchOptions,
   OpenAIWebSearchUserLocation,
+  OpenAICompletionsWebSearchUserLocation,
   // Built-in tool types
   OpenAIBuiltInTool,
   OpenAIWebSearchTool,

package/src/providers/openai/types.ts

@@ -27,8 +27,8 @@ export interface OpenAIAudioConfig {
 // ============================================
 
 /**
- * User location for web search context
- * Requires type: 'approximate' with location fields at the same level
+ * User location for web search context (Responses API format)
+ * Fields are at the same level as type
  */
 export interface OpenAIWebSearchUserLocation {
   /** Location type - must be 'approximate' */
@@ -43,8 +43,29 @@ export interface OpenAIWebSearchUserLocation {
   timezone?: string;
 }
 
+/**
+ * User location for web search context (Chat Completions API format)
+ * Fields are nested under 'approximate' object
+ */
+export interface OpenAICompletionsWebSearchUserLocation {
+  /** Location type - must be 'approximate' */
+  type: 'approximate';
+  /** Approximate location details */
+  approximate: {
+    /** City name */
+    city?: string;
+    /** ISO 3166-1 country code (e.g., "US") */
+    country?: string;
+    /** Region/state name */
+    region?: string;
+    /** IANA timezone (e.g., "America/New_York") */
+    timezone?: string;
+  };
+}
+
 /**
  * Web search options for Chat Completions API
+ * Use with gpt-5-search-api-* models
  */
 export interface OpenAIWebSearchOptions {
   /**
@@ -53,7 +74,7 @@ export interface OpenAIWebSearchOptions {
    */
   search_context_size?: 'low' | 'medium' | 'high';
   /** User location for localizing search results */
-  user_location?: OpenAIWebSearchUserLocation | null;
+  user_location?: OpenAICompletionsWebSearchUserLocation | null;
 }
 
 /**

package/src/types/stream.ts

@@ -10,6 +10,8 @@ export type StreamEventType =
   | 'audio_delta'
   | 'video_delta'
   | 'tool_call_delta'
+  | 'tool_execution_start'
+  | 'tool_execution_end'
   | 'message_start'
   | 'message_stop'
   | 'content_block_start'
@@ -24,6 +26,12 @@ export interface EventDelta {
   toolCallId?: string;
   toolName?: string;
   argumentsJson?: string;
+  /** Tool execution result (for tool_execution_end) */
+  result?: unknown;
+  /** Whether tool execution errored (for tool_execution_end) */
+  isError?: boolean;
+  /** Timestamp in ms (for tool_execution_start/end) */
+  timestamp?: number;
 }
 
 /**
@@ -144,3 +152,37 @@ export function contentBlockStop(index: number): StreamEvent {
     delta: {},
   };
 }
+
+/**
+ * Create a tool execution start event
+ */
+export function toolExecutionStart(
+  toolCallId: string,
+  toolName: string,
+  timestamp: number,
+  index = 0
+): StreamEvent {
+  return {
+    type: 'tool_execution_start',
+    index,
+    delta: { toolCallId, toolName, timestamp },
+  };
+}
+
+/**
+ * Create a tool execution end event
+ */
+export function toolExecutionEnd(
+  toolCallId: string,
+  toolName: string,
+  result: unknown,
+  isError: boolean,
+  timestamp: number,
+  index = 0
+): StreamEvent {
+  return {
+    type: 'tool_execution_end',
+    index,
+    delta: { toolCallId, toolName, result, isError, timestamp },
+  };
+}