@juspay/neurolink 9.85.1 → 9.86.0

package/dist/context/contextCompactor.js

@@ -26,7 +26,7 @@ const DEFAULT_CONFIG = {
     enableTruncate: true,
     pruneProtectTokens: 40_000,
     pruneMinimumSavings: 500,
-    pruneProtectedTools: ["skill"],
+    pruneProtectedTools: ["skill", "use_skill", "read_skill_resource"],
     summarizationProvider: "vertex",
     summarizationModel: "gemini-2.5-flash",
     keepRecentRatio: 0.3,
@@ -120,7 +120,21 @@ export class ContextCompactor {
                             targetTokens,
                         }), 120_000, "LLM summarization timed out after 120s");
                         if (summarizeResult.summarized) {
-                            currentMessages = summarizeResult.messages;
+                            // Pinned skill instructions must survive summarization:
+                            // re-seat any that the summarized region swallowed right
+                            // after the summary message (index 0 of the result).
+                            const survivorIds = new Set(summarizeResult.messages.map((m) => m.id));
+                            const swallowedSkills = currentMessages.filter((m) => m.metadata?.isSkill && !survivorIds.has(m.id));
+                            currentMessages =
+                                swallowedSkills.length > 0
+                                    ? summarizeResult.messages.length > 0
+                                        ? [
+                                            summarizeResult.messages[0],
+                                            ...swallowedSkills,
+                                            ...summarizeResult.messages.slice(1),
+                                        ]
+                                        : swallowedSkills
+                                    : summarizeResult.messages;
                             stagesUsed.push("summarize");
                         }
                         const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);

package/dist/context/stages/slidingWindowTruncator.js

