@juspay/neurolink 9.84.2 → 9.85.1

package/dist/skills/skillMatcher.js

@@ -0,0 +1,79 @@
+/**
+ * Pure index-filtering + prompt-index formatting helpers.
+ *
+ * Matching semantics are ported from curator's battle-tested
+ * `searchSkillsFromIndex`: case-insensitive substring match on
+ * name/displayName/description, optional tag filter on top, scope filter
+ * that always admits global skills, and active-only visibility.
+ */
+/** Strip instructions from a full definition to form an index entry. */
+export function toSkillIndexItem(skill) {
+    const { instructions: _instructions, ...indexItem } = skill;
+    return indexItem;
+}
+/** Filter index entries by query/tag/scope. Active skills only. */
+export function filterSkillIndex(items, query) {
+    const lowerQuery = query.query?.toLowerCase();
+    const lowerTag = query.tag?.toLowerCase();
+    const matched = items.filter((item) => {
+        if ((item.status ?? "active") !== "active") {
+            return false;
+        }
+        // Scope filter: global skills always pass; scoped skills require a
+        // matching scopeId. When the caller provides no scopeId, scoped skills
+        // still pass (curator semantics — unscoped callers see everything).
+        if (query.scopeId && item.scope === "scoped") {
+            if (!(item.scopeIds ?? []).includes(query.scopeId)) {
+                return false;
+            }
+        }
+        if (lowerQuery) {
+            const nameMatch = item.name.toLowerCase().includes(lowerQuery) ||
+                (item.displayName ?? "").toLowerCase().includes(lowerQuery) ||
+                item.description.toLowerCase().includes(lowerQuery);
+            if (!nameMatch) {
+                return false;
+            }
+        }
+        if (lowerTag) {
+            const tagMatch = (item.tags ?? []).some((t) => t.toLowerCase().includes(lowerTag));
+            if (!tagMatch) {
+                return false;
+            }
+        }
+        return true;
+    });
+    return query.limit !== undefined ? matched.slice(0, query.limit) : matched;
+}
+/**
+ * Render the compact skills index injected into the system prompt.
+ * Names + descriptions only — instructions are never included; the model
+ * loads them via search_skills. Returns null when nothing is visible so
+ * callers can skip injection entirely.
+ */
+export function formatSkillsPromptIndex(items, maxItems) {
+    if (items.length === 0) {
+        return null;
+    }
+    const visible = items.slice(0, maxItems);
+    const lines = visible.map((item) => {
+        const label = item.displayName
+            ? `${item.name} (${item.displayName})`
+            : item.name;
+        const tags = item.tags && item.tags.length > 0
+            ? ` [tags: ${item.tags.join(", ")}]`
+            : "";
+        return `- ${label}: ${item.description}${tags}`;
+    });
+    const truncationNote = items.length > visible.length
+        ? `\n(${items.length - visible.length} more skills exist — use search_skills or list_skills to discover them.)`
+        : "";
+    return ([
+        "## Available Skills",
+        "The following team-defined skills (SOPs, playbooks, workflows) are available.",
+        "Before answering from general knowledge, check whether one applies to the user's request.",
+        "To use a skill, call the search_skills tool to load its full instructions, then follow them exactly.",
+        "",
+        ...lines,
+    ].join("\n") + truncationNote);
+}

package/dist/skills/skillStoreRedis.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Redis-backed skill store.
+ *
+ * Reuses NeuroLink's pooled Redis client (`redis` v5 is already a core
+ * dependency, shared with Redis conversation memory). One JSON value per
+ * skill under `<keyPrefix><id>`; the index is derived with SCAN + MGET —
+ * no separate index document to drift. Skills are persistent (no TTL).
+ */
+import type { SkillDefinition, SkillIndexItem, SkillRedisStorageConfig, SkillStore } from "../types/index.js";
+export declare class RedisSkillStore implements SkillStore {
+    private readonly keyPrefix;
+    private readonly normalizedConfig;
+    private clientPromise;
+    constructor(config: SkillRedisStorageConfig);
+    private getClient;
+    private skillKey;
+    get(id: string): Promise<SkillDefinition | null>;
+    put(skill: SkillDefinition): Promise<void>;
+    delete(id: string): Promise<void>;
+    index(): Promise<SkillIndexItem[]>;
+    private parseSkill;
+}

package/dist/skills/skillStoreRedis.js

