@agentxjs/core 1.9.10-dev → 2.0.1

package/src/agent/index.ts

@@ -30,8 +30,8 @@
 // Core API
 // ============================================================================
 
-export { createAgent } from "./createAgent";
 export { AgentStateMachine } from "./AgentStateMachine";
+export { createAgent } from "./createAgent";
 export type { AgentEngine, CreateAgentOptions } from "./types";
 
 // ============================================================================
@@ -44,63 +44,61 @@ export * from "./types";
 // Engine (Stateless)
 // ============================================================================
 
-// MealyMachine
-export { MealyMachine, createMealyMachine } from "./engine/MealyMachine";
-
 // AgentProcessor (for advanced use cases)
 export {
-  agentProcessor,
-  createInitialAgentEngineState,
   type AgentEngineState,
   type AgentProcessorInput,
   type AgentProcessorOutput,
+  agentProcessor,
+  createInitialAgentEngineState,
 } from "./engine/AgentProcessor";
-
 // Internal Processors (for advanced use cases)
 export {
-  // MessageAssembler
-  messageAssemblerProcessor,
-  messageAssemblerProcessorDef,
+  createInitialMessageAssemblerState,
+  createInitialStateEventProcessorContext,
+  createInitialTurnTrackerState,
   type MessageAssemblerInput,
   type MessageAssemblerOutput,
   type MessageAssemblerState,
+  // MessageAssembler
+  messageAssemblerProcessor,
+  messageAssemblerProcessorDef,
   type PendingContent,
-  createInitialMessageAssemblerState,
+  type PendingTurn,
+  type StateEventProcessorContext,
+  type StateEventProcessorInput,
+  type StateEventProcessorOutput,
   // StateEventProcessor
   stateEventProcessor,
   stateEventProcessorDef,
-  type StateEventProcessorInput,
-  type StateEventProcessorOutput,
-  type StateEventProcessorContext,
-  createInitialStateEventProcessorContext,
-  // TurnTracker
-  turnTrackerProcessor,
-  turnTrackerProcessorDef,
   type TurnTrackerInput,
   type TurnTrackerOutput,
   type TurnTrackerState,
-  type PendingTurn,
-  createInitialTurnTrackerState,
+  // TurnTracker
+  turnTrackerProcessor,
+  turnTrackerProcessorDef,
 } from "./engine/internal";
+// MealyMachine
+export { createMealyMachine, MealyMachine } from "./engine/MealyMachine";
 
 // Mealy Machine Core (for building custom processors)
 export {
-  // Core types
-  type Source,
-  type SourceDefinition,
+  chainProcessors,
+  combineInitialStates,
+  // Combinators
+  combineProcessors,
+  filterProcessor,
+  identityProcessor,
+  MemoryStore,
+  mapOutput,
   type Processor,
-  type ProcessorResult,
   type ProcessorDefinition,
+  type ProcessorResult,
   type Sink,
   type SinkDefinition,
+  // Core types
+  type Source,
+  type SourceDefinition,
   type Store,
-  MemoryStore,
-  // Combinators
-  combineProcessors,
-  combineInitialStates,
-  chainProcessors,
-  filterProcessor,
-  mapOutput,
   withLogging,
-  identityProcessor,
 } from "./engine/mealy";

package/src/agent/types/engine.ts

@@ -13,14 +13,14 @@
  * @packageDocumentation
  */
 
-import type { UserMessage } from "./message";
 import type {
-  AgentState,
   AgentOutput,
+  AgentOutputCallback,
+  AgentState,
   StreamEvent,
   Unsubscribe,
-  AgentOutputCallback,
 } from "./event";
+import type { UserMessage } from "./message";
 
 // =============================================================================
 // Message Queue

package/src/agent/types/event.ts

@@ -13,12 +13,11 @@
  */
 
 import type {
-  UserMessage,
   AssistantMessage,
-  ToolCallMessage,
-  ToolResultMessage,
   ErrorMessage,
   TokenUsage,
+  ToolResultMessage,
+  UserMessage,
 } from "./message";
 
 // =============================================================================
@@ -235,13 +234,9 @@ export interface ConversationStartData {
   messageId: string;
 }
 
-export interface ConversationThinkingData {
-  // Empty
-}
+export type ConversationThinkingData = {};
 
