@librechat/agents 3.1.66-dev.0 → 3.1.67

package/dist/types/tools/SkillTool.d.ts

@@ -1,40 +0,0 @@
-import { Constants } from '@/common';
-export declare const SkillToolName = Constants.SKILL_TOOL;
-export declare const SkillToolDescription = "Invoke a skill from the user's library. Skills provide domain-specific instructions loaded into the conversation context, and may also provide files accessible via available tools depending on the runtime environment.\n\nWHEN TO USE:\n- The user's request matches a skill listed in the \"Available Skills\" section of the system prompt.\n- You MUST invoke the matching skill BEFORE attempting the task yourself.\n\nWHAT HAPPENS:\n- The skill's full instructions are loaded into the conversation as context.\n- Files bundled with the skill may become accessible via available tools.\n- Follow the skill's instructions to complete the task.\n\nCONSTRAINTS:\n- Do not invoke a skill that is already active in this conversation.\n- Skill names come from the catalog only. Do not guess names.";
-/**
- * JSON Schema for the SkillTool parameters.
- * Single source of truth used by both SkillToolDefinition (LCTool registry)
- * and createSkillTool() (DynamicStructuredTool instance).
- */
-export declare const SkillToolSchema: {
-    readonly type: "object";
-    readonly properties: {
-        readonly skillName: {
-            readonly type: "string";
-            readonly description: "The kebab-case identifier of the skill to invoke (e.g. \"financial-analyzer\", \"meeting-notes\"). Must match a name from the \"Available Skills\" section.";
-        };
-        readonly args: {
-            readonly type: "string";
-            readonly description: "Optional freeform arguments string passed to the skill.";
-        };
-    };
-    readonly required: readonly ["skillName"];
-};
-export declare const SkillToolDefinition: {
-    readonly name: Constants.SKILL_TOOL;
-    readonly description: "Invoke a skill from the user's library. Skills provide domain-specific instructions loaded into the conversation context, and may also provide files accessible via available tools depending on the runtime environment.\n\nWHEN TO USE:\n- The user's request matches a skill listed in the \"Available Skills\" section of the system prompt.\n- You MUST invoke the matching skill BEFORE attempting the task yourself.\n\nWHAT HAPPENS:\n- The skill's full instructions are loaded into the conversation as context.\n- Files bundled with the skill may become accessible via available tools.\n- Follow the skill's instructions to complete the task.\n\nCONSTRAINTS:\n- Do not invoke a skill that is already active in this conversation.\n- Skill names come from the catalog only. Do not guess names.";
-    readonly parameters: {
-        readonly type: "object";
-        readonly properties: {
-            readonly skillName: {
-                readonly type: "string";
-                readonly description: "The kebab-case identifier of the skill to invoke (e.g. \"financial-analyzer\", \"meeting-notes\"). Must match a name from the \"Available Skills\" section.";
-            };
-            readonly args: {
-                readonly type: "string";
-                readonly description: "Optional freeform arguments string passed to the skill.";
-            };
-        };
-        readonly required: readonly ["skillName"];
-    };
-};

package/dist/types/tools/skillCatalog.d.ts

@@ -1,19 +0,0 @@
-import type { SkillCatalogEntry } from '@/types';
-export type SkillCatalogOptions = {
-    /** Total context window in tokens. Default: 200_000 */
-    contextWindowTokens?: number;
-    /** Fraction of context budget for catalog. Default: 0.01 (1%) */
-    budgetPercent?: number;
-    /** Max chars per entry description. Default: 250 */
-    maxEntryChars?: number;
-    /** Descriptions below this length trigger names-only fallback. Default: 20 */
-    minDescLength?: number;
-    /** Approximate chars per token for budget calculation. Default: 4 */
-    charsPerToken?: number;
-};
-/**
- * Formats a skill catalog for injection into agent context.
- * Uses a truncation ladder: full descriptions, proportional truncation, names-only.
- * Returns empty string for empty input.
- */
-export declare function formatSkillCatalog(skills: SkillCatalogEntry[], opts?: SkillCatalogOptions): string;

