@juspay/neurolink 9.85.1 → 9.86.0

package/dist/skills/skillsManager.js

@@ -8,11 +8,13 @@
  */
 import { randomUUID } from "node:crypto";
 import { logger } from "../utils/logger.js";
-import { filterSkillIndex, formatSkillsPromptIndex } from "./skillMatcher.js";
+import { filterSkillIndex, formatSkillsPromptIndex, renderSkillListing, sortSkillIndex, } from "./skillMatcher.js";
+import { SkillSessionTracker } from "./skillSessionTracker.js";
 import { createSkillStore } from "./skillStores.js";
 const DEFAULT_MAX_MATCHES = 5;
 const DEFAULT_PROMPT_INDEX_MAX_ITEMS = 50;
 const DEFAULT_INDEX_CACHE_TTL_MS = 30_000;
+const DEFAULT_LISTING_BUDGET_CHARS = 15_000;
 export class SkillsManager {
     config;
     store;
@@ -20,11 +22,17 @@ export class SkillsManager {
     cachedIndexAt = 0;
     /** Serializes writes within this process — see requestMutation(). */
     mutationQueue = Promise.resolve();
+    /** Per-session activation state (pinned skills). */
+    sessions = new SkillSessionTracker();
     constructor(config) {
         this.config = config;
         this.store = createSkillStore(config.storage);
     }
-    /** Cached index read. TTL 0 disables caching. */
+    /**
+     * Cached index read, sorted by name. TTL 0 disables caching. Sorting
+     * here (not per render) keeps every downstream listing byte-stable
+     * regardless of store enumeration order.
+     */
     async getIndex(forceRefresh = false) {
         const ttl = this.config.indexCacheTtlMs ?? DEFAULT_INDEX_CACHE_TTL_MS;
         const fresh = this.cachedIndex !== null &&
@@ -33,7 +41,7 @@ export class SkillsManager {
         if (fresh && !forceRefresh && this.cachedIndex) {
             return this.cachedIndex;
         }
-        const index = await this.store.index();
+        const index = sortSkillIndex(await this.store.index());
         this.cachedIndex = index;
         this.cachedIndexAt = Date.now();
         return index;
@@ -87,12 +95,46 @@ export class SkillsManager {
      * nothing is visible. Never includes instructions.
      */
     async buildPromptIndex(options) {
+        const items = await this.visibleItems(options);
+        return formatSkillsPromptIndex(items, this.config.promptIndexMaxItems ?? DEFAULT_PROMPT_INDEX_MAX_ITEMS);
+    }
+    /**
+     * Render the `<available_skills>` block for the use_skill tool
+     * description ("tool" discovery mode), or null when nothing is visible.
+     * Bounded by listingBudgetChars; entries are never dropped.
+     */
+    async buildToolListing(options) {
+        const items = await this.visibleItems(options);
+        return renderSkillListing(items, this.config.listingBudgetChars ?? DEFAULT_LISTING_BUDGET_CHARS);
+    }
+    /** Visible (active, scope- and tag-filtered) index entries for one call. */
+    async visibleItems(options) {
         let items = await this.list(options?.scopeId);
         if (options?.tags && options.tags.length > 0) {
             const wanted = options.tags.map((t) => t.toLowerCase());
             items = items.filter((item) => (item.tags ?? []).some((t) => wanted.includes(t.toLowerCase())));
         }
-        return formatSkillsPromptIndex(items, this.config.promptIndexMaxItems ?? DEFAULT_PROMPT_INDEX_MAX_ITEMS);
+        return items;
+    }
+    /**
+     * Read an auxiliary resource file bundled with a skill. Paths are
+     * relative to the skill; traversal segments are rejected. Null when the
+     * skill, the resource, or store resource support is absent.
+     */
+    async getResource(idOrName, resourcePath) {
+        const normalized = resourcePath.replace(/\\/g, "/");
+        if (normalized.startsWith("/") ||
+            normalized.split("/").some((segment) => segment === "..")) {
+            throw new Error(`Invalid resource path "${resourcePath}" — must be relative to the skill directory`);
+        }
+        if (!this.store.getResource) {
+            return null;
+        }
+        const skill = await this.get(idOrName);
+        if (!skill) {
+            return null;
+        }
+        return this.store.getResource(skill.id, normalized);
     }
     /**
      * Whether skill create/update/delete is enabled on this instance. Gates the

package/dist/types/config.d.ts

@@ -117,11 +117,11 @@ export type NeurolinkConstructorConfig = {
     classifierRouter?: ClassifierRouterConfig;
     /**
      * Native skills: versioned, discoverable instruction packs (SOPs,
-     * playbooks) with progressive disclosure. When enabled, built-in
-     * search_skills / list_skills tools are registered (plus gated mutation
-     * tools) and a compact skills index is injected into the system prompt
-     * of each generate()/stream() call. Opt-in and fails open on read paths.
-     * See {@link SkillsConfig}.
+     * playbooks) with progressive disclosure. When enabled, each
+     * generate()/stream() call gets a skills discovery listing plus
+     * use_skill / read_skill_resource tools; activated skill instructions
+     * pin to the session so they are loaded once and replayed from history.
+     * Opt-in and fails open on read paths. See {@link SkillsConfig}.
      */
     skills?: SkillsConfig;
 };

package/dist/types/conversation.d.ts

@@ -250,6 +250,20 @@ export type ChatMessageMetadata = {
      * payload from the local artifact store.
      */
     artifactId?: string;
+    /**
+     * Marks a pinned skill-activation message: the full instructions of a
+     * skill loaded via use_skill, persisted into session history so later
+     * turns replay it verbatim instead of re-fetching the skill. Pinned
+     * skill messages are protected from sliding-window truncation and are
+     * re-included after memory summarization.
+     */
+    isSkill?: boolean;
+    /** Skill id of a pinned skill-activation message. */
+    skillId?: string;
+    /** Skill name of a pinned skill-activation message. */
+    skillName?: string;
+    /** Skill version captured at activation (sessions pin the activated version). */
+    skillVersion?: number;
 };
 /**
  * Chat message format for conversation history
@@ -383,6 +397,19 @@ export type StoreConversationTurnOptions = {
     };
     /** Gemini 3 thought signature for reasoning continuity across turns */
     thoughtSignature?: string;
+    /**
+     * Pinned skill-activation messages (skills v2) recorded during this turn.
+     * Inserted between the user and assistant messages so replayed history
+     * mirrors the actual order: ask → skill loaded → answer. Stored verbatim —
+     * skill instructions are never truncated.
+     *
+     * Invariant for history consumers: a skill-bearing turn is a
+     * user → skill(user-role, metadata.isSkill) → assistant triplet, so
+     * stored history is NOT strictly pair-wise alternating. Pair-based
+     * logic must filter `metadata.isSkill` first (see slidingWindowTruncator
+     * for the canonical partition-and-reanchor pattern).
+     */
+    skillMessages?: ChatMessage[];
 };
 /**
  * Lightweight session metadata for efficient session listing

package/dist/types/skills.d.ts

@@ -6,15 +6,28 @@
  *
  * Architecture mirrors the Hippocampus memory subsystem: a `skills` config
  * on the NeuroLink constructor lazily initializes a SkillsManager, which
- * auto-registers built-in tools (search_skills / list_skills, plus gated
- * mutation tools) and optionally injects a compact skills index into the
- * system prompt of each generate()/stream() call.
+ * auto-registers built-in tools (list_skills, plus gated mutation tools)
+ * and augments each generate()/stream() call with the discovery listing
+ * plus per-call use_skill / read_skill_resource tools.
  *
  * Naming: every exported type carries a `Skill` prefix to satisfy the
  * `unique-type-names` ESLint rule.
  */
+import type { ChatMessage } from "./conversation.js";
 /** Visibility of a skill: available everywhere, or only in specific scopes. */
 export type SkillScopeKind = "global" | "scoped";
+/**
+ * Reference to an auxiliary file bundled with a skill (progressive
+ * disclosure level 3). Resources are read into context on demand via the
+ * read_skill_resource tool — a skill's SKILL.md should stay lean and point
+ * to resources for rarely-needed detail.
+ */
+export type SkillResourceRef = {
+    /** Path relative to the skill's directory, e.g. "references/edge-cases.md". */
+    path: string;
+    /** Size in bytes when known (listing hint only). */
+    size?: number;
+};
 /** Lifecycle status. Deletes are soft — deprecated skills stay in storage. */
 export type SkillLifecycleStatus = "active" | "deprecated";
 /**
@@ -47,6 +60,12 @@ export type SkillDefinition = {
     createdAt?: string;
     /** ISO timestamp of last update. */
     updatedAt?: string;
+    /**
+     * Auxiliary files bundled with the skill, readable on demand through
+     * read_skill_resource. Populated by stores that support resources
+     * (directory-layout filesystem skills, S3, Redis).
+     */
+    resources?: SkillResourceRef[];
     /** Free-form host metadata (audit fields, approval references, …). */
     metadata?: Record<string, unknown>;
 };
@@ -69,12 +88,24 @@ export type SkillStore = {
     index(): Promise<SkillIndexItem[]>;
     /** Optional: drop any internal caches (called after mutations). */
     invalidate?(): void;
+    /**
+     * Optional: fetch an auxiliary resource file bundled with a skill.
+     * `resourcePath` is relative to the skill (e.g. "references/forms.md").
+     * Null when the skill or resource is absent. Stores without resource
+     * support simply omit this method.
+     */
+    getResource?(id: string, resourcePath: string): Promise<string | null>;
 };
 /** In-process store, optionally seeded. Good for tests and embedded use. */
 export type SkillMemoryStorageConfig = {
     type: "memory";
     /** Initial skills to seed the store with. */
     skills?: SkillDefinition[];
+    /**
+     * Resource file contents keyed by skill id → relative path.
+     * E.g. `{ "my-skill": { "references/forms.md": "..." } }`.
+     */
+    resources?: Record<string, Record<string, string>>;
 };
 /**
  * Directory-backed store. Reads three layouts:
@@ -154,6 +185,15 @@ export type SkillS3IndexDocument = {
     lastUpdated: string;
     skills: SkillIndexItem[];
 };
+/** Result of a conditional (ETag) object read. */
+export type SkillS3ConditionalGetResult = {
+    /** Object body; null when the key is absent. */
+    body: string | null;
+    /** ETag of the returned body, for the next conditional read. */
+    etag?: string;
+    /** True when the object is unchanged since the supplied ETag (no body). */
+    notModified?: boolean;
+};
 /**
  * Minimal object-storage operations the S3 skill store runs on. The
  * default implementation is created lazily from @aws-sdk/client-s3;
@@ -166,9 +206,15 @@ export type SkillS3ObjectOps = {
     deleteObject(key: string): Promise<void>;
     /** List all object keys under a prefix (paginated internally). */
     listKeys(prefix: string): Promise<string[]>;
+    /**
+     * Optional: ETag-conditional read (If-None-Match). Used for index.json
+     * refreshes so an unchanged index costs a 304 instead of a full download.
+     * Ops without it fall back to plain getObject.
+     */
+    getObjectConditional?(key: string, etag?: string): Promise<SkillS3ConditionalGetResult>;
 };
 export type SkillsStorageConfig = SkillMemoryStorageConfig | SkillFilesystemStorageConfig | SkillS3StorageConfig | SkillRedisStorageConfig | SkillCustomStorageConfig;
-/** Query accepted by SkillsManager.search() and the search_skills tool. */
+/** Query accepted by SkillsManager.search() (programmatic + CLI search). */
 export type SkillSearchQuery = {
     /** Keyword matched (case-insensitive substring) against name, displayName, and description. */
     query?: string;
@@ -239,14 +285,38 @@ export type SkillsConfig = {
     /** Persistence backend. Default: `{ type: "memory" }`. */
     storage?: SkillsStorageConfig;
     /**
-     * Inject a compact skills index (names + descriptions, never instructions)
-     * into the system prompt of each generate()/stream() call. Default: true.
-     * Set false for curator-style pure tool-driven disclosure.
+     * Where the skills listing (names + descriptions, never instructions)
+     * surfaces for model-driven discovery:
+     *  - "tool" (default): an `<available_skills>` block embedded in the
+     *    use_skill tool description — the Claude Code pattern. Keeps the
+     *    host's system prompt untouched and the listing cache-stable.
+     *  - "system-prompt": a "## Available Skills" index appended to the
+     *    system prompt instead.
+     *  - "none": no listing anywhere; discovery only via list_skills.
+     */
+    discovery?: SkillDiscoveryMode;
+    /**
+     * Character budget for the "tool" discovery listing. When the full
+     * listing exceeds it, every description is shortened uniformly (first
+     * sentence, then a hard cap) so the render stays a pure function of the
+     * index — byte-stable across calls; names are never dropped.
+     * Default: 15000.
      */
-    promptIndex?: boolean;
+    listingBudgetChars?: number;
+    /**
+     * Pin activated skill instructions into session history so later turns
+     * replay them verbatim (byte-stable, provider-cacheable) instead of
+     * re-fetching the skill. Requires conversation memory + a sessionId on
+     * the call. Default: true.
+     */
+    sessionPersistence?: boolean;
     /** Maximum skills hydrated (with instructions) per search. Default: 5. */
     maxMatches?: number;
-    /** Maximum entries rendered in the prompt index before truncation. Default: 50. */
+    /**
+     * Maximum entries rendered by the "system-prompt" discovery mode before
+     * truncation. Default: 50. The "tool" mode is bounded by
+     * listingBudgetChars instead and never drops entries.
+     */
     promptIndexMaxItems?: number;
     /** Index cache TTL in milliseconds. Default: 30000. 0 disables caching. */
     indexCacheTtlMs?: number;
@@ -265,6 +335,30 @@ export type SkillsConfig = {
      */
     onMutationRequest?: (action: SkillMutationAction) => Promise<SkillMutationDecision>;
 };
+/** Where the skills discovery listing surfaces. See SkillsConfig.discovery. */
+export type SkillDiscoveryMode = "tool" | "system-prompt" | "none";
+/**
+ * One activated skill in a session: which skill, at which version, when.
+ * Sessions pin the version active at activation time — a mid-session skill
+ * update never mutates instructions the model has already loaded.
+ */
+export type SkillActivationRecord = {
+    skillId: string;
+    name: string;
+    version: number;
+    /** ISO timestamp of activation. */
+    activatedAt: string;
+};
+/**
+ * Structural view of the per-session activation tracker consumed by the
+ * skill tools factory.
+ */
+export type SkillSessionStateLike = {
+    isActive: (sessionId: string, skillId: string, name: string) => boolean;
+    getActivation: (sessionId: string, skillId: string, name?: string) => SkillActivationRecord | undefined;
+    recordActivation: (sessionId: string, skill: SkillDefinition) => ChatMessage;
+    hydrate: (sessionId: string, storedMessages: ChatMessage[]) => void;
+};
 /**
  * Structural view of SkillsManager consumed by the skill tools factory —
  * keeps skillTools.ts decoupled from the concrete manager class.
@@ -272,8 +366,38 @@ export type SkillsConfig = {
 export type SkillsManagerLike = {
     search: (query: SkillSearchQuery) => Promise<SkillDefinition[]>;
     list: (scopeId?: string) => Promise<SkillIndexItem[]>;
+    get: (idOrName: string) => Promise<SkillDefinition | null>;
+    getResource: (idOrName: string, resourcePath: string) => Promise<string | null>;
+    sessions: SkillSessionStateLike;
     requestMutation: (action: SkillMutationAction) => Promise<SkillMutationResult>;
 };
+/**
+ * Per-call context bound into the use_skill / read_skill_resource tools at
+ * injection time (prepareGenerate/prepareStream). The sessionId is captured
+ * by closure so activation state is tracked without relying on runtime tool
+ * context plumbing.
+ */
+export type SkillCallToolsContext = {
+    /** Session the call belongs to; absent → activation state is per-turn only. */
+    sessionId?: string;
+    /** Scope filter applied when resolving skills for this call. */
+    scopeId?: string;
+    /**
+     * Pin activated instructions into session history after the turn.
+     * Mirrors SkillsConfig.sessionPersistence resolved for this call.
+     */
+    sessionPersistence: boolean;
+    /** Discovery mode resolved for this call — shapes the use_skill description. */
+    discovery: SkillDiscoveryMode;
+    /** Rendered `<available_skills>` block for "tool" discovery; null when empty. */
+    listing?: string | null;
+    /**
+     * Stored session history loader used to hydrate activation state before
+     * every dedup check (restart/multi-instance/failed-persistence safety).
+     * Invoked once per use_skill / read_skill_resource attempt.
+     */
+    getStoredMessages?: (sessionId: string) => Promise<ChatMessage[]>;
+};
 /** Options for the createSkillTools factory. */
 export type SkillToolsOptions = {
     /** Include skill_create / skill_update / skill_delete. Default: false. */
@@ -285,12 +409,19 @@ export type SkillToolsOptions = {
  * config (same precedence convention as per-call credentials).
  */
 export type SkillsCallOptions = {
-    /** Master toggle for this call (prompt index only — tools stay registered). Default: true. */
+    /** Master toggle for this call (listing + per-call tools). Default: true. */
     enabled?: boolean;
-    /** Per-call override of SkillsConfig.promptIndex. */
-    promptIndex?: boolean;
-    /** Scope filter for the prompt index on this call. Overrides defaultScopeId. */
+    /** Per-call override of SkillsConfig.discovery. */
+    discovery?: SkillDiscoveryMode;
+    /** Scope filter for the listing and skill resolution on this call. Overrides defaultScopeId. */
     scopeId?: string;
-    /** Restrict the prompt index to skills carrying at least one of these tags. */
+    /** Restrict the listing to skills carrying at least one of these tags. */
     tags?: string[];
+    /**
+     * Skill names to activate at the start of this call: their full
+     * instructions are injected up front (and pinned to the session when
+     * sessionPersistence is on), without waiting for the model to invoke
+     * use_skill. Already-active skills are skipped.
+     */
+    preload?: string[];
 };

package/dist/types/skills.js

@@ -6,9 +6,9 @@
  *
  * Architecture mirrors the Hippocampus memory subsystem: a `skills` config
  * on the NeuroLink constructor lazily initializes a SkillsManager, which
- * auto-registers built-in tools (search_skills / list_skills, plus gated
- * mutation tools) and optionally injects a compact skills index into the
- * system prompt of each generate()/stream() call.
+ * auto-registers built-in tools (list_skills, plus gated mutation tools)
+ * and augments each generate()/stream() call with the discovery listing
+ * plus per-call use_skill / read_skill_resource tools.
  *
  * Naming: every exported type carries a `Skill` prefix to satisfy the
  * `unique-type-names` ESLint rule.

package/dist/utils/conversationMemory.d.ts

@@ -28,7 +28,7 @@ export declare function getConversationMessages(conversationMemory: Conversation
  * Store conversation turn for future context
  * Saves user messages and AI responses for conversation memory
  */
-export declare function storeConversationTurn(conversationMemory: ConversationMemoryManager | RedisConversationMemoryManager | null | undefined, originalOptions: TextGenerationOptions, result: TextGenerationResult, startTimeStamp?: Date | undefined, requestId?: string): Promise<void>;
+export declare function storeConversationTurn(conversationMemory: ConversationMemoryManager | RedisConversationMemoryManager | null | undefined, originalOptions: TextGenerationOptions, result: TextGenerationResult, startTimeStamp?: Date | undefined, requestId?: string, skillMessages?: ChatMessage[]): Promise<void>;
 /**
  * Build context messages from pointer onwards (token-based memory)
  * Returns summary message (if exists) + all messages after the summarized pointer

package/dist/utils/conversationMemory.js

@@ -227,7 +227,7 @@ export async function getConversationMessages(conversationMemory, options) {
  * Store conversation turn for future context
  * Saves user messages and AI responses for conversation memory
  */
-export async function storeConversationTurn(conversationMemory, originalOptions, result, startTimeStamp, requestId) {
+export async function storeConversationTurn(conversationMemory, originalOptions, result, startTimeStamp, requestId, skillMessages) {
     logger.debug("[conversationMemoryUtils] storeConversationTurn called", {
         requestId,
         hasMemory: !!conversationMemory,
@@ -369,6 +369,9 @@ export async function storeConversationTurn(conversationMemory, originalOptions,
                 enableSummarization: originalOptions.enableSummarization,
                 requestId,
                 events: toolActivityEvents,
+                ...(skillMessages && skillMessages.length > 0
+                    ? { skillMessages }
+                    : {}),
                 tokenUsage: result.usage
                     ? {
                         inputTokens: result.usage.input,
@@ -450,6 +453,12 @@ export function buildContextFromPointer(session, requestId) {
         return session.messages;
     }
     const messagesAfterPointer = session.messages.slice(pointerIndex + 1);
+    // Pinned skill instructions must survive summarization: any skill message
+    // that fell behind the pointer is re-included verbatim after the summary,
+    // so an activated skill keeps its full instructions for the whole session.
+    const pinnedSkillMessages = session.messages
+        .slice(0, pointerIndex + 1)
+        .filter((msg) => msg.metadata?.isSkill);
     // Construct context: summary message + recent messages
     const summaryMessage = {
         id: `summary-${session.summarizedUpToMessageId}`,
@@ -468,7 +477,11 @@ export function buildContextFromPointer(session, requestId) {
         totalMessages: session.messages.length,
         summaryLength: session.summarizedMessage.length,
     });
-    const contextMessages = [summaryMessage, ...messagesAfterPointer];
+    const contextMessages = [
+        summaryMessage,
+        ...pinnedSkillMessages,
+        ...messagesAfterPointer,
+    ];
     // Log context built for LLM with structural metadata
     const totalChars = contextMessages.reduce((sum, msg) => sum + msg.content.length, 0);
     logger.info("[ConversationMemory] Context built for LLM", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "9.85.1",
+  "version": "9.86.0",
   "packageManager": "pnpm@10.15.1",
   "description": "Universal AI Development Platform with working MCP integration, multi-provider support, voice (TTS/STT/realtime), and professional CLI. 58+ external MCP servers discoverable, multimodal file processing, RAG pipelines. Build, test, and deploy AI applications with 21+ providers: OpenAI, Anthropic, Google AI Studio, Google Vertex, AWS Bedrock, Azure OpenAI, Mistral, LiteLLM, SageMaker, Hugging Face, Ollama, OpenAI-compatible, OpenRouter, DeepSeek, NVIDIA NIM, LM Studio, llama.cpp, plus voice (OpenAI TTS, ElevenLabs, Deepgram, Azure Speech).",
   "author": {