@agentxjs/core 1.9.10-dev → 2.0.0

package/README.md

@@ -0,0 +1,342 @@
+# @agentxjs/core
+
+Foundation library for the AgentX framework — a TypeScript toolkit for building AI agent applications with tool use, streaming, and multi-turn conversation.
+
+`@agentxjs/core` defines the types, interfaces, and agent engine that every other AgentX package depends on. You typically don't install it directly — it's pulled in as a dependency of `agentxjs`, `@agentxjs/server`, or driver packages.
+
+## Core Concepts
+
+AgentX is built around five concepts that work together:
+
+```
+Container  ──contains──►  Image  ──has──►  Session
+                            │
+                     created as──►  Agent  ──uses──►  Driver
+                                     │
+                              runs on──►  Platform
+```
+
+### Container
+
+A **Container** groups related agent configurations. Think of it as a namespace — one per app, workspace, or tenant. All Images inside a Container share the same isolation boundary.
+
+```typescript
+// Create a container for your app
+const container = await runtime.getOrCreateContainer("my-app");
+```
+
+### Image
+
+An **Image** is a persistent agent configuration: system prompt, MCP server definitions, and settings. One Image can spawn many Agents over time. When you update the Image, the next Agent created from it picks up the changes.
+
+```typescript
+// Create an image (configuration) inside the container
+const image = await createImage(
+  {
+    containerId: "my-app",
+    name: "CodeReviewer",
+    systemPrompt: "You are a code review assistant.",
+    mcpServers: {
+      /* optional tool servers */
+    },
+  },
+  ctx
+);
+```
+
+### Session
+
+A **Session** holds the conversation message history for an Image. Each Image has one active Session. Messages accumulate across multiple Agent runs, providing continuity.
+
+```typescript
+// Session is created automatically with the Image
+// Messages are persisted and survive agent restarts
+const messages = session.getMessages(); // full conversation history
+```
+
+### Driver
+
+A **Driver** handles communication with an LLM provider. It takes a user message, sends it to the API, and returns a stream of events (text chunks, tool calls, etc.). To support a new LLM provider, you implement the Driver interface:
+
+```typescript
+interface Driver {
+  receive(message: UserMessage): AsyncIterable<DriverStreamEvent>;
+  initialize(): Promise<void>;
+  dispose(): Promise<void>;
+  interrupt(): void;
+  readonly state: DriverState; // "idle" | "active" | "disposed"
+}
+
+// Factory function that the runtime calls to create a Driver per agent
+type CreateDriver = (config: DriverConfig) => Driver;
+```
+
+**To add a new LLM provider**: implement `Driver` and export a `CreateDriver` factory. Your factory receives `DriverConfig` with `apiKey`, `model`, `systemPrompt`, `session` (for message history), and `mcpServers`. See `@agentxjs/mono-driver` for a reference implementation.
+
+### Platform
+
+A **Platform** provides the infrastructure: repositories for data storage, an event bus for streaming, and optional bash execution. To change where data is stored (e.g., from SQLite to PostgreSQL), you implement the repository interfaces and wire them into a Platform:
+
+```typescript
+interface AgentXPlatform {
+  containerRepository: ContainerRepository; // CRUD for containers
+  imageRepository: ImageRepository; // CRUD for images + metadata
+  sessionRepository: SessionRepository; // CRUD for sessions + messages
+  eventBus: EventBus; // pub/sub for stream events
+  bashProvider?: BashProvider; // optional shell execution
+}
+```
+
+**To change storage backend**: implement `ContainerRepository`, `ImageRepository`, and `SessionRepository`. Each repository is a simple CRUD interface. See `@agentxjs/node-platform` for a SQLite reference implementation.
+
+## AgentEngine Pipeline
+
+The Runtime doesn't just relay raw driver events — it processes them through a **MealyMachine** that derives higher-level events:
+
+```
+Driver Stream Events (raw)
+  │
+  ├── message_start, text_delta, tool_use_start, message_stop ...
+  │
+  ▼
+MealyMachine  ── pure (state, event) → [newState, outputs]
+  │
+  ├── MessageAssembler  ── stream → message events
+  │     └── assistant_message, tool_call_message, tool_result_message, error_message
+  │
+  ├── StateEventProcessor  ── stream → state events
+  │     └── conversation_start, conversation_responding, conversation_end
+  │
+  └── TurnTracker  ── stream → turn events
+        └── turn_request (from message_start), turn_response (from message_stop)
+```
+
+**Key design**: only raw `StreamEvent`s enter the MealyMachine. All message, state, and turn events are **derived** — never injected from outside. Processors can chain: outputs from one processor feed into others (e.g., TurnTracker reads `message_start` / `message_stop` from the stream layer).
+
+The Runtime's **Presenter** handles the outputs:
+
+- **Stream events**: emitted directly to EventBus (for real-time UI streaming)
+- **Message events**: emitted to EventBus + persisted to SessionRepository
+- **State/Turn events**: emitted to EventBus
+
+```typescript
+// Subscribe to different event layers
+runtime.subscribe(agentId, (event) => {
+  switch (event.type) {
+    // Stream layer — real-time chunks
+    case "text_delta":
+      process.stdout.write(event.data.text);
+      break;
+
+    // Message layer — complete, persisted messages
+    case "assistant_message":
+      console.log("Full reply:", event.data.content);
+      break;
+
+    // State layer — conversation lifecycle
+    case "conversation_start":
+    case "conversation_end":
+      break;
+
+    // Turn layer — request-response tracking
+    case "turn_response":
+      console.log(`Turn took ${event.data.duration}ms`);
+      break;
+  }
+});
+```
+
+## Quick Start
+
+Most developers use `agentxjs` (the SDK) instead of `@agentxjs/core` directly. Core is for building custom drivers, platforms, or extending the framework.
+
+```typescript
+import { createAgentXRuntime } from "@agentxjs/core/runtime";
+
+// Platform and driver come from other packages
+const runtime = createAgentXRuntime(platform, createDriver);
+
+const agent = await runtime.createAgent({ imageId: "img_xxx" });
+
+const sub = runtime.subscribe(agent.agentId, (event) => {
+  if (event.type === "text_delta") {
+    process.stdout.write(event.data.text);
+  }
+});
+
+await runtime.receive(agent.agentId, "Hello!");
+
+sub.unsubscribe();
+await runtime.destroyAgent(agent.agentId);
+await runtime.shutdown();
+```
+
+## API Reference
+
+### Sub-module Imports
+
+```typescript
+import { ... } from "@agentxjs/core";            // common + agent
+import { ... } from "@agentxjs/core/agent";       // agent engine
+import { ... } from "@agentxjs/core/container";    // container management
+import { ... } from "@agentxjs/core/image";        // image management
+import { ... } from "@agentxjs/core/session";      // session/message management
+import { ... } from "@agentxjs/core/driver";       // LLM driver interface
+import { ... } from "@agentxjs/core/platform";     // platform interface
+import { ... } from "@agentxjs/core/runtime";      // runtime orchestration
+import { ... } from "@agentxjs/core/event";        // event bus system
+import { ... } from "@agentxjs/core/bash";         // command execution
+import { ... } from "@agentxjs/core/network";      // client-server protocol
+import { ... } from "@agentxjs/core/persistence";  // repository interfaces
+import { ... } from "@agentxjs/core/mq";           // message queue interface
+```
+
+### Runtime (`@agentxjs/core/runtime`)
+
+Orchestrates agent lifecycle. Takes platform and driver as separate parameters.
+
+```typescript
+function createAgentXRuntime(platform: AgentXPlatform, createDriver: CreateDriver): AgentXRuntime;
+
+interface AgentXRuntime {
+  createAgent(options: CreateAgentOptions): Promise<RuntimeAgent>;
+  destroyAgent(agentId: string): Promise<void>;
+  receive(agentId: string, content: string | unknown[]): Promise<void>;
+  subscribe(agentId: string, handler: AgentEventHandler): Subscription;
+  shutdown(): Promise<void>;
+}
+```
+
+### Driver (`@agentxjs/core/driver`)
+
+```typescript
+interface DriverConfig<TOptions = Record<string, unknown>> {
+  apiKey: string;
+  baseUrl?: string;
+  model?: string;
+  timeout?: number; // default: 600000 (10 min)
+  agentId: string;
+  systemPrompt?: string;
+  cwd?: string;
+  mcpServers?: Record<string, McpServerConfig>; // MCP tool servers
+  tools?: ToolDefinition[]; // inline tools
+  session?: Session; // conversation history
+  resumeSessionId?: string;
+  onSessionIdCaptured?: (sessionId: string) => void;
+  options?: TOptions; // driver-specific options
+}
+```
+
+**DriverStreamEvent** — the events your driver yields:
+
+| Event              | Data                               | When                     |
+| ------------------ | ---------------------------------- | ------------------------ |
+| `message_start`    | `{ messageId, model }`             | LLM starts responding    |
+| `text_delta`       | `{ text }`                         | Incremental text chunk   |
+| `tool_use_start`   | `{ toolCallId, toolName }`         | LLM wants to call a tool |
+| `input_json_delta` | `{ partialJson }`                  | Incremental tool input   |
+| `tool_use_stop`    | `{ toolCallId, toolName, input }`  | Tool call complete       |
+| `tool_result`      | `{ toolCallId, result, isError? }` | Tool execution result    |
+| `message_stop`     | `{ stopReason }`                   | LLM finished responding  |
+| `error`            | `{ message, errorCode? }`          | Error occurred           |
+
+**McpServerConfig** — two transports for connecting external tool servers:
+
+```typescript
+// Local subprocess (stdio)
+{ command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }
+
+// Remote server (HTTP Streamable)
+{ type: "http", url: "https://mcp.example.com/sse" }
+```
+
+### Container (`@agentxjs/core/container`)
+
+```typescript
+function createContainer(config: ContainerCreateConfig, ctx: ContainerContext): Promise<Container>;
+function loadContainer(containerId: string, ctx: ContainerContext): Promise<Container | null>;
+function getOrCreateContainer(containerId: string, ctx: ContainerContext): Promise<Container>;
+```
+
+`ContainerContext` provides the repository: `{ containerRepository: ContainerRepository }`.
+
+### Image (`@agentxjs/core/image`)
+
+```typescript
+function createImage(config: ImageCreateConfig, ctx: ImageContext): Promise<Image>;
+function loadImage(imageId: string, ctx: ImageContext): Promise<Image | null>;
+```
+
+`ImageCreateConfig`: `{ containerId, name?, description?, systemPrompt?, mcpServers? }`.
+`ImageContext` provides repositories: `{ imageRepository, sessionRepository }`.
+
+### Session (`@agentxjs/core/session`)
+
+```typescript
+function createSession(config: SessionConfig): Session;
+
+interface Session {
+  initialize(): Promise<void>;
+  addMessage(msg: Message): Promise<void>;
+  getMessages(): Message[];
+  clear(): Promise<void>;
+}
+```
+
+### Event (`@agentxjs/core/event`)
+
+Typed pub/sub event bus.
+
+```typescript
+interface EventBus {
+  emit(event: BusEvent): void;
+  on<T extends string>(type: T, handler: BusEventHandler): Unsubscribe;
+  onAny(handler: BusEventHandler): Unsubscribe;
+  asProducer(): EventProducer; // write-only view
+  asConsumer(): EventConsumer; // read-only view
+}
+```
+
+### Persistence (`@agentxjs/core/persistence`)
+
+Repository interfaces for data storage. Each is a simple CRUD interface:
+
+```typescript
+interface ContainerRepository {
+  create(record: ContainerRecord): Promise<void>;
+  findById(containerId: string): Promise<ContainerRecord | null>;
+  findAll(): Promise<ContainerRecord[]>;
+  delete(containerId: string): Promise<void>;
+}
+
+// ImageRepository and SessionRepository follow the same CRUD pattern
+```
+
+### Bash (`@agentxjs/core/bash`)
+
+```typescript
+interface BashProvider {
+  execute(command: string, options?: BashOptions): Promise<BashResult>;
+}
+
+interface BashResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+function createBashTool(provider: BashProvider): ToolDefinition;
+```
+
+## Configuration
+
+This package has no runtime configuration. It provides interfaces configured through implementation packages:
+
+| Concern     | Configured via                                                                       |
+| ----------- | ------------------------------------------------------------------------------------ |
+| Persistence | `@agentxjs/node-platform` (`dataPath`)                                               |
+| Driver      | `@agentxjs/mono-driver` or `@agentxjs/claude-driver` (`apiKey`, `provider`, `model`) |
+| Event Bus   | Created by platform (`new EventBusImpl()`)                                           |
+| Bash        | Created by platform (`NodeBashProvider`)                                             |
+
+**Dependencies**: `commonxjs`, `rxjs`, `jsonrpc-lite`