package/dist/types/types/skill.d.ts

@@ -1,9 +0,0 @@
-/** Minimal skill metadata for catalog assembly. The host provides these from its own data layer. */
-export type SkillCatalogEntry = {
-    /** Kebab-case identifier (what the model passes to SkillTool) */
-    name: string;
-    /** One-line description for the catalog listing */
-    description: string;
-    /** Optional human-readable label (UI only, not shown to model) */
-    displayTitle?: string;
-};

package/src/hooks/HookRegistry.ts

@@ -1,208 +0,0 @@
-// src/hooks/HookRegistry.ts
-import type { HookEvent, HookMatcher } from './types';
-
-/**
- * Internal matcher storage type.
- *
- * Matchers registered via the public `register<E>` API are strictly typed
- * to a single `E`, but the storage needs one uniform slot type per event.
- * We store them as `HookMatcher<HookEvent>` and cast once at the variance
- * boundary — see `ensureList` and `snapshot` below. The invariant (every
- * matcher in `bucket[event]` was registered with that exact event) is
- * enforced by the public API; breaking it requires bypassing the types.
- */
-type MatcherBucket = Partial<Record<HookEvent, HookMatcher<HookEvent>[]>>;
-
-/**
- * Run-scoped storage for hook matchers with an additional layer for
- * session-scoped matchers that should be cleaned up between sessions.
- *
- * Hosts construct one registry per `Run` (mirroring how `HandlerRegistry` is
- * scoped) and register global matchers + per-session matchers against it.
- * Registration is strictly additive — nothing in this class mutates a
- * matcher's callbacks or flags after insertion.
- *
- * ## Why `Map<sessionId, MatcherBucket>` and not `Record`
- *
- * LibreChat runs thousands of parallel sessions in one Node process, and
- * hook registration happens inside hot paths (tool loading, agent spawning).
- * A `Record<sessionId, ...>` has to be spread on every insertion, which is
- * O(n) per call and O(n²) total for a batch of parallel registrations. A
- * Map mutates in place, keeping insertions O(1). This mirrors the reasoning
- * Claude Code documents at `utils/hooks/sessionHooks.ts:62`.
- */
-export class HookRegistry {
-  private readonly global: MatcherBucket = {};
-  private readonly sessions: Map<string, MatcherBucket> = new Map();
-
-  /**
-   * Register a matcher for the lifetime of this registry (= one Run).
-   * Returns an unregister function that removes the matcher by reference.
-   */
-  register<E extends HookEvent>(event: E, matcher: HookMatcher<E>): () => void {
-    const list = ensureList(this.global, event);
-    list.push(widen(matcher));
-    return () => {
-      removeFromList(list, matcher);
-    };
-  }
-
-  /**
-   * Register a matcher for a specific session. Cleared automatically when
-   * `clearSession(sessionId)` is called, or can be removed directly via the
-   * returned unregister function.
-   */
-  registerSession<E extends HookEvent>(
-    sessionId: string,
-    event: E,
-    matcher: HookMatcher<E>
-  ): () => void {
-    const bucket = this.ensureSessionBucket(sessionId);
-    const list = ensureList(bucket, event);
-    list.push(widen(matcher));
-    return () => {
-      removeFromList(list, matcher);
-    };
-  }
-
-  /**
-   * Returns all matchers registered for `event`, concatenating global first
-   * and then session-specific (when `sessionId` is supplied). The caller
-   * receives a fresh array, so iterating it is safe even if a matcher is
-   * removed mid-iteration (e.g. via `once: true`).
-   */
-  getMatchers<E extends HookEvent>(
-    event: E,
-    sessionId?: string
-  ): HookMatcher<E>[] {
-    const globalList = readList(this.global, event);
-    if (sessionId === undefined) {
-      return snapshot<E>(globalList);
-    }
-    const bucket = this.sessions.get(sessionId);
-    if (bucket === undefined) {
-      return snapshot<E>(globalList);
-    }
-    const sessionList = readList(bucket, event);
-    if (globalList.length === 0) {
-      return snapshot<E>(sessionList);
-    }
-    if (sessionList.length === 0) {
-      return snapshot<E>(globalList);
-    }
-    return snapshot<E>([...globalList, ...sessionList]);
-  }
-
-  /**
-   * Removes `matcher` by reference from global storage first, falling back
-   * to the session bucket when `sessionId` is supplied. Used by
-   * `executeHooks` to drop `once: true` matchers after they fire.
-   */
-  removeMatcher<E extends HookEvent>(
-    event: E,
-    matcher: HookMatcher<E>,
-    sessionId?: string
-  ): boolean {
-    if (removeFromList(readList(this.global, event), matcher)) {
-      return true;
-    }
-    if (sessionId === undefined) {
-      return false;
-    }
-    const bucket = this.sessions.get(sessionId);
-    if (bucket === undefined) {
-      return false;
-    }
-    return removeFromList(readList(bucket, event), matcher);
-  }
-
-  /**
-   * Drops every session-scoped matcher for `sessionId`. Call this in the
-   * `finally` block around a Run so a `once: true` hook that never fired
-   * cannot leak into the next session on the same registry.
-   */
-  clearSession(sessionId: string): void {
-    this.sessions.delete(sessionId);
-  }
-
-  /** True if at least one matcher exists for `event` (global + session). */
-  hasHookFor(event: HookEvent, sessionId?: string): boolean {
-    if (readList(this.global, event).length > 0) {
-      return true;
-    }
-    if (sessionId === undefined) {
-      return false;
-    }
-    const bucket = this.sessions.get(sessionId);
-    if (bucket === undefined) {
-      return false;
-    }
-    return readList(bucket, event).length > 0;
-  }
-
-  private ensureSessionBucket(sessionId: string): MatcherBucket {
-    const existing = this.sessions.get(sessionId);
-    if (existing !== undefined) {
-      return existing;
-    }
-    const fresh: MatcherBucket = {};
-    this.sessions.set(sessionId, fresh);
-    return fresh;
-  }
-}
-
-function ensureList(
-  bucket: MatcherBucket,
-  event: HookEvent
-): HookMatcher<HookEvent>[] {
-  const existing = bucket[event];
-  if (existing !== undefined) {
-    return existing;
-  }
-  const fresh: HookMatcher<HookEvent>[] = [];
-  bucket[event] = fresh;
-  return fresh;
-}
-
-function readList(
-  bucket: MatcherBucket,
-  event: HookEvent
-): HookMatcher<HookEvent>[] {
-  return bucket[event] ?? [];
-}
-
-function removeFromList<E extends HookEvent>(
-  list: HookMatcher<HookEvent>[],
-  matcher: HookMatcher<E>
-): boolean {
-  const idx = list.indexOf(widen(matcher));
-  if (idx < 0) {
-    return false;
-  }
-  list.splice(idx, 1);
-  return true;
-}
-
-/**
- * Widen a per-event matcher to the storage's uniform slot type. Unsound at
- * the type level (function parameters are contravariant) but safe by
- * construction: `HookRegistry.register<E>` only ever puts matchers into the
- * bucket slot for their own event, and reads go through `snapshot<E>`
- * which is only called with the same `E`.
- */
-function widen<E extends HookEvent>(
-  matcher: HookMatcher<E>
-): HookMatcher<HookEvent> {
-  return matcher as unknown as HookMatcher<HookEvent>;
-}
-
-/**
- * Narrow a storage list back to a per-event matcher list on the way out.
- * Sound counterpart to `widen`: the list only contains matchers that were
- * registered against `E`, because the public API enforces it on insert.
- */
-function snapshot<E extends HookEvent>(
-  list: readonly HookMatcher<HookEvent>[]
-): HookMatcher<E>[] {
-  return list.slice() as unknown as HookMatcher<E>[];
-}

