@agentxjs/runtime 1.8.1 → 2.0.0

package/README.md

@@ -1,616 +1,257 @@
 # @agentxjs/runtime
 
-> Complete Runtime implementation for AI Agents with Claude SDK integration
+> Runtime for AI Agents - Agent execution, SystemBus, Environment, and complete lifecycle management
 
 ## Overview
 
-`@agentxjs/runtime` provides the complete runtime infrastructure for AI agents, including:
-
-- **SystemBus** - Event-driven communication backbone
-- **Container** - Agent lifecycle management
-- **Environment** (Receptor + Effector) - External world interface (Claude SDK)
-- **Session** - Message persistence
-- **Persistence** - Storage layer (SQLite, Memory)
+The `@agentxjs/runtime` package provides complete runtime infrastructure for executing AI agents. It manages the full lifecycle from agent creation to destruction, handles communication through a centralized event bus, and integrates with the Claude SDK.
 
 **Key Features:**
 
-- **Event-Driven Architecture** - All operations via command events
-- **Claude SDK Integration** - Production-ready ClaudeEnvironment
-- **Pluggable Storage** - SQLite, Memory, or custom backends
-- **Type-Safe Commands** - Request/response pattern with full typing
-- **Cross-Platform** - Works in Node.js (Browser support via agentxjs)
+- **Docker-Style Lifecycle**: Definition -> Image -> Agent -> Session pattern
+- **Event-Driven Architecture**: Central SystemBus for all runtime communication
+- **Image-First Model**: Persistent conversations with transient runtime agents
+- **Environment Abstraction**: Pluggable receptor/effector pattern for LLM integration
+- **Request/Response Pattern**: Command-based API with correlation support
 
 ## Installation
 
 ```bash
-pnpm add @agentxjs/runtime
-```
-
-**Dependencies:**
-
-- `@anthropic-ai/claude-agent-sdk` - Claude API client
-- `better-sqlite3` - SQLite database (optional, for persistence)
-- `unstorage` - Unified storage layer
-
----
-
-## Quick Start
-
-### Minimal Setup
-
-```typescript
-import { createRuntime } from "@agentxjs/runtime";
-
-// Minimal - uses environment variable ANTHROPIC_API_KEY
-const runtime = createRuntime();
-
-// Subscribe to events
-runtime.on("text_delta", (e) => {
-  console.log(e.data.text);
-});
-
-// Create container
-const containerRes = await runtime.request("container_create_request", {
-  containerId: "my-container",
-});
-
-// Run agent
-const agentRes = await runtime.request("agent_run_request", {
-  containerId: "my-container",
-  config: {
-    name: "Assistant",
-    systemPrompt: "You are a helpful assistant",
-  },
-});
-
-// Send message
-await runtime.request("agent_receive_request", {
-  agentId: agentRes.data.agentId,
-  content: "Hello!",
-});
-
-// Cleanup
-await runtime.dispose();
+bun add @agentxjs/runtime
 ```
 
-### With Configuration
-
-```typescript
-import { createRuntime, createPersistence } from "@agentxjs/runtime";
-import { sqliteDriver } from "@agentxjs/persistence/sqlite";
-
-const runtime = createRuntime({
-  // LLM configuration
-  llm: {
-    apiKey: process.env.ANTHROPIC_API_KEY,
-    baseUrl: "https://api.anthropic.com",
-  },
-
-  // Persistence (using sqlite driver)
-  persistence: await createPersistence(sqliteDriver({ path: "./data.db" })),
-
-  // Logger
-  logger: {
-    level: "info",
-    enableTimestamp: true,
-  },
-});
-```
-
----
-
 ## Architecture
 
