pelulu-cli 1.1.0 → 1.2.0

package/src/mcp/mcp-handler.js

@@ -43,7 +43,7 @@ export class McpHandler {
           result: {
             protocolVersion: PROTOCOL_VERSION,
             capabilities: { tools: {} },
-            serverInfo: { name: 'shellulu', 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 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') {
@@ -90,6 +95,33 @@ export class McpHandler {
     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)

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,44 +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: 60,
-        reconnectPeriod: 5000,
-        connectTimeout: 10000,
+        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 a coding assistant. When the user asks to create, write, or edit files, you MUST use the file tool with appropriate action (write/edit/mkdir). Always use tools to complete tasks. Do not just describe what to do — actually do it using the tools.',
+      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.',
     }));
   }
 
@@ -119,13 +193,14 @@ export class MqttClient {
         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 } });
+            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 => {
-            this._send({ type: 'mcp', payload: { jsonrpc: '2.0', id: r.id, result: { content: [{ type: 'text', text: err.message }], isError: true } } });
-            bus.emit('mcp:tool_result', { name: r.name, args: r.args, result: { isError: true, content: [{ type: 'text', text: err.message }] }, id: r.id });
+            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 });
           });
       }
     }
@@ -139,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' }); }
@@ -166,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;
   }
 }

package/src/tools/file.js

