@juspay/neurolink 12.1.0 → 12.2.0

package/dist/neurolink.d.ts

@@ -6,7 +6,7 @@
  * Uses real MCP infrastructure for tool discovery and execution.
  */
 import type { AgentDefinition, AgentNetworkConfig, AgentRunOptions, AgentRunOutcome, AgentToolRegistrationOptions, IsolatedAgentDefinition, NetworkExecutionInput, NetworkExecutionOptions, NetworkExecutionResult, NetworkStreamChunk, WorkerInstanceOptions } from "./types/index.js";
-import type { CompactionConfig, CompactionResult, SpanData, ObservabilityConfig, MetricsSummary, MCPToolAnnotations, TraceView, AuthenticatedContext, AuthProvider, JsonObject, NeuroLinkEvents, TypedEventEmitter, MCPEnhancementsConfig, NeuroLinkAuthConfig, NeurolinkConstructorConfig, ChatMessage, ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPToolInfo, GenerateOptions, GenerateResult, ProviderStatus, TextGenerationOptions, TextGenerationResult, MCPExecutableTool, MCPServerInfo, MCPStatus, StreamOptions, StreamResult, ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions, BatchOperationResult, StreamGenerationEndContext, ToolRoutingServerDescriptor, ToolDedupConfig, ToolConfig, KnowledgeEngineStatus } from "./types/index.js";
+import type { CompactionConfig, CompactionResult, ArtifactStore, SpanData, ObservabilityConfig, MetricsSummary, MCPToolAnnotations, TraceView, AuthenticatedContext, AuthProvider, JsonObject, NeuroLinkEvents, TypedEventEmitter, MCPEnhancementsConfig, NeuroLinkAuthConfig, NeurolinkConstructorConfig, ChatMessage, ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPToolInfo, GenerateOptions, GenerateResult, ProviderStatus, TextGenerationOptions, TextGenerationResult, MCPExecutableTool, MCPServerInfo, MCPStatus, StreamOptions, StreamResult, ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions, BatchOperationResult, StreamGenerationEndContext, ToolRoutingServerDescriptor, ToolDedupConfig, ToolConfig, KnowledgeEngineStatus, ChecklistState, ArtifactPageRequest, BankArtifactOptions, BankedArtifactRef, DelegateCollectRequest, DelegateCollectResult, DelegateHandle, DelegateRegistrationOptions, DelegateSpawnOptions, BackgroundCommandHandle, BackgroundCommandOptions, BackgroundCommandOutputPage, BackgroundCommandPageRequest, BackgroundCommandPolicy, BackgroundCommandStatus, GitToolResult, GitToolsetOptions } from "./types/index.js";
 import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import type { RedisConversationMemoryManager } from "./core/redisConversationMemoryManager.js";
 import { ExternalServerManager } from "./mcp/externalServerManager.js";
