@usejarvis/brain 0.1.0

package/src/sidecar/rpc.ts

@@ -0,0 +1,161 @@
+/**
+ * RPC Tracker — Two-Timeout State Machine
+ *
+ * Tracks outbound RPC requests with an initial timeout (fast ack)
+ * and a max timeout (detached execution). Resolves promises accordingly.
+ */
+
+import type { RPCState, RPCTimeouts, RPCRequest } from './protocol.ts';
+import { DEFAULT_RPC_TIMEOUTS } from './protocol.ts';
+
+export interface PendingRPC {
+  id: string;
+  sidecarId: string;
+  method: string;
+  state: RPCState;
+  createdAt: number;
+  /** Resolves the dispatch() promise. For pending: result value. For detached: "detached" string. */
+  resolve: (value: unknown) => void;
+  reject: (error: Error) => void;
+  initialTimer: Timer | null;
+  maxTimer: Timer | null;
+  /** Callback invoked when a detached RPC completes */
+  detachedCallback?: (rpcId: string, result: unknown) => void;
+}
+
+export type DetachedCompleteCallback = (rpcId: string, result: unknown, error?: Error) => void;
+
+export class RPCTracker {
+  private pending = new Map<string, PendingRPC>();
+  private detachedCallback: DetachedCompleteCallback | null = null;
+
+  /** Register a global callback for when detached RPCs complete */
+  onDetachedComplete(callback: DetachedCompleteCallback): void {
+    this.detachedCallback = callback;
+  }
+
+  /**
+   * Dispatch an RPC: creates a tracked entry, sets initial timer.
+   * Returns the result if it arrives within initial_timeout, or "detached" if it transitions.
+   */
+  dispatch(
+    rpcId: string,
+    sidecarId: string,
+    method: string,
+    timeouts: RPCTimeouts = DEFAULT_RPC_TIMEOUTS,
+  ): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      const entry: PendingRPC = {
+        id: rpcId,
+        sidecarId,
+        method,
+        state: 'pending',
+        createdAt: Date.now(),
+        resolve,
+        reject,
+        initialTimer: null,
+        maxTimer: null,
+      };
+
+      // Initial timeout: transition to DETACHED
+      entry.initialTimer = setTimeout(() => {
+        if (entry.state !== 'pending') return;
+
+        entry.state = 'detached';
+        entry.initialTimer = null;
+
+        // Resolve the dispatch promise with "detached"
+        resolve('detached');
+
+        // Start max timeout
+        entry.maxTimer = setTimeout(() => {
+          if (entry.state !== 'detached') return;
+          entry.state = 'timed_out';
+          this.pending.delete(rpcId);
+          console.warn(`[RPCTracker] RPC ${rpcId} (${method}) timed out after max timeout`);
+        }, timeouts.max);
+      }, timeouts.initial);
+
+      this.pending.set(rpcId, entry);
+    });
+  }
+
+  /** Called when an rpc_result event arrives. Resolves/rejects the RPC. */
+  resolve(rpcId: string, result: unknown): void {
+    const entry = this.pending.get(rpcId);
+    if (!entry) return;
+
+    this.clearTimers(entry);
+
+    if (entry.state === 'pending') {
+      // Fast path: result arrived within initial timeout
+      entry.state = 'completed';
+      entry.resolve(result);
+    } else if (entry.state === 'detached') {
+      // Late arrival: dispatch promise already resolved with "detached"
+      entry.state = 'completed';
+      this.detachedCallback?.(rpcId, result);
+    }
+
+    this.pending.delete(rpcId);
+  }
+
+  /** Called when an rpc_result with error arrives. */
+  fail(rpcId: string, error: Error): void {
+    const entry = this.pending.get(rpcId);
+    if (!entry) return;
+
+    this.clearTimers(entry);
+
+    if (entry.state === 'pending') {
+      entry.state = 'failed';
+      entry.reject(error);
+    } else if (entry.state === 'detached') {
+      entry.state = 'failed';
+      this.detachedCallback?.(rpcId, undefined, error);
+    }
+
+    this.pending.delete(rpcId);
+  }
+
+  /** Fail all pending RPCs for a disconnected sidecar */
+  failAll(sidecarId: string, reason: string): void {
+    for (const [rpcId, entry] of this.pending) {
+      if (entry.sidecarId !== sidecarId) continue;
+
+      this.clearTimers(entry);
+
+      const error = new Error(`Sidecar disconnected: ${reason}`);
+      if (entry.state === 'pending') {
+        entry.state = 'failed';
+        entry.reject(error);
+      } else if (entry.state === 'detached') {
+        entry.state = 'failed';
+        this.detachedCallback?.(rpcId, undefined, error);
+      }
+
+      this.pending.delete(rpcId);
+    }
+  }
+
+  /** Get a pending RPC by ID */
+  get(rpcId: string): PendingRPC | undefined {
+    return this.pending.get(rpcId);
+  }
+
+  /** Get count of pending RPCs */
+  get size(): number {
+    return this.pending.size;
+  }
+
+  private clearTimers(entry: PendingRPC): void {
+    if (entry.initialTimer) {
+      clearTimeout(entry.initialTimer);
+      entry.initialTimer = null;
+    }
+    if (entry.maxTimer) {
+      clearTimeout(entry.maxTimer);
+      entry.maxTimer = null;
+    }
+  }
+}

