@juspay/neurolink 12.28.3 → 12.29.0

package/dist/server/websocket/WebSocketHandler.js

@@ -6,6 +6,7 @@
  */
 import { WebSocketError, WebSocketConnectionError } from "../errors.js";
 import { logger } from "../../utils/logger.js";
+import { WebSocketAgentRequestSchema } from "../utils/validation.js";
 /**
  * Default WebSocket configuration
  */
@@ -58,6 +59,46 @@ export class WebSocketConnectionManager {
         if (this.connections.size >= this.config.maxConnections) {
             throw new WebSocketConnectionError(`Maximum connections (${this.config.maxConnections}) reached`);
         }
+        // Enforce the auth contract the config already declares. `auth.required`
+        // has existed on WebSocketConfig (with a `strategy`) since this manager
+        // was written, and `handleConnection` has always accepted and stored an
+        // AuthenticatedUser — but nothing ever checked either, so a deployer who
+        // set `required: true` got exactly the same open socket as one who did
+        // not. That was latent while the agent routes were stubs that returned
+        // canned values; it stops being latent the moment `tool_call` actually
+        // reaches `executeTool`, because then an unauthenticated client can
+        // invoke any registered tool with arbitrary arguments. Refuse the
+        // connection rather than letting a route decide, so every handler
+        // registered on this manager inherits the gate.
+        if (this.config.auth.required && !user) {
+            logger.warn(`[WebSocket] Rejected unauthenticated connection to ${path} (auth.required)`);
+            throw new WebSocketConnectionError("Authentication required for this WebSocket endpoint");
+        }
+        // Same gap, same fix, one field over. `ServerAuthConfig.roles`/
+        // `permissions` and `AuthenticatedUser.roles`/`permissions` have existed
+        // since this manager was written — the shipped "Role-Based Access
+        // Control" doc example configures them on a `/ws/admin` path — but
+        // nothing ever consulted either, so a deployer following that example
+        // got an endpoint anyone authenticated could reach, regardless of role.
+        // Semantics match the SDK's own `hasAnyRole`/`hasAllPermissions`
+        // (src/lib/auth/authContext.ts): roles are an any-of allowlist,
+        // permissions must all be present.
+        const requiredRoles = this.config.auth.roles;
+        if (requiredRoles && requiredRoles.length > 0) {
+            const userRoles = user?.roles ?? [];
+            if (!requiredRoles.some((role) => userRoles.includes(role))) {
+                logger.warn(`[WebSocket] Rejected connection to ${path}: missing a required role`);
+                throw new WebSocketConnectionError("Insufficient role for this WebSocket endpoint");
+            }
+        }
+        const requiredPermissions = this.config.auth.permissions;
+        if (requiredPermissions && requiredPermissions.length > 0) {
+            const userPermissions = user?.permissions ?? [];
+            if (!requiredPermissions.every((permission) => userPermissions.includes(permission))) {
+                logger.warn(`[WebSocket] Rejected connection to ${path}: missing a required permission`);
+                throw new WebSocketConnectionError("Insufficient permissions for this WebSocket endpoint");
+            }
+        }
         const connection = {
             id: generateConnectionId(),
             socket,
@@ -284,6 +325,17 @@ export class WebSocketConnectionManager {
         }
     }
 }
+/**
+ * Narrow an incoming message's raw `id` field to the one shape it is safe to
+ * echo back (see `WebSocketRequestId`); anything else — including a missing
+ * field, since most callers won't opt into correlation at all — is treated
+ * as "no id".
+ */
+function readRequestId(value) {
+    return typeof value === "string" || typeof value === "number"
+        ? value
+        : undefined;
+}
 /**
  * WebSocket message router for handling different message types
  */
