@usejarvis/brain 0.1.0

package/src/roles/example-usage.ts

@@ -0,0 +1,198 @@
+#!/usr/bin/env bun
+/**
+ * Example usage of the Role Engine in a real application
+ *
+ * This demonstrates how to integrate the Role Engine with an agent system
+ */
+
+import {
+  loadRolesFromDir,
+  buildSystemPrompt,
+  canPerform,
+  getRolePermissionsSummary,
+  type RoleDefinition,
+  type ActionCategory,
+} from './index.ts';
+
+// Mock agent state
+interface AgentState {
+  id: string;
+  role: RoleDefinition;
+  currentTask?: string;
+  commitments: string[];
+  observations: string[];
+}
+
+/**
+ * Initialize the role system and load all available roles
+ */
+function initializeRoleSystem(rolesDir: string): Map<string, RoleDefinition> {
+  console.log('🔧 Initializing Role System...');
+  const roles = loadRolesFromDir(rolesDir);
+  console.log(`✅ Loaded ${roles.size} roles`);
+
+  // Display loaded roles
+  for (const [id, role] of roles) {
+    console.log(`   - ${role.name} (authority: ${role.authority_level}/10)`);
+  }
+
+  return roles;
+}
+
+/**
+ * Create an agent with a specific role
+ */
+function createAgent(
+  agentId: string,
+  roleId: string,
+  roles: Map<string, RoleDefinition>
+): AgentState | null {
+  const role = roles.get(roleId);
+
+  if (!role) {
+    console.error(`❌ Role '${roleId}' not found`);
+    return null;
+  }
+
+  console.log(`\n🤖 Creating agent '${agentId}' with role '${role.name}'`);
+
+  const agent: AgentState = {
+    id: agentId,
+    role,
+    commitments: [],
+    observations: [],
+  };
+
+  // Display agent capabilities
+  const permissions = getRolePermissionsSummary(role);
+  console.log(`   Authority: ${permissions.level}/10`);
+  console.log(`   ${permissions.description}`);
+  console.log(`   Allowed actions: ${permissions.allowed.join(', ')}`);
+
+  return agent;
+}
+
+/**
+ * Check if an agent can perform an action, with logging
+ */
+function checkAction(agent: AgentState, action: ActionCategory): boolean {
+  const can = canPerform(agent.role, action);
+  const status = can ? '✅' : '❌';
+  console.log(`   ${status} ${action}: ${can ? 'ALLOWED' : 'DENIED'}`);
+  return can;
+}
+
+/**
+ * Generate system prompt for an agent
+ */
+function generateAgentPrompt(agent: AgentState, userName: string): string {
+  console.log(`\n📝 Generating system prompt for ${agent.id}...`);
+
+  const prompt = buildSystemPrompt(agent.role, {
+    userName,
+    currentTime: new Date().toLocaleString(),
+    activeCommitments: agent.commitments,
+    recentObservations: agent.observations,
+    agentHierarchy: 'You are a top-level agent',
+  });
+
+  console.log(`   Generated ${prompt.length} characters`);
+  return prompt;
+}
+
+/**
+ * Simulate an agent attempting various actions
+ */
+function simulateAgentActions(agent: AgentState) {
+  console.log(`\n🎬 Simulating actions for ${agent.role.name}...`);
+
+  const actions: ActionCategory[] = [
+    'read_data',
+    'write_data',
+    'send_message',
+    'execute_command',
+    'spawn_agent',
+    'send_email',
+    'make_payment',
+    'delete_data',
+  ];
+
+  for (const action of actions) {
+    checkAction(agent, action);
+  }
+}
+
+/**
+ * Main demonstration
+ */
+async function main() {
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('  J.A.R.V.I.S. Role Engine - Usage Example');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+
+  // 1. Initialize role system
+  const { join } = await import('path');
+  const roles = initializeRoleSystem(join(import.meta.dir, '../../roles'));
+
+  // 2. Create different agents with different roles
+  const execAgent = createAgent('agent-001', 'executive_assistant', roles);
+  const researchAgent = createAgent('agent-002', 'research_specialist', roles);
+  const observerAgent = createAgent('agent-003', 'activity_observer', roles);
+  const sysAdminAgent = createAgent('agent-004', 'system_admin', roles);
+
+  if (!execAgent || !researchAgent || !observerAgent || !sysAdminAgent) {
+    console.error('Failed to create agents');
+    return;
+  }
+
+  // 3. Add some state to the executive agent
+  execAgent.commitments = [
+    'Prepare board meeting presentation',
+    'Review quarterly reports',
+  ];
+  execAgent.observations = [
+    'User has 3 meetings tomorrow morning',
+    'User prefers detailed reports',
+  ];
+
+  // 4. Generate system prompts
+  const execPrompt = generateAgentPrompt(execAgent, 'Alice Johnson');
+
+  // 5. Test permission boundaries
+  console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('  Permission Testing');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+
+  simulateAgentActions(execAgent);
+  simulateAgentActions(observerAgent);
+  simulateAgentActions(sysAdminAgent);
+
+  // 6. Show a snippet of the generated prompt
+  console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('  Sample System Prompt');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+  console.log(execPrompt.substring(0, 600) + '...\n');
+
+  // 7. Compare roles
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('  Role Comparison');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+
+  const agents = [execAgent, researchAgent, observerAgent, sysAdminAgent];
+
+  console.log('Role                  | Auth | Can Execute? | Can Pay? | Tools');
+  console.log('──────────────────────|──────|──────────────|──────────|──────');
+
+  for (const agent of agents) {
+    const name = agent.role.name.padEnd(21);
+    const auth = `${agent.role.authority_level}/10`.padEnd(4);
+    const canExec = canPerform(agent.role, 'execute_command') ? '✅ Yes' : '❌ No ';
+    const canPay = canPerform(agent.role, 'make_payment') ? '✅ Yes' : '❌ No ';
+    const tools = agent.role.tools.length;
+    console.log(`${name} | ${auth} | ${canExec}       | ${canPay}     | ${tools}`);
+  }
+
+  console.log('\n✅ Example complete!\n');
+}
+
+main().catch(console.error);

