@agentxjs/types 0.0.9 → 0.2.0

package/dist/DriveableEvent-Bj7nn-Uk.d.ts

@@ -0,0 +1,161 @@
+import { S as SystemEvent } from './SystemEvent-CPvvxdMQ.js';
+import { S as StopReason } from './StopReason-D4DthB1h.js';
+
+/**
+ * DriveableEvent - Events from LLM that can drive Agent
+ *
+ * These are environment events with:
+ * - source: "environment"
+ * - category: "stream"
+ * - intent: "notification"
+ *
+ * Flow:
+ * 1. Receptor receives from Claude SDK
+ * 2. Receptor emits DriveableEvent to SystemBus
+ * 3. BusDriver listens and forwards to Agent
+ * 4. Agent Engine processes the event
+ */
+
+/**
+ * Base interface for all LLM stream events
+ *
+ * All DriveableEvents have:
+ * - source: "environment" (from external LLM)
+ * - category: "stream" (streaming output)
+ * - intent: "notification" (informational, no action needed)
+ * - requestId: correlation with the original request
+ * - context: agent/image/session scope (inherited from SystemEvent)
+ */
+interface BaseStreamEvent<T extends string, D = unknown> extends SystemEvent<T, D, "environment", "stream", "notification"> {
+    /**
+     * Content block index (for multi-block responses)
+     */
+    index?: number;
+    /**
+     * Request ID for correlating events with the original message_send_request
+     */
+    requestId?: string;
+}
+/**
+ * MessageStartEvent - Emitted when streaming message begins
+ */
+interface MessageStartEvent extends BaseStreamEvent<"message_start", {
+    message: {
+        id: string;
+        model: string;
+    };
+}> {
+}
+/**
+ * MessageDeltaEvent - Emitted with message-level updates
+ */
+interface MessageDeltaEvent extends BaseStreamEvent<"message_delta", {
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}> {
+}
+/**
+ * MessageStopEvent - Emitted when streaming message completes
+ */
+interface MessageStopEvent extends BaseStreamEvent<"message_stop", {
+    stopReason?: StopReason;
+    stopSequence?: string;
+}> {
+}
+/**
+ * TextContentBlockStartEvent - Text block started
+ */
+interface TextContentBlockStartEvent extends BaseStreamEvent<"text_content_block_start", Record<string, never>> {
+    index: number;
+}
+/**
+ * TextDeltaEvent - Incremental text output
+ */
+interface TextDeltaEvent extends BaseStreamEvent<"text_delta", {
+    text: string;
+}> {
+}
+/**
+ * TextContentBlockStopEvent - Text block completed
+ */
+interface TextContentBlockStopEvent extends BaseStreamEvent<"text_content_block_stop", Record<string, never>> {
+    index: number;
+}
+/**
+ * ToolUseContentBlockStartEvent - Tool use block started
+ */
+interface ToolUseContentBlockStartEvent extends BaseStreamEvent<"tool_use_content_block_start", {
+    id: string;
+    name: string;
+}> {
+    index: number;
+}
+/**
+ * InputJsonDeltaEvent - Incremental tool input JSON
+ */
+interface InputJsonDeltaEvent extends BaseStreamEvent<"input_json_delta", {
+    partialJson: string;
+}> {
+    index: number;
+}
+/**
+ * ToolUseContentBlockStopEvent - Tool use block completed
+ */
+interface ToolUseContentBlockStopEvent extends BaseStreamEvent<"tool_use_content_block_stop", Record<string, never>> {
+    index: number;
+}
+/**
+ * ToolCallEvent - Tool call ready for execution
+ */
+interface ToolCallEvent extends BaseStreamEvent<"tool_call", {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}> {
+}
+/**
+ * ToolResultEvent - Tool execution result
+ */
+interface ToolResultEvent extends BaseStreamEvent<"tool_result", {
+    toolUseId: string;
+    result: unknown;
+    isError?: boolean;
+}> {
+}
+/**
+ * InterruptedEvent - Stream interrupted
+ */
+interface InterruptedEvent extends BaseStreamEvent<"interrupted", {
+    reason: "user_interrupt" | "timeout" | "error" | "system";
+}> {
+}
+/**
+ * ErrorReceivedEvent - Error received from environment (e.g., Claude API error)
+ *
+ * This event drives the MealyMachine to produce:
+ * - error_occurred (StateEvent) → state transitions to "error"
+ * - error_message (MessageEvent) → displayed in chat
+ */
+interface ErrorReceivedEvent extends BaseStreamEvent<"error_received", {
+    /** Error message (human-readable) */
+    message: string;
+    /** Error code (e.g., "rate_limit_error", "api_error", "overloaded_error") */
+    errorCode?: string;
+}> {
+}
+/**
+ * DriveableEvent - All events that can drive Agent
+ */
+type DriveableEvent = MessageStartEvent | MessageDeltaEvent | MessageStopEvent | TextContentBlockStartEvent | TextDeltaEvent | TextContentBlockStopEvent | ToolUseContentBlockStartEvent | InputJsonDeltaEvent | ToolUseContentBlockStopEvent | ToolCallEvent | ToolResultEvent | InterruptedEvent | ErrorReceivedEvent;
+/**
+ * DriveableEventType - String literal union of all driveable event types
+ */
+type DriveableEventType = DriveableEvent["type"];
+/**
+ * Type guard: is this a DriveableEvent?
+ */
+declare function isDriveableEvent(event: SystemEvent): event is DriveableEvent;
+
+export { type DriveableEvent as D, type ErrorReceivedEvent as E, type InputJsonDeltaEvent as I, type MessageStartEvent as M, type TextContentBlockStartEvent as T, type DriveableEventType as a, type MessageDeltaEvent as b, type MessageStopEvent as c, type TextDeltaEvent as d, type TextContentBlockStopEvent as e, type ToolUseContentBlockStartEvent as f, type ToolUseContentBlockStopEvent as g, type ToolCallEvent as h, type ToolResultEvent as i, type InterruptedEvent as j, isDriveableEvent as k };

