@agentxjs/core 1.9.9-dev → 2.0.0

package/src/agent/engine/internal/turnTrackerProcessor.ts

@@ -2,11 +2,11 @@
  * turnTrackerProcessor
  *
  * Pure Mealy transition function that tracks request-response turn pairs.
+ * Derives turn events entirely from stream-layer events (no external injection).
  *
- * Input Events:
- * - user_message (Message Layer)
- * - message_stop (Stream Layer - contains stop reason)
- * - assistant_message (Message Layer)
+ * Input Events (Stream Layer):
+ * - message_start → emit turn_request (a new turn begins)
+ * - message_stop  → emit turn_response (turn completes, based on stop reason)
  *
  * Output Events (Turn Layer):
  * - turn_request
@@ -15,11 +15,9 @@
 
 import type { Processor, ProcessorDefinition } from "../mealy";
 import type {
-  // Input: combined stream and message events
   StreamEvent,
-  AgentMessageEvent,
+  MessageStartEvent,
   MessageStopEvent,
-  UserMessageEvent,
   // Output: Turn events
   TurnRequestEvent,
   TurnResponseEvent,
@@ -88,9 +86,9 @@ export type TurnTrackerOutput = TurnRequestEvent | TurnResponseEvent;
 
 /**
  * Input event types for TurnTracker
- * Accepts both Stream and Message layer events
+ * Only stream-layer events — turn events are derived, not injected.
  */
-export type TurnTrackerInput = StreamEvent | AgentMessageEvent;
+export type TurnTrackerInput = StreamEvent;
 
 /**
  * turnTrackerProcessor
@@ -104,39 +102,37 @@ export const turnTrackerProcessor: Processor<
   TurnTrackerOutput
 > = (state, input): [TurnTrackerState, TurnTrackerOutput[]] => {
   switch (input.type) {
-    case "user_message":
-      return handleUserMessage(state, input as AgentMessageEvent);
+    case "message_start":
+      return handleMessageStart(state, input as MessageStartEvent);
 
     case "message_stop":
       return handleMessageStop(state, input as StreamEvent);
 
-    case "assistant_message":
-      // Turn completion is handled in message_stop
-      // This handler is kept for potential future use
-      return [state, []];
-
     default:
       return [state, []];
   }
 };
 
 /**
- * Handle user_message event
+ * Handle message_start event — a new turn begins
  */
-function handleUserMessage(
+function handleMessageStart(
   state: Readonly<TurnTrackerState>,
-  event: AgentMessageEvent
+  event: MessageStartEvent
 ): [TurnTrackerState, TurnTrackerOutput[]] {
-  const { data } = event as UserMessageEvent;
-  const turnId = generateId();
+  // If there's already a pending turn (e.g. tool_use didn't end the turn),
+  // don't start a new one
+  if (state.pendingTurn) {
+    return [state, []];
+  }
 
-  // Extract content as string (UserMessage.content can be string or array)
-  const contentText = typeof data.content === "string" ? data.content : "";
+  const turnId = generateId();
+  const messageId = event.data.messageId ?? "";
 
   const pendingTurn: PendingTurn = {
     turnId,
-    messageId: data.id,
-    content: contentText,
+    messageId,
+    content: "",
     requestedAt: event.timestamp,
   };
 
@@ -145,8 +141,8 @@ function handleUserMessage(
     timestamp: Date.now(),
     data: {
       turnId,
-      messageId: data.id,
-      content: contentText,
+      messageId,
+      content: "",
       timestamp: event.timestamp,
     },
   };

package/src/agent/types/event.ts

@@ -15,7 +15,6 @@
 import type {
   UserMessage,
   AssistantMessage,
-  ToolCallMessage,
   ToolResultMessage,
   ErrorMessage,
   TokenUsage,
@@ -368,7 +367,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 +376,6 @@ export type ErrorMessageEvent = EngineEvent<"error_message", ErrorMessage>;
 export type AgentMessageEvent =
   | UserMessageEvent
   | AssistantMessageEvent
-  | ToolCallMessageEvent
   | ToolResultMessageEvent
   | ErrorMessageEvent;
 
@@ -389,7 +386,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
@@ -75,7 +75,6 @@ export type {
   TokenUsage,
   UserMessage,
   AssistantMessage,
-  ToolCallMessage,
   ToolResultMessage,
   ErrorMessage,
   Message,
@@ -145,7 +144,6 @@ export type {
   MessageEvent,
   UserMessageEvent,
   AssistantMessageEvent,
-  ToolCallMessageEvent,
   ToolResultMessageEvent,
   ErrorMessageEvent,
   AgentMessageEvent,

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 type { BashProvider, BashResult, BashOptions } from "./types";
+export { createBashTool } from "./tool";

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/driver/index.ts

@@ -18,6 +18,7 @@
 export type {
   // Configuration
   McpServerConfig,
+  ToolDefinition,
   DriverConfig,
   DriverState,
 

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)
 // ============================================================================
@@ -150,6 +233,16 @@ export interface ErrorEvent extends StreamEvent<
   }
 > {}
 
+export interface MessageDeltaEvent extends StreamEvent<
+  "message_delta",
+  {
+    usage?: {
+      inputTokens: number;
+      outputTokens: number;
+    };
+  }
+> {}
+
 export interface InterruptedEvent extends StreamEvent<
   "interrupted",
   {
@@ -162,6 +255,7 @@ export interface InterruptedEvent extends StreamEvent<
  */
 export type DriverStreamEvent =
   | MessageStartEvent
+  | MessageDeltaEvent
   | MessageStopEvent
   | TextDeltaEvent
   | ToolUseStartEvent
@@ -252,8 +346,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/__tests__/EventBus.test.ts

@@ -3,7 +3,7 @@
  */
 
 import { describe, it, expect, beforeEach } from "bun:test";
-import { EventBus } from "../EventBus";
+import { EventBusImpl as EventBus } from "../EventBus";
 import type { BusEvent } from "../types";
 
 // Test event factory

package/src/event/types/agent.ts

@@ -7,7 +7,6 @@
 import type {
   UserMessage,
   AssistantMessage,
-  ToolCallMessage,
   ToolResultMessage,
   ErrorMessage,
 } from "../../agent/types";
@@ -376,15 +375,6 @@ export interface AssistantMessageEvent extends AgentMessageEventBase<
   AssistantMessage
 > {}
 
-/**
- * ToolCallMessageEvent - Tool call message (part of assistant turn)
- * Data: Complete ToolCallMessage object
- */
-export interface ToolCallMessageEvent extends AgentMessageEventBase<
-  "tool_call_message",
-  ToolCallMessage
-> {}
-
 /**
  * ToolResultMessageEvent - Tool result message
  * Data: Complete ToolResultMessage object
@@ -409,7 +399,6 @@ export interface ErrorMessageEvent extends AgentMessageEventBase<"error_message"
 export type AgentMessageEvent =
   | UserMessageEvent
   | AssistantMessageEvent
-  | ToolCallMessageEvent
   | ToolResultMessageEvent
   | ErrorMessageEvent;
 

package/src/event/types/command.ts

@@ -87,7 +87,7 @@ export interface McpServerConfig {
  * Image metadata for storing provider-specific data
  */
 export interface ImageMetadata {
-  claudeSdkSessionId?: string;
+  driverSessionId?: string;
 }
 
 /**
@@ -373,6 +373,7 @@ export interface ImageCreateRequest extends BaseCommandRequest<
       name?: string;
       description?: string;
       systemPrompt?: string;
+      customData?: Record<string, unknown>;
     };
   }
 > {}
@@ -446,6 +447,7 @@ export interface ImageUpdateRequest extends BaseCommandRequest<
     updates: {
       name?: string;
       description?: string;
+      customData?: Record<string, unknown>;
     };
   }
 > {}