open-claude-agent-sdk 0.9.0

package/src/api/ProcessFactory.ts

@@ -0,0 +1,124 @@
+/**
+ * Process factory for dependency injection
+ *
+ * Allows unit tests to inject mock processes without spawning real CLI.
+ *
+ * @internal
+ */
+
+import type { ChildProcess } from 'node:child_process';
+import { buildCliArgs } from '../core/argBuilder.ts';
+import { detectClaudeBinary, spawnClaude } from '../core/spawn.ts';
+import type { Options } from '../types/index.ts';
+
+/**
+ * Interface for creating CLI processes
+ * Allows dependency injection for testing
+ */
+export interface ProcessFactory {
+  spawn(options: Options): ChildProcess;
+}
+
+/**
+ * Check if a path is a native binary (not a JS file)
+ * Matches official SDK: if NOT .js/.mjs/.tsx/.ts/.jsx, it's a native binary
+ */
+function isNativeBinary(path: string): boolean {
+  return !['.js', '.mjs', '.tsx', '.ts', '.jsx'].some((ext) => path.endsWith(ext));
+}
+
+/**
+ * Get default JavaScript runtime
+ */
+function getDefaultExecutable(): string {
+  return typeof process.versions.bun !== 'undefined' ? 'bun' : 'node';
+}
+
+/**
+ * Default implementation that spawns real Claude CLI
+ */
+export class DefaultProcessFactory implements ProcessFactory {
+  spawn(options: Options): ChildProcess {
+    const args = buildCliArgs({ ...options, prompt: '' });
+
+    // Build environment with enableFileCheckpointing support
+    const env: Record<string, string | undefined> = { ...(options.env ?? {}) };
+    if (options.enableFileCheckpointing) {
+      env.CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING = 'true';
+    }
+
+    // Custom spawn function takes priority
+    if (options.spawnClaudeCodeProcess) {
+      const scriptPath = detectClaudeBinary(options);
+      const native = isNativeBinary(scriptPath);
+      const executable = options.executable ?? getDefaultExecutable();
+      const executableArgs = options.executableArgs ?? [];
+      const command = native ? scriptPath : executable;
+      const spawnArgs = native
+        ? [...executableArgs, ...args]
+        : [...executableArgs, scriptPath, ...args];
+
+      // Build full env for SpawnOptions
+      const fullEnv: Record<string, string | undefined> = { ...process.env, ...env };
+      if (!fullEnv.CLAUDE_CODE_ENTRYPOINT) fullEnv.CLAUDE_CODE_ENTRYPOINT = 'sdk-ts';
+      delete fullEnv.NODE_OPTIONS;
+      if (fullEnv.DEBUG_CLAUDE_AGENT_SDK) fullEnv.DEBUG = '1';
+      else delete fullEnv.DEBUG;
+
+      const spawnedProcess = options.spawnClaudeCodeProcess({
+        command,
+        args: spawnArgs,
+        cwd: options.cwd,
+        env: fullEnv,
+        signal: AbortSignal.timeout(3600000), // 1 hour default
+      });
+
+      // Wrap SpawnedProcess to ChildProcess-compatible object
+      return spawnedProcess as unknown as ChildProcess;
+    }
+
+    const scriptPath = detectClaudeBinary(options);
+
+    // When executable is explicitly set, use it as the command with script as arg
+    if (options.executable) {
+      const executableArgs = options.executableArgs ?? [];
+      const fullArgs = [...executableArgs, scriptPath, ...args];
+      return spawnClaude(options.executable, fullArgs, {
+        cwd: options.cwd,
+        env,
+        stderr: options.stderr,
+      });
+    }
+
+    // Default: use detected binary directly (shebang handles runtime)
+    const executableArgs = options.executableArgs ?? [];
+
+    if (isNativeBinary(scriptPath)) {
+      // Native binary: command is the binary, executableArgs before CLI args
+      const fullArgs = [...executableArgs, ...args];
+      return spawnClaude(scriptPath, fullArgs, {
+        cwd: options.cwd,
+        env,
+        stderr: options.stderr,
+      });
+    }
+
+    // JS file with executableArgs: need explicit runtime
+    if (executableArgs.length > 0) {
+      const executable = getDefaultExecutable();
+      const fullArgs = [...executableArgs, scriptPath, ...args];
+      return spawnClaude(executable, fullArgs, {
+        cwd: options.cwd,
+        env,
+        stderr: options.stderr,
+      });
+    }
+
+    // JS file without executableArgs: use script directly (shebang handles runtime)
+    return spawnClaude(scriptPath, args, {
+      cwd: options.cwd,
+      env,
+      stderr: options.stderr,
+    });
+  }
+}

