@juspay/neurolink 9.69.3 → 9.70.1

package/dist/lib/providers/anthropic.js

@@ -21,6 +21,7 @@ import { emitToolEndFromStepFinish } from "../utils/toolEndEmitter.js";
 import { NoOutputGeneratedError } from "../utils/generationErrors.js";
 import { buildNoOutputSentinel, stampNoOutputSpan, } from "../utils/noOutputSentinel.js";
 import { convertZodToJsonSchema } from "../utils/schemaConversion.js";
+import { resolveClaudeMaxTokens } from "../utils/tokenLimits.js";
 import { createChunkQueue, createDeferredAnalytics, stringifyToolInput, } from "./openaiChatCompletionsClient.js";
 /**
  * Beta headers for Claude Code integration.
@@ -493,10 +494,19 @@ const mapAnthropicStopReason = (raw) => {
             return "stop";
     }
 };
-// Anthropic's Messages API requires max_tokens on every request. The previous
-// @ai-sdk/anthropic implementation defaulted it to 4096 when the caller did
-// not specify maxTokens — preserve that wire behavior.
-const ANTHROPIC_DEFAULT_MAX_TOKENS = 4096;
+// Anthropic's Messages API requires max_tokens on every request. When the
+// caller omits it, default to the model's real output ceiling via
+// resolveClaudeMaxTokens (e.g. 64K for Sonnet 4.x) instead of the legacy 4096,
+// which silently truncated large structured responses mid-JSON.
+//
+// Client-level request timeout. The Anthropic SDK throws "Streaming is required
+// for long requests" from a NON-streaming `messages.create` when `max_tokens`
+// is large AND no client-level timeout is configured (it can't estimate a safe
+// timeout). Setting an explicit client timeout — equal to the SDK's own default
+// for the non-throwing path — suppresses that pre-flight throw so large
+// max_tokens (our model-ceiling default) works. Per-request duration is still
+// bounded by the abort signal NeuroLink composes for each call.
+const ANTHROPIC_CLIENT_TIMEOUT_MS = 600_000;
 /**
  * Anthropic Provider v2 - BaseProvider Implementation
  * Enhanced with OAuth support, subscription tiers, and beta headers for Claude Code integration.
@@ -602,6 +612,7 @@ export class AnthropicProvider extends BaseProvider {
                 apiKey: "oauth-authenticated", // Placeholder, actual auth is in fetch wrapper
                 // Note: No headers passed - fetch wrapper sets oauth-2025-04-20 beta header
                 fetch: oauthFetch,
+                timeout: ANTHROPIC_CLIENT_TIMEOUT_MS,
             });
             logger.debug("[AnthropicProvider] Anthropic SDK client created with OAuth fetch wrapper");
             logger.debug("Anthropic Provider initialized with OAuth", {
@@ -647,6 +658,7 @@ export class AnthropicProvider extends BaseProvider {
                 defaultHeaders: headers,
                 ...(normalizedBaseURL && { baseURL: normalizedBaseURL }),
                 fetch: createProxyFetch(),
+                timeout: ANTHROPIC_CLIENT_TIMEOUT_MS,
             });
             logger.debug("Anthropic Provider initialized with API key", {
                 modelName: this.modelName,
@@ -1122,7 +1134,7 @@ export class AnthropicProvider extends BaseProvider {
                 const params = {
                     model: modelId,
                     messages,
-                    max_tokens: options.maxOutputTokens ?? ANTHROPIC_DEFAULT_MAX_TOKENS,
+                    max_tokens: resolveClaudeMaxTokens(modelId, options.maxOutputTokens),
                     ...(system ? { system } : {}),
                     ...(options.temperature !== undefined && options.temperature !== null
                         ? { temperature: options.temperature }
@@ -1137,7 +1149,22 @@ export class AnthropicProvider extends BaseProvider {
                     ...(toolChoice ? { tool_choice: toolChoice } : {}),
                     ...(thinking ? { thinking } : {}),
                 };
-                const timeoutController = createTimeoutController(getTimeoutForOptions(options), providerName, "generate");
+                // The 60s anthropic generate default was tuned for the old ~4096
+                // max_tokens. Now that the default ceiling is the model's real max,
+                // a large structured response needs more wall-clock to be produced —
+                // otherwise the inner controller aborts mid-generation (the AI-SDK
+                // doGenerate layer doesn't see the caller's `timeout`). Raise the
+                // floor to 5 min when a large output budget is in play — but only
+                // when the caller did NOT set an explicit timeout: an explicit value
+                // is a contract and must never be silently extended. The abort
+                // signal stays the real bound.
+                const callerTimeout = options
+                    .timeout;
+                const callerSpecifiedTimeout = callerTimeout !== undefined && callerTimeout !== null;
+                const generateTimeoutMs = params.max_tokens > 8192 && !callerSpecifiedTimeout
+                    ? Math.max(getTimeoutForOptions(options), 300_000)
+                    : getTimeoutForOptions(options);
+                const timeoutController = createTimeoutController(generateTimeoutMs, providerName, "generate");
                 let response;
                 try {
                     response = await client.messages.create(params, {
@@ -1356,7 +1383,7 @@ export class AnthropicProvider extends BaseProvider {
                 const params = {
                     model: modelId,
                     messages: conversation,
-                    max_tokens: options.maxTokens ?? ANTHROPIC_DEFAULT_MAX_TOKENS,
+                    max_tokens: resolveClaudeMaxTokens(modelId, options.maxTokens),
                     stream: true,
                     ...(payload.system ? { system: payload.system } : {}),
                     ...(options.temperature !== undefined && options.temperature !== null

package/dist/lib/providers/googleVertex.js

@@ -14,6 +14,7 @@ import { FileDetector } from "../utils/fileDetector.js";
 import { processUnifiedFilesArray } from "../utils/messageBuilder.js";
 import { logger } from "../utils/logger.js";
 import { hasRestrictedOutputLimit, RESTRICTED_OUTPUT_TOKEN_LIMIT, } from "../utils/modelDetection.js";
+import { resolveClaudeMaxTokens } from "../utils/tokenLimits.js";
 import { validateApiKey, createVertexProjectConfig, createGoogleAuthConfig, } from "../utils/providerConfig.js";
 import { convertZodToJsonSchema, inlineJsonSchema, ensureNestedSchemaTypes, } from "../utils/schemaConversion.js";
 import { createNativeThinkingConfig } from "../utils/thinkingConfig.js";
@@ -2293,7 +2294,11 @@ export class GoogleVertexProvider extends BaseProvider {
                 : undefined;
         const requestParams = {
             model: modelName,
-            max_tokens: options.maxTokens || 4096,
+            // Default to the model's real output ceiling (e.g. 64K for Sonnet 4.x)
+            // instead of the legacy 4096, which silently truncated large structured
+            // responses mid-JSON. resolveClaudeMaxTokens also clamps over-large
+            // caller values so the native Vertex path never 400s.
+            max_tokens: resolveClaudeMaxTokens(modelName, options.maxTokens),
             messages: messages,
             ...(tools && tools.length > 0 && { tools }),
             ...(useFinalResultTool && { tool_choice: { type: "any" } }),
@@ -2813,7 +2818,8 @@ export class GoogleVertexProvider extends BaseProvider {
                 : undefined;
         const requestParams = {
             model: modelName,
-            max_tokens: options.maxTokens || 4096,
+            // Default to the model's real output ceiling (see stream path note).
+            max_tokens: resolveClaudeMaxTokens(modelName, options.maxTokens),
             messages,
             ...(tools && tools.length > 0 && { tools }),
             ...(useFinalResultTool && { tool_choice: { type: "any" } }),
@@ -2835,6 +2841,10 @@ export class GoogleVertexProvider extends BaseProvider {
         const allToolCalls = [];
         let totalInputTokens = 0;
         let totalOutputTokens = 0;
+        // Track the final Anthropic stop_reason so we can surface finishReason
+        // (notably "length" on token truncation) — the legacy native path always
+        // reported "stop", hiding truncation from callers.
+        let lastStopReason;
         const currentMessages = [...messages];
         while (step < maxSteps) {
             step++;
@@ -2849,6 +2859,7 @@ export class GoogleVertexProvider extends BaseProvider {
                 // Update token counts
                 totalInputTokens += response.usage?.input_tokens || 0;
                 totalOutputTokens += response.usage?.output_tokens || 0;
+                lastStopReason = response.stop_reason;
                 // Check if we need to handle tool use
                 const toolUseBlocks = response.content.filter((block) => block.type === "tool_use");
                 // Check for final_result tool call (for structured output)
@@ -2997,6 +3008,10 @@ export class GoogleVertexProvider extends BaseProvider {
         const externalToolExecutions = toolExecutions.filter((te) => te.name !== "final_result");
         const result = {
             content: finalText,
+            // Surface truncation: Anthropic "max_tokens" → unified "length" so the
+            // SDK boundary can flag/observe incomplete structured output. Anything
+            // else (end_turn / stop_sequence / tool_use) is a normal stop.
+            finishReason: lastStopReason === "max_tokens" ? "length" : "stop",
             provider: this.providerName,
             model: modelName,
             usage: {

package/dist/lib/types/generate.d.ts

@@ -249,30 +249,32 @@ export type GenerateOptions = {
     /**
      * Zod schema for structured output validation
      *
-     * @important Google Gemini Limitation
-     * Google Vertex AI and Google AI Studio cannot combine function calling with
-     * structured output. You MUST use `disableTools: true` when using schemas with
-     * Google providers.
-     *
-     * Error without disableTools: "Function calling with a response mime type:
-     * 'application/json' is unsupported"
-     *
-     * This is a documented Google API limitation, not a NeuroLink bug.
-     * All frameworks (LangChain, Vercel AI SDK, Agno, Instructor) use this approach.
+     * @important Google GEMINI limitation (Gemini models only)
+     * Gemini models (Google AI Studio, and Vertex GEMINI models) cannot combine
+     * function calling with schema-enforced structured output — a Gemini API
+     * limitation ("Function calling with a response mime type:
+     * 'application/json' is unsupported"). Vertex CLAUDE models and all other
+     * providers support tools + schema simultaneously.
+     *
+     * You do NOT need to set `disableTools` yourself: when the combination is
+     * impossible, NeuroLink automatically falls back to text-mode JSON coercion
+     * (see `coerceJsonToSchema`), and `disableTools: true` remains available as
+     * an explicit override.
      *
      * @example
      * ```typescript
-     * // ✅ Correct for Google providers
+     * // ✅ Vertex + Claude: tools AND schema together are fully supported
      * const result = await neurolink.generate({
      *   schema: MySchema,
      *   provider: "vertex",
-     *   disableTools: true  // Required for Google
+     *   model: "claude-sonnet-4-6",
      * });
      *
-     * // ✅ No restriction for other providers
+     * // ✅ Gemini + tools: SDK auto-falls back to coerced text-mode JSON
      * const result = await neurolink.generate({
      *   schema: MySchema,
-     *   provider: "openai"  // Works without disableTools
+     *   provider: "google-ai",
+     *   model: "gemini-2.5-pro",
      * });
      * ```
      *
@@ -300,16 +302,18 @@ export type GenerateOptions = {
     /**
      * Disable tool execution (including built-in tools)
      *
-     * @required For Google Gemini providers when using schemas
-     * Google Vertex AI and Google AI Studio require this flag when using
-     * structured output (schemas) due to Google API limitations.
+     * Optional with schemas: the tools↔schema exclusion applies only to Google
+     * GEMINI models (Google AI Studio / Vertex Gemini — a Gemini API
+     * limitation), and NeuroLink handles it automatically by falling back to
+     * text-mode JSON coercion. Vertex CLAUDE models support tools + schema
+     * together. Set this only when you explicitly want a tool-free call.
      *
      * @example
      * ```typescript
-     * // Required for Google providers with schemas
+     * // Explicit override: schema-only call with no tools at all
      * await neurolink.generate({
      *   schema: MySchema,
-     *   provider: "vertex",
+     *   provider: "google-ai",
      *   disableTools: true
      * });
      * ```
@@ -551,6 +555,13 @@ export type AdditionalMemoryUser = {
  */
 export type GenerateResult = {
     content: string;
+    /**
+     * Parsed structured object when a `schema` was requested. Populated from
+     * AI-SDK experimental_output, or from text-mode coercion (balanced-scan +
+     * jsonrepair). Prefer this over JSON.parse(content) — it never requires the
+     * caller to re-parse hand-escaped model text.
+     */
+    structuredData?: unknown;
     outputs?: {
         text: string;
     };
@@ -638,6 +649,17 @@ export type GenerateResult = {
     provider?: string;
     model?: string;
     finishReason?: string;
+    /**
+     * True when the schema JSON in `content`/`structuredData` was repaired from
+     * malformed model text (jsonrepair ran). The result is still valid JSON.
+     */
+    jsonRepaired?: boolean;
+    /**
+     * True when the schema JSON appears truncated — the model hit the output
+     * token cap (finishReason="length") or the recovered object came from an
+     * unclosed span. `structuredData` may be incomplete; raise `maxTokens`.
+     */
+    jsonTruncated?: boolean;
     usage?: TokenUsage;
     responseTime?: number;
     toolCalls?: Array<{
@@ -1090,7 +1112,13 @@ export type TextGenerationOptions = {
  */
 export type TextGenerationResult = {
     content: string;
+    /** Parsed structured object when a `schema` was requested (see GenerateResult.structuredData). */
+    structuredData?: unknown;
     finishReason?: string;
+    /** True when the schema JSON was repaired from malformed model text. */
+    jsonRepaired?: boolean;
+    /** True when the schema JSON appears truncated (output hit the token cap). */
+    jsonTruncated?: boolean;
     provider?: string;
     model?: string;
     usage?: TokenUsage;

package/dist/lib/types/index.d.ts

@@ -28,6 +28,7 @@ export * from "./generate.js";
 export * from "./grounding.js";
 export * from "./guardrails.js";
 export * from "./hitl.js";
+export * from "./livekit.js";
 export * from "./mcp.js";
 export * from "./mcpOutput.js";
 export * from "./memory.js";

package/dist/lib/types/index.js

@@ -29,6 +29,7 @@ export * from "./generate.js";
 export * from "./grounding.js";
 export * from "./guardrails.js";
 export * from "./hitl.js";
+export * from "./livekit.js";
 export * from "./mcp.js";
 export * from "./mcpOutput.js";
 export * from "./memory.js";

package/dist/lib/types/livekit.d.ts

@@ -0,0 +1,369 @@
+/**
+ * Types for the LiveKit voice agent integration.
+ *
+ * The integration uses LiveKit (WebRTC transport, VAD, turn detection,
+ * interruption, worker-per-call scaling) as the real-time loop, and NeuroLink
+ * as the brain (LLM, tools, memory). These types describe the brain seam, the
+ * worker configuration, and the join-token request — all transport-agnostic
+ * except where a LiveKit-specific concept is named explicitly.
+ *
+ * See docs/features/livekit-voice-agent.md.
+ */
+import type { NeuroLinkEvents, TypedEventEmitter } from "./common.js";
+import type { StreamOptions, StreamResult } from "./stream.js";
+/**
+ * Minimal structural shape of the NeuroLink instance the brain depends on.
+ *
+ * Declared structurally (rather than importing the `NeuroLink` class) so the
+ * brain layer stays decoupled from SDK construction and can be unit-tested with
+ * a lightweight stub. The real `NeuroLink` instance satisfies this shape.
+ *
+ * `getEventEmitter` is optional so lightweight stubs remain valid; the real
+ * `NeuroLink` instance provides it, and the data-channel event bridge uses it
+ * to forward tool/text/HITL events to the browser.
+ */
+export type LiveKitNeuroLinkStreamer = {
+    stream: (options: StreamOptions) => Promise<StreamResult>;
+    getEventEmitter?: () => TypedEventEmitter<NeuroLinkEvents>;
+};
+/**
+ * Configuration for the transport-agnostic voice brain.
+ *
+ * The brain owns the conversation: it calls `neurolink.stream()` with a stable
+ * `conversationId` so NeuroLink's memory layer is the source of truth, and it
+ * leaves tool-calling to the NeuroLink instance.
+ */
+export type LiveKitBrainConfig = {
+    /** Configured NeuroLink instance (memory + tools registered on it). */
+    neurolink: LiveKitNeuroLinkStreamer;
+    /** LLM provider name passed to `stream()` (e.g. "bedrock"). */
+    provider?: string;
+    /** LLM model name passed to `stream()` (e.g. "claude-sonnet-4-6"). */
+    model?: string;
+    /** System prompt applied to every turn. */
+    systemPrompt?: string;
+    /** Sampling temperature for spoken-style responses. */
+    temperature?: number;
+    /** Upper bound on tokens per turn. */
+    maxTokens?: number;
+    /** Optional user identifier recorded alongside memory. */
+    userId?: string;
+};
+/** A single user turn handed to the brain. */
+export type LiveKitBrainTurn = {
+    /** Final transcript of the user's utterance. */
+    transcript: string;
+    /** Stable conversation id keying NeuroLink memory for this session. */
+    conversationId: string;
+    /** Cancellation signal; aborting stops the in-flight LLM and tool calls. */
+    signal?: AbortSignal;
+};
+/**
+ * The brain's public surface: stream the assistant reply as text deltas.
+ * The transport layer converts these deltas into audio (TTS).
+ */
+export type LiveKitVoiceBrain = {
+    streamReply: (turn: LiveKitBrainTurn) => AsyncGenerator<string, void, unknown>;
+};
+/** Speech-to-text plugin selection for the LiveKit worker. */
+export type LiveKitSttConfig = {
+    provider: string;
+    model?: string;
+    language?: string;
+    /**
+     * Soniox only: maximum delay (ms) between speech cessation and the STT
+     * endpoint. Raise it so Soniox does not finalize on short pauses — that lets
+     * VAD silence (not the STT endpoint) decide when the turn ends.
+     */
+    maxEndpointDelayMs?: number;
+};
+/** Text-to-speech plugin selection for the LiveKit worker. */
+export type LiveKitTtsConfig = {
+    provider: string;
+    voice?: string;
+    model?: string;
+};
+/**
+ * Silero VAD tuning. Stricter values reject background noise (higher threshold,
+ * longer minimum speech). Durations are in seconds.
+ */
+export type LiveKitVadConfig = {
+    /** Probability cutoff for "this is speech" (default 0.6). Higher = stricter. */
+    activationThreshold?: number;
+    /** Minimum speech length before a turn starts, seconds (default 0.2). */
+    minSpeechDuration?: number;
+    /** Silence before a turn ends, seconds (default 0.6) — tolerates pauses. */
+    minSilenceDuration?: number;
+};
+/**
+ * Turn-detection (end-of-utterance) tuning.
+ *
+ * `mode` selects what decides the user's turn is over:
+ * - `"vad"`  — Silero VAD silence (see `LiveKitVadConfig.minSilenceDuration`).
+ *   Tolerates natural mid-sentence pauses; the turn only ends after a full
+ *   silence window. This mirrors Clairvoyance's behavior.
+ * - `"stt"`  — the STT provider's own endpoint detection (e.g. Soniox). Often
+ *   much faster/aggressive — short pauses can prematurely split one utterance
+ *   into several turns.
+ * - `"realtime_llm"` / `"manual"` — advanced/manual strategies.
+ *
+ * `minEndpointingDelay` / `maxEndpointingDelay` are the framework's endpointing
+ * window in milliseconds (in VAD mode the effective end delay is
+ * `max(VAD silence, minEndpointingDelay)`).
+ */
+export type LiveKitTurnConfig = {
+    mode?: "stt" | "vad" | "realtime_llm" | "manual";
+    minEndpointingDelay?: number;
+    maxEndpointingDelay?: number;
+};
+/**
+ * Interruption (barge-in) tuning. Requiring real words / a minimum duration
+ * stops background noise from cutting off the assistant.
+ */
+export type LiveKitInterruptionConfig = {
+    /** Minimum recognized words to count as an interruption (default 2). */
+    minWords?: number;
+    /** Minimum audio duration to count as an interruption, ms (default 600). */
+    minDuration?: number;
+};
+/**
+ * Options for `defineVoiceAgent` — the agent definition placed as the default
+ * export of the worker entry file.
+ *
+ * LiveKit runs each call as a Job in its own child process and re-imports the
+ * entry file there, so the NeuroLink instance cannot be passed as a live object
+ * from a parent. Instead, `createNeuroLink` is invoked **inside each job
+ * process** to build the brain (and register its tools) for that call.
+ */
+export type LiveKitVoiceAgentConfig = {
+    /**
+     * Factory that builds the NeuroLink instance for a job process.
+     * Called once per call, inside the job's own process.
+     */
+    createNeuroLink: () => LiveKitNeuroLinkStreamer | Promise<LiveKitNeuroLinkStreamer>;
+    /** Realtime speech-to-text selection. */
+    stt: LiveKitSttConfig;
+    /** Realtime text-to-speech selection. */
+    tts: LiveKitTtsConfig;
+    /** LLM provider/model overrides (default to env-resolved values). */
+    provider?: string;
+    model?: string;
+    systemPrompt?: string;
+    temperature?: number;
+    maxTokens?: number;
+    /** Prefix used when deriving a per-room conversation id (default "voice"). */
+    conversationIdPrefix?: string;
+    /** Optional user id recorded alongside memory. */
+    userId?: string;
+    /** Silero VAD tuning (stricter = ignores background noise). */
+    vad?: LiveKitVadConfig;
+    /** Turn-detection tuning (VAD vs STT endpointing, delays). */
+    turn?: LiveKitTurnConfig;
+    /** Interruption tuning (require words/duration so noise can't barge in). */
+    interruption?: LiveKitInterruptionConfig;
+    /**
+     * Data-channel event bridge: forward NeuroLink events (text, tool calls,
+     * tool results, HITL prompts, status) to the browser over the LiveKit data
+     * channel, and accept control messages (HITL responses) back. Disabled
+     * unless `enabled` is `true`.
+     */
+    events?: LiveKitEventBridgeConfig;
+};
+/** Options for `startVoiceAgentWorker` — launches the LiveKit Agents worker. */
+export type LiveKitWorkerLaunchOptions = {
+    /**
+     * Absolute path to the entry file whose default export is the result of
+     * `defineVoiceAgent`. LiveKit re-imports this file in each job process.
+     */
+    agentFile: string;
+    /** Name the worker registers under for dispatch (default "neurolink-voice"). */
+    agentName?: string;
+};
+/** Resolved LiveKit server connection settings. */
+export type LiveKitServerConfig = {
+    /** LiveKit server URL (ws/wss). */
+    url: string;
+    /** API key for token signing and worker registration. */
+    apiKey: string;
+    /** API secret for token signing and worker registration. */
+    apiSecret: string;
+};
+/** LLM defaults resolved from the environment for the brain. */
+export type LiveKitBrainDefaults = {
+    provider: string;
+    model: string;
+};
+/** Arguments for minting a browser join token. */
+export type LiveKitTokenRequest = {
+    /** Participant identity (e.g. the authenticated user id). */
+    identity: string;
+    /** Room name to join (auto-created on first join). */
+    room: string;
+    /** LiveKit API key. */
+    apiKey: string;
+    /** LiveKit API secret. */
+    apiSecret: string;
+    /** Token lifetime in seconds (default 600; clamped to a 3600 max). */
+    ttlSeconds?: number;
+};
+/** Discriminant tags for outbound voice events. */
+export type LiveKitVoiceEventType = "user-text" | "text" | "tool-start" | "tool-result" | "status" | "hitl-prompt" | "done";
+/**
+ * A user STT transcript for display. Interim partials stream with
+ * `final: false`; the end-of-utterance result has `final: true`. The client
+ * updates one live bubble and commits it on `final`.
+ *
+ * `replacesPrevious` is set on the committed (`final: true`) text of a turn that
+ * absorbed a previous turn the user interrupted before it produced any reply
+ * (strict barge-in club). The client removes the orphaned previous user bubble
+ * so the merged utterance shows as one bubble.
+ */
+export type LiveKitVoiceUserTextEvent = {
+    type: "user-text";
+    data: {
+        text: string;
+        final: boolean;
+        replacesPrevious?: boolean;
+    };
+};
+/** A streamed chunk of the assistant's spoken/written reply. */
+export type LiveKitVoiceTextEvent = {
+    type: "text";
+    data: {
+        delta: string;
+    };
+};
+/** A tool invocation has started (best-effort status; may not always fire). */
+export type LiveKitVoiceToolStartEvent = {
+    type: "tool-start";
+    data: {
+        id?: string;
+        name: string;
+        input?: unknown;
+    };
+};
+/**
+ * A tool invocation has finished. `result` carries the tool's structured
+ * output (for example, a chart payload) for the client to render.
+ */
+export type LiveKitVoiceToolResultEvent = {
+    type: "tool-result";
+    data: {
+        id?: string;
+        name: string;
+        result?: unknown;
+        success?: boolean;
+        error?: string;
+    };
+};
+/** Coarse agent state, useful for UI indicators (e.g. "thinking…"). */
+export type LiveKitVoiceStatusEvent = {
+    type: "status";
+    data: {
+        state: "thinking" | "speaking" | "listening" | "error";
+        detail?: string;
+    };
+};
+/** A human-in-the-loop confirmation the user must approve or reject. */
+export type LiveKitVoiceHitlPromptEvent = {
+    type: "hitl-prompt";
+    data: {
+        confirmationId: string;
+        toolName: string;
+        actionType?: string;
+        arguments?: unknown;
+        timeoutMs?: number;
+        allowModification?: boolean;
+    };
+};
+/** The current turn has finished. */
+export type LiveKitVoiceDoneEvent = {
+    type: "done";
+    data: {
+        reason?: string;
+    };
+};
+/** Discriminated union of all outbound voice events (before enveloping). */
+export type LiveKitVoiceEvent = LiveKitVoiceUserTextEvent | LiveKitVoiceTextEvent | LiveKitVoiceToolStartEvent | LiveKitVoiceToolResultEvent | LiveKitVoiceStatusEvent | LiveKitVoiceHitlPromptEvent | LiveKitVoiceDoneEvent;
+/**
+ * Wire format published to the browser: a `LiveKitVoiceEvent` plus a monotonic
+ * sequence number and a timestamp so the client can order and de-duplicate.
+ */
+export type LiveKitVoiceEventEnvelope = LiveKitVoiceEvent & {
+    seq: number;
+    ts: number;
+};
+/** Control messages sent from the browser back to the agent. */
+export type LiveKitVoiceControlMessage = {
+    action: "hitl:accept";
+    confirmationId: string;
+    modifiedArguments?: unknown;
+} | {
+    action: "hitl:reject";
+    confirmationId: string;
+    reason?: string;
+};
+/**
+ * Configuration for the data-channel event bridge, set on
+ * `LiveKitVoiceAgentConfig.events`.
+ */
+export type LiveKitEventBridgeConfig = {
+    /** Master switch — the bridge is inert unless this is `true`. */
+    enabled?: boolean;
+    /** Data-channel topic for outbound events (default "ai-events"). */
+    eventsTopic?: string;
+    /** Data-channel topic for inbound control messages (default "ai-control"). */
+    controlTopic?: string;
+    /** If set, only these event types are forwarded (default: all). */
+    include?: LiveKitVoiceEventType[];
+    /**
+     * Payloads encoded larger than this many bytes are sent via the chunked text
+     * stream API instead of a single reliable data packet (default 12000).
+     */
+    maxInlineBytes?: number;
+};
+/**
+ * Minimal structural view of the LiveKit room the bridge needs: a local
+ * participant to publish on, and event (un)subscription. Declared structurally
+ * so `src/lib/types` carries no dependency on `@livekit/rtc-node`; the real
+ * `Room` from a job context satisfies this shape.
+ */
+export type LiveKitBridgeRoom = {
+    localParticipant?: {
+        publishData(data: Uint8Array, options: {
+            reliable?: boolean;
+            topic?: string;
+        }): Promise<void>;
+        sendText(text: string, options?: {
+            topic?: string;
+        }): Promise<unknown>;
+    };
+    on(event: string, listener: (...args: unknown[]) => void): unknown;
+    off(event: string, listener: (...args: unknown[]) => void): unknown;
+};
+/**
+ * Normalized tool fields extracted from a `tool:start` / `tool:end` emitter
+ * payload, used internally by the event bridge.
+ */
+export type LiveKitToolEventFields = {
+    name: string;
+    id?: string;
+    input?: unknown;
+    result?: unknown;
+    success?: boolean;
+    error?: string;
+};
+/** Inputs to `attachEventBridge`. */
+export type LiveKitEventBridgeParams = {
+    /** The LiveKit room for this call (from the job context). */
+    room: LiveKitBridgeRoom;
+    /** NeuroLink's event emitter (`neurolink.getEventEmitter()`). */
+    emitter: TypedEventEmitter<NeuroLinkEvents>;
+    /** Bridge options (topics, filtering, chunking threshold). */
+    options?: LiveKitEventBridgeConfig;
+};
+/** Handle returned by `attachEventBridge` for teardown. */
+export type LiveKitEventBridgeHandle = {
+    /** Remove all listeners and stop publishing. Idempotent. */
+    dispose: () => void;
+};

package/dist/lib/types/livekit.js

@@ -0,0 +1,13 @@
+/**
+ * Types for the LiveKit voice agent integration.
+ *
+ * The integration uses LiveKit (WebRTC transport, VAD, turn detection,
+ * interruption, worker-per-call scaling) as the real-time loop, and NeuroLink
+ * as the brain (LLM, tools, memory). These types describe the brain seam, the
+ * worker configuration, and the join-token request — all transport-agnostic
+ * except where a LiveKit-specific concept is named explicitly.
+ *
+ * See docs/features/livekit-voice-agent.md.
+ */
+export {};
+//# sourceMappingURL=livekit.js.map