@juspay/neurolink 9.85.1 → 9.86.0

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

@@ -6,15 +6,28 @@
  *
  * 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.
+ * auto-registers built-in tools (list_skills, plus gated mutation tools)
+ * and augments each generate()/stream() call with the discovery listing
+ * plus per-call use_skill / read_skill_resource tools.
  *
  * Naming: every exported type carries a `Skill` prefix to satisfy the
  * `unique-type-names` ESLint rule.
  */
+import type { ChatMessage } from "./conversation.js";
 /** Visibility of a skill: available everywhere, or only in specific scopes. */
 export type SkillScopeKind = "global" | "scoped";
+/**
+ * Reference to an auxiliary file bundled with a skill (progressive
+ * disclosure level 3). Resources are read into context on demand via the
+ * read_skill_resource tool — a skill's SKILL.md should stay lean and point
+ * to resources for rarely-needed detail.
+ */
+export type SkillResourceRef = {
+    /** Path relative to the skill's directory, e.g. "references/edge-cases.md". */
+    path: string;
+    /** Size in bytes when known (listing hint only). */
+    size?: number;
+};
 /** Lifecycle status. Deletes are soft — deprecated skills stay in storage. */
 export type SkillLifecycleStatus = "active" | "deprecated";
 /**
@@ -47,6 +60,12 @@ export type SkillDefinition = {
     createdAt?: string;
     /** ISO timestamp of last update. */
     updatedAt?: string;
+    /**
+     * Auxiliary files bundled with the skill, readable on demand through
+     * read_skill_resource. Populated by stores that support resources
+     * (directory-layout filesystem skills, S3, Redis).
+     */
+    resources?: SkillResourceRef[];
     /** Free-form host metadata (audit fields, approval references, …). */
     metadata?: Record<string, unknown>;
 };
@@ -69,12 +88,24 @@ export type SkillStore = {
     index(): Promise<SkillIndexItem[]>;
     /** Optional: drop any internal caches (called after mutations). */
     invalidate?(): void;
+    /**
+     * Optional: fetch an auxiliary resource file bundled with a skill.
+     * `resourcePath` is relative to the skill (e.g. "references/forms.md").
+     * Null when the skill or resource is absent. Stores without resource
+     * support simply omit this method.
+     */
+    getResource?(id: string, resourcePath: string): Promise<string | null>;
 };
 /** 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[];
+    /**
+     * Resource file contents keyed by skill id → relative path.
+     * E.g. `{ "my-skill": { "references/forms.md": "..." } }`.
+     */
+    resources?: Record<string, Record<string, string>>;
 };
 /**
  * Directory-backed store. Reads three layouts:
@@ -154,6 +185,15 @@ export type SkillS3IndexDocument = {
     lastUpdated: string;
     skills: SkillIndexItem[];
 };
+/** Result of a conditional (ETag) object read. */
+export type SkillS3ConditionalGetResult = {
+    /** Object body; null when the key is absent. */
+    body: string | null;
+    /** ETag of the returned body, for the next conditional read. */
+    etag?: string;
+    /** True when the object is unchanged since the supplied ETag (no body). */
+    notModified?: boolean;
+};
 /**
  * Minimal object-storage operations the S3 skill store runs on. The
  * default implementation is created lazily from @aws-sdk/client-s3;
@@ -166,9 +206,15 @@ export type SkillS3ObjectOps = {
     deleteObject(key: string): Promise<void>;
     /** List all object keys under a prefix (paginated internally). */
     listKeys(prefix: string): Promise<string[]>;
+    /**
+     * Optional: ETag-conditional read (If-None-Match). Used for index.json
+     * refreshes so an unchanged index costs a 304 instead of a full download.
+     * Ops without it fall back to plain getObject.
+     */
+    getObjectConditional?(key: string, etag?: string): Promise<SkillS3ConditionalGetResult>;
 };
 export type SkillsStorageConfig = SkillMemoryStorageConfig | SkillFilesystemStorageConfig | SkillS3StorageConfig | SkillRedisStorageConfig | SkillCustomStorageConfig;
