@juspay/neurolink 13.8.17 → 13.8.19

package/dist/types/config.d.ts

@@ -206,6 +206,15 @@ export type NeurolinkConstructorConfig = {
      * See {@link MiddlewareFactoryOptions}.
      */
     middleware?: MiddlewareFactoryOptions;
+    /**
+     * What this instance may read or fetch when a call names a file path or URL
+     * (`input.files`, `input.images`, `rag.files`, `transcribe({ audio })`,
+     * Director Mode segment images). Unset: URLs must be HTTPS to a public host
+     * (redirects re-checked per hop), local paths are unrestricted but warn once.
+     * Set `allowedRoots` whenever the strings come from untrusted callers. See
+     * {@link AttachmentsConfig}.
+     */
+    attachments?: AttachmentsConfig;
 };
 /**
  * Configuration for MCP enhancement modules wired into generate()/stream() paths.
@@ -219,6 +228,20 @@ export type NeurolinkConstructorConfig = {
  * - middleware: Global tool execution middleware chain (empty by default)
  */
 export type MCPEnhancementsConfig = {
+    /**
+     * Explicit path of a project MCP configuration (`.mcp-config.json` shape)
+     * to load when MCP initialises. Relative paths resolve against the
+     * working directory. This is the SDK's only way to load a project file:
+     * the working directory is never searched implicitly, because a directory
+     * is not a trust boundary — a cloned repository's `.mcp-config.json`
+     * would otherwise run its servers with your credentials.
+     */
+    configPath?: string;
+    /**
+     * Load `<cwd>/.mcp-config.json` without naming it. Set this only when the
+     * working directory is one you control. Default: false.
+     */
+    trustProjectConfig?: boolean;
     /** Tool result caching. Default: enabled. Set enabled: false to opt out. */
     cache?: {
         enabled?: boolean;
@@ -556,6 +579,7 @@ export declare const DEFAULT_CONFIG: NeuroLinkConfig;
 import { TOOL_TIMEOUTS, BACKOFF_CONFIG, PERFORMANCE_PROFILES, PROVIDER_OPERATION_CONFIGS, MCP_OPERATION_CONFIGS } from "../constants/index.js";
 import type { ToolMiddleware, CacheStrategy, RoutingStrategy, ToolDedupConfig, ToolRoutingConfig } from "./index.js";
 import type { ModelAliasConfig } from "./generate.js";
+import type { AttachmentsConfig } from "./attachments.js";
 /** Timeout category keys from TOOL_TIMEOUTS. */
 export type TimeoutCategory = keyof typeof TOOL_TIMEOUTS;
 /** Retry strategy keys from BACKOFF_CONFIG. */
@@ -619,3 +643,35 @@ export type NativeThinkingConfig = {
     thinkingLevel?: ThinkingLevel;
     thinkingBudget?: number;
 };
+export type DotenvBootstrapOptions = {
+    /**
+     * Who is loading. The CLI prints its notices to stderr; an SDK caller
+     * (opted in with `NEUROLINK_DOTENV=1` or by calling `loadDotenv()`) gets
+     * the same notices through `notify`, which defaults to stderr as well.
+     */
+    caller?: "cli" | "sdk";
+    /** Receives one human-readable line per notice. Default: `process.stderr`. */
+    notify?: (line: string) => void;
+};
+export type DotenvBootstrapResult = {
+    /** Whether a `.env` file was read. */
+    loaded: boolean;
+    /** Absolute path of the file that was (or would have been) read. */
+    path?: string;
+    /** Variables the file supplied that were absent from the environment. */
+    supplied: string[];
+    /**
+     * The subset of `supplied` that redirects traffic or file access: provider
+     * `*_BASE_URL` / `*_ENDPOINT(S)` variables, `NEUROLINK_*_DIR` directories
+     * and `DOTENV_CONFIG_PATH`. Still set unless listed under `refused`.
+     */
+    endpointOverrides: string[];
+    /**
+     * Endpoint overrides deleted again because the file is not owned by the
+     * current user or is group/world-writable. Export them in the shell to use
+     * them.
+     */
+    refused: string[];
+    /** Why loading was skipped or overrides were refused, when either happened. */
+    reason?: string;
+};

package/dist/types/file.d.ts

@@ -2,6 +2,7 @@
  * File detection and processing types for unified file handling
  */
 import type { ImageWithAltText } from "./multimodal.js";
+import type { AttachmentPolicy } from "./attachments.js";
 /**
  * Supported file types for multimodal input
  */
@@ -724,6 +725,13 @@ export type FileDetectorOptions = {
      * filesystem access; SDK callers loading their own files can omit it.
      */
     allowedBaseDir?: string;
+    /**
+     * Instance attachment policy: `allowedRoots` containment (when
+     * `allowedBaseDir` is not set), the URL rules (HTTPS-only, public hosts,
+     * re-validated redirects) and the global size cap. The environment-derived
+     * default applies when absent.
+     */
+    attachmentPolicy?: AttachmentPolicy;
     audioOptions?: AudioProcessorOptions;
     csvOptions?: CSVProcessorOptions;
     officeOptions?: OfficeProcessorOptions;

package/dist/types/hitl.d.ts

@@ -28,6 +28,14 @@ export type HITLConfig = {
     auditLogging?: boolean;
     /** Advanced custom rules for complex tool scenarios (default: []) */
     customRules?: HITLRule[];
+    /**
+     * Whether the built-in tools that change the machine — `writeFile` and the
+     * opt-in `executeBashCommand` — always require confirmation while HITL is
+     * enabled, whatever `dangerousActions` says (default: true). Set to `false`
+     * to gate built-in tools by `dangerousActions` keywords and `customRules`
+     * only, as every other tool is.
+     */
+    confirmBuiltinTools?: boolean;
 };
 /**
  * Custom rule for advanced HITL scenarios

package/dist/types/index.d.ts

@@ -8,6 +8,7 @@ export * from "./agentMode.js";
 export * from "./aliases.js";
 export * from "./analytics.js";
 export * from "./artifact.js";
+export * from "./attachments.js";
 export * from "./auth.js";
 export * from "./autoresearch.js";
 export * from "./circuitBreakerErrors.js";

package/dist/types/index.js

@@ -9,6 +9,7 @@ export * from "./agentMode.js";
 export * from "./aliases.js";
 export * from "./analytics.js";
 export * from "./artifact.js";
+export * from "./attachments.js";
 export * from "./auth.js";
 export * from "./autoresearch.js";
 export * from "./circuitBreakerErrors.js";

package/dist/types/mcp.d.ts

@@ -69,6 +69,24 @@ export type MCPServerInfo = {
     cwd?: string;
     autoRestart?: boolean;
     healthCheckInterval?: number;
+    /**
+     * stdio only. By default a spawned server receives the MCP SDK's minimal
+     * default environment (`HOME`, `PATH`, `SHELL`, `TERM`, `USER`, `LOGNAME`
+     * on POSIX) plus `env`; the parent's provider keys and tokens are not
+     * inherited. Set `true` to restore the previous behaviour of handing the
+     * server the whole parent `process.env`. Prefer explicit pass-through:
+     * `"env": { "OPENAI_API_KEY": "${OPENAI_API_KEY}" }`.
+     */
+    inheritParentEnv?: boolean;
+    /**
+     * http / sse / websocket only. A transport URL must use `https:` or `wss:`
+     * unless its host is loopback, and its host must not resolve to a private,
+     * link-local, CGNAT or cloud-metadata address. Set `true` for a server on
+     * your own network: plaintext `http:` / `ws:` is then accepted for hosts
+     * that are (or resolve only to) private addresses. Public hosts still need
+     * TLS.
+     */
+    allowPrivateNetwork?: boolean;
     /**
      * Minimum number of tools that must be discovered for this server's
      * registration to be considered ready (default: 0 — no minimum, so a
@@ -2268,3 +2286,83 @@ export type OptimizeParametersParams = {
     optimizeFor: "speed" | "quality" | "cost" | "tokens";
     iterations: number;
 };
+/** One recorded acceptance of a project `.mcp-config.json`. */
+export type ProjectMcpConfigTrustEntry = {
+    /** Lower-case hex SHA-256 of the file's bytes when it was accepted. */
+    sha256: string;
+    /** ISO-8601 timestamp of the acceptance. */
+    trustedAt: string;
+};
+/**
+ * On-disk shape of `~/.neurolink/trusted-mcp-configs.json`: absolute config
+ * path → the hash the user accepted. A changed file no longer matches and
+ * has to be accepted again.
+ */
+export type ProjectMcpConfigTrustStore = {
+    version: 1;
+    entries: Record<string, ProjectMcpConfigTrustEntry>;
+};
+/**
+ * What a project config would do, reduced to what a human needs to see
+ * before trusting it. Header and `env` values are deliberately absent: only
+ * the `env` key names are listed, so a summary never echoes a secret.
+ */
+export type ProjectMcpConfigServerSummary = {
+    id: string;
+    transport: string;
+    command?: string;
+    args?: string[];
+    url?: string;
+    envKeys?: string[];
+};
+export type ProjectMcpConfigSummary = {
+    /** Absolute path of the config file. */
+    path: string;
+    /** Lower-case hex SHA-256 of the file's bytes. */
+    sha256: string;
+    servers: ProjectMcpConfigServerSummary[];
+    /** Set when the file is not valid JSON or has no `mcpServers` object. */
+    parseError?: string;
+};
+/**
+ * `trusted`: the store holds this path with this hash. `changed`: the store
+ * holds this path with a different hash. `untrusted`: never accepted.
+ */
+export type ProjectMcpConfigTrustStatus = "trusted" | "changed" | "untrusted";
+/**
+ * Which rule let a project config be loaded. `configPath` and
+ * `trustProjectConfig` come from the `NeuroLink` constructor's `mcp` option;
+ * `cliTrust` is the CLI's hash-pinned acceptance; `enableManualMCP` is the
+ * `ProviderRegistry` option a host set after construction.
+ */
+export type ProjectMcpConfigSource = "configPath" | "trustProjectConfig" | "cliTrust" | "enableManualMCP";
+export type ProjectMcpConfigPathResolution = {
+    path: string;
+    source: ProjectMcpConfigSource;
+};
+/**
+ * Registered by the CLI entry point once it has decided what to do about the
+ * working directory's `.mcp-config.json`. Called with the candidate path the
+ * moment a `NeuroLink` instance would load it; returns the path to load or
+ * `null` to load nothing. A hook may also end the process (the CLI's
+ * non-interactive refusal does), which is why it is asynchronous.
+ */
+export type ProjectMcpConfigTrustHook = (candidatePath: string) => Promise<string | null>;
+/** Options for the MCP transport URL policy (`assertMcpTransportUrlAllowed`). */
+export type McpTransportUrlPolicyOptions = {
+    transport: MCPTransportType;
+    /** See {@link MCPServerInfo.allowPrivateNetwork}. */
+    allowPrivateNetwork?: boolean;
+    /**
+     * The host application supplied its own `fetch` (or dispatcher) for this
+     * server, so egress — which addresses are dialled, with which pins — is
+     * decided by that code, not by this policy. Only program code can pass a
+     * function; a config file never can. The scheme allow-list still applies;
+     * the plaintext and address classification is skipped.
+     */
+    hostOwnedEgress?: boolean;
+    /** Used only to name the server in error messages. */
+    serverId?: string;
+};
+/** How an address is classified by the MCP transport URL policy. */
+export type McpTransportAddressClass = "loopback" | "private" | "public";

package/dist/types/multimodal.js

@@ -1,44 +1,3 @@
-/**
- * Multimodal Content Types for NeuroLink
- *
- * Central registry for all multimodal input/output types.
- * This file consolidates types from content.ts and conversation.ts
- * to provide a single source of truth for multimodal functionality.
- *
- * @module types/multimodal
- *
- * @example Basic Multimodal Input
- * ```typescript
- * import type { MultimodalInput } from './types/multimodal.js';
- *
- * const input: MultimodalInput = {
- *   text: "What's in this image?",
- *   images: [imageBuffer, "https://example.com/image.jpg"],
- *   pdfFiles: [pdfBuffer]
- * };
- * ```
- *
- * @example Audio/Video Input (Future)
- * ```typescript
- * const avInput: MultimodalInput = {
- *   text: "Transcribe this audio and analyze this video",
- *   audioFiles: [audioBuffer],
- *   videoFiles: ["path/to/video.mp4"]
- * };
- * ```
- *
- * @example Advanced Content Array
- * ```typescript
- * const advanced: MultimodalInput = {
- *   text: "irrelevant", // ignored when content[] is provided
- *   content: [
- *     { type: "text", text: "Analyze these items:" },
- *     { type: "image", data: imageBuffer, mediaType: "image/jpeg" },
- *     { type: "pdf", data: pdfBuffer, metadata: { filename: "report.pdf" } }
- *   ]
- * };
- * ```
- */
 // ============================================
 // TYPE GUARDS
 // ============================================

package/dist/types/openaiCompatible.d.ts

@@ -129,7 +129,7 @@ export type OpenAICompatStreamDelta = {
     role?: OpenAICompatChatRole;
     content?: string | null;
     tool_calls?: Array<{
-        index: number;
+        index?: number;
         id?: string;
         type?: "function";
         function?: {

package/dist/types/processor.d.ts

@@ -7,6 +7,7 @@
  * @module processors/base/types
  */
 import type { FileErrorCode } from "../processors/errors/FileErrorCode.js";
+import type { AttachmentPolicy } from "./attachments.js";
 /**
  * Generic file information - provider agnostic.
  * Replaces Slack-specific SlackFileInfo with a universal interface.
@@ -145,8 +146,16 @@ export type ProcessorRetryConfig = {
  * Allows customization of download behavior and retry logic.
  */
 export type ProcessOptions = {
-    /** Authentication headers for download requests */
+    /**
+     * Authentication headers for download requests. Sent on the first request
+     * only — never replayed to a redirect target.
+     */
     authHeaders?: Record<string, string>;
+    /**
+     * Attachment policy for the download (URL rules, size cap). The
+     * environment-derived default applies when absent.
+     */
+    attachmentPolicy?: AttachmentPolicy;
     /** Override default timeout (in milliseconds) */
     timeout?: number;
     /** Retry configuration for transient failures */
@@ -872,6 +881,10 @@ export type BoundedZipEntry = {
         crc: number;
     };
 };
+/** The minimum an indexable adm-zip entry carries (see `zipEntryIndex.ts`). */
+export type NamedZipEntry = {
+    entryName: string;
+};
 export type ArchiveEntryReadResult = {
     readonly status: "ok";
     readonly buffer: Buffer;

package/dist/types/proxy.d.ts

@@ -1,5 +1,6 @@
 import type { ProxyTokenBudgetLease, ProxyTokenBudgetSnapshot } from "./proxyBudget.js";
 import type { CodexRuntimeAccount } from "./codex.js";
+import type { TokenUsage } from "./analytics.js";
 import type { JsonObject, JsonValue } from "./common.js";
 import type { ProxyContextEvidence, ProxyPreparedContext } from "./proxyContext.js";
 /**
@@ -258,14 +259,7 @@ export type InternalResult = {
     finishReason?: string;
     /** Thinking/reasoning text from provider (Anthropic thinking blocks, Gemini thought parts) */
     reasoning?: string;
-    usage?: {
-        input: number;
-        output: number;
-        total: number;
-        cacheCreationTokens?: number;
-        cacheReadTokens?: number;
-        reasoning?: number;
-    };
+    usage?: TokenUsage;
     toolCalls?: Array<{
         toolCallId: string;
         toolName: string;
@@ -1307,6 +1301,10 @@ export type PreparedAnthropicAccountAttempt = {
     lastError: unknown;
     authFailureMessage: string | null;
     headers?: Record<string, string>;
+    /** The upstream `anthropic-beta` carries a value the client asked for that
+     *  the proxy would not have sent itself. A rejection of it is then the
+     *  client's doing, and must not re-rank the pool for everyone. */
+    clientSuppliedBetaForwarded?: boolean;
     buildUpstreamBody?: AnthropicUpstreamBodyBuilder;
     finalBodyStr?: string;
     preparedContext?: ProxyPreparedContext<ClaudeRequest>;
@@ -3242,18 +3240,37 @@ export type ProxyStatusPrimaryAccount = {
     label: string | null;
     source: "configured" | "fallback";
 };
-/** Parsed fields captured from a Claude Code client request body. */
+/**
+ * Identity tuple captured from a genuine Claude Code client request body.
+ *
+ * Deliberately carries no prompt text. An earlier shape persisted the client's
+ * "agent block" `system` text and replayed it as the system prompt of every
+ * later non-Claude-Code request on the account, so one hostile request could
+ * plant instructions into everyone else's sessions. The agent block is now a
+ * compiled-in constant; `billingHeader` is stored only in its normalised
+ * two-field form.
+ */
 export type ClaudeSnapshotBody = {
     metadataUserId?: string;
     billingHeader?: string;
-    agentBlock?: string;
     sessionId?: string;
 };
+/** The identity tuple plus one request-shape probe that is never persisted. */
+export type ClaudeSnapshotBodyProbe = ClaudeSnapshotBody & {
+    hasAgentBlock?: boolean;
+};
 /** Snapshot of headers and body from a Claude Code request, used for polyfill. */
 export type ClaudeSnapshot = {
     accountKey: string;
     capturedAt: string;
     source: "claude-code";
+    /**
+     * Set only by a capture that verified the client was Claude Code itself
+     * (session header and `claude-cli/` user-agent). A snapshot without it was
+     * written by a release whose heuristic any caller could satisfy, so its
+     * identity tuple is not trusted and is dropped on load.
+     */
+    capturedFrom?: "genuine-claude-code";
     headers: Record<string, string>;
     body?: ClaudeSnapshotBody;
 };
@@ -3377,10 +3394,46 @@ export type ProxyRuntimeConfigStoreOptions = {
 };
 /** Runtime configuration provider captured by route factories. */
 export type ProxyRuntimeConfigProvider = () => ProxyRequestRoutingSnapshot;
+/**
+ * Inbound authentication for a mounted proxy route group.
+ *
+ * `token` is the bearer every caller must present (header
+ * `x-neurolink-inbound-token`, or `Authorization: Bearer <token>`); when
+ * omitted it is read from `NEUROLINK_PROXY_INBOUND_TOKEN`. With neither, the
+ * routes serve any caller that reaches them, and the factory says so loudly
+ * unless `allowUnauthenticated` records that the operator chose that
+ * (loopback-only bind, or an authenticating reverse proxy in front).
+ */
+export type ProxyInboundAuthOptions = {
+    token?: string;
+    allowUnauthenticated?: boolean;
+};
 /** Optional runtime configuration wiring for Claude proxy route factories. */
 export type ClaudeProxyRouteRuntimeOptions = {
     accountAllowlist?: AccountAllowlist;
-    runtimeConfigProvider: ProxyRuntimeConfigProvider;
+    runtimeConfigProvider?: ProxyRuntimeConfigProvider;
+    inboundAuth?: ProxyInboundAuthOptions;
+};
+/**
+ * Whether a listener may bind where it was asked to.
+ *
+ * A non-loopback bind needs something in front of the pooled subscriptions:
+ * the share gate (`NEUROLINK_PROXY_REQUIRE_GRANT`), an inbound token, or the
+ * operator's explicit `allowUnauthenticated`.
+ */
+export type ProxyBindPolicyDecision = {
+    allowed: true;
+    warning?: string;
+} | {
+    allowed: false;
+    reason: string;
+};
+/** Inputs to the bind policy, resolved from flags and the environment. */
+export type ProxyBindPolicyInput = {
+    host: string;
+    inboundToken?: string;
+    requireGrant: boolean;
+    allowUnauthenticated: boolean;
 };
 /** Listener invoked after a new configuration generation is published. */
 export type ProxyRuntimeConfigListener = (snapshot: ProxyRuntimeConfigSnapshot) => void;
@@ -3465,11 +3518,7 @@ export type StreamSerializerAdapter = {
     start(): Iterable<string>;
     pushDelta(text: string): Iterable<string>;
     pushToolUse(id: string, name: string, input: unknown): Iterable<string>;
-    finish(finishReason: string, usage: {
-        input: number;
-        output: number;
-        total: number;
-    }): Iterable<string>;
+    finish(finishReason: string, usage: TokenUsage): Iterable<string>;
     emitError(message: string): Iterable<string>;
 };
 /** OpenAI content part in a user message. */
@@ -3556,6 +3605,12 @@ export type OpenAIUsage = {
     prompt_tokens: number;
     completion_tokens: number;
     total_tokens: number;
+    prompt_tokens_details?: {
+        cached_tokens: number;
+    };
+    completion_tokens_details?: {
+        reasoning_tokens: number;
+    };
 };
 /** OpenAI non-streaming response. */
 export type OpenAICompletionResponse = {

package/dist/types/proxyClient.d.ts

@@ -268,6 +268,8 @@ export type ProxyLedgerEntry = {
     model: string;
     provider?: string;
     inputTokens: number;
+    /** Native Codex input includes cache reads and writes. */
+    inputIncludesCachedTokens: boolean;
     outputTokens: number;
     cacheReadTokens: number;
     cacheCreationTokens: number;

package/dist/types/rag.d.ts

@@ -1,6 +1,7 @@
 import type { Tool } from "./tools.js";
 import type { EmbedInput } from "./providers.js";
 import type { DecisionCallerFn } from "./decision.js";
+import type { AttachmentPolicy } from "./attachments.js";
 /**
  * RAG Type Definitions
  *
@@ -500,6 +501,14 @@ export type LoaderOptions = {
 export type WebLoaderOptions = LoaderOptions & {
     /** Request timeout in milliseconds */
     timeout?: number;
+    /**
+     * Attachment policy for the fetch: HTTPS-only and public hosts unless it
+     * says otherwise, redirects re-validated per hop. The environment-derived
+     * default applies when absent.
+     */
+    attachmentPolicy?: AttachmentPolicy;
+    /** Cap on the fetched document in bytes. Default 25 MiB. */
+    maxBytes?: number;
     /** Custom headers for request */
     headers?: Record<string, string>;
     /** Extract only main content (remove navigation, ads, etc.) */

package/dist/types/safeFetch.d.ts

@@ -21,4 +21,44 @@ export type SafeDownloadOptions = {
     signal?: AbortSignal;
     /** Optional HTTP transfer timeout (ms), covering headers and body after URL validation. Default: 60_000. */
     timeoutMs?: number;
+    /**
+     * Headers for the FIRST request only. Never replayed to a redirect target:
+     * a credential meant for one host must not be handed to the host it
+     * redirects to. Default: none.
+     */
+    headers?: Record<string, string>;
+    /**
+     * How many redirect hops to follow, each re-validated by the SSRF guard and
+     * sent without the caller's headers. Default 0: a 3xx is refused, which is
+     * the server path's behaviour.
+     */
+    maxRedirects?: number;
+    /** Accept `http:` as well as `https:`. Default false (HTTPS only). */
+    allowInsecure?: boolean;
+    /**
+     * Skip the private/loopback/link-local/metadata range check. The connection
+     * is still pinned to the resolved addresses. Default false.
+     */
+    allowPrivateNetwork?: boolean;
+    /** `HEAD` returns the headers with an empty body. Default `GET`. */
+    method?: "GET" | "HEAD";
+};
+/** `safeDownloadWithMeta()` — the body plus what the response said about it. */
+export type SafeDownloadResult = {
+    buffer: Buffer;
+    /** `Content-Type` of the final response, `""` when absent. */
+    contentType: string;
+    /** `Content-Encoding` of the final response, `""` when absent. */
+    contentEncoding: string;
+    /** The URL that produced the body — differs from the request URL after a redirect. */
+    finalUrl: string;
+    /** Redirect hops that were followed. */
+    redirects: number;
+};
+/** Per-call switches for `validateAndResolveUrl()` / `assertSafeUrlForProxy()`. */
+export type SsrfGuardOptions = {
+    /** Accept `http:` as well as `https:`. Default false. */
+    allowInsecure?: boolean;
+    /** Skip the blocked-range check (addresses are still resolved and returned). Default false. */
+    allowPrivateNetwork?: boolean;
 };