@agentxjs/core 1.9.1-dev

package/src/runtime/types.ts

@@ -0,0 +1,236 @@
+/**
+ * Runtime Types
+ *
+ * AgentXProvider - Dependency injection container
+ * AgentXRuntime - Runtime integration layer
+ *
+ * Architecture:
+ * ```
+ * ┌─────────────────────────────────────────────────────────────┐
+ * │                      AgentXProvider                         │
+ * │  (Dependency Injection - Platform provides implementations) │
+ * │                                                             │
+ * │  ┌─────────────┐ ┌─────────────┐ ┌───────────────┐         │
+ * │  │ Repositories│ │  Workspace  │ │ DriverFactory │         │
+ * │  │  Container  │ │  Provider   │ │ (per-Agent)   │         │
+ * │  │  Image      │ │             │ │             │           │
+ * │  │  Session    │ │             │ │             │           │
+ * │  └─────────────┘ └─────────────┘ └─────────────┘           │
+ * └─────────────────────────────────────────────────────────────┘
+ *                              │
+ *                              ▼
+ * ┌─────────────────────────────────────────────────────────────┐
+ * │                      AgentXRuntime                          │
+ * │           (Integration - Uses Provider dependencies)        │
+ * │                                                             │
+ * │  ┌─────────────────────────────────────────────────────┐   │
+ * │  │  Agent Lifecycle: create / get / destroy            │   │
+ * │  │  Message Flow: receive → EventBus → Driver          │   │
+ * │  │  Event Subscription: subscribe to agent events      │   │
+ * │  └─────────────────────────────────────────────────────┘   │
+ * └─────────────────────────────────────────────────────────────┘
+ * ```
+ */
+
+import type { ContainerRepository } from "../container/types";
+import type { ImageRepository } from "../image/types";
+import type { SessionRepository } from "../session/types";
+import type { WorkspaceProvider } from "../workspace/types";
+import type { CreateDriver } from "../driver/types";
+import type { EventBus } from "../event/types";
+import type { UserContentPart } from "../agent/types";
+import type { BusEvent } from "../event/types";
+
+// ============================================================================
+// Agent Runtime State
+// ============================================================================
+
+/**
+ * Agent lifecycle states
+ */
+export type AgentLifecycle = "running" | "stopped" | "destroyed";
+
+/**
+ * Runtime Agent - Active agent instance
+ */
+export interface RuntimeAgent {
+  readonly agentId: string;
+  readonly imageId: string;
+  readonly containerId: string;
+  readonly sessionId: string;
+  readonly name: string;
+  readonly lifecycle: AgentLifecycle;
+  readonly createdAt: number;
+}
+
+// ============================================================================
+// AgentXProvider - Dependency Injection
+// ============================================================================
+
+/**
+ * AgentXProvider - Collects all dependencies for runtime
+ *
+ * Platform packages provide implementations of these interfaces.
+ * The provider is passed to AgentXRuntime for integration.
+ */
+export interface AgentXProvider {
+  /**
+   * Container repository for persistence
+   */
+  readonly containerRepository: ContainerRepository;
+
+  /**
+   * Image repository for persistence
+   */
+  readonly imageRepository: ImageRepository;
+
+  /**
+   * Session repository for persistence
+   */
+  readonly sessionRepository: SessionRepository;
+
+  /**
+   * Workspace provider for isolated environments
+   */
+  readonly workspaceProvider: WorkspaceProvider;
+
+  /**
+   * LLM Driver factory function - creates Driver per Agent
+   */
+  readonly createDriver: CreateDriver;
+
+  /**
+   * Event bus for pub/sub
+   */
+  readonly eventBus: EventBus;
+}
+
+// ============================================================================
+// AgentXRuntime - Integration Layer
+// ============================================================================
+
+/**
+ * Agent creation options
+ */
+export interface CreateAgentOptions {
+  /**
+   * Image ID to create agent from
+   */
+  imageId: string;
+
+  /**
+   * Optional agent ID (auto-generated if not provided)
+   */
+  agentId?: string;
+}
+
+/**
+ * Event handler for agent events
+ */
+export type AgentEventHandler = (event: BusEvent) => void;
+
+/**
+ * Subscription handle for unsubscribing
+ */
+export interface Subscription {
+  unsubscribe(): void;
+}
+
+/**
+ * AgentXRuntime - Runtime integration layer
+ *
+ * Integrates all components to provide agent lifecycle management
+ * and message handling.
+ */
+export interface AgentXRuntime {
+  /**
+   * The provider containing all dependencies
+   */
+  readonly provider: AgentXProvider;
+
+  // ==================== Agent Lifecycle ====================
+
+  /**
+   * Create and start an agent from an image
+   */
+  createAgent(options: CreateAgentOptions): Promise<RuntimeAgent>;
+
+  /**
+   * Get an active agent by ID
+   */
+  getAgent(agentId: string): RuntimeAgent | undefined;
+
+  /**
+   * Get all active agents
+   */
+  getAgents(): RuntimeAgent[];
+
+  /**
+   * Get agents by container ID
+   */
+  getAgentsByContainer(containerId: string): RuntimeAgent[];
+
+  /**
+   * Stop an agent (can be resumed)
+   */
+  stopAgent(agentId: string): Promise<void>;
+
+  /**
+   * Resume a stopped agent
+   */
+  resumeAgent(agentId: string): Promise<void>;
+
+  /**
+   * Destroy an agent (cannot be resumed)
+   */
+  destroyAgent(agentId: string): Promise<void>;
+
+  // ==================== Message Handling ====================
+
+  /**
+   * Send a message to an agent
+   *
+   * Emits user_message to EventBus, Driver picks it up and responds.
+   */
+  receive(agentId: string, content: string | UserContentPart[], requestId?: string): Promise<void>;
+
+  /**
+   * Interrupt an agent's current operation
+   */
+  interrupt(agentId: string, requestId?: string): void;
+
+  // ==================== Event Subscription ====================
+
+  /**
+   * Subscribe to events for a specific agent
+   */
+  subscribe(agentId: string, handler: AgentEventHandler): Subscription;
+
+  /**
+   * Subscribe to all events (all agents)
+   */
+  subscribeAll(handler: AgentEventHandler): Subscription;
+
+  // ==================== Cleanup ====================
+
+  /**
+   * Shutdown runtime and cleanup all resources
+   */
+  shutdown(): Promise<void>;
+}
+
+// ============================================================================
+// Factory Types
+// ============================================================================
+
+/**
+ * Configuration for creating AgentXRuntime
+ */
+export interface AgentXRuntimeConfig {
+  provider: AgentXProvider;
+}
+
+/**
+ * Factory function type for creating AgentXRuntime
+ */
+export type CreateAgentXRuntime = (config: AgentXRuntimeConfig) => AgentXRuntime;

