@juspay/neurolink 9.84.2 → 9.85.1

package/dist/neurolink.d.ts

@@ -12,6 +12,7 @@ import type { RedisConversationMemoryManager } from "./core/redisConversationMem
 import { ExternalServerManager } from "./mcp/externalServerManager.js";
 import { MCPToolRegistry } from "./mcp/toolRegistry.js";
 import type { DynamicOptions } from "./types/index.js";
+import { SkillsManager } from "./skills/skillsManager.js";
 import { TaskManager } from "./tasks/taskManager.js";
 /**
  * Curator P2-4 dedup (concurrency-safe): native providers emit
@@ -140,6 +141,8 @@ export declare class NeuroLink {
     private cachedFileTools;
     private memoryInstance?;
     private memorySDKConfig?;
+    private skillsManagerInstance?;
+    private skillsConfig?;
     /**
      * Extract and set Langfuse context from options with proper async scoping
      */
@@ -264,6 +267,31 @@ export declare class NeuroLink {
      * Only registered when Redis conversation memory is active.
      */
     private registerMemoryRetrievalTools;
+    /**
+     * Lazy initialization for the skills subsystem — mirrors ensureMemoryReady().
+     * Returns null (and stays null) when skills are not configured or the
+     * store failed to initialize; read paths fail open on that null.
+     */
+    private ensureSkillsReady;
+    /**
+     * Register the built-in skill tools (search_skills / list_skills, plus
+     * mutation tools when allowMutations is set). Follows the
+     * registerMemoryRetrievalTools() pattern: registered via registerTool()
+     * so they land in the "user-defined" category that reaches the LLM tool
+     * schema, with the manager resolved lazily at execution time.
+     */
+    private registerSkillTools;
+    /**
+     * Append the compact skills index (names + descriptions, never
+     * instructions) to the system prompt for one generate()/stream() call.
+     * Fails open: any error leaves the prompt untouched.
+     */
+    private applySkillsPromptIndex;
+    /**
+     * Programmatic access to the skills subsystem (search/list/get/mutations).
+     * Returns null when skills are not configured or failed to initialize.
+     */
+    getSkillsManager(): SkillsManager | null;
     /** Format memory context for prompt inclusion */
     private formatMemoryContext;
     /**

package/dist/neurolink.js

@@ -54,6 +54,8 @@ import { MCPToolRegistry } from "./mcp/toolRegistry.js";
 import { resolveDynamicArgument } from "./dynamic/dynamicResolver.js";
 import { initializeHippocampus } from "./memory/hippocampusInitializer.js";
 import { createMemoryRetrievalTools } from "./memory/memoryRetrievalTools.js";
+import { SkillsManager } from "./skills/skillsManager.js";
+import { createSkillTools } from "./skills/skillTools.js";
 import { getMetricsAggregator, MetricsAggregator, } from "./observability/metricsAggregator.js";
 import { SpanStatus, SpanType, CircuitBreakerOpenError, ConversationMemoryError, ModelAccessDeniedError, } from "./types/index.js";
 import { SpanSerializer } from "./observability/utils/spanSerializer.js";
@@ -458,6 +460,10 @@ export class NeuroLink {
     // Memory instance and config
     memoryInstance;
     memorySDKConfig;
+    // Skills subsystem — lazily initialized manager + instance config.
+    // `undefined` = not yet attempted, `null` = init failed (stay disabled).
+    skillsManagerInstance;
+    skillsConfig;
     /**
      * Extract and set Langfuse context from options with proper async scoping
      */
@@ -830,6 +836,10 @@ export class NeuroLink {
         this.initializeMCPEnhancements(config);
         this.registerFileTools();
         this.registerMemoryRetrievalTools();
+        if (config?.skills?.enabled) {
+            this.skillsConfig = config.skills;
+            this.registerSkillTools();
+        }
         this.initializeLangfuse(constructorId, constructorStartTime, constructorHrTimeStart);
         this.initializeMetricsListeners();
         this.logConstructorComplete(constructorId, constructorStartTime, constructorHrTimeStart);
@@ -1243,6 +1253,107 @@ export class NeuroLink {
         });
         logger.info("[NeuroLink] Memory retrieval tools registered");
     }