package/src/sidecar/scheduler.ts

@@ -0,0 +1,136 @@
+/**
+ * Event Scheduler — Round-Robin Fairness
+ *
+ * Processes sidecar events with round-robin scheduling across sidecars
+ * to prevent any single sidecar from monopolizing event handling.
+ */
+
+import type { SidecarEvent, EventPriority } from './protocol.ts';
+
+interface QueuedEvent {
+  sidecarId: string;
+  event: SidecarEvent;
+  priority: EventPriority;
+  enqueuedAt: number;
+}
+
+type EventHandler = (sidecarId: string, event: SidecarEvent) => Promise<void>;
+
+export class EventScheduler {
+  private queues = new Map<string, QueuedEvent[]>();
+  private sidecarIds: string[] = [];
+  private roundRobinIndex = 0;
+  private handlers = new Map<string, EventHandler[]>();
+  private running = false;
+  private processing = false;
+  private drainTimer: Timer | null = null;
+  private readonly drainIntervalMs: number;
+
+  constructor(drainIntervalMs = 50) {
+    this.drainIntervalMs = drainIntervalMs;
+  }
+
+  /** Register a handler for a specific event_type */
+  on(eventType: string, handler: EventHandler): void {
+    const existing = this.handlers.get(eventType) ?? [];
+    existing.push(handler);
+    this.handlers.set(eventType, existing);
+  }
+
+  /** Enqueue an event from a sidecar */
+  enqueue(sidecarId: string, event: SidecarEvent, priority?: EventPriority): void {
+    let queue = this.queues.get(sidecarId);
+    if (!queue) {
+      queue = [];
+      this.queues.set(sidecarId, queue);
+      this.sidecarIds.push(sidecarId);
+    }
+
+    queue.push({
+      sidecarId,
+      event,
+      priority: priority ?? event.priority ?? 'normal',
+      enqueuedAt: Date.now(),
+    });
+
+    // Sort by priority within each sidecar's queue
+    queue.sort((a, b) => priorityWeight(a.priority) - priorityWeight(b.priority));
+  }
+
+  /** Remove a sidecar's queue (on disconnect) */
+  removeSidecar(sidecarId: string): void {
+    this.queues.delete(sidecarId);
+    this.sidecarIds = this.sidecarIds.filter(id => id !== sidecarId);
+    if (this.roundRobinIndex >= this.sidecarIds.length) {
+      this.roundRobinIndex = 0;
+    }
+  }
+
+  /** Start the processing loop */
+  start(): void {
+    if (this.running) return;
+    this.running = true;
+    this.drainTimer = setInterval(() => this.drain(), this.drainIntervalMs);
+  }
+
+  /** Stop the processing loop */
+  stop(): void {
+    this.running = false;
+    if (this.drainTimer) {
+      clearInterval(this.drainTimer);
+      this.drainTimer = null;
+    }
+  }
+
+  private async drain(): Promise<void> {
+    if (this.processing || this.sidecarIds.length === 0) return;
+    this.processing = true;
+
+    try {
+      // One round-robin pass: try each sidecar once
+      const count = this.sidecarIds.length;
+      for (let i = 0; i < count; i++) {
+        const idx = (this.roundRobinIndex + i) % count;
+        const sidecarId = this.sidecarIds[idx]!;
+        const queue = this.queues.get(sidecarId);
+
+        if (!queue || queue.length === 0) continue;
+
+        const item = queue.shift()!;
+        this.roundRobinIndex = (idx + 1) % count;
+
+        await this.dispatch(item);
+
+        // Process one event per drain tick to stay non-blocking
+        break;
+      }
+    } catch (err) {
+      console.error('[EventScheduler] Drain error:', err);
+    } finally {
+      this.processing = false;
+    }
+  }
+
+  private async dispatch(item: QueuedEvent): Promise<void> {
+    const handlers = this.handlers.get(item.event.event_type) ?? [];
+    const wildcardHandlers = this.handlers.get('*') ?? [];
+    const allHandlers = [...handlers, ...wildcardHandlers];
+
+    for (const handler of allHandlers) {
+      try {
+        await handler(item.sidecarId, item.event);
+      } catch (err) {
+        console.error(`[EventScheduler] Handler error for ${item.event.event_type}:`, err);
+      }
+    }
+  }
+}
+
+function priorityWeight(p: EventPriority): number {
+  switch (p) {
+    case 'critical': return 0;
+    case 'high': return 1;
+    case 'normal': return 2;
+    case 'low': return 3;
+  }
+}

