@providerprotocol/ai 0.0.12 → 0.0.14

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   createProvider
-} from "./chunk-Y6Q7JCNP.js";
+} from "./chunk-MSR5P65T.js";
 import {
   AssistantMessage,
   Message,
@@ -10,21 +10,21 @@ import {
   isAssistantMessage,
   isToolResultMessage,
   isUserMessage
-} from "./chunk-W4BB4BG2.js";
+} from "./chunk-SVYROCLD.js";
 import {
   ExponentialBackoff,
   LinearBackoff,
   NoRetry,
   RetryAfterStrategy,
   TokenBucket
-} from "./chunk-CUCRF5W6.js";
-import "./chunk-X5G4EHL7.js";
+} from "./chunk-U4JJC2YX.js";
+import "./chunk-Z7RBRCRN.js";
 import {
   DynamicKey,
   RoundRobinKeys,
   UPPError,
   WeightedKeys
-} from "./chunk-SUNYWHTH.js";
+} from "./chunk-MOU4U3PO.js";
 
 // src/types/turn.ts
 function createTurn(messages, toolExecutions, usage, cycles, data) {
@@ -46,6 +46,8 @@ function emptyUsage() {
     inputTokens: 0,
     outputTokens: 0,
     totalTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
     cycles: []
   };
 }
@@ -53,18 +55,26 @@ function aggregateUsage(usages) {
   const cycles = [];
   let inputTokens = 0;
   let outputTokens = 0;
+  let cacheReadTokens = 0;
+  let cacheWriteTokens = 0;
   for (const usage of usages) {
     inputTokens += usage.inputTokens;
     outputTokens += usage.outputTokens;
+    cacheReadTokens += usage.cacheReadTokens;
+    cacheWriteTokens += usage.cacheWriteTokens;
     cycles.push({
       inputTokens: usage.inputTokens,
-      outputTokens: usage.outputTokens
+      outputTokens: usage.outputTokens,
+      cacheReadTokens: usage.cacheReadTokens,
+      cacheWriteTokens: usage.cacheWriteTokens
     });
   }
   return {
     inputTokens,
     outputTokens,
     totalTokens: inputTokens + outputTokens,
+    cacheReadTokens,
+    cacheWriteTokens,
     cycles
   };
 }
