@juspay/neurolink 9.69.3 → 9.70.1

package/dist/utils/json/coerce.js

@@ -0,0 +1,140 @@
+/**
+ * Coerce arbitrary model text into canonical, syntactically-valid JSON.
+ *
+ * Used on the text-mode path (providers/models that could not use AI-SDK
+ * structured output, e.g. real Gemini + tools). The model hand-writes JSON and
+ * frequently mis-escapes the content field (bare newline, unescaped quote,
+ * invalid escape like \d). A balanced-brace scan finds the object span; if
+ * JSON.parse rejects it, jsonrepair fixes common escaping mistakes; the result
+ * is re-serialised with JSON.stringify so downstream consumers always receive
+ * valid JSON.
+ *
+ * NOTE: jsonrepair is a heuristic. On content where a lone backslash is
+ * meaningful (regex/script/Windows path) it may drop the backslash, producing
+ * valid-but-semantically-altered content. This only affects the residual
+ * text-mode path — the primary Vertex+Claude path uses experimental_output and
+ * never reaches here. When jsonrepair changes the input we log at debug level
+ * so the event is observable.
+ */
+import { jsonrepair } from "jsonrepair";
+import { logger } from "../logger.js";
+import { nextBalancedJsonSpan } from "./extract.js";
+/** True when the schema exposes a Zod-style `safeParse` we can validate with. */
+function hasSafeParse(schema) {
+    return typeof schema.safeParse === "function";
+}
+/**
+ * Parse `candidate` as JSON, repairing common escaping mistakes on failure.
+ * Returns the parsed value plus whether jsonrepair had to alter the text.
+ */
+function parseOrRepair(candidate) {
+    try {
+        return { value: JSON.parse(candidate), repaired: false };
+    }
+    catch {
+        // fall through to repair
+    }
+    try {
+        const repaired = jsonrepair(candidate);
+        const value = JSON.parse(repaired);
+        if (repaired !== candidate && logger.shouldLog("debug")) {
+            logger.debug("[coerceJsonToSchema] jsonrepair altered model output", {
+                originalLength: candidate.length,
+                repairedLength: repaired.length,
+            });
+        }
+        return { value, repaired: repaired !== candidate };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Try to produce canonical JSON from `text`. Returns null when no JSON object
+ * could be recovered (caller should then keep the raw text).
+ *
+ * When `schema` is a Zod schema, candidates that satisfy it are preferred; a
+ * syntactically-valid-but-schema-failing object is still returned (we guarantee
+ * JSON *validity*, leaving schema/content checks to the caller's own pipeline).
+ */
+export function coerceJsonToSchema(text, schema) {
+    if (typeof text !== "string" || text.trim().length === 0) {
+        return null;
+    }
+    // Ordered candidate substrings, best-formed first:
+    //  1. every balanced object/array span (clean, common case)
+    //  2. first "{" or "[" to last "}" or "]" (drops surrounding prose; lets
+    //     jsonrepair fix escaping inside) — root ARRAYS matter for array schemas
+    //  3. first "{" or "[" to end of text (TRUNCATED output —
+    //     finishReason=length — where the closing bracket was cut off;
+    //     jsonrepair closes it)
+    // `truncated` marks the first-open-to-end candidate: it is only reachable
+    // when no balanced span and no first-to-last span matched, i.e. there was no
+    // closing bracket at all — the signature of token-truncated output.
+    const candidates = [];
+    let searchFrom = 0;
+    for (;;) {
+        const found = nextBalancedJsonSpan(text, searchFrom);
+        if (!found) {
+            break;
+        }
+        candidates.push({ text: found.span, truncated: false });
+        searchFrom = found.end;
+    }
+    const openIndexes = [text.indexOf("{"), text.indexOf("[")].filter((i) => i >= 0);
+    const firstOpen = openIndexes.length > 0 ? Math.min(...openIndexes) : -1;
+    const lastClose = Math.max(text.lastIndexOf("}"), text.lastIndexOf("]"));
+    if (firstOpen >= 0 && lastClose > firstOpen) {
+        candidates.push({
+            text: text.slice(firstOpen, lastClose + 1),
+            truncated: false,
+        });
+    }
+    if (firstOpen >= 0) {
+        candidates.push({ text: text.slice(firstOpen), truncated: true });
+    }
+    let firstValid;
+    let schemaMatch;
+    const seen = new Set();
+    for (const candidate of candidates) {
+        if (seen.has(candidate.text)) {
+            continue;
+        }
+        seen.add(candidate.text);
+        const outcome = parseOrRepair(candidate.text);
+        if (outcome === undefined ||
+            outcome.value === null ||
+            typeof outcome.value !== "object") {
+            continue;
+        }
+        const record = {
+            value: outcome.value,
+            repaired: outcome.repaired,
+            truncated: candidate.truncated,
+        };
+        if (firstValid === undefined) {
+            firstValid = record;
+        }
+        if (schema && hasSafeParse(schema)) {
+            const safeParseable = schema;
+            if (safeParseable.safeParse(outcome.value).success) {
+                schemaMatch = record;
+                break;
+            }
+        }
+        else {
+            // No Zod schema to discriminate — first parseable object wins.
+            break;
+        }
+    }
+    const chosen = schemaMatch ?? firstValid;
+    if (chosen === undefined) {
+        return null;
+    }
+    return {
+        content: JSON.stringify(chosen.value),
+        structuredData: chosen.value,
+        repaired: chosen.repaired,
+        truncated: chosen.truncated,
+    };
+}

package/dist/utils/json/extract.d.ts

@@ -4,6 +4,16 @@
  * Utilities for extracting JSON from mixed text content.
  * Particularly useful for parsing AI responses that contain JSON within prose.
  */
+/**
+ * Find the first balanced JSON object/array span starting at or after
+ * `fromIndex`. Quote- and escape-aware: braces inside string literals do not
+ * affect depth. Returns the matched substring and the index just past it, or
+ * null if no balanced span exists.
+ */
+export declare function nextBalancedJsonSpan(text: string, fromIndex?: number): {
+    span: string;
+    end: number;
+} | null;
 /**
  * Extract JSON string from text that may contain surrounding content.
  *

package/dist/utils/json/extract.js

@@ -5,6 +5,53 @@
  * Particularly useful for parsing AI responses that contain JSON within prose.
  */
 import { parseJsonOrNull } from "./safeParse.js";
+/**
+ * Find the first balanced JSON object/array span starting at or after
+ * `fromIndex`. Quote- and escape-aware: braces inside string literals do not
+ * affect depth. Returns the matched substring and the index just past it, or
+ * null if no balanced span exists.
+ */
+export function nextBalancedJsonSpan(text, fromIndex = 0) {
+    for (let start = fromIndex; start < text.length; start++) {
+        const openChar = text[start];
+        if (openChar !== "{" && openChar !== "[") {
+            continue;
+        }
+        const closeChar = openChar === "{" ? "}" : "]";
+        let depth = 0;
+        let inString = false;
+        let escapeNext = false;
+        for (let i = start; i < text.length; i++) {
+            const ch = text[i];
+            if (escapeNext) {
+                escapeNext = false;
+                continue;
+            }
+            if (ch === "\\") {
+                escapeNext = true;
+                continue;
+            }
+            if (ch === '"') {
+                inString = !inString;
+                continue;
+            }
+            if (inString) {
+                continue;
+            }
+            if (ch === openChar) {
+                depth++;
+            }
+            else if (ch === closeChar) {
+                depth--;
+                if (depth === 0) {
+                    return { span: text.substring(start, i + 1), end: i + 1 };
+                }
+            }
+        }
+        // Unbalanced from this start — try the next opening char.
+    }
+    return null;
+}
 /**
  * Extract JSON string from text that may contain surrounding content.
  *
@@ -45,21 +92,24 @@ export function extractJsonStringFromText(text) {
             // Continue to other patterns
         }
     }
-    // Try to find JSON object or array pattern using non-greedy iterative scan.
-    // Note: [\s\S]*? is non-greedy but can still produce over-spanning matches
-    // in texts with many braces. This is acceptable as we try-parse each candidate
-    // and move to the next on failure. A bracket-balancing parser would be more
-    // precise but significantly more complex for marginal benefit.
-    const candidateRegex = /(\{[\s\S]*?\}|\[[\s\S]*?\])/g;
-    let candidate;
-    while ((candidate = candidateRegex.exec(text)) !== null) {
+    // Scan for balanced JSON object/array spans (quote/escape aware) and return
+    // the first one that parses. Unlike a non-greedy regex, this never stops at a
+    // "}" that lives inside a string value, so nested objects are preserved.
+    let searchFrom = 0;
+    for (;;) {
+        const found = nextBalancedJsonSpan(text, searchFrom);
+        if (!found) {
+            break;
+        }
         try {
-            JSON.parse(candidate[1]);
-            return candidate[1];
+            JSON.parse(found.span);
+            return found.span;
         }
         catch {
-            // Try next candidate
+            // Not valid JSON — resume scanning just past this opening character so a
+            // valid inner object/array can still be found.
         }
+        searchFrom = found.end - found.span.length + 1;
     }
     return null;
 }

package/dist/utils/tokenLimits.d.ts

@@ -7,6 +7,26 @@ import { PROVIDER_MAX_TOKENS } from "../core/constants.js";
  * Get the safe maximum tokens for a provider and model
  */
 export declare function getSafeMaxTokens(provider: keyof typeof PROVIDER_MAX_TOKENS | string, model?: string, requestedMaxTokens?: number): number | undefined;
+/**
+ * Maximum output tokens supported by a given Anthropic Claude model.
+ *
+ * The native Vertex+Claude and native Anthropic message paths send `max_tokens`
+ * straight to the Anthropic API, which returns 400 if the value exceeds the
+ * model's published output ceiling. (The AI-SDK path clamps automatically;
+ * these native paths do not.) This table lets those paths default to the
+ * model's real ceiling — 64K for Sonnet/Haiku 4.x, 32K for Opus 4.x — instead of
+ * the legacy 4096 that silently truncated large structured responses.
+ *
+ * Unknown identifiers fall back to a safe modern floor (8192).
+ */
+export declare function getClaudeMaxOutputTokens(model: string | undefined): number;
+/**
+ * Resolve the `max_tokens` to send on a native Anthropic/Claude request: honour
+ * the caller's value but clamp it to the model's published ceiling, and default
+ * to that ceiling when the caller did not specify one. Prevents both silent
+ * truncation (the legacy 4096 default) and 400s from over-large requests.
+ */
+export declare function resolveClaudeMaxTokens(model: string | undefined, requested?: number): number;
 /**
  * Validate if maxTokens is safe for a provider/model combination
  */

package/dist/utils/tokenLimits.js

@@ -76,6 +76,61 @@ export function getSafeMaxTokens(provider, model, requestedMaxTokens) {
     // Use the requested value if it's within limits
     return requestedMaxTokens;
 }
+/**
+ * Maximum output tokens supported by a given Anthropic Claude model.
+ *
+ * The native Vertex+Claude and native Anthropic message paths send `max_tokens`
+ * straight to the Anthropic API, which returns 400 if the value exceeds the
+ * model's published output ceiling. (The AI-SDK path clamps automatically;
+ * these native paths do not.) This table lets those paths default to the
+ * model's real ceiling — 64K for Sonnet/Haiku 4.x, 32K for Opus 4.x — instead of
+ * the legacy 4096 that silently truncated large structured responses.
+ *
+ * Unknown identifiers fall back to a safe modern floor (8192).
+ */
+export function getClaudeMaxOutputTokens(model) {
+    const m = (model ?? "").toLowerCase();
+    // Claude 4.x family: Opus 4.x = 32K, Sonnet/Haiku 4.x = 64K.
+    if (/opus[-_.]?4/.test(m)) {
+        return 32000;
+    }
+    if (/sonnet[-_.]?4/.test(m) || /haiku[-_.]?4/.test(m)) {
+        return 64000;
+    }
+    // Claude 3.7 Sonnet supports 64K output.
+    if (/3[-_.]?7[-_.]?sonnet/.test(m)) {
+        return 64000;
+    }
+    // Claude 3.5 Sonnet / Haiku → 8192.
+    if (/3[-_.]?5[-_.]?(sonnet|haiku)/.test(m)) {
+        return 8192;
+    }
+    // Claude 3 Opus / Sonnet / Haiku → 4096.
+    if (/claude-3-(opus|sonnet|haiku)/.test(m) || /3[-_.]?opus/.test(m)) {
+        return 4096;
+    }
+    // Bare family aliases (latest of a family) → assume the modern ceiling.
+    if (m.includes("opus")) {
+        return 32000;
+    }
+    if (m.includes("sonnet") || m.includes("haiku")) {
+        return 64000;
+    }
+    return 8192;
+}
+/**
+ * Resolve the `max_tokens` to send on a native Anthropic/Claude request: honour
+ * the caller's value but clamp it to the model's published ceiling, and default
+ * to that ceiling when the caller did not specify one. Prevents both silent
+ * truncation (the legacy 4096 default) and 400s from over-large requests.
+ */
+export function resolveClaudeMaxTokens(model, requested) {
+    const ceiling = getClaudeMaxOutputTokens(model);
+    if (requested !== undefined && requested !== null && requested > 0) {
+        return Math.min(requested, ceiling);
+    }
+    return ceiling;
+}
 /**
  * Validate if maxTokens is safe for a provider/model combination
  */

package/dist/voice/livekit/brain.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Transport-agnostic voice brain.
+ *
+ * Given a user transcript and a stable conversation id, it streams the
+ * assistant's reply as text deltas by calling `neurolink.stream()`. NeuroLink
+ * owns history (via the conversation id and its memory layer) and tools (the
+ * tool-calling loop runs inside `stream()`); this module never touches a
+ * transport. The LiveKit worker (or any other transport) consumes the text
+ * deltas and converts them to audio.
+ *
+ * See docs/features/livekit-voice-agent.md.
+ */
+import type { LiveKitBrainConfig, LiveKitVoiceBrain } from "../../types/index.js";
+/**
+ * Create a voice brain bound to a configured NeuroLink instance.
+ *
+ * The returned `streamReply` is an async generator of text deltas for a single
+ * turn. Aborting `turn.signal` stops the in-flight LLM and tool calls and ends
+ * the generator promptly (barge-in support).
+ */
+export declare function createVoiceBrain(config: LiveKitBrainConfig): LiveKitVoiceBrain;

package/dist/voice/livekit/brain.js

@@ -0,0 +1,74 @@
+/**
+ * Transport-agnostic voice brain.
+ *
+ * Given a user transcript and a stable conversation id, it streams the
+ * assistant's reply as text deltas by calling `neurolink.stream()`. NeuroLink
+ * owns history (via the conversation id and its memory layer) and tools (the
+ * tool-calling loop runs inside `stream()`); this module never touches a
+ * transport. The LiveKit worker (or any other transport) consumes the text
+ * deltas and converts them to audio.
+ *
+ * See docs/features/livekit-voice-agent.md.
+ */
+import { logger } from "../../utils/logger.js";
+/**
+ * Extract spoken text from a stream chunk without type assertions.
+ *
+ * `StreamResult.stream` yields a union: text chunks (`{ content: string }`),
+ * a no-output sentinel, and audio/image events. Only text chunks carry a
+ * string `content`; everything else yields `undefined` and is skipped.
+ */
+function extractTextDelta(chunk) {
+    if (typeof chunk === "object" && chunk !== null && "content" in chunk) {
+        const value = chunk.content;
+        if (typeof value === "string" && value.length > 0) {
+            return value;
+        }
+    }
+    return undefined;
+}
+/**
+ * Create a voice brain bound to a configured NeuroLink instance.
+ *
+ * The returned `streamReply` is an async generator of text deltas for a single
+ * turn. Aborting `turn.signal` stops the in-flight LLM and tool calls and ends
+ * the generator promptly (barge-in support).
+ */
+export function createVoiceBrain(config) {
+    const { neurolink, provider, model, systemPrompt, temperature, maxTokens, userId, } = config;
+    async function* streamReply(turn) {
+        const { transcript, conversationId, signal } = turn;
+        if (signal?.aborted) {
+            return;
+        }
+        const context = {
+            sessionId: conversationId,
+            conversationId,
+        };
+        if (userId !== undefined) {
+            context.userId = userId;
+        }
+        const result = await neurolink.stream({
+            input: { text: transcript },
+            provider,
+            model,
+            systemPrompt,
+            temperature,
+            maxTokens,
+            context,
+            abortSignal: signal,
+            disableTools: false,
+        });
+        for await (const chunk of result.stream) {
+            if (signal?.aborted) {
+                logger.debug("[LiveKitBrain] Turn aborted mid-stream; stopping");
+                return;
+            }
+            const delta = extractTextDelta(chunk);
+            if (delta !== undefined) {
+                yield delta;
+            }
+        }
+    }
+    return { streamReply };
+}

package/dist/voice/livekit/config.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Environment resolution for the LiveKit voice agent.
+ *
+ * Reads LiveKit connection settings and LLM defaults from `process.env` with
+ * descriptive errors for missing required values. No type assertions: presence
+ * is verified with explicit string checks.
+ *
+ * See docs/features/livekit-voice-agent.md.
+ */
+import type { LiveKitServerConfig, LiveKitBrainDefaults } from "../../types/index.js";
+/**
+ * Resolve LiveKit server connection settings from the environment.
+ *
+ * Requires `LIVEKIT_URL`, `LIVEKIT_API_KEY`, and `LIVEKIT_API_SECRET`. Works
+ * identically for LiveKit Cloud, a self-hosted server, or `livekit-server --dev`
+ * — only the values differ.
+ */
+export declare function resolveLiveKitServerConfig(): LiveKitServerConfig;
+/**
+ * Resolve the LLM provider/model defaults for the brain.
+ *
+ * Defaults to Bedrock / Claude; overridable via `VOICE_LLM_PROVIDER` and
+ * `VOICE_LLM_MODEL`.
+ */
+export declare function resolveBrainDefaults(): LiveKitBrainDefaults;
+/**
+ * Resolve the semantic end-of-utterance (EOU) turn-detection settings.
+ *
+ * Opt-in via `LIVEKIT_EOU_TURN_DETECTION` (`1`/`true`/`english`/`en`/`on`/`yes`).
+ * When enabled, the English `@livekit/agents-plugin-livekit` EOU model decides
+ * whether the user's turn is truly over, layered on top of VAD silence — so
+ * natural mid-sentence pauses don't split one utterance. English-only; the
+ * model adds ~200MB RAM per worker and ~10ms per turn-end.
+ *
+ * `LIVEKIT_EOU_UNLIKELY_THRESHOLD` optionally overrides the model's confidence
+ * threshold (lower = end the turn more eagerly).
+ */
+export declare function resolveEouTurnDetection(): {
+    enabled: boolean;
+    unlikelyThreshold: number | undefined;
+};

package/dist/voice/livekit/config.js

@@ -0,0 +1,79 @@
+/**
+ * Environment resolution for the LiveKit voice agent.
+ *
+ * Reads LiveKit connection settings and LLM defaults from `process.env` with
+ * descriptive errors for missing required values. No type assertions: presence
+ * is verified with explicit string checks.
+ *
+ * See docs/features/livekit-voice-agent.md.
+ */
+const DEFAULT_LLM_PROVIDER = "bedrock";
+const DEFAULT_LLM_MODEL = "claude-sonnet-4-6";
+/** Read a required environment variable or throw a descriptive error. */
+function requireEnv(name) {
+    const value = process.env[name];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(`${name} is not set in environment (required for the LiveKit voice agent)`);
+    }
+    return value.trim();
+}
+/** Read an optional environment variable, falling back to a default. */
+function readEnv(name, fallback) {
+    const value = process.env[name];
+    if (typeof value === "string" && value.trim().length > 0) {
+        return value.trim();
+    }
+    return fallback;
+}
+/**
+ * Resolve LiveKit server connection settings from the environment.
+ *
+ * Requires `LIVEKIT_URL`, `LIVEKIT_API_KEY`, and `LIVEKIT_API_SECRET`. Works
+ * identically for LiveKit Cloud, a self-hosted server, or `livekit-server --dev`
+ * — only the values differ.
+ */
+export function resolveLiveKitServerConfig() {
+    return {
+        url: requireEnv("LIVEKIT_URL"),
+        apiKey: requireEnv("LIVEKIT_API_KEY"),
+        apiSecret: requireEnv("LIVEKIT_API_SECRET"),
+    };
+}
+/**
+ * Resolve the LLM provider/model defaults for the brain.
+ *
+ * Defaults to Bedrock / Claude; overridable via `VOICE_LLM_PROVIDER` and
+ * `VOICE_LLM_MODEL`.
+ */
+export function resolveBrainDefaults() {
+    return {
+        provider: readEnv("VOICE_LLM_PROVIDER", DEFAULT_LLM_PROVIDER),
+        model: readEnv("VOICE_LLM_MODEL", DEFAULT_LLM_MODEL),
+    };
+}
+const EOU_TRUTHY = new Set(["1", "true", "english", "en", "on", "yes"]);
+/**
+ * Resolve the semantic end-of-utterance (EOU) turn-detection settings.
+ *
+ * Opt-in via `LIVEKIT_EOU_TURN_DETECTION` (`1`/`true`/`english`/`en`/`on`/`yes`).
+ * When enabled, the English `@livekit/agents-plugin-livekit` EOU model decides
+ * whether the user's turn is truly over, layered on top of VAD silence — so
+ * natural mid-sentence pauses don't split one utterance. English-only; the
+ * model adds ~200MB RAM per worker and ~10ms per turn-end.
+ *
+ * `LIVEKIT_EOU_UNLIKELY_THRESHOLD` optionally overrides the model's confidence
+ * threshold (lower = end the turn more eagerly).
+ */
+export function resolveEouTurnDetection() {
+    const raw = process.env.LIVEKIT_EOU_TURN_DETECTION;
+    const enabled = typeof raw === "string" && EOU_TRUTHY.has(raw.trim().toLowerCase());
+    const thresholdRaw = process.env.LIVEKIT_EOU_UNLIKELY_THRESHOLD;
+    let unlikelyThreshold;
+    if (typeof thresholdRaw === "string" && thresholdRaw.trim().length > 0) {
+        const parsed = Number(thresholdRaw.trim());
+        if (Number.isFinite(parsed)) {
+            unlikelyThreshold = parsed;
+        }
+    }
+    return { enabled, unlikelyThreshold };
+}

package/dist/voice/livekit/eventBridge.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Data-channel event bridge.
+ *
+ * Connects NeuroLink's event emitter to the LiveKit room's data channel: it
+ * forwards NeuroLink events (text deltas, tool start/result, HITL prompts,
+ * stream lifecycle) to the browser as small versioned envelopes, and accepts
+ * control messages (HITL responses) back, re-emitting them onto the emitter so
+ * NeuroLink's HITL manager resolves.
+ *
+ * This is the WebRTC counterpart of the chat-mode SSE controller: same event
+ * source, different transport. The browser renders the envelopes (transcript,
+ * tool status, charts, confirmation prompts).
+ *
+ * `@livekit/rtc-node` is an optional dependency, imported dynamically only for
+ * the `RoomEvent` enum value. All payloads arrive typed as `unknown` and are
+ * narrowed with runtime guards — no type assertions.
+ *
+ * See docs/features/livekit-voice-agent.md.
+ */
+import type { LiveKitEventBridgeHandle, LiveKitEventBridgeParams } from "../../types/index.js";
+/**
+ * Attach the data-channel event bridge to a room.
+ *
+ * Returns a handle whose `dispose()` removes every listener and stops
+ * publishing; it is safe to call more than once.
+ */
+export declare function attachEventBridge(params: LiveKitEventBridgeParams): Promise<LiveKitEventBridgeHandle>;