vault-go 0.33.0 → 0.34.0

package/README.md

@@ -180,6 +180,8 @@ Engines and updates: `vault_go_engines`, `vault_go_engine_select`, `vault_go_gen
 
 Graph and local code: `vault_go_graph`, `vault_go_graph_link`, `vault_go_graph_link_delete`, `vault_go_graph_presets`, `vault_go_graph_preset_save`, `vault_go_smart_outline`, `vault_go_smart_unfold`, `vault_go_smart_search`, `vault_go_smart_languages`.
 
+Computer Use by Vault: `vault_go_computer_status`, `vault_go_computer_permissions`, `vault_go_computer_list_apps`, `vault_go_computer_list_windows`, `vault_go_computer_get_app_state`, `vault_go_computer_query`, `vault_go_computer_click`, `vault_go_computer_perform_secondary_action`, `vault_go_computer_scroll`, `vault_go_computer_drag`, `vault_go_computer_type_text`, `vault_go_computer_paste_text`, `vault_go_computer_set_value`, `vault_go_computer_press_key`, `vault_go_computer_hotkey`. They drive local apps through the Vault Desktop native helper (installed and running), so every MCP client shares its permissions; on macOS grant Accessibility and Screen Recording to "Vault Desktop Computer Use" once. `get_app_state` returns the accessibility tree plus the window screenshot as an MCP image; `query` finds controls by text or role without a screenshot. Element indexes share one session per server. Typed text and values travel over stdin, never the process arguments. Set `VAULT_DESKTOP_CLI` to point at a custom CLI path, or `VAULT_GO_COMPUTER_USE=off` to hide the tools. The tool surface follows [open-computer-use](https://github.com/iFurySt/open-computer-use) (MIT).
+
 Workflows: `vault_go_workflow`, `vault_go_modes`, `vault_go_mode`, plus named prompts such as `vault_go_babysit`. Loading a mode gives the agent instructions; it does not start a background job.
 
 Optional local integrations (explicit consent): Telegram alerts, custom mode taxonomies, Claude/Codex transcript watchers, multi-project context chains, and Grok awareness logs. See `vault_go_capabilities` for what is configured on this machine.

package/dist/capabilities.d.ts

@@ -110,6 +110,11 @@ export declare const CAPABILITIES: {
         readonly status: "available";
         readonly tools: readonly ["vault_go_modes", "vault_go_mode", "vault_go_agent_cost_report"];
         readonly difference: "Setup writes managed SKILL.md files for Claude, Grok and shared agent skill directories. mem-search uses vault_go_search_index → vault_go_timeline → vault_go_observations → vault_go_tool_uses. babysit is a session loop with gh, not a Vault background daemon. agent-cost-report prices local JSONL usage with a published list rate and reports missing usage as unavailable.";
+    }, {
+        readonly upstream: readonly ["open-computer-use: list_apps, get_app_state, query, click, drag, scroll, type_text, press_key, set_value, perform_secondary_action"];
+        readonly status: "available";
+        readonly tools: readonly ["vault_go_computer_status", "vault_go_computer_permissions", "vault_go_computer_list_apps", "vault_go_computer_list_windows", "vault_go_computer_get_app_state", "vault_go_computer_query", "vault_go_computer_click", "vault_go_computer_perform_secondary_action", "vault_go_computer_scroll", "vault_go_computer_drag", "vault_go_computer_type_text", "vault_go_computer_paste_text", "vault_go_computer_set_value", "vault_go_computer_press_key", "vault_go_computer_hotkey"];
+        readonly requires: "Computer Use by Vault runs through the installed Vault Desktop helper and its macOS Accessibility and Screen Recording permissions; Vault Desktop must be running. select_text, background SkyLight input and Locked Use are not ported. VAULT_GO_COMPUTER_USE=off hides the tools.";
     }, {
         readonly upstream: readonly ["viewer", "statusline"];
         readonly status: "available";
@@ -234,6 +239,11 @@ export declare function getCapabilities(home: string, cloud: VaultMemoryApi, ver
         readonly status: "available";
         readonly tools: readonly ["vault_go_modes", "vault_go_mode", "vault_go_agent_cost_report"];
         readonly difference: "Setup writes managed SKILL.md files for Claude, Grok and shared agent skill directories. mem-search uses vault_go_search_index → vault_go_timeline → vault_go_observations → vault_go_tool_uses. babysit is a session loop with gh, not a Vault background daemon. agent-cost-report prices local JSONL usage with a published list rate and reports missing usage as unavailable.";
+    }, {
+        readonly upstream: readonly ["open-computer-use: list_apps, get_app_state, query, click, drag, scroll, type_text, press_key, set_value, perform_secondary_action"];
+        readonly status: "available";
+        readonly tools: readonly ["vault_go_computer_status", "vault_go_computer_permissions", "vault_go_computer_list_apps", "vault_go_computer_list_windows", "vault_go_computer_get_app_state", "vault_go_computer_query", "vault_go_computer_click", "vault_go_computer_perform_secondary_action", "vault_go_computer_scroll", "vault_go_computer_drag", "vault_go_computer_type_text", "vault_go_computer_paste_text", "vault_go_computer_set_value", "vault_go_computer_press_key", "vault_go_computer_hotkey"];
+        readonly requires: "Computer Use by Vault runs through the installed Vault Desktop helper and its macOS Accessibility and Screen Recording permissions; Vault Desktop must be running. select_text, background SkyLight input and Locked Use are not ported. VAULT_GO_COMPUTER_USE=off hides the tools.";
     }, {
         readonly upstream: readonly ["viewer", "statusline"];
         readonly status: "available";

package/dist/capabilities.js

@@ -29,6 +29,7 @@ export const CAPABILITIES = {
         { upstream: ['transcript watchers'], status: 'available', tools: ['vault_go_transcripts_status', 'vault_go_transcripts_configure', 'vault_go_transcripts_poll'], difference: 'Persistent, consented and resumable watchers read Claude, Codex and Cursor JSONL transcripts. Cursor rows use the Claude message shape. Other transcript formats are not claimed.' },
         { upstream: ['Grok awareness push'], status: 'available', tools: ['vault_go_grok_awareness_status', 'vault_go_grok_awareness_configure', 'vault_go_grok_awareness_push'], requires: 'Explicit consent, an allowlisted agent UUID and a local agent-data root. Monthly awareness logs are bounded, private and separate from Telegram.' },
         { upstream: ['development/report/presentation skills', 'babysit', 'mem-search', 'agent-cost-report'], status: 'available', tools: ['vault_go_modes', 'vault_go_mode', 'vault_go_agent_cost_report'], difference: 'Setup writes managed SKILL.md files for Claude, Grok and shared agent skill directories. mem-search uses vault_go_search_index → vault_go_timeline → vault_go_observations → vault_go_tool_uses. babysit is a session loop with gh, not a Vault background daemon. agent-cost-report prices local JSONL usage with a published list rate and reports missing usage as unavailable.' },
+        { upstream: ['open-computer-use: list_apps, get_app_state, query, click, drag, scroll, type_text, press_key, set_value, perform_secondary_action'], status: 'available', tools: ['vault_go_computer_status', 'vault_go_computer_permissions', 'vault_go_computer_list_apps', 'vault_go_computer_list_windows', 'vault_go_computer_get_app_state', 'vault_go_computer_query', 'vault_go_computer_click', 'vault_go_computer_perform_secondary_action', 'vault_go_computer_scroll', 'vault_go_computer_drag', 'vault_go_computer_type_text', 'vault_go_computer_paste_text', 'vault_go_computer_set_value', 'vault_go_computer_press_key', 'vault_go_computer_hotkey'], requires: 'Computer Use by Vault runs through the installed Vault Desktop helper and its macOS Accessibility and Screen Recording permissions; Vault Desktop must be running. select_text, background SkyLight input and Locked Use are not ported. VAULT_GO_COMPUTER_USE=off hides the tools.' },
         { upstream: ['viewer', 'statusline'], status: 'available', tools: [], difference: 'The local worker serves /viewer and /statusline on its loopback port. Semantic search stays on the Vault account index. A second local vector database is not shipped.' },
         { upstream: ['private skills library'], status: 'available', tools: ['vault_go_skills', 'vault_go_skill_folders', 'vault_go_skill_read', 'vault_go_skill_file', 'vault_go_skill_save', 'vault_go_skill_organize', 'vault_go_skill_install', 'vault_go_skill_sync'], requires: 'Account skill packages organized by folders and linked to projects (/v1/skills). Saving publishes a new immutable version; deleting is only available in the Vault apps. Local install verifies sha256 and manifest digest and never replaces a skill the Vault did not install.' },
     ],

package/dist/computer-tools.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ComputerUseBridge } from './computer-use.js';
+/** Computer Use by Vault: native app control through the Vault Desktop helper (opt out with VAULT_GO_COMPUTER_USE=off). */
+export declare function registerComputerTools(server: McpServer, bridge?: ComputerUseBridge, env?: NodeJS.ProcessEnv): void;

package/dist/computer-tools.js

@@ -0,0 +1,135 @@
+import { z } from 'zod';
+import { errorMessage } from './mcp-result.js';
+import { ComputerUseBridge, computerUseEnabled, queryTree } from './computer-use.js';
+const app = z.string().trim().min(1).max(500).describe('Nome do app, bundle ID (preferível, ex.: com.apple.TextEdit) ou pid:N, como em vault_go_computer_list_apps.');
+const elementIndex = z.number().int().min(0).max(1_000_000).describe('Índice do elemento na árvore de acessibilidade do último get_app_state/query.');
+const coordinate = z.number().finite().min(-100_000).max(100_000);
+const observe = {
+    windowId: z.number().int().min(0).optional().describe('ID da janela retornado por vault_go_computer_list_windows.'),
+    windowIndex: z.number().int().min(0).optional().describe('Índice da janela quando o ID for none.'),
+    restoreWindow: z.boolean().optional().describe('Traz o app/janela para frente antes da operação.'),
+    screenshot: z.boolean().default(true).describe('Anexa um screenshot da janela depois da operação. false é mais rápido.'),
+    session: z.string().trim().min(1).max(200).optional().describe('Namespace dos índices de elementos. Por padrão, um por servidor MCP.'),
+};
+const ACTION = { readOnlyHint: false, destructiveHint: false, openWorldHint: false };
+const READ = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const SAFETY = 'Não envie, compre, apague nem altere contas sem pedido explícito do usuário. Ação não verificada (verification.state=unverified) não é sucesso comprovado.';
+function observeFlags(input, bridge) {
+    return {
+        app: undefined,
+        session: input.session ?? bridge.sessionId,
+        'window-id': input.windowId,
+        'window-index': input.windowIndex,
+        'restore-window': input.restoreWindow,
+        'no-screenshot': input.screenshot === false,
+    };
+}
+function toolResult(result) {
+    const content = [{ type: 'text', text: JSON.stringify(result.value) }];
+    if (result.image)
+        content.push({ type: 'image', data: result.image.data, mimeType: result.image.mimeType });
+    return { content, structuredContent: result.value };
+}
+async function invoke(operation) {
+    try {
+        return toolResult(await operation());
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: errorMessage(error) }], isError: true };
+    }
+}
+/** Computer Use by Vault: native app control through the Vault Desktop helper (opt out with VAULT_GO_COMPUTER_USE=off). */
+export function registerComputerTools(server, bridge = new ComputerUseBridge(), env = process.env) {
+    if (!computerUseEnabled(env))
+        return;
+    const action = (command, input, extra, stdin) => invoke(() => bridge.call(command, { ...observeFlags(input, bridge), app: input.app, ...extra }, stdin));
+    server.registerTool('vault_go_computer_status', {
+        description: 'Computer Use by Vault: verifica se o Vault Desktop e o helper nativo estão disponíveis e quais ações a plataforma suporta. Rode antes da primeira ação; em erro de permissão use vault_go_computer_permissions.',
+        inputSchema: {}, annotations: READ,
+    }, () => invoke(async () => {
+        const result = await bridge.call('capabilities');
+        return { ...result, value: { cli: bridge.cliPath(), session: bridge.sessionId, ...result.value } };
+    }));
+    server.registerTool('vault_go_computer_permissions', {
+        description: 'Abre a configuração de permissões do Computer Use by Vault (macOS: Acessibilidade e Gravação de Tela para "Vault Desktop Computer Use") e informa o estado de cada uma.',
+        inputSchema: { id: z.enum(['accessibility', 'screenshots']).optional() }, annotations: ACTION,
+    }, ({ id }) => invoke(() => bridge.call('permissions', { id })));
+    server.registerTool('vault_go_computer_list_apps', {
+        description: 'Lista os apps em execução que o Computer Use by Vault pode operar, com bundle ID e pid.',
+        inputSchema: {}, annotations: READ,
+    }, () => invoke(() => bridge.call('list-apps')));
+    server.registerTool('vault_go_computer_list_windows', {
+        description: 'Lista as janelas de um app (id, índice, título, posição) para mirar uma janela específica.',
+        inputSchema: { app }, annotations: READ,
+    }, ({ app: target }) => invoke(() => bridge.call('list-windows', { app: target })));
+    server.registerTool('vault_go_computer_get_app_state', {
+        description: 'Lê a árvore de acessibilidade da janela de um app e anexa um screenshot. Chame uma vez por turno antes de agir; os números da árvore são os elementIndex das ações e expiram após mudanças na UI.',
+        inputSchema: { app, ...observe }, annotations: READ,
+    }, (input) => action('get-app-state', input, {}));
+    server.registerTool('vault_go_computer_query', {
+        description: 'Busca direcionada: encontra controles por texto e/ou papel (button, text field, AXButton) sem screenshot e sem devolver a árvore inteira. Os índices retornados servem direto para click/set_value/scroll na mesma sessão.',
+        inputSchema: {
+            app,
+            text: z.string().trim().max(1_000).optional().describe('Texto no título, descrição, valor ou conteúdo do elemento (sem diferenciar maiúsculas).'),
+            role: z.string().trim().max(100).optional().describe('Papel de acessibilidade, ex.: button, text field ou AXButton.'),
+            exact: z.boolean().default(false).describe('Exige o nome inteiro em vez de substring.'),
+            limit: z.number().int().min(1).max(100).default(20),
+            windowId: observe.windowId, windowIndex: observe.windowIndex, session: observe.session,
+        },
+        annotations: READ,
+    }, (input) => invoke(async () => {
+        if (!input.text && !input.role)
+            throw new Error('Informe text e/ou role.');
+        const state = await bridge.call('get-app-state', { ...observeFlags({ ...input, screenshot: false }, bridge), app: input.app });
+        const snapshot = (state.value.snapshot ?? {});
+        const found = queryTree(typeof snapshot.treeText === 'string' ? snapshot.treeText : '', input);
+        return { value: { snapshotId: snapshot.id ?? null, app: snapshot.app ?? null, window: snapshot.window ?? null, ...found, treeTruncated: snapshot.truncation?.truncated === true }, image: null };
+    }));
+    server.registerTool('vault_go_computer_click', {
+        description: `Clica em um elemento (elementIndex) ou em coordenadas da janela (x, y). Suporta clique duplo, botão direito/meio e modificadores atômicos (ex.: CmdOrCtrl+Shift). ${SAFETY}`,
+        inputSchema: {
+            app, elementIndex: elementIndex.optional(), x: coordinate.optional(), y: coordinate.optional(),
+            clickCount: z.number().int().min(1).max(3).optional(), mouseButton: z.enum(['left', 'right', 'middle']).optional(),
+            modifiers: z.string().trim().max(100).optional(), ...observe,
+        },
+        annotations: ACTION,
+    }, (input) => action('click', input, { 'element-index': input.elementIndex, x: input.x, y: input.y, 'click-count': input.clickCount, 'mouse-button': input.mouseButton, modifiers: input.modifiers }));
+    server.registerTool('vault_go_computer_perform_secondary_action', {
+        description: `Executa uma ação secundária de acessibilidade listada no elemento (ex.: "show menu", "increment"). ${SAFETY}`,
+        inputSchema: { app, elementIndex, action: z.string().trim().min(1).max(200), ...observe }, annotations: ACTION,
+    }, (input) => action('perform-secondary-action', input, { 'element-index': input.elementIndex, action: input.action }));
+    server.registerTool('vault_go_computer_scroll', {
+        description: 'Rola um elemento ou ponto da janela em páginas (frações permitidas).',
+        inputSchema: { app, direction: z.enum(['up', 'down', 'left', 'right']), elementIndex: elementIndex.optional(), x: coordinate.optional(), y: coordinate.optional(), pages: z.number().positive().max(50).optional(), ...observe },
+        annotations: ACTION,
+    }, (input) => action('scroll', input, { direction: input.direction, 'element-index': input.elementIndex, x: input.x, y: input.y, pages: input.pages }));
+    server.registerTool('vault_go_computer_drag', {
+        description: `Arrasta entre dois elementos (fromElementIndex/toElementIndex) ou entre coordenadas da janela. ${SAFETY}`,
+        inputSchema: {
+            app, fromElementIndex: elementIndex.optional(), toElementIndex: elementIndex.optional(),
+            fromX: coordinate.optional(), fromY: coordinate.optional(), toX: coordinate.optional(), toY: coordinate.optional(), ...observe,
+        },
+        annotations: ACTION,
+    }, (input) => action('drag', input, { 'from-element-index': input.fromElementIndex, 'to-element-index': input.toElementIndex, 'from-x': input.fromX, 'from-y': input.fromY, 'to-x': input.toX, 'to-y': input.toY }));
+    const text = z.string().max(100_000);
+    server.registerTool('vault_go_computer_type_text', {
+        description: `Digita texto literal no foco atual do app. Prefira set_value em campos editáveis; o texto vai por stdin e não aparece na lista de processos. ${SAFETY}`,
+        inputSchema: { app, text, ...observe }, annotations: ACTION,
+    }, (input) => action('type-text', input, { 'text-stdin': true }, input.text));
+    server.registerTool('vault_go_computer_paste_text', {
+        description: `Cola texto exato no foco atual (via área de transferência), útil para textos longos ou com acentos. ${SAFETY}`,
+        inputSchema: { app, text, ...observe }, annotations: ACTION,
+    }, (input) => action('paste-text', input, { 'text-stdin': true }, input.text));
+    server.registerTool('vault_go_computer_set_value', {
+        description: `Define o valor de um elemento editável (campo de texto, slider, busca) diretamente pela acessibilidade, com verificação por leitura. ${SAFETY}`,
+        inputSchema: { app, elementIndex, value: text, ...observe }, annotations: ACTION,
+    }, (input) => action('set-value', input, { 'element-index': input.elementIndex, 'value-stdin': true }, input.value));
+    server.registerTool('vault_go_computer_press_key', {
+        description: `Pressiona uma tecla única: Return, Escape, Tab, setas, PageUp, Delete. Para combinações use vault_go_computer_hotkey. ${SAFETY}`,
+        inputSchema: { app, key: z.string().trim().min(1).max(50), ...observe }, annotations: ACTION,
+    }, (input) => action('press-key', input, { key: input.key }));
+    server.registerTool('vault_go_computer_hotkey', {
+        description: `Pressiona um atalho com modificadores e uma tecla, ex.: CmdOrCtrl+A, CmdOrCtrl+Shift+P. ${SAFETY}`,
+        inputSchema: { app, key: z.string().trim().min(1).max(100), ...observe }, annotations: ACTION,
+    }, (input) => action('hotkey', input, { key: input.key }));
+}

package/dist/computer-use.d.ts

@@ -0,0 +1,60 @@
+export type CommandOutput = {
+    stdout: string;
+    stderr: string;
+    code: number | null;
+};
+export type CommandRunner = (file: string, args: string[], stdin?: string) => Promise<CommandOutput>;
+export type ComputerUseOptions = {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    home?: string;
+    exists?: (path: string) => boolean;
+    runner?: CommandRunner;
+    readFile?: (path: string) => Buffer;
+    sessionId?: string;
+};
+export type ComputerImage = {
+    data: string;
+    mimeType: 'image/png';
+};
+export type ComputerCallResult = {
+    value: Record<string, unknown>;
+    image: ComputerImage | null;
+};
+export declare function computerUseEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** Finds the Vault Desktop CLI: explicit override, the installed app bundle, then PATH. */
+export declare function resolveDesktopCli(options?: ComputerUseOptions): string | null;
+export declare const defaultRunner: CommandRunner;
+export declare class ComputerUseError extends Error {
+    readonly code: string;
+    readonly nextSteps: string[];
+    constructor(code: string, message: string, nextSteps?: string[]);
+}
+export type Flags = Record<string, string | number | boolean | undefined>;
+/** Runs one `vault-desktop computer <command>` call and returns its JSON result. */
+export declare class ComputerUseBridge {
+    readonly sessionId: string;
+    private readonly options;
+    constructor(options?: ComputerUseOptions);
+    cliPath(): string | null;
+    call(command: string, flags?: Flags, stdin?: string): Promise<ComputerCallResult>;
+    /** Moves screenshot pixels out of the JSON so the client receives an MCP image instead of base64 text. */
+    private extractScreenshot;
+}
+export type TreeQuery = {
+    text?: string | undefined;
+    role?: string | undefined;
+    exact?: boolean | undefined;
+    limit?: number | undefined;
+};
+export type TreeMatch = {
+    index: number;
+    depth: number;
+    line: string;
+};
+export declare function normalizeRole(role: string): string;
+export declare function queryTree(treeText: string, query: TreeQuery): {
+    matches: TreeMatch[];
+    truncated: boolean;
+    visitedNodes: number;
+};

package/dist/computer-use.js

@@ -0,0 +1,205 @@
+// Computer Use by Vault: bridge from MCP to the Vault Desktop native helper through its CLI.
+// The tool surface follows iFurySt/open-computer-use (MIT); input, permissions and the
+// accessibility runtime stay in Vault Desktop so every client shares one signed helper.
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, join } from 'node:path';
+const COMMAND_TIMEOUT_MS = 90_000;
+const MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
+const MAX_SCREENSHOT_BYTES = 20 * 1024 * 1024;
+const MAX_TREE_QUERY_LIMIT = 100;
+const DEFAULT_TREE_QUERY_LIMIT = 20;
+export function computerUseEnabled(env = process.env) {
+    const value = env.VAULT_GO_COMPUTER_USE?.trim().toLowerCase();
+    return !(value === 'off' || value === '0' || value === 'false' || value === 'disabled');
+}
+/** Finds the Vault Desktop CLI: explicit override, the installed app bundle, then PATH. */
+export function resolveDesktopCli(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const home = options.home ?? homedir();
+    const exists = options.exists ?? existsSync;
+    const override = env.VAULT_DESKTOP_CLI?.trim();
+    if (override)
+        return exists(override) ? override : null;
+    const candidates = [];
+    if (platform === 'darwin') {
+        const bundled = 'Vault Desktop.app/Contents/Resources/bin/vault-desktop';
+        candidates.push(join('/Applications', bundled), join(home, 'Applications', bundled));
+    }
+    if (platform === 'win32' && env.LOCALAPPDATA) {
+        const bundled = join('resources', 'bin', 'vault-desktop.exe');
+        candidates.push(join(env.LOCALAPPDATA, 'Programs', 'Vault Desktop', bundled), join(env.LOCALAPPDATA, 'Vault Desktop', bundled));
+    }
+    // Why: only the native .exe launcher on Windows; a .cmd shim would need a shell and let
+    // tool arguments such as an app name be interpreted as shell syntax.
+    const names = platform === 'win32' ? ['vault-desktop.exe'] : ['vault-desktop', 'vault-ide'];
+    for (const dir of (env.PATH ?? '').split(delimiter).filter(Boolean)) {
+        for (const name of names)
+            candidates.push(join(dir, name));
+    }
+    return candidates.find((candidate) => exists(candidate)) ?? null;
+}
+export const defaultRunner = (file, args, stdin) => new Promise((resolve, reject) => {
+    const child = spawn(file, args, { stdio: ['pipe', 'pipe', 'pipe'], shell: false, windowsHide: true });
+    const stdout = [], stderr = [];
+    let size = 0;
+    const timer = setTimeout(() => child.kill('SIGKILL'), COMMAND_TIMEOUT_MS);
+    const collect = (target) => (chunk) => {
+        size += chunk.length;
+        if (size > MAX_OUTPUT_BYTES)
+            child.kill('SIGKILL');
+        else
+            target.push(chunk);
+    };
+    child.stdout.on('data', collect(stdout));
+    child.stderr.on('data', collect(stderr));
+    child.on('error', (error) => { clearTimeout(timer); reject(error); });
+    child.on('close', (code) => {
+        clearTimeout(timer);
+        resolve({ stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8'), code });
+    });
+    child.stdin.end(stdin ?? '');
+});
+export class ComputerUseError extends Error {
+    code;
+    nextSteps;
+    constructor(code, message, nextSteps = []) {
+        super(nextSteps.length ? `${message}\nPróximos passos: ${nextSteps.join(' ')}` : message);
+        this.code = code;
+        this.nextSteps = nextSteps;
+    }
+}
+/** Runs one `vault-desktop computer <command>` call and returns its JSON result. */
+export class ComputerUseBridge {
+    sessionId;
+    options;
+    constructor(options = {}) {
+        this.options = options;
+        this.sessionId = options.sessionId ?? `vault-go-${randomUUID().slice(0, 8)}`;
+    }
+    cliPath() {
+        return resolveDesktopCli(this.options);
+    }
+    async call(command, flags = {}, stdin) {
+        const cli = this.cliPath();
+        if (!cli) {
+            throw new ComputerUseError('desktop_not_found', 'Vault Desktop não foi encontrado nesta máquina.', [
+                'Instale e abra o Vault Desktop (https://vaultmemoryai.com) ou defina VAULT_DESKTOP_CLI com o caminho da CLI vault-desktop.',
+            ]);
+        }
+        const args = ['computer', command, ...flagArgs(flags), '--json'];
+        const output = await (this.options.runner ?? defaultRunner)(cli, args, stdin);
+        const envelope = parseEnvelope(output);
+        if (!envelope.ok) {
+            const error = envelope.error ?? {};
+            const steps = Array.isArray(error.data?.nextSteps) ? error.data.nextSteps.filter((s) => typeof s === 'string') : [];
+            throw new ComputerUseError(typeof error.code === 'string' ? error.code : 'runtime_error', typeof error.message === 'string' ? error.message : 'Falha no Computer Use by Vault.', steps);
+        }
+        const value = envelope.result && typeof envelope.result === 'object' && !Array.isArray(envelope.result) ? { ...envelope.result } : { value: envelope.result };
+        return { value, image: this.extractScreenshot(value) };
+    }
+    /** Moves screenshot pixels out of the JSON so the client receives an MCP image instead of base64 text. */
+    extractScreenshot(value) {
+        const screenshot = value.screenshot;
+        if (!screenshot || typeof screenshot !== 'object')
+            return null;
+        const shot = { ...screenshot };
+        let data = typeof shot.data === 'string' && shot.data ? shot.data : null;
+        if (!data && typeof shot.path === 'string') {
+            try {
+                const bytes = (this.options.readFile ?? readFileSync)(shot.path);
+                if (bytes.length <= MAX_SCREENSHOT_BYTES)
+                    data = bytes.toString('base64');
+            }
+            catch {
+                data = null;
+            }
+        }
+        delete shot.data;
+        delete shot.path;
+        shot.attached = data !== null;
+        value.screenshot = shot;
+        return data ? { data, mimeType: 'image/png' } : null;
+    }
+}
+function flagArgs(flags) {
+    const args = [];
+    for (const [name, value] of Object.entries(flags)) {
+        if (value === undefined || value === false)
+            continue;
+        // Why: `--flag=value` keeps values that start with "--" from being read as flags.
+        args.push(value === true ? `--${name}` : `--${name}=${String(value)}`);
+    }
+    return args;
+}
+function parseEnvelope(output) {
+    const text = output.stdout.trim();
+    const start = text.indexOf('{');
+    if (start >= 0) {
+        try {
+            const parsed = JSON.parse(text.slice(start));
+            if (parsed && typeof parsed === 'object' && typeof parsed.ok === 'boolean')
+                return parsed;
+        }
+        catch {
+            // fall through to the stderr message below
+        }
+    }
+    const detail = (output.stderr.trim() || text).split('\n').slice(0, 5).join(' ').slice(0, 500);
+    if (/not running|ECONNREFUSED|runtime.*unavailable|could not connect/i.test(detail)) {
+        throw new ComputerUseError('desktop_not_running', 'O Vault Desktop não está aberto.', ['Abra o Vault Desktop e tente novamente.']);
+    }
+    throw new ComputerUseError('runtime_error', `A CLI do Vault Desktop respondeu sem JSON (código ${output.code ?? 'desconhecido'}): ${detail || 'sem saída'}`);
+}
+const TREE_LINE = /^(\s*)(\d+)(?:\s+(.*))?$/;
+const LABELLED_SEGMENT = /,\s*(?:Description|Value|Placeholder|Text|Secondary Actions):\s*/;
+export function normalizeRole(role) {
+    return role.trim().replace(/^AX(?=[A-Z])/, '').replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/[_-]+/g, ' ').replace(/\s+/g, ' ').toLowerCase();
+}
+export function queryTree(treeText, query) {
+    const limit = Math.min(query.limit ?? DEFAULT_TREE_QUERY_LIMIT, MAX_TREE_QUERY_LIMIT);
+    const text = query.text?.trim().toLowerCase() ?? '';
+    const role = query.role ? normalizeRole(query.role) : '';
+    const matches = [];
+    let visitedNodes = 0, truncated = false;
+    for (const raw of treeText.split('\n')) {
+        const parsed = TREE_LINE.exec(raw);
+        if (!parsed)
+            continue;
+        visitedNodes += 1;
+        const body = (parsed[3] ?? '').trim();
+        if (role && !startsWithWord(body.toLowerCase(), role))
+            continue;
+        if (text && !matchesText(body, text, query.exact === true))
+            continue;
+        if (matches.length >= limit) {
+            truncated = true;
+            break;
+        }
+        matches.push({ index: Number(parsed[2]), depth: Math.floor((parsed[1] ?? '').replace(/\t/g, '  ').length / 2), line: body });
+    }
+    return { matches, truncated, visitedNodes };
+}
+function startsWithWord(body, prefix) {
+    if (!body.startsWith(prefix))
+        return false;
+    const next = body.charAt(prefix.length);
+    return next === '' || next === ' ' || next === '(' || next === ',';
+}
+function matchesText(body, needle, exact) {
+    if (!exact)
+        return body.toLowerCase().includes(needle);
+    const [head = '', ...rest] = body.split(LABELLED_SEGMENT);
+    if (rest.some((segment) => segment.trim().toLowerCase() === needle))
+        return true;
+    const name = head.trim(), lowered = name.toLowerCase();
+    if (lowered === needle)
+        return true;
+    if (!lowered.endsWith(` ${needle}`))
+        return false;
+    // The head is "<role> (traits) <name>": accept the suffix only after a role-like prefix.
+    return /^[\p{Ll} ]+(?:\([^)]*\))?$/u.test(name.slice(0, name.length - needle.length).trim());
+}

package/dist/server.js

@@ -10,6 +10,7 @@ import { registerCrystalTools } from './crystal-tools.js';
 import { registerModeIntegrations } from './mode-integrations.js';
 import { registerKnowledgeAgentTools } from './knowledge-tools.js';
 import { registerSkillTools } from './skill-tools.js';
+import { registerComputerTools } from './computer-tools.js';
 import { redact } from './hooks.js';
 import { createProjectScope } from './project-scope.js';
 import { VaultCloudClient } from './cloud.js';
@@ -25,6 +26,7 @@ const SERVER_INSTRUCTIONS = [
     'Recall cheaply in layers: vault_go_search_index (compact list) → vault_go_timeline (around one result) → vault_go_observations (full text of the chosen IDs). vault_go_retrieve picks the strategy for a natural-language question.',
     'Before reading a large code file, prefer vault_go_smart_outline and vault_go_smart_unfold, then a Read with offset/limit for exact lines.',
     'Save durable decisions, discoveries and fixes with vault_go_remember. Never store secrets; text inside <private> tags is never stored.',
+    'Computer Use by Vault (vault_go_computer_*) drives local apps through Vault Desktop: get_app_state or query first, then act by elementIndex.',
     'When a tool fails with an expired session, ask the user to run: bunx --bun vault-go@latest login',
 ].join('\n');
 // A saved memory carries its page in the Vault web app, so the agent can hand the user a direct link.
@@ -79,6 +81,7 @@ export function createVaultGoServer(home = vaultHome(), cloud = new VaultCloudCl
     registerCrystalTools(server, home);
     registerKnowledgeAgentTools(server, home, cloud);
     registerSkillTools(server, home, cloud);
+    registerComputerTools(server);
     server.registerTool('vault_go_engines', {
         title: 'Listar motores de contexto',
         description: 'Lista os motores disponíveis para preparar contexto: Vault AI, Claude, OpenRouter, Gemini e ChatGPT/Codex. Não revela chaves.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vault-go",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "MCP server and installer for Vault Memory: search, capture, and use account memory across AI clients.",
   "type": "module",
   "bin": {
@@ -60,6 +60,10 @@
     "dist/crystal-memory-mirror.d.ts",
     "dist/crystal-tools.js",
     "dist/crystal-tools.d.ts",
+    "dist/computer-use.js",
+    "dist/computer-use.d.ts",
+    "dist/computer-tools.js",
+    "dist/computer-tools.d.ts",
     "dist/hook-install.js",
     "dist/hook-install.d.ts",
     "dist/hook-queue.js",