package/dist/DriveableEvent-CCMC1h_C.d.cts

@@ -0,0 +1,161 @@
+import { S as SystemEvent } from './SystemEvent-CPvvxdMQ.cjs';
+import { S as StopReason } from './StopReason-D4DthB1h.cjs';
+
+/**
+ * DriveableEvent - Events from LLM that can drive Agent
+ *
+ * These are environment events with:
+ * - source: "environment"
+ * - category: "stream"
+ * - intent: "notification"
+ *
+ * Flow:
+ * 1. Receptor receives from Claude SDK
+ * 2. Receptor emits DriveableEvent to SystemBus
+ * 3. BusDriver listens and forwards to Agent
+ * 4. Agent Engine processes the event
+ */
+
+/**
+ * Base interface for all LLM stream events
+ *
+ * All DriveableEvents have:
+ * - source: "environment" (from external LLM)
+ * - category: "stream" (streaming output)
+ * - intent: "notification" (informational, no action needed)
+ * - requestId: correlation with the original request
+ * - context: agent/image/session scope (inherited from SystemEvent)
+ */
+interface BaseStreamEvent<T extends string, D = unknown> extends SystemEvent<T, D, "environment", "stream", "notification"> {
+    /**
+     * Content block index (for multi-block responses)
+     */
+    index?: number;
+    /**
+     * Request ID for correlating events with the original message_send_request
+     */
+    requestId?: string;
+}
+/**
+ * MessageStartEvent - Emitted when streaming message begins
+ */
+interface MessageStartEvent extends BaseStreamEvent<"message_start", {
+    message: {
+        id: string;
+        model: string;
+    };
+}> {
+}
+/**
+ * MessageDeltaEvent - Emitted with message-level updates
+ */
+interface MessageDeltaEvent extends BaseStreamEvent<"message_delta", {
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}> {
+}
+/**
+ * MessageStopEvent - Emitted when streaming message completes
+ */
+interface MessageStopEvent extends BaseStreamEvent<"message_stop", {
+    stopReason?: StopReason;
+    stopSequence?: string;
+}> {
+}
+/**
+ * TextContentBlockStartEvent - Text block started
+ */
+interface TextContentBlockStartEvent extends BaseStreamEvent<"text_content_block_start", Record<string, never>> {
+    index: number;
+}
+/**
+ * TextDeltaEvent - Incremental text output
+ */
+interface TextDeltaEvent extends BaseStreamEvent<"text_delta", {
+    text: string;
+}> {
+}
+/**
+ * TextContentBlockStopEvent - Text block completed
+ */
+interface TextContentBlockStopEvent extends BaseStreamEvent<"text_content_block_stop", Record<string, never>> {
+    index: number;
+}
+/**
+ * ToolUseContentBlockStartEvent - Tool use block started
+ */
+interface ToolUseContentBlockStartEvent extends BaseStreamEvent<"tool_use_content_block_start", {
+    id: string;
+    name: string;
+}> {
+    index: number;
+}
+/**
+ * InputJsonDeltaEvent - Incremental tool input JSON
+ */
+interface InputJsonDeltaEvent extends BaseStreamEvent<"input_json_delta", {
+    partialJson: string;
+}> {
+    index: number;
+}
+/**
+ * ToolUseContentBlockStopEvent - Tool use block completed
+ */
+interface ToolUseContentBlockStopEvent extends BaseStreamEvent<"tool_use_content_block_stop", Record<string, never>> {
+    index: number;
+}
+/**
+ * ToolCallEvent - Tool call ready for execution
+ */
+interface ToolCallEvent extends BaseStreamEvent<"tool_call", {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}> {
+}
+/**
+ * ToolResultEvent - Tool execution result
+ */
+interface ToolResultEvent extends BaseStreamEvent<"tool_result", {
+    toolUseId: string;
+    result: unknown;
+    isError?: boolean;
+}> {
+}
+/**
+ * InterruptedEvent - Stream interrupted
+ */
+interface InterruptedEvent extends BaseStreamEvent<"interrupted", {
+    reason: "user_interrupt" | "timeout" | "error" | "system";
+}> {
+}
+/**
+ * ErrorReceivedEvent - Error received from environment (e.g., Claude API error)
+ *
+ * This event drives the MealyMachine to produce:
+ * - error_occurred (StateEvent) → state transitions to "error"
+ * - error_message (MessageEvent) → displayed in chat
+ */
+interface ErrorReceivedEvent extends BaseStreamEvent<"error_received", {
+    /** Error message (human-readable) */
+    message: string;
+    /** Error code (e.g., "rate_limit_error", "api_error", "overloaded_error") */
+    errorCode?: string;
+}> {
+}
+/**
+ * DriveableEvent - All events that can drive Agent
+ */
+type DriveableEvent = MessageStartEvent | MessageDeltaEvent | MessageStopEvent | TextContentBlockStartEvent | TextDeltaEvent | TextContentBlockStopEvent | ToolUseContentBlockStartEvent | InputJsonDeltaEvent | ToolUseContentBlockStopEvent | ToolCallEvent | ToolResultEvent | InterruptedEvent | ErrorReceivedEvent;
+/**
+ * DriveableEventType - String literal union of all driveable event types
+ */
+type DriveableEventType = DriveableEvent["type"];
+/**
+ * Type guard: is this a DriveableEvent?
+ */
+declare function isDriveableEvent(event: SystemEvent): event is DriveableEvent;
+
+export { type DriveableEvent as D, type ErrorReceivedEvent as E, type InputJsonDeltaEvent as I, type MessageStartEvent as M, type TextContentBlockStartEvent as T, type DriveableEventType as a, type MessageDeltaEvent as b, type MessageStopEvent as c, type TextDeltaEvent as d, type TextContentBlockStopEvent as e, type ToolUseContentBlockStartEvent as f, type ToolUseContentBlockStopEvent as g, type ToolCallEvent as h, type ToolResultEvent as i, type InterruptedEvent as j, isDriveableEvent as k };

