@shykaruu/jarvis-brain 0.4.0

package/src/roles/tool-guide.ts

@@ -0,0 +1,195 @@
+/**
+ * Tool Guide — Static reference for the AI
+ *
+ * Explains all available tools and how to use them.
+ * Update this file whenever tools are added or changed.
+ *
+ * When `hasSidecars` is false, sidecar-related content (target params,
+ * list_sidecars, sidecar section) is omitted entirely so the AI
+ * doesn't waste tokens thinking about remote execution.
+ */
+
+export function buildToolGuide(hasSidecars: boolean): string {
+  const lines: string[] = [];
+
+  lines.push('# Tool Guide');
+  lines.push('');
+
+  // --- Tools ---
+  lines.push('## Tools');
+  lines.push('');
+
+  if (hasSidecars) {
+    lines.push('These tools work locally by default. To run on a remote machine, pass the `target` parameter with a sidecar name or ID.');
+    lines.push('');
+  }
+
+  lines.push('### run_command');
+  lines.push('Execute a shell command. Returns stdout, stderr, and exit code.');
+  lines.push('- `command` (required): The shell command to run');
+  if (hasSidecars) lines.push('- `target`: Sidecar name or ID for remote execution');
+  lines.push('- `cwd`: Working directory');
+  lines.push('- `timeout`: Timeout in ms (default: 30000)');
+  lines.push('');
+
+  lines.push('### read_file');
+  lines.push('Read a file\'s contents as text (max 100KB).');
+  lines.push('- `path` (required): File path');
+  if (hasSidecars) lines.push('- `target`: Sidecar name or ID for remote execution');
+  lines.push('');
+
+  lines.push('### write_file');
+  lines.push('Write content to a file (creates or overwrites).');
+  lines.push('- `path` (required): File path');
+  lines.push('- `content` (required): Content to write');
+  if (hasSidecars) lines.push('- `target`: Sidecar name or ID for remote execution');
+  lines.push('');
+
+  lines.push('### list_directory');
+  lines.push('List directory contents with types and sizes.');
+  lines.push('- `path` (required): Directory path');
+  if (hasSidecars) lines.push('- `target`: Sidecar name or ID for remote execution');
+  lines.push('');
+
+  lines.push('### get_clipboard');
+  lines.push('Read the clipboard contents.');
+  if (hasSidecars) lines.push('- `target`: Sidecar name or ID for remote execution');
+  lines.push('');
+
+  lines.push('### set_clipboard');
+  lines.push('Write text to the clipboard.');
+  lines.push('- `content` (required): Text to write');
+  if (hasSidecars) lines.push('- `target`: Sidecar name or ID for remote execution');
+  lines.push('');
+
+  lines.push('### capture_screen');
+  lines.push('Take a screenshot of the screen. Returns base64-encoded PNG.');
+  if (hasSidecars) lines.push('- `target`: Sidecar name or ID for remote execution');
+  lines.push('');
+
+  lines.push('### get_system_info');
+  lines.push('Get system information (hostname, OS, architecture, CPU count).');
+  if (hasSidecars) lines.push('- `target`: Sidecar name or ID for remote execution');
+  lines.push('');
+
+  // --- Browser ---
+  lines.push('## Browser');
+  lines.push('');
+  lines.push('Control a Chrome browser for web research and interaction. Chrome auto-launches on first use. A persistent profile at ~/.jarvis/browser/profile retains login sessions.');
+  lines.push('');
+  lines.push('Workflow:');
+  lines.push('1. `browser_navigate` to a URL — returns page text + interactive elements with [id] numbers');
+  lines.push('2. `browser_click` / `browser_type` to interact using element [id]s');
+  lines.push('3. `browser_snapshot` to see the page after an action');
+  lines.push('4. `browser_scroll` to reveal content below the fold');
+  lines.push('5. `browser_evaluate` for advanced JavaScript interactions');
+  lines.push('6. `browser_screenshot` for visual capture');
+  lines.push('');
+  lines.push('### browser_upload_file');
+  lines.push('Upload a file to a file input element (bypasses the native file picker). Use this after clicking an upload/attach button.');
+  lines.push('- `file_path` (required): Absolute path to the file');
+  lines.push('- `selector`: CSS selector for the file input (default: first input[type="file"])');
+  lines.push('');
+  lines.push('Rules:');
+  lines.push('- For READ-ONLY tasks, `browser_navigate` already returns content. Don\'t snapshot just to read.');
+  lines.push('- For INTERACTIVE tasks, snapshot after each action to verify.');
+  lines.push('- Fill forms FIRST, verify in snapshot, THEN submit.');
+  lines.push('- If an element isn\'t visible, scroll down first.');
+  lines.push('- Modern SPAs may need `browser_evaluate` for custom components.');
+  lines.push('');
+
+  // --- Sidecars ---
+  if (hasSidecars) {
+    lines.push('## Sidecars (Remote Machines)');
+    lines.push('');
+    lines.push('Sidecars are the user\'s other machines (laptops, servers, desktops) connected to the brain. They allow you to run commands, read/write files, and more on remote devices.');
+    lines.push('');
+    lines.push('### How to use sidecars');
+    lines.push('1. Call `list_sidecars` to see which machines are available and their connection status');
+    lines.push('2. Use any compatible tool with the `target` parameter set to the sidecar\'s name or ID');
+    lines.push('3. If the sidecar is offline or doesn\'t support the required capability, you\'ll get a clear error');
+    lines.push('');
+    lines.push('### list_sidecars');
+    lines.push('Query live sidecar status. Always call this before targeting a remote machine.');
+    lines.push('- `filter`: Optional string to filter by name or ID (case-insensitive)');
+    lines.push('- Returns: connection status, hostname, OS, capabilities, last seen time');
+    lines.push('');
+    lines.push('### Capabilities');
+    lines.push('Each sidecar advertises what it can do:');
+    lines.push('- `terminal` — supports `run_command`');
+    lines.push('- `filesystem` — supports `read_file`, `write_file`, `list_directory`');
+    lines.push('- `clipboard` — supports `get_clipboard`, `set_clipboard`');
+    lines.push('- `screenshot` — supports `capture_screen`');
+    lines.push('- `system_info` — supports `get_system_info`');
+    lines.push('- `desktop`, `browser` — supports desktop/browser automation tools');
+    lines.push('');
+    lines.push('If a capability is listed as unavailable (with a reason), do NOT try to work around it with `run_command`. The required system tool is missing and shell commands will fail the same way.');
+    lines.push('');
+    lines.push('### Example workflow');
+    lines.push('User: "Check disk space on my server"');
+    lines.push('1. Call `list_sidecars` → see "home-server" is CONNECTED with terminal capability');
+    lines.push('2. Call `run_command` with target="home-server", command="df -h"');
+    lines.push('3. Report results to user');
+    lines.push('');
+  }
+
+  // --- Desktop ---
+  lines.push('## Desktop Automation');
+  lines.push('');
+  lines.push('Control desktop applications on any platform (Windows, macOS, Linux). Works like browser tools but for native desktop apps. The same tools work on all platforms — the sidecar handles OS-specific details internally.');
+  lines.push('');
+  lines.push('Workflow:');
+  lines.push('1. `desktop_list_windows` to see available windows with PIDs');
+  lines.push('2. `desktop_snapshot` to get the UI element tree with [id] numbers (like browser_snapshot)');
+  lines.push('3. `desktop_click` / `desktop_type` to interact using element [id]s');
+  lines.push('4. `desktop_snapshot` again to verify the result');
+  lines.push('');
+  lines.push('Tools:');
+  lines.push('- `desktop_list_windows` — list all visible windows (titles, PIDs, positions)');
+  lines.push('- `desktop_snapshot` — get the UI element tree of a window. Each element has an [id]. Optional `depth` param to control tree depth (default: 8).');
+  lines.push('- `desktop_click` — click or interact with an element by [id]. Optional `action` param: click (default), double_click, right_click, invoke, toggle, set_value, get_value, expand, collapse, focus. Optional `value` param for set_value.');
+  lines.push('- `desktop_type` — type text into the focused element. Optional `element_id` to click-focus first.');
+  lines.push('- `desktop_press_keys` — press key combos (e.g., "ctrl,s", "alt,f4", "enter")');
+  lines.push('- `desktop_find_element` — search for elements by property (name, control_type, class_name, automation_id) without scanning the full tree');
+  lines.push('- `desktop_launch_app` — launch an application by name or path');
+  lines.push('- `desktop_focus_window` — bring a window to the foreground by PID');
+  lines.push('- `desktop_screenshot` — visual capture of the desktop or a specific window');
+  lines.push('');
+  lines.push('Rules:');
+  lines.push('- Always `desktop_list_windows` first to get the PID, then `desktop_snapshot` with that PID.');
+  lines.push('- After clicking or typing, snapshot again to verify the updated state.');
+  lines.push('- Use `desktop_find_element` when you know the element name/type — faster than scanning the full tree.');
+  lines.push('- The `action` param on `desktop_click` supports richer interactions on Windows (invoke, toggle, set_value, expand, collapse). On macOS/Linux, only click, double_click, right_click, and focus are supported.');
+  lines.push('- `automation_id` in `desktop_find_element` is Windows-only; it is ignored on other platforms.');
+  lines.push('');
+
+  // --- Task Management ---
+  lines.push('## Task Management');
+  lines.push('');
+  lines.push('### manage_goals');
+  lines.push('OKR-style goal management (create, list, score, decompose, morning plan, evening review).');
+  lines.push('');
+  lines.push('### manage_workflow');
+  lines.push('Create and run automation workflows from natural language.');
+  lines.push('');
+  lines.push('### delegate_task');
+  lines.push('Send a task to a specialist sub-agent (research analyst, software engineer, etc.). The specialist works independently and returns results.');
+  lines.push('');
+  lines.push('### manage_agents');
+  lines.push('Manage persistent background agents for long-running tasks.');
+  lines.push('');
+
+  // --- Other ---
+  lines.push('## Other Tools');
+  lines.push('');
+  lines.push('### research_queue');
+  lines.push('Queue topics for background research during idle time.');
+  lines.push('');
+  lines.push('### commitments');
+  lines.push('Track promises and tasks with due dates.');
+  lines.push('');
+  lines.push('### content_pipeline');
+  lines.push('Manage content items through drafting stages.');
+
+  return lines.join('\n');
+}

