@juspay/neurolink 12.47.14 → 12.48.0

package/dist/neurolink.js

@@ -32,7 +32,9 @@ import { DEFAULT_RECENT_TURNS, KnowledgeGroundingEngine, } from "./knowledge/ind
 import { AIProviderFactory } from "./core/factory.js";
 import { describeDecisionProviderKeys, PROVIDER_ALIAS_INDEX, PROVIDER_DESCRIPTORS_BY_NAME, resolveDefaultDecisionProvider, } from "./factories/providerDescriptors.js";
 import { MAX_PARALLEL_DECISION_BATCHES, mergeDecisionResults, splitDecisionRequest, } from "./utils/decisionBatches.js";
-import { resolveRequestKind } from "./core/resolveRequestKind.js";
+import { decisionKey, HOST_DECISION_NAMESPACE, isHostDecisionKey, snapshotDecisionQuestion, stripHostAnswers, } from "./utils/decisionAnswers.js";
+import { resolveDecisionLimitsReading } from "./utils/decisionLimits.js";
+import { isDirectTTSRequest, resolveRequestKind, } from "./core/resolveRequestKind.js";
 import { createToolEventPayload } from "./core/toolEvents.js";
 import { ProviderFactory } from "./factories/providerFactory.js";
 import { ProviderRegistry } from "./factories/providerRegistry.js";
@@ -55,6 +57,7 @@ import { MCPToolRegistry } from "./mcp/toolRegistry.js";
 // Dynamic argument resolution imports
 import { resolveDynamicArgument } from "./dynamic/dynamicResolver.js";
 import { initializeHippocampus } from "./memory/hippocampusInitializer.js";
+import { validateCondensationPrompt } from "./memory/condensationPrompt.js";
 import { createMemoryRetrievalTools } from "./memory/memoryRetrievalTools.js";
 import { isSkillVisibleInScope } from "./skills/skillMatcher.js";
 import { buildSkillActivationMessage } from "./skills/skillSessionTracker.js";
@@ -62,7 +65,7 @@ import { SkillsManager } from "./skills/skillsManager.js";
 import { createSkillCallTools, createSkillTools } from "./skills/skillTools.js";
 import { getMetricsAggregator, MetricsAggregator, } from "./observability/metricsAggregator.js";
 import { AnalyticsService, calculateAdvancedCost, parseAnalyticsQualityScore, } from "./analytics/index.js";
-import { SpanStatus, SpanType, CircuitBreakerOpenError, ConversationMemoryError, ModelAccessDeniedError, } from "./types/index.js";
+import { SpanStatus, SpanType, CircuitBreakerOpenError, ConversationMemoryError, DEFAULT_DECISION_HOOK_TIMEOUT_MS, MAX_DECISION_HOOK_TIMEOUT_MS, ModelAccessDeniedError, } from "./types/index.js";
 import { resolveTerminalAgentMode } from "./agent/prompts/terminalAgentPrompt.js";
 import { SpanSerializer } from "./observability/utils/spanSerializer.js";
 import { withSpan } from "./telemetry/withSpan.js";
@@ -192,6 +195,12 @@ const isNonRetryableProviderError = sharedIsNonRetryableProviderError;
  * ModelPool catch sites; every other path keeps the general contract.
  */
 const isNonRetryableForPool = sharedIsNonRetryableForPool;
+/**
+ * Ceiling on one background memory write (`Promise.all` of its `add()`
+ * calls), and therefore on how long `shutdown()` / `dispose()` wait for the
+ * writes already scheduled before releasing the condenser.
+ */
+const MEMORY_WRITE_TIMEOUT_MS = 30_000;
 /**
  * NeuroLink - Universal AI Development Platform
  *
@@ -517,6 +526,9 @@ export class NeuroLink {
     // Undefined = the stage's own defaults; the stage itself is gated on a
     // decision provider being configured, not on this.
     contextRelevanceOptions;
+    // Host hooks riding along on every built-in decide site call. Undefined =
+    // no hooks, and the site calls behave exactly as they did without them.
+    decisionHooks;
     /**
      * Merge instance-level credentials with per-call credentials.
      *
@@ -580,6 +592,38 @@ export class NeuroLink {
     // Memory instance and config
     memoryInstance;
     memorySDKConfig;
+    /**
+     * Set when the instance-level condensation prompt failed validation at
+     * construction (see initializeConversationMemory). Memory stays off for
+     * the instance's lifetime; the reason is what the warning already said.
+     */
+    memoryDisabledReason;
+    /**
+     * Dedicated child instance Hippocampus condenses through. Built on first
+     * condensation, never at construction — so a read-only host, or one whose
+     * memory never activates, never pays for a second NeuroLink.
+     */
+    memoryCondenser;
+    /**
+     * Set by `releaseMemoryCondenser()`, i.e. by `shutdown()` / `dispose()`,
+     * once the writes already scheduled have been drained. A memory write
+     * scheduled past that point must skip, and the condenser must never be
+     * rebuilt: a child resurrected after release would outlive its host,
+     * unreleased, and — after `dispose()` wiped the credentials — condense
+     * with none.
+     */
+    memoryCondenserReleased = false;
+    /**
+     * Memory writes scheduled and not yet settled. `releaseMemoryCondenser()`
+     * awaits them (bounded) before it releases anything, so
+     * `await generate(); await shutdown();` — a serverless handler, a
+     * per-request instance, a one-shot CLI run — still stores its last turn.
+     */
+    pendingMemoryWrites = new Set();
+    /** Prompt templates already warned about, so a per-call template warns once. */
+    warnedCondensationPrompts = new Set();
+    /** `decisionHooks.hookTimeoutMs` once validated; see `decisionHookTimeout`. */
+    decisionHookTimeoutMs;
     // Skills subsystem — lazily initialized manager + instance config.
     // `undefined` = not yet attempted, `null` = init failed (stay disabled).
     skillsManagerInstance;
