@juspay/neurolink 9.85.1 → 9.86.0

package/dist/lib/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);
                     }

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

@@ -9,12 +9,41 @@
 import type { SkillDefinition, SkillIndexItem, SkillSearchQuery } from "../types/index.js";
 /** Strip instructions from a full definition to form an index entry. */
 export declare function toSkillIndexItem(skill: SkillDefinition): SkillIndexItem;
+/**
+ * Sort index entries by name (byte order, locale-independent) so every
+ * listing renders byte-identically across calls and store backends.
+ * Store enumeration order (Redis SCAN, fs.readdir, S3 listings) is not
+ * stable — an unsorted listing would shuffle between calls and invalidate
+ * provider prompt caches. Returns a new array.
+ */
+export declare function sortSkillIndex(items: SkillIndexItem[]): SkillIndexItem[];
 /** Filter index entries by query/tag/scope. Active skills only. */
 export declare function filterSkillIndex(items: SkillIndexItem[], query: SkillSearchQuery): SkillIndexItem[];
 /**
- * Render the compact skills index injected into the system prompt.
- * Names + descriptions only — instructions are never included; the model
- * loads them via search_skills. Returns null when nothing is visible so
- * callers can skip injection entirely.
+ * Reject resource paths that could escape a skill's namespace: absolute
+ * paths, traversal segments, and empty segments. The manager validates
+ * before reaching any store — this is defense in depth for stores whose
+ * keys are built by concatenation (S3, Redis) or path joining.
+ */
+export declare function isSafeSkillResourcePath(resourcePath: string): boolean;
+/** Whether a skill is visible from the calling scope. */
+export declare function isSkillVisibleInScope(skill: Pick<SkillDefinition, "scope" | "scopeIds">, scopeId?: string): boolean;
+/**
+ * Render the `<available_skills>` block embedded in the use_skill tool
+ * description ("tool" discovery mode). One line per skill — name,
+ * description, tags — instructions never appear here.
+ *
+ * Budget handling is uniform and stateless: over budget, every
+ * description drops to its first sentence, then to a hard 80-char cap.
+ * The render is a pure function of the (sorted) index, so the tool
+ * description stays byte-identical across calls — a prerequisite for
+ * provider prompt caching. Names are never dropped.
+ */
+export declare function renderSkillListing(items: SkillIndexItem[], budgetChars: number): string | null;
+/**
+ * Render the compact skills index appended to the system prompt
+ * ("system-prompt" discovery mode). Names + descriptions only —
+ * instructions are never included; the model loads them via use_skill.
+ * Returns null when nothing is visible so callers can skip injection.
  */
 export declare function formatSkillsPromptIndex(items: SkillIndexItem[], maxItems: number): string | null;

package/dist/lib/skills/skillMatcher.js

@@ -11,6 +11,16 @@ export function toSkillIndexItem(skill) {
     const { instructions: _instructions, ...indexItem } = skill;
     return indexItem;
 }