package/src/session/Session.ts

@@ -0,0 +1,71 @@
+/**
+ * Session - Manages conversation messages
+ *
+ * Collects messages and persists to storage via SessionRepository.
+ * Pure implementation without EventBus dependency.
+ */
+
+import type { Message } from "../agent/types";
+import type { Session, SessionConfig, SessionRecord, SessionRepository } from "./types";
+
+/**
+ * SessionImpl - Session implementation
+ */
+export class SessionImpl implements Session {
+  readonly sessionId: string;
+  readonly imageId: string;
+  readonly containerId: string;
+  readonly createdAt: number;
+
+  private readonly repository: SessionRepository;
+
+  constructor(config: SessionConfig) {
+    this.sessionId = config.sessionId;
+    this.imageId = config.imageId;
+    this.containerId = config.containerId;
+    this.createdAt = Date.now();
+    this.repository = config.repository;
+  }
+
+  /**
+   * Initialize session in storage
+   */
+  async initialize(): Promise<void> {
+    const record: SessionRecord = {
+      sessionId: this.sessionId,
+      imageId: this.imageId,
+      containerId: this.containerId,
+      createdAt: this.createdAt,
+      updatedAt: this.createdAt,
+    };
+    await this.repository.saveSession(record);
+  }
+
+  /**
+   * Add a message to the session
+   */
+  async addMessage(message: Message): Promise<void> {
+    await this.repository.addMessage(this.sessionId, message);
+  }
+
+  /**
+   * Get all messages in the session
+   */
+  async getMessages(): Promise<Message[]> {
+    return this.repository.getMessages(this.sessionId);
+  }
+
+  /**
+   * Clear all messages in the session
+   */
+  async clear(): Promise<void> {
+    await this.repository.clearMessages(this.sessionId);
+  }
+}
+
+/**
+ * Create a new Session instance
+ */
+export function createSession(config: SessionConfig): Session {
+  return new SessionImpl(config);
+}

