@agentxjs/claude-driver 1.9.1-dev

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@agentxjs/claude-driver",
+  "version": "1.9.1-dev",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@agentxjs/core": "workspace:*",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.29",
+    "rxjs": "^7.8.2"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3"
+  }
+}

package/src/ClaudeDriver.ts

@@ -0,0 +1,598 @@
+/**
+ * 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
+ * ```
+ */
+
+import type {
+  Driver,
+  DriverConfig,
+  DriverState,
+  DriverStreamEvent,
+  StopReason,
+} from "@agentxjs/core/driver";
+import type { UserMessage } from "@agentxjs/core/agent";
+import type { SDKMessage, SDKPartialAssistantMessage } from "@anthropic-ai/claude-agent-sdk";
+import { Subject } from "rxjs";
+import { createLogger } from "commonxjs/logger";
+import { buildSDKUserMessage } from "./helpers";
+import { SDKQueryLifecycle } from "./SDKQueryLifecycle";
+
+const logger = createLogger("claude-driver/ClaudeDriver");
+
+/**
+ * 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
+ */
+export class ClaudeDriver implements Driver {
+  readonly name = "ClaudeDriver";
+
+  private _sessionId: string | null = null;
+  private _state: DriverState = "idle";
+
+  private readonly config: DriverConfig;
+  private queryLifecycle: SDKQueryLifecycle | null = null;
+
+  // For interrupt handling
+  private currentTurnSubject: Subject<DriverStreamEvent> | null = null;
+
+  constructor(config: DriverConfig) {
+    this.config = config;
+  }
+
+  // ============================================================================
+  // Driver Interface Properties
+  // ============================================================================
+
+  get sessionId(): string | null {
+    return this._sessionId;
+  }
+
+  get state(): DriverState {
+    return this._state;
+  }
+
+  // ============================================================================
+  // Lifecycle Methods
+  // ============================================================================
+
+  /**
+   * Initialize the Driver
+   *
+   * Starts SDK subprocess and MCP servers.
+   * Must be called before receive().
+   */
+  async initialize(): Promise<void> {
+    if (this._state !== "idle") {
+      throw new Error(`Cannot initialize: Driver is in "${this._state}" state`);
+    }
+
+    logger.info("Initializing ClaudeDriver", { agentId: this.config.agentId });
+
+    // SDKQueryLifecycle will be created lazily on first receive()
+    // This allows configuration to be validated early without starting subprocess
+
+    logger.info("ClaudeDriver initialized");
+  }
+
+  /**
+   * Dispose and cleanup resources
+   *
+   * Stops SDK subprocess and MCP servers.
+   * Driver cannot be used after dispose().
+   */
+  async dispose(): Promise<void> {
+    if (this._state === "disposed") {
+      return;
+    }
+
+    logger.info("Disposing ClaudeDriver", { agentId: this.config.agentId });
+
+    // Complete any pending turn
+    if (this.currentTurnSubject) {
+      this.currentTurnSubject.complete();
+      this.currentTurnSubject = null;
+    }
+
+    // Dispose SDK lifecycle
+    if (this.queryLifecycle) {
+      this.queryLifecycle.dispose();
+      this.queryLifecycle = null;
+    }
+
+    this._state = "disposed";
+    logger.info("ClaudeDriver disposed");
+  }
+
+  // ============================================================================
+  // Core Methods
+  // ============================================================================
+
+  /**
+   * 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
+   */
+  async *receive(message: UserMessage): AsyncIterable<DriverStreamEvent> {
+    if (this._state === "disposed") {
+      throw new Error("Cannot receive: Driver is disposed");
+    }
+
+    if (this._state === "active") {
+      throw new Error("Cannot receive: Driver is already processing a message");
+    }
+
+    this._state = "active";
+
+    try {
+      // Ensure SDK lifecycle is initialized
+      await this.ensureLifecycle();
+
+      // Create Subject for this turn's events
+      const turnSubject = new Subject<DriverStreamEvent>();
+      this.currentTurnSubject = turnSubject;
+
+      // Track completion
+      let isComplete = false;
+      let turnError: Error | null = null;
+
+      // Setup callbacks to convert SDK events to DriverStreamEvent
+      this.setupTurnCallbacks(turnSubject, () => {
+        isComplete = true;
+      }, (error) => {
+        turnError = error;
+        isComplete = true;
+      });
+
+      // Build and send SDK message
+      const sessionId = this._sessionId || "default";
+      const sdkMessage = buildSDKUserMessage(message, sessionId);
+
+      logger.debug("Sending message to Claude", {
+        content: typeof message.content === "string"
+          ? message.content.substring(0, 80)
+          : "[structured]",
+        agentId: this.config.agentId,
+      });
+
+      this.queryLifecycle!.send(sdkMessage);
+
+      // Yield events from Subject
+      yield* this.yieldFromSubject(turnSubject, () => isComplete, () => turnError);
+
+    } finally {
+      this._state = "idle";
+      this.currentTurnSubject = null;
+    }
+  }
+
+  /**
+   * Interrupt current operation
+   *
+   * Stops the current receive() operation gracefully.
+   * The AsyncIterable will emit an "interrupted" event and complete.
+   */
+  interrupt(): void {
+    if (this._state !== "active") {
+      logger.debug("Interrupt called but no active operation");
+      return;
+    }
+
+    logger.debug("Interrupting ClaudeDriver");
+
+    // Emit interrupted event
+    if (this.currentTurnSubject) {
+      this.currentTurnSubject.next({
+        type: "interrupted",
+        timestamp: Date.now(),
+        data: { reason: "user" },
+      });
+      this.currentTurnSubject.complete();
+    }
+
+    // Interrupt SDK
+    if (this.queryLifecycle) {
+      this.queryLifecycle.interrupt();
+    }
+  }
+
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+
+  /**
+   * Ensure SDK lifecycle is initialized
+   */
+  private async ensureLifecycle(): Promise<void> {
+    if (this.queryLifecycle && this.queryLifecycle.initialized) {
+      return;
+    }
+
+    // Create new lifecycle
+    this.queryLifecycle = new SDKQueryLifecycle(
+      {
+        apiKey: this.config.apiKey,
+        baseUrl: this.config.baseUrl,
+        model: this.config.model,
+        systemPrompt: this.config.systemPrompt,
+        cwd: this.config.cwd,
+        resumeSessionId: this.config.resumeSessionId,
+        mcpServers: this.config.mcpServers,
+      },
+      {
+        onSessionIdCaptured: (sessionId) => {
+          this._sessionId = sessionId;
+          this.config.onSessionIdCaptured?.(sessionId);
+        },
+      }
+    );
+
+    await this.queryLifecycle.initialize();
+  }
+
+  /**
+   * Setup callbacks for a single turn
+   */
+  private setupTurnCallbacks(
+    subject: Subject<DriverStreamEvent>,
+    onComplete: () => void,
+    onError: (error: Error) => void
+  ): void {
+    if (!this.queryLifecycle) return;
+
+    // Context for tracking content block state
+    const blockContext = {
+      currentBlockType: null as "text" | "tool_use" | null,
+      currentToolId: null as string | null,
+      currentToolName: null as string | null,
+      lastStopReason: null as string | null,
+      accumulatedToolInput: "" as string,
+    };
+
+    // Update lifecycle callbacks for this turn
+    this.queryLifecycle.setCallbacks({
+      onStreamEvent: (msg: SDKMessage) => {
+        const event = this.convertStreamEvent(msg as SDKPartialAssistantMessage, blockContext);
+        if (event) {
+          subject.next(event);
+        }
+      },
+
+      onUserMessage: (msg: SDKMessage) => {
+        const events = this.convertUserMessage(msg);
+        for (const event of events) {
+          subject.next(event);
+        }
+      },
+
+      onResult: (msg: SDKMessage) => {
+        const resultMsg = msg as { is_error?: boolean; error?: { message?: string } };
+
+        if (resultMsg.is_error) {
+          subject.next({
+            type: "error",
+            timestamp: Date.now(),
+            data: {
+              message: resultMsg.error?.message || "Unknown error",
+              errorCode: "sdk_error",
+            },
+          });
+        }
+
+        subject.complete();
+        onComplete();
+      },
+
+      onError: (error: Error) => {
+        subject.next({
+          type: "error",
+          timestamp: Date.now(),
+          data: {
+            message: error.message,
+            errorCode: "runtime_error",
+          },
+        });
+        subject.complete();
+        onError(error);
+      },
+    });
+  }
+
+  /**
+   * Convert SDK stream_event to DriverStreamEvent
+   */
+  private convertStreamEvent(
+    sdkMsg: SDKPartialAssistantMessage,
+    blockContext: {
+      currentBlockType: "text" | "tool_use" | null;
+      currentToolId: string | null;
+      currentToolName: string | null;
+      lastStopReason: string | null;
+      accumulatedToolInput: string;
+    }
+  ): DriverStreamEvent | null {
+    const event = sdkMsg.event;
+    const timestamp = Date.now();
+
+    switch (event.type) {
+      case "message_start":
+        return {
+          type: "message_start",
+          timestamp,
+          data: {
+            messageId: event.message.id,
+            model: event.message.model,
+          },
+        };
+
+      case "content_block_start": {
+        const contentBlock = event.content_block as { type: string; id?: string; name?: string };
+
+        if (contentBlock.type === "text") {
+          blockContext.currentBlockType = "text";
+          // text_content_block_start is internal, don't emit
+          return null;
+        } else if (contentBlock.type === "tool_use") {
+          blockContext.currentBlockType = "tool_use";
+          blockContext.currentToolId = contentBlock.id || null;
+          blockContext.currentToolName = contentBlock.name || null;
+          blockContext.accumulatedToolInput = "";
+          return {
+            type: "tool_use_start",
+            timestamp,
+            data: {
+              toolCallId: contentBlock.id || "",
+              toolName: contentBlock.name || "",
+            },
+          };
+        }
+        return null;
+      }
+
+      case "content_block_delta": {
+        const delta = event.delta as { type: string; text?: string; partial_json?: string };
+
+        if (delta.type === "text_delta") {
+          return {
+            type: "text_delta",
+            timestamp,
+            data: { text: delta.text || "" },
+          };
+        } else if (delta.type === "input_json_delta") {
+          blockContext.accumulatedToolInput += delta.partial_json || "";
+          return {
+            type: "input_json_delta",
+            timestamp,
+            data: { partialJson: delta.partial_json || "" },
+          };
+        }
+        return null;
+      }
+
+      case "content_block_stop":
+        if (blockContext.currentBlockType === "tool_use" && blockContext.currentToolId) {
+          // Parse accumulated JSON
+          let input: Record<string, unknown> = {};
+          try {
+            if (blockContext.accumulatedToolInput) {
+              input = JSON.parse(blockContext.accumulatedToolInput);
+            }
+          } catch {
+            logger.warn("Failed to parse tool input JSON", {
+              input: blockContext.accumulatedToolInput,
+            });
+          }
+
+          const event: DriverStreamEvent = {
+            type: "tool_use_stop",
+            timestamp,
+            data: {
+              toolCallId: blockContext.currentToolId,
+              toolName: blockContext.currentToolName || "",
+              input,
+            },
+          };
+
+          // Reset block context
+          blockContext.currentBlockType = null;
+          blockContext.currentToolId = null;
+          blockContext.currentToolName = null;
+          blockContext.accumulatedToolInput = "";
+
+          return event;
+        }
+        // Reset for text blocks too
+        blockContext.currentBlockType = null;
+        return null;
+
+      case "message_delta": {
+        const msgDelta = event.delta as { stop_reason?: string };
+        if (msgDelta.stop_reason) {
+          blockContext.lastStopReason = msgDelta.stop_reason;
+        }
+        return null;
+      }
+
+      case "message_stop":
+        return {
+          type: "message_stop",
+          timestamp,
+          data: {
+            stopReason: this.mapStopReason(blockContext.lastStopReason),
+          },
+        };
+
+      default:
+        return null;
+    }
+  }
+
+  /**
+   * Convert SDK user message (contains tool_result)
+   */
+  private convertUserMessage(msg: SDKMessage): DriverStreamEvent[] {
+    const events: DriverStreamEvent[] = [];
+    const sdkMsg = msg as { message?: { content?: unknown[] } };
+
+    if (!sdkMsg.message || !Array.isArray(sdkMsg.message.content)) {
+      return events;
+    }
+
+    for (const block of sdkMsg.message.content) {
+      if (block && typeof block === "object" && "type" in block && block.type === "tool_result") {
+        const toolResultBlock = block as unknown as {
+          tool_use_id: string;
+          content: unknown;
+          is_error?: boolean;
+        };
+
+        events.push({
+          type: "tool_result",
+          timestamp: Date.now(),
+          data: {
+            toolCallId: toolResultBlock.tool_use_id,
+            result: toolResultBlock.content,
+            isError: toolResultBlock.is_error,
+          },
+        });
+      }
+    }
+
+    return events;
+  }
+
+  /**
+   * Map SDK stop reason to our StopReason type
+   */
+  private mapStopReason(sdkReason: string | null): StopReason {
+    switch (sdkReason) {
+      case "end_turn":
+        return "end_turn";
+      case "max_tokens":
+        return "max_tokens";
+      case "tool_use":
+        return "tool_use";
+      case "stop_sequence":
+        return "stop_sequence";
+      default:
+        return "other";
+    }
+  }
+
+  /**
+   * Yield events from Subject as AsyncIterable
+   */
+  private async *yieldFromSubject(
+    subject: Subject<DriverStreamEvent>,
+    _isComplete: () => boolean,
+    getError: () => Error | null
+  ): AsyncIterable<DriverStreamEvent> {
+    const queue: DriverStreamEvent[] = [];
+    let resolve: ((value: IteratorResult<DriverStreamEvent>) => void) | null = null;
+    let done = false;
+
+    const subscription = subject.subscribe({
+      next: (value) => {
+        if (resolve) {
+          resolve({ value, done: false });
+          resolve = null;
+        } else {
+          queue.push(value);
+        }
+      },
+      complete: () => {
+        done = true;
+        if (resolve) {
+          resolve({ value: undefined as unknown as DriverStreamEvent, done: true });
+          resolve = null;
+        }
+      },
+      error: (_err) => {
+        done = true;
+        // Error is handled via getError()
+      },
+    });
+
+    try {
+      while (!done || queue.length > 0) {
+        const error = getError();
+        if (error) {
+          throw error;
+        }
+
+        if (queue.length > 0) {
+          yield queue.shift()!;
+        } else if (!done) {
+          const result = await new Promise<IteratorResult<DriverStreamEvent>>((res) => {
+            resolve = res;
+          });
+
+          if (!result.done) {
+            yield result.value;
+          }
+        }
+      }
+    } finally {
+      subscription.unsubscribe();
+    }
+  }
+}
+
+/**
+ * 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();
+ * ```
+ */
+export function createClaudeDriver(config: DriverConfig): Driver {
+  return new ClaudeDriver(config);
+}

