@juspay/neurolink 12.0.5 → 12.2.0

package/dist/types/tasks.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Task-checklist primitive (TodoWrite-style) — types.
+ *
+ * A long-running agent needs a durable, model-visible list of what this run
+ * must finish. The checklist lives on the SESSION, outside the message list,
+ * so summarization/compaction can rewrite the conversation without touching
+ * it, and every tool call returns the whole list so the model re-anchors for
+ * free after a compaction.
+ *
+ * Naming: the scheduler in `task.ts` already owns `Task`, `TaskStatus`,
+ * `TaskDefinition`, `TaskStore`, `TaskRunResult` and `TasksFile`, so every
+ * type here carries the `Checklist` prefix (Critical Rule 9).
+ */
+/** Lifecycle of one checklist item. `closed` means "not done, and here is why". */
+export type ChecklistItemStatus = "pending" | "in_progress" | "done" | "closed";
+export type ChecklistItem = {
+    /** "t1", "t2", … — assigned by the engine, never by the model. */
+    id: string;
+    title: string;
+    status: ChecklistItemStatus;
+    /** Result note, or the REASON an item was closed unfinished. */
+    note?: string;
+    createdAt: number;
+    updatedAt: number;
+};
+/** Everything one session's checklist holds. Never stored in messages. */
+export type ChecklistState = {
+    sessionId: string;
+    items: ChecklistItem[];
+    updatedAt: number;
+};
+export type ChecklistCreateInput = {
+    titles: string[];
+};
+export type ChecklistUpdateInput = {
+    id: string;
+    status: ChecklistItemStatus;
+    note?: string;
+};
+/**
+ * Background delegates outstanding for a session. Populated by the async
+ * delegation primitive; zero while that primitive is unused.
+ */
+export type ChecklistDelegateCounts = {
+    pending: number;
+    ready: number;
+};
+/** Supplies {@link ChecklistDelegateCounts} to every checklist tool result. */
+export type ChecklistDelegateCountsSource = (sessionId: string) => ChecklistDelegateCounts;
+/**
+ * Background commands outstanding for a session. Populated by the
+ * background-command primitive; zero while that primitive is unused.
+ */
+export type ChecklistCommandCounts = {
+    running: number;
+    finished: number;
+};
+/** Supplies {@link ChecklistCommandCounts} to every checklist tool result. */
+export type ChecklistCommandCountsSource = (sessionId: string) => ChecklistCommandCounts;
+/**
+ * Every `tasks_*` tool returns this — the model re-anchors on the full list
+ * on each call, which is what makes the checklist survive compaction with no
+ * re-injection machinery.
+ */
+export type ChecklistToolResult = {
+    items: ChecklistItem[];
+    counts: Record<ChecklistItemStatus, number>;
+    /** Background delegates not yet collected (0 when delegation is unused). */
+    delegatesPending: number;
+    delegatesReady: number;
+    /**
+     * Background commands still running (0 when the command primitive is
+     * unused). Carried here for the same reason the delegate counters are: the
+     * model learns "the build finished" from any `tasks_list`, with no polling
+     * and no change to the core loop.
+     */
+    commandsRunning: number;
+    /** Background commands that have settled and can be read. */
+    commandsFinished: number;
+};
+/** Refusal shape shared with the agent tool registrar: recovery text included. */
+export type ChecklistRefusal = {
+    isError: true;
+    error: string;
+};

package/dist/types/tasks.js

@@ -0,0 +1,14 @@
+/**
+ * Task-checklist primitive (TodoWrite-style) — types.
+ *
+ * A long-running agent needs a durable, model-visible list of what this run
+ * must finish. The checklist lives on the SESSION, outside the message list,
+ * so summarization/compaction can rewrite the conversation without touching
+ * it, and every tool call returns the whole list so the model re-anchors for
+ * free after a compaction.
+ *
+ * Naming: the scheduler in `task.ts` already owns `Task`, `TaskStatus`,
+ * `TaskDefinition`, `TaskStore`, `TaskRunResult` and `TasksFile`, so every
+ * type here carries the `Checklist` prefix (Critical Rule 9).
+ */
+export {};

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/modelChoices.js

