@agentxjs/types 0.0.9 → 0.2.0

package/dist/LoggerFactory-DZtw0M7U.d.ts

@@ -0,0 +1,129 @@
+/**
+ * LogLevel - Standard log level type
+ *
+ * Defines the severity levels for logging.
+ * Uses string literal types for better readability and type safety.
+ */
+type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+
+/**
+ * Logger - Standard logging 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.
+ */
+
+/**
+ * Logging context metadata
+ */
+type LogContext = Record<string, unknown>;
+/**
+ * Logger interface
+ *
+ * All logger implementations must follow this interface.
+ *
+ * @example
+ * ```typescript
+ * class PinoLogger implements Logger {
+ *   private pino: Pino.Logger;
+ *
+ *   constructor(name: string) {
+ *     this.pino = pino({ name });
+ *   }
+ *
+ *   get name() { return this.pino.name; }
+ *   get level() { return LogLevel.DEBUG; }
+ *
+ *   debug(message: string, context?: LogContext) {
+ *     this.pino.debug(context, message);
+ *   }
+ *   // ... other methods
+ * }
+ * ```
+ */
+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 - Standard logger factory interface
+ *
+ * Factory for creating Logger instances. External implementations
+ * can provide their own LoggerFactory to integrate custom logging
+ * libraries (pino, winston, etc.)
+ *
+ * Similar to SLF4J's LoggerFactory in Java.
+ *
+ * @example
+ * ```typescript
+ * // Custom pino-based factory
+ * const pinoFactory: LoggerFactory = {
+ *   getLogger(name: string): Logger {
+ *     return new PinoLogger(name);
+ *   }
+ * };
+ *
+ * // Inject via Runtime
+ * const runtime = createNodeRuntime({
+ *   loggerFactory: pinoFactory
+ * });
+ * ```
+ */
+
+/**
+ * LoggerFactory interface
+ *
+ * Factory for creating named Logger instances.
+ */
+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;
+}
+
+export type { LogLevel as L, Logger as a, LogContext as b, LoggerFactory as c };

package/dist/Message-Crh81uLL.d.cts

@@ -0,0 +1,45 @@
+import { U as UserMessage, A as AssistantMessage, T as ToolCallMessage, a as ToolResultMessage } from './ToolResultMessage-CRKMSf5d.cjs';
+import { E as ErrorMessage } from './ErrorMessage-BoIh3MIO.cjs';
+
+/**
+ * Message Subtype
+ *
+ * Represents the specific type/category of the message.
+ * Used together with role for serialization and type discrimination.
+ */
+type MessageSubtype = "user" | "assistant" | "tool-call" | "tool-result" | "error";
+/**
+ * Message
+ *
+ * Discriminated union of all message types.
+ * Use `subtype` field for precise type discrimination.
+ *
+ * Role: Who sent it (user, assistant, tool, system, error)
+ * Subtype: What type of message (user, assistant, tool-call, tool-result, error)
+ *
+ * @example
+ * ```typescript
+ * function handleMessage(msg: Message) {
+ *   switch (msg.subtype) {
+ *     case "user":
+ *       console.log(msg.content);
+ *       break;
+ *     case "assistant":
+ *       console.log(msg.content);
+ *       break;
+ *     case "tool-call":
+ *       console.log(msg.toolCall.name);
+ *       break;
+ *     case "tool-result":
+ *       console.log(msg.toolResult.output);
+ *       break;
+ *     case "error":
+ *       console.log(msg.content);
+ *       break;
+ *   }
+ * }
+ * ```
+ */
+type Message = UserMessage | AssistantMessage | ToolCallMessage | ToolResultMessage | ErrorMessage;
+
+export type { Message as M, MessageSubtype as a };

package/dist/Message-DWQUt647.d.ts

@@ -0,0 +1,45 @@
+import { U as UserMessage, A as AssistantMessage, T as ToolCallMessage, a as ToolResultMessage } from './ToolResultMessage-CDG2L7Zv.js';
+import { E as ErrorMessage } from './ErrorMessage-BoIh3MIO.js';
+
+/**
+ * Message Subtype
+ *
+ * Represents the specific type/category of the message.
+ * Used together with role for serialization and type discrimination.
+ */
+type MessageSubtype = "user" | "assistant" | "tool-call" | "tool-result" | "error";
+/**
+ * Message
+ *
+ * Discriminated union of all message types.
+ * Use `subtype` field for precise type discrimination.
+ *
+ * Role: Who sent it (user, assistant, tool, system, error)
+ * Subtype: What type of message (user, assistant, tool-call, tool-result, error)
+ *
+ * @example
+ * ```typescript
+ * function handleMessage(msg: Message) {
+ *   switch (msg.subtype) {
+ *     case "user":
+ *       console.log(msg.content);
+ *       break;
+ *     case "assistant":
+ *       console.log(msg.content);
+ *       break;
+ *     case "tool-call":
+ *       console.log(msg.toolCall.name);
+ *       break;
+ *     case "tool-result":
+ *       console.log(msg.toolResult.output);
+ *       break;
+ *     case "error":
+ *       console.log(msg.content);
+ *       break;
+ *   }
+ * }
+ * ```
+ */
+type Message = UserMessage | AssistantMessage | ToolCallMessage | ToolResultMessage | ErrorMessage;
+
+export type { Message as M, MessageSubtype as a };