package/src/roles/index.ts

@@ -0,0 +1,42 @@
+// Type definitions
+export type {
+  KPI,
+  CommunicationStyle,
+  SubRoleTemplate,
+  RoleDefinition,
+} from './types.ts';
+
+// Loader functions
+export {
+  loadRole,
+  loadRolesFromDir,
+  validateRole,
+} from './loader.ts';
+
+// Prompt builder
+export type { PromptContext } from './prompt-builder.ts';
+export { buildSystemPrompt } from './prompt-builder.ts';
+
+// Authority system
+export type { ActionCategory } from './authority.ts';
+export {
+  AUTHORITY_REQUIREMENTS,
+  canPerform,
+  getRequiredLevel,
+  listAllowedActions,
+  listDeniedActions,
+  describeAuthorityLevel,
+  getRolePermissionsSummary,
+} from './authority.ts';
+
+// Utility functions
+export {
+  findRolesWithPermission,
+  findMinimalRoleForAction,
+  compareRoles,
+  getRoleHierarchy,
+  canSpawnRole,
+  findSpawnersOfRole,
+  validateRoleHierarchy,
+  getRoleStats,
+} from './utils.ts';

package/src/roles/loader.ts

@@ -0,0 +1,143 @@
+import YAML from 'yaml';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, extname } from 'node:path';
+import type { RoleDefinition, KPI, CommunicationStyle, SubRoleTemplate } from './types.ts';
+
+/**
+ * Load a role from a YAML file
+ */
+export function loadRole(filePath: string): RoleDefinition {
+  const content = readFileSync(filePath, 'utf-8');
+  const data = YAML.parse(content);
+
+  if (!validateRole(data)) {
+    throw new Error(`Invalid role definition in ${filePath}`);
+  }
+
+  return data;
+}
+
+/**
+ * Load all roles from a directory
+ */
+export function loadRolesFromDir(dirPath: string): Map<string, RoleDefinition> {
+  const roles = new Map<string, RoleDefinition>();
+
+  try {
+    const files = readdirSync(dirPath);
+
+    for (const file of files) {
+      const filePath = join(dirPath, file);
+      const stat = statSync(filePath);
+
+      if (stat.isFile() && (extname(file) === '.yaml' || extname(file) === '.yml')) {
+        try {
+          const role = loadRole(filePath);
+          roles.set(role.id, role);
+        } catch (error) {
+          console.error(`Failed to load role from ${file}:`, error);
+          // Continue loading other roles
+        }
+      }
+    }
+  } catch (error) {
+    console.error(`Failed to read roles directory ${dirPath}:`, error);
+  }
+
+  return roles;
+}
+
+/**
+ * Validate a role definition (check required fields)
+ */
+export function validateRole(role: unknown): role is RoleDefinition {
+  if (!role || typeof role !== 'object') {
+    return false;
+  }
+
+  const r = role as Record<string, unknown>;
+
+  // Check required string fields
+  if (typeof r.id !== 'string' || !r.id) return false;
+  if (typeof r.name !== 'string' || !r.name) return false;
+  if (typeof r.description !== 'string' || !r.description) return false;
+  if (typeof r.heartbeat_instructions !== 'string' || !r.heartbeat_instructions) return false;
+
+  // Check required arrays
+  if (!Array.isArray(r.responsibilities)) return false;
+  if (!Array.isArray(r.autonomous_actions)) return false;
+  if (!Array.isArray(r.approval_required)) return false;
+  if (!Array.isArray(r.kpis)) return false;
+  if (!Array.isArray(r.sub_roles)) return false;
+  if (!Array.isArray(r.tools)) return false;
+
+  // Validate authority_level
+  if (typeof r.authority_level !== 'number') return false;
+  if (r.authority_level < 1 || r.authority_level > 10) return false;
+
+  // Validate string arrays
+  if (!r.responsibilities.every((item) => typeof item === 'string')) return false;
+  if (!r.autonomous_actions.every((item) => typeof item === 'string')) return false;
+  if (!r.approval_required.every((item) => typeof item === 'string')) return false;
+  if (!r.tools.every((item) => typeof item === 'string')) return false;
+
+  // Validate KPIs
+  if (!r.kpis.every(validateKPI)) return false;
+
+  // Validate communication_style
+  if (!validateCommunicationStyle(r.communication_style)) return false;
+
+  // Validate sub_roles
+  if (!r.sub_roles.every(validateSubRoleTemplate)) return false;
+
+  return true;
+}
+
+/**
+ * Validate a KPI object
+ */
+function validateKPI(kpi: unknown): kpi is KPI {
+  if (!kpi || typeof kpi !== 'object') return false;
+
+  const k = kpi as Record<string, unknown>;
+
+  return (
+    typeof k.name === 'string' &&
+    typeof k.metric === 'string' &&
+    typeof k.target === 'string' &&
+    typeof k.check_interval === 'string'
+  );
+}
+
+/**
+ * Validate a CommunicationStyle object
+ */
+function validateCommunicationStyle(style: unknown): style is CommunicationStyle {
+  if (!style || typeof style !== 'object') return false;
+
+  const s = style as Record<string, unknown>;
+
+  return (
+    typeof s.tone === 'string' &&
+    (s.verbosity === 'concise' || s.verbosity === 'detailed' || s.verbosity === 'adaptive') &&
+    (s.formality === 'formal' || s.formality === 'casual' || s.formality === 'adaptive')
+  );
+}
+
+/**
+ * Validate a SubRoleTemplate object
+ */
+function validateSubRoleTemplate(template: unknown): template is SubRoleTemplate {
+  if (!template || typeof template !== 'object') return false;
+
+  const t = template as Record<string, unknown>;
+
+  return (
+    typeof t.role_id === 'string' &&
+    typeof t.name === 'string' &&
+    typeof t.description === 'string' &&
+    typeof t.spawned_by === 'string' &&
+    typeof t.reports_to === 'string' &&
+    typeof t.max_budget_per_task === 'number'
+  );
+}

