@juspay/neurolink 11.12.0 → 11.13.1

package/dist/lib/session/globalSessionState.d.ts

@@ -1,71 +0,0 @@
-import { NeuroLink } from "../neurolink.js";
-import type { ClassifierRouterConfig, ConversationMemoryConfig, LoopSessionState, SessionVariableValue, SkillsConfig, ToolRoutingConfig } from "../types/index.js";
-export declare class GlobalSessionManager {
-    private static instance;
-    private loopSession;
-    /** Optional tool-routing config set by CLI handlers before SDK construction. */
-    private _toolRoutingConfig;
-    /** Optional classifier-router config set by CLI handlers before SDK construction. */
-    private _classifierRouterConfig;
-    /** Optional skills config set by CLI handlers before SDK construction. */
-    private _skillsConfig;
-    static getInstance(): GlobalSessionManager;
-    setLoopSession(config?: ConversationMemoryConfig): string;
-    /**
-     * Restore a loop session with an existing sessionId and NeuroLink instance
-     * Used for conversation restoration
-     */
-    restoreLoopSession(sessionId: string, neurolinkInstance: NeuroLink, config?: ConversationMemoryConfig, sessionVariables?: Record<string, SessionVariableValue>): void;
-    /**
-     * Update session variables during restoration
-     */
-    restoreSessionVariables(variables: Record<string, SessionVariableValue>): void;
-    /**
-     * Check if a session is currently active
-     */
-    hasActiveSession(): boolean;
-    /**
-     * Get current session metadata for restoration purposes
-     */
-    getSessionMetadata(): {
-        sessionId?: string;
-        conversationMemoryConfig?: ConversationMemoryConfig;
-        sessionVariables: Record<string, SessionVariableValue>;
-        isActive: boolean;
-    };
-    /**
-     * Update the sessionId of the current session (used during restoration)
-     */
-    updateSessionId(newSessionId: string): void;
-    getLoopSession(): LoopSessionState | null;
-    clearLoopSession(): void;
-    /**
-     * Store a tool-routing config to be injected at SDK construction time.
-     * Call this BEFORE `getOrCreateNeuroLink()` inside a command handler.
-     * When a loop session is already active the config is ignored (the instance
-     * already exists).
-     */
-    setToolRoutingConfig(config: ToolRoutingConfig): void;
-    /**
-     * Store a classifier-router config to be injected at SDK construction time.
-     * Call this BEFORE `getOrCreateNeuroLink()` inside a command handler.
-     * When a loop session is already active the config is ignored (the instance
-     * already exists).
-     */
-    setClassifierRouterConfig(config: ClassifierRouterConfig): void;
-    /**
-     * Store a skills config to be injected at SDK construction time.
-     * Call this BEFORE `getOrCreateNeuroLink()` inside a command handler.
-     * When a loop session is already active the config is ignored (the instance
-     * already exists).
-     */
-    setSkillsConfig(config: SkillsConfig): void;
-    getOrCreateNeuroLink(): NeuroLink;
-    getCurrentSessionId(): string | undefined;
-    setSessionVariable(key: string, value: SessionVariableValue): void;
-    getSessionVariable(key: string): SessionVariableValue | undefined;
-    getSessionVariables(): Record<string, SessionVariableValue>;
-    unsetSessionVariable(key: string): boolean;
-    clearSessionVariables(): void;
-}
-export declare const globalSession: GlobalSessionManager;

package/dist/lib/session/globalSessionState.js

