@usejarvis/brain 0.1.0

package/src/authority/deferred-executor.ts

@@ -0,0 +1,103 @@
+/**
+ * Deferred Executor — Runs approved tool calls that were waiting for approval.
+ */
+
+import type { ToolRegistry } from '../actions/tools/registry.ts';
+import type { ApprovalManager, ApprovalRequest } from './approval.ts';
+import type { AuditTrail } from './audit.ts';
+import type { AuthorityLearner } from './learning.ts';
+import type { ActionCategory } from '../roles/authority.ts';
+
+export type ExecutionResultCallback = (requestId: string, request: ApprovalRequest, result: string) => void;
+
+export class DeferredExecutor {
+  private toolRegistry: ToolRegistry | null = null;
+  private approvalManager: ApprovalManager;
+  private auditTrail: AuditTrail;
+  private learner: AuthorityLearner | null = null;
+  private onResult: ExecutionResultCallback | null = null;
+
+  constructor(approvalManager: ApprovalManager, auditTrail: AuditTrail) {
+    this.approvalManager = approvalManager;
+    this.auditTrail = auditTrail;
+  }
+
+  setToolRegistry(registry: ToolRegistry): void {
+    this.toolRegistry = registry;
+  }
+
+  setLearner(learner: AuthorityLearner): void {
+    this.learner = learner;
+  }
+
+  setResultCallback(cb: ExecutionResultCallback): void {
+    this.onResult = cb;
+  }
+
+  /**
+   * Execute a previously approved request.
+   */
+  async executeApproved(requestId: string): Promise<string> {
+    const request = this.approvalManager.getRequest(requestId);
+    if (!request || request.status !== 'approved') {
+      return `Error: Request ${requestId} not found or not in approved state`;
+    }
+
+    if (!this.toolRegistry) {
+      return 'Error: No tool registry configured';
+    }
+
+    const startTime = Date.now();
+
+    try {
+      const args = JSON.parse(request.tool_arguments);
+      const raw = await this.toolRegistry.execute(request.tool_name, args);
+      const result = typeof raw === 'string' ? raw : JSON.stringify(raw);
+
+      const executionTimeMs = Date.now() - startTime;
+
+      // Mark as executed
+      this.approvalManager.markExecuted(requestId, result.slice(0, 2000));
+
+      // Log to audit trail
+      this.auditTrail.log({
+        agent_id: request.agent_id,
+        agent_name: request.agent_name,
+        tool_name: request.tool_name,
+        action_category: request.action_category as ActionCategory,
+        authority_decision: 'approval_required',
+        approval_id: requestId,
+        executed: true,
+        execution_time_ms: executionTimeMs,
+      });
+
+      // Record approval for learning
+      this.learner?.recordDecision(
+        request.action_category as ActionCategory,
+        request.tool_name,
+        true
+      );
+
+      // Notify
+      this.onResult?.(requestId, request, result);
+
+      return result;
+    } catch (err) {
+      const errorStr = `Error executing ${request.tool_name}: ${err instanceof Error ? err.message : String(err)}`;
+      this.approvalManager.markExecuted(requestId, errorStr);
+      this.onResult?.(requestId, request, errorStr);
+      return errorStr;
+    }
+  }
+
+  /**
+   * Handle a denial — record for learning.
+   */
+  recordDenial(request: ApprovalRequest): void {
+    this.learner?.recordDecision(
+      request.action_category as ActionCategory,
+      request.tool_name,
+      false
+    );
+  }
+}

package/src/authority/emergency.ts

