@juspay/neurolink 12.27.1 → 12.28.0

package/dist/neurolink.js

@@ -62,6 +62,7 @@ import { createSkillCallTools, createSkillTools } from "./skills/skillTools.js";
 import { getMetricsAggregator, MetricsAggregator, } from "./observability/metricsAggregator.js";
 import { AnalyticsService, calculateAdvancedCost, parseAnalyticsQualityScore, } from "./analytics/index.js";
 import { SpanStatus, SpanType, CircuitBreakerOpenError, ConversationMemoryError, ModelAccessDeniedError, } from "./types/index.js";
+import { resolveTerminalAgentMode } from "./agent/prompts/terminalAgentPrompt.js";
 import { SpanSerializer } from "./observability/utils/spanSerializer.js";
 import { withSpan } from "./telemetry/withSpan.js";
 import { getActiveTraceContext } from "./telemetry/traceContext.js";
@@ -99,6 +100,7 @@ import { isZodSchema, convertZodToJsonSchema, } from "./utils/schemaConversion.j
 import { resolveToolPolicy } from "./tools/toolPolicy.js";
 import { applyToolGate } from "./tools/toolGate.js";
 import { directAgentTools } from "./agent/directTools.js";
+import { bindFileToolRoots, boundFileToolRoots, resolveFileToolRootPolicy, } from "./utils/fileToolRoots.js";
 import { BinaryTaskClassifier } from "./utils/taskClassifier.js";
 // Tool detection and execution imports
 // Transformation utilities
@@ -899,7 +901,15 @@ export class NeuroLink {
         return metricsTraceContextStorage.getStore() ?? null;
     }
     constructor(config) {
-        this.toolRegistry = config?.toolRegistry || new MCPToolRegistry();
+        if (config?.toolRegistry) {
+            // A supplied registry (a host's, shared with a worker) keeps its owner's
+            // roots; per-call executeTool() binds this instance's policy anyway.
+            this.toolRegistry = config.toolRegistry;
+        }
+        else {
+            this.toolRegistry = new MCPToolRegistry();
+            this.toolRegistry.setFileToolRootResolver(() => this.resolveFileToolRoots(undefined));
+        }
         this.fileRegistry = new FileReferenceRegistry();
         this.observabilityConfig = config?.observability;
         this.analyticsService = new AnalyticsService();
@@ -3310,6 +3320,9 @@ Current user's request: ${currentInput}`;
         // String prompts are immutable, so they pass through.
         if (typeof optionsOrPrompt !== "string") {
             optionsOrPrompt = cloneOptionsForCallIsolation(optionsOrPrompt);
+            // Resolved once per call and always overwrites a caller-supplied
+            // policy; an invalid root fails here, before any model call.
+            bindFileToolRoots(optionsOrPrompt, this.resolveFileToolRoots(optionsOrPrompt.toolRoots));
             // The deprecated `conversationHistory` field is not wired into message
             // building — messages passed there never reach the model, which reads
             // as "the SDK forgot my context" rather than a caller bug. Warn loudly
@@ -3321,6 +3334,20 @@ Current user's request: ${currentInput}`;
                 logger.warn("[NeuroLink.generate] `conversationHistory` is deprecated and NOT passed to the model — use `conversationMessages` (ChatMessage[]) instead.");
             }
         }
+        // Resolved once here and removed from the options, so no internal
+        // re-entrant generate() can prepend the agent instructions twice.
+        let agentModeVersion;
+        if (typeof optionsOrPrompt !== "string") {
+            const { agentMode, ...rest } = optionsOrPrompt;
+            if (agentMode !== undefined) {
+                const resolved = resolveTerminalAgentMode(agentMode, rest.systemPrompt);
+                agentModeVersion = resolved.version;
+                optionsOrPrompt = {
+                    ...rest,
+                    systemPrompt: resolved.systemPrompt,
+                };
+            }
+        }
         // Retrieve once at the public call boundary so fallback attempts reuse the
         // same grounding block and internal preparation cannot inject it twice.
         const groundingOptions = typeof optionsOrPrompt === "string"
@@ -3348,6 +3375,9 @@ Current user's request: ${currentInput}`;
             if (knowledgeOutcome) {
                 result.knowledge = knowledgeOutcome.metadata;
             }
