@juspay/neurolink 9.84.2 → 9.85.0

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;

package/dist/skills/skillStores.js

@@ -0,0 +1,251 @@
+/**
+ * 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 * as fs from "node:fs";
+import * as path from "node:path";
+import yaml from "js-yaml";
+import { logger } from "../utils/logger.js";
+import { toSkillIndexItem } from "./skillMatcher.js";
+import { S3SkillStore } from "./skillStoreS3.js";
+import { RedisSkillStore } from "./skillStoreRedis.js";
+/** Fill defaulted fields so downstream logic never branches on undefined. */
+function normalizeSkill(skill) {
+    return {
+        ...skill,
+        scope: skill.scope ?? "global",
+        status: skill.status ?? "active",
+        version: skill.version ?? 1,
+        tags: skill.tags ?? [],
+    };
+}
+/** Minimal structural validation for skills loaded from external sources. */
+function isValidSkill(candidate) {
+    if (typeof candidate !== "object" || candidate === null) {
+        return false;
+    }
+    const record = candidate;
+    return (typeof record.id === "string" &&
+        record.id.length > 0 &&
+        typeof record.name === "string" &&
+        record.name.length > 0 &&
+        typeof record.description === "string" &&
+        typeof record.instructions === "string");
+}
+/** In-process store backed by a Map. */
+export class InMemorySkillStore {
+    skills = new Map();
+    constructor(seed) {
+        for (const skill of seed ?? []) {
+            this.skills.set(skill.id, normalizeSkill(skill));
+        }
+    }
+    async get(id) {
+        return this.skills.get(id) ?? null;
+    }
+    async put(skill) {
+        this.skills.set(skill.id, normalizeSkill(skill));
+    }
+    async delete(id) {
+        this.skills.delete(id);
+    }
+    async index() {
+        return Array.from(this.skills.values()).map(toSkillIndexItem);
+    }
+}
+/**
+ * Parse a markdown document with optional YAML frontmatter into a skill.
+ * The body becomes `instructions`; frontmatter supplies index metadata.
+ * Returns null when required fields are missing (logged, not thrown —
+ * one malformed file must not take down the whole store).
+ */
+function parseSkillMarkdown(raw, fallbackId) {
+    const frontmatterMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    let meta = {};
+    let body = raw;
+    if (frontmatterMatch) {
+        try {
+            const parsed = yaml.load(frontmatterMatch[1]);
+            if (typeof parsed === "object" && parsed !== null) {
+                meta = parsed;
+            }
+        }
+        catch (error) {
+            logger.warn("[SkillStore] Invalid YAML frontmatter in skill markdown", {
+                fallbackId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+        body = raw.slice(frontmatterMatch[0].length);
+    }
+    const name = typeof meta.name === "string" ? meta.name : fallbackId;
+    const description = typeof meta.description === "string" ? meta.description : "";
+    const instructions = body.trim();
+    if (!name || !description || !instructions) {
+        logger.warn("[SkillStore] Skipping skill markdown missing name/description/body", { fallbackId });
+        return null;
+    }
+    const candidate = normalizeSkill({
+        id: typeof meta.id === "string" ? meta.id : name,
+        name,
+        description,
+        instructions,
+        ...(typeof meta.displayName === "string"
+            ? { displayName: meta.displayName }
+            : {}),
+        ...(Array.isArray(meta.tags)
+            ? { tags: meta.tags.map((t) => String(t)) }
+            : {}),
+        ...(meta.scope === "scoped" || meta.scope === "global"
+            ? { scope: meta.scope }
+            : {}),
+        ...(Array.isArray(meta.scopeIds)
+            ? { scopeIds: meta.scopeIds.map((s) => String(s)) }
+            : {}),
+        ...(typeof meta.version === "number" ? { version: meta.version } : {}),
+    });
+    return candidate;
+}
+/**
+ * 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 class FileSystemSkillStore {
+    baseDir;
+    cache = null;
+    constructor(baseDir) {
+        this.baseDir = baseDir;
+    }
+    invalidate() {
+        this.cache = null;
+    }
+    async get(id) {
+        const all = this.load();
+        return all.get(id) ?? null;
+    }
+    async put(skill) {
+        fs.mkdirSync(this.baseDir, { recursive: true });
+        const filePath = path.join(this.baseDir, `${skill.id}.json`);
+        fs.writeFileSync(filePath, JSON.stringify(normalizeSkill(skill), null, 2), "utf-8");
+        this.invalidate();
+    }
+    async delete(id) {
+        const filePath = path.join(this.baseDir, `${id}.json`);
+        try {
+            fs.unlinkSync(filePath);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "ENOENT") {
+                throw error;
+            }
+        }
+        this.invalidate();
+    }
+    async index() {
+        return Array.from(this.load().values()).map(toSkillIndexItem);
+    }
+    /**
+     * Scan the directory into an id→skill map. Markdown sources load first
+     * so JSON files (the mutable layer) shadow them on id collision.
+     */
+    load() {
+        if (this.cache) {
+            return this.cache;
+        }
+        const skills = new Map();
+        let entries;
+        try {
+            entries = fs.readdirSync(this.baseDir, { withFileTypes: true });
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "ENOENT") {
+                logger.warn("[SkillStore] Failed to read skills directory", {
+                    baseDir: this.baseDir,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            this.cache = skills;
+            return skills;
+        }
+        const jsonFiles = [];
+        for (const entry of entries) {
+            const fullPath = path.join(this.baseDir, entry.name);
+            try {
+                if (entry.isDirectory()) {
+                    const skillMd = path.join(fullPath, "SKILL.md");
+                    if (fs.existsSync(skillMd)) {
+                        const parsed = parseSkillMarkdown(fs.readFileSync(skillMd, "utf-8"), entry.name);
+                        if (parsed) {
+                            skills.set(parsed.id, parsed);
+                        }
+                    }
+                }
+                else if (entry.name.endsWith(".md")) {
+                    const parsed = parseSkillMarkdown(fs.readFileSync(fullPath, "utf-8"), entry.name.replace(/\.md$/, ""));
+                    if (parsed) {
+                        skills.set(parsed.id, parsed);
+                    }
+                }
+                else if (entry.name.endsWith(".json")) {
+                    jsonFiles.push(fullPath);
+                }
+            }
+            catch (error) {
+                logger.warn("[SkillStore] Failed to load skill file", {
+                    file: fullPath,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        // JSON layer last — shadows markdown-sourced skills with the same id.
+        for (const filePath of jsonFiles) {
+            try {
+                const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+                if (isValidSkill(parsed)) {
+                    skills.set(parsed.id, normalizeSkill(parsed));
+                }
+                else {
+                    logger.warn("[SkillStore] Skipping invalid skill JSON", {
+                        file: filePath,
+                    });
+                }
+            }
+            catch (error) {
+                logger.warn("[SkillStore] Failed to parse skill JSON", {
+                    file: filePath,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        this.cache = skills;
+        return skills;
+    }
+}
+/** 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);
+    }
+    if (config.type === "filesystem") {
+        return new FileSystemSkillStore(config.path);
+    }
+    if (config.type === "s3") {
+        return new S3SkillStore(config);
+    }
+    if (config.type === "redis") {
+        return new RedisSkillStore(config);
+    }
+    return config.store;
+}

package/dist/skills/skillTools.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Built-in skill tools, following the createMemoryRetrievalTools /
+ * createFileTools / createTaskTools factory pattern.
+ *
+ * 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";
+/**
+ * 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.
+ */
+export declare function createSkillTools(resolveManager: () => SkillsManagerLike | null, options?: SkillToolsOptions): Record<string, Tool>;