@@ -0,0 +1,66 @@
+/**
+ * Emergency controls: pause and kill switch.
+ */
+
+export type EmergencyState = 'normal' | 'paused' | 'killed';
+
+export class EmergencyController {
+  private state: EmergencyState = 'normal';
+  private onStateChange: ((state: EmergencyState) => void) | null = null;
+
+  getState(): EmergencyState {
+    return this.state;
+  }
+
+  /**
+   * Pause: freeze all agent tool execution. Agents can still receive messages
+   * but all tools return [SYSTEM PAUSED].
+   */
+  pause(): void {
+    if (this.state === 'killed') return; // Can't pause from killed
+    this.state = 'paused';
+    this.onStateChange?.(this.state);
+    console.log('[EmergencyController] System PAUSED — all tool execution suspended');
+  }
+
+  /**
+   * Resume from paused state.
+   */
+  resume(): void {
+    if (this.state !== 'paused') return;
+    this.state = 'normal';
+    this.onStateChange?.(this.state);
+    console.log('[EmergencyController] System RESUMED — tool execution restored');
+  }
+
+  /**
+   * Kill: terminate all agents, cancel all pending.
+   * Requires explicit reset() to recover.
+   */
+  kill(): void {
+    this.state = 'killed';
+    this.onStateChange?.(this.state);
+    console.log('[EmergencyController] System KILLED — all agents terminated');
+  }
+
+  /**
+   * Reset from killed state back to normal.
+   */
+  reset(): void {
+    if (this.state !== 'killed') return;
+    this.state = 'normal';
+    this.onStateChange?.(this.state);
+    console.log('[EmergencyController] System RESET — back to normal');
+  }
+
+  /**
+   * Check if tool execution is allowed.
+   */
+  canExecute(): boolean {
+    return this.state === 'normal';
+  }
+
+  setStateChangeCallback(cb: (state: EmergencyState) => void): void {
+    this.onStateChange = cb;
+  }
+}

package/src/authority/engine.ts

