@juspay/neurolink 12.47.13 → 12.48.0

package/dist/types/conversation.d.ts

@@ -44,12 +44,99 @@ export type { ModelMessage, SystemModelMessage, UserModelMessage, AssistantModel
  * uniqueness checks see.
  */
 export type StorageConfig = HippocampusStorageConfig;
+/**
+ * How stored `tool_call` / `tool_result` rows are replayed into the prompt
+ * on later turns of a session (see `ConversationMemoryConfig.replayToolSteps`).
+ *
+ * - `"full"`: replayed as real tool-call / tool-result turns, so the model
+ *   sees the exact call and its output.
+ * - `"marker"`: a compact text line per tool call
+ *   (`[called <tool> → ok]` / `[called <tool> → error]`) folded into the
+ *   assistant turn, so the model knows what it did without the payload.
+ * - `"off"`: tool rows are dropped from the prompt, as before this option.
+ */
+export type ToolReplayMode = "full" | "marker" | "off";
+/**
+ * The fields the tool-step replay reads off a stored history row. Structural
+ * rather than `ChatMessage` because the multimodal builder's history is typed
+ * as `{ role: string; content: string }` while carrying the same rows.
+ */
+export type ToolHistoryRow = {
+    /** Row id; a `repair-*` prefix marks a placeholder `repairToolPairs` invented. */
+    id?: string;
+    role: string;
+    content?: unknown;
+    tool?: string;
+    toolCallId?: string;
+    args?: Record<string, unknown>;
+    result?: {
+        success?: boolean;
+        error?: string;
+    };
+    metadata?: {
+        stepIndex?: number;
+        isSummary?: boolean;
+        isSkill?: boolean;
+    };
+};
+/**
+ * What a replayed step tells the model about the call's outcome: `"ok"`,
+ * `"error"` (the result was a failure — thrown, rejected, or an `isError`
+ * payload), or `"unknown"` when the real result was lost to compaction and
+ * `repairToolPairs` filled the gap with a placeholder.
+ */
+export type ToolReplayOutcome = "ok" | "error" | "unknown";
+/** One paired call/result from a session's history, ready to replay. */
+export type ToolReplayStep = {
+    callId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    output: string;
+    outcome: ToolReplayOutcome;
+};
+/**
+ * One tool call as handed to conversation-memory storage after a loop step.
+ * The stores read `args` (Redis also `arguments` / `parameters`), so the
+ * field is named for what they read — an `input` key here is silently
+ * persisted as `{}`, which is exactly the bug this type exists to prevent.
+ */
+export type MemoryToolCallRecord = {
+    toolCallId?: string;
+    toolName?: string;
+    args?: Record<string, unknown>;
+    /** Zero-based loop step, persisted as `metadata.stepIndex` by stores that keep it. */
+    stepIndex?: number;
+    /** Gemini 3 thought signature riding on the step's first call. */
+    thoughtSignature?: string;
+    timestamp?: Date;
+};
+/** One tool result as handed to conversation-memory storage after a loop step. */
+export type MemoryToolResultRecord = {
+    toolCallId?: string;
+    toolName?: string;
+    output?: unknown;
+    /** Legacy alias of `output`; stores read whichever is present. */
+    result?: unknown;
+    /** Set when the execution failed; persisted as `result.error` and `success: false`. */
+    error?: string;
+    stepIndex?: number;
+    timestamp?: Date;
+};
 /**
  * Configuration for conversation memory feature
  */
 export type ConversationMemoryConfig = {
     /** Enable conversation memory feature */
     enabled: boolean;
+    /**
+     * How a session's stored tool steps are replayed into later prompts.
+     * Default `"marker"`. `"full"` replays real tool-call / tool-result turns
+     * (costs tokens per replayed step and, on Anthropic, changes the prompt
+     * prefix ahead of the cached system breakpoint); `"off"` restores the
+     * previous behaviour of dropping them. Overridable per request via
+     * `replayToolSteps` on the generate / stream options.
+     */
+    replayToolSteps?: ToolReplayMode;
     /** Maximum number of sessions to keep in memory (default: 50) */
     maxSessions?: number;
     /** Enable automatic summarization */

package/dist/types/decision.d.ts

@@ -182,6 +182,56 @@ export type DecisionLimits = {
     }>>;
     /** What the provider accepts besides text. Absent means text only. */
     media?: DecisionMediaLimits;
+    /**
+     * True when these figures describe the provider's own server-side ceiling,
+     * published so callers can plan against it, and NeuroLink does NOT refuse
+     * locally — the server does, with its own `max_tokens_exceeded`. Absent or
+     * false means NeuroLink refuses an over-limit request before any network
+     * call. `NeuroLink.decisionLimits()` reports the distinction as
+     * `enforcedLocally`.
+     */
+    advisory?: boolean;
+};
+/**
+ * A provider's decision limits resolved for one model — the figure the
+ * pre-flight check compares against, flattened from a descriptor's
+ * `decisionLimits` with the per-model override applied.
+ *
+ * Returned by `NeuroLink.decisionLimits()` so a host extending NeuroLink's
+ * questions (see {@link DecisionHooks}) can size its additions before the
+ * call, instead of discovering the cap when the whole request is refused.
+ */
+export type DecisionLimitsReading = {
+    provider: string;
+    model: string;
+    maxStateTokens: number;
+    /**
+     * Absent when the provider caps a request by tokens (or bytes) rather
+     * than by question count — TypeSafe and XOR; `Infinity` is never used.
+     */
+    maxQuestions?: number;
+    nonAsciiTokensPerChar?: number;
+    /** Tokens charged per ASCII digit; see {@link DecisionLimits.digitTokensPerChar}. */
+    digitTokensPerChar?: number;
+    /** Tokens charged per ASCII punctuation/symbol; see {@link DecisionLimits.symbolTokensPerChar}. */
+    symbolTokensPerChar?: number;
+    /** Tokens charged per astral character; see {@link DecisionLimits.astralTokensPerChar}. */
+    astralTokensPerChar?: number;
+    /** What the provider accepts besides text; absent means text only. */
+    media?: DecisionMediaLimits;
+    /**
+     * Whether NeuroLink itself refuses an over-limit request before any network
+     * call (Laya), or merely reports the server's ceiling (TypeSafe).
+     */
+    enforcedLocally: boolean;
+};
+/** What `NeuroLink.decisionLimits()` accepts: the same selection `decide()` takes. */
+export type DecisionLimitsQuery = {
+    /** Provider name or alias; defaults to the configured decision provider. */
+    provider?: string;
+    /** Defaults to the provider's configured model, then its default model. */
+    model?: string;
+    credentials?: NeurolinkCredentials;
 };
 export type DecisionMediaLimits = {
     /** Most images one request may carry. */
@@ -287,6 +337,162 @@ export type DecisionOptions = DecisionRequest & {
     /** Per-call credential overrides, as `generate()` takes. */
     credentials?: NeurolinkCredentials;
 };
+/**
+ * The built-in consumers of the `decide` inference type — one name per place
+ * NeuroLink asks a decision model something on its own behalf. Each consumer
+ * stamps its request with its site, which is what lets a host's
+ * {@link DecisionHooks} tell the calls apart and lets telemetry attribute them.
+ *
+ * - `routing` — the classifier router (difficulty, capabilities, risk, model, context scope)
+ * - `toolRouting` — one yes/no per MCP server
+ * - `contextRelevance` — one yes/no per earlier message, compaction stage 0
+ * - `summaryGate` — accept or reject a generated summary, compaction stage 3
+ * - `ragPlan` — per-query retrieval plan (`RAGPipeline` only)
+ */
+export type DecisionSite = "routing" | "toolRouting" | "contextRelevance" | "summaryGate" | "ragPlan";
+/**
+ * Options an internal decision site hands its caller: the public
+ * {@link DecisionOptions} plus in-process context that never reaches the
+ * wire. A bound `NeuroLink.tryDecide` accepts it unchanged; a host wrapping
+ * one can read `site` to see which consumer is asking.
+ */
+export type DecisionCallerOptions = DecisionOptions & {
+    /** Which built-in consumer is asking. Unset on a host's own `tryDecide` call. */
+    site?: DecisionSite;
+    /** The conversation the outer request belongs to. Never sent to the model. */
+    sessionId?: string;
+    /** The outer request's id. Never sent to the model. */
+    requestId?: string;
+};
+/**
+ * What an internal decision site inherits from the `generate()` / `stream()`
+ * call it runs inside: the per-call credentials (so the decision goes to the
+ * caller's provider account, not the instance's), the abort signal, and the
+ * ids a host's {@link DecisionHooks} may want to correlate on.
+ */
+export type DecisionSiteContext = {
+    credentials?: NeurolinkCredentials;
+    signal?: AbortSignal;
+    sessionId?: string;
+    requestId?: string;
+};
+/** What a site call adds to its decision span beyond the request itself. */
+export type DecisionSiteAttributes = {
+    site: DecisionSite;
+    /** Questions a host's `extendQuestions` hook added; 0 without hooks. */
+    hostQuestionCount: number;
+};
+/**
+ * What a {@link DecisionHooks} callback sees before the call: the site, the
+ * state NeuroLink is about to send, and NeuroLink's own questions — as
+ * copies, so a hook that edits them cannot reach the wire request.
+ */
+export type DecisionHookContext = {
+    site: DecisionSite;
+    state: DecisionState;
+    /** NeuroLink's own questions for this site, keyed by its own ids. */
+    questions: DecisionQuestionMap;
+    sessionId?: string;
+    requestId?: string;
+};
+/** What `onAnswers` receives once the decision has returned. */
+export type DecisionHookAnswersContext = DecisionHookContext & {
+    /**
+     * The host's answers, keyed by the ids the host used in `extendQuestions`
+     * — the namespacing applied on the wire is undone here. Empty when the
+     * host added no questions.
+     */
+    answers: DecisionAnswerMap;
+    /** The whole result, including NeuroLink's own answers under its own ids. */
+    result: DecisionResult;
+};
+/**
+ * Ride along on the decision calls NeuroLink already makes.
+ *
+ * Latency on a decision model is flat in question count, so a host with its
+ * own yes/no or choice questions about the same request pays nothing to ask
+ * them in the round trip NeuroLink is making anyway — one request per
+ * {@link DecisionSite}, never a second. The host's questions are namespaced
+ * on the wire so they can never collide with NeuroLink's, capped so they can
+ * never push the request past the provider's question limit (which would
+ * refuse the whole call and degrade NeuroLink's own routing), and answered
+ * back under the host's original ids.
+ *
+ * Both hooks are fail-open: a hook that throws is logged and the decision
+ * proceeds with NeuroLink's own questions, and neither can change what
+ * NeuroLink does with its own answers — every value a hook or listener is
+ * handed is a copy. Without hooks, the decision payload (state and
+ * questions) is exactly what the consumer built; the outer request's
+ * per-call `credentials` are still forwarded, so the account and base URL
+ * on the wire can differ from the instance's. Hooks are inert without a
+ * decision provider: neither runs, and no event fires.
+ */
+export type DecisionHooks = {
+    /**
+     * Return extra questions to send with this site's call, or `undefined` to
+     * add none. An invalid question is dropped with a warning; questions past
+     * the provider's cap are dropped from the end, also with a warning.
+     */
+    extendQuestions?: (context: DecisionHookContext) => DecisionQuestionMap | undefined | Promise<DecisionQuestionMap | undefined>;
+    /**
+     * Called with the host's answers (under the host's ids) and the full result
+     * whenever a site call returns one. Observe-only: it receives a copy, so
+     * mutating it cannot reach the answers NeuroLink's own consumer reads.
+     */
+    onAnswers?: (context: DecisionHookAnswersContext) => void | Promise<void>;
+    /**
+     * Upper bound, in milliseconds, on each hook call. Both hooks sit on the
+     * request path (routing, tool routing, compaction, RAG planning), so a
+     * hook that hangs would stall the turn; past this bound the call proceeds
+     * as if the hook had returned nothing, with a warning. Default 2000. Must
+     * be a finite number from 1 to {@link MAX_DECISION_HOOK_TIMEOUT_MS};
+     * anything else (including `Infinity`) falls back to the default with one
+     * warning, since a timer given such a delay fires immediately.
+     */
+    hookTimeoutMs?: number;
+};
+/** Default bound on a `DecisionHooks` callback, in milliseconds. */
+export declare const DEFAULT_DECISION_HOOK_TIMEOUT_MS = 2000;
+/**
+ * Largest `hookTimeoutMs` a timer honours (2^31 − 1 ms, about 24.8 days).
+ * A delay past it — or `Infinity`, `NaN`, 0, a negative — fires at once,
+ * so such a value falls back to the default instead of timing every hook
+ * out immediately.
+ */
+export declare const MAX_DECISION_HOOK_TIMEOUT_MS = 2147483647;
+/**
+ * Payload of the `decision:before` event, emitted once per site call. `state`
+ * and `questions` are copies: a listener that edits them changes neither
+ * the request on the wire nor the consumer's own question objects.
+ */
+export type DecisionBeforeEvent = {
+    site: DecisionSite;
+    state: DecisionState;
+    /** Everything about to be sent, NeuroLink's own questions plus the host's (namespaced). */
+    questions: DecisionQuestionMap;
+    hostQuestionCount: number;
+    sessionId?: string;
+    requestId?: string;
+};
+/**
+ * Payload of the `decision:after` event, emitted once per site call whether
+ * or not it produced a result — a decision path that stopped working must
+ * stay observable. `result` is null when an emitted call failed; with no
+ * decision provider configured, no event fires at all.
+ */
+export type DecisionAfterEvent = {
+    site: DecisionSite;
+    /** NeuroLink's own answers, under its own ids. Empty when `result` is null. */
+    answers: DecisionAnswerMap;
+    /** The host's answers, under the host's original ids. Empty when `result` is null. */
+    hostAnswers: DecisionAnswerMap;
+    latencyMs: number;
+    provider?: string;
+    model?: string;
+    result: DecisionResult | null;
+    sessionId?: string;
+    requestId?: string;
+};
 /**
  * Injected fail-open decision caller — typically a bound `NeuroLink.tryDecide`,
  * which returns `null` on any failure rather than throwing.
@@ -297,8 +503,11 @@ export type DecisionOptions = DecisionRequest & {
  * makes "no decision provider configured" indistinguishable from "the call
  * failed" at every call site: both are `null`, and both mean *carry on as
  * before*.
+ *
+ * The options carry a {@link DecisionSite} stamp; a bound `tryDecide` routes
+ * a stamped request through the host's {@link DecisionHooks}.
  */
-export type DecisionCallerFn = (options: DecisionOptions) => Promise<DecisionResult | null>;
+export type DecisionCallerFn = (options: DecisionCallerOptions) => Promise<DecisionResult | null>;
 /**
  * Shared gate for acting on a yes/no answer.
  *

package/dist/types/decision.js

@@ -18,4 +18,12 @@
  * `src/lib/types/` (CLAUDE.md rule 9). Note `evaluate`/`Evaluation*` is a
  * different, unrelated feature — scoring a generated response with RAGAS.
  */
-export {};
+/** Default bound on a `DecisionHooks` callback, in milliseconds. */
+export const DEFAULT_DECISION_HOOK_TIMEOUT_MS = 2000;
+/**
+ * Largest `hookTimeoutMs` a timer honours (2^31 − 1 ms, about 24.8 days).
+ * A delay past it — or `Infinity`, `NaN`, 0, a negative — fires at once,
+ * so such a value falls back to the default instead of timing every hook
+ * out immediately.
+ */
+export const MAX_DECISION_HOOK_TIMEOUT_MS = 2_147_483_647;

package/dist/types/dispatch.d.ts

@@ -3,6 +3,7 @@
  * the single function that decides which of NeuroLink's output modes a
  * generate/stream request is asking for.
  */
+import type { TTSSynthesisMode } from "./tts.js";
 export type RequestKind = "text" | "image" | "video" | "music" | "avatar" | "tts-direct" | "ppt";
 /**
  * Narrow structural subset of TextGenerationOptions/GenerateOptions that
@@ -15,8 +16,14 @@ export type RequestKindInput = {
         mode?: string;
         format?: string;
     };
-    tts?: {
-        enabled?: boolean;
-        useAiResponse?: boolean;
-    };
+    tts?: RequestKindTTSInput;
+};
+/**
+ * The two `tts` fields that decide between direct synthesis and synthesizing
+ * the model's reply. `mode` wins; `useAiResponse` is the legacy spelling.
+ */
+export type RequestKindTTSInput = {
+    enabled?: boolean;
+    mode?: TTSSynthesisMode;
+    useAiResponse?: boolean;
 };

package/dist/types/generate.d.ts

@@ -7,12 +7,13 @@ import type { ClaudeLimitSnapshot } from "./subscription.js";
 import type { JsonValue } from "./common.js";
 import type { TerminalAgentModeOption, TerminalAgentModeVersion } from "./agentMode.js";
 import type { Content, ImageWithAltText } from "./content.js";
-import type { ChatMessage, ConversationMemoryConfig } from "./conversation.js";
+import type { ChatMessage, ConversationMemoryConfig, ToolReplayMode } from "./conversation.js";
+import type { MemoryCallOptions } from "./memory.js";
 import type { EvaluationData } from "./evaluation.js";
 import type { MiddlewareFactoryOptions, OnFinishCallback, OnErrorCallback } from "./middleware.js";
 import type { DirectorModeOptions, DirectorSegment, VideoGenerationResult, VideoOutputOptions } from "./multimodal.js";
 import type { PPTGenerationResult, PPTOutputOptions } from "./ppt.js";
-import type { TTSOptions, TTSResult } from "./tts.js";
+import type { TTSOptions, TTSResult, TTSSynthesisMode } from "./tts.js";
 import type { STTOptions, STTResult } from "./stt.js";
 import type { AvatarOptions, AvatarResult } from "./avatar.js";
 import type { MusicOptions, MusicResult } from "./music.js";
@@ -577,23 +578,48 @@ export type GenerateOptions = {
      * - `"required"`: the model must call at least one tool
      * - `{ type: "tool", toolName: string }`: the model must call the specified tool
      *
-     * Note: When used without `prepareStep`, this applies to **every step** in the
-     * `maxSteps` loop. Using `"required"` or `{ type: "tool" }` without `prepareStep`
-     * will cause infinite tool calls until `maxSteps` is exhausted.
+     * A forced choice (`"required"` or a named tool) is applied only to the
+     * first `toolChoiceSteps` steps of the `maxSteps` loop (default 1) and the
+     * model is then free to answer. Holding a forced choice on every step would
+     * compel a tool call on every step, and the loop would only end when
+     * `maxSteps` ran out. `"auto"` and `"none"` are applied unchanged on every
+     * step. Vertex, Google AI Studio and Bedrock do not honour `toolChoice`.
      */
     toolChoice?: ToolChoice<Record<string, Tool>>;
+    /**
+     * How many leading steps a forced `toolChoice` (`"required"` or a named
+     * tool) stays in force; from that step on the model chooses (`"auto"`).
+     * A non-negative integer, default 1. `0` never forces. Ignored for
+     * `"auto"` and `"none"`. A `prepareStep` result that names a `toolChoice`
+     * overrides this for that step.
+     */
+    toolChoiceSteps?: number;
+    /**
+     * How this request replays the session's stored tool steps
+     * (`tool_call` / `tool_result` rows in `conversationMessages`) into the
+     * prompt: `"full"` (real tool-call / tool-result turns), `"marker"` (a
+     * compact `[called <tool> → ok]` line per call, the default) or `"off"`.
+     * Overrides `conversationMemory.replayToolSteps` for this request.
+     */
+    replayToolSteps?: ToolReplayMode;
     /**
      * Optional callback that runs before each step in a multi-step generation.
-     * Allows dynamically changing `toolChoice` and available tools per step.
      *
-     * This is the recommended way to enforce specific tool calls on certain steps
-     * while allowing the model freedom on others.
+     * Honoured field of the result: `toolChoice`, applied to that step only
+     * and taking precedence over `toolChoice` / `toolChoiceSteps`.
+     *
+     * Not honoured — accepted for source compatibility with the former Vercel
+     * AI SDK `experimental_prepareStep` shape, but ignored by every native
+     * loop: `model` (the turn's model cannot change mid-loop) and
+     * `experimental_activeTools` (tool visibility is fixed for the turn; use
+     * `toolFilter` / `excludeTools` instead).
      *
-     * Maps to Vercel AI SDK's `experimental_prepareStep`.
+     * `steps` carries one record per completed step (content, text, tool calls,
+     * tool results, finish reason, usage); `model` is the resolved model id.
      *
      * @example Force a specific tool on step 0, then switch to auto:
      * ```typescript
-     * prepareStep: ({ stepNumber, steps }) => {
+     * prepareStep: async ({ stepNumber }) => {
      *   if (stepNumber === 0) {
      *     return {
      *       toolChoice: { type: 'tool', toolName: 'myTool' }
@@ -602,8 +628,6 @@ export type GenerateOptions = {
      *   return { toolChoice: 'auto' };
      * }
      * ```
-     *
-     * @see https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#parameters
      */
     prepareStep?: (options: {
         steps: StepResult<Record<string, Tool>>[];
@@ -761,22 +785,9 @@ export type GenerateOptions = {
      * Override the global memory SDK behavior for this specific call.
      * All flags default to `true` when the global memory SDK is enabled.
      * If the global memory SDK is disabled, these flags have no effect.
-     *
+     * Shared with `StreamOptions` — see `MemoryCallOptions`.
      */
-    memory?: {
-        /** Master toggle for this call. When false, both read and write are skipped. Defaults to true. */
-        enabled?: boolean;
-        /** Whether to read condensed memory and prepend to prompt. Defaults to true. */
-        read?: boolean;
-        /** Whether to write (add/condense) the conversation into memory after completion. Defaults to true. */
-        write?: boolean;
-        /**
-         * Additional users whose memory should be retrieved/stored alongside the primary user.
-         * Each entry can override the condensation prompt and maxWords for that user.
-         * Primary user is still determined by context.userId.
-         */
-        additionalUsers?: AdditionalMemoryUser[];
-    };
+    memory?: MemoryCallOptions;
     /**
      * PII detection — scans and optionally redacts PII from input before the LLM call.
      * @example { enabled: true, action: "redact", detectTypes: ["ssn", "email"] }
@@ -847,7 +858,11 @@ export type AdditionalMemoryUser = {
     read?: boolean;
     /** Whether to write conversation into this user's memory. Defaults to true. */
     write?: boolean;
-    /** Custom condensation prompt for this user. Overrides the default Hippocampus prompt. */
+    /**
+     * Custom condensation prompt for this user. Overrides the instance prompt.
+     * Must contain `{{OLD_MEMORY}}` and `{{NEW_CONTENT}}`; a template missing
+     * either is logged and this owner falls back to the instance prompt.
+     */
     prompt?: string;
     /** Max words for this user's condensed memory. Overrides the default maxWords. */
     maxWords?: number;
@@ -1359,33 +1374,19 @@ export type TextGenerationOptions = {
      * - `"required"`: the model must call at least one tool
      * - `{ type: "tool", toolName: string }`: the model must call the specified tool
      *
-     * Note: When used without `prepareStep`, this applies to **every step** in the
-     * `maxSteps` loop. Using `"required"` or `{ type: "tool" }` without `prepareStep`
-     * will cause infinite tool calls until `maxSteps` is exhausted.
+     * A forced choice is applied only to the first `toolChoiceSteps` steps
+     * (default 1); see GenerateOptions.toolChoice.
      */
     toolChoice?: ToolChoice<Record<string, Tool>>;
+    /** Leading steps a forced `toolChoice` stays in force (default 1). See GenerateOptions.toolChoiceSteps. */
+    toolChoiceSteps?: number;
+    /** How stored tool steps are replayed into the prompt. See GenerateOptions.replayToolSteps. */
+    replayToolSteps?: ToolReplayMode;
     /**
      * Optional callback that runs before each step in a multi-step generation.
-     * Allows dynamically changing `toolChoice` and available tools per step.
-     *
-     * This is the recommended way to enforce specific tool calls on certain steps
-     * while allowing the model freedom on others.
-     *
-     * Maps to Vercel AI SDK's `experimental_prepareStep`.
-     *
-     * @example Force a specific tool on step 0, then switch to auto:
-     * ```typescript
-     * prepareStep: ({ stepNumber, steps }) => {
-     *   if (stepNumber === 0) {
-     *     return {
-     *       toolChoice: { type: 'tool', toolName: 'myTool' }
-     *     };
-     *   }
-     *   return { toolChoice: 'auto' };
-     * }
-     * ```
-     *
-     * @see https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text#parameters
+     * Only a returned `toolChoice` is honoured (for that step); `model` and
+     * `experimental_activeTools` are accepted but ignored. See
+     * GenerateOptions.prepareStep.
      */
     prepareStep?: (options: {
         steps: StepResult<Record<string, Tool>>[];
@@ -1400,9 +1401,19 @@ export type TextGenerationOptions = {
     /**
      * Text-to-Speech (TTS) configuration
      *
-     * Enable audio generation from text. Behavior depends on useAiResponse flag:
-     * - When useAiResponse is false/undefined (default): TTS synthesizes the input text directly
-     * - When useAiResponse is true: TTS synthesizes the AI-generated response
+     * Enable audio generation from text. Behavior depends on `tts.mode`
+     * (explicit) or the legacy `useAiResponse` flag:
+     * - `mode: "direct"` / useAiResponse false or undefined (default): TTS
+     *   synthesizes the input text directly, with no LLM call — `usage` is
+     *   zero and `content` echoes the input. A direct request that also
+     *   carries LLM-shaped options (tools, systemPrompt, messages, schema,
+     *   conversationMemory) logs a warning, since those options have no effect
+     *   in this mode.
+     * - `mode: "response"` / useAiResponse true: TTS synthesizes the
+     *   AI-generated response after generation completes.
+     *
+     * `result.ttsMetadata.mode` reports which one ran. Set `tts.sanitize` to
+     * strip markdown, URLs and emoji before synthesis.
      *
      * @example Using input text (default)
      * ```typescript
@@ -1714,6 +1725,12 @@ export type TTSMetadata = {
     attempted: boolean;
     /** Whether TTS synthesis completed successfully. */
     success: boolean;
+    /**
+     * What was synthesized: the input text (`"direct"`) or the model's reply
+     * (`"response"`). Set by `generate()`; `stream()` always synthesizes the
+     * response and reports `"response"` where it records metadata.
+     */
+    mode?: TTSSynthesisMode;
     /** Structured synthesis error details, present only when synthesis failed. */
     error?: {
         code: string;
@@ -1747,6 +1764,40 @@ export type ModelAliasConfig = {
 export type GenerateOptionsNormalized = GenerateOptions & {
     input: NonNullable<GenerateOptions["input"]>;
 };
+/**
+ * The per-step hook shape every native loop calls: the narrowest common form
+ * of the `prepareStep` callbacks declared on GenerateOptions, StreamOptions
+ * and TextGenerationOptions, each of which is assignable to it. The loops
+ * read only `toolChoice` off the result.
+ */
+export type NativeLoopPrepareStep = (options: {
+    steps: StepResult<Record<string, Tool>>[];
+    stepNumber: number;
+    maxSteps: number;
+    model: LanguageModel;
+}) => PromiseLike<{
+    toolChoice?: ToolChoice<Record<string, Tool>>;
+} | undefined>;
+/**
+ * What `resolveStepToolChoice` needs to decide one step's tool choice.
+ * Shared by the native generate loop and both stream loops so the
+ * `toolChoiceSteps` / `prepareStep` rule cannot drift between them.
+ */
+export type StepToolChoiceInput = {
+    /** The turn's resolved tool choice in NeuroLink shape, or undefined. */
+    base: unknown;
+    /** Zero-based step index. */
+    step: number;
+    toolChoiceSteps?: number;
+    prepareStep?: NativeLoopPrepareStep;
+    /** Records of the steps completed so far, handed to `prepareStep`. */
+    steps: StepResult<Record<string, Tool>>[];
+    maxSteps: number;
+    /** The resolved model id (always a string at runtime), handed to `prepareStep`. */
+    model: string;
+    /** The turn's abort signal; a pending `prepareStep` is released when it fires. */
+    abortSignal?: AbortSignal;
+};
 /**
  * Inputs to the shared native generate loop (`core/nativeGenerateLoop.ts`).
  * One loop serves every provider whose delegating model exposes a v3-shaped
@@ -1769,7 +1820,14 @@ export type NativeGenerateLoopArgs = {
     tools?: Array<Record<string, unknown>>;
     /** Registered tools, used to execute a call the model asks for. */
     toolsRecord: Record<string, unknown>;
+    /** The turn's resolved tool choice, applied per step via `resolveStepToolChoice`. */
     toolChoice?: unknown;
+    /** Leading steps a forced `toolChoice` stays in force (default 1). */
+    toolChoiceSteps?: number;
+    /** Caller's per-step hook; only its `toolChoice` is honoured. */
+    prepareStep?: NativeLoopPrepareStep;
+    /** Resolved model id, handed to `prepareStep` as its `model` argument. */
+    modelId: string;
     responseFormat?: Record<string, unknown>;
     providerOptions?: Record<string, Record<string, unknown>>;
     maxSteps: number;
@@ -1780,6 +1838,12 @@ export type NativeGenerateLoopArgs = {
     toolTimeoutMs?: number | null;
     /** Wraps one step: retry ladder plus provider error classification. */
     runStep: (call: () => Promise<Record<string, unknown>>) => Promise<Record<string, unknown>>;
+    /**
+     * Called for a tool call the loop rejects before any execute runs (unknown
+     * tool, arguments the schema rejected), so the provider can emit the
+     * `tool:start` / `tool:end` pair no executor will.
+     */
+    onRejectedToolCall?: (toolName: string, error: string, toolCallId: string) => void;
 };
 export type NativeGenerateLoopResult = {
     text: string;

package/dist/types/loopEngine.d.ts

@@ -187,7 +187,12 @@ export type AgenticLoopAdapter<TConversation = unknown, TRaw = unknown> = {
     readonly resolveToolOnMiss?: (name: string) => {
         execute: (args: Record<string, unknown>, opts: unknown) => Promise<unknown>;
     } | undefined;
-    buildStepRequest(conversation: TConversation, step: number): AgenticLoopStepRequest;
+    /**
+     * May return a promise: an adapter that consults a caller's `prepareStep`
+     * hook for the step's tool choice has to await it before it can build the
+     * request. The engine awaits the result either way.
+     */
+    buildStepRequest(conversation: TConversation, step: number): AgenticLoopStepRequest | Promise<AgenticLoopStepRequest>;
     executeStep(request: AgenticLoopStepRequest, channel: {
         push(chunk: AgenticLoopChunk): void;
     }, signal: AbortSignal): Promise<AgenticLoopStepResult<TRaw>>;
@@ -255,7 +260,7 @@ export type AnthropicLoopAdapterConfig<TMessage = Anthropic.Messages.MessagePara
      * type carries `stream?: boolean` fails to match `stream: true` for a field
      * the adapter is about to overwrite.
      */
-    buildParams: (conversation: TMessage[], step: number) => Anthropic.Messages.MessageCreateParamsNonStreaming;
+    buildParams: (conversation: TMessage[], step: number) => Anthropic.Messages.MessageCreateParamsNonStreaming | Promise<Anthropic.Messages.MessageCreateParamsNonStreaming>;
     /** The turn's live tool record, used for deferred-catalog resolution. */
     toolsRecord: Record<string, Tool>;
     /**