package/src/roles/prompt-builder.ts

@@ -0,0 +1,194 @@
+import type { RoleDefinition } from './types.ts';
+import { buildToolGuide } from './tool-guide.ts';
+
+export type PromptContext = {
+  userName?: string;
+  currentTime?: string;
+  activeCommitments?: string[];
+  recentObservations?: string[];
+  agentHierarchy?: string;
+  knowledgeContext?: string;
+  availableSpecialists?: string;
+  contentPipeline?: string[];
+  authorityRules?: string;
+  activeGoals?: string;
+  hasSidecars?: boolean;
+};
+
+/**
+ * Build a full system prompt from a role definition and context
+ */
+export function buildSystemPrompt(role: RoleDefinition, context?: PromptContext): string {
+  const sections: string[] = [];
+
+  // Identity
+  sections.push('# Identity');
+  sections.push(`You are ${role.name}. ${role.description}`);
+  sections.push('');
+
+  // Responsibilities
+  sections.push('# Responsibilities');
+  for (const responsibility of role.responsibilities) {
+    sections.push(`- ${responsibility}`);
+  }
+  sections.push('');
+
+  // Autonomous Actions
+  sections.push('# Autonomous Actions (do without asking)');
+  if (role.autonomous_actions.length > 0) {
+    for (const action of role.autonomous_actions) {
+      sections.push(`- ${action}`);
+    }
+  } else {
+    sections.push('- None. Always ask for permission before taking any action.');
+  }
+  sections.push('');
+
+  // Approval Required
+  sections.push('# Approval Required (always ask first)');
+  if (role.approval_required.length > 0) {
+    for (const action of role.approval_required) {
+      sections.push(`- ${action}`);
+    }
+  } else {
+    sections.push('- N/A');
+  }
+  sections.push('');
+
+  // Communication Style
+  sections.push('# Communication Style');
+  sections.push(`Tone: ${role.communication_style.tone}.`);
+  sections.push(`Verbosity: ${role.communication_style.verbosity}.`);
+  sections.push(`Formality: ${role.communication_style.formality}.`);
+  sections.push('');
+  sections.push('**Task Acknowledgment**: When asked to perform a task that requires tool use, ALWAYS give a brief acknowledgment first (e.g., "On it.", "Let me check.", "I\'ll look into that.") before using any tools. Never silently start executing tools — the user should know you understood their request.');
+  sections.push('');
+
+  // KPIs
+  sections.push('# Key Performance Indicators (KPIs)');
+  if (role.kpis.length > 0) {
+    sections.push('| KPI | Metric | Target | Check Interval |');
+    sections.push('|-----|--------|--------|----------------|');
+    for (const kpi of role.kpis) {
+      sections.push(`| ${kpi.name} | ${kpi.metric} | ${kpi.target} | ${kpi.check_interval} |`);
+    }
+  } else {
+    sections.push('- No specific KPIs defined.');
+  }
+  sections.push('');
+
+  // Heartbeat Instructions
+  sections.push('# Heartbeat Instructions');
+  sections.push(role.heartbeat_instructions);
+  sections.push('');
+
+  // Available Tools
+  sections.push('# Available Tools');
+  if (role.tools.length > 0) {
+    for (const tool of role.tools) {
+      sections.push(`- ${tool}`);
+    }
+  } else {
+    sections.push('- No tools assigned.');
+  }
+  sections.push('');
+
+  // Sub-roles (if any)
+  if (role.sub_roles.length > 0) {
+    sections.push('# Sub-Roles You Can Spawn');
+    for (const subRole of role.sub_roles) {
+      sections.push(`- **${subRole.name}** (${subRole.role_id}): ${subRole.description}`);
+      sections.push(`  - Reports to: ${subRole.reports_to}`);
+      sections.push(`  - Max budget per task: ${subRole.max_budget_per_task}`);
+    }
+    sections.push('');
+  }
+
+  // Authority Level
+  sections.push('# Authority Level');
+  sections.push(`Your authority level is ${role.authority_level}/10.`);
+  sections.push('This determines which actions you can perform autonomously.');
+  sections.push('');
+
+  // Authority Rules (from engine)
+  if (context?.authorityRules) {
+    sections.push('# Authority Rules');
+    sections.push('The following rules govern your tool execution:');
+    sections.push(context.authorityRules);
+    sections.push('');
+    sections.push('When a tool returns [AWAITING_APPROVAL], tell the user you have submitted the request and are waiting for their approval.');
+    sections.push('When a tool returns [AUTHORITY DENIED], explain that you lack permission and suggest alternatives.');
+    sections.push('');
+  }
+
+  // Tool Guide (static reference, sidecar section conditional)
+  sections.push(buildToolGuide(context?.hasSidecars ?? false));
+  sections.push('');
+
+  // Current Context
+  if (context) {
+    sections.push('# Current Context');
+
+    if (context.userName) {
+      sections.push(`User: ${context.userName}`);
+    }
+
+    if (context.currentTime) {
+      sections.push(`Time: ${context.currentTime}`);
+    }
+
+    if (context.agentHierarchy) {
+      sections.push('');
+      sections.push('## Agent Hierarchy');
+      sections.push(context.agentHierarchy);
+    }
+
+    if (context.availableSpecialists) {
+      sections.push('');
+      sections.push(context.availableSpecialists);
+    }
+
+    if (context.knowledgeContext) {
+      sections.push('');
+      sections.push('## Relevant Knowledge');
+      sections.push('The following is what you remember about entities mentioned in this conversation:');
+      sections.push(context.knowledgeContext);
+    }
+
+    if (context.activeCommitments && context.activeCommitments.length > 0) {
+      sections.push('');
+      sections.push('## Active Commitments');
+      for (const commitment of context.activeCommitments) {
+        sections.push(`- ${commitment}`);
+      }
+    }
+
+    if (context.recentObservations && context.recentObservations.length > 0) {
+      sections.push('');
+      sections.push('## Recent Activity');
+      for (const observation of context.recentObservations) {
+        sections.push(`- ${observation}`);
+      }
+    }
+
+    if (context.contentPipeline && context.contentPipeline.length > 0) {
+      sections.push('');
+      sections.push('## Content Pipeline');
+      sections.push('Active content items you are co-managing:');
+      for (const item of context.contentPipeline) {
+        sections.push(`- ${item}`);
+      }
+    }
+
+    if (context.activeGoals) {
+      sections.push('');
+      sections.push('## Active Goals');
+      sections.push('Current OKR goals you are pursuing (0.0-1.0 scoring, 0.7 = good):');
+      sections.push(context.activeGoals);
+    }
+
+    sections.push('');
+  }
+
+  return sections.join('\n');
+}

