illuma-agents 1.0.49 → 1.0.51

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

@@ -0,0 +1,12 @@
+import { type StructuredToolInterface } from '@langchain/core/tools';
+import type { LCTool } from '@/types';
+/**
+ * Creates a schema-only tool for LLM binding in event-driven mode.
+ * These tools have valid schemas for the LLM to understand but should
+ * never be invoked directly - ToolNode handles execution via events.
+ */
+export declare function createSchemaOnlyTool(definition: LCTool): StructuredToolInterface;
+/**
+ * Creates schema-only tools for all definitions in an array.
+ */
+export declare function createSchemaOnlyTools(definitions: LCTool[]): StructuredToolInterface[];

package/dist/types/tools/search/schema.d.ts

@@ -1,4 +1,3 @@
-import { z } from 'zod';
 export declare enum DATE_RANGE {
     PAST_HOUR = "h",
     PAST_24_HOURS = "d",
@@ -8,9 +7,28 @@ export declare enum DATE_RANGE {
 }
 export declare const DEFAULT_QUERY_DESCRIPTION: string;
 export declare const DEFAULT_COUNTRY_DESCRIPTION: string;
-export declare const querySchema: z.ZodString;
-export declare const dateSchema: z.ZodOptional<z.ZodNativeEnum<typeof DATE_RANGE>>;
-export declare const countrySchema: z.ZodOptional<z.ZodString>;
-export declare const imagesSchema: z.ZodOptional<z.ZodBoolean>;
-export declare const videosSchema: z.ZodOptional<z.ZodBoolean>;
-export declare const newsSchema: z.ZodOptional<z.ZodBoolean>;
+export declare const querySchema: {
+    readonly type: "string";
+    readonly description: string;
+};
+export declare const dateSchema: {
+    readonly type: "string";
+    readonly enum: DATE_RANGE[];
+    readonly description: "Date range for search results.";
+};
+export declare const countrySchema: {
+    readonly type: "string";
+    readonly description: string;
+};
+export declare const imagesSchema: {
+    readonly type: "boolean";
+    readonly description: "Whether to also run an image search.";
+};
+export declare const videosSchema: {
+    readonly type: "boolean";
+    readonly description: "Whether to also run a video search.";
+};
+export declare const newsSchema: {
+    readonly type: "boolean";
+    readonly description: "Whether to also run a news search.";
+};

package/dist/types/tools/search/tool.d.ts

@@ -1,54 +1,3 @@
-import { z } from 'zod';
 import { DynamicStructuredTool } from '@langchain/core/tools';
 import type * as t from './types';
-import { DATE_RANGE } from './schema';
-/**
- * Creates a search tool with a schema that dynamically includes the country field
- * only when the searchProvider is 'serper'.
- *
- * Supports multiple scraper providers:
- * - Firecrawl (default): Full-featured web scraping with multiple formats
- * - Serper: Lightweight scraping using Serper's scrape API
- *
- * @example
- * ```typescript
- * // Using Firecrawl scraper (default)
- * const searchTool = createSearchTool({
- *   searchProvider: 'serper',
- *   scraperProvider: 'firecrawl',
- *   firecrawlApiKey: 'your-firecrawl-key'
- * });
- *
- * // Using Serper scraper
- * const searchTool = createSearchTool({
- *   searchProvider: 'serper',
- *   scraperProvider: 'serper',
- *   serperApiKey: 'your-serper-key'
- * });
- * ```
- *
- * @param config - The search tool configuration
- * @returns A DynamicStructuredTool with a schema that depends on the searchProvider
- */
-export declare const createSearchTool: (config?: t.SearchToolConfig) => DynamicStructuredTool<z.ZodObject<{
-    query: z.ZodString;
-    date: z.ZodOptional<z.ZodNativeEnum<typeof DATE_RANGE>>;
-    country?: z.ZodOptional<z.ZodString>;
-    images: z.ZodOptional<z.ZodBoolean>;
-    videos: z.ZodOptional<z.ZodBoolean>;
-    news: z.ZodOptional<z.ZodBoolean>;
-}, "strip", z.ZodTypeAny, {
-    query: string;
-    videos?: boolean | undefined;
-    images?: boolean | undefined;
-    news?: boolean | undefined;
-    date?: DATE_RANGE | undefined;
-    country?: unknown;
-}, {
-    query: string;
-    videos?: boolean | undefined;
-    images?: boolean | undefined;
-    news?: boolean | undefined;
-    date?: DATE_RANGE | undefined;
-    country?: unknown;
-}>>;
+export declare const createSearchTool: (config?: t.SearchToolConfig) => DynamicStructuredTool;

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

@@ -1,4 +1,3 @@
-import { z } from 'zod';
 import type { Logger as WinstonLogger } from 'winston';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseReranker } from './rerankers';
