@juspay/neurolink 12.1.0 → 12.2.0

package/dist/types/tools.d.ts

@@ -153,6 +153,17 @@ export type ToolRegistrationOptions = {
      *  When omitted, the SDK's global default (2 retries) is used.
      *  Set to 0 to disable retries for this tool. */
     maxRetries?: number;
+    /**
+     * Whether this tool's result may be served from the tool-result cache
+     * (default true).
+     *
+     * Set to `false` for a tool whose result is NOT a function of its arguments
+     * — anything reading or mutating live state. The cache is keyed by tool name
+     * plus arguments, so a stateful tool called twice with the same arguments
+     * replays its first answer for the whole TTL: a checklist that never updates,
+     * a queue that hands out the same item twice.
+     */
+    cacheable?: boolean;
 };
 /**
  * Tool execution result

package/dist/utils/pathSandbox.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ *
+ * The load-bearing detail is **realpath**. A string comparison on resolved
+ * paths is defeated by a symlink: `<root>/escape → /etc` resolves lexically to
+ * `<root>/escape`, which passes, and then the command runs in `/etc`. Both
+ * sides are therefore resolved through the filesystem before they are
+ * compared, and a target that cannot be resolved is refused rather than
+ * assumed innocent.
+ *
+ * The `+ sep` suffix on the prefix test is the other one: without it
+ * `/home/app-evil` passes a containment check against `/home/app`.
+ *
+ * @module utils/pathSandbox
+ */
+import type { PathSandboxResult } from "../types/index.js";
+/**
+ * Resolve `target` and confirm it is `root` or lies inside it, with symlinks
+ * followed on both sides.
+ *
+ * Both must exist and be directories — a containment check on a path that is
+ * not there yet cannot be honest, because whatever appears later may be a
+ * symlink out.
+ *
+ * @param target Directory to check. Relative paths resolve against `root`.
+ * @param root   Sandbox root the target must not escape.
+ * @returns The resolved REAL path, or the reason it was refused.
+ */
+export declare function resolveWithinRoot(target: string, root: string): PathSandboxResult;
+/**
+ * The file twin of {@link resolveWithinRoot}: contain a path that may name a
+ * file, or may not exist at all (a path argument to `git log`, say).
+ *
+ * A path that exists is resolved through its symlinks and checked directly. A
+ * path that does not exist is checked on its nearest EXISTING ancestor, which
+ * is the deepest point a symlink could redirect — everything below that is a
+ * name, not a link. Deleted files therefore stay askable about, and
+ * `../../etc/passwd` still does not.
+ *
+ * @param target Path to check. Relative paths resolve against `root`.
+ * @param root   Sandbox root the target must not escape.
+ * @returns The resolved absolute path, or the reason it was refused.
+ */
+export declare function resolvePathWithinRoot(target: string, root: string): PathSandboxResult;

package/dist/utils/pathSandbox.js

