@juspay/neurolink 9.85.0 → 9.86.0

package/dist/lib/neurolink.js

@@ -54,8 +54,10 @@ import { MCPToolRegistry } from "./mcp/toolRegistry.js";
 import { resolveDynamicArgument } from "./dynamic/dynamicResolver.js";
 import { initializeHippocampus } from "./memory/hippocampusInitializer.js";
 import { createMemoryRetrievalTools } from "./memory/memoryRetrievalTools.js";
+import { isSkillVisibleInScope } from "./skills/skillMatcher.js";
+import { buildSkillActivationMessage } from "./skills/skillSessionTracker.js";
 import { SkillsManager } from "./skills/skillsManager.js";
-import { createSkillTools } from "./skills/skillTools.js";
+import { createSkillCallTools, createSkillTools } from "./skills/skillTools.js";
 import { getMetricsAggregator, MetricsAggregator, } from "./observability/metricsAggregator.js";
 import { SpanStatus, SpanType, CircuitBreakerOpenError, ConversationMemoryError, ModelAccessDeniedError, } from "./types/index.js";
 import { SpanSerializer } from "./observability/utils/spanSerializer.js";
@@ -1276,7 +1278,7 @@ export class NeuroLink {
         return this.skillsManagerInstance;
     }
     /**
-     * Register the built-in skill tools (search_skills / list_skills, plus
+     * Register the built-in skill tools (list_skills, plus
      * mutation tools when allowMutations is set). Follows the
      * registerMemoryRetrievalTools() pattern: registered via registerTool()
      * so they land in the "user-defined" category that reaches the LLM tool
@@ -1300,19 +1302,22 @@ export class NeuroLink {
         logger.info(`[NeuroLink] Registered ${Object.keys(canonicalTools).length} skill tools`, { allowMutations: this.skillsConfig?.allowMutations === true });
     }
     /**
-     * Append the compact skills index (names + descriptions, never
-     * instructions) to the system prompt for one generate()/stream() call.
-     * Fails open: any error leaves the prompt untouched.
+     * Skills augmentation for one generate()/stream() call:
+     *  1. Discovery — surface the skills listing per the resolved mode:
+     *     embedded in the use_skill tool description ("tool", default) or
+     *     appended to the system prompt ("system-prompt").
+     *  2. Per-call tools — inject use_skill + read_skill_resource into
+     *     options.tools (the RAG-tool pattern; same-name entries shadow
+     *     registered tools) with the sessionId closure-bound so activations
+     *     pin to the session.
+     *  3. Preload — activate host-requested skills up front, injecting their
+     *     instructions into this call's system prompt and pinning them.
+     * Fails open: any error leaves the call untouched.
      */
