@juspay/neurolink 9.84.2 → 9.85.0

package/dist/lib/server/routes/agentRoutes.js

@@ -7,7 +7,34 @@ import { ProviderFactory } from "../../factories/providerFactory.js";
 import { withSpan } from "../../telemetry/withSpan.js";
 import { tracers } from "../../telemetry/tracers.js";
 import { createStreamRedactor } from "../utils/redaction.js";
-import { AgentExecuteRequestSchema, createErrorResponse as createError, EmbedManyRequestSchema, EmbedRequestSchema, validateRequest, } from "../utils/validation.js";
+import { AgentExecuteRequestSchema, createErrorResponse as createError, EmbedManyRequestSchema, EmbedRequestSchema, SkillCreateRequestSchema, SkillUpdateRequestSchema, validateRequest, } from "../utils/validation.js";
+/**
+ * Resolve the skills manager from the server's NeuroLink instance, or a
+ * 503 error response when skills are not configured on this server.
+ */
+function resolveSkillsManager(ctx) {
+    const manager = ctx.neurolink.getSkillsManager();
+    if (!manager) {
+        return createError("SKILLS_UNAVAILABLE", "Skills are not enabled on this server — construct NeuroLink with a `skills` config.", undefined, ctx.requestId);
+    }
+    return manager;
+}
+/**
+ * Resolve the skills manager for a *mutating* route, or an error response when
+ * skills aren't configured (503) or mutations are disabled (allowMutations is
+ * not true). The LLM tools are already registration-gated; this applies the
+ * same switch to the REST create/update/delete endpoints.
+ */
+function resolveMutableSkillsManager(ctx) {
+    const manager = resolveSkillsManager(ctx);
+    if ("error" in manager) {
+        return manager;
+    }
+    if (!manager.mutationsAllowed) {
+        return createError("SKILLS_MUTATIONS_DISABLED", "Skill mutations are disabled on this server \u2014 construct NeuroLink with `skills.allowMutations: true` to enable create/update/delete.", undefined, ctx.requestId);
+    }
+    return manager;
+}
 /**
  * Create agent routes
  */
@@ -239,6 +266,134 @@ export function createAgentRoutes(basePath = "/api") {
                 description: "Generate embeddings for multiple texts in a batch",
                 tags: ["agent", "embeddings"],
             },
