@juspay/neurolink 12.47.13 → 12.48.0

package/dist/core/redisConversationMemoryManager.js

@@ -15,6 +15,7 @@ import { withTimeout } from "../utils/errorHandling.js";
 import { buildContextFromPointer, getEffectiveTokenThreshold, } from "../utils/conversationMemory.js";
 import { runWithCurrentLangfuseContext } from "../services/server/ai/observability/instrumentation.js";
 import { logger } from "../utils/logger.js";
+import { extractIsErrorText } from "../utils/toolResultStatus.js";
 import { deserializeConversation, encodeStoredMessages, getSessionMessagesKey, MESSAGES_KEY_SUFFIX, isSessionMessagesKey, parseStoredMessages, serializeConversationMetadata, usesSplitMessageStorage, getNormalizedConfig, getPooledRedisClient, getSessionKey, getUserSessionsKey, releasePooledRedisClient, scanKeys, serializeConversation, } from "../utils/redis.js";
 const redisTracer = tracers.redis;
 const REDIS_TIMEOUT_MS = 5000;
@@ -1602,11 +1603,17 @@ User message: "${userMessage}"`;
                         ? { stepIndex: Number(toolResult.stepIndex) }
                         : {}),
                 };
-                // Build result — success/error metadata only, NOT the output data
+                // Build result — success/error metadata only, NOT the output data.
+                // An `isError: true` payload the tool RETURNED (converted throw,
+                // breaker refusal, MCP failure) is a failure as much as a thrown one,
+                // and is flagged here so replay never reports it as "→ ok".
+                const resultError = toolResult.error !== undefined && toolResult.error !== null
+                    ? String(toolResult.error)
+                    : extractIsErrorText(toolResultValue);
                 const result = {
-                    success: !toolResult.error,
+                    success: resultError === undefined,
                     // result.result intentionally NOT stored — inferred from content at read time
-                    error: toolResult.error ? String(toolResult.error) : undefined,
+                    error: resultError,
                 };
                 const toolResultMessage = {
                     id: randomUUID(),

package/dist/core/resolveRequestKind.d.ts

@@ -1,4 +1,23 @@
-import type { RequestKind, RequestKindInput } from "../types/index.js";
+import type { RequestKind, RequestKindInput, RequestKindTTSInput, TTSSynthesisMode } from "../types/index.js";
+/**
+ * Which text a `generate({ tts })` request synthesizes. An explicit
+ * `tts.mode` wins; otherwise the legacy `useAiResponse` flag decides, and the
+ * absence of both means `"direct"` — the documented default that every
+ * "speak this text" caller relies on.
+ *
+ * Every precedence site (this module, `BaseProvider.synthesizeAIResponseIfNeeded`,
+ * `NeuroLink.attemptMCPGeneration`, the AI Studio generate() override) reads
+ * the answer from here so the rule cannot drift between them.
+ */
+export declare function resolveTTSMode(tts: RequestKindTTSInput | undefined): TTSSynthesisMode;
+/**
+ * True when TTS is enabled and the request wants the input text synthesized,
+ * bypassing the LLM turn. `enabled` is tested for truthiness, as the dispatch
+ * it replaced did and as `synthesizeAIResponseIfNeeded` still does: a caller
+ * off the declared type (`enabled: 1`, `"true"`) reaches the same branch at
+ * every site rather than being routed to a model call by one of them.
+ */
+export declare function isDirectTTSRequest(tts: RequestKindTTSInput | undefined): boolean;
 /**
  * The dispatch decision for "what kind of request is this" — text, image,
  * video, music, avatar, direct TTS synthesis, or PPT generation — at the
@@ -18,9 +37,10 @@ import type { RequestKind, RequestKindInput } from "../types/index.js";
  *      non-image output.format (json/structured/text) — this lets dual-mode
  *      models like gemini-3.1-flash-image-preview still perform text or
  *      structured generation when requested.
- *   3. tts.enabled without tts.useAiResponse — direct synthesis, bypassing
- *      the LLM turn entirely (useAiResponse means the LLM's own text
- *      response gets synthesized afterward, which is NOT this branch).
+ *   3. tts.enabled with `resolveTTSMode()` answering "direct" — i.e. no
+ *      `mode: "response"` and no legacy `useAiResponse: true` — direct
+ *      synthesis, bypassing the LLM turn entirely (response mode means the
+ *      LLM's own text gets synthesized afterward, which is NOT this branch).
  *   4. otherwise, "text".
  */
 export declare function resolveRequestKind(options: RequestKindInput, modelName?: string): RequestKind;

package/dist/core/resolveRequestKind.js

@@ -1,4 +1,30 @@
 import { isImageGenerationModel } from "./constants.js";
+/**
+ * Which text a `generate({ tts })` request synthesizes. An explicit
+ * `tts.mode` wins; otherwise the legacy `useAiResponse` flag decides, and the
+ * absence of both means `"direct"` — the documented default that every
+ * "speak this text" caller relies on.
+ *
+ * Every precedence site (this module, `BaseProvider.synthesizeAIResponseIfNeeded`,
+ * `NeuroLink.attemptMCPGeneration`, the AI Studio generate() override) reads
+ * the answer from here so the rule cannot drift between them.
+ */
+export function resolveTTSMode(tts) {
+    if (tts?.mode === "direct" || tts?.mode === "response") {
+        return tts.mode;
+    }
+    return tts?.useAiResponse ? "response" : "direct";
+}
+/**
+ * True when TTS is enabled and the request wants the input text synthesized,
+ * bypassing the LLM turn. `enabled` is tested for truthiness, as the dispatch
+ * it replaced did and as `synthesizeAIResponseIfNeeded` still does: a caller
+ * off the declared type (`enabled: 1`, `"true"`) reaches the same branch at
+ * every site rather than being routed to a model call by one of them.
+ */
+export function isDirectTTSRequest(tts) {
+    return Boolean(tts?.enabled) && resolveTTSMode(tts) === "direct";
+}
 /**
  * The dispatch decision for "what kind of request is this" — text, image,
  * video, music, avatar, direct TTS synthesis, or PPT generation — at the
@@ -18,9 +44,10 @@ import { isImageGenerationModel } from "./constants.js";
  *      non-image output.format (json/structured/text) — this lets dual-mode
  *      models like gemini-3.1-flash-image-preview still perform text or
  *      structured generation when requested.
- *   3. tts.enabled without tts.useAiResponse — direct synthesis, bypassing
- *      the LLM turn entirely (useAiResponse means the LLM's own text
- *      response gets synthesized afterward, which is NOT this branch).
+ *   3. tts.enabled with `resolveTTSMode()` answering "direct" — i.e. no
+ *      `mode: "response"` and no legacy `useAiResponse: true` — direct
+ *      synthesis, bypassing the LLM turn entirely (response mode means the
+ *      LLM's own text gets synthesized afterward, which is NOT this branch).
  *   4. otherwise, "text".
  */
 export function resolveRequestKind(options, modelName) {
@@ -42,7 +69,7 @@ export function resolveRequestKind(options, modelName) {
     if (isImageGenerationModel(modelName) && !requestsNonImageOutput) {
         return "image";
     }
-    if (options.tts?.enabled && !options.tts?.useAiResponse) {
+    if (isDirectTTSRequest(options.tts)) {
         return "tts-direct";
     }
     return "text";

package/dist/core/toolExecutionRecorder.d.ts

@@ -23,6 +23,12 @@ export declare function serializeToolResult(result: unknown, maxChars: number):
  * Error-shaped tool results (MCP `isError`, `{error}` payloads) count as
  * failures even though the loop received them as normal returns.
  */
+/**
+ * True for an `error` value that actually carries something — `true`, a
+ * non-empty string, or a non-empty object/array — never a falsy placeholder
+ * a tool sets on every call (`error: false`, `error: 0`, `error: {}`).
+ */
+export declare function isMeaningfulError(error: unknown): boolean;
 export declare function isErrorShapedToolResult(result: unknown): boolean;
 /**
  * Per-call recorder for tool executions. See module doc.

package/dist/core/toolExecutionRecorder.js

@@ -45,6 +45,26 @@ export function serializeToolResult(result, maxChars) {
  * Error-shaped tool results (MCP `isError`, `{error}` payloads) count as
  * failures even though the loop received them as normal returns.
  */
+/**
+ * True for an `error` value that actually carries something — `true`, a
+ * non-empty string, or a non-empty object/array — never a falsy placeholder
+ * a tool sets on every call (`error: false`, `error: 0`, `error: {}`).
+ */
+export function isMeaningfulError(error) {
+    if (error === true) {
+        return true;
+    }
+    if (typeof error === "string") {
+        return error.length > 0;
+    }
+    if (Array.isArray(error)) {
+        return error.length > 0;
+    }
+    if (typeof error === "object" && error !== null) {
+        return Object.keys(error).length > 0;
+    }
+    return false;
+}
 export function isErrorShapedToolResult(result) {
     if (!result || typeof result !== "object") {
         return false;
@@ -53,10 +73,12 @@ export function isErrorShapedToolResult(result) {
     if (record.isError === true) {
         return true;
     }
-    if (record.error !== undefined && record.error !== null) {
+    if (isMeaningfulError(record.error)) {
         return true;
     }
-    if (typeof record.status === "string") {
+    if (typeof record.status === "string" &&
+        record.success !== true &&
+        record.ok !== true) {
         return ["error", "failed", "failure", "fail"].includes(record.status.toLowerCase().trim());
     }
     return false;

package/dist/core/toolRoutingDecision.js

@@ -101,6 +101,7 @@ export async function selectServersByDecision(userQuery, routableServers, decide
         questions[decisionKey(SERVER_NAMESPACE, index)] = serverQuestion(server);
     });
     const result = await decide({
+        site: "toolRouting",
         // Structured state rather than a prompt string: the vendor accepts JSON,
         // and naming the fields is what stops the model reading the catalogue as
         // part of the user's request.

package/dist/factories/mediaHandlerCatalog.js

@@ -24,6 +24,11 @@ export const MEDIA_HANDLER_CATALOG = [
     { kind: "stt", name: "deepgram" },
     { kind: "stt", name: "google-stt" },
     { kind: "stt", name: "azure-stt" },
+    // "elevenlabs" is reused across kinds on purpose — TTS primary, STT alias —
+    // the same way "vertex" is a TTS alias and the Video primary. Each kind has
+    // its own registry, so `stt: { provider: "elevenlabs" }` and
+    // `tts: { provider: "elevenlabs" }` resolve to different handlers.
+    { kind: "stt", name: "elevenlabs-stt", aliases: ["scribe", "elevenlabs"] },
     // --- Realtime ---
     { kind: "realtime", name: "openai-realtime" },
     { kind: "realtime", name: "gemini-live" },

package/dist/factories/providerDescriptors.js

@@ -449,6 +449,21 @@ const HAND_DESCRIPTORS = [
         // defaultHealthSweepPriority: all three feed generation fallback chains,
         // and a text-less provider must never be reachable from them.
         timeouts: { decideMs: 5000 },
+        // ADVISORY, not enforced: Jev's server refuses an over-limit request
+        // itself (measured by bisection — a 33,002-token state accepted, 33,003
+        // rejected), so this row exists for `decisionLimits()` to report, and the
+        // pre-flight check skips it. Refusing locally would turn a measured server
+        // ceiling into a client one that drifts from it silently. The number
+        // mirrors TYPESAFE_MAX_STATE_TOKENS in providers/typesafe.ts (which
+        // cannot be imported here without a provider → descriptor cycle); the
+        // decide suite pins the two equal. No question COUNT cap has been
+        // measured — 400 questions beside a near-ceiling state were accepted —
+        // because TypeSafe bounds a request by tokens (TYPESAFE_MAX_REQUEST_TOKENS,
+        // 64K on state plus all questions), not by count.
+        decisionLimits: {
+            maxStateTokens: 33_000,
+            advisory: true,
+        },
         setupUrl: "https://console.typesafe.ai/keys",
     },
     // Laya MUST stay after TypeSafe, XOR after Laya, Perplexity after XOR, and

package/dist/files/fileTools.d.ts

@@ -157,7 +157,7 @@ export declare function createFileTools(registry: FileReferenceRegistry): {
         } | undefined;
         columns?: string[] | undefined;
         entry_path?: string | undefined;
-        format?: "text" | "summary" | "detailed" | undefined;
+        format?: "text" | "detailed" | "summary" | undefined;
     }, {
         success: false;
         error: string | undefined;

package/dist/index.d.ts

@@ -55,12 +55,14 @@ export { createSkillStore, FileSystemSkillStore, InMemorySkillStore, } from "./s
 export { S3SkillStore } from "./skills/skillStoreS3.js";
 export { RedisSkillStore } from "./skills/skillStoreRedis.js";
 export { createSkillTools } from "./skills/skillTools.js";
+export { validateCondensationPrompt } from "./memory/condensationPrompt.js";
 export * from "./types/index.js";
 export { isAbortError } from "./utils/errorHandling.js";
 export { calculateCost, hasPricing } from "./utils/pricing.js";
 export { getAvailableProviders, getBestProvider, isValidProvider, } from "./utils/providerUtils.js";
 export { TTSProcessor } from "./utils/ttsProcessor.js";
 export { TTS_ERROR_CODES, TTSError } from "./utils/ttsProcessor.js";
+export { prepareTextForSpeech, resolveSpeechSanitizeOptions, } from "./utils/speechText.js";
 export { VideoProcessor } from "./utils/videoProcessor.js";
 export { VIDEO_ERROR_CODES, VideoError } from "./utils/videoProcessor.js";
 export { AvatarProcessor } from "./utils/avatarProcessor.js";
@@ -68,7 +70,7 @@ export { AVATAR_ERROR_CODES, AvatarError } from "./utils/avatarProcessor.js";
 export { MusicProcessor } from "./utils/musicProcessor.js";
 export { MUSIC_ERROR_CODES, MusicError } from "./utils/musicProcessor.js";
 export { STTProcessor } from "./utils/sttProcessor.js";
-export { AzureTTS, AzureTTSHandler, CartesiaTTS, CartesiaTTSHandler, ElevenLabsTTS, ElevenLabsTTSHandler, FishAudioTTS, FishAudioTTSHandler, SixtyDBTTS, SixtyDBTTSHandler, GoogleTTSHandler, OpenAITTS, OpenAITTSHandler, AzureSTT, AzureSTTHandler, DeepgramSTT, DeepgramSTTHandler, GoogleSTT, GoogleSTTHandler, OpenAISTT, OpenAISTTHandler, WhisperSTT, WhisperSTTHandler, BaseRealtimeHandler, GeminiLive, GeminiLiveHandler, OpenAIRealtime, OpenAIRealtimeHandler, RealtimeProcessor, RealtimeError, STTError, VoiceError, registerDefaultRealtimeHandlers, registerDefaultSTTHandlers, registerDefaultTTSHandlers, } from "./voice/index.js";
+export { AzureTTS, AzureTTSHandler, CartesiaTTS, CartesiaTTSHandler, ElevenLabsTTS, ElevenLabsTTSHandler, FishAudioTTS, FishAudioTTSHandler, SixtyDBTTS, SixtyDBTTSHandler, GoogleTTSHandler, OpenAITTS, OpenAITTSHandler, AzureSTT, AzureSTTHandler, DeepgramSTT, DeepgramSTTHandler, ElevenLabsSTT, ElevenLabsSTTHandler, GoogleSTT, GoogleSTTHandler, OpenAISTT, OpenAISTTHandler, WhisperSTT, WhisperSTTHandler, BaseRealtimeHandler, GeminiLive, GeminiLiveHandler, OpenAIRealtime, OpenAIRealtimeHandler, RealtimeProcessor, RealtimeError, STTError, VoiceError, registerDefaultRealtimeHandlers, registerDefaultSTTHandlers, registerDefaultTTSHandlers, } from "./voice/index.js";
 export { BeatovenMusic, BeatovenMusicHandler, ElevenLabsMusic, ElevenLabsMusicHandler, LyriaMusic, LyriaMusicHandler, registerDefaultMusicHandlers, ReplicateMusic, ReplicateMusicHandler, } from "./music/index.js";
 export { DIDAvatar, DIDAvatarHandler, HeyGenAvatar, HeyGenAvatarHandler, registerDefaultAvatarHandlers, ReplicateAvatar, ReplicateAvatarHandler, } from "./avatar/index.js";
 export { isVertexVideoConfigured, KlingVideoHandler, registerDefaultVideoHandlers, ReplicateVideoHandler, RunwayVideoHandler, VertexVideoHandler, } from "./adapters/video/index.js";
@@ -417,7 +419,8 @@ export { classifyProviderError, ModelPool, createDefaultRequestRouter, Classifie
  * if (team && team.confidence > 0.7) { route(team.choice); }
  * ```
  */
