@agentxjs/core 1.9.1-dev

package/src/common/logger/types.ts

@@ -0,0 +1,98 @@
+/**
+ * Logger type definitions
+ *
+ * Self-contained types for the logger module.
+ * No external dependencies required.
+ */
+
+/**
+ * LogLevel - Standard log level type
+ *
+ * Defines the severity levels for logging.
+ * Uses string literal types for better readability and type safety.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+
+/**
+ * Logging context metadata
+ */
+export type LogContext = Record<string, unknown>;
+
+/**
+ * Logger interface
+ *
+ * Platform-agnostic logging interface that can be implemented
+ * by any logging library (console, pino, winston, etc.)
+ *
+ * Similar to SLF4J's Logger interface in Java.
+ */
+export interface Logger {
+  /**
+   * Logger name (typically class name or module path)
+   */
+  readonly name: string;
+
+  /**
+   * Current log level
+   */
+  readonly level: LogLevel;
+
+  /**
+   * Log debug message
+   */
+  debug(message: string, context?: LogContext): void;
+
+  /**
+   * Log info message
+   */
+  info(message: string, context?: LogContext): void;
+
+  /**
+   * Log warning message
+   */
+  warn(message: string, context?: LogContext): void;
+
+  /**
+   * Log error message or Error object
+   */
+  error(message: string | Error, context?: LogContext): void;
+
+  /**
+   * Check if debug level is enabled
+   */
+  isDebugEnabled(): boolean;
+
+  /**
+   * Check if info level is enabled
+   */
+  isInfoEnabled(): boolean;
+
+  /**
+   * Check if warn level is enabled
+   */
+  isWarnEnabled(): boolean;
+
+  /**
+   * Check if error level is enabled
+   */
+  isErrorEnabled(): boolean;
+}
+
+/**
+ * LoggerFactory interface
+ *
+ * Factory for creating named Logger instances.
+ * External implementations can provide their own LoggerFactory
+ * to integrate custom logging libraries (pino, winston, etc.)
+ *
+ * Similar to SLF4J's LoggerFactory in Java.
+ */
+export interface LoggerFactory {
+  /**
+   * Get or create a logger with the specified name
+   *
+   * @param name - Logger name (typically class name or module path)
+   * @returns Logger instance
+   */
+  getLogger(name: string): Logger;
+}

package/src/container/Container.ts

@@ -0,0 +1,185 @@
+/**
+ * Container - Resource isolation unit
+ *
+ * Container provides an isolated environment for Images and Agents.
+ * Each container can have multiple Images (conversations).
+ */
+
+import { createLogger } from "commonxjs/logger";
+import type { ContainerRecord } from "../persistence/types";
+import type { Container, ContainerContext, ContainerCreateConfig } from "./types";
+
+const logger = createLogger("container/Container");
+
+/**
+ * ContainerImpl - Container implementation
+ */
+export class ContainerImpl implements Container {
+  private constructor(
+    private readonly record: ContainerRecord,
+    private readonly context: ContainerContext
+  ) {}
+
+  // ==================== Getters ====================
+
+  get containerId(): string {
+    return this.record.containerId;
+  }
+
+  get createdAt(): number {
+    return this.record.createdAt;
+  }
+
+  get updatedAt(): number {
+    return this.record.updatedAt;
+  }
+
+  get config(): Record<string, unknown> | undefined {
+    return this.record.config;
+  }
+
+  // ==================== Static Factory Methods ====================
+
+  /**
+   * Create a new container
+   */
+  static async create(
+    config: ContainerCreateConfig,
+    context: ContainerContext
+  ): Promise<ContainerImpl> {
+    const now = Date.now();
+    const containerId = config.containerId ?? ContainerImpl.generateContainerId();
+
+    const record: ContainerRecord = {
+      containerId,
+      createdAt: now,
+      updatedAt: now,
+      config: config.config,
+    };
+
+    await context.containerRepository.saveContainer(record);
+
+    logger.info("Container created", { containerId });
+
+    return new ContainerImpl(record, context);
+  }
+
+  /**
+   * Load an existing container from storage
+   */
+  static async load(containerId: string, context: ContainerContext): Promise<ContainerImpl | null> {
+    const record = await context.containerRepository.findContainerById(containerId);
+    if (!record) {
+      logger.debug("Container not found", { containerId });
+      return null;
+    }
+
+    logger.debug("Container loaded", { containerId });
+    return new ContainerImpl(record, context);
+  }
+
+  /**
+   * Get or create a container
+   */
+  static async getOrCreate(containerId: string, context: ContainerContext): Promise<ContainerImpl> {
+    const existing = await ContainerImpl.load(containerId, context);
+    if (existing) {
+      return existing;
+    }
+
+    return ContainerImpl.create({ containerId }, context);
+  }
+
+  /**
+   * List all containers
+   */
+  static async listAll(context: ContainerContext): Promise<ContainerRecord[]> {
+    return context.containerRepository.findAllContainers();
+  }
+
+  // ==================== Instance Methods ====================
+
+  /**
+   * Update container configuration
+   */
+  async update(updates: { config?: Record<string, unknown> }): Promise<Container> {
+    const now = Date.now();
+    const updatedRecord: ContainerRecord = {
+      ...this.record,
+      config: updates.config ?? this.record.config,
+      updatedAt: now,
+    };
+
+    await this.context.containerRepository.saveContainer(updatedRecord);
+
+    logger.info("Container updated", { containerId: this.containerId, updates });
+    return new ContainerImpl(updatedRecord, this.context);
+  }
+
+  /**
+   * Delete this container and all its resources
+   */
+  async delete(): Promise<void> {
+    // Find all images in this container
+    const images = await this.context.imageRepository.findImagesByContainerId(this.containerId);
+
+    // Delete all images and their sessions
+    for (const image of images) {
+      await this.context.sessionRepository.deleteSession(image.sessionId);
+      await this.context.imageRepository.deleteImage(image.imageId);
+    }
+
+    // Delete container
+    await this.context.containerRepository.deleteContainer(this.containerId);
+
+    logger.info("Container deleted", {
+      containerId: this.containerId,
+      imagesDeleted: images.length,
+    });
+  }
+
+  /**
+   * Get the underlying record
+   */
+  toRecord(): ContainerRecord {
+    return { ...this.record };
+  }
+
+  // ==================== Private Helpers ====================
+
+  private static generateContainerId(): string {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, 8);
+    return `ctr_${timestamp}_${random}`;
+  }
+}
+
+/**
+ * Create a new Container
+ */
+export async function createContainer(
+  config: ContainerCreateConfig,
+  context: ContainerContext
+): Promise<Container> {
+  return ContainerImpl.create(config, context);
+}
+
+/**
+ * Load an existing Container
+ */
+export async function loadContainer(
+  containerId: string,
+  context: ContainerContext
+): Promise<Container | null> {
+  return ContainerImpl.load(containerId, context);
+}
+
+/**
+ * Get or create a Container
+ */
+export async function getOrCreateContainer(
+  containerId: string,
+  context: ContainerContext
+): Promise<Container> {
+  return ContainerImpl.getOrCreate(containerId, context);
+}

