@vedmalex/ai-connect 0.9.0 → 0.10.0

package/dist/browser/index.js

@@ -2622,6 +2622,73 @@ function normalizeToolResult(result) {
     ...result.isError !== void 0 ? { isError: result.isError } : {}
   };
 }
+var MAX_CLIENT_TOOL_LOOP_DEPTH = 8;
+async function* executeToolCallsRound(params) {
+  const { toolCalls, registry, route, request, runtime, messages, abort } = params;
+  const assistantMessage = {
+    role: "assistant",
+    content: params.assistantText,
+    toolCalls
+  };
+  const toolMessages = [];
+  for (const toolCall of toolCalls) {
+    const tool = registry.get(toolCall.name);
+    if (!tool) {
+      throw new ClientToolExecutionError(
+        new AiConnectError(
+          "validation_error",
+          `No client tool handler is registered for "${toolCall.name}".`
+        )
+      );
+    }
+    if (abort.signal.aborted) {
+      throw mapAbortError(abort.reason);
+    }
+    const startEvent = params.onToolStart?.(toolCall);
+    if (startEvent) {
+      yield startEvent;
+    }
+    let execution;
+    try {
+      execution = normalizeToolResult(
+        await tool.execute(toolCall.arguments, {
+          route,
+          request,
+          runtime,
+          toolCall,
+          messages,
+          ...request.workingDirectory ? { workingDirectory: request.workingDirectory } : {}
+        })
+      );
+    } catch (error) {
+      if (abort.signal.aborted) {
+        throw mapAbortError(abort.reason);
+      }
+      throw new ClientToolExecutionError(
+        new AiConnectError(
+          "validation_error",
+          `Client tool "${tool.function.name}" threw during execution: ${error instanceof Error ? error.message : String(error)}`,
+          { cause: error }
+        )
+      );
+    }
+    toolMessages.push({
+      role: "tool",
+      content: execution.content,
+      toolName: tool.function.name,
+      toolCallId: toolCall.id,
+      ...execution.data !== void 0 ? { data: execution.data } : {},
+      ...execution.isError !== void 0 ? { isError: execution.isError } : {}
+    });
+    const finishEvent = params.onToolFinish?.(toolCall, {
+      ...execution.isError !== void 0 ? { isError: execution.isError } : {}
+    });
+    if (finishEvent) {
+      yield finishEvent;
+    }
+  }
+  return { assistantMessage, toolMessages };
+}
 function sumOptionalNumbers(left, right) {
   if (left === void 0) {
     return right;
@@ -3225,7 +3292,7 @@ function createClient(configOrInput, options = {}) {
     let output = initialOutput;
     let messages = [...request.messages];
     let transportSummary2;
-    for (let round = 0; round < 8; round += 1) {
+    for (let round = 0; ; round += 1) {
       const toolCalls = output.toolCalls ?? [];
       if (toolCalls.length === 0) {
         return {
@@ -3237,62 +3304,36 @@ function createClient(configOrInput, options = {}) {
           ...transportSummary2 ? { transportSummary: transportSummary2 } : {}
         };
       }
-      const assistantMessage = {
-        role: "assistant",
-        content: output.text ?? "",
-        toolCalls
-      };
-      const toolMessages = [];
-      for (const toolCall of toolCalls) {
-        const tool = registry.get(toolCall.name);
-        if (!tool) {
-          throw new ClientToolExecutionError(
-            new AiConnectError(
-              "validation_error",
-              `No client tool handler is registered for "${toolCall.name}".`
-            )
-          );
-        }
-        if (abort.signal.aborted) {
-          throw mapAbortError(abort.reason);
-        }
-        let execution;
-        try {
-          execution = normalizeToolResult(
-            await tool.execute(toolCall.arguments, {
-              route,
-              request,
-              runtime,
-              toolCall,
-              messages,
-              ...request.workingDirectory ? { workingDirectory: request.workingDirectory } : {}
-            })
-          );
-        } catch (error) {
-          if (abort.signal.aborted) {
-            throw mapAbortError(abort.reason);
-          }
-          throw new ClientToolExecutionError(
-            new AiConnectError(
-              "validation_error",
-              `Client tool "${tool.function.name}" threw during execution: ${error instanceof Error ? error.message : String(error)}`,
-              { cause: error }
-            )
-          );
-        }
-        toolMessages.push({
-          role: "tool",
-          content: execution.content,
-          toolName: tool.function.name,
-          toolCallId: toolCall.id,
-          ...execution.data !== void 0 ? { data: execution.data } : {},
-          ...execution.isError !== void 0 ? { isError: execution.isError } : {}
-        });
+      const roundIterator = executeToolCallsRound({
+        toolCalls,
+        assistantText: output.text ?? "",
+        registry,
+        route,
+        request,
+        runtime,
+        messages,
+        abort
+      });
+      let roundStep = await roundIterator.next();
+      while (!roundStep.done) {
+        roundStep = await roundIterator.next();
       }
-      messages = [...messages, assistantMessage, ...toolMessages];
+      messages = [
+        ...messages,
+        roundStep.value.assistantMessage,
+        ...roundStep.value.toolMessages
+      ];
       if (abort.signal.aborted) {
         throw mapAbortError(abort.reason);
       }
+      if (round + 1 >= MAX_CLIENT_TOOL_LOOP_DEPTH) {
+        throw new ClientToolExecutionError(
+          new AiConnectError(
+            "validation_error",
+            `clientTools exceeded the maximum tool-call loop depth of ${MAX_CLIENT_TOOL_LOOP_DEPTH}.`
+          )
+        );
+      }
       output = await runWithAbortRace(
         handler({
           route,
@@ -3315,12 +3356,6 @@ function createClient(configOrInput, options = {}) {
       warnings.push(...output.warnings ?? []);
       usage = mergeUsage(usage, output.usage);
     }
-    throw new ClientToolExecutionError(
-      new AiConnectError(
-        "validation_error",
-        "clientTools exceeded the maximum tool-call loop depth of 8."
-      )
-    );
   }
   async function emitWideEvent(event) {
     if (!logging?.logger) {
@@ -4380,12 +4415,6 @@ function createClient(configOrInput, options = {}) {
     },
     async *stream(request, opts) {
       const preparedRequest = prepareRequest(request);
-      if (preparedRequest.clientTools?.length) {
-        throw new AiConnectError(
-          "not_supported",
-          "clientTools are currently supported only by generate(), not stream()."
-        );
-      }
       const { abort, dispose: disposeAbort } = deriveAbort(
         opts,
         resolveOpTimeout(opts, "generateMs", options.timeouts),
@@ -4405,7 +4434,12 @@ function createClient(configOrInput, options = {}) {
         release = await limiter.acquire(abort.signal);
         const selectedModel = await resolveSelectedModel(preparedRequest);
         const normalizedRequest = withSelectedModel(preparedRequest, selectedModel);
-        const { requiresImage, requiresFile, request: capabilityScopedRequest } = resolveRequiredCapabilities(normalizedRequest);
+        const {
+          requiresImage,
+          requiresFile,
+          requiresClientTools,
+          request: capabilityScopedRequest
+        } = resolveRequiredCapabilities(normalizedRequest);
         const candidates = router.resolveCandidates(capabilityScopedRequest);
         const startedAt = nowMs(runtime);
         const requestId = resolveEventRequestId(normalizedRequest.logContext);
@@ -4413,10 +4447,12 @@ function createClient(configOrInput, options = {}) {
         const requestSummary = summarizeRequest(normalizedRequest, candidateSummaries);
         const attempts = [];
         const wideAttempts = [];
+        let hasYieldedOutward = false;
+        let sawStreamHandler = false;
         if (candidates.length === 0) {
-          const error = requiresImage || requiresFile ? new AiConnectError(
+          const error = requiresImage || requiresFile || requiresClientTools ? new AiConnectError(
             "unsupported_capability",
-            `No eligible route supports the required ${requiresFile ? "document/file" : "image"} input for operation "${normalizedRequest.operation}" in runtime "${runtime.kind}".`
+            requiresImage || requiresFile ? `No eligible route supports the required ${requiresFile ? "document/file" : "image"} input for operation "${normalizedRequest.operation}" in runtime "${runtime.kind}".` : `No eligible route supports client-side tool execution for operation "${normalizedRequest.operation}" in runtime "${runtime.kind}".`
           ) : new AiConnectError("not_supported", `No eligible routes are available for operation "${normalizedRequest.operation}" in runtime "${runtime.kind}".`);
           await emitWideEvent({
             timestamp: isoTimestamp(startedAt),
@@ -4444,84 +4480,202 @@ function createClient(configOrInput, options = {}) {
             continue;
           }
           if (handler.stream) {
+            sawStreamHandler = true;
             const routeSummary = summarizeRoute(route);
             const attemptStartedAt = nowMs(runtime);
             let lastResult;
             let accumulatedText = "";
             const routeRequest = applyRouteDefaults(route, normalizedRequest);
-            const iterable = handler.stream({
-              route,
-              request: routeRequest,
-              runtime,
-              attempt: 1,
-              abort
-            });
-            const iterator = iterable[Symbol.asyncIterator]();
-            let iteratorReturned = false;
-            const returnIterator = async () => {
-              if (iteratorReturned) {
-                return;
-              }
-              iteratorReturned = true;
-              try {
-                await iterator.return?.();
-              } catch {
-              }
-            };
+            const roundTools = routeRequest.clientTools ?? [];
+            const registry = new Map(
+              roundTools.map((tool) => [tool.function.name, tool])
+            );
+            let loopMessages = routeRequest.messages;
+            let aggregatedUsage;
+            const aggregatedWarnings = [];
+            let toolRoundsExecuted = 0;
             try {
-              while (true) {
+              roundsLoop: for (let round = 0; ; round += 1) {
+                if (round >= MAX_CLIENT_TOOL_LOOP_DEPTH) {
+                  throw new ClientToolExecutionError(
+                    new AiConnectError(
+                      "validation_error",
+                      `clientTools exceeded the maximum tool-call loop depth of ${MAX_CLIENT_TOOL_LOOP_DEPTH}.`
+                    )
+                  );
+                }
                 if (abort.signal.aborted) {
-                  await returnIterator();
                   throw mapAbortError(abort.reason);
                 }
-                if (pauseSignal?.aborted) {
+                const roundRequest = round === 0 ? routeRequest : { ...routeRequest, messages: loopMessages, attachments: [] };
+                const iterable = handler.stream({
+                  route,
+                  request: roundRequest,
+                  runtime,
+                  attempt: 1,
+                  abort
+                });
+                const iterator = iterable[Symbol.asyncIterator]();
+                let iteratorReturned = false;
+                const returnIterator = async () => {
+                  if (iteratorReturned) {
+                    return;
+                  }
+                  iteratorReturned = true;
+                  try {
+                    await iterator.return?.();
+                  } catch {
+                  }
+                };
+                let roundResult;
+                try {
+                  while (true) {
+                    if (abort.signal.aborted) {
+                      await returnIterator();
+                      throw mapAbortError(abort.reason);
+                    }
+                    if (pauseSignal?.aborted) {
+                      await returnIterator();
+                      const pausedResult = lastResult ?? {
+                        route,
+                        text: accumulatedText,
+                        attachments: [],
+                        warnings: [],
+                        attempts
+                      };
+                      wideAttempts.push({
+                        index: wideAttempts.length + 1,
+                        route: routeSummary,
+                        durationMs: nowMs(runtime) - attemptStartedAt,
+                        outcome: "success",
+                        retryCount: 0
+                      });
+                      await emitWideEvent({
+                        timestamp: isoTimestamp(startedAt),
+                        event: "ai_connect.operation",
+                        requestId,
+                        operationName: "stream",
+                        operation: normalizedRequest.operation,
+                        runtime: runtime.kind,
+                        outcome: "success",
+                        durationMs: nowMs(runtime) - startedAt,
+                        candidates: candidateSummaries,
+                        attempts: wideAttempts,
+                        selectedRoute: routeSummary,
+                        request: requestSummary,
+                        result: summarizeResult(pausedResult),
+                        ...normalizedRequest.logContext ? { context: normalizedRequest.logContext } : {}
+                      });
+                      yield { type: "paused", result: pausedResult };
+                      return;
+                    }
+                    const next = await iterator.next();
+                    if (next.done) {
+                      break;
+                    }
+                    const event = next.value;
+                    if (event.type === "delta") {
+                      accumulatedText += event.text;
+                      hasYieldedOutward = true;
+                      yield event;
+                      continue;
+                    }
+                    if (event.type === "paused") {
+                      lastResult = event.result;
+                      wideAttempts.push({
+                        index: wideAttempts.length + 1,
+                        route: routeSummary,
+                        durationMs: nowMs(runtime) - attemptStartedAt,
+                        outcome: "success",
+                        retryCount: 0
+                      });
+                      router.recordSuccess(route);
+                      await emitWideEvent({
+                        timestamp: isoTimestamp(startedAt),
+                        event: "ai_connect.operation",
+                        requestId,
+                        operationName: "stream",
+                        operation: normalizedRequest.operation,
+                        runtime: runtime.kind,
+                        outcome: "success",
+                        durationMs: nowMs(runtime) - startedAt,
+                        candidates: candidateSummaries,
+                        attempts: wideAttempts,
+                        selectedRoute: routeSummary,
+                        request: requestSummary,
+                        result: summarizeResult(event.result),
+                        ...normalizedRequest.logContext ? { context: normalizedRequest.logContext } : {}
+                      });
+                      yield event;
+                      return;
+                    }
+                    if (event.type === "result") {
+                      roundResult = event.result;
+                      break;
+                    }
+                  }
+                } finally {
                   await returnIterator();
-                  const pausedResult = lastResult ?? {
-                    route,
-                    text: accumulatedText,
-                    attachments: [],
-                    warnings: [],
-                    attempts
-                  };
-                  wideAttempts.push({
-                    index: wideAttempts.length + 1,
-                    route: routeSummary,
-                    durationMs: nowMs(runtime) - attemptStartedAt,
-                    outcome: "success",
-                    retryCount: 0
-                  });
-                  await emitWideEvent({
-                    timestamp: isoTimestamp(startedAt),
-                    event: "ai_connect.operation",
-                    requestId,
-                    operationName: "stream",
-                    operation: normalizedRequest.operation,
-                    runtime: runtime.kind,
-                    outcome: "success",
-                    durationMs: nowMs(runtime) - startedAt,
-                    candidates: candidateSummaries,
-                    attempts: wideAttempts,
-                    selectedRoute: routeSummary,
-                    request: requestSummary,
-                    result: summarizeResult(pausedResult),
-                    ...normalizedRequest.logContext ? { context: normalizedRequest.logContext } : {}
-                  });
-                  yield { type: "paused", result: pausedResult };
-                  return;
                 }
-                const next = await iterator.next();
-                if (next.done) {
-                  break;
+                if (!roundResult) {
+                  break roundsLoop;
                 }
-                const event = next.value;
-                if (event.type === "delta") {
-                  accumulatedText += event.text;
-                  yield event;
-                  continue;
+                if (registry.size === 0 || !roundResult.toolCalls?.length) {
+                  if (toolRoundsExecuted === 0) {
+                    lastResult = roundResult;
+                  } else {
+                    const mergedUsage = mergeUsage(aggregatedUsage, roundResult.usage);
+                    lastResult = {
+                      ...roundResult,
+                      warnings: [
+                        ...aggregatedWarnings,
+                        ...roundResult.warnings ?? []
+                      ],
+                      ...mergedUsage ? { usage: mergedUsage } : {}
+                    };
+                  }
+                  yield { type: "result", result: lastResult };
+                  break roundsLoop;
                 }
-                lastResult = event.result;
-                yield event;
-                break;
+                aggregatedUsage = mergeUsage(aggregatedUsage, roundResult.usage);
+                aggregatedWarnings.push(...roundResult.warnings ?? []);
+                const roundGen = executeToolCallsRound({
+                  toolCalls: roundResult.toolCalls,
+                  assistantText: roundResult.text ?? "",
+                  registry,
+                  route,
+                  request: routeRequest,
+                  runtime,
+                  messages: loopMessages,
+                  abort,
+                  // D3/UR-007: emit a `tool-call` BEFORE execute, `tool-result` AFTER.
+                  onToolStart: (toolCall) => ({
+                    type: "tool-call",
+                    toolCall: {
+                      id: toolCall.id,
+                      name: toolCall.name,
+                      arguments: toolCall.arguments
+                    }
+                  }),
+                  onToolFinish: (toolCall, execution) => ({
+                    type: "tool-result",
+                    toolCallId: toolCall.id,
+                    name: toolCall.name,
+                    ...execution.isError !== void 0 ? { isError: execution.isError } : {}
+                  })
+                });
+                let toolStep = await roundGen.next();
+                while (!toolStep.done) {
+                  hasYieldedOutward = true;
+                  yield toolStep.value;
+                  toolStep = await roundGen.next();
+                }
+                loopMessages = [
+                  ...loopMessages,
+                  toolStep.value.assistantMessage,
+                  ...toolStep.value.toolMessages
+                ];
+                toolRoundsExecuted += 1;
               }
               wideAttempts.push({
                 index: wideAttempts.length + 1,
@@ -4549,7 +4703,44 @@ function createClient(configOrInput, options = {}) {
               });
               return;
             } catch (error) {
-              await returnIterator();
+              if (error instanceof ClientToolExecutionError && !abort.signal.aborted) {
+                const toolError = error.aiError;
+                attempts.push({
+                  routeId: route.id,
+                  handlerKey: route.handlerKey,
+                  errorCode: toolError.code,
+                  message: toolError.message
+                });
+                wideAttempts.push({
+                  index: wideAttempts.length + 1,
+                  route: routeSummary,
+                  durationMs: nowMs(runtime) - attemptStartedAt,
+                  outcome: "error",
+                  retryCount: 0,
+                  errorCode: toolError.code,
+                  message: toolError.message
+                });
+                await emitWideEvent({
+                  timestamp: isoTimestamp(startedAt),
+                  event: "ai_connect.operation",
+                  requestId,
+                  operationName: "stream",
+                  operation: normalizedRequest.operation,
+                  runtime: runtime.kind,
+                  outcome: "error",
+                  durationMs: nowMs(runtime) - startedAt,
+                  candidates: candidateSummaries,
+                  attempts: wideAttempts,
+                  request: requestSummary,
+                  error: {
+                    code: toolError.code,
+                    message: toolError.message,
+                    routeId: route.id
+                  },
+                  ...normalizedRequest.logContext ? { context: normalizedRequest.logContext } : {}
+                });
+                throw toolError;
+              }
               const normalizedError = abort.signal.aborted ? mapAbortError(abort.reason) : toAiConnectError(error);
               attempts.push({
                 routeId: route.id,
@@ -4588,6 +4779,28 @@ function createClient(configOrInput, options = {}) {
                 });
                 throw normalizedError;
               }
+              if (hasYieldedOutward) {
+                await emitWideEvent({
+                  timestamp: isoTimestamp(startedAt),
+                  event: "ai_connect.operation",
+                  requestId,
+                  operationName: "stream",
+                  operation: normalizedRequest.operation,
+                  runtime: runtime.kind,
+                  outcome: "error",
+                  durationMs: nowMs(runtime) - startedAt,
+                  candidates: candidateSummaries,
+                  attempts: wideAttempts,
+                  request: requestSummary,
+                  error: {
+                    code: normalizedError.code,
+                    message: normalizedError.message,
+                    routeId: route.id
+                  },
+                  ...normalizedRequest.logContext ? { context: normalizedRequest.logContext } : {}
+                });
+                throw normalizedError;
+              }
               router.recordFailure(route, normalizedError.code);
               continue;
             }
@@ -4603,6 +4816,12 @@ function createClient(configOrInput, options = {}) {
           attempts,
           wideAttempts
         });
+        if (requiresClientTools && !sawStreamHandler) {
+          result.warnings = [
+            ...result.warnings,
+            "Streaming tool-loop is not supported by the available route(s); returned a non-streamed result via the generate tool-loop."
+          ];
+        }
         yield {
           type: "result",
           result