@@ -811,12 +855,157 @@ export class NeuroLink {
     }
     initializeMemoryConfig() {
         const memory = this.conversationMemoryConfig?.conversationMemory?.memory;
-        if (!memory?.enabled) {
+        if (!memory?.enabled || this.memoryDisabledReason) {
             return false;
         }
-        this.memorySDKConfig = memory;
+        // Only the HippocampusConfig part reaches the Hippocampus constructor;
+        // `enabled`, `client`, `strictPrompt` and the write hooks are NeuroLink's.
+        const { enabled: _enabled, client: _client, strictPrompt: _strictPrompt, shouldWrite: _shouldWrite, onBeforeStore: _onBeforeStore, prompt, ...sdkConfig } = memory;
+        this.memorySDKConfig = {
+            ...sdkConfig,
+            // A blank template counts as unset here (validateInstanceCondensationPrompt
+            // skips it), so it must not reach Hippocampus either: it resolves
+            // `config.prompt || HC_CONDENSATION_PROMPT || built-in`, and "   " is
+            // truthy — it would condense with a template that has no placeholders.
+            ...(prompt?.trim() ? { prompt } : {}),
+            neurolink: {
+                ...(memory.neurolink ?? {}),
+                credentials: memory.neurolink?.credentials ?? this.credentials,
+                instance: memory.neurolink?.instance ?? this.lazyMemoryCondenserInstance(),
+            },
+        };
         return true;
     }
+    /**
+     * A `generate()`-only handle whose backing NeuroLink is constructed on the
+     * first condensation call, not when memory is configured or first read.
+     */
+    lazyMemoryCondenserInstance() {
+        return {
+            generate: async (options) => {
+                const condenser = this.getMemoryCondenser();
+                if (!condenser) {
+                    // Hippocampus swallows a condensation error and keeps the old
+                    // memory, which is exactly the right outcome for a write that
+                    // outlived its host: skipped, never condensed with no credentials.
+                    logger.debug("[NeuroLink] Memory condensation skipped: the host instance has been shut down");
+                    throw new Error("Memory condenser released: the host NeuroLink instance has been shut down");
+                }
+                return condenser.generate(options);
+            },
+        };
+    }
+    /**
+     * Release the lazily created condenser with its host. Its own
+     * `shutdown()` is a no-op when condensation never ran; when it did, the
+     * child's memory is disabled and it holds no MCP servers, so this is
+     * cheap — the point is that the host's lifecycle owns the child's.
+     *
+     * The writes already scheduled are drained FIRST, bounded by the write
+     * timeout: a turn's memory write is deferred to `setImmediate`, so
+     * `await generate(); await shutdown();` would otherwise never store the
+     * turn. Only then is the host marked released, so a write scheduled after
+     * that point skips instead of rebuilding the child.
+     */
+    async releaseMemoryCondenser() {
+        await this.drainPendingMemoryWrites();
+        this.memoryCondenserReleased = true;
+        const condenser = this.memoryCondenser;
+        if (!condenser) {
+            return;
+        }
+        this.memoryCondenser = undefined;
+        await condenser.shutdown();
+    }
+    /**
+     * Wait for every scheduled memory write to settle, including writes
+     * scheduled while waiting, within one `MEMORY_WRITE_TIMEOUT_MS` budget.
+     * A write that outlives the budget is left in flight and warned about —
+     * it will skip or fail on its own once the condenser is gone — rather
+     * than hold shutdown open indefinitely.
+     */
+    async drainPendingMemoryWrites() {
+        if (this.pendingMemoryWrites.size === 0) {
+            return;
+        }
+        const deadline = Date.now() + MEMORY_WRITE_TIMEOUT_MS;
+        while (this.pendingMemoryWrites.size > 0) {
+            const remainingMs = deadline - Date.now();
+            const inFlight = [...this.pendingMemoryWrites];
+            if (remainingMs <= 0) {
+                this.warnMemoryWritesLeftInFlight(inFlight.length);
+                return;
+            }
+            try {
+                await withTimeout(Promise.allSettled(inFlight), remainingMs, new Error(`Memory writes still in flight after ${MEMORY_WRITE_TIMEOUT_MS}ms`));
+            }
+            catch {
+                this.warnMemoryWritesLeftInFlight(this.pendingMemoryWrites.size);
+                return;
+            }
+        }
+    }
+    warnMemoryWritesLeftInFlight(count) {
+        logger.warn(`[NeuroLink] Shutdown proceeded with ${count} memory write(s) still in flight after ${MEMORY_WRITE_TIMEOUT_MS}ms; the last turn may not be stored`, { pendingWrites: count });
+    }
+    /**
+     * The child instance Hippocampus condenses through, or null once the host
+     * has been released.
+     *
+     * Deliberately NOT `this`: routing condensation through the parent would
+     * run its MCP init, skills and middleware, emit `generation:*` on the
+     * parent emitter and add the condensation call's cost to
+     * `_sessionCostUsd`. The child inherits `credentials` (or the explicit
+     * `memory.neurolink.credentials`) so condensation no longer depends on
+     * provider keys in `process.env`, has memory disabled so it can never
+     * recurse into a memory write of its own, and — like createWorkerInstance —
+     * joins the host tracer without a second Langfuse exporter.
+     */
+    getMemoryCondenser() {
+        if (this.memoryCondenser) {
+            return this.memoryCondenser;
+        }
+        if (this.memoryCondenserReleased) {
+            return null;
+        }
+        // Constructing an instance rebinds the process-global logger sink to the
+        // new instance's emitter. That sink is whatever the process last set —
+        // not necessarily this host's emitter (another instance may own a
+        // log-event bridge) — so it is captured and put back as it was, rather
+        // than pointed at the host.
+        const previousSink = logger.getEventEmitter();
+        const credentials = this.conversationMemoryConfig?.conversationMemory?.memory?.neurolink
+            ?.credentials ?? this.credentials;
+        const hostLangfuse = this.observabilityConfig?.langfuse;
+        this.memoryCondenser = new NeuroLink({
+            ...(credentials ? { credentials } : {}),
+            conversationMemory: { enabled: false },
+            enableOrchestration: false,
+            ...(this.observabilityConfig
+                ? {
+                    observability: {
+                        ...this.observabilityConfig,
+                        ...(hostLangfuse
+                            ? {
+                                langfuse: {
+                                    ...hostLangfuse,
+                                    autoDetectExternalProvider: true,
+                                    skipLangfuseSpanProcessor: true,
+                                },
+                            }
+                            : {}),
+                    },
+                }
+                : {}),
+        });
+        if (previousSink) {
+            logger.setEventEmitter(previousSink);
+        }
+        else {
+            logger.clearEventEmitter(this.memoryCondenser.emitter);
+        }
+        return this.memoryCondenser;
+    }
     /**
      * Lazy initialization for memory — called during generate/stream.
      */
@@ -832,7 +1021,7 @@ export class NeuroLink {
             this.memoryInstance = null;
             return null;
         }
-        this.memoryInstance = initializeHippocampus(this.memorySDKConfig);
+        this.memoryInstance = initializeHippocampus(this.memorySDKConfig, this.conversationMemoryConfig?.conversationMemory?.memory?.client);
         return this.memoryInstance;
     }
     /**
@@ -990,6 +1179,7 @@ export class NeuroLink {
         // reading config at each call site) keeps compactor construction uniform
         // across the five places that build one.
         this.contextRelevanceOptions = config?.contextRelevance;
+        this.decisionHooks = config?.decisionHooks;
         // ClassifierRouter: opt-in. The LLM strategy reuses this instance's
         // generate() (marked so it never recursively re-routes). Fails open.
         this.classifierRouter = config?.classifierRouter?.enabled
@@ -997,12 +1187,18 @@ export class NeuroLink {
                 generate: (genOptions) => this.preservingTurnState(() => this.generate({
                     ...genOptions,
                 })),
-                // Fail-open by construction: tryDecide returns null rather than
+                // Fail-open by construction: siteDecide returns null rather than
                 // throwing, so an absent or broken decision provider leaves routing
-                // exactly as it was.
-                decide: (decideOptions) => this.tryDecide(decideOptions),
-                // Read lazily: `this.credentials` is assigned later in the constructor.
-                hasDecisionProvider: () => resolveDefaultDecisionProvider(this.credentials) !== undefined,
+                // exactly as it was. The per-call credentials and ids arrive on the
+                // options themselves — classifyJev forwards them from the router
+                // input, since this caller is fixed at construction.
+                decide: (decideOptions) => this.siteDecide(decideOptions),
+                // Read lazily: `this.credentials` is assigned later in the
+                // constructor. Counts the request's per-call credentials too, so a
+                // host that holds no decision key itself but passes a tenant's on
+                // each call gets the decision strategy, as the other sites do.
+                hasDecisionProvider: (callCredentials) => this.resolveDecisionProviderName(undefined, callCredentials) !==
+                    undefined,
                 logger: {
                     debug: (message, meta) => logger.debug(message, meta),
                     warn: (message, meta) => logger.warn(message, meta),
@@ -1088,6 +1284,7 @@ export class NeuroLink {
             // Store config for later use and set flag for lazy initialization
             this.conversationMemoryConfig = config;
             this.conversationMemoryNeedsInit = true;
+            this.validateInstanceCondensationPrompt(config.conversationMemory.memory);
             const memoryInitEndTime = process.hrtime.bigint();
             const memoryInitDurationNs = memoryInitEndTime - memoryInitStartTime;
             logger.debug(`[NeuroLink] ✅ LOG_POINT_C006_MEMORY_INIT_FLAG_SET_SUCCESS`, {
@@ -1122,6 +1319,59 @@ export class NeuroLink {
             });
         }
     }
+    /**
+     * Validate the condensation prompt template memory will condense with —
+     * the instance `prompt`, else `HC_CONDENSATION_PROMPT` (which Hippocampus
+     * reads when no config prompt is set). Hippocampus substitutes
+     * placeholders with `replaceAll` and requires none, so a template missing
+     * `{{NEW_CONTENT}}` yields a memory that never grows and one missing
+     * `{{OLD_MEMORY}}` overwrites the summary on every turn — both silently.
+     *
+     * Default is disable-and-log, matching every other memory failure; the
+     * log line is `error` because it is the only signal an operator gets that
+     * memory is off. With `memory.strictPrompt` the constructor throws instead.
+     *
+     * An empty or whitespace-only template counts as unset — Hippocampus
+     * resolves `config.prompt || HC_CONDENSATION_PROMPT || built-in`, so `""`
+     * means "use the next one down", never "a template with no placeholders".
+     */
+    validateInstanceCondensationPrompt(memory) {
+        if (!memory?.enabled) {
+            return;
+        }
+        const configuredPrompt = memory.prompt?.trim() ? memory.prompt : undefined;
+        const envPrompt = process.env.HC_CONDENSATION_PROMPT?.trim()
+            ? process.env.HC_CONDENSATION_PROMPT
+            : undefined;
+        const template = configuredPrompt ?? envPrompt;
+        if (template === undefined) {
+            return;
+        }
+        const source = configuredPrompt !== undefined ? "prompt" : "env";
+        const configName = source === "prompt"
+            ? "conversationMemory.memory.prompt"
+            : "HC_CONDENSATION_PROMPT";
+        const verdict = validateCondensationPrompt(template);
+        if (verdict.valid) {
+            if (verdict.missing.length > 0) {
+                logger.warn(`[NeuroLink] Memory condensation prompt (${configName}) has no {{MAX_WORDS}} placeholder; maxWords will not be enforced`, { source, missing: verdict.missing });
+            }
+            return;
+        }
+        const reason = `missing required placeholder(s) ${verdict.fatal
+            .map((name) => `{{${name}}}`)
+            .join(", ")}`;
+        if (memory.strictPrompt) {
+            throw ErrorFactory.invalidConfiguration(configName, reason, {
+                source,
+                missing: verdict.missing,
+            });
+        }
+        this.memoryDisabledReason = `${configName}: ${reason}`;
+        // `error`, not `warn`: warnings are hidden at the default log level, and
+        // a host whose memory is silently off has no other way to find out.
+        logger.error(`[NeuroLink] Memory disabled: condensation prompt (${configName}) is ${reason}. Without {{NEW_CONTENT}} memory never grows; without {{OLD_MEMORY}} every turn overwrites it. Fix the template or set memory.strictPrompt to fail fast.`, { source, missing: verdict.missing });
+    }
     /**
      * Initialize HITL (Human-in-the-Loop) if enabled
      */