package/dist/Persistence-BQkdKomV.d.ts

@@ -0,0 +1,230 @@
+import { I as ImageRecord, a as ImageMetadata } from './ImageRecord-Cn0VcJWk.js';
+import { M as Message } from './Message-DWQUt647.js';
+
+/**
+ * ImageRepository - Persistence interface for agent images
+ */
+
+/**
+ * ImageRepository - Storage operations for images
+ */
+interface ImageRepository {
+    /**
+     * Save an image record (create or update)
+     */
+    saveImage(record: ImageRecord): Promise<void>;
+    /**
+     * Find image by ID
+     */
+    findImageById(imageId: string): Promise<ImageRecord | null>;
+    /**
+     * Find all images
+     */
+    findAllImages(): Promise<ImageRecord[]>;
+    /**
+     * Find images by agent name
+     */
+    findImagesByName(name: string): Promise<ImageRecord[]>;
+    /**
+     * Find images by container ID
+     */
+    findImagesByContainerId(containerId: string): Promise<ImageRecord[]>;
+    /**
+     * Delete image by ID
+     */
+    deleteImage(imageId: string): Promise<void>;
+    /**
+     * Check if image exists
+     */
+    imageExists(imageId: string): Promise<boolean>;
+    /**
+     * Update image metadata (e.g., Claude SDK session ID)
+     * Merges with existing metadata
+     */
+    updateMetadata(imageId: string, metadata: Partial<ImageMetadata>): Promise<void>;
+}
+
+/**
+ * ContainerRecord - Storage record for Container
+ *
+ * Represents a logical container (resource isolation unit).
+ * Each container provides an isolated environment for running Agents.
+ *
+ * In multi-tenant scenarios:
+ * - Application layer maps tenant → containerId
+ * - ContainerManager manages containers
+ * - Each container has its own Sandbox (workspace, LLM config)
+ */
+/**
+ * Container configuration (extensible)
+ *
+ * Future configurations may include:
+ * - Resource quotas (max tokens, max agents)
+ * - Custom workspace path
+ * - LLM provider overrides
+ */
+interface ContainerConfig {
+    [key: string]: unknown;
+}
+/**
+ * ContainerRecord - Persistent container data
+ *
+ * Stored in Repository for container lifecycle management.
+ */
+interface ContainerRecord {
+    /** Unique container identifier (auto-generated on create) */
+    containerId: string;
+    /** Container creation timestamp */
+    createdAt: number;
+    /** Last update timestamp */
+    updatedAt: number;
+    /** Container configuration (extensible for future needs) */
+    config?: ContainerConfig;
+}
+
+/**
+ * ContainerRepository - Persistence interface for containers
+ */
+
+/**
+ * ContainerRepository - Storage operations for containers
+ */
+interface ContainerRepository {
+    /**
+     * Save a container record (create or update)
+     */
+    saveContainer(record: ContainerRecord): Promise<void>;
+    /**
+     * Find container by ID
+     */
+    findContainerById(containerId: string): Promise<ContainerRecord | null>;
+    /**
+     * Find all containers
+     */
+    findAllContainers(): Promise<ContainerRecord[]>;
+    /**
+     * Delete container by ID
+     */
+    deleteContainer(containerId: string): Promise<void>;
+    /**
+     * Check if container exists
+     */
+    containerExists(containerId: string): Promise<boolean>;
+}
+
+/**
+ * SessionRecord - Storage schema for Session persistence
+ *
+ * Session stores conversation messages for an Image.
+ * Each Image has exactly one Session.
+ */
+/**
+ * Session storage record
+ */
+interface SessionRecord {
+    /**
+     * Unique session identifier
+     */
+    sessionId: string;
+    /**
+     * Associated image ID (owner of this session)
+     */
+    imageId: string;
+    /**
+     * Container this session belongs to
+     */
+    containerId: string;
+    /**
+     * Creation timestamp (Unix milliseconds)
+     */
+    createdAt: number;
+    /**
+     * Last update timestamp (Unix milliseconds)
+     */
+    updatedAt: number;
+}
+
+/**
+ * SessionRepository - Persistence interface for sessions
+ */
+
+/**
+ * SessionRepository - Storage operations for sessions
+ */
+interface SessionRepository {
+    /**
+     * Save a session record (create or update)
+     */
+    saveSession(record: SessionRecord): Promise<void>;
+    /**
+     * Find session by ID
+     */
+    findSessionById(sessionId: string): Promise<SessionRecord | null>;
+    /**
+     * Find session by image ID
+     */
+    findSessionByImageId(imageId: string): Promise<SessionRecord | null>;
+    /**
+     * Find all sessions for a container
+     */
+    findSessionsByContainerId(containerId: string): Promise<SessionRecord[]>;
+    /**
+     * Find all sessions
+     */
+    findAllSessions(): Promise<SessionRecord[]>;
+    /**
+     * Delete session by ID
+     */
+    deleteSession(sessionId: string): Promise<void>;
+    /**
+     * Check if session exists
+     */
+    sessionExists(sessionId: string): Promise<boolean>;
+    /**
+     * Add a message to a session
+     */
+    addMessage(sessionId: string, message: Message): Promise<void>;
+    /**
+     * Get all messages for a session
+     */
+    getMessages(sessionId: string): Promise<Message[]>;
+    /**
+     * Clear all messages for a session
+     */
+    clearMessages(sessionId: string): Promise<void>;
+}
+
+/**
+ * Persistence - Unified storage interface
+ *
+ * Symmetric with Runtime:
+ * - Runtime: event handling
+ * - Persistence: data storage
+ *
+ * @example
+ * ```typescript
+ * // Access via domain-specific repositories
+ * await persistence.images.findById(imageId);
+ * await persistence.sessions.findByContainerId(containerId);
+ * ```
+ */
+
+/**
+ * Persistence - Unified storage interface with domain-specific access
+ */
+interface Persistence {
+    /**
+     * Image storage operations
+     */
+    readonly images: ImageRepository;
+    /**
+     * Container storage operations
+     */
+    readonly containers: ContainerRepository;
+    /**
+     * Session storage operations
+     */
+    readonly sessions: SessionRepository;
+}
+
+export type { ContainerRepository as C, ImageRepository as I, Persistence as P, SessionRepository as S, ContainerRecord as a, SessionRecord as b, ContainerConfig as c };

