@shykaruu/jarvis-brain 0.4.0

package/src/actions/tools/desktop.ts

@@ -0,0 +1,305 @@
+/**
+ * Desktop Tools — Desktop Automation via Sidecar RPC or Local Execution
+ *
+ * 9 tools for controlling desktop applications. Each tool accepts a `target`
+ * parameter to route to a specific sidecar. Without `target`, attempts local
+ * execution (currently stub — TODO: implement per-platform AppController).
+ * Respects --no-local-tools flag.
+ *
+ * The same tools work on all platforms (Windows, macOS, Linux). The sidecar
+ * handles platform-specific implementation details internally.
+ */
+
+import type { ToolDefinition, ToolResult } from './registry.ts';
+import { routeToSidecar } from './sidecar-route.ts';
+import { isNoLocalTools } from './local-tools-guard.ts';
+
+const LOCAL_NOT_IMPLEMENTED = 'Error: Local desktop tool execution is not yet implemented. Specify a "target" sidecar to route this command to a remote machine, or use list_sidecars to see available sidecars.';
+const LOCAL_DISABLED_MSG = 'Error: Local tool execution is disabled (--no-local-tools). Specify a "target" sidecar to route this command to a remote machine. Use list_sidecars to see available sidecars.';
+
+function localGuard(): string {
+  if (isNoLocalTools()) return LOCAL_DISABLED_MSG;
+  return LOCAL_NOT_IMPLEMENTED;
+}
+
+// --- Tool definitions ---
+
+export const desktopListWindowsTool: ToolDefinition = {
+  name: 'desktop_list_windows',
+  description: 'List all visible windows on the desktop. Returns window titles, PIDs, class names, and positions. Use the PID with other desktop tools to target a specific window.',
+  category: 'desktop',
+  parameters: {
+    target: {
+      type: 'string',
+      description: 'Sidecar name or ID to route this command to (omit for local execution)',
+      required: false,
+    },
+  },
+  execute: async (params) => {
+    const target = params.target as string | undefined;
+    if (target) {
+      return routeToSidecar(target, 'list_windows', params, 'desktop');
+    }
+    return localGuard();
+  },
+};
+
+export const desktopSnapshotTool: ToolDefinition = {
+  name: 'desktop_snapshot',
+  description: 'Get the UI element tree of a window (like browser_snapshot but for desktop apps). Each element has an [id] you can use with desktop_click and desktop_type. If no pid is given, snapshots the active (focused) window.',
+  category: 'desktop',
+  parameters: {
+    target: {
+      type: 'string',
+      description: 'Sidecar name or ID to route this command to (omit for local execution)',
+      required: false,
+    },
+    pid: {
+      type: 'number',
+      description: 'Process ID of the window (from desktop_list_windows). Omit for the active window.',
+      required: false,
+    },
+    depth: {
+      type: 'number',
+      description: 'Max tree depth to walk (default: 8). Decrease for faster but shallower snapshots.',
+      required: false,
+    },
+  },
+  execute: async (params) => {
+    const target = params.target as string | undefined;
+    if (target) {
+      return routeToSidecar(target, 'get_window_tree', params, 'desktop');
+    }
+    return localGuard();
+  },
+};
+
+export const desktopClickTool: ToolDefinition = {
+  name: 'desktop_click',
+  description: 'Click or interact with a UI element by its [id] from the last desktop_snapshot or desktop_find_element. Default action is "click". Use the action parameter for richer interactions like double_click, right_click, invoke, toggle, set_value, expand, etc. Available actions vary by platform.',
+  category: 'desktop',
+  parameters: {
+    target: {
+      type: 'string',
+      description: 'Sidecar name or ID to route this command to (omit for local execution)',
+      required: false,
+    },
+    element_id: {
+      type: 'number',
+      description: 'The [id] of the element to interact with (from desktop_snapshot or desktop_find_element)',
+      required: true,
+    },
+    action: {
+      type: 'string',
+      description: 'Action to perform: click (default), double_click, right_click, invoke, toggle, select, set_value, get_value, get_text, expand, collapse, scroll_into_view, focus',
+      required: false,
+    },
+    value: {
+      type: 'string',
+      description: 'Value to set (only for set_value action)',
+      required: false,
+    },
+  },
+  execute: async (params) => {
+    const target = params.target as string | undefined;
+    if (target) {
+      return routeToSidecar(target, 'click_element', params, 'desktop');
+    }
+    return localGuard();
+  },
+};
+
+export const desktopTypeTool: ToolDefinition = {
+  name: 'desktop_type',
+  description: 'Type text into a UI element. Optionally provide an element_id to click and focus it first. Without element_id, types into whatever is currently focused.',
+  category: 'desktop',
+  parameters: {
+    target: {
+      type: 'string',
+      description: 'Sidecar name or ID to route this command to (omit for local execution)',
+      required: false,
+    },
+    text: {
+      type: 'string',
+      description: 'The text to type',
+      required: true,
+    },
+    element_id: {
+      type: 'number',
+      description: 'Optional [id] of element to click before typing (from desktop_snapshot)',
+      required: false,
+    },
+  },
+  execute: async (params) => {
+    const target = params.target as string | undefined;
+    if (target) {
+      return routeToSidecar(target, 'type_text', params, 'desktop');
+    }
+    return localGuard();
+  },
+};
+
+export const desktopPressKeysTool: ToolDefinition = {
+  name: 'desktop_press_keys',
+  description: 'Press a keyboard shortcut or key combination. Keys are pressed simultaneously (e.g., "ctrl,s" for save, "alt,f4" to close). Single keys also work: "enter", "tab", "escape".',
+  category: 'desktop',
+  parameters: {
+    target: {
+      type: 'string',
+      description: 'Sidecar name or ID to route this command to (omit for local execution)',
+      required: false,
+    },
+    keys: {
+      type: 'string',
+      description: 'Comma-separated key names (e.g., "ctrl,s" or "alt,f4" or "enter"). Modifiers: ctrl, alt, shift, win.',
+      required: true,
+    },
+  },
+  execute: async (params) => {
+    const target = params.target as string | undefined;
+    if (target) {
+      return routeToSidecar(target, 'press_keys', params, 'desktop');
+    }
+    return localGuard();
+  },
+};
+
+export const desktopLaunchAppTool: ToolDefinition = {
+  name: 'desktop_launch_app',
+  description: 'Launch an application by executable path or name (e.g., "notepad.exe", "calc.exe"). Returns the PID of the launched process.',
+  category: 'desktop',
+  parameters: {
+    target: {
+      type: 'string',
+      description: 'Sidecar name or ID to route this command to (omit for local execution)',
+      required: false,
+    },
+    executable: {
+      type: 'string',
+      description: 'Application executable path or name',
+      required: true,
+    },
+    args: {
+      type: 'string',
+      description: 'Optional command-line arguments',
+      required: false,
+    },
+  },
+  execute: async (params) => {
+    const target = params.target as string | undefined;
+    if (target) {
+      return routeToSidecar(target, 'launch_app', params, 'desktop');
+    }
+    return localGuard();
+  },
+};
+
+export const desktopScreenshotTool: ToolDefinition = {
+  name: 'desktop_screenshot',
+  description: 'Take a screenshot of the entire desktop or a specific window. The image is sent directly to the AI for visual analysis. Useful for complex UIs, graphics apps, or when the element tree is insufficient.',
+  category: 'desktop',
+  parameters: {
+    target: {
+      type: 'string',
+      description: 'Sidecar name or ID to route this command to (omit for local execution)',
+      required: false,
+    },
+    pid: {
+      type: 'number',
+      description: 'Process ID of window to capture. Omit for full desktop screenshot.',
+      required: false,
+    },
+  },
+  execute: async (params) => {
+    const target = params.target as string | undefined;
+    if (target) {
+      return routeToSidecar(target, 'capture_screen', params, 'screenshot');
+    }
+    return localGuard();
+  },
+};
+
+export const desktopFocusWindowTool: ToolDefinition = {
+  name: 'desktop_focus_window',
+  description: 'Bring a window to the foreground by its PID (from desktop_list_windows). Use this before interacting with a background window.',
+  category: 'desktop',
+  parameters: {
+    target: {
+      type: 'string',
+      description: 'Sidecar name or ID to route this command to (omit for local execution)',
+      required: false,
+    },
+    pid: {
+      type: 'number',
+      description: 'Process ID of the window to focus',
+      required: true,
+    },
+  },
+  execute: async (params) => {
+    const target = params.target as string | undefined;
+    if (target) {
+      return routeToSidecar(target, 'focus_window', params, 'desktop');
+    }
+    return localGuard();
+  },
+};
+
+export const desktopFindElementTool: ToolDefinition = {
+  name: 'desktop_find_element',
+  description: 'Search for UI elements by property (name, control type, class name, automation ID). Returns matching elements with [id] for use with desktop_click and desktop_type. Useful when you know what you are looking for without scanning the full tree.',
+  category: 'desktop',
+  parameters: {
+    target: {
+      type: 'string',
+      description: 'Sidecar name or ID to route this command to (omit for local execution)',
+      required: false,
+    },
+    pid: {
+      type: 'number',
+      description: 'Process ID of the window. Omit for the foreground window.',
+      required: false,
+    },
+    name: {
+      type: 'string',
+      description: 'Element name to search for (exact match)',
+      required: false,
+    },
+    control_type: {
+      type: 'string',
+      description: 'Control type to filter by (e.g., Button, Edit, Text, ComboBox, ListItem, TreeItem, MenuItem, Tab)',
+      required: false,
+    },
+    automation_id: {
+      type: 'string',
+      description: 'AutomationId to search for (Windows only, ignored on other platforms)',
+      required: false,
+    },
+    class_name: {
+      type: 'string',
+      description: 'Class name to search for',
+      required: false,
+    },
+  },
+  execute: async (params) => {
+    const target = params.target as string | undefined;
+    if (target) {
+      return routeToSidecar(target, 'find_element', params, 'desktop');
+    }
+    return localGuard();
+  },
+};
+
+/**
+ * All desktop tools in a single array — platform-agnostic.
+ */
+export const DESKTOP_TOOLS: ToolDefinition[] = [
+  desktopListWindowsTool,
+  desktopSnapshotTool,
+  desktopClickTool,
+  desktopTypeTool,
+  desktopPressKeysTool,
+  desktopLaunchAppTool,
+  desktopScreenshotTool,
+  desktopFocusWindowTool,
+  desktopFindElementTool,
+];

