@juspay/neurolink 9.93.2 → 9.94.1

package/dist/lib/proxy/socketWorkerRuntime.d.ts

@@ -0,0 +1,14 @@
+import type { Server } from "node:http";
+import type { SocketWorkerRuntime, SocketWorkerRuntimeOptions } from "../types/index.js";
+/**
+ * Adapts transferred TCP sockets to an HTTP server without opening another
+ * listener. Active responses finish normally; idle keep-alive sockets close as
+ * soon as draining begins.
+ */
+export declare function createSocketWorkerRuntime(server: Server, options?: SocketWorkerRuntimeOptions): SocketWorkerRuntime;
+export declare function attachSocketWorkerProcess(server: Server, input: {
+    generation: number;
+    version: string;
+    onActivated?: () => void;
+    onDrained?: () => void;
+}): SocketWorkerRuntime;

package/dist/lib/proxy/socketWorkerRuntime.js

@@ -0,0 +1,294 @@
+import { isProxyWorkerControlMessage } from "./rollingWorkerProtocol.js";
+function isTransferableProxySocket(handle) {
+    if (!handle || typeof handle !== "object") {
+        return false;
+    }
+    const candidate = handle;
+    return (typeof candidate.pause === "function" &&
+        typeof candidate.resume === "function" &&
+        typeof candidate.destroy === "function" &&
+        typeof candidate.end === "function" &&
+        typeof candidate.once === "function");
+}
+function destroyTransferredHandle(handle) {
+    if (handle &&
+        typeof handle === "object" &&
+        typeof handle.destroy === "function") {
+        try {
+            handle.destroy();
+        }
+        catch {
+            // Invalid IPC handles must not crash the serving worker.
+        }
+    }
+}
+/**
+ * Adapts transferred TCP sockets to an HTTP server without opening another
+ * listener. Active responses finish normally; idle keep-alive sockets close as
+ * soon as draining begins.
+ */
+export function createSocketWorkerRuntime(server, options) {
+    const sockets = new Set();
+    const activeBySocket = new Map();
+    const activeResponses = new Set();
+    let draining = false;
+    let drained = false;
+    const maybeFinishDrain = () => {
+        if (draining && !drained && sockets.size === 0) {
+            drained = true;
+            options?.onDrained?.();
+        }
+    };
+    const requestStarted = (request, response) => {
+        const socket = request.socket;
+        activeBySocket.set(socket, (activeBySocket.get(socket) ?? 0) + 1);
+        activeResponses.add(response);
+        if (draining) {
+            response.shouldKeepAlive = false;
+        }
+        let settled = false;
+        const settle = () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            activeResponses.delete(response);
+            const remaining = Math.max(0, (activeBySocket.get(socket) ?? 1) - 1);
+            if (remaining === 0) {
+                activeBySocket.delete(socket);
+                if (draining) {
+                    socket.end();
+                }
+            }
+            else {
+                activeBySocket.set(socket, remaining);
+            }
+        };
+        response.once("finish", settle);
+        response.once("close", settle);
+    };
+    server.prependListener("request", requestStarted);
+    const acceptSocket = (socket) => {
+        if (draining) {
+            socket.destroy();
+            return;
+        }
+        sockets.add(socket);
+        socket.once("close", () => {
+            sockets.delete(socket);
+            activeBySocket.delete(socket);
+            maybeFinishDrain();
+        });
+        server.emit("connection", socket);
+        socket.resume();
+    };
+    const drain = () => {
+        if (draining) {
+            return;
+        }
+        draining = true;
+        for (const response of activeResponses) {
+            response.shouldKeepAlive = false;
+        }
+        for (const socket of sockets) {
+            if (!activeBySocket.has(socket)) {
+                socket.end();
+            }
+        }
+        maybeFinishDrain();
+    };
+    return {
+        acceptSocket,
+        drain,
+        close: () => {
+            server.off("request", requestStarted);
+            for (const socket of sockets) {
+                socket.destroy();
+            }
+            sockets.clear();
+            activeBySocket.clear();
+            activeResponses.clear();
+            draining = true;
+            maybeFinishDrain();
+        },
+        snapshot: () => ({
+            draining,
+            sockets: sockets.size,
+            activeRequests: [...activeBySocket.values()].reduce((total, count) => total + count, 0),
+            drained,
+        }),
+    };
+}
+export function attachSocketWorkerProcess(server, input) {
+    let activated = false;
+    let gracefulDrain = false;
+    const pendingSockets = new Map();
+    const send = (message) => {
+        if (!process.connected || !process.send) {
+            return;
+        }
+        try {
+            process.send(message);
+        }
+        catch {
+            // Parent supervision handles the disconnected worker.
+        }
+    };
+    const runtime = createSocketWorkerRuntime(server, {
+        onDrained: () => {
+            send({
+                type: "proxy-worker:drained",
+                generation: input.generation,
+                pid: process.pid,
+            });
+            input.onDrained?.();
+        },
+    });
+    const drainWhenPendingSettled = () => {
+        if (!gracefulDrain || pendingSockets.size > 0) {
+            return;
+        }
+        // Defer to a macrotask so a request buffered on a just-committed socket can
+        // reach the HTTP server before drain() ends idle sockets; draining
+        // synchronously here would truncate that in-flight request.
+        setImmediate(() => runtime.drain());
+    };
+    const onMessage = (message, handle) => {
+        if (message &&
+            typeof message === "object" &&
+            message.type === "proxy-worker:socket") {
+            const socketMessage = message;
+            if (socketMessage.generation === input.generation &&
+                typeof message.socketId === "string" &&
+                message.socketId.length > 0 &&
+                isTransferableProxySocket(handle)) {
+                const socketId = message.socketId;
+                const socket = handle;
+                socket.pause();
+                if (!activated ||
+                    !process.connected ||
+                    !process.send ||
+                    gracefulDrain) {
+                    socket.destroy();
+                    return;
+                }
+                if (pendingSockets.has(socketId)) {
+                    socket.destroy();
+                    return;
+                }
+                pendingSockets.set(socketId, socket);
+                try {
+                    process.send({
+                        type: "proxy-worker:socket-accepted",
+                        generation: input.generation,
+                        pid: process.pid,
+                        socketId,
+                    }, (error) => {
+                        if (error) {
+                            pendingSockets.delete(socketId);
+                            socket.destroy();
+                        }
+                    });
+                }
+                catch {
+                    pendingSockets.delete(socketId);
+                    socket.destroy();
+                }
+            }
+            else {
+                destroyTransferredHandle(handle);
+            }
+            return;
+        }
+        if (handle !== undefined) {
+            destroyTransferredHandle(handle);
+        }
+        if (isProxyWorkerControlMessage(message) &&
+            message.generation === input.generation) {
+            if (message.type === "proxy-worker:activate") {
+                if (!activated) {
+                    try {
+                        input.onActivated?.();
+                        activated = true;
+                        send({
+                            type: "proxy-worker:activated",
+                            generation: input.generation,
+                            pid: process.pid,
+                        });
+                    }
+                    catch (error) {
+                        send({
+                            type: "proxy-worker:fatal",
+                            generation: input.generation,
+                            pid: process.pid,
+                            message: error instanceof Error ? error.message : String(error),
+                        });
+                        runtime.drain();
+                    }
+                }
+            }
+            else if (message.type === "proxy-worker:socket-commit" ||
+                message.type === "proxy-worker:socket-cancel") {
+                const socket = pendingSockets.get(message.socketId);
+                if (!socket) {
+                    return;
+                }
+                pendingSockets.delete(message.socketId);
+                if (message.type === "proxy-worker:socket-commit") {
+                    runtime.acceptSocket(socket);
+                }
+                else {
+                    socket.destroy();
+                }
+                drainWhenPendingSettled();
+            }
+            else {
+                // Graceful drain: a socket-commit for an already-accepted socket may
+                // still be in flight. Stop admitting new offers and defer the drain
+                // until every pending socket is committed or canceled, so an
+                // acknowledged connection is served instead of silently dropped.
+                gracefulDrain = true;
+                drainWhenPendingSettled();
+            }
+        }
+    };
+    // Terminal shutdown path: the parent IPC channel is gone (disconnect) or the
+    // process is being killed (SIGTERM/SIGINT). Unlike the graceful rolling drain
+    // above, pending offers can no longer be committed, so they are destroyed and
+    // the drain runs immediately — a best-effort close is correct when the process
+    // is exiting. The zero-downtime guarantee applies to the rolling handoff
+    // (control-message) path, not to process termination.
+    const drain = () => {
+        for (const socket of pendingSockets.values()) {
+            socket.destroy();
+        }
+        pendingSockets.clear();
+        runtime.drain();
+    };
+    const onTerminationSignal = () => drain();
+    process.on("message", onMessage);
+    process.once("disconnect", drain);
+    process.once("SIGTERM", onTerminationSignal);
+    process.once("SIGINT", onTerminationSignal);
+    send({
+        type: "proxy-worker:ready",
+        generation: input.generation,
+        pid: process.pid,
+        version: input.version,
+    });
+    return {
+        ...runtime,
+        close: () => {
+            process.off("message", onMessage);
+            process.off("disconnect", drain);
+            process.off("SIGTERM", onTerminationSignal);
+            process.off("SIGINT", onTerminationSignal);
+            for (const socket of pendingSockets.values()) {
+                socket.destroy();
+            }
+            pendingSockets.clear();
+            runtime.close();
+        },
+    };
+}
+//# sourceMappingURL=socketWorkerRuntime.js.map

