@agentxjs/types 0.0.9 → 0.2.0

package/dist/Container-DR-1g44i.d.ts

@@ -0,0 +1,641 @@
+import { S as SystemEvent } from './SystemEvent-CPvvxdMQ.js';
+import { b as CommandEventMap, C as CommandRequestType, R as RequestDataFor, a as ResponseEventFor } from './CommandEvent-CbXzPolX.js';
+import { I as ImageRecord } from './ImageRecord-Cn0VcJWk.js';
+
+/**
+ * SystemBusProducer - Write-only view of SystemBus
+ *
+ * Used by components that produce events:
+ * - Effector (emits DriveableEvents from Claude API)
+ * - Receptor (emits stream events)
+ * - Agent (emits state/message events)
+ *
+ * Producer can only emit events, cannot subscribe.
+ * This prevents accidental event loops and clarifies data flow.
+ *
+ * @example
+ * ```typescript
+ * class Effector {
+ *   constructor(private producer: SystemBusProducer) {}
+ *
+ *   async sendMessage(message: UserMessage) {
+ *     // Can only emit, cannot subscribe
+ *     this.producer.emit({
+ *       type: "message_start",
+ *       source: "environment",
+ *       category: "stream",
+ *       ...
+ *     });
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * SystemBusProducer interface - Write-only view
+ *
+ * Components receiving this interface can only emit events,
+ * preventing them from creating event loops by subscribing.
+ */
+interface SystemBusProducer {
+    /**
+     * Emit a single event to the bus
+     *
+     * @param event - The event to emit
+     */
+    emit(event: SystemEvent): void;
+    /**
+     * Emit multiple events (batch operation)
+     *
+     * @param events - Array of events to emit
+     */
+    emitBatch(events: SystemEvent[]): void;
+    /**
+     * Emit a typed command event
+     *
+     * @param type - The command event type
+     * @param data - Event data (type-checked)
+     */
+    emitCommand<T extends keyof CommandEventMap>(type: T, data: CommandEventMap[T]["data"]): void;
+}
+
+/**
+ * SystemBusConsumer - Read-only view of SystemBus
+ *
+ * Used by components that consume events:
+ * - BusDriver (subscribes to DriveableEvents)
+ * - UI components (subscribes to display events)
+ * - Presenters (subscribes to forward events)
+ *
+ * Consumer can only subscribe to events, cannot emit.
+ * This prevents accidental event emission and clarifies data flow.
+ *
+ * @example
+ * ```typescript
+ * class BusDriver {
+ *   constructor(private consumer: SystemBusConsumer) {}
+ *
+ *   async *receive(message: UserMessage) {
+ *     // Can only subscribe, cannot emit
+ *     this.consumer.on('message_start', (event) => {
+ *       console.log('Received:', event.type);
+ *     });
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Unsubscribe function type
+ */
+type Unsubscribe$1 = () => void;
+/**
+ * Event handler function type
+ */
+type BusEventHandler$1<E extends SystemEvent = SystemEvent> = (event: E) => void;
+/**
+ * Subscription options for advanced event handling
+ */
+interface SubscribeOptions$1<E extends SystemEvent = SystemEvent> {
+    /**
+     * Event filter - only events returning true will trigger the handler
+     * Useful for filtering by agentId, sessionId, etc.
+     */
+    filter?: (event: E) => boolean;
+    /**
+     * Priority - higher numbers execute first (default: 0)
+     * Useful for ensuring certain handlers run before others
+     */
+    priority?: number;
+    /**
+     * Whether to trigger only once then auto-unsubscribe
+     */
+    once?: boolean;
+}
+/**
+ * SystemBusConsumer interface - Read-only view
+ *
+ * Components receiving this interface can only subscribe to events,
+ * preventing them from emitting events.
+ */
+interface SystemBusConsumer {
+    /**
+     * Subscribe to a specific event type
+     *
+     * @param type - The event type to listen for
+     * @param handler - Callback invoked when event is received
+     * @param options - Subscription options (filter, priority, once)
+     * @returns Unsubscribe function
+     */
+    on<T extends string>(type: T, handler: BusEventHandler$1<SystemEvent & {
+        type: T;
+    }>, options?: SubscribeOptions$1<SystemEvent & {
+        type: T;
+    }>): Unsubscribe$1;
+    /**
+     * Subscribe to multiple event types
+     *
+     * @param types - Array of event types to listen for
+     * @param handler - Callback invoked when any matching event is received
+     * @param options - Subscription options
+     * @returns Unsubscribe function
+     */
+    on(types: string[], handler: BusEventHandler$1, options?: SubscribeOptions$1): Unsubscribe$1;
+    /**
+     * Subscribe to all events
+     *
+     * @param handler - Callback invoked for every event
+     * @param options - Subscription options
+     * @returns Unsubscribe function
+     */
+    onAny(handler: BusEventHandler$1, options?: SubscribeOptions$1): Unsubscribe$1;
+    /**
+     * Subscribe to an event type once (auto-unsubscribes after first trigger)
+     *
+     * @param type - Event type to subscribe to
+     * @param handler - Callback function
+     * @returns Unsubscribe function
+     */
+    once<T extends string>(type: T, handler: BusEventHandler$1<SystemEvent & {
+        type: T;
+    }>): Unsubscribe$1;
+    /**
+     * Subscribe to a CommandEvent with full type safety
+     *
+     * @example
+     * ```typescript
+     * consumer.onCommand("container_create_request", (event) => {
+     *   event.data.requestId;    // ✓ string
+     *   event.data.containerId;  // ✓ string
+     * });
+     * ```
+     *
+     * @param type - The command event type
+     * @param handler - Callback with fully typed event
+     * @returns Unsubscribe function
+     */
+    onCommand<T extends keyof CommandEventMap>(type: T, handler: (event: CommandEventMap[T]) => void): Unsubscribe$1;
+    /**
+     * Send a command request and wait for response
+     *
+     * Automatically generates requestId, emits request, waits for matching response.
+     *
+     * @example
+     * ```typescript
+     * const response = await consumer.request("container_create_request", {
+     *   containerId: "my-container"
+     * });
+     * // response is ContainerCreateResponse
+     * console.log(response.data.containerId);
+     * ```
+     *
+     * @param type - The request event type
+     * @param data - Request data (without requestId)
+     * @param timeout - Timeout in milliseconds (default: 30000)
+     * @returns Promise of response event
+     */
+    request<T extends CommandRequestType>(type: T, data: RequestDataFor<T>, timeout?: number): Promise<ResponseEventFor<T>>;
+}
+
+/**
+ * SystemBus - Central event bus for the ecosystem.
+ *
+ * All components communicate through the SystemBus:
+ * - Environment emits EnvironmentEvents (text_chunk, stream_start, etc.)
+ * - Agent emits AgentEvents (state changes, messages, etc.)
+ * - Session, Container emit their respective events
+ *
+ * Features:
+ * - Type-safe event subscription
+ * - Custom filters
+ * - Priority-based execution order
+ * - One-time subscriptions
+ *
+ * @example
+ * ```typescript
+ * const bus = new SystemBusImpl();
+ *
+ * // Subscribe to specific event type
+ * bus.on('text_chunk', (e) => {
+ *   console.log('Received text:', e.data.text);
+ * });
+ *
+ * // Subscribe with options
+ * bus.on('text_delta', handler, {
+ *   filter: (e) => e.agentId === 'agent-1',
+ *   priority: 10,
+ *   once: true
+ * });
+ *
+ * // Subscribe to all events
+ * bus.onAny((e) => {
+ *   console.log('Event:', e.type);
+ * });
+ *
+ * // Emit event
+ * bus.emit({ type: 'text_chunk', data: { text: 'Hello' } });
+ * ```
+ */
+
+/**
+ * Unsubscribe function type.
+ */
+type Unsubscribe = () => void;
+/**
+ * Event handler function type.
+ */
+type BusEventHandler<E extends SystemEvent = SystemEvent> = (event: E) => void;
+/**
+ * Subscription options for advanced event handling.
+ */
+interface SubscribeOptions<E extends SystemEvent = SystemEvent> {
+    /**
+     * Event filter - only events returning true will trigger the handler.
+     * Useful for filtering by agentId, sessionId, etc.
+     */
+    filter?: (event: E) => boolean;
+    /**
+     * Priority - higher numbers execute first (default: 0).
+     * Useful for ensuring certain handlers run before others.
+     */
+    priority?: number;
+    /**
+     * Whether to trigger only once then auto-unsubscribe.
+     */
+    once?: boolean;
+}
+/**
+ * SystemBus interface - Central event bus for ecosystem communication.
+ *
+ * Extends both Producer and Consumer interfaces for internal use.
+ * External components should use restricted views via asProducer/asConsumer.
+ */
+interface SystemBus {
+    /**
+     * Emit an event to the bus.
+     *
+     * All subscribed handlers will receive this event.
+     *
+     * @param event - The event to emit
+     */
+    emit(event: SystemEvent): void;
+    /**
+     * Emit multiple events (batch operation).
+     *
+     * @param events - Array of events to emit
+     */
+    emitBatch(events: SystemEvent[]): void;
+    /**
+     * Subscribe to a specific event type.
+     *
+     * @param type - The event type to listen for
+     * @param handler - Callback invoked when event is received
+     * @param options - Subscription options (filter, priority, once)
+     * @returns Unsubscribe function
+     */
+    on<T extends string>(type: T, handler: BusEventHandler<SystemEvent & {
+        type: T;
+    }>, options?: SubscribeOptions<SystemEvent & {
+        type: T;
+    }>): Unsubscribe;
+    /**
+     * Subscribe to multiple event types.
+     *
+     * @param types - Array of event types to listen for
+     * @param handler - Callback invoked when any matching event is received
+     * @param options - Subscription options
+     * @returns Unsubscribe function
+     */
+    on(types: string[], handler: BusEventHandler, options?: SubscribeOptions): Unsubscribe;
+    /**
+     * Subscribe to all events.
+     *
+     * @param handler - Callback invoked for every event
+     * @param options - Subscription options
+     * @returns Unsubscribe function
+     */
+    onAny(handler: BusEventHandler, options?: SubscribeOptions): Unsubscribe;
+    /**
+     * Subscribe to an event type once (auto-unsubscribes after first trigger).
+     *
+     * @param type - Event type to subscribe to
+     * @param handler - Callback function
+     * @returns Unsubscribe function
+     */
+    once<T extends string>(type: T, handler: BusEventHandler<SystemEvent & {
+        type: T;
+    }>): Unsubscribe;
+    /**
+     * Subscribe to a CommandEvent with full type safety.
+     *
+     * @example
+     * ```typescript
+     * bus.onCommand("container_create_request", (event) => {
+     *   event.data.requestId;    // ✓ string
+     *   event.data.containerId;  // ✓ string
+     * });
+     * ```
+     *
+     * @param type - The command event type
+     * @param handler - Callback with fully typed event
+     * @returns Unsubscribe function
+     */
+    onCommand<T extends keyof CommandEventMap>(type: T, handler: (event: CommandEventMap[T]) => void): Unsubscribe;
+    /**
+     * Emit a CommandEvent with full type safety.
+     *
+     * @example
+     * ```typescript
+     * bus.emitCommand("container_create_request", {
+     *   requestId: "req_123",
+     *   containerId: "my-container"
+     * });
+     * ```
+     *
+     * @param type - The command event type
+     * @param data - Event data (type-checked)
+     */
+    emitCommand<T extends keyof CommandEventMap>(type: T, data: CommandEventMap[T]["data"]): void;
+    /**
+     * Send a command request and wait for response.
+     *
+     * Automatically generates requestId, emits request, waits for matching response.
+     *
+     * @example
+     * ```typescript
+     * const response = await bus.request("container_create_request", {
+     *   containerId: "my-container"
+     * });
+     * // response is ContainerCreateResponse
+     * console.log(response.data.containerId);
+     * ```
+     *
+     * @param type - The request event type
+     * @param data - Request data (without requestId)
+     * @param timeout - Timeout in milliseconds (default: 30000)
+     * @returns Promise of response event
+     */
+    request<T extends CommandRequestType>(type: T, data: RequestDataFor<T>, timeout?: number): Promise<ResponseEventFor<T>>;
+    /**
+     * Get a read-only consumer view of the bus.
+     *
+     * Use this to safely expose event subscription to external code
+     * without allowing them to emit events.
+     *
+     * @example
+     * ```typescript
+     * class BusDriver {
+     *   constructor(consumer: SystemBusConsumer) {
+     *     // Can only subscribe, cannot emit
+     *     consumer.on('text_delta', ...);
+     *   }
+     * }
+     * ```
+     *
+     * @returns SystemBusConsumer - Read-only view
+     */
+    asConsumer(): SystemBusConsumer;
+    /**
+     * Get a write-only producer view of the bus.
+     *
+     * Use this to give components the ability to emit events
+     * without exposing subscription capabilities.
+     *
+     * @example
+     * ```typescript
+     * class ClaudeReceptor {
+     *   constructor(producer: SystemBusProducer) {
+     *     // Can only emit, cannot subscribe
+     *     producer.emit({ type: 'text_delta', ... });
+     *   }
+     * }
+     * ```
+     *
+     * @returns SystemBusProducer - Write-only view
+     */
+    asProducer(): SystemBusProducer;
+    /**
+     * Destroy the bus and clean up resources.
+     *
+     * All subscriptions will be terminated.
+     * After calling destroy():
+     * - All subscriptions are removed
+     * - New emissions are ignored
+     * - New subscriptions are no-ops
+     */
+    destroy(): void;
+}
+
+/**
+ * AgentLifecycle - Runtime Agent lifecycle states
+ *
+ * - running: Agent is active, can receive messages
+ * - stopped: Agent is paused, session data preserved, can resume
+ * - destroyed: Agent is removed, all data cleaned up
+ */
+type AgentLifecycle = "running" | "stopped" | "destroyed";
+
+/**
+ * Agent - Runtime Agent (Complete Runtime Entity)
+ *
+ * A complete runtime agent composed of:
+ * - LLM: Large Language Model connection
+ * - Sandbox: Isolated environment (filesystem, permissions, tools)
+ * - Engine: Event processing state machine
+ * - Session: Conversation history (persisted)
+ *
+ * Managed by Container, supports stop/resume lifecycle.
+ *
+ * @example
+ * ```typescript
+ * const agent = await runtime.agents.run(containerId, config);
+ *
+ * // Interact
+ * runtime.events.on("text_delta", (e) => console.log(e.data.text));
+ * await agent.receive("Hello!");
+ *
+ * // Pause (session preserved)
+ * await agent.stop();
+ *
+ * // Resume later
+ * await agent.resume();
+ *
+ * // Destroy (cleanup everything)
+ * await agent.destroy();
+ * ```
+ */
+
+/**
+ * Runtime Agent interface
+ */
+interface Agent {
+    /**
+     * Unique agent identifier
+     */
+    readonly agentId: string;
+    /**
+     * Agent name (from config or default)
+     */
+    readonly name: string;
+    /**
+     * Parent container ID
+     */
+    readonly containerId: string;
+    /**
+     * Current lifecycle state
+     */
+    readonly lifecycle: AgentLifecycle;
+    /**
+     * Creation timestamp (Unix milliseconds)
+     */
+    readonly createdAt: number;
+    /**
+     * Send a message to the agent
+     *
+     * @param message - User message content
+     * @param requestId - Optional request ID for event correlation
+     */
+    receive(message: string, requestId?: string): Promise<void>;
+    /**
+     * Interrupt current processing
+     *
+     * Stops the current operation gracefully.
+     *
+     * @param requestId - Optional request ID for event correlation
+     */
+    interrupt(requestId?: string): void;
+    /**
+     * Stop the agent
+     *
+     * Pauses the agent, preserving session data.
+     * Can be resumed later with resume().
+     */
+    stop(): Promise<void>;
+    /**
+     * Resume a stopped agent
+     *
+     * Restores the agent from preserved session data.
+     */
+    resume(): Promise<void>;
+    /**
+     * Destroy the agent
+     *
+     * Completely removes the agent and all associated data.
+     * Cannot be resumed after destruction.
+     */
+    destroy(): Promise<void>;
+}
+
+/**
+ * Container - Runtime environment for Agent instances
+ *
+ * Container is a runtime isolation boundary where Agents live and work.
+ * Each Container manages multiple Agents, each with its own Sandbox.
+ *
+ * In the Image-First model:
+ * - Image is the persistent entity (conversation)
+ * - Agent is a transient runtime instance of an Image
+ * - Container tracks imageId → agentId mapping
+ *
+ * Architecture:
+ * ```
+ * Container
+ *   └── Image 1 ──→ Agent 1 ─── Sandbox 1
+ *   └── Image 2 ──→ (offline)
+ *   └── Image 3 ──→ Agent 3 ─── Sandbox 3
+ * ```
+ *
+ * Container provides:
+ * - Image → Agent lifecycle management (runImage, stopImage)
+ * - Sandbox creation per Agent (encapsulated)
+ * - Runtime isolation between Containers
+ * - Foundation for multi-agent collaboration
+ *
+ * @example
+ * ```typescript
+ * // Create container via Runtime
+ * const container = await runtime.containers.create("container-1");
+ *
+ * // Run an agent from an image
+ * const { agent, reused } = await container.runImage(imageRecord);
+ *
+ * // Use the agent
+ * await agent.receive("Hello!");
+ *
+ * // Stop the image (destroys agent, keeps image)
+ * await container.stopImage(imageId);
+ *
+ * // Dispose container
+ * await container.dispose();
+ * ```
+ */
+
+/**
+ * Container interface for managing Agent instances at runtime
+ */
+interface Container {
+    /**
+     * Unique container identifier
+     */
+    readonly containerId: string;
+    /**
+     * Container creation timestamp
+     */
+    readonly createdAt: number;
+    /**
+     * Run an Image - create or reuse an Agent for the given Image
+     *
+     * @param image - ImageRecord to run
+     * @returns { agent, reused } - the agent and whether it was reused
+     */
+    runImage(image: ImageRecord): Promise<{
+        agent: Agent;
+        reused: boolean;
+    }>;
+    /**
+     * Stop an Image - destroy the Agent but keep the Image
+     *
+     * @param imageId - Image to stop
+     * @returns true if agent was found and destroyed
+     */
+    stopImage(imageId: string): Promise<boolean>;
+    /**
+     * Get agent ID for an image (if running)
+     */
+    getAgentIdForImage(imageId: string): string | undefined;
+    /**
+     * Check if an image has a running agent
+     */
+    isImageOnline(imageId: string): boolean;
+    /**
+     * Get an Agent by ID
+     */
+    getAgent(agentId: string): Agent | undefined;
+    /**
+     * List all Agents in this container
+     */
+    listAgents(): Agent[];
+    /**
+     * Get the number of Agents in this container
+     */
+    get agentCount(): number;
+    /**
+     * Destroy an Agent by ID
+     *
+     * Cleans up Agent resources and removes from container.
+     *
+     * @param agentId - Agent to destroy
+     * @returns true if agent was found and destroyed
+     */
+    destroyAgent(agentId: string): Promise<boolean>;
+    /**
+     * Destroy all Agents in this container
+     */
+    destroyAllAgents(): Promise<void>;
+    /**
+     * Dispose the container and all its Agents
+     */
+    dispose(): Promise<void>;
+}
+
+export type { Agent as A, BusEventHandler as B, Container as C, SystemBus as S, Unsubscribe as U, AgentLifecycle as a, SystemBusProducer as b, SystemBusConsumer as c, SubscribeOptions as d };