mocode-ai 1.1.7 → 1.1.8

package/dist/tools/builtins/browser.js

@@ -0,0 +1,199 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, extname } from 'node:path';
+import { jailResolve } from '../../sandbox/index.js';
+import { MAX_INLINE_BYTES_DEFAULT } from '../../attachments/image.js';
+import { BrowserManagerError, click, closeAllBrowsers, closeSession, fill, listSessions, navigate, openSession, press, readText, screenshot, waitFor, } from '../../runtime/browser-manager.js';
+function result(status, code, payload) {
+    return { status, code, retryable: false, output: JSON.stringify(payload, null, 2) };
+}
+function invalid(message) {
+    return result('error', 'INVALID_ARGUMENTS', { error: message });
+}
+function optionalString(args, name) {
+    const value = args[name];
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function failure(error) {
+    if (error instanceof BrowserManagerError) {
+        const status = error.code === 'SANDBOX_DENIED' ? 'denied' : 'error';
+        return result(status, error.code, { error: error.message });
+    }
+    return result('error', 'EXECUTION_ERROR', {
+        error: error instanceof Error ? error.message : String(error),
+    });
+}
+export const browserTool = {
+    name: 'browser',
+    description: 'Drive a real Chromium browser to inspect a running frontend. Sessions persist across tool calls, ' +
+        'so open once and then navigate, interact, and screenshot the same page.\n' +
+        'Actions: open, navigate, click, fill, press, wait_for, text, screenshot, console, list, close.\n' +
+        'screenshot returns the rendered page as visual input, so you can actually see layout and styling issues. ' +
+        'Every result also reports recent console messages, page errors, and failed requests.\n' +
+        'Start the app with dev_server first. Only localhost URLs are allowed by default.',
+    risk: 'confirm',
+    parameters: {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                enum: ['open', 'navigate', 'click', 'fill', 'press', 'wait_for', 'text', 'screenshot', 'console', 'list', 'close'],
+                description: 'Operation to perform',
+            },
+            sessionId: { type: 'string', description: 'Session from action=open; optional when only one session exists' },
+            url: { type: 'string', description: 'Target URL for action=navigate, e.g. http://localhost:5173' },
+            selector: { type: 'string', description: 'CSS selector for click/fill/press/wait_for/text/screenshot' },
+            value: { type: 'string', description: 'Text to type for action=fill' },
+            key: { type: 'string', description: 'Key for action=press, e.g. Enter' },
+            fullPage: { type: 'boolean', description: 'Capture the entire scrollable page (action=screenshot)' },
+            headed: { type: 'boolean', description: 'Show a visible browser window on action=open (default: headless)' },
+            path: { type: 'string', description: 'Optional PNG path inside the workspace to also save a screenshot' },
+            detail: {
+                type: 'string',
+                enum: ['auto', 'low', 'high'],
+                description: 'Vision detail level for screenshots (default: high)',
+            },
+            timeoutMs: { type: 'integer', description: 'Action timeout in ms (default 15000, max 60000)' },
+            limit: { type: 'integer', description: 'Max characters for action=text (default 4000)' },
+        },
+        required: ['action'],
+        additionalProperties: false,
+    },
+    async execute(args) {
+        const action = String(args.action);
+        const sessionId = optionalString(args, 'sessionId');
+        try {
+            switch (action) {
+                case 'open':
+                    return result('success', 'OK', await openSession({ headed: args.headed === true }));
+                case 'list':
+                    return result('success', 'OK', { sessions: listSessions() });
+                case 'navigate': {
+                    const url = optionalString(args, 'url');
+                    if (!url)
+                        return invalid('action=navigate requires a url.');
+                    return result('success', 'OK', await navigate({
+                        ...(sessionId ? { sessionId } : {}),
+                        url,
+                        ...(args.timeoutMs === undefined ? {} : { timeoutMs: Number(args.timeoutMs) }),
+                    }));
+                }
+                case 'click':
+                case 'wait_for': {
+                    const selector = optionalString(args, 'selector');
+                    if (!selector)
+                        return invalid(`action=${action} requires a selector.`);
+                    const opts = {
+                        ...(sessionId ? { sessionId } : {}),
+                        selector,
+                        ...(args.timeoutMs === undefined ? {} : { timeoutMs: Number(args.timeoutMs) }),
+                    };
+                    return result('success', 'OK', action === 'click' ? await click(opts) : await waitFor(opts));
+                }
+                case 'fill': {
+                    const selector = optionalString(args, 'selector');
+                    if (!selector)
+                        return invalid('action=fill requires a selector.');
+                    if (typeof args.value !== 'string')
+                        return invalid('action=fill requires a value string.');
+                    return result('success', 'OK', await fill({
+                        ...(sessionId ? { sessionId } : {}),
+                        selector,
+                        value: args.value,
+                        ...(args.timeoutMs === undefined ? {} : { timeoutMs: Number(args.timeoutMs) }),
+                    }));
+                }
+                case 'press': {
+                    const key = optionalString(args, 'key');
+                    if (!key)
+                        return invalid('action=press requires a key.');
+                    return result('success', 'OK', await press({
+                        ...(sessionId ? { sessionId } : {}),
+                        key,
+                        ...(optionalString(args, 'selector') ? { selector: optionalString(args, 'selector') } : {}),
+                        ...(args.timeoutMs === undefined ? {} : { timeoutMs: Number(args.timeoutMs) }),
+                    }));
+                }
+                case 'text':
+                    return result('success', 'OK', await readText({
+                        ...(sessionId ? { sessionId } : {}),
+                        ...(optionalString(args, 'selector') ? { selector: optionalString(args, 'selector') } : {}),
+                        ...(args.limit === undefined ? {} : { limit: Number(args.limit) }),
+                    }));
+                case 'console': {
+                    const sessions = listSessions();
+                    const shot = await readText({ ...(sessionId ? { sessionId } : {}), limit: 100 });
+                    return result('success', 'OK', {
+                        sessionId: shot.sessionId,
+                        url: shot.url,
+                        diagnostics: shot.diagnostics,
+                        openSessions: sessions.length,
+                    });
+                }
+                case 'screenshot': {
+                    const captured = await screenshot({
+                        ...(sessionId ? { sessionId } : {}),
+                        fullPage: args.fullPage === true,
+                        ...(optionalString(args, 'selector') ? { selector: optionalString(args, 'selector') } : {}),
+                        ...(args.timeoutMs === undefined ? {} : { timeoutMs: Number(args.timeoutMs) }),
+                    });
+                    const { buffer, ...meta } = captured;
+                    if (buffer.byteLength > MAX_INLINE_BYTES_DEFAULT) {
+                        return result('error', 'EXECUTION_ERROR', {
+                            error: `Screenshot is ${buffer.byteLength} bytes, above the ${MAX_INLINE_BYTES_DEFAULT} byte inline limit. Retry with fullPage=false or a narrower selector.`,
+                            ...meta,
+                        });
+                    }
+                    let savedPath;
+                    const requestedPath = optionalString(args, 'path');
+                    if (requestedPath) {
+                        if (extname(requestedPath).toLowerCase() !== '.png') {
+                            return invalid('path must use the .png extension.');
+                        }
+                        try {
+                            const absolute = jailResolve(requestedPath);
+                            await mkdir(dirname(absolute), { recursive: true });
+                            await writeFile(absolute, buffer);
+                            savedPath = requestedPath;
+                        }
+                        catch (error) {
+                            return result('denied', 'SANDBOX_DENIED', {
+                                error: error instanceof Error ? error.message : String(error),
+                            });
+                        }
+                    }
+                    const detail = args.detail === 'low' || args.detail === 'auto' ? args.detail : 'high';
+                    return {
+                        status: 'success',
+                        code: 'OK',
+                        retryable: false,
+                        output: JSON.stringify({
+                            ...meta,
+                            bytes: buffer.byteLength,
+                            ...(savedPath ? { savedPath } : {}),
+                            note: 'Rendered page is attached to the next model request.',
+                        }, null, 2),
+                        modelAttachments: [{
+                                type: 'image',
+                                name: `${meta.sessionId}.png`,
+                                mime: 'image/png',
+                                dataUrl: `data:image/png;base64,${buffer.toString('base64')}`,
+                                detail,
+                            }],
+                    };
+                }
+                case 'close': {
+                    if (!sessionId && listSessions().length > 1) {
+                        await closeAllBrowsers();
+                        return result('success', 'OK', { closed: 'all' });
+                    }
+                    return result('success', 'OK', await closeSession(sessionId));
+                }
+                default:
+                    return invalid(`Unsupported action: ${action}`);
+            }
+        }
+        catch (error) {
+            return failure(error);
+        }
+    },
+};

