pelulu-cli 1.0.5 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to **Pelulu CLI** will be documented in this file.
+
+## [1.1.0] - 2026-07-21
+
+### Fixed
+- **MQTT disconnect loop** — `tools/list` response exceeded 8KB broker limit, now optimized to ~4KB
+- **Agent sends prompt before session ready** — `LLMClient` now waits for MCP handshake + session before sending
+- **Double tool execution** — agent loop no longer re-executes tools already handled by MQTT client
+- **Prompt sent multiple times** — agent loop now sends prompt only once per run
+- **AI responses not in log file** — added `llm:text` and `tts:sentence` event logging
+- **Log files accumulate** — old logs deleted on startup, only latest kept
+- **y/N confirmation prompt flashing** — agent tool calls auto-approved (no more UI glitches)
+- **Version mismatch** — version now read from `package.json` (auto-sync)
+
+### Changed
+- **Statusbar redesigned** — clean minimal layout: `🐱 PELULU ● online  session:xxx  xiaozhi.me`
+- **Tool schema optimization** — `action` enum preserved, first 4 properties sent (under 8KB)
+- **System prompt added to hello message** — tells XiaoZhi to use tools instead of just chatting
+
+## [1.0.5] - 2026-07-20
+
+### Added
+- File logging (`logs/` directory)
+- Char counter on TUI input (70 char limit)
+- Scrollable chat (Shift+Up/Down, PgUp/PgDn)
+
+### Fixed
+- Chat limited to 12 visible lines
+- Progress feedback and timeout handling in agent loop
+
+## [1.0.4] - 2026-07-19
+
+### Changed
+- Update checker uses npm registry instead of GitHub releases
+
+### Fixed
+- Activation code displays directly to console
+
+## [1.0.3] - 2026-07-19
+
+### Fixed
+- Duplicate user messages (Enter key fired onSubmit twice)
+- TTS responses handled as assistant messages
+
+## [1.0.2] - 2026-07-18
+
+### Added
+- Cute ASCII cat banner above CLI header
+- Block CLI when update is available
+
+### Fixed
+- Redirect ALL startup logs into Ink TUI
+- Clean status bar header format
+
+## [1.0.1] - 2026-07-17
+
+### Added
+- OpenHands-style agent system (AgentLoop, AgentController, LLMClient)
+- Auto-completion with Tab key
+- Auto-format for written files
+
+### Changed
+- Replaced readline with Ink React TUI
+
+### Fixed
+- Compact banner text
+- TTY fallback for non-interactive mode
+- Log status as single-line auto-updating text
+
+## [1.0.0] - 2026-07-16
+
+### Added
+- Initial release
+- XiaoZhi AI integration via MQTT
+- MCP tool protocol support
+- 18 built-in tools (file, shell, git, project, network, etc.)
+- Interactive REPL with syntax highlighting
+- Plugin system
+- Workspace detection and context building

package/docs/AGENT.md

