@juspay/neurolink 13.8.17 → 13.8.19

package/dist/server/routes/transcribeRoutes.js

@@ -17,6 +17,7 @@ import { withSpan } from "../../telemetry/withSpan.js";
 import { tracers } from "../../telemetry/tracers.js";
 import { logger } from "../../utils/logger.js";
 import { MAX_AUDIO_BYTES } from "../../utils/sizeGuard.js";
+import { clientFacingError, logClientFacingError, PROVIDER_NOT_CONFIGURED_MESSAGE, } from "../utils/clientError.js";
 import { RawBodyTooLargeError } from "../utils/rawBody.js";
 import { getSTTProviderDescriptor, listConfiguredSTTProviders, resolveDefaultSTTProvider, resolveSTTEndpoints, } from "../../factories/sttDescriptors.js";
 import { STTProcessor } from "../../utils/sttProcessor.js";
@@ -170,7 +171,15 @@ async function resolveAudio(request, options, limit) {
             });
         }
         catch (error) {
-            throw new TranscribeRequestError(`could not download audioUrl: ${error instanceof Error ? error.message : String(error)}`, 400, "VALIDATION_ERROR");
+            // The guard's reason can name the address a host resolved to, which
+            // would let a caller map the server's network one URL at a time. The
+            // caller gets a fixed message; the operator gets the reason in the log,
+            // with the URL itself redacted (as agentInput.ts does).
+            const reason = error instanceof Error ? error.message : String(error);
+            logger.warn("[transcribeRoutes] refused an audioUrl", {
+                reason: reason.replaceAll(request.audioUrl, "<url>"),
+            });
+            throw new TranscribeRequestError("audioUrl could not be fetched (it must be a public https URL, answer without a redirect and fit the size limit)", 400, "VALIDATION_ERROR");
         }
         return {
             audio,
@@ -213,7 +222,14 @@ function toTranscribeOptions(config, audio, format, maxAudioBytes) {
         ...(config.timeoutMs !== undefined ? { timeoutMs: config.timeoutMs } : {}),
     };
 }
