@usejarvis/brain 0.1.0

package/src/roles/test-role.yaml

@@ -0,0 +1,77 @@
+id: executive_assistant
+name: Executive Assistant
+description: A highly capable AI assistant that manages your schedule, communications, and daily tasks with proactive intelligence.
+
+responsibilities:
+  - Monitor user's calendar and proactively suggest optimizations
+  - Draft and send emails on behalf of the user (with approval)
+  - Track commitments and follow up on pending tasks
+  - Provide daily briefings and summaries
+  - Research topics and prepare reports
+
+autonomous_actions:
+  - Read calendar events and emails
+  - Send routine status updates to the user
+  - Create calendar events for routine activities
+  - Log observations and track user preferences
+  - Search for information and compile summaries
+
+approval_required:
+  - Send emails to external contacts
+  - Make purchases or financial commitments
+  - Modify important settings or configurations
+  - Delete important data
+  - Cancel or reschedule important meetings
+
+kpis:
+  - name: Response Time
+    metric: Average time to respond to user requests
+    target: < 30 seconds
+    check_interval: daily
+  - name: Task Completion Rate
+    metric: Percentage of assigned tasks completed
+    target: "> 95%"
+    check_interval: weekly
+  - name: Proactive Suggestions
+    metric: Number of helpful suggestions made per day
+    target: "> 5"
+    check_interval: daily
+
+communication_style:
+  tone: Professional yet warm, with occasional wit
+  verbosity: adaptive
+  formality: adaptive
+
+heartbeat_instructions: |
+  Every hour, check:
+  1. Upcoming calendar events in the next 2 hours
+  2. Unread high-priority emails
+  3. Pending tasks approaching their deadlines
+  4. Any commitments that need follow-up
+
+  If you find anything requiring attention, proactively notify the user.
+  Always include context and suggested actions.
+
+sub_roles:
+  - role_id: research_specialist
+    name: Research Specialist
+    description: Deep-dive researcher for complex topics
+    spawned_by: executive_assistant
+    reports_to: executive_assistant
+    max_budget_per_task: 100
+  - role_id: email_specialist
+    name: Email Specialist
+    description: Handles email triage and drafting
+    spawned_by: executive_assistant
+    reports_to: executive_assistant
+    max_budget_per_task: 50
+
+tools:
+  - calendar_access
+  - email_access
+  - web_search
+  - document_creation
+  - note_taking
+  - reminder_system
+
+authority_level: 6

package/src/roles/test-utils.ts

@@ -0,0 +1,93 @@
+#!/usr/bin/env bun
+/**
+ * Test utility functions
+ */
+
+import {
+  loadRolesFromDir,
+  findRolesWithPermission,
+  findMinimalRoleForAction,
+  compareRoles,
+  getRoleHierarchy,
+  validateRoleHierarchy,
+  getRoleStats,
+  findSpawnersOfRole,
+} from './index.ts';
+
+console.log('🧪 Testing Role Utility Functions\n');
+
+// Load roles
+import { join } from 'path';
+const roles = loadRolesFromDir(join(import.meta.dir, '../../roles'));
+console.log(`✅ Loaded ${roles.size} roles\n`);
+
+// Test 1: Find roles with specific permission
+console.log('Test 1: Find roles that can execute commands');
+const execRoles = findRolesWithPermission(roles, 'execute_command');
+console.log(`Found ${execRoles.length} roles:`);
+execRoles.forEach(r => console.log(`  - ${r.name} (level ${r.authority_level})`));
+
+// Test 2: Find minimal role for action
+console.log('\nTest 2: Find least privileged role that can send email');
+const minRole = findMinimalRoleForAction(roles, 'send_email');
+if (minRole) {
+  console.log(`  ✅ ${minRole.name} (level ${minRole.authority_level})`);
+} else {
+  console.log('  ❌ No role can send email');
+}
+
+// Test 3: Compare two roles
+console.log('\nTest 3: Compare Executive Assistant vs Research Specialist');
+const exec = roles.get('executive_assistant');
+const research = roles.get('research_specialist');
+
+if (exec && research) {
+  const comparison = compareRoles(exec, research);
+  console.log(`  Only ${exec.name}:`);
+  comparison.onlyInRole1.forEach(a => console.log(`    - ${a}`));
+  console.log(`  Only ${research.name}:`);
+  comparison.onlyInRole2.forEach(a => console.log(`    - ${a}`));
+  console.log(`  Both roles:`);
+  comparison.inBoth.forEach(a => console.log(`    - ${a}`));
+}
+
+// Test 4: Role hierarchy
+console.log('\nTest 4: Role hierarchy by authority level');
+console.log(getRoleHierarchy(roles));
+
+// Test 5: Validate hierarchy
+console.log('\nTest 5: Validate role hierarchy');
+const validation = validateRoleHierarchy(roles);
+if (validation.valid) {
+  console.log('  ✅ Role hierarchy is valid');
+} else {
+  console.log('  ❌ Hierarchy errors:');
+  validation.errors.forEach(e => console.log(`    - ${e}`));
+}
+
+// Test 6: Find spawners
+console.log('\nTest 6: Find roles that can spawn research_specialist');
+const spawners = findSpawnersOfRole(roles, 'research_specialist');
+if (spawners.length > 0) {
+  console.log(`  Found ${spawners.length} spawner(s):`);
+  spawners.forEach(r => console.log(`    - ${r.name}`));
+} else {
+  console.log('  No roles can spawn research_specialist');
+}
+
+// Test 7: Statistics
+console.log('\nTest 7: Role collection statistics');
+const stats = getRoleStats(roles);
+console.log(`  Total roles: ${stats.totalRoles}`);
+console.log(`  Average authority level: ${stats.averageAuthorityLevel.toFixed(1)}`);
+console.log(`  Total tools: ${stats.totalTools}`);
+console.log(`  Total KPIs: ${stats.totalKPIs}`);
+console.log(`  Roles with sub-roles: ${stats.rolesWithSubRoles}`);
+console.log('  Authority distribution:');
+Object.entries(stats.authorityDistribution)
+  .sort(([a], [b]) => Number(b) - Number(a))
+  .forEach(([level, count]) => {
+    console.log(`    Level ${level}: ${count} role(s)`);
+  });
+
+console.log('\n✅ All utility tests passed!');