package/src/SDKQueryLifecycle.ts

@@ -0,0 +1,311 @@
+/**
+ * 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.
+ */
+
+import {
+  query,
+  type SDKUserMessage,
+  type Query,
+  type SDKMessage,
+  type McpServerConfig,
+} from "@anthropic-ai/claude-agent-sdk";
+import { Subject } from "rxjs";
+import { createLogger } from "commonxjs/logger";
+import { buildOptions, type EnvironmentContext } from "./buildOptions";
+import { observableToAsyncIterable } from "./observableToAsyncIterable";
+
+const logger = createLogger("claude-driver/SDKQueryLifecycle");
+
+/**
+ * Callbacks for SDK events
+ */
+export 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
+ */
+export 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)
+ */
+export class SDKQueryLifecycle {
+  private readonly config: SDKQueryConfig;
+  private _callbacks: SDKQueryCallbacks;
+
+  private promptSubject = new Subject<SDKUserMessage>();
+  private claudeQuery: Query | null = null;
+  private isInitialized = false;
+  private abortController: AbortController | null = null;
+  private capturedSessionId: string | null = null;
+
+  constructor(config: SDKQueryConfig, callbacks: SDKQueryCallbacks = {}) {
+    this.config = config;
+    this._callbacks = callbacks;
+  }
+
+  /**
+   * Get current callbacks (for reading/modification)
+   */
+  get callbacks(): SDKQueryCallbacks {
+    return this._callbacks;
+  }
+
+  /**
+   * Update callbacks
+   *
+   * Allows changing callbacks after initialization.
+   * Useful for per-turn callback setup.
+   */
+  setCallbacks(callbacks: Partial<SDKQueryCallbacks>): void {
+    this._callbacks = { ...this._callbacks, ...callbacks };
+  }
+
+  /**
+   * Check if the query is initialized
+   */
+  get initialized(): boolean {
+    return this.isInitialized;
+  }
+
+  /**
+   * 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
+   */
+  async warmup(): Promise<void> {
+    logger.info("Warming up SDKQueryLifecycle");
+    await this.initialize();
+    logger.info("SDKQueryLifecycle warmup complete");
+  }
+
+  /**
+   * Initialize the SDK query (lazy initialization)
+   *
+   * Creates the query and starts the background listener.
+   * Safe to call multiple times - will only initialize once.
+   */
+  async initialize(): Promise<void> {
+    if (this.isInitialized) return;
+
+    logger.info("Initializing SDKQueryLifecycle");
+
+    this.abortController = new AbortController();
+
+    const context: EnvironmentContext = {
+      apiKey: this.config.apiKey,
+      baseUrl: this.config.baseUrl,
+      model: this.config.model,
+      systemPrompt: this.config.systemPrompt,
+      cwd: this.config.cwd,
+      resume: this.config.resumeSessionId,
+      mcpServers: this.config.mcpServers,
+      claudeCodePath: this.config.claudeCodePath,
+    };
+
+    const sdkOptions = buildOptions(context, this.abortController);
+    const promptStream = observableToAsyncIterable<SDKUserMessage>(this.promptSubject);
+
+    this.claudeQuery = query({
+      prompt: promptStream,
+      options: sdkOptions,
+    });
+
+    this.isInitialized = true;
+
+    // Start background listener
+    this.startBackgroundListener();
+
+    logger.info("SDKQueryLifecycle initialized");
+  }
+
+  /**
+   * Send a message to the SDK
+   *
+   * Must call initialize() first.
+   */
+  send(message: SDKUserMessage): void {
+    if (!this.isInitialized) {
+      throw new Error("SDKQueryLifecycle not initialized. Call initialize() first.");
+    }
+    this.promptSubject.next(message);
+  }
+
+  /**
+   * Interrupt the current SDK operation
+   */
+  interrupt(): void {
+    if (this.claudeQuery) {
+      logger.debug("Interrupting SDK query");
+      this.claudeQuery.interrupt().catch((err) => {
+        logger.debug("SDK interrupt() error (may be expected)", { error: err });
+      });
+    }
+  }
+
+  /**
+   * 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 {
+    logger.debug("Resetting SDKQueryLifecycle");
+
+    // 1. Complete the prompt stream first (signals end of input to subprocess)
+    this.promptSubject.complete();
+
+    // 2. Interrupt any ongoing operation
+    if (this.claudeQuery) {
+      this.claudeQuery.interrupt().catch((err) => {
+        logger.debug("SDK interrupt() during reset (may be expected)", { error: err });
+      });
+    }
+
+    // 3. Reset state for potential reuse
+    this.isInitialized = false;
+    this.claudeQuery = null;
+    this.abortController = null;
+    this.promptSubject = new Subject<SDKUserMessage>();
+  }
+
+  /**
+   * Dispose and cleanup all resources
+   *
+   * Should be called when the lifecycle is no longer needed.
+   */
+  dispose(): void {
+    logger.debug("Disposing SDKQueryLifecycle");
+
+    // Interrupt first
+    if (this.claudeQuery) {
+      this.claudeQuery.interrupt().catch((err) => {
+        logger.debug("SDK interrupt() during dispose (may be expected)", { error: err });
+      });
+    }
+
+    // Abort controller
+    if (this.abortController) {
+      this.abortController.abort();
+    }
+
+    // Reset state
+    this.reset();
+
+    logger.debug("SDKQueryLifecycle disposed");
+  }
+
+  /**
+   * Start the background listener for SDK responses
+   */
+  private startBackgroundListener(): void {
+    (async () => {
+      try {
+        for await (const sdkMsg of this.claudeQuery!) {
+          logger.debug("SDK message received", {
+            type: sdkMsg.type,
+            subtype: (sdkMsg as { subtype?: string }).subtype,
+            sessionId: sdkMsg.session_id,
+          });
+
+          // Capture session ID (only once, on first occurrence)
+          if (
+            sdkMsg.session_id &&
+            this._callbacks.onSessionIdCaptured &&
+            this.capturedSessionId !== sdkMsg.session_id
+          ) {
+            this.capturedSessionId = sdkMsg.session_id;
+            this._callbacks.onSessionIdCaptured(sdkMsg.session_id);
+          }
+
+          // Forward stream_event
+          if (sdkMsg.type === "stream_event") {
+            this._callbacks.onStreamEvent?.(sdkMsg);
+          }
+
+          // Forward user message (contains tool_result)
+          if (sdkMsg.type === "user") {
+            this._callbacks.onUserMessage?.(sdkMsg);
+          }
+
+          // Handle result
+          if (sdkMsg.type === "result") {
+            logger.info("SDK result received", {
+              subtype: (sdkMsg as { subtype?: string }).subtype,
+              is_error: (sdkMsg as { is_error?: boolean }).is_error,
+            });
+            this._callbacks.onResult?.(sdkMsg);
+          }
+        }
+
+        // Normal exit
+        this._callbacks.onListenerExit?.("normal");
+      } catch (error) {
+        if (this.isAbortError(error)) {
+          logger.debug("Background listener aborted (expected during interrupt)");
+          this._callbacks.onListenerExit?.("abort");
+        } else {
+          logger.error("Background listener error", { error });
+          this._callbacks.onError?.(error instanceof Error ? error : new Error(String(error)));
+          this._callbacks.onListenerExit?.("error");
+        }
+
+        // Always reset state on any error
+        this.reset();
+      }
+    })();
+  }
+
+  /**
+   * Check if an error is an abort error
+   */
+  private isAbortError(error: unknown): boolean {
+    if (error instanceof Error) {
+      if (error.name === "AbortError") return true;
+      if (error.message.includes("aborted")) return true;
+      if (error.message.includes("abort")) return true;
+    }
+    return false;
+  }
+}