+    /**
+     * Lazy initialization for the skills subsystem — mirrors ensureMemoryReady().
+     * Returns null (and stays null) when skills are not configured or the
+     * store failed to initialize; read paths fail open on that null.
+     */
+    ensureSkillsReady() {
+        if (this.skillsManagerInstance !== undefined) {
+            return this.skillsManagerInstance;
+        }
+        if (!this.skillsConfig?.enabled) {
+            this.skillsManagerInstance = null;
+            return null;
+        }
+        try {
+            this.skillsManagerInstance = new SkillsManager(this.skillsConfig);
+        }
+        catch (error) {
+            logger.warn("[NeuroLink] Skills initialization failed — skills disabled for this instance", { error: error instanceof Error ? error.message : String(error) });
+            this.skillsManagerInstance = null;
+        }
+        return this.skillsManagerInstance;
+    }
+    /**
+     * Register the built-in skill tools (search_skills / list_skills, plus
+     * mutation tools when allowMutations is set). Follows the
+     * registerMemoryRetrievalTools() pattern: registered via registerTool()
+     * so they land in the "user-defined" category that reaches the LLM tool
+     * schema, with the manager resolved lazily at execution time.
+     */
+    registerSkillTools() {
+        const canonicalTools = createSkillTools(() => this.ensureSkillsReady(), {
+            allowMutations: this.skillsConfig?.allowMutations === true,
+        });
+        for (const [toolName, toolDef] of Object.entries(canonicalTools)) {
+            this.registerTool(toolName, {
+                name: toolName,
+                description: toolDef.description ?? toolName,
+                // Zod schema — registerTool() detects isZodSchema and preserves it
+                // so ToolsManager gives the LLM full parameter types.
+                inputSchema: toolDef
+                    .inputSchema,
+                execute: async (params) => withTimeout(toolDef.execute(params, { toolCallId: "skill-tool", messages: [] }), TOOL_TIMEOUTS.EXECUTION_DEFAULT_MS, ErrorFactory.toolTimeout(toolName, TOOL_TIMEOUTS.EXECUTION_DEFAULT_MS)),
+            });
+        }
+        logger.info(`[NeuroLink] Registered ${Object.keys(canonicalTools).length} skill tools`, { allowMutations: this.skillsConfig?.allowMutations === true });
+    }
+    /**
+     * Append the compact skills index (names + descriptions, never
+     * instructions) to the system prompt for one generate()/stream() call.
+     * Fails open: any error leaves the prompt untouched.
+     */
+    async applySkillsPromptIndex(options) {
+        if (!this.skillsConfig?.enabled || options.skills?.enabled === false) {
+            return;
+        }
+        // Per-call promptIndex wins over instance config; default is on.
+        const promptIndexEnabled = options.skills?.promptIndex ?? this.skillsConfig.promptIndex ?? true;
+        if (!promptIndexEnabled) {
+            return;
+        }
+        // Media-only modes have no meaningful text prompt to augment.
+        const mode = options.output?.mode;
+        if (mode === "avatar" ||
+            mode === "music" ||
+            mode === "video" ||
+            mode === "ppt") {
+            return;
+        }
+        try {
+            const manager = this.ensureSkillsReady();
+            if (!manager) {
+                return;
+            }
+            const block = await manager.buildPromptIndex({
+                ...(options.skills?.scopeId !== undefined
+                    ? { scopeId: options.skills.scopeId }
+                    : {}),
+                ...(options.skills?.tags !== undefined
+                    ? { tags: options.skills.tags }
+                    : {}),
+            });
+            if (block) {
+                options.systemPrompt = options.systemPrompt
+                    ? `${options.systemPrompt}\n\n${block}`
+                    : block;
+                logger.debug("[NeuroLink] Skills prompt index injected", {
+                    blockLength: block.length,
+                });
+            }
+        }
+        catch (error) {
+            logger.warn("[NeuroLink] Skills prompt index injection failed — continuing without it", { error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    /**
+     * Programmatic access to the skills subsystem (search/list/get/mutations).
+     * Returns null when skills are not configured or failed to initialize.
+     */
+    getSkillsManager() {
+        return this.ensureSkillsReady();
+    }
     /** Format memory context for prompt inclusion */
     formatMemoryContext(memoryContext, currentInput) {
         return `Context from previous conversations:
@@ -3499,6 +3610,9 @@ Current user's request: ${currentInput}`;
                 });
             }
         }
+        // Skills: append the compact skills index to the system prompt so the
+        // model knows which skills exist (bodies load via search_skills).
+        await this.applySkillsPromptIndex(options);
         // Media-only modes (avatar, music, video, ppt) do not have a meaningful
         // text prompt to augment with memory — skip injection to avoid corrupting
         // the empty/synthesized input.text that was set for these modes.
@@ -7037,6 +7151,9 @@ Current user's request: ${currentInput}`;
                 logger.warn("Memory retrieval failed:", error);
             }
         }
