autoclaw 1.2.0 → 1.3.1

package/README.md

@@ -111,6 +111,25 @@ autoclaw "Deploy and report" -y -n --json
 ```
 Token usage is collected only when `AUTOCLOW_INCLUDE_USAGE=1` (or `true`) is set — it is opt-in because not every OpenAI-compatible provider accepts `stream_options.include_usage`.
 
+### Batch Mode (Swarm Worker)
+Feed a JSONL manifest of tasks; each task runs in a fresh, isolated agent (one task's context never leaks into another) and per-task results are written as JSONL:
+```bash
+autoclaw batch tasks.jsonl -y                          # results -> tasks.results.jsonl
+autoclaw batch tasks.jsonl -o out.jsonl --fail-fast
+```
+Manifest lines are `{"id": "...", "task": "..."}` — `id` is optional (defaults to `task-N`); blank lines and `#` comments are skipped. Optional per-task overrides: `maxSteps`, `model`, `provider`.
+
+One failing task does not stop the batch (use `--fail-fast` for that). The process exits `0` when every task completed, `1` otherwise, so cron and K8s Jobs can detect bad batches. Task output stays human-readable on stdout — the results file is the machine-readable contract, with `status`, `steps`, `message`, `error` and `usage` per task.
+
+Long batches can stop and pick up where they left off, and can use local parallelism:
+```bash
+autoclaw batch big.jsonl -y --resume        # skip tasks already completed in the results file
+autoclaw batch big.jsonl -y -c 4            # run up to 4 tasks in parallel
+```
+Unattempted tasks are simply absent from the results file, so `--fail-fast` followed by `--resume` is a natural retry loop.
+
+AutoClaw also keeps its own prompt lean: optional tools (web search, email, group notifications, image generation) only register once their credentials are configured, and in long loops older tool results in the model context are replaced by short excerpts.
+
 ### Auto-Confirm (CI/CD)
 Automatically approve all tool executions (dangerous, use with caution or in sandboxes).
 ```bash
@@ -148,6 +167,7 @@ AutoClaw uses a hierarchical configuration system.
 - `model`: Default model to use.
 - `maxSteps`: Max LLM turns per task before the agent stops (default: `25`).
 - `shellTimeout`: Shell command timeout in milliseconds (default: `120000`).
+- `shell`: Force a shell for `execute_shell_command` (`bash`, `powershell`, `cmd`, `sh`; default: auto-detect — Git Bash > PowerShell > cmd on Windows).
 - `tavilyApiKey`: API Key for Tavily Web Search.
 - `smtpHost`, `smtpPort`, `smtpUser`, `smtpPass`, `smtpFrom`: SMTP Email settings.
 - `feishuWebhook`, `dingtalkWebhook`, `wecomWebhook`: Notification webhooks.
@@ -167,6 +187,7 @@ Create a file at `.autoclaw/setting.json`:
 - `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_MODEL`: main LLM settings.
 - `AUTOCLOW_PROVIDER`: provider preset used when `-P` is not passed.
 - `AUTOCLOW_MAX_STEPS`, `AUTOCLOW_SHELL_TIMEOUT`: reliability limits (max LLM turns per task; shell timeout in ms).
+- `AUTOCLOW_SHELL`: force the shell for shell commands (`bash`, `powershell`, `cmd`, `sh`).
 - `AUTOCLOW_INCLUDE_USAGE`: set to `1`/`true` to request token usage from the API (opt-in).
 - `TAVILY_API_KEY`, `SMTP_HOST`/`SMTP_PORT`/`SMTP_USER`/`SMTP_PASS`, `FEISHU_WEBHOOK`/`FEISHU_KEYWORD`, `DINGTALK_WEBHOOK`/`DINGTALK_KEYWORD`, `WECOM_WEBHOOK`/`WECOM_KEYWORD`: tool credentials as an alternative to setup.
 

package/README.zh-CN.md

@@ -112,6 +112,25 @@ autoclaw "执行部署并汇报" -y -n --json
 ```
 Token 用量仅在设置 `AUTOCLOW_INCLUDE_USAGE=1`（或 `true`）时才收集——这是可选项，因为并非所有 OpenAI 兼容端点都接受 `stream_options.include_usage`。
 