package/src/buildOptions.ts

@@ -0,0 +1,135 @@
+/**
+ * Build Claude SDK Options from Driver Config
+ *
+ * Converts driver configuration to Claude SDK Options format.
+ */
+
+import type { Options, McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
+import { createLogger } from "commonxjs/logger";
+
+const logger = createLogger("claude-driver/buildOptions");
+
+/**
+ * Environment context for Claude SDK
+ */
+export interface EnvironmentContext {
+  apiKey: string;
+  baseUrl?: string;
+  model?: string;
+  systemPrompt?: string;
+  cwd?: string;
+  permissionMode?: "default" | "acceptEdits" | "bypassPermissions" | "plan";
+  resume?: string;
+  maxTurns?: number;
+  maxThinkingTokens?: number;
+  mcpServers?: Record<string, McpServerConfig>;
+  claudeCodePath?: string;
+}
+
+/**
+ * Build Claude SDK options from environment context
+ */
+export function buildOptions(
+  context: EnvironmentContext,
+  abortController: AbortController
+): Options {
+  const options: Options = {
+    abortController,
+    includePartialMessages: true,
+  };
+
+  // Working directory
+  if (context.cwd) {
+    options.cwd = context.cwd;
+  }
+
+  // Environment variables - must include PATH for subprocess to find node
+  const env: Record<string, string> = {};
+  // Copy all process.env values, filtering out undefined
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== undefined) {
+      env[key] = value;
+    }
+  }
+  // Ensure PATH is set (critical for subprocess to find node)
+  if (!env.PATH && process.env.PATH) {
+    env.PATH = process.env.PATH;
+  }
+
+  // Mark process as AgentX environment for identification and debugging
+  env.AGENTX_ENVIRONMENT = "true";
+
+  if (context.baseUrl) {
+    env.ANTHROPIC_BASE_URL = context.baseUrl;
+  }
+  if (context.apiKey) {
+    env.ANTHROPIC_API_KEY = context.apiKey;
+  }
+  options.env = env;
+
+  logger.info("buildOptions called", {
+    hasPath: !!env.PATH,
+    pathLength: env.PATH?.length,
+    hasApiKey: !!env.ANTHROPIC_API_KEY,
+    hasBaseUrl: !!env.ANTHROPIC_BASE_URL,
+    baseUrl: env.ANTHROPIC_BASE_URL,
+    model: context.model,
+    permissionMode: context.permissionMode || "bypassPermissions",
+    cwd: context.cwd,
+    systemPrompt: context.systemPrompt,
+    mcpServers: context.mcpServers ? Object.keys(context.mcpServers) : [],
+  });
+
+  // Capture stderr from SDK subprocess for debugging
+  options.stderr = (data: string) => {
+    logger.info("SDK stderr", { data: data.trim() });
+  };
+
+  // Set Claude Code executable path if provided
+  if (context.claudeCodePath) {
+    options.pathToClaudeCodeExecutable = context.claudeCodePath;
+    logger.info("Claude Code path configured", { path: context.claudeCodePath });
+  }
+
+  // Model configuration
+  if (context.model) options.model = context.model;
+  if (context.systemPrompt) options.systemPrompt = context.systemPrompt;
+  if (context.maxTurns) options.maxTurns = context.maxTurns;
+  if (context.maxThinkingTokens) options.maxThinkingTokens = context.maxThinkingTokens;
+
+  // Session control
+  if (context.resume) options.resume = context.resume;
+
+  // MCP servers
+  if (context.mcpServers) {
+    options.mcpServers = context.mcpServers;
+    logger.info("MCP servers configured", {
+      serverNames: Object.keys(context.mcpServers),
+    });
+  }
+
+  // Permission system
+  if (context.permissionMode) {
+    options.permissionMode = context.permissionMode;
+    // Required when using bypassPermissions mode
+    if (context.permissionMode === "bypassPermissions") {
+      options.allowDangerouslySkipPermissions = true;
+    }
+  } else {
+    // Default to bypass permissions (agent runs autonomously)
+    options.permissionMode = "bypassPermissions";
+    options.allowDangerouslySkipPermissions = true;
+  }
+
+  logger.info("SDK Options built", {
+    model: options.model,
+    systemPrompt: options.systemPrompt,
+    permissionMode: options.permissionMode,
+    cwd: options.cwd,
+    resume: options.resume,
+    maxTurns: options.maxTurns,
+    mcpServers: options.mcpServers ? Object.keys(options.mcpServers) : [],
+  });
+
+  return options;
+}