package/src/roles/types.ts

@@ -0,0 +1,36 @@
+export type KPI = {
+  name: string;
+  metric: string;
+  target: string;
+  check_interval: string;
+};
+
+export type CommunicationStyle = {
+  tone: string;
+  verbosity: 'concise' | 'detailed' | 'adaptive';
+  formality: 'formal' | 'casual' | 'adaptive';
+};
+
+export type SubRoleTemplate = {
+  role_id: string;
+  name: string;
+  description: string;
+  spawned_by: string;
+  reports_to: string;
+  max_budget_per_task: number;
+};
+
+export type RoleDefinition = {
+  id: string;
+  name: string;
+  description: string;
+  responsibilities: string[];
+  autonomous_actions: string[];
+  approval_required: string[];
+  kpis: KPI[];
+  communication_style: CommunicationStyle;
+  heartbeat_instructions: string;
+  sub_roles: SubRoleTemplate[];
+  tools: string[];
+  authority_level: number;  // 1-10
+};

package/src/roles/utils.ts

@@ -0,0 +1,200 @@
+/**
+ * Utility functions for working with roles
+ */
+
+import type { RoleDefinition } from './types.ts';
+import type { ActionCategory } from './authority.ts';
+import { canPerform, listAllowedActions } from './authority.ts';
+
+/**
+ * Find roles that can perform a specific action
+ */
+export function findRolesWithPermission(
+  roles: Map<string, RoleDefinition>,
+  action: ActionCategory
+): RoleDefinition[] {
+  const result: RoleDefinition[] = [];
+
+  for (const role of roles.values()) {
+    if (canPerform(role, action)) {
+      result.push(role);
+    }
+  }
+
+  return result.sort((a, b) => a.authority_level - b.authority_level);
+}
+
+/**
+ * Find the least privileged role that can perform an action
+ */
+export function findMinimalRoleForAction(
+  roles: Map<string, RoleDefinition>,
+  action: ActionCategory
+): RoleDefinition | null {
+  const capable = findRolesWithPermission(roles, action);
+  return capable.length > 0 ? capable[0]! : null;
+}
+
+/**
+ * Compare two roles and show permission differences
+ */
+export function compareRoles(
+  role1: RoleDefinition,
+  role2: RoleDefinition
+): {
+  onlyInRole1: ActionCategory[];
+  onlyInRole2: ActionCategory[];
+  inBoth: ActionCategory[];
+} {
+  const actions1 = new Set(listAllowedActions(role1));
+  const actions2 = new Set(listAllowedActions(role2));
+
+  const onlyInRole1: ActionCategory[] = [];
+  const onlyInRole2: ActionCategory[] = [];
+  const inBoth: ActionCategory[] = [];
+
+  for (const action of actions1) {
+    if (actions2.has(action)) {
+      inBoth.push(action);
+    } else {
+      onlyInRole1.push(action);
+    }
+  }
+
+  for (const action of actions2) {
+    if (!actions1.has(action)) {
+      onlyInRole2.push(action);
+    }
+  }
+
+  return { onlyInRole1, onlyInRole2, inBoth };
+}
+
+/**
+ * Get a summary of role hierarchy based on authority levels
+ */
+export function getRoleHierarchy(roles: Map<string, RoleDefinition>): string {
+  const sorted = Array.from(roles.values()).sort(
+    (a, b) => b.authority_level - a.authority_level
+  );
+
+  const lines: string[] = [];
+  let currentLevel = -1;
+
+  for (const role of sorted) {
+    if (role.authority_level !== currentLevel) {
+      currentLevel = role.authority_level;
+      lines.push(`\nLevel ${currentLevel}:`);
+    }
+    lines.push(`  - ${role.name} (${role.id})`);
+  }
+
+  return lines.join('\n').trim();
+}
+
+/**
+ * Check if a role can spawn a specific sub-role
+ */
+export function canSpawnRole(
+  role: RoleDefinition,
+  subRoleId: string
+): boolean {
+  return role.sub_roles.some(sr => sr.role_id === subRoleId);
+}
+
+/**
+ * Get all roles that can spawn a specific role
+ */
+export function findSpawnersOfRole(
+  roles: Map<string, RoleDefinition>,
+  targetRoleId: string
+): RoleDefinition[] {
+  const spawners: RoleDefinition[] = [];
+
+  for (const role of roles.values()) {
+    if (canSpawnRole(role, targetRoleId)) {
+      spawners.push(role);
+    }
+  }
+
+  return spawners;
+}
+
+/**
+ * Validate role hierarchy (check for circular dependencies)
+ */
+export function validateRoleHierarchy(
+  roles: Map<string, RoleDefinition>
+): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  for (const [id, role] of roles) {
+    // Check if sub-roles exist
+    for (const subRole of role.sub_roles) {
+      if (!roles.has(subRole.role_id)) {
+        errors.push(
+          `Role '${id}' references non-existent sub-role '${subRole.role_id}'`
+        );
+      }
+
+      // Check for self-spawning
+      if (subRole.role_id === id) {
+        errors.push(`Role '${id}' attempts to spawn itself`);
+      }
+
+      // Check authority levels (parent should have higher authority)
+      const subRoleDef = roles.get(subRole.role_id);
+      if (subRoleDef && subRoleDef.authority_level > role.authority_level) {
+        errors.push(
+          `Role '${id}' (level ${role.authority_level}) attempts to spawn ` +
+          `'${subRole.role_id}' (level ${subRoleDef.authority_level}) with higher authority`
+        );
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Get statistics about a role collection
+ */
+export function getRoleStats(roles: Map<string, RoleDefinition>): {
+  totalRoles: number;
+  averageAuthorityLevel: number;
+  totalTools: number;
+  totalKPIs: number;
+  rolesWithSubRoles: number;
+  authorityDistribution: Record<number, number>;
+} {
+  let totalAuthority = 0;
+  let totalTools = 0;
+  let totalKPIs = 0;
+  let rolesWithSubRoles = 0;
+  const authorityDistribution: Record<number, number> = {};
+
+  for (const role of roles.values()) {
+    totalAuthority += role.authority_level;
+    totalTools += role.tools.length;
+    totalKPIs += role.kpis.length;
+
+    if (role.sub_roles.length > 0) {
+      rolesWithSubRoles++;
+    }
+
+    authorityDistribution[role.authority_level] =
+      (authorityDistribution[role.authority_level] || 0) + 1;
+  }
+
+  return {
+    totalRoles: roles.size,
+    averageAuthorityLevel: roles.size > 0 ? totalAuthority / roles.size : 0,
+    totalTools,
+    totalKPIs,
+    rolesWithSubRoles,
+    authorityDistribution,
+  };
+}

package/src/scripts/google-setup.ts

@@ -0,0 +1,168 @@
+/**
+ * Google OAuth2 Setup Script
+ *
+ * Interactive CLI to authenticate JARVIS with Google APIs.
+ * Opens browser to Google consent screen, handles callback,
+ * and saves tokens to ~/.jarvis/google-tokens.json.
+ *
+ * Usage: bun run src/scripts/google-setup.ts
+ */
+
+import { GoogleAuth } from '../integrations/google-auth.ts';
+import { loadConfig } from '../config/loader.ts';
+
+const SCOPES = [
+  'https://www.googleapis.com/auth/gmail.readonly',
+  'https://www.googleapis.com/auth/calendar.readonly',
+];
+
+async function main() {
+  console.log('');
+  console.log('=== Google OAuth2 Setup for JARVIS ===');
+  console.log('');
+
+  // Load config to get client_id / client_secret
+  const config = await loadConfig();
+
+  let clientId = config.google?.client_id ?? '';
+  let clientSecret = config.google?.client_secret ?? '';
+
+  if (!clientId || !clientSecret) {
+    console.log('No Google OAuth credentials found in config.yaml.');
+    console.log('');
+    console.log('Add the following to your ~/.jarvis/config.yaml:');
+    console.log('');
+    console.log('google:');
+    console.log('  client_id: "your-client-id.apps.googleusercontent.com"');
+    console.log('  client_secret: "your-client-secret"');
+    console.log('');
+    console.log('To get credentials:');
+    console.log('  1. Go to https://console.cloud.google.com/apis/credentials');
+    console.log('  2. Create an OAuth2 client ID (Web application)');
+    console.log('  3. Add http://localhost:3142/api/auth/google/callback as a redirect URI');
+    console.log('  4. Copy client_id and client_secret into config.yaml');
+    console.log('');
+
+    // Try reading from stdin
+    const rl = require('readline').createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    const ask = (q: string): Promise<string> =>
+      new Promise((resolve) => rl.question(q, resolve));
+
+    clientId = (await ask('Client ID (or press Enter to abort): ')).trim();
+    if (!clientId) {
+      console.log('Aborted.');
+      rl.close();
+      process.exit(1);
+    }
+
+    clientSecret = (await ask('Client Secret: ')).trim();
+    if (!clientSecret) {
+      console.log('Aborted.');
+      rl.close();
+      process.exit(1);
+    }
+
+    rl.close();
+  }
+
+  const auth = new GoogleAuth(clientId, clientSecret);
+
+  // Check if already authenticated
+  if (auth.isAuthenticated()) {
+    console.log('Already authenticated! Tokens exist at ~/.jarvis/google-tokens.json');
+    console.log('To re-authenticate, delete that file and run this again.');
+    process.exit(0);
+  }
+
+  const authUrl = auth.getAuthUrl(SCOPES);
+
+  console.log('');
+  console.log('Opening browser for Google authorization...');
+  console.log('');
+  console.log('If the browser does not open, visit this URL:');
+  console.log(authUrl);
+  console.log('');
+
+  // Try to open browser
+  try {
+    const opener = process.platform === 'darwin'
+      ? 'open'
+      : process.platform === 'win32'
+        ? 'start'
+        : 'xdg-open';
+    Bun.spawn([opener, authUrl], { stdout: 'ignore', stderr: 'ignore' });
+  } catch {
+    // Ignore — user can open manually
+  }
+
+  // Start temporary HTTP server to receive the callback
+  console.log('Waiting for authorization callback on port 3142...');
+  console.log('');
+
+  const server = Bun.serve({
+    port: 3142,
+    async fetch(req) {
+      const url = new URL(req.url);
+
+      if (url.pathname === '/api/auth/google/callback') {
+        const code = url.searchParams.get('code');
+        const error = url.searchParams.get('error');
+
+        if (error) {
+          console.error('Authorization denied:', error);
+          setTimeout(() => {
+            server.stop();
+            process.exit(1);
+          }, 500);
+          return new Response(
+            '<html><body><h1>Authorization Denied</h1><p>You can close this tab.</p></body></html>',
+            { headers: { 'Content-Type': 'text/html' } }
+          );
+        }
+
+        if (!code) {
+          return new Response('Missing code', { status: 400 });
+        }
+
+        try {
+          const tokens = await auth.exchangeCode(code);
+          console.log('Authorization successful!');
+          console.log(`Access token: ${tokens.access_token.slice(0, 20)}...`);
+          console.log(`Refresh token: ${tokens.refresh_token.slice(0, 20)}...`);
+          console.log(`Tokens saved to ~/.jarvis/google-tokens.json`);
+
+          setTimeout(() => {
+            server.stop();
+            process.exit(0);
+          }, 500);
+
+          return new Response(
+            '<html><body><h1>JARVIS Google Authorization Complete!</h1><p>Tokens saved. You can close this tab.</p></body></html>',
+            { headers: { 'Content-Type': 'text/html' } }
+          );
+        } catch (err) {
+          console.error('Token exchange failed:', err);
+          setTimeout(() => {
+            server.stop();
+            process.exit(1);
+          }, 500);
+          return new Response(
+            `<html><body><h1>Token Exchange Failed</h1><pre>${err}</pre></body></html>`,
+            { headers: { 'Content-Type': 'text/html' }, status: 500 }
+          );
+        }
+      }
+
+      return new Response('Not found', { status: 404 });
+    },
+  });
+}
+
+main().catch((err) => {
+  console.error('Setup failed:', err);
+  process.exit(1);
+});