@juspay/neurolink 9.85.1 → 9.86.1

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/proxy/accountQuota.d.ts

@@ -35,5 +35,10 @@ export declare function loadAccountQuota(accountKey: string): Promise<AccountQuo
  * Update quota for a single account.
  * Updates in-memory cache immediately (non-blocking),
  * then debounces the disk write to every 5 seconds.
+ *
+ * Loads the persisted file into the cache before the first write so a save
+ * after a process restart merges with existing entries instead of rewriting
+ * the file with only the accounts used since boot (which silently erased
+ * other accounts' snapshots and blinded quota-aware routing to them).
  */
 export declare function saveAccountQuota(accountKey: string, quota: AccountQuota): Promise<void>;

package/dist/lib/proxy/accountQuota.js

@@ -174,10 +174,17 @@ export async function loadAccountQuota(accountKey) {
  * Update quota for a single account.
  * Updates in-memory cache immediately (non-blocking),
  * then debounces the disk write to every 5 seconds.
+ *
+ * Loads the persisted file into the cache before the first write so a save
+ * after a process restart merges with existing entries instead of rewriting
+ * the file with only the accounts used since boot (which silently erased
+ * other accounts' snapshots and blinded quota-aware routing to them).
  */
 export async function saveAccountQuota(accountKey, quota) {
+    if (!cacheLoaded) {
+        await loadAccountQuotas();
+    }
     memoryCache[accountKey] = quota;
-    cacheLoaded = true;
     dirty = true;
     scheduleFlush();
 }

package/dist/lib/server/routes/claudeProxyRoutes.d.ts

@@ -44,18 +44,32 @@ declare function resetEpochToMs(resetEpoch: number | undefined, now: number): nu
  * allow a couple of jittered same-account retries, then a short cooldown.
  */
 declare function planCooldownFor429(quota: AccountQuota | null, retryAfterMs: number, now: number): AccountCooldownPlan;
+/**
+ * Seed each account's runtime quota from the persisted snapshots in
+ * ~/.neurolink/account-quotas.json (keyed by label). Runtime state is
+ * in-memory only, so without this the quota-aware ordering is blind after a
+ * proxy restart: all accounts tie, selection falls back to token-store
+ * enumeration order, and the first account served becomes self-reinforcing
+ * (it alone has data) — starving the others regardless of their resets.
+ * Never overwrites fresher in-memory quota; stale disk snapshots degrade
+ * gracefully because past reset timestamps are ignored by resetEpochToMs.
+ */
+declare function seedRuntimeQuotasFromDisk(accounts: ProxyPassthroughAccount[]): Promise<void>;
 /**
  * Order accounts to MAXIMIZE quota utilization (fill-first, smart order):
  * spend the account whose window refreshes SOONEST first, so its about-to-reset
  * allowance isn't wasted, then move to accounts with longer-dated resets.
  *
  * Priority among usable accounts:
- *   1. soonest WEEKLY (7d) reset  — the scarce, use-it-or-lose-it ceiling
- *   2. soonest SESSION (5h) reset
- *   3. highest weekly utilization — finish off the one closest to done
- * Accounts with no quota data yet keep insertion order (stable sort) and sit
- * after those with a known soonest reset. Cooling/rejected accounts sort last,
- * soonest-back-to-service first, as last resort.
+ *   1. no quota data yet — probe first: one request reveals its windows and
+ *      self-corrects the ordering. (Ranking unknowns last would starve them
+ *      forever: never picked → never observed → never comparable.)
+ *   2. soonest WEEKLY (7d) reset  — the scarce, use-it-or-lose-it ceiling
+ *   3. soonest SESSION (5h) reset
+ *   4. highest weekly utilization — finish off the one closest to done
+ *   5. configured primary account, then insertion order
+ * Cooling/rejected accounts sort last, soonest-back-to-service first, as
+ * last resort.
  */
 declare function orderAccountsByQuota(accounts: ProxyPassthroughAccount[], now: number): ProxyPassthroughAccount[];
 /**
@@ -95,6 +109,8 @@ export declare const __testHooks: {
     planCooldownFor429: typeof planCooldownFor429;
     orderAccountsByQuota: typeof orderAccountsByQuota;
     resetEpochToMs: typeof resetEpochToMs;
+    seedRuntimeQuotasFromDisk: typeof seedRuntimeQuotasFromDisk;
+    getAccountRuntimeState: (key: string) => RuntimeAccountState | undefined;
     setConfiguredPrimaryAccountKey: (key: string | undefined) => void;
     getConfiguredPrimaryAccountKey: () => string | undefined;
     setPrimaryAccountIndex: (index: number) => void;

package/dist/lib/server/routes/claudeProxyRoutes.js

@@ -13,7 +13,7 @@ import { access, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { buildStableClaudeCodeBillingHeader, CLAUDE_CLI_USER_AGENT, CLAUDE_CODE_OAUTH_BETAS, getOrCreateClaudeCodeIdentity, parseClaudeCodeUserId, } from "../../auth/anthropicOAuth.js";
-import { parseQuotaHeaders, saveAccountQuota, } from "../../proxy/accountQuota.js";
+import { loadAccountQuotas, parseQuotaHeaders, saveAccountQuota, } from "../../proxy/accountQuota.js";
 import { buildClaudeError, ClaudeStreamSerializer, generateToolUseId, parseClaudeRequest, serializeClaudeResponse, } from "../../proxy/claudeFormat.js";
 import { buildAnthropicModelsListResponse, buildTranslationOptions, extractText, extractToolArgs, extractUsageFromStreamResult, handleTranslatedJsonRequest, handleTranslatedStreamRequest, hasTranslatedOutput, } from "../../proxy/proxyTranslationEngine.js";
 import { tracers } from "../../telemetry/tracers.js";
@@ -242,6 +242,30 @@ function maybeCoolFromQuota(state, quota, now) {
         logger.always(`[proxy] proactively cooling account (${reason}) ~${minutesUntil(clamped, now)}m from success-response quota (status rejected)`);
     }
 }
+/**
+ * Seed each account's runtime quota from the persisted snapshots in
+ * ~/.neurolink/account-quotas.json (keyed by label). Runtime state is
+ * in-memory only, so without this the quota-aware ordering is blind after a
+ * proxy restart: all accounts tie, selection falls back to token-store
+ * enumeration order, and the first account served becomes self-reinforcing
+ * (it alone has data) — starving the others regardless of their resets.
+ * Never overwrites fresher in-memory quota; stale disk snapshots degrade
+ * gracefully because past reset timestamps are ignored by resetEpochToMs.
+ */
+async function seedRuntimeQuotasFromDisk(accounts) {
+    try {
+        const persisted = await loadAccountQuotas();
+        for (const account of accounts) {
+            const state = getOrCreateRuntimeState(account.key);
+            if (!state.quota && persisted[account.label]) {
+                state.quota = persisted[account.label];
+            }
+        }
+    }
+    catch {
+        // Non-fatal: seeding is best-effort; ordering falls back to probe-first.
+    }
+}
 /** Quota-aware selection is on by default; disable with
  *  NEUROLINK_PROXY_QUOTA_ROUTING=off|false|0. Only affects the fill-first
  *  strategy (round-robin keeps strict rotation). */
@@ -260,6 +284,7 @@ function accountSortMetrics(accountKey, now) {
     const sessionRejected = q?.sessionStatus === "rejected" && sessionReset !== undefined;
     return {
         usable: !coolingActive && !weeklyRejected && !sessionRejected,
+        hasQuota: !!q,
         coolingUntil: st?.coolingUntil ?? 0,
         weeklyReset: weeklyReset ?? Number.POSITIVE_INFINITY,
         sessionReset: sessionReset ?? Number.POSITIVE_INFINITY,
@@ -272,14 +297,18 @@ function accountSortMetrics(accountKey, now) {
  * allowance isn't wasted, then move to accounts with longer-dated resets.
  *
  * Priority among usable accounts:
- *   1. soonest WEEKLY (7d) reset  — the scarce, use-it-or-lose-it ceiling
- *   2. soonest SESSION (5h) reset
- *   3. highest weekly utilization — finish off the one closest to done
- * Accounts with no quota data yet keep insertion order (stable sort) and sit
- * after those with a known soonest reset. Cooling/rejected accounts sort last,
- * soonest-back-to-service first, as last resort.
+ *   1. no quota data yet — probe first: one request reveals its windows and
+ *      self-corrects the ordering. (Ranking unknowns last would starve them
+ *      forever: never picked → never observed → never comparable.)
+ *   2. soonest WEEKLY (7d) reset  — the scarce, use-it-or-lose-it ceiling
+ *   3. soonest SESSION (5h) reset
+ *   4. highest weekly utilization — finish off the one closest to done
+ *   5. configured primary account, then insertion order
+ * Cooling/rejected accounts sort last, soonest-back-to-service first, as
+ * last resort.
  */
 function orderAccountsByQuota(accounts, now) {
+    const primaryKey = configuredPrimaryAccountKey;
     return [...accounts].sort((a, b) => {
         const ma = accountSortMetrics(a.key, now);
         const mb = accountSortMetrics(b.key, now);
@@ -291,13 +320,22 @@ function orderAccountsByQuota(accounts, now) {
             const bu = mb.coolingUntil || Number.POSITIVE_INFINITY;
             return au - bu;
         }
+        if (ma.hasQuota !== mb.hasQuota) {
+            return ma.hasQuota ? 1 : -1;
+        }
         if (ma.weeklyReset !== mb.weeklyReset) {
             return ma.weeklyReset - mb.weeklyReset;
         }
         if (ma.sessionReset !== mb.sessionReset) {
             return ma.sessionReset - mb.sessionReset;
         }
-        return mb.weeklyUsed - ma.weeklyUsed;
+        if (ma.weeklyUsed !== mb.weeklyUsed) {
+            return mb.weeklyUsed - ma.weeklyUsed;
+        }
+        if (primaryKey && (a.key === primaryKey) !== (b.key === primaryKey)) {
+            return a.key === primaryKey ? -1 : 1;
+        }
+        return 0;
     });
 }
 // ---------------------------------------------------------------------------
@@ -1280,6 +1318,7 @@ async function loadClaudeProxyAccounts(args) {
         state.lastToken = account.token;
         state.lastRefreshToken = account.refreshToken;
     }
+    await seedRuntimeQuotasFromDisk(accounts);
     const enabledAccounts = accounts.filter((account) => {
         return !getOrCreateRuntimeState(account.key).permanentlyDisabled;
     });
@@ -3777,6 +3816,11 @@ export const __testHooks = {
     planCooldownFor429,
     orderAccountsByQuota,
     resetEpochToMs,
+    seedRuntimeQuotasFromDisk,
+    getAccountRuntimeState: (key) => {
+        const state = accountRuntimeState.get(key);
+        return state ? { ...state } : undefined;
+    },
     setConfiguredPrimaryAccountKey: (key) => {
         configuredPrimaryAccountKey = key;
     },

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);