@iflow-ai/iflow-cli-sdk 0.2.1 → 0.2.2

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 // Generated by dts-bundle-generator v9.5.1
 
+import { ExecaChildProcess } from 'execa';
+
 /**
  * iFlow SDK 错误类定义
  *
@@ -255,6 +257,15 @@ export interface AuthMethodInfo {
 	baseUrl?: string;
 	modelName?: string;
 }
+/**
+ * 传输模式枚举
+ */
+export declare enum TransportMode {
+	/** WebSocket 模式 - 通过 WebSocket 连接通信（默认） */
+	WEBSOCKET = "websocket",
+	/** stdio 模式 - 通过标准输入输出通信 */
+	STDIO = "stdio"
+}
 export interface IFlowOptions {
 	url?: string;
 	cwd?: string;
@@ -264,6 +275,26 @@ export interface IFlowOptions {
 	processStartPort?: number;
 	autoStartProcess?: boolean;
 	stream?: boolean;
+	/** 传输模式，可选 "websocket"（默认）或 "stdio" */
+	transportMode?: `${TransportMode}`;
+	/**
+	 * 自定义 iflow 可执行文件的绝对路径（可选）
+	 *
+	 * @remarks
+	 * - 如果指定，将优先使用此路径，不会执行系统 PATH 查找
+	 * - 必须是绝对路径（如 `/usr/local/bin/iflow` 或 `C:\Program Files\iflow\iflow.exe`）
+	 * - SDK 会验证文件是否存在且可执行
+	 * - 如果路径无效，会立即抛出错误
+	 *
+	 * @example
+	 * ```typescript
+	 * const client = new IFlowClient({
+	 *   iflowPath: "/opt/custom/iflow",
+	 *   autoStartProcess: true
+	 * });
+	 * ```
+	 */
+	iflowPath?: string;
 	authMethodId?: string;
 	authMethodInfo?: AuthMethodInfo;
 	mcpServers?: MCPServerConfigs;
@@ -755,71 +786,55 @@ export interface SetThinkResult {
 	currentThinkConfig?: string;
 }
 /**
- * 日志记录器配置选项
- */
-export interface LoggerOptions {
-	/** 日志级别，默认为 INFO */
-	level?: keyof typeof LogLevel;
-}
-declare class Logger {
-	private readonly level;
-	constructor(options?: Partial<LoggerOptions>);
-	debug(message: string): void;
-	info(message: string): void;
-	warn(message: string): void;
-	error(message: string, error?: Error): void;
-	private log;
-}
-/**
- * Transport 类构造选项
+ * ITransport - 传输层抽象接口
+ *
+ * 定义了传输层的统一接口，支持不同的传输协议（WebSocket、stdio 等）
  */
-export interface TransportOptions {
-	/** WebSocket 连接 URL */
-	url: string;
-	/** 日志记录器实例 */
-	logger?: Logger;
-	/** 连接超时时间（毫秒），默认 300000ms (5分钟) */
-	timeout?: number;
-}
-declare class Transport {
-	private readonly url;
-	private readonly logger;
-	private readonly timeout;
-	private ws;
-	private connected;
-	private messageQueue;
-	private waitingResolvers;
-	private generalWaiters;
-	constructor(options: TransportOptions);
-	get isConnected(): boolean;
-	private checkConnected;
-	connect(): Promise<void>;
+export interface ITransport {
 	/**
-	 * 设置持续的消息监听器
-	 * 收到消息后，优先分发给等待的 resolver，否则放入消息队列
+	 * 检查是否已连接
 	 */
-	private setupMessageListener;
+	readonly isConnected: boolean;
 	/**
-	 * 拒绝所有等待的 Promise（包括基于 requestId 的和通用的）
+	 * 建立连接
+	 */
+	connect(): Promise<void>;
+	/**
+	 * 关闭连接
 	 */
-	private rejectAllWaiters;
 	close(): Promise<void>;
+	/**
+	 * 发送消息
+	 * @param data 要发送的数据，可以是字符串或对象
+	 */
 	send(data: string | object): Promise<void>;
 	/**
 	 * 等待指定 requestId 的响应
-	 * 用于 Protocol 层等待特定请求的响应，支持并发请求
 	 * @param requestId 请求 ID（可以是 number 或 string）
 	 * @returns Promise，resolve 时返回响应消息的原始字符串
 	 */
 	waitForResponse(requestId: number | string): Promise<string>;
-	receive(): AsyncGenerator<string>;
 	/**
-	 * 接收原始数据
-	 * - 如果提供 requestId，则等待匹配该 requestId 的响应
-	 * - 如果不提供 requestId，则从消息队列获取，队列为空时等待任何新消息
-	 * @param requestId 可选的请求 ID（可以是 number 或 string），用于精确匹配响应
+	 * 接收消息的异步生成器
+	 * @returns 异步迭代器，yield 每条消息的原始字符串
 	 */
-	private receiveRawData;
+	receive(): AsyncGenerator<string>;
+}
+/**
+ * 日志记录器配置选项
+ */
+export interface LoggerOptions {
+	/** 日志级别，默认为 INFO */
+	level?: keyof typeof LogLevel;
+}
+declare class Logger {
+	private readonly level;
+	constructor(options?: Partial<LoggerOptions>);
+	debug(message: string): void;
+	info(message: string): void;
+	warn(message: string): void;
+	error(message: string, error?: Error): void;
+	private log;
 }
 /**
  * FileHandler 类构造选项
@@ -969,14 +984,16 @@ export interface Selection {
 export interface ProtocolOptions {
 	/** 日志记录器实例 */
 	logger?: Logger;
-	/** WebSocket 传输层实例 */
-	transport: Transport;
+	/** 传输层实例（WebSocket 或 stdio） */
+	transport: ITransport;
 	/** 文件处理器实例，用于文件读写操作 */
 	fileHandler?: FileHandler;
 	/** 权限模式，控制工具调用的审批方式 */
 	permissionMode?: `${PermissionMode}`;
 	/** 自动批准的工具类型列表 */
 	autoApproveTypes?: string[];
+	/** 协议操作超时时间（毫秒），用于 initialize/authenticate/createSession 等 RPC 调用，默认 30000 */
+	timeout?: number;
 }
 declare class Protocol {
 	private readonly logger;
@@ -984,6 +1001,8 @@ declare class Protocol {
 	private readonly fileHandler?;
 	private readonly permissionMode;
 	private readonly autoApproveTypes;
+	/** 协议操作超时时间（毫秒） */
+	private readonly timeout;
 	private requestId;
 	private initialized;
 	private authenticated;
@@ -1019,6 +1038,10 @@ declare class Protocol {
 		sessionId: string;
 		cwd?: string;
 		mcpServers?: MCPServerConfigs;
+		hooks?: HookConfigs;
+		commands?: CommandConfigs;
+		agents?: SubAgentConfigs;
+		settings?: SessionSettings;
 	}): Promise<void>;
 	sendPrompt(params: {
 		sessionId: string;
@@ -1037,7 +1060,7 @@ declare class Protocol {
 	}): Promise<string>;
 	setThink(params: ACPSetThinkParams): Promise<ACPSetThinkResult>;
 	respondToAskUserQuestions(requestId: ACPRequestId, answers: Record<string, string | string[]>): Promise<void>;
-	respondToExitPlanMode(requestId: ACPRequestId, approved: boolean): Promise<void>;
+	respondToExitPlanMode(requestId: ACPRequestId, approved: boolean, reason?: string): Promise<void>;
 	sendPermissionResponse(requestId: ACPRequestId, optionId: string): Promise<void>;
 	cancelPermissionResponse(requestId: ACPRequestId): Promise<void>;
 	handleMessages(): AsyncGenerator<ProtocolMessage>;
@@ -1119,7 +1142,7 @@ export declare class IFlowClient {
 	/** ACP 协议处理器 */
 	protected protocol: Protocol | null;
 	/** WebSocket 传输层 */
-	protected transport: Transport | null;
+	protected transport: ITransport | null;
 	/** 连接状态标识 */
 	protected connected: boolean;
 	/** 认证状态标识 */
@@ -1172,9 +1195,71 @@ export declare class IFlowClient {
 	constructor(options?: IFlowOptions);
 	isConnected(): boolean;
 	getConnectionState(): "disconnected" | "connecting" | "connected";
-	connect(): Promise<void>;
+	getSessionId(): string | null;
+	/**
+	 * 连接到 iFlow CLI
+	 *
+	 * @param options - 连接选项
+	 * @param options.skipSession - 是否跳过会话创建/加载（默认 false）
+	 *   - `false`（默认）：完整连接流程，包括初始化、认证、创建/加载会话
+	 *   - `true`：执行初始化和认证，但跳过会话创建/加载，需要后续手动调用 `newSession()` 或 `loadSession()`
+	 *
+	 * @example
+	 * ```typescript
+	 * // 标准连接（自动创建/加载会话）
+	 * await client.connect();
+	 *
+	 * // 连接并认证，但不创建会话（需要手动调用 newSession 或 loadSession）
+	 * await client.connect({ skipSession: true });
+	 * await client.newSession();  // 或 await client.loadSession('session-id');
+	 * ```
+	 */
+	connect({ skipSession }?: {
+		skipSession?: boolean;
+	}): Promise<void>;
 	private _doConnect;
+	/**
+	 * 确保客户端已认证
+	 * @private
+	 */
+	private _ensureAuthenticated;
+	/**
+	 * 创建新会话的核心逻辑（内部使用）
+	 * @private
+	 */
+	private _createNewSession;
+	/**
+	 * 初始化会话（创建或加载）
+	 * @private
+	 */
+	private _initializeSession;
+	/**
+	 * 加载已存在的会话
+	 *
+	 * @param sessionId - 要加载的会话 ID
+	 *
+	 * @example
+	 * ```typescript
+	 * // 使用 skipSession 连接后，手动加载会话
+	 * await client.connect({ skipSession: true });
+	 * await client.loadSession("existing-session-id");
+	 * ```
+	 */
 	loadSession(sessionId: string): Promise<void>;
+	/**
+	 * 创建新会话
+	 *
+	 * @returns 新创建的会话 ID
+	 *
+	 * @example
+	 * ```typescript
+	 * // 使用 skipSession 连接后，手动创建新会话
+	 * await client.connect({ skipSession: true });
+	 * const sessionId = await client.newSession();
+	 * console.log(`Created session: ${sessionId}`);
+	 * ```
+	 */
+	newSession(): Promise<string>;
 	disconnect(): Promise<void>;
 	sendMessage(text: string, files?: Array<FilePath | ImagePrompt | Selection>): Promise<void>;
 	interrupt(): Promise<void>;
@@ -1190,7 +1275,7 @@ export declare class IFlowClient {
 	 */
 	rejectToolCall(toolId: string): Promise<void>;
 	respondToAskUserQuestions(answers: Record<string, string | string[]>): Promise<void>;
-	respondToExitPlanMode(approved: boolean): Promise<void>;
+	respondToExitPlanMode(approved: boolean, reason?: string): Promise<void>;
 	respondToToolConfirmation(requestId: number | string, optionId: string): Promise<void>;
 	cancelToolConfirmation(requestId: number | string): Promise<void>;
 	/**
@@ -1233,6 +1318,172 @@ export declare class RawDataClient extends IFlowClient {
 	getProtocolStats(): Record<string, any>;
 	sendRaw(data: string | Record<string, any>): Promise<void>;
 }
+/**
+ * Transport 类构造选项
+ */
+export interface TransportOptions {
+	/** WebSocket 连接 URL */
+	url: string;
+	/** 日志记录器实例 */
+	logger?: Logger;
+	/** 连接超时时间（毫秒），默认 300000ms (5分钟) */
+	timeout?: number;
+}
+/**
+ * Transport - WebSocket 传输层
+ *
+ * 负责管理与 iFlow CLI 的 WebSocket 连接，提供：
+ * - 连接建立和断开管理
+ * - 消息发送和接收
+ * - 连接状态监控
+ * - 错误处理和重连机制
+ * - 超时控制
+ *
+ * 这是 SDK 的底层通信组件，所有与 iFlow CLI 的数据交换都通过此类进行。
+ *
+ * @example
+ * ```typescript
+ * const transport = new Transport({
+ *   url: "ws://localhost:8090/acp",
+ *   timeout: 30000,
+ *   logger: new Logger({ level: "DEBUG" })
+ * });
+ *
+ * await transport.connect();
+ * transport.send({ method: "initialize", params: {} });
+ *
+ * transport.onMessage((message) => {
+ *   console.log("Received:", message);
+ * });
+ * ```
+ */
+export declare class Transport implements ITransport {
+	private readonly url;
+	private readonly logger;
+	private readonly timeout;
+	private ws;
+	private connected;
+	private messageQueue;
+	private waitingResolvers;
+	private generalWaiters;
+	constructor(options: TransportOptions);
+	get isConnected(): boolean;
+	private checkConnected;
+	connect(): Promise<void>;
+	/**
+	 * 设置持续的消息监听器
+	 * 收到消息后，优先分发给等待的 resolver，否则放入消息队列
+	 */
+	private setupMessageListener;
+	/**
+	 * 拒绝所有等待的 Promise（包括基于 requestId 的和通用的）
+	 */
+	private rejectAllWaiters;
+	close(): Promise<void>;
+	send(data: string | object): Promise<void>;
+	/**
+	 * 等待指定 requestId 的响应
+	 * 用于 Protocol 层等待特定请求的响应，支持并发请求
+	 * @param requestId 请求 ID（可以是 number 或 string）
+	 * @returns Promise，resolve 时返回响应消息的原始字符串
+	 */
+	waitForResponse(requestId: number | string): Promise<string>;
+	receive(): AsyncGenerator<string>;
+	/**
+	 * 接收原始数据
+	 * - 如果提供 requestId，则等待匹配该 requestId 的响应
+	 * - 如果不提供 requestId，则从消息队列获取，队列为空时等待任何新消息
+	 * @param requestId 可选的请求 ID（可以是 number 或 string），用于精确匹配响应
+	 */
+	private receiveRawData;
+}
+/**
+ * StdioTransport 类构造选项
+ */
+export interface StdioTransportOptions {
+	/** 子进程实例，用于 stdin/stdout 通信 */
+	process: ExecaChildProcess;
+	/** 日志记录器实例 */
+	logger?: Logger;
+	/** 连接超时时间（毫秒），默认 300000ms (5分钟) */
+	timeout?: number;
+	/** 消息队列最大大小，默认 1000 条消息 */
+	maxQueueSize?: number;
+}
+/**
+ * StdioTransport - stdio 传输层
+ *
+ * 负责通过 stdin/stdout 与 iFlow CLI 进程通信，提供：
+ * - 基于标准输入输出的通信
+ * - 消息发送和接收
+ * - 连接状态监控
+ * - 错误处理
+ * - 超时控制
+ *
+ * 这是 SDK 支持 stdio 协议的核心组件，适用于非 WebSocket 场景。
+ *
+ * @example
+ * ```typescript
+ * import { execa } from "execa";
+ *
+ * const process = execa("iflow", ["--experimental-acp", "--stdio"]);
+ * const transport = new StdioTransport({
+ *   process,
+ *   timeout: 30000,
+ *   logger: new Logger({ level: "DEBUG" })
+ * });
+ *
+ * await transport.connect();
+ * transport.send({ method: "initialize", params: {} });
+ *
+ * for await (const message of transport.receive()) {
+ *   console.log("Received:", message);
+ * }
+ * ```
+ */
+export declare class StdioTransport implements ITransport {
+	private readonly logger;
+	private readonly timeout;
+	private readonly childProcess;
+	private readonly maxQueueSize;
+	private connected;
+	private readlineInterface;
+	private errorHandler;
+	private exitHandler;
+	private messageQueue;
+	private waitingResolvers;
+	private generalWaiters;
+	constructor(options: StdioTransportOptions);
+	get isConnected(): boolean;
+	private checkConnected;
+	connect(): Promise<void>;
+	/**
+	 * 设置持续的消息监听器
+	 * 收到消息后，优先分发给等待的 resolver，否则放入消息队列
+	 */
+	private setupMessageListener;
+	/**
+	 * 拒绝所有等待的 Promise（包括基于 requestId 的和通用的）
+	 */
+	private rejectAllWaiters;
+	close(): Promise<void>;
+	send(data: string | object): Promise<void>;
+	/**
+	 * 等待指定 requestId 的响应
+	 * 用于 Protocol 层等待特定请求的响应，支持并发请求
+	 * @param requestId 请求 ID（可以是 number 或 string）
+	 * @returns Promise，resolve 时返回响应消息的原始字符串
+	 */
+	waitForResponse(requestId: number | string): Promise<string>;
+	receive(): AsyncGenerator<string>;
+	/**
+	 * 接收原始数据
+	 * - 如果提供 requestId，则等待匹配该 requestId 的响应
+	 * - 如果不提供 requestId，则从消息队列获取，队列为空时等待任何新消息
+	 * @param requestId 可选的请求 ID（可以是 number 或 string），用于精确匹配响应
+	 */
+	private receiveRawData;
+}
 /**
  * 简单的异步查询函数 - 发送提示并等待完整响应
  *