+            if (agentModeVersion) {
+                result.agentModeVersion = agentModeVersion;
+            }
             return result;
         }
         catch (error) {
@@ -4198,6 +4228,7 @@ Current user's request: ${currentInput}`;
             // (which spreads its options) honoured it.
             disableInternalFallback: options.disableInternalFallback,
             maxSteps: options.maxSteps,
+            toolRoots: options.toolRoots,
             toolChoice: options.toolChoice,
             prepareStep: options.prepareStep,
             enabledToolNames: options.enabledToolNames,
@@ -4266,7 +4297,7 @@ Current user's request: ${currentInput}`;
                     : {}),
             };
         }
-        const textOptions = enhanceTextGenerationOptions(baseOptions, factoryResult);
+        const textOptions = bindFileToolRoots(enhanceTextGenerationOptions(baseOptions, factoryResult), this.fileToolRootsFor(options));
         if (this.conversationMemory) {
             textOptions.conversationMemoryConfig = this.conversationMemory.config;
             textOptions.originalPrompt = originalPrompt;
@@ -4943,10 +4974,15 @@ Current user's request: ${currentInput}`;
             options.prompt.trim() === "") {
             throw new Error("GenerateText options must include prompt as a non-empty string");
         }
+        // Isolate from the caller's object, then resolve file-tool roots exactly
+        // as generate() does: a widening or missing root rejects here, before any
+        // model call, and the resolved policy travels on the private channel.
+        const isolated = cloneOptionsForCallIsolation(options);
         // NL-004: Resolve model aliases/deprecations before processing
-        options.model = resolveModel(options.model, this.modelAliasConfig);
+        isolated.model = resolveModel(isolated.model, this.modelAliasConfig);
+        bindFileToolRoots(isolated, this.resolveFileToolRoots(isolated.toolRoots));
         // Use internal generation method directly