+### 批处理模式 (蜂群工人)
+把 JSONL 任务清单交给 AutoClaw；每个任务在全新的隔离 Agent 中执行（任务之间上下文互不污染），结果逐行写入 JSONL 文件：
+```bash
+autoclaw batch tasks.jsonl -y                          # 结果 -> tasks.results.jsonl
+autoclaw batch tasks.jsonl -o out.jsonl --fail-fast
+```
+清单每行为 `{"id": "...", "task": "..."}`——`id` 可省略（默认 `task-N`）；空行和 `#` 注释行会跳过。可选的每任务覆盖项：`maxSteps`、`model`、`provider`。
+
+单个任务失败不会中断批次（需要中断用 `--fail-fast`）。全部完成时进程退出 `0`，否则 `1`，cron 和 K8s Job 由此感知批次成败。任务输出保持人类可读——结果文件才是机器可读契约，含每个任务的 `status`、`steps`、`message`、`error`、`usage`。
+
+长批次可以中途停、从断点继续，也可以本地并行：
+```bash
+autoclaw batch big.jsonl -y --resume        # 跳过结果文件中已完成的任务
+autoclaw batch big.jsonl -y -c 4            # 最多 4 个任务并行
+```
+未执行的任务不会出现在结果文件里，所以 `--fail-fast` 之后接 `--resume` 就是天然的重试循环。
+
+AutoClaw 同时会自动给提示词瘦身：可选工具（网页搜索、邮件、群通知、图像生成）只在凭据配置后才会注册进工具定义；长循环中较早的工具结果会被替换为短摘要。
+
 ### 自动确认 (CI/CD)
 自动批准所有工具执行（危险操作，请谨慎使用或在沙箱环境下运行）。
 ```bash
@@ -149,6 +168,7 @@ AutoClaw 使用层级配置系统。
 - `model`: 默认使用的模型。
 - `maxSteps`: 单任务最大 LLM 轮数，超出后自动停止 (默认: `25`)。
 - `shellTimeout`: Shell 命令超时时间（毫秒）(默认: `120000`)。
+- `shell`: 强制 `execute_shell_command` 使用的 shell (`bash`、`powershell`、`cmd`、`sh`；默认自动检测——Windows 上优先 Git Bash > PowerShell > cmd)。
 - `tavilyApiKey`: Tavily 网页搜索的 API 密钥。
 - `smtpHost`, `smtpPort`, `smtpUser`, `smtpPass`, `smtpFrom`: SMTP 邮件设置。
 - `feishuWebhook`, `dingtalkWebhook`, `wecomWebhook`: 通知钩子地址。
@@ -168,6 +188,7 @@ AutoClaw 使用层级配置系统。
 - `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_MODEL`: 主模型设置。
 - `AUTOCLOW_PROVIDER`: 未传 `-P` 时使用的 provider 预设。
 - `AUTOCLOW_MAX_STEPS`, `AUTOCLOW_SHELL_TIMEOUT`: 稳定性限制（单任务最大轮数；Shell 超时毫秒数）。
+- `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

@@ -5,10 +5,12 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as util from 'util';
-import { getToolDefinitions, executeToolHandler } from './tools/index.js';
+import { getToolDefinitions, executeToolHandler, listUnavailableTools } from './tools/index.js';
 import { withRetry } from './retry.js';
 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';
 export class Agent {
     client;
     messages;
@@ -22,9 +24,11 @@ export class Agent {
         });
         this.model = model;
         this.config = config;
+        const shellType = resolveShellType(config);
         const systemInfo = `
 System Information:
 - OS: ${os.type()} ${os.release()} (${os.platform()})
+- Shell: ${buildShellInfo(shellType)}
 - Architecture: ${os.arch()}
 - Node.js Version: ${process.version}
 - Current Working Directory: ${process.cwd()}
@@ -32,6 +36,27 @@ System Information:
 - Home Directory: ${os.homedir()}
 - Current Date: ${new Date().toLocaleString()}
 `;
