@juspay/neurolink 9.84.2 → 9.85.1

package/dist/skills/skillsManager.js

@@ -0,0 +1,219 @@
+/**
+ * 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 { randomUUID } from "node:crypto";
+import { logger } from "../utils/logger.js";
+import { filterSkillIndex, formatSkillsPromptIndex } from "./skillMatcher.js";
+import { createSkillStore } from "./skillStores.js";
+const DEFAULT_MAX_MATCHES = 5;
+const DEFAULT_PROMPT_INDEX_MAX_ITEMS = 50;
+const DEFAULT_INDEX_CACHE_TTL_MS = 30_000;
+export class SkillsManager {
+    config;
+    store;
+    cachedIndex = null;
+    cachedIndexAt = 0;
+    /** Serializes writes within this process — see requestMutation(). */
+    mutationQueue = Promise.resolve();
+    constructor(config) {
+        this.config = config;
+        this.store = createSkillStore(config.storage);
+    }
+    /** Cached index read. TTL 0 disables caching. */
+    async getIndex(forceRefresh = false) {
+        const ttl = this.config.indexCacheTtlMs ?? DEFAULT_INDEX_CACHE_TTL_MS;
+        const fresh = this.cachedIndex !== null &&
+            ttl > 0 &&
+            Date.now() - this.cachedIndexAt < ttl;
+        if (fresh && !forceRefresh && this.cachedIndex) {
+            return this.cachedIndex;
+        }
+        const index = await this.store.index();
+        this.cachedIndex = index;
+        this.cachedIndexAt = Date.now();
+        return index;
+    }
+    invalidateIndex() {
+        this.cachedIndex = null;
+        this.store.invalidate?.();
+    }
+    /**
+     * 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.
+     */
+    async search(query) {
+        const limit = query.limit ?? this.config.maxMatches ?? DEFAULT_MAX_MATCHES;
+        const scopeId = query.scopeId ?? this.config.defaultScopeId;
+        const index = await this.getIndex();
+        const matched = filterSkillIndex(index, {
+            ...query,
+            ...(scopeId !== undefined ? { scopeId } : {}),
+            limit,
+        });
+        const hydrated = await Promise.all(matched.map((item) => this.store.get(item.id)));
+        return hydrated.filter((s) => s !== null);
+    }
+    /** Index entries only — no instructions. For discovery/listing. */
+    async list(scopeId) {
+        const effectiveScopeId = scopeId ?? this.config.defaultScopeId;
+        const index = await this.getIndex();
+        return filterSkillIndex(index, {
+            ...(effectiveScopeId !== undefined ? { scopeId: effectiveScopeId } : {}),
+        });
+    }
+    /** Fetch one skill by id, falling back to name lookup. */
+    async get(idOrName) {
+        const byId = await this.store.get(idOrName);
+        if (byId) {
+            return byId;
+        }
+        const index = await this.getIndex();
+        // Prefer an active skill when resolving by name: a soft-deleted skill and a
+        // later same-named active skill can coexist in the index, so a bare
+        // name-find would resolve non-deterministically to the stale deprecated one
+        // across store backends. Fall back to any match only when no active skill
+        // carries the name.
+        const entry = index.find((item) => item.name === idOrName && (item.status ?? "active") === "active") ?? index.find((item) => item.name === idOrName);
+        return entry ? this.store.get(entry.id) : null;
+    }
+    /**
+     * Render the system-prompt skills index for one call, or null when
+     * nothing is visible. Never includes instructions.
+     */
+    async buildPromptIndex(options) {
+        let items = await this.list(options?.scopeId);
+        if (options?.tags && options.tags.length > 0) {
+            const wanted = options.tags.map((t) => t.toLowerCase());
+            items = items.filter((item) => (item.tags ?? []).some((t) => wanted.includes(t.toLowerCase())));
+        }
+        return formatSkillsPromptIndex(items, this.config.promptIndexMaxItems ?? DEFAULT_PROMPT_INDEX_MAX_ITEMS);
+    }
+    /**
+     * 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() {
+        return this.config.allowMutations ?? false;
+    }
+    /**
+     * 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).
+     */
+    async requestMutation(action) {
+        let decision = { outcome: "approved" };
+        if (this.config.onMutationRequest) {
+            decision = await this.config.onMutationRequest(action);
+        }
+        if (decision.outcome !== "approved") {
+            return { decision };
+        }
+        // Serialize writes within this process so the name-uniqueness check and
+        // the store write can never interleave across concurrent mutations.
+        // Cross-process races remain possible with plain-object stores (S3,
+        // Redis) — hosts needing strict global uniqueness should serialize via
+        // their onMutationRequest gate; the S3 index additionally self-heals.
+        const run = this.mutationQueue.then(() => this.applyMutation(action));
+        this.mutationQueue = run.catch(() => undefined);
+        const skill = await run;
+        return { decision, ...(skill ? { skill } : {}) };
+    }
+    async applyMutation(action) {
+        const now = new Date().toISOString();
+        if (action.type === "create") {
+            await this.assertNameAvailable(action.skill.name);
+            const skill = {
+                id: randomUUID(),
+                version: 1,
+                status: "active",
+                createdAt: now,
+                updatedAt: now,
+                ...action.skill,
+            };
+            assertScopeConsistent(skill);
+            await this.store.put(skill);
+            this.invalidateIndex();
+            logger.info("[SkillsManager] Skill created", {
+                skillId: skill.id,
+                name: skill.name,
+            });
+            return skill;
+        }
+        if (action.type === "update") {
+            const existing = await this.get(action.skillId);
+            if (!existing) {
+                throw new Error(`Skill "${action.skillId}" not found`);
+            }
+            if (action.patch.name && action.patch.name !== existing.name) {
+                await this.assertNameAvailable(action.patch.name, existing.id);
+            }
+            const updated = {
+                ...existing,
+                ...definedFields(action.patch),
+                id: existing.id,
+                version: (existing.version ?? 1) + 1,
+                updatedAt: now,
+            };
+            assertScopeConsistent(updated);
+            await this.store.put(updated);
+            this.invalidateIndex();
+            logger.info("[SkillsManager] Skill updated", {
+                skillId: updated.id,
+                version: updated.version,
+            });
+            return updated;
+        }
+        // delete — soft: mark deprecated so the skill drops out of active
+        // listings but stays in storage for audit/undo.
+        const existing = await this.get(action.skillId);
+        if (!existing) {
+            throw new Error(`Skill "${action.skillId}" not found`);
+        }
+        if (existing.status === "deprecated") {
+            throw new Error(`Skill "${existing.name}" is already deleted`);
+        }
+        const deprecated = {
+            ...existing,
+            status: "deprecated",
+            updatedAt: now,
+        };
+        await this.store.put(deprecated);
+        this.invalidateIndex();
+        logger.info("[SkillsManager] Skill deprecated", {
+            skillId: existing.id,
+            name: existing.name,
+        });
+        return deprecated;
+    }
+    async assertNameAvailable(name, excludeId) {
+        const index = await this.getIndex(true);
+        const clash = index.find((item) => item.id !== excludeId &&
+            item.name.toLowerCase() === name.toLowerCase() &&
+            (item.status ?? "active") === "active");
+        if (clash) {
+            throw new Error(`A skill named "${name}" already exists`);
+        }
+    }
+}
+/**
+ * A scoped skill without scopeIds can never match anything — reject the
+ * write instead of persisting an unmatchable skill. Validated post-merge so
+ * both create and patch-style update paths are covered.
+ */
+function assertScopeConsistent(skill) {
+    if (skill.scope === "scoped" && (skill.scopeIds ?? []).length === 0) {
+        throw new Error('A skill with scope "scoped" must have at least one entry in scopeIds');
+    }
+}
+/** Shallow-copy only the defined fields of a patch (undefined must not overwrite). */
+function definedFields(patch) {
+    return Object.fromEntries(Object.entries(patch).filter(([, value]) => value !== undefined));
+}