package/src/container/index.ts

@@ -0,0 +1,44 @@
+/**
+ * Container Module
+ *
+ * Manages resource isolation containers.
+ *
+ * Usage:
+ * ```typescript
+ * import {
+ *   createContainer,
+ *   loadContainer,
+ *   getOrCreateContainer,
+ *   type ContainerRepository,
+ * } from "@agentxjs/core/container";
+ *
+ * const context = {
+ *   containerRepository: myContainerRepository,
+ *   imageRepository: myImageRepository,
+ *   sessionRepository: mySessionRepository,
+ * };
+ *
+ * // Create new container
+ * const container = await createContainer({
+ *   containerId: "user-123",
+ *   config: { maxAgents: 10 },
+ * }, context);
+ *
+ * // Load existing container
+ * const existing = await loadContainer("user-123", context);
+ *
+ * // Get or create
+ * const container = await getOrCreateContainer("user-123", context);
+ * ```
+ */
+
+export type {
+  ContainerRecord,
+  ContainerConfig,
+  ContainerRepository,
+  Container,
+  ContainerContext,
+  ContainerCreateConfig,
+} from "./types";
+
+export { ContainerImpl, createContainer, loadContainer, getOrCreateContainer } from "./Container";

package/src/container/types.ts

@@ -0,0 +1,71 @@
+/**
+ * Container Types
+ *
+ * Container is the resource isolation unit.
+ * Each container provides an isolated environment for Images and Agents.
+ *
+ * Lifecycle:
+ * - create() → ContainerRecord (persistent)
+ * - Container manages multiple Images/Agents within its boundary
+ */
+
+import type { ImageRepository } from "../image/types";
+import type { SessionRepository } from "../session/types";
+
+// ============================================================================
+// Re-export from persistence (storage schema)
+// ============================================================================
+
+export type { ContainerRecord, ContainerConfig, ContainerRepository } from "../persistence/types";
+
+// ============================================================================
+// Container Interface
+// ============================================================================
+
+/**
+ * Container - Resource isolation unit
+ *
+ * Manages Images and Agents within an isolated boundary.
+ */
+export interface Container {
+  readonly containerId: string;
+  readonly createdAt: number;
+  readonly updatedAt: number;
+  readonly config: Record<string, unknown> | undefined;
+
+  /**
+   * Update container configuration
+   */
+  update(updates: { config?: Record<string, unknown> }): Promise<Container>;
+
+  /**
+   * Delete this container and all its resources
+   */
+  delete(): Promise<void>;
+
+  /**
+   * Get the underlying record
+   */
+  toRecord(): import("../persistence/types").ContainerRecord;
+}
+
+// ============================================================================
+// Container Configuration
+// ============================================================================
+
+/**
+ * Context needed by Container operations
+ */
+export interface ContainerContext {
+  containerRepository: import("../persistence/types").ContainerRepository;
+  imageRepository: ImageRepository;
+  sessionRepository: SessionRepository;
+}
+
+/**
+ * Configuration for creating a new Container
+ */
+export interface ContainerCreateConfig {
+  containerId?: string;
+  config?: Record<string, unknown>;
+}

package/src/driver/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Driver Module
+ *
+ * Provides interfaces for LLM communication:
+ * - Driver: Single session communication with LLM
+ * - DriverConfig: Configuration for LLM connection
+ * - CreateDriver: Factory function type
+ *
+ * Key Design:
+ * - Clear input/output boundary (for recording/playback)
+ * - Single responsibility: only handle session communication
+ * - Configuration defined by us (capability boundary)
+ *
+ * Implementations are provided by platform packages:
+ * - @agentxjs/claude-driver: Claude Agent SDK driver
+ */
+
+export type {
+  // Configuration
+  McpServerConfig,
+  DriverConfig,
+  DriverState,
+
+  // Core Interface
+  Driver,
+  CreateDriver,
+
+  // Stream Events
+  StreamEvent,
+  StopReason,
+  MessageStartEvent,
+  MessageStopEvent,
+  TextDeltaEvent,
+  ToolUseStartEvent,
+  InputJsonDeltaEvent,
+  ToolUseStopEvent,
+  ToolResultEvent,
+  ErrorEvent,
+  InterruptedEvent,
+  DriverStreamEvent,
+  DriverStreamEventType,
+} from "./types";