@juspay/neurolink 12.47.13 → 12.48.0

package/dist/utils/decisionAnswers.d.ts

@@ -7,7 +7,7 @@
  *
  * @module utils/decisionAnswers
  */
-import type { DecisionAnswerMap, DecisionBooleanGate, DecisionChoiceReading, DecisionScoreReading, ProviderDescriptor } from "../types/index.js";
+import type { DecisionAnswerMap, DecisionBooleanGate, DecisionChoiceReading, DecisionQuestion, DecisionResult, DecisionScoreReading, ProviderDescriptor } from "../types/index.js";
 /**
  * Read a yes/no answer as a probability.
  *
@@ -54,3 +54,33 @@ export declare function gateDecisionBoolean(answers: DecisionAnswerMap, id: stri
  * after any normalisation the wire might apply.
  */
 export declare function decisionKey(namespace: string, index: number): string;
+/** Namespace for questions a host adds through `decisionHooks.extendQuestions`. */
+export declare const HOST_DECISION_NAMESPACE = "host";
+/** Whether a wire id is one the funnel gave a host's question (`host__N`). */
+export declare function isHostDecisionKey(id: string): boolean;
+/**
+ * A validated copy of a question a host handed back from `extendQuestions`,
+ * or undefined when it is malformed or cannot be copied. The wire carries
+ * the copy, never the host's object: a getter, a proxy or a later edit on
+ * the host's side can then reach neither the request nor the answers keyed
+ * on it. A value `structuredClone` refuses (a proxy, a function-valued
+ * field, a throwing getter) is treated as malformed.
+ */
+export declare function snapshotDecisionQuestion(value: unknown): DecisionQuestion | undefined;
+/**
+ * `result` without the answers to a host's namespaced questions — what a
+ * consumer is handed when the funnel's host-facing steps failed after the
+ * wire call had already returned. A null-prototype map, so an own id such
+ * as `__proto__` survives the copy.
+ */
+export declare function stripHostAnswers(result: DecisionResult, hostIdByWireId: ReadonlyMap<string, string>): DecisionResult;
+/**
+ * Runtime check that a value from outside the type system — a host's
+ * `extendQuestions` hook — is a well-formed question, so a malformed one
+ * is dropped on its own rather than failing the whole request that
+ * NeuroLink's own routing depends on.
+ *
+ * A `choice` needs at least two options and a `score` at least two levels;
+ * fewer carries no information, and the servers refuse it anyway.
+ */
+export declare function isDecisionQuestion(value: unknown): value is DecisionQuestion;

package/dist/utils/decisionAnswers.js

