micro-models-agent 0.9.0 → 0.10.0

package/dist/modules/processes/detect.js

@@ -0,0 +1,34 @@
+/**
+ * Heuristic detection of long-running (server/watch) commands.
+ *
+ * The explicit `background: true` bash parameter always wins; this list is a
+ * convenience so dev servers don't block the agent. It only inspects the raw
+ * shell command (a technical process-type decision, not task classification).
+ */
+const LONG_RUNNING_PATTERNS = [
+    /\b(npm|pnpm|yarn|bun|npx)\s+(run\s+)?(dev|start|serve|preview|watch|server)\b/i,
+    /\b(deno|node)\s+.*\b(run\s+)?(dev|serve|watch|server)\b/i,
+    /(^|\s)--watch\b/i,
+    /(^|\s)-w\b/i,
+    /\bnodemon\b/i,
+    /\btsx watch\b/i,
+    /\b(ts-node|tsc)\s+.*--watch\b/i,
+    /\bvite(?!\s+(build|create))\b/i,
+    /\bwebpack(-dev-server|\s+serve)\b/i,
+    /\bastro dev\b/i,
+    /\bnext (dev|start)\b/i,
+    /\bnuxt (dev|start)\b/i,
+    /\bsvelte-kit (dev|preview)\b/i,
+    /\bgatsby develop\b/i,
+    /\bdocker(-compose)?\s+.*\bup\b/i,
+    /\buvicorn\b|\bgunicorn\b/i,
+    /\bpython\s+-m\s+http\.server\b/i,
+    /\bflask run\b/i,
+    /\bphp artisan serve\b/i,
+    /\brails (server|s)\b/i,
+    /\bvitest watch\b/i,
+    /\bjest --watch\b/i,
+];
+export function isLongRunningCommand(command) {
+    return LONG_RUNNING_PATTERNS.some((pattern) => pattern.test(command));
+}

package/dist/modules/processes/index.js

@@ -0,0 +1,3 @@
+export { runCommand, killByCallId } from "./runner";
+export { processRegistry } from "./registry";
+export { isLongRunningCommand } from "./detect";

package/dist/modules/processes/registry.js

