@usejarvis/brain 0.1.0

package/src/personality/personality.test.ts

@@ -0,0 +1,236 @@
+import { test, expect, beforeEach, afterEach, describe } from 'bun:test';
+import { initDatabase, closeDb } from '../vault/schema.ts';
+import {
+  getPersonality,
+  savePersonality,
+  updatePersonality,
+  type PersonalityModel,
+} from './model.ts';
+import {
+  extractSignals,
+  applySignals,
+  recordInteraction,
+} from './learner.ts';
+import {
+  getChannelPersonality,
+  personalityToPrompt,
+} from './adapter.ts';
+
+describe('Personality Engine', () => {
+  beforeEach(() => {
+    // Initialize in-memory database for each test
+    initDatabase(':memory:');
+  });
+
+  afterEach(() => {
+    // Close database connection after each test
+    closeDb();
+  });
+
+  describe('Model', () => {
+    test('should get default personality', () => {
+      const personality = getPersonality();
+
+      expect(personality.core_traits).toEqual(['direct', 'strategic', 'resourceful']);
+      expect(personality.learned_preferences.verbosity).toBe(5);
+      expect(personality.learned_preferences.formality).toBe(5);
+      expect(personality.relationship.message_count).toBe(0);
+    });
+
+    test('should save and load personality', () => {
+      const personality = getPersonality();
+      personality.learned_preferences.verbosity = 8;
+      personality.relationship.message_count = 42;
+
+      savePersonality(personality);
+
+      const loaded = getPersonality();
+      expect(loaded.learned_preferences.verbosity).toBe(8);
+      expect(loaded.relationship.message_count).toBe(42);
+    });
+
+    test('should update personality with deep merge', () => {
+      const updated = updatePersonality({
+        learned_preferences: {
+          verbosity: 7,
+        },
+      });
+
+      expect(updated.learned_preferences.verbosity).toBe(7);
+      expect(updated.learned_preferences.formality).toBe(5); // unchanged
+      expect(updated.core_traits).toEqual(['direct', 'strategic', 'resourceful']); // unchanged
+    });
+  });
+
+  describe('Learner', () => {
+    test('should extract verbosity signals', () => {
+      const signals = extractSignals('Please keep it brief and concise', 'Here is a long response...');
+
+      expect(signals.length).toBeGreaterThan(0);
+      const verbositySignal = signals.find((s) => s.data.preference === 'verbosity');
+      expect(verbositySignal).toBeDefined();
+      expect(verbositySignal?.data.direction).toBe(-1);
+    });
+
+    test('should extract formality signals', () => {
+      const signals = extractSignals('Be more casual please', 'Understood.');
+
+      const formalitySignal = signals.find((s) => s.data.preference === 'formality');
+      expect(formalitySignal).toBeDefined();
+      expect(formalitySignal?.data.direction).toBe(-1);
+    });
+
+    test('should extract emoji usage signals', () => {
+      const signals = extractSignals('Great work! 🎉✨', 'Thank you!');
+
+      const emojiSignal = signals.find((s) => s.data.preference === 'emoji_usage');
+      expect(emojiSignal).toBeDefined();
+      expect(emojiSignal?.data.value).toBe(true);
+    });
+
+    test('should extract format preference signals', () => {
+      const signals = extractSignals('Can you show this as a table?', 'Sure!');
+
+      const formatSignal = signals.find((s) => s.data.preference === 'preferred_format');
+      expect(formatSignal).toBeDefined();
+      expect(formatSignal?.data.value).toBe('tables');
+    });
+
+    test('should apply signals to personality', () => {
+      const personality = getPersonality();
+      const initialVerbosity = personality.learned_preferences.verbosity;
+      const initialFormality = personality.learned_preferences.formality;
+
+      const signals = [
+        { type: 'user_feedback' as const, data: { preference: 'verbosity', direction: 2 } },
+        { type: 'explicit_preference' as const, data: { preference: 'formality', direction: -1 } },
+      ];
+
+      const updated = applySignals(personality, signals);
+
+      expect(updated.learned_preferences.verbosity).toBe(initialVerbosity + 2);
+      expect(updated.learned_preferences.formality).toBe(initialFormality - 1);
+    });
+
+    test('should clamp values to 0-10 range', () => {
+      let personality = getPersonality();
+      personality.learned_preferences.verbosity = 9;
+
+      const signals = [
+        { type: 'user_feedback' as const, data: { preference: 'verbosity', direction: 5 } },
+      ];
+
+      personality = applySignals(personality, signals);
+
+      expect(personality.learned_preferences.verbosity).toBe(10); // clamped
+    });
+
+    test('should record interactions and increase trust', () => {
+      let personality = getPersonality();
+      const initialCount = personality.relationship.message_count;
+
+      // Simulate 50 interactions
+      for (let i = 0; i < 50; i++) {
+        personality = recordInteraction(personality);
+      }
+
+      expect(personality.relationship.message_count).toBe(initialCount + 50);
+      // Trust should increase based on message count
+      expect(personality.relationship.trust_level).toBeGreaterThan(3);
+    });
+  });
+
+  describe('Adapter', () => {
+    test('should adapt personality for WhatsApp', () => {
+      const base = getPersonality();
+      const adapted = getChannelPersonality(base, 'whatsapp');
+
+      expect(adapted.learned_preferences.emoji_usage).toBe(true);
+      expect(adapted.learned_preferences.verbosity).toBe(4);
+      expect(adapted.learned_preferences.formality).toBe(3);
+    });
+
+    test('should adapt personality for email', () => {
+      const base = getPersonality();
+      const adapted = getChannelPersonality(base, 'email');
+
+      expect(adapted.learned_preferences.emoji_usage).toBe(false);
+      expect(adapted.learned_preferences.verbosity).toBe(7);
+      expect(adapted.learned_preferences.formality).toBe(8);
+    });
+
+    test('should use stored channel overrides', () => {
+      const personality = getPersonality();
+      personality.channel_overrides.custom_channel = {
+        learned_preferences: {
+          verbosity: 10,
+          formality: 0,
+          humor_level: 10,
+          emoji_usage: true,
+          preferred_format: 'lists',
+        },
+      };
+
+      const adapted = getChannelPersonality(personality, 'custom_channel');
+
+      expect(adapted.learned_preferences.verbosity).toBe(10);
+      expect(adapted.learned_preferences.formality).toBe(0);
+    });
+
+    test('should generate personality prompt', () => {
+      const personality = getPersonality();
+      personality.relationship.message_count = 25;
+      personality.relationship.shared_references = ['Project X', 'Anna'];
+
+      const prompt = personalityToPrompt(personality);
+
+      expect(prompt).toContain('Personality');
+      expect(prompt).toContain('direct, strategic, resourceful');
+      expect(prompt).toContain('25 interactions');
+      expect(prompt).toContain('Project X, Anna');
+    });
+  });
+
+  describe('Integration', () => {
+    test('should handle full learning cycle', () => {
+      // Start with default personality
+      let personality = getPersonality();
+      const initialVerbosity = personality.learned_preferences.verbosity;
+
+      // User sends multiple messages asking for brevity
+      const userMessages = [
+        'Keep it short please',
+        'TLDR version?',
+        'Too long, can you summarize?',
+      ];
+
+      userMessages.forEach((msg) => {
+        const signals = extractSignals(msg, 'Response');
+        personality = applySignals(personality, signals);
+        personality = recordInteraction(personality);
+      });
+
+      // Save the learned personality
+      savePersonality(personality);
+
+      // Reload and verify
+      const loaded = getPersonality();
+      // Verbosity should have decreased from initial value
+      expect(loaded.learned_preferences.verbosity).toBeLessThan(initialVerbosity);
+      // Message count should have increased by 3
+      expect(loaded.relationship.message_count).toBeGreaterThanOrEqual(3);
+    });
+
+    test('should adapt for channel and generate prompt', () => {
+      let personality = getPersonality();
+      personality.relationship.message_count = 100;
+
+      const whatsappPersonality = getChannelPersonality(personality, 'whatsapp');
+      const prompt = personalityToPrompt(whatsappPersonality);
+
+      expect(prompt).toContain('Personality');
+      expect(prompt).toContain('100 interactions');
+      expect(whatsappPersonality.learned_preferences.emoji_usage).toBe(true);
+    });
+  });
+});

