@agentxjs/core 1.9.1-dev

package/src/event/types/session.ts

@@ -0,0 +1,314 @@
+/**
+ * Session Events - Session lifecycle, persist, and action events
+ *
+ * Events for session operations in the event system.
+ */
+
+import type { SystemEvent } from "./base";
+
+// ============================================================================
+// Session Lifecycle Events
+// ============================================================================
+
+/**
+ * Base SessionLifecycleEvent
+ */
+interface BaseSessionLifecycleEvent<T extends string, D = unknown> extends SystemEvent<
+  T,
+  D,
+  "session",
+  "lifecycle",
+  "notification"
+> {}
+
+/**
+ * SessionCreatedEvent - Session was created
+ */
+export interface SessionCreatedEvent extends BaseSessionLifecycleEvent<
+  "session_created",
+  {
+    sessionId: string;
+    imageId: string;
+    containerId: string;
+    title?: string;
+    createdAt: number;
+  }
+> {}
+
+/**
+ * SessionDestroyedEvent - Session was destroyed
+ */
+export interface SessionDestroyedEvent extends BaseSessionLifecycleEvent<
+  "session_destroyed",
+  {
+    sessionId: string;
+    reason?: string;
+  }
+> {}
+
+/**
+ * SessionLifecycleEvent - All session lifecycle events
+ */
+export type SessionLifecycleEvent = SessionCreatedEvent | SessionDestroyedEvent;
+
+/**
+ * Type guard: is this a SessionLifecycleEvent?
+ */
+export function isSessionLifecycleEvent(event: {
+  source?: string;
+  category?: string;
+}): event is SessionLifecycleEvent {
+  return event.source === "session" && event.category === "lifecycle";
+}
+
+// ============================================================================
+// Session Persist Events
+// ============================================================================
+
+/**
+ * Base SessionPersistRequest
+ */
+interface BaseSessionPersistRequest<T extends string, D = unknown> extends SystemEvent<
+  T,
+  D,
+  "session",
+  "persist",
+  "request"
+> {}
+
+/**
+ * Base SessionPersistResult
+ */
+interface BaseSessionPersistResult<T extends string, D = unknown> extends SystemEvent<
+  T,
+  D,
+  "session",
+  "persist",
+  "result"
+> {}
+
+/**
+ * SessionSaveRequest - Request to save session
+ */
+export interface SessionSaveRequest extends BaseSessionPersistRequest<
+  "session_save_request",
+  {
+    sessionId: string;
+    title?: string;
+    metadata?: Record<string, unknown>;
+  }
+> {}
+
+/**
+ * SessionSavedEvent - Session was saved
+ */
+export interface SessionSavedEvent extends BaseSessionPersistResult<
+  "session_saved",
+  {
+    sessionId: string;
+    savedAt: number;
+  }
+> {}
+
+/**
+ * MessagePersistRequest - Request to persist a message
+ */
+export interface MessagePersistRequest extends BaseSessionPersistRequest<
+  "message_persist_request",
+  {
+    sessionId: string;
+    messageId: string;
+    role: "user" | "assistant" | "tool_call" | "tool_result";
+    content: unknown;
+  }
+> {}
+
+/**
+ * MessagePersistedEvent - Message was persisted
+ */
+export interface MessagePersistedEvent extends BaseSessionPersistResult<
+  "message_persisted",
+  {
+    sessionId: string;
+    messageId: string;
+    savedAt: number;
+  }
+> {}
+
+/**
+ * SessionPersistEvent - All session persist events
+ */
+export type SessionPersistEvent =
+  | SessionSaveRequest
+  | SessionSavedEvent
+  | MessagePersistRequest
+  | MessagePersistedEvent;
+
+/**
+ * Session persist request events
+ */
+export type SessionPersistRequestEvent = SessionSaveRequest | MessagePersistRequest;
+
+/**
+ * Session persist result events
+ */
+export type SessionPersistResultEvent = SessionSavedEvent | MessagePersistedEvent;
+
+/**
+ * Type guard: is this a SessionPersistEvent?
+ */
+export function isSessionPersistEvent(event: {
+  source?: string;
+  category?: string;
+}): event is SessionPersistEvent {
+  return event.source === "session" && event.category === "persist";
+}
+
+// ============================================================================
+// Session Action Events
+// ============================================================================
+
+/**
+ * Base SessionActionRequest
+ */
+interface BaseSessionActionRequest<T extends string, D = unknown> extends SystemEvent<
+  T,
+  D,
+  "session",
+  "action",
+  "request"
+> {}
+
+/**
+ * Base SessionActionResult
+ */
+interface BaseSessionActionResult<T extends string, D = unknown> extends SystemEvent<
+  T,
+  D,
+  "session",
+  "action",
+  "result"
+> {}
+
+/**
+ * SessionResumeRequest - Request to resume a session
+ */
+export interface SessionResumeRequest extends BaseSessionActionRequest<
+  "session_resume_request",
+  {
+    sessionId: string;
+    containerId?: string;
+  }
+> {}
+
+/**
+ * SessionResumedEvent - Session was resumed
+ */
+export interface SessionResumedEvent extends BaseSessionActionResult<
+  "session_resumed",
+  {
+    sessionId: string;
+    agentId: string;
+    resumedAt: number;
+  }
+> {}
+
+/**
+ * SessionForkRequest - Request to fork a session
+ */
+export interface SessionForkRequest extends BaseSessionActionRequest<
+  "session_fork_request",
+  {
+    sessionId: string;
+    newTitle?: string;
+  }
+> {}
+
+/**
+ * SessionForkedEvent - Session was forked
+ */
+export interface SessionForkedEvent extends BaseSessionActionResult<
+  "session_forked",
+  {
+    originalSessionId: string;
+    newSessionId: string;
+    newImageId: string;
+    forkedAt: number;
+  }
+> {}
+
+/**
+ * SessionTitleUpdateRequest - Request to update session title
+ */
+export interface SessionTitleUpdateRequest extends BaseSessionActionRequest<
+  "session_title_update_request",
+  {
+    sessionId: string;
+    title: string;
+  }
+> {}
+
+/**
+ * SessionTitleUpdatedEvent - Session title was updated
+ */
+export interface SessionTitleUpdatedEvent extends BaseSessionActionResult<
+  "session_title_updated",
+  {
+    sessionId: string;
+    title: string;
+    updatedAt: number;
+  }
+> {}
+
+/**
+ * SessionActionEvent - All session action events
+ */
+export type SessionActionEvent =
+  | SessionResumeRequest
+  | SessionResumedEvent
+  | SessionForkRequest
+  | SessionForkedEvent
+  | SessionTitleUpdateRequest
+  | SessionTitleUpdatedEvent;
+
+/**
+ * Session action request events
+ */
+export type SessionActionRequestEvent =
+  | SessionResumeRequest
+  | SessionForkRequest
+  | SessionTitleUpdateRequest;
+
+/**
+ * Session action result events
+ */
+export type SessionActionResultEvent =
+  | SessionResumedEvent
+  | SessionForkedEvent
+  | SessionTitleUpdatedEvent;
+
+/**
+ * Type guard: is this a SessionActionEvent?
+ */
+export function isSessionActionEvent(event: {
+  source?: string;
+  category?: string;
+}): event is SessionActionEvent {
+  return event.source === "session" && event.category === "action";
+}
+
+// ============================================================================
+// Session Event Union
+// ============================================================================
+
+/**
+ * SessionEvent - All session events
+ */
+export type SessionEvent = SessionLifecycleEvent | SessionPersistEvent | SessionActionEvent;
+
+/**
+ * Type guard: is this a session event?
+ */
+export function isSessionEvent(event: { source?: string }): event is SessionEvent {
+  return event.source === "session";
+}

