react-observer-agent 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,3 +1,5 @@
+'use client';
+
 // src/tools/registerTool.ts
 function registerTool(name, handler, options) {
   return {
@@ -5,6 +7,7 @@ function registerTool(name, handler, options) {
     handler,
     description: options?.description,
     parameters: options?.parameters,
+    schema: options?.schema,
     confirm: options?.confirm ?? false
   };
 }
@@ -28,69 +31,6 @@ function validateToolNames(tools) {
   }
 }
 
-// src/provider/AIAgentProvider.tsx
-import { createContext, useCallback, useEffect, useMemo, useRef, useState } from "react";
-
-// src/state/resolveState.ts
-function resolveState(state) {
-  const resolved = typeof state === "function" ? state() : state;
-  return resolved;
-}
-
-// src/state/createStateSnapshot.ts
-function stripNonSerializable(obj, debug = false) {
-  const result = {};
-  for (const [key, value] of Object.entries(obj)) {
-    try {
-      JSON.stringify(value);
-      result[key] = value;
-    } catch {
-      if (debug) {
-        console.warn(
-          `[react-observer-agent] Non-serializable value stripped from state key "${key}"`
-        );
-      }
-    }
-  }
-  return result;
-}
-function isSerializableValue(value) {
-  if (value === null || value === void 0) return true;
-  if (typeof value === "function" || typeof value === "symbol") return false;
-  if (typeof value === "bigint") return false;
-  return true;
-}
-function createStateSnapshot(state, canAccess, debug = false) {
-  const resolved = resolveState(state);
-  const filtered = {};
-  for (const key of canAccess) {
-    if (key in resolved) {
-      const value = resolved[key];
-      if (!isSerializableValue(value)) {
-        if (debug) {
-          console.warn(
-            `[react-observer-agent] Non-serializable value stripped from state key "${key}"`
-          );
-        }
-        continue;
-      }
-      filtered[key] = value;
-    }
-  }
-  return stripNonSerializable(filtered, debug);
-}
-
-// src/permissions/filterTools.ts
-function filterTools(tools, canExecute) {
-  const allowed = new Set(canExecute);
-  return tools.filter((tool) => allowed.has(tool.name));
-}
-
-// src/permissions/validateToolCall.ts
-function validateToolCall(name, canExecute) {
-  return canExecute.includes(name);
-}
-
 // src/tools/validateArgs.ts
 function validateArgs(args, schema) {
   const errors = [];
@@ -171,14 +111,230 @@ function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+// src/utils/describeError.ts
+function describeError(error, fallback = "Unknown error") {
+  try {
+    return describeUnsafely(error, fallback);
+  } catch {
+    return fallback;
+  }
+}
+function describeUnsafely(error, fallback) {
+  if (error instanceof Error) {
+    return error.message || error.name || fallback;
+  }
+  if (typeof error === "string") {
+    return error || fallback;
+  }
+  if (error === null || error === void 0) {
+    return fallback;
+  }
+  if (typeof error === "object") {
+    const message = error.message;
+    if (typeof message === "string" && message !== "") {
+      return message;
+    }
+    try {
+      const serialized = JSON.stringify(error);
+      if (typeof serialized === "string" && serialized !== "{}") {
+        return serialized;
+      }
+    } catch {
+      return fallback;
+    }
+    return fallback;
+  }
+  return String(error);
+}
+
+// src/tools/validateToolArgs.ts
+async function validateToolArgs(tool, args) {
+  if (tool.schema) {
+    let result;
+    try {
+      result = await tool.schema["~standard"].validate(args);
+    } catch (error) {
+      return { valid: false, errors: [describeError(error)] };
+    }
+    if (result.issues) {
+      return { valid: false, errors: result.issues.map(formatIssue) };
+    }
+    return { valid: true, value: result.value };
+  }
+  if (tool.parameters) {
+    const validation = validateArgs(args, tool.parameters);
+    if (!validation.valid) {
+      return { valid: false, errors: validation.errors };
+    }
+  }
+  return { valid: true, value: args };
+}
+function formatIssue(issue) {
+  const path = (issue.path ?? []).map(
+    (segment) => String(
+      typeof segment === "object" && segment !== null ? segment.key : segment
+    )
+  ).join(".");
+  return path === "" ? issue.message : `${path}: ${issue.message}`;
+}
+
+// src/provider/AIAgentProvider.tsx
+import {
+  createContext,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState
+} from "react";
+
+// src/adapters/AdapterError.ts
+var AdapterError = class extends Error {
+  constructor(message, options) {
+    super(message);
+    // Declared, not just assigned in the constructor, so the emitted typings
+    // publish the literal type the spec promises instead of `string`.
+    this.name = "AdapterError";
+    this.status = options?.status;
+    this.body = options?.body;
+    if (options?.cause !== void 0) {
+      this.cause = options.cause;
+    }
+  }
+};
+
+// src/state/resolveState.ts
+function resolveState(state) {
+  const resolved = typeof state === "function" ? state() : state;
+  return resolved;
+}
+
+// src/state/createStateSnapshot.ts
+function stripNonSerializable(obj, debug = false) {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    try {
+      JSON.stringify(value);
+      result[key] = value;
+    } catch {
+      if (debug) {
+        console.warn(
+          `[react-observer-agent] Non-serializable value stripped from state key "${key}"`
+        );
+      }
+    }
+  }
+  return result;
+}
+function isSerializableValue(value) {
+  if (value === null || value === void 0) return true;
+  if (typeof value === "function" || typeof value === "symbol") return false;
+  if (typeof value === "bigint") return false;
+  return true;
+}
+function applyByteLimit(snapshot, maxBytes, debug) {
+  const limited = {};
+  for (const [key, value] of Object.entries(snapshot)) {
+    const json = JSON.stringify(value);
+    if (json === void 0 || json.length <= maxBytes) {
+      limited[key] = value;
+      continue;
+    }
+    if (debug) {
+      console.warn(
+        `[react-observer-agent] State key "${key}" is ${json.length} bytes, over the ${maxBytes} byte limit, and was truncated`
+      );
+    }
+    limited[key] = {
+      __truncated: true,
+      limit: maxBytes,
+      bytes: json.length,
+      preview: json.slice(0, maxBytes)
+    };
+  }
+  return limited;
+}
+function createStateSnapshot(state, canAccess, debug = false, maxBytes) {
+  const resolved = resolveState(state);
+  const filtered = {};
+  for (const key of canAccess) {
+    if (key in resolved) {
+      const value = resolved[key];
+      if (!isSerializableValue(value)) {
+        if (debug) {
+          console.warn(
+            `[react-observer-agent] Non-serializable value stripped from state key "${key}"`
+          );
+        }
+        continue;
+      }
+      filtered[key] = value;
+    }
+  }
+  const snapshot = stripNonSerializable(filtered, debug);
+  return maxBytes === void 0 ? snapshot : applyByteLimit(snapshot, maxBytes, debug);
+}
+
+// src/permissions/filterTools.ts
+function filterTools(tools, canExecute) {
+  const allowed = new Set(canExecute);
+  return tools.filter((tool) => allowed.has(tool.name));
+}
+
+// src/permissions/validateToolCall.ts
+function validateToolCall(name, canExecute) {
+  return canExecute.includes(name);
+}
+
+// src/utils/abortRace.ts
+var never = () => new Promise(() => {
+});
+function abortRace(signal) {
+  if (!signal) return { promise: never(), release: () => {
+  } };
+  let release = () => {
+  };
+  const promise = new Promise((_resolve, reject) => {
+    const rejectAborted = () => reject(abortReason(signal));
+    if (signal.aborted) {
+      rejectAborted();
+      return;
+    }
+    signal.addEventListener("abort", rejectAborted, { once: true });
+    release = () => signal.removeEventListener("abort", rejectAborted);
+  });
+  return { promise, release };
+}
+function abortReason(signal) {
+  const { reason } = signal;
+  if (reason instanceof Error && reason.name === "AbortError") return reason;
+  const error = new Error("Interaction aborted");
+  error.name = "AbortError";
+  return error;
+}
+
 // src/provider/executeAgentLoop.ts
 var DEFAULT_MAX_TURNS = 5;