@@ -0,0 +1,297 @@
+/**
+ * Authority Engine — Central decision maker for tool execution authorization.
+ *
+ * Decision order:
+ * 1. Temporary grants (parent escalation) → allow
+ * 2. Per-action overrides for this role → explicit allow/deny
+ * 3. Context rules (time-based, tool-name-based) → allow/deny/require_approval
+ * 4. Numeric level check: level >= AUTHORITY_REQUIREMENTS[action]
+ * 5. Governed category check: if allowed but governed → requiresApproval
+ */
+
+import type { ActionCategory } from '../roles/authority.ts';
+import { AUTHORITY_REQUIREMENTS } from '../roles/authority.ts';
+
+export type PerActionOverride = {
+  action: ActionCategory;
+  role_id?: string;           // if unset, applies globally
+  allowed: boolean;           // true = always allow, false = always deny
+  requires_approval?: boolean; // if true, soft gate even when allowed
+};
+
+export type ContextRule = {
+  id: string;
+  action: ActionCategory;
+  condition: 'time_range' | 'tool_name' | 'always';
+  params: Record<string, unknown>;
+  effect: 'allow' | 'deny' | 'require_approval';
+  description: string;
+};
+
+export type AuthorityConfig = {
+  default_level: number;
+  governed_categories: ActionCategory[];
+  overrides: PerActionOverride[];
+  context_rules: ContextRule[];
+  learning: {
+    enabled: boolean;
+    suggest_threshold: number;
+  };
+  emergency_state: 'normal' | 'paused' | 'killed';
+};
+
+export type AuthorityDecision = {
+  allowed: boolean;
+  requiresApproval: boolean;
+  reason: string;
+  actionCategory: ActionCategory;
+  contextRule?: string;
+};
+
+export type AuthorityCheckParams = {
+  agentId: string;
+  agentAuthorityLevel: number;
+  agentRoleId: string;
+  toolName: string;
+  toolCategory: string;
+  actionCategory: ActionCategory;
+  temporaryGrants: Map<string, ActionCategory[]>;
+};
+
+export class AuthorityEngine {
+  private config: AuthorityConfig;
+
+  constructor(config: AuthorityConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Core decision function — determines if an action is allowed.
+   */
+  checkAuthority(params: AuthorityCheckParams): AuthorityDecision {
+    const { agentId, agentAuthorityLevel, agentRoleId, toolName, actionCategory, temporaryGrants } = params;
+
+    // 1. Check temporary grants (parent escalation)
+    const grants = temporaryGrants.get(agentId);
+    if (grants?.includes(actionCategory)) {
+      return {
+        allowed: true,
+        requiresApproval: false,
+        reason: 'Temporarily granted by parent agent',
+        actionCategory,
+      };
+    }
+
+    // 2. Check per-action overrides for this role
+    const override = this.findOverride(actionCategory, agentRoleId);
+    if (override) {
+      if (!override.allowed) {
+        return {
+          allowed: false,
+          requiresApproval: false,
+          reason: `Explicitly denied by override for ${agentRoleId || 'global'}`,
+          actionCategory,
+        };
+      }
+      if (override.requires_approval) {
+        return {
+          allowed: true,
+          requiresApproval: true,
+          reason: `Override requires approval for ${actionCategory}`,
+          actionCategory,
+        };
+      }
+      return {
+        allowed: true,
+        requiresApproval: false,
+        reason: `Explicitly allowed by override for ${agentRoleId || 'global'}`,
+        actionCategory,
+      };
+    }
+
+    // 3. Check context rules
+    const contextResult = this.evaluateContextRules(actionCategory, toolName);
+    if (contextResult) {
+      if (contextResult.effect === 'deny') {
+        return {
+          allowed: false,
+          requiresApproval: false,
+          reason: contextResult.description,
+          actionCategory,
+          contextRule: contextResult.id,
+        };
+      }
+      if (contextResult.effect === 'require_approval') {
+        return {
+          allowed: true,
+          requiresApproval: true,
+          reason: contextResult.description,
+          actionCategory,
+          contextRule: contextResult.id,
+        };
+      }
+      if (contextResult.effect === 'allow') {
+        return {
+          allowed: true,
+          requiresApproval: false,
+          reason: contextResult.description,
+          actionCategory,
+          contextRule: contextResult.id,
+        };
+      }
+    }
+
+    // 4. Numeric level check
+    const requiredLevel = AUTHORITY_REQUIREMENTS[actionCategory];
+    if (agentAuthorityLevel < requiredLevel) {
+      return {
+        allowed: false,
+        requiresApproval: false,
+        reason: `Authority level ${agentAuthorityLevel} is below required ${requiredLevel} for ${actionCategory}`,
+        actionCategory,
+      };
+    }
+
+    // 5. Governed category check — if level is sufficient but action is governed, require approval
+    if (this.config.governed_categories.includes(actionCategory)) {
+      return {
+        allowed: true,
+        requiresApproval: true,
+        reason: `${actionCategory} is a governed action requiring user approval`,
+        actionCategory,
+      };
+    }
+
+    // Allowed without approval
+    return {
+      allowed: true,
+      requiresApproval: false,
+      reason: `Authority level ${agentAuthorityLevel} meets requirement ${requiredLevel}`,
+      actionCategory,
+    };
+  }
+
+  /**
+   * Generate human-readable authority rules for the system prompt.
+   */
+  describeRulesForAgent(authorityLevel: number, roleId: string): string {
+    const lines: string[] = [];
+
+    lines.push(`Your authority level: ${authorityLevel}/10`);
+    lines.push('');
+
+    // Governed categories
+    if (this.config.governed_categories.length > 0) {
+      lines.push('Actions requiring user approval before execution:');
+      for (const cat of this.config.governed_categories) {
+        lines.push(`  - ${cat}`);
+      }
+      lines.push('');
+    }
+
+    // Active overrides for this role
+    const roleOverrides = this.config.overrides.filter(
+      o => !o.role_id || o.role_id === roleId
+    );
+    if (roleOverrides.length > 0) {
+      lines.push('Special permission overrides:');
+      for (const o of roleOverrides) {
+        const scope = o.role_id ? `[${o.role_id}]` : '[global]';
+        const status = o.allowed
+          ? (o.requires_approval ? 'allowed with approval' : 'always allowed')
+          : 'denied';
+        lines.push(`  - ${o.action}: ${status} ${scope}`);
+      }
+      lines.push('');
+    }
+
+    // Active context rules
+    if (this.config.context_rules.length > 0) {
+      lines.push('Context-based rules:');
+      for (const rule of this.config.context_rules) {
+        lines.push(`  - ${rule.description}`);
+      }
+    }
+
+    return lines.join('\n');
+  }
+
+  // --- Config management ---
+
+  addOverride(override: PerActionOverride): void {
+    // Remove existing override for same action+role before adding
+    this.removeOverride(override.action, override.role_id);
+    this.config.overrides.push(override);
+  }
+
+  removeOverride(action: ActionCategory, roleId?: string): void {
+    this.config.overrides = this.config.overrides.filter(
+      o => !(o.action === action && o.role_id === roleId)
+    );
+  }
+
+  addContextRule(rule: ContextRule): void {
+    this.config.context_rules.push(rule);
+  }
+
+  removeContextRule(id: string): void {
+    this.config.context_rules = this.config.context_rules.filter(r => r.id !== id);
+  }
+
+  setGovernedCategories(categories: ActionCategory[]): void {
+    this.config.governed_categories = categories;
+  }
+
+  getConfig(): AuthorityConfig {
+    return { ...this.config };
+  }
+
+  updateConfig(config: AuthorityConfig): void {
+    this.config = config;
+  }
+
+  // --- Private helpers ---
+
+  private findOverride(action: ActionCategory, roleId: string): PerActionOverride | null {
+    // Role-specific override takes priority over global
+    const roleSpecific = this.config.overrides.find(
+      o => o.action === action && o.role_id === roleId
+    );
+    if (roleSpecific) return roleSpecific;
+
+    const global = this.config.overrides.find(
+      o => o.action === action && !o.role_id
+    );
+    return global ?? null;
+  }
+
+  private evaluateContextRules(action: ActionCategory, toolName: string): ContextRule | null {
+    for (const rule of this.config.context_rules) {
+      if (rule.action !== action) continue;
+
+      switch (rule.condition) {
+        case 'time_range': {
+          const now = new Date();
+          const hour = now.getHours();
+          const startHour = (rule.params.start_hour as number) ?? 0;
+          const endHour = (rule.params.end_hour as number) ?? 24;
+          if (hour >= startHour && hour < endHour) {
+            return rule;
+          }
+          break;
+        }
+        case 'tool_name': {
+          const toolPattern = rule.params.tool_name as string;
+          if (toolPattern && (toolName === toolPattern || toolName.startsWith(toolPattern))) {
+            return rule;
+          }
+          break;
+        }
+        case 'always': {
+          return rule;
+        }
+      }
+    }
+    return null;
+  }
+}

package/src/authority/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Authority & Autonomy Engine — Barrel exports
+ */
+
+export { AuthorityEngine, type AuthorityConfig, type AuthorityDecision, type AuthorityCheckParams, type PerActionOverride, type ContextRule } from './engine.ts';
+export { ApprovalManager, type ApprovalRequest, type ApprovalStatus, type ApprovalUrgency } from './approval.ts';
+export { AuditTrail, type AuditEntry, type AuthorityDecisionType } from './audit.ts';
+export { AuthorityLearner } from './learning.ts';
+export { EmergencyController, type EmergencyState } from './emergency.ts';
+export { ApprovalDelivery } from './approval-delivery.ts';
+export { DeferredExecutor } from './deferred-executor.ts';
+export { getActionForTool, TOOL_ACTION_MAP, CATEGORY_ACTION_MAP } from './tool-action-map.ts';

package/src/authority/learning.ts

@@ -0,0 +1,111 @@
+/**
+ * Authority Learner — Tracks approval patterns and suggests auto-approve rules.
+ *
+ * After N consecutive approvals of the same action+tool pattern,
+ * suggests adding a persistent override so the user doesn't have to
+ * keep approving the same thing.
+ */
+
+import { getDb, generateId } from '../vault/schema.ts';
+import type { ActionCategory } from '../roles/authority.ts';
+import type { PerActionOverride } from './engine.ts';
+
+const DEFAULT_SUGGEST_THRESHOLD = 5;
+
+export class AuthorityLearner {
+  private threshold: number;
+
+  constructor(threshold: number = DEFAULT_SUGGEST_THRESHOLD) {
+    this.threshold = threshold;
+  }
+
+  /**
+   * Record an approval or denial decision.
+   * Approvals increment the consecutive count; denials reset it.
+   */
+  recordDecision(actionCategory: ActionCategory, toolName: string, approved: boolean): void {
+    const db = getDb();
+    const now = Date.now();
+
+    if (approved) {
+      // Try to increment existing pattern
+      const result = db.run(
+        `UPDATE approval_patterns
+         SET consecutive_approvals = consecutive_approvals + 1, last_approval_at = ?
+         WHERE action_category = ? AND tool_name = ?`,
+        [now, actionCategory, toolName]
+      );
+
+      // Create pattern if it doesn't exist
+      if (result.changes === 0) {
+        db.run(
+          `INSERT INTO approval_patterns (id, action_category, tool_name, consecutive_approvals, last_approval_at, suggestion_sent)
+           VALUES (?, ?, ?, 1, ?, 0)`,
+          [generateId(), actionCategory, toolName, now]
+        );
+      }
+    } else {
+      // Denial resets the consecutive count
+      db.run(
+        `UPDATE approval_patterns
+         SET consecutive_approvals = 0, suggestion_sent = 0
+         WHERE action_category = ? AND tool_name = ?`,
+        [actionCategory, toolName]
+      );
+    }
+  }
+
+  /**
+   * Get patterns that have crossed the suggestion threshold.
+   */
+  getSuggestions(): Array<{
+    actionCategory: ActionCategory;
+    toolName: string;
+    consecutiveApprovals: number;
+    suggestedRule: PerActionOverride;
+  }> {
+    const db = getDb();
+    const rows = db.query(
+      `SELECT * FROM approval_patterns
+       WHERE consecutive_approvals >= ? AND suggestion_sent = 0
+       ORDER BY consecutive_approvals DESC`
+    ).all(this.threshold) as Array<{
+      action_category: string;
+      tool_name: string;
+      consecutive_approvals: number;
+    }>;
+
+    return rows.map(row => ({
+      actionCategory: row.action_category as ActionCategory,
+      toolName: row.tool_name,
+      consecutiveApprovals: row.consecutive_approvals,
+      suggestedRule: {
+        action: row.action_category as ActionCategory,
+        allowed: true,
+        requires_approval: false, // Auto-approve
+      },
+    }));
+  }
+
+  /**
+   * Mark a suggestion as sent so we don't re-suggest.
+   */
+  markSuggestionSent(actionCategory: ActionCategory, toolName: string): void {
+    const db = getDb();
+    db.run(
+      `UPDATE approval_patterns SET suggestion_sent = 1 WHERE action_category = ? AND tool_name = ?`,
+      [actionCategory, toolName]
+    );
+  }
+
+  /**
+   * Reset a pattern (e.g., when user dismisses a suggestion).
+   */
+  resetPattern(actionCategory: ActionCategory, toolName: string): void {
+    const db = getDb();
+    db.run(
+      `UPDATE approval_patterns SET consecutive_approvals = 0, suggestion_sent = 0 WHERE action_category = ? AND tool_name = ?`,
+      [actionCategory, toolName]
+    );
+  }
+}

package/src/authority/tool-action-map.ts

@@ -0,0 +1,74 @@
+/**
+ * Maps tool names and categories to ActionCategory for authority checks.
+ */
+
+import type { ActionCategory } from '../roles/authority.ts';
+
+/**
+ * Explicit mapping from tool name -> ActionCategory
+ */
+export const TOOL_ACTION_MAP: Record<string, ActionCategory> = {
+  // Terminal
+  run_command: 'execute_command',
+
+  // File ops
+  read_file: 'read_data',
+  write_file: 'write_data',
+  list_directory: 'read_data',
+
+  // Browser
+  browser_navigate: 'access_browser',
+  browser_snapshot: 'access_browser',
+  browser_click: 'access_browser',
+  browser_type: 'access_browser',
+  browser_scroll: 'access_browser',
+  browser_evaluate: 'access_browser',
+  browser_screenshot: 'access_browser',
+
+  // Desktop
+  desktop_list_windows: 'control_app',
+  desktop_focus_window: 'control_app',
+  desktop_snapshot: 'control_app',
+  desktop_click: 'control_app',
+  desktop_type: 'control_app',
+  desktop_press_keys: 'control_app',
+  desktop_launch_app: 'control_app',
+  desktop_screenshot: 'control_app',
+
+  // Delegation
+  delegate_task: 'spawn_agent',
+  manage_agents: 'spawn_agent',
+
+  // Content / tasks
+  content_pipeline: 'write_data',
+  commitments: 'write_data',
+  research_queue: 'read_data',
+};
+
+/**
+ * Fallback mapping from tool category -> ActionCategory
+ */
+export const CATEGORY_ACTION_MAP: Record<string, ActionCategory> = {
+  terminal: 'execute_command',
+  'file-ops': 'write_data',
+  browser: 'access_browser',
+  desktop: 'control_app',
+  delegation: 'spawn_agent',
+  content: 'write_data',
+  tasks: 'write_data',
+  productivity: 'read_data',
+};
+
+/**
+ * Resolve the ActionCategory for a given tool.
+ * Checks explicit tool name map first, then falls back to category map, then defaults to read_data.
+ */
+export function getActionForTool(toolName: string, toolCategory: string): ActionCategory {
+  if (TOOL_ACTION_MAP[toolName]) {
+    return TOOL_ACTION_MAP[toolName];
+  }
+  if (CATEGORY_ACTION_MAP[toolCategory]) {
+    return CATEGORY_ACTION_MAP[toolCategory];
+  }
+  return 'read_data';
+}