package/src/sidecar/types.ts

@@ -0,0 +1,112 @@
+/**
+ * Sidecar Types
+ *
+ * Types for the brain-side sidecar management system.
+ */
+
+/** Capabilities a sidecar can advertise */
+export type SidecarCapability =
+  | 'terminal'
+  | 'filesystem'
+  | 'desktop'
+  | 'browser'
+  | 'clipboard'
+  | 'screenshot'
+  | 'system_info'
+  | 'awareness';
+
+/** A capability that is enabled in config but unavailable on the system */
+export interface UnavailableCapability {
+  name: SidecarCapability;
+  reason: string;
+}
+
+/** Sidecar status in the database */
+export type SidecarStatus = 'enrolled' | 'revoked';
+
+/** Sidecar record as stored in the database */
+export interface SidecarRecord {
+  id: string;
+  name: string;
+  token_id: string;
+  enrolled_at: string;
+  last_seen_at: string | null;
+  status: SidecarStatus;
+  /** Populated after first connection */
+  hostname: string | null;
+  os: string | null;
+  platform: string | null;
+  /** JSON-encoded SidecarCapability[] — populated after first connection */
+  capabilities: string | null;
+}
+
+/** JWT claims for a sidecar enrollment token */
+export interface SidecarTokenClaims {
+  /** Subject: "sidecar:<id>" */
+  sub: string;
+  /** Unique token ID (for revocation tracking) */
+  jti: string;
+  /** Sidecar UUID */
+  sid: string;
+  /** Human-readable sidecar name */
+  name: string;
+  /** WebSocket URL for the sidecar to connect to */
+  brain: string;
+  /** URL to fetch the brain's JWKS public key */
+  jwks: string;
+  /** Issued-at timestamp */
+  iat: number;
+}
+
+/** Registration message sent by sidecar on WebSocket connect */
+export interface SidecarRegistration {
+  type: 'register';
+  hostname: string;
+  os: string;
+  platform: string;
+  capabilities: SidecarCapability[];
+  unavailable_capabilities?: UnavailableCapability[];
+}
+
+/** Capabilities update message sent by sidecar when config changes */
+export interface SidecarCapabilitiesUpdate {
+  type: 'capabilities_update';
+  capabilities: SidecarCapability[];
+  unavailable_capabilities?: UnavailableCapability[];
+}
+
+/** A connected sidecar (runtime state, not persisted) */
+export interface ConnectedSidecar {
+  id: string;
+  name: string;
+  hostname: string;
+  os: string;
+  platform: string;
+  capabilities: SidecarCapability[];
+  unavailableCapabilities: UnavailableCapability[];
+  connectedAt: Date;
+}
+
+/** Sidecar config as returned by get_config RPC (token excluded) */
+export interface SidecarConfig {
+  capabilities: SidecarCapability[];
+  terminal: { blocked_commands: string[]; default_shell: string; timeout_ms: number };
+  filesystem: { blocked_paths: string[]; max_file_size_kb: number };
+  browser: { cdp_port: number; profile_dir: string };
+  awareness: { screen_interval_ms: number; window_interval_ms: number; min_change_threshold: number; stuck_threshold_ms: number };
+}
+
+/** Sidecar info returned by API (DB record + connection state) */
+export interface SidecarInfo {
+  id: string;
+  name: string;
+  enrolled_at: string;
+  last_seen_at: string | null;
+  status: SidecarStatus;
+  connected: boolean;
+  hostname?: string;
+  os?: string;
+  platform?: string;
+  capabilities?: SidecarCapability[];
+  unavailable_capabilities?: UnavailableCapability[];
+}