+            {
+                method: "GET",
+                path: `${basePath}/agent/skills`,
+                handler: async (ctx) => {
+                    const manager = resolveSkillsManager(ctx);
+                    if ("error" in manager) {
+                        return manager;
+                    }
+                    try {
+                        const skills = await manager.list(ctx.query.scopeId);
+                        return { skills, count: skills.length };
+                    }
+                    catch (error) {
+                        return createError("EXECUTION_FAILED", error instanceof Error ? error.message : "Skills listing failed", undefined, ctx.requestId);
+                    }
+                },
+                description: "List active skills (index only — no instructions). Optional ?scopeId= filter.",
+                tags: ["agent", "skills"],
+            },
+            {
+                method: "GET",
+                path: `${basePath}/agent/skills/:id`,
+                handler: async (ctx) => {
+                    const manager = resolveSkillsManager(ctx);
+                    if ("error" in manager) {
+                        return manager;
+                    }
+                    try {
+                        const skill = await manager.get(ctx.params.id);
+                        if (!skill) {
+                            return createError("NOT_FOUND", `Skill "${ctx.params.id}" not found`, undefined, ctx.requestId);
+                        }
+                        return skill;
+                    }
+                    catch (error) {
+                        return createError("EXECUTION_FAILED", error instanceof Error ? error.message : "Skill lookup failed", undefined, ctx.requestId);
+                    }
+                },
+                description: "Fetch one skill (by id or exact name) with instructions",
+                tags: ["agent", "skills"],
+            },
+            {
+                method: "POST",
+                path: `${basePath}/agent/skills`,
+                handler: async (ctx) => {
+                    const manager = resolveMutableSkillsManager(ctx);
+                    if ("error" in manager) {
+                        return manager;
+                    }
+                    const validation = validateRequest(SkillCreateRequestSchema, ctx.body, ctx.requestId);
+                    if (!validation.success) {
+                        return validation.error;
+                    }
+                    const { requestedBy, ...skill } = validation.data;
+                    try {
+                        const result = await manager.requestMutation({
+                            type: "create",
+                            skill,
+                            // Authenticated identity wins over caller-supplied attribution.
+                            ...(ctx.user?.id || requestedBy
+                                ? { requestedBy: ctx.user?.id ?? requestedBy }
+                                : {}),
+                        });
+                        return result;
+                    }
+                    catch (error) {
+                        return createError("EXECUTION_FAILED", error instanceof Error ? error.message : "Skill create failed", undefined, ctx.requestId);
+                    }
+                },
+                description: "Create a skill (routed through the host's onMutationRequest gate when configured)",
+                tags: ["agent", "skills"],
+            },
+            {
+                method: "PATCH",
+                path: `${basePath}/agent/skills/:id`,
+                handler: async (ctx) => {
+                    const manager = resolveMutableSkillsManager(ctx);
+                    if ("error" in manager) {
+                        return manager;
+                    }
+                    const validation = validateRequest(SkillUpdateRequestSchema, ctx.body, ctx.requestId);
+                    if (!validation.success) {
+                        return validation.error;
+                    }
+                    const { requestedBy, ...patch } = validation.data;
+                    try {
+                        const result = await manager.requestMutation({
+                            type: "update",
+                            skillId: ctx.params.id,
+                            patch,
+                            ...(ctx.user?.id || requestedBy
+                                ? { requestedBy: ctx.user?.id ?? requestedBy }
+                                : {}),
+                        });
+                        return result;
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : "Skill update failed";
+                        return createError(message.includes("not found") ? "NOT_FOUND" : "EXECUTION_FAILED", message, undefined, ctx.requestId);
+                    }
+                },
+                description: "Update a skill (patch semantics; version is bumped)",
+                tags: ["agent", "skills"],
+            },
+            {
+                method: "DELETE",
+                path: `${basePath}/agent/skills/:id`,
+                handler: async (ctx) => {
+                    const manager = resolveMutableSkillsManager(ctx);
+                    if ("error" in manager) {
+                        return manager;
+                    }
+                    try {
+                        const result = await manager.requestMutation({
+                            type: "delete",
+                            skillId: ctx.params.id,
+                            ...(ctx.user?.id ? { requestedBy: ctx.user.id } : {}),
+                        });
+                        return result;
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : "Skill delete failed";
+                        return createError(message.includes("not found") ? "NOT_FOUND" : "EXECUTION_FAILED", message, undefined, ctx.requestId);
+                    }
+                },
+                description: "Soft-delete (deprecate) a skill",
+                tags: ["agent", "skills"],
+            },
         ],
     };
 }

package/dist/lib/server/utils/validation.d.ts

