@iflow-ai/iflow-cli-sdk 0.1.9 → 0.2.0-beta.0

package/CHANGELOG.md

@@ -7,6 +7,20 @@
 
 ---
 
+## [0.2.0-beta.0] - 2026-01-27
+
+### 新增能力
+- 配置选项支持 `stream` 参数控制流式输出(依赖 iFlow CLI v0.5.2+)
+- 新增 `setThink()` 方法，支持配置思考模式
+- 新增 `connect()` 时，支持加载已有会话
+- 新增用户交互方法：
+  - `respondToAskUserQuestions()` - 响应 AI 问题请求
+  - `respondToExitPlanMode()` - 响应计划审批请求
+- 新增工具权限请求处理，支持 `respondToPermissionRequest()` 和 `rejectPermissionRequest()` 方法
+- `sendMessage()` 支持图像和文本选择等多种文件类型
+
+---
+
 ## [0.1.9] - 2026-01-26
 
 ### 优化

package/README.md

@@ -14,18 +14,12 @@ A powerful TypeScript SDK for interacting with iFlow CLI using the Agent Communi
 - 🚀 **Automatic Process Management** - Zero-config setup! SDK auto-starts and manages iFlow CLI
 - 🔌 **Smart Port Detection** - Automatically finds available ports, no conflicts
 - 🔄 **Bidirectional Communication** - Real-time streaming of messages and responses
-- 🛠️ **Tool Call Management** - Handle and control tool executions with fine-grained permissions
-- 🤖 **SubAgent Support** - Track and manage multiple AI agents with `agentId` propagation
-- 📋 **Task Planning** - Receive and process structured task plans
-- 🔍 **Raw Data Access** - Debug and inspect protocol-level messages
-- ⚡ **Async/Await Support** - Modern asynchronous Python with full type hints
+- 🛠️ **Tool Call Management** - Handle and control tool executions
+- 🔐 **Permission Request Handling** - Manage and respond to tool execution permission requests
+- 💬 **Interactive Questions** - AI can ask users questions during execution
+- 📝 **Plan Approval** - Review and approve AI plans before execution
+- ⚡ **Async/Await Support** - Modern asynchronous TypeScript with full type hints
 - 🎯 **Simple & Advanced APIs** - From one-line queries to complex conversation management
-- 📦 **Full ACP v1 Protocol** - Complete implementation of the Agent Communication Protocol
-- 🚦 **Advanced Approval Modes** - Including `default`, `autoEdit`, `yolo`, and `plan` modes
-- 🔗 **MCP Server Integration** - Support for Model Context Protocol servers
-- 🪝 **Lifecycle Hooks** - Execute commands at different stages of conversation
-- 🎮 **Session Settings** - Fine-grained control over model behavior and tools
-- 🤖 **Custom Agents** - Define specialized agents with custom prompts and tools
 
 ## Installation
 
@@ -57,8 +51,6 @@ npm install --save @iflow-ai/iflow-cli-sdk
 
 The SDK **automatically manages the iFlow process** - no manual setup required!
 
-### Default Usage (Automatic Process Management)
-
 ```ts
 import { IFlowClient } from "@iflow-ai/iflow-cli-sdk";
 
@@ -73,256 +65,316 @@ async function main() {
   await client.connect();
   await client.sendMessage("Hello, iFlow!");
 
-  for await (const message in client.receiveMessages()) {
+  for await (const message of client.receiveMessages()) {
     console.log(message);
     // Process messages...
   }
+
+  await client.disconnect();
 }
 ```
 
 **No need to manually start iFlow!** The SDK handles everything for you.
 
-### Advanced: Manual Process Control
+## Examples
 
-If you need to manage iFlow yourself (rare cases):
+### Simple Query
 
-```ts
-import { IFlowClient } from "@iflow-ai/iflow-cli-sdk";
+Use the convenience function for one-off queries:
 
-async function main() {
-  // Disable automatic process management
-  const client = new IFlowClient({
-    url: "ws://localhost:8090/acp", // Connect to existing iFlow
-    autoStartProcess: false,
-  });
+```ts
+import { query } from "@iflow-ai/iflow-cli-sdk";
 