-export { decisionBooleanConfidence, decisionKey, gateDecisionBoolean, readDecisionBoolean, readDecisionChoice, readDecisionScore, servesInferenceKind, } from "./utils/decisionAnswers.js";
+export { decisionBooleanConfidence, decisionKey, gateDecisionBoolean, HOST_DECISION_NAMESPACE, isDecisionQuestion, readDecisionBoolean, readDecisionChoice, readDecisionScore, servesInferenceKind, } from "./utils/decisionAnswers.js";
+export { estimateDecisionStateTokens, resolveDecisionLimitsReading, } from "./utils/decisionLimits.js";
 export { DECISION_PROVIDERS, resolveDefaultDecisionProvider, } from "./factories/providerDescriptors.js";
 export { TYPESAFE_MAX_REQUEST_TOKENS, TYPESAFE_MAX_STATE_TOKENS, } from "./providers/typesafe.js";
 /**

package/dist/index.js

@@ -95,6 +95,8 @@ export { createSkillStore, FileSystemSkillStore, InMemorySkillStore, } from "./s
 export { S3SkillStore } from "./skills/skillStoreS3.js";
 export { RedisSkillStore } from "./skills/skillStoreRedis.js";
 export { createSkillTools } from "./skills/skillTools.js";
+// Memory (Hippocampus) — condensation prompt template validation
+export { validateCondensationPrompt } from "./memory/condensationPrompt.js";
 // Export ALL types from the centralized type barrel
 export * from "./types/index.js";
 // Error utilities
@@ -106,6 +108,7 @@ export { getAvailableProviders, getBestProvider, isValidProvider, } from "./util
 // TTS utilities
 export { TTSProcessor } from "./utils/ttsProcessor.js";
 export { TTS_ERROR_CODES, TTSError } from "./utils/ttsProcessor.js";
+export { prepareTextForSpeech, resolveSpeechSanitizeOptions, } from "./utils/speechText.js";
 // Video utilities
 export { VideoProcessor } from "./utils/videoProcessor.js";
 export { VIDEO_ERROR_CODES, VideoError } from "./utils/videoProcessor.js";
@@ -131,7 +134,7 @@ export {
 // TTS
 AzureTTS, AzureTTSHandler, CartesiaTTS, CartesiaTTSHandler, ElevenLabsTTS, ElevenLabsTTSHandler, FishAudioTTS, FishAudioTTSHandler, SixtyDBTTS, SixtyDBTTSHandler, GoogleTTSHandler, OpenAITTS, OpenAITTSHandler, 
 // STT
-AzureSTT, AzureSTTHandler, DeepgramSTT, DeepgramSTTHandler, GoogleSTT, GoogleSTTHandler, OpenAISTT, OpenAISTTHandler, WhisperSTT, WhisperSTTHandler, 
+AzureSTT, AzureSTTHandler, DeepgramSTT, DeepgramSTTHandler, ElevenLabsSTT, ElevenLabsSTTHandler, GoogleSTT, GoogleSTTHandler, OpenAISTT, OpenAISTTHandler, WhisperSTT, WhisperSTTHandler, 
 // Realtime
 BaseRealtimeHandler, GeminiLive, GeminiLiveHandler, OpenAIRealtime, OpenAIRealtimeHandler, RealtimeProcessor, 
 // Voice error classes (RealtimeError + STTError + VoiceError)
@@ -655,7 +658,11 @@ export { classifyProviderError, ModelPool, createDefaultRequestRouter, Classifie
  * if (team && team.confidence > 0.7) { route(team.choice); }
  * ```
  */
