@juspay/neurolink 9.85.1 → 9.86.0

package/dist/lib/skills/skillTools.js

@@ -1,126 +1,240 @@
 /**
- * Built-in skill tools, following the createMemoryRetrievalTools /
- * createFileTools / createTaskTools factory pattern.
+ * Built-in skill tools.
+ *
+ * Two factories, mirroring the two disclosure levels:
+ *
+ * createSkillTools — instance tools registered once at construction:
+ *   list_skills (lightweight catalog) plus the gated skill_create /
+ *   skill_update / skill_delete mutation tools.
+ *
+ * createSkillCallTools — per-call tools injected into options.tools by
+ *   prepareGenerate/prepareStream (the RAG-tool pattern): use_skill, whose
+ *   description embeds the `<available_skills>` listing so the model
+ *   decides from context when a skill applies (no mandatory pre-flight
+ *   call), and read_skill_resource for on-demand auxiliary files. The
+ *   sessionId rides in by closure, so activations pin to the session
+ *   without runtime tool-context plumbing.
  *
  * The manager is resolved lazily via a resolver callback so tools can be
  * registered at construction time while the store initializes on first
  * use (mirrors how retrieve_context resolves conversationMemory lazily).
- *
- * Tool descriptions are ported from curator's production skills tools —
- * the "always check skills first / no_match is expected, not an error /
- * pick the best of 2-5 or ask" prompt engineering is proven in prod.
  */
+import { trace } from "@opentelemetry/api";
 import { z } from "zod";
 import { logger } from "../utils/logger.js";
 import { tool } from "../utils/tool.js";