package/src/roles/test-multi.ts

@@ -0,0 +1,102 @@
+#!/usr/bin/env bun
+/**
+ * Test script for loading multiple roles from a directory
+ */
+
+import {
+  loadRolesFromDir,
+  buildSystemPrompt,
+  getRolePermissionsSummary,
+} from './index.ts';
+
+console.log('🧪 Testing Multi-Role Loading\n');
+
+// Load all roles from the config directory
+import { join } from 'path';
+const rolesDir = join(import.meta.dir, '../../roles');
+console.log(`Loading roles from ${rolesDir}...`);
+const roles = loadRolesFromDir(rolesDir);
+
+console.log(`✅ Loaded ${roles.size} roles:\n`);
+
+// Display summary of each role
+for (const [id, role] of roles) {
+  console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+  console.log(`Role: ${role.name} (${id})`);
+  console.log(`Description: ${role.description.substring(0, 80)}...`);
+  console.log(`Authority Level: ${role.authority_level}/10`);
+
+  const permissions = getRolePermissionsSummary(role);
+  console.log(`Capabilities: ${permissions.description}`);
+
+  console.log(`\nStats:`);
+  console.log(`  - Responsibilities: ${role.responsibilities.length}`);
+  console.log(`  - Autonomous Actions: ${role.autonomous_actions.length}`);
+  console.log(`  - Approval Required: ${role.approval_required.length}`);
+  console.log(`  - Tools: ${role.tools.length}`);
+  console.log(`  - KPIs: ${role.kpis.length}`);
+  console.log(`  - Sub-roles: ${role.sub_roles.length}`);
+  console.log(`  - Allowed Actions: ${permissions.allowed.length}`);
+  console.log(`  - Denied Actions: ${permissions.denied.length}`);
+
+  console.log(`\nCommunication Style:`);
+  console.log(`  - Tone: ${role.communication_style.tone}`);
+  console.log(`  - Verbosity: ${role.communication_style.verbosity}`);
+  console.log(`  - Formality: ${role.communication_style.formality}`);
+
+  if (role.sub_roles.length > 0) {
+    console.log(`\nCan spawn:`);
+    role.sub_roles.forEach(sub => {
+      console.log(`  - ${sub.name} (budget: ${sub.max_budget_per_task})`);
+    });
+  }
+
+  console.log('');
+}
+
+// Generate and display a sample prompt for one role
+console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+console.log('Sample System Prompt Generation');
+console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+
+const executiveRole = roles.get('executive_assistant');
+if (executiveRole) {
+  const prompt = buildSystemPrompt(executiveRole, {
+    userName: 'Alice Johnson',
+    currentTime: new Date().toLocaleString(),
+    activeCommitments: [
+      'Board meeting presentation - Due tomorrow 9 AM',
+      'Review Q1 financial reports',
+    ],
+    recentObservations: [
+      'User prefers meetings before noon',
+      'User checks Slack frequently but email once per day',
+      'User is working on strategic planning this week',
+    ],
+    agentHierarchy: 'System Admin > Executive Assistant (you) > [Research Specialist, Email Specialist]',
+  });
+
+  console.log('Full System Prompt for Executive Assistant:');
+  console.log('─'.repeat(80));
+  console.log(prompt);
+  console.log('─'.repeat(80));
+}
+
+// Compare authority levels
+console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+console.log('Authority Level Comparison');
+console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+
+const sortedRoles = Array.from(roles.values()).sort((a, b) => b.authority_level - a.authority_level);
+
+console.log('Role                     | Authority | Capabilities');
+console.log('─────────────────────────|───────────|─────────────────────────────────');
+
+for (const role of sortedRoles) {
+  const permissions = getRolePermissionsSummary(role);
+  const name = role.name.padEnd(24);
+  const level = `${role.authority_level}/10`.padEnd(9);
+  console.log(`${name} | ${level} | ${permissions.allowed.length} allowed, ${permissions.denied.length} denied`);
+}
+
+console.log('\n✅ Multi-role test complete!');