+/**
+ * Sort index entries by name (byte order, locale-independent) so every
+ * listing renders byte-identically across calls and store backends.
+ * Store enumeration order (Redis SCAN, fs.readdir, S3 listings) is not
+ * stable — an unsorted listing would shuffle between calls and invalidate
+ * provider prompt caches. Returns a new array.
+ */
+export function sortSkillIndex(items) {
+    return [...items].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+}
 /** Filter index entries by query/tag/scope. Active skills only. */
 export function filterSkillIndex(items, query) {
     const lowerQuery = query.query?.toLowerCase();
@@ -46,10 +56,75 @@ export function filterSkillIndex(items, query) {
     return query.limit !== undefined ? matched.slice(0, query.limit) : matched;
 }
 /**
- * Render the compact skills index injected into the system prompt.
- * Names + descriptions only — instructions are never included; the model
- * loads them via search_skills. Returns null when nothing is visible so
- * callers can skip injection entirely.
+ * Reject resource paths that could escape a skill's namespace: absolute
+ * paths, traversal segments, and empty segments. The manager validates
+ * before reaching any store — this is defense in depth for stores whose
+ * keys are built by concatenation (S3, Redis) or path joining.
+ */
+export function isSafeSkillResourcePath(resourcePath) {
+    const normalized = resourcePath.replace(/\\/g, "/");
+    return (normalized.length > 0 &&
+        !normalized.startsWith("/") &&
+        !normalized.split("/").some((segment) => segment === ".." || segment === ""));
+}
+/** Whether a skill is visible from the calling scope. */
+export function isSkillVisibleInScope(skill, scopeId) {
+    if (!scopeId || skill.scope !== "scoped") {
+        return true;
+    }
+    return (skill.scopeIds ?? []).includes(scopeId);
+}
+/** Trim a description to its first sentence (or the whole text when unsplittable). */
+function firstSentence(description) {
+    const match = description.match(/^[^.!?]*[.!?]/);
+    return match ? match[0].trim() : description;
+}
+/**
+ * Render the `<available_skills>` block embedded in the use_skill tool
+ * description ("tool" discovery mode). One line per skill — name,
+ * description, tags — instructions never appear here.
+ *
+ * Budget handling is uniform and stateless: over budget, every
+ * description drops to its first sentence, then to a hard 80-char cap.
+ * The render is a pure function of the (sorted) index, so the tool
+ * description stays byte-identical across calls — a prerequisite for
+ * provider prompt caching. Names are never dropped.
+ */
+export function renderSkillListing(items, budgetChars) {
+    if (items.length === 0) {
+        return null;
+    }
+    const render = (describe) => {
+        const lines = items.map((item) => {
+            const tags = item.tags && item.tags.length > 0
+                ? ` [tags: ${item.tags.join(", ")}]`
+                : "";
+            return `- ${item.name}: ${describe(item)}${tags}`;
+        });
+        return ["<available_skills>", ...lines, "</available_skills>"].join("\n");
+    };
+    const full = render((item) => item.description);
+    if (full.length <= budgetChars) {
+        return full;
+    }
+    const sentences = render((item) => firstSentence(item.description));
+    if (sentences.length <= budgetChars) {
+        return sentences;
+    }
+    const HARD_CAP = 80;
+    // Floor render — returned even if it still exceeds the budget.
+    return render((item) => {
+        const sentence = firstSentence(item.description);
+        return sentence.length > HARD_CAP
+            ? `${sentence.slice(0, HARD_CAP - 1)}…`
+            : sentence;
+    });
+}
+/**
+ * Render the compact skills index appended to the system prompt
+ * ("system-prompt" discovery mode). Names + descriptions only —
+ * instructions are never included; the model loads them via use_skill.
+ * Returns null when nothing is visible so callers can skip injection.
  */
 export function formatSkillsPromptIndex(items, maxItems) {
     if (items.length === 0) {
@@ -66,13 +141,13 @@ export function formatSkillsPromptIndex(items, maxItems) {
         return `- ${label}: ${item.description}${tags}`;
     });
     const truncationNote = items.length > visible.length
-        ? `\n(${items.length - visible.length} more skills exist — use search_skills or list_skills to discover them.)`
+        ? `\n(${items.length - visible.length} more skills exist — use list_skills to discover them.)`
         : "";
     return ([
         "## Available Skills",
         "The following team-defined skills (SOPs, playbooks, workflows) are available.",
         "Before answering from general knowledge, check whether one applies to the user's request.",
-        "To use a skill, call the search_skills tool to load its full instructions, then follow them exactly.",
+        "To use a skill, call the use_skill tool with its name to load the full instructions, then follow them exactly.",
         "",
         ...lines,
     ].join("\n") + truncationNote);

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

@@ -0,0 +1,52 @@
+/**
+ * Per-session skill activation state.
+ *
+ * A skill activated via use_skill is pinned to its session: the tracker
+ * holds the pinned instruction message until the turn is persisted
+ * (drainPending → StoreConversationTurnOptions.skillMessages) and answers
+ * "is this skill already loaded?" so re-invocations return a cheap
+ * already_loaded note instead of the full body.
+ *
+ * The stored session history is the source of truth — pinned messages
+ * carry `metadata.isSkill`. hydrate() rebuilds a session's active set from
+ * stored messages on every activation attempt (use_skill is rare, one
+ * history read per attempt), so dedup stays correct across process
+ * restarts, multiple instances sharing a Redis memory backend, and failed
+ * persistence: a pin that never reached storage simply re-activates on
+ * the next turn instead of being falsely reported as loaded.
+ */
+import type { ChatMessage, SkillActivationRecord, SkillDefinition } from "../types/index.js";
+/** Render the pinned history message for an activated skill. */
+export declare function buildSkillActivationMessage(skill: SkillDefinition): ChatMessage;
+export declare class SkillSessionTracker {
+    /** sessionId → skillId → activation record. */
+    private active;
+    /** sessionId → pinned messages awaiting persistence into the session turn. */
+    private pending;
+    /** Whether the skill is already active (loaded) in this session. */
+    isActive(sessionId: string, skillId: string, name: string): boolean;
+    /** Activation record for an active skill (by id, falling back to name). */
+    getActivation(sessionId: string, skillId: string, name?: string): SkillActivationRecord | undefined;
+    /**
+     * Record an activation: marks the skill active and queues its pinned
+     * message for persistence when the turn is stored.
+     */
+    recordActivation(sessionId: string, skill: SkillDefinition): ChatMessage;
+    /**
+     * Rebuild the active set from stored session history, then merge the
+     * in-process pending activations (this turn's pins, not yet stored).
+     * Called before every dedup check — the rebuild keeps state truthful
+     * when other instances pinned skills or when a past pin never reached
+     * storage.
+     */
+    hydrate(sessionId: string, storedMessages: ChatMessage[]): void;
+    /**
+     * Remove and return the pinned messages queued for this session. Called
+     * once per turn by the memory-store path; an empty result means nothing
+     * was activated this turn.
+     */
+    drainPending(sessionId: string): ChatMessage[];
+    /** Active skill records for a session (listing/debugging). */
+    listActive(sessionId: string): SkillActivationRecord[];
+    private recordsFor;
+}

package/dist/lib/skills/skillSessionTracker.js

@@ -0,0 +1,150 @@
+/**
+ * Per-session skill activation state.
+ *
+ * A skill activated via use_skill is pinned to its session: the tracker
+ * holds the pinned instruction message until the turn is persisted
+ * (drainPending → StoreConversationTurnOptions.skillMessages) and answers
+ * "is this skill already loaded?" so re-invocations return a cheap
+ * already_loaded note instead of the full body.
+ *
+ * The stored session history is the source of truth — pinned messages
+ * carry `metadata.isSkill`. hydrate() rebuilds a session's active set from
+ * stored messages on every activation attempt (use_skill is rare, one
+ * history read per attempt), so dedup stays correct across process
+ * restarts, multiple instances sharing a Redis memory backend, and failed
+ * persistence: a pin that never reached storage simply re-activates on
+ * the next turn instead of being falsely reported as loaded.
+ */
+import { randomUUID } from "node:crypto";
+/** Upper bound on tracked sessions; oldest are evicted first (insertion order). */
+const MAX_TRACKED_SESSIONS = 1000;
+/** Render the pinned history message for an activated skill. */
+export function buildSkillActivationMessage(skill) {
+    const version = skill.version ?? 1;
+    return {
+        id: `skill-${randomUUID()}`,
+        role: "user",
+        content: `[Skill loaded: ${skill.name} v${version}]\n\n${skill.instructions}`,
+        timestamp: new Date().toISOString(),
+        metadata: {
+            isSkill: true,
+            skillId: skill.id,
+            skillName: skill.name,
+            skillVersion: version,
+        },
+    };
+}
+/** Activation record derived from a pinned history message, when it is one. */
+function recordFromMessage(message) {
+    const meta = message.metadata;
+    if (!meta?.isSkill || !meta.skillId || !meta.skillName) {
+        return null;
+    }
+    return {
+        skillId: meta.skillId,
+        name: meta.skillName,
+        version: meta.skillVersion ?? 1,
+        activatedAt: message.timestamp ?? new Date(0).toISOString(),
+    };
+}
+export class SkillSessionTracker {
+    /** sessionId → skillId → activation record. */
+    active = new Map();
+    /** sessionId → pinned messages awaiting persistence into the session turn. */
+    pending = new Map();
+    /** Whether the skill is already active (loaded) in this session. */
+    isActive(sessionId, skillId, name) {
+        return Boolean(this.getActivation(sessionId, skillId, name));
+    }
+    /** Activation record for an active skill (by id, falling back to name). */
+    getActivation(sessionId, skillId, name) {
+        const records = this.active.get(sessionId);
+        if (!records) {
+            return undefined;
+        }
+        const byId = records.get(skillId);
+        if (byId || !name) {
+            return byId;
+        }
+        for (const record of records.values()) {
+            if (record.name === name) {
+                return record;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Record an activation: marks the skill active and queues its pinned
+     * message for persistence when the turn is stored.
+     */
+    recordActivation(sessionId, skill) {
+        const message = buildSkillActivationMessage(skill);
+        const record = recordFromMessage(message);
+        this.recordsFor(sessionId).set(skill.id, record);
+        const queue = this.pending.get(sessionId);
+        if (queue) {
+            queue.push(message);
+        }
+        else {
+            this.pending.set(sessionId, [message]);
+        }
+        return message;
+    }
+    /**
+     * Rebuild the active set from stored session history, then merge the
+     * in-process pending activations (this turn's pins, not yet stored).
+     * Called before every dedup check — the rebuild keeps state truthful
+     * when other instances pinned skills or when a past pin never reached
+     * storage.
+     */
+    hydrate(sessionId, storedMessages) {
+        const records = new Map();
+        for (const message of storedMessages) {
+            const record = recordFromMessage(message);
+            if (record && !records.has(record.skillId)) {
+                records.set(record.skillId, record);
+            }
+        }
+        for (const message of this.pending.get(sessionId) ?? []) {
+            const record = recordFromMessage(message);
+            if (record) {
+                records.set(record.skillId, record);
+            }
+        }
+        this.recordsFor(sessionId); // reserve the slot (applies the session cap)
+        this.active.set(sessionId, records);
+    }
+    /**
+     * Remove and return the pinned messages queued for this session. Called
+     * once per turn by the memory-store path; an empty result means nothing
+     * was activated this turn.
+     */
+    drainPending(sessionId) {
+        const queue = this.pending.get(sessionId);
+        if (!queue || queue.length === 0) {
+            return [];
+        }
+        this.pending.delete(sessionId);
+        return queue;
+    }
+    /** Active skill records for a session (listing/debugging). */
+    listActive(sessionId) {
+        return Array.from(this.active.get(sessionId)?.values() ?? []);
+    }
+    recordsFor(sessionId) {
+        let records = this.active.get(sessionId);
+        if (!records) {
+            if (this.active.size >= MAX_TRACKED_SESSIONS) {
+                const oldest = this.active.keys().next().value;
+                if (oldest !== undefined) {
+                    this.active.delete(oldest);
+                    this.pending.delete(oldest);
+                }
+            }
+            records = new Map();
+            this.active.set(sessionId, records);
+        }
+        return records;
+    }
+}
+//# sourceMappingURL=skillSessionTracker.js.map