@xagent-ai/cli 1.2.2 → 1.3.0

package/docs/architecture/overview.md

@@ -1,169 +1,169 @@
-# Architecture Overview
-
-This document provides a high-level overview of the xAgent CLI architecture.
-
-## Core Philosophy
-
-xAgent CLI is designed as an intelligent agent for personal PCs and autonomous living. It transforms how users interact with their digital life through AI-powered automation.
-
-## System Architecture
-
-### Layered Architecture
-
-```
-┌─────────────────────────────────────────────────┐
-│                  CLI Interface                  │
-│           (Ink/React Components)                │
-├─────────────────────────────────────────────────┤
-│                   Session Layer                 │
-│      (Session + Conversation Management)        │
-├─────────────────────────────────────────────────┤
-│                  Agent System                   │
-│            (SubAgent Orchestration)             │
-├─────────────────────────────────────────────────┤
-│                  Tool Layer                     │
-│      (Built-in + MCP + Skill Tools)             │
-├─────────────────────────────────────────────────┤
-│                 AI Client Layer                 │
-│      (Local + Remote AI Clients)                │
-├─────────────────────────────────────────────────┤
-│              Storage & Config                   │
-│         (Checkpoint, Settings, Memory)          │
-└─────────────────────────────────────────────────┘
-```
-
-## Key Components
-
-### 1. CLI Interface
-- Built with Ink (React for CLI)
-- Interactive terminal UI
-- Theme support
-- Cancellation support (ESC key)
-
-### 2. Session Management
-- `InteractiveSession` - Main session handler
-- `SessionManager` - Session state management
-- `ConversationManager` - Conversation history
-- `CheckpointManager` - State persistence
-- `ContextCompressor` - Context optimization
-
-### 3. Agent System
-- `AgentManager` - Agent configuration and loading
-- Main agent for general tasks
-- Specialized SubAgents:
-  - Plan Agent - Task planning and decomposition
-  - Explore Agent - Codebase exploration
-  - Frontend Tester - Frontend testing
-  - Code Reviewer - Code quality review
-  - Frontend/Backend Developer - Specialized development
-  - GUI SubAgent - Browser/desktop automation
-
-### 4. Tool System
-- `ToolRegistry` - Tool registration and management
-- Built-in tools (20+)
-- MCP integration with dynamic tool loading
-- Skill invocation system (`InvokeSkill` tool)
-- Smart Mode approval system
-
-### 5. AI Client Layer
-- `AIClient` - Local AI client for OpenAI-compatible APIs
-- `RemoteAIClient` - Remote AI client for xAgent web service
-- Multi-model support
-- Token optimization
-
-### 6. GUI SubAgent
-- `ComputerOperator` - Desktop control (mouse, keyboard, screenshots)
-- `GUIAgent` - LLM-driven automation agent
-- Support for local and remote VLM modes
-- Action parsing and execution
-
-### 7. Authentication & Config
-- `AuthService` - OAuth and API key authentication
-- `ConfigManager` - Global and project settings
-- Support for multiple auth types:
-  - `oauth-xagent` - xAgent native authentication
-  - `api_key` - Direct API key
-  - `openai_compatible` - Third-party OpenAI-compatible APIs
-
-## Execution Flow
-
-```
-User Input → Slash Command Parser
-                  ↓
-            Input Processor
-                  ↓
-            Agent Decision
-                  ↓
-      ┌───────────┴───────────┐
-      ↓                       ↓
-  Local Mode             Remote Mode
-  (API Key)              (OAuth)
-      ↓                       ↓
-  Tool Selection         Sync to Remote
-      ↓                       ↓
-  Tool Execution         Remote Approval
-      ↓                       ↓
-  Smart Approval         Tool Execution
-  (if SMART mode)            ↓
-      ↓                  Sync Results
-  Response Output
-      ↓
-  Checkpoint Save
-```
-
-## Security Model
-
-xAgent implements five execution modes:
-- **YOLO**: Full control without restrictions
-- **ACCEPT_EDITS**: File-only modifications
-- **PLAN**: Plan before execution
-- **DEFAULT**: Approval required for actions
-- **SMART**: Intelligent mode with three-layer approval (whitelist, blacklist, AI review)
-
-## Smart Mode Architecture
-
-Smart Mode uses a three-layer approval system:
-
-```
-┌─────────────────────────────────────────┐
-│         Tool Call Request               │
-└─────────────────────────────────────────┘
-                   ↓
-┌─────────────────────────────────────────┐
-│      Layer 1: Whitelist Check           │
-│   (Safe tools → Auto-approved)          │
-└─────────────────────────────────────────┘
-                   ↓
-┌─────────────────────────────────────────┐
-│      Layer 2: Blacklist Check           │
-│   (Dangerous → User confirmation)       │
-└─────────────────────────────────────────┘
-                   ↓
-┌─────────────────────────────────────────┐
-│      Layer 3: AI Review                 │
-│   (Unknown → AI risk assessment)        │
-└─────────────────────────────────────────┘
-```
-
-## Remote Mode Support
-
-xAgent supports two operating modes:
-
-### Local Mode
-- Uses local API key for AI calls
-- All tool execution happens locally
-- Full Smart Mode approval functionality
-- Suitable for self-hosted LLMs
-
-### Remote Mode (OAuth)
-- Uses xAgent web service for AI calls
-- Tools are synced to remote server
-- Approval handled by remote LLM
-- Requires authentication with xAgent account
-
-## Related Documentation
-
-- [Tool System Design](./tool-system-design.md)
-- [MCP Integration Guide](./mcp-integration-guide.md)
-- [CLI Commands](../cli/commands.md)
-- [Smart Mode Documentation](../smart-mode.md)
+# Architecture Overview
+
+This document provides a high-level overview of the xAgent CLI architecture.
+
+## Core Philosophy
+
+xAgent CLI is designed as an intelligent agent for personal PCs and autonomous living. It transforms how users interact with their digital life through AI-powered automation.
+
+## System Architecture
+
+### Layered Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│                  CLI Interface                  │
+│           (Ink/React Components)                │
+├─────────────────────────────────────────────────┤
+│                   Session Layer                 │
+│      (Session + Conversation Management)        │
+├─────────────────────────────────────────────────┤
+│                  Agent System                   │
+│            (SubAgent Orchestration)             │
+├─────────────────────────────────────────────────┤
+│                  Tool Layer                     │
+│      (Built-in + MCP + Skill Tools)             │
+├─────────────────────────────────────────────────┤
+│                 AI Client Layer                 │
+│      (Local + Remote AI Clients)                │
+├─────────────────────────────────────────────────┤
+│              Storage & Config                   │
+│         (Checkpoint, Settings, Memory)          │
+└─────────────────────────────────────────────────┘
+```
+
+## Key Components
+
+### 1. CLI Interface
+- Built with Ink (React for CLI)
+- Interactive terminal UI
+- Theme support
+- Cancellation support (ESC key)
+
+### 2. Session Management
+- `InteractiveSession` - Main session handler
+- `SessionManager` - Session state management
+- `ConversationManager` - Conversation history
+- `CheckpointManager` - State persistence
+- `ContextCompressor` - Context optimization
+
+### 3. Agent System
+- `AgentManager` - Agent configuration and loading
+- Main agent for general tasks
+- Specialized SubAgents:
+  - Plan Agent - Task planning and decomposition
+  - Explore Agent - Codebase exploration
+  - Frontend Tester - Frontend testing
+  - Code Reviewer - Code quality review
+  - Frontend/Backend Developer - Specialized development
+  - GUI SubAgent - Browser/desktop automation
+
+### 4. Tool System
+- `ToolRegistry` - Tool registration and management
+- Built-in tools (20+)
+- MCP integration with dynamic tool loading
+- Skill invocation system (`InvokeSkill` tool)
+- Smart Mode approval system
+
+### 5. AI Client Layer
+- `AIClient` - Local AI client for OpenAI-compatible APIs
+- `RemoteAIClient` - Remote AI client for xAgent web service
+- Multi-model support
+- Token optimization
+
+### 6. GUI SubAgent
+- `ComputerOperator` - Desktop control (mouse, keyboard, screenshots)
+- `GUIAgent` - LLM-driven automation agent
+- Support for local and remote VLM modes
+- Action parsing and execution
+
+### 7. Authentication & Config
+- `AuthService` - OAuth and API key authentication
+- `ConfigManager` - Global and project settings
+- Support for multiple auth types:
+  - `oauth-xagent` - xAgent native authentication
+  - `api_key` - Direct API key
+  - `openai_compatible` - Third-party OpenAI-compatible APIs
+
+## Execution Flow
+
+```
+User Input → Slash Command Parser
+                  ↓
+            Input Processor
+                  ↓
+            Agent Decision
+                  ↓
+      ┌───────────┴───────────┐
+      ↓                       ↓
+  Local Mode             Remote Mode
+  (API Key)              (OAuth)
+      ↓                       ↓
+  Tool Selection         Sync to Remote
+      ↓                       ↓
+  Tool Execution         Remote Approval
+      ↓                       ↓
+  Smart Approval         Tool Execution
+  (if SMART mode)            ↓
+      ↓                  Sync Results
+  Response Output
+      ↓
+  Checkpoint Save
+```
+
+## Security Model
+
+xAgent implements five execution modes:
+- **YOLO**: Full control without restrictions
+- **ACCEPT_EDITS**: File-only modifications
+- **PLAN**: Plan before execution
+- **DEFAULT**: Approval required for actions
+- **SMART**: Intelligent mode with three-layer approval (whitelist, blacklist, AI review)
+
+## Smart Mode Architecture
+
+Smart Mode uses a three-layer approval system:
+
+```
+┌─────────────────────────────────────────┐
+│         Tool Call Request               │
+└─────────────────────────────────────────┘
+                   ↓
+┌─────────────────────────────────────────┐
+│      Layer 1: Whitelist Check           │
+│   (Safe tools → Auto-approved)          │
+└─────────────────────────────────────────┘
+                   ↓
+┌─────────────────────────────────────────┐
+│      Layer 2: Blacklist Check           │
+│   (Dangerous → User confirmation)       │
+└─────────────────────────────────────────┘
+                   ↓
+┌─────────────────────────────────────────┐
+│      Layer 3: AI Review                 │
+│   (Unknown → AI risk assessment)        │
+└─────────────────────────────────────────┘
+```
+
+## Remote Mode Support
+
+xAgent supports two operating modes:
+
+### Local Mode
+- Uses local API key for AI calls
+- All tool execution happens locally
+- Full Smart Mode approval functionality
+- Suitable for self-hosted LLMs
+
+### Remote Mode (OAuth)
+- Uses xAgent web service for AI calls
+- Tools are synced to remote server
+- Approval handled by remote LLM
+- Requires authentication with xAgent account
+
+## Related Documentation
+
+- [Tool System Design](./tool-system-design.md)
+- [MCP Integration Guide](./mcp-integration-guide.md)
+- [CLI Commands](../cli/commands.md)
+- [Smart Mode Documentation](../smart-mode.md)

package/docs/architecture/tool-system-design.md

@@ -1,134 +1,134 @@
-# Tool System Design
-
-This document describes the tool system architecture and design principles.
-
-## Overview
-
-xAgent CLI provides a rich set of built-in tools plus support for external tools via MCP (Model Context Protocol). Tools are the primary way agents interact with the filesystem, execute commands, and perform actions.
-
-## Tool Categories
-
-### File Operations
-| Tool | Description | Permissions Required |
-|------|-------------|---------------------|
-| `Read` | Read file contents | YOLO, ACCEPT_EDITS, PLAN, SMART |
-| `Write` | Create or overwrite files | YOLO, ACCEPT_EDITS, SMART |
-| `replace` | Replace text in files | YOLO, ACCEPT_EDITS, SMART |
-| `DeleteFile` | Delete files | YOLO, ACCEPT_EDITS, SMART |
-
-### Search Tools
-| Tool | Description | Permissions Required |
-|------|-------------|---------------------|
-| `Grep` | Search text patterns | All modes |
-| `SearchCodebase` | Find files by pattern | All modes |
-| `web_search` | Search the web | YOLO, ACCEPT_EDITS, PLAN, SMART |
-| `web_fetch` | Fetch web content | YOLO, ACCEPT_EDITS, PLAN, SMART |
-
-### Execution Tools
-| Tool | Description | Permissions Required |
-|------|-------------|---------------------|
-| `Bash` | Execute shell commands | YOLO, ACCEPT_EDITS, SMART |
-| `ListDirectory` | List directory contents | All modes |
-| `CreateDirectory` | Create directories | YOLO, ACCEPT_EDITS, SMART |
-
-### Task Management
-| Tool | Description | Permissions Required |
-|------|-------------|---------------------|
-| `todo_write` | Create/manage task lists | All modes |
-| `todo_read` | Read task lists | All modes |
-| `task` | Launch SubAgents | YOLO, ACCEPT_EDITS, PLAN, SMART |
-
-### GUI Automation
-| Tool | Description | Permissions Required |
-|------|-------------|---------------------|
-| `gui_operate` | GUI browser automation | YOLO, ACCEPT_EDITS, SMART |
-| `gui_screenshot` | Take browser screenshot | YOLO, ACCEPT_EDITS, SMART |
-| `gui_cleanup` | Cleanup GUI instances | YOLO, ACCEPT_EDITS, SMART |
-
-### Skill Invocation
-| Tool | Description | Permissions Required |
-|------|-------------|---------------------|
-| `InvokeSkill` | Invoke specialized skills | YOLO, ACCEPT_EDITS, PLAN, SMART |
-
-### Additional Tools
-| Tool | Description | Permissions Required |
-|------|-------------|---------------------|
-| `image_read` | Analyze image content | All modes |
-| `save_memory` | Remember user preferences | All modes |
-| `ask_user_question` | Ask user for clarification | All modes |
-| `xml_escape` | Escape XML/HTML content | All modes |
-| `exit_plan_mode` | Exit plan mode | PLAN |
-
-
-## Tool Interface
-
-```typescript
-interface Tool {
-  name: string;
-  description: string;
-  parameters: ToolParameters;
-  execute: (args: Record<string, unknown>) => Promise<ToolResult>;
-  validate?: (args: Record<string, unknown>) => boolean;
-  allowedModes?: ExecutionMode[];
-}
-```
-
-## Tool Registry
-
-The ToolRegistry manages tool registration and retrieval:
-
-```typescript
-class ToolRegistry {
-  register(tool: Tool): void;
-  get(name: string): Tool | undefined;
-  list(): Tool[];
-  getAll(): Tool[];
-  getToolsForMode(mode: ExecutionMode): Tool[];
-  registerMCPTools(mcpTools: any[]): void;
-}
-```
-
-## Tool Execution Flow
-
-```
-Tool Call → Permission Check (by mode)
-                    ↓
-              Whitelist Check (Smart Mode)
-                    ↓
-              Blacklist Check (Smart Mode)
-                    ↓
-              AI Review (Smart Mode)
-                    ↓
-              Execution → Result Formatting
-                    ↓
-              Response Generation
-```
-
-## Smart Mode Integration
-
-In Smart Mode, tools go through a three-layer approval system:
-
-1. **Whitelist Check**: Safe tools (Read, ListDirectory, Grep, etc.) are approved automatically
-2. **Blacklist Check**: Dangerous operations are flagged for user confirmation
-3. **AI Review**: Unknown tools are analyzed by AI for risk assessment
-
-## Adding Custom Tools
-
-1. Implement the Tool interface in tools.ts
-2. Register with ToolRegistry in getToolRegistry()
-3. Add TypeScript types if needed
-4. Write unit tests
-5. Update system-prompt-generator.ts with tool schema
-
-## Remote Mode Support
-
-Tools can operate in two modes:
-
-- **Local Mode**: Tools are executed locally with local AI client
-- **Remote Mode**: Tools are synced to remote server, approval handled by remote LLM
-
-## Related Documentation
-
-- [Architecture Overview](./overview.md)
-- [MCP Integration Guide](./mcp-integration-guide.md)
-- [Smart Mode Documentation](../smart-mode.md)
+# Tool System Design
+
+This document describes the tool system architecture and design principles.
+
+## Overview
+
+xAgent CLI provides a rich set of built-in tools plus support for external tools via MCP (Model Context Protocol). Tools are the primary way agents interact with the filesystem, execute commands, and perform actions.
+
+## Tool Categories
+
+### File Operations
+| Tool | Description | Permissions Required |
+|------|-------------|---------------------|
+| `Read` | Read file contents | YOLO, ACCEPT_EDITS, PLAN, SMART |
+| `Write` | Create or overwrite files | YOLO, ACCEPT_EDITS, SMART |
+| `replace` | Replace text in files | YOLO, ACCEPT_EDITS, SMART |
+| `DeleteFile` | Delete files | YOLO, ACCEPT_EDITS, SMART |
+
+### Search Tools
+| Tool | Description | Permissions Required |
+|------|-------------|---------------------|
+| `Grep` | Search text patterns | All modes |
+| `SearchCodebase` | Find files by pattern | All modes |
+| `web_search` | Search the web | YOLO, ACCEPT_EDITS, PLAN, SMART |
+| `web_fetch` | Fetch web content | YOLO, ACCEPT_EDITS, PLAN, SMART |
+
+### Execution Tools
+| Tool | Description | Permissions Required |
+|------|-------------|---------------------|
+| `Bash` | Execute shell commands | YOLO, ACCEPT_EDITS, SMART |
+| `ListDirectory` | List directory contents | All modes |
+| `CreateDirectory` | Create directories | YOLO, ACCEPT_EDITS, SMART |
+
+### Task Management
+| Tool | Description | Permissions Required |
+|------|-------------|---------------------|
+| `todo_write` | Create/manage task lists | All modes |
+| `todo_read` | Read task lists | All modes |
+| `task` | Launch SubAgents | YOLO, ACCEPT_EDITS, PLAN, SMART |
+
+### GUI Automation
+| Tool | Description | Permissions Required |
+|------|-------------|---------------------|
+| `gui_operate` | GUI browser automation | YOLO, ACCEPT_EDITS, SMART |
+| `gui_screenshot` | Take browser screenshot | YOLO, ACCEPT_EDITS, SMART |
+| `gui_cleanup` | Cleanup GUI instances | YOLO, ACCEPT_EDITS, SMART |
+
+### Skill Invocation
+| Tool | Description | Permissions Required |
+|------|-------------|---------------------|
+| `InvokeSkill` | Invoke specialized skills | YOLO, ACCEPT_EDITS, PLAN, SMART |
+
+### Additional Tools
+| Tool | Description | Permissions Required |
+|------|-------------|---------------------|
+| `image_read` | Analyze image content | All modes |
+| `save_memory` | Remember user preferences | All modes |
+| `ask_user_question` | Ask user for clarification | All modes |
+| `xml_escape` | Escape XML/HTML content | All modes |
+| `exit_plan_mode` | Exit plan mode | PLAN |
+
+
+## Tool Interface
+
+```typescript
+interface Tool {
+  name: string;
+  description: string;
+  parameters: ToolParameters;
+  execute: (args: Record<string, unknown>) => Promise<ToolResult>;
+  validate?: (args: Record<string, unknown>) => boolean;
+  allowedModes?: ExecutionMode[];
+}
+```
+
+## Tool Registry
+
+The ToolRegistry manages tool registration and retrieval:
+
+```typescript
+class ToolRegistry {
+  register(tool: Tool): void;
+  get(name: string): Tool | undefined;
+  list(): Tool[];
+  getAll(): Tool[];
+  getToolsForMode(mode: ExecutionMode): Tool[];
+  registerMCPTools(mcpTools: any[]): void;
+}
+```
+
+## Tool Execution Flow
+
+```
+Tool Call → Permission Check (by mode)
+                    ↓
+              Whitelist Check (Smart Mode)
+                    ↓
+              Blacklist Check (Smart Mode)
+                    ↓
+              AI Review (Smart Mode)
+                    ↓
+              Execution → Result Formatting
+                    ↓
+              Response Generation
+```
+
+## Smart Mode Integration
+
+In Smart Mode, tools go through a three-layer approval system:
+
+1. **Whitelist Check**: Safe tools (Read, ListDirectory, Grep, etc.) are approved automatically
+2. **Blacklist Check**: Dangerous operations are flagged for user confirmation
+3. **AI Review**: Unknown tools are analyzed by AI for risk assessment
+
+## Adding Custom Tools
+
+1. Implement the Tool interface in tools.ts
+2. Register with ToolRegistry in getToolRegistry()
+3. Add TypeScript types if needed
+4. Write unit tests
+5. Update system-prompt-generator.ts with tool schema
+
+## Remote Mode Support
+
+Tools can operate in two modes:
+
+- **Local Mode**: Tools are executed locally with local AI client
+- **Remote Mode**: Tools are synced to remote server, approval handled by remote LLM
+
+## Related Documentation
+
+- [Architecture Overview](./overview.md)
+- [MCP Integration Guide](./mcp-integration-guide.md)
+- [Smart Mode Documentation](../smart-mode.md)