@juspay/neurolink 12.27.2 → 12.28.0

package/dist/utils/fileToolRoots.js

@@ -0,0 +1,111 @@
+/**
+ * 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 { realpathSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { isPathInsideRoot } from "./pathSandbox.js";
+const TOOL_ROOTS_ENV = "NEUROLINK_TOOL_ROOTS";
+// `node:path` delimiter, spelled out: the browser bundle stubs node:path without it.
+const PATH_LIST_DELIMITER = process.platform === "win32" ? ";" : ":";
+function realDirectoryOrThrow(root) {
+    let real;
+    try {
+        real = realpathSync(resolve(root));
+    }
+    catch {
+        throw new Error(`Tool root "${root}" does not exist. Configure file tool roots with existing directories.`);
+    }
+    if (!statSync(real).isDirectory()) {
+        throw new Error(`Tool root "${root}" is not a directory. Configure file tool roots with directories.`);
+    }
+    return real;
+}
+function resolveRoots(roots) {
+    return [...new Set(roots.map(realDirectoryOrThrow))];
+}
+function envRoots() {
+    const entries = (process.env[TOOL_ROOTS_ENV] ?? "")
+        .split(PATH_LIST_DELIMITER)
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    // An empty variable is treated as unset; denying all file access takes an
+    // explicit `fileRoots: []`.
+    return entries.length > 0 ? entries : undefined;
+}
+/**
+ * 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 function resolveFileToolRootPolicy(input) {
+    const configured = input.instance ?? envRoots();
+    if (configured === undefined && input.perCall === undefined) {
+        return { roots: null };
+    }
+    const ceiling = resolveRoots(configured ?? [process.cwd()]);
+    if (input.perCall === undefined) {
+        return Object.freeze({ roots: Object.freeze(ceiling) });
+    }
+    const narrowed = resolveRoots(input.perCall);
+    for (const root of narrowed) {
+        if (!ceiling.some((allowed) => isPathInsideRoot(root, allowed))) {
+            throw new Error(`Tool root "${root}" is outside the permitted roots (${ceiling.join(", ")}). ` +
+                "Per-call toolRoots can only narrow the instance's tools.fileRoots.");
+        }
+    }
+    return Object.freeze({ roots: Object.freeze(narrowed) });
+}
+/**
+ * The resolved policy travels on an options or execution-context object under
+ * this module-private symbol, never a public field. Callers can only name
+ * `toolRoots`, which is resolved and checked against the ceiling; untrusted
+ * JSON cannot carry a symbol, and entry points overwrite whatever is there.
+ * The property is enumerable so it survives the object spreads between the
+ * entry point and the provider.
+ */
+const BOUND_FILE_TOOL_ROOTS = Symbol("neurolink.fileToolRoots");
+/** Attach a resolved policy to `target` (an options bag or execution context). */
+export function bindFileToolRoots(target, policy) {
+    Object.defineProperty(target, BOUND_FILE_TOOL_ROOTS, {
+        value: policy,
+        enumerable: true,
+        configurable: true,
+        writable: true,
+    });
+    return target;
+}
+/** The policy bound by {@link bindFileToolRoots}, if any. */
+export function boundFileToolRoots(source) {
+    if (!source || typeof source !== "object") {
+        return undefined;
+    }
+    const value = Reflect.get(source, BOUND_FILE_TOOL_ROOTS);
+    if (!value || typeof value !== "object" || !("roots" in value)) {
+        return undefined;
+    }
+    const roots = value.roots;
+    if (roots === null) {
+        return { roots: null };
+    }
+    return Array.isArray(roots) &&
+        roots.every((root) => typeof root === "string")
+        ? { roots }
+        : undefined;
+}

package/dist/utils/pathSandbox.d.ts

@@ -1,10 +1,7 @@
 /**
- * Path containment guard for the sandboxed execution paths.
- *
- * `bashTool` does this check inline; `directTools.resolveWithinCwd` does a
- * weaker, non-symlink-aware version against `process.cwd()`. Neither is
- * reusable, and the background-command runner needs the strong form against a
- * caller-declared root, so it lives here once.
+ * Path containment guard for the sandboxed execution paths: the built-in file
+ * tools, bash's `cwd` argument and the background-command runner all check
+ * against caller-declared roots here, so the strong form lives in one place.
  *
  * The load-bearing detail is **realpath**. A string comparison on resolved
  * paths is defeated by a symlink: `<root>/escape → /etc` resolves lexically to
@@ -19,6 +16,12 @@
  * @module utils/pathSandbox
  */
 import type { PathSandboxResult } from "../types/index.js";
+/**
+ * Separator-bounded containment. A root that already ends in the separator
+ * (`/`, `C:\\`) contains every path that starts with it; appending another
+ * separator would turn `/` into `//` and deny everything.
+ */
+export declare function isPathInsideRoot(candidate: string, root: string): boolean;
 /**
  * Resolve `target` and confirm it is `root` or lies inside it, with symlinks
  * followed on both sides.

package/dist/utils/pathSandbox.js

@@ -1,10 +1,7 @@
 /**
- * Path containment guard for the sandboxed execution paths.
- *
- * `bashTool` does this check inline; `directTools.resolveWithinCwd` does a
- * weaker, non-symlink-aware version against `process.cwd()`. Neither is
- * reusable, and the background-command runner needs the strong form against a
- * caller-declared root, so it lives here once.
+ * Path containment guard for the sandboxed execution paths: the built-in file
+ * tools, bash's `cwd` argument and the background-command runner all check
+ * against caller-declared roots here, so the strong form lives in one place.
  *
  * The load-bearing detail is **realpath**. A string comparison on resolved
  * paths is defeated by a symlink: `<root>/escape → /etc` resolves lexically to
@@ -18,7 +15,7 @@
  *
  * @module utils/pathSandbox
  */
-import { realpathSync, statSync } from "node:fs";
+import { lstatSync, realpathSync, statSync } from "node:fs";
 import { basename, isAbsolute, join, resolve, sep } from "node:path";
 /** Real path of an existing directory, or undefined. */
 function realDirectory(candidate) {
@@ -39,9 +36,28 @@ function realEntry(candidate) {
         return undefined;
     }
 }