-    async applySkillsPromptIndex(options) {
+    async applySkillsAugmentation(options) {
         if (!this.skillsConfig?.enabled || options.skills?.enabled === false) {
             return;
         }
-        // Per-call promptIndex wins over instance config; default is on.
-        const promptIndexEnabled = options.skills?.promptIndex ?? this.skillsConfig.promptIndex ?? true;
-        if (!promptIndexEnabled) {
-            return;
-        }
         // Media-only modes have no meaningful text prompt to augment.
         const mode = options.output?.mode;
         if (mode === "avatar" ||
@@ -1326,26 +1331,142 @@ export class NeuroLink {
             if (!manager) {
                 return;
             }
-            const block = await manager.buildPromptIndex({
-                ...(options.skills?.scopeId !== undefined
-                    ? { scopeId: options.skills.scopeId }
-                    : {}),
-                ...(options.skills?.tags !== undefined
-                    ? { tags: options.skills.tags }
-                    : {}),
+            const discovery = options.skills?.discovery ?? this.skillsConfig.discovery ?? "tool";
+            const scopeId = options.skills?.scopeId ?? this.skillsConfig.defaultScopeId;
+            const tags = options.skills?.tags;
+            const sessionId = this.resolveSkillSessionId(options.context) ??
+                this.resolveSkillSessionId(options);
+            const userId = this.resolveSkillUserId(options.context) ??
+                this.resolveSkillUserId(options);
+            // Pinning requires somewhere to pin: without conversation memory the
+            // drained messages would be silently discarded while dedup reports
+            // already_loaded — so persistence is only on when memory is
+            // configured (or already initialized).
+            const memoryAvailable = Boolean(this.conversationMemory) ||
+                Boolean(this.conversationMemoryConfig?.conversationMemory?.enabled);
+            const sessionPersistence = (this.skillsConfig.sessionPersistence ?? true) &&
+                Boolean(sessionId) &&
+                memoryAvailable;
+            const visibility = {
+                ...(scopeId !== undefined ? { scopeId } : {}),
+                ...(tags !== undefined ? { tags } : {}),
+            };
+            if (discovery === "system-prompt") {
+                const block = await manager.buildPromptIndex(visibility);
+                if (block) {
+                    options.systemPrompt = options.systemPrompt
+                        ? `${options.systemPrompt}\n\n${block}`
+                        : block;
+                }
+            }
+            const listing = discovery === "tool"
+                ? await manager.buildToolListing(visibility)
+                : null;
+            const callTools = createSkillCallTools(() => this.ensureSkillsReady(), {
+                ...(sessionId ? { sessionId } : {}),
+                ...(scopeId !== undefined ? { scopeId } : {}),
+                sessionPersistence,
+                discovery,
+                listing,
+                // userId rides by closure: Redis memory keys sessions by
+                // userId:sessionId, so hydration must read the same key the
+                // store-turn path writes.
+                getStoredMessages: async (sid) => this.conversationMemory
+                    ? await this.conversationMemory.getSessionMessages(sid, userId)
+                    : [],
             });
-            if (block) {
-                options.systemPrompt = options.systemPrompt
-                    ? `${options.systemPrompt}\n\n${block}`
-                    : block;
-                logger.debug("[NeuroLink] Skills prompt index injected", {
-                    blockLength: block.length,
+            // Caller-supplied per-call tools win over the injected ones (a host
+            // may bring its own use_skill); the injected tools still shadow any
+            // registered base tool of the same name via the provider merge.
+            options.tools = {
+                ...callTools,
+                ...(options.tools ?? {}),
+            };
+            if (options.skills?.preload?.length) {
+                await this.preloadSkills(manager, options, options.skills.preload, {
+                    ...(sessionId ? { sessionId } : {}),
+                    ...(userId ? { userId } : {}),
+                    sessionPersistence,
+                    ...(scopeId !== undefined ? { scopeId } : {}),
                 });
             }
+            logger.debug("[NeuroLink] Skills augmentation applied", {
+                discovery,
+                listingLength: listing?.length ?? 0,
+                sessionPersistence,
+                preloadCount: options.skills?.preload?.length ?? 0,
+            });
         }
         catch (error) {
-            logger.warn("[NeuroLink] Skills prompt index injection failed — continuing without it", { error: error instanceof Error ? error.message : String(error) });
+            logger.warn("[NeuroLink] Skills augmentation failed — continuing without skills", { error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    /** Session id for skill activation tracking, from the call context. */
+    resolveSkillSessionId(context) {
+        const fromContext = context
+            ?.sessionId;
+        return typeof fromContext === "string" && fromContext
+            ? fromContext
+            : undefined;
+    }
+    /** User id for skill-session hydration (Redis keys sessions by userId). */
+    resolveSkillUserId(context) {
+        const fromContext = context?.userId;
+        return typeof fromContext === "string" && fromContext
+            ? fromContext
+            : undefined;
+    }
+    /**
+     * Activate host-requested skills before the model runs: instructions go
+     * into this call's system prompt; when persisting, the activation is
+     * pinned so later turns replay it from history instead. Unknown or
+     * already-active names are skipped with a warn/debug log (fail-open).
+     */
+    async preloadSkills(manager, options, names, call) {
+        const { sessionId, userId, sessionPersistence, scopeId } = call;
+        for (const name of names) {
+            const skill = await manager.get(name);
+            if (!skill || !isSkillVisibleInScope(skill, scopeId)) {
+                logger.warn("[NeuroLink] Preload skill not found — skipping", {
+                    skill: name,
+                });
+                continue;
+            }
+            let block;
+            if (sessionId && sessionPersistence) {
+                // Always hydrate (empty history when memory isn't initialized yet):
+                // the tracker derives truth from stored pins + this turn's pending,
+                // never from stale in-process records.
+                manager.sessions.hydrate(sessionId, this.conversationMemory
+                    ? await this.conversationMemory.getSessionMessages(sessionId, userId)
+                    : []);
+                if (manager.sessions.isActive(sessionId, skill.id, skill.name)) {
+                    continue;
+                }
+                block = manager.sessions.recordActivation(sessionId, skill).content;
+            }
+            else {
+                block = buildSkillActivationMessage(skill).content;
+            }
+            options.systemPrompt = options.systemPrompt
+                ? `${options.systemPrompt}\n\n${block}`
+                : block;
+        }
+    }
+    /**
+     * Pinned skill messages recorded during this turn, ready for
+     * StoreConversationTurnOptions.skillMessages. Empty when skills are off
+     * or nothing was activated.
+     */
+    drainPendingSkillMessages(sessionId) {
+        if (typeof sessionId !== "string" || !sessionId) {
+            return [];
+        }
+        const manager = this.skillsManagerInstance;
+        if (!manager) {
+            return [];
         }
+        return manager.sessions.drainPending(sessionId);
     }
     /**
      * Programmatic access to the skills subsystem (search/list/get/mutations).
@@ -3610,9 +3731,9 @@ Current user's request: ${currentInput}`;
                 });
             }
         }
-        // Skills: append the compact skills index to the system prompt so the
-        // model knows which skills exist (bodies load via search_skills).
-        await this.applySkillsPromptIndex(options);
+        // Skills: surface the discovery listing and inject the per-call
+        // use_skill / read_skill_resource tools (bodies load on activation).
+        await this.applySkillsAugmentation(options);
         // Media-only modes (avatar, music, video, ppt) do not have a meaningful
         // text prompt to augment with memory — skip injection to avoid corrupting
         // the empty/synthesized input.text that was set for these modes.
@@ -4431,7 +4552,7 @@ Current user's request: ${currentInput}`;
         });
         const memStoreStart = Date.now();
         try {
-            await storeConversationTurn(this.conversationMemory, options, result, new Date(startTime), requestId);
+            await storeConversationTurn(this.conversationMemory, options, result, new Date(startTime), requestId, this.drainPendingSkillMessages(options.context?.sessionId));
             this.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": path }, Date.now() - memStoreStart, SpanStatus.OK);
         }
         catch (memoryError) {
@@ -7151,9 +7272,9 @@ Current user's request: ${currentInput}`;
                 logger.warn("Memory retrieval failed:", error);
             }
         }
-        // Skills: append the compact skills index to the system prompt so the
-        // model knows which skills exist (bodies load via search_skills).
-        await this.applySkillsPromptIndex(options);
+        // Skills: surface the discovery listing and inject the per-call
+        // use_skill / read_skill_resource tools (bodies load on activation).
+        await this.applySkillsAugmentation(options);
         // Apply orchestration if enabled and no specific provider/model requested
         if (this.enableOrchestration && !options.provider && !options.model) {
             try {
@@ -7526,6 +7647,7 @@ Current user's request: ${currentInput}`;
             }
             const memStoreStart = Date.now();
             try {
+                const pendingSkillMessages = this.drainPendingSkillMessages(sessionId);
                 await this.conversationMemory.storeConversationTurn({
                     sessionId,
                     userId,
@@ -7537,6 +7659,9 @@ Current user's request: ${currentInput}`;
                     events: eventSequence.length > 0 ? eventSequence : undefined,
                     requestId: enhancedOptions.context
                         ?.requestId,
+                    ...(pendingSkillMessages.length > 0
+                        ? { skillMessages: pendingSkillMessages }
+                        : {}),
                 });
                 this.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": "stream" }, Date.now() - memStoreStart, SpanStatus.OK);
                 logger.debug("[NeuroLink.stream] Stored conversation turn with events", {
@@ -8075,8 +8200,10 @@ Current user's request: ${currentInput}`;
                     }
                     const memStoreStart = Date.now();
                     try {
+                        const fallbackSessionId = sessionId || options.context?.sessionId;
+                        const pendingSkillMessages = self.drainPendingSkillMessages(fallbackSessionId);
                         await self.conversationMemory.storeConversationTurn({
-                            sessionId: sessionId || options.context?.sessionId,
+                            sessionId: fallbackSessionId,
                             userId: userId || options.context?.userId,
                             userMessage: originalPrompt ?? "",
                             aiResponse: fallbackAccumulatedContent,
@@ -8086,6 +8213,9 @@ Current user's request: ${currentInput}`;
                             requestId: enhancedOptions?.context?.requestId ||
                                 options.context
                                     ?.requestId,
+                            ...(pendingSkillMessages.length > 0
+                                ? { skillMessages: pendingSkillMessages }
+                                : {}),
                         });
                         self.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": "fallback-stream" }, Date.now() - memStoreStart, SpanStatus.OK);
                     }

package/dist/lib/server/routes/claudeProxyRoutes.d.ts

@@ -11,7 +11,7 @@
  */
 import { buildTranslationOptions } from "../../proxy/proxyTranslationEngine.js";
 import type { ModelRouter } from "../../proxy/modelRouter.js";
-import type { ParsedClaudeError, ProxyPassthroughAccount, RouteGroup, RuntimeAccountState } from "../../types/index.js";
+import type { AccountCooldownPlan, AccountQuota, ParsedClaudeError, ProxyPassthroughAccount, RouteGroup, RuntimeAccountState } from "../../types/index.js";
 /** Resolve the configured primary's stable key to its current index in the
  *  request's enabledAccounts list. Returns 0 (insertion-order fallback) when
  *  no key is configured or the key cannot be matched (account disabled/
@@ -23,6 +23,41 @@ declare function resolveHomeIndex(enabledAccounts: ProxyPassthroughAccount[]): n
  *  account once its rate limit window expires. Called at the start of each
  *  request. Home is resolved fresh per call via resolveHomeIndex. */
 declare function maybeResetPrimaryToHome(enabledAccounts: ProxyPassthroughAccount[]): void;
+/** Convert an Anthropic unified-window reset (Unix epoch SECONDS, per the
+ *  `anthropic-ratelimit-unified-*-reset` headers) into epoch-ms. Tolerates a
+ *  value already expressed in ms (some intermediaries normalise it). Returns
+ *  undefined for absent/zero/past-or-garbage timestamps so callers can fall
+ *  back to retry-after. */
+declare function resetEpochToMs(resetEpoch: number | undefined, now: number): number | undefined;
+/**
+ * Decide how to cool an account after a genuine (non-anti-abuse) 429.
+ *
+ * The unified subscription limits expose per-window status + reset:
+ *   - weekly (7d) "rejected"  → hard cap for the week; cool until the 7d reset.
+ *   - session (5h) "rejected" → paced out for this session; cool until the 5h reset.
+ * Both mean "retrying this account is futile until its window resets" → rotate
+ * immediately (no same-account retries) and park the account until the ACTUAL
+ * reset — never the legacy 60s hardcap that let us re-hammer a spent account.
+ *
+ * Anything else (window still "allowed" but momentarily 429'd — a per-minute
+ * burst / acceleration limit) is transient: honor retry-after as a floor,
+ * allow a couple of jittered same-account retries, then a short cooldown.
+ */
+declare function planCooldownFor429(quota: AccountQuota | null, retryAfterMs: number, now: number): AccountCooldownPlan;
+/**
+ * Order accounts to MAXIMIZE quota utilization (fill-first, smart order):
+ * spend the account whose window refreshes SOONEST first, so its about-to-reset
+ * allowance isn't wasted, then move to accounts with longer-dated resets.
+ *
+ * Priority among usable accounts:
+ *   1. soonest WEEKLY (7d) reset  — the scarce, use-it-or-lose-it ceiling
+ *   2. soonest SESSION (5h) reset
+ *   3. highest weekly utilization — finish off the one closest to done
+ * Accounts with no quota data yet keep insertion order (stable sort) and sit
+ * after those with a known soonest reset. Cooling/rejected accounts sort last,
+ * soonest-back-to-service first, as last resort.
+ */
+declare function orderAccountsByQuota(accounts: ProxyPassthroughAccount[], now: number): ProxyPassthroughAccount[];
 /**
  * Create Claude-compatible proxy routes.
  *
@@ -57,6 +92,9 @@ export declare function isTransientHttpFailure(status: number, errBody: string):
 export declare const __testHooks: {
     resolveHomeIndex: typeof resolveHomeIndex;
     maybeResetPrimaryToHome: typeof maybeResetPrimaryToHome;
+    planCooldownFor429: typeof planCooldownFor429;
+    orderAccountsByQuota: typeof orderAccountsByQuota;
+    resetEpochToMs: typeof resetEpochToMs;
     setConfiguredPrimaryAccountKey: (key: string | undefined) => void;
     getConfiguredPrimaryAccountKey: () => string | undefined;
     setPrimaryAccountIndex: (index: number) => void;