-### System Overview
-
-```text
-┌────────────────────────────────────────────────────────────────┐
-│                          Runtime                                │
-├────────────────────────────────────────────────────────────────┤
-│                                                                 │
-│   ┌─────────────────────────────────────────────────────────┐  │
-│   │                    SystemBus                            │  │
-│   │  (Central event bus - all communication flows here)     │  │
-│   └──────────────────────┬──────────────────────────────────┘  │
-│                          │                                      │
-│          ┌───────────────┼───────────────┐                      │
-│          │               │               │                      │
-│          ▼               ▼               ▼                      │
-│   ┌─────────────┐  ┌──────────┐  ┌────────────┐                │
-│   │Environment  │  │Container │  │Persistence │                │
-│   │             │  │          │  │            │                │
-│   │ Receptor    │  │  Agent1  │  │  SQLite    │                │
-│   │ Effector    │  │  Agent2  │  │  Images    │                │
-│   │ (Claude SDK)│  │  Agent3  │  │  Sessions  │                │
-│   └─────────────┘  └──────────┘  └────────────┘                │
-│                                                                 │
-└────────────────────────────────────────────────────────────────┘
 ```
-
-### Component Responsibilities
-
-| Component       | Role                     | Examples                          |
-| --------------- | ------------------------ | --------------------------------- |
-| **SystemBus**   | Event distribution       | Emit, subscribe, request/response |
-| **Environment** | External world interface | Claude API calls, streaming       |
-| **Container**   | Agent lifecycle          | Create, destroy, manage agents    |
-| **Session**     | Message persistence      | Save/load conversation history    |
-| **Persistence** | Storage backend          | SQLite, Memory, custom            |
-
----
-
-## SystemBus - Event Backbone
-
-All Runtime operations go through the SystemBus using **command events**.
-
-### Request/Response Pattern
-
-```typescript
-// Type-safe request
-const response = await runtime.request("container_create_request", {
-  containerId: "my-container",
-});
-
-// Response is fully typed
-console.log(response.data.containerId); // ✓ TypeScript knows this exists
++------------------------------------------------------------------+
+|                           Runtime                                 |
+|                                                                   |
+|  +----------------------+    +-----------------------------+      |
+|  |     SystemBus        |    |      CommandHandler         |      |
+|  |  (Event Routing)     |<-->|  (Request/Response Logic)   |      |
+|  +----------------------+    +-----------------------------+      |
+|           |                                                       |
+|           v                                                       |
+|  +------------------------------------------------------------+  |
+|  |                       Container                             |  |
+|  |  +------------------------------------------------------+  |  |
+|  |  |                    RuntimeAgent                      |  |  |
+|  |  |  +----------------+  +----------------+              |  |  |
+|  |  |  |  AgentEngine   |  |   Session      |              |  |  |
+|  |  |  | (MealyMachine) |  |   (Storage)    |              |  |  |
+|  |  |  +----------------+  +----------------+              |  |  |
+|  |  |                                                      |  |  |
+|  |  |  +------------------------------------------------+ |  |  |
+|  |  |  |              Environment                       | |  |  |
+|  |  |  |  +------------------+  +------------------+    | |  |  |
+|  |  |  |  |    Receptor      |  |    Effector      |    | |  |  |
+|  |  |  |  | (Claude -> Bus)  |  | (Bus -> Claude)  |    | |  |  |
+|  |  |  |  +------------------+  +------------------+    | |  |  |
+|  |  |  +------------------------------------------------+ |  |  |
+|  |  +------------------------------------------------------+  |  |
+|  +------------------------------------------------------------+  |
++------------------------------------------------------------------+
 ```
 
-### Event Subscription
+## Quick Start
 
 ```typescript
-// Subscribe to specific event type
-runtime.on("text_delta", (event) => {
-  console.log(event.data.text);
-});
-
-// Subscribe to multiple types
-runtime.on(["message_start", "message_stop"], (event) => {
-  console.log(event.type);
-});
-
-// Subscribe to all events
-runtime.onAny((event) => {
-  console.log(event.type, event.data);
-});
-
-// Unsubscribe
-const unsubscribe = runtime.on("text_delta", handler);
-unsubscribe();
-```
-
-### Available Commands
+import { createRuntime, createPersistence, memoryDriver } from "@agentxjs/runtime";
 
-#### Container Commands
+// Create runtime with in-memory storage
+const persistence = await createPersistence(memoryDriver());
 