+var ABORTED_TOOL_RESULT = "Tool execution cancelled: interaction aborted";
 var READ_STATE_TOOL_NAME = "__readState";
 var EMPTY_OBJECT_SCHEMA = { type: "object", properties: {} };
+var READ_STATE_SCHEMA = {
+  type: "object",
+  properties: {
+    keys: {
+      type: "array",
+      items: { type: "string" },
+      description: "State keys to read"
+    }
+  },
+  required: ["keys"]
+};
 var UsageTotal = class {
   constructor() {
     this.promptTokens = 0;
     this.completionTokens = 0;
+    this.cacheReadTokens = 0;
+    this.cacheWriteTokens = 0;
     this.reported = false;
   }
   add(usage) {
@@ -186,14 +342,20 @@ var UsageTotal = class {
     this.reported = true;
     this.promptTokens += usage.promptTokens ?? 0;
     this.completionTokens += usage.completionTokens ?? 0;
+    this.cacheReadTokens += usage.cacheReadTokens ?? 0;
+    this.cacheWriteTokens += usage.cacheWriteTokens ?? 0;
   }
   /** Undefined when no adapter response carried usage, rather than a false zero. */
   total() {
     if (!this.reported) return void 0;
-    return {
+    const total = {
       promptTokens: this.promptTokens,
       completionTokens: this.completionTokens
     };
+    if (this.cacheReadTokens > 0) total.cacheReadTokens = this.cacheReadTokens;
+    if (this.cacheWriteTokens > 0)
+      total.cacheWriteTokens = this.cacheWriteTokens;
+    return total;
   }
 };
 function isAbortError(error) {
@@ -219,17 +381,7 @@ function buildReadStateToolDef() {
   return {
     name: READ_STATE_TOOL_NAME,
     description: "Read specific keys from the application state. Only request keys you need.",
-    parameters: {
-      type: "object",
-      properties: {
-        keys: {
-          type: "array",
-          items: { type: "string" },
-          description: "State keys to read"
-        }
-      },
-      required: ["keys"]
-    }
+    parameters: READ_STATE_SCHEMA
   };
 }
 async function executeAgentLoop(message, ctx) {
@@ -241,7 +393,10 @@ async function executeAgentLoop(message, ctx) {
     permissions.stateDescriptions
   );
   if (debug) {
-    console.log("[react-observer-agent] State manifest:", stateManifest.map((m) => m.key));
+    console.log(
+      "[react-observer-agent] State manifest:",
+      stateManifest.map((m) => m.key)
+    );
   }
   const allowedTools = filterTools(tools, permissions.canExecute);
   const llmTools = [];
@@ -264,7 +419,10 @@ async function executeAgentLoop(message, ctx) {
     llmTools.push(buildReadStateToolDef());
   }
   if (debug) {
-    console.log("[react-observer-agent] Available tools:", llmTools.map((t) => t.name));
+    console.log(
+      "[react-observer-agent] Available tools:",
+      llmTools.map((t) => t.name)
+    );
   }
   const toolMap = new Map(allowedTools.map((t) => [t.name, t]));
   const messages = [
@@ -277,7 +435,28 @@ async function executeAgentLoop(message, ctx) {
   const usage = new UsageTotal();
   let turns = 0;
   let finalMessage = "";
+  let finalProviderData;
+  let stopError;
   let completed = false;
+  const emit = (event) => {
+    options?.onEvent?.(event);
+  };
+  const record = (result) => {
+    allToolCalls.push(result);
+    options?.onToolCall?.({
+      toolName: result.toolName,
+      args: result.args,
+      result: result.result,
+      status: result.status
+    });
+    emit({
+      type: "tool_end",
+      toolName: result.toolName,
+      args: result.args,
+      result: result.result,
+      status: result.status
+    });
+  };
   const abortedResult = () => ({
     response: {
       message: "",
@@ -287,6 +466,23 @@ async function executeAgentLoop(message, ctx) {
     },
     messages
   });
+  const cancelForAbort = (toolName, args, toolCallId) => {
+    record({
+      toolName,
+      args,
+      result: ABORTED_TOOL_RESULT,
+      status: "cancelled"
+    });
+    messages.push({
+      role: "tool",
+      content: JSON.stringify({
+        status: "cancelled",
+        reason: "Interaction aborted"
+      }),
+      toolCallId
+    });
+    return abortedResult();
+  };
   while (turns < maxTurns) {
     if (signal?.aborted) return abortedResult();
     turns++;
@@ -310,14 +506,21 @@ async function executeAgentLoop(message, ctx) {
         hasSystemPrompt: !!modelRequest.systemPrompt
       });
     }
+    emit({ type: "turn_start", turn: turns, maxTurns });
     let modelResponse;
+    const modelAbort = abortRace(signal);
     try {
-      modelResponse = await model.sendMessage(modelRequest);
+      modelResponse = await Promise.race([
+        model.sendMessage(modelRequest),
+        modelAbort.promise
+      ]);
     } catch (error) {
       if (isAbortError(error) || signal?.aborted) {
         return abortedResult();
       }
       throw error;
+    } finally {
+      modelAbort.release();
     }
     usage.add(modelResponse.usage);
     if (signal?.aborted) return abortedResult();
@@ -329,26 +532,73 @@ async function executeAgentLoop(message, ctx) {
     }
     if (!modelResponse.toolCalls || modelResponse.toolCalls.length === 0) {
       finalMessage = modelResponse.content ?? "";
+      finalProviderData = modelResponse.providerData;
+      if (modelResponse.stopReason === "max_tokens") {
+        stopError = {
+          message: "Model output was cut off by the max tokens limit",
+          code: "TRUNCATED"
+        };
+      } else if (modelResponse.stopReason === "refusal") {
+        stopError = {
+          message: "Model declined to answer",
+          code: "REFUSED"
+        };
+      }
       completed = true;
       break;
     }
     messages.push({
       role: "assistant",
       content: modelResponse.content ?? "",
-      toolCalls: modelResponse.toolCalls
+      toolCalls: modelResponse.toolCalls,
+      providerData: modelResponse.providerData
     });
     for (const llmCall of modelResponse.toolCalls) {
       if (signal?.aborted) return abortedResult();
       if (llmCall.name === READ_STATE_TOOL_NAME) {
+        const readValidation = validateArgs(
+          llmCall.arguments,
+          READ_STATE_SCHEMA
+        );
+        if (!readValidation.valid) {
+          const errorMessage = `Invalid arguments for ${READ_STATE_TOOL_NAME}: ${readValidation.errors.join("; ")}`;
+          if (debug) {
+            console.warn(`[react-observer-agent] ${errorMessage}`);
+          }
+          messages.push({
+            role: "tool",
+            content: JSON.stringify({ error: errorMessage }),
+            toolCallId: llmCall.id,
+            isError: true
+          });
+          continue;
+        }
         const args = llmCall.arguments;
-        const requestedKeys = args?.keys ?? [];
-        const allowedKeys = requestedKeys.filter((k) => permissions.canAccess.includes(k));
-        const snapshot = createStateSnapshot(state, allowedKeys, debug);
+        const requestedKeys = (args?.keys ?? []).filter(
+          (k) => typeof k === "string"
+        );
+        const allowedKeys = requestedKeys.filter(
+          (k) => permissions.canAccess.includes(k)
+        );
+        const snapshot = createStateSnapshot(
+          state,
+          allowedKeys,
+          debug,
+          options?.maxStateBytes
+        );
         if (debug) {
-          console.log("[react-observer-agent] readState requested:", requestedKeys);
+          console.log(
+            "[react-observer-agent] readState requested:",
+            requestedKeys
+          );
           console.log("[react-observer-agent] readState allowed:", allowedKeys);
           console.log("[react-observer-agent] readState result:", snapshot);
         }
+        emit({
+          type: "state_read",
+          requested: requestedKeys,
+          keys: allowedKeys
+        });
         messages.push({
           role: "tool",
           content: JSON.stringify(snapshot),
@@ -356,6 +606,11 @@ async function executeAgentLoop(message, ctx) {
         });
         continue;
       }
+      emit({
+        type: "tool_start",
+        toolName: llmCall.name,
+        args: llmCall.arguments
+      });
       if (!validateToolCall(llmCall.name, permissions.canExecute)) {
         const deniedResult = {
           toolName: llmCall.name,
@@ -363,17 +618,12 @@ async function executeAgentLoop(message, ctx) {
           result: `Tool "${llmCall.name}" is not permitted`,
           status: "denied"
         };
-        allToolCalls.push(deniedResult);
-        options?.onToolCall?.({
-          toolName: llmCall.name,
-          args: llmCall.arguments,
-          result: deniedResult.result,
-          status: "denied"
-        });
+        record(deniedResult);
         messages.push({
           role: "tool",
           content: JSON.stringify({ error: deniedResult.result }),
-          toolCallId: llmCall.id
+          toolCallId: llmCall.id,
+          isError: true
         });
         continue;
       }
@@ -385,41 +635,38 @@ async function executeAgentLoop(message, ctx) {
           result: `Tool "${llmCall.name}" not found`,
           status: "denied"
         };
-        allToolCalls.push(deniedResult);
+        record(deniedResult);
         messages.push({
           role: "tool",
           content: JSON.stringify({ error: deniedResult.result }),
-          toolCallId: llmCall.id
+          toolCallId: llmCall.id,
+          isError: true
         });
         continue;
       }
-      if (toolDef.parameters) {
-        const validation = validateArgs(llmCall.arguments, toolDef.parameters);
-        if (!validation.valid) {
-          const errorMessage = `Invalid arguments for tool "${llmCall.name}": ${validation.errors.join("; ")}`;
-          if (debug) {
-            console.warn(`[react-observer-agent] ${errorMessage}`);
-          }
-          const invalidResult = {
-            toolName: llmCall.name,
-            args: llmCall.arguments,
-            result: errorMessage,
-            status: "error"
-          };
-          allToolCalls.push(invalidResult);
-          options?.onToolCall?.({
-            toolName: llmCall.name,
-            args: llmCall.arguments,
-            result: errorMessage,
-            status: "error"
-          });
-          messages.push({
-            role: "tool",
-            content: JSON.stringify({ error: errorMessage }),
-            toolCallId: llmCall.id
-          });
-          continue;
+      const validation = await validateToolArgs(toolDef, llmCall.arguments);
+      if (!validation.valid) {
+        const errorMessage = `Invalid arguments for tool "${llmCall.name}": ${validation.errors.join("; ")}`;
+        if (debug) {
+          console.warn(`[react-observer-agent] ${errorMessage}`);
         }
+        record({
+          toolName: llmCall.name,
+          args: llmCall.arguments,
+          result: errorMessage,
+          status: "error"
+        });
+        messages.push({
+          role: "tool",
+          content: JSON.stringify({ error: errorMessage }),
+          toolCallId: llmCall.id,
+          isError: true
+        });
+        continue;
+      }
+      const value = validation.value;
+      if (signal?.aborted) {
+        return cancelForAbort(llmCall.name, value, llmCall.id);
       }
       if (toolDef.confirm) {
         if (!options?.onConfirm) {
@@ -428,98 +675,133 @@ async function executeAgentLoop(message, ctx) {
               `[react-observer-agent] Tool "${llmCall.name}" requires confirmation but no onConfirm handler provided. Skipping.`
             );
           }
-          const cancelledResult = {
+          record({
             toolName: llmCall.name,
-            args: llmCall.arguments,
+            args: value,
             result: "Tool execution cancelled: no confirmation handler provided",
             status: "cancelled"
-          };
-          allToolCalls.push(cancelledResult);
-          options?.onToolCall?.({
-            toolName: llmCall.name,
-            args: llmCall.arguments,
-            result: cancelledResult.result,
-            status: "cancelled"
           });
           messages.push({
             role: "tool",
-            content: JSON.stringify({ status: "cancelled", reason: "No confirmation handler" }),
+            content: JSON.stringify({
+              status: "cancelled",
+              reason: "No confirmation handler"
+            }),
             toolCallId: llmCall.id
           });
           continue;
         }
-        const confirmed = await options.onConfirm({
-          toolName: llmCall.name,
-          args: llmCall.arguments,
-          description: toolDef.description
-        });
+        let confirmed;
+        const confirmAbort = abortRace(signal);
+        try {
+          confirmed = await Promise.race([
+            options.onConfirm({
+              toolName: llmCall.name,
+              args: value,
+              description: toolDef.description,
+              signal
+            }),
+            confirmAbort.promise
+          ]);
+        } catch (error) {
+          if (isAbortError(error) || signal?.aborted) {
+            return cancelForAbort(llmCall.name, value, llmCall.id);
+          }
+          const errorMessage = describeError(error);
+          record({
+            toolName: llmCall.name,
+            args: value,
+            result: errorMessage,
+            status: "error"
+          });
+          messages.push({
+            role: "tool",
+            content: JSON.stringify({ error: errorMessage }),
+            toolCallId: llmCall.id,
+            isError: true
+          });
+          continue;
+        } finally {
+          confirmAbort.release();
+        }
+        if (signal?.aborted) {
+          return cancelForAbort(llmCall.name, value, llmCall.id);
+        }
         if (!confirmed) {
-          const cancelledResult = {
+          record({
             toolName: llmCall.name,
-            args: llmCall.arguments,
+            args: value,
             result: "Tool execution cancelled by user",
             status: "cancelled"
-          };
-          allToolCalls.push(cancelledResult);
-          options?.onToolCall?.({
-            toolName: llmCall.name,
-            args: llmCall.arguments,
-            result: cancelledResult.result,
-            status: "cancelled"
           });
           messages.push({
             role: "tool",
-            content: JSON.stringify({ status: "cancelled", reason: "User denied" }),
+            content: JSON.stringify({
+              status: "cancelled",
+              reason: "User denied"
+            }),
             toolCallId: llmCall.id
           });
           continue;
         }
       }
+      let outcome;
+      const handlerAbort = abortRace(signal);
       try {
-        const result = await toolDef.handler(llmCall.arguments);
-        const status = toolDef.confirm ? "confirmed" : "success";
-        if (debug) {
-          console.log(`[react-observer-agent] Tool "${llmCall.name}" executed:`, { status, result });
+        const result = await Promise.race([
+          toolDef.handler(value, { signal }),
+          handlerAbort.promise
+        ]);
+        let content;
+        try {
+          content = JSON.stringify({ result });
+        } catch (error) {
+          throw new Error(
+            `Tool result is not serializable: ${describeError(error)}`
+          );
         }
-        const toolResult = {
-          toolName: llmCall.name,
-          args: llmCall.arguments,
-          result,
-          status
-        };
-        allToolCalls.push(toolResult);
-        options?.onToolCall?.({
-          toolName: llmCall.name,
-          args: llmCall.arguments,
-          result,
-          status
-        });
-        messages.push({
-          role: "tool",
-          content: JSON.stringify({ result }),
-          toolCallId: llmCall.id
-        });
+        outcome = { kind: "success", result, content };
       } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : "Unknown error";
-        const errorResult = {
+        outcome = isAbortError(error) && signal?.aborted ? { kind: "cancelled" } : { kind: "error", message: describeError(error) };
+      } finally {
+        handlerAbort.release();
+      }
+      if (outcome.kind === "cancelled") {
+        return cancelForAbort(llmCall.name, value, llmCall.id);
+      }
+      if (outcome.kind === "error") {
+        record({
           toolName: llmCall.name,
-          args: llmCall.arguments,
-          result: errorMessage,
-          status: "error"
-        };
-        allToolCalls.push(errorResult);
-        options?.onToolCall?.({
-          toolName: llmCall.name,
-          args: llmCall.arguments,
-          result: errorMessage,
+          args: value,
+          result: outcome.message,
           status: "error"
         });
         messages.push({
           role: "tool",
-          content: JSON.stringify({ error: errorMessage }),
-          toolCallId: llmCall.id
+          content: JSON.stringify({ error: outcome.message }),
+          toolCallId: llmCall.id,
+          isError: true
+        });
+        continue;
+      }
+      const status = toolDef.confirm ? "confirmed" : "success";
+      if (debug) {
+        console.log(`[react-observer-agent] Tool "${llmCall.name}" executed:`, {
+          status,
+          result: outcome.result
         });
       }
+      record({
+        toolName: llmCall.name,
+        args: value,
+        result: outcome.result,
+        status
+      });
+      messages.push({
+        role: "tool",
+        content: outcome.content,
+        toolCallId: llmCall.id
+      });
     }
   }
   if (!completed) {
@@ -539,20 +821,60 @@ async function executeAgentLoop(message, ctx) {
       messages
     };
   }
-  messages.push({ role: "assistant", content: finalMessage });
+  if (finalMessage !== "") {
+    messages.push({
+      role: "assistant",
+      content: finalMessage,
+      providerData: finalProviderData
+    });
+  }
   return {
     response: {
       message: finalMessage,
       toolCalls: allToolCalls,
+      error: stopError,
       usage: usage.total()
     },
     messages
   };
 }
 
+// src/utils/linkSignals.ts
+function linkSignals(...sources) {
+  const controller = new AbortController();
+  const listeners = [];
+  const release = () => {
+    for (const { source, listener } of listeners) {
+      source.removeEventListener("abort", listener);
+    }
+    listeners.length = 0;
+  };
+  for (const source of sources) {
+    if (!source) continue;
+    if (source.aborted) {
+      abortWith(controller, source);
+      release();
+      break;
+    }
+    const listener = () => abortWith(controller, source);
+    source.addEventListener("abort", listener, { once: true });
+    listeners.push({ source, listener });
+  }
+  return { signal: controller.signal, release };
+}
+function abortWith(controller, source) {
+  if (source.reason === void 0) {
+    controller.abort();
+    return;
+  }
+  controller.abort(source.reason);
+}
+
 // src/provider/AIAgentProvider.tsx
 import { jsx } from "react/jsx-runtime";
 var AgentContextValue = createContext(null);
+var noop = () => {
+};
 function AIAgentProvider({
   model,
   state,
@@ -578,61 +900,120 @@ function AIAgentProvider({
     validateToolNames(tools);
   }, [tools]);
   const transcriptRef = useRef([]);
+  const queueRef = useRef(Promise.resolve());
+  const pendingRef = useRef(0);
+  const generationRef = useRef(0);
+  const unmountRef = useRef(null);
+  const unmountController = useCallback(() => {
+    unmountRef.current ?? (unmountRef.current = new AbortController());
+    return unmountRef.current;
+  }, []);
+  useEffect(() => {
+    if (unmountRef.current?.signal.aborted) unmountRef.current = null;
+    const controller = unmountController();
+    return () => controller.abort();
+  }, []);
   const clearHistory = useCallback(() => {
+    generationRef.current++;
     setHistory([]);
     setLastResponse(null);
     transcriptRef.current = [];
   }, []);
-  const send = useCallback(async (message, sendOptions) => {
-    setIsProcessing(true);
-    const userEntry = {
-      role: "user",
-      content: message,
-      timestamp: Date.now()
-    };
-    setHistory((prev) => [...prev, userEntry]);
-    try {
-      const { response, messages } = await executeAgentLoop(message, {
-        model: modelRef.current,
-        state: stateRef.current,
-        tools: toolsRef.current,
-        permissions: permissionsRef.current,
-        options: optionsRef.current,
-        conversationHistory: transcriptRef.current,
-        signal: sendOptions?.signal
-      });
-      if (response.error?.code !== "ABORTED") {
-        transcriptRef.current = messages;
-      }
-      const assistantEntry = {
-        role: "assistant",
-        content: response.message,
-        toolCalls: response.toolCalls,
+  const runInteraction = useCallback(
+    async (message, sendOptions) => {
+      const generation = generationRef.current;
+      const options2 = optionsRef.current;
+      const abort = linkSignals(
+        sendOptions?.signal,
+        unmountController().signal
+      );
+      const userEntry = {
+        role: "user",
+        content: message,
         timestamp: Date.now()
       };
-      setHistory((prev) => [...prev, assistantEntry]);
-      setLastResponse(response);
+      setHistory((prev) => [...prev, userEntry]);
+      let response;
+      try {
+        const loop = await executeAgentLoop(message, {
+          model: modelRef.current,
+          state: stateRef.current,
+          tools: toolsRef.current,
+          permissions: permissionsRef.current,
+          options: options2,
+          conversationHistory: transcriptRef.current,
+          signal: abort.signal
+        });
+        response = loop.response;
+        if (generation === generationRef.current) {
+          if (response.error?.code !== "ABORTED") {
+            transcriptRef.current = loop.messages;
+          }
+          const assistantEntry = {
+            role: "assistant",
+            content: response.message,
+            toolCalls: response.toolCalls,
+            timestamp: Date.now()
+          };
+          if (response.error) {
+            assistantEntry.error = response.error;
+          }
+          setHistory((prev) => [...prev, assistantEntry]);
+          setLastResponse(response);
+        }
+      } catch (error) {
+        const agentError = error instanceof AdapterError ? {
+          message: error.message,
+          code: "ADAPTER_ERROR",
+          status: error.status,
+          cause: error
+        } : {
+          message: describeError(error),
+          cause: error
+        };
+        response = {
+          message: "",
+          toolCalls: [],
+          error: agentError
+        };
+        if (generation === generationRef.current) {
+          setHistory((prev) => [
+            ...prev,
+            {
+              role: "assistant",
+              content: "",
+              toolCalls: [],
+              error: agentError,
+              timestamp: Date.now()
+            }
+          ]);
+          setLastResponse(response);
+        }
+      } finally {
+        abort.release();
+      }
       if (response.error && response.error.code !== "ABORTED") {
-        optionsRef.current?.onError?.(response.error);
+        options2?.onError?.(response.error);
       }
       return response;
-    } catch (error) {
-      const agentError = {
-        message: error instanceof Error ? error.message : "Unknown error",
-        cause: error
-      };
-      const errorResponse = {
-        message: "",
-        toolCalls: [],
-        error: agentError
-      };
-      setLastResponse(errorResponse);
-      optionsRef.current?.onError?.(agentError);
-      return errorResponse;
-    } finally {
-      setIsProcessing(false);
-    }
-  }, []);
+    },
+    [unmountController]
+  );
+  const send = useCallback(
+    (message, sendOptions) => {
+      pendingRef.current++;
+      setIsProcessing(pendingRef.current > 0);
+      const interaction = queueRef.current.then(
+        () => runInteraction(message, sendOptions)
+      );
+      queueRef.current = interaction.then(noop, noop);
+      return interaction.finally(() => {
+        pendingRef.current--;
+        setIsProcessing(pendingRef.current > 0);
+      });
+    },
+    [runInteraction]
+  );
   const contextValue = useMemo(
     () => ({
       send,
@@ -681,7 +1062,7 @@ function openAIAdapter(config) {
   }
   const baseURL = config.baseURL ? config.baseURL.replace(/\/+$/, "") : OPENAI_BASE_URL;
   const model = config.model ?? DEFAULT_MODEL;
-  const temperature = config.temperature ?? DEFAULT_TEMPERATURE;
+  const temperature = config.temperature === null ? void 0 : config.temperature ?? DEFAULT_TEMPERATURE;
   return {
     async sendMessage(request) {
       const headers = {
@@ -691,10 +1072,11 @@ function openAIAdapter(config) {
       if (config.apiKey) {
         headers["Authorization"] = `Bearer ${config.apiKey}`;
       }
+      const conversation = request.messages.filter(isSendable).map(formatMessage);
       const messages = request.systemPrompt ? [
         { role: "system", content: request.systemPrompt },
-        ...request.messages.map(formatMessage)
-      ] : request.messages.map(formatMessage);
+        ...conversation
+      ] : conversation;
       const tools = request.tools.length > 0 ? request.tools.map((t) => ({
         type: "function",
         function: {
@@ -705,9 +1087,11 @@ function openAIAdapter(config) {
       })) : void 0;
       const body = {
         model,
-        messages,
-        temperature
+        messages
       };
+      if (temperature !== void 0) {
+        body.temperature = temperature;
+      }
       if (tools) {
         body.tools = tools;
       }
@@ -722,26 +1106,34 @@ function openAIAdapter(config) {
         });
       } catch (error) {
         if (error instanceof Error && error.name === "AbortError") throw error;
-        throw new Error(
-          `Network error calling OpenAI API: ${error instanceof Error ? error.message : "Unknown error"}`
+        throw new AdapterError(
+          `Network error calling OpenAI API: ${describeError(error)}`,
+          { cause: error }
         );
       }
       if (!res.ok) {
         const text = await res.text().catch(() => "");
-        throw new Error(
-          `OpenAI API error (${res.status}): ${text || res.statusText}`
+        throw new AdapterError(
+          `OpenAI API error (${res.status}): ${text || res.statusText}`,
+          { status: res.status, body: text }
         );
       }
       let data;
       try {
         data = await res.json();
-      } catch {
-        throw new Error("Failed to parse OpenAI API response as JSON");
+      } catch (error) {
+        throw new AdapterError("Failed to parse OpenAI API response as JSON", {
+          cause: error
+        });
       }
       return parseResponse(data);
     }
   };
 }
+function isSendable(msg) {
+  if (msg.role !== "assistant") return true;
+  return msg.content !== "" || (msg.toolCalls?.length ?? 0) > 0;
+}
 function formatMessage(msg) {
   const formatted = {
     role: msg.role,
@@ -769,11 +1161,13 @@ function parseResponse(data) {
   const obj = data;
   const choices = obj.choices;
   if (!choices || choices.length === 0) {
-    throw new Error("Malformed OpenAI response: no choices returned");
+    throw new AdapterError("Malformed OpenAI response: no choices returned");
   }
   const message = choices[0].message;
   if (!message) {
-    throw new Error("Malformed OpenAI response: no message in first choice");
+    throw new AdapterError(
+      "Malformed OpenAI response: no message in first choice"
+    );
   }
   const content = message.content ?? null;
   const toolCalls = message.tool_calls;
@@ -785,12 +1179,36 @@ function parseResponse(data) {
       name: tc.function.name,
       arguments: safeParseJSON(tc.function.arguments)
     })),
-    usage: usage ? {
-      promptTokens: usage.prompt_tokens,
-      completionTokens: usage.completion_tokens
-    } : void 0
+    usage: usage ? mapUsage(usage) : void 0,
+    stopReason: mapStopReason(choices[0].finish_reason)
   };
 }
+function mapUsage(usage) {
+  const cached = usage.prompt_tokens_details?.cached_tokens;
+  const mapped = {
+    promptTokens: usage.prompt_tokens,
+    completionTokens: usage.completion_tokens
+  };
+  if (typeof cached === "number") {
+    mapped.cacheReadTokens = cached;
+  }
+  return mapped;
+}
+function mapStopReason(finishReason) {
+  switch (finishReason) {
+    case "stop":
+      return "end";
+    case "tool_calls":
+    case "function_call":
+      return "tool_use";
+    case "length":
+      return "max_tokens";
+    case "content_filter":
+      return "refusal";
+    default:
+      return "other";
+  }
+}
 function safeParseJSON(str) {
   try {
     return JSON.parse(str);
@@ -813,6 +1231,7 @@ function claudeAdapter(config) {
   const baseURL = config.baseURL ? config.baseURL.replace(/\/+$/, "") : ANTHROPIC_BASE_URL;
   const model = config.model ?? DEFAULT_MODEL2;
   const maxTokens = config.maxTokens ?? DEFAULT_MAX_TOKENS;
+  const cache = config.cache !== false;
   return {
     async sendMessage(request) {
       const headers = {
@@ -829,7 +1248,13 @@ function claudeAdapter(config) {
         messages: toAnthropicMessages(request.messages)
       };
       if (request.systemPrompt) {
-        body.system = request.systemPrompt;
+        body.system = cache ? [
+          {
+            type: "text",
+            text: request.systemPrompt,
+            cache_control: { type: "ephemeral" }
+          }
+        ] : request.systemPrompt;
       }
       if (request.tools.length > 0) {
         body.tools = request.tools.map((t) => ({
@@ -849,21 +1274,26 @@ function claudeAdapter(config) {
         });
       } catch (error) {
         if (error instanceof Error && error.name === "AbortError") throw error;
-        throw new Error(
-          `Network error calling Anthropic API: ${error instanceof Error ? error.message : "Unknown error"}`
+        throw new AdapterError(
+          `Network error calling Anthropic API: ${describeError(error)}`,
+          { cause: error }
         );
       }
       if (!res.ok) {
         const text = await res.text().catch(() => "");
-        throw new Error(
-          `Anthropic API error (${res.status}): ${text || res.statusText}`
+        throw new AdapterError(
+          `Anthropic API error (${res.status}): ${text || res.statusText}`,
+          { status: res.status, body: text }
         );
       }
       let data;
       try {
         data = await res.json();
-      } catch {
-        throw new Error("Failed to parse Anthropic API response as JSON");
+      } catch (error) {
+        throw new AdapterError(
+          "Failed to parse Anthropic API response as JSON",
+          { cause: error }
+        );
       }
       return parseResponse2(data);
     }
@@ -880,40 +1310,60 @@ function toAnthropicMessages(messages) {
   };
   for (const message of messages) {
     if (message.role === "tool") {
-      pendingToolResults.push({
+      const block = {
         type: "tool_result",
         tool_use_id: message.toolCallId ?? "",
         content: message.content
-      });
+      };
+      if (message.isError) {
+        block.is_error = true;
+      }
+      pendingToolResults.push(block);
       continue;
     }
-    flushToolResults();
-    if (message.role === "assistant" && message.toolCalls && message.toolCalls.length > 0) {
-      const blocks = [];
-      if (message.content) {
-        blocks.push({ type: "text", text: message.content });
-      }
-      for (const call of message.toolCalls) {
-        blocks.push({
-          type: "tool_use",
-          id: call.id,
-          name: call.name,
-          input: isPlainObject2(call.arguments) ? call.arguments : {}
-        });
-      }
-      result.push({ role: "assistant", content: blocks });
+    if (message.role === "assistant") {
+      const content = toAssistantContent(message);
+      if (content === null) continue;
+      flushToolResults();
+      result.push({ role: "assistant", content });
       continue;
     }
+    flushToolResults();
     result.push({ role: message.role, content: message.content });
   }
   flushToolResults();
   return result;
 }
+function toAssistantContent(message) {
+  const replay = message.providerData;
+  if (Array.isArray(replay) && replay.length > 0) {
+    return replay;
+  }
+  const toolCalls = message.toolCalls ?? [];
+  if (toolCalls.length > 0) {
+    const blocks = [];
+    if (message.content) {
+      blocks.push({ type: "text", text: message.content });
+    }
+    for (const call of toolCalls) {
+      blocks.push({
+        type: "tool_use",
+        id: call.id,
+        name: call.name,
+        input: isPlainObject2(call.arguments) ? call.arguments : {}
+      });
+    }
+    return blocks;
+  }
+  return message.content ? message.content : null;
+}
 function parseResponse2(data) {
   const obj = data;
   const blocks = obj.content;
   if (!Array.isArray(blocks)) {
-    throw new Error("Malformed Anthropic response: no content blocks returned");
+    throw new AdapterError(
+      "Malformed Anthropic response: no content blocks returned"
+    );
   }
   const textParts = [];
   const toolCalls = [];
@@ -932,23 +1382,55 @@ function parseResponse2(data) {
   return {
     content: textParts.length > 0 ? textParts.join("") : null,
     toolCalls: toolCalls.length > 0 ? toolCalls : void 0,
-    usage: usage ? {
-      promptTokens: usage.input_tokens,
-      completionTokens: usage.output_tokens
-    } : void 0
+    usage: usage ? toTokenUsage(usage) : void 0,
+    stopReason: toStopReason(obj.stop_reason),
+    providerData: blocks
+  };
+}
+function toTokenUsage(usage) {
+  const cacheRead = usage.cache_read_input_tokens;
+  const cacheWrite = usage.cache_creation_input_tokens;
+  const result = {
+    // Anthropic reports the cached tokens outside input_tokens, so the total
+    // input for the call is the three fields added together.
+    promptTokens: usage.input_tokens + (cacheRead ?? 0) + (cacheWrite ?? 0),
+    completionTokens: usage.output_tokens
   };
+  if (typeof cacheRead === "number") {
+    result.cacheReadTokens = cacheRead;
+  }
+  if (typeof cacheWrite === "number") {
+    result.cacheWriteTokens = cacheWrite;
+  }
+  return result;
+}
+function toStopReason(value) {
+  switch (value) {
+    case "end_turn":
+      return "end";
+    case "tool_use":
+      return "tool_use";
+    case "max_tokens":
+      return "max_tokens";
+    case "refusal":
+      return "refusal";
+    default:
+      return "other";
+  }
 }
 function isPlainObject2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 export {
   AIAgentProvider,
+  AdapterError,
   claudeAdapter,
   filterState,
   filterTools,
   openAIAdapter,
   registerTool,
   useAgent,
+  validateToolArgs,
   validateToolCall,
   validateToolNames
 };