@agentxjs/core 1.9.10-dev → 2.0.1

package/src/common/logger/LoggerFactoryImpl.ts

@@ -7,8 +7,8 @@
  * - External LoggerFactory can be injected via Runtime
  */
 
-import type { Logger, LoggerFactory, LogContext, LogLevel } from "./types";
 import { ConsoleLogger, type ConsoleLoggerOptions } from "./ConsoleLogger";
+import type { LogContext, Logger, LoggerFactory, LogLevel } from "./types";
 
 // External factory injected via Runtime
 let externalFactory: LoggerFactory | null = null;
@@ -36,22 +36,22 @@ export class LoggerFactoryImpl {
   static getLogger(nameOrClass: string | (new (...args: unknown[]) => unknown)): Logger {
     const name = typeof nameOrClass === "string" ? nameOrClass : nameOrClass.name;
 
-    if (this.loggers.has(name)) {
-      return this.loggers.get(name)!;
+    if (LoggerFactoryImpl.loggers.has(name)) {
+      return LoggerFactoryImpl.loggers.get(name)!;
     }
 
-    const lazyLogger = this.createLazyLogger(name);
-    this.loggers.set(name, lazyLogger);
+    const lazyLogger = LoggerFactoryImpl.createLazyLogger(name);
+    LoggerFactoryImpl.loggers.set(name, lazyLogger);
     return lazyLogger;
   }
 
   static configure(config: LoggerFactoryConfig): void {
-    this.config = { ...this.config, ...config };
+    LoggerFactoryImpl.config = { ...LoggerFactoryImpl.config, ...config };
   }
 
   static reset(): void {
-    this.loggers.clear();
-    this.config = { defaultLevel: "info" };
+    LoggerFactoryImpl.loggers.clear();
+    LoggerFactoryImpl.config = { defaultLevel: "info" };
     externalFactory = null;
     factoryVersion++; // Invalidate all cached real loggers
   }
@@ -63,7 +63,7 @@ export class LoggerFactoryImpl {
     const getRealLogger = (): Logger => {
       // Recreate logger if factory version changed (setLoggerFactory was called)
       if (!realLogger || loggerVersion !== factoryVersion) {
-        realLogger = this.createLogger(name);
+        realLogger = LoggerFactoryImpl.createLogger(name);
         loggerVersion = factoryVersion;
       }
       return realLogger;
@@ -71,7 +71,7 @@ export class LoggerFactoryImpl {
 
     return {
       name,
-      level: this.config.defaultLevel || "info",
+      level: LoggerFactoryImpl.config.defaultLevel || "info",
       debug: (message: string, context?: LogContext) => getRealLogger().debug(message, context),
       info: (message: string, context?: LogContext) => getRealLogger().info(message, context),
       warn: (message: string, context?: LogContext) => getRealLogger().warn(message, context),
@@ -89,13 +89,13 @@ export class LoggerFactoryImpl {
       return externalFactory.getLogger(name);
     }
 
-    if (this.config.defaultImplementation) {
-      return this.config.defaultImplementation(name);
+    if (LoggerFactoryImpl.config.defaultImplementation) {
+      return LoggerFactoryImpl.config.defaultImplementation(name);
     }
 
     return new ConsoleLogger(name, {
-      level: this.config.defaultLevel,
-      ...this.config.consoleOptions,
+      level: LoggerFactoryImpl.config.defaultLevel,
+      ...LoggerFactoryImpl.config.consoleOptions,
     });
   }
 }

package/src/common/logger/index.ts

@@ -16,11 +16,11 @@
  * ```
  */
 
-export type { Logger, LoggerFactory, LogContext, LogLevel } from "./types";
 export { ConsoleLogger, type ConsoleLoggerOptions } from "./ConsoleLogger";
 export {
-  LoggerFactoryImpl,
+  createLogger,
   type LoggerFactoryConfig,
+  LoggerFactoryImpl,
   setLoggerFactory,
-  createLogger,
 } from "./LoggerFactoryImpl";
+export type { LogContext, Logger, LoggerFactory, LogLevel } from "./types";

package/src/container/index.ts

@@ -32,13 +32,12 @@
  * ```
  */
 
+export { ContainerImpl, createContainer, getOrCreateContainer, loadContainer } from "./Container";
 export type {
-  ContainerRecord,
-  ContainerConfig,
-  ContainerRepository,
   Container,
+  ContainerConfig,
   ContainerContext,
   ContainerCreateConfig,
+  ContainerRecord,
+  ContainerRepository,
 } from "./types";
-
-export { ContainerImpl, createContainer, loadContainer, getOrCreateContainer } from "./Container";

package/src/container/types.ts

@@ -16,7 +16,7 @@ import type { SessionRepository } from "../session/types";
 // Re-export from persistence (storage schema)
 // ============================================================================
 
-export type { ContainerRecord, ContainerConfig, ContainerRepository } from "../persistence/types";
+export type { ContainerConfig, ContainerRecord, ContainerRepository } from "../persistence/types";
 
 // ============================================================================
 // Container Interface

package/src/driver/index.ts

@@ -16,27 +16,26 @@
  */
 
 export type {
-  // Configuration
-  McpServerConfig,
-  DriverConfig,
-  DriverState,
-
+  CreateDriver,
   // Core Interface
   Driver,
-  CreateDriver,
-
-  // Stream Events
-  StreamEvent,
-  StopReason,
+  DriverConfig,
+  DriverState,
+  DriverStreamEvent,
+  DriverStreamEventType,
+  ErrorEvent,
+  InputJsonDeltaEvent,
+  InterruptedEvent,
+  // Configuration
+  McpServerConfig,
   MessageStartEvent,
   MessageStopEvent,
+  StopReason,
+  // Stream Events
+  StreamEvent,
   TextDeltaEvent,
+  ToolDefinition,
+  ToolResultEvent,
   ToolUseStartEvent,
-  InputJsonDeltaEvent,
   ToolUseStopEvent,
-  ToolResultEvent,
-  ErrorEvent,
-  InterruptedEvent,
-  DriverStreamEvent,
-  DriverStreamEventType,
 } from "./types";

package/src/driver/types.ts

@@ -31,17 +31,72 @@
  */
 
 import type { UserMessage } from "../agent/types/message";
+import type { Session } from "../session/types";
 
 // ============================================================================
-// MCP Server Configuration
+// Tool Definition
 // ============================================================================
 
 /**
- * MCP Server configuration
+ * ToolDefinition - Defines a tool for LLM tool calling
+ *
+ * Tools are injected into the Driver via DriverConfig.tools.
+ * The Driver passes tool schemas to the LLM and executes handlers
+ * when the LLM requests a tool call.
  *
- * Defines how to launch an MCP server process.
+ * @example
+ * ```typescript
+ * const calculator: ToolDefinition = {
+ *   name: "calculator",
+ *   description: "Evaluates a math expression",
+ *   parameters: {
+ *     type: "object",
+ *     properties: {
+ *       expression: { type: "string", description: "e.g. '123 * 456'" },
+ *     },
+ *     required: ["expression"],
+ *   },
+ *   execute: async (params) => {
+ *     const result = Function(`"use strict"; return (${params.expression})`)();
+ *     return { result: String(result) };
+ *   },
+ * };
+ * ```
  */
-export interface McpServerConfig {
+export interface ToolDefinition {
+  /**
+   * Tool name (unique identifier)
+   */
+  name: string;
+
+  /**
+   * Description of what the tool does (sent to LLM)
+   */
+  description?: string;
+
+  /**
+   * JSON Schema for the tool's input parameters
+   */
+  parameters: {
+    type: "object";
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+
+  /**
+   * Function to execute when the LLM calls this tool
+   */
+  execute: (params: Record<string, unknown>) => Promise<unknown>;
+}
+
+// ============================================================================
+// MCP Server Configuration
+// ============================================================================
+
+/**
+ * Stdio transport — launches a local MCP server as a child process.
+ */
+export interface McpStdioServerConfig {
   /**
    * Command to run the MCP server
    */
@@ -58,6 +113,34 @@ export interface McpServerConfig {
   env?: Record<string, string>;
 }
 
+/**
+ * HTTP Streamable transport — connects to a remote MCP server over HTTP.
+ */
+export interface McpHttpServerConfig {
+  /**
+   * Transport type discriminator
+   */
+  type: "http";
+
+  /**
+   * URL of the remote MCP server
+   */
+  url: string;
+
+  /**
+   * Additional HTTP headers (e.g. Authorization)
+   */
+  headers?: Record<string, string>;
+}
+
+/**
+ * MCP Server configuration.
+ *
+ * - Stdio: `{ command, args?, env? }` — local subprocess
+ * - HTTP:  `{ transport: "http", url, headers? }` — remote server
+ */
+export type McpServerConfig = McpStdioServerConfig | McpHttpServerConfig;
+
 // ============================================================================
 // Stream Event (Lightweight)
 // ============================================================================
@@ -87,81 +170,102 @@ export interface StreamEvent<T extends string = string, D = unknown> {
 }
 
 // Stream Event Types
-export interface MessageStartEvent extends StreamEvent<
-  "message_start",
-  {
-    messageId: string;
-    model: string;
-  }
-> {}
-
-export interface MessageStopEvent extends StreamEvent<
-  "message_stop",
-  {
-    stopReason: StopReason;
-  }
-> {}
-
-export interface TextDeltaEvent extends StreamEvent<
-  "text_delta",
-  {
-    text: string;
-  }
-> {}
-
-export interface ToolUseStartEvent extends StreamEvent<
-  "tool_use_start",
-  {
-    toolCallId: string;
-    toolName: string;
-  }
-> {}
-
-export interface InputJsonDeltaEvent extends StreamEvent<
-  "input_json_delta",
-  {
-    partialJson: string;
-  }
-> {}
-
-export interface ToolUseStopEvent extends StreamEvent<
-  "tool_use_stop",
-  {
-    toolCallId: string;
-    toolName: string;
-    input: Record<string, unknown>;
-  }
-> {}
-
-export interface ToolResultEvent extends StreamEvent<
-  "tool_result",
-  {
-    toolCallId: string;
-    result: unknown;
-    isError?: boolean;
-  }
-> {}
-
-export interface ErrorEvent extends StreamEvent<
-  "error",
-  {
-    message: string;
-    errorCode?: string;
-  }
-> {}
-
-export interface InterruptedEvent extends StreamEvent<
-  "interrupted",
-  {
-    reason: "user" | "timeout" | "error";
-  }
-> {}
+export interface MessageStartEvent
+  extends StreamEvent<
+    "message_start",
+    {
+      messageId: string;
+      model: string;
+    }
+  > {}
+
+export interface MessageStopEvent
+  extends StreamEvent<
+    "message_stop",
+    {
+      stopReason: StopReason;
+    }
+  > {}
+
+export interface TextDeltaEvent
+  extends StreamEvent<
+    "text_delta",
+    {
+      text: string;
+    }
+  > {}
+
+export interface ToolUseStartEvent
+  extends StreamEvent<
+    "tool_use_start",
+    {
+      toolCallId: string;
+      toolName: string;
+    }
+  > {}
+
+export interface InputJsonDeltaEvent
+  extends StreamEvent<
+    "input_json_delta",
+    {
+      partialJson: string;
+    }
+  > {}
+
+export interface ToolUseStopEvent
+  extends StreamEvent<
+    "tool_use_stop",
+    {
+      toolCallId: string;
+      toolName: string;
+      input: Record<string, unknown>;
+    }
+  > {}
+
+export interface ToolResultEvent
+  extends StreamEvent<
+    "tool_result",
+    {
+      toolCallId: string;
+      result: unknown;
+      isError?: boolean;
+    }
+  > {}
+
+export interface ErrorEvent
+  extends StreamEvent<
+    "error",
+    {
+      message: string;
+      errorCode?: string;
+    }
+  > {}
+
+export interface MessageDeltaEvent
+  extends StreamEvent<
+    "message_delta",
+    {
+      usage?: {
+        inputTokens: number;
+        outputTokens: number;
+      };
+    }
+  > {}
+
+export interface InterruptedEvent
+  extends StreamEvent<
+    "interrupted",
+    {
+      reason: "user" | "timeout" | "error";
+    }
+  > {}
 
 /**
  * DriverStreamEvent - Union of all stream events from Driver
  */
 export type DriverStreamEvent =
   | MessageStartEvent
+  | MessageDeltaEvent
   | MessageStopEvent
   | TextDeltaEvent
   | ToolUseStartEvent
@@ -252,8 +356,32 @@ export interface DriverConfig<TOptions = Record<string, unknown>> {
    */
   mcpServers?: Record<string, McpServerConfig>;
 
+  /**
+   * Tool definitions for LLM tool calling
+   *
+   * Tools are passed to the LLM provider and executed when the LLM
+   * requests a tool call. Each tool includes its JSON Schema (sent to
+   * the LLM) and an execute function (called at runtime).
+   */
+  tools?: ToolDefinition[];
+
   // === Session Configuration ===
 
+  /**
+   * Session for message history access
+   *
+   * Stateless drivers (like MonoDriver) use this to read conversation history.
+   * Stateful drivers (like ClaudeDriver) may ignore this as they manage
+   * history internally via SDK.
+   *
+   * @example
+   * ```typescript
+   * // MonoDriver reads history from Session
+   * const history = await config.session?.getMessages();
+   * ```
+   */
+  session?: Session;
+
   /**
    * Session ID to resume (for conversation continuity)
    *

package/src/event/EventBus.ts

@@ -5,22 +5,22 @@
  * Uses RxJS Subject for reactive event distribution.
  */
 
+import { createLogger } from "commonxjs/logger";
+import { Subject } from "rxjs";
 import type {
-  EventBus,
-  EventProducer,
-  EventConsumer,
-  Unsubscribe,
-  BusEventHandler,
-  SubscribeOptions,
   BusEvent,
+  BusEventHandler,
   CommandEventMap,
+  CommandRequestResponseMap,
   CommandRequestType,
-  ResponseEventFor,
+  EventBus,
+  EventConsumer,
+  EventProducer,
   RequestDataFor,
-  CommandRequestResponseMap,
+  ResponseEventFor,
+  SubscribeOptions,
+  Unsubscribe,
 } from "./types";
-import { Subject } from "rxjs";
-import { createLogger } from "commonxjs/logger";
 
 const logger = createLogger("event/EventBus");
 

package/src/event/__tests__/EventBus.test.ts

@@ -2,8 +2,8 @@
  * EventBus.test.ts - Unit tests for EventBus implementation
  */
 
-import { describe, it, expect, beforeEach } from "bun:test";
-import { EventBus } from "../EventBus";
+import { beforeEach, describe, expect, it } from "bun:test";
+import { EventBusImpl as EventBus } from "../EventBus";
 import type { BusEvent } from "../types";
 
 // Test event factory

package/src/event/index.ts

@@ -39,8 +39,7 @@
  * ```
  */
 
-// Type definitions from types directory
-export * from "./types";
-
 // Implementation
 export { EventBusImpl } from "./EventBus";
+// Type definitions from types directory
+export * from "./types";