package/dist/ErrorMessage-BoIh3MIO.d.cts

@@ -0,0 +1,24 @@
+/**
+ * Error Message
+ *
+ * Message representing an error that occurred during conversation.
+ * Displayed in the chat history so users can see what went wrong.
+ */
+interface ErrorMessage {
+    /** Unique identifier */
+    id: string;
+    /** Message role */
+    role: "error";
+    /** Message subtype for serialization */
+    subtype: "error";
+    /** Error message content (human-readable) */
+    content: string;
+    /** Error code (e.g., "rate_limit_error", "api_error") */
+    errorCode?: string;
+    /** When this error occurred (Unix timestamp in milliseconds) */
+    timestamp: number;
+    /** Parent message ID for threading (optional) */
+    parentId?: string;
+}
+
+export type { ErrorMessage as E };

package/dist/ErrorMessage-BoIh3MIO.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Error Message
+ *
+ * Message representing an error that occurred during conversation.
+ * Displayed in the chat history so users can see what went wrong.
+ */
+interface ErrorMessage {
+    /** Unique identifier */
+    id: string;
+    /** Message role */
+    role: "error";
+    /** Message subtype for serialization */
+    subtype: "error";
+    /** Error message content (human-readable) */
+    content: string;
+    /** Error code (e.g., "rate_limit_error", "api_error") */
+    errorCode?: string;
+    /** When this error occurred (Unix timestamp in milliseconds) */
+    timestamp: number;
+    /** Parent message ID for threading (optional) */
+    parentId?: string;
+}
+
+export type { ErrorMessage as E };