@@ -569,25 +568,8 @@ export type ProcessSourcesFields = {
     /** Skip scraping if content was already extracted directly (e.g., direct URL extraction) */
     skipScraping?: boolean;
 };
-export type SearchToolSchema = z.ZodObject<{
-    query: z.ZodString;
-    date: z.ZodOptional<z.ZodNativeEnum<typeof DATE_RANGE>>;
-    country?: z.ZodOptional<z.ZodString>;
-    images: z.ZodOptional<z.ZodBoolean>;
-    videos: z.ZodOptional<z.ZodBoolean>;
-    news: z.ZodOptional<z.ZodBoolean>;
-}, 'strip', z.ZodTypeAny, {
-    query: string;
-    date?: DATE_RANGE;
-    country?: unknown;
-    images?: boolean;
-    videos?: boolean;
-    news?: boolean;
-}, {
-    query: string;
-    date?: DATE_RANGE;
-    country?: unknown;
-    images?: boolean;
-    videos?: boolean;
-    news?: boolean;
-}>;
+export interface SearchToolSchema {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required: string[];
+}

package/dist/types/types/graph.d.ts

@@ -297,6 +297,24 @@ export interface StructuredOutputConfig {
      */
     includeRaw?: boolean;
 }
+/**
+ * Database/API structured output format (snake_case with enabled flag).
+ * This matches the format stored in MongoDB and sent from frontends.
+ */
+export interface StructuredOutputInput {
+    /** Whether structured output is enabled */
+    enabled?: boolean;
+    /** JSON Schema defining the expected response structure */
+    schema?: Record<string, unknown>;
+    /** Name identifier for the structured output */
+    name?: string;
+    /** Description of what the structured output represents */
+    description?: string;
+    /** Mode for structured output: 'tool' | 'provider' | 'auto' */
+    mode?: StructuredOutputMode;
+    /** Whether to enforce strict schema validation */
+    strict?: boolean;
+}
 export interface AgentInputs {
     agentId: string;
     /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */
@@ -327,9 +345,22 @@ export interface AgentInputs {
      */
     dynamicContext?: string;
     /**
-     * Structured output configuration.
+     * Structured output configuration (camelCase).
      * When set, disables streaming and returns a validated JSON response
      * conforming to the specified schema.
      */
     structuredOutput?: StructuredOutputConfig;
+    /**
+     * Structured output configuration (snake_case - database/API format).
+     * Alternative to structuredOutput for compatibility with MongoDB/frontend.
+     * Uses an `enabled` flag to control activation.
+     * @deprecated Use structuredOutput instead when possible
+     */
+    structured_output?: StructuredOutputInput;
+    /**
+     * Serializable tool definitions for event-driven execution.
+     * When provided, ToolNode operates in event-driven mode, dispatching
+     * ON_TOOL_EXECUTE events instead of invoking tools directly.
+     */
+    toolDefinitions?: LCTool[];
 }

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

@@ -31,6 +31,12 @@ export type ToolNodeOptions = {
     toolRegistry?: LCToolRegistry;
     /** Reference to Graph's sessions map for automatic session injection */
     sessions?: ToolSessionMap;
+    /** When true, dispatches ON_TOOL_EXECUTE events instead of invoking tools directly */
+    eventDrivenMode?: boolean;
+    /** Tool definitions for event-driven mode (used for context, not invocation) */
+    toolDefinitions?: Map<string, LCTool>;
+    /** Agent ID for event-driven mode (used to identify which agent's context to use) */
+    agentId?: string;
 };
 export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
 export type ToolEndEvent = {
@@ -96,6 +102,55 @@ export type LCTool = {
      * Options: 'direct', 'code_execution'
      */
     allowed_callers?: AllowedCaller[];
+    /** Response format for the tool output */
+    responseFormat?: 'content' | 'content_and_artifact';
+    /** Server name for MCP tools */
+    serverName?: string;
+    /** Tool type classification */
+    toolType?: 'builtin' | 'mcp' | 'action';
+};
+/** Single tool call within a batch request for event-driven execution */
+export type ToolCallRequest = {
+    /** Tool call ID from the LLM */
+    id: string;
+    /** Tool name */
+    name: string;
+    /** Tool arguments */
+    args: Record<string, unknown>;
+    /** Step ID for tracking */
+    stepId?: string;
+    /** Usage turn count for this tool */
+    turn?: number;
+};
+/** Batch request containing ALL tool calls for a graph step */
+export type ToolExecuteBatchRequest = {
+    /** All tool calls from the AIMessage */
+    toolCalls: ToolCallRequest[];
+    /** User ID for context */
+    userId?: string;
+    /** Agent ID for context */
+    agentId?: string;
+    /** Runtime configurable from RunnableConfig (includes user, userMCPAuthMap, etc.) */
+    configurable?: Record<string, unknown>;
+    /** Runtime metadata from RunnableConfig (includes thread_id, run_id, provider, etc.) */
+    metadata?: Record<string, unknown>;
+    /** Promise resolver - handler calls this with ALL results */
+    resolve: (results: ToolExecuteResult[]) => void;
+    /** Promise rejector - handler calls this on fatal error */
+    reject: (error: Error) => void;
+};
+/** Result for a single tool call in event-driven execution */
+export type ToolExecuteResult = {
+    /** Matches ToolCallRequest.id */
+    toolCallId: string;
+    /** Tool output content */
+    content: string | unknown[];
+    /** Optional artifact (for content_and_artifact format) */
+    artifact?: unknown;
+    /** Execution status */
+    status: 'success' | 'error';
+    /** Error message if status is 'error' */
+    errorMessage?: string;
 };
 /** Map of tool names to tool definitions */
 export type LCToolRegistry = Map<string, LCTool>;

package/dist/types/utils/index.d.ts

@@ -6,3 +6,4 @@ export * from './run';
 export * from './tokens';
 export * from './toonFormat';
 export * from './contextAnalytics';
+export * from './schema';

package/dist/types/utils/schema.d.ts

@@ -0,0 +1,8 @@
+import type { ZodTypeAny } from 'zod';
+/** Checks if a schema is a Zod schema by looking for the _def property */
+export declare function isZodSchema(schema: unknown): schema is ZodTypeAny;
+/**
+ * Converts a schema to JSON schema format.
+ * Handles both Zod schemas (converts) and JSON schemas (passthrough).
+ */
+export declare function toJsonSchema(schema: unknown, name?: string, description?: string): Record<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "illuma-agents",
-  "version": "1.0.49",
+  "version": "1.0.51",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -18,7 +18,7 @@
     "url": "https://github.com/codevakure/agents"
   },
   "author": "Illuma Team",
-  "license": "MIT",
+  "license": "UNLICENSED",
   "packageManager": "npm@10.5.2",
   "engines": {
     "node": ">=14.0.0"
@@ -26,7 +26,6 @@
   "files": [
     "dist",
     "src",
-    "LICENSE",
     "README.md"
   ],
   "scripts": {
@@ -118,7 +117,6 @@
     "@langchain/openai": "0.5.18",
     "@langchain/textsplitters": "^0.1.0",
     "@langchain/xai": "^0.0.3",
-    "deepagents": "^1.5.1",
     "@langfuse/langchain": "^4.3.0",
     "@langfuse/otel": "^4.3.0",
     "@langfuse/tracing": "^4.3.0",

package/src/agents/AgentContext.test.ts

@@ -68,6 +68,105 @@ describe('AgentContext', () => {
         const context = AgentContext.fromConfig(config);
         expect(context.isStructuredOutputMode).toBe(true);
       });
+
+      // Snake_case structured_output tests (database/API format)
+      it('should return true when structured_output (snake_case) is enabled with schema', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structured_output: {
+            enabled: true,
+            schema: {
+              type: 'object',
+              properties: {
+                result: { type: 'string' },
+              },
+            },
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        expect(context.isStructuredOutputMode).toBe(true);
+      });
+
+      it('should return false when structured_output is not enabled', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structured_output: {
+            enabled: false,
+            schema: {
+              type: 'object',
+              properties: {
+                result: { type: 'string' },
+              },
+            },
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        expect(context.isStructuredOutputMode).toBe(false);
+      });
+
+      it('should return false when structured_output has no schema', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structured_output: {
+            enabled: true,
+            // No schema
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        expect(context.isStructuredOutputMode).toBe(false);
+      });
+
+      it('should prefer structuredOutput (camelCase) over structured_output (snake_case)', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: {
+              type: 'object',
+              properties: { camel: { type: 'string' } },
+            },
+            name: 'CamelSchema',
+          },
+          structured_output: {
+            enabled: true,
+            schema: {
+              type: 'object',
+              properties: { snake: { type: 'string' } },
+            },
+            name: 'SnakeSchema',
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        expect(context.isStructuredOutputMode).toBe(true);
+        expect(context.structuredOutput?.name).toBe('CamelSchema');
+      });
+
+      it('should convert structured_output properties correctly', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structured_output: {
+            enabled: true,
+            schema: {
+              type: 'object',
+              properties: { data: { type: 'string' } },
+            },
+            name: 'TestResponse',
+            description: 'A test response',
+            mode: 'provider',
+            strict: true,
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        expect(context.structuredOutput).toEqual({
+          schema: {
+            type: 'object',
+            properties: { data: { type: 'string' } },
+          },
+          name: 'TestResponse',
+          description: 'A test response',
+          mode: 'provider',
+          strict: true,
+        });
+      });
     });
 
     describe('getStructuredOutputSchema', () => {

package/src/agents/AgentContext.ts

@@ -1,6 +1,5 @@
 /* eslint-disable no-console */
 // src/agents/AgentContext.ts
-import { zodToJsonSchema } from 'zod-to-json-schema';
 import { SystemMessage } from '@langchain/core/messages';
 import { RunnableLambda } from '@langchain/core/runnables';
 import type {
@@ -11,7 +10,9 @@ import type {
 import type { RunnableConfig, Runnable } from '@langchain/core/runnables';
 import type * as t from '@/types';
 import type { createPruneMessages } from '@/messages';
+import { createSchemaOnlyTools } from '@/tools/schema';
 import { ContentTypes, Providers } from '@/common';
+import { toJsonSchema } from '@/utils/schema';
 
 /**
  * Encapsulates agent-specific state that can vary between agents in a multi-agent system
@@ -34,6 +35,7 @@ export class AgentContext {
       toolMap,
       toolEnd,
       toolRegistry,
+      toolDefinitions,
       instructions,
       additional_instructions,
       streamBuffer,
@@ -41,9 +43,27 @@ export class AgentContext {
       reasoningKey,
       useLegacyContent,
       dynamicContext,
-      structuredOutput,
+      structuredOutput: structuredOutputCamel,
+      // eslint-disable-next-line @typescript-eslint/naming-convention
+      structured_output: structuredOutputSnake,
     } = agentConfig;
 
+    // Normalize structured output: support both camelCase and snake_case inputs
+    // Priority: structuredOutput (camelCase) > structured_output (snake_case with enabled check)
+    let structuredOutput: t.StructuredOutputConfig | undefined;
+    if (structuredOutputCamel) {
+      structuredOutput = structuredOutputCamel;
+    } else if (structuredOutputSnake?.enabled && structuredOutputSnake.schema) {
+      // Convert snake_case input to StructuredOutputConfig
+      structuredOutput = {
+        schema: structuredOutputSnake.schema,
+        name: structuredOutputSnake.name,
+        description: structuredOutputSnake.description,
+        mode: structuredOutputSnake.mode,
+        strict: structuredOutputSnake.strict,
+      };
+    }
+
     const agentContext = new AgentContext({
       agentId,
       name: name ?? agentId,
@@ -54,6 +74,7 @@ export class AgentContext {
       tools,
       toolMap,
       toolRegistry,
+      toolDefinitions,
       instructions,
       additionalInstructions: additional_instructions,
       reasoningKey,
@@ -122,6 +143,11 @@ export class AgentContext {
    * Used for tool search and programmatic tool calling.
    */
   toolRegistry?: t.LCToolRegistry;
+  /**
+   * Serializable tool definitions for event-driven execution.
+   * When provided, ToolNode operates in event-driven mode.
+   */
+  toolDefinitions?: t.LCTool[];
   /** Set of tool names discovered via tool search (to be loaded) */
   discoveredToolNames: Set<string> = new Set();
   /** Instructions for this agent */
@@ -207,6 +233,7 @@ export class AgentContext {
     tools,
     toolMap,
     toolRegistry,
+    toolDefinitions,
     instructions,
     additionalInstructions,
     dynamicContext,
@@ -226,6 +253,7 @@ export class AgentContext {
     tools?: t.GraphTools;
     toolMap?: t.ToolMap;
     toolRegistry?: t.LCToolRegistry;
+    toolDefinitions?: t.LCTool[];
     instructions?: string;
     additionalInstructions?: string;
     dynamicContext?: string;
@@ -245,6 +273,7 @@ export class AgentContext {
     this.tools = tools;
     this.toolMap = toolMap;
     this.toolRegistry = toolRegistry;
+    this.toolDefinitions = toolDefinitions;
     this.instructions = instructions;
     this.additionalInstructions = additionalInstructions;
     this.dynamicContext = dynamicContext;
@@ -600,15 +629,10 @@ export class AgentContext {
           genericTool.schema != null &&
           typeof genericTool.schema === 'object'
         ) {
-          const schema = genericTool.schema as {
-            describe: (desc: string) => unknown;
-          };
-          const describedSchema = schema.describe(
-            (genericTool.description as string) || ''
-          );
-          const jsonSchema = zodToJsonSchema(
-            describedSchema as Parameters<typeof zodToJsonSchema>[0],
-            (genericTool.name as string) || ''
+          const jsonSchema = toJsonSchema(
+            genericTool.schema,
+            (genericTool.name as string | undefined) ?? '',
+            (genericTool.description as string | undefined) ?? ''
           );
           const toolName = (genericTool.name as string) || 'unknown';
           const tokens = tokenCounter(
@@ -777,40 +801,70 @@ export class AgentContext {
 
   /**
    * Gets tools that should be bound to the LLM.
-   * Includes:
+   * In event-driven mode (toolDefinitions present, tools empty), creates schema-only tools.
+   * Otherwise filters tool instances based on:
    * 1. Non-deferred tools with allowed_callers: ['direct']
    * 2. Discovered tools (from tool search)
    * @returns Array of tools to bind to model
    */
   getToolsForBinding(): t.GraphTools | undefined {
+    /** Event-driven mode: create schema-only tools from definitions */
+    if (this.toolDefinitions && this.toolDefinitions.length > 0) {
+      return this.getEventDrivenToolsForBinding();
+    }
+
+    /** Traditional mode: filter actual tool instances */
     if (!this.tools || !this.toolRegistry) {
       return this.tools;
     }
 
-    const toolsToInclude = this.tools.filter((tool) => {
+    return this.filterToolsForBinding(this.tools);
+  }
+
+  /** Creates schema-only tools from toolDefinitions for event-driven mode */
+  private getEventDrivenToolsForBinding(): t.GraphTools {
+    if (!this.toolDefinitions) {
+      return [];
+    }
+
+    const defsToInclude = this.toolDefinitions.filter((def) => {
+      const allowedCallers = def.allowed_callers ?? ['direct'];
+      if (!allowedCallers.includes('direct')) {
+        return false;
+      }
+      if (
+        def.defer_loading === true &&
+        !this.discoveredToolNames.has(def.name)
+      ) {
+        return false;
+      }
+      return true;
+    });
+
+    return createSchemaOnlyTools(defsToInclude) as t.GraphTools;
+  }
+
+  /** Filters tool instances for binding based on registry config */
+  private filterToolsForBinding(tools: t.GraphTools): t.GraphTools {
+    return tools.filter((tool) => {
       if (!('name' in tool)) {
-        return true; // No name, include by default
+        return true;
       }
 
       const toolDef = this.toolRegistry?.get(tool.name);
       if (!toolDef) {
-        return true; // Not in registry, include by default
+        return true;
       }
 
-      // Check if discovered (overrides defer_loading)
       if (this.discoveredToolNames.has(tool.name)) {
-        // Discovered tools must still have allowed_callers: ['direct']
         const allowedCallers = toolDef.allowed_callers ?? ['direct'];
         return allowedCallers.includes('direct');
       }
 
-      // Not discovered: must be direct-callable AND not deferred
       const allowedCallers = toolDef.allowed_callers ?? ['direct'];
       return (
         allowedCallers.includes('direct') && toolDef.defer_loading !== true
       );
     });
-
-    return toolsToInclude;
   }
 }

package/src/common/enum.ts

@@ -23,6 +23,8 @@ export enum GraphEvents {
   ON_CONTEXT_ANALYTICS = 'on_context_analytics',
   /** [Custom] Structured output event - emitted when agent returns structured JSON */
   ON_STRUCTURED_OUTPUT = 'on_structured_output',
+  /** [Custom] Request to execute tools - dispatched by ToolNode, handled by host */
+  ON_TOOL_EXECUTE = 'on_tool_execute',
 
   /* Official Events */