pelulu-cli 1.0.5 → 1.2.0

package/src/index.js

@@ -2,18 +2,26 @@
 /**
  * Pelulu CLI — Entry Point
  * Ink-based TUI with React components
+ * 
+ * Now with OpenHands-style agent capabilities:
+ * - Agent Loop (observe→think→act)
+ * - Plan Management
+ * - Enhanced Context
+ * - History Condensation
  */
 import { dirname, join } from 'path';
+import { readFile } from 'fs/promises';
 import { fileURLToPath } from 'url';
 import chalk from 'chalk';
-import { loadConfig, saveConfig } from './core/config.js';
-import { log, setDebug } from './core/logger.js';
+import { existsSync } from 'fs';
+import { loadConfig, saveConfig, expand } from './core/config.js';
+import { log, setDebug, debug, setInkMode, initFileLog, flushLogs, getLogFile, writeRawToLog } from './core/logger.js';
 import { bus } from './core/event-bus.js';
 import { ToolRegistry } from './core/tool-registry.js';
+import { jobManager } from './core/job-manager.js';
 import { Sandbox } from './core/sandbox.js';
 import { SessionState } from './core/session.js';
 import { Stats } from './core/stats.js';
-import { buildSystemPrompt } from './core/system-prompt.js';
 import { buildContext } from './core/context.js';
 import { isDestructive, askConfirmation } from './core/confirm.js';
 import { runWizard } from './core/wizard.js';
@@ -28,15 +36,19 @@ import { MessageSender } from './mcp/message-sender.js';
 import { WssEndpoint } from './mcp/wss-endpoint.js';
 import { PluginManager } from './plugins/manager.js';
 import { checkForUpdates } from './core/update-checker.js';
-import { renderUpdateNotification, renderAsciiBanner } from './tui/renderer.js';
+import { renderUpdateNotification, renderPostUpdate, renderAsciiBanner } from './tui/renderer.js';
 import { startInkTUI } from './tui/ink-entry.js';
 
+// Import new agent system
+import { AgentController } from './agent/agent-controller.js';
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, '..');
 
 const args = process.argv.slice(2);
 if (args.includes('--debug')) setDebug(true);
 const LIST_TOOLS = args.includes('--list-tools');
