@juspay/neurolink 9.84.2 → 9.85.0

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

@@ -0,0 +1,296 @@
+/**
+ * Native skills support — versioned, discoverable instruction packs
+ * (SOPs, playbooks, workflows) exposed to the model via progressive
+ * disclosure: a cheap name+description index up front, full instructions
+ * loaded on demand through built-in skill tools.
+ *
+ * Architecture mirrors the Hippocampus memory subsystem: a `skills` config
+ * on the NeuroLink constructor lazily initializes a SkillsManager, which
+ * auto-registers built-in tools (search_skills / list_skills, plus gated
+ * mutation tools) and optionally injects a compact skills index into the
+ * system prompt of each generate()/stream() call.
+ *
+ * Naming: every exported type carries a `Skill` prefix to satisfy the
+ * `unique-type-names` ESLint rule.
+ */
+/** Visibility of a skill: available everywhere, or only in specific scopes. */
+export type SkillScopeKind = "global" | "scoped";
+/** Lifecycle status. Deletes are soft — deprecated skills stay in storage. */
+export type SkillLifecycleStatus = "active" | "deprecated";
+/**
+ * A complete skill: index metadata plus the full `instructions` body.
+ * `instructions` is the expensive part — it is only hydrated for matched
+ * skills, never included in index listings or the prompt index.
+ */
+export type SkillDefinition = {
+    /** Stable unique identifier (UUID for created skills, or derived from filename). */
+    id: string;
+    /** Machine-friendly unique name (snake_case recommended), used for matching. */
+    name: string;
+    /** Human-readable display name shown in listings. */
+    displayName?: string;
+    /** One or two sentences describing when the skill applies — the matching signal. */
+    description: string;
+    /** Full step-by-step instructions the model follows when the skill matches. */
+    instructions: string;
+    /** Domain tags for filtering (e.g. ["payments", "escalation"]). */
+    tags?: string[];
+    /** Visibility. Default: "global". */
+    scope?: SkillScopeKind;
+    /** Scope identifiers this skill is limited to when scope === "scoped" (e.g. channel/team/tenant ids). */
+    scopeIds?: string[];
+    /** Monotonic version, bumped on every approved update. Default: 1. */
+    version?: number;
+    /** Lifecycle status. Default: "active". */
+    status?: SkillLifecycleStatus;
+    /** ISO timestamp of creation. */
+    createdAt?: string;
+    /** ISO timestamp of last update. */
+    updatedAt?: string;
+    /** Free-form host metadata (audit fields, approval references, …). */
+    metadata?: Record<string, unknown>;
+};
+/** Lightweight index entry — everything except the instructions body. */
+export type SkillIndexItem = Omit<SkillDefinition, "instructions">;
+/**
+ * Pluggable persistence backend. NeuroLink ships memory and filesystem
+ * stores; hosts plug their own (S3, database, …) via the "custom" storage
+ * type. `index()` must be cheap relative to `get()` — it backs every
+ * search and prompt-index build.
+ */
+export type SkillStore = {
+    /** Fetch one skill (with instructions) by id. Null when absent. */
+    get(id: string): Promise<SkillDefinition | null>;
+    /** Create or replace a skill. */
+    put(skill: SkillDefinition): Promise<void>;
+    /** Hard-remove a skill from storage. (Soft deletes go through put().) */
+    delete(id: string): Promise<void>;
+    /** List index entries (no instructions) for all stored skills. */
+    index(): Promise<SkillIndexItem[]>;
+    /** Optional: drop any internal caches (called after mutations). */
+    invalidate?(): void;
+};
+/** In-process store, optionally seeded. Good for tests and embedded use. */
+export type SkillMemoryStorageConfig = {
+    type: "memory";
+    /** Initial skills to seed the store with. */
+    skills?: SkillDefinition[];
+};
+/**
+ * Directory-backed store. Reads three layouts:
+ *  - `<dir>/<id>.json` — one JSON-serialized SkillDefinition per file
+ *  - `<dir>/<name>.md` — markdown with YAML frontmatter; body = instructions
+ *  - `<dir>/<name>/SKILL.md` — Claude-skills-style directory layout
+ * Mutations always write `<id>.json`; markdown sources are read-only.
+ */
+export type SkillFilesystemStorageConfig = {
+    type: "filesystem";
+    /** Directory containing skill files. Created on first write if absent. */
+    path: string;
+};
+/** Host-provided store implementation (e.g. curator's S3 repository). */
+export type SkillCustomStorageConfig = {
+    type: "custom";
+    store: SkillStore;
+};
+/**
+ * S3-backed store. Layout: `<prefix>skills/<id>.json` per skill plus a
+ * `<prefix>index.json` document that is upserted on writes and rebuilt
+ * from a bucket listing when missing or corrupt (self-healing).
+ *
+ * Requires the optional peer `@aws-sdk/client-s3` to be installed in the
+ * host application (same pattern as memory's optional @juspay/hippocampus).
+ * Credentials default to the standard AWS provider chain when omitted.
+ */
+export type SkillS3StorageConfig = {
+    type: "s3";
+    bucket: string;
+    /** Key prefix inside the bucket. Default: "neurolink-skills/". */
+    prefix?: string;
+    region?: string;
+    /** Custom endpoint (MinIO, LocalStack, …). */
+    endpoint?: string;
+    /** Use path-style addressing (required by most S3-compatible stores). */
+    forcePathStyle?: boolean;
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+    };
+};
+/**
+ * Redis-backed store using NeuroLink's pooled Redis client (`redis` v5,
+ * already a core dependency). One JSON value per skill under
+ * `<keyPrefix><id>`; the index is derived via SCAN + MGET. Skills are
+ * persistent — no TTL is applied.
+ */
+export type SkillRedisStorageConfig = {
+    type: "redis";
+    url?: string;
+    host?: string;
+    port?: number;
+    username?: string;
+    password?: string;
+    db?: number;
+    /** Key prefix. Default: "neurolink:skills:". */
+    keyPrefix?: string;
+};
+/**
+ * Structural surface of the lazily-required @aws-sdk/client-s3 module —
+ * only the pieces the S3 skill store touches (same pattern as
+ * HippocampusModule for the optional memory peer).
+ */
+export type SkillS3ModuleSurface = {
+    S3Client: new (config: Record<string, unknown>) => {
+        send: (command: unknown) => Promise<unknown>;
+    };
+    GetObjectCommand: new (input: Record<string, unknown>) => unknown;
+    PutObjectCommand: new (input: Record<string, unknown>) => unknown;
+    DeleteObjectCommand: new (input: Record<string, unknown>) => unknown;
+    ListObjectsV2Command: new (input: Record<string, unknown>) => unknown;
+};
+/** Shape of the `<prefix>index.json` document maintained by the S3 store. */
+export type SkillS3IndexDocument = {
+    lastUpdated: string;
+    skills: SkillIndexItem[];
+};
+/**
+ * Minimal object-storage operations the S3 skill store runs on. The
+ * default implementation is created lazily from @aws-sdk/client-s3;
+ * tests and hosts with pre-built clients can inject their own.
+ */
+export type SkillS3ObjectOps = {
+    /** Fetch an object's body as a UTF-8 string. Null when the key is absent. */
+    getObject(key: string): Promise<string | null>;
+    putObject(key: string, body: string): Promise<void>;
+    deleteObject(key: string): Promise<void>;
+    /** List all object keys under a prefix (paginated internally). */
+    listKeys(prefix: string): Promise<string[]>;
+};
+export type SkillsStorageConfig = SkillMemoryStorageConfig | SkillFilesystemStorageConfig | SkillS3StorageConfig | SkillRedisStorageConfig | SkillCustomStorageConfig;
+/** Query accepted by SkillsManager.search() and the search_skills tool. */
+export type SkillSearchQuery = {
+    /** Keyword matched (case-insensitive substring) against name, displayName, and description. */
+    query?: string;
+    /** Tag filter, applied on top of the keyword match. */
+    tag?: string;
+    /** Scope filter: include global skills plus skills scoped to this id. */
+    scopeId?: string;
+    /** Maximum matches to hydrate. Defaults to SkillsConfig.maxMatches. */
+    limit?: number;
+};
+/** Input for creating a skill (id/version/status/timestamps are assigned by the manager). */
+export type SkillCreateInput = {
+    name: string;
+    displayName?: string;
+    description: string;
+    instructions: string;
+    tags?: string[];
+    scope?: SkillScopeKind;
+    scopeIds?: string[];
+    metadata?: Record<string, unknown>;
+};
+/** Patch for updating a skill. Only provided fields change; version is bumped. */
+export type SkillUpdateInput = Partial<SkillCreateInput>;
+/** A proposed mutation, passed to the host's onMutationRequest gate. */
+export type SkillMutationAction = {
+    type: "create";
+    skill: SkillCreateInput;
+    requestedBy?: string;
+} | {
+    type: "update";
+    skillId: string;
+    patch: SkillUpdateInput;
+    requestedBy?: string;
+} | {
+    type: "delete";
+    skillId: string;
+    requestedBy?: string;
+};
+/**
+ * Host decision for a proposed mutation.
+ *  - "approved": NeuroLink applies the mutation immediately.
+ *  - "rejected": nothing is written; `reason` is surfaced to the model.
+ *  - "pending": the host queued the action for out-of-band approval
+ *    (e.g. a Slack maker-checker flow) and will apply it itself later;
+ *    `reference` is surfaced to the model (e.g. an approval ticket id).
+ */
+export type SkillMutationDecision = {
+    outcome: "approved";
+} | {
+    outcome: "rejected";
+    reason?: string;
+} | {
+    outcome: "pending";
+    reference?: string;
+};
+/** Result envelope returned by SkillsManager.requestMutation(). */
+export type SkillMutationResult = {
+    decision: SkillMutationDecision;
+    /** The resulting skill after an applied create/update (absent for delete/pending/rejected). */
+    skill?: SkillDefinition;
+};
+/**
+ * Instance-level skills configuration (NeuroLink constructor `skills` option).
+ * Opt-in: nothing is registered or injected unless `enabled: true`.
+ */
+export type SkillsConfig = {
+    enabled: boolean;
+    /** Persistence backend. Default: `{ type: "memory" }`. */
+    storage?: SkillsStorageConfig;
+    /**
+     * Inject a compact skills index (names + descriptions, never instructions)
+     * into the system prompt of each generate()/stream() call. Default: true.
+     * Set false for curator-style pure tool-driven disclosure.
+     */
+    promptIndex?: boolean;
+    /** Maximum skills hydrated (with instructions) per search. Default: 5. */
+    maxMatches?: number;
+    /** Maximum entries rendered in the prompt index before truncation. Default: 50. */
+    promptIndexMaxItems?: number;
+    /** Index cache TTL in milliseconds. Default: 30000. 0 disables caching. */
+    indexCacheTtlMs?: number;
+    /** Default scope filter applied when a call/tool provides none. */
+    defaultScopeId?: string;
+    /**
+     * Register skill_create / skill_update / skill_delete tools so the model
+     * can propose skill changes. Default: false. Combine with
+     * `onMutationRequest` to gate writes behind host approval.
+     */
+    allowMutations?: boolean;
+    /**
+     * Host approval gate invoked before any mutation is applied. When absent
+     * and allowMutations is true, mutations apply directly. Errors thrown
+     * here reject the mutation (fail closed for writes).
+     */
+    onMutationRequest?: (action: SkillMutationAction) => Promise<SkillMutationDecision>;
+};
+/**
+ * Structural view of SkillsManager consumed by the skill tools factory —
+ * keeps skillTools.ts decoupled from the concrete manager class.
+ */
+export type SkillsManagerLike = {
+    search: (query: SkillSearchQuery) => Promise<SkillDefinition[]>;
+    list: (scopeId?: string) => Promise<SkillIndexItem[]>;
+    requestMutation: (action: SkillMutationAction) => Promise<SkillMutationResult>;
+};
+/** Options for the createSkillTools factory. */
+export type SkillToolsOptions = {
+    /** Include skill_create / skill_update / skill_delete. Default: false. */
+    allowMutations?: boolean;
+};
+/**
+ * Per-call skills control on generate()/stream(). Only effective when the
+ * instance was constructed with skills enabled; per-call wins over instance
+ * config (same precedence convention as per-call credentials).
+ */
+export type SkillsCallOptions = {
+    /** Master toggle for this call (prompt index only — tools stay registered). Default: true. */
+    enabled?: boolean;
+    /** Per-call override of SkillsConfig.promptIndex. */
+    promptIndex?: boolean;
+    /** Scope filter for the prompt index on this call. Overrides defaultScopeId. */
+    scopeId?: string;
+    /** Restrict the prompt index to skills carrying at least one of these tags. */
+    tags?: string[];
+};

