@juspay/neurolink 11.13.0 → 11.13.2

package/dist/lib/skills/skillSessionTracker.js

@@ -1,150 +0,0 @@
-/**
- * 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

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

@@ -1,30 +0,0 @@
-/**
- * Redis-backed skill store.
- *
- * Reuses NeuroLink's pooled Redis client (`redis` v5 is already a core
- * dependency, shared with Redis conversation memory). One JSON value per
- * skill under `<keyPrefix><id>`; the index is derived with SCAN + MGET —
- * no separate index document to drift. Skills are persistent (no TTL).
- */
-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>;
-    index(): Promise<SkillIndexItem[]>;
-    private parseSkill;
-}

package/dist/lib/skills/skillStoreRedis.js

@@ -1,114 +0,0 @@
-/**
- * Redis-backed skill store.
- *
- * Reuses NeuroLink's pooled Redis client (`redis` v5 is already a core
- * dependency, shared with Redis conversation memory). One JSON value per
- * skill under `<keyPrefix><id>`; the index is derived with SCAN + MGET —
- * no separate index document to drift. Skills are persistent (no TTL).
- */
-import { getNormalizedConfig, getPooledRedisClient, scanKeys, } from "../utils/redis.js";
-import { logger } from "../utils/logger.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 } : {}),
-            ...(config.port !== undefined ? { port: config.port } : {}),
-            ...(config.username ? { username: config.username } : {}),
-            ...(config.password ? { password: config.password } : {}),
-            ...(config.db !== undefined ? { db: config.db } : {}),
-            keyPrefix: this.keyPrefix,
-        });
-    }
-    getClient() {
-        if (!this.clientPromise) {
-            this.clientPromise = getPooledRedisClient(this.normalizedConfig).catch((error) => {
-                // Reset so a later call can retry after a transient outage.
-                this.clientPromise = null;
-                throw error;
-            });
-        }
-        return this.clientPromise;
-    }
-    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));
-        return raw ? this.parseSkill(String(raw), this.skillKey(id)) : null;
-    }
-    async put(skill) {
-        const client = await this.getClient();
-        // Persistent — deliberately no TTL: skills must not expire silently.
-        await client.set(this.skillKey(skill.id), JSON.stringify(skill));
-    }
-    async delete(id) {
-        const client = await this.getClient();
-        await client.del(this.skillKey(id));
-    }
-    async index() {
-        const client = await this.getClient();
-        const keys = (await scanKeys(client, `${this.keyPrefix}*`)).filter((key) => !key.startsWith(this.resourcePrefix));
-        if (keys.length === 0) {
-            return [];
-        }
-        const values = await client.mGet(keys);
-        const items = [];
-        values.forEach((value, i) => {
-            if (!value) {
-                return;
-            }
-            const skill = this.parseSkill(String(value), keys[i]);
-            if (skill) {
-                items.push(toSkillIndexItem(skill));
-            }
-        });
-        return items;
-    }
-    parseSkill(raw, key) {
-        try {
-            const parsed = JSON.parse(raw);
-            if (typeof parsed?.id === "string" &&
-                typeof parsed?.name === "string" &&
-                typeof parsed?.description === "string" &&
-                typeof parsed?.instructions === "string") {
-                return parsed;
-            }
-            logger.warn("[SkillStoreRedis] Value is not a valid skill — skipping", {
-                key,
-            });
-            return null;
-        }
-        catch (error) {
-            logger.warn("[SkillStoreRedis] Failed to parse skill value", {
-                key,
-                error: error instanceof Error ? error.message : String(error),
-            });
-            return null;
-        }
-    }
-}
-//# sourceMappingURL=skillStoreRedis.js.map

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

