agentxjs 0.0.0-dev-20260312143810

package/dist/index.d.ts

@@ -0,0 +1,787 @@
+import { CreateDriver } from '@agentxjs/core/driver';
+import { AgentXRuntime, AgentXPlatform } from '@agentxjs/core/runtime';
+import { Message } from '@agentxjs/core/agent';
+import { AgentXError } from '@agentxjs/core/error';
+export { AgentXError, AgentXErrorCategory, AgentXErrorCode, AgentXErrorContext } from '@agentxjs/core/error';
+import { Unsubscribe, BusEvent, EventBus, BusEventHandler } from '@agentxjs/core/event';
+import { LLMProtocol, LLMProviderRecord } from '@agentxjs/core/persistence';
+import * as _agentxjs_core_network from '@agentxjs/core/network';
+import { RpcMethod } from '@agentxjs/core/network';
+
+/**
+ * Presentation Types
+ *
+ * UI-friendly data model aggregated from stream events.
+ * This implements the Presentation Model pattern.
+ */
+/**
+ * Text block
+ */
+interface TextBlock {
+    type: "text";
+    content: string;
+}
+/**
+ * Tool block - represents a tool call and its result
+ */
+interface ToolBlock {
+    type: "tool";
+    toolUseId: string;
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolResult?: string;
+    status: "pending" | "running" | "completed" | "error";
+}
+/**
+ * Image block
+ */
+interface ImageBlock {
+    type: "image";
+    url: string;
+    alt?: string;
+}
+/**
+ * All block types
+ */
+type Block = TextBlock | ToolBlock | ImageBlock;
+/**
+ * User conversation
+ */
+interface UserConversation {
+    role: "user";
+    blocks: Block[];
+}
+/**
+ * Token usage for a message (one LLM call / step)
+ */
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
+/**
+ * Assistant conversation
+ */
+interface AssistantConversation {
+    role: "assistant";
+    blocks: Block[];
+    isStreaming: boolean;
+    /** Accumulated token usage across all steps in this conversation */
+    usage?: TokenUsage;
+}
+/**
+ * Error conversation
+ */
+interface ErrorConversation {
+    role: "error";
+    message: string;
+}
+/**
+ * All conversation types
+ */
+type Conversation = UserConversation | AssistantConversation | ErrorConversation;
+/**
+ * Presentation state - the complete UI state
+ */
+interface PresentationState {
+    /**
+     * All completed conversations
+     */
+    conversations: Conversation[];
+    /**
+     * Current streaming conversation (null if not streaming)
+     */
+    streaming: AssistantConversation | null;
+    /**
+     * Current status
+     */
+    status: "idle" | "thinking" | "responding" | "executing";
+}
+/**
+ * Initial presentation state
+ */
+declare const initialPresentationState: PresentationState;
+
+/**
+ * Presentation Class
+ *
+ * High-level API for UI integration.
+ * Wraps AgentX client and provides presentation state management.
+ */
+
+/**
+ * Presentation update handler
+ */
+type PresentationUpdateHandler = (state: PresentationState) => void;
+/**
+ * Presentation error handler
+ */
+type PresentationErrorHandler = (error: Error) => void;
+/**
+ * Presentation options
+ */
+interface PresentationOptions {
+    /**
+     * Called on every state update
+     */
+    onUpdate?: PresentationUpdateHandler;
+    /**
+     * Called on errors
+     */
+    onError?: PresentationErrorHandler;
+}
+/**
+ * Presentation - UI-friendly wrapper for AgentX
+ */
+declare class Presentation {
+    private agentx;
+    private agentId;
+    private state;
+    private updateHandlers;
+    private errorHandlers;
+    private eventUnsubscribe;
+    constructor(agentx: AgentX, agentId: string, options?: PresentationOptions, initialConversations?: Conversation[]);
+    /**
+     * Get current state
+     */
+    getState(): PresentationState;
+    /**
+     * Subscribe to state updates
+     */
+    onUpdate(handler: PresentationUpdateHandler): Unsubscribe;
+    /**
+     * Subscribe to errors
+     */
+    onError(handler: PresentationErrorHandler): Unsubscribe;
+    /**
+     * Send a message
+     */
+    send(content: string): Promise<void>;
+    /**
+     * Interrupt current response
+     */
+    interrupt(): Promise<void>;
+    /**
+     * Reset state
+     */
+    reset(): void;
+    /**
+     * Dispose and cleanup
+     */
+    dispose(): void;
+    private subscribeToEvents;
+    private notify;
+    private notifyError;
+}
+
+/**
+ * Presentation Reducer
+ *
+ * Aggregates events into PresentationState.
+ * Pure function: (state, event) => newState
+ *
+ * Event consumption strategy:
+ * - Stream layer: message_start, text_delta, tool_use_start, tool_use_stop, message_stop
+ *   (for real-time streaming display)
+ * - Message layer: tool_result_message
+ *   (for tool execution results — arrives after message_stop)
+ *
+ * Tool calls are stream-level blocks within the assistant turn,
+ * matching the mainstream API pattern (Anthropic, OpenAI).
+ */
+
+/**
+ * Reduce an event into presentation state.
+ *
+ * Consumes:
+ * - Stream events: message_start, text_delta, tool_use_start, tool_use_stop, message_stop
+ * - Message events: tool_result_message
+ * - Error events: error
+ */
+declare function presentationReducer(state: PresentationState, event: BusEvent): PresentationState;
+declare function addUserConversation(state: PresentationState, content: string): PresentationState;
+declare function createInitialState(): PresentationState;
+/**
+ * Convert persisted Messages to Presentation Conversations.
+ *
+ * Groups consecutive assistant + tool-result messages
+ * into a single AssistantConversation.
+ *
+ * Tool calls are now part of AssistantMessage.content (as ToolCallPart),
+ * so we extract them directly from the assistant message.
+ */
+declare function messagesToConversations(messages: Message[]): Conversation[];
+
+/**
+ * AgentX Client SDK Types
+ */
+
+/**
+ * Static or dynamic value
+ */
+type MaybeAsync<T> = T | (() => T) | (() => Promise<T>);
+/**
+ * Agent info returned from server
+ */
+interface AgentInfo {
+    agentId: string;
+    imageId: string;
+    containerId: string;
+    sessionId: string;
+    lifecycle?: string;
+}
+/**
+ * Image record from server
+ */
+interface ImageRecord {
+    imageId: string;
+    containerId: string;
+    sessionId: string;
+    name?: string;
+    description?: string;
+    systemPrompt?: string;
+    customData?: Record<string, unknown>;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Container info
+ */
+interface ContainerInfo {
+    containerId: string;
+}
+/**
+ * Base response with requestId
+ */
+interface BaseResponse {
+    requestId: string;
+    error?: string;
+}
+/**
+ * Agent create response
+ */
+interface AgentCreateResponse extends BaseResponse {
+    agentId: string;
+    imageId: string;
+    containerId: string;
+    sessionId: string;
+}
+/**
+ * Agent get response
+ */
+interface AgentGetResponse extends BaseResponse {
+    agent: AgentInfo | null;
+    exists: boolean;
+}
+/**
+ * Agent list response
+ */
+interface AgentListResponse extends BaseResponse {
+    agents: AgentInfo[];
+}
+/**
+ * Image create response
+ */
+interface ImageCreateResponse extends BaseResponse {
+    record: ImageRecord;
+    __subscriptions?: string[];
+}
+/**
+ * Image get response
+ */
+interface ImageGetResponse extends BaseResponse {
+    record: ImageRecord | null;
+    __subscriptions?: string[];
+}
+/**
+ * Image list response
+ */
+interface ImageListResponse extends BaseResponse {
+    records: ImageRecord[];
+    __subscriptions?: string[];
+}
+/**
+ * Image update response
+ */
+interface ImageUpdateResponse extends BaseResponse {
+    record: ImageRecord;
+}
+/**
+ * Container create response
+ */
+interface ContainerCreateResponse extends BaseResponse {
+    containerId: string;
+}
+/**
+ * Container get response
+ */
+interface ContainerGetResponse extends BaseResponse {
+    containerId: string;
+    exists: boolean;
+}
+/**
+ * Container list response
+ */
+interface ContainerListResponse extends BaseResponse {
+    containerIds: string[];
+}
+/**
+ * Message send response
+ */
+interface MessageSendResponse extends BaseResponse {
+    agentId: string;
+}
+/**
+ * LLM provider create response
+ */
+interface LLMProviderCreateResponse extends BaseResponse {
+    record: LLMProviderRecord;
+}
+/**
+ * LLM provider get response
+ */
+interface LLMProviderGetResponse extends BaseResponse {
+    record: LLMProviderRecord | null;
+}
+/**
+ * LLM provider list response
+ */
+interface LLMProviderListResponse extends BaseResponse {
+    records: LLMProviderRecord[];
+}
+/**
+ * LLM provider update response
+ */
+interface LLMProviderUpdateResponse extends BaseResponse {
+    record: LLMProviderRecord;
+}
+/**
+ * LLM provider default response
+ */
+interface LLMProviderDefaultResponse extends BaseResponse {
+    record: LLMProviderRecord | null;
+}
+/**
+ * Container operations namespace
+ */
+interface ContainerNamespace {
+    /**
+     * Create or get container
+     */
+    create(containerId: string): Promise<ContainerCreateResponse>;
+    /**
+     * Get container
+     */
+    get(containerId: string): Promise<ContainerGetResponse>;
+    /**
+     * List containers
+     */
+    list(): Promise<ContainerListResponse>;
+}
+/**
+ * Image operations namespace
+ */
+interface ImageNamespace {
+    /**
+     * Create a new image
+     */
+    create(params: {
+        containerId: string;
+        name?: string;
+        description?: string;
+        systemPrompt?: string;
+        mcpServers?: Record<string, unknown>;
+        customData?: Record<string, unknown>;
+    }): Promise<ImageCreateResponse>;
+    /**
+     * Get image by ID
+     */
+    get(imageId: string): Promise<ImageGetResponse>;
+    /**
+     * List images
+     */
+    list(containerId?: string): Promise<ImageListResponse>;
+    /**
+     * Update image
+     */
+    update(imageId: string, updates: {
+        name?: string;
+        description?: string;
+        customData?: Record<string, unknown>;
+    }): Promise<ImageUpdateResponse>;
+    /**
+     * Delete image
+     */
+    delete(imageId: string): Promise<BaseResponse>;
+    /**
+     * Get message history for an image
+     */
+    getMessages(imageId: string): Promise<Message[]>;
+}
+/**
+ * Agent operations namespace
+ */
+interface AgentNamespace {
+    /**
+     * Create a new agent
+     */
+    create(params: {
+        imageId: string;
+        agentId?: string;
+    }): Promise<AgentCreateResponse>;
+    /**
+     * Get agent by ID
+     */
+    get(agentId: string): Promise<AgentGetResponse>;
+    /**
+     * List agents
+     */
+    list(containerId?: string): Promise<AgentListResponse>;
+    /**
+     * Destroy an agent
+     */
+    destroy(agentId: string): Promise<BaseResponse>;
+}
+/**
+ * Session operations namespace (messaging)
+ */
+interface SessionNamespace {
+    /**
+     * Send message to agent
+     */
+    send(agentId: string, content: string | unknown[]): Promise<MessageSendResponse>;
+    /**
+     * Interrupt agent
+     */
+    interrupt(agentId: string): Promise<BaseResponse>;
+    /**
+     * Get message history for an agent's session
+     */
+    getMessages(agentId: string): Promise<Message[]>;
+}
+/**
+ * LLM provider operations namespace
+ */
+interface LLMNamespace {
+    /**
+     * Create a new LLM provider configuration
+     */
+    create(params: {
+        containerId: string;
+        name: string;
+        vendor: string;
+        protocol: LLMProtocol;
+        apiKey: string;
+        baseUrl?: string;
+        model?: string;
+    }): Promise<LLMProviderCreateResponse>;
+    /**
+     * Get LLM provider by ID
+     */
+    get(id: string): Promise<LLMProviderGetResponse>;
+    /**
+     * List LLM providers for a container
+     */
+    list(containerId: string): Promise<LLMProviderListResponse>;
+    /**
+     * Update LLM provider
+     */
+    update(id: string, updates: {
+        name?: string;
+        vendor?: string;
+        protocol?: LLMProtocol;
+        apiKey?: string;
+        baseUrl?: string;
+        model?: string;
+    }): Promise<LLMProviderUpdateResponse>;
+    /**
+     * Delete LLM provider
+     */
+    delete(id: string): Promise<BaseResponse>;
+    /**
+     * Set default LLM provider for a container
+     */
+    setDefault(id: string): Promise<BaseResponse>;
+    /**
+     * Get default LLM provider for a container
+     */
+    getDefault(containerId: string): Promise<LLMProviderDefaultResponse>;
+}
+/**
+ * Presentation operations namespace
+ */
+interface PresentationNamespace {
+    /**
+     * Create a presentation for UI integration
+     *
+     * @example
+     * ```typescript
+     * const pres = agentx.presentation.create(agentId, {
+     *   onUpdate: (state) => renderUI(state),
+     *   onError: (error) => console.error(error),
+     * });
+     *
+     * await pres.send("Hello!");
+     * pres.dispose();
+     * ```
+     */
+    create(agentId: string, options?: PresentationOptions): Promise<Presentation>;
+}
+/**
+ * AgentX Client SDK — unified interface for local, remote, and server modes
+ */
+interface AgentX {
+    /**
+     * Check if connected/active
+     */
+    readonly connected: boolean;
+    /**
+     * Event bus for subscribing to events
+     */
+    readonly events: EventBus;
+    readonly container: ContainerNamespace;
+    readonly image: ImageNamespace;
+    readonly agent: AgentNamespace;
+    readonly session: SessionNamespace;
+    readonly presentation: PresentationNamespace;
+    readonly llm: LLMNamespace;
+    on<T extends string>(type: T, handler: BusEventHandler<BusEvent & {
+        type: T;
+    }>): Unsubscribe;
+    onAny(handler: BusEventHandler): Unsubscribe;
+    subscribe(sessionId: string): void;
+    /**
+     * Top-level error handler — receives all AgentXError instances from any layer.
+     *
+     * Independent of `on("error", ...)` (stream events) and `presentation.onError` (UI errors).
+     *
+     * @example
+     * ```typescript
+     * ax.onError((error) => {
+     *   console.error(`[${error.category}] ${error.code}: ${error.message}`);
+     *   if (!error.recoverable) {
+     *     // Circuit is open, stop sending requests
+     *   }
+     * });
+     * ```
+     */
+    onError(handler: (error: AgentXError) => void): Unsubscribe;
+    /**
+     * Universal JSON-RPC entry point — works in all modes:
+     * - Local: dispatches to CommandHandler directly
+     * - Remote: forwards to the remote server via RPC client
+     *
+     * @example
+     * ```typescript
+     * const result = await ax.rpc("container.create", { containerId: "default" });
+     * const { records } = await ax.rpc<{ records: ImageRecord[] }>("image.list");
+     * ```
+     */
+    rpc<T = unknown>(method: string, params?: unknown): Promise<T>;
+    disconnect(): Promise<void>;
+    dispose(): Promise<void>;
+}
+/**
+ * Options for connecting to a remote AgentX server
+ */
+interface ConnectOptions {
+    /** Authentication headers */
+    headers?: MaybeAsync<Record<string, string>>;
+    /** Business context injected into requests */
+    context?: MaybeAsync<Record<string, unknown>>;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+    /** Auto reconnect on disconnect (default: true) */
+    autoReconnect?: boolean;
+}
+/**
+ * Configuration for serving as an AgentX server
+ */
+interface ServeConfig {
+    /** Port to listen on (default: 5200) */
+    port?: number;
+    /** Host to bind to (default: "0.0.0.0") */
+    host?: string;
+    /** Existing HTTP server to attach to */
+    server?: unknown;
+    /** WebSocket path when attached (default: "/ws") */
+    wsPath?: string;
+}
+/**
+ * Server instance returned by serve()
+ */
+interface AgentXServer {
+    listen(port?: number, host?: string): Promise<void>;
+    close(): Promise<void>;
+    dispose(): Promise<void>;
+}
+/**
+ * AgentXBuilder — fluent API entry point
+ *
+ * Created by `createAgentX(platform?)`. The builder itself is an AgentX
+ * instance (local mode). Call `.connect()` to get a remote client,
+ * or `.serve()` to start a server.
+ *
+ * @example
+ * ```typescript
+ * const ax = createAgentX(node({ createDriver }))
+ *
+ * // Local use
+ * await ax.agent.create({ imageId: "..." })
+ *
+ * // Connect to remote server
+ * const client = await ax.connect("wss://...")
+ *
+ * // Serve as server
+ * const server = await ax.serve({ port: 3100 })
+ * ```
+ */
+interface AgentXBuilder extends AgentX {
+    /**
+     * Connect to a remote AgentX server
+     */
+    connect(serverUrl: string, options?: ConnectOptions): Promise<AgentX>;
+    /**
+     * Start serving as an AgentX server
+     */
+    serve(config?: ServeConfig): Promise<AgentXServer>;
+}
+
+/**
+ * CommandHandler - Handles JSON-RPC requests directly
+ *
+ * No longer uses EventBus for request/response. Instead:
+ * - Receives RPC requests directly
+ * - Returns RPC responses directly
+ * - EventBus is only used for stream events (notifications)
+ */
+
+/**
+ * RPC Result type
+ */
+interface RpcResult<T = unknown> {
+    success: true;
+    data: T;
+}
+interface RpcError {
+    success: false;
+    code: number;
+    message: string;
+}
+type RpcResponse<T = unknown> = RpcResult<T> | RpcError;
+/**
+ * CommandHandler - Processes RPC requests directly
+ */
+declare class CommandHandler {
+    private readonly runtime;
+    constructor(runtime: AgentXRuntime);
+    /**
+     * Handle an RPC request and return response
+     */
+    handle(method: RpcMethod, params: unknown): Promise<RpcResponse>;
+    private handleContainerCreate;
+    private handleContainerGet;
+    private handleContainerList;
+    private handleImageCreate;
+    private handleImageGet;
+    private handleImageList;
+    private handleImageDelete;
+    private handleImageRun;
+    private handleImageStop;
+    private handleImageUpdate;
+    private handleImageMessages;
+    private handleAgentGet;
+    private handleAgentList;
+    private handleAgentDestroy;
+    private handleAgentDestroyAll;
+    private handleAgentInterrupt;
+    private handleMessageSend;
+    private handleLLMCreate;
+    private handleLLMGet;
+    private handleLLMList;
+    private handleLLMUpdate;
+    private handleLLMDelete;
+    private handleLLMDefault;
+    dispose(): void;
+}
+
+/**
+ * Server configuration (supports both immediate and deferred platforms)
+ */
+interface ServerConfig {
+    /**
+     * AgentX Platform — must provide `channelServer` for accepting WebSocket connections.
+     */
+    platform: AgentXPlatform;
+    /**
+     * LLM Driver factory function - creates Driver per Agent
+     */
+    createDriver: CreateDriver;
+    /**
+     * Port to listen on (standalone mode)
+     */
+    port?: number;
+    /**
+     * Host to bind to (default: "0.0.0.0")
+     */
+    host?: string;
+    /**
+     * Existing HTTP server to attach to (attached mode)
+     */
+    server?: _agentxjs_core_network.MinimalHTTPServer;
+    /**
+     * WebSocket path when attached (default: "/ws")
+     */
+    wsPath?: string;
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+}
+/**
+ * Create an AgentX server
+ */
+declare function createServer(config: ServerConfig): Promise<AgentXServer>;
+
+/**
+ * agentxjs - AgentX Client SDK
+ *
+ * Fluent API supporting local, remote, and server modes.
+ *
+ * @example Local mode
+ * ```typescript
+ * import { createAgentX } from "agentxjs";
+ * import { nodePlatform } from "@agentxjs/node-platform";
+ *
+ * const ax = createAgentX(nodePlatform({ createDriver }));
+ * await ax.agent.create({ imageId: "..." });
+ * ```
+ *
+ * @example Remote mode
+ * ```typescript
+ * const ax = createAgentX();
+ * const client = await ax.connect("ws://localhost:5200");
+ * ```
+ *
+ * @example Server mode
+ * ```typescript
+ * const ax = createAgentX(nodePlatform({ createDriver }));
+ * const server = await ax.serve({ port: 5200 });
+ * ```
+ */
+
+/**
+ * Platform configuration for createAgentX
+ */
+interface PlatformConfig {
+    platform: AgentXPlatform;
+    createDriver: CreateDriver;
+}
+/**
+ * Create an AgentX builder
+ *
+ * @param config - Platform configuration (optional). Without it, only connect() is available.
+ * @returns AgentXBuilder — local AgentX + connect() + serve()
+ */
+declare function createAgentX(config?: PlatformConfig): AgentXBuilder;
+
+export { type AgentCreateResponse, type AgentGetResponse, type AgentInfo, type AgentListResponse, type AgentNamespace, type AgentX, type AgentXBuilder, type AgentXServer, type AssistantConversation, type BaseResponse, type Block, CommandHandler, type ConnectOptions, type ContainerCreateResponse, type ContainerGetResponse, type ContainerInfo, type ContainerListResponse, type ContainerNamespace, type Conversation, type ErrorConversation, type ImageBlock, type ImageCreateResponse, type ImageGetResponse, type ImageListResponse, type ImageNamespace, type ImageRecord, type LLMNamespace, type LLMProviderCreateResponse, type LLMProviderDefaultResponse, type LLMProviderGetResponse, type LLMProviderListResponse, type LLMProviderUpdateResponse, type MaybeAsync, type MessageSendResponse, type PlatformConfig, Presentation, type PresentationErrorHandler, type PresentationNamespace, type PresentationOptions, type PresentationState, type PresentationUpdateHandler, type ServeConfig, type ServerConfig, type SessionNamespace, type TextBlock, type ToolBlock, type UserConversation, addUserConversation, createAgentX, createInitialState, createServer, initialPresentationState, messagesToConversations, presentationReducer };