package/src/helpers.ts

@@ -0,0 +1,129 @@
+/**
+ * Helper functions for Claude Driver
+ */
+
+import type { UserMessage, ContentPart, TextPart, ImagePart, FilePart } from "@agentxjs/core/agent";
+import type { SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+
+/**
+ * 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;
+
+/**
+ * Type guards for ContentPart discrimination
+ */
+function isTextPart(part: ContentPart): part is TextPart {
+  return part.type === "text";
+}
+
+function isImagePart(part: ContentPart): part is ImagePart {
+  return part.type === "image";
+}
+
+function isFilePart(part: ContentPart): part is FilePart {
+  return part.type === "file";
+}
+
+/**
+ * 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[]
+ */
+export function buildSDKContent(message: UserMessage): string | ClaudeContentBlock[] {
+  // String content - return as-is
+  if (typeof message.content === "string") {
+    return message.content;
+  }
+
+  // Not an array - return empty string
+  if (!Array.isArray(message.content)) {
+    return "";
+  }
+
+  const parts = message.content as ContentPart[];
+
+  // Check if we have only text parts
+  const hasNonTextParts = parts.some((p) => !isTextPart(p));
+
+  if (!hasNonTextParts) {
+    // Pure text - return as string for efficiency
+    return parts
+      .filter(isTextPart)
+      .map((p) => p.text)
+      .join("\n");
+  }
+
+  // Mixed content - return as content blocks
+  return parts.map((part): ClaudeContentBlock => {
+    if (isTextPart(part)) {
+      return {
+        type: "text",
+        text: part.text,
+      };
+    }
+
+    if (isImagePart(part)) {
+      return {
+        type: "image",
+        source: {
+          type: "base64",
+          media_type: part.mediaType,
+          data: part.data,
+        },
+      };
+    }
+
+    if (isFilePart(part)) {
+      // PDF and other files use "document" type in Claude API
+      return {
+        type: "document",
+        source: {
+          type: "base64",
+          media_type: part.mediaType,
+          data: part.data,
+        },
+      };
+    }
+
+    // Unknown type - return empty text block
+    return { type: "text", text: "" };
+  });
+}
+
+/**
+ * Build SDK UserMessage from AgentX UserMessage
+ */
+export function buildSDKUserMessage(message: UserMessage, sessionId: string): SDKUserMessage {
+  return {
+    type: "user",
+    message: { role: "user", content: buildSDKContent(message) },
+    parent_tool_use_id: null,
+    session_id: sessionId,
+  };
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+/**
+ * @agentxjs/claude-driver
+ *
+ * Claude SDK Driver for AgentX
+ *
+ * Provides Driver implementation for connecting AgentX to Claude SDK.
+ *
+ * Key Design:
+ * - Clear input/output boundary (for recording/playback)
+ * - receive() returns AsyncIterable<DriverStreamEvent>
+ * - Single session communication
+ *
+ * Usage:
+ * ```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();
+ * ```
+ */
+
+// Main exports
+export { ClaudeDriver, createClaudeDriver } from "./ClaudeDriver";
+
+// Re-export types from core for convenience
+export type {
+  Driver,
+  DriverConfig,
+  DriverState,
+  CreateDriver,
+  DriverStreamEvent,
+  StopReason,
+} from "@agentxjs/core/driver";
+
+// Internal utilities (for advanced usage)
+export {
+  SDKQueryLifecycle,
+  type SDKQueryCallbacks,
+  type SDKQueryConfig,
+} from "./SDKQueryLifecycle";
+export { buildSDKContent, buildSDKUserMessage } from "./helpers";

package/src/observableToAsyncIterable.ts

@@ -0,0 +1,75 @@
+/**
+ * Convert RxJS Observable to AsyncIterable
+ *
+ * Utility for converting Observable streams to AsyncIterable
+ * for use with SDKs that accept AsyncIterable input.
+ */
+
+import type { Observable } from "rxjs";
+
+export async function* observableToAsyncIterable<T>(observable: Observable<T>): AsyncIterable<T> {
+  const queue: T[] = [];
+  let resolve: ((value: IteratorResult<T>) => void) | null = null;
+  let reject: ((error: Error) => void) | null = null;
+  let done = false;
+  let error: Error | null = null;
+
+  const subscription = observable.subscribe({
+    next: (value) => {
+      if (resolve) {
+        resolve({ value, done: false });
+        resolve = null;
+        reject = null;
+      } else {
+        queue.push(value);
+      }
+    },
+    error: (err) => {
+      error = err instanceof Error ? err : new Error(String(err));
+      done = true;
+      if (reject) {
+        reject(error);
+        resolve = null;
+        reject = null;
+      }
+    },
+    complete: () => {
+      done = true;
+      if (resolve) {
+        resolve({ value: undefined as unknown as T, done: true });
+        resolve = null;
+        reject = null;
+      }
+    },
+  });
+
+  try {
+    while (!done || queue.length > 0) {
+      if (error) {
+        throw error;
+      }
+
+      if (queue.length > 0) {
+        yield queue.shift()!;
+      } else if (!done) {
+        const result = await new Promise<{ value: T; done: false } | { done: true }>((res, rej) => {
+          resolve = (iterResult) => {
+            if (iterResult.done) {
+              done = true;
+              res({ done: true });
+            } else {
+              res({ value: iterResult.value, done: false });
+            }
+          };
+          reject = rej;
+        });
+
+        if (!result.done) {
+          yield result.value;
+        }
+      }
+    }
+  } finally {
+    subscription.unsubscribe();
+  }
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["src/**/__tests__/**/*", "src/**/*.test.ts", "src/**/*.spec.ts"]
+}