@@ -1727,6 +1977,7 @@ Current user's request: ${currentInput}`;
      */
     shouldReadMemory(perCallMemory, userId) {
         if (!this.conversationMemoryConfig?.conversationMemory?.memory?.enabled ||
+            this.memoryDisabledReason ||
             !userId) {
             return false;
         }
@@ -1744,6 +1995,7 @@ Current user's request: ${currentInput}`;
      */
     shouldWriteMemory(perCallMemory, userId, content) {
         if (!this.conversationMemoryConfig?.conversationMemory?.memory?.enabled ||
+            this.memoryDisabledReason ||
             !userId) {
             return false;
         }
@@ -1801,34 +2053,138 @@ Current user's request: ${currentInput}`;
         }
         return this.formatMultiUserMemoryContext(memories, inputText);
     }
+    /**
+     * Build the `add()` options for one memory owner. A per-owner prompt that
+     * fails template validation is dropped (warned once per distinct template)
+     * so that owner condenses with the instance prompt instead — Hippocampus
+     * resolves `options.prompt || this.prompt`, so omitting it is the fallback.
+     * An empty or whitespace-only prompt counts as unset and is omitted the
+     * same way, unvalidated: `""` already falls through in Hippocampus, but
+     * `"   "` is truthy and would be used literally.
+     */
+    resolveMemoryAddOptions(owner, prompt, maxWords) {
+        let effectivePrompt = prompt?.trim() ? prompt : undefined;
+        if (effectivePrompt !== undefined) {
+            const verdict = validateCondensationPrompt(effectivePrompt);
+            if (verdict.missing.length > 0 &&
+                !this.warnedCondensationPrompts.has(effectivePrompt)) {
+                if (this.warnedCondensationPrompts.size >= 64) {
+                    this.warnedCondensationPrompts.clear();
+                }
+                this.warnedCondensationPrompts.add(effectivePrompt);
+                if (verdict.valid) {
+                    logger.warn("[NeuroLink] Per-owner memory condensation prompt has no {{MAX_WORDS}} placeholder; maxWords will not be enforced for this owner", { owner, missing: verdict.missing });
+                }
+                else {
+                    logger.warn(`[NeuroLink] Per-owner memory condensation prompt is missing ${verdict.fatal
+                        .map((name) => `{{${name}}}`)
+                        .join(", ")}; using the instance prompt for this owner instead`, { owner, missing: verdict.missing });
+                }
+            }
+            if (!verdict.valid) {
+                effectivePrompt = undefined;
+            }
+        }
+        if (effectivePrompt === undefined && maxWords === undefined) {
+            return undefined;
+        }
+        // No `prompt` key at all when there is none to send, rather than
+        // `prompt: undefined`: what reaches the client is exactly the fallback.
+        return {
+            ...(effectivePrompt !== undefined ? { prompt: effectivePrompt } : {}),
+            ...(maxWords !== undefined ? { maxWords } : {}),
+        };
+    }
     /**
      * Store a conversation turn in memory (non-blocking).
      * Calls add(userId, content) which internally condenses old + new via LLM.
      * Supports additional users with per-user prompt and maxWords overrides.
-     */
-    storeMemoryInBackground(originalPrompt, responseContent, userId, additionalUsers, langfuseIdentity) {
+     *
+     * The write hooks (`shouldWrite`, `onBeforeStore`; per-call wins over
+     * instance) run inside the deferred closure so an async hook never sits on
+     * the response path. A `false` / `null` verdict, a non-string transform or
+     * a thrown hook skips every `add()` for the turn — a missed memory is
+     * recoverable, a polluted condensed summary is not.
+     */
+    storeMemoryInBackground(turn, perCallMemory, langfuseIdentity) {
+        const { userId } = turn;
+        const instanceHooks = this.conversationMemoryConfig?.conversationMemory?.memory;
+        const shouldWrite = perCallMemory?.shouldWrite ?? instanceHooks?.shouldWrite;
+        const onBeforeStore = perCallMemory?.onBeforeStore ?? instanceHooks?.onBeforeStore;
         const memoryWrite = async () => {
             try {
+                // A write scheduled after shutdown()/dispose() finished draining has
+                // no host left to condense on; landing it would rebuild the released
+                // condenser. (A write scheduled before is what the drain waits for.)
+                if (this.memoryCondenserReleased) {
+                    logger.debug("[NeuroLink] Memory write skipped: the instance has been shut down", { userId });
+                    return;
+                }
                 const client = this.ensureMemoryReady();
                 if (!client) {
                     return;
                 }
-                const content = `User: ${originalPrompt}\nAssistant: ${responseContent}`;
+                if (shouldWrite) {
+                    let allowed;
+                    try {
+                        allowed = await withTimeout(Promise.resolve(shouldWrite(turn)), MEMORY_WRITE_TIMEOUT_MS, new Error(`memory.shouldWrite exceeded ${MEMORY_WRITE_TIMEOUT_MS}ms`));
+                    }
+                    catch (error) {
+                        logger.warn("[NeuroLink] memory.shouldWrite hook threw; skipping memory write for this turn", {
+                            userId,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                        return;
+                    }
+                    if (!allowed) {
+                        logger.debug("[NeuroLink] memory.shouldWrite declined the turn", {
+                            userId,
+                        });
+                        return;
+                    }
+                }
+                let content = `User: ${turn.prompt}\nAssistant: ${turn.response}`;
+                if (onBeforeStore) {
+                    let transformed;
+                    try {
+                        transformed = await withTimeout(Promise.resolve(onBeforeStore(content, turn)), MEMORY_WRITE_TIMEOUT_MS, new Error(`memory.onBeforeStore exceeded ${MEMORY_WRITE_TIMEOUT_MS}ms`));
+                    }
+                    catch (error) {
+                        logger.warn("[NeuroLink] memory.onBeforeStore hook threw; skipping memory write for this turn", {
+                            userId,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                        return;
+                    }
+                    if (transformed === null) {
+                        logger.debug("[NeuroLink] memory.onBeforeStore vetoed the turn", {
+                            userId,
+                        });
+                        return;
+                    }
+                    if (typeof transformed !== "string") {
+                        logger.warn("[NeuroLink] memory.onBeforeStore returned a non-string; skipping memory write for this turn", { userId, returnedType: typeof transformed });
+                        return;
+                    }
+                    content = transformed;
+                }
+                if (!content.trim()) {
+                    return;
+                }
                 // Collect all users to write: primary + additional users with write !== false
-                const writeOps = [client.add(userId, content)];
-                const writableAdditional = (additionalUsers || []).filter((u) => u.write !== false);
+                const writeOps = [
+                    client.add(userId, content, this.resolveMemoryAddOptions(userId, perCallMemory?.prompt, perCallMemory?.maxWords)),
+                ];
+                const writableAdditional = (perCallMemory?.additionalUsers || []).filter((u) => u.write !== false);
                 for (const user of writableAdditional) {
-                    const addOptions = user.prompt || user.maxWords
-                        ? { prompt: user.prompt, maxWords: user.maxWords }
-                        : undefined;
-                    writeOps.push(client.add(user.userId, content, addOptions));
+                    writeOps.push(client.add(user.userId, content, this.resolveMemoryAddOptions(user.userId, user.prompt, user.maxWords)));
                 }
                 // withTimeout races against Promise.all — if the timeout fires, the
                 // await resolves with an error but the underlying client.add() calls
                 // may still complete in the background. This is acceptable: the memory
                 // client API (Mem0) doesn't support AbortSignal, and these are
                 // fire-and-forget background writes where a stale completion is harmless.
-                await withTimeout(Promise.all(writeOps), 30_000, new Error("Background memory write timed out after 30s"));
+                await withTimeout(Promise.all(writeOps), MEMORY_WRITE_TIMEOUT_MS, new Error(`Background memory write timed out after ${MEMORY_WRITE_TIMEOUT_MS}ms`));
             }
             catch (error) {
                 logger.warn("Memory storage failed:", error);
@@ -1848,7 +2204,19 @@ Current user's request: ${currentInput}`;
                 traceName: langfuseIdentity.traceName ?? null,
             }, memoryWrite)
             : runWithCurrentLangfuseContext(memoryWrite);
-        setImmediate(wrappedMemoryWrite);
+        // Tracked from the moment it is scheduled, not from when setImmediate
+        // fires: shutdown() typically runs in that gap, and a write it cannot
+        // see is a write it cannot wait for. `memoryWrite` never rejects (it
+        // catches internally), so the settle only ever resolves.
+        const scheduled = new Promise((resolve) => {
+            setImmediate(() => {
+                Promise.resolve()
+                    .then(wrappedMemoryWrite)
+                    .then(() => resolve(), () => resolve());
+            });
+        });
+        this.pendingMemoryWrites.add(scheduled);
+        void scheduled.then(() => this.pendingMemoryWrites.delete(scheduled));
     }
     /**
      * Set up HITL event forwarding to main emitter
@@ -2844,6 +3212,12 @@ Current user's request: ${currentInput}`;
             catch (error) {
                 logger.warn("[NeuroLink] Background work cleanup failed:", error);
             }
+            try {
+                await this.releaseMemoryCondenser();
+            }
+            catch (error) {
+                logger.warn("[NeuroLink] Memory condenser shutdown failed:", error);
+            }
             try {
                 await flushOpenTelemetry();
                 await shutdownOpenTelemetry();
@@ -4042,16 +4416,40 @@ Current user's request: ${currentInput}`;
     /**
      * Dependencies handed to every `ContextCompactor`.
      *
-     * `tryDecide` returns null whenever no decision provider is configured or
+     * `siteDecide` returns null whenever no decision provider is configured or
      * the call fails, so passing this unconditionally is safe: the compactor
      * runs its previous pipeline unchanged and pays nothing for the option.
+     * `outer` is the request the compaction runs for — its credentials, abort
+     * signal and ids — so both decision stages go to the caller's account.
      */
-    contextCompactorDeps() {
+    contextCompactorDeps(outer) {
         return {
-            decide: (decisionOptions) => this.tryDecide(decisionOptions),
+            decide: (decisionOptions) => this.siteDecide(decisionOptions, outer),
             relevance: this.contextRelevanceOptions,
         };
     }
+    /**
+     * What a decide site inherits from the request it runs inside. Read off the
+     * request options so every site — routing, tool routing, both compaction
+     * stages — forwards the same fields the same way. The request id is the
+     * documented top-level `requestId` first, then `context.requestId`.
+     */
+    decisionSiteContext(options, sessionId) {
+        const requestContext = options.context;
+        const requestId = options.requestId ??
+            (typeof requestContext?.requestId === "string"
+                ? requestContext.requestId
+                : undefined);
+        const contextSessionId = typeof requestContext?.sessionId === "string"
+            ? requestContext.sessionId
+            : undefined;
+        return {
+            credentials: options.credentials,
+            signal: options.abortSignal,
+            sessionId: sessionId ?? contextSessionId,
+            requestId,
+        };
+    }
     /**
      * Applies the host-configured `classifierRouter` to `options` in place.
      *
@@ -4093,6 +4491,10 @@ Current user's request: ${currentInput}`;
         const priorMessageCount = Array.isArray(opt.conversationMessages)
             ? opt.conversationMessages.length
             : undefined;
+        // The decision call inherits this request's credentials, abort signal
+        // and ids exactly as the other sites do, so it reaches the caller's
+        // account, dies with the turn, and correlates on the same requestId.
+        const siteContext = this.decisionSiteContext(opt, sessionId);
         try {
             const decision = await this.classifierRouter.route({
                 prompt: promptText,
@@ -4103,6 +4505,9 @@ Current user's request: ${currentInput}`;
                 sessionId,
                 sessionBound,
                 priorMessageCount,
+                credentials: siteContext.credentials,
+                signal: siteContext.signal,
+                requestId: siteContext.requestId,
             });
             if (!decision) {
                 return;
@@ -4276,7 +4681,9 @@ Current user's request: ${currentInput}`;
             maxSteps: options.maxSteps,
             toolRoots: options.toolRoots,
             toolChoice: options.toolChoice,
+            toolChoiceSteps: options.toolChoiceSteps,
             prepareStep: options.prepareStep,
+            replayToolSteps: options.replayToolSteps,
             enabledToolNames: options.enabledToolNames,
             enableAnalytics: options.enableAnalytics,
             enableEvaluation: options.enableEvaluation,
@@ -4656,7 +5063,19 @@ Current user's request: ${currentInput}`;
         // Memory storage
         if (this.shouldWriteMemory(options.memory, options.context?.userId, generateResult.content) &&
             options.context?.userId) {
-            this.storeMemoryInBackground(originalPrompt ?? "", generateResult.content.trim(), options.context.userId, options.memory?.additionalUsers, options.context);
+            const sessionId = options.context.sessionId;
+            this.storeMemoryInBackground({
+                prompt: originalPrompt ?? "",
+                response: generateResult.content.trim(),
+                userId: options.context.userId,
+                ...(typeof sessionId === "string" ? { sessionId } : {}),
+                provider: generateResult.provider,
+                model: generateResult.model,
+                toolsUsed: generateResult.toolsUsed ??
+                    generateResult.toolExecutions?.map((t) => t.toolName),
+                usage: generateResult.usage,
+                finishReason: generateResult.finishReason,
+            }, options.memory, options.context);
         }
     }
     /**
@@ -5310,7 +5729,7 @@ Current user's request: ${currentInput}`;
                     enableDeduplicate: true,
                     enableTruncate: true,
                     truncationFraction: fraction,
-                }, this.contextCompactorDeps());
+                }, this.contextCompactorDeps(this.decisionSiteContext(options)));
                 const compactionResult = await compactor.compact(originalMessages, compactionTarget, undefined, options.context?.requestId);
                 if (!compactionResult.compacted) {
                     continue;
@@ -5323,6 +5742,7 @@ Current user's request: ${currentInput}`;
                     maxTokens: options.maxTokens,
                     systemPrompt: options.systemPrompt,
                     currentPrompt: options.prompt,
+                    toolReplayMode: this.resolveToolReplayModeForBudget(options),
                     conversationMessages: repairedResult.messages,
                 });
                 if (verifyBudget.withinBudget) {
@@ -5509,8 +5929,7 @@ Current user's request: ${currentInput}`;
      * Attempt MCP generation with retry logic
      */
     async attemptMCPGeneration(options, generateInternalId, generateInternalStartTime, generateInternalHrTimeStart, functionTag) {
-        if (!options.disableTools &&
-            !(options.tts?.enabled && !options.tts?.useAiResponse)) {
+        if (!options.disableTools && !isDirectTTSRequest(options.tts)) {
             return await this.performMCPGenerationRetries(options, generateInternalId, generateInternalStartTime, generateInternalHrTimeStart, functionTag);
         }
         return null;
@@ -5874,6 +6293,26 @@ Current user's request: ${currentInput}`;
             // Ignore serialization errors in debug logging
         }
     }
+    /**
+     * The replay mode the budget check should size stored tool rows by: the
+     * request's `replayToolSteps`, else the instance's, else the builder's
+     * `"marker"` default — the same resolution BaseProvider applies before
+     * building messages, so the estimate matches the prompt.
+     *
+     * Reach: every `checkContextBudget` call on the generate and stream paths,
+     * including the post-compaction and post-truncation re-checks. It does NOT
+     * reach the compactor's own stage gates or the summarizer's sizing
+     * (`ContextCompactor`, `SummarizationEngine`): those still count tool rows
+     * at stored size, so under `"marker"` / `"off"` a stage may prune or
+     * summarize more history than the prompt would have carried. Threading the
+     * mode into the compactor is a follow-up, tracked in
+     * docs/features/context-compaction.md ("Context budget").
+     */
+    resolveToolReplayModeForBudget(options) {
+        return (options.replayToolSteps ??
+            this.conversationMemory?.config?.replayToolSteps ??
+            "marker");
+    }
     async ensureMCPGenerationBudget(options, requestId, providerName, enhancedSystemPrompt, availableTools, conversationMessages) {
         const budgetResult = checkContextBudget({
             provider: providerName,
@@ -5884,6 +6323,7 @@ Current user's request: ${currentInput}`;
             currentPrompt: options.prompt,
             toolDefinitions: availableTools,
             compactionThreshold: options.compactionThreshold,
+            toolReplayMode: this.resolveToolReplayModeForBudget(options),
         });
         logger.info("[TokenBudget] Token breakdown", {
             requestId,
@@ -5946,7 +6386,7 @@ Current user's request: ${currentInput}`;
             summarizationProvider: this.conversationMemoryConfig?.conversationMemory
                 ?.summarizationProvider,
             summarizationModel: this.conversationMemoryConfig?.conversationMemory?.summarizationModel,
-        }, this.contextCompactorDeps());
+        }, this.contextCompactorDeps(this.decisionSiteContext(options, compactionSessionId)));
         // Fixed overhead (system + prompt + tools + files) already exceeds the
         // window — no amount of history compaction can fit this request, and
         // compacting to an empty history would only hide the real cause.
@@ -5979,6 +6419,7 @@ Current user's request: ${currentInput}`;
             systemPrompt: enhancedSystemPrompt,
             conversationMessages: compactedMessages,
             currentPrompt: options.prompt,
+            toolReplayMode: this.resolveToolReplayModeForBudget(options),
             toolDefinitions: availableTools,
         });
         if (postCompactBudget.withinBudget) {
@@ -6000,6 +6441,7 @@ Current user's request: ${currentInput}`;
             systemPrompt: enhancedSystemPrompt,
             conversationMessages: compactedMessages,
             currentPrompt: options.prompt,
+            toolReplayMode: this.resolveToolReplayModeForBudget(options),
             toolDefinitions: availableTools,
         });
         if (!finalBudget.withinBudget) {
@@ -6337,6 +6779,7 @@ Current user's request: ${currentInput}`;
                     systemPrompt: options.systemPrompt,
                     conversationMessages: conversationMessages,
                     currentPrompt: options.prompt,
+                    toolReplayMode: this.resolveToolReplayModeForBudget(options),
                     toolDefinitions: options.tools
                         ? Object.values(options.tools)
                         : undefined,
@@ -6401,6 +6844,7 @@ Current user's request: ${currentInput}`;
                                 systemPrompt: options.systemPrompt,
                                 conversationMessages: [],
                                 currentPrompt: windowed,
+                                toolReplayMode: this.resolveToolReplayModeForBudget(options),
                                 toolDefinitions: options.tools
                                     ? Object.values(options.tools)
                                     : undefined,
@@ -6483,7 +6927,7 @@ Current user's request: ${currentInput}`;
                             ?.summarizationProvider,
                         summarizationModel: this.conversationMemoryConfig?.conversationMemory
                             ?.summarizationModel,
-                    }, this.contextCompactorDeps());
+                    }, this.contextCompactorDeps(this.decisionSiteContext(options, dpgCompactionSessionId)));
                     const compactionResult = await compactor.compact(conversationMessages, resolveHistoryBudget(budgetCheck, options.compactionThreshold), this.conversationMemoryConfig?.conversationMemory, options.context?.requestId, { currentRequest: options.prompt });
                     if (compactionResult.compacted) {
                         const repairedResult = repairToolPairs(compactionResult.messages);
@@ -6498,6 +6942,7 @@ Current user's request: ${currentInput}`;
                         systemPrompt: options.systemPrompt,
                         conversationMessages: conversationMessages,
                         currentPrompt: options.prompt,
+                        toolReplayMode: this.resolveToolReplayModeForBudget(options),
                         toolDefinitions: options.tools
                             ? Object.values(options.tools)
                             : undefined,
@@ -6536,6 +6981,7 @@ Current user's request: ${currentInput}`;
                             systemPrompt: options.systemPrompt,
                             conversationMessages: conversationMessages,
                             currentPrompt: options.prompt,
+                            toolReplayMode: this.resolveToolReplayModeForBudget(options),
                             toolDefinitions: options.tools
                                 ? Object.values(options.tools)
                                 : undefined,
@@ -7512,12 +7958,10 @@ Current user's request: ${currentInput}`;
                     abortSignal: options.abortSignal,
                 })),
                 // Calibrated per-server routing when a decision provider is