package/src/session/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Session Module
+ *
+ * Manages conversation messages for an Image.
+ *
+ * Usage:
+ * ```typescript
+ * import { createSession, type SessionRepository } from "@agentxjs/core/session";
+ *
+ * const session = createSession({
+ *   sessionId: "session-1",
+ *   imageId: "image-1",
+ *   containerId: "container-1",
+ *   repository: mySessionRepository,
+ * });
+ *
+ * await session.initialize();
+ * await session.addMessage(message);
+ * const messages = await session.getMessages();
+ * ```
+ */
+
+export type { SessionRecord, SessionRepository, Session, SessionConfig } from "./types";
+
+export { SessionImpl, createSession } from "./Session";

package/src/session/types.ts

@@ -0,0 +1,77 @@
+/**
+ * Session Types
+ *
+ * Session manages conversation messages for an Image.
+ * Each Image has exactly one Session.
+ */
+
+import type { Message } from "../agent/types";
+
+// ============================================================================
+// Re-export from persistence (storage schema)
+// ============================================================================
+
+export type { SessionRecord, SessionRepository } from "../persistence/types";
+
+// ============================================================================
+// Session Interface
+// ============================================================================
+
+/**
+ * Session - Manages conversation messages
+ */
+export interface Session {
+  /**
+   * Unique session identifier
+   */
+  readonly sessionId: string;
+
+  /**
+   * Associated image ID
+   */
+  readonly imageId: string;
+
+  /**
+   * Container this session belongs to
+   */
+  readonly containerId: string;
+
+  /**
+   * Creation timestamp
+   */
+  readonly createdAt: number;
+
+  /**
+   * Initialize session in storage
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Add a message to the session
+   */
+  addMessage(message: Message): Promise<void>;
+
+  /**
+   * Get all messages in the session
+   */
+  getMessages(): Promise<Message[]>;
+
+  /**
+   * Clear all messages in the session
+   */
+  clear(): Promise<void>;
+}
+
+// ============================================================================
+// Session Configuration
+// ============================================================================
+
+/**
+ * Configuration for creating a Session
+ */
+export interface SessionConfig {
+  sessionId: string;
+  imageId: string;
+  containerId: string;
+  repository: import("../persistence/types").SessionRepository;
+}

package/src/workspace/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Workspace Module
+ *
+ * Abstraction for isolated working environments.
+ * Platform packages provide concrete implementations.
+ *
+ * Usage:
+ * ```typescript
+ * import type { Workspace, WorkspaceProvider } from "@agentxjs/core/workspace";
+ *
+ * // Platform provides implementation
+ * const provider: WorkspaceProvider = new FileWorkspaceProvider({
+ *   basePath: "~/.agentx/workspaces"
+ * });
+ *
+ * // Create workspace for an agent
+ * const workspace = await provider.create({
+ *   containerId: "user-123",
+ *   imageId: "img_xxx",
+ * });
+ *
+ * await workspace.initialize();
+ * console.log(workspace.path); // ~/.agentx/workspaces/user-123/img_xxx
+ * ```
+ */
+
+export type { Workspace, WorkspaceCreateConfig, WorkspaceProvider } from "./types";

