@librechat/agents 3.1.64 → 3.1.66-dev.0

package/src/tools/__tests__/skillCatalog.test.ts

@@ -0,0 +1,161 @@
+import { describe, it, expect } from '@jest/globals';
+import { formatSkillCatalog } from '../skillCatalog';
+import type { SkillCatalogEntry } from '@/types';
+
+describe('formatSkillCatalog', () => {
+  it('returns empty string for empty array', () => {
+    expect(formatSkillCatalog([])).toBe('');
+  });
+
+  it('formats a single skill with header', () => {
+    const skills: SkillCatalogEntry[] = [
+      {
+        name: 'pdf-processor',
+        description: 'Processes PDF files into structured data.',
+      },
+    ];
+    const result = formatSkillCatalog(skills);
+    expect(result).toBe(
+      '## Available Skills\n\n- pdf-processor: Processes PDF files into structured data.'
+    );
+  });
+
+  it('formats multiple skills within budget', () => {
+    const skills: SkillCatalogEntry[] = [
+      { name: 'pdf-processor', description: 'Processes PDF files.' },
+      { name: 'review-pr', description: 'Reviews pull requests.' },
+      { name: 'meeting-notes', description: 'Formats meeting transcripts.' },
+    ];
+    const result = formatSkillCatalog(skills);
+    expect(result).toContain('## Available Skills');
+    expect(result).toContain('- pdf-processor: Processes PDF files.');
+    expect(result).toContain('- review-pr: Reviews pull requests.');
+    expect(result).toContain('- meeting-notes: Formats meeting transcripts.');
+  });
+
+  it('caps per-entry descriptions at maxEntryChars', () => {
+    const longDesc = 'A'.repeat(300);
+    const skills: SkillCatalogEntry[] = [
+      { name: 'long-skill', description: longDesc },
+    ];
+    const result = formatSkillCatalog(skills);
+    expect(result).toContain('- long-skill: ' + 'A'.repeat(249) + '\u2026');
+    expect(result).not.toContain('A'.repeat(300));
+  });
+
+  it('truncates descriptions proportionally when over budget', () => {
+    const skills: SkillCatalogEntry[] = Array.from({ length: 10 }, (_, i) => ({
+      name: `sk-${i}`,
+      description: 'D'.repeat(200),
+    }));
+    // Budget = 10000 * 0.01 * 4 = 400 chars — enough for names + short descs, not full 200-char descs
+    const result = formatSkillCatalog(skills, {
+      contextWindowTokens: 10000,
+      budgetPercent: 0.01,
+      charsPerToken: 4,
+    });
+    expect(result).toContain('## Available Skills');
+    for (let i = 0; i < 10; i++) {
+      expect(result).toContain(`sk-${i}`);
+    }
+    // Full 200-char descriptions should be truncated
+    expect(result).not.toContain('D'.repeat(200));
+  });
+
+  it('falls back to names-only when extremely over budget', () => {
+    const skills: SkillCatalogEntry[] = Array.from({ length: 10 }, (_, i) => ({
+      name: `s${i}`,
+      description: 'Very detailed description that is quite long and verbose.',
+    }));
+    // Budget = 2000 * 0.01 * 4 = 80 chars — enough for names-only but not descriptions
+    const result = formatSkillCatalog(skills, {
+      contextWindowTokens: 2000,
+      budgetPercent: 0.01,
+      charsPerToken: 4,
+    });
+    expect(result).toContain('## Available Skills');
+    expect(result).toContain('- s0');
+    // Verify entry lines have no descriptions (names-only format)
+    const entryLines = result.split('\n').filter((l) => l.startsWith('- '));
+    for (const line of entryLines) {
+      expect(line).toMatch(/^- s\d+$/);
+    }
+  });
+
+  it('respects custom options', () => {
+    const skills: SkillCatalogEntry[] = [
+      { name: 'test', description: 'A'.repeat(100) },
+    ];
+    const result = formatSkillCatalog(skills, { maxEntryChars: 50 });
+    expect(result).toContain('A'.repeat(49) + '\u2026');
+    expect(result).not.toContain('A'.repeat(100));
+  });
+
+  it('includes skills with descriptions shorter than minDescLength', () => {
+    const skills: SkillCatalogEntry[] = [
+      { name: 'short', description: 'Hi' },
+      { name: 'normal', description: 'A normal description here.' },
+    ];
+    const result = formatSkillCatalog(skills);
+    expect(result).toContain('- short: Hi');
+    expect(result).toContain('- normal: A normal description here.');
+  });
+
+  it('handles all skills with zero-length descriptions as names-only', () => {
+    const skills: SkillCatalogEntry[] = [
+      { name: 'alpha', description: '' },
+      { name: 'beta', description: '' },
+    ];
+    const result = formatSkillCatalog(skills);
+    expect(result).toBe('## Available Skills\n\n- alpha\n- beta');
+  });
+
+  it('has no trailing or leading whitespace', () => {
+    const skills: SkillCatalogEntry[] = [
+      { name: 'test', description: 'A test skill.' },
+    ];
+    const result = formatSkillCatalog(skills);
+    expect(result).toBe(result.trim());
+    const lines = result.split('\n');
+    for (const line of lines) {
+      expect(line).toBe(line.trimEnd());
+    }
+  });
+
+  it('truncates names-only list when even names exceed budget', () => {
+    const skills: SkillCatalogEntry[] = Array.from({ length: 100 }, (_, i) => ({
+      name: `skill-with-a-long-name-${i}`,
+      description: 'Some description.',
+    }));
+    // Budget so small that even names-only for 100 skills exceeds it
+    const result = formatSkillCatalog(skills, {
+      contextWindowTokens: 100,
+      budgetPercent: 0.01,
+      charsPerToken: 4,
+    });
+    // Should still have the header and at least one entry, but not all 100
+    if (result === '') {
+      // Budget too small for even one entry — valid edge case
+      expect(result).toBe('');
+    } else {
+      expect(result).toContain('## Available Skills');
+      const entryLines = result.split('\n').filter((l) => l.startsWith('- '));
+      expect(entryLines.length).toBeLessThan(100);
+      expect(entryLines.length).toBeGreaterThan(0);
+      expect(result.length).toBeLessThanOrEqual(100 * 0.01 * 4);
+    }
+  });
+
+  it('ignores displayTitle in output', () => {
+    const skills: SkillCatalogEntry[] = [
+      {
+        name: 'my-skill',
+        description: 'Does stuff.',
+        displayTitle: 'My Fancy Skill',
+      },
+    ];
+    const result = formatSkillCatalog(skills);
+    expect(result).not.toContain('My Fancy Skill');
+    expect(result).toContain('- my-skill: Does stuff.');
+  });
+});