-  await client.connect();
-  await client.sendMessage("Hello, iFlow!");
-}
+const response = await query("What is the capital of France?");
+console.log(response);
 ```
 
-**Note:** Manual mode requires you to start iFlow separately:
+### Interactive Conversation
 
-```bash
-iflow --experimental-acp --port 8090
-```
+For more control over the conversation:
 
-### Simple Examples
+```ts
+import { IFlowClient } from "@iflow-ai/iflow-cli-sdk";
 
-#### Simple Query
+const client = new IFlowClient();
 
-```ts
-import { query } from "@iflow-ai/iflow-cli-sdk";
+await client.connect();
+await client.sendMessage("Explain quantum computing");
 
-async function main() {
-  const response = await query("What is the capital of France?");
-  console.log(response); // "The capital of France is Paris."
+for await (const message of client.receiveMessages()) {
+  if (message.type === "assistant" && message.chunk.text) {
+    console.log(message.chunk.text);
+  } else if (message.type === "task_finish") {
+    break;
+  }
 }
+
+await client.disconnect();
 ```
 
-#### Interactive Conversation
+### Tool Call Monitoring
+
+Monitor tool executions:
 
 ```ts
-import { IFlowClient, MessageType } from "@iflow-ai/iflow-cli-sdk";
+import { IFlowClient } from "@iflow-ai/iflow-cli-sdk";
 
-async function main() {
-  const client = new IFlowClient();
+const client = new IFlowClient({ permissionMode: "auto" });
 
-  await client.connect();
-  await client.sendMessage("Explain quantum computing");
+await client.connect();
+await client.sendMessage("Create a file called test.txt");
 
-  for await (const message in client.receiveMessages()) {
-    if (message.type === MessageType.ASSISTANT && message.chunk.text) {
-      console.log(message.chunk.text);
-    } else if (message.type === MessageType.TASK_FINISH) {
-      break;
+for await (const message of client.receiveMessages()) {
+  if (message.type === "tool_call") {
+    console.log(`Tool: ${message.toolName}, Status: ${message.status}`);
+    if (message.output) {
+      console.log(`Output: ${message.output}`);
     }
+  } else if (message.type === "task_finish") {
+    break;
   }
 }
+
+await client.disconnect();
 ```
 
-#### Tool Call Control with Agent Information
+### Enhanced File Types
+
+The SDK supports multiple file types beyond simple file paths:
 
 ```ts
-import { IFlowClient, PermissionMode, MessageType } from "@iflow-ai/iflow-cli-sdk";
+import { IFlowClient } from "@iflow-ai/iflow-cli-sdk";
 
-async function main() {
-  const client = new IFlowClient({
-    permissionMode: PermissionMode.AUTO,
-  })
+const client = new IFlowClient();
+await client.connect();
 
-  await client.connect();
-  await client.sendMessage("Create a file called test.txt");
-
-  for await (const message in client.receiveMessages()) {
-    if (message.type === MessageType.TOOL_CALL) {
-      console.log(`Tool name: ${message.toolName}`);
-      console.log(`Tool status: ${message.status}`);
-
-      if (message.agentInfo) {
-        console.log(`Agent ID: ${message.agentInfo.agentId}`);
-        console.log(`Task ID: ${message.agentInfo.taskId}`);
-        console.log(`Agent index: ${message.agentInfo.agentIndex}`);
-      }
-
-      if (message.args) {
-        console.log(message.args);
-      }
-      if (message.output) {
-        console.log(message.output);
-      }
-    } else if (message.type === MessageType.TASK_FINISH) {
-      break;
-    }
+// 1. Use image data
+const image = {
+  type: "image" as const,
+  data: "base64-encoded-image-data",
+  mimeType: "image/png"
+};
+await client.sendMessage("Analyze this image", [image]);
+
+// 2. Use text selection
+const selection = {
+  type: "selection" as const,
+  data: "const sum = (a, b) => a + b;",
+  uri: "file:///path/to/file.ts",
+  line: { start: 1, end: 2 }
+};
+await client.sendMessage("Explain this code", [selection]);
+
+// 3. Mix different file types
+await client.sendMessage("Analyze these files", [
+  "package.json",  // File path
+  image,          // Image data
+  selection       // Text selection
+]);
+
+await client.disconnect();
+```
+
+### Interactive Questions
+
+Handle AI questions during execution:
+
+```ts
+import { IFlowClient } from "@iflow-ai/iflow-cli-sdk";
+
+const client = new IFlowClient();
+await client.connect();
+await client.sendMessage("Help me create a web server");
+
+for await (const message of client.receiveMessages()) {
+  if (message.type === "ask_user_questions") {
+    // Display questions
+    message.questions.forEach(q => {
+      console.log(`${q.question}`);
+      q.options.forEach(opt => console.log(`- ${opt.label}`));
+    });
+
+    // Collect and send answers
+    const answers = {
+      [message.questions[0].header]: message.questions[0].options[0].label
+    };
+    await client.respondToAskUserQuestions(answers);
+  } else if (message.type === "task_finish") {
+    break;
   }
 }
+
+await client.disconnect();
 ```
 