package/src/sidecar/validator.ts

@@ -0,0 +1,144 @@
+/**
+ * Sidecar Validator — Schema Validation & Sanitization
+ *
+ * Validates inbound sidecar events and binary frames.
+ */
+
+import type { SidecarEvent, EventPriority } from './protocol.ts';
+
+// Size limits
+export const MAX_JSON_SIZE = 1 * 1024 * 1024;       // 1 MB
+export const MAX_BINARY_SIZE = 50 * 1024 * 1024;     // 50 MB
+export const BINARY_INLINE_THRESHOLD = 256 * 1024;   // 256 KB
+export const BINARY_REF_ID_LENGTH = 36;               // UUID length
+
+export interface ValidationResult {
+  valid: boolean;
+  event?: SidecarEvent;
+  error?: string;
+}
+
+export interface BinaryValidationResult {
+  valid: boolean;
+  refId?: string;
+  payload?: Buffer;
+  error?: string;
+}
+
+const VALID_EVENT_TYPES = new Set([
+  'rpc_result', 'rpc_progress', 'sidecar_event',
+]);
+
+const VALID_PRIORITIES = new Set<EventPriority>([
+  'critical', 'high', 'normal', 'low',
+]);
+
+const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Recursively strip dangerous keys from an object.
+ */
+function sanitize(obj: unknown): unknown {
+  if (obj === null || obj === undefined) return obj;
+  if (typeof obj !== 'object') return obj;
+  if (Array.isArray(obj)) return obj.map(sanitize);
+
+  const clean: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+    if (DANGEROUS_KEYS.has(key)) continue;
+    clean[key] = sanitize(value);
+  }
+  return clean;
+}
+
+/**
+ * Validate and sanitize an inbound sidecar event (parsed JSON).
+ */
+export function validateEvent(raw: unknown): ValidationResult {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    return { valid: false, error: 'Event must be a JSON object' };
+  }
+
+  const obj = raw as Record<string, unknown>;
+
+  // type
+  if (typeof obj.type !== 'string' || !VALID_EVENT_TYPES.has(obj.type)) {
+    return { valid: false, error: `Invalid event type: ${String(obj.type)}` };
+  }
+
+  // event_type
+  if (typeof obj.event_type !== 'string' || obj.event_type.length === 0) {
+    return { valid: false, error: 'Missing or empty event_type' };
+  }
+
+  // timestamp
+  if (typeof obj.timestamp !== 'number' || !Number.isFinite(obj.timestamp)) {
+    return { valid: false, error: 'Invalid timestamp' };
+  }
+
+  // payload
+  if (typeof obj.payload !== 'object' || obj.payload === null || Array.isArray(obj.payload)) {
+    return { valid: false, error: 'Payload must be a JSON object' };
+  }
+
+  // Validate payload fields per type
+  const payload = obj.payload as Record<string, unknown>;
+
+  if (obj.type === 'rpc_result') {
+    if (typeof payload.rpc_id !== 'string') {
+      return { valid: false, error: 'rpc_result requires payload.rpc_id (string)' };
+    }
+    if (payload.result === undefined && payload.error === undefined) {
+      return { valid: false, error: 'rpc_result requires payload.result or payload.error' };
+    }
+    if (payload.error !== undefined) {
+      const err = payload.error as Record<string, unknown>;
+      if (typeof err !== 'object' || typeof err.code !== 'string' || typeof err.message !== 'string') {
+        return { valid: false, error: 'rpc_result error must have code and message strings' };
+      }
+    }
+  }
+
+  if (obj.type === 'rpc_progress') {
+    if (typeof payload.rpc_id !== 'string') {
+      return { valid: false, error: 'rpc_progress requires payload.rpc_id (string)' };
+    }
+    if (typeof payload.progress !== 'number') {
+      return { valid: false, error: 'rpc_progress requires payload.progress (number)' };
+    }
+  }
+
+  // priority (optional)
+  if (obj.priority !== undefined && !VALID_PRIORITIES.has(obj.priority as EventPriority)) {
+    return { valid: false, error: `Invalid priority: ${String(obj.priority)}` };
+  }
+
+  // Sanitize the entire event
+  const sanitized = sanitize(obj) as SidecarEvent;
+
+  return { valid: true, event: sanitized };
+}
+
+/**
+ * Validate a binary frame. First 36 bytes = ref_id (ASCII UUID), rest = payload.
+ */
+export function validateBinaryFrame(data: Buffer): BinaryValidationResult {
+  if (data.length < BINARY_REF_ID_LENGTH) {
+    return { valid: false, error: `Binary frame too small: ${data.length} bytes (min ${BINARY_REF_ID_LENGTH})` };
+  }
+
+  if (data.length > MAX_BINARY_SIZE) {
+    return { valid: false, error: `Binary frame too large: ${data.length} bytes (max ${MAX_BINARY_SIZE})` };
+  }
+
+  const refId = data.subarray(0, BINARY_REF_ID_LENGTH).toString('ascii');
+
+  // Basic UUID format check
+  if (!/^[0-9a-f-]{36}$/i.test(refId)) {
+    return { valid: false, error: `Invalid ref_id format: ${refId}` };
+  }
+
+  const payload = data.subarray(BINARY_REF_ID_LENGTH);
+
+  return { valid: true, refId, payload };
+}