-```typescript
-// Create container
-const res = await runtime.request("container_create_request", {
-  containerId: "my-container",
+const runtime = createRuntime({
+  persistence,
+  llmProvider: {
+    provide: () => ({
+      apiKey: process.env.ANTHROPIC_API_KEY!,
+    }),
+  },
+  basePath: "./data",
 });
 
-// Destroy container
-await runtime.request("container_destroy_request", {
-  containerId: "my-container",
+// Create container for user
+await runtime.request("container_create_request", {
+  containerId: "user-123",
 });
-```
 
-#### Agent Commands
-
-```typescript
-// Run agent
-const res = await runtime.request("agent_run_request", {
-  containerId: "my-container",
+// Create conversation (image)
+const imageRes = await runtime.request("image_create_request", {
+  containerId: "user-123",
   config: {
-    name: "Assistant",
-    systemPrompt: "You are helpful",
+    name: "My Assistant",
+    systemPrompt: "You are a helpful assistant.",
   },
 });
 
-// Send message
-await runtime.request("agent_receive_request", {
-  agentId: res.data.agentId,
-  content: "Hello!",
-});
-
-// Interrupt agent
-await runtime.request("agent_interrupt_request", {
-  agentId: res.data.agentId,
-});
-
-// Destroy agent
-await runtime.request("agent_destroy_request", {
-  agentId: res.data.agentId,
-});
-```
-
-#### Session Commands
-
-```typescript
-// Create session
-await runtime.request("session_create_request", {
-  sessionId: "session_123",
-  containerId: "my-container",
-  agentId: "agent_123",
-});
-
-// Get session
-const res = await runtime.request("session_get_request", {
-  sessionId: "session_123",
-});
-
-// Delete session
-await runtime.request("session_delete_request", {
-  sessionId: "session_123",
+// Subscribe to text deltas
+runtime.on("text_delta", (e) => {
+  process.stdout.write(e.data.text);
 });
-```
-
-### Direct Command Emission
-
-For advanced use cases:
 
-```typescript
-// Emit command directly (fire and forget)
-runtime.emitCommand("agent_receive_request", {
-  requestId: "req_123",
-  agentId: "agent_123",
-  content: "Hello!",
+// Send message (auto-runs image if needed)
+await runtime.request("message_send_request", {
+  imageId: imageRes.data.record.imageId,
+  content: "Hello, how are you?",
 });
 
-// Listen for response
-runtime.onCommand("agent_receive_response", (event) => {
-  if (event.data.requestId === "req_123") {
-    console.log("Response:", event.data);
-  },
-});
+// Cleanup
+await runtime.dispose();
 ```
 
----
+## Core Components
 
-## Environment - External World Interface
+### Runtime
 
-Environment connects Runtime to the external world (Claude API).
-
-### ClaudeEnvironment
-
-Built-in implementation using `@anthropic-ai/claude-agent-sdk`:
+Top-level API orchestrating all operations. Implements SystemBus interface and delegates to CommandHandler for request processing.
 
 ```typescript
-import { createRuntime } from "@agentxjs/runtime";
-
 const runtime = createRuntime({
-  llm: {
-    apiKey: process.env.ANTHROPIC_API_KEY,
-    baseUrl: "https://api.anthropic.com",
-  },
+  persistence,
+  llmProvider: { provide: () => ({ apiKey: "..." }) },
+  basePath: "/path/to/.agentx",
+  defaultAgent: { name: "Assistant", systemPrompt: "..." },
 });
 ```
 
-### Architecture
-
-```text
-┌────────────────────────────────────────────────────────────┐
-│                    Environment                              │
-├────────────────────────────────────────────────────────────┤
-│                                                             │
-│   Receptor (Perceives external world → emits to SystemBus) │
-│       │                                                     │
-│       │  Claude API Streaming Response                      │
-│       ▼                                                     │
-│   ┌──────────────────────────────────────────────────────┐ │
-│   │  Transforms Claude SDK events → DriveableEvent        │ │
-│   │  (message_delta, tool_use, etc.)                      │ │
-│   └──────────────────────────────────────────────────────┘ │
-│       │                                                     │
-│       │  emit to SystemBus                                  │
-│       ▼                                                     │
-│   SystemBus                                                 │
-│       │                                                     │
-│       │  subscribe                                          │
-│       ▼                                                     │
-│   Effector (Subscribes to SystemBus → acts on external world)│
-│       │                                                     │
-│       │  Executes tool calls                                │
-│       ▼                                                     │
-│   External Tools (MCP, filesystem, etc.)                    │
-│                                                             │
-└────────────────────────────────────────────────────────────┘
-```
+### Container
 
