@juspay/neurolink 12.47.14 → 12.48.0

package/dist/providers/systemOneDecision.d.ts

@@ -133,6 +133,12 @@ export declare abstract class SystemOneDecisionProvider extends BaseProvider {
      * Refuse a request the model cannot read in full. An encoder cuts the state
      * off past its window without saying so, so without this a decision would
      * be made on input the model never saw — and reported as if it had.
+     *
+     * Advisory limits (`decisionLimits.advisory`) are skipped: they publish a
+     * server's own ceiling for `NeuroLink.decisionLimits()` to report, and the
+     * server enforces them itself. The estimator and the flattening are the
+     * same functions that method uses, so a host that sizes a state against the
+     * reading measures exactly what is checked here.
      */
     private assertWithinDecisionLimits;
     /**

package/dist/providers/systemOneDecision.js

@@ -6,7 +6,7 @@ import { ProviderError } from "../types/index.js";
 import { prepareDecisionMedia } from "../utils/decisionMedia.js";
 import { logger } from "../utils/logger.js";
 import { redactUrlsInText } from "../utils/logSanitize.js";
-import { CHARS_PER_TOKEN, estimateTokens, serializeForEstimate, } from "../utils/tokenEstimation.js";
+import { estimateDecisionStateTokens, resolveDecisionLimitsReading, } from "../utils/decisionLimits.js";
 /**
  * Generous enough for a cold start (measured at 2.0–2.7s after idle on Jev)
  * while still bounded. Every internal caller is fail-open, so this only bites
@@ -171,59 +171,6 @@ const sleep = (ms, signal) => new Promise((resolve, reject) => {
     }
     signal?.addEventListener("abort", onAbort, { once: true });
 });
-/**
- * `estimateTokens` assumes ~4 characters per token. That holds for English
- * and is several times too generous for other scripts on an English
- * tokenizer, so when a provider declares a rate, non-ASCII characters are
- * counted at it instead. ASCII text is estimated exactly as before.
- */
-function estimateDecisionStateTokens(text, nonAsciiTokensPerChar, rates = {}) {
-    const { digit, symbol, astral } = rates;
-    if (nonAsciiTokensPerChar === undefined &&
-        digit === undefined &&
-        symbol === undefined &&
-        astral === undefined) {
-        return estimateTokens(text);
-    }
-    // Each class of character is counted once, at its own rate. A class with no
-    // declared rate stays in the ordinary four-characters-a-token estimate (or,
-    // for non-ASCII, at that estimate's per-character rate), so a provider that
-    // declares none of the extra rates is estimated exactly as before.
-    const isDigit = (c) => c >= "0" && c <= "9";
-    const isSymbol = (c) => /[!-/:-@[-`{-~]/.test(c);
-    let digits = 0;
-    let symbols = 0;
-    let astrals = 0;
-    let nonAscii = 0;
-    const rest = [];
-    for (const c of text) {
-        const code = c.codePointAt(0) ?? 0;
-        if (code > 0xffff && astral !== undefined) {
-            astrals += 1;
-        }
-        else if (code > 0x7f) {
-            nonAscii += 1;
-        }
-        else if (digit !== undefined && isDigit(c)) {
-            digits += 1;
-        }
-        else if (symbol !== undefined && isSymbol(c)) {
-            symbols += 1;
-        }
-        else {
-            rest.push(c);
-        }
-    }
-    // Digits, punctuation and astral characters (emoji) are charged separately
-    // only when the provider declares a rate for them: a tokenizer that reads each
-    // digit, and most punctuation, on its own makes a number-heavy or JSON-heavy
-    // state several times longer than four characters a token suggests.
-    return (estimateTokens(rest.join("")) +
-        Math.ceil(digits * (digit ?? 0)) +
-        Math.ceil(symbols * (symbol ?? 0)) +
-        Math.ceil(astrals * (astral ?? 0)) +
-        Math.ceil(nonAscii * (nonAsciiTokensPerChar ?? 1 / CHARS_PER_TOKEN)));
-}
 /**
  * The shared half of every "System One" decision provider — a model that takes
  * one `state` plus typed questions and returns one typed answer each, with no
@@ -551,10 +498,19 @@ export class SystemOneDecisionProvider extends BaseProvider {
      * Refuse a request the model cannot read in full. An encoder cuts the state
      * off past its window without saying so, so without this a decision would
      * be made on input the model never saw — and reported as if it had.
+     *
+     * Advisory limits (`decisionLimits.advisory`) are skipped: they publish a
+     * server's own ceiling for `NeuroLink.decisionLimits()` to report, and the
+     * server enforces them itself. The estimator and the flattening are the
+     * same functions that method uses, so a host that sizes a state against the
+     * reading measures exactly what is checked here.
      */
     assertWithinDecisionLimits(request, model, questionCount) {
-        const limits = PROVIDER_DESCRIPTORS_BY_NAME.get(this.providerName)?.decisionLimits;
-        if (!limits) {
+        const descriptor = PROVIDER_DESCRIPTORS_BY_NAME.get(this.providerName);
+        const limits = descriptor
+            ? resolveDecisionLimitsReading(descriptor, model)
+            : null;
+        if (!limits || !limits.enforcedLocally) {
             return;
         }
         const label = this.vendorLabel();
@@ -566,13 +522,8 @@ export class SystemOneDecisionProvider extends BaseProvider {
                 retryable: false,
             });
         }
-        const modelLimits = limits.models?.[model];
-        const maxStateTokens = modelLimits?.maxStateTokens ?? limits.maxStateTokens;
-        const stateTokens = estimateDecisionStateTokens(serializeForEstimate(request.state), modelLimits?.nonAsciiTokensPerChar ?? limits.nonAsciiTokensPerChar, {
-            digit: limits.digitTokensPerChar,
-            symbol: limits.symbolTokensPerChar,
-            astral: limits.astralTokensPerChar,
-        });
+        const { maxStateTokens } = limits;
+        const stateTokens = estimateDecisionStateTokens(request.state, limits);
         if (stateTokens > maxStateTokens) {
             throw this.decisionError({
                 kind: "max_tokens_exceeded",

package/dist/providers/typesafe.d.ts

@@ -4,6 +4,12 @@ import { SystemOneDecisionProvider } from "./systemOneDecision.js";
  * The binding limit in practice: `state` plus the SINGLE LONGEST question.
  * Measured by bisection at single-character resolution — 33,002 reported
  * input tokens accepted, 33,003 not.
+ *
+ * The same figure sits on the TypeSafe descriptor as an ADVISORY
+ * `decisionLimits.maxStateTokens`, which is what `NeuroLink.decisionLimits()`
+ * reads; the server enforces it, NeuroLink only reports it. The descriptor
+ * cannot import this constant without a cycle, so the decide suite pins them
+ * equal instead.
  */
 export declare const TYPESAFE_MAX_STATE_TOKENS = 33000;
 /**

package/dist/providers/typesafe.js

@@ -27,6 +27,12 @@ const GATEWAY_SPEC_VERSION = "4";
  * The binding limit in practice: `state` plus the SINGLE LONGEST question.
  * Measured by bisection at single-character resolution — 33,002 reported
  * input tokens accepted, 33,003 not.
+ *
+ * The same figure sits on the TypeSafe descriptor as an ADVISORY
+ * `decisionLimits.maxStateTokens`, which is what `NeuroLink.decisionLimits()`
+ * reads; the server enforces it, NeuroLink only reports it. The descriptor
+ * cannot import this constant without a cycle, so the decide suite pins them
+ * equal instead.
  */
 export const TYPESAFE_MAX_STATE_TOKENS = 33_000;
 /**

package/dist/rag/retrieval/searchDecision.js

@@ -75,6 +75,7 @@ export async function decideSearchPlan(query, decide, capabilities) {
         };
     }
     const result = await decide({
+        site: "ragPlan",
         state: { query: query.slice(0, 4000) },
         // The map is assembled dynamically above; its members are all valid
         // question shapes, which the cast asserts once here rather than at four

package/dist/routing/classifierRouter.js

@@ -98,7 +98,7 @@ export class ClassifierRouter {
         try {
             // Both the LLM and Jev strategies can pick a model straight out of the
             // pool — the generic path for custom/registry-less models.
-            const strategy = this.resolveStrategy();
+            const strategy = this.resolveStrategy(input);
             const usesCandidates = (strategy === "jev" && !!this.deps.decide) ||
                 (strategy === "llm" && !!this.deps.generate);
             const built = usesCandidates ? this.buildCandidates() : undefined;
@@ -138,7 +138,7 @@ export class ClassifierRouter {
      * moment a decision provider is configured; without one the behaviour is
      * exactly what it was before Jev existed.
      */
-    resolveStrategy() {
+    resolveStrategy(input) {
         const configured = this.config.classifier ?? "auto";
         if (configured !== "auto") {
             return configured;
@@ -146,10 +146,11 @@ export class ClassifierRouter {
         // A decision provider that is both registered AND configured is the whole
         // activation condition — this is where "if somebody sets it we start
         // using it" lives for routing. The caller's check also counts the
-        // credentials it was constructed with.
+        // credentials it was constructed with and the request's own per-call
+        // credentials, which the decision call itself will use.
         const hasProvider = this.deps.hasDecisionProvider
-            ? this.deps.hasDecisionProvider()
-            : resolveDefaultDecisionProvider() !== undefined;
+            ? this.deps.hasDecisionProvider(input.credentials)
+            : resolveDefaultDecisionProvider(input.credentials) !== undefined;
         return this.deps.decide && hasProvider ? "jev" : "heuristic";
     }
     /** Run the chosen strategy; every one falls back to heuristic on failure. */

package/dist/routing/classifierStrategies.js

@@ -297,8 +297,15 @@ export async function classifyJev(input, decide, timeoutMs, candidates, threshol
     // short conversational one.
     // Continuity is sent as `session_bound` / `prior_messages`, never as the
     // raw sessionId: the id is an opaque identifier that tells a third-party
-    // model nothing, so it stays in-process.
+    // model nothing, so it stays in-process — as do the site stamp, the
+    // per-call credentials and the ids below, which the caller reads and the
+    // wire never sees.
     const result = await decide({
+        site: "routing",
+        credentials: input.credentials,
+        signal: input.signal,
+        sessionId: input.sessionId,
+        requestId: input.requestId,
         state: {
             request: (input.prompt ?? "").slice(0, 8000),
             estimated_input_tokens: input.estimatedInputTokens ?? 0,

package/dist/types/classifierRouter.d.ts

@@ -15,6 +15,7 @@
  */
 import type { ValidationSchema } from "./aliases.js";
 import type { DecisionCallerFn } from "./decision.js";
+import type { NeurolinkCredentials } from "./providers.js";
 /** Coarse difficulty buckets the classifier maps a request into. */
 export type ClassifierDifficulty = "trivial" | "simple" | "moderate" | "hard" | "expert";
 /**
@@ -307,6 +308,16 @@ export type ClassifierRouterInput = {
     sessionBound?: boolean;
     /** Number of prior conversation messages the caller supplied, when known. */
     priorMessageCount?: number;
+    /**
+     * The outer request's per-call credentials, forwarded to the decision call
+     * so it reaches the caller's provider account rather than the instance's.
+     * Never part of the state sent to the model.
+     */
+    credentials?: NeurolinkCredentials;
+    /** The outer request's abort signal; an abandoned turn abandons its routing call. */
+    signal?: AbortSignal;
+    /** The outer request's id, for hook and event correlation. Never sent to the model. */
+    requestId?: string;
 };
 /** Enriched per-model metadata used while ranking pool members. */
 export type ClassifierModelMeta = {
@@ -359,9 +370,11 @@ export type ClassifierRouterDeps = {
     decide?: ClassifierDecideFn;
     /**
      * Whether a decision provider is configured for this caller, counting the
-     * credentials it was given as well as the environment. Omit to check the
-     * environment alone.
+     * credentials it was given as well as the environment — and the request's
+     * own per-call `credentials`, passed in from `ClassifierRouterInput`, so a
+     * caller that holds no decision key itself can still route a request that
+     * carries one. Omit to check the environment alone.
      */
-    hasDecisionProvider?: () => boolean;
+    hasDecisionProvider?: (callCredentials?: NeurolinkCredentials) => boolean;
     logger?: ClassifierLogger;
 };

package/dist/types/common.d.ts

@@ -102,6 +102,8 @@ export type NeuroLinkEvents = {
     "stream:error": unknown;
     "generation:start": unknown;
     "generation:end": unknown;
+    "decision:before": unknown;
+    "decision:after": unknown;
     "response:start": unknown;
     "response:end": unknown;
     "externalMCP:serverConnected": unknown;

package/dist/types/config.d.ts

@@ -14,6 +14,7 @@ import type { ModelPoolConfig } from "./modelPool.js";
 import type { RequestRouter } from "./requestRouter.js";
 import type { ClassifierRouterConfig } from "./classifierRouter.js";
 import type { ContextRelevanceOptions } from "./context.js";
+import type { DecisionHooks } from "./decision.js";
 import type { SkillsConfig } from "./skills.js";
 import type { KnowledgeGroundingConfig } from "./knowledge.js";
 /**
@@ -155,6 +156,14 @@ export type NeurolinkConstructorConfig = {
      * which is the same activation rule every other decision consumer uses.
      */
     contextRelevance?: ContextRelevanceOptions;
+    /**
+     * Ride along on the decision calls NeuroLink already makes for routing,
+     * tool routing, compaction and RAG planning: add your own questions to the
+     * same round trip and read the answers back. Observe-only with respect to
+     * NeuroLink's behaviour, fail-open, and inert until a decision provider is
+     * configured. See {@link DecisionHooks}.
+     */
+    decisionHooks?: DecisionHooks;
     /**
      * Native skills: versioned, discoverable instruction packs (SOPs,
      * playbooks) with progressive disclosure. When enabled, each

package/dist/types/context.d.ts

@@ -4,7 +4,7 @@
  */
 import type { ExecutionContext } from "../types/tools.js";
 import type { JsonObject } from "./common.js";
-import type { ChatMessage, ConversationMemoryConfig } from "./conversation.js";
+import type { ChatMessage, ConversationMemoryConfig, ToolReplayMode } from "./conversation.js";
 import type { DecisionCallerFn } from "./decision.js";
 /**
  * Base context type for all AI operations
@@ -237,6 +237,13 @@ export type BudgetCheckParams = {
     }>;
     /** Compaction trigger threshold (0.0-1.0). Default: 0.80 */
     compactionThreshold?: number;
+    /**
+     * How this request replays stored `tool_call` / `tool_result` rows
+     * (`replayToolSteps`). When set, tool rows are estimated at the size they
+     * reach the model in that mode rather than at stored size; when omitted
+     * they count at stored size.
+     */
+    toolReplayMode?: ToolReplayMode;
 };
 /** A file prepared for potential summarization. */
 export type FileForSummarization = {

package/dist/types/conversation.d.ts

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

package/dist/types/decision.d.ts

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

package/dist/types/decision.js

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