@@ -309,7 +361,8 @@ export class WebSocketMessageRouter {
         catch {
             throw new WebSocketError("Invalid JSON message");
         }
-        const { type, payload } = parsed;
+        const { type, payload, id } = parsed;
+        const requestId = readRequestId(id);
         if (!type) {
             throw new WebSocketError("Message type is required");
         }
@@ -317,7 +370,22 @@ export class WebSocketMessageRouter {
         if (!handler) {
             throw new WebSocketError(`Unknown message type: ${type}`);
         }
-        return handler(connection, payload);
+        const result = await handler(connection, payload, requestId);
+        // Overlapping in-flight messages on one connection previously produced
+        // response frames with nothing tying them back to the request that
+        // caused them (silent when the client had more than one call open at
+        // once). A route that already tags its own frame — the streaming route
+        // does, for the intermediate frames it sends directly — is left alone;
+        // this only fills in the id for a plain result object that doesn't
+        // carry one, so a route that ignores `requestId` still gets correlated
+        // for free, and a client that never sends an `id` sees no change at all.
+        if (requestId !== undefined &&
+            result !== null &&
+            typeof result === "object" &&
+            !("id" in result)) {
+            return { ...result, id: requestId };
+        }
+        return result;
     }
     /**
      * Get registered routes
@@ -329,23 +397,110 @@ export class WebSocketMessageRouter {
 /**
  * Create a WebSocket handler for AI agent interactions
  */
-export function createAgentWebSocketHandler(_neurolink) {
+/**
+ * Send one frame, reporting failure instead of throwing.
+ *
+ * A socket that has already closed throws on `send`. That matters in two
+ * places here: mid-stream, where an unguarded throw unwinds into `onMessage`'s
+ * catch, which then tries to send an error frame on the same dead socket and
+ * throws again — this time with nothing above it to catch, i.e. an unhandled
+ * rejection; and in that catch itself, for the same reason. Returning a
+ * boolean lets both callers stop cleanly instead.
+ */
+function trySend(connection, payload) {
+    const socket = connection.socket;
+    try {
+        socket.send(JSON.stringify(payload));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Pull a correlation id off a raw incoming frame without depending on
+ * `WebSocketMessageRouter.handle` having successfully parsed it — the one
+ * case this is for is a message that fails *inside* `handle` (bad JSON,
+ * missing type, unknown route), where the router never gets far enough to
+ * return the id it would otherwise have tagged the response with. Failure
+ * here (not text, not JSON, no `id`) just means "no id", the same as if the
+ * client never sent one.
+ */
+function readIncomingRequestId(message) {
+    if (message.type !== "text") {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(message.data);
+        return readRequestId(parsed.id);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function createAgentWebSocketHandler(neurolink) {
     const router = new WebSocketMessageRouter();
     // Register message routes
+    //
+    // `payload` is attacker-controlled JSON (WebSocketMessageRouter.handle does
+    // nothing but JSON.parse it), so `generate`/`stream` validate it against
+    // `WebSocketAgentRequestSchema` before it reaches the SDK rather than
+    // trusting a bare type assertion. The schema's `options` allowlist is
+    // deliberately narrower than `GenerateOptions`/`StreamOptions` — most
+    // importantly it has no `credentials` field, so a client can no longer
+    // point the server's outbound request at an arbitrary `baseURL` (SSRF) or
+    // swap in its own provider API key.
     router.route("generate", async (connection, payload) => {
-        const { prompt, options: _options } = payload;
-        // TODO(#1576): Implement generate using neurolink
-        return { type: "response", data: `Received: ${prompt}` };
+        const parsed = WebSocketAgentRequestSchema.safeParse(payload);
+        if (!parsed.success) {
+            throw new WebSocketError(`Invalid generate payload: ${parsed.error.issues.map((issue) => issue.message).join(", ")}`);
+        }
+        const { prompt, options } = parsed.data;
+        const result = await neurolink.generate({
+            ...options,
+            input: { text: prompt },
+        });
+        return { type: "response", content: result.content };
     });
-    router.route("stream", async (connection, payload) => {
-        const { prompt, options: _options } = payload;
-        // TODO(#1576): Implement streaming using neurolink
-        return { type: "stream_start", data: { prompt } };
+    router.route("stream", async (connection, payload, requestId) => {
+        const parsed = WebSocketAgentRequestSchema.safeParse(payload);
+        if (!parsed.success) {
+            throw new WebSocketError(`Invalid stream payload: ${parsed.error.issues.map((issue) => issue.message).join(", ")}`);
+        }
+        const { prompt, options } = parsed.data;
+        // stream_start/chunk are sent directly through trySend rather than
+        // returned, so — unlike generate/tool_call's single returned frame —
+        // they sit outside WebSocketMessageRouter.handle's own id-tagging and
+        // must carry the correlation id themselves.
+        const withRequestId = (frame) => requestId !== undefined ? { ...frame, id: requestId } : frame;
+        if (!trySend(connection, withRequestId({ type: "stream_start", data: { prompt } }))) {
+            return undefined;
+        }
+        const result = await neurolink.stream({
+            ...options,
+            input: { text: prompt },
+        });
+        let clientPresent = true;
+        for await (const chunk of result.stream) {
+            if ("content" in chunk && typeof chunk.content === "string") {
+                if (!trySend(connection, withRequestId({ type: "chunk", content: chunk.content }))) {
+                    // The client is gone. Breaking runs the stream's IteratorClose,
+                    // which now aborts the upstream request rather than leaving it in
+                    // flight for a reader that no longer exists.
+                    clientPresent = false;
+                    logger.info(`[AgentWebSocket] Client went away mid-stream: ${connection.id}`);
+                    break;
+                }
+            }
+        }
+        // Returning nothing keeps onMessage from sending a completion frame on a
+        // socket that just refused one.
+        return clientPresent ? { type: "stream_complete" } : undefined;
     });
     router.route("tool_call", async (connection, payload) => {
-        const { toolName, args: _args } = payload;
-        // TODO(#1576): Implement tool call using neurolink
-        return { type: "tool_result", data: { toolName, result: null } };
+        const { toolName, args } = payload;
+        const result = await neurolink.executeTool(toolName, args);
+        return { type: "tool_result", toolName, result };
     });
     return {
         onOpen: async (connection) => {
@@ -358,19 +513,31 @@ export function createAgentWebSocketHandler(_neurolink) {
             }));
         },
         onMessage: async (connection, message) => {
+            // Best-effort only: a malformed frame still fails inside
+            // router.handle below (and reports as an id-less error, same as
+            // before), this just lets a *valid* frame's error response carry the
+            // same correlation id a successful response would have gotten.
+            const requestId = readIncomingRequestId(message);
             try {
                 const result = await router.handle(connection, message);
                 if (result) {
-                    const socket = connection.socket;
-                    socket.send(JSON.stringify(result));
+                    trySend(connection, result);
                 }
             }
             catch (error) {
-                const socket = connection.socket;
-                socket.send(JSON.stringify({
+                // Guarded: this catch is the last line of defence, so a throw from
+                // the send itself — which is exactly what a closed socket does — has
+                // nothing above it and would surface as an unhandled rejection.
+                const errorFrame = {
                     type: "error",
                     error: error.message,
-                }));
+                };
+                if (requestId !== undefined) {
+                    errorFrame.id = requestId;
+                }
+                if (!trySend(connection, errorFrame)) {
+                    logger.warn(`[AgentWebSocket] Could not deliver error frame, socket closed: ${connection.id}`);
+                }
             }
         },
         onClose: async (connection, code, reason) => {

package/dist/types/cli.d.ts

@@ -1753,6 +1753,17 @@ export type CliClassifierRouterFlags = {
     /** LLM-classifier hard timeout in ms (--classifier-timeout). */
     classifierTimeout?: number;
 };
+/**
+ * `neurolink voices` arguments — TTS voice discovery.
+ */
+export type CliVoicesCommandArgs = {
+    /** TTS provider whose voices to list (e.g. google-ai, openai-tts). */
+    provider: string;
+    /** Optional language filter passed through to the provider (e.g. en-US). */
+    language?: string;
+    /** Emit the raw list as JSON instead of a table. */
+    json?: boolean;
+};
 /**
  * Agent command arguments for multi-agent orchestration
  */

package/dist/types/generate.d.ts

@@ -1453,6 +1453,21 @@ export type TextGenerationOptions = {
          */
         outputFormat?: VisionImageOutputFormat;
     };
+    /**
+     * Video processing options (mirrors `GenerateOptions.videoOptions`). Never
+     * declared here before, so `buildGenerateTextOptions` had nowhere to
+     * forward the caller's setting even once the allowlist itself named it.
+     */
+    videoOptions?: {
+        /** Frames to extract. Unset lets VideoProcessor pick from the clip's duration; clamped to 100. */
+        frames?: number;
+        /** Frame encoder quality, clamped to 1-100. Default 80. */
+        quality?: number;
+        /** Frame encoding. Default jpeg. */
+        format?: "jpeg" | "png";
+        /** Not implemented yet (#433) — warns rather than silently doing nothing. */
+        transcribeAudio?: boolean;
+    };
     enableSummarization?: boolean;
     /**
      * Skip injecting tool schemas into the system prompt.

package/dist/types/isolatedAgent.d.ts

@@ -43,13 +43,22 @@ export type WorkerInstanceOptions = {
      * Log bridge sink. Fire-and-forget: listener errors never disrupt the
      * worker.
      *
-     * KNOWN LIMITATION: the underlying NeuroLink logger is process-global with
-     * a single active emitter, so this bridge receives ALL NeuroLink log
-     * events emitted in the process (host, other workers, MCP) for the
-     * worker's lifetime, each stamped with this worker's `tag`. The tag
-     * identifies which bridge forwarded the event, not which instance emitted
-     * it. Per-instance log attribution requires per-instance logger routing —
-     * tracked as follow-up work in the RFC.
+     * Receives only log events this worker emitted. The logger routes per
+     * instance: the worker's `generate` / `stream` / `generateText` run their
+     * bodies inside an AsyncLocalStorage scope carrying the worker's id, and
+     * this bridge is subscribed to that id — so a sibling worker's, the host's
+     * or a background MCP reconnect's logs never arrive here, and `tag` is
+     * true attribution rather than "whichever bridge forwarded it".
+     *
+     * Two things stay outside the scope, by construction:
+     * - Logs emitted while a **consumer drains a returned stream**. Iteration
+     *   happens in the consumer's async context, after `stream()` resolved.
+     * - Logs emitted **outside any call** — construction, background MCP
+     *   reconnects, module init. These are unattributed rather than charged to
+     *   an arbitrary instance.
+     *
+     * A process-wide sink (`logger.setEventEmitter`) still sees everything, so
+     * a host bridge is unaffected by this narrowing.
      */
     onLog?: (event: WorkerLogEvent) => void;
     /**

package/dist/types/openaiCompatible.d.ts

@@ -246,6 +246,12 @@ export type StreamLoopArgs = {
         totalTokens: number;
     }) => void;
     resolveFinish: (reason: string) => void;
+    /**
+     * `response_format` for this turn's requests, computed once up front from
+     * `options.schema` (see `suppressResponseFormatWithTools`). Absent when no
+     * schema was requested, or when tools suppress it.
+     */
+    responseFormat?: OpenAICompatResponseFormat;
 };
 export type OpenAICompatBuildBodyArgs = {
     modelId: string;

package/dist/types/providerCatalog.generated.d.ts

@@ -1,2 +1,2 @@
-export type CatalogProviderName = "api-route" | "baseten" | "cerebras" | "cloudflare" | "deepseek" | "fireworks" | "friendli" | "gmicloud" | "groq" | "huggingface" | "inception-labs" | "io-intelligence" | "mancer" | "mistral" | "perplexity" | "sambanova" | "together-ai" | "upstage" | "xai";
-export type CatalogCredentialKey = "apiRoute" | "baseten" | "cerebras" | "cloudflare" | "deepseek" | "fireworks" | "friendli" | "gmicloud" | "groq" | "huggingFace" | "inceptionLabs" | "ioIntelligence" | "mancer" | "mistral" | "perplexity" | "sambanova" | "together" | "upstage" | "xai";
+export type CatalogProviderName = "api-route" | "baseten" | "cerebras" | "cloudflare" | "deepseek" | "fireworks" | "friendli" | "gmicloud" | "groq" | "huggingface" | "inception-labs" | "io-intelligence" | "mancer" | "mistral" | "morph" | "novita" | "perplexity" | "sambanova" | "together-ai" | "upstage" | "xai";
+export type CatalogCredentialKey = "apiRoute" | "baseten" | "cerebras" | "cloudflare" | "deepseek" | "fireworks" | "friendli" | "gmicloud" | "groq" | "huggingFace" | "inceptionLabs" | "ioIntelligence" | "mancer" | "mistral" | "morph" | "novita" | "perplexity" | "sambanova" | "together" | "upstage" | "xai";

package/dist/types/providers.d.ts

@@ -229,6 +229,14 @@ export type NeurolinkCredentials = {
         apiKey?: string;
         baseURL?: string;
     };
+    morph?: {
+        apiKey?: string;
+        baseURL?: string;
+    };
+    novita?: {
+        apiKey?: string;
+        baseURL?: string;
+    };
     perplexity?: {
         apiKey?: string;
         baseURL?: string;
@@ -1761,8 +1769,31 @@ export type ProviderHealthCheckOptions = {
     includeConnectivityTest?: boolean;
     includeModelValidation?: boolean;
     cacheResults?: boolean;
+    /**
+     * Max age (ms) of a cached health-check result before it is treated as
+     * stale. Only consulted when `cacheResults` is true — with
+     * `cacheResults: false` this option has no effect. It does not affect the
+     * circuit breaker's blacklist expiry, which uses its own fixed window
+     * independent of any caller's `maxCacheAge`.
+     */
     maxCacheAge?: number;
 };
+/**
+ * Outcome of a provider-specific config check's own outbound runtime probe
+ * (LiteLLM's `/v1/models`, Ollama's `/api/tags` availability check) — the
+ * request `checkLiteLLMConfig`/`checkOllamaConfig` make from inside step 1
+ * (`checkEnvironmentConfiguration`), independent of the step-3 connectivity
+ * test. `checkProviderHealth`'s circuit breaker needs to know whether this
+ * probe ran at all (a blacklisted provider skips it — `ran: false`) and,
+ * if it ran, whether it failed, so a dead local proxy counts toward the
+ * breaker the same way a failing step-3 probe does. `ran: false` must never
+ * move the breaker either way — it is not evidence the provider is up OR
+ * down.
+ */
+export type ProviderRuntimeProbeOutcome = {
+    ran: boolean;
+    failed: boolean;
+};
 /**
  * Amazon Bedrock specific types
  */
@@ -2023,14 +2054,30 @@ export type ProviderDescriptor = {
     /** How ProviderHealthChecker should verify this provider is reachable. */
     healthCheck: "env-only" | "models-probe" | "live-generate";
     /**
-     * Membership + order in the default health sweep
+     * ORDER (not membership) in the default health sweep
      * (`ProviderHealthChecker.checkAllProvidersHealth` with no explicit
      * list). Lower number = checked and reported first; the sweep's array
      * order is behaviour for its first-healthy fallback consumers. Absent =
-     * not part of the default sweep. Replaces the hand-maintained 8-provider
-     * array that lived in providerHealth.ts.
+     * sorted after every explicitly-prioritized descriptor, in this file's
+     * declaration order (a stable sort, so ties never reorder). Originally
+     * this field ALSO controlled membership (absent = excluded), which
+     * silently dropped every provider added without it from the sweep —
+     * issue #1305, ~30 of ~38 registered providers, undocumented. Membership
+     * is now `excludeFromHealthSweep` below, which every new descriptor
+     * satisfies by default without needing this field at all.
      */
     defaultHealthSweepPriority?: number;
+    /**
+     * Opt a provider OUT of `checkAllProvidersHealth`'s default sweep. Every
+     * registered descriptor participates by default — a newly added provider
+     * needs no action to be included, which is the fix for issue #1305
+     * (silent, undocumented exclusion of most providers). Set this only for a
+     * descriptor that genuinely should never appear in a health rollup; no
+     * current descriptor sets it. `checkProviderHealth()` for a single named
+     * provider is unaffected either way — this only gates the "all
+     * providers" sweep.
+     */
+    excludeFromHealthSweep?: true;
     /**
      * Preference rank for `getBestHealthyProvider`'s default auto-selection
      * (lower = tried first). Deliberately a SEPARATE ordering from the sweep:

package/dist/types/server.d.ts

@@ -682,6 +682,14 @@ export type WebSocketMessage = {
     data: string | ArrayBuffer;
     timestamp: number;
 };
+/**
+ * Client-supplied correlation id on an agent-protocol WebSocket message
+ * (`{ type, payload, id }`). Echoed back on the matching response frame so a
+ * caller with more than one in-flight message on a connection can tell which
+ * frame answers which request; optional and ignored entirely by a client
+ * that never sends one.
+ */
+export type WebSocketRequestId = string | number;
 /**
  * Authenticated user information
  */

package/dist/types/stream.d.ts

@@ -838,6 +838,36 @@ export type StreamResult = {
         stopReason?: GenerateStopReason;
         rawFinishReason?: string;
         stepsUsed?: number;
+        /**
+         * Parsed structured output for a `stream({ schema })` turn, available
+         * AFTER the stream has been drained.
+         *
+         * Lives on metadata for the same reason `finishReason` above does: it is a
+         * mutable reference the loop fills in, so result-object spreads in stream
+         * wrappers cannot snapshot it before it resolves. A plain field rather than
+         * a promise, deliberately — when a middleware short-circuits the request
+         * and the loop never runs, an unresolved promise would hang every reader,
+         * whereas an absent field is simply absent. Readers must tolerate that:
+         * absence means the model never produced the object.
+         */
+        structuredData?: unknown;
+        /**
+         * Tokens spent by the tool-free re-ask that produced `structuredData`,
+         * when one was needed.
+         *
+         * That re-ask is a second, separately-billed model call, and the stream's
+         * own `usage` has already resolved by the time it runs — so folding these
+         * tokens into it would mutate a value a caller may have read, and leaving
+         * them out entirely would under-report what the turn cost. Reported here
+         * instead: same delivery as `structuredData`, filled at the same moment,
+         * read at the same moment. Absent when no re-ask was needed, which is the
+         * common case. The generate path accounts for its equivalent re-ask
+         * inline, since there the usage has not been handed out yet.
+         */
+        structuredDataUsage?: {
+            inputTokens: number;
+            outputTokens: number;
+        };
         thoughtSignature?: string;
         thoughts?: Array<{
             id?: string;

package/dist/types/tts.d.ts

@@ -164,6 +164,16 @@ export declare const VALID_AUDIO_FORMATS: readonly TTSAudioFormat[];
 export declare const VALID_TTS_QUALITIES: readonly TTSQuality[];
 /** Valid Google TTS audio formats */
 export type GoogleAudioEncoding = "MP3" | "LINEAR16" | "OGG_OPUS";
+/**
+ * Audio encodings Google's *streaming* synthesis endpoint accepts.
+ *
+ * Deliberately a separate type from {@link GoogleAudioEncoding}: the
+ * batch and streaming endpoints do not accept the same set. `MP3` and
+ * `LINEAR16` are valid for batch and rejected by streaming with
+ * `INVALID_ARGUMENT: Unsupported audio encoding`, while `PCM` — raw
+ * 16-bit signed LE, headerless — exists only on the streaming side.
+ */
+export type GoogleStreamingAudioEncoding = "PCM" | "OGG_OPUS";
 /**
  * Type guard to check if an object is a TTSResult
  */

package/dist/types/utilities.d.ts

@@ -65,9 +65,24 @@ export type LogEntry = {
     /** Optional additional data associated with the log entry (objects, arrays, etc.) */
     data?: unknown;
 };
+/**
+ * Minimal emitter shape the logger forwards `"log-event"` payloads to.
+ *
+ * Structurally satisfied by `node:events`' `EventEmitter` and by NeuroLink's
+ * own typed emitter, so a sink can be either.
+ */
+export type LogEventEmitter = {
+    emit: (event: string, ...args: unknown[]) => boolean;
+};
 /**
  * Logger interface matching the logger object shape
  * Used for SDK tool contexts and other components that need a logger
+ *
+ * Deliberately a subset of the real logger: the per-instance routing methods
+ * (`runInInstanceScope`, `addScopedEventEmitter`, …) are internal plumbing
+ * between the SDK entry points and the logger, and this type is a structural
+ * contract a caller can satisfy — `SDKToolContext.logger`. Adding required
+ * members here would break anyone constructing that context themselves.
  */
 export type Logger = {
     debug: (...args: unknown[]) => void;
@@ -79,9 +94,7 @@ export type Logger = {
     setLogLevel: (level: LogLevel) => void;
     getLogs: (level?: LogLevel) => LogEntry[];
     clearLogs: () => void;
-    setEventEmitter: (emitter: {
-        emit: (event: string, ...args: unknown[]) => boolean;
-    }) => void;
+    setEventEmitter: (emitter: LogEventEmitter) => void;
     clearEventEmitter: () => void;
 };
 export type StructuredError = {

package/dist/utils/logger.d.ts

@@ -13,7 +13,7 @@
  * - Structured data support for complex objects
  * - Tabular data display
  */
-import type { LogEntry, LogLevel } from "../types/index.js";
+import type { LogEntry, LogEventEmitter, LogLevel } from "../types/index.js";
 declare class NeuroLinkLogger {
     private logLevel;
     private logs;
@@ -21,6 +21,7 @@ declare class NeuroLinkLogger {
     private isDebugMode;
     private diagnosticsToStderr;
     private eventEmitter?;
+    private readonly scopedEmitters;
     constructor();
     /**
      * Sets the event emitter that will receive log events.
@@ -28,9 +29,7 @@ declare class NeuroLinkLogger {
      *
      * @param emitter - The event emitter instance
      */
-    setEventEmitter(emitter: {
-        emit: (event: string, ...args: unknown[]) => boolean;
-    }): void;
+    setEventEmitter(emitter: LogEventEmitter): void;
     /**
      * Clears the event emitter reference.
      * Should be called when a NeuroLink instance is disposed to prevent memory
@@ -40,9 +39,54 @@ declare class NeuroLinkLogger {
      *
      * @param ifEmitter - When provided, clear only if it is the current emitter
      */
-    clearEventEmitter(ifEmitter?: {
-        emit: (event: string, ...args: unknown[]) => boolean;
-    }): void;
+    clearEventEmitter(ifEmitter?: LogEventEmitter): void;
+    /**
+     * Runs `fn` with every log call beneath it attributed to `instanceId`.
+     *
+     * Nesting is safe and expected: a host turn that delegates to a worker ends
+     * up with the worker's id on top for the duration of the worker's call, and
+     * the host's id restored afterwards. Re-entering with the same id is a
+     * no-op in effect.
+     *
+     * @param instanceId - Identifier of the emitting NeuroLink instance
+     * @param fn - Work to run inside the scope
+     * @returns Whatever `fn` returns
+     */
+    runInInstanceScope<T>(instanceId: string, fn: () => T): T;
+    /**
+     * The instance id currently attributed, or undefined outside any scope.
+     */
+    getInstanceScope(): string | undefined;
+    /**
+     * Subscribes `emitter` to log events emitted by one instance only.
+     *
+     * Unlike {@link setEventEmitter} — a single process-wide sink that receives
+     * everything — a scoped emitter receives only events logged inside that
+     * instance's {@link runInInstanceScope}. Several emitters may share an id.
+     *
+     * @param instanceId - Instance whose events this emitter should receive
+     * @param emitter - The sink to subscribe
+     */
+    addScopedEventEmitter(instanceId: string, emitter: LogEventEmitter): void;
+    /**
+     * Unsubscribes a scoped emitter. Must be called when the owning instance is
+     * disposed, or the emitter — and everything it closes over — is retained by
+     * the process-global logger for the lifetime of the process.
+     *
+     * @param instanceId - Instance the emitter was registered against
+     * @param emitter - The sink to unsubscribe
+     */
+    removeScopedEventEmitter(instanceId: string, emitter: LogEventEmitter): void;
+    /**
+     * Drops every scoped emitter registered against an instance.
+     *
+     * Called from `NeuroLink.dispose()`: the registry lives on the
+     * process-global logger, so an instance that goes away without clearing its
+     * own entry would keep its sinks — and their closures — reachable forever.
+     *
+     * @param instanceId - Instance whose sinks should be dropped
+     */
+    clearScopedEventEmitters(instanceId: string): void;
     /**
      * Sets the minimum log level that will be processed and output.
      * Log messages with a level lower than this will be ignored.
@@ -234,12 +278,13 @@ export declare const logger: {
     setDiagnosticsToStderr: (enabled: boolean) => void;
     getLogs: (level?: LogLevel) => LogEntry[];
     clearLogs: () => void;
-    setEventEmitter: (emitter: {
-        emit: (event: string, ...args: unknown[]) => boolean;
-    }) => void;
-    clearEventEmitter: (ifEmitter?: {
-        emit: (event: string, ...args: unknown[]) => boolean;
-    }) => void;
+    setEventEmitter: (emitter: LogEventEmitter) => void;
+    clearEventEmitter: (ifEmitter?: LogEventEmitter) => void;
+    runInInstanceScope: <T>(instanceId: string, fn: () => T) => T;
+    getInstanceScope: () => string | undefined;
+    addScopedEventEmitter: (instanceId: string, emitter: LogEventEmitter) => void;
+    removeScopedEventEmitter: (instanceId: string, emitter: LogEventEmitter) => void;
+    clearScopedEventEmitters: (instanceId: string) => void;
 };
 /**
  * MCP compatibility exports - all use the same unified logger instance.