@@ -93,3 +93,117 @@ export function gateDecisionBoolean(answers, id, gate) {
 export function decisionKey(namespace, index) {
     return `${namespace}__${index}`;
 }
+/** Namespace for questions a host adds through `decisionHooks.extendQuestions`. */
+export const HOST_DECISION_NAMESPACE = "host";
+/** Whether a wire id is one the funnel gave a host's question (`host__N`). */
+export function isHostDecisionKey(id) {
+    return id.startsWith(`${HOST_DECISION_NAMESPACE}__`);
+}
+/**
+ * A validated copy of a question a host handed back from `extendQuestions`,
+ * or undefined when it is malformed or cannot be copied. The wire carries
+ * the copy, never the host's object: a getter, a proxy or a later edit on
+ * the host's side can then reach neither the request nor the answers keyed
+ * on it. A value `structuredClone` refuses (a proxy, a function-valued
+ * field, a throwing getter) is treated as malformed.
+ */
+export function snapshotDecisionQuestion(value) {
+    let copy;
+    try {
+        copy = structuredClone(value);
+    }
+    catch {
+        return undefined;
+    }
+    return isDecisionQuestion(copy) ? copy : undefined;
+}
+/**
+ * `result` without the answers to a host's namespaced questions — what a
+ * consumer is handed when the funnel's host-facing steps failed after the
+ * wire call had already returned. A null-prototype map, so an own id such
+ * as `__proto__` survives the copy.
+ */
+export function stripHostAnswers(result, hostIdByWireId) {
+    if (hostIdByWireId.size === 0) {
+        return result;
+    }
+    const answers = Object.create(null);
+    for (const [id, answer] of Object.entries(result.answers)) {
+        if (!hostIdByWireId.has(id)) {
+            answers[id] = answer;
+        }
+    }
+    return { ...result, answers };
+}
+const isRecordValue = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Whether `value` is something a decision model accepts as content: a
+ * string, number or boolean, or an array or plain object of the same.
+ * `null` and `undefined` are not — a question with no instructions is
+ * refused by every provider.
+ */
+function isDecisionInput(value) {
+    switch (typeof value) {
+        case "string":
+        case "boolean":
+            return true;
+        case "number":
+            // NaN and ±Infinity serialise to null and would make the provider
+            // reject the whole request, not just this question.
+            return Number.isFinite(value);
+        case "object":
+            if (value === null) {
+                return false;
+            }
+            return Array.isArray(value)
+                ? value.every(isDecisionInput)
+                : Object.values(value).every(isDecisionInput);
+        default:
+            return false;
+    }
+}
+/**
+ * Runtime check that a value from outside the type system — a host's
+ * `extendQuestions` hook — is a well-formed question, so a malformed one
+ * is dropped on its own rather than failing the whole request that
+ * NeuroLink's own routing depends on.
+ *
+ * A `choice` needs at least two options and a `score` at least two levels;
+ * fewer carries no information, and the servers refuse it anyway.
+ */
+export function isDecisionQuestion(value) {
+    try {
+        return isWellFormedDecisionQuestion(value);
+    }
+    catch {
+        // Cyclic or otherwise exotic host input: the walk below can overflow the
+        // stack. That drops this question alone rather than failing the request.
+        return false;
+    }
+}
+function isWellFormedDecisionQuestion(value) {
+    if (!isRecordValue(value) || !isDecisionInput(value.instructions)) {
+        return false;
+    }
+    switch (value.type) {
+        case "boolean": {
+            if (value.criteria === undefined) {
+                return true;
+            }
+            if (!isRecordValue(value.criteria)) {
+                return false;
+            }
+            return Object.values(value.criteria).every((side) => side === null || side === undefined || isDecisionInput(side));
+        }
+        case "choice":
+            return (isRecordValue(value.criteria) &&
+                Object.keys(value.criteria).length >= 2 &&
+                Object.values(value.criteria).every((rubric) => rubric === null || isDecisionInput(rubric)));
+        case "score":
+            return (Array.isArray(value.criteria) &&
+                value.criteria.length >= 2 &&
+                value.criteria.every((level) => level === null || isDecisionInput(level)));
+        default:
+            return false;
+    }
+}

package/dist/utils/decisionLimits.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Decision limits — the one place a provider's `decisionLimits` are read and
+ * a state's size is estimated against them.
+ *
+ * `SystemOneDecisionProvider` refuses an over-limit request through these
+ * functions, and `NeuroLink.decisionLimits()` / `estimateDecisionStateTokens`
+ * expose the same functions to hosts, so what a host measures before the call
+ * is exactly what the pre-flight check measures inside it. Two estimators that
+ * drift apart would let a host size a state as fitting and then watch it be
+ * refused.
+ *
+ * @module utils/decisionLimits
+ */
+import type { DecisionLimits, DecisionLimitsReading, DecisionState, ProviderDescriptor } from "../types/index.js";
+/**
+ * Estimate how many tokens a decision model will read from `state`.
+ *
+ * `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 the limits declare a `nonAsciiTokensPerChar` rate,
+ * non-ASCII characters are counted at it instead. Digits, ASCII punctuation
+ * and astral characters (emoji) are each counted separately only when the
+ * limits declare a rate for that class — a tokenizer that reads each digit,
+ * and most punctuation, on its own makes a number-heavy or JSON-heavy state
+ * several times longer than the ~4-characters-per-token estimate suggests. A
+ * non-string state is serialized first, as it is on the wire.
+ *
+ * This is the estimator the pre-flight refusal uses: a state this reports at
+ * or under `maxStateTokens` is sent, one over it is refused before any
+ * network call.
+ */
+export declare function estimateDecisionStateTokens(state: DecisionState, limits?: Pick<DecisionLimits, "nonAsciiTokensPerChar" | "digitTokensPerChar" | "symbolTokensPerChar" | "astralTokensPerChar">): number;
+/**
+ * Flatten a descriptor's `decisionLimits` for one model: the per-model entry
+ * overrides the base, field by field, and `advisory` becomes
+ * `enforcedLocally: false`. Returns null for a descriptor that declares no
+ * limits.
+ */
+export declare function resolveDecisionLimitsReading(descriptor: Pick<ProviderDescriptor, "name" | "decisionLimits">, model: string): DecisionLimitsReading | null;

package/dist/utils/decisionLimits.js

@@ -0,0 +1,116 @@
+/**
+ * Decision limits — the one place a provider's `decisionLimits` are read and
+ * a state's size is estimated against them.
+ *
+ * `SystemOneDecisionProvider` refuses an over-limit request through these
+ * functions, and `NeuroLink.decisionLimits()` / `estimateDecisionStateTokens`
+ * expose the same functions to hosts, so what a host measures before the call
+ * is exactly what the pre-flight check measures inside it. Two estimators that
+ * drift apart would let a host size a state as fitting and then watch it be
+ * refused.
+ *
+ * @module utils/decisionLimits
+ */
+import { CHARS_PER_TOKEN, estimateTokens, serializeForEstimate, } from "./tokenEstimation.js";
+/**
+ * Estimate how many tokens a decision model will read from `state`.
+ *
+ * `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 the limits declare a `nonAsciiTokensPerChar` rate,
+ * non-ASCII characters are counted at it instead. Digits, ASCII punctuation
+ * and astral characters (emoji) are each counted separately only when the
+ * limits declare a rate for that class — a tokenizer that reads each digit,
+ * and most punctuation, on its own makes a number-heavy or JSON-heavy state
+ * several times longer than the ~4-characters-per-token estimate suggests. A
+ * non-string state is serialized first, as it is on the wire.
+ *
+ * This is the estimator the pre-flight refusal uses: a state this reports at
+ * or under `maxStateTokens` is sent, one over it is refused before any
+ * network call.
+ */
+export function estimateDecisionStateTokens(state, limits) {
+    const text = serializeForEstimate(state);
+    const nonAsciiTokensPerChar = limits?.nonAsciiTokensPerChar;
+    const digit = limits?.digitTokensPerChar;
+    const symbol = limits?.symbolTokensPerChar;
+    const astral = limits?.astralTokensPerChar;
+    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);
+        }
+    }
+    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)));
+}
+/**
+ * Flatten a descriptor's `decisionLimits` for one model: the per-model entry
+ * overrides the base, field by field, and `advisory` becomes
+ * `enforcedLocally: false`. Returns null for a descriptor that declares no
+ * limits.
+ */
+export function resolveDecisionLimitsReading(descriptor, model) {
+    const limits = descriptor.decisionLimits;
+    if (!limits) {
+        return null;
+    }
+    const modelLimits = limits.models?.[model];
+    const nonAsciiTokensPerChar = modelLimits?.nonAsciiTokensPerChar ?? limits.nonAsciiTokensPerChar;
+    return {
+        provider: descriptor.name,
+        model,
+        maxStateTokens: modelLimits?.maxStateTokens ?? limits.maxStateTokens,
+        // Absent for a provider that caps by tokens or bytes rather than by
+        // question count (TypeSafe, XOR).
+        ...(limits.maxQuestions !== undefined
+            ? { maxQuestions: limits.maxQuestions }
+            : {}),
+        ...(nonAsciiTokensPerChar !== undefined ? { nonAsciiTokensPerChar } : {}),
+        // Not model-overridable — `models` only carries `maxStateTokens` and
+        // `nonAsciiTokensPerChar` — so these three come from the base limits only.
+        ...(limits.digitTokensPerChar !== undefined
+            ? { digitTokensPerChar: limits.digitTokensPerChar }
+            : {}),
+        ...(limits.symbolTokensPerChar !== undefined
+            ? { symbolTokensPerChar: limits.symbolTokensPerChar }
+            : {}),
+        ...(limits.astralTokensPerChar !== undefined
+            ? { astralTokensPerChar: limits.astralTokensPerChar }
+            : {}),
+        ...(limits.media !== undefined ? { media: limits.media } : {}),
+        enforcedLocally: limits.advisory !== true,
+    };
+}

