termux-dev 1.8.1 → 1.8.2

package/dist/core/background.js

@@ -0,0 +1,376 @@
+import { spawn } from 'child_process';
+import { EventEmitter } from 'events';
+import { StringDecoder } from 'string_decoder';
+export const MAX_BACKGROUND_TASKS = 8;
+/** What is kept of the output of one task; older text is dropped. */
+export const MAX_BUFFER = 200_000;
+/** The most a single read gives back to the model. */
+export const MAX_READ_CHARS = 8000;
+const MAX_NOTES_PER_TASK = 12;
+const NOTE_TAIL_CHARS = 1500;
+const MATCH_DEBOUNCE_MS = 400;
+/** Strips colour codes and carriage-return redraws so the model reads text, not terminal noise. */
+export function cleanOutput(text) {
+    return text
+        .replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, '')
+        .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '')
+        .replace(/[^\n]*\r(?!\n)/g, '')
+        .replace(/\r/g, '');
+}
+function compileRegex(source) {
+    if (!source)
+        return undefined;
+    try {
+        return new RegExp(source, 'i');
+    }
+    catch {
+        throw new Error(`Invalid regular expression: ${source}`);
+    }
+}
+export function formatDuration(ms) {
+    const s = Math.max(0, Math.round(ms / 1000));
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m ${String(s % 60).padStart(2, '0')}s`;
+    return `${Math.floor(m / 60)}h ${String(m % 60).padStart(2, '0')}m`;
+}
+export class BackgroundManager extends EventEmitter {
+    tasks = new Map();
+    counter = 0;
+    notes = [];
+    // ───────────────────────── starting and stopping ─────────────────────────
+    start(command, options = {}) {
+        if (!command || !command.trim())
+            throw new Error('command is required');
+        if (this.running().length >= MAX_BACKGROUND_TASKS) {
+            throw new Error(`Too many background tasks running (${MAX_BACKGROUND_TASKS}). Stop one first (action "stop").`);
+        }
+        const watch = compileRegex(options.notifyOn);
+        this.installExitHook();
+        const isWin = process.platform === 'win32';
+        const cwd = options.cwd || process.cwd();
+        const proc = spawn(command, { shell: true, cwd, detached: !isWin, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+        const id = `bg${++this.counter}`;
+        const info = {
+            id,
+            label: (options.label || command).replace(/\s+/g, ' ').trim().slice(0, 60),
+            command,
+            cwd,
+            pid: proc.pid,
+            status: 'running',
+            code: null,
+            startedAt: Date.now(),
+            outputChars: 0,
+            watching: options.notifyOn || undefined,
+        };
+        let finish;
+        const done = new Promise((resolve) => { finish = resolve; });
+        const task = {
+            info, proc, buffer: '', trimmed: 0, readCursor: 0, scanFrom: 0, pendingLine: '', watch,
+            notes: 0, matchedLines: [], stopRequested: false, timedOut: false, done,
+        };
+        this.tasks.set(id, task);
+        const decoders = { out: new StringDecoder('utf8'), err: new StringDecoder('utf8') };
+        proc.stdout.on('data', (d) => this.append(task, decoders.out.write(d)));
+        proc.stderr.on('data', (d) => this.append(task, decoders.err.write(d)));
+        let ended = false;
+        const end = (status, code) => {
+            if (ended)
+                return;
+            ended = true;
+            this.append(task, decoders.out.end() + decoders.err.end());
+            this.flushPendingLine(task);
+            clearTimeout(task.killTimer);
+            clearTimeout(task.runtimeTimer);
+            info.status = task.stopRequested ? 'stopped' : status;
+            info.code = code;
+            info.endedAt = Date.now();
+            this.flushMatches(task);
+            // A task the model stopped itself needs no note; anything else does.
+            if (!task.stopRequested || task.timedOut)
+                this.addNote(task, 'exit', this.exitNote(task));
+            this.emit('change', this.snapshot(task));
+            finish();
+        };
+        proc.on('error', () => end('failed', null));
+        proc.on('close', (code) => end(code === 0 ? 'exited' : 'failed', code));
+        // A child that got away can keep the pipes open for good: do not wait for them for long.
+        proc.on('exit', (code) => {
+            setTimeout(() => {
+                proc.stdout?.destroy();
+                proc.stderr?.destroy();
+                end(code === 0 ? 'exited' : 'failed', code);
+            }, 400).unref();
+        });
+        if (options.maxRuntimeSeconds && options.maxRuntimeSeconds > 0) {
+            task.runtimeTimer = setTimeout(() => { task.timedOut = true; void this.stop(id); }, options.maxRuntimeSeconds * 1000);
+            task.runtimeTimer.unref();
+        }
+        this.emit('change', this.snapshot(task));
+        return this.snapshot(task);
+    }
+    /** Stops a task (SIGTERM, then SIGKILL after a second). Resolves when it is gone. */
+    async stop(id) {
+        const task = this.must(id);
+        if (task.info.status !== 'running')
+            return this.snapshot(task);
+        task.stopRequested = true;
+        this.killTree(task, false);
+        task.killTimer = setTimeout(() => this.killTree(task, true), 1000);
+        task.killTimer.unref();
+        await Promise.race([task.done, new Promise((r) => setTimeout(r, 2500).unref())]);
+        return this.snapshot(task);
+    }
+    async stopAll() {
+        const running = this.running();
+        await Promise.all(running.map((t) => this.stop(t.id).catch(() => null)));
+        return running.length;
+    }
+    /** Forgets finished tasks (their output is gone with them). */
+    clearFinished() {
+        let n = 0;
+        for (const [id, task] of this.tasks) {
+            if (task.info.status !== 'running') {
+                this.tasks.delete(id);
+                n++;
+            }
+        }
+        if (n)
+            this.emit('change');
+        return n;
+    }
+    // ───────────────────────── looking at tasks ─────────────────────────
+    list() {
+        return [...this.tasks.values()].map((t) => this.snapshot(t));
+    }
+    running() {
+        return this.list().filter((t) => t.status === 'running');
+    }
+    get(id) {
+        const task = this.tasks.get(id);
+        return task ? this.snapshot(task) : undefined;
+    }
+    /** The output of a task as text for the model or the screen. */
+    read(id, options = {}) {
+        const task = this.must(id);
+        const grep = compileRegex(options.grep);
+        let from;
+        if (options.mode === 'tail')
+            from = task.trimmed;
+        else
+            from = Math.max(task.readCursor, task.trimmed);
+        let text = task.buffer.slice(from - task.trimmed);
+        if (options.mode !== 'tail')
+            task.readCursor = task.trimmed + task.buffer.length;
+        let lines = cleanOutput(text).split('\n');
+        if (lines.length && lines[lines.length - 1] === '')
+            lines.pop();
+        if (grep)
+            lines = lines.filter((l) => grep.test(l));
+        const want = Math.max(1, Math.min(Math.floor(options.lines ?? (options.mode === 'tail' ? 40 : 200)), 1000));
+        let omitted = 0;
+        if (lines.length > want) {
+            omitted = lines.length - want;
+            lines = lines.slice(-want);
+        }
+        text = lines.join('\n');
+        if (text.length > MAX_READ_CHARS) {
+            omitted += text.slice(0, text.length - MAX_READ_CHARS).split('\n').length - 1;
+            text = text.slice(-MAX_READ_CHARS).replace(/^[^\n]*\n/, '');
+        }
+        return { text, omitted };
+    }
+    /**
+     * Waits until the task ends, a line matches `pattern`, the time is up or the turn is cancelled.
+     * Lines the model has already read do not count; lines it has not read yet do.
+     */
+    wait(id, options = {}) {
+        const task = this.must(id);
+        const pattern = compileRegex(options.pattern);
+        const timeoutMs = Math.min(Math.max(options.timeoutSeconds ?? 60, 1), 600) * 1000;
+        return new Promise((resolve) => {
+            let timer;
+            // Output nobody has read yet counts: a line that came while the model was busy elsewhere is not lost.
+            let scan = Math.max(task.readCursor, task.trimmed);
+            const finish = (result) => {
+                clearTimeout(timer);
+                options.signal?.removeEventListener('abort', onAbort);
+                this.removeListener(`data:${id}`, onData);
+                resolve(result);
+            };
+            const onAbort = () => finish({ reason: 'aborted' });
+            const onClose = () => finish({ reason: 'exit' });
+            void task.done.then(onClose);
+            const onData = () => {
+                if (!pattern)
+                    return;
+                const start = Math.max(scan, task.trimmed);
+                const chunk = cleanOutput(task.buffer.slice(start - task.trimmed));
+                const lastNl = chunk.lastIndexOf('\n');
+                if (lastNl < 0)
+                    return;
+                scan = start + lastNl + 1;
+                const hit = chunk.slice(0, lastNl).split('\n').find((l) => pattern.test(l));
+                if (hit !== undefined)
+                    finish({ reason: 'match', line: hit.trim() });
+            };
+            if (task.info.status !== 'running')
+                return resolve({ reason: 'exit' });
+            if (options.signal?.aborted)
+                return resolve({ reason: 'aborted' });
+            timer = setTimeout(() => finish({ reason: 'timeout' }), timeoutMs);
+            options.signal?.addEventListener('abort', onAbort, { once: true });
+            this.on(`data:${id}`, onData);
+            onData();
+        });
+    }
+    // ───────────────────────── notes for the model ─────────────────────────
+    hasNotes() {
+        return this.notes.length > 0;
+    }
+    /** The notes since the last call, as one message for the model (or '' when there are none). */
+    takeNotes() {
+        if (this.notes.length === 0)
+            return '';
+        const text = this.notes.map((n) => n.text).join('\n\n');
+        this.notes = [];
+        return `[devx · background tasks]\n${text}`;
+    }
+    // ───────────────────────── internals ─────────────────────────
+    must(id) {
+        const task = this.tasks.get(String(id));
+        if (!task) {
+            const known = [...this.tasks.keys()].join(', ');
+            throw new Error(`No background task "${id}"${known ? ` (known: ${known})` : ' (none started)'}`);
+        }
+        return task;
+    }
+    snapshot(task) {
+        return { ...task.info, outputChars: task.trimmed + task.buffer.length };
+    }
+    append(task, text) {
+        if (!text)
+            return;
+        task.buffer += text;
+        if (task.buffer.length > MAX_BUFFER * 1.5) {
+            const cut = task.buffer.length - MAX_BUFFER;
+            task.buffer = task.buffer.slice(cut);
+            task.trimmed += cut;
+        }
+        if (task.watch)
+            this.scanLines(task, text);
+        this.emit(`data:${task.info.id}`);
+        this.emit('output', task.info.id);
+    }
+    scanLines(task, text) {
+        const parts = cleanOutput(task.pendingLine + text).split('\n');
+        task.pendingLine = parts.pop() ?? '';
+        for (const line of parts) {
+            if (task.watch.test(line))
+                this.matched(task, line);
+        }
+    }
+    flushPendingLine(task) {
+        if (task.watch && task.pendingLine && task.watch.test(task.pendingLine))
+            this.matched(task, task.pendingLine);
+        task.pendingLine = '';
+    }
+    matched(task, line) {
+        task.matchedLines.push(line.trim().slice(0, 300));
+        if (task.matchedLines.length > 20)
+            task.matchedLines.shift();
+        clearTimeout(task.matchTimer);
+        task.matchTimer = setTimeout(() => this.flushMatches(task), MATCH_DEBOUNCE_MS);
+        task.matchTimer.unref();
+    }
+    flushMatches(task) {
+        clearTimeout(task.matchTimer);
+        if (task.matchedLines.length === 0)
+            return;
+        const lines = task.matchedLines.splice(0);
+        const shown = lines.slice(-5).map((l) => `  ${l}`).join('\n');
+        this.addNote(task, 'match', {
+            summary: `${task.info.id} · ${lines[lines.length - 1]}`,
+            text: `${task.info.id} "${task.info.label}" printed ${lines.length} line${lines.length === 1 ? '' : 's'} matching /${task.info.watching}/:\n${shown}`,
+        });
+    }
+    exitNote(task) {
+        const { id, label, code, startedAt, endedAt } = task.info;
+        const how = task.timedOut ? 'was stopped: its time limit ran out' : code === 0 ? 'finished (exit code 0)' : code === null ? 'stopped unexpectedly' : `failed (exit code ${code})`;
+        const after = formatDuration((endedAt ?? Date.now()) - startedAt);
+        const tail = this.tailForNote(task);
+        return {
+            summary: `${id} ${code === 0 ? 'finished' : code === null ? 'stopped' : `failed · exit ${code}`} · ${after}`,
+            text: `${id} "${label}" ${how} after ${after}.${tail ? `\nLast output:\n${tail}` : ''}`,
+        };
+    }
+    tailForNote(task) {
+        const text = cleanOutput(task.buffer).trimEnd();
+        return text.length > NOTE_TAIL_CHARS ? '…' + text.slice(-NOTE_TAIL_CHARS).replace(/^[^\n]*\n/, '') : text;
+    }
+    addNote(task, kind, body) {
+        task.notes++;
+        // A chatty watcher must not flood the conversation: after a dozen notes only the end is reported.
+        if (kind === 'match' && task.notes > MAX_NOTES_PER_TASK)
+            return;
+        const note = { taskId: task.info.id, kind, ...body };
+        this.notes.push(note);
+        this.emit('note', note);
+    }
+    killTree(task, force) {
+        const pid = task.proc.pid;
+        if (!pid || task.info.status !== 'running')
+            return;
+        if (process.platform === 'win32') {
+            const killer = spawn('taskkill', ['/pid', String(pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' });
+            killer.on('error', () => task.proc.kill());
+            return;
+        }
+        try {
+            process.kill(-pid, force ? 'SIGKILL' : 'SIGTERM');
+        }
+        catch (err) {
+            if (err.code !== 'ESRCH') {
+                try {
+                    task.proc.kill(force ? 'SIGKILL' : 'SIGTERM');
+                }
+                catch { }
+            }
+        }
+    }
+    /** Nothing started by devx may outlive it. */
+    installExitHook() {
+        liveManagers.add(this);
+        if (exitHookInstalled)
+            return;
+        exitHookInstalled = true;
+        process.on('exit', () => {
+            for (const manager of liveManagers)
+                manager.killAllNow();
+        });
+    }
+    /** Synchronous: used when the process is exiting. */
+    killAllNow() {
+        for (const task of this.tasks.values()) {
+            if (task.info.status === 'running')
+                this.killTree(task, true);
+        }
+    }
+}
+const liveManagers = new Set();
+let exitHookInstalled = false;
+let instance = null;
+export function getBackgroundManager() {
+    if (!instance) {
+        instance = new BackgroundManager();
+        instance.setMaxListeners(50);
+    }
+    return instance;
+}
+/** For tests: a fresh manager. */
+export function resetBackgroundManager() {
+    void instance?.stopAll();
+    instance = null;
+}

package/dist/core/config-merge.js

@@ -0,0 +1,67 @@
+/**
+ * Saving the user's config when several devx processes run at once.
+ *
+ * Every process keeps its own copy of ~/.devxrc.json in memory. Writing that copy back whole would
+ * let the process that saves last overwrite what the others changed meanwhile (theme, API keys,
+ * "Always" permissions, the default model...). So a save writes only what THIS process changed
+ * since it last looked at the file (`base` -> `mine`) on top of what is on disk now (`disk`).
+ */
+const isPlain = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+function isPrimitiveList(v) {
+    return Array.isArray(v) && v.every((x) => x === null || ['string', 'number', 'boolean'].includes(typeof x));
+}
+/** Structural equality for JSON-like values. */
+export function sameValue(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b))
+        return a.length === b.length && a.every((x, i) => sameValue(x, b[i]));
+    if (isPlain(a) && isPlain(b)) {
+        const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+        for (const k of keys)
+            if (!sameValue(a[k], b[k]))
+                return false;
+        return true;
+    }
+    return false;
+}
+/** A deep copy that is safe to keep as a baseline. */
+export function cloneConfig(value) {
+    return value === undefined ? value : JSON.parse(JSON.stringify(value));
+}
+/**
+ * `disk` with the changes that `base` -> `mine` made applied to it.
+ *  - a value that did not change is left as it is on disk (another process may have changed it);
+ *  - objects (apiKeys, trustedProjects...) are merged key by key;
+ *  - lists of plain values (the bash allowlist) get what this process added and lose what it removed.
+ */
+export function mergeConfigChanges(base, mine, disk) {
+    const result = { ...disk };
+    const keys = new Set([...Object.keys(base), ...Object.keys(mine)]);
+    for (const key of keys) {
+        const b = base[key];
+        const m = mine[key];
+        if (sameValue(b, m))
+            continue;
+        if (m === undefined) {
+            delete result[key];
+        }
+        else if (isPlain(m) && (b === undefined || isPlain(b)) && (disk[key] === undefined || isPlain(disk[key]))) {
+            result[key] = mergeConfigChanges(isPlain(b) ? b : {}, m, isPlain(disk[key]) ? disk[key] : {});
+        }
+        else if (isPrimitiveList(m) && (b === undefined || isPrimitiveList(b)) && (disk[key] === undefined || isPrimitiveList(disk[key]))) {
+            const old = b ?? [];
+            const now = m;
+            const added = now.filter((x) => !old.includes(x));
+            const removed = old.filter((x) => !now.includes(x));
+            // Emptying a list ("/permissions clear") really empties it.
+            result[key] = m.length === 0
+                ? []
+                : [...new Set([...(disk[key] ?? []).filter((x) => !removed.includes(x)), ...added])];
+        }
+        else {
+            result[key] = m;
+        }
+    }
+    return result;
+}

package/dist/core/loop.js

@@ -32,6 +32,17 @@ export function getActionDescription(toolName, args) {
     if (t === 'bash' || t === 'execute_command' || t === 'run_command' || t === 'exec') {
         return `→ Run: ${args.command || args.cmd || ''}`;
     }
+    if (t === 'background') {
+        const id = args.id ? ` ${args.id}` : '';
+        switch (args.action) {
+            case 'start': return `→ Background: ${args.label ? `${args.label} · ` : ''}${args.command || ''}`;
+            case 'list': return `→ Background: list tasks`;
+            case 'output': return `→ Background: output${id}`;
+            case 'wait': return `→ Background: wait${id}${args.pattern ? ` for /${args.pattern}/` : ''}`;
+            case 'stop': return `→ Background: stop${id}`;
+            default: return `→ Background`;
+        }
+    }
     if (t === 'todo_list' || t === 'update_todos') {
         return `→ Update Plan & Tasks`;
     }
@@ -83,6 +94,12 @@ export class Agent {
                 this.history.addMessage(message);
                 yield { type: 'user_message', content: message.content };
             }
+            // A background task ended or printed what was asked for: the model learns it before it decides.
+            const news = hooks?.takeNotes?.();
+            if (news) {
+                this.history.addMessage({ role: 'user', content: news });
+                yield { type: 'background_note', content: news };
+            }
             const toolDefinitions = Array.from(this.tools.values()).map((t) => t.definition);
             // Tool schemas are sent with every request and count against the context window.
             const schemaTokens = toolSchemaTokens(toolDefinitions);
@@ -207,7 +224,7 @@ export class Agent {
             }
             if (!response.toolCalls || response.toolCalls.length === 0) {
                 // The user wrote something while the model was finishing: answer it instead of stopping.
-                if (hooks?.hasPending?.()) {
+                if (hooks?.hasPending?.() || hooks?.hasNotes?.()) {
                     iterations++;
                     continue;
                 }

package/dist/core/types.js

@@ -1 +1 @@
-export const DEVX_VERSION = '1.8.1';
+export const DEVX_VERSION = '1.8.2';

package/dist/permissions/guard.js

@@ -277,7 +277,7 @@ function hasComplexChainingOrRedirection(commandStr) {
         commandStr.includes('\r'));
 }
 // ───────────────────────── guard ─────────────────────────
-const SHELL_TOOLS = new Set(['bash', 'exec', 'run_command', 'execute_command']);
+const SHELL_TOOLS = new Set(['bash', 'background', 'exec', 'run_command', 'execute_command']);
 const READ_TOOLS = new Set(['read_file', 'view_file', 'read', 'list_dir', 'list_files', 'ls', 'search', 'grep_search', 'grep', 'diagnose_code']);
 const WRITE_TOOLS = new Set(['write_file', 'edit_file', 'make_dir', 'mkdir', 'create_file', 'write_to_file', 'patch']);
 function pathArg(args) {
@@ -409,6 +409,8 @@ export function buildPermissionRequest(toolName, args) {
             notes.push('looks destructive or runs downloaded code');
         else if (shellTouchesSecrets(cmd))
             notes.push('reads a credentials / secrets file: its content would reach the model');
+        if (t === 'background')
+            notes.push('keeps running in the background until it ends or you stop it');
         return { title: t === 'bash' ? 'bash' : toolName, danger, lines: cmd.split('\n'), notes };
     }
     if (t === 'mcp_manage') {

package/dist/prompts/builder.js

@@ -34,7 +34,8 @@ export async function buildSystemPrompt(planMode) {
         prompt += `- Before using tools on a task, say in one short line what you are about to do. Do not narrate every step.\n`;
         prompt += `- Do the whole task step by step. For a task with several steps, keep the checklist with 'todo_list'.\n`;
         prompt += `- Read a file before you edit it. Change only what the task needs, with 'edit_file' for small changes. Do not rewrite a whole file or touch unrelated code.\n`;
-        prompt += `- 'bash' stops after 120 s and cuts long output: give long jobs a timeout or run them in the background, and print only what you need (head, tail, grep).\n`;
+        prompt += `- 'bash' stops after 120 s and cuts long output: give a long job a timeout, and print only what you need (head, tail, grep).\n`;
+        prompt += `- Anything that keeps running (dev server, watcher, long test run or build) goes to the 'background' tool, not to 'bash': action 'start' returns at once and the work goes on while you continue. Set notify_on to a regex ('ready|listening|error|FAIL') to be told when such a line appears; you are always told when a task ends. Then do other work or finish your answer: do not poll. To wait for a line use action 'wait' with a pattern, to read output use 'output', to end it use 'stop'. The user sees the tasks under /tasks. Never start the same server twice: check 'list' first.\n`;
         prompt += `- After you change code, run 'diagnose_code' and fix what it reports. Install missing dependencies with 'install_package'.\n`;
         prompt += `- After you create or change a web page or frontend app, start the local preview with 'serve_preview' (action 'start').\n`;
         if (MemoryManager.enabled)

package/dist/tools/background.js

@@ -0,0 +1,118 @@
+import { MAX_BACKGROUND_TASKS, formatDuration, getBackgroundManager } from '../core/background.js';
+const ACTIONS = ['start', 'list', 'output', 'wait', 'stop'];
+/** One line per task: `bg1 running 2m 03s  npm run dev`. */
+export function describeTask(info, now = Date.now()) {
+    const age = formatDuration((info.endedAt ?? now) - info.startedAt);
+    const state = info.status === 'running' ? 'running'
+        : info.status === 'stopped' ? 'stopped'
+            : info.status === 'exited' ? 'finished (exit 0)'
+                : `failed (exit ${info.code ?? '?'})`;
+    const watch = info.watching && info.status === 'running' ? `  [watching /${info.watching}/]` : '';
+    return `${info.id}  ${state}  ${age}  ${info.label}${watch}`;
+}
+function outputBlock(text, omitted) {
+    if (!text)
+        return '(no output)';
+    return (omitted > 0 ? `[... ${omitted} earlier line${omitted === 1 ? '' : 's'} left out ...]\n` : '') + text;
+}
+export const backgroundTool = {
+    name: 'background',
+    definition: {
+        name: 'background',
+        description: 'Run a long-lived command in the background and keep working: dev servers, file watchers, long builds or test runs. ' +
+            'Do NOT use it for commands that finish quickly (use bash). Actions: ' +
+            '"start" (command, optional label, notify_on, max_runtime_seconds) launches it and returns its id and first output; ' +
+            '"list" shows all tasks; ' +
+            '"output" (id) reads what the task printed since the last read (mode "tail" gives the last lines instead; "grep" filters lines); ' +
+            '"wait" (id, optional pattern, timeout_seconds) blocks until the task ends, a line matches the regex, or the time is up; ' +
+            '"stop" (id) ends the task. ' +
+            'Set "notify_on" (a regex such as "ready|listening|error|FAIL") to be told when such a line appears, and you are always told when a task ends: ' +
+            'then you do not need to poll. Never poll in a loop; wait with a pattern instead. ' +
+            `At most ${MAX_BACKGROUND_TASKS} tasks run at once, and all of them are stopped when devx exits.`,
+        parameters: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: [...ACTIONS], description: 'What to do' },
+                command: { type: 'string', description: 'start: the shell command' },
+                label: { type: 'string', description: 'start: a short name shown to the user, e.g. "dev server"' },
+                notify_on: { type: 'string', description: 'start: regex; a matching output line is reported to you' },
+                max_runtime_seconds: { type: 'number', description: 'start: stop the task after this many seconds (default: no limit)' },
+                id: { type: 'string', description: 'output / wait / stop: the task id (bg1, bg2, ...)' },
+                mode: { type: 'string', enum: ['new', 'tail'], description: 'output: "new" (default) = since the last read, "tail" = last lines' },
+                lines: { type: 'number', description: 'output: how many lines at most (default 200 for new, 40 for tail)' },
+                grep: { type: 'string', description: 'output: only lines that match this regex' },
+                pattern: { type: 'string', description: 'wait: regex of an output line to wait for (default: wait for the end)' },
+                timeout_seconds: { type: 'number', description: 'wait: give up after this long (default 60, max 600)' },
+            },
+            required: ['action'],
+        },
+    },
+    validateArgs(args) {
+        if (!args || !ACTIONS.includes(args.action))
+            throw new Error(`action must be one of: ${ACTIONS.join(', ')}`);
+        if (args.action === 'start' && (!args.command || typeof args.command !== 'string'))
+            throw new Error('command is required for "start"');
+        if (['output', 'wait', 'stop'].includes(args.action) && !args.id)
+            throw new Error(`id is required for "${args.action}" (see action "list")`);
+    },
+    async execute(args, _config, context) {
+        const manager = getBackgroundManager();
+        const action = args.action;
+        try {
+            if (action === 'start') {
+                const info = manager.start(args.command, {
+                    label: args.label,
+                    notifyOn: args.notify_on,
+                    maxRuntimeSeconds: Number(args.max_runtime_seconds) || 0,
+                });
+                // Give it a moment: a command that dies at once (wrong script, busy port) should be seen now.
+                const first = await manager.wait(info.id, { timeoutSeconds: 1.5, signal: context?.signal });
+                const now = manager.get(info.id);
+                const out = manager.read(info.id, { mode: 'new', lines: 30 });
+                const head = now.status === 'running'
+                    ? `Started ${now.id} (pid ${now.pid ?? '?'}): ${now.label}. It runs in the background.`
+                    : `${describeTask(now)} - it ended right after the start.`;
+                const hint = now.status === 'running'
+                    ? '\nYou will be told when it ends' + (now.watching ? ' or prints a line matching the pattern' : '') + '. Use "output" to read more, "wait" to wait for a line.'
+                    : '';
+                return `${head}${hint}\n${outputBlock(out.text, out.omitted)}${first.reason === 'aborted' ? '\n[Operation cancelled by user]' : ''}`;
+            }
+            if (action === 'list') {
+                const tasks = manager.list();
+                return tasks.length === 0 ? 'No background tasks.' : tasks.map((t) => describeTask(t)).join('\n');
+            }
+            if (action === 'output') {
+                const info = manager.get(String(args.id));
+                const out = manager.read(String(args.id), {
+                    mode: args.mode === 'tail' ? 'tail' : 'new',
+                    lines: args.lines,
+                    grep: args.grep,
+                });
+                return `${info ? describeTask(info) : args.id}\n${outputBlock(out.text, out.omitted)}`;
+            }
+            if (action === 'wait') {
+                const result = await manager.wait(String(args.id), {
+                    pattern: args.pattern,
+                    timeoutSeconds: Number(args.timeout_seconds) || 60,
+                    signal: context?.signal,
+                });
+                const info = manager.get(String(args.id));
+                const out = manager.read(String(args.id), { mode: 'new', lines: 60 });
+                const why = result.reason === 'match' ? `A line matched: ${result.line}`
+                    : result.reason === 'exit' ? 'The task has ended.'
+                        : result.reason === 'timeout' ? 'Timed out; the task is still running.'
+                            : '[Operation cancelled by user]';
+                return `${why}\n${describeTask(info)}\n${outputBlock(out.text, out.omitted)}`;
+            }
+            // stop
+            const before = manager.get(String(args.id));
+            if (before && before.status !== 'running')
+                return `${describeTask(before)} (already ended)`;
+            const info = await manager.stop(String(args.id));
+            return `Stopped. ${describeTask(info)}`;
+        }
+        catch (err) {
+            return `Error: ${err.message}`;
+        }
+    },
+};