+        // Skills: append the compact skills index to the system prompt so the
+        // model knows which skills exist (bodies load via search_skills).
+        await this.applySkillsPromptIndex(options);
         // Apply orchestration if enabled and no specific provider/model requested
         if (this.enableOrchestration && !options.provider && !options.model) {
             try {

package/dist/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/server/routes/claudeProxyRoutes.d.ts

@@ -11,7 +11,7 @@
  */
 import { buildTranslationOptions } from "../../proxy/proxyTranslationEngine.js";
 import type { ModelRouter } from "../../proxy/modelRouter.js";
-import type { ParsedClaudeError, ProxyPassthroughAccount, RouteGroup, RuntimeAccountState } from "../../types/index.js";
+import type { AccountCooldownPlan, AccountQuota, ParsedClaudeError, ProxyPassthroughAccount, RouteGroup, RuntimeAccountState } from "../../types/index.js";
 /** Resolve the configured primary's stable key to its current index in the
  *  request's enabledAccounts list. Returns 0 (insertion-order fallback) when
  *  no key is configured or the key cannot be matched (account disabled/
@@ -23,6 +23,41 @@ declare function resolveHomeIndex(enabledAccounts: ProxyPassthroughAccount[]): n
  *  account once its rate limit window expires. Called at the start of each
  *  request. Home is resolved fresh per call via resolveHomeIndex. */
 declare function maybeResetPrimaryToHome(enabledAccounts: ProxyPassthroughAccount[]): void;
+/** Convert an Anthropic unified-window reset (Unix epoch SECONDS, per the
+ *  `anthropic-ratelimit-unified-*-reset` headers) into epoch-ms. Tolerates a
+ *  value already expressed in ms (some intermediaries normalise it). Returns
+ *  undefined for absent/zero/past-or-garbage timestamps so callers can fall
+ *  back to retry-after. */
+declare function resetEpochToMs(resetEpoch: number | undefined, now: number): number | undefined;
+/**
+ * Decide how to cool an account after a genuine (non-anti-abuse) 429.
+ *
+ * The unified subscription limits expose per-window status + reset:
+ *   - weekly (7d) "rejected"  → hard cap for the week; cool until the 7d reset.
+ *   - session (5h) "rejected" → paced out for this session; cool until the 5h reset.
+ * Both mean "retrying this account is futile until its window resets" → rotate
+ * immediately (no same-account retries) and park the account until the ACTUAL
+ * reset — never the legacy 60s hardcap that let us re-hammer a spent account.
+ *
+ * Anything else (window still "allowed" but momentarily 429'd — a per-minute
+ * burst / acceleration limit) is transient: honor retry-after as a floor,
+ * allow a couple of jittered same-account retries, then a short cooldown.
+ */
+declare function planCooldownFor429(quota: AccountQuota | null, retryAfterMs: number, now: number): AccountCooldownPlan;
+/**
+ * Order accounts to MAXIMIZE quota utilization (fill-first, smart order):
+ * spend the account whose window refreshes SOONEST first, so its about-to-reset
+ * allowance isn't wasted, then move to accounts with longer-dated resets.
+ *
+ * Priority among usable accounts:
+ *   1. soonest WEEKLY (7d) reset  — the scarce, use-it-or-lose-it ceiling
+ *   2. soonest SESSION (5h) reset
+ *   3. highest weekly utilization — finish off the one closest to done
+ * Accounts with no quota data yet keep insertion order (stable sort) and sit
+ * after those with a known soonest reset. Cooling/rejected accounts sort last,
+ * soonest-back-to-service first, as last resort.
+ */
+declare function orderAccountsByQuota(accounts: ProxyPassthroughAccount[], now: number): ProxyPassthroughAccount[];
 /**
  * Create Claude-compatible proxy routes.
  *
@@ -57,6 +92,9 @@ export declare function isTransientHttpFailure(status: number, errBody: string):
 export declare const __testHooks: {
     resolveHomeIndex: typeof resolveHomeIndex;
     maybeResetPrimaryToHome: typeof maybeResetPrimaryToHome;
+    planCooldownFor429: typeof planCooldownFor429;
+    orderAccountsByQuota: typeof orderAccountsByQuota;
+    resetEpochToMs: typeof resetEpochToMs;
     setConfiguredPrimaryAccountKey: (key: string | undefined) => void;
     getConfiguredPrimaryAccountKey: () => string | undefined;
     setPrimaryAccountIndex: (index: number) => void;