@juspay/neurolink 12.47.14 → 12.48.1

package/dist/neurolink.d.ts

@@ -5,7 +5,7 @@
  * Enhanced AI provider system with natural MCP tool access.
  * Uses real MCP infrastructure for tool discovery and execution.
  */
-import type { DecisionOptions, DecisionResult, AgentDefinition, AgentNetworkConfig, AgentRunOptions, AgentRunOutcome, AgentToolRegistrationOptions, IsolatedAgentDefinition, NetworkExecutionInput, NetworkExecutionOptions, NetworkExecutionResult, NetworkStreamChunk, WorkerInstanceOptions } from "./types/index.js";
+import type { DecisionCallerOptions, DecisionLimitsQuery, DecisionLimitsReading, DecisionOptions, DecisionResult, AgentDefinition, AgentNetworkConfig, AgentRunOptions, AgentRunOutcome, AgentToolRegistrationOptions, IsolatedAgentDefinition, NetworkExecutionInput, NetworkExecutionOptions, NetworkExecutionResult, NetworkStreamChunk, WorkerInstanceOptions } from "./types/index.js";
 import type { CompactionConfig, CompactionResult, ArtifactStore, SpanData, ObservabilityConfig, MetricsSummary, MCPToolAnnotations, TraceView, AuthenticatedContext, AuthProvider, JsonObject, NeuroLinkEvents, TypedEventEmitter, MCPEnhancementsConfig, NeuroLinkAuthConfig, NeurolinkConstructorConfig, ChatMessage, ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPToolInfo, GenerateOptions, GenerateResult, ProviderStatus, TextGenerationOptions, TextGenerationResult, MCPExecutableTool, MCPServerInfo, MCPStatus, StreamOptions, StreamResult, ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions, BatchOperationResult, StreamGenerationEndContext, ToolRoutingServerDescriptor, ToolDedupConfig, ToolConfig, KnowledgeEngineStatus, ChecklistState, ArtifactPageRequest, BankArtifactOptions, BankedArtifactRef, DelegateCollectRequest, DelegateCollectResult, DelegateHandle, DelegateRegistrationOptions, DelegateSpawnOptions, BackgroundCommandHandle, BackgroundCommandOptions, BackgroundCommandOutputPage, BackgroundCommandPageRequest, BackgroundCommandPolicy, BackgroundCommandStatus, GitToolResult, GitToolsetOptions } from "./types/index.js";
 import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import type { RedisConversationMemoryManager } from "./core/redisConversationMemoryManager.js";
@@ -173,6 +173,7 @@ export declare class NeuroLink {
     private readonly requestRouter;
     private readonly classifierRouter;
     private readonly contextRelevanceOptions;
+    private readonly decisionHooks;
     /**
      * Merge instance-level credentials with per-call credentials.
      *
@@ -199,6 +200,38 @@ export declare class NeuroLink {
     private cachedFileTools;
     private memoryInstance?;
     private 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.
+     */
+    private 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.
+     */
+    private 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.
+     */
+    private memoryCondenserReleased;
+    /**
+     * 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.
+     */
+    private readonly pendingMemoryWrites;
+    /** Prompt templates already warned about, so a per-call template warns once. */
+    private readonly warnedCondensationPrompts;
+    /** `decisionHooks.hookTimeoutMs` once validated; see `decisionHookTimeout`. */
+    private decisionHookTimeoutMs?;
     private skillsManagerInstance?;
     private skillsConfig?;
     /**
@@ -212,6 +245,47 @@ export declare class NeuroLink {
     private applyGenerateLifecycleMiddleware;
     private applyStreamLifecycleMiddleware;
     private initializeMemoryConfig;
+    /**
+     * A `generate()`-only handle whose backing NeuroLink is constructed on the
+     * first condensation call, not when memory is configured or first read.
+     */
+    private lazyMemoryCondenserInstance;
+    /**
+     * 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.
+     */
+    private releaseMemoryCondenser;
+    /**
+     * 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.
+     */
+    private drainPendingMemoryWrites;
+    private warnMemoryWritesLeftInFlight;
+    /**
+     * 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.
+     */
+    private getMemoryCondenser;
     /**
      * Lazy initialization for memory — called during generate/stream.
      */
@@ -324,6 +398,23 @@ export declare class NeuroLink {
      * Initialize conversation memory if enabled
      */
     private initializeConversationMemory;
+    /**
+     * 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".
+     */
+    private validateInstanceCondensationPrompt;
     /**
      * Initialize HITL (Human-in-the-Loop) if enabled
      */
@@ -427,10 +518,26 @@ export declare class NeuroLink {
      * Returns the input text enhanced with memory context, or unchanged if no memory.
      */
     private retrieveMemory;
+    /**
+     * 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.
+     */
+    private resolveMemoryAddOptions;
     /**
      * 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.
+     *
+     * 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.
      */
     private storeMemoryInBackground;
     /**
@@ -845,11 +952,20 @@ export declare class NeuroLink {
     /**
      * 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.
      */
     private contextCompactorDeps;
+    /**
+     * 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`.
+     */
+    private decisionSiteContext;
     /**
      * Applies the host-configured `classifierRouter` to `options` in place.
      *
@@ -978,6 +1094,22 @@ export declare class NeuroLink {
     private tryMCPGeneration;
     private prepareMCPGenerationContext;
     private logMCPConversationSummary;
+    /**
+     * 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").
+     */
+    private resolveToolReplayModeForBudget;
     private ensureMCPGenerationBudget;
     private compactMCPConversationForBudget;
     private generateWithMCPProvider;
@@ -2431,6 +2563,111 @@ export declare class NeuroLink {
      * @throws when no decision provider is configured, or the call fails
      */
     decide(options: DecisionOptions): Promise<DecisionResult>;
+    /**
+     * 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.
+     */
+    private resolveDecisionProviderName;
+    /**
+     * 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.
+     */
+    private registeredDecisionModel;
+    /**
+     * 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?: DecisionLimitsQuery): DecisionLimitsReading | null;
+    /**
+     * `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.
+     */
+    private decisionHookTimeout;
+    /**
+     * `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.
+     */
+    private emitDecisionEvent;
+    /**
+     * 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.
+     */
+    private siteDecide;
+    /**
+     * `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.
+     */
+    private runDecide;
     /**
      * Fail-open {@link NeuroLink.decide}: returns null on any failure instead
      * of throwing.
@@ -2445,8 +2682,20 @@ export declare class NeuroLink {
      * 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`.
+     */
+    tryDecide(options: DecisionCallerOptions): Promise<DecisionResult | null>;
+    /**
+     * `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.
      */
-    tryDecide(options: DecisionOptions): Promise<DecisionResult | null>;
+    private tryRunDecide;
     /**
      * One `decide()` call, or, when the question map is longer than the resolved
      * provider's cap, several run a few at a time with their results joined. The