-#### Working with AgentInfo
+### Plan Approval
+
+Review and approve AI plans:
 
 ```ts
-import { IFlowClient, MessageType } from "@iflow-ai/iflow-cli-sdk";
-
-const options: IFlowOptions = {
-  agents: [
-    {
-      agentType: "code-reviewer",
-      name: "reviewer",
-      description: "Code review specialist",
-      whenToUse: "For code review and quality checks",
-      allowedTools: ["fs", "grep"],
-      allowedMcps: ["eslint", "prettier"],
-      systemPrompt: "You are a code review expert.",
-      proactive: False,
-      location: "project",
-    },
-    {
-      agentType: "test-writer",
-      name: "tester",
-      description: "Test writing specialist",
-      whenToUse: "For writing unit and integration tests",
-      allowedTools: ["fs", "bash"],
-      systemPrompt: "You are a test writing expert.",
-      location: "project",
-    },
-  ],
-};
+import { IFlowClient } from "@iflow-ai/iflow-cli-sdk";
 
-async function main() {
-  const client = new IFlowClient(options)
+const client = new IFlowClient();
+await client.connect();
+await client.sendMessage("Refactor the authentication module");
+
+for await (const message of client.receiveMessages()) {
+  if (message.type === "exit_plan_mode") {
+    console.log("AI Plan:", message.plan);
+    
+    // Approve or reject the plan
+    const approved = true;
+    await client.respondToExitPlanMode(approved);
+  } else if (message.type === "task_finish") {
+    break;
+  }
+}
 
-  await client.connect();
-  await client.sendMessage("$test-writer Write a unit test");
-
-  for await (const message in client.receiveMessages()) {
-    if (message.type === MessageType.TOOL_CALL) {
-      console.log(`Tool name: ${message.toolName}`);
-
-      if (message.args) {
-        console.log(message.args);
-      }
-      if (message.output) {
-        console.log(message.output);
-      }
-    } if (message.type === MessageType.ASSISTANT && message.chunk.text) {
-      console.log(message.chunk.text);
-    } else if (message.type === MessageType.TASK_FINISH) {
-      break;
+await client.disconnect();
+```
+
+### Permission Request Handling
+
+Handle tool execution permission requests from AI:
+
+```ts
+import { IFlowClient } from "@iflow-ai/iflow-cli-sdk";
+
+const client = new IFlowClient();
+await client.connect();
+await client.sendMessage("Create a file and write some code");
+
+for await (const message of client.receiveMessages()) {
+  if (message.type === "permission_request") {
+    console.log(`Tool permission request: ${message.toolCall.title}`);
+    console.log(`Request ID: ${message.requestId}`);
+    
+    // Display available options
+    console.log("Available options:");
+    message.options.forEach(option => {
+      console.log(`- ${option.optionId}`);
+    });
+    
+    // Based on user input, either approve or cancel
+    const userChoice = "proceed_once"; // or based on user input
+    
+    if (userChoice === "cancel") {
+      await client.cancelToolConfirmation(message.requestId);
+      console.log("Permission request cancelled");
+    } else {
+      await client.respondToToolConfirmation(message.requestId, userChoice);
+      console.log(`Permission approved with option: ${userChoice}`);
     }
+  } else if (message.type === "task_finish") {
+    break;
   }
 }
+
+await client.disconnect();
 ```
 
