@usejarvis/brain 0.1.0

package/src/roles/utils.ts

@@ -0,0 +1,200 @@
+/**
+ * Utility functions for working with roles
+ */
+
+import type { RoleDefinition } from './types.ts';
+import type { ActionCategory } from './authority.ts';
+import { canPerform, listAllowedActions } from './authority.ts';
+
+/**
+ * Find roles that can perform a specific action
+ */
+export function findRolesWithPermission(
+  roles: Map<string, RoleDefinition>,
+  action: ActionCategory
+): RoleDefinition[] {
+  const result: RoleDefinition[] = [];
+
+  for (const role of roles.values()) {
+    if (canPerform(role, action)) {
+      result.push(role);
+    }
+  }
+
+  return result.sort((a, b) => a.authority_level - b.authority_level);
+}
+
+/**
+ * Find the least privileged role that can perform an action
+ */
+export function findMinimalRoleForAction(
+  roles: Map<string, RoleDefinition>,
+  action: ActionCategory
+): RoleDefinition | null {
+  const capable = findRolesWithPermission(roles, action);
+  return capable.length > 0 ? capable[0]! : null;
+}
+
+/**
+ * Compare two roles and show permission differences
+ */
+export function compareRoles(
+  role1: RoleDefinition,
+  role2: RoleDefinition
+): {
+  onlyInRole1: ActionCategory[];
+  onlyInRole2: ActionCategory[];
+  inBoth: ActionCategory[];
+} {
+  const actions1 = new Set(listAllowedActions(role1));
+  const actions2 = new Set(listAllowedActions(role2));
+
+  const onlyInRole1: ActionCategory[] = [];
+  const onlyInRole2: ActionCategory[] = [];
+  const inBoth: ActionCategory[] = [];
+
+  for (const action of actions1) {
+    if (actions2.has(action)) {
+      inBoth.push(action);
+    } else {
+      onlyInRole1.push(action);
+    }
+  }
+
+  for (const action of actions2) {
+    if (!actions1.has(action)) {
+      onlyInRole2.push(action);
+    }
+  }
+
+  return { onlyInRole1, onlyInRole2, inBoth };
+}
+
+/**
+ * Get a summary of role hierarchy based on authority levels
+ */
+export function getRoleHierarchy(roles: Map<string, RoleDefinition>): string {
+  const sorted = Array.from(roles.values()).sort(
+    (a, b) => b.authority_level - a.authority_level
+  );
+
+  const lines: string[] = [];
+  let currentLevel = -1;
+
+  for (const role of sorted) {
+    if (role.authority_level !== currentLevel) {
+      currentLevel = role.authority_level;
+      lines.push(`\nLevel ${currentLevel}:`);
+    }
+    lines.push(`  - ${role.name} (${role.id})`);
+  }
+
+  return lines.join('\n').trim();
+}
+
+/**
+ * Check if a role can spawn a specific sub-role
+ */
+export function canSpawnRole(
+  role: RoleDefinition,
+  subRoleId: string
+): boolean {
+  return role.sub_roles.some(sr => sr.role_id === subRoleId);
+}
+
+/**
+ * Get all roles that can spawn a specific role
+ */
+export function findSpawnersOfRole(
+  roles: Map<string, RoleDefinition>,
+  targetRoleId: string
+): RoleDefinition[] {
+  const spawners: RoleDefinition[] = [];
+
+  for (const role of roles.values()) {
+    if (canSpawnRole(role, targetRoleId)) {
+      spawners.push(role);
+    }
+  }
+
+  return spawners;
+}
+
+/**
+ * Validate role hierarchy (check for circular dependencies)
+ */
+export function validateRoleHierarchy(
+  roles: Map<string, RoleDefinition>
+): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  for (const [id, role] of roles) {
+    // Check if sub-roles exist
+    for (const subRole of role.sub_roles) {
+      if (!roles.has(subRole.role_id)) {
+        errors.push(
+          `Role '${id}' references non-existent sub-role '${subRole.role_id}'`
+        );
+      }
+
+      // Check for self-spawning
+      if (subRole.role_id === id) {
+        errors.push(`Role '${id}' attempts to spawn itself`);
+      }
+
+      // Check authority levels (parent should have higher authority)
+      const subRoleDef = roles.get(subRole.role_id);
+      if (subRoleDef && subRoleDef.authority_level > role.authority_level) {
+        errors.push(
+          `Role '${id}' (level ${role.authority_level}) attempts to spawn ` +
+          `'${subRole.role_id}' (level ${subRoleDef.authority_level}) with higher authority`
+        );
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Get statistics about a role collection
+ */
+export function getRoleStats(roles: Map<string, RoleDefinition>): {
+  totalRoles: number;
+  averageAuthorityLevel: number;
+  totalTools: number;
+  totalKPIs: number;
+  rolesWithSubRoles: number;
+  authorityDistribution: Record<number, number>;
+} {
+  let totalAuthority = 0;
+  let totalTools = 0;
+  let totalKPIs = 0;
+  let rolesWithSubRoles = 0;
+  const authorityDistribution: Record<number, number> = {};
+
+  for (const role of roles.values()) {
+    totalAuthority += role.authority_level;
+    totalTools += role.tools.length;
+    totalKPIs += role.kpis.length;
+
+    if (role.sub_roles.length > 0) {
+      rolesWithSubRoles++;
+    }
+
+    authorityDistribution[role.authority_level] =
+      (authorityDistribution[role.authority_level] || 0) + 1;
+  }
+
+  return {
+    totalRoles: roles.size,
+    averageAuthorityLevel: roles.size > 0 ? totalAuthority / roles.size : 0,
+    totalTools,
+    totalKPIs,
+    rolesWithSubRoles,
+    authorityDistribution,
+  };
+}

package/src/scripts/google-setup.ts

@@ -0,0 +1,168 @@
+/**
+ * Google OAuth2 Setup Script
+ *
+ * Interactive CLI to authenticate JARVIS with Google APIs.
+ * Opens browser to Google consent screen, handles callback,
+ * and saves tokens to ~/.jarvis/google-tokens.json.
+ *
+ * Usage: bun run src/scripts/google-setup.ts
+ */
+
+import { GoogleAuth } from '../integrations/google-auth.ts';
+import { loadConfig } from '../config/loader.ts';
+
+const SCOPES = [
+  'https://www.googleapis.com/auth/gmail.readonly',
+  'https://www.googleapis.com/auth/calendar.readonly',
+];
+
+async function main() {
+  console.log('');
+  console.log('=== Google OAuth2 Setup for JARVIS ===');
+  console.log('');
+
+  // Load config to get client_id / client_secret
+  const config = await loadConfig();
+
+  let clientId = config.google?.client_id ?? '';
+  let clientSecret = config.google?.client_secret ?? '';
+
+  if (!clientId || !clientSecret) {
+    console.log('No Google OAuth credentials found in config.yaml.');
+    console.log('');
+    console.log('Add the following to your ~/.jarvis/config.yaml:');
+    console.log('');
+    console.log('google:');
+    console.log('  client_id: "your-client-id.apps.googleusercontent.com"');
+    console.log('  client_secret: "your-client-secret"');
+    console.log('');
+    console.log('To get credentials:');
+    console.log('  1. Go to https://console.cloud.google.com/apis/credentials');
+    console.log('  2. Create an OAuth2 client ID (Web application)');
+    console.log('  3. Add http://localhost:3142/api/auth/google/callback as a redirect URI');
+    console.log('  4. Copy client_id and client_secret into config.yaml');
+    console.log('');
+
+    // Try reading from stdin
+    const rl = require('readline').createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    const ask = (q: string): Promise<string> =>
+      new Promise((resolve) => rl.question(q, resolve));
+
+    clientId = (await ask('Client ID (or press Enter to abort): ')).trim();
+    if (!clientId) {
+      console.log('Aborted.');
+      rl.close();
+      process.exit(1);
+    }
+
+    clientSecret = (await ask('Client Secret: ')).trim();
+    if (!clientSecret) {
+      console.log('Aborted.');
+      rl.close();
+      process.exit(1);
+    }
+
+    rl.close();
+  }
+
+  const auth = new GoogleAuth(clientId, clientSecret);
+
+  // Check if already authenticated
+  if (auth.isAuthenticated()) {
+    console.log('Already authenticated! Tokens exist at ~/.jarvis/google-tokens.json');
+    console.log('To re-authenticate, delete that file and run this again.');
+    process.exit(0);
+  }
+
+  const authUrl = auth.getAuthUrl(SCOPES);
+
+  console.log('');
+  console.log('Opening browser for Google authorization...');
+  console.log('');
+  console.log('If the browser does not open, visit this URL:');
+  console.log(authUrl);
+  console.log('');
+
+  // Try to open browser
+  try {
+    const opener = process.platform === 'darwin'
+      ? 'open'
+      : process.platform === 'win32'
+        ? 'start'
+        : 'xdg-open';
+    Bun.spawn([opener, authUrl], { stdout: 'ignore', stderr: 'ignore' });
+  } catch {
+    // Ignore — user can open manually
+  }
+
+  // Start temporary HTTP server to receive the callback
+  console.log('Waiting for authorization callback on port 3142...');
+  console.log('');
+
+  const server = Bun.serve({
+    port: 3142,
+    async fetch(req) {
+      const url = new URL(req.url);
+
+      if (url.pathname === '/api/auth/google/callback') {
+        const code = url.searchParams.get('code');
+        const error = url.searchParams.get('error');
+
+        if (error) {
+          console.error('Authorization denied:', error);
+          setTimeout(() => {
+            server.stop();
+            process.exit(1);
+          }, 500);
+          return new Response(
+            '<html><body><h1>Authorization Denied</h1><p>You can close this tab.</p></body></html>',
+            { headers: { 'Content-Type': 'text/html' } }
+          );
+        }
+
+        if (!code) {
+          return new Response('Missing code', { status: 400 });
+        }
+
+        try {
+          const tokens = await auth.exchangeCode(code);
+          console.log('Authorization successful!');
+          console.log(`Access token: ${tokens.access_token.slice(0, 20)}...`);
+          console.log(`Refresh token: ${tokens.refresh_token.slice(0, 20)}...`);
+          console.log(`Tokens saved to ~/.jarvis/google-tokens.json`);
+
+          setTimeout(() => {
+            server.stop();
+            process.exit(0);
+          }, 500);
+
+          return new Response(
+            '<html><body><h1>JARVIS Google Authorization Complete!</h1><p>Tokens saved. You can close this tab.</p></body></html>',
+            { headers: { 'Content-Type': 'text/html' } }
+          );
+        } catch (err) {
+          console.error('Token exchange failed:', err);
+          setTimeout(() => {
+            server.stop();
+            process.exit(1);
+          }, 500);
+          return new Response(
+            `<html><body><h1>Token Exchange Failed</h1><pre>${err}</pre></body></html>`,
+            { headers: { 'Content-Type': 'text/html' }, status: 500 }
+          );
+        }
+      }
+
+      return new Response('Not found', { status: 404 });
+    },
+  });
+}
+
+main().catch((err) => {
+  console.error('Setup failed:', err);
+  process.exit(1);
+});

package/src/sidecar/connection.ts

@@ -0,0 +1,179 @@
+/**
+ * Sidecar Connection — Per-Sidecar WebSocket Wrapper
+ *
+ * Manages a single sidecar's WebSocket connection, including message
+ * parsing, validation, binary frame correlation, and heartbeat.
+ */
+
+import type { ServerWebSocket } from 'bun';
+import type { RPCRequest, SidecarEvent } from './protocol.ts';
+import type { EventScheduler } from './scheduler.ts';
+import { validateEvent, validateBinaryFrame, MAX_JSON_SIZE } from './validator.ts';
+
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const MAX_MISSED_PONGS = 3;
+const BINARY_WAIT_TIMEOUT_MS = 5_000;
+
+interface PendingBinary {
+  resolve: (payload: Buffer) => void;
+  reject: (error: Error) => void;
+  timer: Timer;
+}
+
+export class SidecarConnection {
+  readonly sidecarId: string;
+  private ws: ServerWebSocket<unknown>;
+  private scheduler: EventScheduler;
+  private pendingBinary = new Map<string, PendingBinary>();
+  private heartbeatTimer: Timer | null = null;
+  private missedPongs = 0;
+  private alive = true;
+  private onDisconnect: () => void;
+
+  constructor(
+    sidecarId: string,
+    ws: ServerWebSocket<unknown>,
+    scheduler: EventScheduler,
+    onDisconnect: () => void,
+  ) {
+    this.sidecarId = sidecarId;
+    this.ws = ws;
+    this.scheduler = scheduler;
+    this.onDisconnect = onDisconnect;
+  }
+
+  /** Send an RPC request to the sidecar */
+  sendRPC(request: RPCRequest): void {
+    try {
+      this.ws.send(JSON.stringify(request));
+    } catch (err) {
+      console.error(`[SidecarConnection:${this.sidecarId}] Failed to send RPC:`, err);
+    }
+  }
+
+  /** Handle an inbound text (JSON) message */
+  async handleMessage(raw: string): Promise<void> {
+    if (raw.length > MAX_JSON_SIZE) {
+      console.warn(`[SidecarConnection:${this.sidecarId}] Message too large: ${raw.length} bytes`);
+      return;
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      console.warn(`[SidecarConnection:${this.sidecarId}] Invalid JSON`);
+      return;
+    }
+
+    const result = validateEvent(parsed);
+    if (!result.valid || !result.event) {
+      console.warn(`[SidecarConnection:${this.sidecarId}] Validation failed: ${result.error}`);
+      return;
+    }
+
+    const event = result.event;
+
+    // If event references binary data via ref, wait for the binary frame
+    if (event.binary?.type === 'ref') {
+      const refId = event.binary.ref_id;
+      try {
+        const binaryPayload = await this.waitForBinary(refId);
+        // Attach resolved binary data to the event payload
+        (event.payload as Record<string, unknown>)._binary = binaryPayload;
+      } catch (err) {
+        console.warn(`[SidecarConnection:${this.sidecarId}] Binary wait failed for ${refId}:`, err);
+        return;
+      }
+    }
+
+    this.scheduler.enqueue(this.sidecarId, event, event.priority);
+  }
+
+  /** Handle an inbound binary frame */
+  handleBinary(data: Buffer): void {
+    const result = validateBinaryFrame(data);
+    if (!result.valid || !result.refId) {
+      console.warn(`[SidecarConnection:${this.sidecarId}] Invalid binary frame: ${result.error}`);
+      return;
+    }
+
+    const pending = this.pendingBinary.get(result.refId);
+    if (pending) {
+      clearTimeout(pending.timer);
+      this.pendingBinary.delete(result.refId);
+      pending.resolve(result.payload!);
+    } else {
+      console.warn(`[SidecarConnection:${this.sidecarId}] Unexpected binary ref: ${result.refId}`);
+    }
+  }
+
+  /** Start heartbeat ping/pong */
+  startHeartbeat(): void {
+    this.missedPongs = 0;
+    this.alive = true;
+
+    this.heartbeatTimer = setInterval(() => {
+      if (!this.alive) {
+        this.missedPongs++;
+        if (this.missedPongs >= MAX_MISSED_PONGS) {
+          console.warn(`[SidecarConnection:${this.sidecarId}] ${MAX_MISSED_PONGS} missed pongs, disconnecting`);
+          this.close();
+          this.onDisconnect();
+          return;
+        }
+      }
+
+      this.alive = false;
+      try {
+        this.ws.ping();
+      } catch {
+        this.close();
+        this.onDisconnect();
+      }
+    }, HEARTBEAT_INTERVAL_MS);
+  }
+
+  /** Called when a pong is received */
+  handlePong(): void {
+    this.alive = true;
+    this.missedPongs = 0;
+  }
+
+  /** Stop heartbeat */
+  stopHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+
+  /** Close connection and clean up */
+  close(): void {
+    this.stopHeartbeat();
+
+    // Reject all pending binary waits
+    for (const [refId, pending] of this.pendingBinary) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error('Connection closed'));
+    }
+    this.pendingBinary.clear();
+
+    try {
+      this.ws.close();
+    } catch {
+      // Already closed
+    }
+  }
+
+  private waitForBinary(refId: string): Promise<Buffer> {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingBinary.delete(refId);
+        reject(new Error(`Binary frame timeout for ref ${refId}`));
+      }, BINARY_WAIT_TIMEOUT_MS);
+
+      this.pendingBinary.set(refId, { resolve, reject, timer });
+    });
+  }
+}

package/src/sidecar/index.ts

@@ -0,0 +1,6 @@
+export { SidecarManager } from './manager.ts';
+export { EventScheduler } from './scheduler.ts';
+export { RPCTracker } from './rpc.ts';
+export { SidecarConnection } from './connection.ts';
+export type * from './types.ts';
+export type * from './protocol.ts';