-function isInside(candidate, root) {
-    return candidate === root || candidate.startsWith(root + sep);
+/** A symbolic link that does not resolve (dangling, or a loop). */
+function isUnresolvableLink(candidate) {
+    try {
+        return lstatSync(candidate).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Separator-bounded containment. A root that already ends in the separator
+ * (`/`, `C:\\`) contains every path that starts with it; appending another
+ * separator would turn `/` into `//` and deny everything.
+ */
+export function isPathInsideRoot(candidate, root) {
+    if (candidate === root) {
+        return true;
+    }
+    const prefix = root.endsWith(sep) ? root : root + sep;
+    return candidate.startsWith(prefix);
 }
+const isInside = isPathInsideRoot;
 /**
  * Resolve `target` and confirm it is `root` or lies inside it, with symlinks
  * followed on both sides.
@@ -108,6 +124,13 @@ export function resolvePathWithinRoot(target, root) {
     if (direct) {
         return isInside(direct, realRoot) ? { path: direct } : denied;
     }
+    // The path does not resolve. A link that exists but points nowhere is where
+    // a write would be redirected — a dangling `<root>/x → /elsewhere/new` would
+    // pass an ancestor check and then create `/elsewhere/new` — so any
+    // unresolvable link on the way down is refused outright.
+    if (isUnresolvableLink(requested)) {
+        return denied;
+    }
     let existing = resolve(requested, "..");
     let suffix = basename(requested);
     for (;;) {
@@ -117,6 +140,9 @@ export function resolvePathWithinRoot(target, root) {
                 ? { path: resolve(real, suffix) }
                 : denied;
         }
+        if (isUnresolvableLink(existing)) {
+            return denied;
+        }
         const parent = resolve(existing, "..");
         if (parent === existing) {
             return denied;

package/docs-site/static/search-index.json

@@ -1132,12 +1132,12 @@
 {"objectID":"60ff5ff90a83793fbb662616b0bd566cd23eca8a84655b42e5b32cf4f90e1daa","title":"5. Evaluation Best Practices","url":"/docs/cli-domain-examples#5-evaluation-best-practices","content":"Always enable evaluation for critical domain applications\nUse domain-specific evaluation criteria\nMonitor evaluation scores for quality assurance\nCombine evaluation with analytics for comprehensive insights","hierarchy":{"lvl0":"Cli Domain Examples","lvl1":"Domain Configuration Examples for NeuroLink CLI","lvl2":"5. Evaluation Best Practices","lvl3":""}},
 {"objectID":"dd41aac620495beb0dc46254d107039ea15114bed43604934ce603872cd9850e","title":"Common Issues and Solutions","url":"/docs/cli-domain-examples#common-issues-and-solutions","content":"Unknown domain error\nContext parsing errors\nPerformance issues\nProvider compatibility","hierarchy":{"lvl0":"Cli Domain Examples","lvl1":"Domain Configuration Examples for NeuroLink CLI","lvl2":"Common Issues and Solutions","lvl3":""}},
 {"objectID":"5e572d81420e9fe637d381fe38515132c6e63595631c3d0a7334086dc2e801b8","title":"Additional Resources","url":"/docs/cli-domain-examples#additional-resources","content":"CLI Reference\nConfiguration Guide\nPerformance Optimization\nAPI Documentation\n\nFor more examples and advanced usage patterns, visit the NeuroLink Examples Repository.","hierarchy":{"lvl0":"Cli Domain Examples","lvl1":"Domain Configuration Examples for NeuroLink CLI","lvl2":"Additional Resources","lvl3":""}},
-{"objectID":"0714465a0877032f81918020770181bbb9b4996e234b593677c050ef344e6f7f","title":"🖥️ CLI Reference Guide","url":"/docs/cli-reference","content":"🖥️ CLI Reference Guide\n\nComplete Command Reference\n\nPrimary Usage (Recommended)\n\nMigration Examples\n\nCore Options\n\n| Flag            | Type    | Default          | Description                                                                                                                |\n| --------------- | ------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------- |\n|     | string  |            | AI provider (, , , , , , , , , ) |\n|        | string  | provider default | Specific model (e.g., , , )                                                       |\n|  | number  |             | Creativity level (0.0 = focused, 1.0 = creative)                                                                           |\n|   | number  |            | Maximum tokens to generate                                                                                                 |\n|       | string  | none             | System prompt to guide AI behavior                                                                                         |\n|       | string  |            | Output format (, )                                                                                             |\n|      | number  |             | Maximum execution time in seconds                                                                                          |\n|        | boolean |           | Enable debug mode with verbose output                                                                                      |\n\nEnhancement Features\n\n| Flag                  | Type    | Default | Description                                        |\n| --------------------- | ------- | ------- | -------------------------------------------------- |\n|   | boolean |  | Enable usage analytics (tokens, cost, performance) |\n|  | boolean |  | Enable AI response quality evaluation              |\n|            | string  | none    | JSON context object for custom data                |\n\nUniversal Evaluation System\n\n| Flag                   | Type    | Default | Description                                                   |\n| ---------------------- | ------- | ------- | ------------------------------------------------------------- |\n|   | string  | none    | Domain expertise for evaluation (e.g., 'AI coding assistant') |\n|  | string  | none    | Tool usage context for evaluation                             |\n|    | boolean |  | Use Lighthouse-compatible domain-aware evaluation             |\n\nMCP Integration\n\n| Flag              | Type    | Default | Description                                             |\n| ----------------- | ------- | ------- | ------------------------------------------------------- |\n|  | boolean |  | Disable MCP tool integration (tools enabled by default) |\n\nVideo Generation (Veo 3.1)\n\n| Flag                   | Type    | Default | Description                                                               |\n| ---------------------- | ------- | ------- | ------------------------------------------------------------------------- |\n|          | string  |   | Output mode: 'text', 'video', or 'ppt'                                    |\n|               | string  | none    | Path to an input image to base the generated video on (e.g., ./input.png) |\n| ,  | string  | none    | Path to save generated video (e.g., ./output.mp4)                         |\n|     | string  |   | Video resolution: '720p' or '1080p'                                       |\n|         | number  |      | Video duration in seconds: 4, 6, or 8                                     |\n|    | string  |   | Aspect ratio: '9:16' (portrait) or '16:9' (landscape)                     |\n|          | boolean |   | Include synchronized audio                                                |\n\nPPT Generation (AI Presentations)\n(string, default: ) — Output mode: , , or \n,  (number, default: ) — Number of slides to generate (5-50)\n(string, default: AI-selected) — Theme: , , , , or \n(string, default: AI-selected) — Audience: , , , or \n(string, default: AI-selected) — Tone: , , , or \n(boolean, default: ) — Disable AI image generation (AI images are enabled by default in CLI)\n(string, default: ) — Aspect ratio:  or \n,  (string, default: auto-generated) — Path to save generated presentation\n\nUsage Examples\n\nBasic Text Generation\n\nEnhanced Analytics & Evaluation\n\nDomain-Aware Evaluation\n\nDebug & Development\n\nAdvanced Examples\n\nOutput Examples\n\nBasic Output\n\nEnhanced Output (with --enable-analytics --enable-evaluation)\n\nDebug Output (with --debug)\n\nError Handling\n\nCommon Errors & Solutions\n\nProvider not available:\n\nInvalid context JSON:\n\nModel not found:\n\nEvaluation failed:\n\nPerformance Tips\nFast Evaluation: Use  for quick, cost-effective evaluation\nQuality Content: Use  for high-quality generation\nCost Optimization: Set  for automatic cost optimization\nDebug Efficiently: Use  only when troubleshooting to avoid verbose output\nConte","hierarchy":{"lvl0":"Cli Reference","lvl1":"🖥️ CLI Reference Guide","lvl2":"","lvl3":""}},
+{"objectID":"0714465a0877032f81918020770181bbb9b4996e234b593677c050ef344e6f7f","title":"🖥️ CLI Reference Guide","url":"/docs/cli-reference","content":"🖥️ CLI Reference Guide\n\nComplete Command Reference\n\nPrimary Usage (Recommended)\n\nMigration Examples\n\nCore Options\n\n| Flag            | Type    | Default          | Description                                                                                                                               |\n| --------------- | ------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |\n|     | string  |            | AI provider (, , , , , , , , , )                |\n|        | string  | provider default | Specific model (e.g., , , )                                                                      |\n|  | number  |             | Creativity level (0.0 = focused, 1.0 = creative)                                                                                          |\n|   | number  |            | Maximum tokens to generate                                                                                                                |\n|       | string  | none             | System prompt to guide AI behavior                                                                                                        |\n|   | boolean |           | Run as an autonomous terminal agent: prepend Neurolink's versioned agent instructions to the system prompt.  and  only. |\n|    | number  |             | Maximum tool-calling steps before the turn stops (integer 1–500). Some providers cap lower.  and  only.                 |\n|       | string  |            | Output format (, )                                                                                                            |\n|      | number  |             | Maximum execution time in seconds                                                                                                         |\n|        | boolean |           | Enable debug mode with verbose output                                                                                                     |\n\nEnhancement Features\n\n| Flag                  | Type    | Default | Description                                        |\n| --------------------- | ------- | ------- | -------------------------------------------------- |\n|   | boolean |  | Enable usage analytics (tokens, cost, performance) |\n|  | boolean |  | Enable AI response quality evaluation              |\n|            | string  | none    | JSON context object for custom data                |\n\nUniversal Evaluation System\n\n| Flag                   | Type    | Default | Description                                                   |\n| ---------------------- | ------- | ------- | ------------------------------------------------------------- |\n|   | string  | none    | Domain expertise for evaluation (e.g., 'AI coding assistant') |\n|  | string  | none    | Tool usage context for evaluation                             |\n|    | boolean |  | Use Lighthouse-compatible domain-aware evaluation             |\n\nMCP Integration\n\n| Flag              | Type    | Default | Description                                             |\n| ----------------- | ------- | ------- | ------------------------------------------------------- |\n|  | boolean |  | Disable MCP tool integration (tools enabled by default) |\n\nVideo Generation (Veo 3.1)\n\n| Flag                   | Type    | Default | Description                                                               |\n| ---------------------- | ------- | ------- | ------------------------------------------------------------------------- |\n|          | string  |   | Output mode: 'text', 'video', or 'ppt'                                    |\n|               | string  | none    | Path to an input image to base the generated video on (e.g., ./input.png) |\n| ,  | string  | none    | Path to save generated video (e.g., ./output.mp4)                         |\n|     | string  |   | Video resolution: '720p' or '1080p'                                       |\n|         | number  |      | Video duration in seconds: 4, 6, or 8                                     |\n|    | string  |   | Aspect ratio: '9:16' (portrait) or '16:9' (landscape)                     |\n|          | boolean |   | Include synchronized audio                                                |\n\nPPT Generation (AI Presentations)\n(string, default: ) — Output mode: , , or \n,  (number, default: ) — Number of slides to generate (5-50)\n(string, default: AI-selected) — Theme: , , , , or \n(string, default: AI-selected) — Audience: , , , or \n(string, default: AI-selected) — Tone: , , , or \n(boolean, default: ) — Disable AI image generation (AI images are enabled by default in CLI)\n(string, default: ) — Aspect ratio:  or \n,  (string, default: auto-generated) — Path to save generated presentation\n\nUsage Examples\n\nBasic Text Generation\n\nEnhanced Analytics & Evaluation\n\nDomain-Aware Evaluation\n\nDebug & Development\n\nAdvanced Examples\n\nOutput Examples\n\nBasic Output\n\nEnhanced Output (with --enabl","hierarchy":{"lvl0":"Cli Reference","lvl1":"🖥️ CLI Reference Guide","lvl2":"","lvl3":""}},
 {"objectID":"38ed564ef0c73b014068a5779a33c8ae3a9819853a07db28620e67d0ae5c7529","title":"Primary Usage (Recommended)","url":"/docs/cli-reference#primary-usage-recommended","content":"`bash","hierarchy":{"lvl0":"Cli Reference","lvl1":"🖥️ CLI Reference Guide","lvl2":"Primary Usage (Recommended)","lvl3":""}},
 {"objectID":"145fa74c68b2cb19eab6fba883cf3909db8ea68fb101d80766d9116180d3368e","title":"NEW: Primary command","url":"/docs/cli-reference#new-primary-command","content":"npx @juspay/neurolink generate \"Your prompt here\" [options]\nnpx @juspay/neurolink gen \"Your prompt here\" [options]    # Short form\n\n`","hierarchy":{"lvl0":"Cli Reference","lvl1":"🖥️ CLI Reference Guide","lvl2":"NEW: Primary command","lvl3":""}},
 {"objectID":"d1dd9c6e78327926039d1ee3df4319538047fb7f0c7913bb3e40f8db54dacca4","title":"Migration Examples","url":"/docs/cli-reference#migration-examples","content":"`bash","hierarchy":{"lvl0":"Cli Reference","lvl1":"🖥️ CLI Reference Guide","lvl2":"Migration Examples","lvl3":""}},
 {"objectID":"4353b5e4db9a5e0b634567604cba7a018a62eda1072a2edd0992bb5f5e9723d6","title":"✅ NEW: Recommended usage","url":"/docs/cli-reference#-new-recommended-usage","content":"npx @juspay/neurolink generate \"Explain AI\" --provider google-ai\nnpx @juspay/neurolink gen \"Write code\" --provider openai\n`","hierarchy":{"lvl0":"Cli Reference","lvl1":"🖥️ CLI Reference Guide","lvl2":"✅ NEW: Recommended usage","lvl3":""}},
-{"objectID":"761bade9189e0784a1f9b75e5ba3805db50591a39e281605a7c6f891a631084e","title":"Core Options","url":"/docs/cli-reference#core-options","content":"| Flag            | Type    | Default          | Description                                                                                                                |\n| --------------- | ------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------- |\n|     | string  |            | AI provider (, , , , , , , , , ) |\n|        | string  | provider default | Specific model (e.g., , , )                                                       |\n|  | number  |             | Creativity level (0.0 = focused, 1.0 = creative)                                                                           |\n|   | number  |            | Maximum tokens to generate                                                                                                 |\n|       | string  | none             | System prompt to guide AI behavior                                                                                         |\n|       | string  |            | Output format (, )                                                                                             |\n|      | number  |             | Maximum execution time in seconds                                                                                          |\n|        | boolean |           | Enable debug mode with verbose output                                                                                      |","hierarchy":{"lvl0":"Cli Reference","lvl1":"🖥️ CLI Reference Guide","lvl2":"Core Options","lvl3":""}},
+{"objectID":"761bade9189e0784a1f9b75e5ba3805db50591a39e281605a7c6f891a631084e","title":"Core Options","url":"/docs/cli-reference#core-options","content":"| Flag            | Type    | Default          | Description                                                                                                                               |\n| --------------- | ------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |\n|     | string  |            | AI provider (, , , , , , , , , )                |\n|        | string  | provider default | Specific model (e.g., , , )                                                                      |\n|  | number  |             | Creativity level (0.0 = focused, 1.0 = creative)                                                                                          |\n|   | number  |            | Maximum tokens to generate                                                                                                                |\n|       | string  | none             | System prompt to guide AI behavior                                                                                                        |\n|   | boolean |           | Run as an autonomous terminal agent: prepend Neurolink's versioned agent instructions to the system prompt.  and  only. |\n|    | number  |             | Maximum tool-calling steps before the turn stops (integer 1–500). Some providers cap lower.  and  only.                 |\n|       | string  |            | Output format (, )                                                                                                            |\n|      | number  |             | Maximum execution time in seconds                                                                                                         |\n|        | boolean |           | Enable debug mode with verbose output                                                                                                     |","hierarchy":{"lvl0":"Cli Reference","lvl1":"🖥️ CLI Reference Guide","lvl2":"Core Options","lvl3":""}},
 {"objectID":"7279eee139239c40051efeb2361bb7630f673ef350e8f803757f2f5fecee1c3c","title":"Enhancement Features","url":"/docs/cli-reference#enhancement-features","content":"| Flag                  | Type    | Default | Description                                        |\n| --------------------- | ------- | ------- | -------------------------------------------------- |\n|   | boolean |  | Enable usage analytics (tokens, cost, performance) |\n|  | boolean |  | Enable AI response quality evaluation              |\n|            | string  | none    | JSON context object for custom data                |","hierarchy":{"lvl0":"Cli Reference","lvl1":"🖥️ CLI Reference Guide","lvl2":"Enhancement Features","lvl3":""}},
 {"objectID":"f65b9263f8a85a02c4d7202f5ef217887b3604269a76f3b30be1fd8a1846a5bb","title":"Universal Evaluation System","url":"/docs/cli-reference#universal-evaluation-system","content":"| Flag                   | Type    | Default | Description                                                   |\n| ---------------------- | ------- | ------- | ------------------------------------------------------------- |\n|   | string  | none    | Domain expertise for evaluation (e.g., 'AI coding assistant') |\n|  | string  | none    | Tool usage context for evaluation                             |\n|    | boolean |  | Use Lighthouse-compatible domain-aware evaluation             |","hierarchy":{"lvl0":"Cli Reference","lvl1":"🖥️ CLI Reference Guide","lvl2":"Universal Evaluation System","lvl3":""}},
 {"objectID":"ab715fbd2d03072de907b61de7a797a229dd18141fb3cee69c020293b94b94df","title":"MCP Integration","url":"/docs/cli-reference#mcp-integration","content":"| Flag              | Type    | Default | Description                                             |\n| ----------------- | ------- | ------- | ------------------------------------------------------- |\n|  | boolean |  | Disable MCP tool integration (tools enabled by default) |","hierarchy":{"lvl0":"Cli Reference","lvl1":"🖥️ CLI Reference Guide","lvl2":"MCP Integration","lvl3":""}},
@@ -3741,7 +3741,7 @@
 {"objectID":"d72275c9e7abbf35d2de393371870aaa3be8bbdd91700d6b40b764f021b98ee7","title":"Testing","url":"/docs/features/mcp-enhancements#testing","content":"The MCP enhancements include a comprehensive continuous test suite covering all 14 modules.","hierarchy":{"lvl0":"Features","lvl1":"MCP Enhancements","lvl2":"Testing","lvl3":""}},
 {"objectID":"b7897e60e94294066b1f6cc7bf6826a9775fceed2d09959e6ddfaaea03c5e278","title":"Environment Variables","url":"/docs/features/mcp-enhancements#environment-variables","content":"| Variable        | Description                              | Default                |\n| --------------- | ---------------------------------------- | ---------------------- |\n|  | AI provider to use for integration tests |                |\n|     | Model name override                      | Provider default model |","hierarchy":{"lvl0":"Features","lvl1":"MCP Enhancements","lvl2":"Environment Variables","lvl3":""}},
 {"objectID":"41243c9cf6b59f63bf30d887f10b3be94d6ab2926fb59964b17b25292ef90e89","title":"Test Coverage","url":"/docs/features/mcp-enhancements#test-coverage","content":"The suite contains 44 test functions with 172+ assertions organized across 9 parts:\n\n| Part | Module                            | Tests | Focus                                                 |\n| ---- | --------------------------------- | ----- | ----------------------------------------------------- |\n| 1    | Tool Router                       | 5     | Strategies, registration, affinity, health, events    |\n| 2    | Tool Cache                        | 5     | Set/get, TTL, eviction, invalidation, stats           |\n| 3    | Request Batcher                   | 5     | Batching, flush, drain, server grouping, events       |\n| 4    | Tool Annotations                  | 5     | Inference, safety levels, validation, merge, filter   |\n| 5    | Tool Converter                    | 5     | Bidirectional conversion, batch, function, sanitize   |\n| 6    | Tool Integration & Middleware     | 5     | Middleware chain, elicitation, timeout, retry, custom |\n| 7    | Enhanced Discovery & Multi-Server | 5     | Search, safety filter, server groups, namespacing     |\n| 8    | Server Base, Exposure, Registry   | 5     | Custom server, agent/workflow exposure, registry      |\n| 9    | Server Capabilities & Elicitation | 4     | Resources, prompts, subscriptions, elicitation types  |","hierarchy":{"lvl0":"Features","lvl1":"MCP Enhancements","lvl2":"Test Coverage","lvl3":""}},
-{"objectID":"1f250cb2aa3fc19be6b69bf1883a325f5979f48d35c830dd3b09590df31fdd27","title":"MCP Tools Ecosystem - Built-in Tools + Any MCP Server","url":"/docs/features/mcp-tools-showcase","content":"MCP Tools Ecosystem: Built-in Tools + Any MCP Server\n\nSince: v7.0.0 | Status: Production Ready | MCP Version: 2024-11-05\n\nOverview\n\nNeuroLink's Model Context Protocol (MCP) integration provides a universal plugin system that transforms the SDK from a simple AI interface into a complete AI development platform. With 6 built-in core tools and the ability to connect any community MCP server (58+ cataloged in the server directory), you can extend AI capabilities to interact with filesystems, databases, APIs, cloud services, and custom enterprise systems.\n\nWhat is MCP?\n\nThe Model Context Protocol is an open standard (like USB-C for AI) that enables AI models to securely interact with external tools and data sources through a unified interface. Think of it as:\nFor Developers: A standardized way to connect AI to any external system\nFor AI Models: A tool registry with discoverable, executable functions\nFor Enterprises: A controlled, auditable way to extend AI capabilities\n\nWhy MCP Matters\n\n| Traditional Approach                    | MCP Approach                      | Benefit                 |\n| --------------------------------------- | --------------------------------- | ----------------------- |\n| Custom tool integrations per provider   | One MCP tool works everywhere     | 10x faster integration  |\n| Manual tool discovery and configuration | Automatic tool registry           | Zero-config tool usage  |\n| Provider-specific tool formats          | Universal JSON-RPC protocol       | Provider portability    |\n| Limited to SDK-defined tools            | any community MCP server + custom | Unlimited extensibility |\n| Static tool set                         | Dynamic runtime addition          | Adapt to changing needs |\n\nNeuroLink's Deep MCP Integration\n\nFactory-First Architecture: MCP tools work internally while users see simple factory methods:\n\nKey Features:\n99% Lighthouse Compatible: Existing MCP tools work with minimal changes\nDynamic Server Management: Add/remove MCP servers programmatically\nRich Context: 15+ fields including session, user, permissions, metadata\nPerformance Optimized: 0-11ms tool execution (target: \\<100ms)\nEnterprise Grade: Comprehensive error handling, audit logging, security\n\nQuick Start\n\nBuilt-in Core Tools (6)\n\nNeuroLink ships with 6 essential tools that require zero configuration:\ngetCurrentTime\n\nPurpose: Real-time clock with timezone support\n\nAuto-Available: Yes (always enabled)\n\nUse Cases:\nTimestamp generation\nTimezone conversions\nScheduling and reminders\nTime-based calculations\n\nExample:\n\nTool Schema:\nreadFile\n\nPurpose: Read file contents from filesystem\n\nAuto-Available: Yes (with filesystem access)\n\nUse Cases:\nDocument analysis\nCode review\nConfiguration reading\nLog file processing\n\nExample:\n\nTool Schema:\nwriteFile\n\nPurpose: Write content to filesystem\n\nAuto-Available: Yes (with HITL approval recommended)\n\nUse Cases:\nGenerated content saving\nReport creation\nConfiguration updates\nCode generation output\n\nExample:\n\nTool Schema:\nlistDirectory\n\nPurpose: List files and directories\n\nAuto-Available: Yes (with filesystem access)\n\nUse Cases:\nProject structure analysis\nFile discovery\nDirectory traversal\nAsset inventory\n\nExample:\n\nTool Schema:\ncalculateMath\n\nPurpose: Complex mathematical calculations\n\nAuto-Available: Yes (always enabled)\n\nUse Cases:\nFinancial calculations\nStatistical analysis\nUnit conversions\nScientific computations\n\nExample:\n\nTool Schema:\nwebsearchGrounding\n\nPurpose: Web search with result grounding\n\nAuto-Available: Only with Google Vertex AI provider\n\nUse Cases:\nReal-time information lookup\nFact verification\nCurrent events\nResearch augmentation\n\nExample:\n\nTool Schema:\n\nNote: This tool is provider-specific (Google Vertex AI only) and leverages Google's grounding capabilities.\n\nExternal MCP Servers\n\nNeuroLink connects to the growing MCP ecosystem — any MCP-compliant server works; the server catalog lists 58+ across 6 major categories.\n\nQuick Integration Example\n\nProductivity Tools (8 Servers)\n\nEnterprise collaboration and workflow automation\n\nGitHub - Complete Repository Management\n\nInstall: \n\nTools (15):\n- Create GitHub issues\n- Create PRs with diff\n- List repositories\n- Search code across repos\n- Read file from repo\n- Create new branch\n- View commit history\n- Get issue details\n- Update issue status\n- Add comments\n- List PRs\n- Merge PR\n- Create new repo\n- Fork repo\n- Star repo\n\nUse Cases:\nAutomated code reviews\nIssue management from AI chat\nRepository analysis\nCI/CD integration\nTeam collaboration\n\nExample:\n\nGoogle Drive - Document Management\n\nInstall: \n\nTools (12):\n- List files and folders\n- Search by name/content\n- Read document contents\n- Create new file\n- Update existing file\n- Delete file\n- Manage sharing\n- Create folder\n- Move file to folder\n- Duplicate file\n- Export to different format\n- View file permissions\n\nUse Cases:\nDocument processing automation\nReport generation\nTeam collaboration\nContent migration\n\nSlack - Team Communication\n\nInstall: \n\nTools (10):\n- Send message to ","hierarchy":{"lvl0":"Features","lvl1":"MCP Tools Ecosystem - Built-in Tools + Any MCP Server","lvl2":"","lvl3":""}},
+{"objectID":"1f250cb2aa3fc19be6b69bf1883a325f5979f48d35c830dd3b09590df31fdd27","title":"MCP Tools Ecosystem - Built-in Tools + Any MCP Server","url":"/docs/features/mcp-tools-showcase","content":"MCP Tools Ecosystem: Built-in Tools + Any MCP Server\n\nSince: v7.0.0 | Status: Production Ready | MCP Version: 2024-11-05\n\nOverview\n\nNeuroLink's Model Context Protocol (MCP) integration provides a universal plugin system that transforms the SDK from a simple AI interface into a complete AI development platform. With 6 built-in core tools and the ability to connect any community MCP server (58+ cataloged in the server directory), you can extend AI capabilities to interact with filesystems, databases, APIs, cloud services, and custom enterprise systems.\n\nWhat is MCP?\n\nThe Model Context Protocol is an open standard (like USB-C for AI) that enables AI models to securely interact with external tools and data sources through a unified interface. Think of it as:\nFor Developers: A standardized way to connect AI to any external system\nFor AI Models: A tool registry with discoverable, executable functions\nFor Enterprises: A controlled, auditable way to extend AI capabilities\n\nWhy MCP Matters\n\n| Traditional Approach                    | MCP Approach                      | Benefit                 |\n| --------------------------------------- | --------------------------------- | ----------------------- |\n| Custom tool integrations per provider   | One MCP tool works everywhere     | 10x faster integration  |\n| Manual tool discovery and configuration | Automatic tool registry           | Zero-config tool usage  |\n| Provider-specific tool formats          | Universal JSON-RPC protocol       | Provider portability    |\n| Limited to SDK-defined tools            | any community MCP server + custom | Unlimited extensibility |\n| Static tool set                         | Dynamic runtime addition          | Adapt to changing needs |\n\nNeuroLink's Deep MCP Integration\n\nFactory-First Architecture: MCP tools work internally while users see simple factory methods:\n\nKey Features:\n99% Lighthouse Compatible: Existing MCP tools work with minimal changes\nDynamic Server Management: Add/remove MCP servers programmatically\nRich Context: 15+ fields including session, user, permissions, metadata\nPerformance Optimized: 0-11ms tool execution (target: \\<100ms)\nEnterprise Grade: Comprehensive error handling, audit logging, security\n\nQuick Start\n\nBuilt-in Core Tools (6)\n\nNeuroLink ships with 6 essential tools that require zero configuration:\ngetCurrentTime\n\nPurpose: Real-time clock with timezone support\n\nAuto-Available: Yes (always enabled)\n\nUse Cases:\nTimestamp generation\nTimezone conversions\nScheduling and reminders\nTime-based calculations\n\nExample:\n\nTool Schema:\nreadFile\n\nPurpose: Read file contents from filesystem\n\nAuto-Available: Yes (with filesystem access)\n\nUse Cases:\nDocument analysis\nCode review\nConfiguration reading\nLog file processing\n\nExample:\n\nTool Schema:\nwriteFile\n\nPurpose: Write content to filesystem\n\nAuto-Available: Yes (with HITL approval recommended)\n\nUse Cases:\nGenerated content saving\nReport creation\nConfiguration updates\nCode generation output\n\nExample:\n\nTool Schema:\nlistDirectory\n\nPurpose: List files and directories\n\nAuto-Available: Yes (with filesystem access)\n\nUse Cases:\nProject structure analysis\nFile discovery\nDirectory traversal\nAsset inventory\n\nExample:\n\nTool Schema:\n\nFile tool roots\n\n, ,  and  only touch paths inside their roots. By default that is the process working directory. Configure other roots per instance, and narrow them per call:\nPrecedence: per-call , then instance , then the  environment variable (a -separated list;  on Windows). A per-call root outside the instance roots is rejected, so a server that forwards caller options cannot widen file access.\nResolution: each root must be an existing directory and is resolved through symlinks once, when the request starts. A missing root rejects the call before any model request.  denies all file access.\nContainment: target paths are resolved through symlinks too, and the prefix check is separator-bounded, so neither  nor a sibling such as  gets through. A symlink that does not resolve is refused, and writes never follow a symlink at the final path component. Relative paths resolve against the first root; a root of  contains every absolute path.\nWhere it applies: , , , , , the server's tool and MCP routes (which execute through the instance's tool registry), and worker instances (, isolated agents, delegates), which inherit the host's roots and can only narrow them. The resolved policy is internal: only  is settable per call.\nCLI: .\nBash: when the opt-in  tool is enabled, roots constrain only its  argument. The command itself runs with the full privileges of the process and can  anywhere. Use OS-level isolation (a container or a separate user) to sandbox shell commands.\ncalculateMath\n\nPurpose: Complex mathematical calculations\n\nAuto-Available: Yes (always enabled)\n\nUse Cases:\nFinancial calculations\nStatistical analysis\nUnit conversions\nScientific computations\n\nExample:\n\nTool Schema:\nwebsearchGrounding\n\nPurpose: Web search with result grounding\n\nAuto-Available: Only wi","hierarchy":{"lvl0":"Features","lvl1":"MCP Tools Ecosystem - Built-in Tools + Any MCP Server","lvl2":"","lvl3":""}},
 {"objectID":"d77f56e2563e08643ae18e7fea4540e640fdcdc7720690210a1b9c5c9a651cc2","title":"MCP Tools Ecosystem: Built-in Tools + Any MCP Server","url":"/docs/features/mcp-tools-showcase#mcp-tools-ecosystem-built-in-tools-any-mcp-server","content":"Since: v7.0.0 | Status: Production Ready | MCP Version: 2024-11-05","hierarchy":{"lvl0":"Features","lvl1":"MCP Tools Ecosystem - Built-in Tools + Any MCP Server","lvl2":"MCP Tools Ecosystem: Built-in Tools + Any MCP Server","lvl3":""}},
 {"objectID":"a2f242bd22bfb6fb857e7dc60825acc010064d863f53ef5ec236dbb81f1a6a88","title":"Overview","url":"/docs/features/mcp-tools-showcase#overview","content":"NeuroLink's Model Context Protocol (MCP) integration provides a universal plugin system that transforms the SDK from a simple AI interface into a complete AI development platform. With 6 built-in core tools and the ability to connect any community MCP server (58+ cataloged in the server directory), you can extend AI capabilities to interact with filesystems, databases, APIs, cloud services, and custom enterprise systems.","hierarchy":{"lvl0":"Features","lvl1":"MCP Tools Ecosystem - Built-in Tools + Any MCP Server","lvl2":"Overview","lvl3":""}},
 {"objectID":"6baec5fd689dfd70d9280b9efedecb44456fddef2a81d409f734d582aa0e856b","title":"What is MCP?","url":"/docs/features/mcp-tools-showcase#what-is-mcp","content":"The Model Context Protocol is an open standard (like USB-C for AI) that enables AI models to securely interact with external tools and data sources through a unified interface. Think of it as:\nFor Developers: A standardized way to connect AI to any external system\nFor AI Models: A tool registry with discoverable, executable functions\nFor Enterprises: A controlled, auditable way to extend AI capabilities","hierarchy":{"lvl0":"Features","lvl1":"MCP Tools Ecosystem - Built-in Tools + Any MCP Server","lvl2":"What is MCP?","lvl3":""}},
@@ -3752,6 +3752,7 @@
 {"objectID":"0415eee591ea3bb5e8bb01bdcea857d051be08a17783ada2a3f2f3e8c9abfbac","title":"2. readFile","url":"/docs/features/mcp-tools-showcase#2-readfile","content":"Purpose: Read file contents from filesystem\n\nAuto-Available: Yes (with filesystem access)\n\nUse Cases:\nDocument analysis\nCode review\nConfiguration reading\nLog file processing\n\nExample:\n\nTool Schema:","hierarchy":{"lvl0":"Features","lvl1":"MCP Tools Ecosystem - Built-in Tools + Any MCP Server","lvl2":"2. readFile","lvl3":""}},
 {"objectID":"0cb0c9165418d9251e667c3cc9ffab1dc09a25dbb4360b6317d3e4fe85bae458","title":"3. writeFile","url":"/docs/features/mcp-tools-showcase#3-writefile","content":"Purpose: Write content to filesystem\n\nAuto-Available: Yes (with HITL approval recommended)\n\nUse Cases:\nGenerated content saving\nReport creation\nConfiguration updates\nCode generation output\n\nExample:\n\nTool Schema:","hierarchy":{"lvl0":"Features","lvl1":"MCP Tools Ecosystem - Built-in Tools + Any MCP Server","lvl2":"3. writeFile","lvl3":""}},
 {"objectID":"c27259323275ac78a5c96f275cba4c67336b351f10d6a5990acd9ecb33c015f4","title":"4. listDirectory","url":"/docs/features/mcp-tools-showcase#4-listdirectory","content":"Purpose: List files and directories\n\nAuto-Available: Yes (with filesystem access)\n\nUse Cases:\nProject structure analysis\nFile discovery\nDirectory traversal\nAsset inventory\n\nExample:\n\nTool Schema:","hierarchy":{"lvl0":"Features","lvl1":"MCP Tools Ecosystem - Built-in Tools + Any MCP Server","lvl2":"4. listDirectory","lvl3":""}},
+{"objectID":"ea372be739ffab9dc37c0fce82830b21566da728269b630501d0755b353a2491","title":"File tool roots","url":"/docs/features/mcp-tools-showcase#file-tool-roots","content":", ,  and  only touch paths inside their roots. By default that is the process working directory. Configure other roots per instance, and narrow them per call:\nPrecedence: per-call , then instance , then the  environment variable (a -separated list;  on Windows). A per-call root outside the instance roots is rejected, so a server that forwards caller options cannot widen file access.\nResolution: each root must be an existing directory and is resolved through symlinks once, when the request starts. A missing root rejects the call before any model request.  denies all file access.\nContainment: target paths are resolved through symlinks too, and the prefix check is separator-bounded, so neither  nor a sibling such as  gets through. A symlink that does not resolve is refused, and writes never follow a symlink at the final path component. Relative paths resolve against the first root; a root of  contains every absolute path.\nWhere it applies: , , , , , the server's tool and MCP routes (which execute through the instance's tool registry), and worker instances (, isolated agents, delegates), which inherit the host's roots and can only narrow them. The resolved policy is internal: only  is settable per call.\nCLI: .\nBash: when the opt-in  tool is enabled, roots constrain only its  argument. The command itself runs with the full privileges of the process and can  anywhere. Use OS-level isolation (a container or a separate user) to sandbox shell commands.","hierarchy":{"lvl0":"Features","lvl1":"MCP Tools Ecosystem - Built-in Tools + Any MCP Server","lvl2":"File tool roots","lvl3":""}},
 {"objectID":"ad698242f08b12159d85a199152ed3aa7035bbde7fe3ba613977b8cf5371fbbd","title":"5. calculateMath","url":"/docs/features/mcp-tools-showcase#5-calculatemath","content":"Purpose: Complex mathematical calculations\n\nAuto-Available: Yes (always enabled)\n\nUse Cases:\nFinancial calculations\nStatistical analysis\nUnit conversions\nScientific computations\n\nExample:\n\nTool Schema:","hierarchy":{"lvl0":"Features","lvl1":"MCP Tools Ecosystem - Built-in Tools + Any MCP Server","lvl2":"5. calculateMath","lvl3":""}},
 {"objectID":"143629fbd9246f9f135dab71bb41068eb3b7a1007a086298e48eadd77f4782c2","title":"6. websearchGrounding","url":"/docs/features/mcp-tools-showcase#6-websearchgrounding","content":"Purpose: Web search with result grounding\n\nAuto-Available: Only with Google Vertex AI provider\n\nUse Cases:\nReal-time information lookup\nFact verification\nCurrent events\nResearch augmentation\n\nExample:\n\nTool Schema:\n\nNote: This tool is provider-specific (Google Vertex AI only) and leverages Google's grounding capabilities.","hierarchy":{"lvl0":"Features","lvl1":"MCP Tools Ecosystem - Built-in Tools + Any MCP Server","lvl2":"6. websearchGrounding","lvl3":""}},
 {"objectID":"34487d043deb9df5927b3f66758bf17d6e28e070682a3d99a5f16c9628829088","title":"External MCP Servers","url":"/docs/features/mcp-tools-showcase#external-mcp-servers","content":"NeuroLink connects to the growing MCP ecosystem — any MCP-compliant server works; the server catalog lists 58+ across 6 major categories.","hierarchy":{"lvl0":"Features","lvl1":"MCP Tools Ecosystem - Built-in Tools + Any MCP Server","lvl2":"External MCP Servers","lvl3":""}},
@@ -4369,12 +4370,12 @@
 {"objectID":"c2740a21a3ccb6ab1d0e7b30776071c132b69ae748354c256a62636ccdbe7c29","title":"Phase 2 — Vertex, Text, Tools, Client SDK","url":"/docs/features/speech-agents#phase-2-vertex-text-tools-client-sdk","content":"[ ] Implement Vertex Live API channel (WS) with / env support.\n[ ] Enable text delta events and downstream handling.\n[ ] Bridge Live API tool-calls to MCP; emit / events and roundtrip to provider.\n[ ] Add optional OpenTelemetry spans/metrics (connect/send/receive/flush/close).\n[ ] Create new package  (ESM, browser-first).\n[ ] Implement client WS bridge () and message codecs ().\n[ ] Define client SDK types and API (, , , events).\n[ ] Client SDK documentation and example integration.\n[ ] Optional: CLI helpers (e.g., ).","hierarchy":{"lvl0":"Features","lvl1":"Speech-to-Speech Agents: Architecture and Gemini Live Integration Plan","lvl2":"Phase 2 — Vertex, Text, Tools, Client SDK","lvl3":""}},
 {"objectID":"3215cc8c23511c1e9911b1fcda3172a99d5be62bb399c77f0ac8e150af152c90","title":"Phase 3 — Voice Catalog & Advanced Controls","url":"/docs/features/speech-agents#phase-3-voice-catalog-advanced-controls","content":"[ ] Implement  discovery and caching for Gemini Live.\n[ ] Support dynamic voice switching mid-session (where supported).\n[ ] Add advanced prosody/style/SSML-like parameters (provider-permitting).\n[ ] Add transcription/diarization toggles and corresponding events.\n[ ] Optional server/client helpers for WS/WebRTC patterns.","hierarchy":{"lvl0":"Features","lvl1":"Speech-to-Speech Agents: Architecture and Gemini Live Integration Plan","lvl2":"Phase 3 — Voice Catalog & Advanced Controls","lvl3":""}},
 {"objectID":"5ee15ed4fb755ea62d863ab193adce5b4944b98ec541f1edcf89bef3125bb6eb","title":"Open Questions for Review","url":"/docs/features/speech-agents#open-questions-for-review","content":"Minimum audio contract for upstream: we recommend PCM16LE 16 kHz mono; OK to lock this as a requirement for Phase 1?\nClient WS protocol: keep default JSON + base64 audio with opt-in binary? Any constraints from your infra?\nDo we want a tiny built-in WS helper (opt-in) in Phase 3 for servers, or keep strictly library-only on server side?\n\nIf this plan looks good, next step is to extend the  types and implement the Gemini Live (Studio) provider bridging for audio, keeping all server transport concerns outside the library as requested.","hierarchy":{"lvl0":"Features","lvl1":"Speech-to-Speech Agents: Architecture and Gemini Live Integration Plan","lvl2":"Open Questions for Review","lvl3":""}},
-{"objectID":"19e83803ff6836a63ca348bd039386eea2306841c20b8f6d76e7a62475e0a640","title":"Streaming Guide","url":"/docs/features/streaming","content":"Streaming Guide\n\nSince: v8.0.0 | Status: Stable | Availability: SDK + CLI\nProvider Defaults: When  (CLI) or  (SDK) is not specified, NeuroLink defaults to Vertex AI with gemini-2.5-flash. Set the  or  environment variable to change the default provider.\n\nOverview\n\nStreaming lets you receive AI-generated text incrementally -- token by token -- instead of waiting for the entire response. This is the same mechanism behind the \"typing\" effect you see in ChatGPT and other chat interfaces.\n\nWhy use streaming?\nFaster time-to-first-token -- Users see output within milliseconds rather than waiting seconds for a complete response.\nBetter UX -- Progressive rendering feels more interactive and responsive.\nLower memory footprint -- Process tokens as they arrive instead of buffering the full response.\nEarly cancellation -- Stop generation as soon as you have what you need.\n\nQuick Start\n\nThat is the simplest possible streaming call. The sections below cover every option in detail.\n\nSDK API\n\nThe  method accepts a  object and returns a .\n\nStreamOptions (Key Parameters)\n\n| Parameter      | Type                    | Required | Description                                                                   |\n| -------------- | ----------------------- | -------- | ----------------------------------------------------------------------------- |\n|         |  | Yes      | The prompt and optional multimodal inputs (images, PDFs, files, audio)        |\n|      |                 | No       | AI provider name (, , , , etc.) |\n|         |                 | No       | Specific model (, , )      |\n|   |                 | No       | Randomness (0.0 = deterministic, 2.0 = creative). Default varies by provider  |\n|     |                 | No       | Maximum tokens in the response                                                |\n|  |                 | No       | System message to control AI behavior                                         |\n|         |   | No       | Custom tools the model can invoke during generation                           |\n|           |              | No       | RAG configuration -- pass  for automatic retrieval          |\n|       |       | No       | Request timeout in milliseconds                                               |\n|   |            | No       | External cancellation signal                                                  |\n|      |                 | No       | Maximum tool execution steps (default: 5)                                     |\n|  |                | No       | Set  to disable all tool usage                                          |\n|           |             | No       | Enable text-to-speech audio alongside text                                    |\n\nObject\n\nThe  field is the only required parameter. At minimum it needs a  property:\n\nStreamResult\n\nCalling  returns a  object. The response itself arrives through the  async iterable, while metadata fields resolve once the stream completes.\n\n| Field            | Type                                      | Description                                                      |\n| ---------------- | ----------------------------------------- | ---------------------------------------------------------------- |\n|          |               | The async iterable you consume with                   |\n|        |                                   | Name of the provider that served the request                     |\n|           |                                   | Model that was used                                              |\n|           |                               | Token usage (prompt, completion, total)                          |\n|    |                                   | Why generation stopped (, , )    |\n|       |                               | Tool calls made during generation                                |\n|     |                             | Results from tool execution                                      |\n|  |                   | Detailed summary of all tool executions                          |\n|        |                                   | Stream metadata (streamId, startTime, totalChunks, responseTime) |\n|       |  | Usage analytics (when )                   |\n\nStream Chunks\n\nEach chunk yielded by  is a discriminated union:\n\nText Chunks\n\nThe most common chunk type. Contains a  string with the next piece of generated text.\n\nYou can also check the  discriminator:\n\nAudio Chunks (TTS)\n\nWhen TTS is enabled, the stream interleaves text and audio chunks:\n\nSee the TTS Guide for full audio streaming details.\n\nCollecting the Full Response\n\nIf you need the complete text after streaming finishes, accumulate chunks into a string:\n\nStreaming with Tools\n\nTools work transparently during streaming. The model calls tools mid-stream, receives results, and continues generating. You consume the stream exactly the same way -- tool execution happens behind the scenes.\n\nStreaming with RAG\n\nPass  to automatically index documents and give the model a search tool. The mode","hierarchy":{"lvl0":"Features","lvl1":"Streaming Guide","lvl2":"","lvl3":""}},
+{"objectID":"19e83803ff6836a63ca348bd039386eea2306841c20b8f6d76e7a62475e0a640","title":"Streaming Guide","url":"/docs/features/streaming","content":"Streaming Guide\n\nSince: v8.0.0 | Status: Stable | Availability: SDK + CLI\nProvider Defaults: When  (CLI) or  (SDK) is not specified, NeuroLink defaults to Vertex AI with gemini-2.5-flash. Set the  or  environment variable to change the default provider.\n\nOverview\n\nStreaming lets you receive AI-generated text incrementally -- token by token -- instead of waiting for the entire response. This is the same mechanism behind the \"typing\" effect you see in ChatGPT and other chat interfaces.\n\nWhy use streaming?\nFaster time-to-first-token -- Users see output within milliseconds rather than waiting seconds for a complete response.\nBetter UX -- Progressive rendering feels more interactive and responsive.\nLower memory footprint -- Process tokens as they arrive instead of buffering the full response.\nEarly cancellation -- Stop generation as soon as you have what you need.\n\nQuick Start\n\nThat is the simplest possible streaming call. The sections below cover every option in detail.\n\nSDK API\n\nThe  method accepts a  object and returns a .\n\nStreamOptions (Key Parameters)\n\n| Parameter      | Type                                 | Required | Description                                                                                                                                                                                     |\n| -------------- | ------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n|         |               | Yes      | The prompt and optional multimodal inputs (images, PDFs, files, audio)                                                                                                                          |\n|      |                              | No       | AI provider name (, , , , etc.)                                                                                                                   |\n|         |                              | No       | Specific model (, , )                                                                                                                        |\n|   |                              | No       | Randomness (0.0 = deterministic, 2.0 = creative). Default varies by provider                                                                                                                    |\n|     |                              | No       | Maximum tokens in the response                                                                                                                                                                  |\n|  |                              | No       | System message to control AI behavior                                                                                                                                                           |\n|     |  | No       | Prepend Neurolink's versioned terminal agent instructions to ;  applies the current version (), and the result reports . Same option on  |\n|         |                | No       | Custom tools the model can invoke during generation                                                                                                                                             |\n|           |                           | No       | RAG configuration -- pass  for automatic retrieval                                                                                                                            |\n|       |                    | No       | Request timeout in milliseconds                                                                                                                                                                 |\n|   |                         | No       | External cancellation signal                                                                                                                                                                    |\n|      |                              | No       | Maximum tool execution steps (default: 5)                                                                                                                                                       |\n|  |                             | No       | Set  to disable all tool usage                                                                                                                                                            |\n|           |                          | No       | Enable text-to-speech audio alongside text                                                                                                                                                      |\n\nObject\n\nThe  field is the only required parameter. At minimum it needs a  property:\n\nStreamResult\n\nCalling  returns a  object. The response itself arrives through the  async iterable, while metadata fields resolve once the st","hierarchy":{"lvl0":"Features","lvl1":"Streaming Guide","lvl2":"","lvl3":""}},
 {"objectID":"b6449793dde4c00a0689bea6c723ea12b1e13080c5fe2ce45f88b1c1fa020385","title":"Streaming Guide","url":"/docs/features/streaming#streaming-guide","content":"Since: v8.0.0 | Status: Stable | Availability: SDK + CLI\nProvider Defaults: When  (CLI) or  (SDK) is not specified, NeuroLink defaults to Vertex AI with gemini-2.5-flash. Set the  or  environment variable to change the default provider.","hierarchy":{"lvl0":"Features","lvl1":"Streaming Guide","lvl2":"Streaming Guide","lvl3":""}},
 {"objectID":"351ac8c102caa3cf9cd451e1bf64528362e996569b7a5b3e868cc237027c8a5a","title":"Overview","url":"/docs/features/streaming#overview","content":"Streaming lets you receive AI-generated text incrementally -- token by token -- instead of waiting for the entire response. This is the same mechanism behind the \"typing\" effect you see in ChatGPT and other chat interfaces.\n\nWhy use streaming?\nFaster time-to-first-token -- Users see output within milliseconds rather than waiting seconds for a complete response.\nBetter UX -- Progressive rendering feels more interactive and responsive.\nLower memory footprint -- Process tokens as they arrive instead of buffering the full response.\nEarly cancellation -- Stop generation as soon as you have what you need.","hierarchy":{"lvl0":"Features","lvl1":"Streaming Guide","lvl2":"Overview","lvl3":""}},
 {"objectID":"7eb63a7c019c46f041f5006529a7ec982af229d1badffea8acda9770c84d82ff","title":"Quick Start","url":"/docs/features/streaming#quick-start","content":"That is the simplest possible streaming call. The sections below cover every option in detail.","hierarchy":{"lvl0":"Features","lvl1":"Streaming Guide","lvl2":"Quick Start","lvl3":""}},
 {"objectID":"a42dc13482175d6518a9a63bb6562227fe3420f17d4d49a2250023cf21b6dcf8","title":"neurolink.stream(options): Promise<StreamResult>","url":"/docs/features/streaming#neurolinkstreamoptions-promisestreamresult","content":"The  method accepts a  object and returns a .","hierarchy":{"lvl0":"Features","lvl1":"Streaming Guide","lvl2":"neurolink.stream(options): Promise<StreamResult>","lvl3":""}},
-{"objectID":"bba0a6d877033db735b056acf8c3a154b8c71d42cdf40b555409ff6a31c7a5a5","title":"StreamOptions (Key Parameters)","url":"/docs/features/streaming#streamoptions-key-parameters","content":"| Parameter      | Type                    | Required | Description                                                                   |\n| -------------- | ----------------------- | -------- | ----------------------------------------------------------------------------- |\n|         |  | Yes      | The prompt and optional multimodal inputs (images, PDFs, files, audio)        |\n|      |                 | No       | AI provider name (, , , , etc.) |\n|         |                 | No       | Specific model (, , )      |\n|   |                 | No       | Randomness (0.0 = deterministic, 2.0 = creative). Default varies by provider  |\n|     |                 | No       | Maximum tokens in the response                                                |\n|  |                 | No       | System message to control AI behavior                                         |\n|         |   | No       | Custom tools the model can invoke during generation                           |\n|           |              | No       | RAG configuration -- pass  for automatic retrieval          |\n|       |       | No       | Request timeout in milliseconds                                               |\n|   |            | No       | External cancellation signal                                                  |\n|      |                 | No       | Maximum tool execution steps (default: 5)                                     |\n|  |                | No       | Set  to disable all tool usage                                          |\n|           |             | No       | Enable text-to-speech audio alongside text                                    |","hierarchy":{"lvl0":"Features","lvl1":"Streaming Guide","lvl2":"StreamOptions (Key Parameters)","lvl3":""}},
+{"objectID":"bba0a6d877033db735b056acf8c3a154b8c71d42cdf40b555409ff6a31c7a5a5","title":"StreamOptions (Key Parameters)","url":"/docs/features/streaming#streamoptions-key-parameters","content":"| Parameter      | Type                                 | Required | Description                                                                                                                                                                                     |\n| -------------- | ------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n|         |               | Yes      | The prompt and optional multimodal inputs (images, PDFs, files, audio)                                                                                                                          |\n|      |                              | No       | AI provider name (, , , , etc.)                                                                                                                   |\n|         |                              | No       | Specific model (, , )                                                                                                                        |\n|   |                              | No       | Randomness (0.0 = deterministic, 2.0 = creative). Default varies by provider                                                                                                                    |\n|     |                              | No       | Maximum tokens in the response                                                                                                                                                                  |\n|  |                              | No       | System message to control AI behavior                                                                                                                                                           |\n|     |  | No       | Prepend Neurolink's versioned terminal agent instructions to ;  applies the current version (), ","hierarchy":{"lvl0":"Features","lvl1":"Streaming Guide","lvl2":"StreamOptions (Key Parameters)","lvl3":""}},
 {"objectID":"1035996a9f834d2e38372eeba656da9ad2a3db9d4d87bd2be35eee2881b4e7c5","title":"input Object","url":"/docs/features/streaming#input-object","content":"The  field is the only required parameter. At minimum it needs a  property:","hierarchy":{"lvl0":"Features","lvl1":"Streaming Guide","lvl2":"input Object","lvl3":""}},
 {"objectID":"bd07a2ac1e22e7837b0e7ac93a2b984a1f2b2d1fc4c0edabe5c712fb26a991ea","title":"StreamResult","url":"/docs/features/streaming#streamresult","content":"Calling  returns a  object. The response itself arrives through the  async iterable, while metadata fields resolve once the stream completes.\n\n| Field            | Type                                      | Description                                                      |\n| ---------------- | ----------------------------------------- | ---------------------------------------------------------------- |\n|          |               | The async iterable you consume with                   |\n|        |                                   | Name of the provider that served the request                     |\n|           |                                   | Model that was used                                              |\n|           |                               | Token usage (prompt, completion, total)                          |\n|    |                                   | Why generation stopped (, , )    |\n|       |                               | Tool calls made during generation                                |\n|     |                             | Results from tool execution                                      |\n|  |                   | Detailed summary of all tool executions                          |\n|        |                                   | Stream metadata (streamId, startTime, totalChunks, responseTime) |\n|       |  | Usage analytics (when )                   |","hierarchy":{"lvl0":"Features","lvl1":"Streaming Guide","lvl2":"StreamResult","lvl3":""}},
 {"objectID":"1d5055fa64ccc86d1796d237e1756b86044f3d734049983ff20a1afeb74b5655","title":"Stream Chunks","url":"/docs/features/streaming#stream-chunks","content":"Each chunk yielded by  is a discriminated union:","hierarchy":{"lvl0":"Features","lvl1":"Streaming Guide","lvl2":"Stream Chunks","lvl3":""}},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "12.27.2",
+  "version": "12.28.0",
   "packageManager": "pnpm@10.15.1",
   "description": "The pipe layer of an AI nervous system: one interface connecting provider neurons to your application, across three inference types — generate, stream and decide. `decide` returns typed, calibrated judgements from a non-generative model (~400ms, ~$0.00002/call) for routing, tool selection and context budgeting. MCP-native (4 transports), voice TTS/STT/realtime, RAG, agents, memory, compaction, 9 observability exporters. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · TypeSafe Jev and more.",
   "author": {
@@ -141,6 +141,7 @@
     "test:rag": "pnpm exec tsx test/continuous-test-suite-rag.ts",
     "test:skills": "pnpm exec tsx test/continuous-test-suite-skills.ts",
     "test:decide": "pnpm exec tsx test/continuous-test-suite-decide.ts",
+    "test:agent-mode": "pnpm exec tsx test/continuous-test-suite-agent-mode.ts",
     "test:servers": "pnpm exec tsx test/continuous-test-suite-servers.ts",
     "test:tool-reliability": "pnpm exec tsx test/continuous-test-suite-tool-reliability.ts",
     "test:video-abort": "pnpm exec tsx test/continuous-test-suite-video-abort.ts",
@@ -263,8 +264,10 @@
     "test:docs-mcp": "pnpm exec tsx test/continuous-test-suite-docs-mcp.ts",
     "test:vertex-claude-characterization": "tsx test/continuous-test-suite-vertex-claude-characterization.ts",
     "test:toolfree-guard-overhead": "pnpm exec tsx test/continuous-test-suite-toolfree-guard-overhead.ts",
+    "test:file-tool-roots": "pnpm exec tsx test/continuous-test-suite-file-tool-roots.ts",
     "test:native-failure-events": "pnpm exec tsx test/continuous-test-suite-native-failure-events.ts",
-    "test:native-audio-model-aware": "pnpm exec tsx test/continuous-test-suite-native-audio-model-aware.ts"
+    "test:native-audio-model-aware": "pnpm exec tsx test/continuous-test-suite-native-audio-model-aware.ts",
+    "test:cli-json-output": "pnpm exec tsx test/continuous-test-suite-cli-json-output.ts"
   },
   "files": [
     "dist",