-export { decisionBooleanConfidence, decisionKey, gateDecisionBoolean, readDecisionBoolean, readDecisionChoice, readDecisionScore, servesInferenceKind, } from "./utils/decisionAnswers.js";
+export { decisionBooleanConfidence, decisionKey, gateDecisionBoolean, HOST_DECISION_NAMESPACE, isDecisionQuestion, readDecisionBoolean, readDecisionChoice, readDecisionScore, servesInferenceKind, } from "./utils/decisionAnswers.js";
+// The estimator the pre-flight refusal uses, and the flattening behind
+// `neurolink.decisionLimits()` — exported so a host measures a state with the
+// very function that will judge it.
+export { estimateDecisionStateTokens, resolveDecisionLimitsReading, } from "./utils/decisionLimits.js";
 export { DECISION_PROVIDERS, resolveDefaultDecisionProvider, } from "./factories/providerDescriptors.js";
 export { TYPESAFE_MAX_REQUEST_TOKENS, TYPESAFE_MAX_STATE_TOKENS, } from "./providers/typesafe.js";
 /**

package/dist/memory/condensationPrompt.d.ts

@@ -0,0 +1,8 @@
+import type { CondensationPromptValidation } from "../types/index.js";
+/**
+ * Check a condensation prompt template for the placeholders Hippocampus
+ * expects. Pure — never logs or throws. `valid` is false only when a
+ * structural placeholder (`OLD_MEMORY` / `NEW_CONTENT`) is missing;
+ * a missing `MAX_WORDS` is reported in `missing` but leaves `valid` true.
+ */
+export declare function validateCondensationPrompt(prompt: string): CondensationPromptValidation;