-        return await this.generateTextInternal(options);
+        return await this.generateTextInternal(isolated);
     }
     /**
      * REDESIGNED INTERNAL GENERATION - NO CIRCULAR DEPENDENCIES
@@ -5940,6 +5976,7 @@ Current user's request: ${currentInput}`;
             maxSteps: options.maxSteps,
             skipToolPromptInjection: options.skipToolPromptInjection,
         });
+        provider.setFileToolRootPolicy?.(this.fileToolRootsFor(options));
         const result = await provider.generate({
             ...options,
             systemPrompt: enhancedSystemPrompt,
@@ -6108,6 +6145,7 @@ Current user's request: ${currentInput}`;
                             disableToolCache: options.disableToolCache,
                         }),
                     }, functionTag);
+                    poolProvider.setFileToolRootPolicy?.(this.fileToolRootsFor(options));
                     const poolResult = await poolProvider.generate({
                         ...options,
                         conversationMessages: poolConversationMessages,
@@ -6482,6 +6520,7 @@ Current user's request: ${currentInput}`;
                         disableToolCache: options.disableToolCache,
                     }),
                 }, functionTag);
+                provider.setFileToolRootPolicy?.(this.fileToolRootsFor(options));
                 const result = await provider.generate({
                     ...options,
                     conversationMessages, // Inject conversation history
@@ -6830,6 +6869,16 @@ Current user's request: ${currentInput}`;
         // shallow rebind at the orchestration site only covered the
         // top-level keys and left `options.input` shared with the caller.
         options = cloneOptionsForCallIsolation(options);
+        let agentModeVersion;
+        {
+            const { agentMode, ...rest } = options;
+            if (agentMode !== undefined) {
+                const resolved = resolveTerminalAgentMode(agentMode, rest.systemPrompt);
+                agentModeVersion = resolved.version;
+                options = { ...rest, systemPrompt: resolved.systemPrompt };
+            }
+        }
+        bindFileToolRoots(options, this.resolveFileToolRoots(options.toolRoots));
         const startedAt = Date.now();
         // Retrieve once before provider/model fallback orchestration. Every fallback
         // receives the same explicitly enriched options, without the retrieval helper
@@ -6847,6 +6896,9 @@ Current user's request: ${currentInput}`;
             if (knowledgeOutcome) {
                 result.knowledge = knowledgeOutcome.metadata;
             }
+            if (agentModeVersion) {
+                result.agentModeVersion = agentModeVersion;
+            }
             return result;
         }
         catch (error) {
@@ -8415,6 +8467,7 @@ Current user's request: ${currentInput}`;
                     prompt: enhancedOptions.input.text,
                     context: enhancedOptions.context,
                 });
+            fallbackProvider.setFileToolRootPolicy?.(this.fileToolRootsFor(enhancedOptions));
             const fallbackResult = await fallbackProvider.stream({
                 ...this.deferProviderStreamTTS(enhancedOptions),
                 model: fallbackRoute.model,
@@ -8846,6 +8899,7 @@ Current user's request: ${currentInput}`;
                             disableToolCache: options.disableToolCache,
                         }),
                     }, "NeuroLink.createMCPStream");
+                    poolStreamProvider.setFileToolRootPolicy?.(this.fileToolRootsFor(options));
                     const poolStreamResult = await poolStreamProvider.stream({
                         ...this.deferProviderStreamTTS(options),
                         provider: poolStreamProviderName,
@@ -8925,6 +8979,7 @@ Current user's request: ${currentInput}`;
         // ─── End ModelPool stream path ────────────────────────────────────────────
         // 🔧 FIX: Pass enhanced system prompt to real streaming
         // Tools will be accessed through the streamText call in executeStream
+        provider.setFileToolRootPolicy?.(this.fileToolRootsFor(options));
         const streamResult = await provider.stream({
             ...this.deferProviderStreamTTS(options),
             systemPrompt: enhancedSystemPrompt, // Use enhanced prompt with tool descriptions
@@ -9048,6 +9103,7 @@ Current user's request: ${currentInput}`;
         const responseTime = Date.now() - startTime;
         const providerName = await getBestProvider(options.provider);
         const provider = await AIProviderFactory.createProvider(providerName, options.model, true, undefined, undefined, this.resolveCredentials(options.credentials));
+        provider.setFileToolRootPolicy?.(this.fileToolRootsFor(options));
         const fallbackStreamResult = await provider.stream({
             input: { text: options.input.text },
             model: options.model,
@@ -9422,6 +9478,39 @@ Current user's request: ${currentInput}`;
      * Called by `BaseProvider.applyToolFiltering` so the tool gate composes the
      * instance policy with per-call options on every generate/stream call.
      */
+    /**
+     * The policy an entry point bound to `options`, or — for an internal path
+     * that built its own options — the instance policy narrowed by any
+     * per-call `toolRoots`. Never trusts a public field.
+     */
+    fileToolRootsFor(options) {
+        return (boundFileToolRoots(options) ??
+            this.resolveFileToolRoots(options.toolRoots));
+    }
+    /**
+     * A worker's tool config: it inherits this instance's file-tool roots, and a
+     * worker-level `fileRoots` may only narrow them (throws otherwise).
+     */
+    workerToolsConfig(override) {
+        const hostRoots = this.toolsConfig?.fileRoots;
+        if (override?.fileRoots === undefined) {
+            return hostRoots === undefined
+                ? override
+                : { ...override, fileRoots: hostRoots };
+        }
+        const narrowed = resolveFileToolRootPolicy({
+            perCall: override.fileRoots,
+            instance: hostRoots,
+        }).roots;
+        return { ...override, fileRoots: narrowed ? [...narrowed] : [] };
+    }
+    /** File-tool roots for one call: per-call roots narrow the instance's `tools.fileRoots`. */
+    resolveFileToolRoots(perCall) {
+        return resolveFileToolRootPolicy({
+            perCall,
+            instance: this.toolsConfig?.fileRoots,
+        });
+    }
     getToolsConfig() {
         return this.toolsConfig;
     }