-#### Advanced Protocol Features
+### Configuration Management
+
+Manage session configuration for models and modes:
 
 ```ts
-import { IFlowClient, IFlowOptions, ApprovalMode, HookEventType } from "@iflow-ai/iflow-cli-sdk";
-
-const options: IFlowOptions = {
-  mcpServers: [
-    {
-      name: "filesystem",
-      command: "mcp-server-filesystem",
-      args: ["--allowed-dirs", "/workspace"],
-      env: [
-        {
-          name: "DEBUG",
-          value: "1",
-        },
-      ],
-    },
-  ],
-
-  sessionSettings: {
-    allowed_tools: ["read_file", "write_file", "execute_code"],
-    system_prompt: "You are an expert Python developer",
-    permission_mode: ApprovalMode.AUTO_EDIT,
-    max_turns: 100,
-  },
-
-  hooks: {
-    [HookEventType.PRE_TOOL_USE]: [
-      {
-        hooks: {
-          command: "echo 'Processing request...'",
-          timeout: 5,
-        },
-      },
-    ],
-  },
-
-  commands: [
-    {
-      name: "test",
-      content: "pytest --verbose",
-    },
-  ],
-
-  agents: [
-    {
-      agentType: "python-expert",
-      whenToUse: "For Python development tasks",
-      allowedTools: ["edit_file", "run_python", "debug"],
-      systemPrompt: "You are a Python expert focused on clean, efficient code",
-      name: "Python Expert",
-      description: "Specialized in Python development",
-    },
-  ],
-};
+import { IFlowClient } from "@iflow-ai/iflow-cli-sdk";
 
-async function main() {
-  const client = new IFlowClient(options);
+const client = new IFlowClient();
+await client.connect();
 
-  await client.connect();
-  await client.sendMessage("$test-writer Write a unit test");
+// Get available models and modes
+const models = await client.config.get("models");
+const modes = await client.config.get("modes");
 
-  // Process responses...
-}
+console.log("Available models:", models);
+console.log("Available modes:", modes);
+
+// Get current configuration
+const currentModel = await client.config.get("model");
+const currentMode = await client.config.get("mode");
+
+console.log("Current model:", currentModel);
+console.log("Current mode:", currentMode);
+
+// Set new configuration
+await client.config.set("model", "glm-4.7");
+await client.config.set("mode", "plan");
+
+console.log("Switched to glm-4.7 model and plan mode");
+
+await client.disconnect();
 ```
 
-## API Reference
+### Complete Configuration Example
+
+```ts
+import { IFlowClient } from "@iflow-ai/iflow-cli-sdk";
 
-### Core Classes
+async function configExample() {
+  const client = new IFlowClient();
+  
+  try {
+    await client.connect();
+    
+    // Get all available configuration
+    const models = await client.config.get("models");
+    const modes = await client.config.get("modes");
+    const commands = await client.config.get("commands");
+    const agents = await client.config.get("agents");
+    const skills = await client.config.get("skills");
+    const mcpServers = await client.config.get("mcpServers");
+    
+    console.log("=== Configuration Information ===");
+    console.log("Available models:", models);
+    console.log("Available modes:", modes);
+    console.log("Available commands:", commands);
+    console.log("Available agents:", agents);
+    console.log("Available skills:", skills);
+    console.log("Available MCP servers:", mcpServers);
+    
+    // Save original configuration
+    const originalModel = await client.config.get("model");
+    const originalMode = await client.config.get("mode");
+    
+    // Temporarily switch configuration
+    await client.config.set("model", "glm-4.7");
+    await client.config.set("mode", "plan");
+    
+    console.log("Switched to glm-4.7 model and plan mode");
+    
+    // Restore original configuration
+    await client.config.set("model", originalModel);
+    await client.config.set("mode", originalMode);
+    
+    console.log("Restored original configuration");
+    
+  } finally {
+    await client.disconnect();
+  }
+}
 
-- **`IFlowClient`**: Main client for bidirectional communication
-- **`IFlowOptions`**: Configuration options
-- **`RawDataClient`**: Access to raw protocol data
+configExample().catch(console.error);
+```
 
