@anuma/sdk 6.39.1 → 6.39.3

package/dist/react/index.cjs

@@ -8741,6 +8741,93 @@ function composeHooks(hooks) {
   };
 }
 
+// src/lib/chat/streamIdleTimeout.ts
+var StreamIdleTimeoutError = class extends Error {
+  constructor(idleTimeoutMs) {
+    super(`Stream timed out after ${idleTimeoutMs} ms without activity.`);
+    this.name = "StreamIdleTimeoutError";
+    this.idleTimeoutMs = idleTimeoutMs;
+  }
+};
+function withStreamIdleTimeout(transport, idleTimeoutMs) {
+  if (!(idleTimeoutMs > 0) || idleTimeoutMs === Infinity) return transport;
+  return (options) => ({
+    stream: (async function* () {
+      const controller = new AbortController();
+      let timer;
+      let settled = false;
+      let completed = false;
+      let iterator;
+      let interruption;
+      let rejectPending;
+      const disarm = () => {
+        if (timer !== void 0) clearTimeout(timer);
+        timer = void 0;
+      };
+      const interrupt = (error) => {
+        if (interruption) return;
+        interruption = error;
+        rejectPending?.(error);
+        controller.abort();
+      };
+      const arm = () => {
+        if (settled || controller.signal.aborted) return;
+        disarm();
+        timer = setTimeout(() => {
+          interrupt(new StreamIdleTimeoutError(idleTimeoutMs));
+        }, idleTimeoutMs);
+      };
+      const onAbort = () => {
+        controller.abort();
+      };
+      options.signal?.addEventListener("abort", onAbort, { once: true });
+      try {
+        if (options.signal?.aborted) {
+          const error = new Error("Request aborted");
+          error.name = "AbortError";
+          throw error;
+        }
+        arm();
+        iterator = transport({
+          ...options,
+          signal: controller.signal,
+          onActivity: () => {
+            arm();
+            options.onActivity?.();
+          }
+        }).stream[Symbol.asyncIterator]();
+        while (true) {
+          if (interruption) throw interruption;
+          const next = await new Promise((resolve, reject) => {
+            rejectPending = reject;
+            Promise.resolve(iterator.next()).then(resolve, reject);
+          });
+          rejectPending = void 0;
+          if (next.done) {
+            completed = true;
+            break;
+          }
+          arm();
+          yield next.value;
+        }
+      } finally {
+        settled = true;
+        rejectPending = void 0;
+        disarm();
+        options.signal?.removeEventListener("abort", onAbort);
+        if (!completed) {
+          controller.abort();
+          try {
+            void iterator?.return?.().catch(() => {
+            });
+          } catch {
+          }
+        }
+      }
+    })()
+  });
+}
+
 // src/lib/chat/useChat/utils.ts
 var import_jsonrepair = require("jsonrepair");
 init_logger();
@@ -10931,7 +11018,20 @@ var defaultTransport = (options) => {
       } catch {
       }
     }
