pelulu-cli 1.0.5 → 1.2.0

package/src/core/job-manager.js

@@ -0,0 +1,192 @@
+/**
+ * JobManager — universal async job layer for ALL tools.
+ *
+ * WHY: XiaoZhi aborts any MCP tool call that runs longer than ~30s and then
+ * assumes the tool "timed out" — even though it is still working. That is the
+ * root cause of the "system timeout padahal berjalan" bug. Instead of making
+ * every one of the tools background-aware by hand, we wrap the tool dispatch
+ * boundary in a single job layer:
+ *
+ *   - Fast actions (finish within `graceMs`) return their result inline, exactly
+ *     as before — no behaviour change for reads/config/etc.
+ *   - Slow actions keep running in the BACKGROUND and immediately return a
+ *     job handle. The AI (or the user) then polls the `jobs` tool for progress
+ *     and the final result, so the agent never stalls or hallucinates a failure.
+ *
+ * Every job streams lifecycle events on the bus (job:started / job:progress /
+ * job:done) so the TUI can show continuous, inline feedback for ANY tool.
+ */
+import { randomUUID } from 'crypto';
+import { bus } from './event-bus.js';
+import { debug } from './logger.js';
+
+const MAX_JOBS = 40;          // ring-buffer cap so memory never grows unbounded
+const DEFAULT_GRACE_MS = 8000; // < XiaoZhi's ~30s timeout, with wide margin
+
+class JobManager {
+  #jobs = new Map();   // id -> job
+  #order = [];         // insertion order for pruning + "latest"
+
+  /**
+   * Run `executor(job)` under a job. Resolves as soon as we know whether the
+   * work finished quickly or had to be backgrounded.
+   *
+   * @returns {Promise<{done:boolean, job:object, result?:any, error?:Error}>}
+   *   done=true  -> finished within the grace window (result/error populated)
+   *   done=false -> still running in the background (poll via the `jobs` tool)
+   */
+  async dispatch({ tool, action, label } = {}, executor, { graceMs = DEFAULT_GRACE_MS } = {}) {
+    const job = this.#create({ tool, action, label });
+
+    // Kick off the actual work. We attach terminal handlers up-front so the job
+    // is always finalized regardless of whether we returned inline or backgrounded.
+    const work = Promise.resolve()
+      .then(() => executor(job))
+      .then((result) => { this.#finish(job, result); return { kind: 'result', result }; })
+      .catch((error) => { this.#fail(job, error); return { kind: 'error', error }; });
+
+    const raced = await Promise.race([
+      work,
+      new Promise((res) => setTimeout(() => res({ kind: 'timeout' }), graceMs)),
+    ]);
+
+    if (raced.kind === 'result') return { done: true, job, result: raced.result };
+    if (raced.kind === 'error') return { done: true, job, error: raced.error };
+
+    // Timed out the grace window -> run in background, let the AI poll.
+    job.backgrounded = true;
+    debug('job', `${tool}.${action || ''} backgrounded as ${job.id}`);
+    bus.emit('job:backgrounded', this.snapshot(job));
+    return { done: false, job };
+  }
+
+  /** Append a human-readable progress line to a running job (streamed to TUI). */
+  progress(jobId, message, extra = {}) {
+    const job = this.#jobs.get(jobId);
+    if (!job || job.status !== 'running') return;
+    const entry = { at: Date.now(), message, ...extra };
+    job.progress.push(entry);
+    if (job.progress.length > 100) job.progress.shift();
+    bus.emit('job:progress', { id: job.id, tool: job.tool, action: job.action, message, ...extra });
+  }
+
+  get(id) { return this.#jobs.get(id) || null; }
+
+  /** Most recent job (running preferred), for "status" with no explicit id. */
+  latest() {
+    for (let i = this.#order.length - 1; i >= 0; i--) {
+      const job = this.#jobs.get(this.#order[i]);
+      if (job && job.status === 'running') return job;
+    }
+    const lastId = this.#order[this.#order.length - 1];
+    return lastId ? this.#jobs.get(lastId) : null;
+  }
+
+  list() { return this.#order.map((id) => this.#jobs.get(id)).filter(Boolean); }
+
+  running() { return this.list().filter((j) => j.status === 'running'); }
+
+  /**
+   * Cooperative cancel: flag the job so cancel-aware executors can bail out.
+   * Non-cooperative work keeps running but its result is discarded.
+   */
+  cancel(id) {
+    const job = this.#jobs.get(id);
+    if (!job || job.status !== 'running') return false;
+    job.cancelRequested = true;
+    return true;
+  }
+
+  /** Wait up to `timeoutMs` for a job to leave the running state. */
+  async wait(id, timeoutMs = 20000) {
+    const job = this.#jobs.get(id);
+    if (!job) return null;
+    if (job.status !== 'running') return job;
+    return new Promise((resolve) => {
+      const done = () => { clearInterval(poll); clearTimeout(timer); bus.off('job:done', onDone); resolve(job); };
+      const onDone = (snap) => { if (snap.id === id) done(); };
+      const poll = setInterval(() => { if (job.status !== 'running') done(); }, 200);
+      const timer = setTimeout(() => { clearInterval(poll); bus.off('job:done', onDone); resolve(job); }, timeoutMs);
+      bus.on('job:done', onDone);
+    });
+  }
+
+  /** Plain, serializable view of a job for tool results / events. */
+  snapshot(job) {
+    if (!job) return null;
+    const now = job.finishedAt || Date.now();
+    return {
+      id: job.id,
+      tool: job.tool,
+      action: job.action,
+      label: job.label,
+      status: job.status,
+      backgrounded: !!job.backgrounded,
+      elapsed_s: Math.round((now - job.startedAt) / 1000),
+      progress: job.progress.slice(-5).map((p) => p.message),
+      error: job.error || undefined,
+    };
+  }
+
+  // ─── internals ───────────────────────────────────────────
+  #create({ tool, action, label }) {
+    const job = {
+      id: `job_${randomUUID().slice(0, 8)}`,
+      tool, action,
+      label: label || `${tool}${action ? `.${action}` : ''}`,
+      status: 'running',
+      startedAt: Date.now(),
+      finishedAt: null,
+      progress: [],
+      result: undefined,
+      error: null,
+      backgrounded: false,
+      cancelRequested: false,
+    };
+    this.#jobs.set(job.id, job);
+    this.#order.push(job.id);
+    this.#prune();
+    bus.emit('job:started', this.snapshot(job));
+    return job;
+  }
+
+  #finish(job, result) {
+    if (job.status !== 'running') return;
+    job.status = job.cancelRequested ? 'cancelled' : 'done';
+    job.finishedAt = Date.now();
+    job.result = this.#normalizeResult(result);
+    bus.emit('job:done', { ...this.snapshot(job), result: job.result });
+  }
+
+  #fail(job, error) {
+    if (job.status !== 'running') return;
+    job.status = 'error';
+    job.finishedAt = Date.now();
+    job.error = error?.message || String(error);
+    bus.emit('job:done', { ...this.snapshot(job), error: job.error });
+  }
+
+  /**
+   * Tool results come back in MCP shape ({ isError, content:[{text}] }). Unwrap
+   * to the raw payload so polling the `jobs` tool returns clean data.
+   */
+  #normalizeResult(result) {
+    if (result && Array.isArray(result.content) && result.content[0]?.type === 'text') {
+      const text = result.content[0].text;
+      try { return JSON.parse(text); } catch { return text; }
+    }
+    return result;
+  }
+
+  #prune() {
+    while (this.#order.length > MAX_JOBS) {
+      const oldest = this.#order.shift();
+      const job = this.#jobs.get(oldest);
+      // Never evict a job that is still running.
+      if (job && job.status === 'running') { this.#order.push(oldest); break; }
+      this.#jobs.delete(oldest);
+    }
+  }
+}
+
+export const jobManager = new JobManager();

package/src/core/logger.js

@@ -1,10 +1,18 @@
 /**
- * Logger — colored terminal output with levels
+ * Logger — colored terminal output with levels + file logging
  * Supports Ink mode: when active, logs go through bus instead of console
  */
+import { writeFile, mkdir, appendFile, readdir, unlink } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+
 let _debug = false;
 let _inkMode = false;
 let _bus = null;
+let _logFile = null;
+let _logQueue = [];
+let _logTimer = null;
 
 export const COLORS = {
   reset: '\x1b[0m',
@@ -35,9 +43,82 @@ export function setDebug(enabled) { _debug = enabled; }
 export function isDebug() { return _debug; }
 export function debug(msg, data) { log('debug', msg, data); }
 
+/**
+ * Initialize file logging
+ * Deletes old logs, keeps only the latest one
+ */
+export async function initFileLog(root, appName = 'pelulu') {
+  const logDir = join(root, 'logs');
+  await mkdir(logDir, { recursive: true });
+
+  // Delete old log files
+  try {
+    const files = await readdir(logDir);
+    for (const f of files) {
+      if (f.endsWith('.log')) {
+        await unlink(join(logDir, f)).catch(() => {});
+      }
+    }
+  } catch {}
+
+  const now = new Date();
+  const date = now.toISOString().slice(0, 10);
+  const time = now.toISOString().slice(11, 19).replace(/:/g, '-');
+  _logFile = join(logDir, `${appName}-${date}_${time}.log`);
+  
+  // Write header
+  const header = `═══════════════════════════════════════\n` +
+    `${appName} Log\n` +
+    `Started: ${now.toISOString()}\n` +
+    `═══════════════════════════════════════\n\n`;
+  await writeFile(_logFile, header, 'utf-8');
+  return _logFile;
+}
+
+/**
+ * Write log entry to file
+ */
+function writeToFile(level, msg, data) {
+  if (!_logFile) return;
+  
+  const ts = new Date().toISOString().slice(11, 23);
+  const icon = ICONS[level] || '';
+  let line = `${ts} ${icon} ${msg}`;
+  if (data && _debug) line += ` ${JSON.stringify(data)}`;
+  line += '\n';
+  
+  _logQueue.push(line);
+  _flushSoon();
+}
+
+/**
+ * Write raw text to log file (for AI responses, chat messages)
+ */
+export function writeRawToLog(text) {
+  if (!_logFile || !text) return;
+  const ts = new Date().toISOString().slice(11, 23);
+  _logQueue.push(`${ts} ${text}\n`);
+  _flushSoon();
+}
+
+function _flushSoon() {
+  if (_logTimer) return;
+  _logTimer = setTimeout(async () => {
+    const batch = _logQueue.join('');
+    _logQueue = [];
+    _logTimer = null;
+    try {
+      await appendFile(_logFile, batch, 'utf-8');
+    } catch {}
+  }, 500);
+}
+
 export function log(level, msg, data) {
   if (level === 'debug' && !_debug) return;
 
+  // Write to file
+  writeToFile(level, msg, data);
+
   // In Ink mode, route logs through bus so they render inside the TUI
   if (_inkMode && _bus) {
     _bus.emit('log:message', { level, msg, data });
@@ -56,6 +137,30 @@ export function log(level, msg, data) {
   if (data && _debug) console.log(`${COLORS.gray}${JSON.stringify(data, null, 2)}${COLORS.reset}`);
 }
 
+/**
+ * Flush pending logs to file
+ */
+export async function flushLogs() {
+  if (_logTimer) {
+    clearTimeout(_logTimer);
+    _logTimer = null;
+  }
+  if (_logQueue.length > 0 && _logFile) {
+    const batch = _logQueue.join('');
+    _logQueue = [];
+    try {
+      await appendFile(_logFile, batch, 'utf-8');
+    } catch {}
+  }
+}
+
+/**
+ * Get log file path
+ */
+export function getLogFile() {
+  return _logFile;
+}
+
 export function table(rows) {
   if (!rows.length) return;
   const keys = Object.keys(rows[0]);

package/src/core/system-prompt.js

@@ -1,13 +1,22 @@
 /**
  * SystemPrompt — builds context prompt for XiaoZhi LLM
- * Tells the AI what tools are available and how to use them
+ * 
+ * Now supports both legacy mode and OpenHands-style agent mode.
+ * The agent mode provides richer context and tool descriptions.
  */
 
+// Re-export from agent module for backward compatibility
+export { buildSystemPrompt as buildAgentSystemPrompt } from '../agent/system-prompt.js';
+
+/**
+ * Legacy system prompt (for direct XiaoZhi MQTT mode)
+ */
 export function buildSystemPrompt(registry, config) {
   const tools = registry.list();
+  const agentName = config.agent?.name || 'Pelulu';
   const lines = [
-    `You are ${config.agent?.name || 'a coding agent'} running in Termux/Node.js.`,
-    `You have access to ${tools.length} MCP tools. Use them to help the user.`,
+    `You are ${agentName}, an AI coding agent running in Termux/Node.js.`,
+    `You have access to ${tools.length} tools. Use them to help the user.`,
     '',
     '## Available Tools',
     '',
@@ -16,15 +25,21 @@ export function buildSystemPrompt(registry, config) {
   for (const tool of tools) {
     lines.push(`### ${tool.name}`);
     lines.push(`${tool.description}`);
-    lines.push(`Actions: ${tool.actions.join(', ')}`);
+    if (tool.actions && tool.actions.length > 0) {
+      lines.push(`Actions: ${tool.actions.map(a => typeof a === 'string' ? a : a.name).join(', ')}`);
+    }
     lines.push('');
   }
 
   lines.push('## Tool Call Format');
-  lines.push('When you need to use a tool, call it with the action and required parameters.');
-  lines.push('Example: file(action="read", path="./src/index.js")');
-  lines.push('Example: shell(action="exec", command="npm test")');
-  lines.push('Example: git(action="status")');
+  lines.push('When you need to use a tool, respond with a JSON object:');
+  lines.push('```json');
+  lines.push('{"tool": "tool_name", "action": "action_name", "param1": "value1", ...}');
+  lines.push('```');
+  lines.push('');
+  lines.push('Example: {"tool": "file", "action": "read", "path": "./src/index.js"}');
+  lines.push('Example: {"tool": "shell", "action": "exec", "command": "npm test"}');
+  lines.push('Example: {"tool": "git", "action": "status"}');
   lines.push('');
 
   lines.push('## Guidelines');
@@ -33,6 +48,7 @@ export function buildSystemPrompt(registry, config) {
   lines.push('- Run tests after making changes');
   lines.push('- Be concise in explanations');
   lines.push('- Show code changes clearly');
+  lines.push('- When done, call: {"tool": "finish", "result": "summary of what was done"}');
 
   return lines.join('\n');
 }

package/src/core/tool-registry.js

@@ -51,24 +51,83 @@ export class ToolRegistry {
   }
 
   toMcpTools() {
-    return this.all().map(t => ({
-      name: t.name,
-      description: t.description,
-      inputSchema: t.inputSchema || { type: 'object', properties: {} },
-    }));
+    // Trimmed descriptions to stay under XiaoZhi broker 8KB limit
+    const desc = {
+      agent: 'Agent: spawn, list, status',
+      ai: 'Code analysis, summarize, diff',
+      config: 'Config: get, set, list, reset',
+      diff: 'File comparison: compare, patch',
+      env: 'Env variables: get, set, list',
+      file: 'File ops: read, write, edit, delete, copy',
+      git: 'Git: init, clone, status, diff, commit, push',
+      history: 'Tool history: list, clear, stats',
+      jobs: 'Poll background jobs: list, status, wait, result, cancel',
+      network: 'Network: fetch, download, ping',
+      process: 'Process: list, info, kill, top',
+      project: 'Project: init, build, test, lint',
+      search: 'Search: grep, find, web fetch',
+      shell: 'Shell: exec, background, ps, kill',
+      snippet: 'Snippets: save, load, list, delete',
+      template: 'Templates: list, create, info',
+      watch: 'File watch: start, stop, status',
+    };
+    return this.all().map(t => {
+      const schema = t.inputSchema || { type: 'object', properties: {} };
+      const compact = { type: 'object', properties: {} };
+      // Send all properties with type + enum only (no descriptions)
+      if (schema.properties) {
+        for (const [k, v] of Object.entries(schema.properties)) {
+          const prop = { type: v.type };
+          if (v.enum) prop.enum = v.enum;
+          compact.properties[k] = prop;
+        }
+      }
+      // Include per-action required fields in the description so the AI
+      // knows exactly which params each action needs (MCP schema only
+      // supports a flat required array, not conditional per-action).
+      let description = desc[t.name] || t.description;
+      if (t.actions?.length) {
+        const actionReqs = t.actions
+          .filter(a => a.required?.length)
+          .map(a => `${a.name}→${a.required.join(',')}`)
+          .join('; ');
+        if (actionReqs) description += ` [required: ${actionReqs}]`;
+      }
+      return { name: t.name, description, inputSchema: compact };
+    });
   }
 
   async call(name, args = {}) {
     const tool = this.#tools.get(name);
     if (!tool) return { isError: true, content: [{ type: 'text', text: `Unknown tool: ${name}` }] };
     try {
-      const result = await tool.handler(args);
+      const result = await tool.handler(args, this._toolsRef());
       return { isError: false, content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result) }] };
     } catch (e) {
       return { isError: true, content: [{ type: 'text', text: e.message }] };
     }
   }
 
+  /** Call a tool and return parsed result (for internal tool-to-tool calls) */
+  async callParsed(name, args = {}) {
+    const tool = this.#tools.get(name);
+    if (!tool) throw new Error(`Unknown tool: ${name}`);
+    return await tool.handler(args, this._toolsRef());
+  }
+
+  /**
+   * The reference handed to every tool handler. Beyond `call`, it exposes tool
+   * discovery (`has` / `names`) so orchestrator tools can adapt dynamically to
+   * whatever tools are actually loaded instead of hardcoding a fixed pipeline.
+   */
+  _toolsRef() {
+    return {
+      call: (toolName, toolArgs) => this.callParsed(toolName, toolArgs),
+      has: (toolName) => this.#tools.has(toolName),
+      names: () => [...this.#tools.keys()],
+    };
+  }
+
   async shutdown() {
     for (const tool of this.#tools.values()) {
       if (tool.shutdown) await tool.shutdown();