package/dist/Persistence-Dr70FEBh.d.cts

@@ -0,0 +1,230 @@
+import { I as ImageRecord, a as ImageMetadata } from './ImageRecord-Cn0VcJWk.cjs';
+import { M as Message } from './Message-Crh81uLL.cjs';
+
+/**
+ * ImageRepository - Persistence interface for agent images
+ */
+
+/**
+ * ImageRepository - Storage operations for images
+ */
+interface ImageRepository {
+    /**
+     * Save an image record (create or update)
+     */
+    saveImage(record: ImageRecord): Promise<void>;
+    /**
+     * Find image by ID
+     */
+    findImageById(imageId: string): Promise<ImageRecord | null>;
+    /**
+     * Find all images
+     */
+    findAllImages(): Promise<ImageRecord[]>;
+    /**
+     * Find images by agent name
+     */
+    findImagesByName(name: string): Promise<ImageRecord[]>;
+    /**
+     * Find images by container ID
+     */
+    findImagesByContainerId(containerId: string): Promise<ImageRecord[]>;
+    /**
+     * Delete image by ID
+     */
+    deleteImage(imageId: string): Promise<void>;
+    /**
+     * Check if image exists
+     */
+    imageExists(imageId: string): Promise<boolean>;
+    /**
+     * Update image metadata (e.g., Claude SDK session ID)
+     * Merges with existing metadata
+     */
+    updateMetadata(imageId: string, metadata: Partial<ImageMetadata>): Promise<void>;
+}
+
+/**
+ * ContainerRecord - Storage record for Container
+ *
+ * Represents a logical container (resource isolation unit).
+ * Each container provides an isolated environment for running Agents.
+ *
+ * In multi-tenant scenarios:
+ * - Application layer maps tenant → containerId
+ * - ContainerManager manages containers
+ * - Each container has its own Sandbox (workspace, LLM config)
+ */
+/**
+ * Container configuration (extensible)
+ *
+ * Future configurations may include:
+ * - Resource quotas (max tokens, max agents)
+ * - Custom workspace path
+ * - LLM provider overrides
+ */
+interface ContainerConfig {
+    [key: string]: unknown;
+}
+/**
+ * ContainerRecord - Persistent container data
+ *
+ * Stored in Repository for container lifecycle management.
+ */
+interface ContainerRecord {
+    /** Unique container identifier (auto-generated on create) */
+    containerId: string;
+    /** Container creation timestamp */
+    createdAt: number;
+    /** Last update timestamp */
+    updatedAt: number;
+    /** Container configuration (extensible for future needs) */
+    config?: ContainerConfig;
+}
+
+/**
+ * ContainerRepository - Persistence interface for containers
+ */
+
+/**
+ * ContainerRepository - Storage operations for containers
+ */
+interface ContainerRepository {
+    /**
+     * Save a container record (create or update)
+     */
+    saveContainer(record: ContainerRecord): Promise<void>;
+    /**
+     * Find container by ID
+     */
+    findContainerById(containerId: string): Promise<ContainerRecord | null>;
+    /**
+     * Find all containers
+     */
+    findAllContainers(): Promise<ContainerRecord[]>;
+    /**
+     * Delete container by ID
+     */
+    deleteContainer(containerId: string): Promise<void>;
+    /**
+     * Check if container exists
+     */
+    containerExists(containerId: string): Promise<boolean>;
+}
+
+/**
+ * SessionRecord - Storage schema for Session persistence
+ *
+ * Session stores conversation messages for an Image.
+ * Each Image has exactly one Session.
+ */
+/**
+ * Session storage record
+ */
+interface SessionRecord {
+    /**
+     * Unique session identifier
+     */
+    sessionId: string;
+    /**
+     * Associated image ID (owner of this session)
+     */
+    imageId: string;
+    /**
+     * Container this session belongs to
+     */
+    containerId: string;
+    /**
+     * Creation timestamp (Unix milliseconds)
+     */
+    createdAt: number;
+    /**
+     * Last update timestamp (Unix milliseconds)
+     */
+    updatedAt: number;
+}
+
+/**
+ * SessionRepository - Persistence interface for sessions
+ */
+
+/**
+ * SessionRepository - Storage operations for sessions
+ */
+interface SessionRepository {
+    /**
+     * Save a session record (create or update)
+     */
+    saveSession(record: SessionRecord): Promise<void>;
+    /**
+     * Find session by ID
+     */
+    findSessionById(sessionId: string): Promise<SessionRecord | null>;
+    /**
+     * Find session by image ID
+     */
+    findSessionByImageId(imageId: string): Promise<SessionRecord | null>;
+    /**
+     * Find all sessions for a container
+     */
+    findSessionsByContainerId(containerId: string): Promise<SessionRecord[]>;
+    /**
+     * Find all sessions
+     */
+    findAllSessions(): Promise<SessionRecord[]>;
+    /**
+     * Delete session by ID
+     */
+    deleteSession(sessionId: string): Promise<void>;
+    /**
+     * Check if session exists
+     */
+    sessionExists(sessionId: string): Promise<boolean>;
+    /**
+     * Add a message to a session
+     */
+    addMessage(sessionId: string, message: Message): Promise<void>;
+    /**
+     * Get all messages for a session
+     */
+    getMessages(sessionId: string): Promise<Message[]>;
+    /**
+     * Clear all messages for a session
+     */
+    clearMessages(sessionId: string): Promise<void>;
+}
+
+/**
+ * Persistence - Unified storage interface
+ *
+ * Symmetric with Runtime:
+ * - Runtime: event handling
+ * - Persistence: data storage
+ *
+ * @example
+ * ```typescript
+ * // Access via domain-specific repositories
+ * await persistence.images.findById(imageId);
+ * await persistence.sessions.findByContainerId(containerId);
+ * ```
+ */
+
+/**
+ * Persistence - Unified storage interface with domain-specific access
+ */
+interface Persistence {
+    /**
+     * Image storage operations
+     */
+    readonly images: ImageRepository;
+    /**
+     * Container storage operations
+     */
+    readonly containers: ContainerRepository;
+    /**
+     * Session storage operations
+     */
+    readonly sessions: SessionRepository;
+}
+
+export type { ContainerRepository as C, ImageRepository as I, Persistence as P, SessionRepository as S, ContainerRecord as a, SessionRecord as b, ContainerConfig as c };

package/dist/StopReason-D4DthB1h.d.cts

@@ -0,0 +1,39 @@
+/**
+ * Reason why the LLM stopped generating
+ *
+ * Based on common stop reasons across multiple LLM providers:
+ * - Anthropic Claude: end_turn, max_tokens, tool_use, stop_sequence
+ * - OpenAI: stop, length, tool_calls, content_filter
+ * - Vercel AI SDK: stop, length, tool-calls, content-filter, error, other
+ */
+type StopReason = 
+/**
+ * Natural completion - model decided to stop
+ */
+"end_turn"
+/**
+ * Reached maximum token limit
+ */
+ | "max_tokens"
+/**
+ * Model requested tool usage
+ */
+ | "tool_use"
+/**
+ * Encountered a custom stop sequence
+ */
+ | "stop_sequence"
+/**
+ * Content filter triggered
+ */
+ | "content_filter"
+/**
+ * Error occurred during generation
+ */
+ | "error"
+/**
+ * Other/unknown reason
+ */
+ | "other";
+
+export type { StopReason as S };