@librechat/agents-types 3.0.36 → 3.0.40

package/graph.ts

@@ -18,7 +18,7 @@ import type {
 import type { RunnableConfig, Runnable } from '@langchain/core/runnables';
 import type { ChatGenerationChunk } from '@langchain/core/outputs';
 import type { GoogleAIToolType } from '@langchain/google-common';
-import type { ToolMap, ToolEndEvent, GenericTool } from '@/types/tools';
+import type { ToolMap, ToolEndEvent, GenericTool, LCTool } from '@/types/tools';
 import type { Providers, Callback, GraphNodeKeys } from '@/common';
 import type { StandardGraph, MultiAgentGraph } from '@/graphs';
 import type { ClientOptions } from '@/types/llm';
@@ -369,4 +369,10 @@ export interface AgentInputs {
   reasoningKey?: 'reasoning_content' | 'reasoning';
   /** Format content blocks as strings (for legacy compatibility i.e. Ollama/Azure Serverless) */
   useLegacyContent?: boolean;
+  /**
+   * Tool definitions for all tools, including deferred and programmatic.
+   * Used for tool search and programmatic tool calling.
+   * Maps tool name to LCTool definition.
+   */
+  toolRegistry?: Map<string, LCTool>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents-types",
-  "version": "3.0.36",
+  "version": "3.0.40",
   "description": "Type definitions for @librechat/agents",
   "types": "index.d.ts",
   "scripts": {

package/tools.ts

@@ -35,6 +35,12 @@ export type ToolNodeOptions = {
     data: ToolErrorData,
     metadata?: Record<string, unknown>
   ) => Promise<void>;
+  /** Tools available for programmatic code execution (allowed_callers includes 'code_execution') */
+  programmaticToolMap?: ToolMap;
+  /** Tool definitions for programmatic code execution (sent to Code API for stub generation) */
+  programmaticToolDefs?: LCTool[];
+  /** Tool registry for tool search (deferred tool definitions) */
+  toolRegistry?: LCToolRegistry;
 };
 
 export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
@@ -78,3 +84,163 @@ export type ExecuteResult = {
   stderr: string;
   files?: FileRefs;
 };
+
+/** JSON Schema type definition for tool parameters */
+export type JsonSchemaType = {
+  type:
+    | 'string'
+    | 'number'
+    | 'integer'
+    | 'float'
+    | 'boolean'
+    | 'array'
+    | 'object';
+  enum?: string[];
+  items?: JsonSchemaType;
+  properties?: Record<string, JsonSchemaType>;
+  required?: string[];
+  description?: string;
+  additionalProperties?: boolean | JsonSchemaType;
+};
+
+/**
+ * Specifies which contexts can invoke a tool (inspired by Anthropic's allowed_callers)
+ * - 'direct': Only callable directly by the LLM (default if omitted)
+ * - 'code_execution': Only callable from within programmatic code execution
+ */
+export type AllowedCaller = 'direct' | 'code_execution';
+
+/** Tool definition with optional deferred loading and caller restrictions */
+export type LCTool = {
+  name: string;
+  description?: string;
+  parameters?: JsonSchemaType;
+  /** When true, tool is not loaded into context initially (for tool search) */
+  defer_loading?: boolean;
+  /**
+   * Which contexts can invoke this tool.
+   * Default: ['direct'] (only callable directly by LLM)
+   * Options: 'direct', 'code_execution'
+   */
+  allowed_callers?: AllowedCaller[];
+};
+
+/** Map of tool names to tool definitions */
+export type LCToolRegistry = Map<string, LCTool>;
+
+/** Parameters for creating a Tool Search Regex tool */
+export type ToolSearchRegexParams = {
+  apiKey?: string;
+  toolRegistry?: LCToolRegistry;
+  onlyDeferred?: boolean;
+  baseUrl?: string;
+  [key: string]: unknown;
+};
+
+/** Simplified tool metadata for search purposes */
+export type ToolMetadata = {
+  name: string;
+  description: string;
+  parameters?: JsonSchemaType;
+};
+
+/** Individual search result for a matching tool */
+export type ToolSearchResult = {
+  tool_name: string;
+  match_score: number;
+  matched_field: string;
+  snippet: string;
+};
+
+/** Response from the tool search operation */
+export type ToolSearchResponse = {
+  tool_references: ToolSearchResult[];
+  total_tools_searched: number;
+  pattern_used: string;
+};
+
+/** Artifact returned alongside the formatted search results */
+export type ToolSearchArtifact = {
+  tool_references: ToolSearchResult[];
+  metadata: {
+    total_searched: number;
+    pattern: string;
+    error?: string;
+  };
+};
+
+// ============================================================================
+// Programmatic Tool Calling Types
+// ============================================================================
+
+/**
+ * Tool call requested by the Code API during programmatic execution
+ */
+export type PTCToolCall = {
+  /** Unique ID like "call_001" */
+  id: string;
+  /** Tool name */
+  name: string;
+  /** Input parameters */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  input: Record<string, any>;
+};
+
+/**
+ * Tool result sent back to the Code API
+ */
+export type PTCToolResult = {
+  /** Matches PTCToolCall.id */
+  call_id: string;
+  /** Tool execution result (any JSON-serializable value) */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  result: any;
+  /** Whether tool execution failed */
+  is_error: boolean;
+  /** Error details if is_error=true */
+  error_message?: string;
+};
+
+/**
+ * Response from the Code API for programmatic execution
+ */
+export type ProgrammaticExecutionResponse = {
+  status: 'tool_call_required' | 'completed' | 'error' | unknown;
+  session_id?: string;
+
+  /** Present when status='tool_call_required' */
+  continuation_token?: string;
+  tool_calls?: PTCToolCall[];
+
+  /** Present when status='completed' */
+  stdout?: string;
+  stderr?: string;
+  files?: FileRefs;
+
+  /** Present when status='error' */
+  error?: string;
+};
+
+/**
+ * Artifact returned by the PTC tool
+ */
+export type ProgrammaticExecutionArtifact = {
+  session_id?: string;
+  files?: FileRefs;
+};
+
+/**
+ * Initialization parameters for the PTC tool
+ */
+export type ProgrammaticToolCallingParams = {
+  /** Code API key (or use CODE_API_KEY env var) */
+  apiKey?: string;
+  /** Code API base URL (or use CODE_BASEURL env var) */
+  baseUrl?: string;
+  /** Safety limit for round-trips (default: 20) */
+  maxRoundTrips?: number;
+  /** HTTP proxy URL */
+  proxy?: string;
+  /** Environment variable key for API key */
+  [key: string]: unknown;
+};