@@ -0,0 +1,142 @@
+import { spawn } from "child_process";
+import { platform } from "os";
+const MAX_LOG_LINES = 300;
+const MAX_KEPT_PROCESSES = 20;
+let seq = 0;
+function killTree(child) {
+    const pid = child.pid;
+    if (!pid)
+        return;
+    if (platform() === "win32") {
+        spawn("taskkill", ["/pid", String(pid), "/T", "/F"], {
+            windowsHide: true,
+            stdio: "ignore",
+        });
+        return;
+    }
+    try {
+        process.kill(-pid, "SIGTERM");
+    }
+    catch {
+        try {
+            child.kill("SIGKILL");
+        }
+        catch {
+            /* already dead */
+        }
+    }
+}
+class ProcessRegistry {
+    procs = new Map();
+    children = new Map();
+    /**
+     * Start a background process. Returns immediately with the entry; output is
+     * buffered into `entry.log` as it arrives.
+     */
+    start(command, cwd, sessionId) {
+        const id = `proc_${Date.now()}_${++seq}`;
+        const entry = {
+            id,
+            pid: 0,
+            command,
+            cwd,
+            sessionId,
+            status: "running",
+            exitCode: null,
+            startedAt: new Date().toISOString(),
+            log: [],
+        };
+        this.trimOldEntries();
+        this.procs.set(id, entry);
+        const child = spawn(command, {
+            cwd,
+            shell: true,
+            windowsHide: true,
+            detached: platform() !== "win32",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        this.children.set(id, child);
+        entry.pid = child.pid ?? 0;
+        let partial = "";
+        const append = (chunk) => {
+            const text = partial + chunk.toString();
+            const lines = text.split(/\r?\n/);
+            partial = lines.pop() ?? "";
+            for (const line of lines) {
+                if (entry.log.length >= MAX_LOG_LINES) {
+                    entry.log.shift();
+                }
+                entry.log.push(line);
+            }
+        };
+        child.stdout?.on("data", append);
+        child.stderr?.on("data", append);
+        child.on("error", (err) => {
+            if (entry.status === "running") {
+                entry.status = "killed";
+            }
+            append(Buffer.from(`[process error] ${err.message}`));
+        });
+        child.on("close", (code) => {
+            if (entry.status === "running") {
+                entry.status = "exited";
+            }
+            entry.exitCode = code;
+            this.children.delete(id);
+            if (partial) {
+                entry.log.push(partial);
+                partial = "";
+            }
+        });
+        return entry;
+    }
+    list(sessionId) {
+        const all = Array.from(this.procs.values());
+        if (!sessionId)
+            return all;
+        return all.filter((p) => p.sessionId === sessionId);
+    }
+    get(id) {
+        return this.procs.get(id);
+    }
+    getLog(id, tail) {
+        const entry = this.procs.get(id);
+        if (!entry)
+            return "";
+        const lines = tail && tail > 0 ? entry.log.slice(-tail) : entry.log;
+        return lines.join("\n");
+    }
+    /** Kill a background process tree. Returns false when not found. */
+    kill(id) {
+        const entry = this.procs.get(id);
+        if (!entry)
+            return false;
+        if (entry.status === "running") {
+            entry.status = "killed";
+            const child = this.children.get(id);
+            if (child) {
+                killTree(child);
+            }
+        }
+        return true;
+    }
+    /** Kill every managed background process (used on agent shutdown). */
+    killAll(sessionId) {
+        const targets = this.list(sessionId);
+        for (const entry of targets) {
+            this.kill(entry.id);
+        }
+        return targets.length;
+    }
+    trimOldEntries() {
+        if (this.procs.size < MAX_KEPT_PROCESSES)
+            return;
+        const sorted = Array.from(this.procs.values()).sort((a, b) => a.startedAt.localeCompare(b.startedAt));
+        const toRemove = sorted.slice(0, sorted.length - MAX_KEPT_PROCESSES + 1);
+        for (const entry of toRemove) {
+            this.procs.delete(entry.id);
+            this.children.delete(entry.id);
+        }
+    }
+}
+export const processRegistry = new ProcessRegistry();

package/dist/modules/processes/runner.js

@@ -0,0 +1,109 @@
+import { spawn } from "child_process";
+import { platform } from "os";
+const activeChildren = new Map();
+/**
+ * Kill a foreground command previously registered by `callId` (used by the
+ * tool executor when the execution timeout fires). Returns true when a child
+ * was found and killed.
+ */
+export function killByCallId(callId) {
+    const entry = activeChildren.get(callId);
+    if (!entry)
+        return false;
+    activeChildren.delete(callId);
+    try {
+        entry.kill();
+    }
+    catch {
+        /* already dead */
+    }
+    return true;
+}
+function killTree(child) {
+    const pid = child.pid;
+    if (!pid)
+        return;
+    if (platform() === "win32") {
+        spawn("taskkill", ["/pid", String(pid), "/T", "/F"], {
+            windowsHide: true,
+            stdio: "ignore",
+        });
+        return;
+    }
+    try {
+        // `detached: true` makes the child a process-group leader on POSIX,
+        // so killing -pid terminates the whole tree.
+        process.kill(-pid, "SIGTERM");
+    }
+    catch {
+        try {
+            child.kill("SIGKILL");
+        }
+        catch {
+            /* already dead */
+        }
+    }
+}
+/**
+ * Run a shell command asynchronously (non-blocking event loop) and collect
+ * stdout/stderr. The child is killed on timeout and can be killed externally
+ * via `killByCallId` (used by the tool executor timeout).
+ */
+export function runCommand(command, options = {}) {
+    const { cwd, callId, timeoutMs = 120_000, maxBuffer = 10 * 1024 * 1024, } = options;
+    return new Promise((resolve) => {
+        let timedOut = false;
+        let stdout = "";
+        let stderr = "";
+        const child = spawn(command, {
+            cwd,
+            shell: true,
+            windowsHide: true,
+            detached: platform() !== "win32",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const append = (ref, chunk) => {
+            const text = chunk.toString();
+            const next = ref.value.length + text.length;
+            if (next > maxBuffer) {
+                ref.value =
+                    ref.value.slice(ref.value.length + text.length - maxBuffer) + text;
+            }
+            else {
+                ref.value = ref.value + text;
+            }
+        };
+        const stdoutRef = { value: stdout };
+        const stderrRef = { value: stderr };
+        child.stdout?.on("data", (chunk) => append(stdoutRef, chunk));
+        child.stderr?.on("data", (chunk) => append(stderrRef, chunk));
+        const entry = {
+            kill: () => killTree(child),
+        };
+        if (callId) {
+            activeChildren.set(callId, entry);
+        }
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killTree(child);
+        }, timeoutMs);
+        child.on("error", () => {
+            clearTimeout(timer);
+            if (callId)
+                activeChildren.delete(callId);
+            resolve({
+                stdout: stdoutRef.value,
+                stderr: stderrRef.value,
+                code: null,
+                signal: null,
+                timedOut,
+            });
+        });
+        child.on("close", (code, signal) => {
+            clearTimeout(timer);
+            if (callId)
+                activeChildren.delete(callId);
+            resolve({ stdout: stdoutRef.value, stderr: stderrRef.value, code, signal, timedOut });
+        });
+    });
+}

package/dist/tools/bash.js

@@ -1,9 +1,11 @@
-import { execSync } from 'child_process';
-import { platform } from 'os';
 import { isCommandAllowed, sanitizeCommandForLog } from '../modules/security/command-validator';
 import { logBashCommand, logSecurityBlock } from '../modules/security/audit-log';
 import { getSessionSecurityConfig } from '../modules/security/session-isolation';
 import { DEFAULT_SECURITY_CONFIG } from '../config/security';
+import { runCommand, processRegistry, isLongRunningCommand } from '../modules/processes';
+import { t } from '../i18n/index';
+import { platform } from 'os';
+const BASH_TIMEOUT_MS = 120_000;
 function adaptCommandForWindows(command) {
     if (platform() !== 'win32')
         return command;
@@ -19,13 +21,14 @@ function adaptCommandForWindows(command) {
 }
 export const bashTool = {
     name: 'bash',
-    description: 'Execute a shell command and return its output. Use for running tests, build, git, and shell operations.',
+    description: 'Execute a shell command and return its output. Use for running tests, build, git, and shell operations. Long-running commands (dev servers, watchers) start in the background and return a process id immediately — manage them with process_list, process_log, process_kill. Set background=true to force background execution.',
     tags: ['shell', 'code'],
     parameters: {
         type: 'object',
         properties: {
             command: { type: 'string', description: 'Shell command to execute' },
             workdir: { type: 'string', description: 'Working directory (default: baseDir)' },
+            background: { type: 'boolean', description: 'Start the command in the background and return immediately with a process id (default: auto-detect long-running commands)' },
         },
         required: ['command'],
     },
@@ -53,28 +56,52 @@ export const bashTool = {
             logBashCommand(ctx.sessionId, sanitizeCommandForLog(command), false, // Will be updated after execution
             `Working directory: ${workdir}`);
         }
+        const background = args.background === true || isLongRunningCommand(command);
+        if (background) {
+            const entry = processRegistry.start(command, workdir, ctx.sessionId);
+            if (securityConfig?.logCommands) {
+                logBashCommand(ctx.sessionId, sanitizeCommandForLog(command), true, `Started in background: ${entry.id} (PID ${entry.pid})`);
+            }
+            const explicit = args.background === true;
+            return {
+                success: true,
+                output: `${t("proc.started", {
+                    id: entry.id,
+                    pid: entry.pid,
+                    command,
+                })}${explicit ? "" : `\n${t("proc.detected_hint")}`}\n${t("proc.manage_hint", {
+                    id: entry.id,
+                })}`,
+            };
+        }
         try {
-            const output = execSync(command, {
+            const res = await runCommand(command, {
                 cwd: workdir,
-                encoding: 'utf-8',
-                maxBuffer: 10 * 1024 * 1024,
-                timeout: 120_000,
+                callId: ctx.activeCallId,
+                timeoutMs: BASH_TIMEOUT_MS,
             });
-            // Update audit log with success
+            const parts = [res.stdout.trimEnd(), res.stderr.trimEnd()].filter(Boolean);
+            let output = parts.join("\n");
+            if (res.timedOut) {
+                output = `${output ? output + "\n" : ""}${t("proc.timed_out", {
+                    ms: BASH_TIMEOUT_MS,
+                })}`;
+            }
+            else if (!output && res.code !== 0) {
+                output = `(exit code ${res.code})`;
+            }
+            // Update audit log with result
             if (securityConfig?.logCommands) {
-                logBashCommand(ctx.sessionId, sanitizeCommandForLog(command), true, `Working directory: ${workdir}, Output length: ${output.length}`);
+                logBashCommand(ctx.sessionId, sanitizeCommandForLog(command), res.code === 0, `Working directory: ${workdir}, Output length: ${res.stdout.length}`);
             }
-            return { success: true, output: output.trimEnd() };
+            return { success: res.code === 0, output };
         }
         catch (e) {
-            const stderr = e.stderr?.toString() || '';
-            const stdout = e.stdout?.toString() || '';
-            const errorOutput = stderr || stdout || e.message;
             // Update audit log with failure
             if (securityConfig?.logCommands) {
-                logBashCommand(ctx.sessionId, sanitizeCommandForLog(command), false, `Working directory: ${workdir}, Error: ${errorOutput.slice(0, 100)}`);
+                logBashCommand(ctx.sessionId, sanitizeCommandForLog(command), false, `Working directory: ${workdir}, Error: ${e.message?.slice(0, 100) || ""}`);
             }
-            return { success: false, output: errorOutput };
+            return { success: false, output: e.message || String(e) };
         }
     },
 };

package/dist/tools/executor.js

@@ -1,3 +1,4 @@
+import { killByCallId } from "../modules/processes/runner";
 import { t } from "../i18n/index";
 const TOOL_EXECUTION_TIMEOUT_MS = 60000;
 export class ToolExecutor {
@@ -39,16 +40,21 @@ export class ToolExecutor {
         }
         let result;
         try {
+            this.ctx.activeCallId = call.id;
             if (tool.interactive) {
                 // Interactive tools wait for user input — no timeout.
                 result = await tool.handler(this.ctx, call.arguments);
             }
             else {
                 const timeoutPromise = new Promise((_, reject) => {
-                    setTimeout(() => reject(new Error(t("tool.timeout", {
-                        name: call.name,
-                        seconds: TOOL_EXECUTION_TIMEOUT_MS / 1000,
-                    }))), TOOL_EXECUTION_TIMEOUT_MS);
+                    setTimeout(() => {
+                        // Kill any long-running child process registered for this call.
+                        killByCallId(call.id);
+                        reject(new Error(t("tool.timeout", {
+                            name: call.name,
+                            seconds: TOOL_EXECUTION_TIMEOUT_MS / 1000,
+                        })));
+                    }, TOOL_EXECUTION_TIMEOUT_MS);
                 });
                 result = await Promise.race([
                     tool.handler(this.ctx, call.arguments),

package/dist/tools/index.js

@@ -11,6 +11,9 @@ import { deleteFileTool } from './delete-file';
 import { moveFileTool } from './move-file';
 import { fileInfoTool } from './file-info';
 import { bashTool } from './bash';
+import { processListTool } from './process-list';
+import { processLogTool } from './process-log';
+import { processKillTool } from './process-kill';
 import { subagentTool } from './subagent';
 import { webSearchTool } from './web-search';
 import { webFetchTool } from './web-fetch';
@@ -24,13 +27,14 @@ import { searchHistoryTool } from './search-history';
 import { createBrowserTool } from './browser';
 export { ToolRegistry, ToolExecutor };
 export { filterToolsByTags } from './filter-tools';
-export { readFileTool, writeFileTool, editFileTool, globTool, grepTool, listDirTool, createDirTool, deleteFileTool, moveFileTool, fileInfoTool, bashTool, subagentTool, webSearchTool, webFetchTool, webBrowseTool, questionTool, approveTool, createLoadSkillTool, pipelineRunTool, mcpCallTool, searchHistoryTool, createBrowserTool, };
+export { readFileTool, writeFileTool, editFileTool, globTool, grepTool, listDirTool, createDirTool, deleteFileTool, moveFileTool, fileInfoTool, bashTool, subagentTool, processListTool, processLogTool, processKillTool, webSearchTool, webFetchTool, webBrowseTool, questionTool, approveTool, createLoadSkillTool, pipelineRunTool, mcpCallTool, searchHistoryTool, createBrowserTool, };
 export function registerAllTools(registry, skillsModule) {
     const tools = [
         readFileTool, writeFileTool, editFileTool,
         globTool, grepTool, listDirTool, createDirTool,
         deleteFileTool, moveFileTool, fileInfoTool,
         bashTool, subagentTool,
+        processListTool, processLogTool, processKillTool,
         webSearchTool, webFetchTool, webBrowseTool,
         questionTool, approveTool,
         pipelineRunTool, mcpCallTool, searchHistoryTool,

package/dist/tools/process-kill.js

@@ -0,0 +1,29 @@
+import { processRegistry } from '../modules/processes';
+import { t } from '../i18n/index';
+export const processKillTool = {
+    name: 'process_kill',
+    description: 'Stop a background process started via bash (dev server, watcher). Kills the whole process tree (children included). Use the id returned by bash or process_list.',
+    tags: ['shell'],
+    parameters: {
+        type: 'object',
+        properties: {
+            id: { type: 'string', description: 'Process id from bash output or process_list' },
+        },
+        required: ['id'],
+    },
+    handler: async (ctx, args) => {
+        const id = String(args.id);
+        const entry = processRegistry.get(id);
+        if (!entry) {
+            return { success: false, output: t('proc.not_found', { id }) };
+        }
+        const killed = processRegistry.kill(id);
+        if (!killed) {
+            return { success: false, output: t('proc.kill_failed', { id }) };
+        }
+        return {
+            success: true,
+            output: t('proc.killed', { id, pid: entry.pid }),
+        };
+    },
+};

package/dist/tools/process-list.js

@@ -0,0 +1,38 @@
+import { processRegistry } from '../modules/processes';
+import { t } from '../i18n/index';
+export const processListTool = {
+    name: 'process_list',
+    description: 'List background processes started via the bash tool (dev servers, watchers, long-running commands). Shows id, pid, command, status, and recent output. Use with process_log and process_kill to inspect or stop them.',
+    tags: ['shell'],
+    parameters: {
+        type: 'object',
+        properties: {},
+    },
+    handler: async (ctx) => {
+        const list = processRegistry.list(ctx.sessionId);
+        if (list.length === 0) {
+            return { success: true, output: t('proc.none') };
+        }
+        const statusLabel = (status) => {
+            if (status === 'running')
+                return t('proc.status_running');
+            if (status === 'exited')
+                return t('proc.status_exited');
+            return t('proc.status_killed');
+        };
+        const lines = [`${t('proc.list_header')} (${list.length}):`];
+        for (const entry of list) {
+            const tail = entry.log.length > 0 ? entry.log[entry.log.length - 1] : '';
+            const detail = tail
+                ? ` — ${tail.slice(0, 80)}${tail.length > 80 ? '…' : ''}`
+                : '';
+            lines.push(`  ${entry.id}  PID ${entry.pid}  ${statusLabel(entry.status)}  ${entry.command}${detail}`);
+        }
+        lines.push(`\n${t('proc.hint', {
+            list: 'process_list',
+            log: 'process_log',
+            kill: 'process_kill',
+        })}`);
+        return { success: true, output: lines.join('\n') };
+    },
+};

package/dist/tools/process-log.js

@@ -0,0 +1,39 @@
+import { processRegistry } from '../modules/processes';
+import { t } from '../i18n/index';
+export const processLogTool = {
+    name: 'process_log',
+    description: 'Show the buffered output of a background process started via bash. Use after starting a dev server to verify it came up without errors, and while it runs to check its state.',
+    tags: ['shell'],
+    parameters: {
+        type: 'object',
+        properties: {
+            id: { type: 'string', description: 'Process id from bash output or process_list' },
+            tail: { type: 'number', description: 'Number of trailing lines to show (default: all buffered lines, max 300)' },
+        },
+        required: ['id'],
+    },
+    handler: async (ctx, args) => {
+        const id = String(args.id);
+        const entry = processRegistry.get(id);
+        if (!entry) {
+            return { success: false, output: t('proc.not_found', { id }) };
+        }
+        const status = entry.status === 'running'
+            ? t('proc.status_running')
+            : entry.status === 'exited'
+                ? t('proc.status_exited')
+                : t('proc.status_killed');
+        const tail = typeof args.tail === 'number' ? args.tail : undefined;
+        const log = processRegistry.getLog(id, tail);
+        if (!log) {
+            return {
+                success: true,
+                output: `${t('proc.log_header', { id, status })} ${t('proc.log_empty')}`,
+            };
+        }
+        return {
+            success: true,
+            output: `${t('proc.log_header', { id, status })}\n${log}`,
+        };
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "micro-models-agent",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Micro Models Agent (MMA) — LLM agent harness for small models (Qwen3.5-9B, 32K-64K context)",
   "type": "module",
   "bin": {