@@ -10679,11 +10768,8 @@ Current user's request: ${currentInput}`;
             try {
                 const storedContext = this.toolExecutionContext || {};
                 const passedAuthContext = options.authContext || {};
-                const context = {
-                    ...storedContext,
-                    ...passedAuthContext,
-                    hitlState: HITLState,
-                };
+                // This instance's roots, on the private channel (overwrites the caller's).
+                const context = bindFileToolRoots({ ...storedContext, ...passedAuthContext, hitlState: HITLState }, this.resolveFileToolRoots(undefined));
                 logger.debug(`[Using merged context for unified registry tool:`, {
                     toolName,
                     storedContextKeys: Object.keys(storedContext),
@@ -13206,7 +13292,8 @@ Current user's request: ${currentInput}`;
                 toolRegistry: this.toolRegistry,
             }),
         };
-        const worker = new NeuroLink(workerConfig);
+        const workerTools = this.workerToolsConfig(configOverrides.tools);
+        const worker = new NeuroLink(workerTools ? { ...workerConfig, tools: workerTools } : workerConfig);
         // The cacheable:false flag lives BESIDE the registry, not in it, so a
         // shared registry alone would re-enable caching on the worker for exactly
         // the tools whose results are live state (tasks_list, command_status,

package/dist/session/globalSessionState.d.ts