@@ -0,0 +1,237 @@
+# Pelulu-CLI Agent System
+
+Pelulu-CLI now includes an OpenHands-style agent system that provides autonomous coding capabilities.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Agent Controller                          │
+│  Orchestrates all agent components                          │
+└──────────────────────────┬──────────────────────────────────┘
+                           │
+         ┌─────────────────┼─────────────────┐
+         │                 │                 │
+         ▼                 ▼                 ▼
+┌─────────────┐   ┌──────────────┐   ┌──────────────┐
+│  Agent Loop │   │ Plan Manager │   │ LLM Client   │
+│  (observe→  │   │ (task        │   │ (XiaoZhi AI  │
+│   think→act)│   │  decomposition│   │  via MQTT)   │
+└──────┬──────┘   └──────────────┘   └──────────────┘
+       │
+       ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     Tool System                              │
+│  file, shell, git, search, agent, ai, ...                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Components
+
+### 1. Agent Loop (`agent-loop.js`)
+The core observe→think→act cycle:
+- **Observe**: Builds context from history, workspace, and plan
+- **Think**: Sends context to LLM for reasoning
+- **Act**: Executes tool calls returned by LLM
+- **Loop**: Repeats until "finish" is called or max iterations reached
+
+### 2. Plan Manager (`plan-manager.js`)
+Task decomposition and tracking:
+- Auto-generates plans for complex tasks
+- Tracks step progress (pending → in_progress → completed/failed)
+- Supports dynamic plan modification during execution
+- Provides visual progress indicators
+
+### 3. LLM Client (`llm-client.js`)
+Wraps XiaoZhi AI into a standard interface:
+- MQTT-based communication
+- Tool call parsing from text responses
+- Token usage tracking
+- Request timeout and abort support
+
+### 4. Context Builder (`context-builder.js`)
+Builds rich workspace context:
+- Git status and history
+- Project type detection
+- File structure analysis
+- Runtime environment info
+- Cached for performance
+
+### 5. History Condenser (`history-condenser.js`)
+Manages long conversations:
+- Automatic condensation when history is too long
+- Preserves important context (files modified, errors)
+- Optional LLM-based summarization
+- Token-aware windowing
+
+### 6. System Prompt (`system-prompt.js`)
+Builds comprehensive prompts:
+- Agent identity and capabilities
+- Tool descriptions with schemas
+- Workspace context
+- Microagents/skills (trigger-based)
+- Plan status
+- Guidelines and constraints
+
+## Usage
+
+### Basic Usage
+The agent system is automatically initialized when you start Pelulu-CLI:
+
+```bash
+pelulu
+```
+
+Then simply describe your task:
+```
+> Fix the bug in auth.js where login fails with special characters
+```
+
+### Disable Agent Mode
+If you want to use the legacy direct tool call mode:
+
+```bash
+pelulu --no-agent
+```
+
+### Debug Mode
+Enable debug logging:
+
+```bash
+pelulu --debug
+```
+
+## Agent Tool
+
+The agent system is exposed as a tool that can be called directly:
+
+```json
+{
+  "tool": "agent",
+  "action": "run",
+  "task": "Implement user authentication with JWT"
+}
+```
+
+### Actions
+
+| Action | Description |
+|--------|-------------|
+| `run` | Execute a task with the agent loop |
+| `plan` | Create, view, or manage plans |
+| `status` | Get agent status and summary |
+| `abort` | Abort the current run |
+| `reset` | Reset agent state |
+| `history` | Get conversation history |
+| `context` | Get workspace context |
+
+## Plan Management
+
+### Auto-Planning
+Complex tasks automatically get plans:
+```
+> Implement a REST API with user authentication, CRUD operations, and tests
+
+📋 Plan: Implement REST API
+────────────────────────────
+🔄 1. Set up Express project structure
+⬜ 2. Create User model with Mongoose
+⬜ 3. Implement authentication middleware
+⬜ 4. Create CRUD routes for users
+⬜ 5. Add input validation
+⬜ 6. Write unit tests
+⬜ 7. Test the API
+────────────────────────────
+Progress: 14%
+```
+
+### Manual Planning
+Create plans explicitly:
+```json
+{
+  "tool": "agent",
+  "action": "plan",
+  "goal": "Refactor auth module",
+  "steps": [
+    { "description": "Extract auth logic to separate file" },
+    { "description": "Add JWT support" },
+    { "description": "Update tests" }
+  ]
+}
+```
+
+## Skills/Microagents
+
+Pelulu-CLI loads skills from:
+- `.pelulu/skills/*.md`
+- `.openhands/microagents/*.md`
+- `.agents/skills/*.md`
+
+### Skill File Format
+```markdown
+---
+triggers:
+- authentication
+- jwt
+- login
+---
+# Authentication Best Practices
+
+When implementing authentication:
+1. Always hash passwords with bcrypt
+2. Use JWT with short expiration
+3. Implement refresh tokens
+4. Add rate limiting to login endpoints
+```
+
+Skills with triggers are only loaded when the user's message matches the trigger keywords.
+
+## Configuration
+
+Add to your `pelulu.config.json`:
+
+```json
+{
+  "agent": {
+    "name": "Pelulu",
+    "max_iterations": 100,
+    "max_history": 50,
+    "auto_plan": true,
+    "max_tokens": 100000
+  }
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `max_iterations` | 100 | Maximum agent loop iterations |
+| `max_history` | 50 | Maximum messages before condensation |
+| `auto_plan` | true | Auto-generate plans for complex tasks |
+| `max_tokens` | 100000 | Token limit for history |
+
+## Differences from OpenHands
+
+| Feature | OpenHands | Pelulu-CLI |
+|---------|-----------|------------|
+| LLM | OpenAI/Anthropic/etc | XiaoZhi AI (MQTT) |
+| Runtime | Docker sandbox | Local execution |
+| UI | Web React | Terminal Ink |
+| Planning | Optional | Auto for complex tasks |
+| Skills | Global + repo | Local files |
+| Multi-agent | Yes | Single agent |
+
+## Troubleshooting
+
+### Agent not responding
+1. Check MQTT connection: `pelulu --debug`
+2. Verify XiaoZhi is activated
+3. Check network connectivity
+
+### Plan not generating
+- Ensure `auto_plan: true` in config
+- Task must be complex enough (50+ chars, contain action words)
+
+### History too long
+- The agent auto-condenses history
+- Use `agent.history` with `condensed: true`
+- Adjust `max_history` in config

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "pelulu-cli",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "description": "CLI coding agent powered by XiaoZhi AI — a tiny Chinese LLM that lives in ESP32 chips",
   "type": "module",
   "main": "src/index.js",
   "bin": {
-    "pelulu": "src/index.js"
+    "pelulu-cli": "src/index.js"
   },
   "scripts": {
     "start": "node src/index.js",
     "start:debug": "node src/index.js --debug",
     "start:fallback": "node src/index.js --no-ink",
+    "start:no-agent": "node src/index.js --no-agent",
     "tools": "node src/index.js --list-tools",
     "test": "node src/index.js --test"
   },

package/specifications/xiaozhi-mqtt-broker.md

@@ -0,0 +1,46 @@
+# XiaoZhi MQTT Broker Specifications
+
+## MCP Tools/List Response Size Limit
+
+- **Limit:** ~8KB (8,192 bytes estimated)
+- **Behavior:** Broker disconnects client immediately after receiving `tools/list` response that exceeds the limit
+- **Tested:** 
+  - 15,423 bytes → ❌ Disconnected
+  - 10,344 bytes → ❌ Disconnected  
+  - 9,104 bytes → ❌ Disconnected
+  - 8,894 bytes → ❌ Disconnected
+  - 8,079 bytes → ✅ Connected
+  - 7,656 bytes → ✅ Connected
+  - 7,928 bytes → ✅ Connected (Pelulu-CLI baseline)
+
+## Content Filtering
+
+- **No content filtering detected.** Tool names like `bruteforce`, `exploit`, `sqli`, `injection`, `fuzzer`, `evasion`, `vuln` are accepted as long as response is under 8KB.
+
+## Optimization Techniques (to stay under 8KB)
+
+1. Remove `description` from inputSchema properties
+2. Remove `action` enum values (keep as plain `{ type: "string" }`)
+3. Trim tool descriptions to essential keywords only
+
+## MQTT Connection
+
+- **Endpoint:** `mqtt.xiaozhi.me:8883` (MQTTS)
+- **Keepalive:** 60s recommended (240s may cause issues)
+- **Protocol:** MQTT v3.1.1 (v5 rejected)
+- **Subscribe topic:** `devices/p2p/#`
+- **Publish topic:** `device-server` (from OTA response)
+- **subscribe_topic from OTA:** Always `"null"` (string, not null)
+
+## Device Activation
+
+- **OTA URL:** `https://api.tenclass.net/xiaozhi/ota/`
+- **Activation URL:** `https://xiaozhi.me`
+- **Device name:** Set in `board.name` field of OTA request
+- **Credentials:** Fresh credentials from OTA for each connection (do not cache/reuse)
+
+## Tool Execution Notes
+
+- **Port scanning:** Use `nc -z -w1` (netcat) instead of `bash /dev/tcp` for reliable scanning
+- **Timeout:** 15 default ports × 1s timeout = ~15-20s total (within 30s tool timeout)
+- **Shell escaping:** Use semicolons (`;`) not newlines when passing multi-command scripts to `bash -c` via `JSON.stringify`

package/src/agent/agent-controller.js

@@ -0,0 +1,100 @@
+/**
+ * AgentController — Orchestrates the agent system
+ */
+import { AgentLoop } from './agent-loop.js';
+import { LLMClient } from './llm-client.js';
+import { ContextBuilder } from './context-builder.js';
+import { bus } from '../core/event-bus.js';
+import { debug } from '../core/logger.js';
+
+export class AgentController {
+  #loop;
+  #llm;
+  #contextBuilder;
+  #registry;
+  #sandbox;
+  #confirm;
+  #config;
+  #running = false;
+
+  constructor({ registry, mqtt, sandbox, confirm, config }) {
+    this.#registry = registry;
+    this.#sandbox = sandbox;
+    this.#confirm = confirm;
+    this.#config = config;
+    this.#loop = new AgentLoop({ maxIterations: config.agent?.max_iterations || 50 });
+    this.#llm = new LLMClient(mqtt);
+    this.#contextBuilder = new ContextBuilder();
+  }
+
+  get isRunning() { return this.#running; }
+
+  get summary() {
+    return {
+      state: this.#loop.state,
+      iteration: this.#loop.iteration,
+      history: this.#loop.history.length,
+      running: this.#running,
+    };
+  }
+
+  /**
+   * Run agent for a user prompt
+   */
+  async run(userPrompt, options = {}) {
+    // Validate input length
+    const MAX_LEN = 70;
+    if (userPrompt.length > MAX_LEN) {
+      throw new Error(`Input too long (${userPrompt.length}/${MAX_LEN} chars)`);
+    }
+
+    if (this.#running) {
+      this.abort();
+      await new Promise(r => setTimeout(r, 300));
+    }
+
+    this.#running = true;
+    const start = Date.now();
+
+    try {
+      debug('agent', `Running: ${userPrompt}`);
+      
+      const result = await this.#loop.run(userPrompt, {
+        llm: this.#llm,
+        tools: this.#registry,
+        sandbox: this.#sandbox,
+        confirm: this.#confirm,
+      });
+
+      result.duration = Date.now() - start;
+      debug('agent', `Done in ${result.duration}ms: ${result.success}`);
+      return result;
+
+    } finally {
+      this.#running = false;
+    }
+  }
+
+  /**
+   * Abort current run
+   */
+  abort() {
+    this.#loop.abort();
+    this.#running = false;
+    debug('agent', 'Aborted');
+  }
+
+  /**
+   * Get workspace context
+   */
+  async getContext() {
+    return this.#contextBuilder.build();
+  }
+
+  /**
+   * Reset agent state
+   */
+  reset() {
+    this.#running = false;
+  }
+}