package/dist/types/config.d.ts

@@ -12,6 +12,7 @@ import type { NeurolinkCredentials } from "./providers.js";
 import type { ModelPoolConfig } from "./modelPool.js";
 import type { RequestRouter } from "./requestRouter.js";
 import type { ClassifierRouterConfig } from "./classifierRouter.js";
+import type { SkillsConfig } from "./skills.js";
 /**
  * Main NeuroLink configuration type
  */
@@ -114,6 +115,15 @@ export type NeurolinkConstructorConfig = {
      * caller pinned both `provider` and `model`. See {@link ClassifierRouterConfig}.
      */
     classifierRouter?: ClassifierRouterConfig;
+    /**
+     * Native skills: versioned, discoverable instruction packs (SOPs,
+     * playbooks) with progressive disclosure. When enabled, built-in
+     * search_skills / list_skills tools are registered (plus gated mutation
+     * tools) and a compact skills index is injected into the system prompt
+     * of each generate()/stream() call. Opt-in and fails open on read paths.
+     * See {@link SkillsConfig}.
+     */
+    skills?: SkillsConfig;
 };
 /**
  * Configuration for MCP enhancement modules wired into generate()/stream() paths.

package/dist/types/generate.d.ts

@@ -1,5 +1,6 @@
 import type { AIProviderName } from "../constants/enums.js";
 import type { RAGConfig } from "./rag.js";
+import type { SkillsCallOptions } from "./skills.js";
 import type { AnalyticsData, TokenUsage } from "./analytics.js";
 import type { JsonValue } from "./common.js";
 import type { Content, ImageWithAltText } from "./content.js";
@@ -615,6 +616,13 @@ export type GenerateOptions = {
      * @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;
 };
 /**
  * Represents an additional user whose memory should be included in a generate/stream call.

package/dist/types/index.d.ts

@@ -46,6 +46,7 @@ export * from "./scorer.js";
 export * from "./sdk.js";
 export * from "./server.js";
 export * from "./service.js";
+export * from "./skills.js";
 export * from "./stream.js";
 export * from "./subscription.js";
 export * from "./task.js";

package/dist/types/index.js

@@ -47,6 +47,7 @@ export * from "./scorer.js";
 export * from "./sdk.js";
 export * from "./server.js";
 export * from "./service.js";
+export * from "./skills.js";
 export * from "./stream.js";
 export * from "./subscription.js";
 export * from "./task.js";

package/dist/types/proxy.d.ts

@@ -574,11 +574,26 @@ export type PreparedAnthropicAccountAttempt = {
     fetchStartMs?: number;
     upstreamSpan?: Span;
 };
+/** How to cool an account after a genuine (non-anti-abuse) 429, derived from
+ *  the response's quota headers + retry-after. */
+export type AccountCooldownPlan = {
+    reason: AccountCoolingReason;
+    /** Epoch-ms until which the account should not be used. */
+    coolingUntil: number;
+    /** When true (5h/7d window rejected), rotate immediately — retrying the same
+     *  account is futile until its window resets. When false (transient burst),
+     *  a small number of jittered same-account retries is allowed first. */
+    rotateImmediately: boolean;
+};
 export type AnthropicUpstreamFetchResult = {
     continueLoop: boolean;
     retrySameAccount?: boolean;
     /** When set, the caller should wait this many ms before retrying (from upstream retry-after). */
     retryAfterMs?: number;
+    /** Set on a genuine 429: how long / why to cool this account before rotating. */
+    cooldownPlan?: AccountCooldownPlan;
+    /** Quota snapshot parsed from the response headers (429 or success), if present. */
+    quota?: AccountQuota;
     response?: Response;
     lastError: unknown;
     sawRateLimit: boolean;
@@ -640,6 +655,12 @@ export type AccountQuota = {
     /** Epoch ms when we last captured this data */
     lastUpdated: number;
 };
+/** Why an account is currently cooling. Drives cooldown duration and logging.
+ *  - "weekly"    : 7d unified limit rejected — cool until the weekly reset.
+ *  - "session"   : 5h unified limit rejected — cool until the session reset.
+ *  - "transient" : short per-minute/burst 429 — cool for retry-after only.
+ *  - "auth"      : auth/refresh failures (reserved; currently rotate-only). */
+export type AccountCoolingReason = "weekly" | "session" | "transient" | "auth";
 /** Runtime state for a proxy account. */
 export type RuntimeAccountState = {
     consecutiveRefreshFailures: number;
@@ -647,9 +668,16 @@ export type RuntimeAccountState = {
     lastToken?: string;
     lastRefreshToken?: string;
     /** Epoch-ms timestamp until which the account should not be used for new
-     *  requests (set after 429 retries are exhausted). Other requests arriving
-     *  during this window will skip the account rather than hammering it again. */
+     *  requests. Set from the ACTUAL Anthropic reset window (5h/7d) on an
+     *  exhaustion 429, or from retry-after on a transient burst. Other requests
+     *  arriving during this window skip the account rather than hammering it. */
     coolingUntil?: number;
+    /** Why the account is cooling (set alongside coolingUntil). */
+    coolingReason?: AccountCoolingReason;
+    /** Latest quota snapshot parsed from Anthropic `anthropic-ratelimit-unified-*`
+     *  headers on ANY response (success or 429). Drives proactive, reset-aware
+     *  selection so we don't have to eat a 429 to discover an account is spent. */
+    quota?: AccountQuota;
 };
 /** A passthrough account used in the proxy route handler. */
 export type ProxyPassthroughAccount = {

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