-### Message Types
+## API Reference
 
-- **`AssistantMessage`**: AI assistant responses with optional agent information
-- **`ToolCallMessage`**: Tool execution requests with execution details (toolName, args, output) and agent information
-- **`PlanMessage`**: Structured task plans with priority and status
-- **`TaskFinishMessage`**: Task completion signal with stop reason (end_urn, max_tokens, refusal, cancelled)
+详细的 API 文档请查看 [API_REFERENCE.md](API_REFERENCE.md)
 
-### Agent Information
+### 核心类
 
-- **`AgentInfo`**: Agent metadata extracted from iFlow's agentId format (agentId, taskId, agentIndex, timestamp)
+- **`IFlowClient`** - 主要客户端类
+- **`query()`** / **`queryStream()`** - 便捷查询函数
 
-### Convenience Functions
+### 主要消息类型
 
-- `query(prompt)`: Simple synchronous query
-- `queryStream(prompt)`: Streaming responses
+- `AssistantMessage` - AI 响应
+- `ToolCallMessage` - 工具调用
+- `TaskFinishMessage` - 任务完成
+- `AskUserQuestionsMessage` - 用户问题
+- `ExitPlanModeMessage` - 计划审批
+- `PermissionRequestMessage` - 权限请求
+- `ErrorMessage` - 错误消息
 
 ## Project Structure
 
@@ -348,12 +400,19 @@ src/
 
 ## Development
 
+### Build dev package
+```bash
+npm run dev
+```
+
 ### Running Tests
 
 ```bash
 npm test
 ```
 
+> 💡 **Testing Tool**: See [`mock-server/`](./mock-server/) directory for the ACP Mock Server, useful for testing and development without a real CLI.
+
 ### Code Quality
 
 ```bash
@@ -366,26 +425,12 @@ npm run format
 
 ## Protocol Support
 
-The SDK implements the Agent Communication Protocol (ACP) v1 with full extension support, including:
-
-- **Session Management**: Create, load, and manage conversation sessions with advanced settings
-- **Message Types**:
-  - `agent_message_chunk` - Assistant responses
-  - `agent_thought_chunk` - Internal reasoning
-  - `tool_call` / `tool_call_update` - Tool execution lifecycle
-  - `plan` - Structured task planning with priorities
-  - `user_message_chunk` - User message echoing
-  - `stop_reason` - Task completion with reason (end_turn, max_tokens, refusal, cancelled)
-- **Authentication**: Built-in iFlow authentication with token support
-- **File System Access**: Read/write file permissions with configurable limits
-- **SubAgent Support**: Full `agentId` tracking and management
-- **Advanced Features**:
-  - **MCP Servers**: Integrate Model Context Protocol servers for extended capabilities
-  - **Approval Modes**: DEFAULT, AUTO_EDIT, YOLO (auto-approve all), PLAN modes
-  - **Session Settings**: Control allowed tools, system prompts, model selection
-  - **Lifecycle Hooks**: Execute commands at different conversation stages
-  - **Custom Commands**: Define and execute custom commands
-  - **Specialized Agents**: Create agents with specific expertise and tool access
+本 SDK 完整实现了 Agent Communication Protocol (ACP) v1，支持：
+
+- 会话管理和消息流式传输
+- 工具调用和权限控制
+- 用户交互（提问和计划审批）
+- 完整的错误处理
 
 ## Contributing