@iflow-ai/iflow-cli-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present iFlow SDK Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,401 @@
+# iFlow CLI TypeScript SDK
+
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![WebSocket Protocol](https://img.shields.io/badge/protocol-ACP%20v1-orange)](docs/protocol.md)
+
+[English](README.md) | [中文](README_CN.md)
+
+A powerful TypeScript SDK for interacting with iFlow CLI using the Agent Communication Protocol (ACP). Build AI-powered applications with full control over conversations, tool execution, and SubAgent orchestration.
+
+**✨ Key Feature: The SDK automatically manages the iFlow process - no manual setup required!**
+
+## Features
+
+- 🚀 **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
+- 🎯 **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
+
+### 1. Install iFlow CLI
+
+If you haven't installed iFlow CLI yet:
+
+**Mac/Linux/Ubuntu:**
+
+```bash
+bash -c "$(curl -fsSL https://cloud.iflow.cn/iflow-cli/install.sh)"
+```
+
+**Windows:**
+
+```bash
+npm install -g @iflow-ai/iflow-cli@latest
+```
+
+### 2. Install the SDK
+
+**Install from NPM:**
+
+```bash
+npm install --save @iflow-ai/iflow-cli-sdk
+```
+
+## Quick Start
+
+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";
+
+async function main() {
+  // SDK automatically:
+  // 1. Detects if iFlow is installed
+  // 2. Starts iFlow process if not running
+  // 3. Finds an available port
+  // 4. Cleans up on exit
+  const client = new IFlowClient();
+
+  await client.connect();
+  await client.sendMessage("Hello, iFlow!");
+
+  for await (const message in client.receiveMessages()) {
+    console.log(message);
+    // Process messages...
+  }
+}
+```
+
+**No need to manually start iFlow!** The SDK handles everything for you.
+
+### Advanced: Manual Process Control
+
+If you need to manage iFlow yourself (rare cases):
+
+```ts
+import { IFlowClient } from "@iflow-ai/iflow-cli-sdk";
+
+async function main() {
+  // Disable automatic process management
+  const client = new IFlowClient({
+    url: "ws://localhost:8090/acp", // Connect to existing iFlow
+    autoStartProcess: false,
+  });
+
+  await client.connect();
+  await client.sendMessage("Hello, iFlow!");
+}
+```
+
+**Note:** Manual mode requires you to start iFlow separately:
+
+```bash
+iflow --experimental-acp --port 8090
+```
+
+### Simple Examples
+
+#### Simple Query
+
+```ts
+import { query } from "@iflow-ai/iflow-cli-sdk";
+
+async function main() {
+  const response = await query("What is the capital of France?");
+  console.log(response); // "The capital of France is Paris."
+}
+```
+
+#### Interactive Conversation
+
+```ts
+import { IFlowClient, MessageType } from "@iflow-ai/iflow-cli-sdk";
+
+async function main() {
+  const client = new IFlowClient();
+
+  await client.connect();
+  await client.sendMessage("Explain quantum computing");
+
+  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;
+    }
+  }
+}
+```
+
+#### Tool Call Control with Agent Information
+
+```ts
+import { IFlowClient, PermissionMode, MessageType } from "@iflow-ai/iflow-cli-sdk";
+
+async function main() {
+  const client = new IFlowClient({
+    permissionMode: PermissionMode.AUTO,
+  })
+
+  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;
+    }
+  }
+}
+```
+
+#### Working with AgentInfo
+
+```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",
+    },
+  ],
+};
+
+async function main() {
+  const client = new IFlowClient(options)
+
+  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;
+    }
+  }
+}
+```
+
+#### Advanced Protocol Features
+
+```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",
+    },
+  ],
+};
+
+async function main() {
+  const client = new IFlowClient(options);
+
+  await client.connect();
+  await client.sendMessage("$test-writer Write a unit test");
+
+  // Process responses...
+}
+```
+
+## API Reference
+
+### Core Classes
+
+- **`IFlowClient`**: Main client for bidirectional communication
+- **`IFlowOptions`**: Configuration options
+- **`RawDataClient`**: Access to raw protocol data
+
+### Message Types
+
+- **`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)
+
+### Agent Information
+
+- **`AgentInfo`**: Agent metadata extracted from iFlow's agentId format (agentId, taskId, agentIndex, timestamp)
+
+### Convenience Functions
+
+- `query(prompt)`: Simple synchronous query
+- `querySync(prompt)`: Synchronous with timeout
+- `queryStream(prompt)`: Streaming responses
+
+## Project Structure
+
+```
+src/
+├── internals/
+│   ├── FileHandler.ts        # File access
+│   ├── ProcessManager.ts     # iFlow process management
+│   ├── Protocol.ts           # ACP protocol handler
+│   └── Transport.ts          # WebSocket transport layer
+├── types/
+│   ├── acp.ts                # ACP data types
+│   ├── messages.ts           # Message types
+│   └── options.ts            # iFlow options
+├── utils/
+│   ├── logger.ts             # Logs util
+│   └── parseAgentId.ts       # Parse agent id
+├── IFlowClient.ts            # Main IFlowClient implementation
+├── RawDataClient.ts          # Raw protocol access
+├── query.ts                  # Simple query functions
+└── index.ts                  # Main entry
+```
+
+## Development
+
+### Running Tests
+
+```bash
+npm test
+```
+
+### Code Quality
+
+```bash
+# Lint code
+npm run lint
+
+# Format code
+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
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+Built with ❤️ for the AI development community