-/** Trim a hydrated skill to the fields the model needs. */
-function toToolSkill(skill) {
+import { isSkillVisibleInScope } from "./skillMatcher.js";
+const NOT_CONFIGURED = {
+    success: false,
+    error: "Skills are not available — the skills store failed to initialize. " +
+        "Answer from general knowledge.",
+};
+/** Response payload for an activated skill — full instructions, never truncated. */
+function toActivationPayload(skill) {
     return {
-        id: skill.id,
         name: skill.name,
         ...(skill.displayName ? { displayName: skill.displayName } : {}),
-        description: skill.description,
-        instructions: skill.instructions,
-        tags: skill.tags ?? [],
-        scope: skill.scope ?? "global",
         version: skill.version ?? 1,
+        instructions: skill.instructions,
+        ...(skill.resources && skill.resources.length > 0
+            ? {
+                resources: skill.resources.map((r) => r.path),
+                resourcesHint: "Auxiliary files — read one with read_skill_resource only when the task needs it.",
+            }
+            : {}),
+        note: "Follow these instructions for the current task. The skill stays loaded " +
+            "for this conversation — do not invoke use_skill for it again.",
     };
 }
+/** Build the use_skill description for the call's discovery mode. */
+function useSkillDescription(context) {
+    const base = "Load a team-defined skill (SOP, playbook, workflow) by name to get its full instructions. " +
+        "When the user's task matches a skill, invoke this tool, then follow the loaded instructions exactly. " +
+        "Do NOT invoke it for a skill that is already loaded in this conversation, and do not " +
+        "invoke it at all when no skill matches the task.";
+    if (context.discovery === "tool" && context.listing) {
+        return `${base}\n\nSkills available in this conversation:\n${context.listing}`;
+    }
+    if (context.discovery === "system-prompt") {
+        return `${base} The available skills are listed under "## Available Skills" in your instructions.`;
+    }
+    return `${base} Discover available skills with list_skills.`;
+}
 /**
- * Create the built-in skill tools bound to a lazily-resolved manager.
- * Returns Vercel AI SDK tool() objects (description + Zod inputSchema +
- * execute) keyed by tool name.
+ * Per-call skill tools: use_skill + read_skill_resource. Injected into
+ * options.tools for one generate()/stream() call; same-name entries shadow
+ * any registered tool, so the description always reflects this call's
+ * listing and scope.
  */
-export function createSkillTools(resolveManager, options) {
-    const notConfigured = {
-        success: false,
-        error: "Skills are not available — the skills store failed to initialize. " +
-            "Answer from general knowledge.",
-        data: { skills: [] },
+export function createSkillCallTools(resolveManager, context) {
+    /**
+     * Rebuild activation state from stored history before every dedup
+     * check. use_skill is rare, so one history read per attempt is cheap —
+     * and it keeps dedup truthful across restarts, other instances sharing
+     * the memory backend, and pins whose persistence failed. Fail-open: a
+     * hydration error only risks a duplicate pin, never a lost activation.
+     */
+    const ensureHydrated = async (manager) => {
+        const { sessionId, getStoredMessages } = context;
+        if (!sessionId) {
+            return;
+        }
+        try {
+            const stored = getStoredMessages
+                ? await getStoredMessages(sessionId)
+                : [];
+            manager.sessions.hydrate(sessionId, stored);
+        }
+        catch (error) {
+            logger.warn("[SkillTools] Session hydration failed — continuing", {
+                sessionId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
     };
-    const tools = {
-        search_skills: tool({
-            description: "ALWAYS call this at the start of every user request before answering from general knowledge. " +
-                "Searches team-defined skills (SOPs, playbooks, workflows) using an index-first approach — " +
-                "fast, low-cost, and does not load skills that do not match. " +
-                "You MUST provide at least one of: query (keyword from the user message) or tag (domain category). " +
-                "If 1 match is found, follow its instructions exactly. " +
-                "If 2-5 matches are found, use your judgment based on the user message to pick the best one, " +
-                "or ask the user to clarify if the instructions would lead to meaningfully different actions. " +
-                "Only skip this call for purely conversational messages like greetings. " +
-                'Returns `{ skills: [], reason: "no_match" }` when nothing matches — this is expected, NOT an ' +
-                "error. In that case, answer from general knowledge.",
+    return {
+        use_skill: tool({
+            description: useSkillDescription(context),
             inputSchema: z.object({
-                query: z
-                    .string()
-                    .optional()
-                    .describe("Keyword from the user message, matched against skill name, display name, and description. " +
-                    'E.g. "deployment", "refund process", "on-call escalation".'),
-                tag: z
-                    .string()
-                    .optional()
-                    .describe('Domain category tag to narrow results (e.g. "payments", "devops"). ' +
-                    "Applied on top of the query filter when both are provided."),
-                scopeId: z
+                name: z
                     .string()
-                    .optional()
-                    .describe("Scope identifier (channel/team/tenant id) to include scoped skills alongside global ones. " +
-                    "Usually omit — the host default applies."),
+                    .min(1)
+                    .describe('Exact skill name from the available skills listing, e.g. "refund_dispute_escalation".'),
             }),
             execute: async (args) => {
-                if (!args.query && !args.tag) {
+                const manager = resolveManager();
+                if (!manager) {
+                    return NOT_CONFIGURED;
+                }
+                try {
+                    const skill = await manager.get(args.name);
+                    if (!skill || !isSkillVisibleInScope(skill, context.scopeId)) {
+                        return {
+                            success: false,
+                            error: `No skill named "${args.name}" is available. Use the exact name ` +
+                                "from the available skills listing (or list_skills).",
+                        };
+                    }
+                    if (context.sessionId && context.sessionPersistence) {
+                        await ensureHydrated(manager);
+                        if (manager.sessions.isActive(context.sessionId, skill.id, skill.name)) {
+                            // Report the version the session actually follows — a
+                            // mid-session update must not masquerade as loaded.
+                            const activation = manager.sessions.getActivation(context.sessionId, skill.id, skill.name);
+                            return {
+                                success: true,
+                                data: {
+                                    status: "already_loaded",
+                                    name: skill.name,
+                                    version: activation?.version ?? skill.version ?? 1,
+                                    message: "This skill is already loaded in the conversation — follow " +
+                                        "the instructions from when it was loaded.",
+                                },
+                            };
+                        }
+                        manager.sessions.recordActivation(context.sessionId, skill);
+                    }
+                    const pinned = Boolean(context.sessionId && context.sessionPersistence);
+                    trace.getActiveSpan()?.setAttributes({
+                        "skill.name": skill.name,
+                        "skill.version": skill.version ?? 1,
+                        "skill.instructions_chars": skill.instructions.length,
+                        "skill.pinned": pinned,
+                    });
+                    logger.debug("[SkillTools] Skill activated", {
+                        skill: skill.name,
+                        version: skill.version ?? 1,
+                        sessionId: context.sessionId,
+                        pinned,
+                    });
+                    return { success: true, data: toActivationPayload(skill) };
+                }
+                catch (error) {
+                    logger.warn("[SkillTools] use_skill failed", {
+                        skill: args.name,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
                     return {
                         success: false,
-                        error: 'At least one of "query" or "tag" must be provided to search_skills.',
-                        data: { skills: [] },
+                        error: error instanceof Error ? error.message : String(error),
                     };
                 }
+            },
+        }),
+        read_skill_resource: tool({
+            description: "Read an auxiliary file bundled with a loaded skill (paths appear in the " +
+                "skill's `resources` list or are referenced from its instructions). Load the " +
+                "skill with use_skill first. Only read files the current task actually needs — " +
+                "each resource costs context.",
+            inputSchema: z.object({
+                skill: z.string().min(1).describe("Name of the loaded skill."),
+                path: z
+                    .string()
+                    .min(1)
+                    .describe('Resource path relative to the skill, e.g. "references/forms.md".'),
+            }),
+            execute: async (args) => {
                 const manager = resolveManager();
                 if (!manager) {
-                    return notConfigured;
+                    return NOT_CONFIGURED;
                 }
                 try {
-                    const skills = await manager.search(args);
-                    if (skills.length === 0) {
+                    const skill = await manager.get(args.skill);
+                    if (!skill || !isSkillVisibleInScope(skill, context.scopeId)) {
                         return {
-                            success: true,
-                            data: {
-                                skills: [],
-                                reason: "no_match",
-                                message: `No skills found${args.query ? ` matching "${args.query}"` : ""}${args.tag ? ` with tag "${args.tag}"` : ""}. Answer from general knowledge.`,
-                            },
+                            success: false,
+                            error: `No skill named "${args.skill}" is available.`,
+                        };
+                    }
+                    if (context.sessionId && context.sessionPersistence) {
+                        await ensureHydrated(manager);
+                        if (!manager.sessions.isActive(context.sessionId, skill.id, skill.name)) {
+                            return {
+                                success: false,
+                                error: `Skill "${skill.name}" is not loaded — call use_skill first.`,
+                            };
+                        }
+                    }
+                    const content = await manager.getResource(skill.id, args.path);
+                    if (content === null) {
+                        return {
+                            success: false,
+                            error: `Resource "${args.path}" not found on skill "${skill.name}". ` +
+                                "Valid paths are listed in the skill's `resources`.",
                         };
                     }
                     return {
                         success: true,
-                        data: {
-                            skills: skills.map(toToolSkill),
-                            count: skills.length,
-                            ...(skills.length > 1
-                                ? {
-                                    hint: "Multiple skills matched. Pick the most relevant one for the user message, or ask the user to clarify.",
-                                }
-                                : {}),
-                        },
+                        data: { skill: skill.name, path: args.path, content },
                     };
                 }
                 catch (error) {
-                    logger.warn("[SkillTools] search_skills failed", {
+                    logger.warn("[SkillTools] read_skill_resource failed", {
+                        skill: args.skill,
+                        path: args.path,
                         error: error instanceof Error ? error.message : String(error),
                     });
                     return {
                         success: false,
                         error: error instanceof Error ? error.message : String(error),
-                        data: { skills: [] },
                     };
                 }
             },
         }),
+    };
+}
+/**
+ * Instance skill tools bound to a lazily-resolved manager: list_skills
+ * plus the gated mutation tools. Returns Vercel AI SDK tool() objects
+ * (description + Zod inputSchema + execute) keyed by tool name.
+ */
+export function createSkillTools(resolveManager, options) {
+    const tools = {
         list_skills: tool({
             description: "Returns a lightweight list of all available skills — name, display name, description, and " +
                 "tags only. No instructions are returned, keeping context cost minimal. " +
                 'Use this only when a user explicitly asks "what skills do you have?" or "what can you help ' +
-                'me with?". Do NOT use this for skill lookup before answering — use search_skills instead.',
+                'me with?". To load a skill for a task, use use_skill instead.',
             inputSchema: z.object({
                 scopeId: z
                     .string()
@@ -130,7 +244,7 @@ export function createSkillTools(resolveManager, options) {
             execute: async (args) => {
                 const manager = resolveManager();
                 if (!manager) {
-                    return notConfigured;
+                    return { ...NOT_CONFIGURED, data: { skills: [] } };
                 }
                 try {
                     const items = await manager.list(args.scopeId);
@@ -170,10 +284,7 @@ export function createSkillTools(resolveManager, options) {
 async function runMutation(resolveManager, action) {
     const manager = resolveManager();
     if (!manager) {
-        return {
-            success: false,
-            error: "Skills are not available — the skills store failed to initialize.",
-        };
+        return NOT_CONFIGURED;
     }
     try {
         const result = await manager.requestMutation(action);
@@ -285,8 +396,8 @@ function createSkillMutationTools(resolveManager) {
         skill_update: tool({
             description: "Propose an update to an EXISTING skill. Only the provided fields change; the version is " +
                 "bumped. Depending on host configuration the change is applied immediately or queued for " +
-                "human approval. Look the skill up with search_skills or list_skills first to get its id or " +
-                "exact name. Do not paraphrase or expand the user's instructions.",
+                "human approval. Look the skill up with list_skills first to get its exact name. " +
+                "Do not paraphrase or expand the user's instructions.",
             inputSchema: z.object({
                 skillId: z
                     .string()

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

@@ -7,6 +7,7 @@
  * write paths fail closed (errors reject the mutation).
  */
 import type { SkillDefinition, SkillIndexItem, SkillMutationAction, SkillMutationResult, SkillSearchQuery, SkillsConfig } from "../types/index.js";
+import { SkillSessionTracker } from "./skillSessionTracker.js";
 export declare class SkillsManager {
     private readonly config;
     private readonly store;
@@ -14,8 +15,14 @@ export declare class SkillsManager {
     private cachedIndexAt;
     /** Serializes writes within this process — see requestMutation(). */
     private mutationQueue;
+    /** Per-session activation state (pinned skills). */
+    readonly sessions: SkillSessionTracker;
     constructor(config: SkillsConfig);
-    /** 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.
+     */
     getIndex(forceRefresh?: boolean): Promise<SkillIndexItem[]>;
     private invalidateIndex;
     /**
@@ -36,6 +43,23 @@ export declare class SkillsManager {
         scopeId?: string;
         tags?: string[];
     }): Promise<string | null>;
+    /**
+     * 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.
+     */
+    buildToolListing(options?: {
+        scopeId?: string;
+        tags?: string[];
+    }): Promise<string | null>;
+    /** Visible (active, scope- and tag-filtered) index entries for one call. */
+    private visibleItems;
+    /**
+     * 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.
+     */
+    getResource(idOrName: string, resourcePath: string): Promise<string | null>;
     /**
      * Whether skill create/update/delete is enabled on this instance. Gates the
      * LLM-facing `skill_*` tools (registration) and the server REST mutation

package/dist/lib/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/lib/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/lib/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