@@ -99,6 +99,38 @@ export declare const EmbedManyRequestSchema: z.ZodObject<{
     provider: z.ZodOptional<z.ZodString>;
     model: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * Skill create request schema
+ */
+export declare const SkillCreateRequestSchema: z.ZodObject<{
+    name: z.ZodString;
+    displayName: z.ZodOptional<z.ZodString>;
+    description: z.ZodString;
+    instructions: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    scope: z.ZodOptional<z.ZodEnum<{
+        global: "global";
+        scoped: "scoped";
+    }>>;
+    scopeIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    requestedBy: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Skill update request schema — all fields optional (patch semantics)
+ */
+export declare const SkillUpdateRequestSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    displayName: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+    description: z.ZodOptional<z.ZodString>;
+    instructions: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    scope: z.ZodOptional<z.ZodOptional<z.ZodEnum<{
+        global: "global";
+        scoped: "scoped";
+    }>>>;
+    scopeIds: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    requestedBy: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
 /**
  * Type guard to check if a value is an ErrorResponse
  */

package/dist/lib/server/utils/validation.js

@@ -127,6 +127,23 @@ export const EmbedManyRequestSchema = z.object({
     provider: z.string().optional(),
     model: z.string().optional(),
 });
+/**
+ * Skill create request schema
+ */
+export const SkillCreateRequestSchema = z.object({
+    name: z.string().min(1, "Name is required"),
+    displayName: z.string().optional(),
+    description: z.string().min(1, "Description is required"),
+    instructions: z.string().min(1, "Instructions are required"),
+    tags: z.array(z.string()).optional(),
+    scope: z.enum(["global", "scoped"]).optional(),
+    scopeIds: z.array(z.string()).optional(),
+    requestedBy: z.string().optional(),
+});
+/**
+ * Skill update request schema — all fields optional (patch semantics)
+ */
+export const SkillUpdateRequestSchema = SkillCreateRequestSchema.partial();
 // ============================================
 // Error Response Type Guards / Helpers
 // ============================================
@@ -159,6 +176,7 @@ function getDefaultHttpStatus(code) {
         RATE_LIMIT_EXCEEDED: 429,
         MCP_UNAVAILABLE: 503,
         MEMORY_UNAVAILABLE: 503,
+        SKILLS_UNAVAILABLE: 503,
         EXECUTION_FAILED: 500,
         INTERNAL_ERROR: 500,
     };

package/dist/lib/session/globalSessionState.d.ts

@@ -1,5 +1,5 @@
 import { NeuroLink } from "../neurolink.js";
-import type { ClassifierRouterConfig, ConversationMemoryConfig, LoopSessionState, SessionVariableValue, ToolRoutingConfig } from "../types/index.js";
+import type { ClassifierRouterConfig, ConversationMemoryConfig, LoopSessionState, SessionVariableValue, SkillsConfig, ToolRoutingConfig } from "../types/index.js";
 export declare class GlobalSessionManager {
     private static instance;
     private loopSession;
@@ -7,6 +7,8 @@ export declare class GlobalSessionManager {
     private _toolRoutingConfig;
     /** Optional classifier-router config set by CLI handlers before SDK construction. */
     private _classifierRouterConfig;
+    /** Optional skills config set by CLI handlers before SDK construction. */
+    private _skillsConfig;
     static getInstance(): GlobalSessionManager;
     setLoopSession(config?: ConversationMemoryConfig): string;
     /**
@@ -51,6 +53,13 @@ export declare class GlobalSessionManager {
      * already exists).
      */
     setClassifierRouterConfig(config: ClassifierRouterConfig): void;
+    /**
+     * Store a skills config to be injected at SDK construction time.
+     * Call this BEFORE `getOrCreateNeuroLink()` inside a command handler.
+     * When a loop session is already active the config is ignored (the instance
+     * already exists).
+     */
+    setSkillsConfig(config: SkillsConfig): void;
     getOrCreateNeuroLink(): NeuroLink;
     getCurrentSessionId(): string | undefined;
     setSessionVariable(key: string, value: SessionVariableValue): void;

package/dist/lib/session/globalSessionState.js

@@ -35,6 +35,8 @@ export class GlobalSessionManager {
     _toolRoutingConfig = undefined;
     /** Optional classifier-router config set by CLI handlers before SDK construction. */
     _classifierRouterConfig = undefined;
+    /** Optional skills config set by CLI handlers before SDK construction. */
+    _skillsConfig = undefined;
     static getInstance() {
         if (!GlobalSessionManager.instance) {
             GlobalSessionManager.instance = new GlobalSessionManager();
@@ -155,6 +157,18 @@ export class GlobalSessionManager {
         }
         this._classifierRouterConfig = config;
     }
+    /**
+     * Store a skills config to be injected at SDK construction time.
+     * Call this BEFORE `getOrCreateNeuroLink()` inside a command handler.
+     * When a loop session is already active the config is ignored (the instance
+     * already exists).
+     */
+    setSkillsConfig(config) {
+        if (this.hasActiveSession()) {
+            return;
+        }
+        this._skillsConfig = config;
+    }
     getOrCreateNeuroLink() {
         const session = this.getLoopSession();
         if (session) {
@@ -178,6 +192,10 @@ export class GlobalSessionManager {
             options.classifierRouter = this._classifierRouterConfig;
             this._classifierRouterConfig = undefined;
         }
+        if (this._skillsConfig) {
+            options.skills = this._skillsConfig;
+            this._skillsConfig = undefined;
+        }
         return new NeuroLink(Object.keys(options).length ? options : undefined);
     }
     getCurrentSessionId() {

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

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+import type { SkillDefinition, SkillIndexItem, SkillSearchQuery } from "../types/index.js";
+/** Strip instructions from a full definition to form an index entry. */
+export declare function toSkillIndexItem(skill: SkillDefinition): SkillIndexItem;
+/** Filter index entries by query/tag/scope. Active skills only. */
+export declare function filterSkillIndex(items: SkillIndexItem[], query: SkillSearchQuery): SkillIndexItem[];
+/**
+ * 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 declare function formatSkillsPromptIndex(items: SkillIndexItem[], maxItems: number): string | null;

package/dist/lib/skills/skillMatcher.js

@@ -0,0 +1,80 @@
+/**
+ * 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);
+}
+//# sourceMappingURL=skillMatcher.js.map

package/dist/lib/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/lib/skills/skillStoreRedis.js

@@ -0,0 +1,98 @@
+/**
+ * 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;
+        }
+    }
+}
+//# sourceMappingURL=skillStoreRedis.js.map

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