package/dist/memory/condensationPrompt.js

@@ -0,0 +1,29 @@
+/**
+ * Placeholders `@juspay/hippocampus` substitutes into a condensation prompt
+ * (`replaceAll` in `Hippocampus.add()`). None is required by Hippocampus
+ * itself — a missing one simply stays literal — which is exactly why the
+ * two structural ones must be checked here: a prompt without
+ * `{{NEW_CONTENT}}` produces a memory that never grows, and one without
+ * `{{OLD_MEMORY}}` overwrites the whole summary on every turn. Both fail
+ * silently at the LLM boundary.
+ */
+const CONDENSATION_PLACEHOLDERS = [
+    "OLD_MEMORY",
+    "NEW_CONTENT",
+    "MAX_WORDS",
+];
+const FATAL_PLACEHOLDERS = new Set([
+    "OLD_MEMORY",
+    "NEW_CONTENT",
+]);
+/**
+ * Check a condensation prompt template for the placeholders Hippocampus
+ * expects. Pure — never logs or throws. `valid` is false only when a
+ * structural placeholder (`OLD_MEMORY` / `NEW_CONTENT`) is missing;
+ * a missing `MAX_WORDS` is reported in `missing` but leaves `valid` true.
+ */
+export function validateCondensationPrompt(prompt) {
+    const missing = CONDENSATION_PLACEHOLDERS.filter((name) => !prompt.includes(`{{${name}}}`));
+    const fatal = missing.filter((name) => FATAL_PLACEHOLDERS.has(name));
+    return { valid: fatal.length === 0, missing, fatal };
+}

