@juspay/neurolink 12.47.14 → 12.48.0

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>;
     /**

package/dist/types/memory.d.ts

@@ -19,6 +19,9 @@
  *    re-export) keep their original public names — only their definitions
  *    move from `import("@juspay/hippocampus").Foo` to local structural form.
  */
+import type { TokenUsage } from "./analytics.js";
+import type { AdditionalMemoryUser } from "./generate.js";
+import type { NeurolinkCredentials } from "./providers.js";
 export type MemorySqliteStorageConfig = {
     type: "sqlite";
     /** Path to SQLite file. Default: ./data/hippocampus.sqlite */
@@ -56,17 +59,159 @@ export type HippocampusAddOptions = {
     prompt?: string;
     maxWords?: number;
 };
+/**
+ * The exact request shape Hippocampus's condenser sends to `generate()`
+ * (`@juspay/hippocampus` `src/client.ts`, the `neurolink.generate({...})`
+ * call inside `add()`). A full `NeuroLink` instance satisfies this
+ * structurally; so does any host object that can answer a plain text prompt.
+ */
+export type HippocampusCondenserGenerateOptions = {
+    input: {
+        text: string;
+    };
+    provider?: string;
+    model?: string;
+    temperature?: number;
+    disableTools?: boolean;
+};
+/** The only field Hippocampus reads back from the condensation call. */
+export type HippocampusCondenserResult = {
+    content?: string;
+};
+/**
+ * Minimal `generate()`-bearing object Hippocampus can use for condensation
+ * instead of constructing its own bare `new NeuroLink()`.
+ */
+export type HippocampusNeurolinkLike = {
+    generate: (options: HippocampusCondenserGenerateOptions) => Promise<HippocampusCondenserResult>;
+};
+/**
+ * Condenser settings forwarded to Hippocampus.
+ *
+ * `provider` / `model` / `temperature` select the condensation model.
+ * `credentials` and `instance` are read by `@juspay/hippocampus` ≥0.2.0;
+ * the peer floor is 0.2.1, which also substitutes the condensation
+ * placeholders literally (user content containing `$&` no longer corrupts
+ * the prompt). NeuroLink always fills `instance` itself — a dedicated
+ * child instance that carries this instance's `credentials` — unless the
+ * host supplies one, so condensation stops depending on provider keys being
+ * present in `process.env`.
+ */
+export type HippocampusNeurolinkConfig = {
+    provider?: string;
+    model?: string;
+    temperature?: number;
+    /**
+     * Credentials for the condenser's own NeuroLink instance. Defaults to the
+     * parent `new NeuroLink({ credentials })` value.
+     */
+    credentials?: NeurolinkCredentials;
+    /**
+     * Host-managed condenser. When set, NeuroLink does not build a child
+     * instance and passes this object through untouched.
+     */
+    instance?: HippocampusNeurolinkLike;
+};
 /** Constructor config accepted by the Hippocampus class. */
 export type HippocampusConfig = {
     storage?: HippocampusStorageConfig;
     prompt?: string;
-    neurolink?: {
-        provider?: string;
-        model?: string;
-        temperature?: number;
-    };
+    neurolink?: HippocampusNeurolinkConfig;
     maxWords?: number;
 };
+/**
+ * One completed turn as seen by the memory write hooks. `usage`,
+ * `finishReason` and `toolsUsed` are best-effort: the generate path has the
+ * full result, the stream path only knows the provider, the accumulated
+ * text and this request's own stream result's tool names.
+ */
+export type MemoryTurn = {
+    /** The caller's original prompt, before memory context was prepended. */
+    prompt: string;
+    /** The assistant's final text, trimmed. */
+    response: string;
+    /** Primary memory owner — `context.userId`. */
+    userId: string;
+    /** `context.sessionId`, when the call carried one. */
+    sessionId?: string;
+    provider?: string;
+    model?: string;
+    /** Names of tools that ran during the turn. */
+    toolsUsed?: string[];
+    /** Token usage — generate path only. */
+    usage?: TokenUsage;
+    /** Provider finish reason — generate path only. */
+    finishReason?: string;
+};
+/**
+ * Gate that decides whether a turn is written to memory at all. Runs inside
+ * the deferred background write, never on the response path. Returning
+ * `false` skips every `add()` for the turn (primary owner and
+ * `additionalUsers`). A thrown error is logged and treated as `false`.
+ */
+export type MemoryShouldWriteHook = (turn: MemoryTurn) => boolean | Promise<boolean>;
+/**
+ * Transform (or veto) the exact text handed to `Hippocampus.add()`. Receives
+ * the default `"User: …\nAssistant: …"` rendering; return a replacement
+ * string, or `null` to skip the write. A thrown error is logged and the
+ * write is skipped — a missed memory is recoverable, a polluted condensed
+ * summary is not.
+ */
+export type MemoryBeforeStoreHook = (content: string, turn: MemoryTurn) => string | null | Promise<string | null>;
+/**
+ * Write-side hooks accepted both per call (`generate({ memory })` /
+ * `stream({ memory })`) and on the instance
+ * (`conversationMemory.memory`). When both are set for the same hook, the
+ * per-call one wins for that call.
+ */
+export type MemoryWriteHooks = {
+    shouldWrite?: MemoryShouldWriteHook;
+    onBeforeStore?: MemoryBeforeStoreHook;
+};
+/**
+ * Per-call `memory` block shared by `GenerateOptions` and `StreamOptions`.
+ *
+ * Overrides the instance-level memory behaviour for one call. All flags
+ * default to `true` when the instance memory SDK is enabled; when it is
+ * disabled this block has no effect.
+ */
+export type MemoryCallOptions = MemoryWriteHooks & {
+    /** 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[];
+    /**
+     * Condensation prompt for the primary owner on this call. Precedence:
+     * per-call > instance `conversationMemory.memory.prompt` > Hippocampus
+     * default. Must contain `{{OLD_MEMORY}}` and `{{NEW_CONTENT}}`; a template
+     * missing either is logged and the instance prompt is used instead. An
+     * empty or whitespace-only string counts as unset.
+     */
+    prompt?: string;
+    /** Max words for the primary owner's condensed memory on this call. */
+    maxWords?: number;
+};
+/** Placeholder names a condensation prompt template can carry. */
+export type CondensationPlaceholder = "OLD_MEMORY" | "NEW_CONTENT" | "MAX_WORDS";
+/**
+ * Result of `validateCondensationPrompt()`. `missing` lists every absent
+ * placeholder; `fatal` is the subset whose absence breaks memory
+ * (`OLD_MEMORY`: each turn overwrites the summary; `NEW_CONTENT`: memory
+ * never grows). A missing `MAX_WORDS` only loses the word cap.
+ */
+export type CondensationPromptValidation = {
+    valid: boolean;
+    missing: CondensationPlaceholder[];
+    fatal: CondensationPlaceholder[];
+};
 /**
  * Subset of the @juspay/hippocampus client surface that NeuroLink core
  * actually calls. Defining this locally lets the initializer / SDK code
@@ -78,13 +223,36 @@ export type HippocampusLike = {
     delete: (ownerId: string) => Promise<void>;
     close: () => Promise<void>;
 };
+/** Builds a Hippocampus-compatible client from the config NeuroLink assembled. */
+export type HippocampusClientFactory = (config: HippocampusConfig) => HippocampusLike;
 /**
- * Consumer-facing memory config. Same shape as before — the `enabled`
- * flag toggles activation while the rest is passed straight through to
- * the Hippocampus constructor when the optional package is installed.
+ * Consumer-facing memory config. The `enabled` flag toggles activation; the
+ * `HippocampusConfig` part is passed to the Hippocampus constructor when the
+ * optional package is installed. The remaining fields are NeuroLink-side and
+ * never reach Hippocampus.
  */
-export type HippocampusMemory = HippocampusConfig & {
+export type HippocampusMemory = HippocampusConfig & MemoryWriteHooks & {
     enabled?: boolean;
+    /**
+     * Host-managed Hippocampus client (or any object with the same
+     * `add/get/delete/close` surface). When set, NeuroLink skips loading and
+     * constructing `@juspay/hippocampus` and uses this instance directly.
+     * `add()` and `get()` are what core calls and must both be functions;
+     * a client missing either disables memory with an `error` log.
+     *
+     * As a factory it receives the `HippocampusConfig` NeuroLink assembled —
+     * including the credentialed condenser under `neurolink.instance` — so a
+     * host can construct its own client (a subclass, a different version, a
+     * test double) from exactly what `new Hippocampus(config)` would get.
+     */
+    client?: HippocampusLike | HippocampusClientFactory;
+    /**
+     * When true, a condensation prompt template (instance `prompt` or
+     * `HC_CONDENSATION_PROMPT`) missing `{{OLD_MEMORY}}` or `{{NEW_CONTENT}}`
+     * makes the constructor throw instead of the default disable-and-log
+     * (at `error`). An empty or whitespace-only template counts as unset.
+     */
+    strictPrompt?: boolean;
 };
 /**
  * Shape of the dynamically-required `@juspay/hippocampus` module surface

package/dist/types/openaiCompatible.d.ts

@@ -1,8 +1,9 @@
-import type { DeferredUsage, NeuroLinkEvents, TypedEventEmitter } from "./common.js";
+import type { DeferredUsage } from "./common.js";
 import type { JSONSchema7 } from "./middleware.js";
 import type { LanguageModelV3, LanguageModelV3CallOptions } from "./middleware.js";
 import type { StreamOptions } from "./stream.js";
 import type { Tool } from "./tools.js";
+import type { StepResult } from "./providers.js";
 export type OpenAICompatChatRole = "system" | "user" | "assistant" | "tool";
 export type OpenAICompatTextContent = {
     type: "text";
@@ -223,6 +224,8 @@ export type ToolExecutionSummaryInternal = {
     error?: string;
     startTime: Date;
     endTime: Date;
+    /** Zero-based loop step that ran this tool, when the loop tracks one. */
+    stepIndex?: number;
 };
 export type StreamLoopArgs = {
     maxSteps: number;
@@ -233,11 +236,16 @@ export type StreamLoopArgs = {
     options: StreamOptions;
     conversation: OpenAICompatChatMessage[];
     openAITools: OpenAICompatChatTool[] | undefined;
-    openAIToolChoice: OpenAICompatToolChoiceWire | undefined;
+    /**
+     * The wire `tool_choice` for one step. A function rather than a value
+     * because a forced choice applies only to the first `toolChoiceSteps`
+     * steps, and a caller's `prepareStep` hook may override it per step;
+     * `steps` is the record of the steps completed so far, handed to that hook.
+     */
+    stepToolChoice: (step: number, steps: StepResult<Record<string, Tool>>[]) => Promise<OpenAICompatToolChoiceWire | undefined>;
     toolsRecord: Record<string, Tool>;
     /** Wire → registered tool-name map when sanitization was needed (see buildWireToolNameMaps). */
     toolNameFromWire?: Map<string, string>;
-    emitter: TypedEventEmitter<NeuroLinkEvents> | undefined;
     toolsUsed: string[];
     toolExecutionSummaries: ToolExecutionSummaryInternal[];
     pushChunk: (chunk: OpenAICompatStreamChunk) => void;

package/dist/types/stream.d.ts

@@ -9,9 +9,10 @@ import type { TokenUsage } from "./analytics.js";
 import type { JsonValue, UnknownRecord } from "./common.js";
 import type { TerminalAgentModeOption, TerminalAgentModeVersion } from "./agentMode.js";
 import type { Content, ImageWithAltText } from "./content.js";
-import type { ChatMessage } from "./conversation.js";
+import type { ChatMessage, ToolReplayMode } from "./conversation.js";
 import type { StreamNoOutputSentinel } from "./noOutputSentinel.js";
-import type { AdditionalMemoryUser, GenerateStopReason, TTSMetadata, ToolExecutionCaptureOptions } from "./generate.js";
+import type { GenerateStopReason, TTSMetadata, ToolExecutionCaptureOptions } from "./generate.js";
+import type { MemoryCallOptions } from "./memory.js";
 import type { AIModelProviderConfig, NeurolinkCredentials } from "./providers.js";
 import type { TTSChunk, TTSOptions, TTSResult } from "./tts.js";
 import type { STTOptions, STTResult } from "./stt.js";
@@ -580,10 +581,18 @@ export type StreamOptions = {
     /**
      * Tool choice configuration for streaming generation.
      * Mirrors generate() so translated/fallback requests can preserve forced tool use.
+     * A forced choice (`"required"` or a named tool) 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 stream step in a multi-step generation.
+     * Only a returned `toolChoice` is honoured (for that step); `activeTools` is
+     * accepted but ignored. See GenerateOptions.prepareStep.
      */
     prepareStep?: (options: {
         steps: StepResult<Record<string, Tool>>[];
@@ -739,21 +748,9 @@ export type StreamOptions = {
      * 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 `GenerateOptions` — 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. */
     piiDetection?: {
         enabled?: boolean;