autoclaw 1.3.3 → 1.3.5

package/README.zh-CN.md

@@ -4,6 +4,7 @@
 [![NPM Downloads](https://img.shields.io/npm/dm/autoclaw.svg?style=flat-square)](https://www.npmjs.com/package/autoclaw)
 [![GitHub](https://img.shields.io/badge/GitHub-Repository-blue?logo=github&style=flat-square)](https://github.com/tsingliuwin/autoclaw)
 [![License](https://img.shields.io/npm/l/autoclaw.svg?style=flat-square)](https://github.com/tsingliuwin/autoclaw/blob/main/LICENSE)
+[![Safety](https://img.shields.io/badge/Safety-Notice-yellow?style=flat-square)](./SAFETY.md)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
 
 **稳定、高工程化、易规模化：专为无界面系统设计的高效自动化 Agent 框架。**
@@ -34,7 +35,8 @@ AutoClaw 是一款针对 **“无界面系统” (Headless Systems)** 的高稳
 - 📜 **无头执行 (Headless Execution)**: 无需图形界面，纯终端运行。核心流程仅依赖 Shell 与文件操作；可选的网页工具在无头 Chromium 中运行。
 - 🤖 **非交互模式**: 支持自动化标志（`-y`, `--no-interactive`），完美适配零干预的自动化流程。
 - 📂 **全方位控制 (Universal Control)**: 从基础的文件 I/O 到复杂的系统管理。
-- 🛡️ **防失控保护**: 单任务步数上限、API 指数退避重试、Shell 命令超时、工具输出截断，保证模型上下文不被撑爆。
+- 🖥️ **后台进程**: 后台启动长期命令(开发服务器、watcher)并轮询输出,不阻塞任务运行。
+- 🛡️ **安全护栏**: 破坏性命令闸、凭据文件防线、步数上限、墙钟超时与 API 重试——为没有人看着的机器而设计。
 - 🧠 **上下文感知 (Context Aware)**: 提供精确的操作系统与时间上下文，正确处理"今天"、"下周一"等相对时间。
 - 🌐 **网页搜索**: 集成 Tavily，支持实时信息检索。
 - 🌍 **网页阅读与截图**: 提取文章正文、截取页面图片（需先执行 `npx playwright install chromium`）。
@@ -170,6 +172,14 @@ autoclaw "将 src/index.ts 重构为使用 ES 模块" -y
 
 ### 诊断
 `autoclaw doctor` 无头完成全面自检,逐项打印 ✓/✗:配置文件、解析出的 provider/baseUrl/model、API key、真实连接测试、解析出的 shell、已注册工具、playwright 浏览器状态。退出 `0` = 就绪,`1` = 有关键项失败(会打印是哪项)。适合 CI 或新机器。
+
+### 沙箱
+命令执行可通过 `config.sandbox` / `AUTOCLOW_SANDBOX` 加以约束(词汇借鉴自 DeepSeek Harness):
+- `danger-full-access`(默认):命令不受约束地运行。
+- `workspace-write`:命令只能在当前工作目录和 `/tmp` 内写入。
+- `read-only`:命令无法在任何位置写入。
+
+后端:Linux 使用 bubblewrap(`apt install bubblewrap`),macOS 使用 `sandbox-exec`。**Windows 暂无后端**——非默认模式会"失败关闭"(直接拒绝命令并给出明确错误),而不是假装约束;在 Windows 上请暂用 `danger-full-access`。此词汇不约束读取与网络。
 - `--json`: 在 stdout 输出 NDJSON 事件流 (供编排器使用,配合 `-n`)。
 
 ### Provider 预设
@@ -196,6 +206,8 @@ AutoClaw 使用层级配置系统。
 - `model`: 默认使用的模型。
 - `maxSteps`: 单任务最大 LLM 轮数，超出后自动停止 (默认: `25`)。
 - `shellTimeout`: Shell 命令超时时间（毫秒）(默认: `120000`)。
+- `taskTimeoutMs`: 单任务整体墙钟超时（毫秒，默认关闭；会中断进行中的 API 调用并以 `timeout` 状态停止）。
+- `sandbox`: 约束 shell 命令（`read-only`、`workspace-write`、`danger-full-access`；默认 `danger-full-access`）。
 - `shell`: 强制 `execute_shell_command` 使用的 shell (`bash`、`powershell`、`cmd`、`sh`；默认自动检测——Windows 上优先 Git Bash > PowerShell > cmd)。
 - `tavilyApiKey`: Tavily 网页搜索的 API 密钥。
 - `smtpHost`, `smtpPort`, `smtpUser`, `smtpPass`, `smtpFrom`: SMTP 邮件设置。
@@ -216,6 +228,8 @@ AutoClaw 使用层级配置系统。
 - `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_MODEL`: 主模型设置。
 - `AUTOCLOW_PROVIDER`: 未传 `-P` 时使用的 provider 预设。
 - `AUTOCLOW_MAX_STEPS`, `AUTOCLOW_SHELL_TIMEOUT`: 稳定性限制（单任务最大轮数；Shell 超时毫秒数）。
+- `AUTOCLOW_TASK_TIMEOUT_MS`: 单任务整体墙钟超时（毫秒）。
+- `AUTOCLOW_SANDBOX`: 约束 shell 命令（`read-only`、`workspace-write`、`danger-full-access`）。
 - `AUTOCLOW_SHELL`: 强制 shell 命令使用的 shell (`bash`、`powershell`、`cmd`、`sh`)。
 - `AUTOCLOW_INCLUDE_USAGE`: 设为 `1`/`true` 时向 API 请求 token 用量（可选开启）。
 - `TAVILY_API_KEY`, `SMTP_HOST`/`SMTP_PORT`/`SMTP_USER`/`SMTP_PASS`, `FEISHU_WEBHOOK`/`FEISHU_KEYWORD`, `DINGTALK_WEBHOOK`/`DINGTALK_KEYWORD`, `WECOM_WEBHOOK`/`WECOM_KEYWORD`: 工具凭据，可作为 setup 的替代方式。

package/dist/agent.js

@@ -11,6 +11,21 @@ import { truncateOutput } from './truncate.js';
 import { buildShellInfo, resolveShellType } from './shell.js';
 const DEFAULT_MAX_STEPS = 25;
 const TOOL_RESULT_TRIM_MARKER = 'older tool output trimmed';
+// Canonical JSON: sorted object keys, so equivalent arguments from
+// different model turns map to the same repeat signature.
+function canonicalArgs(args) {
+    try {
+        return JSON.stringify(args, (_key, value) => {
+            if (value && typeof value === 'object' && !Array.isArray(value)) {
+                return Object.keys(value).sort().reduce((acc, k) => { acc[k] = value[k]; return acc; }, {});
+            }
+            return value;
+        });
+    }
+    catch {
+        return String(args);
+    }
+}
 export class Agent {
     client;
     messages;
@@ -51,6 +66,7 @@ System Information:
             has('web_search') ? '- Web: web_search — real-time information lookup' : null,
             has('read_website') ? '- Web: read_website — extract article content from a URL' : null,
             has('take_screenshot') ? '- Web: take_screenshot — capture page visuals' : null,
+            has('start_background_process') ? '- Processes: start_background_process / check_background_process / stop_background_process — run long-lived commands (servers, watchers) in the background and poll their output' : null,
             has('send_email') ? '- Communication: send_email — SMTP email delivery' : null,
             has('send_notification') ? '- Communication: send_notification — push to Feishu/DingTalk/WeCom' : null,
             has('generate_image') ? '- Creation: generate_image — AI image generation (DALL-E compatible)' : null,
@@ -104,11 +120,20 @@ RULES OF ENGAGEMENT:
     async chat(userInput) {
         this.messages.push({ role: "user", content: userInput });
         const maxSteps = Number(this.config?.maxSteps || process.env.AUTOCLOW_MAX_STEPS || DEFAULT_MAX_STEPS);
+        const taskTimeoutMs = Number(this.config?.taskTimeoutMs || process.env.AUTOCLOW_TASK_TIMEOUT_MS || 0);
+        const deadline = taskTimeoutMs > 0 ? Date.now() + taskTimeoutMs : Number.POSITIVE_INFINITY;
+        const abortController = new AbortController();
+        const abortTimer = taskTimeoutMs > 0
+            ? setTimeout(() => abortController.abort(new Error(`task wall-clock timeout after ${taskTimeoutMs}ms`)), taskTimeoutMs)
+            : null;
+        const startedAt = Date.now();
         let active = true;
         let step = 0;
         let status = 'completed';
         let errorMessage;
         let lastContent = null;
+        let lastToolSignature = null;
+        let consecutiveRepeats = 0;
         const totalUsage = { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 };
         let sawUsage = false;
         this.emitEvent({ event: 'run_start', model: this.model, task: userInput });
@@ -120,6 +145,13 @@ RULES OF ENGAGEMENT:
                 }
                 break;
             }
+            if (Date.now() > deadline) {
+                status = 'timeout';
+                if (!this.jsonMode) {
+                    console.log(chalk.yellow(`\n[TaskTimeout] Wall-clock limit of ${taskTimeoutMs}ms reached; stopping.`));
+                }
+                break;
+            }
             this.trimOldToolResults();
             step++;
             const spinner = this.jsonMode
@@ -133,13 +165,13 @@ RULES OF ENGAGEMENT:
                 stream = await withRetry(async () => this.client.chat.completions.create({
                     model: this.model,
                     messages: this.messages,
-                    tools: getToolDefinitions(),
+                    tools: getToolDefinitions(this.config),
                     tool_choice: "auto",
                     stream: true,
                     // Not every OpenAI-compatible provider accepts stream_options;
                     // usage tracking is therefore opt-in only.
                     ...(this.config?.includeUsage ? { stream_options: { include_usage: true } } : {})
-                }), {
+                }, { signal: abortController.signal }), {
                     onRetry: (err, nextAttempt, delayMs) => {
                         spinner.text = `API error (${err.message}); retrying in ${Math.round(delayMs / 1000)}s (attempt ${nextAttempt})...`;
                     }
@@ -149,8 +181,14 @@ RULES OF ENGAGEMENT:
                 spinner.fail('Error during processing');
                 if (!this.jsonMode)
                     console.error(chalk.red(error.message));
-                status = 'error';
-                errorMessage = error.message;
+                if (abortController.signal.aborted) {
+                    status = 'timeout';
+                    errorMessage = `task wall-clock timeout after ${taskTimeoutMs}ms`;
+                }
+                else {
+                    status = 'error';
+                    errorMessage = error.message;
+                }
                 active = false;
                 break;
             }
@@ -231,8 +269,14 @@ RULES OF ENGAGEMENT:
                 spinner.fail('Error during processing');
                 if (!this.jsonMode)
                     console.error(chalk.red(error.message));
-                status = 'error';
-                errorMessage = error.message;
+                if (abortController.signal.aborted) {
+                    status = 'timeout';
+                    errorMessage = `task wall-clock timeout after ${taskTimeoutMs}ms`;
+                }
+                else {
+                    status = 'error';
+                    errorMessage = error.message;
+                }
                 active = false;
                 break;
             }
@@ -308,6 +352,21 @@ RULES OF ENGAGEMENT:
                     const truncation = truncateOutput(toolResult);
                     const boundedResult = truncation.content;
                     const resultLines = boundedResult.split('\n');
+                    // Loop hygiene (idea from dsh repeat-tool-reminder): identical
+                    // consecutive calls get an escalating reminder so the model changes
+                    // approach early instead of burning turns until the step cap.
+                    const signature = `${functionName}:${canonicalArgs(functionArgs)}`;
+                    if (signature === lastToolSignature)
+                        consecutiveRepeats++;
+                    else {
+                        consecutiveRepeats = 1;
+                        lastToolSignature = signature;
+                    }
+                    const repeatSuffix = consecutiveRepeats < 3
+                        ? ''
+                        : consecutiveRepeats < 5
+                            ? `\n[AutoClaw] Note: this is the ${consecutiveRepeats}th identical ${functionName} call in a row. If it keeps returning the same result, change approach instead of repeating it.`
+                            : `\n[AutoClaw] You have now made the identical ${functionName} call ${consecutiveRepeats} times in a row (arguments: ${JSON.stringify(functionArgs).slice(0, 120)}). This exact call keeps returning the same result. Stop retrying it: change approach, fix the underlying problem, or finish the task with what you already have.`;
                     let outputFile = null;
                     if (resultLines.length > MAX_PREVIEW_LINES || truncation.truncated) {
                         outputFile = await this.saveOutput(functionName, toolResult);
@@ -340,7 +399,7 @@ RULES OF ENGAGEMENT:
                     this.messages.push({
                         role: "tool",
                         tool_call_id: toolCall.id,
-                        content: boundedResult
+                        content: boundedResult + repeatSuffix
                     });
                 }
             }
@@ -351,6 +410,8 @@ RULES OF ENGAGEMENT:
                 this.emitEvent({ event: 'usage', step, ...totalUsage });
             }
         }
+        if (abortTimer)
+            clearTimeout(abortTimer);
         const result = {
             status,
             steps: step,
@@ -358,9 +419,33 @@ RULES OF ENGAGEMENT:
             ...(errorMessage ? { error: errorMessage } : {}),
             ...(sawUsage ? { usage: totalUsage } : {})
         };
+        this.appendRunLog(userInput, result, startedAt);
         this.emitEvent({ event: 'run_end', ...result });
         return result;
     }
+    // Best-effort local run history: ~/.autoclaw/logs/runs.jsonl, one line
+    // per run, for post-hoc debugging of unattended batches. Logging must
+    // never fail a run.
+    appendRunLog(userInput, result, startedAt) {
+        try {
+            const dir = path.join(os.homedir(), '.autoclaw', 'logs');
+            fs.mkdirSync(dir, { recursive: true });
+            const line = JSON.stringify({
+                time: new Date().toISOString(),
+                model: this.model,
+                task: String(userInput).slice(0, 200),
+                status: result.status,
+                steps: result.steps,
+                ...(result.error ? { error: result.error.slice(0, 300) } : {}),
+                ...(result.usage ? { usage: result.usage } : {}),
+                durationMs: Date.now() - startedAt
+            });
+            fs.appendFileSync(path.join(dir, 'runs.jsonl'), line + '\n');
+        }
+        catch {
+            // ignore
+        }
+    }
     // Every turn resends the full history, so early large tool results
     // dominate context growth. Keep the most recent results intact and bound
     // older ones to a short excerpt (full output stays on disk via /view when

package/dist/batch.js

@@ -25,6 +25,8 @@ export function parseManifest(raw) {
         const entry = { lineNo, id, task: parsed.task.trim() };
         if (typeof parsed.maxSteps === 'number' && parsed.maxSteps > 0)
             entry.maxSteps = parsed.maxSteps;
+        if (typeof parsed.taskTimeoutMs === 'number' && parsed.taskTimeoutMs > 0)
+            entry.taskTimeoutMs = parsed.taskTimeoutMs;
         if (typeof parsed.model === 'string' && parsed.model.trim())
             entry.model = parsed.model.trim();
         if (typeof parsed.provider === 'string' && parsed.provider.trim())

package/dist/index.js

@@ -46,7 +46,7 @@ dotenv.config({ path: GLOBAL_ENV_FILE });
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // In dist/index.js, package.json is usually up one level in the root
 const pkgPath = path.join(__dirname, '..', 'package.json');
-let version = '1.3.3';
+let version = '1.3.5';
 try {
     const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
     version = pkg.version;
@@ -615,7 +615,8 @@ async function runBatchCommand(manifestPath, globalOptions, cmdOptions) {
             ...fullConfig,
             // The results file is the machine-readable contract in batch mode.
             jsonMode: false,
-            maxSteps: entry.maxSteps ?? fullConfig.maxSteps
+            maxSteps: entry.maxSteps ?? fullConfig.maxSteps,
+            taskTimeoutMs: entry.taskTimeoutMs ?? fullConfig.taskTimeoutMs
         };
         const agent = new Agent(apiKey, taskBaseURL, taskModel, taskConfig);
         const start = Date.now();
@@ -667,9 +668,9 @@ async function runChat(queryParts, options) {
         }
         const result = await agent.chat(initialQuery);
         // Headless mode exit — the exit code is the orchestrator-facing outcome:
-        // 0 completed, 1 hard failure, 2 step cap reached (task unfinished).
+        // 0 completed, 1 hard failure, 2 unfinished (step cap or wall-clock timeout).
         if (!options.interactive) {
-            process.exit(result.status === 'completed' ? 0 : result.status === 'max_steps' ? 2 : 1);
+            process.exit(result.status === 'completed' ? 0 : result.status === 'max_steps' || result.status === 'timeout' ? 2 : 1);
         }
     }
     // Main chat loop

package/dist/sandbox.js

@@ -0,0 +1,94 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { shellInvocation } from './shell.js';
+export function resolveSandboxMode(config) {
+    const requested = String(config?.sandbox || process.env.AUTOCLOW_SANDBOX || 'danger-full-access').toLowerCase();
+    if (requested === 'read-only' || requested === 'workspace-write' || requested === 'danger-full-access') {
+        return requested;
+    }
+    return 'danger-full-access';
+}
+export function sandboxBackend(platform = process.platform) {
+    if (platform === 'linux') {
+        const available = hasExecutable('bwrap');
+        return {
+            backend: 'bwrap',
+            available,
+            detail: available
+                ? 'bubblewrap found'
+                : 'bubblewrap (bwrap) not found — install it (e.g. apt install bubblewrap) or set sandbox to danger-full-access'
+        };
+    }
+    if (platform === 'darwin') {
+        const available = fs.existsSync('/usr/bin/sandbox-exec');
+        return {
+            backend: 'sandbox-exec',
+            available,
+            detail: available ? 'sandbox-exec found' : 'sandbox-exec missing (unexpected on macOS)'
+        };
+    }
+    return {
+        backend: 'none',
+        available: false,
+        detail: 'no sandbox backend on this platform yet (Windows restricted-token rung is planned). Set sandbox to danger-full-access to run unrestricted.'
+    };
+}
+function hasExecutable(name) {
+    for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+        try {
+            if (fs.existsSync(path.join(dir, name)))
+                return true;
+        }
+        catch {
+            // skip unreadable PATH entries
+        }
+    }
+    return false;
+}
+// Pure shape builder: wraps the platform shell invocation so the command can
+// only write where the mode allows. danger-full-access returns the command
+// unchanged; read-only/workspace-write require the platform backend, which
+// the caller checks with sandboxBackend() first (fail-closed otherwise).
+export function sandboxedInvocation(command, mode, workspace, platform = process.platform) {
+    const base = shellInvocation(command);
+    if (mode === 'danger-full-access')
+        return base;
+    if (platform === 'linux') {
+        if (mode === 'read-only') {
+            return {
+                file: 'bwrap',
+                args: ['--ro-bind', '/', '/', '--dev-bind', '/dev', '/dev', '--proc', '/proc', '--', base.file, ...base.args]
+            };
+        }
+        return {
+            file: 'bwrap',
+            args: [
+                '--ro-bind', '/', '/',
+                '--bind', workspace, workspace,
+                '--dev-bind', '/dev', '/dev',
+                '--proc', '/proc',
+                '--tmpfs', '/tmp',
+                '--', base.file, ...base.args
+            ]
+        };
+    }
+    if (platform === 'darwin') {
+        const ws = workspace.replace(/"/g, '\\"');
+        if (mode === 'read-only') {
+            return {
+                file: '/usr/bin/sandbox-exec',
+                args: ['-p', '(version 1)(allow default)(deny file-write*)', base.file, ...base.args]
+            };
+        }
+        return {
+            file: '/usr/bin/sandbox-exec',
+            args: [
+                '-p',
+                `(version 1)(allow default)(deny file-write*)(allow file-write* (subpath "${ws}") (subpath "/private/tmp") (regex #"^/private/var/folders/"))`,
+                base.file,
+                ...base.args
+            ]
+        };
+    }
+    return { blocked: true, detail: sandboxBackend(platform).detail };
+}

package/dist/shell.js

@@ -1,5 +1,6 @@
 import { spawn, execSync } from 'child_process';
 import * as fs from 'fs';
+import * as path from 'path';
 const GIT_BASH_CANDIDATES = [
     'C:\\Program Files\\Git\\bin\\bash.exe',
     'C:\\Program Files\\Git\\usr\\bin\\bash.exe',
@@ -7,6 +8,7 @@ const GIT_BASH_CANDIDATES = [
 ];
 let cachedType = null;
 let cachedBashPath;
+let cachedBashEnv = null;
 function findBashPath() {
     if (process.platform === 'win32') {
         for (const candidate of GIT_BASH_CANDIDATES) {
@@ -31,6 +33,26 @@ export function getBashPath() {
         cachedBashPath = findBashPath();
     return cachedBashPath;
 }
+// A login shell (-l) would source the profile to put Git's /usr/bin on
+// PATH, but that costs ~450ms per command. Prepending the directories to
+// the child PATH achieves the same tool resolution at spawn speed.
+export function spawnEnv() {
+    if (process.platform !== 'win32')
+        return process.env;
+    if (cachedBashEnv)
+        return cachedBashEnv;
+    const env = { ...process.env };
+    const bp = getBashPath();
+    if (bp) {
+        const usrBin = path.dirname(bp);
+        const gitRoot = path.resolve(usrBin, '..', '..');
+        const extra = [usrBin, path.join(gitRoot, 'mingw64', 'bin'), path.join(gitRoot, 'cmd')]
+            .filter(p => fs.existsSync(p));
+        env.PATH = `${extra.join(path.delimiter)}${path.delimiter}${env.PATH ?? ''}`;
+    }
+    cachedBashEnv = env;
+    return env;
+}
 export function resolveShellType(config) {
     const requested = String(config?.shell || process.env.AUTOCLOW_SHELL || 'auto').toLowerCase();
     if (requested === 'bash' || requested === 'powershell' || requested === 'cmd' || requested === 'sh') {
@@ -57,28 +79,42 @@ export function smartDecode(buf) {
         }
     }
 }
-export function execShellCommand(command, opts) {
+export function shellInvocation(command) {
     const type = resolveShellType();
-    let file;
-    let args;
     if (type === 'bash') {
-        // -l sources the profile so Git Bash's /usr/bin lands on PATH and Unix
-        // tools (ls, grep, ...) actually resolve.
-        file = getBashPath();
-        args = ['-l', '-c', command];
+        // --noprofile/--norc: profile loading costs ~450ms per command; PATH is
+        // handled by spawnEnv() instead.
+        return { file: getBashPath(), args: ['--noprofile', '--norc', '-c', command] };
     }
-    else if (type === 'powershell') {
-        file = 'powershell.exe';
-        args = ['-NoProfile', '-Command', command];
+    if (type === 'powershell') {
+        return { file: 'powershell.exe', args: ['-NoProfile', '-Command', command] };
     }
-    else if (type === 'cmd') {
-        file = process.env.ComSpec || 'cmd.exe';
-        args = ['/d', '/s', '/c', command];
+    if (type === 'cmd') {
+        return { file: process.env.ComSpec || 'cmd.exe', args: ['/d', '/s', '/c', command] };
     }
-    else {
-        file = '/bin/sh';
-        args = ['-c', command];
+    return { file: '/bin/sh', args: ['-c', command] };
+}
+export function killProcessTree(pid) {
+    if (process.platform !== 'win32') {
+        // The negative pid targets the detached process group.
+        try {
+            process.kill(-pid, 'SIGKILL');
+        }
+        catch {
+            try {
+                process.kill(pid, 'SIGKILL');
+            }
+            catch {
+                // already gone
+            }
+        }
+        return;
     }
+    spawn('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+}
+export function execShellCommand(command, opts) {
+    const type = resolveShellType();
+    const { file, args } = opts.sandboxed ?? shellInvocation(command);
     return new Promise(resolve => {
         const stdout = [];
         const stderr = [];
@@ -87,7 +123,7 @@ export function execShellCommand(command, opts) {
         let truncated = false;
         let settled = false;
         const posix = process.platform !== 'win32';
-        const child = spawn(file, args, { windowsHide: true, detached: posix });
+        const child = spawn(file, args, { windowsHide: true, detached: posix, env: spawnEnv() });
         const finish = () => {
             if (settled)
                 return;
@@ -101,21 +137,8 @@ export function execShellCommand(command, opts) {
             });
         };
         const killTree = () => {
-            if (!child.pid)
-                return;
-            if (posix) {
-                try {
-                    process.kill(-child.pid, 'SIGKILL');
-                }
-                catch {
-                    child.kill('SIGKILL');
-                }
-            }
-            else {
-                // Terminating the shell alone would orphan grandchildren, whose
-                // inherited stdio pipes keep 'close' pending — kill the whole tree.
-                spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
-            }
+            if (child.pid)
+                killProcessTree(child.pid);
         };
         const timer = setTimeout(() => {
             timedOut = true;

package/dist/tools/background.js

@@ -0,0 +1,165 @@
+import { spawn } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { killProcessTree, shellInvocation, spawnEnv } from '../shell.js';
+import { resolveSandboxMode, sandboxBackend, sandboxedInvocation } from '../sandbox.js';
+import { matchDangerousPattern } from './core.js';
+const handles = new Map();
+const MAX_TRACKED = 20;
+function newHandleId() {
+    return `bg-${Date.now().toString(36)}-${Math.floor(Math.random() * 1e6).toString(36)}`;
+}
+function tailOf(logPath, bytes = 4000) {
+    try {
+        if (!fs.existsSync(logPath))
+            return '(no output yet)';
+        const stat = fs.statSync(logPath);
+        const start = Math.max(0, stat.size - bytes);
+        const fd = fs.openSync(logPath, 'r');
+        try {
+            const buf = Buffer.alloc(stat.size - start);
+            fs.readSync(fd, buf, 0, buf.length, start);
+            return (start > 0 ? '…(earlier output omitted)\n' : '') + buf.toString('utf-8');
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch (err) {
+        return `(could not read log: ${err.message})`;
+    }
+}
+export const StartBackgroundProcessTool = {
+    name: "Background Process Starter",
+    definition: {
+        type: "function",
+        function: {
+            name: "start_background_process",
+            description: "Start a long-lived command in the background without blocking: dev servers, watchers, long builds. Output is written to a log file you can read later.",
+            parameters: {
+                type: "object",
+                properties: {
+                    command: { type: "string", description: "The command to run in the background." },
+                    rationale: { type: "string", description: "Explain why this command should run in the background." }
+                },
+                required: ["command", "rationale"]
+            }
+        }
+    },
+    handler: async (args, config) => {
+        const command = String(args.command ?? '').trim();
+        if (!command)
+            return 'Error: "command" is required.';
+        // Same safety gate as the foreground shell tool.
+        const gateLabel = matchDangerousPattern(command);
+        if (gateLabel) {
+            return `Error: command blocked by AutoClaw safety policy (matched: ${gateLabel}). It was NOT started. If this task genuinely requires it, restart AutoClaw with --allow-dangerous.`;
+        }
+        // Same sandbox policy as the foreground shell tool.
+        const sandboxMode = resolveSandboxMode(config);
+        let target = shellInvocation(command);
+        if (sandboxMode !== 'danger-full-access') {
+            const backend = sandboxBackend();
+            if (!backend.available) {
+                return `Error: sandbox mode "${sandboxMode}" is configured but no sandbox backend is available: ${backend.detail}`;
+            }
+            const inv = sandboxedInvocation(command, sandboxMode, process.cwd());
+            if ('blocked' in inv) {
+                return `Error: sandbox mode "${sandboxMode}" cannot wrap this command: ${inv.detail}`;
+            }
+            target = inv;
+        }
+        for (const [id, h] of handles) {
+            if (h.exited && Date.now() - h.startedAt > 3600_000)
+                handles.delete(id);
+        }
+        if (handles.size >= MAX_TRACKED) {
+            return `Error: too many tracked background processes (${MAX_TRACKED}). Stop finished ones first or wait for them to exit.`;
+        }
+        const id = newHandleId();
+        const logDir = path.join(os.homedir(), '.autoclaw', 'output');
+        fs.mkdirSync(logDir, { recursive: true });
+        const logPath = path.join(logDir, `bg-${id}.log`);
+        const { file: logFile, args: spawnArgs } = target;
+        const out = fs.openSync(logPath, 'a');
+        let child;
+        try {
+            child = spawn(logFile, spawnArgs, {
+                windowsHide: true,
+                detached: process.platform !== 'win32',
+                env: spawnEnv(),
+                stdio: ['ignore', out, out]
+            });
+        }
+        catch (err) {
+            fs.closeSync(out);
+            return `Error: failed to start background process: ${err.message}`;
+        }
+        fs.closeSync(out);
+        const entry = { id, pid: child.pid, command, logPath, startedAt: Date.now(), exited: false, exitCode: null };
+        handles.set(id, entry);
+        child.on('exit', code => { entry.exited = true; entry.exitCode = code ?? null; });
+        child.unref();
+        return `Background process started.\n- handle id: ${id}\n- pid: ${child.pid}\n- log: ${logPath}\nUse check_background_process with this id to read output, or stop_background_process to terminate it.`;
+    }
+};
+export const CheckBackgroundProcessTool = {
+    name: "Background Process Checker",
+    definition: {
+        type: "function",
+        function: {
+            name: "check_background_process",
+            description: "Check a background process started with start_background_process: running/exited status and the tail of its output log.",
+            parameters: {
+                type: "object",
+                properties: {
+                    id: { type: "string", description: "The handle id returned by start_background_process." }
+                },
+                required: ["id"]
+            }
+        }
+    },
+    handler: async (args) => {
+        const id = String(args.id ?? '');
+        const entry = handles.get(id);
+        if (!entry) {
+            return `Error: unknown background process id "${id}". Handles live for the current AutoClaw process only; the log file may still exist under ~/.autoclaw/output/.`;
+        }
+        const status = entry.exited
+            ? `exited (code: ${entry.exitCode ?? 'unknown'})`
+            : `running (pid: ${entry.pid}, ${Math.round((Date.now() - entry.startedAt) / 1000)}s elapsed)`;
+        return `Background process ${id}: ${status}\nCommand: ${entry.command}\nLog tail:\n${tailOf(entry.logPath)}`;
+    }
+};
+export const StopBackgroundProcessTool = {
+    name: "Background Process Stopper",
+    definition: {
+        type: "function",
+        function: {
+            name: "stop_background_process",
+            description: "Terminate a background process started with start_background_process (kills the whole process tree).",
+            parameters: {
+                type: "object",
+                properties: {
+                    id: { type: "string", description: "The handle id returned by start_background_process." }
+                },
+                required: ["id"]
+            }
+        }
+    },
+    handler: async (args) => {
+        const id = String(args.id ?? '');
+        const entry = handles.get(id);
+        if (!entry) {
+            return `Error: unknown background process id "${id}".`;
+        }
+        if (entry.exited) {
+            return `Background process ${id} already exited (code: ${entry.exitCode ?? 'unknown'}). Log: ${entry.logPath}`;
+        }
+        if (entry.pid)
+            killProcessTree(entry.pid);
+        entry.exited = true;
+        return `Background process ${id} terminated.\nLog: ${entry.logPath}\nLog tail:\n${tailOf(entry.logPath)}`;
+    }
+};