@@ -58,8 +58,10 @@ function truncateSmallConversation(messages, config) {
     let totalSaved = 0;
     for (let i = 0; i < result.length; i++) {
         const msg = result[i];
-        // Don't truncate system/summary messages
-        if (msg.role === "system" || msg.metadata?.isSummary) {
+        // Don't truncate system/summary messages or pinned skill instructions
+        if (msg.role === "system" ||
+            msg.metadata?.isSummary ||
+            msg.metadata?.isSkill) {
             continue;
         }
         const proportionalBudget = Math.floor((msgTokens[i] / totalContentTokens) * contentBudget);
@@ -93,8 +95,40 @@ function truncateSmallConversation(messages, config) {
     return { truncated: false, messages, messagesRemoved: 0 };
 }
 export function truncateWithSlidingWindow(messages, config) {
-    if (messages.length <= 4) {
-        // Delegate to content truncation for small conversations (BUG-005)
+    // Partition pinned skill messages out so the pair-based arithmetic below
+    // runs on the alternating user/assistant stream (skill pins are extra
+    // user-role messages inside a turn and would misalign every even-count
+    // cut). Each skill anchors to the next conversational message; kept
+    // anchors put their skills back in place, dropped anchors re-seat them
+    // after the truncation marker.
+    const skillsByAnchor = new Map();
+    const trailingSkills = [];
+    const conversational = [];
+    for (let i = 0; i < messages.length; i++) {
+        const msg = messages[i];
+        if (!msg.metadata?.isSkill) {
+            conversational.push(msg);
+            continue;
+        }
+        const anchor = messages
+            .slice(i + 1)
+            .find((next) => !next.metadata?.isSkill);
+        if (anchor) {
+            const anchored = skillsByAnchor.get(anchor.id);
+            if (anchored) {
+                anchored.push(msg);
+            }
+            else {
+                skillsByAnchor.set(anchor.id, [msg]);
+            }
+        }
+        else {
+            trailingSkills.push(msg);
+        }
+    }
+    if (conversational.length <= 4) {
+        // Delegate to content truncation for small conversations (BUG-005);
+        // it never removes messages, so skills keep their positions.
         return truncateSmallConversation(messages, config);
     }
     // ADAPTIVE MODE: calculate fraction from actual overage (PERF-001)
@@ -118,8 +152,42 @@ export function truncateWithSlidingWindow(messages, config) {
         fraction = config?.fraction ?? 0.5;
     }
     // Always preserve first user-assistant pair
-    const firstPair = messages.slice(0, 2);
-    const remainingMessages = messages.slice(2);
+    const firstPair = conversational.slice(0, 2);
+    const remainingMessages = conversational.slice(2);
+    /** Reassemble a candidate: skills inline before kept anchors, orphans after the marker. */
+    const buildCandidate = (keptAfterTruncation, marker) => {
+        const keptIds = new Set([...firstPair, ...keptAfterTruncation].map((m) => m.id));
+        const orphanedSkills = [];
+        for (const [anchorId, anchored] of skillsByAnchor) {
+            if (!keptIds.has(anchorId)) {
+                orphanedSkills.push(...anchored);
+            }
+        }
+        const withInlineSkills = (msg) => {
+            const anchored = skillsByAnchor.get(msg.id);
+            return anchored ? [...anchored, msg] : [msg];
+        };
+        return [
+            ...firstPair.flatMap(withInlineSkills),
+            marker,
+            ...orphanedSkills,
+            ...keptAfterTruncation.flatMap(withInlineSkills),
+            ...trailingSkills,
+        ];
+    };
+    // Insert a truncation marker with machine-readable metadata so
+    // effectiveHistory.ts can detect it via isTruncationMarker /
+    // truncationId and removeTruncationTags can rewind it.
+    const makeMarker = () => {
+        const truncId = randomUUID();
+        return {
+            id: `truncation-marker-${truncId}`,
+            role: "user",
+            content: TRUNCATION_MARKER_CONTENT,
+            isTruncationMarker: true,
+            truncationId: truncId,
+        };
+    };
     // ITERATIVE: if first pass isn't enough, increase fraction
     const maxIterations = config?.maxIterations ?? 3;
     let currentFraction = fraction;
@@ -129,19 +197,7 @@ export function truncateWithSlidingWindow(messages, config) {
         if (evenRemoveCount <= 0) {
             break;
         }
-        const keptAfterTruncation = remainingMessages.slice(evenRemoveCount);
-        // Insert a truncation marker with machine-readable metadata so
-        // effectiveHistory.ts can detect it via isTruncationMarker /
-        // truncationId and removeTruncationTags can rewind it.
-        const truncId = randomUUID();
-        const marker = {
-            id: `truncation-marker-${truncId}`,
-            role: "user",
-            content: TRUNCATION_MARKER_CONTENT,
-            isTruncationMarker: true,
-            truncationId: truncId,
-        };
-        const candidateMessages = [...firstPair, marker, ...keptAfterTruncation];
+        const candidateMessages = buildCandidate(remainingMessages.slice(evenRemoveCount), makeMarker());
         validateRoleAlternation(candidateMessages);
         // If we have token targets, verify the result fits
         if (config?.targetTokens) {
@@ -168,17 +224,7 @@ export function truncateWithSlidingWindow(messages, config) {
     const maxRemove = Math.floor(remainingMessages.length * 0.95);
     const evenMaxRemove = maxRemove - (maxRemove % 2);
     if (evenMaxRemove > 0) {
-        const keptMessages = remainingMessages.slice(evenMaxRemove);
-        // Insert a truncation marker (see iterative block above)
-        const fallbackTruncId = randomUUID();
-        const fallbackMarker = {
-            id: `truncation-marker-${fallbackTruncId}`,
-            role: "user",
-            content: TRUNCATION_MARKER_CONTENT,
-            isTruncationMarker: true,
-            truncationId: fallbackTruncId,
-        };
-        const fallbackMessages = [...firstPair, fallbackMarker, ...keptMessages];
+        const fallbackMessages = buildCandidate(remainingMessages.slice(evenMaxRemove), makeMarker());
         validateRoleAlternation(fallbackMessages);
         return {
             truncated: true,

package/dist/core/conversationMemoryManager.js

@@ -89,7 +89,14 @@ export class ConversationMemoryManager {
                 if (options.events && options.events.length > 0) {
                     assistantMsg.events = options.events;
                 }
-                session.messages.push(userMsg, assistantMsg);
+                session.messages.push(userMsg);
+                // Pinned skill activations ride between ask and answer, mirroring
+                // the actual order (ask → skill loaded → answer). Stored verbatim —
+                // skill instructions are never truncated.
+                if (options.skillMessages && options.skillMessages.length > 0) {
+                    session.messages.push(...options.skillMessages);
+                }
+                session.messages.push(assistantMsg);
                 session.lastActivity = Date.now();
                 // Store API-reported token counts if available
                 if (options.tokenUsage) {
@@ -275,7 +282,11 @@ export class ConversationMemoryManager {
     async getStats() {
         await this.ensureInitialized();
         const sessions = Array.from(this.sessions.values());
-        const totalTurns = sessions.reduce((sum, session) => sum + session.messages.length / MESSAGES_PER_TURN, 0);
+        // Pinned skill messages are extra rows inside a turn — exclude them so
+        // a skill-activating turn still counts as one turn.
+        const totalTurns = sessions.reduce((sum, session) => sum +
+            session.messages.filter((msg) => !msg.metadata?.isSkill).length /
+                MESSAGES_PER_TURN, 0);
         return {
             totalSessions: sessions.length,
             totalTurns,

package/dist/core/redisConversationMemoryManager.js

@@ -457,6 +457,12 @@ export class RedisConversationMemoryManager {
                 };
                 conversation.messages.push(userMsg);
                 await this.flushPendingToolData(conversation, options.sessionId, normalizedUserId);
+                // Pinned skill activations ride between ask and answer, mirroring
+                // the actual order (ask → skill loaded → answer). Stored verbatim —
+                // skill instructions are never truncated.
+                if (options.skillMessages && options.skillMessages.length > 0) {
+                    conversation.messages.push(...options.skillMessages);
+                }
                 const assistantMsg = {
                     id: randomUUID(),
                     timestamp: this.generateTimestamp(),
@@ -1097,7 +1103,10 @@ User message: "${userMessage}"`;
             const conversationData = await this.redisClient.get(key);
             const conversation = deserializeConversation(conversationData);
             if (conversation?.messages) {
-                totalTurns += conversation.messages.length / MESSAGES_PER_TURN;
+                // Pinned skill messages are extra rows inside a turn — exclude them
+                // so a skill-activating turn still counts as one turn.
+                totalTurns +=
+                    conversation.messages.filter((msg) => !msg.metadata?.isSkill).length / MESSAGES_PER_TURN;
             }
         }
         return {

package/dist/lib/context/contextCompactor.js

@@ -26,7 +26,7 @@ const DEFAULT_CONFIG = {
     enableTruncate: true,
     pruneProtectTokens: 40_000,
     pruneMinimumSavings: 500,
-    pruneProtectedTools: ["skill"],
+    pruneProtectedTools: ["skill", "use_skill", "read_skill_resource"],
     summarizationProvider: "vertex",
     summarizationModel: "gemini-2.5-flash",
     keepRecentRatio: 0.3,
@@ -120,7 +120,21 @@ export class ContextCompactor {
                             targetTokens,
                         }), 120_000, "LLM summarization timed out after 120s");
                         if (summarizeResult.summarized) {
-                            currentMessages = summarizeResult.messages;
+                            // Pinned skill instructions must survive summarization:
+                            // re-seat any that the summarized region swallowed right
+                            // after the summary message (index 0 of the result).
+                            const survivorIds = new Set(summarizeResult.messages.map((m) => m.id));
+                            const swallowedSkills = currentMessages.filter((m) => m.metadata?.isSkill && !survivorIds.has(m.id));
+                            currentMessages =
+                                swallowedSkills.length > 0
+                                    ? summarizeResult.messages.length > 0
+                                        ? [
+                                            summarizeResult.messages[0],
+                                            ...swallowedSkills,
+                                            ...summarizeResult.messages.slice(1),
+                                        ]
+                                        : swallowedSkills
+                                    : summarizeResult.messages;
                             stagesUsed.push("summarize");
                         }
                         const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);

package/dist/lib/context/stages/slidingWindowTruncator.js

@@ -58,8 +58,10 @@ function truncateSmallConversation(messages, config) {
     let totalSaved = 0;
     for (let i = 0; i < result.length; i++) {
         const msg = result[i];
-        // Don't truncate system/summary messages
-        if (msg.role === "system" || msg.metadata?.isSummary) {
+        // Don't truncate system/summary messages or pinned skill instructions
+        if (msg.role === "system" ||
+            msg.metadata?.isSummary ||
+            msg.metadata?.isSkill) {
             continue;
         }
         const proportionalBudget = Math.floor((msgTokens[i] / totalContentTokens) * contentBudget);
@@ -93,8 +95,40 @@ function truncateSmallConversation(messages, config) {
     return { truncated: false, messages, messagesRemoved: 0 };
 }
 export function truncateWithSlidingWindow(messages, config) {
-    if (messages.length <= 4) {
-        // Delegate to content truncation for small conversations (BUG-005)
+    // Partition pinned skill messages out so the pair-based arithmetic below
+    // runs on the alternating user/assistant stream (skill pins are extra
+    // user-role messages inside a turn and would misalign every even-count
+    // cut). Each skill anchors to the next conversational message; kept
+    // anchors put their skills back in place, dropped anchors re-seat them
+    // after the truncation marker.
+    const skillsByAnchor = new Map();
+    const trailingSkills = [];
+    const conversational = [];
+    for (let i = 0; i < messages.length; i++) {
+        const msg = messages[i];
+        if (!msg.metadata?.isSkill) {
+            conversational.push(msg);
+            continue;
+        }
+        const anchor = messages
+            .slice(i + 1)
+            .find((next) => !next.metadata?.isSkill);
+        if (anchor) {
+            const anchored = skillsByAnchor.get(anchor.id);
+            if (anchored) {
+                anchored.push(msg);
+            }
+            else {
+                skillsByAnchor.set(anchor.id, [msg]);
+            }
+        }
+        else {
+            trailingSkills.push(msg);
+        }
+    }
+    if (conversational.length <= 4) {
+        // Delegate to content truncation for small conversations (BUG-005);
+        // it never removes messages, so skills keep their positions.
         return truncateSmallConversation(messages, config);
     }
     // ADAPTIVE MODE: calculate fraction from actual overage (PERF-001)
@@ -118,8 +152,42 @@ export function truncateWithSlidingWindow(messages, config) {
         fraction = config?.fraction ?? 0.5;
     }
     // Always preserve first user-assistant pair
-    const firstPair = messages.slice(0, 2);
-    const remainingMessages = messages.slice(2);
+    const firstPair = conversational.slice(0, 2);
+    const remainingMessages = conversational.slice(2);
+    /** Reassemble a candidate: skills inline before kept anchors, orphans after the marker. */
+    const buildCandidate = (keptAfterTruncation, marker) => {
+        const keptIds = new Set([...firstPair, ...keptAfterTruncation].map((m) => m.id));
+        const orphanedSkills = [];
+        for (const [anchorId, anchored] of skillsByAnchor) {
+            if (!keptIds.has(anchorId)) {
+                orphanedSkills.push(...anchored);
+            }
+        }
+        const withInlineSkills = (msg) => {
+            const anchored = skillsByAnchor.get(msg.id);
+            return anchored ? [...anchored, msg] : [msg];
+        };
+        return [
+            ...firstPair.flatMap(withInlineSkills),
+            marker,
+            ...orphanedSkills,
+            ...keptAfterTruncation.flatMap(withInlineSkills),
+            ...trailingSkills,
+        ];
+    };
+    // Insert a truncation marker with machine-readable metadata so
+    // effectiveHistory.ts can detect it via isTruncationMarker /
+    // truncationId and removeTruncationTags can rewind it.
+    const makeMarker = () => {
+        const truncId = randomUUID();
+        return {
+            id: `truncation-marker-${truncId}`,
+            role: "user",
+            content: TRUNCATION_MARKER_CONTENT,
+            isTruncationMarker: true,
+            truncationId: truncId,
+        };
+    };
     // ITERATIVE: if first pass isn't enough, increase fraction
     const maxIterations = config?.maxIterations ?? 3;
     let currentFraction = fraction;
@@ -129,19 +197,7 @@ export function truncateWithSlidingWindow(messages, config) {
         if (evenRemoveCount <= 0) {
             break;
         }
-        const keptAfterTruncation = remainingMessages.slice(evenRemoveCount);
-        // Insert a truncation marker with machine-readable metadata so
-        // effectiveHistory.ts can detect it via isTruncationMarker /
-        // truncationId and removeTruncationTags can rewind it.
-        const truncId = randomUUID();
-        const marker = {
-            id: `truncation-marker-${truncId}`,
-            role: "user",
-            content: TRUNCATION_MARKER_CONTENT,
-            isTruncationMarker: true,
-            truncationId: truncId,
-        };
-        const candidateMessages = [...firstPair, marker, ...keptAfterTruncation];
+        const candidateMessages = buildCandidate(remainingMessages.slice(evenRemoveCount), makeMarker());
         validateRoleAlternation(candidateMessages);
         // If we have token targets, verify the result fits
         if (config?.targetTokens) {
@@ -168,17 +224,7 @@ export function truncateWithSlidingWindow(messages, config) {
     const maxRemove = Math.floor(remainingMessages.length * 0.95);
     const evenMaxRemove = maxRemove - (maxRemove % 2);
     if (evenMaxRemove > 0) {
-        const keptMessages = remainingMessages.slice(evenMaxRemove);
-        // Insert a truncation marker (see iterative block above)
-        const fallbackTruncId = randomUUID();
-        const fallbackMarker = {
-            id: `truncation-marker-${fallbackTruncId}`,
-            role: "user",
-            content: TRUNCATION_MARKER_CONTENT,
-            isTruncationMarker: true,
-            truncationId: fallbackTruncId,
-        };
-        const fallbackMessages = [...firstPair, fallbackMarker, ...keptMessages];
+        const fallbackMessages = buildCandidate(remainingMessages.slice(evenMaxRemove), makeMarker());
         validateRoleAlternation(fallbackMessages);
         return {
             truncated: true,

package/dist/lib/core/conversationMemoryManager.js

@@ -89,7 +89,14 @@ export class ConversationMemoryManager {
                 if (options.events && options.events.length > 0) {
                     assistantMsg.events = options.events;
                 }
-                session.messages.push(userMsg, assistantMsg);
+                session.messages.push(userMsg);
+                // Pinned skill activations ride between ask and answer, mirroring
+                // the actual order (ask → skill loaded → answer). Stored verbatim —
+                // skill instructions are never truncated.
+                if (options.skillMessages && options.skillMessages.length > 0) {
+                    session.messages.push(...options.skillMessages);
+                }
+                session.messages.push(assistantMsg);
                 session.lastActivity = Date.now();
                 // Store API-reported token counts if available
                 if (options.tokenUsage) {
@@ -275,7 +282,11 @@ export class ConversationMemoryManager {
     async getStats() {
         await this.ensureInitialized();
         const sessions = Array.from(this.sessions.values());
-        const totalTurns = sessions.reduce((sum, session) => sum + session.messages.length / MESSAGES_PER_TURN, 0);
+        // Pinned skill messages are extra rows inside a turn — exclude them so
+        // a skill-activating turn still counts as one turn.
+        const totalTurns = sessions.reduce((sum, session) => sum +
+            session.messages.filter((msg) => !msg.metadata?.isSkill).length /
+                MESSAGES_PER_TURN, 0);
         return {
             totalSessions: sessions.length,
             totalTurns,

package/dist/lib/core/redisConversationMemoryManager.js

@@ -457,6 +457,12 @@ export class RedisConversationMemoryManager {
                 };
                 conversation.messages.push(userMsg);
                 await this.flushPendingToolData(conversation, options.sessionId, normalizedUserId);
+                // Pinned skill activations ride between ask and answer, mirroring
+                // the actual order (ask → skill loaded → answer). Stored verbatim —
+                // skill instructions are never truncated.
+                if (options.skillMessages && options.skillMessages.length > 0) {
+                    conversation.messages.push(...options.skillMessages);
+                }
                 const assistantMsg = {
                     id: randomUUID(),
                     timestamp: this.generateTimestamp(),
@@ -1097,7 +1103,10 @@ User message: "${userMessage}"`;
             const conversationData = await this.redisClient.get(key);
             const conversation = deserializeConversation(conversationData);
             if (conversation?.messages) {
-                totalTurns += conversation.messages.length / MESSAGES_PER_TURN;
+                // Pinned skill messages are extra rows inside a turn — exclude them
+                // so a skill-activating turn still counts as one turn.
+                totalTurns +=
+                    conversation.messages.filter((msg) => !msg.metadata?.isSkill).length / MESSAGES_PER_TURN;
             }
         }
         return {

package/dist/lib/neurolink.d.ts

@@ -274,7 +274,7 @@ export declare class NeuroLink {
      */
     private ensureSkillsReady;
     /**
-     * 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
@@ -282,11 +282,36 @@ export declare class NeuroLink {
      */
     private registerSkillTools;
     /**
-     * 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.
-     */
-    private applySkillsPromptIndex;
+     * 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.
+     */
+    private applySkillsAugmentation;
+    /** Session id for skill activation tracking, from the call context. */
+    private resolveSkillSessionId;
+    /** User id for skill-session hydration (Redis keys sessions by userId). */
+    private resolveSkillUserId;
+    /**
+     * 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).
+     */
+    private preloadSkills;
+    /**
+     * Pinned skill messages recorded during this turn, ready for
+     * StoreConversationTurnOptions.skillMessages. Empty when skills are off
+     * or nothing was activated.
+     */
+    private drainPendingSkillMessages;
     /**
      * Programmatic access to the skills subsystem (search/list/get/mutations).
      * Returns null when skills are not configured or failed to initialize.