----
-
-## Container - Agent Lifecycle
-
-Container manages multiple agents:
-
-```typescript
-// Via command events (recommended)
-const res = await runtime.request("container_create_request", {
-  containerId: "my-container",
-});
+Isolation boundary managing multiple agents. Tracks `imageId -> agentId` mapping for the Image-First model.
 
-// Run agents in container
-const agent1 = await runtime.request("agent_run_request", {
-  containerId: "my-container",
-  config: { name: "Agent1" },
-});
+### Agent (RuntimeAgent)
 
-const agent2 = await runtime.request("agent_run_request", {
-  containerId: "my-container",
-  config: { name: "Agent2" },
-});
+Transient runtime entity processing user messages. Created by running an Image, destroyed when stopped.
 
-// Destroy container (destroys all agents)
-await runtime.request("container_destroy_request", {
-  containerId: "my-container",
-});
-```
+### Session (RuntimeSession)
 
----
+Manages conversation history storage and retrieval via persistence layer.
 
-## Persistence - Storage Layer
+### Image (RuntimeImage)
 
-Persistence is now provided by the separate `@agentxjs/persistence` package with subpath exports for each driver.
+Persistent conversation entity. Users interact with Images (conversations), while Agents are transient instances.
 
-### Built-in Storage Backends
+### SystemBus
 
-#### SQLite (Production)
+Central event bus using RxJS. Supports pub/sub, request/response, priority-based dispatch, and filtering.
 
 ```typescript
-import { createRuntime, createPersistence } from "@agentxjs/runtime";
-import { sqliteDriver } from "@agentxjs/persistence/sqlite";
+// Subscribe to events
+runtime.on("text_delta", (e) => console.log(e.data.text));
+runtime.on(["message_start", "message_stop"], (e) => console.log(e.type));
+runtime.onAny((e) => console.log(e.type));
 
-const runtime = createRuntime({
-  persistence: await createPersistence(sqliteDriver({ path: "./data.db" })),
-});
+// Request/response pattern
+const response = await runtime.request("image_get_request", { imageId: "..." });
 ```
 
-#### Memory (Development)
+### Environment
 
-```typescript
-import { createRuntime, createPersistence, memoryDriver } from "@agentxjs/runtime";
+Abstraction for LLM integration using Receptor/Effector pattern:
 
-const runtime = createRuntime({
-  persistence: await createPersistence(memoryDriver()),
-});
-```
+- **ClaudeReceptor**: Perceives Claude SDK responses, emits DriveableEvents to SystemBus
+- **ClaudeEffector**: Subscribes to SystemBus events, sends to Claude SDK
 
-#### Other Drivers
+## Command API
 
-```typescript
-// Redis
-import { redisDriver } from "@agentxjs/persistence/redis";
-const persistence = await createPersistence(redisDriver({ url: "redis://localhost:6379" }));
-
-// MongoDB
-import { mongodbDriver } from "@agentxjs/persistence/mongodb";
-const persistence = await createPersistence(mongodbDriver({ connectionString: "mongodb://..." }));
-
-// MySQL
-import { mysqlDriver } from "@agentxjs/persistence/mysql";
-const persistence = await createPersistence(mysqlDriver({ host: "localhost", database: "agentx" }));
-
-// PostgreSQL
-import { postgresqlDriver } from "@agentxjs/persistence/postgresql";
-const persistence = await createPersistence(
-  postgresqlDriver({ host: "localhost", database: "agentx" })
-);
-```
+### Container Commands
 
-### Storage Schema
+| Command                    | Description            |
+| -------------------------- | ---------------------- |
+| `container_create_request` | Create a new container |
+| `container_get_request`    | Get container by ID    |
+| `container_list_request`   | List all containers    |
 
-Persistence stores:
+### Image Commands
 