-export interface ConversationRespondingData {
-  // Empty
-}
+export type ConversationRespondingData = {};
 
 export interface ConversationEndData {
   reason: "completed" | "interrupted" | "error";
@@ -368,7 +363,6 @@ export interface MessageEvent<T extends string = string, D = unknown> extends En
 
 export type UserMessageEvent = EngineEvent<"user_message", UserMessage>;
 export type AssistantMessageEvent = EngineEvent<"assistant_message", AssistantMessage>;
-export type ToolCallMessageEvent = EngineEvent<"tool_call_message", ToolCallMessage>;
 export type ToolResultMessageEvent = EngineEvent<"tool_result_message", ToolResultMessage>;
 export type ErrorMessageEvent = EngineEvent<"error_message", ErrorMessage>;
 
@@ -378,7 +372,6 @@ export type ErrorMessageEvent = EngineEvent<"error_message", ErrorMessage>;
 export type AgentMessageEvent =
   | UserMessageEvent
   | AssistantMessageEvent
-  | ToolCallMessageEvent
   | ToolResultMessageEvent
   | ErrorMessageEvent;
 
@@ -389,7 +382,6 @@ export function isMessageEvent(event: EngineEvent): event is AgentMessageEvent {
   const messageTypes = [
     "user_message",
     "assistant_message",
-    "tool_call_message",
     "tool_result_message",
     "error_message",
   ];

package/src/agent/types/index.ts

@@ -48,7 +48,7 @@
  * ## Message Types (Three-Party Model)
  *
  * - **User**: Human participant (UserMessage)
- * - **Assistant**: AI participant (AssistantMessage, ToolCallMessage)
+ * - **Assistant**: AI participant (AssistantMessage — content includes ToolCallPart)
  * - **Tool**: Computer/execution environment (ToolResultMessage)
  *
  * @packageDocumentation
@@ -59,26 +59,25 @@
 // =============================================================================
 
 export type {
+  AssistantMessage,
+  ContentPart,
+  ErrorMessage,
+  FilePart,
+  ImagePart,
+  Message,
+  // Message Types
+  MessageRole,
+  MessageSubtype,
   // Content Parts
   TextPart,
   ThinkingPart,
-  ImagePart,
-  FilePart,
+  TokenUsage,
   ToolCallPart,
+  ToolResultMessage,
   ToolResultOutput,
   ToolResultPart,
-  ContentPart,
   UserContentPart,
-  // Message Types
-  MessageRole,
-  MessageSubtype,
-  TokenUsage,
   UserMessage,
-  AssistantMessage,
-  ToolCallMessage,
-  ToolResultMessage,
-  ErrorMessage,
-  Message,
 } from "./message";
 
 // =============================================================================
@@ -86,112 +85,111 @@ export type {
 // =============================================================================
 
 export type {
-  // Base Types
-  EngineEvent,
+  AgentError,
+  AgentErrorCategory,
+  AgentErrorOccurredEvent,
   AgentEvent,
+  AgentEventHandler,
+  AgentMessageEvent,
+  // Agent Output
+  AgentOutput,
+  AgentOutputCallback,
   // Agent State and Error
   AgentState,
-  AgentErrorCategory,
-  AgentError,
-  // Stream Events
-  StopReason,
-  MessageStartData,
-  MessageDeltaData,
-  MessageStopData,
-  TextDeltaData,
-  ToolUseStartData,
-  InputJsonDeltaData,
-  ToolUseStopData,
-  ToolResultData,
-  ErrorReceivedData,
-  MessageStartEvent,
-  MessageDeltaEvent,
-  MessageStopEvent,
-  TextDeltaEvent,
-  ToolUseStartEvent,
-  InputJsonDeltaEvent,
-  ToolUseStopEvent,
-  ToolResultEvent,
-  ErrorReceivedEvent,
-  StreamEvent,
-  StreamEventType,
-  // State Events
-  ConversationQueuedData,
-  ConversationStartData,
-  ConversationThinkingData,
-  ConversationRespondingData,
+  AgentStateEvent,
+  AgentTurnEvent,
+  AssistantMessageEvent,
   ConversationEndData,
+  ConversationEndEvent,
   ConversationInterruptedData,
-  ToolPlannedData,
-  ToolExecutingData,
-  ToolCompletedData,
-  ToolFailedData,
-  ErrorOccurredData,
-  StateEvent,
+  ConversationInterruptedEvent,
+  // State Events
+  ConversationQueuedData,
   ConversationQueuedEvent,
+  ConversationRespondingData,
+  ConversationRespondingEvent,
+  ConversationStartData,
   ConversationStartEvent,
+  ConversationThinkingData,
   ConversationThinkingEvent,
-  ConversationRespondingEvent,
-  ConversationEndEvent,
-  ConversationInterruptedEvent,
-  ToolPlannedEvent,
-  ToolExecutingEvent,
-  ToolCompletedEvent,
-  ToolFailedEvent,
+  // Base Types
+  EngineEvent,
+  ErrorMessageEvent,
+  ErrorOccurredData,
   ErrorOccurredEvent,
-  AgentErrorOccurredEvent,
-  AgentStateEvent,
+  ErrorReceivedData,
+  ErrorReceivedEvent,
+  InputJsonDeltaData,
+  InputJsonDeltaEvent,
+  MessageDeltaData,
+  MessageDeltaEvent,
   // Message Events
   MessageEvent,
-  UserMessageEvent,
-  AssistantMessageEvent,
-  ToolCallMessageEvent,
+  MessageStartData,
+  MessageStartEvent,
+  MessageStopData,
+  MessageStopEvent,
+  StateEvent,
+  // Stream Events
+  StopReason,
+  StreamEvent,
+  StreamEventType,
+  TextDeltaData,
+  TextDeltaEvent,
+  ToolCompletedData,
+  ToolCompletedEvent,
+  ToolExecutingData,
+  ToolExecutingEvent,
+  ToolFailedData,
+  ToolFailedEvent,
+  ToolPlannedData,
+  ToolPlannedEvent,
+  ToolResultData,
+  ToolResultEvent,
   ToolResultMessageEvent,
-  ErrorMessageEvent,
-  AgentMessageEvent,
+  ToolUseStartData,
+  ToolUseStartEvent,
+  ToolUseStopData,
+  ToolUseStopEvent,
+  TurnEvent,
   // Turn Events
   TurnRequestData,
-  TurnResponseData,
-  TurnEvent,
   TurnRequestEvent,
+  TurnResponseData,
   TurnResponseEvent,
-  AgentTurnEvent,
-  // Agent Output
-  AgentOutput,
   // Event Handling
   Unsubscribe,
-  AgentOutputCallback,
-  AgentEventHandler,
+  UserMessageEvent,
 } from "./event";
 
 // Type guards (functions, not types)
-export { isStateEvent, isMessageEvent, isTurnEvent } from "./event";
+export { isMessageEvent, isStateEvent, isTurnEvent } from "./event";
 
 // =============================================================================
 // Engine Types - Engine, Source, Presenter, Middleware, Interceptor
 // =============================================================================
 
 export type {
-  // Message Queue
-  MessageQueue,
-  // Middleware & Interceptor
-  AgentMiddlewareNext,
-  AgentMiddleware,
-  AgentInterceptorNext,
-  AgentInterceptor,
-  // State Machine
-  StateChange,
-  StateChangeHandler,
-  AgentStateMachineInterface,
-  // Event Handler Maps
-  EventHandlerMap,
-  ReactHandlerMap,
   // Agent Engine
   AgentEngine,
+  AgentEventBus,
+  AgentInterceptor,
+  AgentInterceptorNext,
+  AgentMiddleware,
+  // Middleware & Interceptor
+  AgentMiddlewareNext,
+  AgentPresenter,
   // Source & Presenter (EventBus adapters)
   AgentSource,
-  AgentPresenter,
-  AgentEventBus,
+  AgentStateMachineInterface,
   // Factory Options
   CreateAgentOptions,
+  // Event Handler Maps
+  EventHandlerMap,
+  // Message Queue
+  MessageQueue,
+  ReactHandlerMap,
+  // State Machine
+  StateChange,
+  StateChangeHandler,
 } from "./engine";

package/src/agent/types/message.ts

@@ -3,7 +3,7 @@
  *
  * This file defines:
  * - Content Parts: TextPart, ThinkingPart, ImagePart, FilePart, ToolCallPart, ToolResultPart
- * - Message Types: UserMessage, AssistantMessage, ToolCallMessage, ToolResultMessage, ErrorMessage
+ * - Message Types: UserMessage, AssistantMessage, ToolResultMessage, ErrorMessage
  * - Message Role and Subtype discriminators
  *
  * @packageDocumentation
@@ -215,7 +215,7 @@ export type MessageRole = "user" | "assistant" | "tool" | "system" | "error";
  * Represents the specific type/category of the message.
  * Used together with role for serialization and type discrimination.
  */
-export type MessageSubtype = "user" | "assistant" | "tool-call" | "tool-result" | "error";
+export type MessageSubtype = "user" | "assistant" | "tool-result" | "error";
 
 /**
  * Token usage information
@@ -256,9 +256,9 @@ export interface UserMessage {
  * Assistant Message
  *
  * Message generated by the AI assistant.
- * Contains text, thinking process, or files.
- *
- * Note: Tool calls are separate - use ToolCallMessage for tool invocations.
+ * Contains text, thinking process, files, and tool calls.
+ * Tool calls are content blocks within the assistant message,
+ * matching the mainstream API pattern (Anthropic, OpenAI).
  */
 export interface AssistantMessage {
   /** Unique identifier */
@@ -270,8 +270,8 @@ export interface AssistantMessage {
   /** Message subtype for serialization */
   subtype: "assistant";
 
-  /** Message content - can be simple string or array of parts */
-  content: string | Array<TextPart | ThinkingPart | FilePart>;
+  /** Message content - can be simple string or array of parts (including tool calls) */
+  content: string | Array<TextPart | ThinkingPart | FilePart | ToolCallPart>;
 
   /** When this message was created (Unix timestamp in milliseconds) */
   timestamp: number;
@@ -283,35 +283,6 @@ export interface AssistantMessage {
   usage?: TokenUsage;
 }
 
-/**
- * Tool Call Message
- *
- * Represents AI's request to invoke a tool.
- * Emitted when tool call parameters are fully assembled.
- *
- * Subject: Assistant (AI decided to call a tool)
- * Timing: At tool_use_content_block_stop
- */
-export interface ToolCallMessage {
-  /** Unique message identifier */
-  id: string;
-
-  /** Message role - assistant initiates tool calls */
-  role: "assistant";
-
-  /** Message subtype for serialization */
-  subtype: "tool-call";
-
-  /** Tool call details */
-  toolCall: ToolCallPart;
-
-  /** When this message was created (Unix timestamp in milliseconds) */
-  timestamp: number;
-
-  /** Parent message ID (the assistant message that triggered this) */
-  parentId?: string;
-}
-
 /**
  * Tool Result Message
  *
@@ -377,11 +348,6 @@ export interface ErrorMessage {
  * Use `subtype` field for precise type discrimination.
  *
  * Role: Who sent it (user, assistant, tool, system, error)
- * Subtype: What type of message (user, assistant, tool-call, tool-result, error)
+ * Subtype: What type of message (user, assistant, tool-result, error)
  */
-export type Message =
-  | UserMessage
-  | AssistantMessage
-  | ToolCallMessage
-  | ToolResultMessage
-  | ErrorMessage;
+export type Message = UserMessage | AssistantMessage | ToolResultMessage | ErrorMessage;

package/src/bash/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Bash Module
+ *
+ * Abstraction for command execution capability.
+ * Platform packages provide concrete implementations.
+ *
+ * Usage:
+ * ```typescript
+ * import type { BashProvider, BashResult } from "@agentxjs/core/bash";
+ *
+ * // Platform provides implementation
+ * const bash: BashProvider = platform.bashProvider;
+ *
+ * const result = await bash.execute("echo hello", { cwd: "/tmp" });
+ * console.log(result.stdout);  // "hello\n"
+ * console.log(result.exitCode); // 0
+ * ```
+ */
+
+export { createBashTool } from "./tool";
+export type { BashOptions, BashProvider, BashResult } from "./types";

package/src/bash/tool.ts

@@ -0,0 +1,57 @@
+/**
+ * Bash Tool Definition
+ *
+ * Creates a ToolDefinition that wraps a BashProvider.
+ * The tool schema is sent to the LLM, the execute function
+ * delegates to the platform-provided BashProvider via closure.
+ */
+
+import type { ToolDefinition } from "../driver/types";
+import type { BashProvider } from "./types";
+
+/**
+ * Create a bash ToolDefinition from a BashProvider
+ *
+ * @param provider - Platform-provided BashProvider
+ * @returns ToolDefinition ready for DriverConfig.tools
+ *
+ * @example
+ * ```typescript
+ * if (platform.bashProvider) {
+ *   tools.push(createBashTool(platform.bashProvider));
+ * }
+ * ```
+ */
+export function createBashTool(provider: BashProvider): ToolDefinition {
+  return {
+    name: "bash",
+    description:
+      "Execute a shell command and return stdout, stderr, and exit code. " +
+      "Use this for running CLI tools, scripts, file operations, etc.",
+    parameters: {
+      type: "object",
+      properties: {
+        command: {
+          type: "string",
+          description: "Shell command to execute (e.g. 'ls -la', 'cat file.txt')",
+        },
+        cwd: {
+          type: "string",
+          description: "Working directory for the command (optional)",
+        },
+        timeout: {
+          type: "number",
+          description: "Timeout in milliseconds (optional, default 30000)",
+        },
+      },
+      required: ["command"],
+    },
+    execute: async (params) => {
+      const result = await provider.execute(params.command as string, {
+        cwd: params.cwd as string | undefined,
+        timeout: params.timeout as number | undefined,
+      });
+      return result;
+    },
+  };
+}

package/src/bash/types.ts

@@ -0,0 +1,108 @@
+/**
+ * Bash Types
+ *
+ * Abstraction for command execution capability.
+ * Different platforms provide different implementations:
+ * - Node.js: child_process based
+ * - Docker: Container exec
+ * - Sandbox: Isolated environment
+ *
+ * ```
+ * ┌─────────────────────────────────────────────────────┐
+ * │                     core/bash                        │
+ * │  ┌─────────────────────────────────────────────────┐│
+ * │  │  BashProvider (interface)                       ││
+ * │  │  BashResult   (interface)                       ││
+ * │  │  BashOptions  (interface)                       ││
+ * │  └─────────────────────────────────────────────────┘│
+ * └─────────────────────────────────────────────────────┘
+ *                           │
+ *          ┌────────────────┼────────────────┐
+ *          ▼                ▼                ▼
+ *   ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
+ *   │ platform-node│ │platform-docker│ │platform-sandbox│
+ *   │ ChildProcess │ │ ContainerExec│ │ SandboxExec  │
+ *   └──────────────┘ └──────────────┘ └──────────────┘
+ * ```
+ */
+
+// ============================================================================
+// Bash Result
+// ============================================================================
+
+/**
+ * BashResult - Output from a command execution
+ */
+export interface BashResult {
+  /**
+   * Standard output
+   */
+  stdout: string;
+
+  /**
+   * Standard error
+   */
+  stderr: string;
+
+  /**
+   * Process exit code (0 = success)
+   */
+  exitCode: number;
+}
+
+// ============================================================================
+// Bash Options
+// ============================================================================
+
+/**
+ * BashOptions - Configuration for a single command execution
+ */
+export interface BashOptions {
+  /**
+   * Working directory for the command
+   */
+  cwd?: string;
+
+  /**
+   * Timeout in milliseconds
+   */
+  timeout?: number;
+
+  /**
+   * Environment variables
+   */
+  env?: Record<string, string>;
+}
+
+// ============================================================================
+// Bash Provider
+// ============================================================================
+
+/**
+ * BashProvider - Abstraction for command execution
+ *
+ * Platform implementations provide this interface.
+ * The provider is stateless — each execute() call is independent.
+ *
+ * @example
+ * ```typescript
+ * const result = await provider.execute("ls -la", { cwd: "/tmp" });
+ * console.log(result.stdout);
+ * console.log(result.exitCode); // 0
+ * ```
+ */
+export interface BashProvider {
+  /**
+   * Provider type (e.g., "child-process", "docker", "sandbox")
+   */
+  readonly type: string;
+
+  /**
+   * Execute a shell command
+   *
+   * @param command - Shell command to execute
+   * @param options - Execution options
+   * @returns Command output and exit code
+   */
+  execute(command: string, options?: BashOptions): Promise<BashResult>;
+}

package/src/common/logger/ConsoleLogger.ts

@@ -5,7 +5,7 @@
  * Used as fallback when no custom LoggerFactory is provided.
  */
 
-import type { Logger, LogContext, LogLevel } from "./types";
+import type { LogContext, Logger, LogLevel } from "./types";
 
 export interface ConsoleLoggerOptions {
   level?: LogLevel;