@agentxjs/core 1.9.10-dev → 2.0.0

package/src/image/Image.ts

@@ -49,6 +49,10 @@ export class ImageImpl implements Image {
     return this.record.mcpServers;
   }
 
+  get customData(): Record<string, unknown> | undefined {
+    return this.record.customData;
+  }
+
   get createdAt(): number {
     return this.record.createdAt;
   }
@@ -76,6 +80,7 @@ export class ImageImpl implements Image {
       description: config.description,
       systemPrompt: config.systemPrompt,
       mcpServers: config.mcpServers,
+      customData: config.customData,
       createdAt: now,
       updatedAt: now,
     };
@@ -135,12 +140,17 @@ export class ImageImpl implements Image {
   /**
    * Update image metadata
    */
-  async update(updates: { name?: string; description?: string }): Promise<Image> {
+  async update(updates: {
+    name?: string;
+    description?: string;
+    customData?: Record<string, unknown>;
+  }): Promise<Image> {
     const now = Date.now();
     const updatedRecord: ImageRecord = {
       ...this.record,
       name: updates.name ?? this.record.name,
       description: updates.description ?? this.record.description,
+      customData: updates.customData !== undefined ? updates.customData : this.record.customData,
       updatedAt: now,
     };
 

package/src/image/types.ts

@@ -34,13 +34,18 @@ export interface Image {
   readonly description: string | undefined;
   readonly systemPrompt: string | undefined;
   readonly mcpServers: Record<string, McpServerConfig> | undefined;
+  readonly customData: Record<string, unknown> | undefined;
   readonly createdAt: number;
   readonly updatedAt: number;
 
   /**
-   * Update image metadata (name, description)
+   * Update image metadata (name, description, customData)
    */
-  update(updates: { name?: string; description?: string }): Promise<Image>;
+  update(updates: {
+    name?: string;
+    description?: string;
+    customData?: Record<string, unknown>;
+  }): Promise<Image>;
 
   /**
    * Delete this image and its session
@@ -74,4 +79,5 @@ export interface ImageCreateConfig {
   description?: string;
   systemPrompt?: string;
   mcpServers?: Record<string, McpServerConfig>;
+  customData?: Record<string, unknown>;
 }

package/src/network/RpcClient.ts

@@ -39,19 +39,18 @@ import {
 } from "./jsonrpc";
 import type { SystemEvent } from "../event/types/base";
 
-/**
- * Check if running in browser environment
- */
-function isBrowser(): boolean {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const globalWindow = typeof globalThis !== "undefined" ? (globalThis as any).window : undefined;
-  return globalWindow?.document !== undefined;
-}
-
 // ============================================================================
 // Types
 // ============================================================================
 
+/**
+ * Factory function for creating WebSocket instances.
+ * Platform layer provides the implementation:
+ * - Browser: native WebSocket (default)
+ * - Node.js: ws library (via @agentxjs/node-platform)
+ */
+export type WebSocketFactory = (url: string) => WebSocket;
+
 /**
  * RpcClient configuration
  */
@@ -61,6 +60,12 @@ export interface RpcClientConfig {
    */
   url: string;
 
+  /**
+   * Factory for creating WebSocket instances.
+   * If not provided, falls back to the global WebSocket constructor.
+   */
+  createWebSocket?: WebSocketFactory;
+
   /**
    * Request timeout in milliseconds (default: 30000)
    */
@@ -77,7 +82,7 @@ export interface RpcClientConfig {
   reconnectDelay?: number;
 
   /**
-   * Headers for authentication (Node.js only, sent in first message for browser)
+   * Headers for authentication (sent in first message after connection)
    */
   headers?:
     | Record<string, string>
@@ -172,14 +177,9 @@ export class RpcClient {
 
     const url = this.config.url;
 
-    // Create WebSocket (browser or Node.js)
-    let ws: WebSocket;
-    if (isBrowser()) {
-      ws = new WebSocket(url);
-    } else {
-      const { default: WS } = await import("ws");
-      ws = new WS(url) as unknown as WebSocket;
-    }
+    // Create WebSocket via injected factory or global WebSocket
+    const factory = this.config.createWebSocket ?? ((u: string) => new WebSocket(u));
+    const ws = factory(url);
 
     this.ws = ws;
 
@@ -191,8 +191,9 @@ export class RpcClient {
           console.log("[RpcClient] Connected to", url);
         }
 
-        // Send auth if in browser (headers not supported in WebSocket API)
-        if (isBrowser() && this.config.headers) {
+        // Send auth headers after connection (for environments where
+        // WebSocket constructor doesn't support headers, e.g. browser)
+        if (this.config.headers) {
           const headers =
             typeof this.config.headers === "function"
               ? await this.config.headers()

package/src/network/index.ts

@@ -72,5 +72,5 @@ export {
 } from "./jsonrpc";
 
 // RPC Client
-export type { RpcClientConfig, RpcClientState } from "./RpcClient";
+export type { RpcClientConfig, RpcClientState, WebSocketFactory } from "./RpcClient";
 export { RpcClient } from "./RpcClient";

package/src/persistence/types.ts

@@ -50,8 +50,8 @@ export interface ContainerRecord {
  * Image metadata for storing provider-specific data
  */
 export interface ImageMetadata {
-  /** Claude SDK session ID for conversation resume */
-  claudeSdkSessionId?: string;
+  /** Driver session ID for conversation resume */
+  driverSessionId?: string;
 }
 
 /**
@@ -93,6 +93,9 @@ export interface ImageRecord {
   /** Provider-specific metadata */
   metadata?: ImageMetadata;
 
+  /** Application-specific custom data (favorites, sort order, tags, etc.) */
+  customData?: Record<string, unknown>;
+
   /** Creation timestamp (Unix milliseconds) */
   createdAt: number;
 

package/src/platform/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Platform Module
+ *
+ * AgentXPlatform dependency injection container.
+ * Platform packages provide concrete implementations.
+ *
+ * Usage:
+ * ```typescript
+ * import type { AgentXPlatform } from "@agentxjs/core/platform";
+ *
+ * const platform: AgentXPlatform = {
+ *   containerRepository,
+ *   imageRepository,
+ *   sessionRepository,
+ *   eventBus,
+ *   bashProvider, // optional
+ * };
+ * ```
+ */
+
+export type { AgentXPlatform } from "./types";

package/src/platform/types.ts

@@ -0,0 +1,84 @@
+/**
+ * Platform Types
+ *
+ * AgentXPlatform - Dependency injection container for platform capabilities.
+ * Platform packages (node-platform, etc.) provide implementations.
+ *
+ * ```
+ * ┌─────────────────────────────────────────────────────────────┐
+ * │                      AgentXPlatform                         │
+ * │  (Dependency Injection - Platform provides implementations) │
+ * │                                                             │
+ * │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐          │
+ * │  │ Repositories│ │  EventBus   │ │  Providers  │          │
+ * │  │  Container  │ │             │ │  Bash (opt) │          │
+ * │  │  Image      │ │             │ │             │          │
+ * │  │  Session    │ │             │ │             │          │
+ * │  └─────────────┘ └─────────────┘ └─────────────┘          │
+ * └─────────────────────────────────────────────────────────────┘
+ * ```
+ */
+
+import type { ContainerRepository } from "../container/types";
+import type { ImageRepository } from "../image/types";
+import type { SessionRepository } from "../session/types";
+import type { EventBus } from "../event/types";
+import type { BashProvider } from "../bash/types";
+import type { WebSocketFactory } from "../network/RpcClient";
+
+// ============================================================================
+// AgentXPlatform - Dependency Injection
+// ============================================================================
+
+/**
+ * AgentXPlatform - Collects all dependencies for runtime
+ *
+ * Platform packages provide implementations of these interfaces.
+ * The platform is passed to AgentXRuntime for integration.
+ *
+ * Required capabilities:
+ * - containerRepository, imageRepository, sessionRepository — persistence
+ * - eventBus — pub/sub
+ *
+ * Optional capabilities:
+ * - bashProvider — command execution (not all platforms support this)
+ */
+export interface AgentXPlatform {
+  /**
+   * Container repository for persistence
+   */
+  readonly containerRepository: ContainerRepository;
+
+  /**
+   * Image repository for persistence
+   */
+  readonly imageRepository: ImageRepository;
+
+  /**
+   * Session repository for persistence
+   */
+  readonly sessionRepository: SessionRepository;
+
+  /**
+   * Event bus for pub/sub
+   */
+  readonly eventBus: EventBus;
+
+  // === Optional Providers ===
+
+  /**
+   * Bash provider for command execution
+   *
+   * Optional — not all platforms support shell execution.
+   * Node.js platform provides child_process based implementation.
+   */
+  readonly bashProvider?: BashProvider;
+
+  /**
+   * WebSocket factory for creating client connections
+   *
+   * Optional — browser uses native WebSocket by default.
+   * Node.js platform provides ws-based implementation.
+   */
+  readonly webSocketFactory?: WebSocketFactory;
+}

package/src/runtime/AgentXRuntime.ts

@@ -2,17 +2,18 @@
  * AgentXRuntimeImpl - Runtime integration implementation
  *
  * Integrates all components to provide agent lifecycle management.
- * Uses Provider dependencies to coordinate Session, Image, Container, etc.
+ * Uses Platform dependencies to coordinate Session, Image, Container, etc.
  *
- * New Design:
+ * Architecture:
  * - Driver.receive() returns AsyncIterable<DriverStreamEvent>
- * - Runtime processes events and emits to EventBus
- * - No more EventBus-based communication with Driver
+ * - Runtime emits raw stream events to EventBus
+ * - Runtime pushes events through AgentEngine (MealyMachine → Presenter)
+ * - Presenter emits message/state/turn events and persists messages
  */
 
 import { createLogger } from "commonxjs/logger";
 import type {
-  AgentXProvider,
+  AgentXPlatform,
   AgentXRuntime,
   RuntimeAgent,
   CreateAgentOptions,
@@ -20,9 +21,27 @@ import type {
   Subscription,
   AgentLifecycle,
 } from "./types";
-import type { UserContentPart, UserMessage } from "../agent/types";
+import type {
+  UserContentPart,
+  UserMessage,
+  AgentEngine,
+  StreamEvent,
+  AgentOutput,
+  AgentPresenter,
+  AgentSource,
+  Message,
+} from "../agent/types";
 import type { BusEvent } from "../event/types";
-import type { Driver, DriverConfig, DriverStreamEvent } from "../driver/types";
+import type {
+  CreateDriver,
+  Driver,
+  DriverConfig,
+  DriverStreamEvent,
+  ToolDefinition,
+} from "../driver/types";
+import { createSession } from "../session/Session";
+import { createBashTool } from "../bash/tool";
+import { createAgent as createAgentEngine } from "../agent/createAgent";
 
 const logger = createLogger("runtime/AgentXRuntime");
 
@@ -34,6 +53,7 @@ interface AgentState {
   lifecycle: AgentLifecycle;
   subscriptions: Set<() => void>;
   driver: Driver;
+  engine: AgentEngine;
   /** Flag to track if a receive operation is in progress */
   isReceiving: boolean;
 }
@@ -42,14 +62,16 @@ interface AgentState {
  * AgentXRuntimeImpl - Runtime implementation
  */
 export class AgentXRuntimeImpl implements AgentXRuntime {
-  readonly provider: AgentXProvider;
+  readonly platform: AgentXPlatform;
+  private readonly createDriver: CreateDriver;
 
   private agents = new Map<string, AgentState>();
   private globalSubscriptions = new Set<() => void>();
   private isShutdown = false;
 
-  constructor(provider: AgentXProvider) {
-    this.provider = provider;
+  constructor(platform: AgentXPlatform, createDriver: CreateDriver) {
+    this.platform = platform;
+    this.createDriver = createDriver;
     logger.info("AgentXRuntime initialized");
   }
 
@@ -63,7 +85,7 @@ export class AgentXRuntimeImpl implements AgentXRuntime {
     const { imageId } = options;
 
     // Load image
-    const imageRecord = await this.provider.imageRepository.findImageById(imageId);
+    const imageRecord = await this.platform.imageRepository.findImageById(imageId);
     if (!imageRecord) {
       throw new Error(`Image not found: ${imageId}`);
     }
@@ -72,41 +94,102 @@ export class AgentXRuntimeImpl implements AgentXRuntime {
     const agentId = options.agentId ?? this.generateAgentId();
 
     // Ensure container exists
-    const containerExists = await this.provider.containerRepository.containerExists(
+    const containerExists = await this.platform.containerRepository.containerExists(
       imageRecord.containerId
     );
     if (!containerExists) {
       throw new Error(`Container not found: ${imageRecord.containerId}`);
     }
 
-    // Create workspace
-    const workspace = await this.provider.workspaceProvider.create({
-      containerId: imageRecord.containerId,
+    // Create Session for driver (MonoDriver needs this to read history)
+    const session = createSession({
+      sessionId: imageRecord.sessionId,
       imageId,
+      containerId: imageRecord.containerId,
+      repository: this.platform.sessionRepository,
     });
-    await workspace.initialize();
 
-    // Create driver config
+    // Assemble platform-provided default tools
+    const defaultTools: ToolDefinition[] = [];
+    if (this.platform.bashProvider) {
+      defaultTools.push(createBashTool(this.platform.bashProvider));
+    }
+
+    // Create driver config (apiKey/baseUrl are provided by the createDriver closure)
     const driverConfig: DriverConfig = {
-      apiKey: process.env.ANTHROPIC_API_KEY ?? "",
-      baseUrl: process.env.ANTHROPIC_BASE_URL,
+      apiKey: "",
       agentId,
       systemPrompt: imageRecord.systemPrompt,
-      cwd: workspace.path,
       mcpServers: imageRecord.mcpServers,
-      resumeSessionId: imageRecord.metadata?.claudeSdkSessionId as string | undefined,
-      onSessionIdCaptured: async (claudeSdkSessionId: string) => {
-        // Persist SDK session ID for resume
-        await this.provider.imageRepository.updateMetadata(imageId, { claudeSdkSessionId });
+      tools: defaultTools.length > 0 ? defaultTools : undefined,
+      session, // Inject Session for stateless drivers
+      resumeSessionId: imageRecord.metadata?.driverSessionId as string | undefined,
+      onSessionIdCaptured: async (driverSessionId: string) => {
+        // Persist driver session ID for resume
+        await this.platform.imageRepository.updateMetadata(imageId, { driverSessionId });
       },
     };
 
-    // Create driver using the new CreateDriver function
-    const driver = this.provider.createDriver(driverConfig);
+    // Create driver using the injected CreateDriver function
+    const driver = this.createDriver(driverConfig);
 
     // Initialize driver
     await driver.initialize();
 
+    // Create AgentEngine with custom Source and Presenter
+    // Source: no-op (Runtime pushes events directly via handleStreamEvent)
+    // Presenter: emits message/state/turn events to EventBus + persists messages
+    const noopSource: AgentSource = {
+      name: "RuntimeSource",
+      connect: () => {},
+      disconnect: () => {},
+    };
+
+    const sessionId = imageRecord.sessionId;
+    const sessionRepository = this.platform.sessionRepository;
+    const eventBus = this.platform.eventBus;
+
+    const runtimePresenter: AgentPresenter = {
+      name: "RuntimePresenter",
+      present: (_agentId: string, output: AgentOutput) => {
+        const category = categorizeAgentOutput(output.type);
+
+        // Skip stream events — already emitted by handleDriverEvent
+        if (category === "stream") return;
+
+        // Emit state/message/turn events to EventBus
+        eventBus.emit({
+          type: output.type,
+          timestamp: output.timestamp,
+          source: "agent",
+          category,
+          intent: "notification",
+          data: output.data,
+          context: {
+            agentId,
+            imageId,
+            containerId: imageRecord.containerId,
+            sessionId,
+          },
+        } as BusEvent);
+
+        // Persist message events to SessionRepository
+        if (category === "message" && output.type !== "user_message") {
+          const message = output.data as Message;
+          sessionRepository.addMessage(sessionId, message).catch((err) => {
+            logger.error("Failed to persist message", { type: output.type, error: err });
+          });
+        }
+      },
+    };
+
+    const engine = createAgentEngine({
+      agentId,
+      bus: this.platform.eventBus,
+      source: noopSource,
+      presenter: runtimePresenter,
+    });
+
     // Create runtime agent
     const agent: RuntimeAgent = {
       agentId,
@@ -118,18 +201,19 @@ export class AgentXRuntimeImpl implements AgentXRuntime {
       createdAt: Date.now(),
     };
 
-    // Store agent state with driver
+    // Store agent state with driver and engine
     const state: AgentState = {
       agent,
       lifecycle: "running",
       subscriptions: new Set(),
       driver,
+      engine,
       isReceiving: false,
     };
     this.agents.set(agentId, state);
 
     // Emit agent_created event
-    this.provider.eventBus.emit({
+    this.platform.eventBus.emit({
       type: "agent_created",
       timestamp: Date.now(),
       source: "runtime",
@@ -185,7 +269,7 @@ export class AgentXRuntimeImpl implements AgentXRuntime {
     state.lifecycle = "stopped";
 
     // Emit agent_stopped event
-    this.provider.eventBus.emit({
+    this.platform.eventBus.emit({
       type: "agent_stopped",
       timestamp: Date.now(),
       source: "runtime",
@@ -216,7 +300,7 @@ export class AgentXRuntimeImpl implements AgentXRuntime {
     state.lifecycle = "running";
 
     // Emit agent_resumed event
-    this.provider.eventBus.emit({
+    this.platform.eventBus.emit({
       type: "agent_resumed",
       timestamp: Date.now(),
       source: "runtime",
@@ -240,8 +324,9 @@ export class AgentXRuntimeImpl implements AgentXRuntime {
       throw new Error(`Agent not found: ${agentId}`);
     }
 
-    // Dispose driver (new interface, no disconnect needed)
+    // Dispose driver and engine
     await state.driver.dispose();
+    await state.engine.destroy();
 
     // Cleanup subscriptions
     for (const unsub of state.subscriptions) {
@@ -252,7 +337,7 @@ export class AgentXRuntimeImpl implements AgentXRuntime {
     state.lifecycle = "destroyed";
 
     // Emit agent_destroyed event
-    this.provider.eventBus.emit({
+    this.platform.eventBus.emit({
       type: "agent_destroyed",
       timestamp: Date.now(),
       source: "runtime",
@@ -305,7 +390,7 @@ export class AgentXRuntimeImpl implements AgentXRuntime {
     };
 
     // Persist to session
-    await this.provider.sessionRepository.addMessage(state.agent.sessionId, userMessage);
+    await this.platform.sessionRepository.addMessage(state.agent.sessionId, userMessage);
 
     // Emit user_message event (for external subscribers)
     this.emitEvent(state, "user_message", userMessage, actualRequestId);
@@ -314,7 +399,11 @@ export class AgentXRuntimeImpl implements AgentXRuntime {
       agentId,
       requestId: actualRequestId,
       contentPreview:
-        typeof content === "string" ? content.substring(0, 50) : `[${content.length} parts]`,
+        typeof content === "string"
+          ? content.substring(0, 50)
+          : Array.isArray(content)
+            ? `[${content.length} parts]`
+            : `[${typeof content}]`,
     });
 
     // Mark as receiving
@@ -353,12 +442,7 @@ export class AgentXRuntimeImpl implements AgentXRuntime {
     state.driver.interrupt();
 
     // Emit interrupt event (for external subscribers)
-    this.emitEvent(
-      state,
-      "interrupt",
-      { agentId },
-      requestId ?? this.generateRequestId()
-    );
+    this.emitEvent(state, "interrupt", { agentId }, requestId ?? this.generateRequestId());
 
     logger.debug("Interrupt sent", { agentId, requestId });
   }
@@ -371,7 +455,7 @@ export class AgentXRuntimeImpl implements AgentXRuntime {
       throw new Error(`Agent not found: ${agentId}`);
     }
 
-    const unsub = this.provider.eventBus.onAny((event) => {
+    const unsub = this.platform.eventBus.onAny((event) => {
       const context = (event as BusEvent & { context?: { agentId?: string } }).context;
       if (context?.agentId === agentId) {
         handler(event);
@@ -389,7 +473,7 @@ export class AgentXRuntimeImpl implements AgentXRuntime {
   }
 
   subscribeAll(handler: AgentEventHandler): Subscription {
-    const unsub = this.provider.eventBus.onAny(handler);
+    const unsub = this.platform.eventBus.onAny(handler);
     this.globalSubscriptions.add(unsub);
 
     return {
@@ -428,25 +512,21 @@ export class AgentXRuntimeImpl implements AgentXRuntime {
   /**
    * Handle a single DriverStreamEvent
    */
-  private handleDriverEvent(
-    state: AgentState,
-    event: DriverStreamEvent,
-    requestId: string
-  ): void {
-    // Map DriverStreamEvent to BusEvent and emit
+  private handleDriverEvent(state: AgentState, event: DriverStreamEvent, requestId: string): void {
+    // 1. Emit raw stream event to EventBus (for Presentation and other subscribers)
     this.emitEvent(state, event.type, event.data, requestId);
+
+    // 2. Push to AgentEngine for MealyMachine processing
+    //    Engine produces message/state/turn events via Presenter
+    const streamEvent = toStreamEvent(event);
+    state.engine.handleStreamEvent(streamEvent);
   }
 
   /**
    * Emit an event to the EventBus
    */
-  private emitEvent(
-    state: AgentState,
-    type: string,
-    data: unknown,
-    requestId: string
-  ): void {
-    this.provider.eventBus.emit({
+  private emitEvent(state: AgentState, type: string, data: unknown, requestId: string): void {
+    this.platform.eventBus.emit({
       type,
       timestamp: Date.now(),
       source: "runtime",
@@ -493,9 +573,56 @@ export class AgentXRuntimeImpl implements AgentXRuntime {
   }
 }
 
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Convert DriverStreamEvent to agent-layer StreamEvent.
+ * Data structures are identical; only "error" type needs renaming.
+ */
+function toStreamEvent(event: DriverStreamEvent): StreamEvent {
+  const type = event.type === "error" ? "error_received" : event.type;
+  return { type, data: event.data, timestamp: Date.now() } as StreamEvent;
+}
+
+/**
+ * Categorize AgentOutput type for EventBus emission.
+ */
+function categorizeAgentOutput(type: string): string {
+  // Stream layer — already emitted by handleDriverEvent
+  const streamTypes = [
+    "message_start",
+    "message_delta",
+    "message_stop",
+    "text_delta",
+    "tool_use_start",
+    "input_json_delta",
+    "tool_use_stop",
+    "tool_result",
+    "error_received",
+  ];
+  if (streamTypes.includes(type)) return "stream";
+
+  // Message layer
+  if (type.endsWith("_message")) return "message";
+
+  // Turn layer
+  if (type.startsWith("turn_")) return "turn";
+
+  // State layer (default)
+  return "state";
+}
+
 /**
  * Create an AgentXRuntime instance
+ *
+ * @param platform - AgentXPlatform with repositories and event bus
+ * @param createDriver - Factory function for creating Driver instances per Agent
  */
-export function createAgentXRuntime(provider: AgentXProvider): AgentXRuntime {
-  return new AgentXRuntimeImpl(provider);
+export function createAgentXRuntime(
+  platform: AgentXPlatform,
+  createDriver: CreateDriver
+): AgentXRuntime {
+  return new AgentXRuntimeImpl(platform, createDriver);
 }