+        const shellRule = shellType === 'cmd'
+            ? `\n8. Mind the shell noted above: on Windows it is cmd.exe, not bash — && only, no \$(...) substitution, no mkdir -p, GBK output possible; prefer powershell -Command "..." for system queries.`
+            : shellType === 'powershell'
+                ? `\n8. The shell is Windows PowerShell: use PowerShell syntax — \$( ) works, but && does not in Windows PowerShell 5; use ; or separate tool calls instead.`
+                : '';
+        // Every turn resends every tool definition, so unconfigured capabilities
+        // are dropped from both the tool array and this capability list.
+        const unavailable = listUnavailableTools(config);
+        const has = (tool) => !unavailable.includes(tool);
+        const capabilities = [
+            '- Shell: execute_shell_command — run scripts, install packages, manage processes, interact with the OS',
+            '- Files: read_file / write_file — inspect logs, generate configs, produce reports',
+            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('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,
+            has('optimize_prompt') ? '- Creation: optimize_prompt — refine raw prompts for creative/complex tasks (recommended before creative work)' : null,
+            '- Utility: get_current_datetime — accurate system time for temporal reasoning'
+        ].filter((line) => line !== null).join('\n');
         this.messages = [
             {
                 role: "system",
@@ -42,12 +67,7 @@ You may be running on a developer workstation, a headless server, inside a Docke
 ${systemInfo}
 
 WHAT YOU CAN DO:
-- Shell: execute_shell_command — run scripts, install packages, manage processes, interact with the OS
-- Files: read_file / write_file — inspect logs, generate configs, produce reports
-- Web: web_search — real-time information lookup; read_website — extract article content; take_screenshot — capture page visuals
-- Communication: send_email — SMTP email delivery; send_notification — push to Feishu/DingTalk/WeCom
-- Creation: generate_image — AI image generation (DALL-E compatible); optimize_prompt — refine raw prompts for creative/complex tasks
-- Utility: get_current_datetime — accurate system time for temporal reasoning
+${capabilities}
 
 RULES OF ENGAGEMENT:
 1. One shot, not one chat. Produce working results, not conversation. Be terse.
@@ -56,7 +76,7 @@ RULES OF ENGAGEMENT:
 4. Container-friendly: stick to standard Unix tools available in Alpine/Debian slim images. No GUI apps, no browser-based debug tools.
 5. For creative or complex tasks (image prompts, long-form writing, intricate scripts): call optimize_prompt first. It significantly raises output quality.
 6. If a command fails, diagnose and try one alternative. Don't retry the same thing, don't give up on first error.
-7. Read before write. When modifying a file, read it first. When installing a package, check if it's already there.
+7. Read before write. When modifying a file, read it first. When installing a package, check if it's already there.${shellRule}
 `
             }
         ];
@@ -100,6 +120,7 @@ RULES OF ENGAGEMENT:
                 }
                 break;
             }
+            this.trimOldToolResults();
             step++;
             const spinner = this.jsonMode
                 ? { stop() { }, fail() { }, text: '' }
@@ -340,6 +361,25 @@ RULES OF ENGAGEMENT:
         this.emitEvent({ event: 'run_end', ...result });
         return result;
     }
+    // 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
+    // it was large enough to be saved).
+    trimOldToolResults() {
+        const toolIndexes = [];
+        this.messages.forEach((m, i) => {
+            if (m.role === 'tool')
+                toolIndexes.push(i);
+        });
+        const cutoff = toolIndexes.length - 3;
+        for (let k = 0; k < cutoff; k++) {
+            const msg = this.messages[toolIndexes[k]];
+            if (typeof msg.content === 'string' && msg.content.length > 512 && !msg.content.includes(TOOL_RESULT_TRIM_MARKER)) {
+                const original = msg.content.length;
+                msg.content = `${msg.content.slice(0, 256)}\n[${TOOL_RESULT_TRIM_MARKER}: ${original} bytes total; re-run the tool if you need the full output again]`;
+            }
+        }
+    }
     async saveOutput(functionName, toolResult) {
         const outputDir = path.join(os.homedir(), '.autoclaw', 'output');
         if (!fs.existsSync(outputDir)) {

package/dist/batch.js

@@ -0,0 +1,84 @@
+// Blank lines and lines starting with '#' are skipped. Malformed lines are
+// kept as errored entries (in manifest order) rather than dropped, so the
+// result file accounts for every task the user submitted.
+export function parseManifest(raw) {
+    return raw
+        .split('\n')
+        .map((line, idx) => {
+        const lineNo = idx + 1;
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            return null;
+        let parsed = null;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            // fall through to the error entry below
+        }
+        const id = parsed && typeof parsed === 'object' && typeof parsed.id === 'string' && parsed.id.trim()
+            ? parsed.id.trim()
+            : `task-${lineNo}`;
+        if (!parsed || typeof parsed !== 'object' || typeof parsed.task !== 'string' || !parsed.task.trim()) {
+            return { lineNo, id, task: '', error: 'not valid JSON or missing "task" field' };
+        }
+        const entry = { lineNo, id, task: parsed.task.trim() };
+        if (typeof parsed.maxSteps === 'number' && parsed.maxSteps > 0)
+            entry.maxSteps = parsed.maxSteps;
+        if (typeof parsed.model === 'string' && parsed.model.trim())
+            entry.model = parsed.model.trim();
+        if (typeof parsed.provider === 'string' && parsed.provider.trim())
+            entry.provider = parsed.provider.trim();
+        return entry;
+    })
+        .filter((entry) => entry !== null);
+}
+export async function runBatch(entries, execute, options = {}) {
+    const total = entries.length;
+    const results = [];
+    let completed = 0;
+    let failed = 0;
+    let skipped = 0;
+    let stopped = false;
+    let done = 0;
+    const runEntry = async (i) => {
+        const entry = entries[i];
+        let result;
+        if (entry.error) {
+            result = { id: entry.id, status: 'error', error: `Manifest line ${entry.lineNo}: ${entry.error}`, durationMs: 0 };
+        }
+        else if (options.resume?.completedIds.has(entry.id)) {
+            result = options.resume.previousById.get(entry.id) ?? {
+                id: entry.id, status: 'error', error: 'missing previous result', durationMs: 0
+            };
+            skipped++;
+        }
+        else {
+            try {
+                result = await execute(entry);
+            }
+            catch (err) {
+                result = { id: entry.id, status: 'error', error: err?.message ?? String(err), durationMs: 0 };
+            }
+        }
+        if (result.status === 'completed')
+            completed++;
+        else
+            failed++;
+        results.push(result);
+        done++;
+        options.onResult?.(entry, result, done, total);
+        if (options.failFast && result.status !== 'completed')
+            stopped = true;
+    };
+    const concurrency = Math.max(1, Math.min(options.concurrency ?? 1, total || 1));
+    let next = 0;
+    const worker = async () => {
+        while (next < total && !stopped) {
+            const i = next++;
+            await runEntry(i);
+        }
+    };
+    await Promise.all(Array.from({ length: concurrency }, () => worker()));
+    return { results, completed, failed, skipped };
+}

package/dist/index.js

@@ -4,6 +4,7 @@ import inquirer from 'inquirer';
 import chalk from 'chalk';
 import dotenv from 'dotenv';
 import { Agent } from './agent.js';
+import { parseManifest, runBatch } from './batch.js';
 import { PROVIDER_PRESETS, providerNames, resolveProvider } from './providers.js';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -43,7 +44,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.2.0';
+let version = '1.3.1';
 try {
     const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
     version = pkg.version;
@@ -75,6 +76,17 @@ program
     const options = program.opts();
     await runChat(queryParts, options);
 });
+program
+    .command('batch <manifest>')
+    .description('Run tasks from a JSONL manifest, each in a fresh agent ({"id":"...","task":"..."})')
+    .option('-o, --output <file>', 'Per-task results as JSONL (default: <manifest base>.results.jsonl)')
+    .option('--fail-fast', 'Stop on the first failed task')
+    .option('--resume', 'Skip tasks already completed in the results file')
+    .option('-c, --concurrency <n>', 'Max tasks to run in parallel (default: 1)')
+    .action(async (manifest, cmdOptions) => {
+    const options = program.opts();
+    await runBatchCommand(manifest, options, cmdOptions);
+});
 program.parse(process.argv);
 async function runSetup(options = {}) {
     const isProject = options.project;
@@ -354,11 +366,9 @@ async function runSetup(options = {}) {
         console.error(chalk.red(`Failed to write config: ${error.message}`));
     }
 }
-async function runChat(queryParts, options) {
-    if (options.interactive) {
-        console.log(chalk.bold.cyan("Welcome to AutoClaw CLI 🦞"));
-    }
-    const initialQuery = queryParts.join(' ');
+// Shared by `chat` and `batch`: resolve credentials, endpoints and runtime
+// flags from CLI args > env > project config > global config > provider preset.
+async function resolveRuntime(options) {
     // 1. Load Global JSON
     const globalConfig = loadJsonConfig(GLOBAL_CONFIG_FILE);
     // 2. Load Local JSON (Project Level)
@@ -439,6 +449,104 @@ async function runChat(queryParts, options) {
         console.error(chalk.red("API Key is still missing. Exiting."));
         process.exit(1);
     }
+    return { apiKey, baseURL, model, fullConfig };
+}
+async function runBatchCommand(manifestPath, globalOptions, cmdOptions) {
+    const { apiKey, baseURL, model, fullConfig } = await resolveRuntime(globalOptions);
+    let raw;
+    try {
+        raw = fs.readFileSync(manifestPath, 'utf-8');
+    }
+    catch (err) {
+        console.error(chalk.red(`Cannot read manifest ${manifestPath}: ${err.message}`));
+        process.exit(1);
+    }
+    const entries = parseManifest(raw);
+    if (entries.length === 0) {
+        console.error(chalk.red(`Manifest ${manifestPath} contains no tasks (blank lines and '#' comments are skipped).`));
+        process.exit(1);
+    }
+    const outputPath = cmdOptions.output || manifestPath.replace(/\.[^.]+$/, '') + '.results.jsonl';
+    let resumeState;
+    if (cmdOptions.resume) {
+        const previousById = new Map();
+        const completedIds = new Set();
+        if (fs.existsSync(outputPath)) {
+            for (const line of fs.readFileSync(outputPath, 'utf-8').split('\n')) {
+                if (!line.trim())
+                    continue;
+                try {
+                    const r = JSON.parse(line);
+                    if (r?.id) {
+                        previousById.set(r.id, r);
+                        if (r.status === 'completed')
+                            completedIds.add(r.id);
+                    }
+                }
+                catch {
+                    // ignore malformed lines in the previous results file
+                }
+            }
+        }
+        else {
+            console.log(chalk.yellow(`--resume: no previous results at ${outputPath}; starting fresh.`));
+        }
+        resumeState = { completedIds, previousById };
+    }
+    const concurrency = Math.max(1, parseInt(cmdOptions.concurrency ?? '1', 10) || 1);
+    console.log(chalk.bold.cyan(`AutoClaw Batch 🦞  ${entries.length} task(s)${concurrency > 1 ? ` (concurrency ${concurrency})` : ''}${resumeState ? ' [resume]' : ''}`));
+    console.log(chalk.dim(`Results: ${outputPath}\n`));
+    const startedAt = Date.now();
+    const { results, completed, failed, skipped } = await runBatch(entries, async (entry) => {
+        // A fresh Agent per task keeps contexts isolated; per-task overrides
+        // beat the globally resolved defaults.
+        const taskPreset = resolveProvider(entry.provider);
+        const taskModel = entry.model || taskPreset?.defaultModel || model;
+        const taskBaseURL = taskPreset?.baseUrl || baseURL;
+        const taskConfig = {
+            ...fullConfig,
+            // The results file is the machine-readable contract in batch mode.
+            jsonMode: false,
+            maxSteps: entry.maxSteps ?? fullConfig.maxSteps
+        };
+        const agent = new Agent(apiKey, taskBaseURL, taskModel, taskConfig);
+        const start = Date.now();
+        const runResult = await agent.chat(entry.task);
+        return {
+            id: entry.id,
+            status: runResult.status,
+            steps: runResult.steps,
+            message: runResult.message ?? null,
+            ...(runResult.error ? { error: runResult.error } : {}),
+            ...(runResult.usage ? { usage: runResult.usage } : {}),
+            durationMs: Date.now() - start
+        };
+    }, {
+        failFast: !!cmdOptions.failFast,
+        concurrency,
+        resume: resumeState,
+        onResult: (entry, result, done, total) => {
+            const color = result.status === 'completed' ? chalk.green : chalk.red;
+            console.log(color(`[${done}/${total}] ${entry.id} -> ${result.status} (${Math.round(result.durationMs / 1000)}s)`));
+        }
+    });
+    try {
+        fs.writeFileSync(outputPath, results.map(r => JSON.stringify(r)).join('\n') + '\n', 'utf-8');
+    }
+    catch (err) {
+        console.error(chalk.red(`Failed to write results to ${outputPath}: ${err.message}`));
+        process.exit(1);
+    }
+    const skipNote = skipped > 0 ? `, ${skipped} skipped (resume)` : '';
+    console.log(chalk.cyan(`\nBatch done: ${completed}/${results.length + skipped} completed, ${failed} failed${skipNote} in ${Math.round((Date.now() - startedAt) / 1000)}s -> ${outputPath}`));
+    process.exit(failed > 0 ? 1 : 0);
+}
+async function runChat(queryParts, options) {
+    if (options.interactive) {
+        console.log(chalk.bold.cyan("Welcome to AutoClaw CLI 🦞"));
+    }
+    const initialQuery = queryParts.join(' ');
+    const { apiKey, baseURL, model, fullConfig } = await resolveRuntime(options);
     const agent = new Agent(apiKey, baseURL, model, fullConfig);
     if (options.interactive) {
         console.log(chalk.green(`Agent initialized with model: ${model}`));

package/dist/shell.js

@@ -0,0 +1,171 @@
+import { spawn, execSync } from 'child_process';
+import * as fs from 'fs';
+const GIT_BASH_CANDIDATES = [
+    'C:\\Program Files\\Git\\bin\\bash.exe',
+    'C:\\Program Files\\Git\\usr\\bin\\bash.exe',
+    'C:\\Program Files (x86)\\Git\\bin\\bash.exe'
+];
+let cachedType = null;
+let cachedBashPath;
+function findBashPath() {
+    if (process.platform === 'win32') {
+        for (const candidate of GIT_BASH_CANDIDATES) {
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+        try {
+            // 'where' may report WSL's System32\bash.exe, which has a different
+            // filesystem view — exclude it.
+            const out = execSync('where bash.exe', { stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+            const hit = out.split(/\r?\n/).map(l => l.trim()).find(l => l && !/System32/i.test(l));
+            return hit ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return fs.existsSync('/bin/bash') ? '/bin/bash' : null;
+}
+export function getBashPath() {
+    if (cachedBashPath === undefined)
+        cachedBashPath = findBashPath();
+    return cachedBashPath;
+}
+export function resolveShellType(config) {
+    const requested = String(config?.shell || process.env.AUTOCLOW_SHELL || 'auto').toLowerCase();
+    if (requested === 'bash' || requested === 'powershell' || requested === 'cmd' || requested === 'sh') {
+        if (requested !== 'bash' || getBashPath())
+            return requested;
+    }
+    if (!cachedType) {
+        cachedType = process.platform === 'win32' ? (getBashPath() ? 'bash' : 'powershell') : 'sh';
+    }
+    return cachedType;
+}
+// Windows tools emit GBK on CN-locale systems while Unix tools emit UTF-8;
+// strict UTF-8 decode with GBK fallback covers both.
+export function smartDecode(buf) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(buf);
+    }
+    catch {
+        try {
+            return new TextDecoder('gbk').decode(buf);
+        }
+        catch {
+            return buf.toString('utf8');
+        }
+    }
+}
+export function execShellCommand(command, opts) {
+    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];
+    }
+    else if (type === 'powershell') {
+        file = 'powershell.exe';
+        args = ['-NoProfile', '-Command', command];
+    }
+    else if (type === 'cmd') {
+        file = process.env.ComSpec || 'cmd.exe';
+        args = ['/d', '/s', '/c', command];
+    }
+    else {
+        file = '/bin/sh';
+        args = ['-c', command];
+    }
+    return new Promise(resolve => {
+        const stdout = [];
+        const stderr = [];
+        let total = 0;
+        let timedOut = false;
+        let truncated = false;
+        let settled = false;
+        const posix = process.platform !== 'win32';
+        const child = spawn(file, args, { windowsHide: true, detached: posix });
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({
+                stdout: smartDecode(Buffer.concat(stdout)),
+                stderr: smartDecode(Buffer.concat(stderr)),
+                timedOut,
+                truncated
+            });
+        };
+        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 });
+            }
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killTree();
+        }, Math.max(1, opts.timeoutMs));
+        const collect = (buf, chunk) => {
+            if (total >= opts.maxBuffer)
+                return;
+            total += chunk.length;
+            if (total > opts.maxBuffer) {
+                buf.push(chunk.subarray(0, chunk.length - (total - opts.maxBuffer)));
+                truncated = true;
+                killTree();
+            }
+            else {
+                buf.push(chunk);
+            }
+        };
+        child.stdout.on('data', c => collect(stdout, c));
+        child.stderr.on('data', c => collect(stderr, c));
+        child.on('error', err => {
+            stderr.push(Buffer.from(`\n[shell] failed to start ${type}: ${err.message}`));
+            finish();
+        });
+        child.on('exit', () => {
+            // The direct child is gone. Killed shells leave grandchildren holding
+            // stdio pipes, so don't wait for 'close' after a kill — return what we
+            // collected. On natural exit give the streams a short grace period
+            // before 'close' confirms the full flush.
+            if (timedOut || truncated) {
+                finish();
+            }
+            else {
+                const grace = setTimeout(finish, 1000);
+                if (typeof grace.unref === 'function')
+                    grace.unref();
+            }
+        });
+        child.on('close', finish);
+    });
+}
+export function buildShellInfo(type) {
+    switch (type) {
+        case 'bash':
+            return 'Bash (POSIX). Standard Unix tools, pipes and $() substitution work.';
+        case 'powershell':
+            return 'Windows PowerShell. Use PowerShell syntax: $() works, but && does not on Windows PowerShell 5 — use ; or separate calls. Prefer cmdlets like Get-ChildItem.';
+        case 'cmd':
+            return 'cmd.exe (Windows). Chain commands with && only, there is no $() command substitution, mkdir has no -p flag, and native tool output may be GBK-garbled. For system queries prefer: powershell -Command "..."';
+        default:
+            return 'POSIX shell (sh). Standard Unix tools apply.';
+    }
+}

package/dist/tools/browser.js

@@ -1,9 +1,20 @@
 import { chromium } from 'playwright';
 import { Readability } from '@mozilla/readability';
 import { JSDOM } from 'jsdom';
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
 export const BrowserTool = {
     name: "Web Browser",
     configKeys: [],
+    isAvailable: () => {
+        try {
+            require.resolve('playwright');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
     definition: {
         type: "function",
         function: {

package/dist/tools/core.js

@@ -1,10 +1,8 @@
-import { exec } from 'child_process';
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import inquirer from 'inquirer';
 import chalk from 'chalk';
-import util from 'util';
-const execAsync = util.promisify(exec);
+import { execShellCommand } from '../shell.js';
 const DEFAULT_SHELL_TIMEOUT_MS = 120000;
 const SHELL_MAX_BUFFER = 10 * 1024 * 1024;
 export const ShellTool = {
@@ -50,16 +48,15 @@ export const ShellTool = {
             console.log(chalk.gray("(Auto-confirming command execution due to --yes flag)"));
         }
         try {
-            const { stdout, stderr } = await execAsync(args.command, {
-                timeout: timeoutMs,
-                maxBuffer: SHELL_MAX_BUFFER
-            });
-            return stdout + (stderr ? `\nStderr: ${stderr}` : '');
+            const r = await execShellCommand(args.command, { timeoutMs, maxBuffer: SHELL_MAX_BUFFER });
+            if (r.timedOut) {
+                return `Command timed out after ${timeoutMs}ms and was terminated.\nStdout: ${r.stdout}\nStderr: ${r.stderr}`;
+            }
+            return (r.stdout +
+                (r.truncated ? '\n[AutoClaw] Output truncated at the buffer limit.' : '') +
+                (r.stderr ? `\nStderr: ${r.stderr}` : ''));
         }
         catch (error) {
-            if (error.killed === true || error.signal) {
-                return `Command timed out after ${timeoutMs}ms and was terminated.\nStdout: ${error.stdout ?? ''}\nStderr: ${error.stderr ?? ''}`;
-            }
             return `Command failed: ${error.message}\nStdout: ${error.stdout}\nStderr: ${error.stderr}`;
         }
     }

package/dist/tools/email.js

@@ -2,6 +2,7 @@ import nodemailer from 'nodemailer';
 export const EmailTool = {
     name: "Email Service",
     configKeys: ["smtpHost", "smtpPort", "smtpUser", "smtpPass", "smtpFrom"],
+    isAvailable: (config) => !!(config?.smtpHost && config?.smtpUser && config?.smtpPass),
     definition: {
         type: "function",
         function: {

package/dist/tools/image.js

@@ -251,6 +251,7 @@ const handler = async (args, config) => {
 };
 export const ImageTool = {
     name: "Image Generation",
+    isAvailable: (config) => !!(config?.imageApiKey || config?.apiKey || process.env.OPENAI_API_KEY),
     definition: toolDefinition,
     handler: handler
 };

package/dist/tools/index.js

@@ -20,8 +20,15 @@ export const toolRegistry = [
     ScreenshotTool,
     ImageTool
 ];
-export function getToolDefinitions() {
-    return toolRegistry.map(t => t.definition);
+export function getToolDefinitions(config) {
+    return toolRegistry
+        .filter(t => !t.isAvailable || t.isAvailable(config ?? {}))
+        .map(t => t.definition);
+}
+export function listUnavailableTools(config) {
+    return toolRegistry
+        .filter(t => t.isAvailable && !t.isAvailable(config ?? {}))
+        .map(t => t.definition.function.name);
 }
 export async function executeToolHandler(name, args, fullConfig) {
     const tool = toolRegistry.find(t => t.definition.function.name === name);

package/dist/tools/notify.js

@@ -5,6 +5,8 @@ export const NotifyTool = {
         "dingtalkWebhook", "dingtalkKeyword",
         "wecomWebhook", "wecomKeyword"
     ],
+    isAvailable: (config) => !!(config?.feishuWebhook || config?.dingtalkWebhook || config?.wecomWebhook ||
+        process.env.FEISHU_WEBHOOK || process.env.DINGTALK_WEBHOOK || process.env.WECOM_WEBHOOK),
     definition: {
         type: "function",
         function: {

package/dist/tools/prompt-optimizer.js

@@ -1,6 +1,7 @@
 import OpenAI from 'openai';
 export const PromptOptimizerTool = {
     name: "Prompt Optimizer",
+    isAvailable: (config) => !!(config?.apiKey || process.env.OPENAI_API_KEY),
     definition: {
         type: "function",
         function: {

package/dist/tools/screenshot.js

@@ -1,7 +1,9 @@
 import { chromium } from 'playwright';
+import { createRequire } from 'module';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as child_process from 'child_process';
+const require = createRequire(import.meta.url);
 // Helper to check for common CJK and Emoji font paths on Linux
 const checkLinuxFonts = () => {
     if (os.platform() !== 'linux')
@@ -77,6 +79,15 @@ const installFonts = (missing) => {
 export const ScreenshotTool = {
     name: "Screenshot Tool",
     configKeys: [],
+    isAvailable: () => {
+        try {
+            require.resolve('playwright');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
     definition: {
         type: "function",
         function: {

package/dist/tools/search.js

@@ -1,6 +1,7 @@
 export const SearchTool = {
     name: "Web Search (Tavily)",
     configKeys: ["tavilyApiKey"],
+    isAvailable: (config) => !!(config?.tavilyApiKey || process.env.TAVILY_API_KEY),
     definition: {
         type: "function",
         function: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autoclaw",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -12,6 +12,7 @@
     "dev": "node --loader ts-node/esm src/index.ts",
     "test": "vitest run",
     "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
     "prepublishOnly": "npm run build"
   },
   "files": [
@@ -65,6 +66,7 @@
     "@types/jsdom": "^27.0.0",
     "@types/node": "^25.2.1",
     "@types/nodemailer": "^7.0.9",
+    "@vitest/coverage-v8": "^4.1.11",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3",
     "vitest": "^4.1.4"