+const NO_AGENT = args.includes('--no-agent');
 
 async function main() {
   // Buffer ALL startup logs for Ink to display inside TUI
@@ -47,11 +59,32 @@ async function main() {
   // 1. Load config
   const config = await loadConfig(ROOT);
 
-  // 2. Check for updates — block if outdated
+  // 1b. Initialize file logging (deletes old logs, keeps only latest)
+  const appName = config.agent?.name?.toLowerCase().replace(/\s+/g, '-') || 'pelulu';
+  const logFile = await initFileLog(ROOT, appName);
+  debug('init', `Log file: ${logFile}`);
+
+  // 1c. Enable Ink mode early — route ALL logs through bus (no console.log leak)
+  if (process.stdin.isTTY) {
+    setInkMode(true, bus);
+  }
+
+  // 2. Auto-update — silently install latest if outdated
   const update = await checkForUpdates(ROOT);
   if (update.available) {
-    renderUpdateNotification(update);
-    process.exit(1);
+    const pkgName = await (async () => {
+      try { return JSON.parse(await readFile(join(ROOT, 'package.json'), 'utf-8')).name; } catch { return 'pelulu-cli'; }
+    })();
+    try {
+      const { execSync } = await import('child_process');
+      execSync(`npm install -g ${pkgName}@latest`, { stdio: 'ignore' });
+      renderPostUpdate(pkgName, update.remote);
+      process.exit(0);
+    } catch (e) {
+      console.error(chalk.red(`  ✗ Update failed: ${e.message}`));
+      console.log(chalk.gray(`  Run manually: npm install -g ${pkgName}@latest`));
+      process.exit(1);
+    }
   }
 
   // 3. Workspace & wizard
@@ -61,8 +94,11 @@ async function main() {
     await runWizard(ROOT);
   }
 
-  // Show ASCII banner before Ink takes over
-  renderAsciiBanner(config.agent?.version);
+  // Banner is now a React component inside Ink TUI (AsciiBanner)
+  // Only render console banner for fallback REPL (non-TTY)
+  if (!process.stdin.isTTY) {
+    await renderAsciiBanner();
+  }
 
   // Redirect console.log to buffer — everything after this goes into Ink
   console.log = bufferLog;
@@ -95,7 +131,6 @@ async function main() {
 
   // 6. Build context & system prompt
   const context = await buildContext();
-  const systemPrompt = buildSystemPrompt(registry, config);
 
   // 7. Connect to XiaoZhi
   const mqtt = new MqttClient(config);
@@ -125,30 +160,103 @@ async function main() {
   // 8. Message sender
   const sender = new MessageSender(mqtt);
 
-  // 9. Register MCP tool handler
+  // 9. Initialize Agent Controller (OpenHands-style)
+  let agentController = null;
+  if (!NO_AGENT) {
+    agentController = new AgentController({
+      registry,
+      mqtt,
+      sandbox,
+      confirm: { isDestructive, ask: askConfirmation },
+      config,
+    });
+
+    startupLogs.push(chalk.green('  ✓ Agent system initialized'));
+    startupLogs.push(chalk.gray(`    - Max iterations: ${config.agent?.max_iterations || 50}`));
+    startupLogs.push(chalk.gray(`    - Max input: 70 chars`));
+    startupLogs.push(chalk.gray(`    - Log: ${getLogFile()}`));
+  }
+
+  // 10. Register MCP tool handler (for XiaoZhi direct tool calls)
+  // Agent calls are auto-approved — XiaoZhi controls the flow, no y/N prompts
+  // File tool actions that mutate the filesystem — tracked + surfaced in chat
+  const FILE_MUTATIONS = ['write', 'edit', 'delete', 'mkdir', 'copy', 'move'];
+
   mqtt.registerToolHandler(
     async (name, args) => {
-      const destructive = isDestructive(name, args);
-      if (destructive.destructive) {
-        const ok = await askConfirmation(name, args, destructive);
-        if (!ok) return { isError: true, content: [{ type: 'text', text: 'Cancelled by user' }] };
-      }
       sandbox.validate(name, args);
 
       thinking.set('tool_call');
       const start = Date.now();
-      try {
-        const result = await registry.call(name, args);
+
+      // Capture pre-state so we can report created vs modified accurately
+      const trackedPath = args?.to || args?.path;
+      let preExisted = false;
+      if (name === 'file' && FILE_MUTATIONS.includes(args?.action) && trackedPath) {
+        try { preExisted = existsSync(expand(trackedPath)); } catch {}
+      }
+
+      // Post-processing shared by the inline and background completion paths:
+      // record stats, track file mutations, and surface the result in the TUI.
+      const finalize = (result) => {
         stats.record(name, args.action, !result.isError, Date.now() - start);
         session.addToolCall(name, args, result);
 
-        if (name === 'file' && (args.action === 'write' || args.action === 'edit') && args.path) {
-          autoFormat(args.path).catch(() => {});
+        // Track file changes and broadcast them so the TUI can show tracking in chat
+        if (name === 'file' && !result.isError && FILE_MUTATIONS.includes(args.action) && trackedPath) {
+          const change =
+            args.action === 'delete' ? 'deleted'
+            : (args.action === 'edit' || preExisted) ? 'modified'
+            : 'created';
+          fileTracker.track(trackedPath, change);
+          bus.emit('files:changed', { path: trackedPath, change, changes: fileTracker.getChanges() });
+
+          if (args.action === 'write' || args.action === 'edit') {
+            autoFormat(trackedPath).catch(() => {});
+          }
         }
 
-        thinking.set('idle');
         bus.emit('tool:called', { name, result, args });
-        return result;
+      };
+
+      try {
+        // Route EVERY tool action through the job layer. Fast actions resolve
+        // inline (unchanged UX); slow ones background themselves and return a
+        // pollable job handle so XiaoZhi never assumes a timeout while the tool
+        // is still working. The AI polls progress/results with the `jobs` tool.
+        const dispatched = await jobManager.dispatch(
+          { tool: name, action: args.action, label: `${name}${args.action ? `.${args.action}` : ''}` },
+          () => registry.call(name, args),
+        );
+
+        if (dispatched.done) {
+          if (dispatched.error) throw dispatched.error;
+          finalize(dispatched.result);
+          thinking.set('idle');
+          return dispatched.result;
+        }
+
+        // Backgrounded: tell XiaoZhi it's running and how to follow up. Finalize
+        // the real result once the background work completes.
+        const job = dispatched.job;
+        jobManager.wait(job.id, 3_600_000).then(() => {
+          if (job.status === 'done' && job.result) {
+            const wrapped = { isError: false, content: [{ type: 'text', text: typeof job.result === 'string' ? job.result : JSON.stringify(job.result) }] };
+            finalize(wrapped);
+          }
+        }).catch(() => {});
+
+        thinking.set('idle');
+        return {
+          isError: false,
+          content: [{ type: 'text', text: JSON.stringify({
+            status: 'running',
+            job_id: job.id,
+            tool: name,
+            action: args.action,
+            message: `"${name}${args.action ? `.${args.action}` : ''}" is running in the background (job ${job.id}). It is NOT an error or timeout. Poll it with the jobs tool: {"action":"wait","id":"${job.id}"} to wait, or {"action":"status","id":"${job.id}"} to check progress.`,
+          }) }],
+        };
       } catch (e) {
         stats.record(name, args.action, false, Date.now() - start, e.message);
         thinking.set('idle');
@@ -158,7 +266,7 @@ async function main() {
     () => registry.toMcpTools()
   );
 
-  // 10. Optional WSS endpoint
+  // 11. Optional WSS endpoint
   let wss = null;
   if (config.mcp?.endpoint_url) {
     wss = new WssEndpoint(config.mcp.endpoint_url, () => registry.toMcpTools(), async (name, args) => {
@@ -168,25 +276,39 @@ async function main() {
     wss.start();
   }
 
-  // 11. Track conversation
-  bus.on('user:text', (text) => session.addUserMessage(text));
-  bus.on('llm:text', (text) => session.addAiMessage(text));
+  // 12. Track conversation + log AI responses
+  bus.on('user:text', (text) => {
+    session.addUserMessage(text);
+    writeRawToLog(`[USER] ${text}`);
+  });
+  bus.on('llm:text', (text) => {
+    session.addAiMessage(text);
+    writeRawToLog(`[AI] ${text}`);
+  });
+  bus.on('tts:sentence', (text) => {
+    writeRawToLog(`[AI-TTS] ${text}`);
+  });
 
-  // 12. Save config
+  // 13. Save config
   await saveConfig(ROOT, config);
 
-  // 13. Start Ink TUI
+  // 14. Start Ink TUI
   const { unmount, waitUntilExit } = startInkTUI({
     registry, mqtt, stats, session, bus, config,
-    extras: { fileTracker, thinking, sender, autoFormat, startupLogs },
+    extras: {
+      fileTracker, thinking, sender, autoFormat, startupLogs,
+      agentController, // Pass agent controller to TUI
+    },
   });
 
   // Graceful shutdown
   const shutdown = async () => {
     unmount();
+    if (agentController) agentController.abort();
     if (wss) wss.stop();
     await registry.shutdown();
     mqtt.disconnect();
+    await flushLogs();
     process.exit(0);
   };
   process.on('SIGINT', shutdown);

package/src/mcp/mcp-handler.js

@@ -43,7 +43,7 @@ export class McpHandler {
           result: {
             protocolVersion: PROTOCOL_VERSION,
             capabilities: { tools: {} },
-            serverInfo: { name: 'coding-agent', version: '1.0.0' },
+            serverInfo: { name: 'pelulu-cli', version: '1.0.0' },
           },
         },
       });
@@ -58,13 +58,18 @@ export class McpHandler {
     if (p.method === 'tools/list') {
       this.#toolsReceived = true;
       this.#nameMap.clear();
-      const tools = (this.#toolsFn?.() || []).map(t => {
+      let tools = (this.#toolsFn?.() || []).map(t => {
         const safeName = this._sanitize(t.name);
         this.#nameMap.set(safeName, t.name);
-        return { name: safeName, description: t.description, inputSchema: t.inputSchema || { type: 'object', properties: {} } };
+        return this._optimizeTool({ name: safeName, description: t.description, inputSchema: t.inputSchema || { type: 'object', properties: {} } });
       });
+      // Hard guard: the XiaoZhi broker disconnects the client if the
+      // tools/list payload exceeds ~8KB. Progressively shrink until it fits so
+      // a newly added tool can never silently break the whole connection.
+      tools = this._fitUnderLimit(tools, p.id);
+      const bytes = Buffer.byteLength(JSON.stringify({ jsonrpc: '2.0', id: p.id, result: { tools } }));
       responses.push({ type: 'mcp', payload: { jsonrpc: '2.0', id: p.id, result: { tools } } });
-      log('mcp', `Sent ${tools.length} tools`);
+      log('mcp', `Sent ${tools.length} tools (${bytes} bytes)`);
     }
 
     if (p.method === 'tools/call') {
@@ -89,4 +94,58 @@ export class McpHandler {
   _sanitize(name) {
     return String(name).replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64);
   }
+
+  /**
+   * Keep the serialized tools/list under the broker's ~8KB limit.
+   * Step 1: trim descriptions. Step 2: drop schema properties down to just
+   * `action`. We stop as soon as we're safely under the limit.
+   */
+  _fitUnderLimit(tools, id, limit = 7800) {
+    const size = (t) => Buffer.byteLength(JSON.stringify({ jsonrpc: '2.0', id, result: { tools: t } }));
+    if (size(tools) <= limit) return tools;
+
+    // Step 1: shorten descriptions to ~40 chars.
+    let trimmed = tools.map(t => ({ ...t, description: (t.description || '').slice(0, 40) }));
+    if (size(trimmed) <= limit) { log('warn', 'tools/list trimmed descriptions to fit 8KB'); return trimmed; }
+
+    // Step 2: reduce each schema to only the `action` property.
+    trimmed = trimmed.map(t => {
+      const props = t.inputSchema?.properties || {};
+      const minimal = props.action ? { action: props.action } : {};
+      return { ...t, description: (t.description || '').slice(0, 24), inputSchema: { type: 'object', properties: minimal } };
+    });
+    if (size(trimmed) <= limit) { log('warn', 'tools/list reduced schemas to fit 8KB'); return trimmed; }
+
+    // Step 3 (last resort): drop tools from the end until it fits.
+    while (trimmed.length > 1 && size(trimmed) > limit) trimmed.pop();
+    log('warn', `tools/list truncated to ${trimmed.length} tools to fit 8KB`);
+    return trimmed;
+  }
+
+  /**
+   * Optimize tool definition to stay under 8KB MQTT broker limit
+   * - Keep descriptions (truncated to 200 chars)
+   * - Keep enum values (critical for XiaoZhi to know valid actions)
+   * - Keep required fields (critical for XiaoZhi to know what's mandatory)
+   */
+  _optimizeTool(tool) {
+    const optimized = {
+      name: tool.name,
+      description: tool.description?.slice(0, 100) || '',
+      inputSchema: { type: 'object', properties: {} }
+    };
+
+    // Keep first 4 properties only (to stay under 8KB MQTT limit)
+    // action + first 3 params — enough for XiaoZhi to understand the tool
+    if (tool.inputSchema?.properties) {
+      const entries = Object.entries(tool.inputSchema.properties);
+      for (const [key, val] of entries.slice(0, 4)) {
+        const prop = { type: val.type };
+        if (val.enum) prop.enum = val.enum;
+        optimized.inputSchema.properties[key] = prop;
+      }
+    }
+
+    return optimized;
+  }
 }

package/src/mcp/mqtt-client.js

@@ -9,6 +9,13 @@ import { bus } from '../core/event-bus.js';
 import { McpHandler } from './mcp-handler.js';
 import { fetchOtaConfig, handleActivation } from './activation.js';
 
+// Max serialized bytes for a single MQTT publish. The XiaoZhi broker drops the
+// connection the instant a message crosses ~8KB (see specifications/
+// xiaozhi-mqtt-broker.md). tools/list is already guarded; tool RESULTS must be
+// clamped here too, otherwise a single large file.read / recursive list / shell
+// dump silently kills the whole connection.
+const MAX_MQTT_BYTES = 7800;
+
 export class MqttClient {
   constructor(config) {
     this.config = config;
@@ -20,13 +27,38 @@ export class MqttClient {
     this.mqttCfg = null;
     this.mcp = new McpHandler();
     this._helloQueue = [];
+    // Reconnection state — we manage reconnect ourselves because the broker
+    // hands out FRESH credentials from OTA on every connection (cached creds
+    // are rejected), so mqtt.js's built-in reconnect can never recover.
+    this._manualClose = false;
+    this._reconnectTimer = null;
+    this._reconnectAttempts = 0;
+    // Whether an agent turn is actively in progress. XiaoZhi closes idle audio
+    // sessions with a `goodbye`; if that lands while we're still working we must
+    // keep the session warm (re-`hello`) instead of letting the task stall until
+    // the next user message. Driven by the agent-loop's progress events.
+    this._turnActive = false;
+    this._resuming = false;
+    bus.on('agent:progress', ({ state } = {}) => {
+      if (state === 'done' || state === 'timeout') this._turnActive = false;
+      else if (state) this._turnActive = true; // thinking/tool/tool_done/receiving
+    });
   }
 
   async connect() {
     if (!this.deviceId) this.deviceId = this._randomMac();
     if (!this.clientId) this.clientId = crypto.randomUUID();
     await this._persistIds();
+    this._manualClose = false;
+    return this._refreshAndConnect();
+  }
 
+  /**
+   * Fetch fresh OTA credentials, then (re)connect. Used for the initial
+   * connection AND every reconnect — the broker requires new credentials
+   * each time, so we must always re-run the OTA handshake.
+   */
+  async _refreshAndConnect() {
     log('info', 'Fetching device config...');
     const data = await fetchOtaConfig(this.config.mqtt.ota_url, this.deviceId, this.clientId);
     this.mqttCfg = await handleActivation(data, this.config.mqtt.ota_url, this.deviceId, this.clientId);
@@ -46,42 +78,86 @@ export class MqttClient {
 
   _connectMqtt() {
     return new Promise((resolve, reject) => {
+      // Tear down any previous client so we never leak listeners / sockets.
+      if (this.client) {
+        try { this.client.removeAllListeners(); this.client.end(true); } catch {}
+        this.client = null;
+      }
+
       this.client = mqtt.connect(`mqtts://${this.mqttCfg.endpoint}:8883`, {
         clientId: this.mqttCfg.client_id,
         username: this.mqttCfg.username,
         password: this.mqttCfg.password,
-        keepalive: 240,
-        reconnectPeriod: 5000,
-        connectTimeout: 10000,
+        keepalive: 60,
+        reconnectPeriod: 0, // we manage reconnect ourselves (fresh OTA creds required)
+        connectTimeout: 15000,
         clean: true,
+        protocolVersion: 4, // MQTT v3.1.1
       });
 
+      let settled = false;
+
       this.client.on('connect', () => {
         this.connected = true;
+        this._reconnectAttempts = 0;
         log('ok', 'MQTT Connected');
         this.client.subscribe('devices/p2p/#');
         this._sendHello();
-        resolve();
+        bus.emit('mqtt:connected');
+        if (!settled) { settled = true; resolve(); }
       });
 
       this.client.on('message', (_, raw) => this._onMessage(raw));
       this.client.on('error', e => { log('err', `MQTT: ${e.message}`); bus.emit('mqtt:error', e); });
       this.client.on('close', () => {
+        const wasConnected = this.connected;
         this.connected = false;
         this.sessionId = null;
+        // A dropped MQTT connection invalidates the whole MCP handshake — the
+        // server re-runs initialize/tools/list on the next connection, so a
+        // full reset here is correct (unlike a `goodbye`, see _onOther).
         this.mcp.reset();
         this._helloQueue = [];
-        log('warn', 'MQTT Disconnected');
+        if (wasConnected) log('warn', 'MQTT Disconnected');
+        bus.emit('mqtt:disconnected');
+        // Kick off our own reconnect (fresh OTA credentials) unless the user
+        // asked to disconnect. This is what recovers from the sudden drops.
+        if (!this._manualClose) this._scheduleReconnect();
+        if (!settled) { settled = true; reject(new Error('MQTT connection closed before ready')); }
       });
-      this.client.on('reconnect', () => log('info', 'MQTT Reconnecting...'));
     });
   }
 
+  /**
+   * Reconnect with exponential backoff. Each attempt re-fetches OTA config so
+   * we always present valid, fresh credentials to the broker.
+   */
+  _scheduleReconnect() {
+    if (this._reconnectTimer || this._manualClose) return;
+    this._reconnectAttempts++;
+    const delay = Math.min(30000, 2000 * Math.pow(1.6, Math.min(this._reconnectAttempts - 1, 6)));
+    log('info', `MQTT reconnecting in ${Math.round(delay / 1000)}s (attempt ${this._reconnectAttempts})...`);
+    bus.emit('mqtt:reconnecting', { attempt: this._reconnectAttempts, delay });
+    this._reconnectTimer = setTimeout(async () => {
+      this._reconnectTimer = null;
+      if (this._manualClose) return;
+      try {
+        await this._refreshAndConnect();
+        log('ok', 'MQTT reconnected');
+        bus.emit('mqtt:reconnected');
+      } catch (e) {
+        log('err', `Reconnect failed: ${e.message}`);
+        this._scheduleReconnect();
+      }
+    }, delay);
+  }
+
   _sendHello() {
     this.client.publish(this.mqttCfg.publish_topic, JSON.stringify({
       type: 'hello', version: 3, transport: 'udp',
       features: { mcp: true },
       audio_params: { format: 'opus', sample_rate: 16000, channels: 1, frame_duration: 60 },
+      system_prompt: 'You are Pelulu, a CLI coding agent. When the user asks to create, write, or edit files, you MUST use the file tool (action write/edit/mkdir) — actually do it, never just describe it. For multi-file work, call the tools one after another until the whole task is done. When you finish, ALWAYS say one short sentence confirming what you did (e.g. "Done, created 3 files.") so the client knows the turn is complete. Keep spoken replies short.',
     }));
   }
 
@@ -112,9 +188,20 @@ export class MqttClient {
       if (r.type === 'mcp') { this._send(r); }
       else if (r.type === 'tool_call') {
         log('tool', r.name);
+        // Emit tool call event so agent can track it
+        bus.emit('mcp:tool_call', { name: r.name, args: r.args, id: r.id });
         this.mcp.executeTool(r.name, r.args)
-          .then(result => { log('tool', result.isError ? 'failed' : 'done'); this._send({ type: 'mcp', payload: { jsonrpc: '2.0', id: r.id, result } }); })
-          .catch(err => { this._send({ type: 'mcp', payload: { jsonrpc: '2.0', id: r.id, result: { content: [{ type: 'text', text: err.message }], isError: true } } }); });
+          .then(result => {
+            log('tool', result.isError ? 'failed' : 'done');
+            this._send({ type: 'mcp', payload: { jsonrpc: '2.0', id: r.id, result: this._clampResult(result) } });
+            // Emit tool result event
+            bus.emit('mcp:tool_result', { name: r.name, args: r.args, result, id: r.id });
+          })
+          .catch(err => {
+            const errResult = { content: [{ type: 'text', text: err.message }], isError: true };
+            this._send({ type: 'mcp', payload: { jsonrpc: '2.0', id: r.id, result: this._clampResult(errResult) } });
+            bus.emit('mcp:tool_result', { name: r.name, args: r.args, result: errResult, id: r.id });
+          });
       }
     }
     if (this.mcp.toolsReceived && this._helloQueue.length) {
@@ -127,19 +214,110 @@ export class MqttClient {
     if (msg.type === 'stt') { log('user', `"${msg.text}"`); bus.emit('stt', msg.text); }
     if (msg.type === 'llm' && msg.text) { bus.emit('llm:text', msg.text); }
     if (msg.type === 'tts' && msg.state === 'sentence_start' && msg.text) { bus.emit('tts:sentence', msg.text); }
-    if (msg.type === 'goodbye') { this.sessionId = null; this.mcp.reset(); this._helloQueue = []; }
+    if (msg.type === 'goodbye') {
+      // A server `goodbye` only closes the audio SESSION — the MQTT connection
+      // and the MCP handshake (tools/list) remain valid. So we must NOT reset
+      // the MCP handler here; doing so made ensureSession() wait forever for a
+      // tools/list that never comes again, which looked like a permanent
+      // disconnect. We only drop the session id; the next message re-opens a
+      // session via a fresh hello (see ensureSession).
+      this.sessionId = null;
+      bus.emit('session:end', { turnActive: this._turnActive });
+      // Stay connected while there is still work in progress. If a turn is
+      // active we immediately re-open the session so the current task keeps
+      // talking to XiaoZhi, instead of stalling until the user types again.
+      // The MCP handshake is still valid (goodbye only closes the audio
+      // session), so this is a cheap `hello` round-trip, not a full reconnect.
+      if (this._turnActive && !this._manualClose && this.mcp.toolsReceived && !this._resuming) {
+        this._resuming = true;
+        this.ensureSession()
+          .then(ok => { if (ok) bus.emit('session:resumed'); })
+          .catch(() => {})
+          .finally(() => { this._resuming = false; });
+      }
+    }
+  }
+
+  /**
+   * Clamp an MCP tool-result so the serialized MQTT message stays under the
+   * broker's ~8KB limit. Oversized output (large file reads, recursive
+   * listings, shell dumps, search hits) would otherwise drop the whole
+   * connection the moment it's published. We truncate the result text and
+   * append a clear notice so the model knows the output was cut and can fetch
+   * the rest with a narrower request (e.g. offset/limit on file reads).
+   */
+  _clampResult(result) {
+    const measure = (res) => Buffer.byteLength(JSON.stringify({
+      type: 'mcp', payload: { jsonrpc: '2.0', id: 0, result: res }, session_id: this.sessionId || '',
+    }));
+    try {
+      if (measure(result) <= MAX_MQTT_BYTES) return result;
+
+      const text = result?.content?.[0]?.text;
+      if (typeof text !== 'string') return result; // can't safely trim non-text
+
+      const notice = '\n\n[output truncated: exceeded the 8KB transport limit — request less at once (e.g. use offset/limit for file reads or a narrower query)]';
+      // Binary-search the largest text prefix that still fits once re-wrapped.
+      let lo = 0, hi = text.length, best = 0;
+      while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const candidate = { ...result, content: [{ type: 'text', text: text.slice(0, mid) + notice }] };
+        if (measure(candidate) <= MAX_MQTT_BYTES) { best = mid; lo = mid + 1; }
+        else { hi = mid - 1; }
+      }
+      log('warn', `Tool result truncated to ${best}/${text.length} chars to fit 8KB`);
+      return { ...result, content: [{ type: 'text', text: text.slice(0, best) + notice }] };
+    } catch { return result; }
   }
 
   _send(msg) {
     if (!this.client || !this.mqttCfg) return;
     if (this.sessionId) msg.session_id = this.sessionId;
-    this.client.publish(this.mqttCfg.publish_topic, JSON.stringify(msg));
+    const payload = JSON.stringify(msg);
+    // Final safety net: never publish a message that would trip the broker's
+    // ~8KB cutoff and drop the connection. Results are pre-clamped above; this
+    // catches any other oversized message type before it does damage.
+    if (Buffer.byteLength(payload) > MAX_MQTT_BYTES) {
+      log('warn', `Dropping oversized MQTT message (${Buffer.byteLength(payload)} bytes > ${MAX_MQTT_BYTES})`);
+      return;
+    }
+    this.client.publish(this.mqttCfg.publish_topic, payload);
   }
 
-  sendText(text) {
+  /**
+   * Ensure a live XiaoZhi session exists before sending.
+   * XiaoZhi ends idle sessions with `goodbye` (common during long local
+   * tasks). When that happens we must re-send `hello` to get a fresh session
+   * + MCP handshake, otherwise all further messages are silently dropped.
+   * Resolves true once ready, false on timeout.
+   */
+  async ensureSession(timeoutMs = 15000) {
+    if (this.sessionId && this.mcp.toolsReceived) return true;
+    if (!this.client) return false;
+
+    // Re-initiate the handshake (server replies with a new hello + session_id)
+    this._sendHello();
+
+    return new Promise((resolve) => {
+      if (this.sessionId && this.mcp.toolsReceived) return resolve(true);
+      const onReady = () => { cleanup(); resolve(true); };
+      const poll = setInterval(() => {
+        if (this.sessionId && this.mcp.toolsReceived) { cleanup(); resolve(true); }
+      }, 200);
+      const timer = setTimeout(() => { cleanup(); resolve(false); }, timeoutMs);
+      const cleanup = () => { clearInterval(poll); clearTimeout(timer); bus.off('ready', onReady); };
+      bus.on('ready', onReady);
+    });
+  }
+
+  async sendText(text) {
+    // Re-establish the session if XiaoZhi dropped it while idle.
+    const ok = await this.ensureSession();
+    if (!ok) { bus.emit('session:dead'); return false; }
     this._send({ type: 'listen', state: 'detect', text });
     log('user', `"${text}"`);
     bus.emit('user:text', text);
+    return true;
   }
 
   abort() { this._send({ type: 'abort' }); }
@@ -154,7 +332,12 @@ export class MqttClient {
   }
 
   disconnect() {
-    if (this.client) { this.client.end(true); this.client = null; }
+    this._manualClose = true;
+    if (this._reconnectTimer) { clearTimeout(this._reconnectTimer); this._reconnectTimer = null; }
+    if (this.client) {
+      try { this.client.removeAllListeners(); this.client.end(true); } catch {}
+      this.client = null;
+    }
     this.connected = false;
   }
 }