package/dist/lib/skills/skillMatcher.d.ts

@@ -26,7 +26,13 @@ export declare function filterSkillIndex(items: SkillIndexItem[], query: SkillSe
  * keys are built by concatenation (S3, Redis) or path joining.
  */
 export declare function isSafeSkillResourcePath(resourcePath: string): boolean;
-/** Whether a skill is visible from the calling scope. */
+/**
+ * Whether a skill is visible from the calling scope. Fails closed, matching
+ * `filterSkillIndex`: a scoped skill is hidden unless the caller supplies a
+ * `scopeId` that the skill explicitly lists. Omitting `scopeId` therefore
+ * yields global skills only — it must never expose a scoped skill by name
+ * through `use_skill` / `read_skill_resource` (#1139).
+ */
 export declare function isSkillVisibleInScope(skill: Pick<SkillDefinition, "scope" | "scopeIds">, scopeId?: string): boolean;
 /**
  * Render the `<available_skills>` block embedded in the use_skill tool

package/dist/lib/skills/skillMatcher.js

@@ -29,11 +29,14 @@ export function filterSkillIndex(items, query) {
         if ((item.status ?? "active") !== "active") {
             return false;
         }
-        // Scope filter: global skills always pass; scoped skills require a
-        // matching scopeId. When the caller provides no scopeId, scoped skills
-        // still pass (curator semantics — unscoped callers see everything).
-        if (query.scopeId && item.scope === "scoped") {
-            if (!(item.scopeIds ?? []).includes(query.scopeId)) {
+        // Scope filter: global skills always pass. Scoped skills require a
+        // scopeId that matches; when the caller supplies no scopeId we fail
+        // closed and exclude them, so a shared multi-tenant instance that forgets
+        // to pass a per-call scopeId never leaks one tenant's scoped skills to
+        // everyone (#1139). Callers that legitimately want a tenant's scoped
+        // skills must pass that tenant's scopeId.
+        if (item.scope === "scoped") {
+            if (!query.scopeId || !(item.scopeIds ?? []).includes(query.scopeId)) {
                 return false;
             }
         }
@@ -67,11 +70,20 @@ export function isSafeSkillResourcePath(resourcePath) {
         !normalized.startsWith("/") &&
         !normalized.split("/").some((segment) => segment === ".." || segment === ""));
 }
-/** Whether a skill is visible from the calling scope. */
+/**
+ * Whether a skill is visible from the calling scope. Fails closed, matching
+ * `filterSkillIndex`: a scoped skill is hidden unless the caller supplies a
+ * `scopeId` that the skill explicitly lists. Omitting `scopeId` therefore
+ * yields global skills only — it must never expose a scoped skill by name
+ * through `use_skill` / `read_skill_resource` (#1139).
+ */
 export function isSkillVisibleInScope(skill, scopeId) {
-    if (!scopeId || skill.scope !== "scoped") {
+    if (skill.scope !== "scoped") {
         return true;
     }
+    if (!scopeId) {
+        return false;
+    }
     return (skill.scopeIds ?? []).includes(scopeId);
 }
 /** Trim a description to its first sentence (or the whole text when unsplittable). */
@@ -127,7 +139,10 @@ export function renderSkillListing(items, budgetChars) {
  * Returns null when nothing is visible so callers can skip injection.
  */
 export function formatSkillsPromptIndex(items, maxItems) {
-    if (items.length === 0) {
+    // Nothing visible, or the index is explicitly disabled (maxItems <= 0):
+    // skip injection entirely rather than emit a header + "N more skills exist"
+    // note with zero skill lines (#1139).
+    if (items.length === 0 || maxItems <= 0) {
         return null;
     }
     const visible = items.slice(0, maxItems);

package/dist/lib/types/cli.d.ts

@@ -820,6 +820,42 @@ export type FallbackInfo = {
     provider: string;
     model: string;
 };
+export type ProxyRollingState = {
+    generation: number;
+    active: {
+        pid: number;
+        version: string;
+        generation: number;
+    } | null;
+    candidate: {
+        pid: number;
+        expectedVersion: string;
+        generation: number;
+    } | null;
+    draining: Array<{
+        pid: number;
+        version: string;
+        generation: number;
+    }>;
+    queuedSockets: number;
+    rejectedSockets: number;
+    failedTransfers: number;
+    lastFailure: {
+        at: string;
+        generation: number;
+        version: string;
+        phase: "startup" | "activation" | "runtime" | "transfer";
+        message: string;
+    } | null;
+};
+export type ProxySupervisorState = {
+    pid: number;
+    host: string;
+    port: number;
+    startTime: string;
+    updaterPid?: number;
+    rolling: ProxyRollingState;
+};
 /** Persisted state for a running proxy instance */
 export type ProxyState = {
     pid: number;
@@ -840,6 +876,8 @@ export type ProxyState = {
     guardPid?: number;
     /** Dedicated updater PID for launchd-managed proxy installations. */
     updaterPid?: number;
+    /** Stable listener supervisor PID when requests are served by socket workers. */
+    supervisorPid?: number;
     /** How the proxy was launched — "launchd" if installed as service, "manual" otherwise */
     managedBy?: "launchd" | "manual";
     /** Whether the proxy is running in transparent passthrough mode */
@@ -1637,3 +1675,12 @@ export type CliNetworkCommandArgs = BaseCommandArgs & {
     /** Show detailed information */
     detailed?: boolean;
 };
+/**
+ * A single audio-player invocation for CLI TTS playback: a binary plus its
+ * arguments for `execFile`. The player list is tried in order until one
+ * succeeds (see `src/cli/utils/audioPlayer.ts`).
+ */
+export type CliAudioPlayerCommand = {
+    command: string;
+    args: string[];
+};

package/dist/lib/types/proxy.d.ts

@@ -1455,6 +1455,162 @@ export type UpdaterWorkerSupervisor = {
     checkNow: () => number | undefined;
     stop: () => void;
 };
+export type ProxyWorkerControlMessage = {
+    type: "proxy-worker:activate";
+    generation: number;
+} | {
+    type: "proxy-worker:drain";
+    generation: number;
+} | {
+    type: "proxy-worker:shutdown";
+    generation: number;
+} | {
+    type: "proxy-worker:socket-commit";
+    generation: number;
+    socketId: string;
+} | {
+    type: "proxy-worker:socket-cancel";
+    generation: number;
+    socketId: string;
+};
+export type ProxyWorkerStatusMessage = {
+    type: "proxy-worker:ready";
+    generation: number;
+    pid: number;
+    version: string;
+} | {
+    type: "proxy-worker:drained";
+    generation: number;
+    pid: number;
+} | {
+    type: "proxy-worker:activated";
+    generation: number;
+    pid: number;
+} | {
+    type: "proxy-worker:fatal";
+    generation: number;
+    pid: number;
+    message: string;
+} | {
+    type: "proxy-worker:socket-accepted";
+    generation: number;
+    pid: number;
+    socketId: string;
+};
+export type ProxyWorkerSocketMessage = {
+    type: "proxy-worker:socket";
+    generation: number;
+    socketId: string;
+};
+export type ProxyWorkerIpcMessage = ProxyWorkerControlMessage | ProxyWorkerStatusMessage | ProxyWorkerSocketMessage;
+export type TransferableProxySocket = Pick<import("node:net").Socket, "destroy" | "end" | "pause" | "resume" | "once">;
+export type RollingWorkerHandle = {
+    pid: number;
+    sendControl: (message: ProxyWorkerControlMessage) => void;
+    sendSocket: (generation: number, socket: TransferableProxySocket, callback: (error?: Error | null) => void) => void;
+    terminate: (signal?: NodeJS.Signals) => void;
+    onMessage: (listener: (message: ProxyWorkerStatusMessage) => void) => () => void;
+    onExit: (listener: (code: number | null, signal: string | null) => void) => () => void;
+};
+export type SpawnProxySocketWorkerOptions = {
+    generation: number;
+    expectedVersion: string;
+    command: string;
+    args: string[];
+    env?: NodeJS.ProcessEnv;
+    stdout?: "inherit" | "ignore";
+    stderr?: "inherit" | "ignore";
+    socketAckTimeoutMs?: number;
+};
+export type RollingWorkerSupervisorSnapshot = {
+    generation: number;
+    active: {
+        pid: number;
+        version: string;
+        generation: number;
+    } | null;
+    candidate: {
+        pid: number;
+        expectedVersion: string;
+        generation: number;
+    } | null;
+    draining: Array<{
+        pid: number;
+        version: string;
+        generation: number;
+    }>;
+    queuedSockets: number;
+    rejectedSockets: number;
+    failedTransfers: number;
+    lastFailure: {
+        at: string;
+        generation: number;
+        version: string;
+        phase: "startup" | "activation" | "runtime" | "transfer";
+        message: string;
+    } | null;
+};
+export type RollingWorkerSupervisorOptions = {
+    spawnWorker: (generation: number, expectedVersion: string) => RollingWorkerHandle;
+    readyTimeoutMs?: number;
+    socketQueueLimit?: number;
+    socketQueueTimeoutMs?: number;
+    shutdownTimeoutMs?: number;
+    onStateChange?: (snapshot: RollingWorkerSupervisorSnapshot) => void;
+    log?: (message: string) => void;
+};
+export type RollingProxyServerOptions = {
+    host: string;
+    port: number;
+    initialVersion: string;
+    spawnWorker: (generation: number, expectedVersion: string) => RollingWorkerHandle;
+    readyTimeoutMs?: number;
+    socketQueueLimit?: number;
+    socketQueueTimeoutMs?: number;
+    shutdownTimeoutMs?: number;
+    recoveryDelayMs?: number;
+    maxRecoveryDelayMs?: number;
+    onStateChange?: (snapshot: RollingWorkerSupervisorSnapshot) => void;
+    log?: (message: string) => void;
+};
+export type RollingProxyServer = {
+    address: {
+        host: string;
+        port: number;
+    };
+    replace: (expectedVersion: string) => Promise<RollingWorkerSupervisorSnapshot>;
+    snapshot: () => RollingWorkerSupervisorSnapshot;
+    close: () => Promise<void>;
+};
+export type RollingManagedWorker = {
+    handle: RollingWorkerHandle;
+    generation: number;
+    version: string;
+    dispose: () => void;
+};
+export type RollingCandidateWorker = RollingManagedWorker & {
+    expectedVersion: string;
+    activationRequested: boolean;
+    settle: (error?: Error) => void;
+};
+export type RollingQueuedSocket = {
+    socket: TransferableProxySocket;
+    timeout: NodeJS.Timeout;
+};
+export type SocketWorkerRuntime = {
+    acceptSocket: (socket: TransferableProxySocket) => void;
+    drain: () => void;
+    close: () => void;
+    snapshot: () => {
+        draining: boolean;
+        sockets: number;
+        activeRequests: number;
+        drained: boolean;
+    };
+};
+export type SocketWorkerRuntimeOptions = {
+    onDrained?: () => void;
+};
 /** Shape of the dynamically-imported js-yaml module. `dump` is optional —
  *  read-only consumers (proxy config loader) only need `load`; writers
  *  (CLI primary-account commands) check `dump` before calling. */

package/dist/lib/utils/errorHandling.d.ts

@@ -14,6 +14,7 @@ export declare const ERROR_CODES: {
     readonly MEMORY_EXHAUSTED: "MEMORY_EXHAUSTED";
     readonly NETWORK_ERROR: "NETWORK_ERROR";
     readonly PERMISSION_DENIED: "PERMISSION_DENIED";
+    readonly PROXY_WORKER_LIFECYCLE_FAILED: "PROXY_WORKER_LIFECYCLE_FAILED";
     readonly PROVIDER_NOT_AVAILABLE: "PROVIDER_NOT_AVAILABLE";
     readonly PROVIDER_AUTH_FAILED: "PROVIDER_AUTH_FAILED";
     readonly PROVIDER_QUOTA_EXCEEDED: "PROVIDER_QUOTA_EXCEEDED";
@@ -247,6 +248,13 @@ export declare class ErrorFactory {
      * Create an evaluation execution failed error
      */
     static evaluationExecutionFailed(operation: string, originalError: Error): NeuroLinkError;
+    /**
+     * Create a proxy rolling-worker lifecycle error. Preserves the caller's exact
+     * message so existing substring-based assertions keep working, while giving
+     * callers a typed `code`/`category` to branch on instead of string-matching
+     * generic `Error` instances.
+     */
+    static proxyWorkerLifecycle(message: string, context?: Record<string, unknown>): NeuroLinkError;
 }
 /**
  * Timeout wrapper for async operations

package/dist/lib/utils/errorHandling.js

@@ -20,6 +20,7 @@ export const ERROR_CODES = {
     MEMORY_EXHAUSTED: "MEMORY_EXHAUSTED",
     NETWORK_ERROR: "NETWORK_ERROR",
     PERMISSION_DENIED: "PERMISSION_DENIED",
+    PROXY_WORKER_LIFECYCLE_FAILED: "PROXY_WORKER_LIFECYCLE_FAILED",
     // Provider errors
     PROVIDER_NOT_AVAILABLE: "PROVIDER_NOT_AVAILABLE",
     PROVIDER_AUTH_FAILED: "PROVIDER_AUTH_FAILED",
@@ -818,6 +819,25 @@ export class ErrorFactory {
             originalError,
         });
     }
+    // ============================================================================
+    // PROXY ROLLING-WORKER ERRORS
+    // ============================================================================
+    /**
+     * Create a proxy rolling-worker lifecycle error. Preserves the caller's exact
+     * message so existing substring-based assertions keep working, while giving
+     * callers a typed `code`/`category` to branch on instead of string-matching
+     * generic `Error` instances.
+     */
+    static proxyWorkerLifecycle(message, context) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.PROXY_WORKER_LIFECYCLE_FAILED,
+            message,
+            category: ErrorCategory.SYSTEM,
+            severity: ErrorSeverity.HIGH,
+            retriable: false,
+            context: context || {},
+        });
+    }
 }
 /**
  * Timeout wrapper for async operations

package/dist/proxy/rollingProxyServer.d.ts

@@ -0,0 +1,3 @@
+import type { RollingProxyServer, RollingProxyServerOptions } from "../types/index.js";
+/** Keep one public listener stable while serving workers start and rotate. */
+export declare function startRollingProxyServer(options: RollingProxyServerOptions): Promise<RollingProxyServer>;