package/src/image/Image.ts

@@ -0,0 +1,203 @@
+/**
+ * Image - Persistent conversation entity
+ *
+ * Image is the primary entity that users interact with (displayed as "conversation").
+ * Agent is a transient runtime instance created from Image.
+ */
+
+import { createLogger } from "commonxjs/logger";
+import type { Image, ImageRecord, ImageContext, ImageCreateConfig } from "./types";
+
+const logger = createLogger("image/Image");
+
+/**
+ * ImageImpl - Image implementation
+ */
+export class ImageImpl implements Image {
+  private constructor(
+    private readonly record: ImageRecord,
+    private readonly context: ImageContext
+  ) {}
+
+  // ==================== Getters ====================
+
+  get imageId(): string {
+    return this.record.imageId;
+  }
+
+  get containerId(): string {
+    return this.record.containerId;
+  }
+
+  get sessionId(): string {
+    return this.record.sessionId;
+  }
+
+  get name(): string {
+    return this.record.name;
+  }
+
+  get description(): string | undefined {
+    return this.record.description;
+  }
+
+  get systemPrompt(): string | undefined {
+    return this.record.systemPrompt;
+  }
+
+  get mcpServers() {
+    return this.record.mcpServers;
+  }
+
+  get createdAt(): number {
+    return this.record.createdAt;
+  }
+
+  get updatedAt(): number {
+    return this.record.updatedAt;
+  }
+
+  // ==================== Static Factory Methods ====================
+
+  /**
+   * Create a new image (conversation)
+   */
+  static async create(config: ImageCreateConfig, context: ImageContext): Promise<ImageImpl> {
+    const now = Date.now();
+    const imageId = ImageImpl.generateImageId();
+    const sessionId = ImageImpl.generateSessionId();
+
+    // Create image record
+    const record: ImageRecord = {
+      imageId,
+      containerId: config.containerId,
+      sessionId,
+      name: config.name ?? "New Conversation",
+      description: config.description,
+      systemPrompt: config.systemPrompt,
+      mcpServers: config.mcpServers,
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    // Persist image
+    await context.imageRepository.saveImage(record);
+
+    // Create associated session (for message storage)
+    await context.sessionRepository.saveSession({
+      sessionId,
+      imageId,
+      containerId: config.containerId,
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    logger.info("Image created", {
+      imageId,
+      sessionId,
+      containerId: config.containerId,
+      name: record.name,
+    });
+
+    return new ImageImpl(record, context);
+  }
+
+  /**
+   * Load an existing image from storage
+   */
+  static async load(imageId: string, context: ImageContext): Promise<ImageImpl | null> {
+    const record = await context.imageRepository.findImageById(imageId);
+    if (!record) {
+      logger.debug("Image not found", { imageId });
+      return null;
+    }
+
+    logger.debug("Image loaded", { imageId, name: record.name });
+    return new ImageImpl(record, context);
+  }
+
+  /**
+   * List all images in a container
+   */
+  static async listByContainer(containerId: string, context: ImageContext): Promise<ImageRecord[]> {
+    return context.imageRepository.findImagesByContainerId(containerId);
+  }
+
+  /**
+   * List all images
+   */
+  static async listAll(context: ImageContext): Promise<ImageRecord[]> {
+    return context.imageRepository.findAllImages();
+  }
+
+  // ==================== Instance Methods ====================
+
+  /**
+   * Update image metadata
+   */
+  async update(updates: { name?: string; description?: string }): Promise<Image> {
+    const now = Date.now();
+    const updatedRecord: ImageRecord = {
+      ...this.record,
+      name: updates.name ?? this.record.name,
+      description: updates.description ?? this.record.description,
+      updatedAt: now,
+    };
+
+    await this.context.imageRepository.saveImage(updatedRecord);
+
+    logger.info("Image updated", { imageId: this.imageId, updates });
+    return new ImageImpl(updatedRecord, this.context);
+  }
+
+  /**
+   * Delete this image and its session
+   */
+  async delete(): Promise<void> {
+    // Delete session first (including messages)
+    await this.context.sessionRepository.deleteSession(this.sessionId);
+
+    // Delete image
+    await this.context.imageRepository.deleteImage(this.imageId);
+
+    logger.info("Image deleted", { imageId: this.imageId, sessionId: this.sessionId });
+  }
+
+  /**
+   * Get the underlying record
+   */
+  toRecord(): ImageRecord {
+    return { ...this.record };
+  }
+
+  // ==================== Private Helpers ====================
+
+  private static generateImageId(): string {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, 8);
+    return `img_${timestamp}_${random}`;
+  }
+
+  private static generateSessionId(): string {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, 8);
+    return `sess_${timestamp}_${random}`;
+  }
+}
+
+/**
+ * Create a new Image
+ */
+export async function createImage(
+  config: ImageCreateConfig,
+  context: ImageContext
+): Promise<Image> {
+  return ImageImpl.create(config, context);
+}
+
+/**
+ * Load an existing Image
+ */
+export async function loadImage(imageId: string, context: ImageContext): Promise<Image | null> {
+  return ImageImpl.load(imageId, context);
+}

package/src/image/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Image Module
+ *
+ * Manages persistent conversation entities (Images).
+ *
+ * Usage:
+ * ```typescript
+ * import { createImage, loadImage, type ImageRepository } from "@agentxjs/core/image";
+ *
+ * const context = {
+ *   imageRepository: myImageRepository,
+ *   sessionRepository: mySessionRepository,
+ * };
+ *
+ * // Create new image
+ * const image = await createImage({
+ *   containerId: "container-1",
+ *   name: "My Conversation",
+ *   systemPrompt: "You are helpful",
+ * }, context);
+ *
+ * // Load existing image
+ * const existing = await loadImage("img_xxx", context);
+ * ```
+ */
+
+export type {
+  ImageMetadata,
+  ImageRecord,
+  ImageRepository,
+  Image,
+  ImageContext,
+  ImageCreateConfig,
+} from "./types";
+
+export { ImageImpl, createImage, loadImage } from "./Image";

package/src/image/types.ts

@@ -0,0 +1,77 @@
+/**
+ * Image Types
+ *
+ * Image is the persistent representation of a conversation.
+ * Agent is a transient runtime instance created from Image.
+ *
+ * Lifecycle:
+ * - create() → ImageRecord (persistent) + SessionRecord (for messages)
+ * - run() → Agent (runtime, in-memory)
+ * - stop() / server restart → Agent destroyed, Image remains
+ */
+
+import type { McpServerConfig } from "../driver/types";
+import type { SessionRepository } from "../persistence/types";
+
+// ============================================================================
+// Re-export from persistence (storage schema)
+// ============================================================================
+
+export type { ImageMetadata, ImageRecord, ImageRepository } from "../persistence/types";
+
+// ============================================================================
+// Image Interface
+// ============================================================================
+
+/**
+ * Image - Persistent conversation entity
+ */
+export interface Image {
+  readonly imageId: string;
+  readonly containerId: string;
+  readonly sessionId: string;
+  readonly name: string;
+  readonly description: string | undefined;
+  readonly systemPrompt: string | undefined;
+  readonly mcpServers: Record<string, McpServerConfig> | undefined;
+  readonly createdAt: number;
+  readonly updatedAt: number;
+
+  /**
+   * Update image metadata (name, description)
+   */
+  update(updates: { name?: string; description?: string }): Promise<Image>;
+
+  /**
+   * Delete this image and its session
+   */
+  delete(): Promise<void>;
+
+  /**
+   * Get the underlying record
+   */
+  toRecord(): import("../persistence/types").ImageRecord;
+}
+
+// ============================================================================
+// Image Configuration
+// ============================================================================
+
+/**
+ * Context needed by Image operations
+ */
+export interface ImageContext {
+  imageRepository: import("../persistence/types").ImageRepository;
+  sessionRepository: SessionRepository;
+}
+
+/**
+ * Configuration for creating a new Image
+ */
+export interface ImageCreateConfig {
+  containerId: string;
+  name?: string;
+  description?: string;
+  systemPrompt?: string;
+  mcpServers?: Record<string, McpServerConfig>;
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @agentxjs/core
+ *
+ * Core library for AgentX framework.
+ * Provides types, common utilities, and agent implementation.
+ *
+ * @packageDocumentation
+ */
+
+// ============================================================================
+// Common Utilities
+// ============================================================================
+
+export * from "./common";
+
+// ============================================================================
+// Agent (includes all types)
+// ============================================================================
+
+export * from "./agent";

package/src/mq/OffsetGenerator.ts

@@ -0,0 +1,48 @@
+/**
+ * OffsetGenerator - Generates monotonically increasing offsets
+ *
+ * Format: "{timestamp_base36}-{sequence_padded}"
+ * Example: "lq5x4g2-0001"
+ *
+ * This format ensures:
+ * - Lexicographic ordering matches temporal ordering
+ * - Multiple events in same millisecond get unique offsets
+ * - Human-readable and compact
+ */
+export class OffsetGenerator {
+  private lastTimestamp = 0;
+  private sequence = 0;
+
+  /**
+   * Generate a new offset
+   */
+  generate(): string {
+    const now = Date.now();
+
+    if (now === this.lastTimestamp) {
+      this.sequence++;
+    } else {
+      this.lastTimestamp = now;
+      this.sequence = 0;
+    }
+
+    const timestampPart = now.toString(36);
+    const sequencePart = this.sequence.toString().padStart(4, "0");
+
+    return `${timestampPart}-${sequencePart}`;
+  }
+
+  /**
+   * Compare two offsets
+   * @returns negative if a < b, 0 if a == b, positive if a > b
+   */
+  static compare(a: string, b: string): number {
+    const [aTime, aSeq] = a.split("-");
+    const [bTime, bSeq] = b.split("-");
+
+    const timeDiff = parseInt(aTime, 36) - parseInt(bTime, 36);
+    if (timeDiff !== 0) return timeDiff;
+
+    return parseInt(aSeq) - parseInt(bSeq);
+  }
+}