package/src/tools/skillCatalog.ts

@@ -0,0 +1,126 @@
+// src/tools/skillCatalog.ts
+import type { SkillCatalogEntry } from '@/types';
+
+const HEADER = '## Available Skills';
+const DEFAULT_CONTEXT_WINDOW_TOKENS = 200_000;
+const DEFAULT_BUDGET_PERCENT = 0.01;
+const DEFAULT_MAX_ENTRY_CHARS = 250;
+const DEFAULT_MIN_DESC_LENGTH = 20;
+const DEFAULT_CHARS_PER_TOKEN = 4;
+
+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 function formatSkillCatalog(
+  skills: SkillCatalogEntry[],
+  opts?: SkillCatalogOptions
+): string {
+  if (skills.length === 0) return '';
+
+  const contextWindowTokens =
+    opts?.contextWindowTokens ?? DEFAULT_CONTEXT_WINDOW_TOKENS;
+  const budgetPercent = opts?.budgetPercent ?? DEFAULT_BUDGET_PERCENT;
+  const maxEntryChars = Math.max(
+    1,
+    opts?.maxEntryChars ?? DEFAULT_MAX_ENTRY_CHARS
+  );
+  const minDescLength = opts?.minDescLength ?? DEFAULT_MIN_DESC_LENGTH;
+  const charsPerToken = opts?.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;
+
+  const budgetChars = Math.floor(
+    contextWindowTokens * budgetPercent * charsPerToken
+  );
+
+  const capped = skills.map((s) => ({
+    name: s.name,
+    description:
+      s.description.length > maxEntryChars
+        ? s.description.slice(0, maxEntryChars - 1) + '\u2026'
+        : s.description,
+  }));
+
+  const fullOutput = formatEntries(capped);
+  if (fullOutput.length <= budgetChars) return fullOutput;
+
+  const headerLen = HEADER.length + 2;
+  const newlineChars = capped.length > 1 ? capped.length - 1 : 0;
+  const availableChars = budgetChars - headerLen - newlineChars;
+  const perEntryOverhead = 4;
+  const nameCharsTotal = capped.reduce(
+    (sum, s) => sum + s.name.length + perEntryOverhead,
+    0
+  );
+  const availableForDescs = availableChars - nameCharsTotal;
+
+  if (availableForDescs <= 0) {
+    return fitNamesOnly(capped, budgetChars);
+  }
+
+  const maxDescPerEntry = Math.floor(availableForDescs / capped.length);
+
+  if (maxDescPerEntry < minDescLength) {
+    return fitNamesOnly(capped, budgetChars);
+  }
+
+  const truncated = capped.map((s) => ({
+    name: s.name,
+    description:
+      s.description.length > maxDescPerEntry
+        ? s.description.slice(0, maxDescPerEntry - 1) + '\u2026'
+        : s.description,
+  }));
+
+  const result = formatEntries(truncated);
+  if (result.length <= budgetChars) return result;
+  return fitNamesOnly(capped, budgetChars);
+}
+
+function formatEntries(
+  entries: { name: string; description: string }[]
+): string {
+  const lines = entries.map((e) =>
+    e.description ? `- ${e.name}: ${e.description}` : `- ${e.name}`
+  );
+  return `${HEADER}\n\n${lines.join('\n')}`;
+}
+
+/** Names-only fallback that drops trailing entries if the list still exceeds budget. */
+function fitNamesOnly(
+  entries: { name: string }[],
+  budgetChars: number
+): string {
+  // Format: "HEADER\n\n- name1\n- name2\n..."
+  // Running sum avoids O(n²) repeated string construction.
+  const prefix = HEADER.length + 2; // "HEADER\n\n"
+  const entryOverhead = 2; // "- "
+  let total = prefix;
+  let fitCount = 0;
+
+  for (let i = 0; i < entries.length; i++) {
+    const added = (i > 0 ? 1 : 0) + entryOverhead + entries[i].name.length;
+    if (total + added > budgetChars) break;
+    total += added;
+    fitCount = i + 1;
+  }
+
+  if (fitCount === 0) return '';
+  const namesOnly = entries
+    .slice(0, fitCount)
+    .map((s) => ({ name: s.name, description: '' }));
+  return formatEntries(namesOnly);
+}