-- **Images** - Agent snapshots with conversation history
-- **Containers** - Container metadata
-- **Sessions** - Message history per agent
+| Command                  | Description                       |
+| ------------------------ | --------------------------------- |
+| `image_create_request`   | Create a new image (conversation) |
+| `image_run_request`      | Run an image (create agent)       |
+| `image_stop_request`     | Stop an image (destroy agent)     |
+| `image_update_request`   | Update image metadata             |
+| `image_list_request`     | List all images                   |
+| `image_get_request`      | Get image by ID                   |
+| `image_delete_request`   | Delete an image                   |
+| `image_messages_request` | Get messages for an image         |
 
-```typescript
-// Save agent image
-const image = await runtime.request("image_snapshot_request", {
-  agentId: "agent_123",
-});
-
-// Resume from image
-const agent = await runtime.request("image_resume_request", {
-  imageId: image.data.imageId,
-});
-```
+### Agent Commands
 
----
+| Command                     | Description                       |
+| --------------------------- | --------------------------------- |
+| `message_send_request`      | Send message to agent             |
+| `agent_interrupt_request`   | Interrupt agent operation         |
+| `agent_get_request`         | Get agent by ID                   |
+| `agent_list_request`        | List agents in a container        |
+| `agent_destroy_request`     | Destroy an agent                  |
+| `agent_destroy_all_request` | Destroy all agents in a container |
 
-## Advanced Usage
+## Event Types
 
-### Custom Persistence Backend
+### Stream Events (from Environment)
 
 ```typescript
-import { type StorageDriver } from "@agentxjs/runtime";
-
-const customDriver: StorageDriver = {
-  async getItem(key) {
-    // Fetch from your backend
-  },
-  async setItem(key, value) {
-    // Save to your backend
-  },
-  async removeItem(key) {
-    // Delete from your backend
-  },
-  async getKeys(base) {
-    // List keys with prefix
-  },
-  async clear() {
-    // Clear all data
-  },
-};
-
-const runtime = createRuntime({
-  persistence: createPersistence({
-    driver: customDriver,
-  }),
-});
+{ type: "message_start", data: { message: { id, model } } }
+{ type: "text_delta", data: { text: string } }
+{ type: "message_stop", data: { stopReason: "end_turn" | "tool_use" | "max_tokens" } }
 ```
 
-### Event Filtering
+### Lifecycle Events
 
 ```typescript
-// Filter events by agent
-runtime.on(
-  "text_delta",
-  (event) => {
-    console.log(event.data.text);
-  },
-  {
-    filter: (event) => event.context?.agentId === "agent_123",
-  }
-);
-
-// Priority execution
-runtime.on("message_stop", handler, {
-  priority: 10, // Higher priority runs first
-});
-
-// One-time subscription
-runtime.once("agent_created", (event) => {
-  console.log("Agent created:", event.data.agentId);
-});
+{ type: "container_created", data: { containerId, createdAt } }
+{ type: "agent_registered", data: { containerId, agentId, registeredAt } }
+{ type: "session_created", data: { sessionId, imageId, containerId, createdAt } }
 ```
 