package/dist/utils/logger.d.ts

@@ -30,6 +30,12 @@ declare class NeuroLinkLogger {
      * @param emitter - The event emitter instance
      */
     setEventEmitter(emitter: LogEventEmitter): void;
+    /**
+     * The process-wide sink currently receiving log events, or undefined when
+     * none is set. Lets code that must construct an instance without changing
+     * the sink capture it beforehand and put it back afterwards.
+     */
+    getEventEmitter(): LogEventEmitter | undefined;
     /**
      * Clears the event emitter reference.
      * Should be called when a NeuroLink instance is disposed to prevent memory
@@ -279,6 +285,7 @@ export declare const logger: {
     getLogs: (level?: LogLevel) => LogEntry[];
     clearLogs: () => void;
     setEventEmitter: (emitter: LogEventEmitter) => void;
+    getEventEmitter: () => LogEventEmitter | undefined;
     clearEventEmitter: (ifEmitter?: LogEventEmitter) => void;
     runInInstanceScope: <T>(instanceId: string, fn: () => T) => T;
     getInstanceScope: () => string | undefined;

package/dist/utils/logger.js

@@ -113,6 +113,14 @@ class NeuroLinkLogger {
     setEventEmitter(emitter) {
         this.eventEmitter = emitter;
     }
+    /**
+     * The process-wide sink currently receiving log events, or undefined when
+     * none is set. Lets code that must construct an instance without changing
+     * the sink capture it beforehand and put it back afterwards.
+     */
+    getEventEmitter() {
+        return this.eventEmitter;
+    }
     /**
      * Clears the event emitter reference.
      * Should be called when a NeuroLink instance is disposed to prevent memory
@@ -634,6 +642,7 @@ export const logger = {
     getLogs: (level) => neuroLinkLogger.getLogs(level),
     clearLogs: () => neuroLinkLogger.clearLogs(),
     setEventEmitter: (emitter) => neuroLinkLogger.setEventEmitter(emitter),
+    getEventEmitter: () => neuroLinkLogger.getEventEmitter(),
     clearEventEmitter: (ifEmitter) => neuroLinkLogger.clearEventEmitter(ifEmitter),
     // Per-instance routing (see NeuroLinkLogger.runInInstanceScope)
     runInInstanceScope: (instanceId, fn) => neuroLinkLogger.runInInstanceScope(instanceId, fn),

package/dist/utils/messageBuilder.d.ts

@@ -1,10 +1,47 @@
 import type { GenerateOptions, MultimodalChatMessage, StreamOptions, TextGenerationOptions, VisionImageOutputFormat } from "../types/index.js";
-import type { ModelMessage } from "../types/index.js";
+import type { ModelMessage, ToolHistoryRow, ToolReplayMode } from "../types/index.js";
 /**
  * Type-safe conversion from MultimodalChatMessage[] to ModelMessage[]
  * Filters out invalid content and ensures strict ModelMessage contract compliance
  */
 export declare function convertToModelMessages(messages: MultimodalChatMessage[]): ModelMessage[];
+/**
+ * Resolve the replay mode for a request: the per-request option, else the
+ * default. The instance-level `conversationMemory.replayToolSteps` is folded
+ * into the option by BaseProvider before the builder runs.
+ */
+export declare const resolveToolReplayMode: (options: {
+    replayToolSteps?: ToolReplayMode;
+} | undefined) => ToolReplayMode;
+/**
+ * Replay a session's tool rows into the prompt while the caller converts the
+ * regular rows its own way.
+ *
+ * Usage: normalise the history with `rows()`, then for each row call
+ * `consume(row)`; a `true` return means the row was a tool row and is now
+ * held. Before converting a non-tool row (and once after the last row) call
+ * `flush(messages, nextRole)`, which appends whatever the held tool rows
+ * amount to under `mode`:
+ *
+ * - `"full"`: paired tool-call / tool-result turns, one pair per step.
+ * - `"marker"`: markers are folded into the assistant text — returned for
+ *   the caller to prepend when the next row is the assistant that answered
+ *   after those tools; otherwise appended to the assistant turn just
+ *   emitted, or emitted as a marker-only assistant turn when there is none.
+ * - `"off"`: dropped.
+ *
+ * The caller owns the conversion of regular rows so that the text and the
+ * multimodal builders keep their own (different) handling of them.
+ */
+export declare const createToolStepReplay: (mode: ToolReplayMode) => {
+    rows: <TRow extends ToolHistoryRow>(rows: ReadonlyArray<TRow>) => TRow[];
+    consume: (row: ToolHistoryRow) => boolean;
+    /**
+     * Append the held steps to `messages`. Returns marker text the caller must
+     * prepend to the assistant row it is about to convert, or undefined.
+     */
+    flush: (messages: Array<ModelMessage | MultimodalChatMessage>, nextRole: string | undefined) => string | undefined;
+};
 /**
  * Build a properly formatted message array for AI providers
  * Combines system prompt, conversation history, and current user prompt
@@ -43,6 +80,13 @@ export declare function processUnifiedFilesArray(options: GenerateOptions, maxSi
  * Detects when images are present and routes through provider adapter
  */
 export declare function buildMultimodalMessagesArray(options: GenerateOptions, provider: string, model: string): Promise<MultimodalChatMessage[]>;
+/**
+ * The multimodal builder proper. Returns model messages so a session's tool
+ * steps can be replayed as real tool turns (`replayToolSteps: "full"`) on a
+ * turn that also carries files or images; `buildMultimodalMessagesArray`
+ * wraps this for callers on the older `MultimodalChatMessage[]` shape.
+ */
+export declare function buildMultimodalModelMessages(options: GenerateOptions, provider: string, model: string, replayMode?: ToolReplayMode): Promise<Array<MultimodalChatMessage | ModelMessage>>;
 /**
  * Transcode any image in `input.images` that no vision provider accepts,
  * rewriting the entry in place as a PNG data URI.