@@ -46,13 +46,19 @@ const ACTIONS = {
   },
 
   edit: {
-    required: ['path', 'old_text', 'new_text'],
+    // new_text is intentionally NOT required: XiaoZhi (a voice model) often
+    // omits it — either it means "delete this text" or it dropped the field
+    // mid-call. Treating a missing/undefined new_text as an empty string keeps
+    // the edit working (as a deletion) instead of failing the whole turn with
+    // "Missing required field: new_text".
+    required: ['path', 'old_text'],
     handler: async ({ path, old_text, new_text }) => {
       const abs = safe(path);
+      const replacement = new_text ?? '';
       let content = await readFile(abs, 'utf-8');
       if (!content.includes(old_text)) throw new Error(`old_text not found in ${abs}`);
       const count = content.split(old_text).length - 1;
-      content = content.replace(old_text, new_text);
+      content = content.split(old_text).join(replacement);
       await writeFile(abs, content, 'utf-8');
       log('file', `[EDIT] Edited: ${abs} (${count} occurrence(s))`);
       return { path: abs, edited: true, occurrences: count };

package/src/tools/git.js

@@ -1,14 +1,18 @@
 /**
  * Git Tool — consolidated git operations (1 MCP tool, 10 actions)
  * Actions: init, clone, status, diff, log, add, commit, push, pull, branch
+ *
+ * Long-running operations (clone, push, pull) stream progress via task:progress
+ * so the TUI shows live feedback instead of appearing stuck.
  */
 import { exec } from 'child_process';
 import { log } from '../core/logger.js';
 import { getConfig } from '../core/config.js';
+import { bus } from '../core/event-bus.js';
 
-function git(cmd, cwd) {
+function git(cmd, cwd, { timeout = 60000 } = {}) {
   return new Promise((resolve, reject) => {
-    exec(`git ${cmd}`, { cwd, timeout: 30000, maxBuffer: 512 * 1024 }, (err, stdout, stderr) => {
+    exec(`git ${cmd}`, { cwd, timeout, maxBuffer: 512 * 1024 }, (err, stdout, stderr) => {
       if (err?.killed) return reject(new Error('Git timed out'));
       resolve({ stdout: stdout?.trim() || '', stderr: stderr?.trim() || '', code: err?.code ?? 0 });
     });
@@ -17,6 +21,37 @@ function git(cmd, cwd) {
 
 function cwd(params) { return params?.cwd || getConfig().agent?.workspace || process.cwd(); }
 
+/**
+ * Run a git command with progress reporting. For operations that may take
+ * a while (clone, push, pull), emits task:progress events.
+ */
+async function gitWithProgress(cmd, dir, { label, timeout = 120000 } = {}) {
+  const started = Date.now();
+  const tag = label || `git ${cmd.split(' ')[0]}`;
+
+  bus.emit('task:progress', {
+    tool: 'git', running: true, phase: 'exec',
+    target: tag, elapsed: 0, log: `running: git ${cmd}`,
+  });
+
+  try {
+    const result = await git(cmd, dir, { timeout });
+    const elapsed = Math.round((Date.now() - started) / 1000);
+    bus.emit('task:progress', {
+      tool: 'git', running: false, phase: 'done',
+      target: tag, elapsed, log: result.code === 0 ? 'completed' : `exit ${result.code}`,
+    });
+    return result;
+  } catch (err) {
+    bus.emit('task:progress', {
+      tool: 'git', running: false, phase: 'error',
+      target: tag, elapsed: Math.round((Date.now() - started) / 1000),
+      log: err.message,
+    });
+    throw err;
+  }
+}
+
 const ACTIONS = {
   init: {
     required: [],
@@ -31,7 +66,12 @@ const ACTIONS = {
     required: ['url'],
     handler: async ({ url, path, branch }) => {
       const cmd = `clone${branch ? ` -b ${branch}` : ''} "${url}"${path ? ` "${path}"` : ''}`;
-      await git(cmd);
+      log('git', `[CLONE] ${url}`);
+      const result = await gitWithProgress(cmd, undefined, {
+        label: `clone ${url.split('/').pop()?.replace('.git', '') || url}`,
+        timeout: 120000,
+      });
+      if (result.code !== 0) throw new Error(result.stderr || 'clone failed');
       return { cloned: true, url, path: path || url.split('/').pop()?.replace('.git', '') };
     },
   },
@@ -85,7 +125,7 @@ const ACTIONS = {
       const msg = params.message.replace(/"/g, '\\"');
       const r = await git(`commit -m "${msg}"`, dir);
       if (r.code !== 0 && r.stderr.includes('nothing to commit')) return { committed: false, reason: 'nothing to commit' };
-      log('git', `[EDIT] Committed: ${params.message}`);
+      log('git', `[COMMIT] ${params.message}`);
       return { committed: true, message: params.message, output: r.stdout.slice(-300) };
     },
   },
@@ -96,7 +136,12 @@ const ACTIONS = {
       const dir = cwd(params);
       const remote = params.remote || '';
       const branch = params.branch || '';
-      const r = await git(`push ${remote} ${branch}`.trim(), dir);
+      log('git', `[PUSH] ${remote} ${branch}`);
+      const r = await gitWithProgress(`push ${remote} ${branch}`.trim(), dir, {
+        label: `push ${remote || 'origin'} ${branch || 'current'}`,
+        timeout: 60000,
+      });
+      if (r.code !== 0) throw new Error(r.stderr || 'push failed');
       return { pushed: true, output: r.stdout.slice(-300) || r.stderr.slice(-300) };
     },
   },
@@ -107,7 +152,12 @@ const ACTIONS = {
       const dir = cwd(params);
       const remote = params.remote || '';
       const branch = params.branch || '';
-      const r = await git(`pull ${remote} ${branch}`.trim(), dir);
+      log('git', `[PULL] ${remote} ${branch}`);
+      const r = await gitWithProgress(`pull ${remote} ${branch}`.trim(), dir, {
+        label: `pull ${remote || 'origin'} ${branch || 'current'}`,
+        timeout: 60000,
+      });
+      if (r.code !== 0) throw new Error(r.stderr || 'pull failed');
       return { pulled: true, output: r.stdout.slice(-300) };
     },
   },

package/src/tools/jobs.js

@@ -0,0 +1,93 @@
+/**
+ * jobs — universal poll interface for background tool runs.
+ *
+ * Any tool action that takes longer than the grace window is turned into a
+ * background job (see core/job-manager.js). This tool is how the AI keeps
+ * track of them so it never assumes a still-running action "timed out":
+ *
+ *   jobs { action: "list" }                 -> all recent jobs + their status
+ *   jobs { action: "status", id: "job_x" }  -> one job (or the latest if no id)
+ *   jobs { action: "wait",   id: "job_x" }  -> wait briefly for it to finish
+ *   jobs { action: "result", id: "job_x" }  -> the finished job's result payload
+ *   jobs { action: "cancel", id: "job_x" }  -> request cancellation
+ */
+import { jobManager } from '../core/job-manager.js';
+
+function describe(job) {
+  if (!job) return null;
+  const snap = jobManager.snapshot(job);
+  return {
+    ...snap,
+    hint:
+      snap.status === 'running'
+        ? `Still running (${snap.elapsed_s}s). Poll again with action=status id=${snap.id}, or action=wait.`
+        : snap.status === 'done'
+          ? `Finished in ${snap.elapsed_s}s. Use action=result id=${snap.id} to read the output.`
+          : `${snap.status}.`,
+  };
+}
+
+const ACTIONS = {
+  list: () => {
+    const jobs = jobManager.list().map(describe);
+    const running = jobs.filter((j) => j.status === 'running').length;
+    return {
+      total: jobs.length,
+      running,
+      message: running
+        ? `${running} job(s) still running. Poll them with action=status.`
+        : 'No jobs are currently running.',
+      jobs: jobs.slice(-15),
+    };
+  },
+
+  status: ({ id }) => {
+    const job = id ? jobManager.get(id) : jobManager.latest();
+    if (!job) return { status: 'none', message: 'No jobs yet. Start a tool action first.' };
+    return describe(job);
+  },
+
+  wait: async ({ id, timeout }) => {
+    const target = id ? jobManager.get(id) : jobManager.latest();
+    if (!target) return { status: 'none', message: 'No jobs to wait for.' };
+    const ms = Math.min(Math.max(Number(timeout) || 20000, 1000), 25000); // capped < XiaoZhi timeout
+    const job = await jobManager.wait(target.id, ms);
+    const out = describe(job);
+    if (job.status === 'running') out.message = `Still running after ${Math.round(ms / 1000)}s — poll again or action=wait.`;
+    return out;
+  },
+
+  result: ({ id }) => {
+    const job = id ? jobManager.get(id) : jobManager.latest();
+    if (!job) return { status: 'none', message: 'No jobs yet.' };
+    if (job.status === 'running') return { ...describe(job), message: 'Not finished yet — use action=wait first.' };
+    return { id: job.id, tool: job.tool, action: job.action, status: job.status, error: job.error || undefined, result: job.result };
+  },
+
+  cancel: ({ id }) => {
+    const job = id ? jobManager.get(id) : jobManager.latest();
+    if (!job) return { status: 'none', message: 'No job to cancel.' };
+    const ok = jobManager.cancel(job.id);
+    return { id: job.id, cancelled: ok, message: ok ? 'Cancellation requested.' : `Job is already ${job.status}.` };
+  },
+};
+
+export default {
+  name: 'jobs',
+  description: 'Track background tool jobs so long-running actions never look timed out. Actions: list, status, wait, result, cancel.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      action: { type: 'string', enum: ['list', 'status', 'wait', 'result', 'cancel'] },
+      id: { type: 'string', description: 'Job id (defaults to the latest job)' },
+      timeout: { type: 'number', description: 'wait: max ms to block (<=25000)' },
+    },
+    required: ['action'],
+  },
+  async handler(args = {}) {
+    const action = args.action || 'status';
+    const fn = ACTIONS[action];
+    if (!fn) return { error: `Unknown action "${action}". Use: ${Object.keys(ACTIONS).join(', ')}` };
+    return await fn(args);
+  },
+};