@juspay/neurolink 13.8.17 → 13.8.19

package/dist/cli/utils/serverUtils.js

@@ -6,14 +6,60 @@ import { timingSafeEqual } from "crypto";
 import fs from "fs";
 import os from "os";
 import path from "path";
+import { DEFAULT_SERVER_HOST } from "../../server/abstract/baseServerAdapter.js";
 import { ConfigurationError } from "../../server/errors.js";
 import { createAuthMiddleware } from "../../server/middleware/auth.js";
+import { isLoopbackAddress } from "../../server/utils/clientAddress.js";
+import { stripQuery } from "../../server/utils/pathMatch.js";
 // ============================================
 // Listen Address & Access Control
 // ============================================
 export const DEFAULT_SERVER_PORT = 3000;
-/** Comma-separated API keys; when set, every route except health needs one. */
+/** The interface `neurolink serve` binds unless told otherwise: this host only. */
+export { DEFAULT_SERVER_HOST };
+/** Comma-separated API keys; when set, every route except the health probes needs one. */
 export const SERVER_API_KEY_ENV = "NEUROLINK_SERVER_API_KEY";
+/**
+ * `=1` lets `neurolink serve` listen on a non-loopback host with no API key,
+ * and serves the tool and MCP execution routes to anyone who can reach it.
+ */
+export const SERVER_ALLOW_UNAUTHENTICATED_ENV = "NEUROLINK_SERVER_ALLOW_UNAUTHENTICATED";
+/** `=1` keeps the built-in tools (filesystem among them) in the server's registry. */
+export const SERVER_ENABLE_BUILTIN_TOOLS_ENV = "NEUROLINK_SERVER_ENABLE_BUILTIN_TOOLS";
+/** `=1` lets the transcription WebSocket take the API key as `?token=`. */
+export const SERVER_WS_ALLOW_QUERY_TOKEN_ENV = "NEUROLINK_SERVER_WS_ALLOW_QUERY_TOKEN";
+/** Whether `name` is set to `1` (trimmed) in the environment. */
+export function envFlag(name) {
+    return process.env[name]?.trim() === "1";
+}
+/** `true` when `host` names only this machine (`127.0.0.1`, `::1`, `localhost`). */
+export function isLoopbackHost(host) {
+    return isLoopbackAddress(host);
+}
+/**
+ * Why `neurolink serve` must not start as asked, or `undefined` when it may.
+ * A listener the network can reach with no API key hands every route, tool
+ * execution included, to anyone who finds the port; the operator has to say so.
+ */
+export function unauthenticatedBindRefusal(options) {
+    if (options.apiKeyCount > 0 ||
+        options.allowUnauthenticated ||
+        isLoopbackHost(options.host)) {
+        return undefined;
+    }
+    return (`Refusing to listen on ${options.host} without authentication: every route, including tool execution, would be open to anyone who can reach this port. ` +
+        `Set ${SERVER_API_KEY_ENV}, bind a loopback address (--host ${DEFAULT_SERVER_HOST}), or pass --allow-unauthenticated (${SERVER_ALLOW_UNAUTHENTICATED_ENV}=1) to run open on purpose.`);
+}
+/**
+ * The paths a key never guards: the liveness, readiness and startup probes an
+ * orchestrator calls with no credentials, and the basic health check. An
+ * exact list: `/health/detailed` reports the runtime and the MCP inventory,
+ * and `/version` the Node version, so both need the key like any other route.
+ */
+export function healthExemptPaths(basePath) {
+    const health = `${basePath.replace(/\/+$/, "")}/health`;
+    return [health, `${health}/live`, `${health}/ready`, `${health}/startup`];
+}
 /**
  * Resolve the listen port: --port, then the config file, then the PORT
  * environment variable (what container platforms set), then 3000.
@@ -39,8 +85,11 @@ export function readServerApiKeys() {
 const matchesKey = (key, token) => key.length === token.length && timingSafeEqual(key, token);
 /**
  * Require one of `apiKeys` as `Authorization: Bearer <key>` or `X-API-Key`.
- * Health probes stay open so orchestrators can reach them, and the dev
- * playground header cannot bypass a key the operator configured.
+ * The health probes (see `healthExemptPaths`) stay open so orchestrators can
+ * reach them, and the dev playground header cannot bypass a key the operator
+ * configured. The exemption is an exact match on the path, made here rather
+ * than through the adapters' `excludePaths`, whose entries cover a subtree:
+ * `/health` used to exempt `/health/detailed` and even `/health/api/version`.
  *
  * Every holder of a key gets the same `{ id: "api-key" }`, marked `shared` so
  * the agent routes know it names no person and do not warn when a request
@@ -48,10 +97,11 @@ const matchesKey = (key, token) => key.length === token.length && timingSafeEqua
  */
 export function createServerApiKeyMiddleware(apiKeys, basePath) {
     const keys = apiKeys.map((key) => Buffer.from(key, "utf8"));
-    return createAuthMiddleware({
+    const exempt = new Set(healthExemptPaths(basePath));
+    const inner = createAuthMiddleware({
         type: "custom",
         extractToken: (ctx) => {
-            const bearer = /^Bearer\s+(.+)$/i.exec(ctx.headers["authorization"] ?? "");
+            const bearer = /^Bearer\s+(\S.*)$/i.exec(ctx.headers["authorization"] ?? "");
             return bearer?.[1] ?? ctx.headers["x-api-key"] ?? null;
         },
         validate: async (token) => {
@@ -60,9 +110,16 @@ export function createServerApiKeyMiddleware(apiKeys, basePath) {
                 ? { id: "api-key", shared: true }
                 : null;
         },
-        skipPaths: [`${basePath.replace(/\/+$/, "")}/health`],
         skipDevPlayground: false,
     });
+    return {
+        ...inner,
+        name: "api-key",
+        excludePaths: undefined,
+        handler: (ctx, next) => exempt.has(stripQuery(ctx.path).replace(/\/+$/, "") || "/")
+            ? next()
+            : inner.handler(ctx, next),
+    };
 }
 // ============================================
 // State Directory Management

package/dist/core/baseProvider.js

@@ -3039,7 +3039,13 @@ export class BaseProvider {
             const { executeDirectorPipeline, DIRECTOR_PIPELINE_TIMEOUT_MS } = await import("../adapters/video/directorPipeline.js");
             // Use caller's timeout if provided, otherwise use default Director timeout
             const directorTimeout = options.timeout ?? DIRECTOR_PIPELINE_TIMEOUT_MS;
-            const videoResult = await this.executeWithTimeout(() => executeDirectorPipeline(segments, generateOptions.output?.video ?? {}, generateOptions.output?.director ?? {}, options.region), { timeout: directorTimeout, operationType: "generate" });
+            const videoResult = await this.executeWithTimeout(() => executeDirectorPipeline(segments, generateOptions.output?.video ?? {}, {
+                ...(generateOptions.output?.director ?? {}),
+                // Director Mode fetches/reads reference images itself; hand it
+                // the same attachment policy the rest of the request runs under.
+                attachmentPolicy: generateOptions.output?.director?.attachmentPolicy ??
+                    options.attachmentPolicy,
+            }, options.region), { timeout: directorTimeout, operationType: "generate" });
             // Build content summary with metadata
             const joinedPrompts = generateOptions.input.segments
                 .map((s) => s.prompt)

package/dist/core/modules/MessageBuilder.js

@@ -1,6 +1,7 @@
 import { tracers, ATTR, withSpan } from "../../telemetry/index.js";
 import { logger } from "../../utils/logger.js";
 import { buildMessagesArray, buildMultimodalModelMessages, } from "../../utils/messageBuilder.js";
+import { getAttachmentPolicy } from "../../utils/attachmentPolicy.js";
 /**
  * Compute total content length across all messages for span attributes.
  */
@@ -131,6 +132,9 @@ export class MessageBuilder {
                     schema: options.schema,
                     output: options.output,
                     fileRegistry: options.fileRegistry,
+                    // The instance's attachment policy has to ride along like the
+                    // registry: this literal is the only road into the loaders.
+                    attachmentPolicy: getAttachmentPolicy(options),
                 };
                 messages = await buildMultimodalModelMessages(multimodalOptions, this.providerName, this.modelName);
                 // Propagate any systemPrompt augmentation (e.g. inline-file
@@ -280,6 +284,7 @@ export class MessageBuilder {
                     schema: options.schema,
                     output: options.output,
                     fileRegistry: options.fileRegistry,
+                    attachmentPolicy: getAttachmentPolicy(options),
                 };
                 messages = await buildMultimodalModelMessages(multimodalOptions, this.providerName, this.modelName);
                 // Propagate any systemPrompt augmentation (e.g. inline-file

package/dist/core/modules/ToolsManager.d.ts

@@ -40,6 +40,36 @@ export declare class ToolsManager {
      * every tool uncancellable (deadline overshoot / ghost executions).
      */
     private wrapExecuteWithTruncation;
+    /**
+     * The HITL manager of the owning NeuroLink instance, when one is configured.
+     * It lives on the tool registry (`setHITLManager`), which is also where the
+     * registered-tool execution path reads it, so the two paths cannot disagree.
+     */
+    private resolveHITLManager;
+    /**
+     * Whether a built-in tool call must be confirmed by a human first.
+     *
+     * Same rule as `MCPToolRegistry.executeTool` applies to registered tools —
+     * `dangerousActions` keywords and `customRules` — plus the built-in tools
+     * that change the machine (`HITL_ALWAYS_CONFIRM_DIRECT_TOOLS`), which are
+     * confirmed on every call unless `hitl.confirmBuiltinTools` is `false`.
+     */
+    private directToolNeedsConfirmation;
+    /**
+     * Gate a built-in (direct) tool's execute behind the instance's HITL
+     * manager, with the semantics of the registry path: a denial throws
+     * `HITLUserRejectedError` (the loop reports it to the model as a failed
+     * call), a timeout propagates the manager's `HITLTimeoutError` (or the
+     * auto-approval it is configured for), and user-modified arguments replace
+     * the model's. Without HITL the execute runs untouched.
+     *
+     * Direct tools reach the model through `getAllTools()` and are executed by
+     * the provider loops directly, never through `MCPToolRegistry.executeTool`
+     * — so before this wrapper the registry's HITL check never saw them, and
+     * `writeFile` / `executeBashCommand` ran unconfirmed while the bash tool's
+     * own description promised otherwise.
+     */
+    private wrapExecuteWithHITL;
     /**
      * Byte budget for BZ-666 truncation. Reads the instance-level
      * `tools.outputTruncationMaxBytes` config (see `ToolConfig` /
@@ -182,7 +212,22 @@ export declare class ToolsManager {
      */
     private createCustomToolFromDefinition;
     /**
-     * Create an external MCP tool
+     * Prepare an external tool's declaration and validator from its inputSchema,
+     * once per schema object (see mcpSchemaCache).
+     *
+     * The schema is a remote server's data. Every `pattern` and every
+     * `patternProperties` key in it is compiled with `new RegExp` by the
+     * validator on each check, so one nested-quantifier pattern from a server
+     * could stall the event loop for seconds per tool call.
+     * Patterns `vetRegexPattern` refuses are removed before the validator is
+     * built and reported once, at warn level.
+     */
+    private prepareExternalToolSchema;
+    /**
+     * Create an external MCP tool. `registeredName` is the key the tool is
+     * exposed under — normally `tool.name`, or `<serverId>__<tool.name>` after a
+     * collision — and is what events and spans report; execution always goes to
+     * the owning server by the tool's own name.
      */
     private createExternalMCPTool;
 }

package/dist/core/modules/ToolsManager.js

@@ -7,7 +7,8 @@ import { TOOL_EVENTS_WRAPPED } from "../../types/index.js";
 import { getKeyCount } from "../../utils/transformationUtils.js";
 import { extractIsErrorText } from "../../utils/toolResultStatus.js";
 import { createToolExecutionId } from "../../utils/toolExecutionId.js";
-import { convertJsonSchemaToZod } from "../../utils/schemaConversion.js";
+import { convertJsonSchemaToZod, stripUnsafeRegexPatterns, } from "../../utils/schemaConversion.js";
+import { HITLUserRejectedError } from "../../hitl/hitlErrors.js";
 import { generateToolOutputPreview, DEFAULT_MAX_PREVIEW_BYTES, RETRIEVE_CONTEXT_TOOL_NAME, } from "../../context/toolOutputLimits.js";
 /**
  * Own property stamped on a tool object whose `execute` already emits
@@ -32,17 +33,55 @@ function makeToolAbortError() {
     return e;
 }
 /**
- * Compiled-validator cache, keyed by the ORIGINAL MCP tool inputSchema
- * object. createExternalMCPTool runs once per external tool on EVERY
- * getAllTools() (i.e. every generation call), and the schema object identity
- * is stable for the lifetime of a server connection — without the cache the
- * same JSON Schema is recompiled on every generate() (hot-path CPU for
- * 50+-tool deployments). Rediscovery produces new schema objects, so stale
- * entries fall out via WeakMap semantics. `undefined` values (schemas that
- * failed to compile) are cached too — hence has()/get() rather than a
- * get()-only check.
+ * Built-in tools that change the machine. While HITL is enabled they require
+ * confirmation on every call, whatever `dangerousActions` lists, unless the
+ * host sets `hitl.confirmBuiltinTools: false`. The other built-ins (clock,
+ * arithmetic, reads, directory listings, CSV analysis, web search) are gated
+ * by `dangerousActions` keywords and `customRules` like every other tool.
  */
-const mcpValidatorCache = new WeakMap();
+const HITL_ALWAYS_CONFIRM_DIRECT_TOOLS = new Set([
+    "writeFile",
+    "executeBashCommand",
+]);
+/** serverId the registry uses for the built-in tools; reused in HITL requests. */
+const DIRECT_TOOL_SERVER_ID = "direct";
+/** Tool names a provider accepts: 1-64 characters from this set. */
+const TOOL_NAME_SAFE_CHARS = /[^A-Za-z0-9_-]/g;
+const MAX_TOOL_NAME_LENGTH = 64;
+/**
+ * `<serverId>__<tool>`, reduced to the characters every provider accepts and
+ * to 64 characters, keeping the tool name's tail (the distinctive part) when
+ * the two together are too long.
+ */
+function qualifyToolName(serverId, toolName) {
+    const safeServer = serverId.replace(TOOL_NAME_SAFE_CHARS, "_") || "server";
+    const safeTool = toolName.replace(TOOL_NAME_SAFE_CHARS, "_") || "tool";
+    const joined = `${safeServer}__${safeTool}`;
+    if (joined.length <= MAX_TOOL_NAME_LENGTH) {
+        return joined;
+    }
+    const room = MAX_TOOL_NAME_LENGTH - safeTool.length - 2;
+    return room > 0
+        ? `${safeServer.slice(0, room)}__${safeTool}`
+        : joined.slice(-MAX_TOOL_NAME_LENGTH);
+}
+/**
+ * Per-schema cache of the prepared declaration and compiled validator, keyed
+ * by the ORIGINAL MCP tool inputSchema object. createExternalMCPTool runs once
+ * per external tool on EVERY getAllTools() (i.e. every generation call), and
+ * the schema object identity is stable for the lifetime of a server connection
+ * — without the cache the same JSON Schema is cloned, vetted and recompiled on
+ * every generate() (hot-path CPU for 50+-tool deployments). Rediscovery
+ * produces new schema objects, so stale entries fall out via WeakMap
+ * semantics. An `undefined` validator (a schema that failed to compile) is
+ * cached too — hence has()/get() rather than a get()-only check.
+ *
+ * `schema` is the declaration the model sees: strict-mode fixed and with every
+ * regular expression `vetRegexPattern` refused removed. The removal
+ * happens once per schema object, so its warning fires once per schema, not
+ * once per request.
+ */
+const mcpSchemaCache = new WeakMap();
 /**
  * Build an argument validator for an external MCP tool's JSON Schema, in the
  * shape the AI SDK's `jsonSchema()` wrapper expects. Returns undefined when
@@ -235,6 +274,72 @@ export class ToolsManager {
             return this.truncateToolResult(toolName, result);
         };
     }
+    /**
+     * The HITL manager of the owning NeuroLink instance, when one is configured.
+     * It lives on the tool registry (`setHITLManager`), which is also where the
+     * registered-tool execution path reads it, so the two paths cannot disagree.
+     */
+    resolveHITLManager() {
+        const registry = this.neurolink?.getToolRegistry?.();
+        const manager = registry && typeof registry.getHITLManager === "function"
+            ? registry.getHITLManager()
+            : undefined;
+        return manager && manager.isEnabled() ? manager : undefined;
+    }
+    /**
+     * Whether a built-in tool call must be confirmed by a human first.
+     *
+     * Same rule as `MCPToolRegistry.executeTool` applies to registered tools —
+     * `dangerousActions` keywords and `customRules` — plus the built-in tools
+     * that change the machine (`HITL_ALWAYS_CONFIRM_DIRECT_TOOLS`), which are
+     * confirmed on every call unless `hitl.confirmBuiltinTools` is `false`.
+     */
+    directToolNeedsConfirmation(manager, toolName, params) {
+        if (manager.requiresConfirmation(toolName, params)) {
+            return true;
+        }
+        if (!HITL_ALWAYS_CONFIRM_DIRECT_TOOLS.has(toolName)) {
+            return false;
+        }
+        const confirmBuiltins = manager.getConfig().confirmBuiltinTools;
+        return confirmBuiltins !== false;
+    }
+    /**
+     * Gate a built-in (direct) tool's execute behind the instance's HITL
+     * manager, with the semantics of the registry path: a denial throws
+     * `HITLUserRejectedError` (the loop reports it to the model as a failed
+     * call), a timeout propagates the manager's `HITLTimeoutError` (or the
+     * auto-approval it is configured for), and user-modified arguments replace
+     * the model's. Without HITL the execute runs untouched.
+     *
+     * Direct tools reach the model through `getAllTools()` and are executed by
+     * the provider loops directly, never through `MCPToolRegistry.executeTool`
+     * — so before this wrapper the registry's HITL check never saw them, and
+     * `writeFile` / `executeBashCommand` ran unconfirmed while the bash tool's
+     * own description promised otherwise.
+     */
+    wrapExecuteWithHITL(toolName, execute) {
+        return async (params, execOptions) => {
+            const manager = this.resolveHITLManager();
+            if (!manager ||
+                !this.directToolNeedsConfirmation(manager, toolName, params)) {
+                return execute(params, execOptions);
+            }
+            logger.info(`Built-in tool '${toolName}' requires HITL confirmation`);
+            const confirmation = await manager.requestConfirmation(toolName, params, {
+                serverId: DIRECT_TOOL_SERVER_ID,
+                sessionId: this.sessionId,
+                userId: this.userId,
+            });
+            if (!confirmation.approved) {
+                throw new HITLUserRejectedError(`Tool execution rejected by user: ${confirmation.reason || "No reason provided"}`, toolName, confirmation.reason);
+            }
+            const finalParams = confirmation.modifiedArguments !== undefined
+                ? confirmation.modifiedArguments
+                : params;
+            return execute(finalParams, execOptions);
+        };
+    }
     /**
      * Byte budget for BZ-666 truncation. Reads the instance-level
      * `tools.outputTruncationMaxBytes` config (see `ToolConfig` /
@@ -740,8 +845,10 @@ export class ToolsManager {
                 typeof directTool === "object" &&
                 "execute" in directTool) {
                 const originalExecute = directTool.execute;
-                // Create a new tool with wrapped execute function (BZ-666/BZ-664 guards applied)
-                const guardedExecute = this.wrapExecuteWithTruncation(toolName, originalExecute);
+                // Create a new tool with wrapped execute function (BZ-666/BZ-664 guards applied).
+                // HITL sits INSIDE the truncation wrapper so a pending confirmation is
+                // raced against the loop's abort signal like any other tool wait.
+                const guardedExecute = this.wrapExecuteWithTruncation(toolName, this.wrapExecuteWithHITL(toolName, originalExecute));
                 tools[toolName] = markEventWrapped({
                     ...directTool,
                     execute: this.wrapExecuteWithEvents(toolName, guardedExecute),
@@ -810,11 +917,32 @@ export class ToolsManager {
         }
         try {
             const externalTools = await this.neurolink.getExternalMCPTools();
+            // Which server owns each external name added in this pass, so a
+            // collision names both sides. Names present before this phase belong to
+            // a built-in or a registered tool.
+            const externalOwners = new Map();
             let addedCount = 0;
             for (const tool of externalTools) {
-                const mcpTool = await this.createExternalMCPTool(tool);
-                if (mcpTool && !tools[tool.name]) {
-                    tools[tool.name] = mcpTool;
+                const serverId = tool.serverId || "unknown";
+                let registeredName = tool.name;
+                if (tools[tool.name]) {
+                    // A silent first-wins drop here left the losing server's tool
+                    // unreachable, with the outcome depending on connection order
+                    //. Keep both: the later one is registered
+                    // under `<serverId>__<tool>` so the model can still call it.
+                    const owner = externalOwners.get(tool.name);
+                    const qualified = qualifyToolName(serverId, tool.name);
+                    if (tools[qualified]) {
+                        logger.warn(`[ToolsManager] Tool name collision: '${tool.name}' from server '${serverId}' is already provided by ${owner ? `server '${owner}'` : "a built-in or registered tool"}, and the qualified name '${qualified}' is taken too; the '${serverId}' copy is not exposed to the model`);
+                        continue;
+                    }
+                    logger.warn(`[ToolsManager] Tool name collision: '${tool.name}' from server '${serverId}' is already provided by ${owner ? `server '${owner}'` : "a built-in or registered tool"}; the '${serverId}' copy is exposed as '${qualified}'`);
+                    registeredName = qualified;
+                }
+                const mcpTool = await this.createExternalMCPTool(tool, registeredName);
+                if (mcpTool) {
+                    tools[registeredName] = mcpTool;
+                    externalOwners.set(registeredName, serverId);
                     addedCount++;
                 }
             }
@@ -993,36 +1121,55 @@ export class ToolsManager {
         }
     }
     /**
-     * Create an external MCP tool
+     * Prepare an external tool's declaration and validator from its inputSchema,
+     * once per schema object (see mcpSchemaCache).
+     *
+     * The schema is a remote server's data. Every `pattern` and every
+     * `patternProperties` key in it is compiled with `new RegExp` by the
+     * validator on each check, so one nested-quantifier pattern from a server
+     * could stall the event loop for seconds per tool call.
+     * Patterns `vetRegexPattern` refuses are removed before the validator is
+     * built and reported once, at warn level.
      */
-    async createExternalMCPTool(tool) {
+    async prepareExternalToolSchema(toolName, serverId, originalSchema) {
+        const cached = mcpSchemaCache.get(originalSchema);
+        if (cached) {
+            return cached;
+        }
+        // Clone and fix the schema for OpenAI strict mode compatibility
+        const fixedSchema = this.utilities?.fixSchemaForOpenAIStrictMode
+            ? this.utilities.fixSchemaForOpenAIStrictMode(originalSchema)
+            : originalSchema;
+        const { schema, drops } = stripUnsafeRegexPatterns(fixedSchema);
+        if (drops.length > 0) {
+            logger.warn(`[ToolsManager] Removed ${drops.length} regular expression pattern(s) from the schema of tool '${toolName}' (server '${serverId}') because they could stall the process; the affected fields are validated without them`, { drops: drops.map(({ path, reason }) => ({ path, reason })) });
+        }
+        // A jsonSchema() wrapper WITHOUT a validate function is declarative
+        // only — the AI SDK passes any parsed arguments straight through
+        // (safeValidateTypes short-circuits on `validate == null`). That let
+        // malformed calls (missing required params, "123" for a number)
+        // reach execution, where the MCP-layer validator rejected them at
+        // the cost of a full model round-trip. Attach a real validator so
+        // invalid calls fail at parse time, where experimental_repairToolCall
+        // can still fix them silently.
+        const validate = await buildMCPSchemaValidator(toolName, schema);
+        const prepared = { schema, validate };
+        mcpSchemaCache.set(originalSchema, prepared);
+        return prepared;
+    }
+    /**
+     * Create an external MCP tool. `registeredName` is the key the tool is
+     * exposed under — normally `tool.name`, or `<serverId>__<tool.name>` after a
+     * collision — and is what events and spans report; execution always goes to
+     * the owning server by the tool's own name.
+     */
+    async createExternalMCPTool(tool, registeredName = tool.name) {
         try {
             // Use original JSON Schema from MCP tool if available, otherwise use permissive schema
             let finalSchema;
             if (tool.inputSchema && typeof tool.inputSchema === "object") {
-                // Clone and fix the schema for OpenAI strict mode compatibility
-                const originalSchema = tool.inputSchema;
-                const fixedSchema = this.utilities?.fixSchemaForOpenAIStrictMode
-                    ? this.utilities.fixSchemaForOpenAIStrictMode(originalSchema)
-                    : originalSchema;
-                // A jsonSchema() wrapper WITHOUT a validate function is declarative
-                // only — the AI SDK passes any parsed arguments straight through
-                // (safeValidateTypes short-circuits on `validate == null`). That let
-                // malformed calls (missing required params, "123" for a number)
-                // reach execution, where the MCP-layer validator rejected them at
-                // the cost of a full model round-trip. Attach a real validator so
-                // invalid calls fail at parse time, where experimental_repairToolCall
-                // can still fix them silently. Compiled once per schema object —
-                // see mcpValidatorCache.
-                let validate;
-                if (mcpValidatorCache.has(originalSchema)) {
-                    validate = mcpValidatorCache.get(originalSchema);
-                }
-                else {
-                    validate = await buildMCPSchemaValidator(tool.name, fixedSchema);
-                    mcpValidatorCache.set(originalSchema, validate);
-                }
-                finalSchema = jsonSchema(fixedSchema, validate ? { validate } : {});
+                const { schema, validate } = await this.prepareExternalToolSchema(tool.name, tool.serverId || "unknown", tool.inputSchema);
+                finalSchema = jsonSchema(schema, validate ? { validate } : {});
             }
             else {
                 finalSchema = this.utilities?.createPermissiveZodSchema
@@ -1037,7 +1184,7 @@ export class ToolsManager {
                 }
                 throw new Error(`Cannot execute external MCP tool: NeuroLink executeExternalMCPTool not available`);
             };
-            const guardedExecute = this.wrapExecuteWithTruncation(tool.name, rawExecute);
+            const guardedExecute = this.wrapExecuteWithTruncation(registeredName, rawExecute);
             const loggedExecute = async (params, execOptions) => {
                 try {
                     return await guardedExecute(params, execOptions);
@@ -1053,7 +1200,7 @@ export class ToolsManager {
             return markEventWrapped(createAISDKTool({
                 description: tool.description || `External MCP tool ${tool.name}`,
                 inputSchema: finalSchema, // AI SDK v6 uses inputSchema (not parameters)
-                execute: this.wrapExecuteWithEvents(tool.name, loggedExecute),
+                execute: this.wrapExecuteWithEvents(registeredName, loggedExecute),
             }));
         }
         catch (toolCreationError) {

package/dist/files/fileReferenceRegistry.d.ts

@@ -12,32 +12,11 @@
  * @module files/fileReferenceRegistry
  */
 import type { FileSource, FileExtractionParams, FileExtractionResult, FileReadResult, FileReference, FileRegistrationOptions, FileRegistryOptions, FileSearchResult, SizeTier } from "../types/index.js";
-/**
- * Registry for managing file references with on-demand processing.
- *
- * Design decisions:
- * - One instance per NeuroLink SDK instance (not global singleton)
- * - File buffers persisted to temp dir for later streaming access
- * - LRU eviction when maxFiles exceeded
- * - Thread-safe via sequential async operations (Node.js single-threaded)
- *
- * @example
- * ```typescript
- * const registry = new FileReferenceRegistry();
- * const ref = await registry.register(buffer, {
- *   filename: 'report.xlsx',
- * });
- * console.log(ref.sizeTier);      // 'medium'
- * console.log(ref.preview);       // First 2000 chars of processed content
- * console.log(ref.estimatedTokens); // Type-aware estimate
- *
- * // Later, LLM requests specific section
- * const section = await registry.readSection(ref.id, 1, 50, 5000);
- * ```
- */
 export declare class FileReferenceRegistry {
     private files;
     private tempDir;
+    /** `tempDir` was supplied by the host rather than minted here. */
+    private readonly tempDirSupplied;
     private maxFiles;
     private maxTempBytes;
     private defaultPreviewChars;

package/dist/files/fileReferenceRegistry.js

@@ -12,7 +12,8 @@
  * @module files/fileReferenceRegistry
  */
 import { randomUUID } from "node:crypto";
-import { mkdir, readFile, stat, unlink, writeFile } from "node:fs/promises";
+import { rmSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, rm, stat, unlink, writeFile, } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, extname, join } from "node:path";
 import { estimatePostProcessingTokens } from "../context/fileTokenBudget.js";
@@ -51,17 +52,49 @@ const MAX_ACCEPTED_SIZE = 2 * 1024 * 1024 * 1024;
  * const section = await registry.readSection(ref.id, 1, 50, 5000);
  * ```
  */
+/**
+ * Temp directories this process created and has not yet removed. Swept on
+ * `exit` so an attachment persisted for lazy reading does not outlive the
+ * process that read it (a `clear()` that never ran, a crash, a SIGTERM that
+ * reached `exit`). Created directories are 0o700 and files 0o600, so until
+ * then only this user can read them.
+ */
+const ACTIVE_TEMP_DIRS = new Set();
+let exitSweepRegistered = false;
+function registerExitSweep() {
+    if (exitSweepRegistered) {
+        return;
+    }
+    exitSweepRegistered = true;
+    process.on("exit", () => {
+        for (const dir of ACTIVE_TEMP_DIRS) {
+            try {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                // Best effort: the exit handler must not throw.
+            }
+        }
+        ACTIVE_TEMP_DIRS.clear();
+    });
+}
 export class FileReferenceRegistry {
     files = new Map();
     tempDir;
+    /** `tempDir` was supplied by the host rather than minted here. */
+    tempDirSupplied;
     maxFiles;
     maxTempBytes;
     defaultPreviewChars;
     currentTempBytes = 0;
     tempDirCreated = false;
     constructor(options = {}) {
+        // A host-supplied directory is used as given; otherwise the directory is
+        // minted with `mkdtemp` (0o700) on first use, so its name is unguessable
+        // and nothing else on the host can read what lands in it.
+        this.tempDirSupplied = Boolean(options.tempDir);
         this.tempDir =
-            options.tempDir || join(tmpdir(), "neurolink-files", randomUUID());
+            options.tempDir || join(tmpdir(), `neurolink-files-${randomUUID()}`);
         this.maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
         this.maxTempBytes = options.maxTempBytes ?? DEFAULT_MAX_TEMP_BYTES;
         this.defaultPreviewChars =
@@ -686,6 +719,13 @@ export class FileReferenceRegistry {
         }
         this.files.clear();
         this.currentTempBytes = 0;
+        // Remove the directory itself, not only the files in it, and forget it so
+        // a later registration mints a fresh one.
+        if (this.tempDirCreated) {
+            await rm(this.tempDir, { recursive: true, force: true }).catch(() => undefined);
+            ACTIVE_TEMP_DIRS.delete(this.tempDir);
+            this.tempDirCreated = false;
+        }
     }
     /**
      * Get the number of registered files.
@@ -1505,13 +1545,23 @@ export class FileReferenceRegistry {
                 throw new Error(`Temp directory budget exceeded (${this.formatSize(this.maxTempBytes)})`);
             }
         }
-        // Ensure temp directory exists
+        // Ensure temp directory exists. Owner-only: the files persisted here are
+        // the caller's attachments, and the OS temp directory is shared.
         if (!this.tempDirCreated) {
-            await mkdir(this.tempDir, { recursive: true });
+            if (this.tempDirSupplied) {
+                await mkdir(this.tempDir, { recursive: true, mode: 0o700 });
+            }
+            else {
+                this.tempDir = await mkdtemp(join(tmpdir(), "neurolink-files-"));
+            }
+            registerExitSweep();
+            ACTIVE_TEMP_DIRS.add(this.tempDir);
             this.tempDirCreated = true;
         }
         const tempPath = join(this.tempDir, `${id}${ext ? `.${ext}` : ""}`);
-        await writeFile(tempPath, buffer);
+        // `wx`: create, never overwrite — an id collision or a file planted at the
+        // path fails loudly instead of being written over. 0o600: owner-only.
+        await writeFile(tempPath, buffer, { mode: 0o600, flag: "wx" });
         this.currentTempBytes += buffer.length;
         return tempPath;
     }

package/dist/hitl/hitlManager.js

@@ -57,6 +57,7 @@ export class HITLManager extends EventEmitter {
                 : (config.autoApproveExclusions ?? []),
             auditLogging: config.auditLogging ?? false, // Default: false
             customRules: config.customRules ?? [], // Default: empty array
+            confirmBuiltinTools: config.confirmBuiltinTools ?? true, // Default: true (built-in write/bash tools prompt)
         };
         if (!configWithDefaults.enabled) {
             return configWithDefaults; // If disabled, don't validate other fields