package/dist/lib/types/skills.js

@@ -0,0 +1,17 @@
+/**
+ * Native skills support — versioned, discoverable instruction packs
+ * (SOPs, playbooks, workflows) exposed to the model via progressive
+ * disclosure: a cheap name+description index up front, full instructions
+ * loaded on demand through built-in skill tools.
+ *
+ * Architecture mirrors the Hippocampus memory subsystem: a `skills` config
+ * on the NeuroLink constructor lazily initializes a SkillsManager, which
+ * auto-registers built-in tools (search_skills / list_skills, plus gated
+ * mutation tools) and optionally injects a compact skills index into the
+ * system prompt of each generate()/stream() call.
+ *
+ * Naming: every exported type carries a `Skill` prefix to satisfy the
+ * `unique-type-names` ESLint rule.
+ */
+export {};
+//# sourceMappingURL=skills.js.map

package/dist/lib/types/stream.d.ts

@@ -1,6 +1,7 @@
 import type { AIProviderName } from "../constants/enums.js";
 import type { EvaluationData } from "./evaluation.js";
 import type { RAGConfig } from "./rag.js";
+import type { SkillsCallOptions } from "./skills.js";
 import type { AnalyticsData, ToolExecutionEvent, ToolExecutionSummary } from "../types/index.js";
 import type { MiddlewareFactoryOptions, OnChunkCallback, OnErrorCallback, OnFinishCallback } from "../types/middleware.js";
 import type { TokenUsage } from "./analytics.js";
@@ -534,6 +535,13 @@ export type StreamOptions = {
     };
     /** @deprecated Use `piiDetection`, `responseValidation`, and `inputValidation` instead. */
     processors?: ProcessorPipelineConfig;
+    /**
+     * Per-call skills control. Only effective when the instance was
+     * constructed with `skills.enabled: true`. Lets a call disable the
+     * prompt index, or narrow it by scope/tags. Per-call wins over
+     * instance config.
+     */
+    skills?: SkillsCallOptions;
 };
 /**
  * Stream function result type - Primary output format for streaming

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 {