package/src/hooks/__tests__/HookRegistry.test.ts

@@ -1,190 +0,0 @@
-// src/hooks/__tests__/HookRegistry.test.ts
-import { HookRegistry } from '../HookRegistry';
-import type {
-  HookMatcher,
-  HookCallback,
-  PreToolUseHookOutput,
-  PostToolUseHookOutput,
-} from '../types';
-
-const noop: HookCallback<
-  'PreToolUse'
-> = async (): Promise<PreToolUseHookOutput> => ({});
-const noopPost: HookCallback<
-  'PostToolUse'
-> = async (): Promise<PostToolUseHookOutput> => ({});
-
-function makePreToolUseMatcher(pattern?: string): HookMatcher<'PreToolUse'> {
-  return {
-    pattern,
-    hooks: [noop],
-  };
-}
-
-function makePostToolUseMatcher(): HookMatcher<'PostToolUse'> {
-  return {
-    hooks: [noopPost],
-  };
-}
-
-describe('HookRegistry', () => {
-  describe('global registration', () => {
-    it('stores a matcher and returns it via getMatchers', () => {
-      const registry = new HookRegistry();
-      const matcher = makePreToolUseMatcher('Bash');
-      registry.register('PreToolUse', matcher);
-      const matchers = registry.getMatchers('PreToolUse');
-      expect(matchers).toHaveLength(1);
-      expect(matchers[0]).toBe(matcher);
-    });
-
-    it('keeps registrations isolated across events', () => {
-      const registry = new HookRegistry();
-      const pre = makePreToolUseMatcher('Bash');
-      const post = makePostToolUseMatcher();
-      registry.register('PreToolUse', pre);
-      registry.register('PostToolUse', post);
-      expect(registry.getMatchers('PreToolUse')).toEqual([pre]);
-      expect(registry.getMatchers('PostToolUse')).toEqual([post]);
-      expect(registry.getMatchers('Stop')).toEqual([]);
-    });
-
-    it('unregister removes the matcher from the registry', () => {
-      const registry = new HookRegistry();
-      const matcher = makePreToolUseMatcher();
-      const unregister = registry.register('PreToolUse', matcher);
-      expect(registry.getMatchers('PreToolUse')).toHaveLength(1);
-      unregister();
-      expect(registry.getMatchers('PreToolUse')).toHaveLength(0);
-    });
-
-    it('hasHookFor reflects registration state', () => {
-      const registry = new HookRegistry();
-      expect(registry.hasHookFor('PreToolUse')).toBe(false);
-      registry.register('PreToolUse', makePreToolUseMatcher());
-      expect(registry.hasHookFor('PreToolUse')).toBe(true);
-      expect(registry.hasHookFor('PostToolUse')).toBe(false);
-    });
-
-    it('supports multiple matchers on the same event', () => {
-      const registry = new HookRegistry();
-      const a = makePreToolUseMatcher('Bash');
-      const b = makePreToolUseMatcher('Edit');
-      registry.register('PreToolUse', a);
-      registry.register('PreToolUse', b);
-      const matchers = registry.getMatchers('PreToolUse');
-      expect(matchers).toHaveLength(2);
-      expect(matchers).toContain(a);
-      expect(matchers).toContain(b);
-    });
-
-    it('returns a fresh array on each getMatchers call', () => {
-      const registry = new HookRegistry();
-      registry.register('PreToolUse', makePreToolUseMatcher());
-      const first = registry.getMatchers('PreToolUse');
-      const second = registry.getMatchers('PreToolUse');
-      expect(first).not.toBe(second);
-      first.length = 0;
-      expect(registry.getMatchers('PreToolUse')).toHaveLength(1);
-    });
-  });
-
-  describe('session registration', () => {
-    it('scopes matchers to a single session', () => {
-      const registry = new HookRegistry();
-      const sessionA = makePreToolUseMatcher('Bash');
-      const sessionB = makePreToolUseMatcher('Edit');
-      registry.registerSession('run-a', 'PreToolUse', sessionA);
-      registry.registerSession('run-b', 'PreToolUse', sessionB);
-
-      expect(registry.getMatchers('PreToolUse', 'run-a')).toEqual([sessionA]);
-      expect(registry.getMatchers('PreToolUse', 'run-b')).toEqual([sessionB]);
-      expect(registry.getMatchers('PreToolUse')).toEqual([]);
-    });
-
-    it('merges global matchers in front of session matchers', () => {
-      const registry = new HookRegistry();
-      const global = makePreToolUseMatcher('global');
-      const session = makePreToolUseMatcher('session');
-      registry.register('PreToolUse', global);
-      registry.registerSession('run-a', 'PreToolUse', session);
-
-      const matchers = registry.getMatchers('PreToolUse', 'run-a');
-      expect(matchers).toEqual([global, session]);
-    });
-
-    it('clearSession drops only the given session', () => {
-      const registry = new HookRegistry();
-      const a = makePreToolUseMatcher('a');
-      const b = makePreToolUseMatcher('b');
-      registry.registerSession('run-a', 'PreToolUse', a);
-      registry.registerSession('run-b', 'PreToolUse', b);
-
-      registry.clearSession('run-a');
-      expect(registry.getMatchers('PreToolUse', 'run-a')).toEqual([]);
-      expect(registry.getMatchers('PreToolUse', 'run-b')).toEqual([b]);
-    });
-
-    it('removeMatcher removes from the correct scope', () => {
-      const registry = new HookRegistry();
-      const global = makePreToolUseMatcher('global');
-      const session = makePreToolUseMatcher('session');
-      registry.register('PreToolUse', global);
-      registry.registerSession('run-a', 'PreToolUse', session);
-
-      expect(registry.removeMatcher('PreToolUse', session, 'run-a')).toBe(true);
-      expect(registry.getMatchers('PreToolUse', 'run-a')).toEqual([global]);
-
-      expect(registry.removeMatcher('PreToolUse', global)).toBe(true);
-      expect(registry.getMatchers('PreToolUse', 'run-a')).toEqual([]);
-    });
-
-    it('removeMatcher returns false when the matcher is not found', () => {
-      const registry = new HookRegistry();
-      const orphan = makePreToolUseMatcher('orphan');
-      expect(registry.removeMatcher('PreToolUse', orphan)).toBe(false);
-      expect(registry.removeMatcher('PreToolUse', orphan, 'run-a')).toBe(false);
-    });
-
-    it('session unregister function removes only that matcher', () => {
-      const registry = new HookRegistry();
-      const a = makePreToolUseMatcher('a');
-      const b = makePreToolUseMatcher('b');
-      const unregisterA = registry.registerSession('run-a', 'PreToolUse', a);
-      registry.registerSession('run-a', 'PreToolUse', b);
-
-      unregisterA();
-      expect(registry.getMatchers('PreToolUse', 'run-a')).toEqual([b]);
-    });
-
-    it('hasHookFor honours the sessionId parameter', () => {
-      const registry = new HookRegistry();
-      registry.registerSession('run-a', 'PreToolUse', makePreToolUseMatcher());
-      expect(registry.hasHookFor('PreToolUse')).toBe(false);
-      expect(registry.hasHookFor('PreToolUse', 'run-a')).toBe(true);
-      expect(registry.hasHookFor('PreToolUse', 'run-b')).toBe(false);
-    });
-  });
-
-  describe('session isolation under parallel registration', () => {
-    it('does not leak matchers between sessions registered in parallel', async () => {
-      const registry = new HookRegistry();
-      const sessions = Array.from({ length: 50 }, (_, i) => `run-${i}`);
-      await Promise.all(
-        sessions.map(async (sid): Promise<void> => {
-          registry.registerSession(
-            sid,
-            'PreToolUse',
-            makePreToolUseMatcher(sid)
-          );
-        })
-      );
-
-      for (const sid of sessions) {
-        const matchers = registry.getMatchers('PreToolUse', sid);
-        expect(matchers).toHaveLength(1);
-        expect(matchers[0]?.pattern).toBe(sid);
-      }
-    });
-  });
-});