package/src/vault/README.md

@@ -0,0 +1,110 @@
+# Vault Module
+
+Knowledge graph storage and extraction system for J.A.R.V.I.S.
+
+## Modules
+
+- **`schema.ts`**: Database schema and initialization
+- **`entities.ts`**: Entity CRUD operations
+- **`facts.ts`**: Fact storage and queries
+- **`relationships.ts`**: Relationship management
+- **`commitments.ts`**: Promise and task tracking
+- **`observations.ts`**: Raw event storage
+- **`vectors.ts`**: Embedding storage for semantic search
+- **`extractor.ts`**: LLM-powered knowledge extraction
+- **`index.ts`**: Public API exports
+
+## Quick Start
+
+### Initialize Database
+
+```typescript
+import { initDatabase } from '@/vault';
+
+initDatabase('./data/jarvis.db');
+```
+
+### Store Knowledge Manually
+
+```typescript
+import { createEntity, createFact, createRelationship } from '@/vault';
+
+// Create entity
+const anna = createEntity('person', 'Anna', {
+  role: 'software engineer',
+});
+
+// Add fact
+createFact(anna.id, 'birthday_is', 'March 15', {
+  confidence: 1.0,
+});
+
+// Create relationship
+const google = createEntity('tool', 'Google');
+createRelationship(anna.id, google.id, 'works_at');
+```
+
+### Extract Knowledge with LLM
+
+```typescript
+import { extractAndStore } from '@/vault';
+import { AnthropicProvider } from '@/llm/anthropic';
+
+const llm = new AnthropicProvider(process.env.ANTHROPIC_API_KEY);
+
+const result = await extractAndStore(
+  "Anna's birthday is March 15th",
+  "I'll remember that!",
+  llm
+);
+```
+
+### Query Knowledge
+
+```typescript
+import { findEntities, findFacts, findCommitments } from '@/vault';
+
+// Find people
+const people = findEntities({ type: 'person' });
+
+// Find facts about Anna
+const facts = findFacts({ subject_id: anna.id });
+
+// Find pending commitments
+const pending = findCommitments({ status: 'pending' });
+```
+
+## Documentation
+
+- **Vault Extractor**: [docs/VAULT_EXTRACTOR.md](~/jarvis/docs/VAULT_EXTRACTOR.md)
+- **Entity Types**: person, project, tool, place, concept, event
+- **Commitment Statuses**: pending, active, completed, failed, escalated
+
+## Testing
+
+```bash
+# Test extractor
+bun test src/vault/extractor.test.ts
+
+# Test entire vault (if you have other tests)
+bun test src/vault/**/*.test.ts
+```
+
+## Demo
+
+```bash
+bun run examples/extractor-demo.ts
+```
+
+## Database Schema
+
+SQLite database with the following tables:
+- `entities`: People, projects, tools, places, concepts, events
+- `facts`: Atomic knowledge with confidence scores
+- `relationships`: Typed edges between entities
+- `commitments`: Promises and tasks
+- `observations`: Raw events
+- `vectors`: Embeddings for semantic search
+- `agent_messages`: Inter-agent communication
+- `personality_state`: Personality model storage
+- `conversations`: Conversation tracking