-    return response;
+    if (!response.body || !options.onActivity) return response;
+    const body = response.body.pipeThrough(
+      new TransformStream({
+        transform(chunk, controller) {
+          if (chunk.byteLength > 0) options.onActivity?.();
+          controller.enqueue(chunk);
+        }
+      })
+    );
+    return new Response(body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers
+    });
   };
   return createSseClient({
     method: options.method ?? "POST",
@@ -10988,6 +11088,7 @@ async function runToolLoop(options) {
     conversationId,
     smoothing,
     signal,
+    idleTimeoutMs = 12e4,
     resumable,
     detachSignal,
     onStreamMeta,
@@ -11001,13 +11102,14 @@ async function runToolLoop(options) {
     onStepFinish,
     onRequest,
     onStreamRetry,
-    transport: makeStreamingRequest = defaultTransport,
+    transport = defaultTransport,
     preProcessors,
     maxConnectorCalls = 2,
     hooks: hooksOption,
     piiRedaction,
     onPiiRedacted
   } = options;
+  const makeStreamingRequest = withStreamIdleTimeout(transport, idleTimeoutMs);
   const hooks = Array.isArray(hooksOption) ? composeHooks(hooksOption) : hooksOption;
   const runId = generateRunId();
   let messages = options.messages;
@@ -32345,6 +32447,7 @@ function useChat(options) {
     apiType: defaultApiType = "auto",
     smoothing,
     preProcessors,
+    hooks,
     piiRedaction,
     onPiiRedacted
   } = options || {};
@@ -32516,6 +32619,7 @@ function useChat(options) {
           onToolCallArgumentsDelta,
           onStepFinish,
           preProcessors,
+          hooks,
           piiRedaction: requestPiiRedaction ?? resolvedPiiRedaction,
           onPiiRedacted
         });
@@ -32553,6 +32657,7 @@ function useChat(options) {
       defaultApiType,
       smoothing,
       preProcessors,
+      hooks,
       resolvedPiiRedaction,
       onPiiRedacted
     ]
@@ -33767,6 +33872,7 @@ function useChatStorage(options) {
     minContentLength = DEFAULT_MIN_CONTENT_LENGTH,
     mcpR2Domain = MCP_R2_DOMAIN,
     preProcessors,
+    hooks,
     smoothing,
     piiRedaction,
     onPiiRedacted,
@@ -34341,6 +34447,7 @@ function useChatStorage(options) {
     onStreamMeta,
     apiType,
     preProcessors,
+    hooks,
     smoothing,
     piiRedaction: resolvedPiiRedaction,
     onPiiRedacted

package/dist/react/index.d.mts

@@ -2706,6 +2706,127 @@ declare class PiiRedactor {
     clear(): void;
 }
 
+type LlmTokenUsage = {
+    inputTokens?: number;
+    outputTokens?: number;
+};
+type ModelCallStartEvent = {
+    runId: string;
+    stepIndex: number;
+    model: string;
+    messages: Array<LlmapiMessage>;
+    tools: Array<LlmapiChatCompletionTool>;
+    requestBody: Record<string, unknown>;
+};
+type ModelCallEndEvent = {
+    runId: string;
+    stepIndex: number;
+    content: string;
+    toolCalls: Array<{
+        id: string;
+        name: string;
+        arguments: string;
+    }>;
+    usage?: LlmTokenUsage;
+    finishReason?: string;
+    error?: string;
+};
+type ToolUseStartEvent = {
+    runId: string;
+    stepIndex: number;
+    toolCallId: string;
+    name: string;
+    rawArguments: string;
+    parsedArguments?: Record<string, unknown>;
+};
+type ToolUseEndEvent = {
+    runId: string;
+    stepIndex: number;
+    toolCallId: string;
+    name: string;
+    result?: unknown;
+    error?: string;
+    errorType?: "parse" | "timeout" | "execution" | "cancelled";
+};
+type RunStartEvent = {
+    runId: string;
+    model: string;
+    messages: Array<LlmapiMessage>;
+    tools: Array<LlmapiChatCompletionTool>;
+};
+type RunEndEvent = {
+    runId: string;
+    finalContent: string;
+    /** Number of LLM rounds executed. */
+    totalSteps: number;
+};
+type RunErrorEvent = {
+    runId: string;
+    error: string;
+    /**
+     * Only `"model"` today. Tool failures surface on {@link RunHooks.afterToolUse}
+     * with `errorType`, not on `onRunError`, so a tool stage isn't needed yet.
+     * Left as a union to leave room for `"validation"` or `"tool"` later
+     * without a breaking change.
+     */
+    stage: "model";
+    /**
+     * The underlying `Error` when one is available. `RunErrorEvent` predates
+     * this field, so `error` (a string message) is kept for backwards
+     * compatibility; new consumers should prefer `errorObject` when present
+     * for stack traces and `cause`.
+     */
+    errorObject?: Error;
+};
+type RunHooks = {
+    /**
+     * Fires once per `runToolLoop` invocation, before any pre-processor or
+     * model call. The `messages` payload is the raw caller-supplied
+     * conversation — pre-processors that enrich it (e.g. web search context)
+     * run afterwards, so `beforeModelCall.messages` reflects the
+     * post-enrichment state.
+     */
+    onRunStart?: (e: RunStartEvent) => Promise<void> | void;
+    /**
+     * Fires exactly once per run on clean completion. Mutually exclusive
+     * with `onRunError` — a run that completes fires `onRunEnd`; a run that
+     * errors or is aborted fires `onRunError`. Consumers can rely on
+     * exactly one terminal hook per `onRunStart`.
+     */
+    onRunEnd?: (e: RunEndEvent) => Promise<void> | void;
+    /**
+     * Fires exactly once per run when the loop errors or is aborted.
+     * `stage` is `"model"` for stream/provider errors and for aborts;
+     * tool execution failures surface as structured `{ error, errorType }`
+     * results on `afterToolUse` rather than firing `onRunError`.
+     * Mutually exclusive with `onRunEnd`.
+     */
+    onRunError?: (e: RunErrorEvent) => Promise<void> | void;
+    beforeModelCall?: (e: ModelCallStartEvent) => Promise<void> | void;
+    afterModelCall?: (e: ModelCallEndEvent) => Promise<void> | void;
+    /**
+     * Fires before each tool the model invoked — including server-side
+     * tools that have no client executor. Today this is observe-only.
+     * TODO(follow-up PR): allow returning { args?, abort?: { reason } } to
+     * mutate arguments or short-circuit the tool call.
+     *
+     * Pairing with {@link afterToolUse} is asymmetric: server-side tools
+     * routed via `onToolCall` get `beforeToolUse` but no `afterToolUse`,
+     * because they don't execute in-process. Tools blocked by a failed
+     * dependency or a dependency cycle DO get `afterToolUse` with
+     * `errorType: "execution"` — consumers tallying matched pairs should
+     * filter on executor-backed tools to avoid spurious imbalances.
+     */
+    beforeToolUse?: (e: ToolUseStartEvent) => Promise<void> | void;
+    /**
+     * Fires after each executor-backed tool finishes (success or failure)
+     * and after each dependency-blocked tool is skipped (`errorType:
+     * "execution"`). Does NOT fire for server-side tools routed via
+     * `onToolCall`. See {@link beforeToolUse} for the pairing contract.
+     */
+    afterToolUse?: (e: ToolUseEndEvent) => Promise<void> | void;
+};
+
 /**
  * Configuration for stream output smoothing.
  *
@@ -2900,6 +3021,8 @@ type BaseSendMessageArgs = ResponsesApiOptions & {
 type BaseUseChatOptions = {
     getToken?: () => Promise<string | null>;
     baseUrl?: string;
+    /** Run lifecycle hooks for telemetry and tracing, for example from `createMetricsHooks` */
+    hooks?: RunHooks | RunHooks[];
     /**
      * Callback function to be called when a new data chunk is received.
      */
@@ -3124,12 +3247,10 @@ type StreamingTransportOptions = {
         inferenceId: string;
     }) => void;
     /**
-     * Fires whenever bytes arrive on the wire — data frames AND the keep-alive
-     * comment lines (`: ...`) the SSE parser otherwise discards. A pure liveness
-     * signal: a consumer running an idle watchdog uses it to tell a slow-but-alive
-     * stream (the server still heart-beating through a long reasoning silence)
-     * apart from a dead connection (no bytes at all). Not every transport emits it
-     * — the xhr transport does; treat its absence as "no extra liveness info".
+     * Fires when the transport receives bytes, including SSE keep-alive comments.
+     * Consumers can use this callback to reset the idle timeout.
+     * The fetch and XHR transports emit it.
+     * Custom transports can omit it if they cannot report byte activity.
      */
     onActivity?: () => void;
 };
@@ -8691,6 +8812,8 @@ interface CreateConversationOptions {
  * @inline
  */
 interface BaseUseChatStorageOptions {
+    /** Run lifecycle hooks for telemetry and tracing, for example from `createMetricsHooks` */
+    hooks?: RunHooks | RunHooks[];
     /** WatermelonDB database instance for storing conversations and messages */
     database: Database;
     /** Route memory reads, writes, recall and the memory tools through this store instead of the database's vault; folders are unsupported. With `piiRedaction` on, build the store with `embeddingOptions.maskInput` (e.g. `(text) => redactor.maskText(text)` with any `PiiRedactor`) or its memory calls throw. */

package/dist/react/index.d.ts

@@ -2706,6 +2706,127 @@ declare class PiiRedactor {
     clear(): void;
 }
 
+type LlmTokenUsage = {
+    inputTokens?: number;
+    outputTokens?: number;
+};
+type ModelCallStartEvent = {
+    runId: string;
+    stepIndex: number;
+    model: string;
+    messages: Array<LlmapiMessage>;
+    tools: Array<LlmapiChatCompletionTool>;
+    requestBody: Record<string, unknown>;
+};
+type ModelCallEndEvent = {
+    runId: string;
+    stepIndex: number;
+    content: string;
+    toolCalls: Array<{
+        id: string;
+        name: string;
+        arguments: string;
+    }>;
+    usage?: LlmTokenUsage;
+    finishReason?: string;
+    error?: string;
+};
+type ToolUseStartEvent = {
+    runId: string;
+    stepIndex: number;
+    toolCallId: string;
+    name: string;
+    rawArguments: string;
+    parsedArguments?: Record<string, unknown>;
+};
+type ToolUseEndEvent = {
+    runId: string;
+    stepIndex: number;
+    toolCallId: string;
+    name: string;
+    result?: unknown;
+    error?: string;
+    errorType?: "parse" | "timeout" | "execution" | "cancelled";
+};
+type RunStartEvent = {
+    runId: string;
+    model: string;
+    messages: Array<LlmapiMessage>;
+    tools: Array<LlmapiChatCompletionTool>;
+};
+type RunEndEvent = {
+    runId: string;
+    finalContent: string;
+    /** Number of LLM rounds executed. */
+    totalSteps: number;
+};
+type RunErrorEvent = {
+    runId: string;
+    error: string;
+    /**
+     * Only `"model"` today. Tool failures surface on {@link RunHooks.afterToolUse}
+     * with `errorType`, not on `onRunError`, so a tool stage isn't needed yet.
+     * Left as a union to leave room for `"validation"` or `"tool"` later
+     * without a breaking change.
+     */
+    stage: "model";
+    /**
+     * The underlying `Error` when one is available. `RunErrorEvent` predates
+     * this field, so `error` (a string message) is kept for backwards
+     * compatibility; new consumers should prefer `errorObject` when present
+     * for stack traces and `cause`.
+     */
+    errorObject?: Error;
+};
+type RunHooks = {
+    /**
+     * Fires once per `runToolLoop` invocation, before any pre-processor or
+     * model call. The `messages` payload is the raw caller-supplied
+     * conversation — pre-processors that enrich it (e.g. web search context)
+     * run afterwards, so `beforeModelCall.messages` reflects the
+     * post-enrichment state.
+     */
+    onRunStart?: (e: RunStartEvent) => Promise<void> | void;
+    /**
+     * Fires exactly once per run on clean completion. Mutually exclusive
+     * with `onRunError` — a run that completes fires `onRunEnd`; a run that
+     * errors or is aborted fires `onRunError`. Consumers can rely on
+     * exactly one terminal hook per `onRunStart`.
+     */
+    onRunEnd?: (e: RunEndEvent) => Promise<void> | void;
+    /**
+     * Fires exactly once per run when the loop errors or is aborted.
+     * `stage` is `"model"` for stream/provider errors and for aborts;
+     * tool execution failures surface as structured `{ error, errorType }`
+     * results on `afterToolUse` rather than firing `onRunError`.
+     * Mutually exclusive with `onRunEnd`.
+     */
+    onRunError?: (e: RunErrorEvent) => Promise<void> | void;
+    beforeModelCall?: (e: ModelCallStartEvent) => Promise<void> | void;
+    afterModelCall?: (e: ModelCallEndEvent) => Promise<void> | void;
+    /**
+     * Fires before each tool the model invoked — including server-side
+     * tools that have no client executor. Today this is observe-only.
+     * TODO(follow-up PR): allow returning { args?, abort?: { reason } } to
+     * mutate arguments or short-circuit the tool call.
+     *
+     * Pairing with {@link afterToolUse} is asymmetric: server-side tools
+     * routed via `onToolCall` get `beforeToolUse` but no `afterToolUse`,
+     * because they don't execute in-process. Tools blocked by a failed
+     * dependency or a dependency cycle DO get `afterToolUse` with
+     * `errorType: "execution"` — consumers tallying matched pairs should
+     * filter on executor-backed tools to avoid spurious imbalances.
+     */
+    beforeToolUse?: (e: ToolUseStartEvent) => Promise<void> | void;
+    /**
+     * Fires after each executor-backed tool finishes (success or failure)
+     * and after each dependency-blocked tool is skipped (`errorType:
+     * "execution"`). Does NOT fire for server-side tools routed via
+     * `onToolCall`. See {@link beforeToolUse} for the pairing contract.
+     */
+    afterToolUse?: (e: ToolUseEndEvent) => Promise<void> | void;
+};
+
 /**
  * Configuration for stream output smoothing.
  *
@@ -2900,6 +3021,8 @@ type BaseSendMessageArgs = ResponsesApiOptions & {
 type BaseUseChatOptions = {
     getToken?: () => Promise<string | null>;
     baseUrl?: string;
+    /** Run lifecycle hooks for telemetry and tracing, for example from `createMetricsHooks` */
+    hooks?: RunHooks | RunHooks[];
     /**
      * Callback function to be called when a new data chunk is received.
      */
@@ -3124,12 +3247,10 @@ type StreamingTransportOptions = {
         inferenceId: string;
     }) => void;
     /**
-     * Fires whenever bytes arrive on the wire — data frames AND the keep-alive
-     * comment lines (`: ...`) the SSE parser otherwise discards. A pure liveness
-     * signal: a consumer running an idle watchdog uses it to tell a slow-but-alive
-     * stream (the server still heart-beating through a long reasoning silence)
-     * apart from a dead connection (no bytes at all). Not every transport emits it
-     * — the xhr transport does; treat its absence as "no extra liveness info".
+     * Fires when the transport receives bytes, including SSE keep-alive comments.
+     * Consumers can use this callback to reset the idle timeout.
+     * The fetch and XHR transports emit it.
+     * Custom transports can omit it if they cannot report byte activity.
      */
     onActivity?: () => void;
 };
@@ -8691,6 +8812,8 @@ interface CreateConversationOptions {
  * @inline
  */
 interface BaseUseChatStorageOptions {
+    /** Run lifecycle hooks for telemetry and tracing, for example from `createMetricsHooks` */
+    hooks?: RunHooks | RunHooks[];
     /** WatermelonDB database instance for storing conversations and messages */
     database: Database;
     /** Route memory reads, writes, recall and the memory tools through this store instead of the database's vault; folders are unsupported. With `piiRedaction` on, build the store with `embeddingOptions.maskInput` (e.g. `(text) => redactor.maskText(text)` with any `PiiRedactor`) or its memory calls throw. */

package/dist/react/index.mjs

@@ -6889,6 +6889,93 @@ function composeHooks(hooks) {
   };
 }
 
+// src/lib/chat/streamIdleTimeout.ts
+var StreamIdleTimeoutError = class extends Error {
+  constructor(idleTimeoutMs) {
+    super(`Stream timed out after ${idleTimeoutMs} ms without activity.`);
+    this.name = "StreamIdleTimeoutError";
+    this.idleTimeoutMs = idleTimeoutMs;
+  }
+};
+function withStreamIdleTimeout(transport, idleTimeoutMs) {
+  if (!(idleTimeoutMs > 0) || idleTimeoutMs === Infinity) return transport;
+  return (options) => ({
+    stream: (async function* () {
+      const controller = new AbortController();
+      let timer;
+      let settled = false;
+      let completed = false;
+      let iterator;
+      let interruption;
+      let rejectPending;
+      const disarm = () => {
+        if (timer !== void 0) clearTimeout(timer);
+        timer = void 0;
+      };
+      const interrupt = (error) => {
+        if (interruption) return;
+        interruption = error;
+        rejectPending?.(error);
+        controller.abort();
+      };
+      const arm = () => {
+        if (settled || controller.signal.aborted) return;
+        disarm();
+        timer = setTimeout(() => {
+          interrupt(new StreamIdleTimeoutError(idleTimeoutMs));
+        }, idleTimeoutMs);
+      };
+      const onAbort = () => {
+        controller.abort();
+      };
+      options.signal?.addEventListener("abort", onAbort, { once: true });
+      try {
+        if (options.signal?.aborted) {
+          const error = new Error("Request aborted");
+          error.name = "AbortError";
+          throw error;
+        }
+        arm();
+        iterator = transport({
+          ...options,
+          signal: controller.signal,
+          onActivity: () => {
+            arm();
+            options.onActivity?.();
+          }
+        }).stream[Symbol.asyncIterator]();
+        while (true) {
+          if (interruption) throw interruption;
+          const next = await new Promise((resolve, reject) => {
+            rejectPending = reject;
+            Promise.resolve(iterator.next()).then(resolve, reject);
+          });
+          rejectPending = void 0;
+          if (next.done) {
+            completed = true;
+            break;
+          }
+          arm();
+          yield next.value;
+        }
+      } finally {
+        settled = true;
+        rejectPending = void 0;
+        disarm();
+        options.signal?.removeEventListener("abort", onAbort);
+        if (!completed) {
+          controller.abort();
+          try {
+            void iterator?.return?.().catch(() => {
+            });
+          } catch {
+          }
+        }
+      }
+    })()
+  });
+}
+
 // src/lib/chat/useChat/utils.ts
 import { jsonrepair } from "jsonrepair";
 function parseToolArguments(raw) {
@@ -9078,7 +9165,20 @@ var defaultTransport = (options) => {
       } catch {
       }
     }
-    return response;
+    if (!response.body || !options.onActivity) return response;
+    const body = response.body.pipeThrough(
+      new TransformStream({
+        transform(chunk, controller) {
+          if (chunk.byteLength > 0) options.onActivity?.();
+          controller.enqueue(chunk);
+        }
+      })
+    );
+    return new Response(body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers
+    });
   };
   return createSseClient({
     method: options.method ?? "POST",
@@ -9135,6 +9235,7 @@ async function runToolLoop(options) {
     conversationId,
     smoothing,
     signal,
+    idleTimeoutMs = 12e4,
     resumable,
     detachSignal,
     onStreamMeta,
@@ -9148,13 +9249,14 @@ async function runToolLoop(options) {
     onStepFinish,
     onRequest,
     onStreamRetry,
-    transport: makeStreamingRequest = defaultTransport,
+    transport = defaultTransport,
     preProcessors,
     maxConnectorCalls = 2,
     hooks: hooksOption,
     piiRedaction,
     onPiiRedacted
   } = options;
+  const makeStreamingRequest = withStreamIdleTimeout(transport, idleTimeoutMs);
   const hooks = Array.isArray(hooksOption) ? composeHooks(hooksOption) : hooksOption;
   const runId = generateRunId();
   let messages = options.messages;
@@ -30435,6 +30537,7 @@ function useChat(options) {
     apiType: defaultApiType = "auto",
     smoothing,
     preProcessors,
+    hooks,
     piiRedaction,
     onPiiRedacted
   } = options || {};
@@ -30606,6 +30709,7 @@ function useChat(options) {
           onToolCallArgumentsDelta,
           onStepFinish,
           preProcessors,
+          hooks,
           piiRedaction: requestPiiRedaction ?? resolvedPiiRedaction,
           onPiiRedacted
         });
@@ -30643,6 +30747,7 @@ function useChat(options) {
       defaultApiType,
       smoothing,
       preProcessors,
+      hooks,
       resolvedPiiRedaction,
       onPiiRedacted
     ]
@@ -31847,6 +31952,7 @@ function useChatStorage(options) {
     minContentLength = DEFAULT_MIN_CONTENT_LENGTH,
     mcpR2Domain = MCP_R2_DOMAIN,
     preProcessors,
+    hooks,
     smoothing,
     piiRedaction,
     onPiiRedacted,
@@ -32421,6 +32527,7 @@ function useChatStorage(options) {
     onStreamMeta,
     apiType,
     preProcessors,
+    hooks,
     smoothing,
     piiRedaction: resolvedPiiRedaction,
     onPiiRedacted