package/dist/RpcClient-BcJ_zAGu.d.ts

@@ -0,0 +1,304 @@
+import { JsonRpc, IParsedObject } from 'jsonrpc-lite';
+import { S as SystemEvent } from './base-m40r3Qgu.js';
+
+/**
+ * JSON-RPC 2.0 Protocol for AgentX Network Communication
+ *
+ * Uses jsonrpc-lite for message parsing/serialization.
+ *
+ * Message Types:
+ * - Request: Client → Server (has id, expects response)
+ * - Response: Server → Client (success or error)
+ * - Notification: Server → Client (no id, stream events)
+ *
+ * @see https://www.jsonrpc.org/specification
+ */
+
+/**
+ * All RPC method names supported by AgentX
+ */
+type RpcMethod = "container.create" | "container.get" | "container.list" | "image.create" | "image.get" | "image.list" | "image.delete" | "image.run" | "image.stop" | "image.update" | "image.messages" | "agent.get" | "agent.list" | "agent.destroy" | "agent.destroyAll" | "agent.interrupt" | "message.send";
+/**
+ * Notification method names (server push)
+ */
+type NotificationMethod = "stream.event" | "control.ack";
+/**
+ * JSON-RPC Request structure
+ */
+interface RpcRequest<M extends RpcMethod = RpcMethod, P = unknown> {
+    jsonrpc: "2.0";
+    method: M;
+    params: P;
+    id: string | number;
+}
+/**
+ * JSON-RPC Success Response structure
+ */
+interface RpcSuccessResponse<R = unknown> {
+    jsonrpc: "2.0";
+    result: R;
+    id: string | number;
+}
+/**
+ * JSON-RPC Error Response structure
+ */
+interface RpcErrorResponse {
+    jsonrpc: "2.0";
+    error: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+    id: string | number | null;
+}
+/**
+ * JSON-RPC Notification structure (no id, no response expected)
+ */
+interface RpcNotification<M extends NotificationMethod = NotificationMethod, P = unknown> {
+    jsonrpc: "2.0";
+    method: M;
+    params: P;
+}
+/**
+ * Stream event notification params
+ */
+interface StreamEventParams {
+    topic: string;
+    event: SystemEvent;
+}
+/**
+ * Control ACK notification params
+ */
+interface ControlAckParams {
+    msgId: string;
+}
+declare const RpcErrorCodes: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+    readonly SERVER_ERROR: -32000;
+    readonly NOT_FOUND: 404;
+    readonly UNAUTHORIZED: 401;
+    readonly FORBIDDEN: 403;
+    readonly TIMEOUT: 408;
+};
+/**
+ * Create a JSON-RPC request
+ */
+declare function createRequest(id: string | number, method: RpcMethod | string, params: unknown): JsonRpc;
+/**
+ * Create a JSON-RPC notification (no response expected)
+ */
+declare function createNotification(method: NotificationMethod | string, params: unknown): JsonRpc;
+/**
+ * Create a stream event notification
+ */
+declare function createStreamEvent(topic: string, event: SystemEvent): JsonRpc;
+/**
+ * Create an ACK notification
+ */
+declare function createAckNotification(msgId: string): JsonRpc;
+/**
+ * Create a success response
+ */
+declare function createSuccessResponse(id: string | number, result: unknown): JsonRpc;
+/**
+ * Create an error response
+ */
+declare function createErrorResponse(id: string | number | null, code: number, message: string, data?: unknown): JsonRpc;
+/**
+ * Parse a JSON-RPC message string
+ */
+declare function parseMessage(message: string): IParsedObject | IParsedObject[];
+/**
+ * Parse a JSON-RPC message object
+ */
+declare function parseMessageObject(obj: unknown): IParsedObject;
+/**
+ * Check if parsed message is a request
+ */
+declare function isRequest(parsed: IParsedObject): boolean;
+/**
+ * Check if parsed message is a notification
+ */
+declare function isNotification(parsed: IParsedObject): boolean;
+/**
+ * Check if parsed message is a success response
+ */
+declare function isSuccessResponse(parsed: IParsedObject): boolean;
+/**
+ * Check if parsed message is an error response
+ */
+declare function isErrorResponse(parsed: IParsedObject): boolean;
+/**
+ * Check if parsed message is invalid
+ */
+declare function isInvalid(parsed: IParsedObject): boolean;
+/**
+ * Check if notification is a stream event
+ */
+declare function isStreamEvent(parsed: IParsedObject): parsed is IParsedObject & {
+    payload: RpcNotification<"stream.event", StreamEventParams>;
+};
+/**
+ * Check if notification is a control ACK
+ */
+declare function isControlAck(parsed: IParsedObject): parsed is IParsedObject & {
+    payload: RpcNotification<"control.ack", ControlAckParams>;
+};
+/**
+ * Map old event type names to new RPC method names
+ */
+declare const eventTypeToRpcMethod: Record<string, RpcMethod>;
+/**
+ * Map RPC method names back to response event types
+ */
+declare const rpcMethodToResponseType: Record<RpcMethod, string>;
+
+/**
+ * RpcClient - JSON-RPC 2.0 Client over WebSocket
+ *
+ * Provides:
+ * - Request/Response with automatic ID matching
+ * - Notification handling (stream events)
+ * - Timeout management
+ * - Reconnection support
+ *
+ * @example
+ * ```typescript
+ * const client = new RpcClient({ url: "ws://localhost:5200" });
+ * await client.connect();
+ *
+ * // RPC call
+ * const result = await client.call("container.list", {});
+ *
+ * // Stream events
+ * client.onNotification("stream.event", (params) => {
+ *   console.log("Event:", params.event);
+ * });
+ *
+ * // Subscribe to topic
+ * client.notify("subscribe", { topic: "session-123" });
+ * ```
+ */
+
+/**
+ * Factory function for creating WebSocket instances.
+ * Platform layer provides the implementation:
+ * - Browser: native WebSocket (default)
+ * - Node.js: ws library (via @agentxjs/node-platform)
+ */
+type WebSocketFactory = (url: string) => WebSocket;
+/**
+ * RpcClient configuration
+ */
+interface RpcClientConfig {
+    /**
+     * WebSocket URL
+     */
+    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)
+     */
+    timeout?: number;
+    /**
+     * Auto reconnect on disconnect (default: true)
+     */
+    autoReconnect?: boolean;
+    /**
+     * Reconnect delay in milliseconds (default: 3000)
+     */
+    reconnectDelay?: number;
+    /**
+     * Headers for authentication (sent in first message after connection)
+     */
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    /**
+     * Debug logging
+     */
+    debug?: boolean;
+}
+/**
+ * Notification handler
+ */
+type NotificationHandler = (method: string, params: unknown) => void;
+/**
+ * Stream event handler
+ */
+type StreamEventHandler = (topic: string, event: SystemEvent) => void;
+/**
+ * Connection state
+ */
+type RpcClientState = "disconnected" | "connecting" | "connected";
+/**
+ * JSON-RPC 2.0 Client
+ */
+declare class RpcClient {
+    private readonly config;
+    private readonly timeout;
+    private readonly pendingRequests;
+    private readonly notificationHandlers;
+    private readonly streamEventHandlers;
+    private ws;
+    private state;
+    private requestId;
+    private reconnectTimer;
+    private disposed;
+    constructor(config: RpcClientConfig);
+    /**
+     * Current connection state
+     */
+    get connectionState(): RpcClientState;
+    /**
+     * Whether client is connected
+     */
+    get connected(): boolean;
+    /**
+     * Connect to server
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from server
+     */
+    disconnect(): void;
+    /**
+     * Dispose client and clean up resources
+     */
+    dispose(): void;
+    private scheduleReconnect;
+    /**
+     * Call an RPC method and wait for response
+     */
+    call<T = unknown>(method: RpcMethod, params: unknown): Promise<T>;
+    /**
+     * Send a notification (no response expected)
+     */
+    notify(method: NotificationMethod | string, params: unknown): void;
+    /**
+     * Subscribe to a topic (convenience method)
+     */
+    subscribe(topic: string): void;
+    /**
+     * Unsubscribe from a topic (convenience method)
+     */
+    unsubscribe(topic: string): void;
+    /**
+     * Register handler for all notifications
+     */
+    onNotification(handler: NotificationHandler): () => void;
+    /**
+     * Register handler for stream events
+     */
+    onStreamEvent(handler: StreamEventHandler): () => void;
+    private handleMessage;
+    private handleParsedMessage;
+}
+
+export { type ControlAckParams as C, type NotificationMethod as N, type RpcMethod as R, type StreamEventParams as S, type WebSocketFactory as W, type RpcRequest as a, type RpcSuccessResponse as b, type RpcErrorResponse as c, type RpcNotification as d, RpcErrorCodes as e, createRequest as f, createNotification as g, createStreamEvent as h, createAckNotification as i, createSuccessResponse as j, createErrorResponse as k, parseMessageObject as l, isRequest as m, isNotification as n, isSuccessResponse as o, parseMessage as p, isErrorResponse as q, isInvalid as r, isStreamEvent as s, isControlAck as t, eventTypeToRpcMethod as u, rpcMethodToResponseType as v, type RpcClientConfig as w, type RpcClientState as x, RpcClient as y };