@@ -1,235 +0,0 @@
-import { nanoid } from "nanoid";
-import { NeuroLink } from "../neurolink.js";
-import { buildObservabilityConfigFromEnv } from "../utils/observabilityHelpers.js";
-/**
- * Build mcp.outputLimits config from environment variables.
- * Reads NEUROLINK_MCP_OUTPUT_STRATEGY and NEUROLINK_MCP_MAX_OUTPUT_BYTES.
- * Returns undefined when neither variable is set (no overhead).
- */
-function buildMcpOutputLimitsFromEnv() {
-    const strategyRaw = process.env.NEUROLINK_MCP_OUTPUT_STRATEGY;
-    const maxBytesRaw = process.env.NEUROLINK_MCP_MAX_OUTPUT_BYTES;
-    const warnBytesRaw = process.env.NEUROLINK_MCP_WARN_OUTPUT_BYTES;
-    if (!strategyRaw && !maxBytesRaw) {
-        return undefined;
-    }
-    const strategy = strategyRaw === "inline" || strategyRaw === "externalize"
-        ? strategyRaw
-        : "externalize"; // safe default when only maxBytes is set
-    const maxBytes = maxBytesRaw ? parseInt(maxBytesRaw, 10) : undefined;
-    const warnBytes = warnBytesRaw ? parseInt(warnBytesRaw, 10) : undefined;
-    return {
-        strategy,
-        ...(maxBytes !== undefined && Number.isFinite(maxBytes) && maxBytes >= 0
-            ? { maxBytes }
-            : {}),
-        ...(warnBytes !== undefined && Number.isFinite(warnBytes) && warnBytes >= 0
-            ? { warnBytes }
-            : {}),
-    };
-}
-export class GlobalSessionManager {
-    static instance;
-    loopSession = null;
-    /** Optional tool-routing config set by CLI handlers before SDK construction. */
-    _toolRoutingConfig = undefined;
-    /** Optional classifier-router config set by CLI handlers before SDK construction. */
-    _classifierRouterConfig = undefined;
-    /** Optional skills config set by CLI handlers before SDK construction. */
-    _skillsConfig = undefined;
-    static getInstance() {
-        if (!GlobalSessionManager.instance) {
-            GlobalSessionManager.instance = new GlobalSessionManager();
-        }
-        return GlobalSessionManager.instance;
-    }
-    setLoopSession(config) {
-        const sessionId = `NL_${nanoid()}`;
-        const neurolinkOptions = {};
-        if (config?.enabled) {
-            neurolinkOptions.conversationMemory = {
-                enabled: true,
-                maxSessions: config.maxSessions,
-                maxTurnsPerSession: config.maxTurnsPerSession,
-            };
-        }
-        // Add observability config from environment variables (CLI usage)
-        const observabilityConfig = buildObservabilityConfigFromEnv();
-        if (observabilityConfig) {
-            neurolinkOptions.observability = observabilityConfig;
-        }
-        // Add MCP output limits from environment variables (CLI usage)
-        const mcpOutputLimits = buildMcpOutputLimitsFromEnv();
-        if (mcpOutputLimits) {
-            neurolinkOptions.mcp = {
-                ...neurolinkOptions.mcp,
-                outputLimits: mcpOutputLimits,
-            };
-        }
-        this.loopSession = {
-            neurolinkInstance: new NeuroLink(neurolinkOptions),
-            sessionId,
-            isActive: true,
-            conversationMemoryConfig: config,
-            sessionVariables: {},
-        };
-        return sessionId;
-    }
-    /**
-     * Restore a loop session with an existing sessionId and NeuroLink instance
-     * Used for conversation restoration
-     */
-    restoreLoopSession(sessionId, neurolinkInstance, config, sessionVariables) {
-        this.loopSession = {
-            neurolinkInstance,
-            sessionId,
-            isActive: true,
-            conversationMemoryConfig: config,
-            sessionVariables: sessionVariables || {},
-        };
-    }
-    /**
-     * Update session variables during restoration
-     */
-    restoreSessionVariables(variables) {
-        const session = this.getLoopSession();
-        if (session) {
-            session.sessionVariables = { ...session.sessionVariables, ...variables };
-        }
-    }
-    /**
-     * Check if a session is currently active
-     */
-    hasActiveSession() {
-        return this.loopSession?.isActive ?? false;
-    }
-    /**
-     * Get current session metadata for restoration purposes
-     */
-    getSessionMetadata() {
-        const session = this.getLoopSession();
-        return {
-            sessionId: session?.sessionId,
-            conversationMemoryConfig: session?.conversationMemoryConfig,
-            sessionVariables: session?.sessionVariables || {},
-            isActive: session?.isActive ?? false,
-        };
-    }
-    /**
-     * Update the sessionId of the current session (used during restoration)
-     */
-    updateSessionId(newSessionId) {
-        const session = this.getLoopSession();
-        if (session) {
-            session.sessionId = newSessionId;
-        }
-    }
-    getLoopSession() {
-        return this.loopSession?.isActive ? this.loopSession : null;
-    }
-    clearLoopSession() {
-        if (this.loopSession) {
-            this.loopSession.isActive = false;
-            this.loopSession = null;
-        }
-    }
-    /**
-     * Store a tool-routing config to be injected at SDK construction time.
-     * Call this BEFORE `getOrCreateNeuroLink()` inside a command handler.
-     * When a loop session is already active the config is ignored (the instance
-     * already exists).
-     */
-    setToolRoutingConfig(config) {
-        if (this.hasActiveSession()) {
-            return;
-        }
-        this._toolRoutingConfig = config;
-    }
-    /**
-     * Store a classifier-router config to be injected at SDK construction time.
-     * Call this BEFORE `getOrCreateNeuroLink()` inside a command handler.
-     * When a loop session is already active the config is ignored (the instance
-     * already exists).
-     */
-    setClassifierRouterConfig(config) {
-        if (this.hasActiveSession()) {
-            return;
-        }
-        this._classifierRouterConfig = config;
-    }
-    /**
-     * Store a skills config to be injected at SDK construction time.
-     * Call this BEFORE `getOrCreateNeuroLink()` inside a command handler.
-     * When a loop session is already active the config is ignored (the instance
-     * already exists).
-     */
-    setSkillsConfig(config) {
-        if (this.hasActiveSession()) {
-            return;
-        }
-        this._skillsConfig = config;
-    }
-    getOrCreateNeuroLink() {
-        const session = this.getLoopSession();
-        if (session) {
-            return session.neurolinkInstance;
-        }
-        // Create new NeuroLink with observability config from environment (CLI usage)
-        const observabilityConfig = buildObservabilityConfigFromEnv();
-        const mcpOutputLimits = buildMcpOutputLimitsFromEnv();
-        const options = {};
-        if (observabilityConfig) {
-            options.observability = observabilityConfig;
-        }
-        if (mcpOutputLimits) {
-            options.mcp = { outputLimits: mcpOutputLimits };
-        }
-        if (this._toolRoutingConfig) {
-            options.toolRouting = this._toolRoutingConfig;
-            this._toolRoutingConfig = undefined;
-        }
-        if (this._classifierRouterConfig) {
-            options.classifierRouter = this._classifierRouterConfig;
-            this._classifierRouterConfig = undefined;
-        }
-        if (this._skillsConfig) {
-            options.skills = this._skillsConfig;
-            this._skillsConfig = undefined;
-        }
-        return new NeuroLink(Object.keys(options).length ? options : undefined);
-    }
-    getCurrentSessionId() {
-        return this.getLoopSession()?.sessionId;
-    }
-    // Session variable management
-    setSessionVariable(key, value) {
-        const session = this.getLoopSession();
-        if (session) {
-            session.sessionVariables[key] = value;
-        }
-    }
-    getSessionVariable(key) {
-        const session = this.getLoopSession();
-        return session?.sessionVariables[key];
-    }
-    getSessionVariables() {
-        const session = this.getLoopSession();
-        return session?.sessionVariables || {};
-    }
-    unsetSessionVariable(key) {
-        const session = this.getLoopSession();
-        if (session && key in session.sessionVariables) {
-            delete session.sessionVariables[key];
-            return true;
-        }
-        return false;
-    }
-    clearSessionVariables() {
-        const session = this.getLoopSession();
-        if (session) {
-            session.sessionVariables = {};
-        }
-    }
-}
-export const globalSession = GlobalSessionManager.getInstance();
-//# sourceMappingURL=globalSessionState.js.map

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

