termux-dev 1.6.0 → 1.8.1

package/dist/tools/bash.js

@@ -1,13 +1,144 @@
 import { spawn } from 'child_process';
+import { StringDecoder } from 'string_decoder';
+export const DEFAULT_TIMEOUT_SECONDS = 120;
+export const MAX_TIMEOUT_SECONDS = 1800;
+// Output is kept as "head + tail": build/test tools print their summary and
+// their errors at the very end, so the tail must never be the part we drop.
+const HEAD_CHARS = 6000;
+const TAIL_CHARS = 14000;
+class OutputBuffer {
+    head = '';
+    tail = '';
+    dropped = 0;
+    push(text) {
+        if (this.head.length < HEAD_CHARS) {
+            const room = HEAD_CHARS - this.head.length;
+            this.head += text.slice(0, room);
+            text = text.slice(room);
+        }
+        if (!text)
+            return;
+        this.tail += text;
+        // Trim lazily (at 2x) so a chatty command does not cause a slice per chunk.
+        if (this.tail.length > TAIL_CHARS * 2) {
+            const cut = this.tail.length - TAIL_CHARS;
+            this.dropped += cut;
+            this.tail = this.tail.slice(cut);
+        }
+    }
+    toString() {
+        let tail = this.tail;
+        let dropped = this.dropped;
+        if (tail.length > TAIL_CHARS) {
+            dropped += tail.length - TAIL_CHARS;
+            tail = tail.slice(tail.length - TAIL_CHARS);
+        }
+        if (dropped === 0)
+            return this.head + tail;
+        return `${this.head}\n[... ${dropped} characters omitted ...]\n${tail}`;
+    }
+}
+export function normalizeTimeout(value) {
+    const n = typeof value === 'string' ? Number(value) : value;
+    if (typeof n !== 'number' || !Number.isFinite(n) || n <= 0)
+        return DEFAULT_TIMEOUT_SECONDS;
+    return Math.min(Math.max(n, 1), MAX_TIMEOUT_SECONDS);
+}
+/**
+ * Runs a shell command, killing the whole process tree on cancel / timeout.
+ * stdin is closed so commands that wait for input fail fast instead of hanging.
+ */
+export function runShell(command, options = {}) {
+    const { signal } = options;
+    const timeoutSeconds = normalizeTimeout(options.timeoutSeconds);
+    return new Promise((resolve, reject) => {
+        const isWin = process.platform === 'win32';
+        const proc = spawn(command, {
+            shell: true,
+            detached: !isWin,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const output = new OutputBuffer();
+        const stdoutDecoder = new StringDecoder('utf8');
+        const stderrDecoder = new StringDecoder('utf8');
+        let stopReason = '';
+        let killTimer;
+        const killProcessTree = (force) => {
+            if (!proc.pid)
+                return;
+            if (isWin) {
+                // Killing the shell alone leaves its child commands running on Windows.
+                const killer = spawn('taskkill', ['/pid', String(proc.pid), '/T', '/F'], {
+                    windowsHide: true,
+                    stdio: 'ignore',
+                });
+                killer.on('error', () => proc.kill());
+                return;
+            }
+            try {
+                process.kill(-proc.pid, force ? 'SIGKILL' : 'SIGTERM');
+            }
+            catch (err) {
+                if (err.code !== 'ESRCH')
+                    proc.kill(force ? 'SIGKILL' : 'SIGTERM');
+            }
+        };
+        const stop = (reason) => {
+            if (stopReason)
+                return;
+            stopReason = reason;
+            killProcessTree(false);
+            // Commands can ignore SIGTERM. Do not leave them running after cancellation.
+            killTimer = setTimeout(() => killProcessTree(true), 1000);
+        };
+        const onAbort = () => stop('[Operation cancelled by user]');
+        const timeout = setTimeout(() => stop(`[Process killed due to timeout after ${timeoutSeconds}s. ` +
+            `Pass a larger "timeout_seconds" (max ${MAX_TIMEOUT_SECONDS}) for long-running commands.]`), timeoutSeconds * 1000);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (signal?.aborted)
+            onAbort();
+        proc.stdout.on('data', (data) => {
+            if (!stopReason)
+                output.push(stdoutDecoder.write(data));
+        });
+        proc.stderr.on('data', (data) => {
+            if (!stopReason)
+                output.push(stderrDecoder.write(data));
+        });
+        const cleanup = () => {
+            clearTimeout(timeout);
+            clearTimeout(killTimer);
+            signal?.removeEventListener('abort', onAbort);
+        };
+        proc.on('close', (code) => {
+            if (stopReason)
+                killProcessTree(true);
+            output.push(stdoutDecoder.end() + stderrDecoder.end());
+            cleanup();
+            resolve({ output: output.toString(), code, stopReason });
+        });
+        proc.on('error', (err) => {
+            cleanup();
+            reject(new Error(`Failed to start process: ${err.message}`));
+        });
+    });
+}
 export const bashTool = {
     name: 'bash',
     definition: {
         name: 'bash',
-        description: 'Execute a bash command',
+        description: `Execute a bash command. stdin is closed (no interactive input). ` +
+            `Commands are stopped after ${DEFAULT_TIMEOUT_SECONDS}s by default; ` +
+            `for long builds/installs pass "timeout_seconds" (max ${MAX_TIMEOUT_SECONDS}). ` +
+            `Very long output is shortened in the middle, the end is always kept.`,
         parameters: {
             type: 'object',
             properties: {
-                command: { type: 'string' }
+                command: { type: 'string' },
+                timeout_seconds: {
+                    type: 'number',
+                    description: `Optional time limit in seconds (default ${DEFAULT_TIMEOUT_SECONDS}, max ${MAX_TIMEOUT_SECONDS})`,
+                },
             },
             required: ['command']
         }
@@ -16,55 +147,14 @@ export const bashTool = {
         if (!args.command || typeof args.command !== 'string')
             throw new Error('command is required');
     },
-    async execute(args) {
-        return new Promise((resolve, reject) => {
-            const isWin = process.platform === 'win32';
-            const proc = spawn(args.command, { shell: true, detached: !isWin });
-            let output = '';
-            let isTruncated = false;
-            const killProc = () => {
-                try {
-                    if (!isWin && proc.pid) {
-                        process.kill(-proc.pid, 'SIGTERM');
-                    }
-                    else {
-                        proc.kill();
-                    }
-                }
-                catch { }
-            };
-            const timeout = setTimeout(() => {
-                killProc();
-                resolve(output + '\n[Process killed due to timeout]');
-            }, 30000);
-            proc.stdout.on('data', (data) => {
-                if (isTruncated)
-                    return;
-                output += data.toString();
-                if (output.length > 20000) {
-                    isTruncated = true;
-                    output = output.substring(0, 20000) + '\n[Output truncated]';
-                    killProc();
-                }
-            });
-            proc.stderr.on('data', (data) => {
-                if (isTruncated)
-                    return;
-                output += data.toString();
-                if (output.length > 20000) {
-                    isTruncated = true;
-                    output = output.substring(0, 20000) + '\n[Output truncated]';
-                    killProc();
-                }
-            });
-            proc.on('close', (code) => {
-                clearTimeout(timeout);
-                resolve(`${output}\n[Exit code: ${code}]`);
-            });
-            proc.on('error', (err) => {
-                clearTimeout(timeout);
-                reject(new Error(`Failed to start process: ${err.message}`));
-            });
+    async execute(args, _config, context) {
+        const signal = context?.signal;
+        if (signal?.aborted)
+            return '[Operation cancelled by user]';
+        const { output, code, stopReason } = await runShell(args.command, {
+            signal,
+            timeoutSeconds: args.timeout_seconds,
         });
+        return `${output}\n${stopReason || `[Exit code: ${code}]`}`;
     }
 };

package/dist/tools/diagnostics.js

@@ -1,5 +1,57 @@
-import { exec } from 'child_process';
 import fsSync from 'fs';
+import path from 'path';
+import { runShell } from './bash.js';
+const DIAGNOSE_TIMEOUT_SECONDS = 180;
+// The file name ends up inside a quoted shell argument, so only plain path
+// characters are accepted. Anything else (quotes, $, `, ;, &, |, <, >, %, ^,
+// newlines, backslashes...) is rejected instead of being escaped.
+const SAFE_PATH = /^[\w\-./@+ ]+$/;
+/**
+ * Validates the user/model supplied file and returns a cwd-relative POSIX path.
+ * Throws if it is unsafe to place on a command line or escapes the project.
+ */
+export function resolveDiagnoseFile(file) {
+    const cwd = process.cwd();
+    const absolute = path.resolve(cwd, file);
+    const rel = path.relative(cwd, absolute);
+    if (!rel || rel === '..' || rel.startsWith('..' + path.sep) || path.isAbsolute(rel)) {
+        throw new Error(`File must be inside the project directory: ${file}`);
+    }
+    const posix = rel.split(path.sep).join('/');
+    if (posix.startsWith('-')) {
+        throw new Error(`Invalid file name: ${file}`);
+    }
+    if (!SAFE_PATH.test(posix)) {
+        throw new Error(`Invalid file name (unsupported characters): ${file}`);
+    }
+    if (!fsSync.existsSync(absolute)) {
+        throw new Error(`File not found: ${file}`);
+    }
+    return posix;
+}
+function pickCommand(file) {
+    if (file) {
+        const quoted = `"${file}"`;
+        if (file.endsWith('.ts') || file.endsWith('.tsx')) {
+            if (fsSync.existsSync('tsconfig.json'))
+                return 'npx --no-install tsc --noEmit';
+            return 'echo "node --check does not work for TypeScript. Please use tsc or tsx."';
+        }
+        if (file.endsWith('.js') || file.endsWith('.mjs') || file.endsWith('.cjs'))
+            return `node --check ${quoted}`;
+        if (file.endsWith('.py'))
+            return `python -m py_compile ${quoted}`;
+        if (file.endsWith('.rs'))
+            return 'cargo check';
+    }
+    if (fsSync.existsSync('tsconfig.json'))
+        return 'npx --no-install tsc --noEmit';
+    if (fsSync.existsSync('Cargo.toml'))
+        return 'cargo check';
+    if (fsSync.existsSync('package.json'))
+        return 'npm test -- --passWithNoTests';
+    return null;
+}
 export const diagnoseCodeTool = {
     name: 'diagnose_code',
     definition: {
@@ -12,53 +64,29 @@ export const diagnoseCodeTool = {
             }
         }
     },
-    validateArgs() { },
-    async execute(args) {
-        return new Promise((resolve) => {
-            let cmd = '';
-            if (args.file) {
-                const quotedFile = `"${args.file}"`;
-                if (args.file.endsWith('.ts') || args.file.endsWith('.tsx')) {
-                    if (fsSync.existsSync('tsconfig.json')) {
-                        cmd = 'npx tsc --noEmit';
-                    }
-                    else {
-                        cmd = `echo "node --check does not work for TypeScript. Please use tsc or tsx."`;
-                    }
-                }
-                else if (args.file.endsWith('.js') || args.file.endsWith('.mjs') || args.file.endsWith('.cjs')) {
-                    cmd = `node --check ${quotedFile}`;
-                }
-                else if (args.file.endsWith('.py')) {
-                    cmd = `python -m py_compile ${quotedFile}`;
-                }
-                else if (args.file.endsWith('.rs')) {
-                    cmd = 'cargo check';
-                }
-            }
-            if (!cmd) {
-                if (fsSync.existsSync('tsconfig.json')) {
-                    cmd = 'npx tsc --noEmit';
-                }
-                else if (fsSync.existsSync('Cargo.toml')) {
-                    cmd = 'cargo check';
-                }
-                else if (fsSync.existsSync('package.json')) {
-                    cmd = 'npm test -- --passWithNoTests';
-                }
-                else {
-                    return resolve('No automated checker found for this workspace. Manual review looks good.');
-                }
-            }
-            exec(cmd, (err, stdout, stderr) => {
-                const out = (stdout + '\n' + stderr).trim();
-                if (!err) {
-                    resolve('✅ Diagnostics passed with 0 errors! Code is clean and valid.');
-                }
-                else {
-                    resolve(`❌ Diagnostic errors found:\n${out.slice(0, 3000)}`);
-                }
-            });
+    validateArgs(args) {
+        if (args?.file !== undefined && args.file !== null && args.file !== '') {
+            if (typeof args.file !== 'string')
+                throw new Error('file must be a string');
+            resolveDiagnoseFile(args.file);
+        }
+    },
+    async execute(args, _config, context) {
+        const file = args?.file ? resolveDiagnoseFile(args.file) : undefined;
+        const cmd = pickCommand(file);
+        if (!cmd) {
+            return 'No automated checker found for this workspace. Manual review looks good.';
+        }
+        const { output, code, stopReason } = await runShell(cmd, {
+            signal: context?.signal,
+            timeoutSeconds: DIAGNOSE_TIMEOUT_SECONDS,
         });
+        if (stopReason) {
+            return `Diagnostics did not finish: ${stopReason}\n${output.trim().slice(-3000)}`;
+        }
+        if (code === 0) {
+            return 'Diagnostics passed with 0 errors. Code is clean and valid.';
+        }
+        return `Diagnostic errors found:\n${output.trim().slice(-3000)}`;
     }
 };

package/dist/tools/fs.js

@@ -1,15 +1,30 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { globalSnapshotManager } from '../core/snapshot.js';
+// A single read result lands in the model context, so it must stay bounded.
+export const MAX_READ_CHARS = 60000;
+const MAX_READ_FILE_BYTES = 10 * 1024 * 1024;
+function toLineNumber(value, name) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    const n = typeof value === 'string' ? Number(value) : value;
+    if (typeof n !== 'number' || !Number.isInteger(n) || n < 1) {
+        throw new Error(`${name} must be a positive integer`);
+    }
+    return n;
+}
 export const readFileTool = {
     name: 'read_file',
     definition: {
         name: 'read_file',
-        description: 'Read contents of a file',
+        description: `Read contents of a file. Large files are returned in parts (max ~${MAX_READ_CHARS} characters per call): ` +
+            'use startLine/endLine (1-based, inclusive) to read a specific range or to continue reading.',
         parameters: {
             type: 'object',
             properties: {
-                path: { type: 'string' }
+                path: { type: 'string' },
+                startLine: { type: 'number', description: 'First line to read (1-based, optional)' },
+                endLine: { type: 'number', description: 'Last line to read (inclusive, optional)' }
             },
             required: ['path']
         }
@@ -17,10 +32,63 @@ export const readFileTool = {
     validateArgs(args) {
         if (!args.path || typeof args.path !== 'string')
             throw new Error('path is required');
+        const start = toLineNumber(args.startLine, 'startLine');
+        const end = toLineNumber(args.endLine, 'endLine');
+        if (start !== undefined && end !== undefined && end < start) {
+            throw new Error('endLine must be greater than or equal to startLine');
+        }
     },
     async execute(args) {
         try {
-            return await fs.readFile(args.path, 'utf8');
+            const stat = await fs.stat(args.path);
+            if (stat.isDirectory()) {
+                throw new Error('Path is a directory, use list_dir instead');
+            }
+            if (stat.size > MAX_READ_FILE_BYTES) {
+                throw new Error(`File is too large (${(stat.size / 1024 / 1024).toFixed(1)} MB). Use the search tool, or bash (e.g. head/tail/sed -n) to look at part of it`);
+            }
+            const buffer = await fs.readFile(args.path);
+            if (buffer.subarray(0, 8000).includes(0)) {
+                return `[Binary file ${args.path} (${stat.size} bytes) - contents not shown]`;
+            }
+            const text = buffer.toString('utf8');
+            const startArg = toLineNumber(args.startLine, 'startLine');
+            const endArg = toLineNumber(args.endLine, 'endLine');
+            // Small files without a range: return the exact content.
+            if (startArg === undefined && endArg === undefined && text.length <= MAX_READ_CHARS) {
+                return text;
+            }
+            const lines = text.split('\n');
+            const total = lines.length;
+            const start = Math.min(startArg ?? 1, total);
+            const end = Math.min(Math.max(endArg ?? total, start), total);
+            let selected = lines.slice(start - 1, end);
+            let shownEnd = end;
+            let joined = selected.join('\n');
+            let truncated = false;
+            if (joined.length > MAX_READ_CHARS) {
+                truncated = true;
+                // Cut on a line boundary so the model can continue exactly where we stopped.
+                let size = 0;
+                let count = 0;
+                for (const line of selected) {
+                    if (size + line.length + 1 > MAX_READ_CHARS && count > 0)
+                        break;
+                    size += line.length + 1;
+                    count++;
+                }
+                selected = selected.slice(0, count);
+                shownEnd = start + count - 1;
+                joined = selected.join('\n');
+                if (joined.length > MAX_READ_CHARS) {
+                    // A single enormous line (e.g. minified bundle).
+                    joined = joined.slice(0, MAX_READ_CHARS);
+                }
+            }
+            const note = truncated
+                ? ` - output truncated, continue with startLine=${shownEnd + 1}`
+                : shownEnd < total ? ` - file continues, use startLine=${shownEnd + 1} to read more` : '';
+            return `[Lines ${start}-${shownEnd} of ${total}${note}]\n${joined}`;
         }
         catch (err) {
             throw new Error(`Failed to read file: ${err.message}`);
@@ -117,12 +185,16 @@ export const editFileTool = {
     validateArgs(args) {
         if (!args.path || typeof args.path !== 'string')
             throw new Error('path is required');
-        if (typeof args.target !== 'string')
-            throw new Error('target is required');
+        if (typeof args.target !== 'string' || args.target === '') {
+            throw new Error('target is required and must not be empty (use write_file to create or overwrite a whole file)');
+        }
         if (typeof args.replacement !== 'string')
             throw new Error('replacement is required');
     },
     async execute(args) {
+        if (typeof args.target !== 'string' || args.target === '') {
+            throw new Error('Failed to edit file: target must not be empty');
+        }
         try {
             await globalSnapshotManager.recordFileBeforeChange(args.path);
             const oldContent = await fs.readFile(args.path, 'utf8');

package/dist/tools/index.js

@@ -9,6 +9,7 @@ import { saveMemoryTool } from '../core/memory.js';
 import { planReadyTool, lastPlanReady, resetPlanReady } from './plan.js';
 import { todoListTool, currentTodoList, resetTodoList } from './todo.js';
 import { servePreviewTool } from './server.js';
+import { mcpManageTool } from './mcp.js';
 import { MCPManager } from '../mcp/manager.js';
 export function getTools(planMode) {
     const baseTools = [readFileTool, listDirTool, searchTool, askQuestionsTool, webSearchTool, fetchUrlTool, saveMemoryTool, planReadyTool, todoListTool];
@@ -16,6 +17,6 @@ export function getTools(planMode) {
     if (planMode) {
         return [...baseTools, ...mcpTools];
     }
-    return [...baseTools, writeFileTool, editFileTool, mkdirTool, bashTool, diagnoseCodeTool, installPackageTool, servePreviewTool, ...mcpTools];
+    return [...baseTools, writeFileTool, editFileTool, mkdirTool, bashTool, diagnoseCodeTool, installPackageTool, servePreviewTool, mcpManageTool, ...mcpTools];
 }
 export { webSearchTool, fetchUrlTool, diagnoseCodeTool, installPackageTool, saveMemoryTool, planReadyTool, lastPlanReady, resetPlanReady, todoListTool, currentTodoList, resetTodoList, servePreviewTool };

package/dist/tools/mcp.js

@@ -0,0 +1,72 @@
+import { MCPManager, readClaudeServers, saveUserServers } from '../mcp/manager.js';
+/**
+ * Lets the agent set up MCP servers when the user asks ("connect to Notion over MCP").
+ * Adding a server starts a program on the user's machine, so devx always asks first (see
+ * the guard), also in YOLO mode. The server is written to the user's own `~/.devx/mcp.json`.
+ */
+export const mcpManageTool = {
+    name: 'mcp_manage',
+    definition: {
+        name: 'mcp_manage',
+        description: "Manage MCP servers of devx. action 'list': the servers with their state, tools and errors. " +
+            "action 'add': save a server (name, command, args, env) to ~/.devx/mcp.json and start it; the user is asked to approve. " +
+            "action 'import_claude': take the servers the user already has in Claude Code (~/.claude.json). " +
+            "The tools of a newly added server can be called from the user's next message on.",
+        parameters: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['list', 'add', 'import_claude'], description: 'What to do' },
+                name: { type: 'string', description: "add: short server name, letters, digits, '-' and '_' (it becomes part of the tool names)" },
+                command: { type: 'string', description: "add: the program to start, e.g. 'npx', 'uvx', or a path to a binary (for a local server)" },
+                url: { type: 'string', description: 'add: the address of a remote MCP server over HTTP, instead of command. Put a token in headers; a server that needs OAuth is reached with command npx and args ["-y","mcp-remote","<url>"] instead.' },
+                headers: { type: 'object', description: 'add (with url): HTTP headers, e.g. {"Authorization": "Bearer ${TOKEN}"}: ${NAME} is read from the environment' },
+                args: { type: 'array', items: { type: 'string' }, description: "add: arguments, e.g. ['-y', 'mcp-remote', 'https://mcp.notion.com/mcp']" },
+                env: { type: 'object', description: 'add: environment variables the server needs (tokens go here, never into args)' },
+            },
+            required: ['action'],
+        },
+    },
+    validateArgs(args) {
+        if (!args || !['list', 'add', 'import_claude'].includes(args.action))
+            throw new Error("action must be 'list', 'add' or 'import_claude'");
+        if (args.action === 'add') {
+            if (!args.name || !/^[A-Za-z0-9_-]{1,40}$/.test(args.name))
+                throw new Error("name is required: letters, digits, '-' and '_', up to 40 characters");
+            if (args.url !== undefined) {
+                if (typeof args.url !== 'string' || !/^https?:\/\//i.test(args.url))
+                    throw new Error('url must start with http:// or https://');
+            }
+            else if (!args.command || typeof args.command !== 'string') {
+                throw new Error('command (or url) is required');
+            }
+            if (args.args !== undefined && !Array.isArray(args.args))
+                throw new Error('args must be an array of strings');
+        }
+    },
+    async execute(args) {
+        const manager = MCPManager.getInstance();
+        if (args.action === 'add') {
+            saveUserServers({
+                [args.name]: args.url
+                    ? { url: args.url, ...(args.headers && typeof args.headers === 'object' ? { headers: args.headers } : {}) }
+                    : { command: args.command, ...(args.args?.length ? { args: args.args.map(String) } : {}), ...(args.env && typeof args.env === 'object' ? { env: args.env } : {}) },
+            }, true);
+            await manager.reload();
+        }
+        else if (args.action === 'import_claude') {
+            const found = readClaudeServers();
+            if (Object.keys(found).length === 0)
+                return 'No MCP servers found in ~/.claude.json.';
+            saveUserServers(found);
+            await manager.reload();
+        }
+        const rows = manager.getStatuses().map((s) => ({
+            name: s.name,
+            status: s.status,
+            tools: s.toolsCount,
+            ...(s.error ? { error: s.error } : {}),
+            ...(s.status === 'connected' ? { sample_tools: s.tools.slice(0, 8) } : {}),
+        }));
+        return JSON.stringify({ servers: rows, note: rows.length === 0 ? 'No MCP servers configured yet.' : 'New tools can be called from the next user message.' });
+    },
+};

package/dist/tools/packages.js

@@ -22,6 +22,18 @@ export const installPackageTool = {
         if (!/^[@a-zA-Z0-9_\-./=><^~+:[\] ]+$/.test(sanitized) || /[;&|`$\n\r()]/.test(sanitized)) {
             throw new Error(`Invalid package name: "${args.package}". Invalid characters or potential command injection detected.`);
         }
+        // A token starting with "-" would be parsed by the package manager as an option
+        // (--registry=..., --index-url=..., -r file), not as a package name.
+        if (sanitized.split(/\s+/).some((token) => token.startsWith('-'))) {
+            throw new Error(`Invalid package name: "${args.package}". Command line options are not allowed, pass package names only.`);
+        }
+        // On Windows the package manager is started through cmd.exe, where these are redirection / escape characters.
+        if (process.platform === 'win32' && /[<>^]/.test(sanitized)) {
+            throw new Error(`Invalid package name: "${args.package}". Version ranges with < > ^ are not supported on Windows, use an exact version (pkg@1.2.3 or pkg==1.2.3).`);
+        }
+        if (args.manager !== undefined && !['npm', 'pip', 'yarn', 'pnpm', 'cargo'].includes(args.manager)) {
+            throw new Error(`Unsupported package manager: "${args.manager}".`);
+        }
     },
     async execute(args) {
         let pkgManager = args.manager;
@@ -71,7 +83,10 @@ export const installPackageTool = {
         else if (pkgManager === 'pip') {
             executable = 'pip';
             cmdArgs = ['install'];
-            if (process.platform !== 'win32') {
+            // Termux's Python is "externally managed" and has no system package manager that
+            // could be broken. On a regular Linux/macOS system this flag would override PEP 668
+            // and may damage the OS Python, so it is only used on Termux.
+            if (process.env.PREFIX?.includes('com.termux')) {
                 cmdArgs.push('--break-system-packages');
             }
             cmdArgs.push(...pkgs);

package/dist/tools/plan.js

@@ -40,13 +40,13 @@ export const planReadyTool = {
             steps: args.steps,
             timestamp: Date.now()
         };
-        let output = `Plan finalized: ${args.summary}\n`;
-        if (args.files && args.files.length > 0) {
-            output += `Files: ${args.files.join(', ')}\n`;
-        }
-        if (args.steps && args.steps.length > 0) {
-            output += `Steps:\n${args.steps.map((s, i) => `${i + 1}. ${s}`).join('\n')}`;
-        }
-        return output;
+        // JSON: devx draws it as the plan card; the model reads the same data.
+        return JSON.stringify({
+            type: 'plan_ready',
+            status: 'shown to the user, who approves it or asks for changes',
+            summary: args.summary,
+            ...(args.files && args.files.length > 0 ? { files: args.files } : {}),
+            ...(args.steps && args.steps.length > 0 ? { steps: args.steps } : {}),
+        });
     }
 };