-/** Query accepted by SkillsManager.search() and the search_skills tool. */
+/** Query accepted by SkillsManager.search() (programmatic + CLI search). */
 export type SkillSearchQuery = {
     /** Keyword matched (case-insensitive substring) against name, displayName, and description. */
     query?: string;
@@ -239,14 +285,38 @@ export type SkillsConfig = {
     /** 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.
+     * Where the skills listing (names + descriptions, never instructions)
+     * surfaces for model-driven discovery:
+     *  - "tool" (default): an `<available_skills>` block embedded in the
+     *    use_skill tool description — the Claude Code pattern. Keeps the
+     *    host's system prompt untouched and the listing cache-stable.
+     *  - "system-prompt": a "## Available Skills" index appended to the
+     *    system prompt instead.
+     *  - "none": no listing anywhere; discovery only via list_skills.
+     */
+    discovery?: SkillDiscoveryMode;
+    /**
+     * Character budget for the "tool" discovery listing. When the full
+     * listing exceeds it, every description is shortened uniformly (first
+     * sentence, then a hard cap) so the render stays a pure function of the
+     * index — byte-stable across calls; names are never dropped.
+     * Default: 15000.
      */
-    promptIndex?: boolean;
+    listingBudgetChars?: number;
+    /**
+     * Pin activated skill instructions into session history so later turns
+     * replay them verbatim (byte-stable, provider-cacheable) instead of
+     * re-fetching the skill. Requires conversation memory + a sessionId on
+     * the call. Default: true.
+     */
+    sessionPersistence?: boolean;
     /** Maximum skills hydrated (with instructions) per search. Default: 5. */
     maxMatches?: number;
-    /** Maximum entries rendered in the prompt index before truncation. Default: 50. */
+    /**
+     * Maximum entries rendered by the "system-prompt" discovery mode before
+     * truncation. Default: 50. The "tool" mode is bounded by
+     * listingBudgetChars instead and never drops entries.
+     */
     promptIndexMaxItems?: number;
     /** Index cache TTL in milliseconds. Default: 30000. 0 disables caching. */
     indexCacheTtlMs?: number;
@@ -265,6 +335,30 @@ export type SkillsConfig = {
      */
     onMutationRequest?: (action: SkillMutationAction) => Promise<SkillMutationDecision>;
 };
+/** Where the skills discovery listing surfaces. See SkillsConfig.discovery. */
+export type SkillDiscoveryMode = "tool" | "system-prompt" | "none";
+/**
+ * One activated skill in a session: which skill, at which version, when.
+ * Sessions pin the version active at activation time — a mid-session skill
+ * update never mutates instructions the model has already loaded.
+ */
+export type SkillActivationRecord = {
+    skillId: string;
+    name: string;
+    version: number;
+    /** ISO timestamp of activation. */
+    activatedAt: string;
+};
+/**
+ * Structural view of the per-session activation tracker consumed by the
+ * skill tools factory.
+ */
+export type SkillSessionStateLike = {
+    isActive: (sessionId: string, skillId: string, name: string) => boolean;
+    getActivation: (sessionId: string, skillId: string, name?: string) => SkillActivationRecord | undefined;
+    recordActivation: (sessionId: string, skill: SkillDefinition) => ChatMessage;
+    hydrate: (sessionId: string, storedMessages: ChatMessage[]) => void;
+};
 /**
  * Structural view of SkillsManager consumed by the skill tools factory —
  * keeps skillTools.ts decoupled from the concrete manager class.
@@ -272,8 +366,38 @@ export type SkillsConfig = {
 export type SkillsManagerLike = {
     search: (query: SkillSearchQuery) => Promise<SkillDefinition[]>;
     list: (scopeId?: string) => Promise<SkillIndexItem[]>;
+    get: (idOrName: string) => Promise<SkillDefinition | null>;
+    getResource: (idOrName: string, resourcePath: string) => Promise<string | null>;
+    sessions: SkillSessionStateLike;
     requestMutation: (action: SkillMutationAction) => Promise<SkillMutationResult>;
 };
+/**
+ * Per-call context bound into the use_skill / read_skill_resource tools at
+ * injection time (prepareGenerate/prepareStream). The sessionId is captured
+ * by closure so activation state is tracked without relying on runtime tool
+ * context plumbing.
+ */
+export type SkillCallToolsContext = {
+    /** Session the call belongs to; absent → activation state is per-turn only. */
+    sessionId?: string;
+    /** Scope filter applied when resolving skills for this call. */
+    scopeId?: string;
+    /**
+     * Pin activated instructions into session history after the turn.
+     * Mirrors SkillsConfig.sessionPersistence resolved for this call.
+     */
+    sessionPersistence: boolean;
+    /** Discovery mode resolved for this call — shapes the use_skill description. */
+    discovery: SkillDiscoveryMode;
+    /** Rendered `<available_skills>` block for "tool" discovery; null when empty. */
+    listing?: string | null;
+    /**
+     * Stored session history loader used to hydrate activation state before
+     * every dedup check (restart/multi-instance/failed-persistence safety).
+     * Invoked once per use_skill / read_skill_resource attempt.
+     */
+    getStoredMessages?: (sessionId: string) => Promise<ChatMessage[]>;
+};
 /** Options for the createSkillTools factory. */
 export type SkillToolsOptions = {
     /** Include skill_create / skill_update / skill_delete. Default: false. */
@@ -285,12 +409,19 @@ export type SkillToolsOptions = {
  * config (same precedence convention as per-call credentials).
  */
 export type SkillsCallOptions = {
-    /** Master toggle for this call (prompt index only — tools stay registered). Default: true. */
+    /** Master toggle for this call (listing + per-call tools). Default: true. */
     enabled?: boolean;
-    /** Per-call override of SkillsConfig.promptIndex. */
-    promptIndex?: boolean;
-    /** Scope filter for the prompt index on this call. Overrides defaultScopeId. */
+    /** Per-call override of SkillsConfig.discovery. */
+    discovery?: SkillDiscoveryMode;
+    /** Scope filter for the listing and skill resolution on this call. Overrides defaultScopeId. */
     scopeId?: string;
-    /** Restrict the prompt index to skills carrying at least one of these tags. */
+    /** Restrict the listing to skills carrying at least one of these tags. */
     tags?: string[];
+    /**
+     * Skill names to activate at the start of this call: their full
+     * instructions are injected up front (and pinned to the session when
+     * sessionPersistence is on), without waiting for the model to invoke
+     * use_skill. Already-active skills are skipped.
+     */
+    preload?: string[];
 };

package/dist/lib/types/skills.js

@@ -6,9 +6,9 @@
  *
  * 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.
+ * auto-registers built-in tools (list_skills, plus gated mutation tools)
+ * and augments each generate()/stream() call with the discovery listing
+ * plus per-call use_skill / read_skill_resource tools.
  *
  * Naming: every exported type carries a `Skill` prefix to satisfy the
  * `unique-type-names` ESLint rule.

package/dist/lib/utils/conversationMemory.d.ts

@@ -28,7 +28,7 @@ export declare function getConversationMessages(conversationMemory: Conversation
  * Store conversation turn for future context
  * Saves user messages and AI responses for conversation memory
  */
-export declare function storeConversationTurn(conversationMemory: ConversationMemoryManager | RedisConversationMemoryManager | null | undefined, originalOptions: TextGenerationOptions, result: TextGenerationResult, startTimeStamp?: Date | undefined, requestId?: string): Promise<void>;
+export declare function storeConversationTurn(conversationMemory: ConversationMemoryManager | RedisConversationMemoryManager | null | undefined, originalOptions: TextGenerationOptions, result: TextGenerationResult, startTimeStamp?: Date | undefined, requestId?: string, skillMessages?: ChatMessage[]): Promise<void>;
 /**
  * Build context messages from pointer onwards (token-based memory)
  * Returns summary message (if exists) + all messages after the summarized pointer

package/dist/lib/utils/conversationMemory.js

@@ -227,7 +227,7 @@ export async function getConversationMessages(conversationMemory, options) {
  * Store conversation turn for future context
  * Saves user messages and AI responses for conversation memory
  */
-export async function storeConversationTurn(conversationMemory, originalOptions, result, startTimeStamp, requestId) {
+export async function storeConversationTurn(conversationMemory, originalOptions, result, startTimeStamp, requestId, skillMessages) {
     logger.debug("[conversationMemoryUtils] storeConversationTurn called", {
         requestId,
         hasMemory: !!conversationMemory,
@@ -369,6 +369,9 @@ export async function storeConversationTurn(conversationMemory, originalOptions,
                 enableSummarization: originalOptions.enableSummarization,
                 requestId,
                 events: toolActivityEvents,
+                ...(skillMessages && skillMessages.length > 0
+                    ? { skillMessages }
+                    : {}),
                 tokenUsage: result.usage
                     ? {
                         inputTokens: result.usage.input,
@@ -450,6 +453,12 @@ export function buildContextFromPointer(session, requestId) {
         return session.messages;
     }
     const messagesAfterPointer = session.messages.slice(pointerIndex + 1);
+    // Pinned skill instructions must survive summarization: any skill message
+    // that fell behind the pointer is re-included verbatim after the summary,
+    // so an activated skill keeps its full instructions for the whole session.
+    const pinnedSkillMessages = session.messages
+        .slice(0, pointerIndex + 1)
+        .filter((msg) => msg.metadata?.isSkill);
     // Construct context: summary message + recent messages
     const summaryMessage = {
         id: `summary-${session.summarizedUpToMessageId}`,
@@ -468,7 +477,11 @@ export function buildContextFromPointer(session, requestId) {
         totalMessages: session.messages.length,
         summaryLength: session.summarizedMessage.length,
     });
-    const contextMessages = [summaryMessage, ...messagesAfterPointer];
+    const contextMessages = [
+        summaryMessage,
+        ...pinnedSkillMessages,
+        ...messagesAfterPointer,
+    ];
     // Log context built for LLM with structural metadata
     const totalChars = contextMessages.reduce((sum, msg) => sum + msg.content.length, 0);
     logger.info("[ConversationMemory] Context built for LLM", {

package/dist/neurolink.d.ts

@@ -274,7 +274,7 @@ export declare class NeuroLink {
      */
     private ensureSkillsReady;
     /**
-     * Register the built-in skill tools (search_skills / list_skills, plus
+     * Register the built-in skill tools (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
@@ -282,11 +282,36 @@ export declare class NeuroLink {
      */
     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;
+     * Skills augmentation for one generate()/stream() call:
+     *  1. Discovery — surface the skills listing per the resolved mode:
+     *     embedded in the use_skill tool description ("tool", default) or
+     *     appended to the system prompt ("system-prompt").
+     *  2. Per-call tools — inject use_skill + read_skill_resource into
+     *     options.tools (the RAG-tool pattern; same-name entries shadow
+     *     registered tools) with the sessionId closure-bound so activations
+     *     pin to the session.
+     *  3. Preload — activate host-requested skills up front, injecting their
+     *     instructions into this call's system prompt and pinning them.
+     * Fails open: any error leaves the call untouched.
+     */
+    private applySkillsAugmentation;
+    /** Session id for skill activation tracking, from the call context. */
+    private resolveSkillSessionId;
+    /** User id for skill-session hydration (Redis keys sessions by userId). */
+    private resolveSkillUserId;
+    /**
+     * Activate host-requested skills before the model runs: instructions go
+     * into this call's system prompt; when persisting, the activation is
+     * pinned so later turns replay it from history instead. Unknown or
+     * already-active names are skipped with a warn/debug log (fail-open).
+     */
+    private preloadSkills;
+    /**
+     * Pinned skill messages recorded during this turn, ready for
+     * StoreConversationTurnOptions.skillMessages. Empty when skills are off
+     * or nothing was activated.
+     */
+    private drainPendingSkillMessages;
     /**
      * Programmatic access to the skills subsystem (search/list/get/mutations).
      * Returns null when skills are not configured or failed to initialize.

package/dist/neurolink.js

@@ -54,8 +54,10 @@ 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 { isSkillVisibleInScope } from "./skills/skillMatcher.js";
+import { buildSkillActivationMessage } from "./skills/skillSessionTracker.js";
 import { SkillsManager } from "./skills/skillsManager.js";
-import { createSkillTools } from "./skills/skillTools.js";
+import { createSkillCallTools, 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";
@@ -1276,7 +1278,7 @@ export class NeuroLink {
         return this.skillsManagerInstance;
     }
     /**
-     * Register the built-in skill tools (search_skills / list_skills, plus
+     * Register the built-in skill tools (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
@@ -1300,19 +1302,22 @@ export class NeuroLink {
         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.
+     * Skills augmentation for one generate()/stream() call:
+     *  1. Discovery — surface the skills listing per the resolved mode:
+     *     embedded in the use_skill tool description ("tool", default) or
+     *     appended to the system prompt ("system-prompt").
+     *  2. Per-call tools — inject use_skill + read_skill_resource into
+     *     options.tools (the RAG-tool pattern; same-name entries shadow
+     *     registered tools) with the sessionId closure-bound so activations
+     *     pin to the session.
+     *  3. Preload — activate host-requested skills up front, injecting their
+     *     instructions into this call's system prompt and pinning them.
+     * Fails open: any error leaves the call untouched.
      */
-    async applySkillsPromptIndex(options) {
+    async applySkillsAugmentation(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" ||
@@ -1326,26 +1331,142 @@ export class NeuroLink {
             if (!manager) {
                 return;
             }
-            const block = await manager.buildPromptIndex({
-                ...(options.skills?.scopeId !== undefined
-                    ? { scopeId: options.skills.scopeId }
-                    : {}),
-                ...(options.skills?.tags !== undefined
-                    ? { tags: options.skills.tags }
-                    : {}),
+            const discovery = options.skills?.discovery ?? this.skillsConfig.discovery ?? "tool";
+            const scopeId = options.skills?.scopeId ?? this.skillsConfig.defaultScopeId;
+            const tags = options.skills?.tags;
+            const sessionId = this.resolveSkillSessionId(options.context) ??
+                this.resolveSkillSessionId(options);
+            const userId = this.resolveSkillUserId(options.context) ??
+                this.resolveSkillUserId(options);
+            // Pinning requires somewhere to pin: without conversation memory the
+            // drained messages would be silently discarded while dedup reports
+            // already_loaded — so persistence is only on when memory is
+            // configured (or already initialized).
+            const memoryAvailable = Boolean(this.conversationMemory) ||
+                Boolean(this.conversationMemoryConfig?.conversationMemory?.enabled);
+            const sessionPersistence = (this.skillsConfig.sessionPersistence ?? true) &&
+                Boolean(sessionId) &&
+                memoryAvailable;
+            const visibility = {
+                ...(scopeId !== undefined ? { scopeId } : {}),
+                ...(tags !== undefined ? { tags } : {}),
+            };
+            if (discovery === "system-prompt") {
+                const block = await manager.buildPromptIndex(visibility);
+                if (block) {
+                    options.systemPrompt = options.systemPrompt
+                        ? `${options.systemPrompt}\n\n${block}`
+                        : block;
+                }
+            }
+            const listing = discovery === "tool"
+                ? await manager.buildToolListing(visibility)
+                : null;
+            const callTools = createSkillCallTools(() => this.ensureSkillsReady(), {
+                ...(sessionId ? { sessionId } : {}),
+                ...(scopeId !== undefined ? { scopeId } : {}),
+                sessionPersistence,
+                discovery,
+                listing,
+                // userId rides by closure: Redis memory keys sessions by
+                // userId:sessionId, so hydration must read the same key the
+                // store-turn path writes.
+                getStoredMessages: async (sid) => this.conversationMemory
+                    ? await this.conversationMemory.getSessionMessages(sid, userId)
+                    : [],
             });
-            if (block) {
-                options.systemPrompt = options.systemPrompt
-                    ? `${options.systemPrompt}\n\n${block}`
-                    : block;
-                logger.debug("[NeuroLink] Skills prompt index injected", {
-                    blockLength: block.length,
+            // Caller-supplied per-call tools win over the injected ones (a host
+            // may bring its own use_skill); the injected tools still shadow any
+            // registered base tool of the same name via the provider merge.
+            options.tools = {
+                ...callTools,
+                ...(options.tools ?? {}),
+            };
+            if (options.skills?.preload?.length) {
+                await this.preloadSkills(manager, options, options.skills.preload, {
+                    ...(sessionId ? { sessionId } : {}),
+                    ...(userId ? { userId } : {}),
+                    sessionPersistence,
+                    ...(scopeId !== undefined ? { scopeId } : {}),
                 });
             }
+            logger.debug("[NeuroLink] Skills augmentation applied", {
+                discovery,
+                listingLength: listing?.length ?? 0,
+                sessionPersistence,
+                preloadCount: options.skills?.preload?.length ?? 0,
+            });
         }
         catch (error) {
-            logger.warn("[NeuroLink] Skills prompt index injection failed — continuing without it", { error: error instanceof Error ? error.message : String(error) });
+            logger.warn("[NeuroLink] Skills augmentation failed — continuing without skills", { error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    /** Session id for skill activation tracking, from the call context. */
+    resolveSkillSessionId(context) {
+        const fromContext = context
+            ?.sessionId;
+        return typeof fromContext === "string" && fromContext
+            ? fromContext
+            : undefined;
+    }
+    /** User id for skill-session hydration (Redis keys sessions by userId). */
+    resolveSkillUserId(context) {
+        const fromContext = context?.userId;
+        return typeof fromContext === "string" && fromContext
+            ? fromContext
+            : undefined;
+    }
+    /**
+     * Activate host-requested skills before the model runs: instructions go
+     * into this call's system prompt; when persisting, the activation is
+     * pinned so later turns replay it from history instead. Unknown or
+     * already-active names are skipped with a warn/debug log (fail-open).
+     */
+    async preloadSkills(manager, options, names, call) {
+        const { sessionId, userId, sessionPersistence, scopeId } = call;
+        for (const name of names) {
+            const skill = await manager.get(name);
+            if (!skill || !isSkillVisibleInScope(skill, scopeId)) {
+                logger.warn("[NeuroLink] Preload skill not found — skipping", {
+                    skill: name,
+                });
+                continue;
+            }
+            let block;
+            if (sessionId && sessionPersistence) {
+                // Always hydrate (empty history when memory isn't initialized yet):
+                // the tracker derives truth from stored pins + this turn's pending,
+                // never from stale in-process records.
+                manager.sessions.hydrate(sessionId, this.conversationMemory
+                    ? await this.conversationMemory.getSessionMessages(sessionId, userId)
+                    : []);
+                if (manager.sessions.isActive(sessionId, skill.id, skill.name)) {
+                    continue;
+                }
+                block = manager.sessions.recordActivation(sessionId, skill).content;
+            }
+            else {
+                block = buildSkillActivationMessage(skill).content;
+            }
+            options.systemPrompt = options.systemPrompt
+                ? `${options.systemPrompt}\n\n${block}`
+                : block;
+        }
+    }
+    /**
+     * Pinned skill messages recorded during this turn, ready for
+     * StoreConversationTurnOptions.skillMessages. Empty when skills are off
+     * or nothing was activated.
+     */
+    drainPendingSkillMessages(sessionId) {
+        if (typeof sessionId !== "string" || !sessionId) {
+            return [];
+        }
+        const manager = this.skillsManagerInstance;
+        if (!manager) {
+            return [];
         }
+        return manager.sessions.drainPending(sessionId);
     }
     /**
      * Programmatic access to the skills subsystem (search/list/get/mutations).
@@ -3610,9 +3731,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);
+        // Skills: surface the discovery listing and inject the per-call
+        // use_skill / read_skill_resource tools (bodies load on activation).
+        await this.applySkillsAugmentation(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.
@@ -4431,7 +4552,7 @@ Current user's request: ${currentInput}`;
         });
         const memStoreStart = Date.now();
         try {
-            await storeConversationTurn(this.conversationMemory, options, result, new Date(startTime), requestId);
+            await storeConversationTurn(this.conversationMemory, options, result, new Date(startTime), requestId, this.drainPendingSkillMessages(options.context?.sessionId));
             this.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": path }, Date.now() - memStoreStart, SpanStatus.OK);
         }
         catch (memoryError) {
@@ -7151,9 +7272,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);
+        // Skills: surface the discovery listing and inject the per-call
+        // use_skill / read_skill_resource tools (bodies load on activation).
+        await this.applySkillsAugmentation(options);
         // Apply orchestration if enabled and no specific provider/model requested
         if (this.enableOrchestration && !options.provider && !options.model) {
             try {
@@ -7526,6 +7647,7 @@ Current user's request: ${currentInput}`;
             }
             const memStoreStart = Date.now();
             try {
+                const pendingSkillMessages = this.drainPendingSkillMessages(sessionId);
                 await this.conversationMemory.storeConversationTurn({
                     sessionId,
                     userId,
@@ -7537,6 +7659,9 @@ Current user's request: ${currentInput}`;
                     events: eventSequence.length > 0 ? eventSequence : undefined,
                     requestId: enhancedOptions.context
                         ?.requestId,
+                    ...(pendingSkillMessages.length > 0
+                        ? { skillMessages: pendingSkillMessages }
+                        : {}),
                 });
                 this.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": "stream" }, Date.now() - memStoreStart, SpanStatus.OK);
                 logger.debug("[NeuroLink.stream] Stored conversation turn with events", {
@@ -8075,8 +8200,10 @@ Current user's request: ${currentInput}`;
                     }
                     const memStoreStart = Date.now();
                     try {
+                        const fallbackSessionId = sessionId || options.context?.sessionId;
+                        const pendingSkillMessages = self.drainPendingSkillMessages(fallbackSessionId);
                         await self.conversationMemory.storeConversationTurn({
-                            sessionId: sessionId || options.context?.sessionId,
+                            sessionId: fallbackSessionId,
                             userId: userId || options.context?.userId,
                             userMessage: originalPrompt ?? "",
                             aiResponse: fallbackAccumulatedContent,
@@ -8086,6 +8213,9 @@ Current user's request: ${currentInput}`;
                             requestId: enhancedOptions?.context?.requestId ||
                                 options.context
                                     ?.requestId,
+                            ...(pendingSkillMessages.length > 0
+                                ? { skillMessages: pendingSkillMessages }
+                                : {}),
                         });
                         self.recordMemorySpan("memory.store", { "memory.operation": "store", "memory.path": "fallback-stream" }, Date.now() - memStoreStart, SpanStatus.OK);
                     }