package/dist/memory/hippocampusInitializer.d.ts

@@ -1,2 +1,14 @@
-import type { HippocampusConfig, HippocampusLike } from "../types/index.js";
-export declare function initializeHippocampus(config: HippocampusConfig): HippocampusLike | null;
+import type { HippocampusClientFactory, HippocampusConfig, HippocampusLike } from "../types/index.js";
+/**
+ * Construct (or adopt) the Hippocampus client. `config.neurolink.instance`
+ * and `config.neurolink.credentials` are read by `@juspay/hippocampus`
+ * ≥0.2.0 itself (the peer floor is 0.2.1, which also fixes literal
+ * placeholder substitution), so condensation runs through the
+ * instance NeuroLink supplies (the one carrying this host's credentials)
+ * with no help from this side.
+ *
+ * Every path that disables memory logs at `error`: warnings are hidden at
+ * the default log level, and a host whose memory is silently off has no
+ * other way to learn it.
+ */
+export declare function initializeHippocampus(config: HippocampusConfig, injectedClient?: HippocampusLike | HippocampusClientFactory): HippocampusLike | null;

package/dist/memory/hippocampusInitializer.js

@@ -25,10 +25,70 @@ function loadHippocampusModule() {
         return null;
     }
 }
-export function initializeHippocampus(config) {
+/**
+ * The client methods NeuroLink core calls: `add()` on the write path and
+ * `get()` on the read path. `delete()` and `close()` are on the type for a
+ * host's own use, but core never calls them, so a client without them is
+ * still usable.
+ */
+const REQUIRED_CLIENT_METHODS = ["add", "get"];
+/**
+ * Construct (or adopt) the Hippocampus client. `config.neurolink.instance`
+ * and `config.neurolink.credentials` are read by `@juspay/hippocampus`
+ * ≥0.2.0 itself (the peer floor is 0.2.1, which also fixes literal
+ * placeholder substitution), so condensation runs through the
+ * instance NeuroLink supplies (the one carrying this host's credentials)
+ * with no help from this side.
+ *
+ * Every path that disables memory logs at `error`: warnings are hidden at
+ * the default log level, and a host whose memory is silently off has no
+ * other way to learn it.
+ */
+export function initializeHippocampus(config, injectedClient) {
+    if (injectedClient) {
+        try {
+            const client = typeof injectedClient === "function"
+                ? injectedClient(config)
+                : injectedClient;
+            // A loosely typed or async factory can hand back undefined or a
+            // Promise; cache neither. A partial client — a write-only double with
+            // no get() — would make every read fail silently, so it is refused
+            // here rather than on each call. Memory is disabled with a clear
+            // message instead of failing every call with a generic error.
+            //
+            // The Promise case falls through to the same "missing" check below
+            // (a thenable has none of the required methods), but a rejecting
+            // factory's Promise needs a handler attached NOW — nothing else ever
+            // awaits it, so an unhandled rejection would otherwise end the
+            // process under the default Node rejection policy.
+            const maybeThenable = client;
+            if (client &&
+                typeof client === "object" &&
+                typeof maybeThenable.then === "function") {
+                maybeThenable.then(undefined, () => {
+                    logger.error("[memoryInitializer] Host-supplied async client factory rejected");
+                });
+            }
+            const missing = !client || typeof client !== "object"
+                ? [...REQUIRED_CLIENT_METHODS]
+                : REQUIRED_CLIENT_METHODS.filter((name) => typeof client[name] !== "function");
+            if (missing.length > 0) {
+                logger.error(`[memoryInitializer] Host-supplied client has no ${missing
+                    .map((name) => `${name}()`)
+                    .join(" / ")}; disabling memory`);
+                return null;
+            }
+            logger.info("[memoryInitializer] Memory initialized with host-supplied client", { fromFactory: typeof injectedClient === "function" });
+            return client;
+        }
+        catch (error) {
+            logger.error("[memoryInitializer] Host-supplied client factory threw; disabling memory", { error: error instanceof Error ? error.message : String(error) });
+            return null;
+        }
+    }
     const mod = loadHippocampusModule();
     if (!mod) {
-        logger.warn("[memoryInitializer] Memory configuration provided but @juspay/hippocampus is not installed. Run `pnpm add @juspay/hippocampus` (or your package manager equivalent) to enable memory.");
+        logger.error("[memoryInitializer] Memory configuration provided but @juspay/hippocampus is not installed. Run `pnpm add @juspay/hippocampus` (or your package manager equivalent) to enable memory.");
         return null;
     }
     try {
@@ -37,11 +97,12 @@ export function initializeHippocampus(config) {
             storageType: config.storage?.type || "sqlite",
             maxWords: config.maxWords || 50,
             hasCustomPrompt: !!config.prompt,
+            condenserSupplied: config.neurolink?.instance !== undefined,
         });
         return instance;
     }
     catch (error) {
-        logger.warn("[memoryInitializer] Failed to initialize memory; disabling", {
+        logger.error("[memoryInitializer] Failed to initialize memory; disabling", {
             error: error instanceof Error ? error.message : String(error),
         });
         return null;