@juspay/neurolink 9.85.1 → 9.86.1

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

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

package/dist/skills/skillStoreRedis.d.ts

@@ -9,11 +9,19 @@
 import type { SkillDefinition, SkillIndexItem, SkillRedisStorageConfig, SkillStore } from "../types/index.js";
 export declare class RedisSkillStore implements SkillStore {
     private readonly keyPrefix;
+    /**
+     * Resources live under `<keyPrefix>__resources__:` — a reserved segment
+     * inside the skill prefix, explicitly excluded from the index SCAN so
+     * resource values are never mistaken for skills, whatever the
+     * configured keyPrefix looks like.
+     */
+    private readonly resourcePrefix;
     private readonly normalizedConfig;
     private clientPromise;
     constructor(config: SkillRedisStorageConfig);
     private getClient;
     private skillKey;
+    getResource(id: string, resourcePath: string): Promise<string | null>;
     get(id: string): Promise<SkillDefinition | null>;
     put(skill: SkillDefinition): Promise<void>;
     delete(id: string): Promise<void>;

package/dist/skills/skillStoreRedis.js

@@ -8,14 +8,22 @@
  */
 import { getNormalizedConfig, getPooledRedisClient, scanKeys, } from "../utils/redis.js";
 import { logger } from "../utils/logger.js";
-import { toSkillIndexItem } from "./skillMatcher.js";
+import { isSafeSkillResourcePath, toSkillIndexItem } from "./skillMatcher.js";
 const DEFAULT_KEY_PREFIX = "neurolink:skills:";
 export class RedisSkillStore {
     keyPrefix;
+    /**
+     * Resources live under `<keyPrefix>__resources__:` — a reserved segment
+     * inside the skill prefix, explicitly excluded from the index SCAN so
+     * resource values are never mistaken for skills, whatever the
+     * configured keyPrefix looks like.
+     */
+    resourcePrefix;
     normalizedConfig;
     clientPromise = null;
     constructor(config) {
         this.keyPrefix = config.keyPrefix ?? DEFAULT_KEY_PREFIX;
+        this.resourcePrefix = `${this.keyPrefix}__resources__:`;
         this.normalizedConfig = getNormalizedConfig({
             ...(config.url ? { url: config.url } : {}),
             ...(config.host ? { host: config.host } : {}),
@@ -39,6 +47,14 @@ export class RedisSkillStore {
     skillKey(id) {
         return `${this.keyPrefix}${id}`;
     }
+    async getResource(id, resourcePath) {
+        if (!isSafeSkillResourcePath(resourcePath)) {
+            return null;
+        }
+        const client = await this.getClient();
+        const raw = await client.get(`${this.resourcePrefix}${id}:${resourcePath}`);
+        return raw ? String(raw) : null;
+    }
     async get(id) {
         const client = await this.getClient();
         const raw = await client.get(this.skillKey(id));
@@ -55,7 +71,7 @@ export class RedisSkillStore {
     }
     async index() {
         const client = await this.getClient();
-        const keys = await scanKeys(client, `${this.keyPrefix}*`);
+        const keys = (await scanKeys(client, `${this.keyPrefix}*`)).filter((key) => !key.startsWith(this.resourcePrefix));
         if (keys.length === 0) {
             return [];
         }

package/dist/skills/skillStoreS3.d.ts

@@ -22,20 +22,35 @@ export declare class S3SkillStore implements SkillStore {
     private readonly injectedOps?;
     private readonly prefix;
     private ops;
+    /** Last parsed index + its ETag, revalidated with If-None-Match reads. */
+    private cachedIndexDoc;
+    private cachedIndexEtag;
     constructor(config: SkillS3StorageConfig, 
     /** Test/host seam — omit to build ops from @aws-sdk/client-s3 lazily. */
     injectedOps?: SkillS3ObjectOps | undefined);
+    invalidate(): void;
     private getOps;
     private skillKey;
     private indexKey;
+    /** Resources live beside the skill object: <prefix>skills/<id>/<path>. */
+    private resourceKey;
+    getResource(id: string, resourcePath: string): Promise<string | null>;
     get(id: string): Promise<SkillDefinition | null>;
     put(skill: SkillDefinition): Promise<void>;
     delete(id: string): Promise<void>;
     index(): Promise<SkillIndexItem[]>;
     private writeIndex;
     /**
-     * Read index.json; when missing or unparsable, rebuild it from a listing
-     * of the skills/ prefix and persist the rebuilt document (self-heal).
+     * Raw index.json read. Returns the body (with its ETag when available),
+     * null body when the object is absent, or notModified when a
+     * conditional read reported the cached copy unchanged.
+     */
+    private readIndexObject;
+    /**
+     * Read index.json (ETag-revalidated when the ops support conditional
+     * reads — an unchanged index costs a 304, not a download); when missing
+     * or unparsable, rebuild it from a listing of the skills/ prefix and
+     * persist the rebuilt document (self-heal).
      */
     private readOrRebuildIndex;
 }