package/src/actions/tools/documents.ts

@@ -0,0 +1,169 @@
+/**
+ * Document Tool
+ *
+ * Allows the agent to create, read, update, and list documents stored
+ * in the vault. Use this instead of write_file when creating reports,
+ * plans, analyses, or any document the user should be able to download.
+ *
+ * Returns a document marker that the dashboard renders as a card with
+ * a download button.
+ */
+
+import type { ToolDefinition } from './registry.ts';
+import type { DocumentFormat } from '../../vault/documents.ts';
+import {
+  createDocument, getDocument, findDocuments, updateDocument, deleteDocument,
+} from '../../vault/documents.ts';
+
+export const documentTool: ToolDefinition = {
+  name: 'create_document',
+  description: [
+    'Create, read, update, or list documents stored in the vault.',
+    'Use this tool instead of write_file when producing reports, plans, analyses,',
+    'guides, summaries, or any document the user may want to download.',
+    '',
+    'Actions:',
+    '  create — Create a new document (returns a preview card in chat)',
+    '  get    — Read a document by ID',
+    '  list   — List all documents, optionally filtered',
+    '  update — Update an existing document',
+    '  append — Append text to an existing document (for long content)',
+    '  delete — Delete a document',
+    '',
+    'Formats: markdown, plain, html, json, csv, code',
+    '',
+    'IMPORTANT: For long documents, use create first with the initial section,',
+    'then use append to add remaining sections. This prevents token truncation.',
+    '',
+    'When you create a document, a download card is shown to the user in chat.',
+  ].join('\n'),
+  category: 'documents',
+  parameters: {
+    action: {
+      type: 'string',
+      description: 'The action: create, get, list, update, append, delete',
+      required: true,
+    },
+    id: {
+      type: 'string',
+      description: 'Document ID (required for get, update, append, delete)',
+      required: false,
+    },
+    title: {
+      type: 'string',
+      description: 'Document title (required for create, optional for update)',
+      required: false,
+    },
+    body: {
+      type: 'string',
+      description: 'Document content. For create/update: full body. For append: text to add.',
+      required: false,
+    },
+    format: {
+      type: 'string',
+      description: 'Document format: markdown (default), plain, html, json, csv, code',
+      required: false,
+    },
+    tags: {
+      type: 'string',
+      description: 'Comma-separated tags for create/update/filter',
+      required: false,
+    },
+    search: {
+      type: 'string',
+      description: 'Search term for list action (searches title and body)',
+      required: false,
+    },
+  },
+  execute: async (params) => {
+    const action = params.action as string;
+
+    switch (action) {
+      case 'create': {
+        if (!params.title) return 'Error: "title" is required for create action';
+        const tags = params.tags ? (params.tags as string).split(',').map(t => t.trim()) : undefined;
+        const doc = createDocument(
+          params.title as string,
+          (params.body as string) ?? '',
+          {
+            format: (params.format as DocumentFormat) ?? 'markdown',
+            tags,
+          },
+        );
+        // Return the document marker + preview for the chat UI
+        const preview = doc.body.length > 200 ? doc.body.slice(0, 200) + '...' : doc.body;
+        return [
+          `Document created: "${doc.title}" (${doc.format}, ${doc.body.length} chars)`,
+          '',
+          `<!-- jarvis:document id="${doc.id}" title="${doc.title}" format="${doc.format}" size="${doc.body.length}" -->`,
+          '',
+          preview ? `Preview:\n${preview}` : '',
+        ].filter(Boolean).join('\n');
+      }
+
+      case 'get': {
+        if (!params.id) return 'Error: "id" is required for get action';
+        const doc = getDocument(params.id as string);
+        if (!doc) return `Document not found: ${params.id}`;
+        return [
+          `Title: ${doc.title}`,
+          `Format: ${doc.format}`,
+          `Tags: ${doc.tags.join(', ') || 'none'}`,
+          `Size: ${doc.body.length} chars`,
+          `Created: ${new Date(doc.created_at).toLocaleString()}`,
+          `Updated: ${new Date(doc.updated_at).toLocaleString()}`,
+          '',
+          '--- Content ---',
+          doc.body || '(empty)',
+        ].join('\n');
+      }
+
+      case 'list': {
+        const query: { format?: DocumentFormat; tag?: string; search?: string } = {};
+        if (params.format) query.format = params.format as DocumentFormat;
+        if (params.tags) query.tag = params.tags as string;
+        if (params.search) query.search = params.search as string;
+        const docs = findDocuments(Object.keys(query).length > 0 ? query : undefined);
+        if (docs.length === 0) return 'No documents found.';
+        return docs.map(d =>
+          `[${d.id}] "${d.title}" (${d.format}, ${d.body.length} chars) — tags: ${d.tags.join(', ') || 'none'}, updated: ${new Date(d.updated_at).toLocaleString()}`
+        ).join('\n');
+      }
+
+      case 'update': {
+        if (!params.id) return 'Error: "id" is required for update action';
+        const updates: Record<string, unknown> = {};
+        if (params.title !== undefined) updates.title = params.title;
+        if (params.body !== undefined) updates.body = params.body;
+        if (params.format !== undefined) updates.format = params.format;
+        if (params.tags !== undefined) {
+          updates.tags = (params.tags as string).split(',').map(t => t.trim());
+        }
+        const updated = updateDocument(params.id as string, updates);
+        if (!updated) return `Document not found: ${params.id}`;
+        return `Updated: "${updated.title}" — ${updated.body.length} chars`;
+      }
+
+      case 'append': {
+        if (!params.id) return 'Error: "id" is required for append action';
+        if (!params.body) return 'Error: "body" is required for append action (the text to append)';
+        const existing = getDocument(params.id as string);
+        if (!existing) return `Document not found: ${params.id}`;
+        const newBody = existing.body + (existing.body ? '\n\n' : '') + (params.body as string);
+        const updated = updateDocument(params.id as string, { body: newBody });
+        if (!updated) return 'Failed to append to document';
+        return `Appended ${(params.body as string).length} chars. Total: ${updated.body.length} chars for "${updated.title}"`;
+      }
+
+      case 'delete': {
+        if (!params.id) return 'Error: "id" is required for delete action';
+        const deleted = deleteDocument(params.id as string);
+        if (!deleted) return `Document not found: ${params.id}`;
+        return 'Document deleted.';
+      }
+
+      default:
+        return `Unknown action: "${action}". Valid actions: create, get, list, update, append, delete`;
+    }
+  },
+};