@@ -9,6 +9,7 @@ export declare class GlobalSessionManager {
     private _classifierRouterConfig;
     /** Optional skills config set by CLI handlers before SDK construction. */
     private _skillsConfig;
+    private _fileToolRoots;
     static getInstance(): GlobalSessionManager;
     setLoopSession(config?: ConversationMemoryConfig): string;
     /**
@@ -60,6 +61,13 @@ export declare class GlobalSessionManager {
      * already exists).
      */
     setSkillsConfig(config: SkillsConfig): void;
+    /**
+     * Store file-tool roots (`--tool-root`) to be injected at SDK construction
+     * time as `tools.fileRoots`. Call this BEFORE `getOrCreateNeuroLink()`.
+     * When a loop session is already active the roots are ignored (the
+     * instance already exists).
+     */
+    setFileToolRoots(roots: string[] | undefined): void;
     getOrCreateNeuroLink(): NeuroLink;
     getCurrentSessionId(): string | undefined;
     setSessionVariable(key: string, value: SessionVariableValue): void;

package/dist/session/globalSessionState.js

@@ -37,6 +37,7 @@ export class GlobalSessionManager {
     _classifierRouterConfig = undefined;
     /** Optional skills config set by CLI handlers before SDK construction. */
     _skillsConfig = undefined;
+    _fileToolRoots = undefined;
     static getInstance() {
         if (!GlobalSessionManager.instance) {
             GlobalSessionManager.instance = new GlobalSessionManager();
@@ -169,6 +170,18 @@ export class GlobalSessionManager {
         }
         this._skillsConfig = config;
     }
+    /**
+     * Store file-tool roots (`--tool-root`) to be injected at SDK construction
+     * time as `tools.fileRoots`. Call this BEFORE `getOrCreateNeuroLink()`.
+     * When a loop session is already active the roots are ignored (the
+     * instance already exists).
+     */
+    setFileToolRoots(roots) {
+        if (this.hasActiveSession() || !roots?.length) {
+            return;
+        }
+        this._fileToolRoots = roots;
+    }
     getOrCreateNeuroLink() {
         const session = this.getLoopSession();
         if (session) {
@@ -196,6 +209,10 @@ export class GlobalSessionManager {
             options.skills = this._skillsConfig;
             this._skillsConfig = undefined;
         }
+        if (this._fileToolRoots) {
+            options.tools = { ...options.tools, fileRoots: this._fileToolRoots };
+            this._fileToolRoots = undefined;
+        }
         return new NeuroLink(Object.keys(options).length ? options : undefined);
     }
     getCurrentSessionId() {

package/dist/types/agentMode.d.ts

@@ -0,0 +1,9 @@
+/** Version of the terminal agent instructions applied by `agentMode`. */
+export type TerminalAgentModeVersion = "1" | "2";
+/**
+ * Opt-in terminal agent mode. `true` applies the current instructions; the
+ * object form pins a version so results stay comparable across releases.
+ */
+export type TerminalAgentModeOption = boolean | {
+    version?: TerminalAgentModeVersion;
+};

package/dist/types/agentMode.js

@@ -0,0 +1 @@
+export {};

package/dist/types/cli.d.ts

@@ -55,6 +55,8 @@ export type GenerateCommandArgs = BaseCommandArgs & CliToolRoutingFlags & CliCla
     model?: string;
     /** System prompt */
     system?: string;
+    /** Prepend Neurolink's versioned terminal agent instructions */
+    agentMode?: boolean;
     /** Temperature setting */
     temperature?: number;
     /** Maximum tokens */
@@ -120,6 +122,10 @@ export type StreamCommandArgs = BaseCommandArgs & CliToolRoutingFlags & CliClass
     model?: string;
     /** System prompt */
     system?: string;
+    /** Prepend Neurolink's versioned terminal agent instructions */
+    agentMode?: boolean;
+    /** Maximum tool-calling steps */
+    maxSteps?: number;
     /** Temperature setting */
     temperature?: number;
     /** Maximum tokens */

package/dist/types/config.d.ts

@@ -427,6 +427,15 @@ export type ToolConfig = {
     enableMCPTools?: boolean;
     /** Whether the bash command execution tool should be enabled (opt-in, defaults to false) */
     enableBashTool?: boolean;
+    /**
+     * Directories the built-in file tools (readFile, listDirectory, writeFile,
+     * analyzeCSV) and bash's `cwd` argument may touch. Resolved through
+     * symlinks; each must be an existing directory. Default: the process
+     * working directory. An empty array denies all file access. Per-call
+     * `toolRoots` can only narrow this list. Roots do not sandbox the shell
+     * commands themselves — a command can still `cd` anywhere.
+     */
+    fileRoots?: string[];
     /**
      * Byte ceiling for the safety-net truncation `ToolsManager` applies to
      * every direct/custom/external-MCP tool result before it reaches the AI

package/dist/types/fileToolRoots.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Filesystem roots for the built-in file tools — types.
+ *
+ * Naming: `pathSandbox.ts` owns `PathSandbox*` and `file.ts` owns `FilePath*`,
+ * so this carries the `FileToolRoot` prefix (Critical Rule 9).
+ */
+/**
+ * The directories the built-in file tools (readFile, listDirectory,
+ * writeFile, analyzeCSV) and bash's `cwd` argument may touch for one request.
+ *
+ * `roots` are real, existing directories resolved once when the request
+ * starts. `null` means the historical default: the process working
+ * directory, read at call time. An empty array denies all file access.
+ */
+export type FileToolRootPolicy = {
+    readonly roots: readonly string[] | null;
+};

package/dist/types/fileToolRoots.js

@@ -0,0 +1,7 @@
+/**
+ * Filesystem roots for the built-in file tools — types.
+ *
+ * Naming: `pathSandbox.ts` owns `PathSandbox*` and `file.ts` owns `FilePath*`,
+ * so this carries the `FileToolRoot` prefix (Critical Rule 9).
+ */
+export {};

package/dist/types/generate.d.ts

@@ -5,6 +5,7 @@ import type { SkillsCallOptions } from "./skills.js";
 import type { AnalyticsData, TokenUsage } from "./analytics.js";
 import type { ClaudeLimitSnapshot } from "./subscription.js";
 import type { JsonValue } from "./common.js";
+import type { TerminalAgentModeOption, TerminalAgentModeVersion } from "./agentMode.js";
 import type { Content, ImageWithAltText } from "./content.js";
 import type { ChatMessage, ConversationMemoryConfig } from "./conversation.js";
 import type { EvaluationData } from "./evaluation.js";
@@ -310,6 +311,11 @@ export type GenerateOptions = {
     /** Stop sequences that will halt generation when encountered. */
     stopSequences?: string[];
     systemPrompt?: string;
+    /**
+     * Opt-in terminal agent mode: prepends Neurolink's versioned autonomous-agent
+     * instructions to `systemPrompt`. Omitted means no change in behaviour.
+     */
+    agentMode?: TerminalAgentModeOption;
     /**
      * Zod schema for structured output validation
      *
@@ -517,6 +523,13 @@ export type GenerateOptions = {
     disableInternalFallback?: boolean;
     /** Maximum number of tool execution steps (default: 200) */
     maxSteps?: number;
+    /**
+     * Directories the built-in file tools and bash's `cwd` argument may touch
+     * for this call. Can only narrow the instance's `tools.fileRoots` (or the
+     * working-directory default); a root outside them is rejected before any
+     * model call. An empty array denies all file access.
+     */
+    toolRoots?: string[];
     /**
      * Tool choice configuration for the generation.
      * Controls whether and which tools the model must call.
@@ -985,6 +998,8 @@ export type GenerateResult = {
     content: string;
     /** Knowledge-grounding diagnostics for this turn (present only when grounding ran). */
     knowledge?: KnowledgeGroundingMetadata;
+    /** Terminal agent instructions version applied (present only with `agentMode`). */
+    agentModeVersion?: TerminalAgentModeVersion;
     /**
      * Parsed structured object when a `schema` was requested. Populated from
      * AI-SDK experimental_output, or from text-mode coercion (balanced-scan +
@@ -1281,6 +1296,8 @@ export type TextGenerationOptions = {
     /** Disable the schema-driven tool call repair mechanism (BZ-665). Default: false (repair enabled). */
     disableToolCallRepair?: boolean;
     maxSteps?: number;
+    /** Directories the built-in file tools may touch for this call; see GenerateOptions.toolRoots. */
+    toolRoots?: string[];
     /** Include only these tools by name (whitelist). If set, only matching tools are available. */
     toolFilter?: string[];
     /** Exclude these tools by name (blacklist). Applied after toolFilter. */

package/dist/types/index.d.ts

@@ -4,6 +4,7 @@
  */
 export * from "./enums.js";
 export * from "./action.js";
+export * from "./agentMode.js";
 export * from "./aliases.js";
 export * from "./analytics.js";
 export * from "./artifact.js";
@@ -23,6 +24,7 @@ export * from "./delegation.js";
 export * from "./backgroundCommand.js";
 export * from "./gitTools.js";
 export * from "./pathSandbox.js";
+export * from "./fileToolRoots.js";
 export * from "./domain.js";
 export * from "./errors.js";
 export * from "./evaluation.js";

package/dist/types/index.js

@@ -5,6 +5,7 @@
 // All type files (alphabetical)
 export * from "./enums.js";
 export * from "./action.js";
+export * from "./agentMode.js";
 export * from "./aliases.js";
 export * from "./analytics.js";
 export * from "./artifact.js";
@@ -27,6 +28,7 @@ export * from "./backgroundCommand.js";
 export * from "./gitTools.js";
 // Path containment guard shared by the sandboxed execution paths
 export * from "./pathSandbox.js";
+export * from "./fileToolRoots.js";
 export * from "./domain.js";
 export * from "./errors.js";
 export * from "./evaluation.js";

package/dist/types/providers.d.ts

@@ -6,6 +6,7 @@ import type { NeuroLink } from "../neurolink.js";
 import { AIProviderName, AnthropicModels, BedrockModels, DeepSeekModels, GoogleAIModels, LlamaCppModels, LMStudioModels, NvidiaNimModels, OpenAIModels, VertexModels } from "../constants/enums.js";
 import type { ValidationSchema } from "./aliases.js";
 import type { DecisionLimits, DecisionRequest, DecisionResult } from "./decision.js";
+import type { FileToolRootPolicy } from "./fileToolRoots.js";
 import type { EnhancedGenerateResult, TextGenerationOptions } from "./generate.js";
 import type { MultimodalAudioEntry, MultimodalVideoEntry } from "./file.js";
 import type { StreamOptions, StreamResult } from "./stream.js";
@@ -833,6 +834,11 @@ export type AIProvider = {
         traceId: string;
         parentSpanId: string;
     } | null): void;
+    /**
+     * Bind the built-in file tools to one request's root policy. Optional so
+     * custom provider implementations keep compiling; BaseProvider implements it.
+     */
+    setFileToolRootPolicy?(policy: FileToolRootPolicy | undefined): void;
     /**
      * Whether this provider supports native tool/function calling for the
      * current model. Implemented by BaseProvider (default true); overridden by

package/dist/types/stream.d.ts

@@ -7,6 +7,7 @@ import type { AnalyticsData, ToolExecutionEvent, ToolExecutionSummary } from "..
 import type { MiddlewareFactoryOptions, OnChunkCallback, OnErrorCallback, OnFinishCallback } from "../types/middleware.js";
 import type { TokenUsage } from "./analytics.js";
 import type { JsonValue, UnknownRecord } from "./common.js";
+import type { TerminalAgentModeOption, TerminalAgentModeVersion } from "./agentMode.js";
 import type { Content, ImageWithAltText } from "./content.js";
 import type { ChatMessage } from "./conversation.js";
 import type { StreamNoOutputSentinel } from "./noOutputSentinel.js";
@@ -504,6 +505,8 @@ export type StreamOptions = {
     /** Stop sequences that will halt generation when encountered. */
     stopSequences?: string[];
     systemPrompt?: string;
+    /** Opt-in terminal agent mode. See GenerateOptions.agentMode. */
+    agentMode?: TerminalAgentModeOption;
     schema?: ValidationSchema;
     tools?: Record<string, Tool>;
     timeout?: number | string;
@@ -550,6 +553,8 @@ export type StreamOptions = {
     /** Disable the schema-driven tool call repair mechanism (BZ-665). Default: false (repair enabled). */
     disableToolCallRepair?: boolean;
     maxSteps?: number;
+    /** Directories the built-in file tools may touch for this call; see GenerateOptions.toolRoots; can only narrow tools.fileRoots. */
+    toolRoots?: string[];
     /**
      * Tool choice configuration for streaming generation.
      * Mirrors generate() so translated/fallback requests can preserve forced tool use.
@@ -777,6 +782,8 @@ export type StreamOptions = {
 export type StreamResult = {
     /** Knowledge-grounding diagnostics for this turn (present only when grounding ran). */
     knowledge?: KnowledgeGroundingMetadata;
+    /** Terminal agent instructions version applied (present only with `agentMode`). */
+    agentModeVersion?: TerminalAgentModeVersion;
     stream: AsyncIterable<{
         content: string;
         reasoning?: string;

package/dist/types/tools.d.ts

@@ -412,6 +412,13 @@ export type SdkSimpleTool<TArgs = ToolArgs, TResult = JsonValue> = Omit<SimpleTo
         [key: string]: JsonValue | undefined;
     };
 };
+/** Arguments of the built-in analyzeCSV tool, after schema defaults. */
+export type AnalyzeCsvToolArgs = {
+    filePath: string;
+    operation: "count_by_column" | "sum_by_column" | "average_by_column" | "min_max_by_column" | "describe";
+    column: string;
+    maxRows?: number;
+};
 /** Subset of directAgentTools exposing only the "basic" category. */
 export type BasicToolsMap = {
     getCurrentTime: Tool;

package/dist/utils/fileToolRoots.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Resolve which directories the built-in file tools may touch for a request.
+ *
+ * Precedence follows the credential pattern: per-call beats instance, and
+ * instance beats the `NEUROLINK_TOOL_ROOTS` environment variable. The
+ * instance list (or the environment, or the working directory) is a
+ * ceiling — per-call roots may only narrow it, so a server that forwards
+ * caller options cannot be talked into widening file access.
+ *
+ * Every root is resolved through realpath once, here, so a root reached
+ * through a symlink (`/home/user` → `/home/agent`) admits its own files, and
+ * a later `chdir` cannot move the boundary mid-request.
+ *
+ * @module utils/fileToolRoots
+ */
+import type { FileToolRootPolicy } from "../types/index.js";
+/**
+ * The file-tool root policy for one request.
+ *
+ * Returns `{ roots: null }` when nothing is configured anywhere, which keeps
+ * the historical behaviour: the working directory, read at call time.
+ *
+ * @throws when a root does not exist, is not a directory, or a per-call root
+ *   lies outside the instance ceiling. Callers invoke this before any model
+ *   request so a misconfiguration fails fast.
+ */
+export declare function resolveFileToolRootPolicy(input: {
+    perCall?: readonly string[];
+    instance?: readonly string[];
+}): FileToolRootPolicy;
+/** Attach a resolved policy to `target` (an options bag or execution context). */
+export declare function bindFileToolRoots<T extends object>(target: T, policy: FileToolRootPolicy): T;
+/** The policy bound by {@link bindFileToolRoots}, if any. */
+export declare function boundFileToolRoots(source: unknown): FileToolRootPolicy | undefined;