@juspay/neurolink 9.85.0 → 9.86.0

package/dist/skills/skillStores.js

@@ -40,9 +40,23 @@ function isValidSkill(candidate) {
 /** In-process store backed by a Map. */
 export class InMemorySkillStore {
     skills = new Map();
-    constructor(seed) {
+    /** skill id → relative path → content. */
+    resources = new Map();
+    constructor(seed, resources) {
+        for (const [skillId, files] of Object.entries(resources ?? {})) {
+            this.resources.set(skillId, new Map(Object.entries(files)));
+        }
         for (const skill of seed ?? []) {
-            this.skills.set(skill.id, normalizeSkill(skill));
+            const files = this.resources.get(skill.id);
+            const withRefs = files && !skill.resources
+                ? {
+                    ...skill,
+                    resources: Array.from(files.keys())
+                        .sort()
+                        .map((p) => ({ path: p })),
+                }
+                : skill;
+            this.skills.set(skill.id, normalizeSkill(withRefs));
         }
     }
     async get(id) {
@@ -57,6 +71,9 @@ export class InMemorySkillStore {
     async index() {
         return Array.from(this.skills.values()).map(toSkillIndexItem);
     }
+    async getResource(id, resourcePath) {
+        return this.resources.get(id)?.get(resourcePath) ?? null;
+    }
 }
 /**
  * Parse a markdown document with optional YAML frontmatter into a skill.
@@ -112,17 +129,56 @@ function parseSkillMarkdown(raw, fallbackId) {
     });
     return candidate;
 }
+/**
+ * List every file bundled beside a skill's SKILL.md as a resource ref,
+ * relative paths, sorted for deterministic listings. Recurses into
+ * subdirectories (references/, assets/, …).
+ */
+function listSkillResourceFiles(skillDir) {
+    const refs = [];
+    const walk = (current, relative) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const relPath = relative ? `${relative}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                walk(path.join(current, entry.name), relPath);
+            }
+            else if (relPath !== "SKILL.md") {
+                try {
+                    refs.push({
+                        path: relPath,
+                        size: fs.statSync(path.join(current, entry.name)).size,
+                    });
+                }
+                catch {
+                    refs.push({ path: relPath });
+                }
+            }
+        }
+    };
+    walk(skillDir, "");
+    return refs.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
 /**
  * Directory-backed store. Read layouts:
  *  - `<dir>/<id>.json`      — JSON SkillDefinition (mutable)
  *  - `<dir>/<name>.md`      — frontmatter markdown (read-only source)
- *  - `<dir>/<name>/SKILL.md` — Claude-skills directory layout (read-only source)
+ *  - `<dir>/<name>/SKILL.md` — Claude-skills directory layout (read-only source);
+ *    sibling files become on-demand resources (read_skill_resource)
  * Mutations always write `<id>.json`; a JSON file shadows a markdown skill
  * with the same id, so updating a markdown-sourced skill "copies up" to JSON.
  */
 export class FileSystemSkillStore {
     baseDir;
     cache = null;
+    /** skill id → directory, for skills loaded from the SKILL.md layout. */
+    skillDirs = new Map();
     constructor(baseDir) {
         this.baseDir = baseDir;
     }
@@ -133,6 +189,36 @@ export class FileSystemSkillStore {
         const all = this.load();
         return all.get(id) ?? null;
     }
+    /**
+     * Resources exist only for directory-layout skills (`<name>/SKILL.md`) —
+     * every sibling file of SKILL.md is addressable by its relative path.
+     * The REAL path must stay inside the skill directory: lexical
+     * containment alone would follow a symlink planted inside the skill dir
+     * to anywhere on the host.
+     */
+    async getResource(id, resourcePath) {
+        this.load();
+        const dir = this.skillDirs.get(id);
+        if (!dir) {
+            return null;
+        }
+        try {
+            const realDir = fs.realpathSync(dir);
+            const realResolved = fs.realpathSync(path.resolve(dir, resourcePath));
+            if (realResolved !== realDir &&
+                !realResolved.startsWith(realDir + path.sep)) {
+                return null;
+            }
+            return fs.readFileSync(realResolved, "utf-8");
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ENOENT" || code === "EISDIR" || code === "ELOOP") {
+                return null;
+            }
+            throw error;
+        }
+    }
     async put(skill) {
         fs.mkdirSync(this.baseDir, { recursive: true });
         const filePath = path.join(this.baseDir, `${skill.id}.json`);
@@ -164,6 +250,7 @@ export class FileSystemSkillStore {
             return this.cache;
         }
         const skills = new Map();
+        this.skillDirs = new Map();
         let entries;
         try {
             entries = fs.readdirSync(this.baseDir, { withFileTypes: true });
@@ -188,7 +275,9 @@ export class FileSystemSkillStore {
                     if (fs.existsSync(skillMd)) {
                         const parsed = parseSkillMarkdown(fs.readFileSync(skillMd, "utf-8"), entry.name);
                         if (parsed) {
-                            skills.set(parsed.id, parsed);
+                            const resources = listSkillResourceFiles(fullPath);
+                            skills.set(parsed.id, resources.length > 0 ? { ...parsed, resources } : parsed);
+                            this.skillDirs.set(parsed.id, path.resolve(fullPath));
                         }
                     }
                 }
@@ -236,7 +325,7 @@ export class FileSystemSkillStore {
 /** Resolve a storage config to a concrete store. Defaults to memory. */
 export function createSkillStore(config) {
     if (!config || config.type === "memory") {
-        return new InMemorySkillStore(config?.type === "memory" ? config.skills : undefined);
+        return new InMemorySkillStore(config?.type === "memory" ? config.skills : undefined, config?.type === "memory" ? config.resources : undefined);
     }
     if (config.type === "filesystem") {
         return new FileSystemSkillStore(config.path);

package/dist/skills/skillTools.d.ts

@@ -1,19 +1,35 @@
 /**
- * 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 type { SkillsManagerLike, SkillToolsOptions, Tool } from "../types/index.js";
+import type { SkillCallToolsContext, SkillsManagerLike, SkillToolsOptions, Tool } from "../types/index.js";
+/**
+ * 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 declare function createSkillCallTools(resolveManager: () => SkillsManagerLike | null, context: SkillCallToolsContext): Record<string, Tool>;
 /**
- * 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.
+ * 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 declare function createSkillTools(resolveManager: () => SkillsManagerLike | null, options?: SkillToolsOptions): Record<string, Tool>;

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