@@ -313,7 +323,6 @@ async function executeGenerate(model, config, system, params, tools, toolStrateg
   const data = structure ? structuredData : void 0;
   return createTurn(
     allMessages.slice(history.length),
-    // Only messages from this turn
     toolExecutions,
     aggregateUsage(usages),
     cycles,
@@ -430,10 +439,25 @@ async function executeTools(message, tools, toolStrategy, executions, onEvent) {
     }
     const startTime = Date.now();
     onEvent?.(toolExecutionStart(call.toolCallId, tool.name, startTime, index));
-    await toolStrategy?.onToolCall?.(tool, call.arguments);
+    let effectiveParams = call.arguments;
+    await toolStrategy?.onToolCall?.(tool, effectiveParams);
     if (toolStrategy?.onBeforeCall) {
-      const shouldRun = await toolStrategy.onBeforeCall(tool, call.arguments);
-      if (!shouldRun) {
+      const beforeResult = await toolStrategy.onBeforeCall(tool, effectiveParams);
+      const isBeforeCallResult = (value) => typeof value === "object" && value !== null && "proceed" in value;
+      if (isBeforeCallResult(beforeResult)) {
+        if (!beforeResult.proceed) {
+          const endTime = Date.now();
+          onEvent?.(toolExecutionEnd(call.toolCallId, tool.name, "Tool execution skipped", true, endTime, index));
+          return {
+            toolCallId: call.toolCallId,
+            result: "Tool execution skipped",
+            isError: true
+          };
+        }
+        if (beforeResult.params !== void 0) {
+          effectiveParams = beforeResult.params;
+        }
+      } else if (!beforeResult) {
         const endTime = Date.now();
         onEvent?.(toolExecutionEnd(call.toolCallId, tool.name, "Tool execution skipped", true, endTime, index));
         return {
@@ -446,7 +470,7 @@ async function executeTools(message, tools, toolStrategy, executions, onEvent) {
     let approved = true;
     if (tool.approval) {
       try {
-        approved = await tool.approval(call.arguments);
+        approved = await tool.approval(effectiveParams);
       } catch (error) {
         throw error;
       }
@@ -456,7 +480,7 @@ async function executeTools(message, tools, toolStrategy, executions, onEvent) {
       const execution = {
         toolName: tool.name,
         toolCallId: call.toolCallId,
-        arguments: call.arguments,
+        arguments: effectiveParams,
         result: "Tool execution denied",
         isError: true,
         duration: endTime - startTime,
@@ -471,13 +495,19 @@ async function executeTools(message, tools, toolStrategy, executions, onEvent) {
       };
     }
     try {
-      const result = await tool.run(call.arguments);
+      let result = await tool.run(effectiveParams);
       const endTime = Date.now();
-      await toolStrategy?.onAfterCall?.(tool, call.arguments, result);
+      if (toolStrategy?.onAfterCall) {
+        const afterResult = await toolStrategy.onAfterCall(tool, effectiveParams, result);
+        const isAfterCallResult = (value) => typeof value === "object" && value !== null && "result" in value;
+        if (isAfterCallResult(afterResult)) {
+          result = afterResult.result;
+        }
+      }
       const execution = {
         toolName: tool.name,
         toolCallId: call.toolCallId,
-        arguments: call.arguments,
+        arguments: effectiveParams,
         result,
         isError: false,
         duration: endTime - startTime,
@@ -492,12 +522,12 @@ async function executeTools(message, tools, toolStrategy, executions, onEvent) {
       };
     } catch (error) {
       const endTime = Date.now();
-      await toolStrategy?.onError?.(tool, call.arguments, error);
+      await toolStrategy?.onError?.(tool, effectiveParams, error);
       const errorMessage = error instanceof Error ? error.message : String(error);
       const execution = {
         toolName: tool.name,
         toolCallId: call.toolCallId,
-        arguments: call.arguments,
+        arguments: effectiveParams,
         result: errorMessage,
         isError: true,
         duration: endTime - startTime,
@@ -550,9 +580,13 @@ function validateMediaCapabilities(messages, capabilities, providerName) {
 // src/core/image.ts
 import { readFile } from "fs/promises";
 var Image = class _Image {
+  /** The underlying image source (bytes, base64, or URL) */
   source;
+  /** MIME type of the image (e.g., 'image/jpeg', 'image/png') */
   mimeType;
+  /** Image width in pixels, if known */
   width;
+  /** Image height in pixels, if known */
   height;
   constructor(source, mimeType, width, height) {
     this.source = source;
@@ -561,13 +595,19 @@ var Image = class _Image {
     this.height = height;
   }
   /**
-   * Check if this image has data loaded (false for URL sources)
+   * Whether this image has data loaded in memory.
+   *
+   * Returns `false` for URL-sourced images that reference external resources.
+   * These must be fetched before their data can be accessed.
    */
   get hasData() {
     return this.source.type !== "url";
   }
   /**
-   * Convert to base64 string (throws if source is URL)
+   * Converts the image to a base64-encoded string.
+   *
+   * @returns The image data as a base64 string
+   * @throws {Error} When the source is a URL (data must be fetched first)
    */
   toBase64() {
     if (this.source.type === "base64") {
@@ -581,14 +621,20 @@ var Image = class _Image {
     throw new Error("Cannot convert URL image to base64. Fetch the image first.");
   }
   /**
-   * Convert to data URL (throws if source is URL)
+   * Converts the image to a data URL suitable for embedding in HTML or CSS.
+   *
+   * @returns A data URL in the format `data:{mimeType};base64,{data}`
+   * @throws {Error} When the source is a URL (data must be fetched first)
    */
   toDataUrl() {
     const base64 = this.toBase64();
     return `data:${this.mimeType};base64,${base64}`;
   }
   /**
-   * Get raw bytes (throws if source is URL)
+   * Gets the image data as raw bytes.
+   *
+   * @returns The image data as a Uint8Array
+   * @throws {Error} When the source is a URL (data must be fetched first)
    */
   toBytes() {
     if (this.source.type === "bytes") {
@@ -605,7 +651,10 @@ var Image = class _Image {
     throw new Error("Cannot get bytes from URL image. Fetch the image first.");
   }
   /**
-   * Get the URL (only for URL sources)
+   * Gets the URL for URL-sourced images.
+   *
+   * @returns The image URL
+   * @throws {Error} When the source is not a URL
    */
   toUrl() {
     if (this.source.type === "url") {
@@ -614,7 +663,9 @@ var Image = class _Image {
     throw new Error("This image does not have a URL source.");
   }
   /**
-   * Convert to ImageBlock for use in messages
+   * Converts this Image to an ImageBlock for use in UPP messages.
+   *
+   * @returns An ImageBlock that can be included in message content arrays
    */
   toBlock() {
     return {
@@ -626,7 +677,18 @@ var Image = class _Image {
     };
   }
   /**
-   * Create from file path (reads file into memory)
+   * Creates an Image by reading a file from disk.
+   *
+   * The file is read into memory as bytes. MIME type is automatically
+   * detected from the file extension.
+   *
+   * @param path - Path to the image file
+   * @returns Promise resolving to an Image with the file contents
+   *
+   * @example
+   * ```typescript
+   * const image = await Image.fromPath('./photos/vacation.jpg');
+   * ```
    */
   static async fromPath(path) {
     const data = await readFile(path);
@@ -637,26 +699,63 @@ var Image = class _Image {
     );
   }
   /**
-   * Create from URL reference (does not fetch - providers handle URL conversion)
+   * Creates an Image from a URL reference.
+   *
+   * The URL is stored as a reference and not fetched. Providers will handle
+   * URL-to-data conversion if needed. MIME type is detected from the URL
+   * path if not provided.
+   *
+   * @param url - URL pointing to the image
+   * @param mimeType - Optional MIME type override
+   * @returns An Image referencing the URL
+   *
+   * @example
+   * ```typescript
+   * const image = Image.fromUrl('https://example.com/logo.png');
+   * ```
    */
   static fromUrl(url, mimeType) {
     const detected = mimeType || detectMimeTypeFromUrl(url);
     return new _Image({ type: "url", url }, detected);
   }
   /**
-   * Create from raw bytes
+   * Creates an Image from raw byte data.
+   *
+   * @param data - The image data as a Uint8Array
+   * @param mimeType - The MIME type of the image
+   * @returns An Image containing the byte data
+   *
+   * @example
+   * ```typescript
+   * const image = Image.fromBytes(pngData, 'image/png');
+   * ```
    */
   static fromBytes(data, mimeType) {
     return new _Image({ type: "bytes", data }, mimeType);
   }
   /**
-   * Create from base64 string
+   * Creates an Image from a base64-encoded string.
+   *
+   * @param base64 - The base64-encoded image data (without data URL prefix)
+   * @param mimeType - The MIME type of the image
+   * @returns An Image containing the base64 data
+   *
+   * @example
+   * ```typescript
+   * const image = Image.fromBase64(base64String, 'image/jpeg');
+   * ```
    */
   static fromBase64(base64, mimeType) {
     return new _Image({ type: "base64", data: base64 }, mimeType);
   }
   /**
-   * Create from an existing ImageBlock
+   * Creates an Image from an existing ImageBlock.
+   *
+   * Useful for converting content blocks received from providers back
+   * into Image instances for further processing.
+   *
+   * @param block - An ImageBlock from message content
+   * @returns An Image with the block's source and metadata
    */
   static fromBlock(block) {
     return new _Image(
@@ -729,7 +828,9 @@ var Thread = class _Thread {
   /** Last update timestamp */
   _updatedAt;
   /**
-   * Create a new thread, optionally with initial messages
+   * Creates a new thread instance.
+   *
+   * @param messages - Optional initial messages to populate the thread
    */
   constructor(messages) {
     this.id = generateId();
@@ -737,16 +838,23 @@ var Thread = class _Thread {
     this._createdAt = /* @__PURE__ */ new Date();
     this._updatedAt = /* @__PURE__ */ new Date();
   }
-  /** All messages in the thread (readonly) */
+  /**
+   * All messages in the thread (readonly).
+   */
   get messages() {
     return this._messages;
   }
-  /** Number of messages */
+  /**
+   * Number of messages in the thread.
+   */
   get length() {
     return this._messages.length;
   }
   /**
-   * Append messages from a turn
+   * Appends all messages from a Turn to the thread.
+   *
+   * @param turn - The Turn containing messages to append
+   * @returns This thread instance for chaining
    */
   append(turn) {
     this._messages.push(...turn.messages);
@@ -754,7 +862,10 @@ var Thread = class _Thread {
     return this;
   }
   /**
-   * Add raw messages
+   * Adds raw messages to the thread.
+   *
+   * @param messages - Messages to add
+   * @returns This thread instance for chaining
    */
   push(...messages) {
     this._messages.push(...messages);
@@ -762,7 +873,19 @@ var Thread = class _Thread {
     return this;
   }
   /**
-   * Add a user message
+   * Adds a user message to the thread.
+   *
+   * @param content - String or array of content blocks
+   * @returns This thread instance for chaining
+   *
+   * @example
+   * ```typescript
+   * thread.user('Hello, world!');
+   * thread.user([
+   *   { type: 'text', text: 'Describe this image:' },
+   *   { type: 'image', source: { type: 'url', url: '...' }, mimeType: 'image/png' }
+   * ]);
+   * ```
    */
   user(content) {
     this._messages.push(new UserMessage(content));
@@ -770,7 +893,15 @@ var Thread = class _Thread {
     return this;
   }
   /**
-   * Add an assistant message
+   * Adds an assistant message to the thread.
+   *
+   * @param content - String or array of content blocks
+   * @returns This thread instance for chaining
+   *
+   * @example
+   * ```typescript
+   * thread.assistant('I can help with that!');
+   * ```
    */
   assistant(content) {
     this._messages.push(new AssistantMessage(content));
@@ -778,25 +909,53 @@ var Thread = class _Thread {
     return this;
   }
   /**
-   * Get messages by type
+   * Filters messages by type.
+   *
+   * @param type - The message type to filter by
+   * @returns Array of messages matching the type
+   *
+   * @example
+   * ```typescript
+   * const userMessages = thread.filter('user');
+   * const assistantMessages = thread.filter('assistant');
+   * ```
    */
   filter(type) {
     return this._messages.filter((m) => m.type === type);
   }
   /**
-   * Get the last N messages
+   * Returns the last N messages from the thread.
+   *
+   * @param count - Number of messages to return
+   * @returns Array of the last N messages
+   *
+   * @example
+   * ```typescript
+   * const recent = thread.tail(5);
+   * ```
    */
   tail(count) {
     return this._messages.slice(-count);
   }
   /**
-   * Create a new thread with a subset of messages
+   * Creates a new thread with a subset of messages.
+   *
+   * @param start - Start index (inclusive)
+   * @param end - End index (exclusive)
+   * @returns New Thread containing the sliced messages
+   *
+   * @example
+   * ```typescript
+   * const subset = thread.slice(0, 10);
+   * ```
    */
   slice(start, end) {
     return new _Thread(this._messages.slice(start, end));
   }
   /**
-   * Clear all messages
+   * Removes all messages from the thread.
+   *
+   * @returns This thread instance for chaining
    */
   clear() {
     this._messages = [];
@@ -804,13 +963,23 @@ var Thread = class _Thread {
     return this;
   }
   /**
-   * Convert to plain message array
+   * Converts the thread to a plain message array.
+   *
+   * @returns Copy of the internal message array
    */
   toMessages() {
     return [...this._messages];
   }
   /**
-   * Serialize to JSON
+   * Serializes the thread to JSON format.
+   *
+   * @returns JSON-serializable representation of the thread
+   *
+   * @example
+   * ```typescript
+   * const json = thread.toJSON();
+   * localStorage.setItem('thread', JSON.stringify(json));
+   * ```
    */
   toJSON() {
     return {
@@ -821,7 +990,16 @@ var Thread = class _Thread {
     };
   }
   /**
-   * Deserialize from JSON
+   * Deserializes a thread from JSON format.
+   *
+   * @param json - The JSON representation to deserialize
+   * @returns Reconstructed Thread instance
+   *
+   * @example
+   * ```typescript
+   * const json = JSON.parse(localStorage.getItem('thread'));
+   * const thread = Thread.fromJSON(json);
+   * ```
    */
   static fromJSON(json) {
     const messages = json.messages.map((m) => _Thread.messageFromJSON(m));
@@ -832,13 +1010,22 @@ var Thread = class _Thread {
     return thread;
   }
   /**
-   * Iterate over messages
+   * Enables iteration over messages with for...of loops.
+   *
+   * @returns Iterator over the thread's messages
+   *
+   * @example
+   * ```typescript
+   * for (const message of thread) {
+   *   console.log(message.text);
+   * }
+   * ```
    */
   [Symbol.iterator]() {
     return this._messages[Symbol.iterator]();
   }
   /**
-   * Convert a message to JSON
+   * Converts a message to JSON format.
    */
   messageToJSON(m) {
     const base = {
@@ -859,7 +1046,7 @@ var Thread = class _Thread {
     return base;
   }
   /**
-   * Reconstruct a message from JSON
+   * Reconstructs a message from JSON format.
    */
   static messageFromJSON(json) {
     const options = {
@@ -885,9 +1072,8 @@ var Thread = class _Thread {
 
 // src/index.ts
 var ai = {
+  /** LLM instance factory */
   llm
-  // embedding, // Coming soon
-  // image,     // Coming soon
 };
 export {
   AssistantMessage,