package/src/types/index.ts

@@ -2,6 +2,7 @@
 export * from './graph';
 export * from './llm';
 export * from './run';
+export * from './skill';
 export * from './stream';
 export * from './tools';
 export * from './summarize';

package/src/types/run.ts

@@ -11,6 +11,8 @@ import type * as s from '@/types/stream';
 import type * as e from '@/common/enum';
 import type * as g from '@/types/graph';
 import type * as l from '@/types/llm';
+import type { ToolSessionMap } from '@/types/tools';
+import type { HookRegistry } from '@/hooks';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type ZodObjectAny = z.ZodObject<any, any, any, any>;
@@ -112,6 +114,18 @@ export type RunConfig = {
   runId: string;
   graphConfig: LegacyGraphConfig | StandardGraphConfig | MultiAgentGraphConfig;
   customHandlers?: Record<string, g.EventHandler>;
+  /**
+   * Pre-constructed hook registry for this run. Hooks fire at lifecycle
+   * points in `processStream` (RunStart, UserPromptSubmit, Stop,
+   * StopFailure) and around tool calls (PreToolUse, PostToolUse,
+   * PostToolUseFailure, PermissionDenied).
+   *
+   * Pass `undefined` (the default) to skip all hook dispatch. When a
+   * registry is provided, the run attaches it to the `Graph` so internal
+   * nodes can fire hooks too, and clears the session in the `finally`
+   * block to prevent leaks.
+   */
+  hooks?: HookRegistry;
   returnContent?: boolean;
   tokenCounter?: TokenCounter;
   indexTokenCountMap?: Record<string, number>;
@@ -126,6 +140,12 @@ export type RunConfig = {
   calibrationRatio?: number;
   /** Skip post-stream cleanup (clearHeavyState) — useful for tests that inspect graph state after processStream */
   skipCleanup?: boolean;
+  /**
+   * Initial session state to seed the Graph's ToolSessionMap.
+   * Used to carry over code environment sessions from skill file priming
+   * at run start, so ToolNode can inject session_id + files into tool calls.
+   */
+  initialSessions?: ToolSessionMap;
 };
 
 export type ProvidedCallbacks =

package/src/types/skill.ts

@@ -0,0 +1,11 @@
+// src/types/skill.ts
+
+/** 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/types/tools.ts

@@ -2,7 +2,8 @@
 import type { StructuredToolInterface } from '@langchain/core/tools';
 import type { RunnableToolLike } from '@langchain/core/runnables';
 import type { ToolCall } from '@langchain/core/messages/tool';
-import type { ToolErrorData } from './stream';
+import type { HookRegistry } from '@/hooks';
+import type { MessageContentComplex, ToolErrorData } from './stream';
 import { EnvVar } from '@/common';
 
 /** Replacement type for `import type { ToolCall } from '@langchain/core/messages/tool'` in order to have stringified args typed */
@@ -49,6 +50,12 @@ export type ToolNodeOptions = {
   agentId?: string;
   /** Tool names that must be executed directly (via runTool) even in event-driven mode (e.g., graph-managed handoff tools) */
   directToolNames?: Set<string>;
+  /**
+   * Hook registry for PreToolUse/PostToolUse lifecycle hooks.
+   * Only fires for event-driven tool calls (`dispatchToolEvents`). Tools
+   * routed through `directToolNames` bypass hook dispatch entirely.
+   */
+  hookRegistry?: HookRegistry;
   /** Max context tokens for the agent — used to compute tool result truncation limits. */
   maxContextTokens?: number;
   /**
@@ -186,6 +193,26 @@ export type ToolExecuteBatchRequest = {
   reject: (error: Error) => void;
 };
 
+/**
+ * A message injected into graph state by any tool execution handler.
+ * Generic mechanism: any tool returning `injectedMessages` in its `ToolExecuteResult`
+ * will have these appended to state after the ToolMessage for this call.
+ */
+export type InjectedMessage = {
+  /** 'user' for skill body injection, 'system' for context hints.
+   *  Both are converted to HumanMessage at runtime; the original role
+   *  is preserved in additional_kwargs.role. */
+  role: 'user' | 'system';
+  /** Message content: string for simple text, array for complex multi-part content */
+  content: string | MessageContentComplex[];
+  /** When true, the message is framework-internal: not shown in UI, not counted as a user turn */
+  isMeta?: boolean;
+  /** Origin tag for downstream consumers (UI, pruner, compaction) */
+  source?: 'skill' | 'hook' | 'system';
+  /** Only set when source is 'skill', for compaction preservation */
+  skillName?: string;
+};
+
 /** Result for a single tool call in event-driven execution */
 export type ToolExecuteResult = {
   /** Matches ToolCallRequest.id */
@@ -198,6 +225,13 @@ export type ToolExecuteResult = {
   status: 'success' | 'error';
   /** Error message if status is 'error' */
   errorMessage?: string;
+  /**
+   * Messages to inject into graph state after the ToolMessage for this call.
+   * Placed after tool results to respect provider message ordering (tool_call -> tool_result adjacency).
+   * The host's message formatter may merge injected user messages with the preceding tool_result turn.
+   * Generic mechanism: any tool execution handler can use this.
+   */
+  injectedMessages?: InjectedMessage[];
 };
 
 /** Map of tool names to tool definitions */
@@ -318,6 +352,12 @@ export type ProgrammaticExecutionArtifact = {
   files?: FileRefs;
 };
 
+/** Parameters for creating a bash execution tool (same API as CodeExecutor, bash-only) */
+export type BashExecutionToolParams = CodeExecutionToolParams;
+
+/** Parameters for creating a bash programmatic tool calling tool (same API as PTC, bash-only) */
+export type BashProgrammaticToolCallingParams = ProgrammaticToolCallingParams;
+
 /**
  * Initialization parameters for the PTC tool
  */