@@ -0,0 +1,97 @@
+/**
+ * Redis-backed skill store.
+ *
+ * Reuses NeuroLink's pooled Redis client (`redis` v5 is already a core
+ * dependency, shared with Redis conversation memory). One JSON value per
+ * skill under `<keyPrefix><id>`; the index is derived with SCAN + MGET —
+ * no separate index document to drift. Skills are persistent (no TTL).
+ */
+import { getNormalizedConfig, getPooledRedisClient, scanKeys, } from "../utils/redis.js";
+import { logger } from "../utils/logger.js";
+import { toSkillIndexItem } from "./skillMatcher.js";
+const DEFAULT_KEY_PREFIX = "neurolink:skills:";
+export class RedisSkillStore {
+    keyPrefix;
+    normalizedConfig;
+    clientPromise = null;
+    constructor(config) {
+        this.keyPrefix = config.keyPrefix ?? DEFAULT_KEY_PREFIX;
+        this.normalizedConfig = getNormalizedConfig({
+            ...(config.url ? { url: config.url } : {}),
+            ...(config.host ? { host: config.host } : {}),
+            ...(config.port !== undefined ? { port: config.port } : {}),
+            ...(config.username ? { username: config.username } : {}),
+            ...(config.password ? { password: config.password } : {}),
+            ...(config.db !== undefined ? { db: config.db } : {}),
+            keyPrefix: this.keyPrefix,
+        });
+    }
+    getClient() {
+        if (!this.clientPromise) {
+            this.clientPromise = getPooledRedisClient(this.normalizedConfig).catch((error) => {
+                // Reset so a later call can retry after a transient outage.
+                this.clientPromise = null;
+                throw error;
+            });
+        }
+        return this.clientPromise;
+    }
+    skillKey(id) {
+        return `${this.keyPrefix}${id}`;
+    }
+    async get(id) {
+        const client = await this.getClient();
+        const raw = await client.get(this.skillKey(id));
+        return raw ? this.parseSkill(String(raw), this.skillKey(id)) : null;
+    }
+    async put(skill) {
+        const client = await this.getClient();
+        // Persistent — deliberately no TTL: skills must not expire silently.
+        await client.set(this.skillKey(skill.id), JSON.stringify(skill));
+    }
+    async delete(id) {
+        const client = await this.getClient();
+        await client.del(this.skillKey(id));
+    }
+    async index() {
+        const client = await this.getClient();
+        const keys = await scanKeys(client, `${this.keyPrefix}*`);
+        if (keys.length === 0) {
+            return [];
+        }
+        const values = await client.mGet(keys);
+        const items = [];
+        values.forEach((value, i) => {
+            if (!value) {
+                return;
+            }
+            const skill = this.parseSkill(String(value), keys[i]);
+            if (skill) {
+                items.push(toSkillIndexItem(skill));
+            }
+        });
+        return items;
+    }
+    parseSkill(raw, key) {
+        try {
+            const parsed = JSON.parse(raw);
+            if (typeof parsed?.id === "string" &&
+                typeof parsed?.name === "string" &&
+                typeof parsed?.description === "string" &&
+                typeof parsed?.instructions === "string") {
+                return parsed;
+            }
+            logger.warn("[SkillStoreRedis] Value is not a valid skill — skipping", {
+                key,
+            });
+            return null;
+        }
+        catch (error) {
+            logger.warn("[SkillStoreRedis] Failed to parse skill value", {
+                key,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    }
+}

package/dist/skills/skillStoreS3.d.ts

@@ -0,0 +1,41 @@
+/**
+ * S3-backed skill store.
+ *
+ * Layout (curator-compatible):
+ *   <prefix>skills/<id>.json  — one JSON-serialized SkillDefinition per object
+ *   <prefix>index.json        — { lastUpdated, skills: SkillIndexItem[] }
+ *
+ * The index document is upserted on every write and rebuilt from a bucket
+ * listing when missing or unparsable (self-healing). Concurrent writers can
+ * race the index read-modify-write; the rebuild path recovers from any
+ * resulting drift, matching curator's production behavior.
+ *
+ * @aws-sdk/client-s3 is an optional peer — loaded lazily with the same
+ * createRequire pattern as memory's @juspay/hippocampus so importing
+ * NeuroLink core never requires the AWS SDK. Tests (and hosts with
+ * pre-configured clients) inject a SkillS3ObjectOps implementation instead.
+ */
+import type { SkillDefinition, SkillIndexItem, SkillS3ObjectOps, SkillS3StorageConfig, SkillStore } from "../types/index.js";
+export declare class S3SkillStore implements SkillStore {
+    private readonly config;
+    /** Test/host seam — omit to build ops from @aws-sdk/client-s3 lazily. */
+    private readonly injectedOps?;
+    private readonly prefix;
+    private ops;
+    constructor(config: SkillS3StorageConfig, 
+    /** Test/host seam — omit to build ops from @aws-sdk/client-s3 lazily. */
+    injectedOps?: SkillS3ObjectOps | undefined);
+    private getOps;
+    private skillKey;
+    private indexKey;
+    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).
+     */
+    private readOrRebuildIndex;
+}

package/dist/skills/skillStoreS3.js

@@ -0,0 +1,232 @@
+/**
+ * S3-backed skill store.
+ *
+ * Layout (curator-compatible):
+ *   <prefix>skills/<id>.json  — one JSON-serialized SkillDefinition per object
+ *   <prefix>index.json        — { lastUpdated, skills: SkillIndexItem[] }
+ *
+ * The index document is upserted on every write and rebuilt from a bucket
+ * listing when missing or unparsable (self-healing). Concurrent writers can
+ * race the index read-modify-write; the rebuild path recovers from any
+ * resulting drift, matching curator's production behavior.
+ *
+ * @aws-sdk/client-s3 is an optional peer — loaded lazily with the same
+ * createRequire pattern as memory's @juspay/hippocampus so importing
+ * NeuroLink core never requires the AWS SDK. Tests (and hosts with
+ * pre-configured clients) inject a SkillS3ObjectOps implementation instead.
+ */
+import { createRequire } from "node:module";
+import { logger } from "../utils/logger.js";
+import { toSkillIndexItem } from "./skillMatcher.js";
+const lazyRequire = createRequire(import.meta.url);
+let cachedS3Module;
+function loadS3Module() {
+    if (cachedS3Module !== undefined) {
+        return cachedS3Module;
+    }
+    try {
+        cachedS3Module = lazyRequire("@aws-sdk/client-s3");
+        return cachedS3Module;
+    }
+    catch (error) {
+        cachedS3Module = null;
+        logger.debug("[SkillStoreS3] @aws-sdk/client-s3 is not installed; S3 skill storage unavailable.", { error: error instanceof Error ? error.message : String(error) });
+        return null;
+    }
+}
+/** Build default object ops from @aws-sdk/client-s3. Throws when absent. */
+function createDefaultOps(config) {
+    const mod = loadS3Module();
+    if (!mod) {
+        throw new Error("Skills S3 storage requires @aws-sdk/client-s3. Run `pnpm add @aws-sdk/client-s3` " +
+            "(or your package manager equivalent), or supply a custom store instead.");
+    }
+    const client = new mod.S3Client({
+        ...(config.region ? { region: config.region } : {}),
+        ...(config.endpoint ? { endpoint: config.endpoint } : {}),
+        ...(config.forcePathStyle !== undefined
+            ? { forcePathStyle: config.forcePathStyle }
+            : {}),
+        ...(config.credentials ? { credentials: config.credentials } : {}),
+    });
+    const bucket = config.bucket;
+    return {
+        async getObject(key) {
+            try {
+                const response = (await client.send(new mod.GetObjectCommand({ Bucket: bucket, Key: key })));
+                return (await response.Body?.transformToString()) ?? null;
+            }
+            catch (error) {
+                const name = error.name;
+                if (name === "NoSuchKey" || name === "NotFound") {
+                    return null;
+                }
+                throw error;
+            }
+        },
+        async putObject(key, body) {
+            await client.send(new mod.PutObjectCommand({
+                Bucket: bucket,
+                Key: key,
+                Body: body,
+                ContentType: "application/json",
+            }));
+        },
+        async deleteObject(key) {
+            await client.send(new mod.DeleteObjectCommand({ Bucket: bucket, Key: key }));
+        },
+        async listKeys(prefix) {
+            const keys = [];
+            let continuationToken;
+            do {
+                const response = (await client.send(new mod.ListObjectsV2Command({
+                    Bucket: bucket,
+                    Prefix: prefix,
+                    ...(continuationToken
+                        ? { ContinuationToken: continuationToken }
+                        : {}),
+                })));
+                for (const item of response.Contents ?? []) {
+                    if (item.Key) {
+                        keys.push(item.Key);
+                    }
+                }
+                continuationToken = response.IsTruncated
+                    ? response.NextContinuationToken
+                    : undefined;
+            } while (continuationToken);
+            return keys;
+        },
+    };
+}
+export class S3SkillStore {
+    config;
+    injectedOps;
+    prefix;
+    ops = null;
+    constructor(config, 
+    /** Test/host seam — omit to build ops from @aws-sdk/client-s3 lazily. */
+    injectedOps) {
+        this.config = config;
+        this.injectedOps = injectedOps;
+        const rawPrefix = config.prefix ?? "neurolink-skills/";
+        this.prefix =
+            rawPrefix === "" || rawPrefix.endsWith("/") ? rawPrefix : `${rawPrefix}/`;
+    }
+    getOps() {
+        if (!this.ops) {
+            this.ops = this.injectedOps ?? createDefaultOps(this.config);
+        }
+        return this.ops;
+    }
+    skillKey(id) {
+        return `${this.prefix}skills/${id}.json`;
+    }
+    indexKey() {
+        return `${this.prefix}index.json`;
+    }
+    async get(id) {
+        const body = await this.getOps().getObject(this.skillKey(id));
+        if (!body) {
+            return null;
+        }
+        try {
+            return JSON.parse(body);
+        }
+        catch (error) {
+            logger.warn("[SkillStoreS3] Failed to parse skill object", {
+                id,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    }
+    async put(skill) {
+        const ops = this.getOps();
+        await ops.putObject(this.skillKey(skill.id), JSON.stringify(skill, null, 2));
+        const index = await this.readOrRebuildIndex();
+        const entry = toSkillIndexItem(skill);
+        const position = index.skills.findIndex((s) => s.id === skill.id);
+        if (position >= 0) {
+            index.skills[position] = entry;
+        }
+        else {
+            index.skills.push(entry);
+        }
+        await this.writeIndex(index);
+    }
+    async delete(id) {
+        const ops = this.getOps();
+        await ops.deleteObject(this.skillKey(id));
+        const index = await this.readOrRebuildIndex();
+        index.skills = index.skills.filter((s) => s.id !== id);
+        await this.writeIndex(index);
+    }
+    async index() {
+        const index = await this.readOrRebuildIndex();
+        return index.skills;
+    }
+    async writeIndex(index) {
+        index.lastUpdated = new Date().toISOString();
+        await this.getOps().putObject(this.indexKey(), JSON.stringify(index, null, 2));
+    }
+    /**
+     * Read index.json; 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) {
+            try {
+                const parsed = JSON.parse(raw);
+                if (Array.isArray(parsed.skills)) {
+                    return parsed;
+                }
+            }
+            catch (error) {
+                logger.warn("[SkillStoreS3] index.json unparsable — rebuilding", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        const skillsPrefix = `${this.prefix}skills/`;
+        const keys = await ops.listKeys(skillsPrefix);
+        const skills = [];
+        for (const key of keys) {
+            if (!key.endsWith(".json")) {
+                continue;
+            }
+            const body = await ops.getObject(key);
+            if (!body) {
+                continue;
+            }
+            try {
+                skills.push(toSkillIndexItem(JSON.parse(body)));
+            }
+            catch {
+                logger.warn("[SkillStoreS3] Skipping unparsable skill during rebuild", {
+                    key,
+                });
+            }
+        }
+        const rebuilt = {
+            lastUpdated: new Date().toISOString(),
+            skills,
+        };
+        try {
+            await this.writeIndex(rebuilt);
+            logger.info("[SkillStoreS3] Rebuilt skills index", {
+                count: skills.length,
+            });
+        }
+        catch (error) {
+            // Index persistence is best-effort; the rebuilt in-memory copy is
+            // still returned so reads keep working.
+            logger.warn("[SkillStoreS3] Failed to persist rebuilt index", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        return rebuilt;
+    }
+}

package/dist/skills/skillStores.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Built-in skill stores + the storage-config factory.
+ *
+ * First-party backends: in-process memory (tests, embedded), filesystem
+ * (curator-style JSON alongside Claude-skills-style markdown — `<name>.md`
+ * or `<name>/SKILL.md` with YAML frontmatter), S3 (skillStoreS3.ts, optional
+ * @aws-sdk/client-s3 peer), and Redis (skillStoreRedis.ts, pooled core
+ * client). Anything else plugs in via `{ type: "custom", store }`.
+ */
+import type { SkillDefinition, SkillIndexItem, SkillStore, SkillsStorageConfig } from "../types/index.js";
+/** In-process store backed by a Map. */
+export declare class InMemorySkillStore implements SkillStore {
+    private skills;
+    constructor(seed?: SkillDefinition[]);
+    get(id: string): Promise<SkillDefinition | null>;
+    put(skill: SkillDefinition): Promise<void>;
+    delete(id: string): Promise<void>;
+    index(): Promise<SkillIndexItem[]>;
+}
+/**
+ * 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)
+ * 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;
+    constructor(baseDir: string);
+    invalidate(): void;
+    get(id: string): Promise<SkillDefinition | null>;
+    put(skill: SkillDefinition): Promise<void>;
+    delete(id: string): Promise<void>;
+    index(): Promise<SkillIndexItem[]>;
+    /**
+     * Scan the directory into an id→skill map. Markdown sources load first
+     * so JSON files (the mutable layer) shadow them on id collision.
+     */
+    private load;
+}
+/** Resolve a storage config to a concrete store. Defaults to memory. */
+export declare function createSkillStore(config?: SkillsStorageConfig): SkillStore;