@juspay/neurolink 13.0.0 → 13.0.2

package/dist/server/middleware/auth.d.ts

@@ -7,12 +7,16 @@ import type { ApiKeyAuthOptions, AuthResult, AuthenticatedUser, BearerAuthOption
  * Check if request is from development playground.
  * Detects playground requests via special headers for development mode.
  *
+ * This only inspects the headers. `createAuthMiddleware` honours the result
+ * solely when `process.env.NODE_ENV` is exactly `"development"`, so a caller
+ * that acts on this on its own must apply that gate itself.
+ *
  * @param headers - Request headers to check
  * @returns True if request is from dev playground
  *
  * @example
  * ```typescript
- * if (isDevPlayground(ctx.headers)) {
+ * if (process.env.NODE_ENV === "development" && isDevPlayground(ctx.headers)) {
  *   // Skip authentication for playground
  * }
  * ```

package/dist/server/middleware/auth.js

@@ -7,12 +7,16 @@ import { AuthenticationError, AuthorizationError, InvalidAuthenticationError, }
  * Check if request is from development playground.
  * Detects playground requests via special headers for development mode.
  *
+ * This only inspects the headers. `createAuthMiddleware` honours the result
+ * solely when `process.env.NODE_ENV` is exactly `"development"`, so a caller
+ * that acts on this on its own must apply that gate itself.
+ *
  * @param headers - Request headers to check
  * @returns True if request is from dev playground
  *
  * @example
  * ```typescript
- * if (isDevPlayground(ctx.headers)) {
+ * if (process.env.NODE_ENV === "development" && isDevPlayground(ctx.headers)) {
  *   // Skip authentication for playground
  * }
  * ```
@@ -61,9 +65,12 @@ export function createAuthMiddleware(config) {
         order: 10, // Run early but after request ID
         excludePaths: skipPaths,
         handler: async (ctx, next) => {
-            // Skip auth for dev playground in non-production
+            // The playground header is a development convenience, so it is honoured
+            // only when NODE_ENV is exactly "development". An unset NODE_ENV (the
+            // default for most deployments), "test", "staging" or a misspelling must
+            // not let an unauthenticated caller claim the developer identity.
             if (skipDevPlayground &&
-                process.env.NODE_ENV !== "production" &&
+                process.env.NODE_ENV === "development" &&
                 isDevPlayground(ctx.headers)) {
                 ctx.user = {
                     id: DEV_PLAYGROUND_USER.id,

package/dist/server/openapi/schemas.js

@@ -117,12 +117,12 @@ export const AgentInputSchema = {
                 images: {
                     type: "array",
                     items: { type: "string" },
-                    description: "Array of image URLs or base64 data",
+                    description: "Array of images, each a data: URI, an https URL the server downloads (public hosts only, no redirects) or a path under a directory the server allows (allowedInputRoots; with none set every local path is refused with 403). Bare base64 is not accepted, and http:// or any other scheme is refused with 400. A request is limited in attachment count and total bytes (413).",
                 },
                 files: {
                     type: "array",
                     items: { type: "string" },
-                    description: "Array of file paths or URLs",
+                    description: "Array of files, each a data: URI, an https URL the server downloads (public hosts only, no redirects) or a path under a directory the server allows (allowedInputRoots; with none set every local path is refused with 403). http:// or any other scheme is refused with 400. A request is limited in attachment count and total bytes (413), images and files together.",
                 },
             },
         },

package/dist/server/routes/agentRoutes.d.ts

@@ -2,8 +2,15 @@
  * Agent Routes
  * Endpoints for agent execution and streaming
  */
-import type { RouteGroup } from "../../types/index.js";
+import type { RouteGroup, ServerAgentRouteOptions } from "../../types/index.js";
 /**
  * Create agent routes
+ *
+ * @param options - Limits for `input.images` / `input.files`:
+ *   `allowedInputRoots` (default: none, every local-path attachment is
+ *   refused), `maxInputBytes` per attachment (default 50 MiB),
+ *   `maxInputAttachments` per request (default 20, images and files together)
+ *   and `maxInputTotalBytes` per request (default 100 MiB, one budget shared by
+ *   images and files).
  */
-export declare function createAgentRoutes(basePath?: string): RouteGroup;
+export declare function createAgentRoutes(basePath?: string, options?: ServerAgentRouteOptions): RouteGroup;

package/dist/server/routes/agentRoutes.js

@@ -27,6 +27,7 @@ async function resolveRequestToolFilter(ctx, requestedTools) {
     logger.warn("[agentRoutes] Ignoring request.tools — no entries match registered tool names (legacy fail-open)", { requested: requestedTools });
     return undefined;
 }
+import { AgentInputError, resolveAgentInput } from "../utils/agentInput.js";
 import { createStreamRedactor } from "../utils/redaction.js";
 import { AgentExecuteRequestSchema, createErrorResponse as createError, EmbedManyRequestSchema, EmbedRequestSchema, SkillCreateRequestSchema, SkillUpdateRequestSchema, validateRequest, } from "../utils/validation.js";
 /**
@@ -56,10 +57,35 @@ function resolveMutableSkillsManager(ctx) {
     }
     return manager;
 }
+/**
+ * The request's `input` with its attachments vetted (see `agentInput.ts`), or
+ * the error response for the first one the server refuses.
+ */
+async function resolveRequestInput(ctx, requestInput, options) {
+    if (typeof requestInput === "string") {
+        return { text: requestInput };
+    }
+    try {
+        return await resolveAgentInput(requestInput, options);
+    }
+    catch (error) {
+        if (error instanceof AgentInputError) {
+            return createError(error.code, error.message, undefined, ctx.requestId, error.status);
+        }
+        throw error;
+    }
+}
 /**
  * Create agent routes
+ *
+ * @param options - Limits for `input.images` / `input.files`:
+ *   `allowedInputRoots` (default: none, every local-path attachment is
+ *   refused), `maxInputBytes` per attachment (default 50 MiB),
+ *   `maxInputAttachments` per request (default 20, images and files together)
+ *   and `maxInputTotalBytes` per request (default 100 MiB, one budget shared by
+ *   images and files).
  */
-export function createAgentRoutes(basePath = "/api") {
+export function createAgentRoutes(basePath = "/api", options) {
     return {
         prefix: `${basePath}/agent`,
         routes: [
@@ -82,10 +108,10 @@ export function createAgentRoutes(basePath = "/api") {
                             "ai.model": request.model || "default",
                         },
                     }, async () => {
-                        // Normalize input
-                        const input = typeof request.input === "string"
-                            ? { text: request.input }
-                            : request.input;
+                        const input = await resolveRequestInput(ctx, request.input, options);
+                        if ("error" in input) {
+                            return input;
+                        }
                         const requestToolFilter = await resolveRequestToolFilter(ctx, request.tools);
                         const result = await ctx.neurolink.generate({
                             input,
@@ -135,10 +161,10 @@ export function createAgentRoutes(basePath = "/api") {
                         return validation.error;
                     }
                     const request = validation.data;
-                    // Normalize input
-                    const input = typeof request.input === "string"
-                        ? { text: request.input }
-                        : request.input;
+                    const input = await resolveRequestInput(ctx, request.input, options);
+                    if ("error" in input) {
+                        return input;
+                    }
                     const streamToolFilter = await resolveRequestToolFilter(ctx, request.tools);
                     const result = await ctx.neurolink.stream({
                         input,

package/dist/server/routes/index.js

@@ -41,7 +41,7 @@ export { createTranscribeRoutes } from "./transcribeRoutes.js";
  */
 export function createAllRoutes(basePath = "/api", options) {
     const routes = [
-        createAgentRoutes(basePath),
+        createAgentRoutes(basePath, options?.agent),
         createToolRoutes(basePath),
         createMCPRoutes(basePath),
         createMemoryRoutes(basePath),

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

@@ -0,0 +1,53 @@
+/**
+ * Agent request attachments, vetted at the HTTP boundary.
+ *
+ * `input.images` and `input.files` reach the SDK as strings, and the SDK
+ * resolves a string itself: an `http(s)` URL is fetched with redirects followed
+ * and no address check, and anything else is read from the local disk. Both
+ * are right for a program that names its own files. Neither is right when the
+ * string came from a caller of a network server, who could name
+ * `https://169.254.169.254/...`, a redirect to it, or `/etc/passwd`.
+ *
+ * So the route resolves every attachment itself and hands the SDK bytes:
+ *   - `data:` URIs pass through, they carry their own content;
+ *   - `https` URLs are downloaded with `safeDownload`: redirects are refused and
+ *     the size is capped. The address is checked and the connection pinned to
+ *     the checked addresses only for a direct download. Behind `HTTPS_PROXY` /
+ *     `ALL_PROXY` the proxy resolves the host, so only the URL text is checked
+ *     (IP literals, single-label and internal host names) and what a
+ *     public-looking name resolves to is the proxy's egress policy;
+ *   - local paths are read only from the operator's `allowedInputRoots`, after
+ *     symlinks are resolved;
+ *   - everything else is refused rather than guessed at, so this classifier
+ *     can never disagree with the SDK's about what a string means.
+ *
+ * One request is also bounded as a whole: at most `maxInputAttachments`
+ * entries, each at most `maxInputBytes`, all together at most
+ * `maxInputTotalBytes`. The count and every `data:` URI are judged before
+ * anything is read; the rest are resolved one at a time, each allowed only what
+ * is left of the shared budget, so a transfer that would overflow it stops
+ * mid-stream.
+ *
+ * The SDK itself is untouched: a program calling `generate()` directly keeps
+ * reading the paths and URLs it names.
+ *
+ * @module server/utils/agentInput
+ */
+import type { ServerAgentResolvedInput, ServerAgentRouteOptions } from "../../types/index.js";
+/** An attachment the server refuses, with the HTTP status that says why. */
+export declare class AgentInputError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(message: string, status: number, code: string);
+}
+/**
+ * Replace every attachment of an agent request's `input` with vetted content.
+ *
+ * @throws {AgentInputError} for the first attachment that is refused, or for a
+ *   request that carries too many attachments or too many bytes.
+ */
+export declare function resolveAgentInput(input: {
+    text: string;
+    images?: string[];
+    files?: string[];
+}, options?: ServerAgentRouteOptions): Promise<ServerAgentResolvedInput>;

package/dist/server/utils/agentInput.js

@@ -0,0 +1,304 @@
+/**
+ * Agent request attachments, vetted at the HTTP boundary.
+ *
+ * `input.images` and `input.files` reach the SDK as strings, and the SDK
+ * resolves a string itself: an `http(s)` URL is fetched with redirects followed
+ * and no address check, and anything else is read from the local disk. Both
+ * are right for a program that names its own files. Neither is right when the
+ * string came from a caller of a network server, who could name
+ * `https://169.254.169.254/...`, a redirect to it, or `/etc/passwd`.
+ *
+ * So the route resolves every attachment itself and hands the SDK bytes:
+ *   - `data:` URIs pass through, they carry their own content;
+ *   - `https` URLs are downloaded with `safeDownload`: redirects are refused and
+ *     the size is capped. The address is checked and the connection pinned to
+ *     the checked addresses only for a direct download. Behind `HTTPS_PROXY` /
+ *     `ALL_PROXY` the proxy resolves the host, so only the URL text is checked
+ *     (IP literals, single-label and internal host names) and what a
+ *     public-looking name resolves to is the proxy's egress policy;
+ *   - local paths are read only from the operator's `allowedInputRoots`, after
+ *     symlinks are resolved;
+ *   - everything else is refused rather than guessed at, so this classifier
+ *     can never disagree with the SDK's about what a string means.
+ *
+ * One request is also bounded as a whole: at most `maxInputAttachments`
+ * entries, each at most `maxInputBytes`, all together at most
+ * `maxInputTotalBytes`. The count and every `data:` URI are judged before
+ * anything is read; the rest are resolved one at a time, each allowed only what
+ * is left of the shared budget, so a transfer that would overflow it stops
+ * mid-stream.
+ *
+ * The SDK itself is untouched: a program calling `generate()` directly keeps
+ * reading the paths and URLs it names.
+ *
+ * @module server/utils/agentInput
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { logger } from "../../utils/logger.js";
+const DEFAULT_MAX_INPUT_BYTES = 50 * 1024 * 1024;
+const DEFAULT_MAX_INPUT_TOTAL_BYTES = 100 * 1024 * 1024;
+const DEFAULT_MAX_INPUT_ATTACHMENTS = 20;
+const READ_CHUNK_BYTES = 64 * 1024;
+/** Two or more scheme characters, so a Windows drive letter (`C:\`) is not one. */
+const URL_SCHEME = /^[a-zA-Z][a-zA-Z0-9+.-]+:/;
+/** An attachment the server refuses, with the HTTP status that says why. */
+export class AgentInputError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "AgentInputError";
+    }
+}
+const isUnder = (child, root) => child === root ||
+    child.startsWith(root.endsWith(path.sep) ? root : root + path.sep);
+const forbidden = () => new AgentInputError("attachment path is outside the directories this server allows (or local paths are disabled)", 403, "FORBIDDEN");
+const notFound = () => new AgentInputError("attachment path does not exist", 404, "NOT_FOUND");
+const notReadable = () => new AgentInputError("attachment path is not readable", 403, "FORBIDDEN");
+const notAFile = () => new AgentInputError("attachment path is not a file", 400, "VALIDATION_ERROR");
+const tooLarge = (limit) => new AgentInputError(`attachment exceeds the ${limit}-byte limit`, 413, "PAYLOAD_TOO_LARGE");
+const budgetExceeded = (total) => new AgentInputError(`attachments together exceed the ${total}-byte limit`, 413, "PAYLOAD_TOO_LARGE");
+const tooMany = (max) => new AgentInputError(`a request may carry at most ${max} attachments`, 413, "PAYLOAD_TOO_LARGE");
+/** A configured limit, or the default when it is missing or not a number >= 0. */
+const limitOr = (value, fallback) => typeof value === "number" && value >= 0 ? value : fallback;
+const isDataUri = (entry) => entry.startsWith("data:");
+const fsErrorCode = (error) => typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    typeof error.code === "string"
+    ? error.code
+    : undefined;
+/**
+ * Turn whatever the file system threw into the refusal the caller gets. Nothing
+ * raw gets through: a Node error message carries the server's path, and an
+ * unmapped code is logged for the operator (the code only) and answered like an
+ * unreadable file instead of surfacing as a 500.
+ */
+function asAgentInputError(error) {
+    if (error instanceof AgentInputError) {
+        return error;
+    }
+    const code = fsErrorCode(error);
+    switch (code) {
+        case "ENOENT":
+        case "ENOTDIR":
+            return notFound();
+        case "EACCES":
+        case "EPERM":
+        case "ELOOP":
+            return notReadable();
+        case "ENXIO":
+        case "EOPNOTSUPP":
+        case "ENOTSUP":
+        case "EISDIR":
+            return notAFile();
+        case "ENAMETOOLONG":
+        case "EINVAL":
+        case "ERR_INVALID_ARG_VALUE":
+            return new AgentInputError("attachment path is not a usable path", 400, "VALIDATION_ERROR");
+        default:
+            logger.warn("[agentInput] unmapped file-system error on an attachment", {
+                code,
+                name: error instanceof Error ? error.name : typeof error,
+            });
+            return notReadable();
+    }
+}
+/**
+ * A file under one of the allowed roots, after symlinks are resolved.
+ *
+ * A path outside every root is refused before the file system is touched, so
+ * the answer for `/etc/passwd` and for `/etc/nothing-here` is the same 403 and
+ * the route is not an oracle for which files exist.
+ */
+async function readAllowedPath(requested, roots, limit) {
+    if (!roots || roots.length === 0) {
+        throw forbidden();
+    }
+    const lexical = path.resolve(requested);
+    const realRoots = (await Promise.all(roots.map(async (root) => {
+        try {
+            return [path.resolve(root), await fs.promises.realpath(root)];
+        }
+        catch {
+            return [];
+        }
+    }))).flat();
+    if (!realRoots.some((root) => isUnder(lexical, root))) {
+        throw forbidden();
+    }
+    let real;
+    try {
+        real = await fs.promises.realpath(lexical);
+    }
+    catch (error) {
+        throw asAgentInputError(error);
+    }
+    if (!realRoots.some((root) => isUnder(real, root))) {
+        throw forbidden();
+    }
+    // Open once and judge the descriptor, not the path: a path can be swapped for
+    // a symlink between the checks above and a later read. O_NOFOLLOW refuses a
+    // symlink in the last component; a directory swapped higher up is not caught,
+    // which matters only if something untrusted can write under an allowed root.
+    let handle;
+    try {
+        // O_NONBLOCK: opening a FIFO for reading otherwise waits for a writer, and
+        // each such request would hold a libuv worker until one appears. With it
+        // the open returns at once and the stat below refuses the FIFO as not a
+        // file. Regular files read the same either way. Windows has no constant.
+        handle = await fs.promises.open(real, fs.constants.O_RDONLY |
+            fs.constants.O_NOFOLLOW |
+            (fs.constants.O_NONBLOCK ?? 0));
+    }
+    catch (error) {
+        throw asAgentInputError(error);
+    }
+    let content;
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile()) {
+            throw notAFile();
+        }
+        if (stat.size > limit) {
+            throw tooLarge(limit);
+        }
+        content = await readWithinLimit(handle, limit);
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        throw asAgentInputError(error);
+    }
+    try {
+        await handle.close();
+    }
+    catch (error) {
+        throw asAgentInputError(error);
+    }
+    return content;
+}
+/**
+ * Read the whole file, refusing one that outgrew `limit` since it was measured:
+ * reads one byte past the limit, so growth is seen rather than buffered.
+ */
+async function readWithinLimit(handle, limit) {
+    const chunks = [];
+    let total = 0;
+    while (total <= limit) {
+        const chunk = Buffer.allocUnsafe(Math.min(READ_CHUNK_BYTES, limit + 1 - total));
+        const { bytesRead } = await handle.read(chunk, 0, chunk.length, total);
+        if (bytesRead === 0) {
+            break;
+        }
+        chunks.push(chunk.subarray(0, bytesRead));
+        total += bytesRead;
+    }
+    if (total > limit) {
+        throw tooLarge(limit);
+    }
+    return Buffer.concat(chunks, total);
+}
+async function downloadAttachment(url, limit) {
+    // Dynamic import keeps undici off the static import graph; see
+    // test/continuous-test-suite-import-cost.ts.
+    const { safeDownload } = await import("../../utils/safeFetch.js");
+    try {
+        return await safeDownload(url, {
+            maxBytes: limit,
+            label: "agent attachment",
+        });
+    }
+    catch (error) {
+        // The reason can name the address a host resolved to; the caller gets none
+        // of it, the operator gets it in the log.
+        const reason = error instanceof Error ? error.message : String(error);
+        logger.warn("[agentInput] refused an attachment URL", {
+            reason: reason.replaceAll(url, "<url>"),
+        });
+        throw new AgentInputError("attachment URL could not be fetched (it must be a public https URL, answer without a redirect and fit the size limit)", 400, "VALIDATION_ERROR");
+    }
+}
+/** The bytes of one attachment that is not a `data:` URI, read within `limit`. */
+async function resolveAttachment(entry, roots, limit) {
+    if (/^https?:\/\//i.test(entry)) {
+        return downloadAttachment(entry, limit);
+    }
+    if (URL_SCHEME.test(entry)) {
+        throw new AgentInputError("attachment must be a data: URI, an https URL, or a path under an allowed directory", 400, "VALIDATION_ERROR");
+    }
+    return readAllowedPath(entry, roots, limit);
+}
+/**
+ * Replace every attachment of an agent request's `input` with vetted content.
+ *
+ * @throws {AgentInputError} for the first attachment that is refused, or for a
+ *   request that carries too many attachments or too many bytes.
+ */
+export async function resolveAgentInput(input, options) {
+    const maxAttachments = limitOr(options?.maxInputAttachments, DEFAULT_MAX_INPUT_ATTACHMENTS);
+    const totalBytes = limitOr(options?.maxInputTotalBytes, DEFAULT_MAX_INPUT_TOTAL_BYTES);
+    const perAttachment = Math.min(limitOr(options?.maxInputBytes, DEFAULT_MAX_INPUT_BYTES), totalBytes);
+    const roots = options?.allowedInputRoots;
+    const entries = [...(input.images ?? []), ...(input.files ?? [])];
+    // Everything that needs no I/O is judged first, so a request that is already
+    // too big costs the server nothing: the count, then each data: URI against
+    // its own cap and against the shared budget.
+    if (entries.length > maxAttachments) {
+        throw tooMany(maxAttachments);
+    }
+    let remaining = totalBytes;
+    for (const entry of entries) {
+        if (!isDataUri(entry)) {
+            continue;
+        }
+        if (entry.length > perAttachment) {
+            throw tooLarge(perAttachment);
+        }
+        remaining -= entry.length;
+        if (remaining < 0) {
+            throw budgetExceeded(totalBytes);
+        }
+    }
+    // One at a time: a request naming many URLs must not open them all at once,
+    // and each entry may use only what the ones before it left of the budget.
+    const resolveList = async (list) => {
+        if (list === undefined) {
+            return undefined;
+        }
+        const resolved = [];
+        for (const entry of list) {
+            // Exactly the prefix the SDK keys on, so nothing that reaches it as a
+            // string is anything but a data URI.
+            if (isDataUri(entry)) {
+                resolved.push(entry);
+                continue;
+            }
+            const limit = Math.min(perAttachment, remaining);
+            let bytes;
+            try {
+                bytes = await resolveAttachment(entry, roots, limit);
+            }
+            catch (error) {
+                if (limit < perAttachment &&
+                    error instanceof AgentInputError &&
+                    error.status === 413) {
+                    throw budgetExceeded(totalBytes);
+                }
+                throw error;
+            }
+            remaining -= bytes.length;
+            resolved.push(bytes);
+        }
+        return resolved;
+    };
+    const images = await resolveList(input.images);
+    const files = await resolveList(input.files);
+    return {
+        text: input.text,
+        ...(images ? { images } : {}),
+        ...(files ? { files } : {}),
+    };
+}

package/dist/types/server.d.ts

@@ -434,6 +434,45 @@ export type AgentExecuteRequest = {
     /** User ID for context */
     userId?: string;
 };
+/** Options for `createAgentRoutes()`. */
+export type ServerAgentRouteOptions = {
+    /**
+     * Directories a request's `input.images` / `input.files` entries may name as
+     * local paths. Empty or omitted (the default) refuses every local path: a
+     * server must not read its own disk on a caller's say-so unless the operator
+     * names where.
+     */
+    allowedInputRoots?: string[];
+    /**
+     * Largest single attachment accepted, in bytes. Default 50 MiB. A `data:` URI
+     * is measured by its string length. When `maxInputTotalBytes` is set lower,
+     * the smaller of the two is the per-attachment cap.
+     */
+    maxInputBytes?: number;
+    /**
+     * Most attachments one request may carry, `input.images` and `input.files`
+     * counted together. Default 20. A longer list is refused with 413 before any
+     * attachment is read or downloaded.
+     */
+    maxInputAttachments?: number;
+    /**
+     * Largest sum of all attachments of one request, in bytes: images and files
+     * share this one budget, and a `data:` URI is charged its string length.
+     * Default 100 MiB. A request that overflows it is refused with 413, and a
+     * file or download that would overflow it stops mid-transfer.
+     */
+    maxInputTotalBytes?: number;
+};
+/**
+ * An agent request's `input` once every attachment has been vetted: URLs and
+ * allowed local paths are replaced by the bytes the server read itself, `data:`
+ * URIs pass through untouched.
+ */
+export type ServerAgentResolvedInput = {
+    text: string;
+    images?: Array<Buffer | string>;
+    files?: Array<Buffer | string>;
+};
 /**
  * Agent execution response
  */
@@ -941,12 +980,16 @@ export type ServerServerAuthConfig = {
      */
     extractToken?: (ctx: ServerContext) => string | null;
     /**
-     * Skip authentication for dev playground requests in non-production.
-     * When true (default), requests with x-neurolink-dev-playground or
-     * x-neurolink-playground header set to "true" will bypass authentication
-     * and receive a default developer user context.
+     * Skip authentication for dev playground requests during development.
+     * When true (default), a request with an x-neurolink-dev-playground or
+     * x-neurolink-playground header set to "true" bypasses authentication and
+     * receives a default developer user context (`id: "playground"`,
+     * `roles: ["developer"]`).
      *
-     * Only applies when NODE_ENV is not "production".
+     * Only applies when `process.env.NODE_ENV` is exactly `"development"`,
+     * read on every request. With NODE_ENV unset, `"production"`, `"test"` or
+     * any other value the header is ignored and the request must authenticate
+     * as usual. Set this to `false` to refuse the header even in development.
      *
      * @default true
      */
@@ -1106,6 +1149,12 @@ export type CreateRoutesOptions = {
      * always mounted.
      */
     transcribe?: ServerTranscribeRouteOptions;
+    /**
+     * Options for the agent routes (`POST <basePath>/agent/execute` and
+     * `/agent/stream`): where local-path attachments may be read from, and how
+     * large an attachment may be.
+     */
+    agent?: ServerAgentRouteOptions;
 };
 /** Options for `createTranscribeRoutes()`. */
 export type ServerTranscribeRouteOptions = {