@agentxjs/claude-driver 1.9.5-dev → 1.9.7-dev

package/dist/index.d.ts

@@ -0,0 +1,302 @@
+import { Driver, DriverConfig, DriverState, DriverStreamEvent } from '@agentxjs/core/driver';
+export { CreateDriver, Driver, DriverConfig, DriverState, DriverStreamEvent, StopReason } from '@agentxjs/core/driver';
+import { UserMessage } from '@agentxjs/core/agent';
+import { McpServerConfig, SDKMessage, SDKUserMessage } from '@anthropic-ai/claude-agent-sdk';
+
+/**
+ * ClaudeDriver - Claude SDK Driver Implementation
+ *
+ * Implements the new Driver interface with clear input/output boundaries:
+ * - receive(message) returns AsyncIterable<DriverStreamEvent>
+ * - No EventBus dependency
+ * - Single session communication
+ *
+ * ```
+ *         UserMessage
+ *              │
+ *              ▼
+ *     ┌─────────────────┐
+ *     │   ClaudeDriver   │
+ *     │                  │
+ *     │   receive()      │──► AsyncIterable<DriverStreamEvent>
+ *     │       │          │
+ *     │       ▼          │
+ *     │   SDK Query      │
+ *     └─────────────────┘
+ *              │
+ *              ▼
+ *        Claude SDK
+ * ```
+ */
+
+/**
+ * ClaudeDriver - Driver implementation for Claude SDK
+ *
+ * Implements the new Driver interface:
+ * - receive() returns AsyncIterable<DriverStreamEvent>
+ * - Clear input/output boundaries for recording/playback
+ * - Single session communication
+ */
+declare class ClaudeDriver implements Driver {
+    readonly name = "ClaudeDriver";
+    private _sessionId;
+    private _state;
+    private readonly config;
+    private queryLifecycle;
+    private currentTurnSubject;
+    constructor(config: DriverConfig);
+    get sessionId(): string | null;
+    get state(): DriverState;
+    /**
+     * Initialize the Driver
+     *
+     * Starts SDK subprocess and MCP servers.
+     * Must be called before receive().
+     */
+    initialize(): Promise<void>;
+    /**
+     * Dispose and cleanup resources
+     *
+     * Stops SDK subprocess and MCP servers.
+     * Driver cannot be used after dispose().
+     */
+    dispose(): Promise<void>;
+    /**
+     * Receive a user message and return stream of events
+     *
+     * This is the main method for communication.
+     * Returns an AsyncIterable that yields DriverStreamEvent.
+     *
+     * @param message - User message to send
+     * @returns AsyncIterable of stream events
+     */
+    receive(message: UserMessage): AsyncIterable<DriverStreamEvent>;
+    /**
+     * Interrupt current operation
+     *
+     * Stops the current receive() operation gracefully.
+     * The AsyncIterable will emit an "interrupted" event and complete.
+     */
+    interrupt(): void;
+    /**
+     * Ensure SDK lifecycle is initialized
+     */
+    private ensureLifecycle;
+    /**
+     * Setup callbacks for a single turn
+     */
+    private setupTurnCallbacks;
+    /**
+     * Convert SDK stream_event to DriverStreamEvent
+     */
+    private convertStreamEvent;
+    /**
+     * Convert SDK user message (contains tool_result)
+     */
+    private convertUserMessage;
+    /**
+     * Map SDK stop reason to our StopReason type
+     */
+    private mapStopReason;
+    /**
+     * Yield events from Subject as AsyncIterable
+     */
+    private yieldFromSubject;
+}
+/**
+ * CreateDriver function for ClaudeDriver
+ *
+ * Factory function that creates a ClaudeDriver instance.
+ * Conforms to the CreateDriver type from @agentxjs/core/driver.
+ *
+ * @example
+ * ```typescript
+ * import { createClaudeDriver } from "@agentxjs/claude-driver";
+ *
+ * const driver = createClaudeDriver({
+ *   apiKey: process.env.ANTHROPIC_API_KEY!,
+ *   agentId: "my-agent",
+ *   systemPrompt: "You are helpful",
+ * });
+ *
+ * await driver.initialize();
+ *
+ * for await (const event of driver.receive({ content: "Hello" })) {
+ *   if (event.type === "text_delta") {
+ *     process.stdout.write(event.data.text);
+ *   }
+ * }
+ *
+ * await driver.dispose();
+ * ```
+ */
+declare function createClaudeDriver(config: DriverConfig): Driver;
+
+/**
+ * SDKQueryLifecycle - Manages Claude SDK query lifecycle
+ *
+ * This class encapsulates the low-level SDK interaction:
+ * - Query initialization and lazy loading
+ * - Background listener for SDK responses
+ * - Interrupt and cleanup operations
+ *
+ * It emits events via callbacks, allowing the parent Driver
+ * to handle business logic like timeout management.
+ */
+
+/**
+ * Callbacks for SDK events
+ */
+interface SDKQueryCallbacks {
+    /** Called when a stream_event is received */
+    onStreamEvent?: (msg: SDKMessage) => void;
+    /** Called when a user message is received (contains tool_result) */
+    onUserMessage?: (msg: SDKMessage) => void;
+    /** Called when a result is received */
+    onResult?: (msg: SDKMessage) => void;
+    /** Called when session ID is captured */
+    onSessionIdCaptured?: (sessionId: string) => void;
+    /** Called when an error occurs */
+    onError?: (error: Error) => void;
+    /** Called when the listener exits (normally or due to error) */
+    onListenerExit?: (reason: "normal" | "abort" | "error") => void;
+}
+/**
+ * Configuration for SDKQueryLifecycle
+ */
+interface SDKQueryConfig {
+    apiKey: string;
+    baseUrl?: string;
+    model?: string;
+    systemPrompt?: string;
+    cwd?: string;
+    resumeSessionId?: string;
+    mcpServers?: Record<string, McpServerConfig>;
+    claudeCodePath?: string;
+}
+/**
+ * SDKQueryLifecycle - Manages the lifecycle of a Claude SDK query
+ *
+ * Responsibilities:
+ * - Lazy initialization of SDK query
+ * - Background listener for SDK responses
+ * - Interrupt and cleanup operations
+ * - Resource management (subprocess termination)
+ */
+declare class SDKQueryLifecycle {
+    private readonly config;
+    private _callbacks;
+    private promptSubject;
+    private claudeQuery;
+    private isInitialized;
+    private abortController;
+    private capturedSessionId;
+    constructor(config: SDKQueryConfig, callbacks?: SDKQueryCallbacks);
+    /**
+     * Get current callbacks (for reading/modification)
+     */
+    get callbacks(): SDKQueryCallbacks;
+    /**
+     * Update callbacks
+     *
+     * Allows changing callbacks after initialization.
+     * Useful for per-turn callback setup.
+     */
+    setCallbacks(callbacks: Partial<SDKQueryCallbacks>): void;
+    /**
+     * Check if the query is initialized
+     */
+    get initialized(): boolean;
+    /**
+     * Warmup the SDK query (pre-initialize)
+     *
+     * Call this early to start the SDK subprocess before the first message.
+     * This reduces latency for the first user message.
+     *
+     * @returns Promise that resolves when SDK is ready
+     */
+    warmup(): Promise<void>;
+    /**
+     * Initialize the SDK query (lazy initialization)
+     *
+     * Creates the query and starts the background listener.
+     * Safe to call multiple times - will only initialize once.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Send a message to the SDK
+     *
+     * Must call initialize() first.
+     */
+    send(message: SDKUserMessage): void;
+    /**
+     * Interrupt the current SDK operation
+     */
+    interrupt(): void;
+    /**
+     * Reset state and cleanup resources
+     *
+     * This properly terminates the Claude subprocess by:
+     * 1. Completing the prompt stream (signals end of input)
+     * 2. Interrupting any ongoing operation
+     * 3. Resetting state for potential reuse
+     */
+    reset(): void;
+    /**
+     * Dispose and cleanup all resources
+     *
+     * Should be called when the lifecycle is no longer needed.
+     */
+    dispose(): void;
+    /**
+     * Start the background listener for SDK responses
+     */
+    private startBackgroundListener;
+    /**
+     * Check if an error is an abort error
+     */
+    private isAbortError;
+}
+
+/**
+ * Helper functions for Claude Driver
+ */
+
+/**
+ * Claude API content block types
+ */
+type ClaudeTextBlock = {
+    type: "text";
+    text: string;
+};
+type ClaudeImageBlock = {
+    type: "image";
+    source: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    };
+};
+type ClaudeDocumentBlock = {
+    type: "document";
+    source: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    };
+};
+type ClaudeContentBlock = ClaudeTextBlock | ClaudeImageBlock | ClaudeDocumentBlock;
+/**
+ * Build SDK content from UserMessage
+ *
+ * Converts AgentX ContentPart[] to Claude API format:
+ * - Pure text messages return as string (for efficiency)
+ * - Mixed content returns as ClaudeContentBlock[]
+ */
+declare function buildSDKContent(message: UserMessage): string | ClaudeContentBlock[];
+/**
+ * Build SDK UserMessage from AgentX UserMessage
+ */
+declare function buildSDKUserMessage(message: UserMessage, sessionId: string): SDKUserMessage;
+
+export { ClaudeDriver, type SDKQueryCallbacks, type SDKQueryConfig, SDKQueryLifecycle, buildSDKContent, buildSDKUserMessage, createClaudeDriver };