package/dist/tools/builtins/dev-server.js

@@ -0,0 +1,99 @@
+import { DevServerManagerError, getDevServerStatus, readDevServerLogs, startDevServer, stopDevServer, } from '../../runtime/dev-server-manager.js';
+function result(status, code, payload) {
+    return { status, code, retryable: false, output: JSON.stringify(payload, null, 2) };
+}
+function invalid(message) {
+    return result('error', 'INVALID_ARGUMENTS', { error: message });
+}
+function optionalString(args, name) {
+    const value = args[name];
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function failure(error) {
+    if (error instanceof DevServerManagerError) {
+        const status = error.code === 'SANDBOX_DENIED'
+            ? 'denied'
+            : error.code === 'ABORTED' ? 'aborted' : 'error';
+        return result(status, error.code, { error: error.message });
+    }
+    return result('error', 'EXECUTION_ERROR', {
+        error: error instanceof Error ? error.message : String(error),
+    });
+}
+export const devServerTool = {
+    name: 'dev_server',
+    description: 'Manage long-running background processes such as a frontend dev server. Unlike run_command, ' +
+        'the process keeps running across tool calls, so you can start a server, then inspect it with the browser tool.\n' +
+        'Actions: start (needs command; optional readyUrl or readyPattern to wait until it actually serves), ' +
+        'status (all servers, or one by id), logs (tail output; pass offset for incremental reads), stop (terminate the process tree).\n' +
+        'Always stop servers you started once you are done verifying.',
+    risk: 'dangerous',
+    parameters: {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                enum: ['start', 'status', 'logs', 'stop'],
+                description: 'Operation to perform',
+            },
+            id: { type: 'string', description: 'Server id returned by start (required for logs/stop)' },
+            command: { type: 'string', description: 'Command to run for action=start, e.g. "npm run dev"' },
+            cwd: { type: 'string', description: 'Working directory inside the workspace (default: workspace root)' },
+            readyUrl: {
+                type: 'string',
+                description: 'Wait until this loopback URL responds, e.g. http://localhost:5173. Only localhost/127.0.0.1/::1 allowed.',
+            },
+            readyPattern: {
+                type: 'string',
+                description: 'Wait until server output matches this case-insensitive regex, e.g. "ready in|listening on"',
+            },
+            timeoutMs: { type: 'integer', description: 'Readiness wait budget in ms (default 30000, max 180000)' },
+            offset: { type: 'integer', description: 'Byte offset for action=logs (default: tail)' },
+            limit: { type: 'integer', description: 'Max bytes for action=logs (default 8000, max 64000)' },
+        },
+        required: ['action'],
+        additionalProperties: false,
+    },
+    async execute(args, ctx) {
+        const action = String(args.action);
+        try {
+            if (action === 'start') {
+                const command = optionalString(args, 'command');
+                if (!command)
+                    return invalid('action=start requires a non-empty command.');
+                const started = await startDevServer({
+                    command,
+                    cwd: optionalString(args, 'cwd'),
+                    readyUrl: optionalString(args, 'readyUrl'),
+                    readyPattern: optionalString(args, 'readyPattern'),
+                    ...(args.timeoutMs === undefined ? {} : { timeoutMs: Number(args.timeoutMs) }),
+                    ...(ctx?.signal ? { signal: ctx.signal } : {}),
+                });
+                return result('success', 'OK', started);
+            }
+            if (action === 'status') {
+                return result('success', 'OK', { servers: getDevServerStatus(optionalString(args, 'id')) });
+            }
+            if (action === 'logs') {
+                const id = optionalString(args, 'id');
+                if (!id)
+                    return invalid('action=logs requires the server id.');
+                const logs = await readDevServerLogs(id, {
+                    ...(args.offset === undefined ? {} : { offset: Number(args.offset) }),
+                    ...(args.limit === undefined ? {} : { limit: Number(args.limit) }),
+                });
+                return result('success', 'OK', logs);
+            }
+            if (action === 'stop') {
+                const id = optionalString(args, 'id');
+                if (!id)
+                    return invalid('action=stop requires the server id.');
+                return result('success', 'OK', await stopDevServer(id));
+            }
+            return invalid(`Unsupported action: ${action}`);
+        }
+        catch (error) {
+            return failure(error);
+        }
+    },
+};

