@juspay/neurolink 9.84.2 → 9.85.0

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

@@ -0,0 +1,16 @@
+/**
+ * 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 {};

package/dist/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "9.84.2",
+  "version": "9.85.0",
   "packageManager": "pnpm@10.15.1",
   "description": "Universal AI Development Platform with working MCP integration, multi-provider support, voice (TTS/STT/realtime), and professional CLI. 58+ external MCP servers discoverable, multimodal file processing, RAG pipelines. Build, test, and deploy AI applications with 21+ providers: OpenAI, Anthropic, Google AI Studio, Google Vertex, AWS Bedrock, Azure OpenAI, Mistral, LiteLLM, SageMaker, Hugging Face, Ollama, OpenAI-compatible, OpenRouter, DeepSeek, NVIDIA NIM, LM Studio, llama.cpp, plus voice (OpenAI TTS, ElevenLabs, Deepgram, Azure Speech).",
   "author": {
@@ -93,6 +93,7 @@
     "test:mcp:infra": "npx tsx test/continuous-test-suite-mcp-infra.ts",
     "test:providers-mocked": "npx tsx test/continuous-test-suite-providers-mocked.ts",
     "test:rag": "npx tsx test/continuous-test-suite-rag.ts",
+    "test:skills": "npx tsx test/continuous-test-suite-skills.ts",
     "test:servers": "npx tsx test/continuous-test-suite-servers.ts",
     "test:tool-reliability": "npx tsx test/continuous-test-suite-tool-reliability.ts",
     "test:google-native": "npx tsx test/continuous-test-suite-google-native.ts",