----
-
-## Testing
-
-Runtime is designed for easy testing:
+## Configuration
 
 ```typescript
-import { createRuntime, createPersistence, memoryDriver } from "@agentxjs/runtime";
-import { describe, it, expect } from "vitest";
-
-describe("Runtime", () => {
-  it("creates and runs agent", async () => {
-    const runtime = createRuntime({
-      llm: {
-        apiKey: "test-key",
-      },
-      persistence: await createPersistence(memoryDriver()),
-    });
-
-    // Create container
-    const containerRes = await runtime.request("container_create_request", {
-      containerId: "test-container",
-    });
-
-    expect(containerRes.data.containerId).toBe("test-container");
-
-    // Run agent
-    const agentRes = await runtime.request("agent_run_request", {
-      containerId: "test-container",
-      config: { name: "TestAgent" },
-    });
-
-    expect(agentRes.data.name).toBe("TestAgent");
-
-    await runtime.dispose();
-  });
-});
-```
-
----
-
-## Design Decisions
-
-### Why Event-Driven?
-
-Event-driven architecture enables:
-
-1. **Decoupling** - Components communicate via events, not direct calls
-2. **Extensibility** - Add new components without modifying existing ones
-3. **Testability** - Mock events instead of entire components
-4. **Observability** - All operations are visible as events
-
-### Why SystemBus?
-
-SystemBus provides:
-
-1. **Single Source of Truth** - All communication flows through one point
-2. **Type Safety** - Commands are fully typed
-3. **Request/Response** - Async operations with correlation IDs
-4. **Priority/Filtering** - Advanced subscription options
-
-### Why Separate Environment?
-
-Environment abstraction allows:
+interface RuntimeConfig {
+  /** Persistence layer for data storage */
+  persistence: Persistence;
 
-1. **Multiple Backends** - Claude, OpenAI, local models
-2. **Testing** - Mock Environment in tests
-3. **Cross-Platform** - Different implementations for Node.js, Browser
-4. **Clear Boundary** - External world vs. internal logic
+  /** LLM provider for AI model access */
+  llmProvider: LLMProvider<ClaudeLLMConfig>;
 
----
+  /** Base path for runtime data (containers, workdirs, etc.) */
+  basePath: string;
 
-## Configuration Reference
+  /** Optional environment factory for dependency injection */
+  environmentFactory?: EnvironmentFactory;
 
-```typescript
-interface RuntimeConfig {
-  // LLM configuration
-  llm?: {
-    apiKey?: string; // Default: process.env.ANTHROPIC_API_KEY
-    baseUrl?: string; // Default: "https://api.anthropic.com"
-  };
-
-  // Persistence
-  persistence?: Persistence;
-
-  // Logger
-  logger?: {
-    level?: LogLevel;
-    enableTimestamp?: boolean;
-    enableColor?: boolean;
-  };
+  /** Default agent definition used when creating new images */
+  defaultAgent?: AgentDefinition;
 }
 ```
 
----
-
 ## Environment Variables
 
-```bash
-# Required
-ANTHROPIC_API_KEY=sk-ant-xxxxx
+| Variable             | Description    | Default           |
+| -------------------- | -------------- | ----------------- |
+| `ANTHROPIC_API_KEY`  | Claude API key | Required          |
+| `ANTHROPIC_BASE_URL` | API endpoint   | Anthropic default |
+| `LOG_LEVEL`          | Logging level  | `info`            |
 
-# Optional
-ANTHROPIC_BASE_URL=https://api.anthropic.com  # Custom endpoint
-LOG_LEVEL=info                                  # debug, info, warn, error
-```
-
----
-
-## Package Dependencies
-
-```text
-@agentxjs/types        Type definitions
-       ↑
-@agentxjs/common       Logger facade
-       ↑
-@agentxjs/persistence  Storage layer (drivers as subpath exports)
-       ↑
-@agentxjs/agent        AgentEngine
-       ↑
-@agentxjs/runtime      This package (Runtime + Environment)
-       ↑
-agentxjs               High-level unified API
-```
+## Dependencies
 
----
+- `@agentxjs/agent` - Agent engine and event processing
+- `@agentxjs/common` - Logging, ID generation
+- `@agentxjs/persistence` - Storage layer
+- `@agentxjs/types` - Type definitions
+- `@anthropic-ai/claude-agent-sdk` - Claude SDK integration
+- `rxjs` - Reactive event handling
 
 ## Related Packages
 
-- **[@agentxjs/types](../types)** - Type definitions
-- **[@agentxjs/common](../common)** - Logger facade
-- **[@agentxjs/persistence](../persistence)** - Storage layer with driver subpath exports
-- **[@agentxjs/agent](../agent)** - AgentEngine
-- **[agentxjs](../agentx)** - High-level unified API
+- [@agentxjs/agent](../agent) - Agent engine and event processing
+- [@agentxjs/persistence](../persistence) - Storage layer
+- [@agentxjs/types](../types) - Type definitions
+- [agentxjs](../agentx) - Unified entry point
+
+## Full Documentation
 
----
+See [docs/packages/runtime.md](../../docs/packages/runtime.md) for complete documentation including advanced usage, custom environment factories, and integration examples.
 
 ## License