package/dist/tools/builtins/index.js

@@ -1,14 +1,17 @@
 import { readFileTool } from './read-file.js';
+import { viewImageTool } from './view-image.js';
+import { screenshotTool } from './screenshot.js';
 import { writeFileTool } from './write-file.js';
 import { editFileTool } from './edit-file.js';
 import { runCommandTool } from './run-command.js';
+import { devServerTool } from './dev-server.js';
+import { browserTool } from './browser.js';
 import { globTool } from './glob.js';
 import { grepTool } from './grep.js';
 import { webSearchTool } from './web-search.js';
 import { webFetchTool } from './web-fetch.js';
 import { useSkillTool } from './use-skill.js';
 import { askHumanTool } from './ask-human.js';
-import { dropContextTool } from './drop-context.js';
 import { memorySaveTool } from './memory-save.js';
 import { memorySearchTool } from './memory-search.js';
 import { memoryListTool } from './memory-list.js';
@@ -42,27 +45,30 @@ const pathResource = (args) => typeof args.path === 'string' && args.path ? [`fi
 const workspaceResource = () => ['workspace'];
 const memoryResource = () => ['memory-store'];
 const CAPABILITIES = {
-    read_file: { effect: 'read', concurrency: 'parallel', retry: 'safe', resources: pathResource },
-    write_file: { effect: 'write', concurrency: 'resource-locked', retry: 'never', resources: pathResource, delegatesResourceLocks: true },
-    edit_file: { effect: 'write', concurrency: 'resource-locked', retry: 'never', resources: pathResource, delegatesResourceLocks: true },
-    run_command: { effect: 'process', concurrency: 'serial', retry: 'never', resources: workspaceResource, supportsAbort: true },
-    glob: { effect: 'read', concurrency: 'parallel', retry: 'safe', resources: workspaceResource },
-    grep: { effect: 'read', concurrency: 'parallel', retry: 'safe', resources: workspaceResource },
-    web_search: { effect: 'network', concurrency: 'parallel', retry: 'safe', supportsAbort: true },
-    web_fetch: { effect: 'network', concurrency: 'parallel', retry: 'safe', supportsAbort: true },
-    use_skill: { effect: 'read', concurrency: 'serial', retry: 'safe' },
-    ask_human: { effect: 'read', concurrency: 'serial', retry: 'never' },
-    drop_context: { effect: 'write', concurrency: 'serial', retry: 'never', resources: () => ['conversation-context'] },
-    memory_save: { effect: 'write', concurrency: 'serial', retry: 'never', resources: memoryResource },
-    memory_search: { effect: 'write', concurrency: 'serial', retry: 'never', resources: memoryResource },
-    memory_list: { effect: 'read', concurrency: 'serial', retry: 'safe', resources: memoryResource },
-    memory_update: { effect: 'write', concurrency: 'serial', retry: 'never', resources: memoryResource },
-    memory_forget: { effect: 'write', concurrency: 'serial', retry: 'never', resources: memoryResource },
+    read_file: { effect: 'read', concurrency: 'parallel', resources: pathResource },
+    view_image: { effect: 'read', concurrency: 'parallel', resources: pathResource },
+    screenshot: { effect: 'process', concurrency: 'serial', resources: workspaceResource, supportsAbort: true },
+    write_file: { effect: 'write', concurrency: 'resource-locked', resources: pathResource, delegatesResourceLocks: true },
+    edit_file: { effect: 'write', concurrency: 'resource-locked', resources: pathResource, delegatesResourceLocks: true },
+    run_command: { effect: 'process', concurrency: 'serial', resources: workspaceResource, supportsAbort: true },
+    // 后台进程与浏览器会话跨调用存活；串行执行避免同一页面/服务被并发操作。
+    dev_server: { effect: 'process', concurrency: 'serial', resources: workspaceResource, supportsAbort: true },
+    browser: { effect: 'process', concurrency: 'serial', resources: workspaceResource },
+    glob: { effect: 'read', concurrency: 'parallel', resources: workspaceResource },
+    grep: { effect: 'read', concurrency: 'parallel', resources: workspaceResource },
+    web_search: { effect: 'network', concurrency: 'parallel', supportsAbort: true },
+    web_fetch: { effect: 'network', concurrency: 'parallel', supportsAbort: true },
+    use_skill: { effect: 'read', concurrency: 'serial' },
+    ask_human: { effect: 'read', concurrency: 'serial' },
+    memory_save: { effect: 'write', concurrency: 'serial', resources: memoryResource },
+    memory_search: { effect: 'write', concurrency: 'serial', resources: memoryResource },
+    memory_list: { effect: 'read', concurrency: 'serial', resources: memoryResource },
+    memory_update: { effect: 'write', concurrency: 'serial', resources: memoryResource },
+    memory_forget: { effect: 'write', concurrency: 'serial', resources: memoryResource },
     // sub-agent 动态协调：只读任务无锁并行；写任务在 overlay 中执行，merge 时由 ChangeSet 持 canonical lock。
     'sub-agent': {
         effect: 'write',
         concurrency: 'resource-locked',
-        retry: 'never',
         resources: (args) => args.mode === 'write' && Array.isArray(args.writeSet) && args.writeSet.length
             ? args.writeSet.map((item) => `file:${String(item)}`)
             : args.mode === 'write' ? ['workspace'] : [],
@@ -72,16 +78,19 @@ const CAPABILITIES = {
 };
 const rawBuiltinTools = [
     readFileTool,
+    viewImageTool,
+    screenshotTool,
     writeFileTool,
     editFileTool,
     runCommandTool,
+    devServerTool,
+    browserTool,
     globTool,
     grepTool,
     webSearchTool,
     webFetchTool,
     useSkillTool,
     askHumanTool,
-    dropContextTool,
     ..._memoryTools,
     subAgentTool,
 ];

package/dist/tools/builtins/screenshot.js

@@ -0,0 +1,173 @@
+import { spawn } from 'node:child_process';
+import { mkdir } from 'node:fs/promises';
+import { dirname, extname } from 'node:path';
+import { loadImageAttachment, MAX_INLINE_BYTES_DEFAULT, } from '../../attachments/image.js';
+import { filterEnv, jailResolve } from '../../sandbox/index.js';
+function runCaptureProcess(program, args, env, signal) {
+    return new Promise((resolve) => {
+        const child = spawn(program, args, {
+            env,
+            windowsHide: true,
+            stdio: ['ignore', 'ignore', 'pipe'],
+        });
+        let stderr = '';
+        let finished = false;
+        const finish = (result) => {
+            if (finished)
+                return;
+            finished = true;
+            signal?.removeEventListener('abort', onAbort);
+            resolve(result);
+        };
+        const onAbort = () => {
+            child.kill();
+            finish({ status: 'aborted', detail: 'Screenshot capture was aborted.' });
+        };
+        child.stderr.on('data', (chunk) => {
+            stderr = (stderr + chunk.toString('utf8')).slice(-4000);
+        });
+        child.on('error', (error) => finish({ status: 'spawn_error', detail: error.message }));
+        child.on('close', (code) => finish({
+            status: code === 0 ? 'passed' : 'failed',
+            detail: stderr.trim() || `Capture process exited with code ${code ?? 'null'}.`,
+        }));
+        if (signal) {
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener('abort', onAbort, { once: true });
+        }
+    });
+}
+const WINDOWS_CAPTURE_SCRIPT = [
+    'Add-Type -AssemblyName System.Windows.Forms',
+    'Add-Type -AssemblyName System.Drawing',
+    "$bounds = if ($env:MOCODE_SCREENSHOT_TARGET -eq 'all') { [System.Windows.Forms.SystemInformation]::VirtualScreen } else { [System.Windows.Forms.Screen]::PrimaryScreen.Bounds }",
+    '$bitmap = [System.Drawing.Bitmap]::new($bounds.Width, $bounds.Height)',
+    '$graphics = [System.Drawing.Graphics]::FromImage($bitmap)',
+    'try {',
+    '  $graphics.CopyFromScreen($bounds.X, $bounds.Y, 0, 0, $bounds.Size)',
+    '  $bitmap.Save($env:MOCODE_SCREENSHOT_PATH, [System.Drawing.Imaging.ImageFormat]::Png)',
+    '} finally {',
+    '  $graphics.Dispose()',
+    '  $bitmap.Dispose()',
+    '}',
+].join('\n');
+async function captureDesktop(outputPath, target, signal) {
+    const env = {
+        ...filterEnv(process.env),
+        MOCODE_SCREENSHOT_PATH: outputPath,
+        MOCODE_SCREENSHOT_TARGET: target,
+    };
+    if (process.platform === 'win32') {
+        return runCaptureProcess('powershell.exe', ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', WINDOWS_CAPTURE_SCRIPT], env, signal);
+    }
+    if (process.platform === 'darwin') {
+        const args = ['-x', ...(target === 'primary' ? ['-m'] : []), outputPath];
+        return runCaptureProcess('/usr/sbin/screencapture', args, env, signal);
+    }
+    const candidates = [
+        ['gnome-screenshot', ['-f', outputPath]],
+        ['grim', [outputPath]],
+        ['scrot', [outputPath]],
+        ['import', ['-window', 'root', outputPath]],
+    ];
+    const failures = [];
+    for (const [program, args] of candidates) {
+        const result = await runCaptureProcess(program, args, env, signal);
+        if (result.status === 'passed' || result.status === 'aborted')
+            return result;
+        failures.push(`${program}: ${result.detail}`);
+    }
+    return {
+        status: 'failed',
+        detail: `No supported Linux screenshot command succeeded. ${failures.join(' | ')}`,
+    };
+}
+export const screenshotTool = {
+    name: 'screenshot',
+    description: 'Capture the desktop and inspect it as visual model input. Use this to diagnose visible UI state, dialogs, rendering problems, or applications that cannot be understood from source files alone. The user must approve each capture because screenshots may contain sensitive information.',
+    risk: 'confirm',
+    parameters: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Optional output PNG path inside the workspace. Defaults to .mocode/screenshots/<timestamp>.png.',
+            },
+            target: {
+                type: 'string',
+                enum: ['primary', 'all'],
+                description: 'Capture the primary display or the full virtual desktop (default: primary).',
+            },
+            detail: {
+                type: 'string',
+                enum: ['auto', 'low', 'high'],
+                description: 'Vision detail level (default: high).',
+            },
+        },
+        additionalProperties: false,
+    },
+    async execute(args, ctx) {
+        const defaultName = `.mocode/screenshots/screenshot-${new Date().toISOString().replace(/[:.]/g, '-')}.png`;
+        let requestedPath = String(args.path ?? defaultName).trim();
+        if (!requestedPath)
+            requestedPath = defaultName;
+        if (!extname(requestedPath))
+            requestedPath += '.png';
+        if (extname(requestedPath).toLowerCase() !== '.png') {
+            return {
+                status: 'error', code: 'INVALID_ARGUMENTS', retryable: false,
+                output: 'Screenshot output path must use the .png extension.',
+            };
+        }
+        let outputPath;
+        try {
+            outputPath = jailResolve(requestedPath);
+            await mkdir(dirname(outputPath), { recursive: true });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { status: 'denied', code: 'SANDBOX_DENIED', retryable: false, output: message };
+        }
+        const target = args.target === 'all' ? 'all' : 'primary';
+        const capture = await captureDesktop(outputPath, target, ctx?.signal);
+        if (capture.status !== 'passed') {
+            if (capture.status === 'aborted') {
+                return { status: 'aborted', code: 'ABORTED', retryable: false, output: capture.detail };
+            }
+            return {
+                status: 'error',
+                code: capture.status === 'failed' ? 'PROCESS_FAILED' : 'EXECUTION_ERROR',
+                retryable: false,
+                output: `Unable to capture screenshot: ${capture.detail}`,
+            };
+        }
+        const loaded = await loadImageAttachment(outputPath, {
+            maxBytes: MAX_INLINE_BYTES_DEFAULT,
+        });
+        if (!loaded.ok) {
+            return {
+                status: 'error',
+                code: 'EXECUTION_ERROR',
+                retryable: false,
+                output: `Screenshot saved to ${requestedPath}, but it could not be attached: ${loaded.reason}`,
+            };
+        }
+        const detail = args.detail === 'low' || args.detail === 'auto' ? args.detail : 'high';
+        const { att } = loaded;
+        return {
+            status: 'success',
+            code: 'OK',
+            retryable: false,
+            output: `Captured ${target} display to ${requestedPath} (${att.bytes} bytes). Visual content is attached to the next model request.`,
+            modelAttachments: [{
+                    type: 'image',
+                    name: att.name,
+                    mime: att.mime,
+                    dataUrl: att.dataUrl,
+                    detail,
+                }],
+        };
+    },
+};

package/dist/tools/builtins/view-image.js

@@ -0,0 +1,49 @@
+import { loadImageAttachment, MAX_INLINE_BYTES_DEFAULT, } from '../../attachments/image.js';
+export const viewImageTool = {
+    name: 'view_image',
+    description: 'View a local image as visual model input. Use this whenever the user refers to a screenshot, UI error, design mockup, Figma export, diagram, or other image file. Supports PNG, JPEG, GIF, and WebP up to 4 MiB.',
+    parameters: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Image path, relative to the working directory',
+            },
+            detail: {
+                type: 'string',
+                enum: ['auto', 'low', 'high'],
+                description: 'Vision detail level (default: auto)',
+            },
+        },
+        required: ['path'],
+        additionalProperties: false,
+    },
+    async execute(args) {
+        const loaded = await loadImageAttachment(String(args.path ?? ''), {
+            maxBytes: MAX_INLINE_BYTES_DEFAULT,
+        });
+        if (!loaded.ok) {
+            return {
+                status: 'error',
+                code: loaded.reason.startsWith('outside sandbox') ? 'SANDBOX_DENIED' : 'EXECUTION_ERROR',
+                retryable: false,
+                output: `Unable to view image: ${loaded.reason}`,
+            };
+        }
+        const detail = args.detail === 'low' || args.detail === 'high' ? args.detail : 'auto';
+        const { att } = loaded;
+        return {
+            status: 'success',
+            code: 'OK',
+            retryable: false,
+            output: `Viewed image "${att.name}" (${att.mime}, ${att.bytes} bytes). Visual content is attached to the next model request.`,
+            modelAttachments: [{
+                    type: 'image',
+                    name: att.name,
+                    mime: att.mime,
+                    dataUrl: att.dataUrl,
+                    detail,
+                }],
+        };
+    },
+};

package/dist/tools/constants.js

@@ -35,6 +35,9 @@ export const PLAN_DISABLED_TOOLS = new Set([
     'write_file',
     'edit_file',
     'run_command',
+    'screenshot',
+    'dev_server',
+    'browser',
     'memory_save',
     'memory_update',
     'memory_forget',