@@ -1,56 +0,0 @@
-/**
- * S3-backed skill store.
- *
- * Layout (curator-compatible):
- *   <prefix>skills/<id>.json  — one JSON-serialized SkillDefinition per object
- *   <prefix>index.json        — { lastUpdated, skills: SkillIndexItem[] }
- *
- * The index document is upserted on every write and rebuilt from a bucket
- * listing when missing or unparsable (self-healing). Concurrent writers can
- * race the index read-modify-write; the rebuild path recovers from any
- * resulting drift, matching curator's production behavior.
- *
- * @aws-sdk/client-s3 is an optional peer — loaded lazily with the same
- * createRequire pattern as memory's @juspay/hippocampus so importing
- * NeuroLink core never requires the AWS SDK. Tests (and hosts with
- * pre-configured clients) inject a SkillS3ObjectOps implementation instead.
- */
-import type { SkillDefinition, SkillIndexItem, SkillS3ObjectOps, SkillS3StorageConfig, SkillStore } from "../types/index.js";
-export declare class S3SkillStore implements SkillStore {
-    private readonly config;
-    /** Test/host seam — omit to build ops from @aws-sdk/client-s3 lazily. */
-    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;
-    /**
-     * 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;
-}

package/dist/lib/skills/skillStoreS3.js

@@ -1,305 +0,0 @@
-/**
- * S3-backed skill store.
- *
- * Layout (curator-compatible):
- *   <prefix>skills/<id>.json  — one JSON-serialized SkillDefinition per object
- *   <prefix>index.json        — { lastUpdated, skills: SkillIndexItem[] }
- *
- * The index document is upserted on every write and rebuilt from a bucket
- * listing when missing or unparsable (self-healing). Concurrent writers can
- * race the index read-modify-write; the rebuild path recovers from any
- * resulting drift, matching curator's production behavior.
- *
- * @aws-sdk/client-s3 is an optional peer — loaded lazily with the same
- * createRequire pattern as memory's @juspay/hippocampus so importing
- * NeuroLink core never requires the AWS SDK. Tests (and hosts with
- * pre-configured clients) inject a SkillS3ObjectOps implementation instead.
- */
-import { createRequire } from "node:module";
-import { logger } from "../utils/logger.js";
-import { isSafeSkillResourcePath, toSkillIndexItem } from "./skillMatcher.js";
-const lazyRequire = createRequire(import.meta.url);
-let cachedS3Module;
-function loadS3Module() {
-    if (cachedS3Module !== undefined) {
-        return cachedS3Module;
-    }
-    try {
-        cachedS3Module = lazyRequire("@aws-sdk/client-s3");
-        return cachedS3Module;
-    }
-    catch (error) {
-        cachedS3Module = null;
-        logger.debug("[SkillStoreS3] @aws-sdk/client-s3 is not installed; S3 skill storage unavailable.", { error: error instanceof Error ? error.message : String(error) });
-        return null;
-    }
-}
-/** Build default object ops from @aws-sdk/client-s3. Throws when absent. */
-function createDefaultOps(config) {
-    const mod = loadS3Module();
-    if (!mod) {
-        throw new Error("Skills S3 storage requires @aws-sdk/client-s3. Run `pnpm add @aws-sdk/client-s3` " +
-            "(or your package manager equivalent), or supply a custom store instead.");
-    }
-    const client = new mod.S3Client({
-        ...(config.region ? { region: config.region } : {}),
-        ...(config.endpoint ? { endpoint: config.endpoint } : {}),
-        ...(config.forcePathStyle !== undefined
-            ? { forcePathStyle: config.forcePathStyle }
-            : {}),
-        ...(config.credentials ? { credentials: config.credentials } : {}),
-    });
-    const bucket = config.bucket;
-    return {
-        async getObject(key) {
-            try {
-                const response = (await client.send(new mod.GetObjectCommand({ Bucket: bucket, Key: key })));
-                return (await response.Body?.transformToString()) ?? null;
-            }
-            catch (error) {
-                const name = error.name;
-                if (name === "NoSuchKey" || name === "NotFound") {
-                    return null;
-                }
-                throw error;
-            }
-        },
-        async putObject(key, body) {
-            await client.send(new mod.PutObjectCommand({
-                Bucket: bucket,
-                Key: key,
-                Body: body,
-                ContentType: "application/json",
-            }));
-        },
-        async deleteObject(key) {
-            await client.send(new mod.DeleteObjectCommand({ Bucket: bucket, Key: key }));
-        },
-        async listKeys(prefix) {
-            const keys = [];
-            let continuationToken;
-            do {
-                const response = (await client.send(new mod.ListObjectsV2Command({
-                    Bucket: bucket,
-                    Prefix: prefix,
-                    ...(continuationToken
-                        ? { ContinuationToken: continuationToken }
-                        : {}),
-                })));
-                for (const item of response.Contents ?? []) {
-                    if (item.Key) {
-                        keys.push(item.Key);
-                    }
-                }
-                continuationToken = response.IsTruncated
-                    ? response.NextContinuationToken
-                    : undefined;
-            } while (continuationToken);
-            return keys;
-        },
-        async getObjectConditional(key, etag) {
-            try {
-                const response = (await client.send(new mod.GetObjectCommand({
-                    Bucket: bucket,
-                    Key: key,
-                    ...(etag ? { IfNoneMatch: etag } : {}),
-                })));
-                const body = (await response.Body?.transformToString()) ?? null;
-                return {
-                    body,
-                    ...(response.ETag ? { etag: response.ETag } : {}),
-                };
-            }
-            catch (error) {
-                const name = error.name;
-                const status = error
-                    .$metadata?.httpStatusCode;
-                if (status === 304 || name === "304" || name === "NotModified") {
-                    return { body: null, notModified: true };
-                }
-                if (name === "NoSuchKey" || name === "NotFound") {
-                    return { body: null };
-                }
-                throw error;
-            }
-        },
-    };
-}
-export class S3SkillStore {
-    config;
-    injectedOps;
-    prefix;
-    ops = null;
-    /** Last parsed index + its ETag, revalidated with If-None-Match reads. */
-    cachedIndexDoc = null;
-    cachedIndexEtag;
-    constructor(config, 
-    /** Test/host seam — omit to build ops from @aws-sdk/client-s3 lazily. */
-    injectedOps) {
-        this.config = config;
-        this.injectedOps = injectedOps;
-        const rawPrefix = config.prefix ?? "neurolink-skills/";
-        this.prefix =
-            rawPrefix === "" || rawPrefix.endsWith("/") ? rawPrefix : `${rawPrefix}/`;
-    }
-    invalidate() {
-        this.cachedIndexDoc = null;
-        this.cachedIndexEtag = undefined;
-    }
-    getOps() {
-        if (!this.ops) {
-            this.ops = this.injectedOps ?? createDefaultOps(this.config);
-        }
-        return this.ops;
-    }
-    skillKey(id) {
-        return `${this.prefix}skills/${id}.json`;
-    }
-    indexKey() {
-        return `${this.prefix}index.json`;
-    }
-    /** Resources live beside the skill object: <prefix>skills/<id>/<path>. */
-    resourceKey(id, resourcePath) {
-        return `${this.prefix}skills/${id}/${resourcePath}`;
-    }
-    async getResource(id, resourcePath) {
-        if (!isSafeSkillResourcePath(resourcePath)) {
-            return null;
-        }
-        return this.getOps().getObject(this.resourceKey(id, resourcePath));
-    }
-    async get(id) {
-        const body = await this.getOps().getObject(this.skillKey(id));
-        if (!body) {
-            return null;
-        }
-        try {
-            return JSON.parse(body);
-        }
-        catch (error) {
-            logger.warn("[SkillStoreS3] Failed to parse skill object", {
-                id,
-                error: error instanceof Error ? error.message : String(error),
-            });
-            return null;
-        }
-    }
-    async put(skill) {
-        const ops = this.getOps();
-        await ops.putObject(this.skillKey(skill.id), JSON.stringify(skill, null, 2));
-        const index = await this.readOrRebuildIndex();
-        const entry = toSkillIndexItem(skill);
-        const position = index.skills.findIndex((s) => s.id === skill.id);
-        if (position >= 0) {
-            index.skills[position] = entry;
-        }
-        else {
-            index.skills.push(entry);
-        }
-        await this.writeIndex(index);
-    }
-    async delete(id) {
-        const ops = this.getOps();
-        await ops.deleteObject(this.skillKey(id));
-        const index = await this.readOrRebuildIndex();
-        index.skills = index.skills.filter((s) => s.id !== id);
-        await this.writeIndex(index);
-    }
-    async index() {
-        const index = await this.readOrRebuildIndex();
-        return index.skills;
-    }
-    async writeIndex(index) {
-        index.lastUpdated = new Date().toISOString();
-        await this.getOps().putObject(this.indexKey(), JSON.stringify(index, null, 2));
-        // The write changed the object's ETag; keep the doc, revalidate next read.
-        this.cachedIndexDoc = index;
-        this.cachedIndexEtag = undefined;
-    }
-    /**
-     * 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.
-     */
-    async readIndexObject(ops) {
-        if (ops.getObjectConditional) {
-            return ops.getObjectConditional(this.indexKey(), this.cachedIndexDoc ? this.cachedIndexEtag : undefined);
-        }
-        return { body: await ops.getObject(this.indexKey()) };
-    }
-    /**
-     * 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).
-     */
-    async readOrRebuildIndex() {
-        const ops = this.getOps();
-        const read = await this.readIndexObject(ops);
-        if (read.notModified && this.cachedIndexDoc) {
-            return this.cachedIndexDoc;
-        }
-        if (read.body) {
-            try {
-                const parsed = JSON.parse(read.body);
-                if (Array.isArray(parsed.skills)) {
-                    this.cachedIndexDoc = parsed;
-                    // Cache the ETag only for a body that parsed: pairing a corrupt
-                    // object's ETag with the previous good doc would make every
-                    // later conditional read 304 into permanently stale data.
-                    this.cachedIndexEtag = read.etag;
-                    return parsed;
-                }
-            }
-            catch (error) {
-                logger.warn("[SkillStoreS3] index.json unparsable — rebuilding", {
-                    error: error instanceof Error ? error.message : String(error),
-                });
-            }
-            this.cachedIndexEtag = undefined;
-        }
-        const skillsPrefix = `${this.prefix}skills/`;
-        const keys = await ops.listKeys(skillsPrefix);
-        const skills = [];
-        for (const key of keys) {
-            if (!key.endsWith(".json")) {
-                continue;
-            }
-            const body = await ops.getObject(key);
-            if (!body) {
-                continue;
-            }
-            try {
-                skills.push(toSkillIndexItem(JSON.parse(body)));
-            }
-            catch {
-                logger.warn("[SkillStoreS3] Skipping unparsable skill during rebuild", {
-                    key,
-                });
-            }
-        }
-        const rebuilt = {
-            lastUpdated: new Date().toISOString(),
-            skills,
-        };
-        // Cache the rebuilt doc even when persistence below fails, so reads
-        // don't fall back to a stale pre-rebuild copy.
-        this.cachedIndexDoc = rebuilt;
-        this.cachedIndexEtag = undefined;
-        try {
-            await this.writeIndex(rebuilt);
-            logger.info("[SkillStoreS3] Rebuilt skills index", {
-                count: skills.length,
-            });
-        }
-        catch (error) {
-            // Index persistence is best-effort; the rebuilt in-memory copy is
-            // still returned so reads keep working.
-            logger.warn("[SkillStoreS3] Failed to persist rebuilt index", {
-                error: error instanceof Error ? error.message : String(error),
-            });
-        }
-        return rebuilt;
-    }
-}
-//# sourceMappingURL=skillStoreS3.js.map