package/dist/ImageRecord-Cn0VcJWk.d.cts

@@ -0,0 +1,71 @@
+/**
+ * ImageRecord - Persistent representation of a conversation
+ *
+ * Image is the primary entity users interact with (displayed as "conversation").
+ * Agent is a transient runtime instance created from Image.
+ *
+ * Lifecycle:
+ * - image_create → ImageRecord (persistent)
+ * - image_run → Agent (runtime, in-memory)
+ * - image_stop / server restart → Agent destroyed, Image remains
+ *
+ * Messages are stored separately in Session (via sessionId).
+ */
+/**
+ * Image metadata for storing provider-specific data
+ */
+interface ImageMetadata {
+    /** Claude SDK session ID for conversation resume */
+    claudeSdkSessionId?: string;
+}
+/**
+ * Image storage record
+ *
+ * Represents a conversation that persists across server restarts.
+ */
+interface ImageRecord {
+    /**
+     * Unique image identifier
+     * Pattern: `img_${nanoid()}`
+     */
+    imageId: string;
+    /**
+     * Container ID (user isolation boundary)
+     */
+    containerId: string;
+    /**
+     * Session ID for message storage
+     * Messages are stored in Session, not duplicated here
+     */
+    sessionId: string;
+    /**
+     * Conversation name (displayed to user)
+     */
+    name: string;
+    /**
+     * Conversation description (optional)
+     */
+    description?: string;
+    /**
+     * System prompt - controls agent behavior
+     */
+    systemPrompt?: string;
+    /**
+     * Parent image ID (for fork/branch feature)
+     */
+    parentImageId?: string;
+    /**
+     * Provider-specific metadata (e.g., Claude SDK session ID)
+     */
+    metadata?: ImageMetadata;
+    /**
+     * Creation timestamp (Unix milliseconds)
+     */
+    createdAt: number;
+    /**
+     * Last update timestamp (Unix milliseconds)
+     */
+    updatedAt: number;
+}
+
+export type { ImageRecord as I, ImageMetadata as a };

package/dist/ImageRecord-Cn0VcJWk.d.ts

@@ -0,0 +1,71 @@
+/**
+ * ImageRecord - Persistent representation of a conversation
+ *
+ * Image is the primary entity users interact with (displayed as "conversation").
+ * Agent is a transient runtime instance created from Image.
+ *
+ * Lifecycle:
+ * - image_create → ImageRecord (persistent)
+ * - image_run → Agent (runtime, in-memory)
+ * - image_stop / server restart → Agent destroyed, Image remains
+ *
+ * Messages are stored separately in Session (via sessionId).
+ */
+/**
+ * Image metadata for storing provider-specific data
+ */
+interface ImageMetadata {
+    /** Claude SDK session ID for conversation resume */
+    claudeSdkSessionId?: string;
+}
+/**
+ * Image storage record
+ *
+ * Represents a conversation that persists across server restarts.
+ */
+interface ImageRecord {
+    /**
+     * Unique image identifier
+     * Pattern: `img_${nanoid()}`
+     */
+    imageId: string;
+    /**
+     * Container ID (user isolation boundary)
+     */
+    containerId: string;
+    /**
+     * Session ID for message storage
+     * Messages are stored in Session, not duplicated here
+     */
+    sessionId: string;
+    /**
+     * Conversation name (displayed to user)
+     */
+    name: string;
+    /**
+     * Conversation description (optional)
+     */
+    description?: string;
+    /**
+     * System prompt - controls agent behavior
+     */
+    systemPrompt?: string;
+    /**
+     * Parent image ID (for fork/branch feature)
+     */
+    parentImageId?: string;
+    /**
+     * Provider-specific metadata (e.g., Claude SDK session ID)
+     */
+    metadata?: ImageMetadata;
+    /**
+     * Creation timestamp (Unix milliseconds)
+     */
+    createdAt: number;
+    /**
+     * Last update timestamp (Unix milliseconds)
+     */
+    updatedAt: number;
+}
+
+export type { ImageRecord as I, ImageMetadata as a };

package/dist/LoggerFactory-DZtw0M7U.d.cts

@@ -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 };