@fgv/ts-extras 5.1.0-4 → 5.1.0-40

package/lib/packlets/ai-assist/streamingAdapters/clientToolContinuationBuilder.js

@@ -0,0 +1,694 @@
+"use strict";
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAnthropicContinuation = buildAnthropicContinuation;
+exports.buildOpenAiContinuation = buildOpenAiContinuation;
+exports.buildGeminiContinuation = buildGeminiContinuation;
+exports.hasGeminiToolConflict = hasGeminiToolConflict;
+exports.executeClientToolTurn = executeClientToolTurn;
+/**
+ * Per-provider continuation message builders and the `executeClientToolTurn`
+ * helper for orchestrating a single client-tool round-trip.
+ *
+ * Each provider requires a different wire format for the follow-up request:
+ * - **Anthropic**: assistant turn reconstructed from the ordered accumulation
+ *   buffer (thinking / redacted_thinking / text / tool_use in original stream
+ *   order) + user turn with `tool_result` blocks. When thinking is active, the
+ *   follow-up request must NOT set `tool_choice: { type: 'any' }` or
+ *   `tool_choice: { type: 'tool', ... }` (E3 / §5.4 of b4-spike-findings).
+ * - **OpenAI / xAI Responses API**: `function_call` input items +
+ *   `function_call_output` input items.
+ * - **Gemini**: model turn with `functionCall` parts + user turn with
+ *   `functionResponse` parts (correlation by tool name).
+ *
+ * @packageDocumentation
+ */
+const ts_utils_1 = require("@fgv/ts-utils");
+const model_1 = require("../model");
+const chatRequestBuilders_1 = require("../chatRequestBuilders");
+const endpoint_1 = require("../endpoint");
+const anthropic_1 = require("./anthropic");
+const openaiResponses_1 = require("./openaiResponses");
+const gemini_1 = require("./gemini");
+// ============================================================================
+// Anthropic continuation builder
+// ============================================================================
+/**
+ * Returns `true` when `id` is a usable correlation id — present and non-empty.
+ *
+ * `??` is NOT sufficient for this check: an empty string is a *bad* id (a
+ * `tool_use_id: ''` is rejected by Anthropic as a "malformed identifier") but
+ * `'' ?? fallback` yields `''`, silently passing the empty id through. Every id
+ * correlation in this module must use this predicate, never `??`.
+ *
+ * @internal
+ */
+function isUsableId(id) {
+    return id !== undefined && id.length > 0;
+}
+/**
+ * Builds the Anthropic follow-up messages for a client-tool round-trip.
+ *
+ * Reconstructs the assistant turn from the ordered accumulation buffer
+ * (all block types in original stream order) and appends a user turn
+ * with `tool_result` blocks for each executed tool call.
+ *
+ * **Single source of truth for the id (id-correlation fix).** Each
+ * `tool_result.tool_use_id` is drawn from — and validated against — the set of
+ * assistant `tool_use.id`s actually present in the accumulation buffer. The id
+ * is NEVER derived from the tool name: a tool name can never match a `toolu_*`
+ * id, so a name fallback produces exactly the "malformed identifier" the
+ * provider rejects. If any tool result cannot be correlated to a buffered
+ * `tool_use` block with a non-empty id, the build fails loud (naming the tool)
+ * rather than emitting a malformed continuation.
+ *
+ * **Constraint (E3):** The returned continuation does NOT include a forced
+ * `tool_choice` field. When thinking is active, Anthropic rejects
+ * `tool_choice: { type: 'any' }` and `tool_choice: { type: 'tool', ... }`
+ * with an HTTP 400 error. Only `tool_choice: { type: 'auto' }` (the default,
+ * i.e. omitted) is compatible with extended thinking.
+ *
+ * @internal
+ */
+function buildAnthropicContinuation(accBuffer, toolResults, logger) {
+    // Reconstruct the assistant turn from the ordered accumulation buffer.
+    // Sort by buffer key (SSE index) to restore original stream order.
+    const sortedKeys = Array.from(accBuffer.keys()).sort((a, b) => a - b);
+    const assistantContent = [];
+    // The set of assistant tool_use ids — the single source of truth every
+    // tool_result.tool_use_id must be drawn from.
+    const bufferedToolUseIds = new Set();
+    for (const key of sortedKeys) {
+        const block = accBuffer.get(key);
+        /* c8 ignore next 1 - defensive: key always exists in map since we iterate its keys */
+        if (!block)
+            continue;
+        if (block.type === 'thinking') {
+            assistantContent.push({
+                type: 'thinking',
+                thinking: block.thinking,
+                signature: block.signature
+            });
+        }
+        else if (block.type === 'redacted_thinking') {
+            assistantContent.push({
+                type: 'redacted_thinking',
+                data: block.data
+            });
+        }
+        else if (block.type === 'text') {
+            if (block.text.length > 0) {
+                assistantContent.push({ type: 'text', text: block.text });
+            }
+        }
+        else if (block.type === 'tool_use') {
+            // A buffered tool_use with an empty id can never be referenced by a valid
+            // tool_result; emitting it would corrupt the assistant turn. Fail loud.
+            if (!isUsableId(block.id)) {
+                return (0, ts_utils_1.fail)(`Anthropic continuation: buffered tool_use block for tool '${block.name}' has an empty id; ` +
+                    `cannot build a valid continuation`);
+            }
+            let parsedInput;
+            try {
+                /* c8 ignore next 1 - defensive: argsBuffer is JSON-parsed in the adapter before emitting client-tool-call-done */
+                parsedInput = JSON.parse(block.argsBuffer || '{}');
+                /* c8 ignore start - defensive: malformed argsBuffer defaults to empty object */
+            }
+            catch (_a) {
+                parsedInput = {};
+            }
+            /* c8 ignore stop */
+            bufferedToolUseIds.add(block.id);
+            assistantContent.push({
+                type: 'tool_use',
+                id: block.id,
+                name: block.name,
+                input: parsedInput
+            });
+        }
+    }
+    // Build user turn with tool_result blocks for each tool call. Correlate each
+    // result to a buffered tool_use id — the SAME id that keys the assistant
+    // tool_use block — and fail loud on a missing / empty / mismatched id. A
+    // missing callId is a bug to surface, not paper over with a name fallback.
+    const userContent = [];
+    for (const r of toolResults) {
+        if (!isUsableId(r.callId)) {
+            return (0, ts_utils_1.fail)(`Anthropic continuation: tool '${r.toolName}' result has no call id (missing or empty); ` +
+                `cannot correlate it to an assistant tool_use block`);
+        }
+        if (!bufferedToolUseIds.has(r.callId)) {
+            return (0, ts_utils_1.fail)(`Anthropic continuation: tool '${r.toolName}' call id '${r.callId}' does not match any ` +
+                `buffered assistant tool_use block id`);
+        }
+        const block = {
+            type: 'tool_result',
+            // eslint-disable-next-line @typescript-eslint/naming-convention
+            tool_use_id: r.callId,
+            content: r.result
+        };
+        userContent.push(r.isError ? Object.assign(Object.assign({}, block), { is_error: true }) : block);
+    }
+    // Decisive diagnostic: the tool_use.id ↔ tool_result.tool_use_id pairing for
+    // the outgoing continuation. A failing turn is field-confirmable by capturing
+    // this line (the pairing is by construction matched here — divergence fails
+    // loud above, before reaching this point).
+    if (logger) {
+        const pairing = toolResults.map((r) => `${r.toolName}:${r.callId}`).join(', ');
+        logger.detail(`ai-assist:anthropic-continuation tool_use.id↔tool_result.tool_use_id [${pairing}]`);
+    }
+    const assistantMessage = {
+        role: 'assistant',
+        content: assistantContent
+    };
+    const userMessage = {
+        role: 'user',
+        content: userContent
+    };
+    return (0, ts_utils_1.succeed)({
+        messages: [assistantMessage, userMessage],
+        toolCallsSummary: toolResults.map((r) => ({
+            toolName: r.toolName,
+            callId: r.callId,
+            args: r.args,
+            result: r.result,
+            isError: r.isError
+        }))
+    });
+}
+// ============================================================================
+// OpenAI / xAI Responses API continuation builder
+// ============================================================================
+/**
+ * Builds the OpenAI / xAI Responses API follow-up input items for a
+ * client-tool round-trip.
+ *
+ * Emits `function_call` items (the model's call) followed by
+ * `function_call_output` items (the harness execution result), one pair
+ * per executed tool call.
+ *
+ * **Single source of truth for the id (id-correlation fix).** Each
+ * `function_call_output.call_id` is drawn from — and validated against — the
+ * set of `function_call.call_id`s in the accumulation map. It is NEVER derived
+ * from the tool name (the OpenAI parity of the Anthropic `tool_use_id` fix). A
+ * missing / empty / unmatched call id fails the build loud rather than emitting
+ * a continuation the provider would reject.
+ *
+ * @internal
+ */
+function buildOpenAiContinuation(calls, toolResults, logger) {
+    const items = [];
+    // Emit function_call items for each call (model's side). Per the Responses API spec
+    // (ResponseFunctionToolCall), `call_id` is the required correlation field — it must
+    // match the matching function_call_output's `call_id` below. The optional `id` field
+    // is the output-item id (`fc_*`) used to reference the streamed item; we omit it
+    // because it is not load-bearing for input items.
+    const bufferedCallIds = new Set();
+    for (const [callId, call] of calls) {
+        bufferedCallIds.add(callId);
+        items.push({
+            type: 'function_call',
+            call_id: callId,
+            name: call.name,
+            arguments: call.argsBuffer
+        });
+    }
+    // Emit function_call_output items (harness execution results). Correlate each
+    // to a buffered function_call call_id — never the tool name — and fail loud on
+    // a missing / empty / mismatched id.
+    for (const r of toolResults) {
+        if (!isUsableId(r.callId)) {
+            return (0, ts_utils_1.fail)(`OpenAI continuation: tool '${r.toolName}' result has no call id (missing or empty); ` +
+                `cannot correlate it to a function_call item`);
+        }
+        if (!bufferedCallIds.has(r.callId)) {
+            return (0, ts_utils_1.fail)(`OpenAI continuation: tool '${r.toolName}' call id '${r.callId}' does not match any ` +
+                `accumulated function_call call_id`);
+        }
+        items.push({
+            type: 'function_call_output',
+            call_id: r.callId,
+            output: r.result
+        });
+    }
+    // Decisive diagnostic: the function_call.call_id ↔ function_call_output.call_id
+    // pairing for the outgoing continuation (matched by construction here).
+    if (logger) {
+        const pairing = toolResults.map((r) => `${r.toolName}:${r.callId}`).join(', ');
+        logger.detail(`ai-assist:openai-continuation function_call.call_id↔output.call_id [${pairing}]`);
+    }
+    return (0, ts_utils_1.succeed)({
+        messages: items,
+        toolCallsSummary: toolResults.map((r) => ({
+            toolName: r.toolName,
+            callId: r.callId,
+            args: r.args,
+            result: r.result,
+            isError: r.isError
+        }))
+    });
+}
+// ============================================================================
+// Gemini continuation builder
+// ============================================================================
+/**
+ * Builds the Gemini follow-up contents for a client-tool round-trip.
+ *
+ * Emits a model turn with `functionCall` parts (one per tool call) and a
+ * user turn with `functionResponse` parts (correlation by tool name, since
+ * Gemini does not assign call IDs).
+ *
+ * When thinking is enabled, Gemini stamps an opaque `thoughtSignature` on each
+ * `functionCall` part and requires it echoed back, verbatim, as a sibling of
+ * `functionCall` on the continuation's model turn — otherwise the follow-up is
+ * rejected with "Function call is missing a thought_signature in functionCall
+ * parts". The captured signature (see {@link IAccumulatedGeminiFunctionCall})
+ * is replayed here only when present; the key is omitted entirely when thinking
+ * was disabled. See https://ai.google.dev/gemini-api/docs/thought-signatures.
+ *
+ * @internal
+ */
+function buildGeminiContinuation(calls, toolResults) {
+    // Model turn: functionCall parts for each call. Replay the part-level
+    // thoughtSignature as a sibling of functionCall only when present.
+    const modelParts = calls.map((call) => (Object.assign({ functionCall: {
+            name: call.name,
+            args: call.args
+        } }, (call.thoughtSignature !== undefined ? { thoughtSignature: call.thoughtSignature } : {}))));
+    // User turn: functionResponse parts for each executed result.
+    // Correlation is by name since Gemini has no call IDs.
+    const userParts = toolResults.map((r) => ({
+        functionResponse: {
+            name: r.toolName,
+            response: Object.assign({ content: r.result }, (r.isError ? { error: true } : {}))
+        }
+    }));
+    const modelMessage = {
+        role: 'model',
+        parts: modelParts
+    };
+    const userMessage = {
+        role: 'user',
+        parts: userParts
+    };
+    return {
+        messages: [modelMessage, userMessage],
+        toolCallsSummary: toolResults.map((r) => ({
+            toolName: r.toolName,
+            callId: r.callId,
+            args: r.args,
+            result: r.result,
+            isError: r.isError
+        }))
+    };
+}
+// ============================================================================
+// executeClientToolTurn
+// ============================================================================
+/**
+ * True when a request would combine Gemini built-in grounding (a `web_search`
+ * server tool) with client (function) tools — a combination Gemini's
+ * `generateContent` API rejects with HTTP 400 (`INVALID_ARGUMENT`). Callers gate
+ * on `descriptor.apiFormat === 'gemini'` before consulting this; other providers
+ * accept the mix. Kept as a pure predicate so the conflict rule is unit-testable
+ * without a live stream.
+ *
+ * @internal
+ */
+function hasGeminiToolConflict(tools, clientTools) {
+    var _a;
+    return clientTools.length > 0 && ((_a = tools === null || tools === void 0 ? void 0 : tools.some((t) => t.type === 'web_search')) !== null && _a !== void 0 ? _a : false);
+}
+/**
+ * Orchestrates a single client-tool streaming turn for any supported provider.
+ *
+ * Starts a streaming request, iterates the underlying provider stream, and:
+ * - Forwards `text-delta`, `tool-event`, `client-tool-call-start`, and
+ *   `client-tool-call-done` events through to the consumer.
+ * - For each `client-tool-call-done` event: validates the raw args against the
+ *   tool's `parametersSchema`, invokes `execute(typedArgs)`, and emits a
+ *   `client-tool-result` event.
+ * - After stream completion: builds the per-provider continuation (or
+ *   `{ continuation: undefined }` when no tool calls occurred) and resolves
+ *   `nextTurn`.
+ *
+ * **Anthropic constraint (E3):** The continuation for Anthropic does not set
+ * a forced `tool_choice`. Only `tool_choice: 'auto'` (the default, i.e.
+ * omitted) is compatible with extended thinking.
+ *
+ * @param params - Turn parameters
+ * @returns `{ events, nextTurn }` — stream iterable + completion promise
+ * @public
+ */
+function executeClientToolTurn(params) {
+    const { descriptor, apiKey, system, messages, continuationMessages, temperature, tools, clientTools, signal, logger, resolvedThinking, model, endpoint, onBeforeToolExecute } = params;
+    const splitResult = (0, chatRequestBuilders_1.splitChatRequest)(system, messages);
+    if (splitResult.isFailure()) {
+        return (0, ts_utils_1.fail)(splitResult.message);
+    }
+    const { prompt, head } = splitResult.value;
+    if (prompt.attachments.length > 0 && !descriptor.acceptsImageInput) {
+        return (0, ts_utils_1.fail)(`provider "${descriptor.id}" does not accept image input`);
+    }
+    // Build a lookup map of client tools by name for fast access.
+    // Fail fast on duplicate names — silently overwriting would cause one tool
+    // to shadow another with no observable signal.
+    const toolsByName = new Map();
+    for (const tool of clientTools) {
+        if (toolsByName.has(tool.config.name)) {
+            return (0, ts_utils_1.fail)(`executeClientToolTurn: duplicate client tool name '${tool.config.name}'`);
+        }
+        toolsByName.set(tool.config.name, tool);
+    }
+    // Merge server tools and client tool configs into a single array for the provider.
+    // This is the fix for P1-1: client tools were never sent to the provider because
+    // the adapters only received `tools` (server tools). Both must coexist per design §2.5.
+    const effectiveTools = clientTools.length > 0 ? [...(tools !== null && tools !== void 0 ? tools : []), ...clientTools.map((t) => t.config)] : tools;
+    // Gemini pre-flight: its generateContent API HTTP-400s (INVALID_ARGUMENT) when
+    // built-in grounding (`web_search`) and function calling (client tools) are
+    // combined in one request. Fail fast with a clear, actionable message rather
+    // than letting the opaque wire 400 surface. Other providers accept the mix.
+    if (descriptor.apiFormat === 'gemini' && hasGeminiToolConflict(tools, clientTools)) {
+        return (0, ts_utils_1.fail)('executeClientToolTurn: Gemini cannot combine web_search grounding with client (function) tools in the same request; send one or the other');
+    }
+    const modelResult = (0, model_1.resolveProviderModel)(descriptor, model);
+    if (modelResult.isFailure()) {
+        return (0, ts_utils_1.fail)(modelResult.message);
+    }
+    const resolvedModel = modelResult.value;
+    const baseUrlResult = (0, endpoint_1.resolveEffectiveBaseUrl)(descriptor, endpoint);
+    if (baseUrlResult.isFailure()) {
+        return (0, ts_utils_1.fail)(baseUrlResult.message);
+    }
+    const config = {
+        baseUrl: baseUrlResult.value,
+        apiKey,
+        model: resolvedModel
+    };
+    // Accumulation buffers — populated by the adapter, read by the builder.
+    const anthropicBuffer = new Map();
+    const openAiCallMap = new Map();
+    const geminiCalls = [];
+    // Collected tool results, populated as each client-tool-call-done is processed.
+    const toolResults = [];
+    // Stream start: open the underlying adapter stream.
+    const streamPromise = (() => {
+        switch (descriptor.apiFormat) {
+            case 'anthropic':
+                return (0, anthropic_1.callAnthropicStream)(config, prompt, head, temperature, effectiveTools, logger, signal, resolvedThinking, anthropicBuffer, continuationMessages);
+            case 'openai':
+                return (0, openaiResponses_1.callOpenAiResponsesStream)(config, prompt, 
+                /* c8 ignore next 1 - defensive: openai path requires tools; empty array fallback unreachable in practice */
+                effectiveTools !== null && effectiveTools !== void 0 ? effectiveTools : [], head, temperature, logger, signal, resolvedThinking, openAiCallMap, continuationMessages);
+            case 'gemini':
+                return (0, gemini_1.callGeminiStream)(config, prompt, head, temperature, effectiveTools, logger, signal, resolvedThinking, geminiCalls, continuationMessages);
+            /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
+            default: {
+                const _exhaustive = descriptor.apiFormat;
+                return Promise.resolve((0, ts_utils_1.fail)(`unsupported API format: ${String(_exhaustive)}`));
+            }
+        }
+    })();
+    // Resolve controls for `nextTurn`.
+    let resolveNextTurn;
+    const nextTurn = new Promise((resolve) => {
+        resolveNextTurn = resolve;
+    });
+    // The unified-event generator: opens the stream, proxies events, executes tools.
+    function eventGenerator() {
+        return __asyncGenerator(this, arguments, function* eventGenerator_1() {
+            var _a, e_1, _b, _c;
+            const streamResult = yield __await(streamPromise);
+            if (streamResult.isFailure()) {
+                resolveNextTurn((0, ts_utils_1.fail)(streamResult.message));
+                yield yield __await({ type: 'error', message: streamResult.message });
+                return yield __await(void 0);
+            }
+            let truncated = false;
+            let fullText = '';
+            let streamError;
+            try {
+                for (var _d = true, _e = __asyncValues(streamResult.value), _f; _f = yield __await(_e.next()), _a = _f.done, !_a; _d = true) {
+                    _c = _f.value;
+                    _d = false;
+                    const event = _c;
+                    if (event.type === 'done') {
+                        truncated = event.truncated;
+                        fullText = event.fullText;
+                        yield yield __await(event);
+                        continue;
+                    }
+                    if (event.type === 'error') {
+                        streamError = event.message;
+                        yield yield __await(event);
+                        continue;
+                    }
+                    if (event.type === 'text-delta') {
+                        yield yield __await(event);
+                        continue;
+                    }
+                    if (event.type === 'tool-event') {
+                        yield yield __await(event);
+                        continue;
+                    }
+                    if (event.type === 'client-tool-call-start') {
+                        yield yield __await(event);
+                        continue;
+                    }
+                    if (event.type === 'client-tool-call-done') {
+                        yield yield __await(event);
+                        const { toolName, callId, args } = event;
+                        const tool = toolsByName.get(toolName);
+                        if (!tool) {
+                            const errMsg = `model called unknown tool: ${toolName}`;
+                            const resultEvent = {
+                                type: 'client-tool-result',
+                                toolName,
+                                callId,
+                                result: errMsg,
+                                isError: true
+                            };
+                            yield yield __await(resultEvent);
+                            toolResults.push({ toolName, callId, args, result: errMsg, isError: true });
+                            resolveNextTurn((0, ts_utils_1.fail)(errMsg));
+                            return yield __await(void 0);
+                        }
+                        const validationResult = tool.config.parametersSchema.validate(args);
+                        if (validationResult.isFailure()) {
+                            const errMsg = `${toolName} (callId=${callId}): ${validationResult.message}`;
+                            const resultEvent = {
+                                type: 'client-tool-result',
+                                toolName,
+                                callId,
+                                result: errMsg,
+                                isError: true
+                            };
+                            yield yield __await(resultEvent);
+                            toolResults.push({ toolName, callId, args, result: errMsg, isError: true });
+                            continue;
+                        }
+                        // Host gate: run after arg-validation, before execute. A `deny` decision
+                        // synthesizes a denial tool-result and continues the turn; a `fail`/reject
+                        // from the gate itself is a hard error (mirrors an execute failure), never
+                        // a silent deny.
+                        if (onBeforeToolExecute !== undefined) {
+                            const decisionResult = (yield __await((0, ts_utils_1.captureAsyncResult)(async () => onBeforeToolExecute(tool, validationResult.value)))).onSuccess((decision) => decision);
+                            if (decisionResult.isFailure()) {
+                                const errMsg = `${toolName} (callId=${callId}): ${decisionResult.message}`;
+                                const resultEvent = {
+                                    type: 'client-tool-result',
+                                    toolName,
+                                    callId,
+                                    result: errMsg,
+                                    isError: true
+                                };
+                                yield yield __await(resultEvent);
+                                // Gate-fail is a hard, turn-terminating error (unlike a non-fatal `deny`, whose
+                                // generator continues). Emit an explicit `error` event so a consumer watching only
+                                // `events` sees the fatal failure inline and can distinguish it from a deny — matching
+                                // the stream-open / continuation hard-error paths.
+                                yield yield __await({ type: 'error', message: errMsg });
+                                toolResults.push({ toolName, callId, args, result: errMsg, isError: true });
+                                resolveNextTurn((0, ts_utils_1.fail)(errMsg));
+                                return yield __await(void 0);
+                            }
+                            if (decisionResult.value.action === 'deny') {
+                                const denialMsg = `${toolName} (callId=${callId}): tool execution denied: ${decisionResult.value.reason}`;
+                                const resultEvent = {
+                                    type: 'client-tool-result',
+                                    toolName,
+                                    callId,
+                                    result: denialMsg,
+                                    isError: true
+                                };
+                                yield yield __await(resultEvent);
+                                toolResults.push({ toolName, callId, args, result: denialMsg, isError: true });
+                                continue;
+                            }
+                        }
+                        const executeResult = yield __await((0, ts_utils_1.captureAsyncResult)(async () => tool.execute(validationResult.value)));
+                        const executionResult = executeResult.isSuccess()
+                            ? executeResult.value
+                            : executeResult;
+                        if (executionResult.isFailure()) {
+                            const errMsg = `${toolName} (callId=${callId}): ${executionResult.message}`;
+                            const resultEvent = {
+                                type: 'client-tool-result',
+                                toolName,
+                                callId,
+                                result: errMsg,
+                                isError: true
+                            };
+                            yield yield __await(resultEvent);
+                            toolResults.push({ toolName, callId, args, result: errMsg, isError: true });
+                            continue;
+                        }
+                        // JSON.stringify can throw (circular references) or return undefined
+                        // (e.g. for a bare `undefined` value, or a value of type `function`).
+                        // Either outcome violates the client-tool-result event contract, so
+                        // emit an isError result with diagnostic context instead.
+                        let resultStr;
+                        try {
+                            const stringified = JSON.stringify(executionResult.value);
+                            if (stringified === undefined) {
+                                const errMsg = `${toolName} (callId=${callId}): tool returned a non-serializable value (JSON.stringify produced undefined)`;
+                                const resultEvent = {
+                                    type: 'client-tool-result',
+                                    toolName,
+                                    callId,
+                                    result: errMsg,
+                                    isError: true
+                                };
+                                yield yield __await(resultEvent);
+                                toolResults.push({ toolName, callId, args, result: errMsg, isError: true });
+                                continue;
+                            }
+                            resultStr = stringified;
+                        }
+                        catch (e) {
+                            const errMsg = `${toolName} (callId=${callId}): failed to serialize tool result: ${e.message}`;
+                            const resultEvent = {
+                                type: 'client-tool-result',
+                                toolName,
+                                callId,
+                                result: errMsg,
+                                isError: true
+                            };
+                            yield yield __await(resultEvent);
+                            toolResults.push({ toolName, callId, args, result: errMsg, isError: true });
+                            continue;
+                        }
+                        const resultEvent = {
+                            type: 'client-tool-result',
+                            toolName,
+                            callId,
+                            result: resultStr,
+                            isError: false
+                        };
+                        yield yield __await(resultEvent);
+                        toolResults.push({ toolName, callId, args, result: resultStr, isError: false });
+                        continue;
+                    }
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (!_d && !_a && (_b = _e.return)) yield __await(_b.call(_e));
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+            // Stream has ended. Build the continuation.
+            if (streamError !== undefined) {
+                resolveNextTurn((0, ts_utils_1.fail)(streamError));
+                return yield __await(void 0);
+            }
+            if (toolResults.length === 0) {
+                resolveNextTurn((0, ts_utils_1.succeed)({ continuation: undefined, truncated, fullText }));
+                return yield __await(void 0);
+            }
+            let continuationResult;
+            switch (descriptor.apiFormat) {
+                case 'anthropic':
+                    continuationResult = buildAnthropicContinuation(anthropicBuffer, toolResults, logger);
+                    break;
+                case 'openai':
+                    continuationResult = buildOpenAiContinuation(openAiCallMap, toolResults, logger);
+                    break;
+                case 'gemini':
+                    // Gemini correlates by tool name by design (no call ids) — its builder
+                    // cannot mis-key and stays non-fallible.
+                    continuationResult = (0, ts_utils_1.succeed)(buildGeminiContinuation(geminiCalls, toolResults));
+                    break;
+                /* c8 ignore next 5 - defensive coding: exhaustive switch guaranteed by TypeScript */
+                default: {
+                    const _exhaustive = descriptor.apiFormat;
+                    resolveNextTurn((0, ts_utils_1.fail)(`unsupported API format: ${String(_exhaustive)}`));
+                    return yield __await(void 0);
+                }
+            }
+            // A bad id-correlation fails loud here rather than emitting a malformed
+            // continuation the provider would reject as a "malformed identifier". Mirror
+            // the stream-open-failure path above: surface an `error` event so a consumer
+            // iterating `events` sees the failure inline, not only via `nextTurn`.
+            if (continuationResult.isFailure()) {
+                resolveNextTurn((0, ts_utils_1.fail)(continuationResult.message));
+                yield yield __await({ type: 'error', message: continuationResult.message });
+                return yield __await(void 0);
+            }
+            let continuation = continuationResult.value;
+            // Prepend inbound continuationMessages so the returned continuation is cumulative.
+            // A consumer that does `tail = outcome.continuation.messages` (replace) is then
+            // correct for all N rounds — messages always contains the full wire tail from
+            // round 1 through the current round. toolCallsSummary stays per-round (this
+            // round's calls only); messages is the accumulated tail to re-send.
+            if (continuationMessages && continuationMessages.length > 0) {
+                continuation = Object.assign(Object.assign({}, continuation), { messages: [...continuationMessages, ...continuation.messages] });
+            }
+            resolveNextTurn((0, ts_utils_1.succeed)({ continuation, truncated, fullText }));
+        });
+    }
+    return (0, ts_utils_1.succeed)({
+        events: { [Symbol.asyncIterator]: () => eventGenerator() },
+        nextTurn
+    });
+}
+//# sourceMappingURL=clientToolContinuationBuilder.js.map