package/src/roles/README.md

@@ -0,0 +1,252 @@
+# Role Engine
+
+The Role Engine is a core component of Project J.A.R.V.I.S. that defines, loads, and manages AI agent roles with their permissions, responsibilities, and behavior patterns.
+
+## Overview
+
+The Role Engine provides:
+
+- **Role Definitions**: YAML-based role configuration with clear responsibilities and boundaries
+- **Authority System**: 10-level permission system controlling what actions agents can perform
+- **System Prompt Generation**: Automatic generation of detailed system prompts from role definitions
+- **Validation**: Type-safe role loading with comprehensive validation
+- **Multi-Role Management**: Load and manage multiple roles from a directory
+
+## Architecture
+
+```
+src/roles/
+├── types.ts            # TypeScript type definitions
+├── loader.ts           # YAML loading and validation
+├── prompt-builder.ts   # System prompt generation
+├── authority.ts        # Permission and authority system
+└── index.ts            # Public API exports
+```
+
+## Usage
+
+### Loading a Single Role
+
+```typescript
+import { loadRole } from './roles/index.ts';
+
+const role = loadRole('/path/to/role.yaml');
+console.log(role.name, role.authority_level);
+```
+
+### Loading Multiple Roles
+
+```typescript
+import { loadRolesFromDir } from './roles/index.ts';
+
+const roles = loadRolesFromDir('/config/roles');
+for (const [id, role] of roles) {
+  console.log(`${id}: ${role.name}`);
+}
+```
+
+### Building System Prompts
+
+```typescript
+import { buildSystemPrompt } from './roles/index.ts';
+
+const prompt = buildSystemPrompt(role, {
+  userName: 'John Doe',
+  currentTime: new Date().toLocaleString(),
+  activeCommitments: ['Finish report by Friday'],
+  recentObservations: ['User prefers morning meetings'],
+  agentHierarchy: 'Manager > Assistant (you) > Specialist',
+});
+```
+
+### Checking Permissions
+
+```typescript
+import { canPerform, getRolePermissionsSummary } from './roles/index.ts';
+
+// Check specific action
+if (canPerform(role, 'execute_command')) {
+  console.log('Can execute commands');
+}
+
+// Get full permission summary
+const summary = getRolePermissionsSummary(role);
+console.log(summary.allowed);  // List of allowed actions
+console.log(summary.denied);   // List of denied actions
+```
+
+## Role Definition Format
+
+Roles are defined in YAML files with the following structure:
+
+```yaml
+id: unique_role_id
+name: Human-Readable Role Name
+description: Brief description of the role's purpose
+
+responsibilities:
+  - First responsibility
+  - Second responsibility
+
+autonomous_actions:
+  - Actions the agent can take without asking
+
+approval_required:
+  - Actions that require user approval
+
+kpis:
+  - name: KPI Name
+    metric: What to measure
+    target: Target value
+    check_interval: How often to check
+
+communication_style:
+  tone: Description of communication tone
+  verbosity: concise | detailed | adaptive
+  formality: formal | casual | adaptive
+
+heartbeat_instructions: |
+  Instructions for periodic check-ins.
+  What to monitor and when to notify the user.
+
+sub_roles:
+  - role_id: sub_role_id
+    name: Sub-Role Name
+    description: What this sub-role does
+    spawned_by: parent_role_id
+    reports_to: parent_role_id
+    max_budget_per_task: 100
+
+tools:
+  - tool_name_1
+  - tool_name_2
+
+authority_level: 6  # 1-10
+```
+
+## Authority Levels
+
+The authority system uses a 1-10 scale:
+
+| Level | Capabilities |
+|-------|-------------|
+| 1-2   | **Read Only**: Can read data but cannot modify anything |
+| 3-4   | **Read & Write**: Can read/write data and send messages |
+| 5-6   | **Command Execution**: Can execute commands, control apps, access browser |
+| 7-8   | **Agent Management**: Can spawn agents, send emails, install software |
+| 9-10  | **Full Access**: Can make payments, modify settings, delete data, terminate agents |
+
+### Action Categories
+
+The following action categories are enforced:
+
+**Level 1+**: `read_data`
+
+**Level 3+**: `write_data`, `send_message`
+
+**Level 5+**: `execute_command`, `access_browser`, `control_app`
+
+**Level 7+**: `spawn_agent`, `send_email`, `install_software`
+
+**Level 9+**: `make_payment`, `modify_settings`, `delete_data`, `terminate_agent`
+
+## Example Roles
+
+See `/config/roles/` for example role definitions:
+
+- **Executive Assistant** (Level 6): Manages schedule, communications, and tasks
+- **Research Specialist** (Level 4): Deep research and report generation
+- **System Administrator** (Level 9): System maintenance and infrastructure
+
+## Type Definitions
+
+### RoleDefinition
+
+```typescript
+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
+};
+```
+
+### KPI
+
+```typescript
+type KPI = {
+  name: string;
+  metric: string;
+  target: string;
+  check_interval: string;
+};
+```
+
+### CommunicationStyle
+
+```typescript
+type CommunicationStyle = {
+  tone: string;
+  verbosity: 'concise' | 'detailed' | 'adaptive';
+  formality: 'formal' | 'casual' | 'adaptive';
+};
+```
+
+### SubRoleTemplate
+
+```typescript
+type SubRoleTemplate = {
+  role_id: string;
+  name: string;
+  description: string;
+  spawned_by: string;
+  reports_to: string;
+  max_budget_per_task: number;
+};
+```
+
+## Testing
+
+Run the test suite:
+
+```bash
+# Test single role loading
+bun run src/roles/test.ts
+
+# Test multi-role loading
+bun run src/roles/test-multi.ts
+```
+
+## Integration with J.A.R.V.I.S.
+
+The Role Engine integrates with:
+
+1. **Agent System**: Agents are instantiated with specific roles
+2. **LLM Integration**: System prompts are generated for LLM context
+3. **Permission System**: Authority levels enforce action restrictions
+4. **Daemon**: Roles are loaded at startup and managed by the daemon
+
+## Best Practices
+
+1. **Authority Principle**: Assign the minimum authority level needed for the role
+2. **Clear Boundaries**: Explicitly define autonomous vs approval-required actions
+3. **Measurable KPIs**: Define concrete, measurable success metrics
+4. **Heartbeat Clarity**: Provide clear, actionable heartbeat instructions
+5. **Tool Assignment**: Only assign tools the role actually needs
+6. **Communication Style**: Match style to the role's purpose and audience
+
+## Future Enhancements
+
+- Role templates and inheritance
+- Dynamic authority adjustment based on performance
+- Role-based routing and delegation
+- Automatic KPI tracking and reporting
+- Role versioning and migration

package/src/roles/authority.ts

@@ -0,0 +1,119 @@
+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)
+ * - 7-8: + spawn agents, send email, install software (spawn_agent, 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': 7,
+  '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),
+  };
+}