package/src/api/QueryImpl.ts

@@ -0,0 +1,543 @@
+/**
+ * Query implementation with bidirectional control protocol support
+ *
+ * Combines AsyncIterableIterator pattern with control methods for:
+ * - Multi-turn conversations (streamInput)
+ * - Runtime control (interrupt, setPermissionMode, setModel)
+ * - Background control protocol handling
+ *
+ * @internal
+ */
+
+import type { ChildProcess } from 'node:child_process';
+import {
+  ControlProtocolHandler,
+  ControlRequests,
+  type OutboundControlRequest,
+} from '../core/control.ts';
+import { buildHookConfig } from '../core/hookConfig.ts';
+import { McpServerBridge } from '../core/mcpBridge.ts';
+import { MessageType, RequestSubtype, ResponseSubtype } from '../types/control.ts';
+import type {
+  AccountInfo,
+  McpServerConfig,
+  McpServerStatus,
+  McpSetServersResult,
+  ModelInfo,
+  Options,
+  PermissionMode,
+  Query,
+  RewindFilesResult,
+  SDKControlInitializeResponse,
+  SDKMessage,
+  SDKUserMessage,
+  SlashCommand,
+} from '../types/index.ts';
+import { MessageQueue } from './MessageQueue.ts';
+import { type ControlResponsePayload, MessageRouter } from './MessageRouter.ts';
+import { DefaultProcessFactory, type ProcessFactory } from './ProcessFactory.ts';
+
+export class QueryImpl implements Query {
+  private closed = false;
+  private abortHandler: (() => void) | null = null;
+
+  // Pending control request/response map (for mcpServerStatus, etc.)
+  private pendingControlResponses = new Map<
+    string,
+    // biome-ignore lint/suspicious/noExplicitAny: response shape varies by request type
+    { resolve: (value: any) => void; reject: (reason: Error) => void }
+  >();
+
+  private constructor(
+    private process: ChildProcess,
+    private messageQueue: MessageQueue<SDKMessage>,
+    private controlHandler: ControlProtocolHandler,
+    private router: MessageRouter,
+    private initResponsePromise: Promise<SDKControlInitializeResponse>,
+    private initResolve: (value: SDKControlInitializeResponse) => void,
+    private initReject: (reason: Error) => void,
+    private initRequestId: string,
+    private sdkMcpServerNames: string[],
+    private isSingleUserTurn: boolean,
+    private abortController?: AbortController
+  ) {}
+
+  /**
+   * Factory method — performs all initialization that was previously in the constructor.
+   */
+  static create(
+    params: { prompt: string | AsyncIterable<SDKUserMessage>; options?: Options },
+    processFactory: ProcessFactory = new DefaultProcessFactory()
+  ): QueryImpl {
+    const { prompt, options = {} } = params;
+
+    // Check for pre-aborted signal BEFORE spawning process (save resources)
+    if (options.abortController?.signal.aborted) {
+      return QueryImpl.createAborted();
+    }
+
+    // 1. Spawn process via factory
+    const childProcess = processFactory.spawn(options);
+
+    // Validate stdio streams exist (they should with stdio: 'pipe')
+    if (!childProcess.stdin || !childProcess.stdout) {
+      throw new Error('Process stdin/stdout not available');
+    }
+
+    // 2. Initialize message queue
+    const messageQueue = new MessageQueue<SDKMessage>();
+
+    // 3. Initialize control protocol handler
+    const controlHandler = new ControlProtocolHandler(childProcess.stdin, options);
+
+    // 3.5. Connect SDK MCP servers (in-process servers with `instance` property)
+    const sdkMcpServerNames: string[] = [];
+    QueryImpl.connectMcpBridges(options, controlHandler, sdkMcpServerNames);
+
+    // 4. Set up init response promise before sending init request
+    let initResolve!: (value: SDKControlInitializeResponse) => void;
+    let initReject!: (reason: Error) => void;
+    const initResponsePromise = new Promise<SDKControlInitializeResponse>((resolve, reject) => {
+      initResolve = resolve;
+      initReject = reject;
+    });
+
+    const initRequestId = `init_${Date.now()}`;
+    const isSingleUserTurn = typeof prompt === 'string';
+
+    // 5. Construct instance
+    const instance = new QueryImpl(
+      childProcess,
+      messageQueue,
+      controlHandler,
+      // router placeholder — set below after constructing with callbacks
+      null as unknown as MessageRouter,
+      initResponsePromise,
+      initResolve,
+      initReject,
+      initRequestId,
+      sdkMcpServerNames,
+      isSingleUserTurn,
+      options.abortController
+    );
+
+    // 6. Initialize message router with callbacks (needs instance for closures)
+    instance.router = new MessageRouter(
+      childProcess.stdout,
+      controlHandler,
+      (msg) => instance.handleMessage(msg),
+      (error) => instance.handleDone(error),
+      (response) => instance.handleControlResponse(response)
+    );
+
+    // 7. Start background reading
+    instance.router.startReading();
+
+    // 8. Send control protocol initialization
+    instance.sendControlProtocolInit(options);
+
+    // 9. Handle input based on type
+    if (typeof prompt === 'string') {
+      instance.sendInitialPrompt(prompt);
+    } else {
+      instance.consumeInputGenerator(prompt);
+    }
+
+    // 10. Setup process exit/error handlers + abort listener
+    instance.setupProcessHandlers();
+
+    return instance;
+  }
+
+  /**
+   * Create an already-aborted QueryImpl (no process spawned).
+   */
+  private static createAborted(): QueryImpl {
+    const messageQueue = new MessageQueue<SDKMessage>();
+    messageQueue.complete();
+    const abortError = new Error('Query was aborted before initialization');
+    const initResponsePromise = Promise.reject(abortError);
+    initResponsePromise.catch(() => {}); // Prevent unhandled rejection
+
+    const instance = new QueryImpl(
+      null as unknown as ChildProcess,
+      messageQueue,
+      null as unknown as ControlProtocolHandler,
+      null as unknown as MessageRouter,
+      initResponsePromise,
+      () => {},
+      () => {},
+      '',
+      [],
+      false
+    );
+    instance.closed = true;
+    return instance;
+  }
+
+  /**
+   * Connect SDK MCP server bridges (in-process servers with `instance` property).
+   */
+  private static connectMcpBridges(
+    options: Options,
+    controlHandler: ControlProtocolHandler,
+    sdkMcpServerNames: string[]
+  ): void {
+    if (!options.mcpServers) return;
+
+    const bridges = new Map<string, McpServerBridge>();
+    for (const [name, config] of Object.entries(options.mcpServers)) {
+      if ('instance' in config && config.instance) {
+        const bridge = new McpServerBridge(config.instance);
+        bridge.connect(); // async but we don't await — server connects in background
+        bridges.set(name, bridge);
+        sdkMcpServerNames.push(name);
+      }
+    }
+    if (bridges.size > 0) {
+      controlHandler.setMcpServerBridges(bridges);
+    }
+  }
+
+  /**
+   * Set up process exit/error handlers and abort controller listener.
+   */
+  private setupProcessHandlers(): void {
+    this.process.on('exit', (code) => {
+      if (code !== 0 && code !== null && !this.messageQueue.isDone()) {
+        const error = new Error(`Claude CLI exited with code ${code}`);
+        this.messageQueue.complete(error);
+        this.rejectPendingPromises(error);
+      } else if (!this.messageQueue.isDone()) {
+        this.messageQueue.complete();
+        this.rejectPendingPromises(new Error('CLI exited before responding'));
+      }
+    });
+
+    this.process.on('error', (err) => {
+      if (!this.messageQueue.isDone()) {
+        this.messageQueue.complete(err);
+      }
+      this.rejectPendingPromises(err);
+    });
+
+    if (this.abortController) {
+      this.abortHandler = () => {
+        this.interrupt();
+      };
+      this.abortController.signal.addEventListener('abort', this.abortHandler);
+    }
+  }
+
+  /**
+   * Handle incoming message from router
+   */
+  private handleMessage(msg: SDKMessage): void {
+    this.messageQueue.push(msg);
+
+    // For single-turn queries, close stdin on result to signal CLI to exit
+    if (msg.type === 'result' && this.isSingleUserTurn) {
+      this.process.stdin?.end();
+    }
+  }
+
+  /**
+   * Handle stream completion from router
+   */
+  private handleDone(error?: Error): void {
+    if (!this.messageQueue.isDone()) {
+      this.messageQueue.complete(error);
+    }
+  }
+
+  /**
+   * Handle control_response messages from CLI
+   * Routes to init promise or pending request/response handlers
+   */
+  private handleControlResponse(response: ControlResponsePayload): void {
+    if (!response) return;
+
+    const requestId = response.request_id;
+
+    // Check if this is the init response
+    if (requestId === this.initRequestId) {
+      if (response.subtype === ResponseSubtype.SUCCESS) {
+        this.initResolve(response.response as SDKControlInitializeResponse);
+      } else {
+        this.initReject(new Error(`Initialization failed: ${response.error || 'unknown error'}`));
+      }
+      return;
+    }
+
+    // Check if there's a pending request/response handler
+    const pending = requestId ? this.pendingControlResponses.get(requestId) : undefined;
+    if (pending) {
+      const { resolve, reject } = pending;
+      this.pendingControlResponses.delete(requestId);
+      if (response.subtype === ResponseSubtype.SUCCESS) {
+        resolve(response.response);
+      } else {
+        reject(new Error(`Control request failed: ${response.error || 'unknown error'}`));
+      }
+    }
+  }
+
+  // ============================================================================
+  // AsyncGenerator implementation
+  // ============================================================================
+
+  async next(): Promise<IteratorResult<SDKMessage>> {
+    return this.messageQueue.next();
+  }
+
+  async return(_value?: unknown): Promise<IteratorResult<SDKMessage>> {
+    this.close();
+    return { value: undefined as unknown as SDKMessage, done: true };
+  }
+
+  async throw(e?: unknown): Promise<IteratorResult<SDKMessage>> {
+    this.close();
+    throw e;
+  }
+
+  [Symbol.asyncIterator](): AsyncGenerator<SDKMessage, void> {
+    return this as unknown as AsyncGenerator<SDKMessage, void>;
+  }
+
+  async [Symbol.asyncDispose](): Promise<void> {
+    this.close();
+  }
+
+  // ============================================================================
+  // Control methods (12 methods from Query interface)
+  // ============================================================================
+
+  async interrupt(): Promise<void> {
+    this.sendControlRequest(ControlRequests.interrupt());
+  }
+
+  async setPermissionMode(mode: PermissionMode): Promise<void> {
+    this.sendControlRequest(ControlRequests.setPermissionMode(mode));
+  }
+
+  async setModel(model?: string): Promise<void> {
+    this.sendControlRequest(ControlRequests.setModel(model));
+  }
+
+  async setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void> {
+    this.sendControlRequest(ControlRequests.setMaxThinkingTokens(maxThinkingTokens));
+  }
+
+  async streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void> {
+    for await (const msg of stream) {
+      this.writeToStdin(msg);
+    }
+  }
+
+  close(): void {
+    if (!this.closed) {
+      this.closed = true;
+      // Clean up abort controller listener
+      if (this.abortController && this.abortHandler) {
+        this.abortController.signal.removeEventListener('abort', this.abortHandler);
+        this.abortHandler = null;
+      }
+      this.router?.close();
+      this.process?.kill();
+      if (!this.messageQueue.isDone()) {
+        this.messageQueue.complete();
+      }
+      // Reject any pending control response promises
+      this.rejectPendingPromises(new Error('Query closed'));
+    }
+  }
+
+  async initializationResult(): Promise<SDKControlInitializeResponse> {
+    return this.initResponsePromise;
+  }
+
+  async supportedCommands(): Promise<SlashCommand[]> {
+    const init = await this.initResponsePromise;
+    return init.commands;
+  }
+
+  async supportedModels(): Promise<ModelInfo[]> {
+    const init = await this.initResponsePromise;
+    return init.models;
+  }
+
+  async availableOutputStyles(): Promise<string[]> {
+    const init = await this.initResponsePromise;
+    return init.available_output_styles;
+  }
+
+  async currentOutputStyle(): Promise<string> {
+    const init = await this.initResponsePromise;
+    return init.output_style;
+  }
+
+  async mcpServerStatus(): Promise<McpServerStatus[]> {
+    const response = await this.sendControlRequestWithResponse<{ mcpServers: McpServerStatus[] }>(
+      ControlRequests.mcpStatus()
+    );
+    return response.mcpServers;
+  }
+
+  async accountInfo(): Promise<AccountInfo> {
+    const init = await this.initResponsePromise;
+    return init.account;
+  }
+
+  async rewindFiles(
+    _userMessageId: string,
+    _options?: { dryRun?: boolean }
+  ): Promise<RewindFilesResult> {
+    throw new Error('rewindFiles() not yet implemented');
+  }
+
+  async reconnectMcpServer(serverName: string): Promise<void> {
+    await this.sendControlRequestWithResponse(ControlRequests.mcpReconnect(serverName));
+  }
+
+  async toggleMcpServer(serverName: string, enabled: boolean): Promise<void> {
+    await this.sendControlRequestWithResponse(ControlRequests.mcpToggle(serverName, enabled));
+  }
+
+  async setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult> {
+    return this.sendControlRequestWithResponse(ControlRequests.mcpSetServers(servers));
+  }
+
+  // ============================================================================
+  // Private helpers
+  // ============================================================================
+
+  /**
+   * Reject initResponsePromise and all pending control response promises
+   */
+  private rejectPendingPromises(error: Error): void {
+    this.initReject?.(error);
+    for (const [, { reject }] of this.pendingControlResponses) {
+      reject(error);
+    }
+    this.pendingControlResponses.clear();
+  }
+
+  /** Write an NDJSON message to the CLI stdin */
+  private writeToStdin(msg: unknown): void {
+    this.process.stdin?.write(`${JSON.stringify(msg)}\n`);
+  }
+
+  /** Build a control_request envelope for the wire */
+  private buildControlRequest(request: OutboundControlRequest, requestId?: string) {
+    return {
+      type: MessageType.CONTROL_REQUEST,
+      request_id: requestId ?? this.generateRequestId(),
+      request,
+    };
+  }
+
+  private sendControlRequest(request: OutboundControlRequest): void {
+    this.writeToStdin(this.buildControlRequest(request));
+  }
+
+  /**
+   * Send a control request and return a Promise that resolves when the CLI responds
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: response shape varies by request type
+  private sendControlRequestWithResponse<T = any>(request: OutboundControlRequest): Promise<T> {
+    if (this.closed) {
+      return Promise.reject(new Error('Cannot send control request: query is closed'));
+    }
+    const envelope = this.buildControlRequest(request);
+    const promise = new Promise<T>((resolve, reject) => {
+      this.pendingControlResponses.set(envelope.request_id, { resolve, reject });
+    });
+    this.writeToStdin(envelope);
+    return promise;
+  }
+
+  private generateRequestId(): string {
+    return `req_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+  }
+
+  private async sendControlProtocolInit(options: Options): Promise<void> {
+    const requestId = `init_${Date.now()}`;
+    this.initRequestId = requestId;
+
+    // Resolve systemPrompt to match official SDK behavior:
+    // - undefined → systemPrompt: "" (use minimal prompt, saves tokens)
+    // - string → systemPrompt: "..." (custom full prompt)
+    // - { type: 'preset', preset: 'claude_code' } → neither field (use claude_code preset)
+    // - { type: 'preset', preset: 'claude_code', append: '...' } → appendSystemPrompt: "..."
+    let systemPrompt: string | undefined;
+    let appendSystemPrompt: string | undefined;
+
+    if (options.systemPrompt === undefined) {
+      systemPrompt = '';
+    } else if (typeof options.systemPrompt === 'string') {
+      systemPrompt = options.systemPrompt;
+    } else if (options.systemPrompt.type === 'preset' && options.systemPrompt.append) {
+      appendSystemPrompt = options.systemPrompt.append;
+    }
+
+    const request: {
+      subtype: typeof RequestSubtype.INITIALIZE;
+      systemPrompt?: string;
+      appendSystemPrompt?: string;
+      sdkMcpServers?: string[];
+      agents?: Record<string, unknown>;
+      hooks?: ReturnType<typeof buildHookConfig>;
+    } = {
+      subtype: RequestSubtype.INITIALIZE,
+      ...(systemPrompt !== undefined && { systemPrompt }),
+      ...(appendSystemPrompt !== undefined && { appendSystemPrompt }),
+      ...(this.sdkMcpServerNames.length > 0 && { sdkMcpServers: this.sdkMcpServerNames }),
+      ...(options.agents && { agents: options.agents }),
+    };
+
+    // Register hooks if configured
+    if (options.hooks) {
+      request.hooks = buildHookConfig(options.hooks, this.controlHandler);
+    }
+
+    const init = {
+      type: MessageType.CONTROL_REQUEST,
+      request_id: requestId,
+      request,
+    };
+
+    if (process.env.DEBUG_HOOKS) {
+      console.error('[DEBUG] Sending control protocol init:', JSON.stringify(init, null, 2));
+    }
+
+    this.writeToStdin(init);
+  }
+
+  private sendInitialPrompt(prompt: string): void {
+    const initialMessage: SDKUserMessage = {
+      type: 'user',
+      message: {
+        role: 'user',
+        content: [{ type: 'text', text: prompt }],
+      },
+      session_id: '',
+      parent_tool_use_id: null,
+    };
+
+    this.writeToStdin(initialMessage);
+  }
+
+  private async consumeInputGenerator(generator: AsyncIterable<SDKUserMessage>): Promise<void> {
+    try {
+      for await (const userMsg of generator) {
+        this.writeToStdin(userMsg);
+      }
+    } catch (error: unknown) {
+      const wrappedError = error instanceof Error ? error : new Error(String(error));
+      console.error('[QueryImpl] Error consuming input generator:', wrappedError);
+      if (!this.messageQueue.isDone()) {
+        this.messageQueue.complete(wrappedError);
+      }
+    }
+  }
+}

package/src/api/query.ts

@@ -0,0 +1,36 @@
+/**
+ * Main query implementation - spawns Claude CLI and streams messages
+ *
+ * Reference: https://buildwithaws.substack.com/p/inside-the-claude-agent-sdk-from
+ */
+
+import type { Options, Query, SDKUserMessage } from '../types/index.ts';
+import { QueryImpl } from './QueryImpl.ts';
+
+/**
+ * Main query function - returns Query interface with control methods
+ *
+ * Features:
+ * - AsyncGenerator for streaming messages
+ * - Control methods: interrupt(), setPermissionMode(), setModel(), etc.
+ * - Multi-turn conversations via streamInput() OR AsyncIterable input
+ * - Permission callbacks via options.canUseTool
+ * - Hook callbacks via options.hooks
+ *
+ * Input modes:
+ * - String: Simple one-shot or multi-turn via streamInput()
+ * - AsyncIterable: Streaming input mode (recommended for complex flows)
+ *
+ * Tip: Cast to ExtendedQuery to access extra convenience methods:
+ *   const q = query({ prompt: '...' }) as ExtendedQuery;
+ *   const styles = await q.availableOutputStyles();
+ *
+ * @param params Query parameters (prompt and options)
+ * @returns Query interface (AsyncGenerator + control methods)
+ */
+export function query(params: {
+  prompt: string | AsyncIterable<SDKUserMessage>;
+  options?: Options;
+}): Query {
+  return QueryImpl.create(params);
+}