@juspay/neurolink 9.84.2 → 9.85.1

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>;

package/dist/skills/skillTools.js

@@ -0,0 +1,339 @@
+/**
+ * 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 { 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) {
+    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,
+    };
+}
+/**
+ * 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 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: [] },
+    };
+    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.",
+            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
+                    .string()
+                    .optional()
+                    .describe("Scope identifier (channel/team/tenant id) to include scoped skills alongside global ones. " +
+                    "Usually omit — the host default applies."),
+            }),
+            execute: async (args) => {
+                if (!args.query && !args.tag) {
+                    return {
+                        success: false,
+                        error: 'At least one of "query" or "tag" must be provided to search_skills.',
+                        data: { skills: [] },
+                    };
+                }
+                const manager = resolveManager();
+                if (!manager) {
+                    return notConfigured;
+                }
+                try {
+                    const skills = await manager.search(args);
+                    if (skills.length === 0) {
+                        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.`,
+                            },
+                        };
+                    }
+                    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.",
+                                }
+                                : {}),
+                        },
+                    };
+                }
+                catch (error) {
+                    logger.warn("[SkillTools] search_skills failed", {
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    return {
+                        success: false,
+                        error: error instanceof Error ? error.message : String(error),
+                        data: { skills: [] },
+                    };
+                }
+            },
+        }),
+        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.',
+            inputSchema: z.object({
+                scopeId: z
+                    .string()
+                    .optional()
+                    .describe("Scope identifier to include scoped skills alongside global ones. Usually omit."),
+            }),
+            execute: async (args) => {
+                const manager = resolveManager();
+                if (!manager) {
+                    return notConfigured;
+                }
+                try {
+                    const items = await manager.list(args.scopeId);
+                    return {
+                        success: true,
+                        data: {
+                            skills: items.map((item) => ({
+                                name: item.name,
+                                ...(item.displayName ? { displayName: item.displayName } : {}),
+                                description: item.description,
+                                tags: item.tags ?? [],
+                                scope: item.scope ?? "global",
+                            })),
+                            count: items.length,
+                        },
+                    };
+                }
+                catch (error) {
+                    logger.warn("[SkillTools] list_skills failed", {
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    return {
+                        success: false,
+                        error: error instanceof Error ? error.message : String(error),
+                        data: { skills: [] },
+                    };
+                }
+            },
+        }),
+    };
+    if (options?.allowMutations) {
+        Object.assign(tools, createSkillMutationTools(resolveManager));
+    }
+    return tools;
+}
+/** Shared executor for the three mutation tools. */
+async function runMutation(resolveManager, action) {
+    const manager = resolveManager();
+    if (!manager) {
+        return {
+            success: false,
+            error: "Skills are not available — the skills store failed to initialize.",
+        };
+    }
+    try {
+        const result = await manager.requestMutation(action);
+        if (result.decision.outcome === "rejected") {
+            return {
+                success: false,
+                error: `Skill ${action.type} was rejected${result.decision.reason ? `: ${result.decision.reason}` : "."}`,
+            };
+        }
+        if (result.decision.outcome === "pending") {
+            return {
+                success: true,
+                data: {
+                    status: "pending_approval",
+                    ...(result.decision.reference
+                        ? { reference: result.decision.reference }
+                        : {}),
+                    message: `Skill ${action.type} was submitted for approval. It takes effect once an approver accepts it.`,
+                },
+            };
+        }
+        return {
+            success: true,
+            data: {
+                status: "applied",
+                ...(result.skill
+                    ? {
+                        skillId: result.skill.id,
+                        name: result.skill.name,
+                        version: result.skill.version,
+                        skillStatus: result.skill.status,
+                    }
+                    : {}),
+            },
+        };
+    }
+    catch (error) {
+        logger.warn(`[SkillTools] skill_${action.type} failed`, {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function createSkillMutationTools(resolveManager) {
+    const scopeFields = {
+        scope: z
+            .enum(["global", "scoped"])
+            .optional()
+            .describe('"global" = available everywhere; "scoped" = only for specific scope ids.'),
+        scopeIds: z
+            .array(z.string())
+            .optional()
+            .describe('Required when scope="scoped": the scope ids (channel/team/tenant) the skill applies to.'),
+    };
+    return {
+        skill_create: tool({
+            description: "Propose a NEW skill (SOP/playbook). Depending on host configuration the skill is either " +
+                "applied immediately or queued for human approval. " +
+                "INVOKE ONLY WHEN the user explicitly asks to create a new skill and has supplied the name, " +
+                "description, and full instructions text. DO NOT INVENT CONTENT — the instructions must come " +
+                "from the user verbatim or nearly so. If the user has not given the full text, ask. " +
+                "Do not use this to modify an existing skill (use skill_update).",
+            inputSchema: z.object({
+                name: z
+                    .string()
+                    .min(1)
+                    .describe('Short machine-friendly skill name (snake_case recommended), unique. E.g. "refund_dispute_escalation".'),
+                displayName: z
+                    .string()
+                    .optional()
+                    .describe('Human-readable display name. E.g. "Refund Dispute Escalation".'),
+                description: z
+                    .string()
+                    .min(1)
+                    .describe("One or two sentences explaining when this skill applies. Used for matching."),
+                instructions: z
+                    .string()
+                    .min(1)
+                    .describe("The full step-by-step instructions to follow when this skill matches. " +
+                    "Must come from the user — do not invent steps."),
+                tags: z
+                    .array(z.string())
+                    .optional()
+                    .describe('Domain tags for filtering (e.g. ["payments", "escalation"]).'),
+                ...scopeFields,
+                requestedBy: z
+                    .string()
+                    .optional()
+                    .describe("Identifier of the requesting user, when known."),
+            }),
+            execute: async (args) => {
+                if (args.scope === "scoped" && (args.scopeIds ?? []).length === 0) {
+                    return {
+                        success: false,
+                        error: '"scopeIds" must contain at least one scope id when scope="scoped".',
+                    };
+                }
+                const { requestedBy, ...skill } = args;
+                return runMutation(resolveManager, {
+                    type: "create",
+                    skill,
+                    ...(requestedBy ? { requestedBy } : {}),
+                });
+            },
+        }),
+        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.",
+            inputSchema: z.object({
+                skillId: z
+                    .string()
+                    .min(1)
+                    .describe("Id (or exact unique name) of the skill to update."),
+                displayName: z.string().optional(),
+                description: z.string().optional(),
+                instructions: z
+                    .string()
+                    .optional()
+                    .describe("Replacement instructions text, verbatim from the user."),
+                tags: z.array(z.string()).optional(),
+                ...scopeFields,
+                requestedBy: z.string().optional(),
+            }),
+            execute: async (args) => {
+                const { skillId, requestedBy, ...patch } = args;
+                if (Object.values(patch).every((v) => v === undefined)) {
+                    return {
+                        success: false,
+                        error: "Provide at least one field to update.",
+                    };
+                }
+                return runMutation(resolveManager, {
+                    type: "update",
+                    skillId,
+                    patch,
+                    ...(requestedBy ? { requestedBy } : {}),
+                });
+            },
+        }),
+        skill_delete: tool({
+            description: "Propose deleting (deprecating) an EXISTING skill. The skill stops matching but stays in " +
+                "storage for audit. Depending on host configuration this is applied immediately or queued " +
+                "for human approval. INVOKE ONLY WHEN the user explicitly asks to delete a skill.",
+            inputSchema: z.object({
+                skillId: z
+                    .string()
+                    .min(1)
+                    .describe("Id (or exact unique name) of the skill to delete."),
+                requestedBy: z.string().optional(),
+            }),
+            execute: async (args) => runMutation(resolveManager, {
+                type: "delete",
+                skillId: args.skillId,
+                ...(args.requestedBy ? { requestedBy: args.requestedBy } : {}),
+            }),
+        }),
+    };
+}

package/dist/skills/skillsManager.d.ts

@@ -0,0 +1,54 @@
+/**
+ * SkillsManager — orchestrates the skill store, cached index, index-first
+ * search (hydrating instructions only for matches), prompt-index rendering,
+ * and the mutation gate.
+ *
+ * Read paths fail open (errors surface as empty results + a warn log);
+ * write paths fail closed (errors reject the mutation).
+ */
+import type { SkillDefinition, SkillIndexItem, SkillMutationAction, SkillMutationResult, SkillSearchQuery, SkillsConfig } from "../types/index.js";
+export declare class SkillsManager {
+    private readonly config;
+    private readonly store;
+    private cachedIndex;
+    private cachedIndexAt;
+    /** Serializes writes within this process — see requestMutation(). */
+    private mutationQueue;
+    constructor(config: SkillsConfig);
+    /** Cached index read. TTL 0 disables caching. */
+    getIndex(forceRefresh?: boolean): Promise<SkillIndexItem[]>;
+    private invalidateIndex;
+    /**
+     * Index-first search: filter the cached index, hydrate only the matched
+     * entries (max `limit`) with instructions. Cost: one cached index read +
+     * N_matched store gets.
+     */
+    search(query: SkillSearchQuery): Promise<SkillDefinition[]>;
+    /** Index entries only — no instructions. For discovery/listing. */
+    list(scopeId?: string): Promise<SkillIndexItem[]>;
+    /** Fetch one skill by id, falling back to name lookup. */
+    get(idOrName: string): Promise<SkillDefinition | null>;
+    /**
+     * Render the system-prompt skills index for one call, or null when
+     * nothing is visible. Never includes instructions.
+     */
+    buildPromptIndex(options?: {
+        scopeId?: string;
+        tags?: 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
+     * routes. Direct programmatic `requestMutation` calls are intentionally not
+     * gated, so a host can still seed skills at startup.
+     */
+    get mutationsAllowed(): boolean;
+    /**
+     * Gate a proposed mutation through the host's onMutationRequest hook,
+     * then apply it when approved. No hook configured means direct apply
+     * (the tools themselves are already gated by allowMutations).
+     */
+    requestMutation(action: SkillMutationAction): Promise<SkillMutationResult>;
+    private applyMutation;
+    private assertNameAvailable;
+}