-/** Status and code for an error thrown by `transcribe()` or by this file. */
+/**
+ * Status, code and the message the client may see for an error thrown by
+ * `transcribe()` or by this file. The exception's own text is passed through
+ * only when this file composed it or when it describes the request (an empty
+ * or malformed recording); a missing engine is named by category, never by
+ * the variable that would configure it, and anything else is reduced to a
+ * fixed message. The detail is logged by the caller.
+ */
 function classifyError(error) {
     const message = error instanceof Error ? error.message : String(error);
     if (error instanceof TranscribeRequestError) {
@@ -222,10 +238,26 @@ function classifyError(error) {
     const code = typeof error === "object" && error !== null && "code" in error
         ? String(error.code)
         : undefined;
+    if (code === "STT_PROVIDER_NOT_CONFIGURED") {
+        return {
+            status: 503,
+            code: "PROVIDER_NOT_CONFIGURED",
+            message: PROVIDER_NOT_CONFIGURED_MESSAGE,
+        };
+    }
     if (code && CLIENT_ERROR_CODES.has(code)) {
         return { status: 400, code: "VALIDATION_ERROR", message };
     }
-    return { status: 500, code: "EXECUTION_FAILED", message };
+    const shaped = clientFacingError(error);
+    return shaped.status === 500
+        ? { ...shaped, code: "EXECUTION_FAILED" }
+        : shaped;
+}
+/** `classifyError` plus the server-side log the client-facing message leaves out. */
+function classifyAndLog(ctx, route, error) {
+    const classified = classifyError(error);
+    logClientFacingError(`transcribeRoutes ${route}`, ctx.requestId, error, classified);
+    return classified;
 }
 async function runTranscription(ctx, route, options) {
     return withSpan({
@@ -420,11 +452,7 @@ async function handleOpenAITranscription(ctx, options, limit, route) {
         result = await runTranscription(ctx, route, toTranscribeOptions(parsed.data, audio, format, limit));
     }
     catch (error) {
-        const classified = classifyError(error);
-        logger.warn("[transcribeRoutes] OpenAI-compatible transcription failed", {
-            requestId: ctx.requestId,
-            error: classified.message,
-        });
+        const classified = classifyAndLog(ctx, route, error);
         return openAIError(classified.status, classified.message);
     }
     if (responseFormat === "text") {
@@ -541,7 +569,17 @@ export function createTranscribeRoutes(basePath = "/api", options = {}) {
     const nativePath = `${basePath}/agent/transcribe`;
     const openaiPath = `${options.openaiBasePath ?? ""}/v1/audio/transcriptions`;
     const evalPath = `${options.openaiBasePath ?? ""}/v1/evals/stt`;
-    const evalStore = options.evals === false ? undefined : new STTEvalStore(options.evals);
+    // The collector keeps every transcript it is sent and reads them back to
+    // whoever asks, so it is mounted only when the operator asks for it: an
+    // options object, or NEUROLINK_STT_EVAL_ENABLED=1. It used to be on by
+    // default.
+    const evalStore = options.evals === false
+        ? undefined
+        : options.evals !== undefined
+            ? new STTEvalStore(options.evals)
+            : process.env.NEUROLINK_STT_EVAL_ENABLED?.trim() === "1"
+                ? new STTEvalStore()
+                : undefined;
     return {
         // Empty prefix: the two routes live under different roots, and every
         // route path already starts with "", so the adapters add nothing.
@@ -561,7 +599,7 @@ export function createTranscribeRoutes(basePath = "/api", options = {}) {
                         return await runTranscription(ctx, nativePath, toTranscribeOptions(request, audio, format, limit));
                     }
                     catch (error) {
-                        const classified = classifyError(error);
+                        const classified = classifyAndLog(ctx, nativePath, error);
                         return createErrorResponse(classified.code, classified.message, undefined, ctx.requestId, classified.status);
                     }
                 },
@@ -593,6 +631,11 @@ export function createTranscribeRoutes(basePath = "/api", options = {}) {
  * apart they were per speaker.
  */
 function createEvalRoutes(evalPath, store) {
+    // A person the server identified owns the calls they post and sees only
+    // those; a shared key names no person, so its calls are visible to every
+    // holder, as before. The handler sees ctx.user only when the server carries
+    // middleware state (see ServerAdapterConfig.carryMiddlewareState).
+    const ownerOf = (ctx) => ctx.user && ctx.user.shared !== true ? ctx.user.id : undefined;
     return [
         {
             method: "POST",
@@ -603,7 +646,9 @@ function createEvalRoutes(evalPath, store) {
                     return validation.error;
                 }
                 const batch = validation.data;
-                return store.accept(batch);
+                const accepted = await store.accept(batch, ownerOf(ctx));
+                return (accepted ??
+                    createErrorResponse("FORBIDDEN", "This call belongs to another caller", undefined, ctx.requestId, 403));
             },
             description: "Accept a batch of one call's segments from two STTs (primary shown, shadow for evaluation); a resent segment id replaces the earlier one",
             tags: ["transcribe", "evaluation"],
@@ -611,7 +656,9 @@ function createEvalRoutes(evalPath, store) {
         {
             method: "GET",
             path: evalPath,
-            handler: async () => ({ calls: await store.list() }),
+            handler: async (ctx) => ({
+                calls: await store.list(ownerOf(ctx)),
+            }),
             description: "Calls collected for STT evaluation, most recent first",
             tags: ["transcribe", "evaluation"],
         },
@@ -622,7 +669,7 @@ function createEvalRoutes(evalPath, store) {
                 // Adapters already decode path params; decoding again would turn a
                 // literal "%" in an id into something else, or throw on "%E0%A4%A".
                 const callId = ctx.params.callId ?? "";
-                const report = await store.report(callId, ctx.query.segments === "true");
+                const report = await store.report(callId, ctx.query.segments === "true", ownerOf(ctx));
                 return (report ??
                     createErrorResponse("NOT_FOUND", `No STT evaluation for call ${callId}`, undefined, ctx.requestId, 404));
             },

package/dist/server/utils/clientAddress.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The address a request is counted against.
+ *
+ * The TCP peer is the only address a client cannot choose, so it is the
+ * default. `X-Forwarded-For` is read only when the operator says a reverse
+ * proxy stands in front of the server (`trustProxy`), and then from the right:
+ * the hops of the listed proxies are skipped and the first other entry is the
+ * client, because a proxy appends the address it saw and anything a client put
+ * in the header itself sits further left.
+ *
+ * @module server/utils/clientAddress
+ */
+import type { ServerClientAddressInput } from "../../types/index.js";
+/** Strip an IPv4-mapped IPv6 prefix and a port, so one client has one key. */
+export declare function canonicalAddress(address: string): string | undefined;
+/**
+ * The client's address, or `undefined` when the runtime reports no peer and
+ * no trusted header names one. The result is always a bare IP, so a header
+ * holding anything else cannot become a counter key.
+ */
+export declare function resolveClientAddress(input: ServerClientAddressInput): string | undefined;
+/** `true` for an address only this host can reach: 127/8, `::1`, or their mapped forms. */
+export declare function isLoopbackAddress(address: string | undefined): boolean;

package/dist/server/utils/clientAddress.js

@@ -0,0 +1,65 @@
+/**
+ * The address a request is counted against.
+ *
+ * The TCP peer is the only address a client cannot choose, so it is the
+ * default. `X-Forwarded-For` is read only when the operator says a reverse
+ * proxy stands in front of the server (`trustProxy`), and then from the right:
+ * the hops of the listed proxies are skipped and the first other entry is the
+ * client, because a proxy appends the address it saw and anything a client put
+ * in the header itself sits further left.
+ *
+ * @module server/utils/clientAddress
+ */
+import { isIP } from "node:net";
+/** Strip an IPv4-mapped IPv6 prefix and a port, so one client has one key. */
+export function canonicalAddress(address) {
+    let value = address.trim();
+    if (value.startsWith("[")) {
+        const end = value.indexOf("]");
+        value = end === -1 ? value.slice(1) : value.slice(1, end);
+    }
+    else if (/^\d{1,3}(\.\d{1,3}){3}:\d+$/.test(value) ||
+        /^[^:]+:\d+$/.test(value)) {
+        value = value.slice(0, value.lastIndexOf(":"));
+    }
+    if (value.toLowerCase().startsWith("::ffff:") && isIP(value.slice(7)) === 4) {
+        value = value.slice(7);
+    }
+    return isIP(value) ? value : undefined;
+}
+/**
+ * The client's address, or `undefined` when the runtime reports no peer and
+ * no trusted header names one. The result is always a bare IP, so a header
+ * holding anything else cannot become a counter key.
+ */
+export function resolveClientAddress(input) {
+    const peer = input.remoteAddress
+        ? canonicalAddress(input.remoteAddress)
+        : undefined;
+    if (!input.trustProxy || !input.forwardedFor) {
+        return peer;
+    }
+    const trusted = new Set(input.trustedProxies
+        .map(canonicalAddress)
+        .filter((value) => value !== undefined));
+    const hops = input.forwardedFor
+        .split(",")
+        .map(canonicalAddress)
+        .filter((value) => value !== undefined);
+    for (let index = hops.length - 1; index >= 0; index--) {
+        if (!trusted.has(hops[index])) {
+            return hops[index];
+        }
+    }
+    return peer;
+}
+/** `true` for an address only this host can reach: 127/8, `::1`, or their mapped forms. */
+export function isLoopbackAddress(address) {
+    if (!address) {
+        return false;
+    }
+    const value = canonicalAddress(address) ?? address.trim().toLowerCase();
+    return (value === "::1" ||
+        value === "localhost" ||
+        /^127\.\d+\.\d+\.\d+$/.test(value));
+}

package/dist/server/utils/clientError.d.ts

@@ -0,0 +1,35 @@
+/**
+ * What a failed request may tell the client.
+ *
+ * An exception's text names environment variables, provider wiring, file
+ * paths and upstream response bodies; none of that belongs in a response to
+ * an unknown caller. A route therefore answers with one of a few fixed
+ * messages plus the request id, and the detail goes to the server log under
+ * that id, where the operator can find it. The pattern is the one the OpenAI
+ * proxy route already followed.
+ *
+ * What is passed through: a `ServerAdapterError` below 500, whose message
+ * this server composed (a validation failure, a missing route), and the
+ * category of a provider that is missing credentials, without saying which
+ * credential.
+ *
+ * @module server/utils/clientError
+ */
+import type { ServerClientFacingError } from "../../types/index.js";
+export declare const GENERIC_ERROR_MESSAGE = "An internal error occurred";
+export declare const PROVIDER_NOT_CONFIGURED_MESSAGE = "The requested provider is not configured on this server";
+export declare const UPSTREAM_RATE_LIMITED_MESSAGE = "The upstream provider is rate limiting this server; retry later";
+export declare const REQUEST_TIMEOUT_MESSAGE = "The request timed out";
+/**
+ * The response for `error`. Never the exception's own text unless this
+ * server wrote it (a `ServerAdapterError` below 500).
+ */
+export declare function clientFacingError(error: unknown): ServerClientFacingError;
+/**
+ * Log the detail the client does not get, under the request id the client
+ * does get. A client error is routine traffic and logs as one line; anything
+ * else keeps its stack.
+ */
+export declare function logClientFacingError(source: string, requestId: string | undefined, error: unknown, shaped: ServerClientFacingError): void;
+/** {@link clientFacingError} and {@link logClientFacingError} in one step. */
+export declare function shapeRouteError(source: string, requestId: string | undefined, error: unknown): ServerClientFacingError;

package/dist/server/utils/clientError.js

@@ -0,0 +1,129 @@
+/**
+ * What a failed request may tell the client.
+ *
+ * An exception's text names environment variables, provider wiring, file
+ * paths and upstream response bodies; none of that belongs in a response to
+ * an unknown caller. A route therefore answers with one of a few fixed
+ * messages plus the request id, and the detail goes to the server log under
+ * that id, where the operator can find it. The pattern is the one the OpenAI
+ * proxy route already followed.
+ *
+ * What is passed through: a `ServerAdapterError` below 500, whose message
+ * this server composed (a validation failure, a missing route), and the
+ * category of a provider that is missing credentials, without saying which
+ * credential.
+ *
+ * @module server/utils/clientError
+ */
+import { AuthenticationError as ProviderAuthenticationError, RateLimitError as ProviderRateLimitError, } from "../../types/index.js";
+import { logger } from "../../utils/logger.js";
+import { ServerAdapterError } from "../errors.js";
+export const GENERIC_ERROR_MESSAGE = "An internal error occurred";
+export const PROVIDER_NOT_CONFIGURED_MESSAGE = "The requested provider is not configured on this server";
+export const UPSTREAM_RATE_LIMITED_MESSAGE = "The upstream provider is rate limiting this server; retry later";
+export const REQUEST_TIMEOUT_MESSAGE = "The request timed out";
+/** Signs that a provider refused the server's own credentials, or has none. */
+const PROVIDER_CONFIGURATION_PATTERN = /api[ _-]?key|credential|not configured|no (?:ai )?provider|authenticat|unauthori[sz]ed|forbidden|permission denied|invalid[ _-]?(?:key|token)|missing (?:required )?(?:environment|env|key|token)|environment variable/i;
+/** Names the SDK's own error classes and codes use for the same thing. */
+const PROVIDER_CONFIGURATION_CODES = new Set([
+    "AUTHENTICATION_ERROR",
+    "AUTHENTICATION_FAILED",
+    "AUTH_ERROR",
+    "INVALID_API_KEY",
+    "MISSING_API_KEY",
+    "PROVIDER_NOT_CONFIGURED",
+    "CONFIGURATION_ERROR",
+    "NO_PROVIDER",
+    "STT_PROVIDER_NOT_CONFIGURED",
+]);
+function codeOf(error) {
+    if (typeof error !== "object" || error === null) {
+        return undefined;
+    }
+    const code = error.code;
+    return typeof code === "string" ? code : undefined;
+}
+function isAbortError(error) {
+    return (error instanceof Error &&
+        (error.name === "AbortError" || error.name === "TimeoutError"));
+}
+/**
+ * The response for `error`. Never the exception's own text unless this
+ * server wrote it (a `ServerAdapterError` below 500).
+ */
+export function clientFacingError(error) {
+    if (error instanceof ServerAdapterError) {
+        // The request timeout is the server's deadline, not the client's slowness
+        // (the TIMEOUT code maps to 408 for the latter), so it answers 504.
+        if (error.name === "ServerTimeoutError") {
+            return {
+                code: "REQUEST_TIMEOUT",
+                message: REQUEST_TIMEOUT_MESSAGE,
+                status: 504,
+            };
+        }
+        const status = error.getHttpStatus();
+        if (status < 500) {
+            return { code: error.code, message: error.message, status };
+        }
+        return { code: "INTERNAL_ERROR", message: GENERIC_ERROR_MESSAGE, status };
+    }
+    if (isAbortError(error)) {
+        return {
+            code: "REQUEST_TIMEOUT",
+            message: REQUEST_TIMEOUT_MESSAGE,
+            status: 504,
+        };
+    }
+    if (error instanceof ProviderRateLimitError) {
+        return {
+            code: "UPSTREAM_RATE_LIMITED",
+            message: UPSTREAM_RATE_LIMITED_MESSAGE,
+            status: 503,
+        };
+    }
+    const code = codeOf(error);
+    const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof ProviderAuthenticationError ||
+        (code !== undefined && PROVIDER_CONFIGURATION_CODES.has(code)) ||
+        PROVIDER_CONFIGURATION_PATTERN.test(message)) {
+        return {
+            code: "PROVIDER_NOT_CONFIGURED",
+            message: PROVIDER_NOT_CONFIGURED_MESSAGE,
+            status: 503,
+        };
+    }
+    return {
+        code: "INTERNAL_ERROR",
+        message: GENERIC_ERROR_MESSAGE,
+        status: 500,
+    };
+}
+/**
+ * Log the detail the client does not get, under the request id the client
+ * does get. A client error is routine traffic and logs as one line; anything
+ * else keeps its stack.
+ */
+export function logClientFacingError(source, requestId, error, shaped) {
+    const detail = error instanceof Error ? error.message : String(error);
+    if (shaped.status < 500) {
+        logger.warn(`[${source}] Request rejected`, {
+            requestId,
+            code: shaped.code,
+            error: detail,
+        });
+        return;
+    }
+    logger.error(`[${source}] Request failed`, {
+        requestId,
+        code: shaped.code,
+        error: detail,
+        stack: error instanceof Error ? error.stack : undefined,
+    });
+}
+/** {@link clientFacingError} and {@link logClientFacingError} in one step. */
+export function shapeRouteError(source, requestId, error) {
+    const shaped = clientFacingError(error);
+    logClientFacingError(source, requestId, error, shaped);
+    return shaped;
+}

package/dist/server/utils/pathMatch.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Path matching shared by the adapters' middleware `paths` / `excludePaths`
+ * and the rate limiters' `skipPaths`.
+ *
+ * Every match is at a segment boundary: a pattern names the path itself and
+ * what lies under it as a directory would, so `/api/health` covers
+ * `/api/health` and `/api/health/live` but not `/api/healthz`. The plain
+ * prefix test the adapters used to run let the second be exempted by the
+ * first.
+ *
+ * @module server/utils/pathMatch
+ */
+/** The request path without its query string or fragment. */
+export declare function stripQuery(path: string): string;
+/**
+ * `true` when `path` is `prefix`, or lies under `prefix` at a segment
+ * boundary. `"*"`, `""` and `"/"` match every path.
+ */
+export declare function pathStartsWithSegment(path: string, prefix: string): boolean;
+/** `true` when any of `prefixes` matches `path` (see {@link pathStartsWithSegment}). */
+export declare function pathMatchesAny(path: string, prefixes: readonly string[] | undefined): boolean;

package/dist/server/utils/pathMatch.js

@@ -0,0 +1,41 @@
+/**
+ * Path matching shared by the adapters' middleware `paths` / `excludePaths`
+ * and the rate limiters' `skipPaths`.
+ *
+ * Every match is at a segment boundary: a pattern names the path itself and
+ * what lies under it as a directory would, so `/api/health` covers
+ * `/api/health` and `/api/health/live` but not `/api/healthz`. The plain
+ * prefix test the adapters used to run let the second be exempted by the
+ * first.
+ *
+ * @module server/utils/pathMatch
+ */
+/** The request path without its query string or fragment. */
+export function stripQuery(path) {
+    const cut = path.search(/[?#]/);
+    return cut === -1 ? path : path.slice(0, cut);
+}
+/** Collapse repeated slashes and drop a trailing one, keeping the root `/`. */
+function normalize(path) {
+    const collapsed = path.replace(/\/{2,}/g, "/");
+    return collapsed.length > 1 ? collapsed.replace(/\/+$/, "") : collapsed;
+}
+/**
+ * `true` when `path` is `prefix`, or lies under `prefix` at a segment
+ * boundary. `"*"`, `""` and `"/"` match every path.
+ */
+export function pathStartsWithSegment(path, prefix) {
+    if (prefix === "*" || prefix === "" || prefix === "/") {
+        return true;
+    }
+    const target = normalize(stripQuery(path));
+    const base = normalize(prefix);
+    return target === base || target.startsWith(`${base}/`);
+}
+/** `true` when any of `prefixes` matches `path` (see {@link pathStartsWithSegment}). */
+export function pathMatchesAny(path, prefixes) {
+    if (!prefixes || prefixes.length === 0) {
+        return false;
+    }
+    return prefixes.some((prefix) => pathStartsWithSegment(path, prefix));
+}

package/dist/server/utils/validation.d.ts

@@ -57,6 +57,15 @@ export declare const WebSocketAgentRequestSchema: z.ZodObject<{
         maxSteps: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/**
+ * WebSocket `tool_call` message payload schema: a tool name the registry can
+ * look up and a JSON object of arguments. The payload used to reach
+ * `executeTool` unchecked.
+ */
+export declare const WebSocketToolCallSchema: z.ZodObject<{
+    toolName: z.ZodString;
+    args: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strip>;
 /**
  * Tool execute request schema
  */

package/dist/server/utils/validation.js

@@ -55,6 +55,15 @@ export const WebSocketAgentRequestSchema = z.object({
     prompt: z.string().min(1, "Prompt is required"),
     options: WebSocketAgentOptionsSchema.optional(),
 });
+/**
+ * WebSocket `tool_call` message payload schema: a tool name the registry can
+ * look up and a JSON object of arguments. The payload used to reach
+ * `executeTool` unchecked.
+ */
+export const WebSocketToolCallSchema = z.object({
+    toolName: z.string().min(1, "toolName is required").max(256),
+    args: z.record(z.string(), z.unknown()).optional().default({}),
+});
 /**
  * Tool execute request schema
  */

package/dist/server/websocket/WebSocketHandler.js

@@ -6,7 +6,7 @@
  */
 import { WebSocketError, WebSocketConnectionError } from "../errors.js";
 import { logger } from "../../utils/logger.js";
-import { WebSocketAgentRequestSchema } from "../utils/validation.js";
+import { WebSocketAgentRequestSchema, WebSocketToolCallSchema, } from "../utils/validation.js";
 /**
  * Default WebSocket configuration
  */
@@ -36,7 +36,20 @@ export class WebSocketConnectionManager {
     pingIntervals = new Map();
     handlers = new Map();
     constructor(config = {}) {
-        this.config = { ...DEFAULT_CONFIG, ...config };
+        // A strategy other than "none" means the deployer wants callers
+        // identified, so `required` defaults to true with it: a config that named
+        // a strategy and forgot `required` used to get an open socket.
+        const strategy = config.auth?.strategy ?? DEFAULT_CONFIG.auth.strategy;
+        this.config = {
+            ...DEFAULT_CONFIG,
+            ...config,
+            auth: {
+                ...DEFAULT_CONFIG.auth,
+                ...config.auth,
+                strategy,
+                required: config.auth?.required ?? strategy !== "none",
+            },
+        };
     }
     /**
      * Register a handler for a path
@@ -498,7 +511,13 @@ export function createAgentWebSocketHandler(neurolink) {
         return clientPresent ? { type: "stream_complete" } : undefined;
     });
     router.route("tool_call", async (connection, payload) => {
-        const { toolName, args } = payload;
+        const parsed = WebSocketToolCallSchema.safeParse(payload);
+        if (!parsed.success) {
+            throw new WebSocketError(`Invalid tool_call payload: ${parsed.error.issues
+                .map((issue) => `${issue.path.join(".") || "payload"} ${issue.message}`)
+                .join("; ")}`, undefined, connection.id);
+        }
+        const { toolName, args } = parsed.data;
         const result = await neurolink.executeTool(toolName, args);
         return { type: "tool_result", toolName, result };
     });

package/dist/server/websocket/frameQueue.d.ts

@@ -2,15 +2,34 @@
  * Push-driven async iterable shared by the transcription sockets: socket
  * frames are pushed in, `transcribeStream()` pulls them out.
  *
+ * The queue reports its level to whoever feeds it, so a socket can be paused
+ * when audio arrives faster than the engine takes it and resumed once the
+ * backlog drains (TCP backpressure, instead of buffering the whole burst).
+ * Every queue also charges its bytes to one process-wide budget, so a burst
+ * of uploads across many sockets cannot exhaust the process.
+ *
  * @module server/websocket/frameQueue
  */
+/** What every queue in the process holds right now, for caps and tests. */
+export declare function totalQueuedFrameBytes(): number;
 /** Push-driven async iterable: socket frames in, `transcribeStream()` pulls. */
 export declare class FrameQueue implements AsyncIterable<Buffer> {
     private readonly frames;
     private waiting;
     private ended;
+    private onLevel;
     queuedBytes: number;
+    /** Called after every change of `queuedBytes`, with the new level. */
+    setLevelListener(listener: ((queuedBytes: number) => void) | undefined): void;
     push(frame: Buffer): void;
+    /**
+     * No more frames will arrive; the ones already queued are still handed
+     * out, so a recording whose `end` frame followed its audio is transcribed
+     * whole. The consumer's `return()` (see below) is what discards.
+     */
     end(): void;
+    /** The consumer is gone: whatever it did not pull leaves the process budget. */
+    private discard;
+    private charge;
     [Symbol.asyncIterator](): AsyncIterator<Buffer>;
 }

package/dist/server/websocket/frameQueue.js

@@ -2,14 +2,31 @@
  * Push-driven async iterable shared by the transcription sockets: socket
  * frames are pushed in, `transcribeStream()` pulls them out.
  *
+ * The queue reports its level to whoever feeds it, so a socket can be paused
+ * when audio arrives faster than the engine takes it and resumed once the
+ * backlog drains (TCP backpressure, instead of buffering the whole burst).
+ * Every queue also charges its bytes to one process-wide budget, so a burst
+ * of uploads across many sockets cannot exhaust the process.
+ *
  * @module server/websocket/frameQueue
  */
+/** Queued bytes across every `FrameQueue` of this process. */
+let processQueuedBytes = 0;
+/** What every queue in the process holds right now, for caps and tests. */
+export function totalQueuedFrameBytes() {
+    return processQueuedBytes;
+}
 /** Push-driven async iterable: socket frames in, `transcribeStream()` pulls. */
 export class FrameQueue {
     frames = [];
     waiting;
     ended = false;
+    onLevel;
     queuedBytes = 0;
+    /** Called after every change of `queuedBytes`, with the new level. */
+    setLevelListener(listener) {
+        this.onLevel = listener;
+    }
     push(frame) {
         if (this.ended) {
             return;
@@ -21,9 +38,17 @@ export class FrameQueue {
             return;
         }
         this.frames.push(frame);
-        this.queuedBytes += frame.length;
+        this.charge(frame.length);
     }
+    /**
+     * No more frames will arrive; the ones already queued are still handed
+     * out, so a recording whose `end` frame followed its audio is transcribed
+     * whole. The consumer's `return()` (see below) is what discards.
+     */
     end() {
+        if (this.ended) {
+            return;
+        }
         this.ended = true;
         if (this.waiting) {
             const resolve = this.waiting;
@@ -31,12 +56,25 @@ export class FrameQueue {
             resolve({ value: undefined, done: true });
         }
     }
+    /** The consumer is gone: whatever it did not pull leaves the process budget. */
+    discard() {
+        this.end();
+        if (this.queuedBytes > 0) {
+            this.charge(-this.queuedBytes);
+        }
+        this.frames.length = 0;
+    }
+    charge(delta) {
+        this.queuedBytes += delta;
+        processQueuedBytes = Math.max(0, processQueuedBytes + delta);
+        this.onLevel?.(this.queuedBytes);
+    }
     [Symbol.asyncIterator]() {
         return {
             next: () => {
                 const frame = this.frames.shift();
                 if (frame) {
-                    this.queuedBytes -= frame.length;
+                    this.charge(-frame.length);
                     return Promise.resolve({ value: frame, done: false });
                 }
                 if (this.ended) {
@@ -47,7 +85,7 @@ export class FrameQueue {
                 });
             },
             return: () => {
-                this.end();
+                this.discard();
                 return Promise.resolve({ value: undefined, done: true });
             },
         };