@@ -191,6 +191,28 @@ export declare class NeuroLink {
      * tool — gates the per-turn delegation scope in generate().
      */
     private hasAgentTools;
+    /**
+     * Tools registered with `cacheable: false` — their results are never served
+     * from the tool-result cache. A tool whose answer depends on live state (a
+     * checklist, a work queue) would otherwise replay its first answer for the
+     * whole TTL to every caller passing the same arguments.
+     */
+    private readonly uncacheableTools;
+    /** Set once registerTaskTools() has registered the checklist toolset. */
+    private hasTaskChecklistTools;
+    /** Set once registerDelegationTools() has registered the delegation toolset. */
+    private hasBackgroundDelegationTools;
+    /** Set once registerBackgroundCommandTools() has registered the command toolset. */
+    private hasBackgroundCommandTools;
+    /** Set once registerGitTools() has registered the read-only git toolset. */
+    private hasGitTools;
+    /**
+     * Set once `retrieve_context` has been registered. The constructor skips
+     * registration when neither Redis nor an artifact store exists; banking can
+     * create a store later, and this keeps that second attempt from
+     * re-registering the tool on instances that already have it.
+     */
+    private retrieveContextRegistered;
     /**
      * Creates a new NeuroLink instance for AI text generation with MCP tool integration.
      *
@@ -285,11 +307,14 @@ export declare class NeuroLink {
      */
     private registerFileTools;
     /**
-     * Register task management tools bound to a TaskManager instance.
+     * Register SCHEDULER task tools bound to a TaskManager instance (task_create,
+     * task_list, … — scheduled/self-running jobs). Distinct from the agent task
+     * CHECKLIST (registerTaskTools() / tasks_create): different tools, different
+     * state, different purpose.
      * Follows the same factory + registry pattern as registerFileTools().
      * Called when TaskManager is created (eagerly or lazily via the `tasks` getter).
      */
-    private registerTaskTools;
+    private registerSchedulerTaskTools;
     /**
      * Register memory retrieval tools that allow the AI to access
      * conversation history, including full tool outputs.
@@ -2530,6 +2555,272 @@ export declare class NeuroLink {
     registerAgentTool(definition: IsolatedAgentDefinition, options?: AgentToolRegistrationOptions): Promise<{
         name: string;
     }>;
+    /**
+     * Register the task CHECKLIST toolset — `tasks_create`, `tasks_update`,
+     * `tasks_list` — on this instance (TodoWrite-style planning for a
+     * long-running run). Opt-in and idempotent: existing callers see no new
+     * tools until they ask for them.
+     *
+     * The checklist is session state, not conversation state: it lives outside
+     * the message list, so summarization/compaction cannot lose it, and every
+     * tool result returns the whole list so the model re-anchors for free after
+     * a compaction. Read the same state from host code with
+     * {@link getTaskState} — that is all a completeness gate needs.
+     *
+     * Sessions come from the tool execution context. Call
+     * `setToolContext({ sessionId })` (or run the agent through
+     * `runIsolatedAgent`, which stamps one) so the checklist has a stable
+     * identity; a model tool call with no session anywhere falls back to a
+     * single default checklist per instance rather than one per call. A DIRECT
+     * `executeTool("tasks_create", …)` call should pass
+     * `authContext: { sessionId }` — the tool registry otherwise mints a fresh
+     * id for that one call.
+     *
+     * @see {@link getTaskState} for the host-side read
+     */
+    registerTaskTools(): void;
+    /**
+     * Read a session's task checklist — synchronous, so a completeness gate is
+     * one line of host code:
+     * `getTaskState(id).items.filter(i => i.status === "pending")`.
+     *
+     * Never throws: an unknown session simply has an empty checklist. Omit
+     * `sessionId` to read the session the tools would currently write to (the
+     * instance's tool-context session, or its default checklist).
+     */
+    getTaskState(sessionId?: string): ChecklistState;
+    /**
+     * Drop a session's checklist. Returns whether there was one to drop.
+     * Omit `sessionId` to clear the session the tools currently write to.
+     */
+    clearTaskState(sessionId?: string): boolean;
+    /**
+     * Register the background-delegation toolset — `delegate_task` and
+     * `collect_results` — on this instance. Opt-in and idempotent: existing
+     * callers see no new tools until they ask for them.
+     *
+     * Delegation through {@link registerAgentTool} is synchronous — the loop
+     * blocks on each worker. These tools make it asynchronous: `delegate_task`
+     * returns a `workerId` at once and the agent keeps working, then
+     * `collect_results` claims whichever worker finished FIRST. Concurrency is
+     * bounded by the same process-wide pool `registerAgentTool` uses (raised,
+     * never lowered, by `maxConcurrent`), each worker's FULL report is banked to
+     * a file via {@link bankArtifact}, and the outstanding counts ride along in
+     * every `tasks_list` result so the agent learns a worker landed without
+     * polling.
+     *
+     * @param options - Depth ceiling, pool raise, and queue wait
+     * @see {@link spawnDelegate} for the host-side spawn
+     * @see {@link collectDelegates} for the host-side collect
+     */
+    registerDelegationTools(options?: DelegateRegistrationOptions): void;
+    /**
+     * Start a background worker and get its handle immediately — before it has
+     * run anything, and long before it finishes.
+     *
+     * The worker runs through {@link runIsolatedAgent}: a fresh session on a
+     * worker instance sharing THIS instance's tool registry (so live MCP
+     * connections are reused), waste detection, honest stop reasons. Its
+     * complete report is banked when it settles; the outcome you collect carries
+     * a bounded summary plus the read-back call for the rest.
+     *
+     * @example
+     * ```typescript
+     * const a = await neurolink.spawnDelegate({ task: "Audit the auth changes" });
+     * const b = await neurolink.spawnDelegate({ task: "Review the migrations" });
+     * // …keep working…
+     * const first = await neurolink.collectDelegates({ mode: "any" });
+     * ```
+     *
+     * @param options - Task, scope, context, tool allowlist, budgets
+     * @returns The worker id, spawn time, and whether it is queued for a slot
+     * @throws when the task is empty or the caller is at the depth ceiling
+     */
+    spawnDelegate(options: DelegateSpawnOptions): Promise<DelegateHandle>;
+    /**
+     * Claim finished background workers — in COMPLETION order, which has nothing
+     * to do with spawn order. Each outcome is handed out exactly once.
+     *
+     * @param request - `{ mode: "any" | "all" }` or `{ workerId }`, plus `waitMs`
+     * @returns Claimed outcomes plus what is still pending/ready
+     */
+    collectDelegates(request: DelegateCollectRequest): Promise<DelegateCollectResult>;
+    /**
+     * Cancel background workers: one by id, or every outstanding worker this
+     * instance spawned. Cancelled workers still settle into a claimable outcome
+     * saying so.
+     *
+     * @param workerId - Cancel just this worker; omit to cancel all
+     * @returns How many workers were cancelled
+     */
+    cancelDelegates(workerId?: string): Promise<number>;
+    /**
+     * This instance's artifact store, created on first use.
+     *
+     * Until now a store existed only when `mcp.outputLimits.strategy` was set to
+     * `"externalize"`, so a caller that just wanted to bank a worker report had
+     * to configure MCP output limits it did not use. This creates one on demand
+     * and registers `retrieve_context` alongside it, so a banked payload is
+     * readable by the model, not only by host code.
+     *
+     * Already-configured instances get the store they already had — the MCP
+     * output normalizer and banking deliberately share one store, so an
+     * externalized tool output and a banked report read back the same way.
+     *
+     * @returns The artifact store backing {@link bankArtifact} / {@link readArtifact}
+     */
+    getArtifactStore(): ArtifactStore;
+    /**
+     * Bank a payload to a file and get back a pointer to it.
+     *
+     * The payload is stored WHOLE. What you put in the conversation is the
+     * returned `preview` (a bounded head slice) and `readBackHint` (the literal
+     * `retrieve_context` call that fetches the rest) — so a 4 MB worker report
+     * costs a few hundred tokens of context and loses nothing, and compaction
+     * can drop the preview without destroying evidence.
+     *
+     * @example
+     * ```typescript
+     * const ref = await neurolink.bankArtifact(fullReport, {
+     *   kind: "worker-report",
+     *   label: "delegate:auth-review",
+     *   sessionId: "review-1421",
+     * });
+     * // Hand the model ref.preview + ref.readBackHint, never fullReport.
+     * ```
+     *
+     * @param payload  Complete text or JSON. Never truncated.
+     * @param options  `kind` and `label` are required; see {@link BankArtifactOptions}
+     * @returns Id, bounded preview, byte size, and the read-back call
+     */
+    bankArtifact(payload: string, options: BankArtifactOptions): Promise<BankedArtifactRef>;
+    /**
+     * Read a banked payload back from host code — the programmatic twin of the
+     * model's `retrieve_context({ artifactId })` call.
+     *
+     * Omit `page` for the complete payload; pass `{ offset, limit }` to walk a
+     * large one in windows. Returns null when the id is unknown or expired.
+     *
+     * @param id    `artifactId` from a {@link BankedArtifactRef}
+     * @param page  Optional character window
+     */
+    readArtifact(id: string, page?: ArtifactPageRequest): Promise<string | null>;
+    /**
+     * Register the background-command toolset — `run_command_bg`,
+     * `command_status`, `command_output`, `command_kill` — on this instance, and
+     * declare what may be executed. Opt-in and idempotent: existing callers see
+     * no new tools until they ask for them.
+     *
+     * A reviewing agent needs to run real commands — a build, a test suite, a
+     * linter whose output is the evidence for a finding — without blocking its
+     * own loop and without losing a byte of what they printed. These tools start
+     * a command detached, write both streams to files as they arrive, and bank
+     * the COMPLETE files as artifacts when the command settles; the conversation
+     * gets a bounded tail plus the read-back call.
+     *
+     * The policy is not optional. `allowedExecutables` is matched exactly
+     * against `argv[0]`, `cwdRoot` is a realpath-checked sandbox, there is never
+     * a shell, and a command that outlives `defaultTimeoutMs` is killed.
+     *
+     * @param policy - What may run, where, for how long, and how loudly
+     * @see {@link startBackgroundCommand} for the host-side start
+     * @see {@link registerGitTools} for read-only git without a general policy
+     */
+    registerBackgroundCommandTools(policy: BackgroundCommandPolicy): void;
+    /**
+     * Declare (or replace) what this instance may execute, without registering
+     * the model-facing tools. Host code that only drives
+     * {@link startBackgroundCommand} itself needs nothing more than this.
+     *
+     * @param policy - What may run, where, for how long, and how loudly
+     */
+    setBackgroundCommandPolicy(policy: BackgroundCommandPolicy): void;
+    /**
+     * Start a command in the background and get its task id immediately.
+     *
+     * @example
+     * ```typescript
+     * const { taskId } = await neurolink.startBackgroundCommand(
+     *   ["pnpm", "run", "lint"],
+     *   { cwd: repoRoot },
+     * );
+     * // …keep working…
+     * const status = await neurolink.awaitBackgroundCommand(taskId);
+     * const full = await neurolink.readArtifact(status.stdout!.artifactId);
+     * ```
+     *
+     * @param argv - Executable first, one entry per argument. Never a command string.
+     * @param options - cwd (sandboxed), timeout, byte cap, env, label, session
+     * @returns The task id, the argv that ran, and when it started
+     * @throws when no policy is set, argv is malformed, the executable is not
+     *         allowlisted, the policy vetoes it, or the cwd escapes the sandbox
+     */
+    startBackgroundCommand(argv: string[], options: BackgroundCommandOptions): Promise<BackgroundCommandHandle>;
+    /**
+     * Everything known about one command right now — synchronous, so a
+     * mid-loop monitor costs nothing.
+     *
+     * @param taskId - Task id from {@link startBackgroundCommand}
+     * @throws when the task id is unknown to this instance
+     */
+    getBackgroundCommandStatus(taskId: string): BackgroundCommandStatus;
+    /**
+     * Wait for a command to settle. `timeoutMs` bounds the WAIT, not the
+     * command: when it elapses the current status is returned rather than
+     * thrown, so a caller can poll in bounded steps and never lose the job.
+     *
+     * @param taskId - Task id from {@link startBackgroundCommand}
+     * @param opts - `timeoutMs` to bound the wait
+     */
+    awaitBackgroundCommand(taskId: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<BackgroundCommandStatus>;
+    /**
+     * Kill a running command — SIGTERM, then SIGKILL five seconds later — and
+     * resolve with its settled status. Whatever it printed first is still
+     * banked: killing a command discards the process, never its output.
+     *
+     * @param taskId - Task id from {@link startBackgroundCommand}
+     * @param signal - Signal to send first. Default SIGTERM
+     */
+    killBackgroundCommand(taskId: string, signal?: NodeJS.Signals): Promise<BackgroundCommandStatus>;
+    /**
+     * Read one character window of a command's output straight from its log
+     * file — while it is still running, or long after it finished. Offsets,
+     * `totalSize` and `hasMore` match `retrieve_context` exactly.
+     *
+     * @param taskId - Task id from {@link startBackgroundCommand}
+     * @param page - Which stream, and which window of it
+     */
+    readBackgroundCommandOutput(taskId: string, page: BackgroundCommandPageRequest): Promise<BackgroundCommandOutputPage>;
+    /**
+     * Register the read-only git toolset — `git_log`, `git_show`, `git_diff`,
+     * `git_blame`, `git_merge_base`, `git_ls_files` — on this instance. Opt-in
+     * and idempotent.
+     *
+     * These are BOUNDED tools, not a shell: the model supplies values (a ref, a
+     * path, a line range), never flags, and each tool assembles a fixed argv
+     * from them. That is what keeps them read-only — a free-form argument string
+     * would carry `--output=<file>` and `diff.external` straight through.
+     *
+     * Registering them widens nothing else: they run under a private
+     * one-executable policy rooted at `repoRoot`, so `run_command_bg` still
+     * cannot execute git, and no general command policy is required.
+     *
+     * @param options - Repository root, plus timeout / byte-cap / preview bounds
+     */
+    registerGitTools(options: GitToolsetOptions): void;
+    /**
+     * Run one read-only git command from host code, with the same bounding the
+     * tools get: the complete stdout is banked, the result carries a preview and
+     * the read-back call.
+     *
+     * @param args - Git arguments, e.g. `["log", "--oneline"]`. Assembled by the
+     *               caller, which is responsible for every value in them
+     * @param sessionId - Session the command belongs to
+     * @throws when {@link registerGitTools} has not been called
+     */
+    runGitCommand(args: string[], sessionId?: string): Promise<GitToolResult>;
     /**
      * Execute an agent network with the given input.
      *