-                // configured. tryDecide returns null without one, so the resolver
-                // falls straight through to the generative router as before.
-                decideFn: (decisionOptions) => this.tryDecide({
-                    ...decisionOptions,
-                    signal: options.abortSignal,
-                }),
+                // configured. siteDecide returns null without one, so the resolver
+                // falls straight through to the generative router as before. The
+                // outer request's credentials, abort signal and ids ride along.
+                decideFn: (decisionOptions) => this.siteDecide(decisionOptions, this.decisionSiteContext(options, sessionId || undefined)),
                 decisionMinDropConfidence: routingConfig.minDropConfidence,
                 emitDecision: captureDecision,
                 // L2 / ITEM D — only populated when embedding is configured.
@@ -8198,6 +8642,16 @@ Current user's request: ${currentInput}`;
                         accumulatedContent,
                         startTime,
                         eventSequence,
+                        // Read only now, after the stream drained: the provider's
+                        // toolsUsed is a live getter that resolves as the loop runs.
+                        resultToolsUsed: (() => {
+                            const fromResult = mcpStreamOutcome.toolsUsed;
+                            if (Array.isArray(fromResult) && fromResult.length > 0) {
+                                return fromResult;
+                            }
+                            const fromCalls = currentToolCalls().map((t) => t.toolName);
+                            return fromCalls.length > 0 ? fromCalls : undefined;
+                        })(),
                     });
                 }
             })();
