@juspay/neurolink 12.47.13 → 12.48.0

package/dist/core/modules/ToolsManager.js

@@ -3,9 +3,26 @@ import { createToolEventPayload } from "../toolEvents.js";
 import { tracers, ATTR, withSpan } from "../../telemetry/index.js";
 import { SpanStatusCode } from "@opentelemetry/api";
 import { logger } from "../../utils/logger.js";
+import { TOOL_EVENTS_WRAPPED } from "../../types/index.js";
 import { getKeyCount } from "../../utils/transformationUtils.js";
+import { extractIsErrorText } from "../../utils/toolResultStatus.js";
 import { convertJsonSchemaToZod } from "../../utils/schemaConversion.js";
 import { generateToolOutputPreview, DEFAULT_MAX_PREVIEW_BYTES, RETRIEVE_CONTEXT_TOOL_NAME, } from "../../context/toolOutputLimits.js";
+/**
+ * Own property stamped on a tool object whose `execute` already emits
+ * `tool:start` / `tool:end`. It lives on the OBJECT, not the function: later
+ * layers (the execution recorder, discovery) replace `execute` via
+ * `{ ...tool, execute }`, which drops a function-identity check but carries a
+ * symbol-keyed own property along — so one execution still yields one pair.
+ */
+function isEventWrappedTool(tool) {
+    return (typeof tool === "object" &&
+        tool !== null &&
+        tool[TOOL_EVENTS_WRAPPED] === true);
+}
+function markEventWrapped(tool) {
+    return Object.assign(tool, { [TOOL_EVENTS_WRAPPED]: true });
+}
 import { tool as createAISDKTool, jsonSchema } from "../../utils/tool.js";
 /** Abort-shaped error so provider loops route it to their cancellation path. */
 function makeToolAbortError() {
@@ -183,6 +200,9 @@ export class ToolsManager {
     // Session context
     sessionId;
     userId;
+    // Execute functions this manager already instrumented for tool events,
+    // so re-wrapping is a no-op rather than a second start/end pair.
+    eventWrappedExecutes = new WeakSet();
     constructor(providerName, directTools, neurolink, utilities) {
         this.providerName = providerName;
         this.directTools = directTools;
@@ -443,12 +463,128 @@ export class ToolsManager {
         this.sessionId = sessionId;
         this.userId = userId;
     }
+    /**
+     * Emit one tool event. A listener that throws must never reach the tool
+     * loop: it would turn a successful execution into a failed one (the model
+     * then retries a side effect that already happened) and, from inside the
+     * wrapper's catch, produce a second `tool:end` for the same call. Listener
+     * failures are logged and swallowed here instead.
+     */
     emitToolEvent(eventName, toolName, payload) {
-        if (this.neurolink?.getEventEmitter) {
+        if (!this.neurolink?.getEventEmitter) {
+            return;
+        }
+        try {
             this.neurolink
                 .getEventEmitter()
                 .emit(eventName, createToolEventPayload(toolName, payload));
         }
+        catch (listenerError) {
+            logger.warn(`A ${eventName} listener threw for tool ${toolName}`, {
+                error: listenerError instanceof Error
+                    ? listenerError.message
+                    : String(listenerError),
+            });
+        }
+    }
+    /**
+     * Wrap an execute function so one `tool:start` and exactly one `tool:end`
+     * (with the real duration) fire per invocation. Idempotent: a function this
+     * manager already wrapped is returned as is, so a tool that re-enters
+     * resolution (the stream → generate fallback re-resolves `options.tools`)
+     * never emits twice.
+     *
+     * A result the tool RETURNED with `isError: true` (MCP failure, breaker
+     * refusal, a thrown error already converted by `neurolink.executeTool`) is
+     * a failure: `tool:end` carries `success: false` and the extracted text,
+     * as the step-finish emitter this wrapper replaced did.
+     */
+    wrapExecuteWithEvents(toolName, execute) {
+        if (this.eventWrappedExecutes.has(execute)) {
+            return execute;
+        }
+        const wrapped = async (params, execOptions) => {
+            const startTime = Date.now();
+            // The loop's execute options carry the model's tool_call id, which is
+            // what lets a listener pair concurrent same-name start/end events.
+            const toolCallId = execOptions && typeof execOptions === "object"
+                ? execOptions.toolCallId
+                : undefined;
+            const idField = typeof toolCallId === "string" && toolCallId.length > 0
+                ? { toolCallId }
+                : {};
+            this.emitToolEvent("tool:start", toolName, {
+                input: params,
+                ...idField,
+            });
+            let result;
+            try {
+                result = await execute(params, execOptions);
+            }
+            catch (error) {
+                const errorMsg = error instanceof Error ? error.message : String(error);
+                this.emitToolEvent("tool:end", toolName, {
+                    error: errorMsg,
+                    success: false,
+                    responseTime: Date.now() - startTime,
+                    ...idField,
+                });
+                throw error;
+            }
+            const isErrorText = extractIsErrorText(result);
+            this.emitToolEvent("tool:end", toolName, {
+                result,
+                success: isErrorText === undefined,
+                ...(isErrorText !== undefined ? { error: isErrorText } : {}),
+                responseTime: Date.now() - startTime,
+                ...idField,
+            });
+            return result;
+        };
+        this.eventWrappedExecutes.add(wrapped);
+        return wrapped;
+    }
+    /**
+     * Report a tool call the loop rejected BEFORE any execute ran — an unknown
+     * tool name, arguments the schema rejected, a breaker skip. Nothing else
+     * emits for such a call, so listeners (memory event capture, tool spans,
+     * error-rate metrics) saw zero attempts while the result list held the
+     * failures. One `tool:start` / `tool:end(success: false)` pair.
+     */
+    emitRejectedToolCall(toolName, error, toolCallId) {
+        const idField = toolCallId ? { toolCallId } : {};
+        this.emitToolEvent("tool:start", toolName, { ...idField });
+        this.emitToolEvent("tool:end", toolName, {
+            error,
+            success: false,
+            responseTime: 0,
+            ...idField,
+        });
+    }
+    /**
+     * Give per-call tools (`options.tools`) the same `tool:start` / `tool:end`
+     * emission that registered and MCP tools get from their executors. Tools
+     * without an `execute` pass through untouched.
+     */
+    wrapExternalToolsWithEvents(tools) {
+        const wrapped = {};
+        for (const [toolName, tool] of Object.entries(tools)) {
+            if (isEventWrappedTool(tool)) {
+                wrapped[toolName] = tool;
+                continue;
+            }
+            const execute = tool && typeof tool === "object" && "execute" in tool
+                ? tool.execute
+                : undefined;
+            wrapped[toolName] =
+                typeof execute === "function"
+                    ? markEventWrapped({
+                        ...tool,
+                        execute: this.wrapExecuteWithEvents(toolName, execute),
+                    })
+                    : tool;
+        }
+        return wrapped;
     }
     /**
      * Set up tool executor for a provider to enable actual tool execution
@@ -586,31 +722,10 @@ export class ToolsManager {
                 const originalExecute = directTool.execute;
                 // Create a new tool with wrapped execute function (BZ-666/BZ-664 guards applied)
                 const guardedExecute = this.wrapExecuteWithTruncation(toolName, originalExecute);
-                tools[toolName] = {
+                tools[toolName] = markEventWrapped({
                     ...directTool,
-                    execute: async (params, execOptions) => {
-                        const startTime = Date.now();
-                        this.emitToolEvent("tool:start", toolName, { input: params });
-                        try {
-                            const result = await guardedExecute(params, execOptions);
-                            this.emitToolEvent("tool:end", toolName, {
-                                result,
-                                success: true,
-                                responseTime: Date.now() - startTime,
-                            });
-                            return result;
-                        }
-                        catch (error) {
-                            const errorMsg = error instanceof Error ? error.message : String(error);
-                            this.emitToolEvent("tool:end", toolName, {
-                                error: errorMsg,
-                                success: false,
-                                responseTime: Date.now() - startTime,
-                            });
-                            throw error;
-                        }
-                    },
-                };
+                    execute: this.wrapExecuteWithEvents(toolName, guardedExecute),
+                });
             }
             else {
                 // Fallback: include tool as-is if it doesn't have execute function
@@ -722,7 +837,9 @@ export class ToolsManager {
             else {
                 finalSchema = z.object({});
             }
-            return createAISDKTool({
+            // Emits its own tool:start / tool:end through neurolink.executeTool, so
+            // it is marked as instrumented and never wrapped a second time.
+            return markEventWrapped(createAISDKTool({
                 description: toolInfo.description || `Tool ${toolName}`,
                 inputSchema: finalSchema, // AI SDK v6 uses inputSchema (not parameters)
                 execute: async (params) => {
@@ -849,7 +966,7 @@ export class ToolsManager {
                         customToolSpan.end();
                     }
                 },
-            });
+            }));
         }
         catch (toolCreationError) {
             logger.error(`Failed to create tool: ${toolName}`, toolCreationError);
@@ -902,36 +1019,23 @@ export class ToolsManager {
                 throw new Error(`Cannot execute external MCP tool: NeuroLink executeExternalMCPTool not available`);
             };
             const guardedExecute = this.wrapExecuteWithTruncation(tool.name, rawExecute);
-            return createAISDKTool({
+            const loggedExecute = async (params, execOptions) => {
+                try {
+                    return await guardedExecute(params, execOptions);
+                }
+                catch (mcpError) {
+                    logger.error(`External MCP tool failed: ${tool.name}`, {
+                        serverId: tool.serverId,
+                        error: mcpError instanceof Error ? mcpError.message : String(mcpError),
+                    });
+                    throw mcpError;
+                }
+            };
+            return markEventWrapped(createAISDKTool({
                 description: tool.description || `External MCP tool ${tool.name}`,
                 inputSchema: finalSchema, // AI SDK v6 uses inputSchema (not parameters)
-                execute: async (params, execOptions) => {
-                    const startTime = Date.now();
-                    this.emitToolEvent("tool:start", tool.name, { input: params });
-                    try {
-                        const result = await guardedExecute(params, execOptions);
-                        this.emitToolEvent("tool:end", tool.name, {
-                            result,
-                            success: true,
-                            responseTime: Date.now() - startTime,
-                        });
-                        return result;
-                    }
-                    catch (mcpError) {
-                        const errorMsg = mcpError instanceof Error ? mcpError.message : String(mcpError);
-                        this.emitToolEvent("tool:end", tool.name, {
-                            error: errorMsg,
-                            success: false,
-                            responseTime: Date.now() - startTime,
-                        });
-                        logger.error(`External MCP tool failed: ${tool.name}`, {
-                            serverId: tool.serverId,
-                            error: errorMsg,
-                        });
-                        throw mcpError;
-                    }
-                },
-            });
+                execute: this.wrapExecuteWithEvents(tool.name, loggedExecute),
+            }));
         }
         catch (toolCreationError) {
             logger.error(`Failed to create external MCP tool: ${tool.name}`, toolCreationError);

package/dist/core/nativeGenerateLoop.d.ts

@@ -13,7 +13,64 @@
  * share this: the v3 result shape (`content` parts, `finishReason`, `usage`) is
  * the same across Anthropic, the OpenAI-compatible family and SageMaker.
  */
-import type { NativeGenerateLoopArgs, NativeGenerateLoopResult, ToolExecutionSummaryInternal } from "../types/index.js";
+import type { NativeGenerateLoopArgs, NativeGenerateLoopResult, StepResult, StepToolChoiceInput, Tool, ToolExecutionSummaryInternal } from "../types/index.js";
+/**
+ * Decide the tool choice for ONE step of a multi-step loop.
+ *
+ * A forced choice held on every step compels a tool call on every step, so
+ * the loop could only end when `maxSteps` ran out — which is exactly what
+ * happened before this existed. The rule: a forced choice applies while
+ * `step < toolChoiceSteps` (default 1), after which the model chooses
+ * (`"auto"`). `"auto"` and `"none"` pass through unchanged on every step.
+ *
+ * A `prepareStep` hook, when supplied, runs first and its `toolChoice` wins
+ * for the step — including a forced choice past `toolChoiceSteps`, which is
+ * how a caller forces a tool on step 3 only. A hook that returns no
+ * `toolChoice` defers to the rule. Nothing else on the hook's result is read.
+ *
+ * A hook that THROWS is logged and treated as "no override": the steps
+ * already billed are kept and the rule decides. An abort of the turn while
+ * the hook is pending is not a hook failure and is re-thrown. The two are
+ * told apart by the LOOP's signal, never by the error's name: a hook that
+ * rejects with its own `AbortError` (its policy service timed out) has
+ * failed, and must not end a turn the caller never cancelled.
+ */
+export declare function resolveStepToolChoice(input: StepToolChoiceInput): Promise<unknown>;
+/**
+ * Translate a NeuroLink-shape tool choice (`"auto"` / `"none"` /
+ * `"required"` / `{ type: "tool", toolName }`) into the v3 call-option
+ * OBJECT every `doGenerate` converter switches on. The bare strings were
+ * being handed straight to `doGenerate`; Anthropic's converter normalises
+ * them, but the OpenAI-compatible one reads `.type` off the value and
+ * silently dropped every string form. An already-object value passes
+ * through untouched.
+ */
+export declare const toV3ToolChoice: (choice: unknown) => Record<string, unknown> | undefined;
+/**
+ * The record of one completed step that `prepareStep` receives in `steps`.
+ * Built the same way by every native loop so a hook sees one shape.
+ */
+export declare const toPrepareStepRecord: (step: {
+    stepNumber: number;
+    content: Array<Record<string, unknown>>;
+    text: string;
+    toolCalls: Array<{
+        toolName: string;
+        toolCallId: string;
+        input: unknown;
+    }>;
+    toolResults: Array<{
+        toolName: string;
+        toolCallId: string;
+        output: unknown;
+    }>;
+    finishReason: string;
+    inputTokens: number;
+    outputTokens: number;
+    /** Prompt-cache tokens for the step, when the provider reports them. */
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+}) => StepResult<Record<string, Tool>>;
 /**
  * Narrow a model handle to the delegating shape this loop drives.
  * `LanguageModel` is a union that includes a bare string id, and a double

package/dist/core/nativeGenerateLoop.js

@@ -15,6 +15,221 @@
  */
 import { logger } from "../utils/logger.js";
 import { guardToolExecutor } from "./toolExecutionGuards.js";
+const DEFAULT_TOOL_CHOICE_STEPS = 1;
+/**
+ * A choice that compels a tool call: `"required"` or a named tool, in either
+ * the NeuroLink string/object shape or the v3 `{ type }` object shape.
+ * `"auto"` and `"none"` leave the model free (or forbidden) and are never
+ * time-limited.
+ */
+const isForcedToolChoice = (choice) => {
+    if (choice === "required") {
+        return true;
+    }
+    if (typeof choice === "object" && choice !== null) {
+        const type = choice.type;
+        return type === "required" || type === "tool" || type === "any";
+    }
+    return false;
+};
+/**
+ * `toolChoiceSteps` is a count of leading steps, so anything but a
+ * non-negative integer is meaningless. Fall back to the default with a WARN
+ * rather than throw: a bad knob should not fail a turn that would otherwise
+ * complete, but it must not be silent either.
+ */
+const normalizeToolChoiceSteps = (value) => {
+    if (value === undefined) {
+        return DEFAULT_TOOL_CHOICE_STEPS;
+    }
+    if (Number.isInteger(value) && value >= 0) {
+        return value;
+    }
+    logger.warn(`toolChoiceSteps must be a non-negative integer; got ${String(value)} — using ${DEFAULT_TOOL_CHOICE_STEPS}`);
+    return DEFAULT_TOOL_CHOICE_STEPS;
+};
+/**
+ * Fields of a `prepareStep` result that the former AI-SDK loop honoured and
+ * the native loops do not. Their presence is reported once per process: a
+ * hook written for the old loop that hides a destructive tool through
+ * `experimental_activeTools` would otherwise fail open in silence.
+ */
+const IGNORED_PREPARE_STEP_FIELDS = [
+    "model",
+    "activeTools",
+    "experimental_activeTools",
+];
+let warnedIgnoredPrepareStepFields = false;
+const warnIgnoredPrepareStepFields = (prepared) => {
+    if (warnedIgnoredPrepareStepFields ||
+        !prepared ||
+        typeof prepared !== "object") {
+        return;
+    }
+    const present = IGNORED_PREPARE_STEP_FIELDS.filter((field) => prepared[field] !== undefined);
+    if (present.length === 0) {
+        return;
+    }
+    warnedIgnoredPrepareStepFields = true;
+    logger.warn(`prepareStep returned ${present.join(", ")}, which the native loops ignore — only toolChoice is honoured. Use toolFilter / excludeTools for tool visibility and set the model on the request. (reported once)`);
+};
+/**
+ * Await the caller's hook without letting it outlive the turn: a hook that
+ * stalls (a remote policy service that never answers) parked the loop past
+ * every deadline, because nothing observed the abort signal while the hook
+ * was pending. An abort rejects with the signal's reason so the loop's
+ * cancellation path handles it like any other abort.
+ */
+const awaitPrepareStep = (pending, abortSignal) => {
+    if (!abortSignal) {
+        return Promise.resolve(pending);
+    }
+    if (abortSignal.aborted) {
+        // The hook has already been invoked. Its promise is abandoned here, so
+        // a rejection it settles with later must have a handler: without one it
+        // is an unhandled rejection, which terminates Node by default.
+        void Promise.resolve(pending).catch(() => undefined);
+        return Promise.reject(abortReason(abortSignal));
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(abortReason(abortSignal));
+        abortSignal.addEventListener("abort", onAbort, { once: true });
+        // Both handlers stay attached after an abort wins the race, so a hook
+        // that rejects afterwards is observed (the second `reject` is a no-op).
+        Promise.resolve(pending).then((value) => {
+            abortSignal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            abortSignal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+};
+const abortReason = (signal) => {
+    if (signal.reason instanceof Error) {
+        return signal.reason;
+    }
+    const error = new Error(typeof signal.reason === "string" ? signal.reason : "Request was aborted.");
+    error.name = "AbortError";
+    return error;
+};
+/**
+ * Decide the tool choice for ONE step of a multi-step loop.
+ *
+ * A forced choice held on every step compels a tool call on every step, so
+ * the loop could only end when `maxSteps` ran out — which is exactly what
+ * happened before this existed. The rule: a forced choice applies while
+ * `step < toolChoiceSteps` (default 1), after which the model chooses
+ * (`"auto"`). `"auto"` and `"none"` pass through unchanged on every step.
+ *
+ * A `prepareStep` hook, when supplied, runs first and its `toolChoice` wins
+ * for the step — including a forced choice past `toolChoiceSteps`, which is
+ * how a caller forces a tool on step 3 only. A hook that returns no
+ * `toolChoice` defers to the rule. Nothing else on the hook's result is read.
+ *
+ * A hook that THROWS is logged and treated as "no override": the steps
+ * already billed are kept and the rule decides. An abort of the turn while
+ * the hook is pending is not a hook failure and is re-thrown. The two are
+ * told apart by the LOOP's signal, never by the error's name: a hook that
+ * rejects with its own `AbortError` (its policy service timed out) has
+ * failed, and must not end a turn the caller never cancelled.
+ */
+export async function resolveStepToolChoice(input) {
+    if (input.prepareStep) {
+        let prepared;
+        try {
+            prepared = await awaitPrepareStep(input.prepareStep({
+                steps: input.steps,
+                stepNumber: input.step,
+                maxSteps: input.maxSteps,
+                model: input.model,
+            }), input.abortSignal);
+        }
+        catch (hookError) {
+            if (input.abortSignal?.aborted) {
+                throw abortReason(input.abortSignal);
+            }
+            logger.warn(`prepareStep threw at step ${input.step}; using the default tool choice for this step`, {
+                error: hookError instanceof Error ? hookError.message : String(hookError),
+            });
+            prepared = undefined;
+        }
+        warnIgnoredPrepareStepFields(prepared);
+        if (prepared?.toolChoice !== undefined) {
+            return prepared.toolChoice;
+        }
+    }
+    if (input.base === undefined) {
+        return undefined;
+    }
+    if (!isForcedToolChoice(input.base) ||
+        input.step < normalizeToolChoiceSteps(input.toolChoiceSteps)) {
+        return input.base;
+    }
+    return "auto";
+}
+/**
+ * Translate a NeuroLink-shape tool choice (`"auto"` / `"none"` /
+ * `"required"` / `{ type: "tool", toolName }`) into the v3 call-option
+ * OBJECT every `doGenerate` converter switches on. The bare strings were
+ * being handed straight to `doGenerate`; Anthropic's converter normalises
+ * them, but the OpenAI-compatible one reads `.type` off the value and
+ * silently dropped every string form. An already-object value passes
+ * through untouched.
+ */
+export const toV3ToolChoice = (choice) => {
+    if (choice === undefined || choice === null) {
+        return undefined;
+    }
+    if (typeof choice === "string") {
+        return choice === "auto" || choice === "none" || choice === "required"
+            ? { type: choice }
+            : undefined;
+    }
+    if (typeof choice === "object") {
+        return choice;
+    }
+    return undefined;
+};
+const KNOWN_FINISH_REASONS = new Set([
+    "stop",
+    "length",
+    "content-filter",
+    "tool-calls",
+    "error",
+    "other",
+]);
+const toFinishReason = (value) => KNOWN_FINISH_REASONS.has(value) ? value : "other";
+/**
+ * The record of one completed step that `prepareStep` receives in `steps`.
+ * Built the same way by every native loop so a hook sees one shape.
+ */
+export const toPrepareStepRecord = (step) => {
+    const hasCacheDetail = step.cacheReadTokens !== undefined || step.cacheWriteTokens !== undefined;
+    return {
+        stepNumber: step.stepNumber,
+        content: step.content,
+        text: step.text,
+        toolCalls: step.toolCalls,
+        toolResults: step.toolResults,
+        finishReason: toFinishReason(step.finishReason),
+        usage: {
+            inputTokens: step.inputTokens,
+            outputTokens: step.outputTokens,
+            totalTokens: step.inputTokens + step.outputTokens,
+            ...(hasCacheDetail
+                ? {
+                    inputTokenDetails: {
+                        noCacheTokens: step.inputTokens,
+                        cacheReadTokens: step.cacheReadTokens ?? 0,
+                        cacheWriteTokens: step.cacheWriteTokens ?? 0,
+                    },
+                    cachedInputTokens: step.cacheReadTokens ?? 0,
+                }
+                : {}),
+        },
+    };
+};
 /**
  * Narrow a model handle to the delegating shape this loop drives.
  * `LanguageModel` is a union that includes a bare string id, and a double
@@ -122,8 +337,29 @@ export async function runNativeGenerateLoop(args, toolExecutionSummaries) {
     // answer is that result — not a thrown turn.
     let preReask;
     const hasTools = Boolean(args.tools && args.tools.length > 0);
+    // Completed-step records for `prepareStep`; one per step that returned.
+    const stepRecords = [];
     for (let step = 0; step < args.maxSteps; step++) {
         steps = step + 1;
+        // The forced-choice window and the caller's hook are resolved BEFORE the
+        // re-ask override below: the re-ask has to win, since its whole point is
+        // a request with tools disabled.
+        // A request with no tools declares no tool_choice either: a hook that
+        // forces a tool on a tool-less request (the schema reformat pass starts
+        // every pass at step 0) would be a 400 on OpenAI-compatible backends.
+        const stepToolChoice = hasTools
+            ? await resolveStepToolChoice({
+                base: args.toolChoice,
+                step,
+                toolChoiceSteps: args.toolChoiceSteps,
+                prepareStep: args.prepareStep,
+                steps: stepRecords,
+                maxSteps: args.maxSteps,
+                model: args.modelId,
+                ...(args.abortSignal ? { abortSignal: args.abortSignal } : {}),
+            })
+            : undefined;
+        const wireToolChoice = toV3ToolChoice(stepToolChoice);
         // Per-step context reclaim. The pre-dispatch budget check runs ONCE and
         // never sees the assistant turns and tool results this loop appends, which
         // is how a long agentic run overflows the model window mid-loop and loses
@@ -145,11 +381,12 @@ export async function runNativeGenerateLoop(args, toolExecutionSummaries) {
             // bare string "none" type-checks against `unknown` and is then
             // dropped by every converter that switches on `choice.type`, so the
             // re-ask silently went out unchanged. Caught by the stand-in asserting
-            // the wire body, not by any live provider.
+            // the wire body, not by any live provider. The same applied to the
+            // caller's own string-form choice, hence `toV3ToolChoice` above.
             ...(reasked
                 ? { toolChoice: { type: "none" } }
-                : args.toolChoice !== undefined
-                    ? { toolChoice: args.toolChoice }
+                : wireToolChoice !== undefined
+                    ? { toolChoice: wireToolChoice }
                     : {}),
             ...(args.responseFormat
                 ? { responseFormat: args.responseFormat }
@@ -237,6 +474,39 @@ export async function runNativeGenerateLoop(args, toolExecutionSummaries) {
         cacheReadTokens += inShaped?.cacheRead ?? 0;
         cacheWriteTokens += inShaped?.cacheWrite ?? 0;
         const calls = parts.filter((p) => p.type === "tool-call");
+        const stepInputTokens = typeof inShaped?.noCache === "number"
+            ? inShaped.noCache
+            : readTotal(usage?.inputTokens);
+        const stepOutputTokens = readTotal(usage?.outputTokens);
+        // `input` is the PARSED object, as the stream loops record it: the v3
+        // part carries the raw JSON string, and a hook reading
+        // `steps.at(-1)?.toolCalls[0]?.input?.orderId` got undefined on
+        // generate() while the same hook worked on stream().
+        const stepToolCalls = calls.map((call) => ({
+            toolName: String(call.toolName ?? ""),
+            toolCallId: String(call.toolCallId ?? ""),
+            input: parseToolInput(call.input).input,
+        }));
+        // Pushed now with empty results and filled in below once the tools have
+        // run, so a hook consulted on the next step sees this step's outputs.
+        const stepRecord = toPrepareStepRecord({
+            stepNumber: step,
+            content: parts,
+            text,
+            toolCalls: stepToolCalls,
+            toolResults: [],
+            finishReason,
+            inputTokens: stepInputTokens,
+            outputTokens: stepOutputTokens,
+            ...(inShaped?.cacheRead !== undefined ||
+                inShaped?.cacheWrite !== undefined
+                ? {
+                    cacheReadTokens: inShaped?.cacheRead ?? 0,
+                    cacheWriteTokens: inShaped?.cacheWrite ?? 0,
+                }
+                : {}),
+        });
+        stepRecords.push(stepRecord);
         if (calls.length === 0) {
             // io.net's Llama endpoint ends a tool loop on `finish_reason:
             // tool_calls` carrying neither a tool call nor any text: the model's
@@ -287,6 +557,7 @@ export async function runNativeGenerateLoop(args, toolExecutionSummaries) {
             if (typeof tool?.execute !== "function") {
                 failure = `Tool not found: ${name}`;
                 output = { error: failure };
+                args.onRejectedToolCall?.(name, failure, id);
             }
             else if (rejection) {
                 // An error tool-result rather than a throw: the model gets to see what
@@ -294,6 +565,7 @@ export async function runNativeGenerateLoop(args, toolExecutionSummaries) {
                 // own validation did.
                 failure = `Tool ${name}: ${rejection}`;
                 output = { error: failure };
+                args.onRejectedToolCall?.(name, failure, id);
             }
             else {
                 try {
@@ -326,8 +598,10 @@ export async function runNativeGenerateLoop(args, toolExecutionSummaries) {
                 ...(failure ? { error: failure } : { output }),
                 startTime,
                 endTime: new Date(),
+                stepIndex: step,
             });
             resultParts.push({ type: "tool-result", toolCallId: id, output });
+            stepRecord.toolResults.push({ toolName: name, toolCallId: id, output });
         }
         args.conversation.push({ role: "tool", content: resultParts });
     }