@shykaruu/jarvis-brain 0.4.0

package/src/roles/authority.ts

@@ -0,0 +1,120 @@
+import type { RoleDefinition } from './types.ts';
+
+export type ActionCategory =
+  | 'read_data' | 'write_data' | 'delete_data'
+  | 'send_message' | 'send_email'
+  | 'execute_command' | 'install_software'
+  | 'make_payment' | 'modify_settings'
+  | 'spawn_agent' | 'terminate_agent'
+  | 'access_browser' | 'control_app';
+
+/**
+ * Maps action categories to minimum required authority level
+ *
+ * Authority levels:
+ * - 1-2: Read only (read_data)
+ * - 3-4: Read + write + send messages (write_data, send_message)
+ * - 5-6: + execute commands, control apps (execute_command, access_browser, control_app)
+ * - 1+: spawn agents (spawn_agent) — always allowed
+ * - 7-8: + send email, install software (send_email, install_software)
+ * - 9-10: Full access including payments and settings (make_payment, modify_settings, delete_data, terminate_agent)
+ */
+export const AUTHORITY_REQUIREMENTS: Record<ActionCategory, number> = {
+  // Level 1-2: Read only
+  'read_data': 1,
+
+  // Level 3-4: Read + write + send messages
+  'write_data': 3,
+  'send_message': 3,
+
+  // Level 5-6: + execute commands, control apps
+  'execute_command': 5,
+  'access_browser': 5,
+  'control_app': 5,
+
+  // Level 7-8: + spawn agents, send email, install software
+  'spawn_agent': 1,
+  'send_email': 7,
+  'install_software': 7,
+
+  // Level 9-10: Full access including payments and settings
+  'make_payment': 9,
+  'modify_settings': 9,
+  'delete_data': 9,
+  'terminate_agent': 9,
+};
+
+/**
+ * Check if a role can perform a specific action
+ */
+export function canPerform(role: RoleDefinition, action: ActionCategory): boolean {
+  const requiredLevel = AUTHORITY_REQUIREMENTS[action];
+  return role.authority_level >= requiredLevel;
+}
+
+/**
+ * Get the required authority level for an action
+ */
+export function getRequiredLevel(action: ActionCategory): number {
+  return AUTHORITY_REQUIREMENTS[action];
+}
+
+/**
+ * List all actions a role is allowed to perform
+ */
+export function listAllowedActions(role: RoleDefinition): ActionCategory[] {
+  const actions = Object.keys(AUTHORITY_REQUIREMENTS) as ActionCategory[];
+  return actions.filter(action => canPerform(role, action));
+}
+
+/**
+ * List all actions a role is NOT allowed to perform
+ */
+export function listDeniedActions(role: RoleDefinition): ActionCategory[] {
+  const actions = Object.keys(AUTHORITY_REQUIREMENTS) as ActionCategory[];
+  return actions.filter(action => !canPerform(role, action));
+}
+
+/**
+ * Get a human-readable description of what an authority level allows
+ */
+export function describeAuthorityLevel(level: number): string {
+  if (level < 1 || level > 10) {
+    return 'Invalid authority level';
+  }
+
+  if (level <= 2) {
+    return 'Read-only access. Can read data but cannot modify anything.';
+  }
+
+  if (level <= 4) {
+    return 'Read and write access. Can read/write data and send messages.';
+  }
+
+  if (level <= 6) {
+    return 'Command execution. Can execute commands, control apps, and access browser.';
+  }
+
+  if (level <= 8) {
+    return 'Agent management. Can spawn agents, send emails, and install software.';
+  }
+
+  return 'Full access. Can make payments, modify settings, delete data, and terminate agents.';
+}
+
+/**
+ * Get a summary of a role's permissions
+ */
+export function getRolePermissionsSummary(role: RoleDefinition): {
+  level: number;
+  description: string;
+  allowed: ActionCategory[];
+  denied: ActionCategory[];
+} {
+  return {
+    level: role.authority_level,
+    description: describeAuthorityLevel(role.authority_level),
+    allowed: listAllowedActions(role),
+    denied: listDeniedActions(role),
+  };
+}

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'
+  );
+}