@juspay/neurolink 12.48.2 → 12.49.1

package/dist/processors/media/VideoProcessor.js

@@ -51,6 +51,9 @@ import { Readable } from "stream";
 import { pipeline } from "stream/promises";
 import { BaseFileProcessor } from "../base/BaseFileProcessor.js";
 import { formatKeyframeTimestamp, formatMediaDuration, } from "../../utils/mediaDuration.js";
+import { getSTTProviderDescriptor, resolveDefaultSTTProvider, STT_PROVIDER_DESCRIPTORS, } from "../../factories/sttDescriptors.js";
+import { STTProcessor } from "../../utils/sttProcessor.js";
+import { freshEnvSTTCredentials } from "../../voice/sttEnvCredentials.js";
 import { SIZE_LIMITS_MB } from "../config/index.js";
 import { extensionsForModality, mimeTypesForModality, } from "../config/fileTypeRegistry.js";
 import { FileErrorCode } from "../errors/index.js";
@@ -211,10 +214,11 @@ const VIDEO_CONFIG = {
      * seeking to a handful of offsets, and a meeting recording is long.
      */
     AUDIO_EXTRACT_TIMEOUT_MS: 180_000,
-    /** Timeout for one Whisper transcription request in milliseconds */
+    /** Timeout for one transcription request in milliseconds */
     TRANSCRIPTION_TIMEOUT_MS: 120_000,
     /**
-     * Whisper's upload ceiling in MB. The extracted track is mono 16 kHz MP3,
+     * Transcription upload ceiling in MB (Whisper's documented limit, and a
+     * floor for the other engines). The extracted track is mono 16 kHz MP3,
      * so this is roughly six hours of speech — a clip that breaches it is
      * unusual enough to be worth saying so rather than silently truncating.
      */
@@ -853,11 +857,9 @@ export class VideoProcessor extends BaseFileProcessor {
      * working implementation of the same thing, and `--transcribe-audio` would
      * still do nothing.
      *
-     * The Whisper call is reproduced here rather than shared with
-     * `AudioProcessor`: extracting it into a common module is the better
-     * long-term shape, but that file is being edited concurrently, and a
-     * merge conflict in the audio pipeline is a worse outcome than fifty
-     * duplicated lines. The duplication is worth removing once both land.
+     * The call goes through `STTProcessor`, like `AudioProcessor` and
+     * `transcribe()`, so the default-provider rule, `OPENAI_STT_*` and every
+     * STT handler apply to video too.
      *
      * ## Failure behaviour
      *
@@ -890,11 +892,35 @@ export class VideoProcessor extends BaseFileProcessor {
         if (!metadata.audioCodec) {
             return skipped("the video has no audio track");
         }
-        const apiKey = process.env.OPENAI_API_KEY;
-        if (!apiKey) {
-            return skipped("OPENAI_API_KEY is not set, and Whisper is the only transcription backend wired up");
+        // The same provider rule as every other transcription: the provider named
+        // by NEUROLINK_STT_PROVIDER, else the first configured one, else the
+        // built-in local engine when it can run here.
+        const provider = resolveDefaultSTTProvider();
+        const descriptor = getSTTProviderDescriptor(provider);
+        // Same slice AudioProcessor builds, from one shared helper, so audio
+        // attachments and video audio tracks can never resolve different endpoints.
+        const credentials = descriptor
+            ? freshEnvSTTCredentials(descriptor.credentialsKey)
+            : {};
+        let handler;
+        try {
+            handler = await STTProcessor.resolveHandler(provider, credentials);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            return skipped(`the transcription backend could not be loaded — ${detail}`);
         }
-        const audioPath = join(tempDir, "audio.mp3");
+        if (!handler?.isConfigured()) {
+            return skipped(descriptor?.capabilities.local
+                ? `no transcription backend is configured — set one of: ${STT_PROVIDER_DESCRIPTORS.flatMap((d) => d.envVars).join(", ")}`
+                : `transcription provider "${provider}" is not configured`);
+        }
+        const label = provider === "whisper" ? "openai-whisper" : provider;
+        // MP3 keeps a long recording under the upload ceiling; an engine that
+        // does not read MP3 gets 16-bit PCM WAV instead.
+        const supported = handler.getSupportedFormats();
+        const audioFormat = supported.length === 0 || supported.includes("mp3") ? "mp3" : "wav";
+        const audioPath = join(tempDir, `audio.${audioFormat}`);
         try {
             await runFfmpeg([
                 "-y",
@@ -905,16 +931,15 @@ export class VideoProcessor extends BaseFileProcessor {
                 // Drop the video stream outright. Without -vn ffmpeg tries to carry
                 // it into an MP3 container as cover art and fails on most inputs.
                 "-vn",
-                // Mono at 16 kHz is what Whisper resamples to anyway, and it keeps
-                // an hour-long recording comfortably under the upload ceiling.
+                // Mono at 16 kHz is what speech engines resample to anyway, and it
+                // keeps an hour-long recording comfortably under the upload ceiling.
                 "-ac",
                 "1",
                 "-ar",
                 "16000",
-                "-c:a",
-                "libmp3lame",
-                "-q:a",
-                "4",
+                ...(audioFormat === "mp3"
+                    ? ["-c:a", "libmp3lame", "-q:a", "4"]
+                    : ["-c:a", "pcm_s16le"]),
                 audioPath,
             ], { timeoutMs: VIDEO_CONFIG.AUDIO_EXTRACT_TIMEOUT_MS });
         }
@@ -934,52 +959,28 @@ export class VideoProcessor extends BaseFileProcessor {
         }
         const sizeMB = audioBuffer.length / (1024 * 1024);
         if (sizeMB > VIDEO_CONFIG.WHISPER_MAX_SIZE_MB) {
-            return skipped(`the extracted audio is ${sizeMB.toFixed(1)}MB, over Whisper's ` +
-                `${VIDEO_CONFIG.WHISPER_MAX_SIZE_MB}MB limit — split the recording`);
+            return skipped(`the extracted audio is ${sizeMB.toFixed(1)}MB, over the ` +
+                `${VIDEO_CONFIG.WHISPER_MAX_SIZE_MB}MB transcription limit — split the recording`);
         }
-        const baseUrl = (process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1").replace(/\/+$/, "");
-        const form = new FormData();
-        form.append("file", new Blob([new Uint8Array(audioBuffer)], { type: "audio/mpeg" }), "audio.mp3");
-        form.append("model", "whisper-1");
-        form.append("response_format", "verbose_json");
-        // `withTimeout` only races a promise against a timer — it cannot cancel
-        // the request. Without the abort, a timed-out upload keeps its socket and
-        // its in-flight body alive after the caller has already moved on.
-        const abort = new AbortController();
-        const timer = setTimeout(() => abort.abort(), VIDEO_CONFIG.TRANSCRIPTION_TIMEOUT_MS);
         try {
-            const response = await withTimeout(fetch(`${baseUrl}/audio/transcriptions`, {
-                method: "POST",
-                headers: { Authorization: `Bearer ${apiKey}` },
-                body: form,
-                signal: abort.signal,
-            }), VIDEO_CONFIG.TRANSCRIPTION_TIMEOUT_MS);
-            if (!response.ok) {
-                const detail = await response.text().catch(() => "");
-                return skipped(`the transcription request failed — HTTP ${response.status}` +
-                    `${detail ? `: ${detail.slice(0, 200)}` : ""}`);
-            }
-            const payload = await response.json();
-            const text = typeof payload === "object" &&
-                payload !== null &&
-                typeof payload.text === "string"
-                ? payload.text.trim()
-                : "";
+            const result = await withTimeout(STTProcessor.transcribe(audioBuffer, provider, {
+                format: audioFormat,
+                timeoutMs: VIDEO_CONFIG.TRANSCRIPTION_TIMEOUT_MS,
+                maxAudioBytes: VIDEO_CONFIG.WHISPER_MAX_SIZE_MB * 1024 * 1024,
+            }, credentials), VIDEO_CONFIG.TRANSCRIPTION_TIMEOUT_MS);
+            const text = result.text.trim();
             if (text.length === 0) {
                 // A successful call returning nothing is a real outcome — silence,
                 // music, no speech — and not the same as a failure.
-                return skipped("Whisper returned an empty transcript for this audio");
+                return skipped(`${provider === "whisper" ? "Whisper" : label} returned an empty transcript for this audio`);
             }
-            logger.debug(`[VideoProcessor] Transcribed ${filename} via openai-whisper (${text.length} chars)`);
+            logger.debug(`[VideoProcessor] Transcribed ${filename} via ${label} (${text.length} chars)`);
             return { transcript: text };
         }
         catch (error) {
             const detail = error instanceof Error ? error.message : String(error);
             return skipped(`the transcription request failed — ${detail}`);
         }
-        finally {
-            clearTimeout(timer);
-        }
     }
     /**
      * Extract keyframes from a video at calculated intervals.

package/dist/providers/cloudflareClef.js

@@ -24,6 +24,12 @@ const SUPPORTED_IMAGE_TYPES = new Set([
  */
 const TRAILING_REQUEST_ID = /\(([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\)\s*$/i;
 const MAX_ERROR_MESSAGE_CHARS = 500;
+/**
+ * The code on the 429 an account gets once it has used its daily free
+ * allocation of 10,000 neurons (seen 2026-10-05). Unlike the capacity 429
+ * (3040), nothing changes within a retry's backoff, so it is not retried.
+ */
+const DAILY_ALLOCATION_CODE = 4006;
 /**
  * An error message is cut to this before any pattern runs on it, so a hostile or
  * garbled body cannot hold the event loop. Cloudflare's own messages are far
@@ -317,7 +323,9 @@ export class CloudflareClefProvider extends SystemOneDecisionProvider {
             message,
             status,
             requestId: requestId ?? parsed?.requestId,
-            retryable: kind === "rate_limit" || kind === "overloaded" || kind === "server",
+            retryable: (kind === "rate_limit" && parsed?.code !== DAILY_ALLOCATION_CODE) ||
+                kind === "overloaded" ||
+                kind === "server",
         };
     }
     /**

package/dist/server/abstract/baseServerAdapter.d.ts

@@ -57,6 +57,13 @@ export declare abstract class BaseServerAdapter extends EventEmitter {
      * Get the underlying framework instance (for advanced usage)
      */
     abstract getFrameworkInstance(): unknown;
+    /**
+     * The listening Node `http.Server`, once `start()` has run and the runtime
+     * is Node (Bun and Deno serve without one). A WebSocket upgrade handler
+     * such as `attachTranscribeWebSocket` attaches to it; `undefined` means
+     * there is nothing to attach to.
+     */
+    getNativeServer(): unknown;
     /**
      * Stop accepting new connections
      * Called during graceful shutdown to prevent new requests

package/dist/server/abstract/baseServerAdapter.js

@@ -53,7 +53,10 @@ export class BaseServerAdapter extends EventEmitter {
             basePath: config.basePath ?? "/api",
             cors: {
                 enabled: config.cors?.enabled ?? true,
-                origins: config.cors?.origins ?? ["*"],
+                // No origin by default: a browser page may call this server only
+                // from an origin the operator listed, or from any origin with an
+                // explicit ["*"]. The adapters honour the wildcard, so it is opt-in.
+                origins: config.cors?.origins ?? [],
                 methods: config.cors?.methods ?? [
                     "GET",
                     "POST",
@@ -98,6 +101,15 @@ export class BaseServerAdapter extends EventEmitter {
             shutdown: this.shutdownConfig,
         };
     }
+    /**
+     * The listening Node `http.Server`, once `start()` has run and the runtime
+     * is Node (Bun and Deno serve without one). A WebSocket upgrade handler
+     * such as `attachTranscribeWebSocket` attaches to it; `undefined` means
+     * there is nothing to attach to.
+     */
+    getNativeServer() {
+        return undefined;
+    }
     // ============================================
     // Common Methods (Shared Implementation)
     // ============================================

package/dist/server/adapters/expressAdapter.d.ts

@@ -67,4 +67,5 @@ export declare class ExpressServerAdapter extends BaseServerAdapter {
      * Get the Express app instance
      */
     getFrameworkInstance(): unknown;
+    getNativeServer(): unknown;
 }

package/dist/server/adapters/expressAdapter.js

@@ -6,6 +6,7 @@ import { logger } from "../../utils/logger.js";
 import { AlreadyRunningError, ServerAdapterError, ServerStartError, ServerStopError, wrapError, } from "../errors.js";
 import { BaseServerAdapter } from "../abstract/baseServerAdapter.js";
 import { isErrorResponse } from "../utils/validation.js";
+import { isRawBodyContentType, isWebResponse, readWebResponse, } from "../utils/rawBody.js";
 /**
  * Express-specific server adapter
  */
@@ -42,13 +43,23 @@ export class ExpressServerAdapter extends BaseServerAdapter {
                 "10mb";
             this.app.use(express.json({ limit: this.config.bodyParser.jsonLimit || bodyLimit }));
             this.app.use(express.urlencoded({ extended: true, limit: bodyLimit }));
+            // Uploads (multipart, octet-stream, audio/*) reach the route as bytes.
+            this.app.use(express.raw({
+                type: (req) => isRawBodyContentType(req.headers["content-type"]),
+                limit: this.config.bodyParser.maxSize || "10mb",
+            }));
         }
         // CORS
         if (this.config.cors.enabled) {
             const corsModule = await this.importFrameworkDependency("cors", "Express");
             const cors = corsModule.default;
             this.app.use(cors({
-                origin: this.config.cors.origins,
+                // A list is matched literally, so the default `["*"]` would match
+                // nothing; the wildcard has to be the string "*" (Koa handles it in
+                // its origin callback).
+                origin: this.config.cors.origins.includes("*")
+                    ? "*"
+                    : this.config.cors.origins,
                 methods: this.config.cors.methods,
                 allowedHeaders: this.config.cors.headers,
                 credentials: this.config.cors.credentials,
@@ -170,6 +181,24 @@ export class ExpressServerAdapter extends BaseServerAdapter {
                 // Execute handler
                 const result = await route.handler(ctx);
                 const duration = Date.now() - startTime;
+                // A route that answers in its own wire format returns a web Response.
+                if (isWebResponse(result)) {
+                    const raw = await readWebResponse(result);
+                    this.emit("response", {
+                        requestId,
+                        statusCode: raw.status,
+                        duration,
+                        timestamp: new Date(),
+                    });
+                    for (const [key, value] of Object.entries({
+                        ...ctx.responseHeaders,
+                        ...raw.headers,
+                    })) {
+                        res.setHeader(key, value);
+                    }
+                    res.status(raw.status).send(raw.body);
+                    return;
+                }
                 // Check if result is an error response
                 if (isErrorResponse(result)) {
                     const statusCode = result.httpStatus ?? 500;
@@ -247,9 +276,21 @@ export class ExpressServerAdapter extends BaseServerAdapter {
             });
             // Use dynamic status code from ServerAdapterError if available
             const isServerAdapterError = error instanceof ServerAdapterError;
-            const statusCode = isServerAdapterError ? error.getHttpStatus() : 500;
-            const errorCode = isServerAdapterError ? error.code : "INTERNAL_ERROR";
-            const errorMessage = isServerAdapterError
+            // body-parser marks an over-limit body; it is the client's error.
+            const tooLarge = !isServerAdapterError &&
+                "type" in error &&
+                error.type === "entity.too.large";
+            const statusCode = isServerAdapterError
+                ? error.getHttpStatus()
+                : tooLarge
+                    ? 413
+                    : 500;
+            const errorCode = isServerAdapterError
+                ? error.code
+                : tooLarge
+                    ? "PAYLOAD_TOO_LARGE"
+                    : "INTERNAL_ERROR";
+            const errorMessage = isServerAdapterError || tooLarge
                 ? error.message
                 : "An internal error occurred";
             res.status(statusCode).json({
@@ -489,4 +530,7 @@ export class ExpressServerAdapter extends BaseServerAdapter {
     getFrameworkInstance() {
         return this.app;
     }
+    getNativeServer() {
+        return this.server;
+    }
 }

package/dist/server/adapters/fastifyAdapter.d.ts

@@ -67,4 +67,5 @@ export declare class FastifyServerAdapter extends BaseServerAdapter {
      * Get the Fastify instance
      */
     getFrameworkInstance(): unknown;
+    getNativeServer(): unknown;
 }

package/dist/server/adapters/fastifyAdapter.js

@@ -8,6 +8,7 @@ import { AlreadyRunningError, ServerAdapterError, ServerStartError, ServerStopEr
 import { withTimeout } from "../../utils/errorHandling.js";
 import { BaseServerAdapter } from "../abstract/baseServerAdapter.js";
 import { isErrorResponse } from "../utils/validation.js";
+import { isRawBodyContentType, isWebResponse, readWebResponse, } from "../utils/rawBody.js";
 /**
  * Fastify-specific server adapter
  * Provides high-performance HTTP server with schema validation
@@ -46,11 +47,25 @@ export class FastifyServerAdapter extends BaseServerAdapter {
             genReqId: () => this.generateRequestId(),
             bodyLimit: this.parseBodyLimit(this.config.bodyParser.maxSize),
         });
+        // Uploads (multipart, octet-stream, audio/*) reach the route as bytes;
+        // without a parser Fastify refuses these content types with a 415.
+        if (this.config.bodyParser.enabled) {
+            this.app.addContentTypeParser(/^\s*(multipart\/form-data|application\/octet-stream|audio\/)/i, { parseAs: "buffer" }, (request, body, done) => {
+                done(null, isRawBodyContentType(request.headers["content-type"])
+                    ? body
+                    : undefined);
+            });
+        }
         // Register CORS plugin if enabled
         if (this.config.cors.enabled) {
             const corsModule = await this.importFrameworkDependency("@fastify/cors", "Fastify");
             await this.app.register(corsModule.default, {
-                origin: this.config.cors.origins,
+                // A list is matched literally, so the default `["*"]` would match
+                // nothing; the wildcard has to be the string "*" (Koa handles it in
+                // its origin callback).
+                origin: this.config.cors.origins.includes("*")
+                    ? "*"
+                    : this.config.cors.origins,
                 methods: this.config.cors.methods,
                 allowedHeaders: this.config.cors.headers,
                 credentials: this.config.cors.credentials,
@@ -235,6 +250,24 @@ export class FastifyServerAdapter extends BaseServerAdapter {
                 // Execute handler
                 const result = await route.handler(ctx);
                 const duration = Date.now() - startTime;
+                // A route that answers in its own wire format returns a web Response.
+                if (isWebResponse(result)) {
+                    const raw = await readWebResponse(result);
+                    this.emit("response", {
+                        requestId,
+                        statusCode: raw.status,
+                        duration,
+                        timestamp: new Date(),
+                    });
+                    for (const [key, value] of Object.entries({
+                        ...ctx.responseHeaders,
+                        ...raw.headers,
+                    })) {
+                        reply.header(key, value);
+                    }
+                    reply.status(raw.status);
+                    return reply.send(raw.body);
+                }
                 // Check if result is an error response
                 if (isErrorResponse(result)) {
                     const statusCode = result.httpStatus ?? 500;
@@ -485,4 +518,8 @@ export class FastifyServerAdapter extends BaseServerAdapter {
     getFrameworkInstance() {
         return this.app;
     }
+    getNativeServer() {
+        // Fastify owns its http.Server and exposes it as `app.server`.
+        return this.app?.server;
+    }
 }

package/dist/server/adapters/honoAdapter.d.ts

@@ -6,10 +6,6 @@
 import type { NeuroLink } from "../../neurolink.js";
 import { BaseServerAdapter } from "../abstract/baseServerAdapter.js";
 import type { MiddlewareDefinition, RouteDefinition, ServerAdapterConfig } from "../../types/index.js";
-/**
- * Hono-specific server adapter
- * Supports multiple runtimes: Bun, Deno, Node.js
- */
 export declare class HonoServerAdapter extends BaseServerAdapter {
     private app;
     private server?;
@@ -75,6 +71,7 @@ export declare class HonoServerAdapter extends BaseServerAdapter {
      * Get the Hono app instance
      */
     getFrameworkInstance(): unknown;
+    getNativeServer(): unknown;
     private extractHeaders;
     private extractQuery;
     private extractBody;

package/dist/server/adapters/honoAdapter.js

@@ -7,10 +7,31 @@ import { logger } from "../../utils/logger.js";
 import { AlreadyRunningError, ServerAdapterError, ServerStopError, wrapError, } from "../errors.js";
 import { BaseServerAdapter } from "../abstract/baseServerAdapter.js";
 import { isErrorResponse } from "../utils/validation.js";
+import { isRawBodyContentType, isWebResponse, parseByteLimit, RawBodyTooLargeError, readRawBody, } from "../utils/rawBody.js";
 /**
  * Hono-specific server adapter
  * Supports multiple runtimes: Bun, Deno, Node.js
  */
+/** Raw bodies already read for a request, so a second extraction never hits a consumed stream. */
+const rawBodies = new WeakMap();
+/** A web `ReadableStream` of bytes as an async iterable of Buffers, releasing the reader on exit. */
+async function* webStreamChunks(stream) {
+    const reader = stream.getReader();
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done) {
+                return;
+            }
+            if (value) {
+                yield Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
 export class HonoServerAdapter extends BaseServerAdapter {
     app;
     server;
@@ -132,7 +153,12 @@ export class HonoServerAdapter extends BaseServerAdapter {
         // Add CORS if enabled
         if (this.config.cors.enabled) {
             this.app.use("*", cors({
-                origin: this.config.cors.origins,
+                // Hono matches a list of origins literally, so `["*"]` (the default)
+                // matches nothing and no CORS header is sent; the string "*" is the
+                // wildcard. Pass it as such when the list contains it.
+                origin: this.config.cors.origins.includes("*")
+                    ? "*"
+                    : this.config.cors.origins,
                 allowMethods: this.config.cors.methods,
                 allowHeaders: this.config.cors.headers,
                 credentials: this.config.cors.credentials,
@@ -242,6 +268,21 @@ export class HonoServerAdapter extends BaseServerAdapter {
                 // Execute handler
                 const result = await route.handler(ctx);
                 const duration = Date.now() - startTime;
+                // A route that answers in its own wire format returns a web Response.
+                if (isWebResponse(result)) {
+                    this.emit("response", {
+                        requestId,
+                        statusCode: result.status,
+                        duration,
+                        timestamp: new Date(),
+                    });
+                    for (const [key, value] of Object.entries(ctx.responseHeaders ?? {})) {
+                        if (!result.headers.has(key)) {
+                            result.headers.set(key, value);
+                        }
+                    }
+                    return result;
+                }
                 // Check if result is an error response
                 if (isErrorResponse(result)) {
                     const statusCode = result.httpStatus ?? 500;
@@ -604,6 +645,10 @@ export class HonoServerAdapter extends BaseServerAdapter {
     getFrameworkInstance() {
         return this.app;
     }
+    getNativeServer() {
+        // @hono/node-server's serve() returns the http.Server; Bun/Deno do not.
+        return this.server;
+    }
     // ============================================
     // Helper Methods
     // ============================================
@@ -643,6 +688,43 @@ export class HonoServerAdapter extends BaseServerAdapter {
                 return undefined;
             }
         }
+        // Uploads (multipart, octet-stream, audio/*) reach the route as bytes.
+        // Over the size limit the body is the error itself rather than a throw:
+        // a throw from the middleware path would land in onError, which answers
+        // 500. The route answers 413 (or a validation error) from it.
+        if (isRawBodyContentType(contentType)) {
+            const limit = parseByteLimit(this.config.bodyParser.maxSize);
+            if (Number(c.req.header("Content-Length") ?? 0) > limit) {
+                return new RawBodyTooLargeError(limit);
+            }
+            // Read the web stream chunk by chunk and stop at the limit, so a
+            // chunked upload without a Content-Length cannot be buffered whole
+            // (and that before any route logic, including the API-key check, runs).
+            // The body is extracted more than once per request (middleware and
+            // route); a web stream can only be read once, so the outcome is kept
+            // per request the way Hono caches `arrayBuffer()`.
+            const cached = rawBodies.get(c.req.raw);
+            if (cached !== undefined) {
+                return cached;
+            }
+            const stream = c.req.raw.body;
+            if (!stream) {
+                return Buffer.alloc(0);
+            }
+            let outcome;
+            try {
+                outcome = await readRawBody(webStreamChunks(stream), limit);
+            }
+            catch (error) {
+                if (!(error instanceof RawBodyTooLargeError)) {
+                    throw error;
+                }
+                await stream.cancel().catch(() => undefined);
+                outcome = error;
+            }
+            rawBodies.set(c.req.raw, outcome);
+            return outcome;
+        }
         return undefined;
     }
 }

package/dist/server/adapters/koaAdapter.d.ts

@@ -82,4 +82,5 @@ export declare class KoaServerAdapter extends BaseServerAdapter {
      * Get the Koa app instance
      */
     getFrameworkInstance(): unknown;
+    getNativeServer(): unknown;
 }

package/dist/server/adapters/koaAdapter.js

@@ -7,6 +7,7 @@ import { logger } from "../../utils/logger.js";
 import { AlreadyRunningError, ServerAdapterError, ServerStopError, wrapError, } from "../errors.js";
 import { BaseServerAdapter } from "../abstract/baseServerAdapter.js";
 import { isErrorResponse } from "../utils/validation.js";
+import { isRawBodyContentType, isWebResponse, parseByteLimit, RawBodyTooLargeError, readRawBody, readWebResponse, } from "../utils/rawBody.js";
 /**
  * Koa-specific server adapter
  * Leverages Koa's middleware composition for clean request handling
@@ -111,6 +112,26 @@ export class KoaServerAdapter extends BaseServerAdapter {
                 jsonLimit: this.config.bodyParser.jsonLimit,
                 enableTypes: ["json", "form", "text"],
             }));
+            // Uploads (multipart, octet-stream, audio/*) reach the route as bytes.
+            const rawLimit = parseByteLimit(this.config.bodyParser.maxSize);
+            this.app.use(async (ctx, next) => {
+                if (isRawBodyContentType(ctx.get("content-type"))) {
+                    try {
+                        ctx.request.body = await readRawBody(ctx.req, rawLimit);
+                    }
+                    catch (error) {
+                        if (error instanceof RawBodyTooLargeError) {
+                            ctx.status = 413;
+                            ctx.body = {
+                                error: { code: "PAYLOAD_TOO_LARGE", message: error.message },
+                            };
+                            return;
+                        }
+                        throw error;
+                    }
+                }
+                await next();
+            });
         }
         // Rate limiting middleware
         if (this.config.rateLimit.enabled) {
@@ -254,6 +275,25 @@ export class KoaServerAdapter extends BaseServerAdapter {
             // Execute handler
             const result = await route.handler(serverCtx);
             const duration = Date.now() - startTime;
+            // A route that answers in its own wire format returns a web Response.
+            if (isWebResponse(result)) {
+                const raw = await readWebResponse(result);
+                this.emit("response", {
+                    requestId,
+                    statusCode: raw.status,
+                    duration,
+                    timestamp: new Date(),
+                });
+                for (const [key, value] of Object.entries({
+                    ...serverCtx.responseHeaders,
+                    ...raw.headers,
+                })) {
+                    ctx.set(key, value);
+                }
+                ctx.status = raw.status;
+                ctx.body = raw.body;
+                return;
+            }
             // Check if result is an error response
             if (isErrorResponse(result)) {
                 const statusCode = result.httpStatus ?? 500;
@@ -535,4 +575,7 @@ export class KoaServerAdapter extends BaseServerAdapter {
     getFrameworkInstance() {
         return this.app;
     }
+    getNativeServer() {
+        return this.server;
+    }
 }

package/dist/server/index.d.ts

@@ -38,9 +38,10 @@ export { createMCPBodyAttachmentMiddleware, fastifyMCPBodyHook, } from "./middle
 export { createRateLimitMiddleware, createSlidingWindowRateLimitMiddleware, InMemoryRateLimitStore, } from "./middleware/rateLimit.js";
 export { CommonSchemas, createFieldValidator, createRequestValidationMiddleware, ValidationError, } from "./middleware/validation.js";
 export { AgentExecuteRequestSchema as OpenAPIAgentExecuteRequestSchema, AgentExecuteResponseSchema, AgentInputSchema, ApiKeySecurityScheme, BasicSecurityScheme, BearerSecurityScheme, CommonParameters, ConversationMessageSchema, createApiInfo, createDeleteOperation, createErrorResponse as createOpenAPIErrorResponse, createGetOperation, createHeaderParameter, createOpenAPIGenerator, createPathParameter, createPostOperation, createQueryParameter, createServer as createOpenAPIServer, createStreamingPostOperation, createStreamingResponse, createSuccessResponse, DefaultServers, ErrorResponseSchema, generateOpenAPIFromConfig, generateOpenAPISpec, HealthResponseSchema, MCPServerStatusSchema, MCPServersListResponseSchema, MCPServerToolSchema, MetricsResponseSchema, NeuroLinkApiInfo, OpenAPIGenerator, OpenAPISchemas, ProviderInfoSchema, ReadyResponseSchema, SessionSchema, SessionsListResponseSchema, StandardErrorResponses, StandardTags, TokenUsageSchema, ToolCallSchema, ToolDefinitionSchema, ToolExecuteRequestSchema as OpenAPIToolExecuteRequestSchema, ToolExecuteResponseSchema, ToolListResponseSchema, ToolParameterSchema, } from "./openapi/index.js";
-export { createAgentRoutes, createAllRoutes, createHealthRoutes, createMCPRoutes, createMemoryRoutes, createOpenApiRoutes, createToolRoutes, registerAllRoutes, createClaudeProxyRoutes, createOpenAIProxyRoutes, createCodexProxyRoutes, createGeminiProxyRoutes, } from "./routes/index.js";
+export { createAgentRoutes, createAllRoutes, createHealthRoutes, createMCPRoutes, createMemoryRoutes, createOpenApiRoutes, createToolRoutes, createTranscribeRoutes, registerAllRoutes, createClaudeProxyRoutes, createOpenAIProxyRoutes, createCodexProxyRoutes, createGeminiProxyRoutes, } from "./routes/index.js";
 export { BaseDataStreamWriter, createDataStreamResponse, createDataStreamWriter, createNDJSONHeaders, createSSEHeaders, DataStreamResponse, formatSSEEvent, pipeAsyncIterableToDataStream, WebStreamWriter, } from "./streaming/index.js";
 export { ErrorCategory, ErrorSeverity, ServerAdapterErrorCode, } from "../types/index.js";
 export { createStreamRedactor, redactStreamChunk } from "./utils/redaction.js";
-export { AgentExecuteRequestSchema, createErrorResponse, ServerNameParamSchema, SessionIdParamSchema, ToolArgumentsSchema, ToolExecuteRequestSchema, ToolNameParamSchema, ToolSearchQuerySchema, validateParams, validateQuery, validateRequest, } from "./utils/validation.js";
+export { AgentExecuteRequestSchema, createErrorResponse, ServerNameParamSchema, SessionIdParamSchema, ToolArgumentsSchema, ToolExecuteRequestSchema, ToolNameParamSchema, ToolSearchQuerySchema, TranscribeConfigSchema, TranscribeRequestSchema, TranscribeStreamConfigSchema, validateParams, validateQuery, validateRequest, } from "./utils/validation.js";
 export { createAgentWebSocketHandler, WebSocketConnectionManager, WebSocketMessageRouter, } from "./websocket/index.js";
+export { attachTranscribeWebSocket } from "./websocket/transcribeWebSocket.js";