@@ -0,0 +1,127 @@
+/**
+ * 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.
+ *
+ * The load-bearing detail is **realpath**. A string comparison on resolved
+ * paths is defeated by a symlink: `<root>/escape → /etc` resolves lexically to
+ * `<root>/escape`, which passes, and then the command runs in `/etc`. Both
+ * sides are therefore resolved through the filesystem before they are
+ * compared, and a target that cannot be resolved is refused rather than
+ * assumed innocent.
+ *
+ * The `+ sep` suffix on the prefix test is the other one: without it
+ * `/home/app-evil` passes a containment check against `/home/app`.
+ *
+ * @module utils/pathSandbox
+ */
+import { 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) {
+    try {
+        const real = realpathSync(candidate);
+        return statSync(real).isDirectory() ? real : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Real path of anything that exists — file, directory or otherwise. */
+function realEntry(candidate) {
+    try {
+        return realpathSync(candidate);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isInside(candidate, root) {
+    return candidate === root || candidate.startsWith(root + sep);
+}
+/**
+ * Resolve `target` and confirm it is `root` or lies inside it, with symlinks
+ * followed on both sides.
+ *
+ * Both must exist and be directories — a containment check on a path that is
+ * not there yet cannot be honest, because whatever appears later may be a
+ * symlink out.
+ *
+ * @param target Directory to check. Relative paths resolve against `root`.
+ * @param root   Sandbox root the target must not escape.
+ * @returns The resolved REAL path, or the reason it was refused.
+ */
+export function resolveWithinRoot(target, root) {
+    const realRoot = realDirectory(resolve(root));
+    if (!realRoot) {
+        return {
+            error: `Sandbox root "${root}" is not an existing directory. Point the policy's ` +
+                "cwdRoot at a directory that exists before starting commands.",
+        };
+    }
+    const requested = isAbsolute(target) ? target : resolve(realRoot, target);
+    const realTarget = realDirectory(requested);
+    if (!realTarget) {
+        return {
+            error: `Working directory "${target}" is not an existing directory. Name a directory ` +
+                `that exists inside ${realRoot}.`,
+        };
+    }
+    if (!isInside(realTarget, realRoot)) {
+        return {
+            error: `Access denied: "${target}" resolves to ${realTarget}, which is outside the ` +
+                `permitted root ${realRoot}. Run the command inside that root instead.`,
+        };
+    }
+    return { path: realTarget };
+}
+/**
+ * The file twin of {@link resolveWithinRoot}: contain a path that may name a
+ * file, or may not exist at all (a path argument to `git log`, say).
+ *
+ * A path that exists is resolved through its symlinks and checked directly. A
+ * path that does not exist is checked on its nearest EXISTING ancestor, which
+ * is the deepest point a symlink could redirect — everything below that is a
+ * name, not a link. Deleted files therefore stay askable about, and
+ * `../../etc/passwd` still does not.
+ *
+ * @param target Path to check. Relative paths resolve against `root`.
+ * @param root   Sandbox root the target must not escape.
+ * @returns The resolved absolute path, or the reason it was refused.
+ */
+export function resolvePathWithinRoot(target, root) {
+    const realRoot = realDirectory(resolve(root));
+    if (!realRoot) {
+        return { error: `Sandbox root "${root}" is not an existing directory.` };
+    }
+    const denied = {
+        error: `Access denied: "${target}" resolves outside the permitted root ${realRoot}. ` +
+            "Name a path inside it, relative to the root.",
+    };
+    const requested = isAbsolute(target)
+        ? resolve(target)
+        : resolve(realRoot, target);
+    const direct = realEntry(requested);
+    if (direct) {
+        return isInside(direct, realRoot) ? { path: direct } : denied;
+    }
+    let existing = resolve(requested, "..");
+    let suffix = basename(requested);
+    for (;;) {
+        const real = realDirectory(existing);
+        if (real) {
+            return isInside(real, realRoot)
+                ? { path: resolve(real, suffix) }
+                : denied;
+        }
+        const parent = resolve(existing, "..");
+        if (parent === existing) {
+            return denied;
+        }
+        suffix = join(basename(existing), suffix);
+        existing = parent;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "12.1.0",
+  "version": "12.2.0",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {
@@ -69,6 +69,10 @@
     "convert:specific": "tsx tools/automation/shellConverter.ts --specific",
     "// Testing (Continuous Test Suites)": "",
     "test": "pnpm exec tsx test/continuous-test-suite.ts",
+    "test:agent-delegation": "pnpm exec tsx test/continuous-test-suite-agent-delegation.ts",
+    "test:agent-tasks": "pnpm exec tsx test/continuous-test-suite-agent-tasks.ts",
+    "test:artifact-banking": "pnpm exec tsx test/continuous-test-suite-artifact-banking.ts",
+    "test:background-commands": "pnpm exec tsx test/continuous-test-suite-background-commands.ts",
     "test:client": "pnpm exec tsx test/continuous-test-suite-client.ts",
     "test:context": "pnpm exec tsx test/continuous-test-suite-context.ts",
     "test:evaluation": "pnpm exec tsx test/continuous-test-suite-evaluation.ts",