@@ -8715,7 +9169,7 @@ Current user's request: ${currentInput}`;
      * Handles conversation memory storage in the background.
      */
     async storeStreamConversationMemory(params) {
-        const { enhancedOptions, providerName, originalPrompt, accumulatedContent, startTime, eventSequence, } = params;
+        const { enhancedOptions, providerName, originalPrompt, accumulatedContent, startTime, eventSequence, resultToolsUsed, } = params;
         // Logger Guard: the full options object (history + tool outputs) can be
         // enormous — an eager JSON.stringify here threw RangeError: Invalid
         // string length in production and killed the turn. Serialize lazily,
@@ -8793,7 +9247,26 @@ Current user's request: ${currentInput}`;
             }
         }
         if (this.shouldWriteMemory(enhancedOptions.memory, enhancedOptions.context?.userId, accumulatedContent)) {
-            this.storeMemoryInBackground(originalPrompt ?? "", accumulatedContent.trim(), enhancedOptions.context?.userId, enhancedOptions.memory?.additionalUsers, enhancedOptions.context);
+            const streamSessionId = enhancedOptions.context?.sessionId;
+            // Tool names come from THIS request's stream result ONLY, as generate()
+            // reads them off its own result — an empty list is authoritative. The
+            // captured tool:start events are never consulted: they are collected
+            // by instance-wide listeners, so a stream that used no tools, running
+            // beside any other tool call on the same instance, would otherwise
+            // hand that tool's name to its shouldWrite / onBeforeStore.
+            // usage/finishReason stay unavailable.
+            const toolsUsed = [...new Set(resultToolsUsed ?? [])];
+            this.storeMemoryInBackground({
+                prompt: originalPrompt ?? "",
+                response: accumulatedContent.trim(),
+                userId: enhancedOptions.context?.userId,
+                ...(typeof streamSessionId === "string"
+                    ? { sessionId: streamSessionId }
+                    : {}),
+                provider: providerName,
+                model: enhancedOptions.model,
+                ...(toolsUsed.length > 0 ? { toolsUsed } : {}),
+            }, enhancedOptions.memory, enhancedOptions.context);
         }
     }
     /**
@@ -8903,6 +9376,7 @@ Current user's request: ${currentInput}`;
             model: options.model,
             maxTokens: options.maxTokens,
             systemPrompt: enhancedSystemPrompt,
+            toolReplayMode: this.resolveToolReplayModeForBudget(options),
             conversationMessages: conversationMessages,
             currentPrompt: options.input.text,
             toolDefinitions: availableTools,
@@ -8956,7 +9430,7 @@ Current user's request: ${currentInput}`;
                     ?.summarizationProvider,
                 summarizationModel: this.conversationMemoryConfig?.conversationMemory
                     ?.summarizationModel,
-            }, this.contextCompactorDeps());
+            }, this.contextCompactorDeps(this.decisionSiteContext(options, streamCompactionSessionId)));
             const compactionResult = await compactor.compact(conversationMessages, resolveHistoryBudget(streamBudget, options.compactionThreshold), this.conversationMemoryConfig?.conversationMemory, options.context?.requestId, { currentRequest: options.input.text });
             if (compactionResult.compacted) {
                 const repairedResult = repairToolPairs(compactionResult.messages);
@@ -8973,6 +9447,7 @@ Current user's request: ${currentInput}`;
                 model: options.model,
                 maxTokens: options.maxTokens,
                 systemPrompt: enhancedSystemPrompt,
+                toolReplayMode: this.resolveToolReplayModeForBudget(options),
                 conversationMessages: conversationMessages,
                 currentPrompt: options.input.text,
                 toolDefinitions: availableTools,
@@ -9012,6 +9487,7 @@ Current user's request: ${currentInput}`;
                     model: options.model,
                     maxTokens: options.maxTokens,
                     systemPrompt: enhancedSystemPrompt,
+                    toolReplayMode: this.resolveToolReplayModeForBudget(options),
                     conversationMessages: conversationMessages,
                     currentPrompt: options.input.text,
                     toolDefinitions: availableTools,
@@ -13022,14 +13498,366 @@ Current user's request: ${currentInput}`;
      * @throws when no decision provider is configured, or the call fails
      */
     async decide(options) {
+        return this.runDecide(options);
+    }
+    /**
+     * The provider a decision call will go to, resolved exactly as `decide()`
+     * resolves it: an explicit name (or alias) wins, else the first configured
+     * decision provider counting SDK credentials as well as the environment.
+     */
+    resolveDecisionProviderName(provider, credentials) {
+        return (provider ??
+            resolveDefaultDecisionProvider(this.resolveCredentials(credentials)));
+    }
+    /**
+     * The model `decide()` sends when the caller names none: the one the
+     * provider factory registered — `<PROVIDER>_MODEL` as it read at
+     * registration, else the descriptor default. `decisionLimits()` must
+     * report this same value rather than re-read the environment, or a
+     * `LAYA_MODEL` changed after registration would size a state against one
+     * checkpoint's window while the pre-flight check applies another's.
+     * Before registration has run the registry is empty, and the factory will
+     * read the environment when it does — so that read is returned here.
+     */
+    registeredDecisionModel(descriptor) {
+        const registered = ProviderFactory.getProviderInfo(descriptor.name)?.defaultModel;
+        if (registered) {
+            return registered;
+        }
+        const envModel = descriptor.envVars.model
+            ? process.env[descriptor.envVars.model]
+            : undefined;
+        return envModel || descriptor.defaultModel;
+    }
+    /**
+     * What the decision provider can read, resolved for one model — the same
+     * figures the pre-flight refusal compares against, so a host can size the
+     * questions it adds through `decisionHooks` (or a state it is about to
+     * send) before the call instead of after the refusal.
+     *
+     * Provider resolution is `decide()`'s; the model is `query.model`, else
+     * the model `decide()` would send (see `registeredDecisionModel`); the
+     * per-model entry is flattened over the base. `enforcedLocally` says
+     * whether NeuroLink refuses an over-limit request itself (Laya) or only
+     * reports the server's ceiling (TypeSafe, whose limits are advisory).
+     *
+     * Returns null when no decision provider is configured and none is named —
+     * parity with `tryDecide` — and for a provider that declares no limits.
+     * A named provider is read whether or not it is configured: its limits are
+     * facts about the model, not about this host's credentials.
+     */
+    decisionLimits(query) {
+        const requested = this.resolveDecisionProviderName(query?.provider, query?.credentials);
+        if (!requested) {
+            return null;
+        }
+        const canonical = PROVIDER_ALIAS_INDEX.get(requested.toLowerCase()) ?? requested;
+        const descriptor = PROVIDER_DESCRIPTORS_BY_NAME.get(canonical);
+        if (!descriptor) {
+            return null;
+        }
+        const model = query?.model ?? this.registeredDecisionModel(descriptor);
+        return resolveDecisionLimitsReading(descriptor, model);
+    }
+    /**
+     * `decisionHooks.hookTimeoutMs`, validated once per instance. A timer
+     * honours delays from 1 to 2^31 − 1 ms and fires at once for anything
+     * else — so `Infinity`, meant to lift the bound, would instead time every
+     * hook out immediately, as would 0, NaN or a negative. Such a value falls
+     * back to the default with one warning.
+     */
+    decisionHookTimeout() {
+        if (this.decisionHookTimeoutMs !== undefined) {
+            return this.decisionHookTimeoutMs;
+        }
+        const configured = this.decisionHooks?.hookTimeoutMs;
+        let resolved = DEFAULT_DECISION_HOOK_TIMEOUT_MS;
+        if (configured !== undefined) {
+            if (typeof configured === "number" &&
+                Number.isFinite(configured) &&
+                configured > 0 &&
+                configured <= MAX_DECISION_HOOK_TIMEOUT_MS) {
+                resolved = configured;
+            }
+            else {
+                logger.warn(`[Decision] decisionHooks.hookTimeoutMs must be a finite number from 1 to ${MAX_DECISION_HOOK_TIMEOUT_MS} ms; using the default ${DEFAULT_DECISION_HOOK_TIMEOUT_MS} ms`, { configured: String(configured) });
+            }
+        }
+        this.decisionHookTimeoutMs = resolved;
+        return resolved;
+    }
+    /**
+     * `EventEmitter.emit` runs listeners synchronously and rethrows whatever
+     * they throw. A decision event is observe-only, so a throwing listener
+     * must not be able to change the turn's routing or compaction outcome.
+     */
+    emitDecisionEvent(name, payload) {
+        try {
+            this.emitter.emit(name, payload);
+        }
+        catch (error) {
+            logger.warn(`[Decision] a ${name} listener threw`, {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    /**
+     * The one path every fail-open decision takes — a host's own `tryDecide`
+     * and all five built-in sites (routing, tool routing, both compaction
+     * stages, RAG planning) end up here.
+     *
+     * For a request stamped with a {@link DecisionSite} this is also where the
+     * host's `decisionHooks` ride along:
+     *
+     * 1. `extendQuestions` may add questions; a throw is logged and ignored.
+     * 2. Each host question is validated (invalid ones dropped, with a warning)
+     *    and namespaced `host__N` on the wire, so it can never collide with
+     *    NeuroLink's own ids (`difficulty`, `server__N`, `msg__N`, …).
+     * 3. Additions are capped at the provider's `maxQuestions` minus
+     *    NeuroLink's own count. Without the cap a host adding one question too
+     *    many would have the WHOLE request refused, and NeuroLink's own routing
+     *    would silently degrade to the heuristic — the host's problem would
+     *    become NeuroLink's. A provider that declares no `maxQuestions`
+     *    (TypeSafe, XOR) takes every well-formed addition.
+     * 4. Answers are split: the consumer sees only its own ids, exactly as it
+     *    would without hooks; `onAnswers` gets the host's answers under the
+     *    host's original ids plus the full result.
+     *
+     * The request's `images` and `video` ride along untouched — `merged` and
+     * the wire call spread the request, and only `state`, the questions and
+     * the result are cloned — so an XOR request keeps its Buffers and its
+     * result keeps `mediaBytes`.
+     *
+     * `decision:before` / `decision:after` fire once per site call on the
+     * instance emitter, observe-only, whether or not the call produced a
+     * result. Without hooks and listeners, 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.
+     *
+     * Fail-open by construction, in three layers. Without a decision provider
+     * nothing runs at all — no hook, no event — and the consumer gets the null
+     * it always got. Everything a host can reach (its hook's return value, the
+     * event payloads, the answer split, `onAnswers`) runs inside one `try`;
+     * whatever a host throws, the consumer gets what `tryRunDecide` alone
+     * would have given it. And every host-facing value is a `structuredClone`,
+     * so a hook or listener that edits what it is handed edits neither the
+     * wire request nor the consumer's own question objects.
+     *
+     * `outer` is what the surrounding `generate()` / `stream()` supplies —
+     * per-call credentials, abort signal, ids — and wins over the same fields
+     * on the request.
+     */
+    async siteDecide(request, outer) {
+        const merged = {
+            ...request,
+            credentials: outer?.credentials ?? request.credentials,
+            // Either cancellation must win: the outer call's abort and the site's
+            // own deadline are independent limits.
+            signal: outer?.signal && request.signal
+                ? AbortSignal.any([outer.signal, request.signal])
+                : (outer?.signal ?? request.signal),
+            sessionId: outer?.sessionId ?? request.sessionId,
+            requestId: outer?.requestId ?? request.requestId,
+        };
+        const site = merged.site;
+        if (!site) {
+            return this.tryRunDecide(merged);
+        }
+        // Inert without a decision provider: a host's hook must not sit on the
+        // request path of a tenant that has no decision model to reach, and an
+        // event for a call that could never be made would only mislead.
+        if (!this.resolveDecisionProviderName(merged.provider, merged.credentials)) {
+            return null;
+        }
+        // Wire id → the host's own id, so answers can be handed back under the
+        // ids the host used, and NeuroLink's consumers never see a host id. A Map,
+        // so a host id such as `__proto__` is an ordinary key.
+        const hostIdByWireId = new Map();
+        // Set once the wire call has returned, so the catch below knows whether
+        // to fall back to a fresh call or to hand over what was already obtained.
+        let obtained;
+        try {
+            const ownQuestions = merged.questions;
+            const ownCount = Object.keys(ownQuestions).length;
+            const hooks = this.decisionHooks;
+            const hookTimeoutMs = this.decisionHookTimeout();
+            // Host-facing copies of the consumer's state and questions, made once
+            // and only when something will receive them. The consumer's question
+            // objects are often module-level rubric constants; a listener that
+            // edited one in place would otherwise rewrite every later call.
+            let hostView;
+            const hostFacing = () => {
+                hostView ??= {
+                    state: structuredClone(merged.state),
+                    questions: structuredClone(ownQuestions),
+                };
+                return hostView;
+            };
+            const hookContext = () => ({
+                site,
+                ...hostFacing(),
+                sessionId: merged.sessionId,
+                requestId: merged.requestId,
+            });
+            let questions = ownQuestions;
+            if (hooks?.extendQuestions) {
+                let proposed;
+                try {
+                    proposed =
+                        (await withTimeout(Promise.resolve(hooks.extendQuestions(hookContext())), hookTimeoutMs, new Error(`extendQuestions exceeded ${hookTimeoutMs}ms`))) ?? undefined;
+                }
+                catch (error) {
+                    logger.warn(`[Decision] extendQuestions hook failed for site "${site}" — proceeding with NeuroLink's own questions`, { error: error instanceof Error ? error.message : String(error) });
+                }
+                const proposedEntries = proposed ? Object.entries(proposed) : [];
+                if (proposedEntries.length > 0) {
+                    const limits = this.decisionLimits({
+                        provider: merged.provider,
+                        model: merged.model,
+                        credentials: merged.credentials,
+                    });
+                    // A provider without a question-count cap (TypeSafe, XOR) takes
+                    // every well-formed addition; its token/byte limits still apply
+                    // and are what `decisionLimits()` reports for sizing.
+                    const room = limits?.maxQuestions !== undefined
+                        ? Math.max(0, limits.maxQuestions - ownCount)
+                        : Number.POSITIVE_INFINITY;
+                    const combined = {
+                        ...ownQuestions,
+                    };
+                    let invalidCount = 0;
+                    let overflowCount = 0;
+                    for (const [hostId, proposal] of proposedEntries) {
+                        // The wire carries a snapshot of the host's question, never the
+                        // host's object: validated as a copy, sent as that copy.
+                        const question = snapshotDecisionQuestion(proposal);
+                        if (question === undefined) {
+                            invalidCount += 1;
+                            continue;
+                        }
+                        if (hostIdByWireId.size >= room) {
+                            overflowCount += 1;
+                            continue;
+                        }
+                        const wireId = decisionKey(HOST_DECISION_NAMESPACE, hostIdByWireId.size);
+                        combined[wireId] = question;
+                        hostIdByWireId.set(wireId, hostId);
+                    }
+                    if (invalidCount > 0) {
+                        logger.warn(`[Decision] dropped ${invalidCount} malformed host question(s) for site "${site}"`);
+                    }
+                    if (overflowCount > 0 && limits) {
+                        logger.warn(`[Decision] dropped ${overflowCount} host question(s) for site "${site}": ${limits.provider} accepts ${limits.maxQuestions} per request and NeuroLink asks ${ownCount}`);
+                    }
+                    questions = combined;
+                }
+            }
+            const hostQuestionCount = hostIdByWireId.size;
+            if (this.emitter.listenerCount("decision:before") > 0) {
+                const beforeEvent = {
+                    site,
+                    state: hostFacing().state,
+                    questions: hostQuestionCount === 0
+                        ? hostFacing().questions
+                        : structuredClone(questions),
+                    hostQuestionCount,
+                    sessionId: merged.sessionId,
+                    requestId: merged.requestId,
+                };
+                this.emitDecisionEvent("decision:before", beforeEvent);
+            }
+            const startedAt = Date.now();
+            const result = await this.tryRunDecide({ ...merged, questions });
+            obtained = result;
+            // Null-prototype maps: a host id such as `__proto__` or `constructor`
+            // must land as an own key, not fall into the prototype and vanish.
+            const ownAnswers = Object.create(null);
+            const hostAnswers = Object.create(null);
+            if (result) {
+                for (const [id, answer] of Object.entries(result.answers)) {
+                    const hostId = hostIdByWireId.get(id);
+                    if (hostId === undefined) {
+                        ownAnswers[id] = answer;
+                    }
+                    else {
+                        hostAnswers[hostId] = answer;
+                    }
+                }
+            }
+            // Everything host-facing — the event and the hook — gets its own copy,
+            // so a listener that edits an answer cannot change what NeuroLink's
+            // consumer reads from the same call.
+            const hostFacingResult = result ? structuredClone(result) : null;
+            const afterEvent = {
+                site,
+                answers: structuredClone(ownAnswers),
+                hostAnswers: structuredClone(hostAnswers),
+                latencyMs: result?.latencyMs ?? Date.now() - startedAt,
+                provider: result?.provider ??
+                    this.resolveDecisionProviderName(merged.provider, merged.credentials),
+                model: result?.model,
+                result: hostFacingResult,
+                sessionId: merged.sessionId,
+                requestId: merged.requestId,
+            };
+            this.emitDecisionEvent("decision:after", afterEvent);
+            if (!result || !hostFacingResult) {
+                return null;
+            }
+            if (hooks?.onAnswers) {
+                try {
+                    await withTimeout(Promise.resolve(hooks.onAnswers({
+                        ...hookContext(),
+                        answers: structuredClone(hostAnswers),
+                        result: hostFacingResult,
+                    })), hookTimeoutMs, new Error(`onAnswers exceeded ${hookTimeoutMs}ms`));
+                }
+                catch (error) {
+                    logger.warn(`[Decision] onAnswers hook failed for site "${site}"`, {
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+            // The consumer's result: untouched when nothing was added, so the
+            // no-hooks path returns the very object the provider produced.
+            return hostQuestionCount === 0
+                ? result
+                : { ...result, answers: ownAnswers };
+        }
+        catch (error) {
+            logger.warn(`[Decision] site "${site}" hook or event handling threw — ${obtained === undefined
+                ? "deciding with NeuroLink's own questions"
+                : "handing the consumer the answers already obtained"}`, { error: error instanceof Error ? error.message : String(error) });
+            if (obtained === undefined) {
+                return this.tryRunDecide(merged);
+            }
+            return obtained ? stripHostAnswers(obtained, hostIdByWireId) : null;
+        }
+    }
+    /**
+     * `decide()` proper. A request stamped with a site — every built-in
+     * consumer's, and a host-wired consumer's — adds `decision.site` and
+     * `decision.host_question_count` (the `host__N` ids the funnel namespaced)
+     * to both spans, so a trace can tell a routing decision from a compaction
+     * one and see how many questions the host rode along with.
+     */
+    async runDecide(options) {
         // SDK config counts as much as the environment: credentials given to the
         // constructor or to this call can configure a provider on their own.
-        const providerName = options.provider ??
-            resolveDefaultDecisionProvider(this.resolveCredentials(options.credentials));
+        const providerName = this.resolveDecisionProviderName(options.provider, options.credentials);
         if (!providerName) {
             throw new Error(`No decision provider is configured. Set ${describeDecisionProviderKeys()} (in the environment or in \`credentials\`), or pass \`provider\` explicitly.`);
         }
-        const questionCount = Object.keys(options.questions).length;
+        const questionIds = Object.keys(options.questions);
+        const questionCount = questionIds.length;
+        const stamped = options;
+        const siteSpanAttributes = stamped.site
+            ? {
+                "decision.site": stamped.site,
+                "decision.host_question_count": questionIds.filter(isHostDecisionKey).length,
+            }
+            : {};
         // Observability parity with generate()/stream(): an OTEL span for the
         // trace view, a serialized span for the in-process metrics aggregator,
         // and a cost figure. Without these a decision model is invisible — and
@@ -13045,6 +13873,7 @@ Current user's request: ${currentInput}`;
                 "ai.provider": providerName,
                 "decision.question_count": questionCount,
                 "decision.images.count": options.images?.length ?? 0,
+                ...siteSpanAttributes,
             },
         }, async (otelSpan) => {
             const { traceId, parentSpanId } = getActiveTraceContext();
@@ -13054,6 +13883,7 @@ Current user's request: ${currentInput}`;
                 "ai.model": options.model ?? "",
                 "decision.question_count": questionCount,
                 "decision.images.count": options.images?.length ?? 0,
+                ...siteSpanAttributes,
             }, parentSpanId, traceId);
             try {
                 // enableMCP: false — a decision model has no tools and never will.
@@ -13140,8 +13970,22 @@ Current user's request: ${currentInput}`;
      * back joined. A batch that fails costs only its own answers, which every
      * consumer already reads as "no decision"; null comes back only when every
      * batch failed. `decide()` itself stays strict and refuses an over-cap request.
+     *
+     * A request stamped with a `site` — every built-in consumer stamps its own,
+     * so a `RAGPipeline` or `ClassifierRouter` a host wired to this method gets
+     * the same treatment as NeuroLink's internal ones — also runs the host's
+     * `decisionHooks` and emits `decision:before` / `decision:after`.
      */
     async tryDecide(options) {
+        return this.siteDecide(options);
+    }
+    /**
+     * `tryDecide` without the site handling: the try/catch around the call.
+     * Dispatches through `this.decide`, so a subclass override or an instance
+     * patch on the public method sees every decision — the funnel's routing,
+     * tool routing and compaction calls included, not only a host's own.
+     */
+    async tryRunDecide(options) {
         try {
             const result = await this.decideInBatches(options);
             if (logger.shouldLog("debug")) {
@@ -14273,6 +15117,14 @@ Current user's request: ${currentInput}`;
                 cleanupErrors.push(err);
                 logger.warn("[NeuroLink] Error stopping background work:", error);
             }
+            // 0b. The memory condenser is a child instance this one created; it
+            // goes with the host.
+            try {
+                await this.releaseMemoryCondenser();
+            }
+            catch (error) {
+                cleanupErrors.push(error instanceof Error ? error : new Error(String(error)));
+            }
             // 1. Flush and shutdown OpenTelemetry
             try {
                 logger.debug("[NeuroLink] Flushing and shutting down OpenTelemetry...");
@@ -14488,11 +15340,12 @@ Current user's request: ${currentInput}`;
                     ?.summarizationProvider,
             summarizationModel: config?.summarizationModel ??
                 this.conversationMemoryConfig?.conversationMemory?.summarizationModel,
-        }, this.contextCompactorDeps());
+        }, this.contextCompactorDeps({ sessionId }));
         // Use actual context window to determine target, not arbitrary heuristic
         const budgetInfo = checkContextBudget({
             provider: config?.provider || "openai",
             conversationMessages: messages,
+            toolReplayMode: this.resolveToolReplayModeForBudget({}),
         });
         // Target 60% of available input tokens — leave room for new messages
         const targetTokens = Math.floor(budgetInfo.availableInputTokens * 0.6);
@@ -14518,6 +15371,7 @@ Current user's request: ${currentInput}`;
             provider: provider || "openai",
             model,
             conversationMessages: messages,
+            toolReplayMode: this.resolveToolReplayModeForBudget({}),
         });
         return {
             estimatedInputTokens: budgetResult.estimatedInputTokens,
@@ -14542,6 +15396,7 @@ Current user's request: ${currentInput}`;
             provider: provider || "openai",
             model,
             conversationMessages: session.messages,
+            toolReplayMode: this.resolveToolReplayModeForBudget({}),
         });
         return budgetResult.shouldCompact;
     }