package/src/roles/test.ts

@@ -0,0 +1,106 @@
+#!/usr/bin/env bun
+/**
+ * Test script for the Role Engine
+ */
+
+import {
+  loadRole,
+  validateRole,
+  buildSystemPrompt,
+  canPerform,
+  listAllowedActions,
+  listDeniedActions,
+  getRolePermissionsSummary,
+  type RoleDefinition,
+  type ActionCategory,
+} from './index.ts';
+
+console.log('🧪 Testing Role Engine\n');
+
+// Test 1: Load a role from YAML
+console.log('Test 1: Loading role from YAML...');
+try {
+  const role = loadRole(import.meta.dir + '/test-role.yaml');
+  console.log(`✅ Loaded role: ${role.name} (${role.id})`);
+  console.log(`   Authority Level: ${role.authority_level}`);
+  console.log(`   Responsibilities: ${role.responsibilities.length}`);
+  console.log(`   Tools: ${role.tools.length}`);
+  console.log(`   KPIs: ${role.kpis.length}`);
+  console.log(`   Sub-roles: ${role.sub_roles.length}`);
+} catch (error) {
+  console.error('❌ Failed to load role:', error);
+  process.exit(1);
+}
+
+// Test 2: Validate role
+console.log('\nTest 2: Validating role...');
+const role = loadRole(import.meta.dir + '/test-role.yaml');
+const isValid = validateRole(role);
+console.log(isValid ? '✅ Role is valid' : '❌ Role is invalid');
+
+// Test 3: Build system prompt
+console.log('\nTest 3: Building system prompt...');
+const prompt = buildSystemPrompt(role, {
+  userName: 'John Doe',
+  currentTime: new Date().toLocaleString(),
+  activeCommitments: [
+    'Finish Q1 report by Friday',
+    'Prepare presentation for Monday meeting',
+  ],
+  recentObservations: [
+    'User prefers morning meetings',
+    'User checks email every 2 hours',
+  ],
+  agentHierarchy: 'Executive Assistant (you) > Research Specialist, Email Specialist',
+});
+console.log('✅ System prompt generated');
+console.log(`   Length: ${prompt.length} characters`);
+console.log('\n--- PROMPT PREVIEW ---');
+console.log(prompt.substring(0, 500) + '...\n');
+
+// Test 4: Authority checks
+console.log('Test 4: Testing authority system...');
+const permissions = getRolePermissionsSummary(role);
+console.log(`✅ Authority Level: ${permissions.level}/10`);
+console.log(`   ${permissions.description}`);
+console.log(`   Allowed actions: ${permissions.allowed.length}`);
+console.log(`   Denied actions: ${permissions.denied.length}`);
+
+// Test specific actions
+const actionsToTest: ActionCategory[] = [
+  'read_data',
+  'write_data',
+  'execute_command',
+  'spawn_agent',
+  'make_payment',
+];
+
+console.log('\nAction Permissions:');
+for (const action of actionsToTest) {
+  const can = canPerform(role, action);
+  console.log(`   ${can ? '✅' : '❌'} ${action}`);
+}
+
+// Test 5: List allowed/denied actions
+console.log('\nTest 5: Listing all permissions...');
+const allowed = listAllowedActions(role);
+const denied = listDeniedActions(role);
+
+console.log('\n✅ Allowed Actions:');
+allowed.forEach(action => console.log(`   - ${action}`));
+
+console.log('\n❌ Denied Actions:');
+denied.forEach(action => console.log(`   - ${action}`));
+
+// Test 6: Invalid role validation
+console.log('\nTest 6: Testing validation with invalid data...');
+const invalidRole = {
+  id: 'test',
+  name: 'Test',
+  // Missing required fields
+};
+
+const isInvalid = validateRole(invalidRole);
+console.log(isInvalid ? '❌ Should have been invalid!' : '✅ Correctly rejected invalid role');
+
+console.log('\n✅ All tests passed!');

package/src/roles/tool-guide.ts

@@ -0,0 +1,190 @@
+/**
+ * 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('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
+};