@@ -1,55 +0,0 @@
-/**
- * Pure index-filtering + prompt-index formatting helpers.
- *
- * Matching semantics are ported from curator's battle-tested
- * `searchSkillsFromIndex`: case-insensitive substring match on
- * name/displayName/description, optional tag filter on top, scope filter
- * that always admits global skills, and active-only visibility.
- */
-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[];
-/**
- * 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. Fails closed, matching
- * `filterSkillIndex`: a scoped skill is hidden unless the caller supplies a
- * `scopeId` that the skill explicitly lists. Omitting `scopeId` therefore
- * yields global skills only — it must never expose a scoped skill by name
- * through `use_skill` / `read_skill_resource` (#1139).
- */
-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

@@ -1,170 +0,0 @@
-/**
- * Pure index-filtering + prompt-index formatting helpers.
- *
- * Matching semantics are ported from curator's battle-tested
- * `searchSkillsFromIndex`: case-insensitive substring match on
- * name/displayName/description, optional tag filter on top, scope filter
- * that always admits global skills, and active-only visibility.
- */
-/** Strip instructions from a full definition to form an index entry. */
-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();
-    const lowerTag = query.tag?.toLowerCase();
-    const matched = items.filter((item) => {
-        if ((item.status ?? "active") !== "active") {
-            return false;
-        }
-        // Scope filter: global skills always pass. Scoped skills require a
-        // scopeId that matches; when the caller supplies no scopeId we fail
-        // closed and exclude them, so a shared multi-tenant instance that forgets
-        // to pass a per-call scopeId never leaks one tenant's scoped skills to
-        // everyone (#1139). Callers that legitimately want a tenant's scoped
-        // skills must pass that tenant's scopeId.
-        if (item.scope === "scoped") {
-            if (!query.scopeId || !(item.scopeIds ?? []).includes(query.scopeId)) {
-                return false;
-            }
-        }
-        if (lowerQuery) {
-            const nameMatch = item.name.toLowerCase().includes(lowerQuery) ||
-                (item.displayName ?? "").toLowerCase().includes(lowerQuery) ||
-                item.description.toLowerCase().includes(lowerQuery);
-            if (!nameMatch) {
-                return false;
-            }
-        }
-        if (lowerTag) {
-            const tagMatch = (item.tags ?? []).some((t) => t.toLowerCase().includes(lowerTag));
-            if (!tagMatch) {
-                return false;
-            }
-        }
-        return true;
-    });
-    return query.limit !== undefined ? matched.slice(0, query.limit) : matched;
-}
-/**
- * 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. Fails closed, matching
- * `filterSkillIndex`: a scoped skill is hidden unless the caller supplies a
- * `scopeId` that the skill explicitly lists. Omitting `scopeId` therefore
- * yields global skills only — it must never expose a scoped skill by name
- * through `use_skill` / `read_skill_resource` (#1139).
- */
-export function isSkillVisibleInScope(skill, scopeId) {
-    if (skill.scope !== "scoped") {
-        return true;
-    }
-    if (!scopeId) {
-        return false;
-    }
-    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) {
-    // Nothing visible, or the index is explicitly disabled (maxItems <= 0):
-    // skip injection entirely rather than emit a header + "N more skills exist"
-    // note with zero skill lines (#1139).
-    if (items.length === 0 || maxItems <= 0) {
-        return null;
-    }
-    const visible = items.slice(0, maxItems);
-    const lines = visible.map((item) => {
-        const label = item.displayName
-            ? `${item.name} (${item.displayName})`
-            : item.name;
-        const tags = item.tags && item.tags.length > 0
-            ? ` [tags: ${item.tags.join(", ")}]`
-            : "";
-        return `- ${label}: ${item.description}${tags}`;
-    });
-    const truncationNote = items.length > visible.length
-        ? `\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 use_skill tool with its name to load the full instructions, then follow them exactly.",
-        "",
-        ...lines,
-    ].join("\n") + truncationNote);
-}
-//# sourceMappingURL=skillMatcher.js.map

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

@@ -1,52 +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 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;
-}