@@ -2,7 +2,7 @@
  * Centralized model choices for CLI commands
  * Derives choices from model enums to ensure consistency
  */
-import { AIProviderName, OpenAIModels, AnthropicModels, GoogleAIModels, BedrockModels, VertexModels, MistralModels, OllamaModels, AzureOpenAIModels, LiteLLMModels, HuggingFaceModels, SageMakerModels, OpenRouterModels, DeepSeekModels, NvidiaNimModels, XaiModels, GroqModels, CohereModels, TogetherAIModels, FireworksModels, PerplexityModels, CloudflareModels, VoyageModels, JinaModels, StabilityModels, IdeogramModels, RecraftModels, ReplicateModels, } from "../constants/enums.js";
+import { AIProviderName, OpenAIModels, AnthropicModels, GoogleAIModels, BedrockModels, VertexModels, MistralModels, OllamaModels, AzureOpenAIModels, LiteLLMModels, HuggingFaceModels, SageMakerModels, OpenRouterModels, DeepSeekModels, NvidiaNimModels, XaiModels, GroqModels, CerebrasModels, CohereModels, TogetherAIModels, FireworksModels, PerplexityModels, CloudflareModels, VoyageModels, JinaModels, StabilityModels, IdeogramModels, RecraftModels, ReplicateModels, } from "../constants/enums.js";
 /**
  * Top models per provider with descriptions for CLI prompts
  * These are curated lists of the most commonly used/recommended models
@@ -302,6 +302,21 @@ const TOP_MODELS_CONFIG = {
             description: "Mistral 8x7B MoE, 32K context",
         },
     ],
+    [AIProviderName.CEREBRAS]: [
+        {
+            model: CerebrasModels.LLAMA_3_3_70B,
+            description: "Recommended - Production default; wafer-scale speed",
+        },
+        {
+            model: CerebrasModels.LLAMA_3_1_8B,
+            description: "Lowest latency tier",
+        },
+        { model: CerebrasModels.QWEN_3_32B, description: "Qwen 3 32B" },
+        {
+            model: CerebrasModels.GPT_OSS_120B,
+            description: "OpenAI GPT-OSS 120B (open-weight)",
+        },
+    ],
     [AIProviderName.COHERE]: [
         {
             model: CohereModels.COMMAND_R_PLUS,
@@ -539,6 +554,7 @@ const MODEL_ENUMS = {
     [AIProviderName.LLAMACPP]: null,
     [AIProviderName.XAI]: XaiModels,
     [AIProviderName.GROQ]: GroqModels,
+    [AIProviderName.CEREBRAS]: CerebrasModels,
     [AIProviderName.COHERE]: CohereModels,
     [AIProviderName.TOGETHER_AI]: TogetherAIModels,
     [AIProviderName.FIREWORKS]: FireworksModels,

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/dist/utils/providerConfig.d.ts

@@ -135,6 +135,10 @@ export declare function createNvidiaNimConfig(): ProviderConfigOptions;
  * Creates xAI Grok provider configuration.
  */
 export declare function createXaiConfig(): ProviderConfigOptions;
+/**
+ * Creates Cerebras provider configuration.
+ */
+export declare function createCerebrasConfig(): ProviderConfigOptions;
 /**
  * Creates Groq provider configuration.
  */

package/dist/utils/providerConfig.js

@@ -451,6 +451,23 @@ export function createXaiConfig() {
         ],
     };
 }
+/**
+ * Creates Cerebras provider configuration.
+ */
+export function createCerebrasConfig() {
+    return {
+        providerName: "Cerebras",
+        envVarName: "CEREBRAS_API_KEY",
+        setupUrl: "https://cloud.cerebras.ai",
+        description: "API key",
+        instructions: [
+            "1. Visit: https://cloud.cerebras.ai",
+            "2. Sign in or create a free Cerebras account",
+            "3. Create an API key under API Keys",
+            "4. Set CEREBRAS_API_KEY in your .env file",
+        ],
+    };
+}
 /**
  * Creates Groq provider configuration.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "12.0.5",
+  "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",