package/src/workspace/types.ts

@@ -0,0 +1,131 @@
+/**
+ * Workspace Types
+ *
+ * Workspace is an abstraction for isolated working environments.
+ * Different platforms provide different implementations:
+ * - Node.js: File system based (local directories)
+ * - Cloudflare: R2/KV based (cloud storage)
+ * - Browser: IndexedDB/Memory based
+ *
+ * Architecture:
+ * ```
+ * ┌─────────────────────────────────────────────────────────┐
+ * │                     core/workspace                       │
+ * │  ┌─────────────────────────────────────────────────────┐│
+ * │  │  Workspace (interface)                              ││
+ * │  │  WorkspaceProvider (interface)                      ││
+ * │  └─────────────────────────────────────────────────────┘│
+ * └─────────────────────────────────────────────────────────┘
+ *                           │
+ *          ┌────────────────┼────────────────┐
+ *          ▼                ▼                ▼
+ *   ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
+ *   │ platform-node│ │platform-cf   │ │platform-web  │
+ *   │ FileWorkspace│ │ R2Workspace  │ │ IDBWorkspace │
+ *   └──────────────┘ └──────────────┘ └──────────────┘
+ * ```
+ */
+
+// ============================================================================
+// Workspace Interface
+// ============================================================================
+
+/**
+ * Workspace - Isolated working environment for an Agent
+ *
+ * Provides a location abstraction for Agent file operations.
+ * The actual storage mechanism depends on platform implementation.
+ */
+export interface Workspace {
+  /**
+   * Unique workspace identifier
+   */
+  readonly id: string;
+
+  /**
+   * Human-readable workspace name
+   */
+  readonly name: string;
+
+  /**
+   * Workspace path or URI
+   *
+   * Platform-specific:
+   * - Node.js: Absolute file path (e.g., ~/.agentx/workspaces/xxx/)
+   * - Cloudflare: R2 bucket prefix (e.g., workspaces/xxx/)
+   * - Browser: IndexedDB store name
+   */
+  readonly path: string;
+
+  /**
+   * Initialize workspace (create if not exists)
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Check if workspace exists
+   */
+  exists(): Promise<boolean>;
+
+  /**
+   * Clean up workspace (optional, for temporary workspaces)
+   */
+  cleanup?(): Promise<void>;
+}
+
+// ============================================================================
+// Workspace Provider Interface
+// ============================================================================
+
+/**
+ * Configuration for creating a workspace
+ */
+export interface WorkspaceCreateConfig {
+  /**
+   * Associated container ID
+   */
+  containerId: string;
+
+  /**
+   * Associated image ID
+   */
+  imageId: string;
+
+  /**
+   * Optional custom workspace name
+   */
+  name?: string;
+}
+
+/**
+ * WorkspaceProvider - Factory for creating workspaces
+ *
+ * Platform implementations provide this interface to create
+ * platform-specific workspaces.
+ */
+export interface WorkspaceProvider {
+  /**
+   * Provider name (e.g., "file", "r2", "indexeddb")
+   */
+  readonly type: string;
+
+  /**
+   * Create a new workspace
+   */
+  create(config: WorkspaceCreateConfig): Promise<Workspace>;
+
+  /**
+   * Get an existing workspace by ID
+   */
+  get(workspaceId: string): Promise<Workspace | null>;
+
+  /**
+   * List all workspaces for a container
+   */
+  listByContainer(containerId: string): Promise<Workspace[]>;
+
+  /**
+   * Delete a workspace
+   */
+  delete(workspaceId: string): Promise<void>;
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["src/**/__tests__/**/*", "src/**/*.test.ts", "src/**/*.spec.ts"]
+}