@juspay/neurolink 9.85.1 → 9.86.0

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

@@ -9,11 +9,19 @@
 import type { SkillDefinition, SkillIndexItem, SkillRedisStorageConfig, SkillStore } from "../types/index.js";
 export declare class RedisSkillStore implements SkillStore {
     private readonly keyPrefix;
+    /**
+     * Resources live under `<keyPrefix>__resources__:` — a reserved segment
+     * inside the skill prefix, explicitly excluded from the index SCAN so
+     * resource values are never mistaken for skills, whatever the
+     * configured keyPrefix looks like.
+     */
+    private readonly resourcePrefix;
     private readonly normalizedConfig;
     private clientPromise;
     constructor(config: SkillRedisStorageConfig);
     private getClient;
     private skillKey;
+    getResource(id: string, resourcePath: string): Promise<string | null>;
     get(id: string): Promise<SkillDefinition | null>;
     put(skill: SkillDefinition): Promise<void>;
     delete(id: string): Promise<void>;

package/dist/lib/skills/skillStoreRedis.js

@@ -8,14 +8,22 @@
  */
 import { getNormalizedConfig, getPooledRedisClient, scanKeys, } from "../utils/redis.js";
 import { logger } from "../utils/logger.js";
-import { toSkillIndexItem } from "./skillMatcher.js";
+import { isSafeSkillResourcePath, toSkillIndexItem } from "./skillMatcher.js";
 const DEFAULT_KEY_PREFIX = "neurolink:skills:";
 export class RedisSkillStore {
     keyPrefix;
+    /**
+     * Resources live under `<keyPrefix>__resources__:` — a reserved segment
+     * inside the skill prefix, explicitly excluded from the index SCAN so
+     * resource values are never mistaken for skills, whatever the
+     * configured keyPrefix looks like.
+     */
+    resourcePrefix;
     normalizedConfig;
     clientPromise = null;
     constructor(config) {
         this.keyPrefix = config.keyPrefix ?? DEFAULT_KEY_PREFIX;
+        this.resourcePrefix = `${this.keyPrefix}__resources__:`;
         this.normalizedConfig = getNormalizedConfig({
             ...(config.url ? { url: config.url } : {}),
             ...(config.host ? { host: config.host } : {}),
@@ -39,6 +47,14 @@ export class RedisSkillStore {
     skillKey(id) {
         return `${this.keyPrefix}${id}`;
     }
+    async getResource(id, resourcePath) {
+        if (!isSafeSkillResourcePath(resourcePath)) {
+            return null;
+        }
+        const client = await this.getClient();
+        const raw = await client.get(`${this.resourcePrefix}${id}:${resourcePath}`);
+        return raw ? String(raw) : null;
+    }
     async get(id) {
         const client = await this.getClient();
         const raw = await client.get(this.skillKey(id));
@@ -55,7 +71,7 @@ export class RedisSkillStore {
     }
     async index() {
         const client = await this.getClient();
-        const keys = await scanKeys(client, `${this.keyPrefix}*`);
+        const keys = (await scanKeys(client, `${this.keyPrefix}*`)).filter((key) => !key.startsWith(this.resourcePrefix));
         if (keys.length === 0) {
             return [];
         }

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

@@ -22,20 +22,35 @@ export declare class S3SkillStore implements SkillStore {
     private readonly injectedOps?;
     private readonly prefix;
     private ops;
+    /** Last parsed index + its ETag, revalidated with If-None-Match reads. */
+    private cachedIndexDoc;
+    private cachedIndexEtag;
     constructor(config: SkillS3StorageConfig, 
     /** Test/host seam — omit to build ops from @aws-sdk/client-s3 lazily. */
     injectedOps?: SkillS3ObjectOps | undefined);
+    invalidate(): void;
     private getOps;
     private skillKey;
     private indexKey;
+    /** Resources live beside the skill object: <prefix>skills/<id>/<path>. */
+    private resourceKey;
+    getResource(id: string, resourcePath: string): Promise<string | null>;
     get(id: string): Promise<SkillDefinition | null>;
     put(skill: SkillDefinition): Promise<void>;
     delete(id: string): Promise<void>;
     index(): Promise<SkillIndexItem[]>;
     private writeIndex;
     /**
-     * Read index.json; when missing or unparsable, rebuild it from a listing
-     * of the skills/ prefix and persist the rebuilt document (self-heal).
+     * Raw index.json read. Returns the body (with its ETag when available),
+     * null body when the object is absent, or notModified when a
+     * conditional read reported the cached copy unchanged.
+     */
+    private readIndexObject;
+    /**
+     * Read index.json (ETag-revalidated when the ops support conditional
+     * reads — an unchanged index costs a 304, not a download); when missing
+     * or unparsable, rebuild it from a listing of the skills/ prefix and
+     * persist the rebuilt document (self-heal).
      */
     private readOrRebuildIndex;
 }

package/dist/lib/skills/skillStoreS3.js

@@ -17,7 +17,7 @@
  */
 import { createRequire } from "node:module";
 import { logger } from "../utils/logger.js";
-import { toSkillIndexItem } from "./skillMatcher.js";
+import { isSafeSkillResourcePath, toSkillIndexItem } from "./skillMatcher.js";
 const lazyRequire = createRequire(import.meta.url);
 let cachedS3Module;
 function loadS3Module() {
@@ -97,6 +97,32 @@ function createDefaultOps(config) {
             } while (continuationToken);
             return keys;
         },
+        async getObjectConditional(key, etag) {
+            try {
+                const response = (await client.send(new mod.GetObjectCommand({
+                    Bucket: bucket,
+                    Key: key,
+                    ...(etag ? { IfNoneMatch: etag } : {}),
+                })));
+                const body = (await response.Body?.transformToString()) ?? null;
+                return {
+                    body,
+                    ...(response.ETag ? { etag: response.ETag } : {}),
+                };
+            }
+            catch (error) {
+                const name = error.name;
+                const status = error
+                    .$metadata?.httpStatusCode;
+                if (status === 304 || name === "304" || name === "NotModified") {
+                    return { body: null, notModified: true };
+                }
+                if (name === "NoSuchKey" || name === "NotFound") {
+                    return { body: null };
+                }
+                throw error;
+            }
+        },
     };
 }
 export class S3SkillStore {
@@ -104,6 +130,9 @@ export class S3SkillStore {
     injectedOps;
     prefix;
     ops = null;
+    /** Last parsed index + its ETag, revalidated with If-None-Match reads. */
+    cachedIndexDoc = null;
+    cachedIndexEtag;
     constructor(config, 
     /** Test/host seam — omit to build ops from @aws-sdk/client-s3 lazily. */
     injectedOps) {
@@ -113,6 +142,10 @@ export class S3SkillStore {
         this.prefix =
             rawPrefix === "" || rawPrefix.endsWith("/") ? rawPrefix : `${rawPrefix}/`;
     }
+    invalidate() {
+        this.cachedIndexDoc = null;
+        this.cachedIndexEtag = undefined;
+    }
     getOps() {
         if (!this.ops) {
             this.ops = this.injectedOps ?? createDefaultOps(this.config);
@@ -125,6 +158,16 @@ export class S3SkillStore {
     indexKey() {
         return `${this.prefix}index.json`;
     }
+    /** Resources live beside the skill object: <prefix>skills/<id>/<path>. */
+    resourceKey(id, resourcePath) {
+        return `${this.prefix}skills/${id}/${resourcePath}`;
+    }
+    async getResource(id, resourcePath) {
+        if (!isSafeSkillResourcePath(resourcePath)) {
+            return null;
+        }
+        return this.getOps().getObject(this.resourceKey(id, resourcePath));
+    }
     async get(id) {
         const body = await this.getOps().getObject(this.skillKey(id));
         if (!body) {
@@ -169,18 +212,42 @@ export class S3SkillStore {
     async writeIndex(index) {
         index.lastUpdated = new Date().toISOString();
         await this.getOps().putObject(this.indexKey(), JSON.stringify(index, null, 2));
+        // The write changed the object's ETag; keep the doc, revalidate next read.
+        this.cachedIndexDoc = index;
+        this.cachedIndexEtag = undefined;
     }
     /**
-     * Read index.json; when missing or unparsable, rebuild it from a listing
-     * of the skills/ prefix and persist the rebuilt document (self-heal).
+     * Raw index.json read. Returns the body (with its ETag when available),
+     * null body when the object is absent, or notModified when a
+     * conditional read reported the cached copy unchanged.
+     */
+    async readIndexObject(ops) {
+        if (ops.getObjectConditional) {
+            return ops.getObjectConditional(this.indexKey(), this.cachedIndexDoc ? this.cachedIndexEtag : undefined);
+        }
+        return { body: await ops.getObject(this.indexKey()) };
+    }
+    /**
+     * Read index.json (ETag-revalidated when the ops support conditional
+     * reads — an unchanged index costs a 304, not a download); when missing
+     * or unparsable, rebuild it from a listing of the skills/ prefix and
+     * persist the rebuilt document (self-heal).
      */
     async readOrRebuildIndex() {
         const ops = this.getOps();
-        const raw = await ops.getObject(this.indexKey());
-        if (raw) {
+        const read = await this.readIndexObject(ops);
+        if (read.notModified && this.cachedIndexDoc) {
+            return this.cachedIndexDoc;
+        }
+        if (read.body) {
             try {
-                const parsed = JSON.parse(raw);
+                const parsed = JSON.parse(read.body);
                 if (Array.isArray(parsed.skills)) {
+                    this.cachedIndexDoc = parsed;
+                    // Cache the ETag only for a body that parsed: pairing a corrupt
+                    // object's ETag with the previous good doc would make every
+                    // later conditional read 304 into permanently stale data.
+                    this.cachedIndexEtag = read.etag;
                     return parsed;
                 }
             }
@@ -189,6 +256,7 @@ export class S3SkillStore {
                     error: error instanceof Error ? error.message : String(error),
                 });
             }
+            this.cachedIndexEtag = undefined;
         }
         const skillsPrefix = `${this.prefix}skills/`;
         const keys = await ops.listKeys(skillsPrefix);
@@ -214,6 +282,10 @@ export class S3SkillStore {
             lastUpdated: new Date().toISOString(),
             skills,
         };
+        // Cache the rebuilt doc even when persistence below fails, so reads
+        // don't fall back to a stale pre-rebuild copy.
+        this.cachedIndexDoc = rebuilt;
+        this.cachedIndexEtag = undefined;
         try {
             await this.writeIndex(rebuilt);
             logger.info("[SkillStoreS3] Rebuilt skills index", {

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

@@ -11,26 +11,40 @@ import type { SkillDefinition, SkillIndexItem, SkillStore, SkillsStorageConfig }
 /** In-process store backed by a Map. */
 export declare class InMemorySkillStore implements SkillStore {
     private skills;
-    constructor(seed?: SkillDefinition[]);
+    /** skill id → relative path → content. */
+    private resources;
+    constructor(seed?: SkillDefinition[], resources?: Record<string, Record<string, string>>);
     get(id: string): Promise<SkillDefinition | null>;
     put(skill: SkillDefinition): Promise<void>;
     delete(id: string): Promise<void>;
     index(): Promise<SkillIndexItem[]>;
+    getResource(id: string, resourcePath: string): Promise<string | null>;
 }
 /**
  * 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 declare class FileSystemSkillStore implements SkillStore {
     private readonly baseDir;
     private cache;
+    /** skill id → directory, for skills loaded from the SKILL.md layout. */
+    private skillDirs;
     constructor(baseDir: string);
     invalidate(): void;
     get(id: string): Promise<SkillDefinition | 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.
+     */
+    getResource(id: string, resourcePath: string): Promise<string | null>;
     put(skill: SkillDefinition): Promise<void>;
     delete(id: string): Promise<void>;
     index(): Promise<SkillIndexItem[]>;

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