@shykaruu/jarvis-brain 0.4.0

package/src/daemon/pid.test.ts

@@ -0,0 +1,283 @@
+import { test, expect, describe, beforeEach, afterEach } from 'bun:test';
+import { join } from 'node:path';
+import { homedir, tmpdir } from 'node:os';
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import {
+  acquireLock,
+  isLocked,
+  releaseLock,
+  readPid,
+  getPidPath,
+  getLogPath,
+  getLogDir,
+} from './pid.ts';
+
+const JARVIS_DIR = join(homedir(), '.jarvis');
+const LOCK_PATH = join(JARVIS_DIR, 'jarvis.pid');
+const PID_MODULE = join(import.meta.dir, 'pid.ts');
+const READY_SIGNAL = join(tmpdir(), 'jarvis-test-lock-ready');
+const HOLDER_SCRIPT = join(tmpdir(), 'jarvis-test-lock-holder.ts');
+
+function cleanup(): void {
+  releaseLock();
+  try { unlinkSync(READY_SIGNAL); } catch {}
+  try { unlinkSync(HOLDER_SCRIPT); } catch {}
+}
+
+/**
+ * Spawn a child process that acquires the flock and holds it until killed.
+ * Returns once the child has confirmed it holds the lock.
+ */
+async function spawnLockHolder(): Promise<{ proc: ReturnType<typeof Bun.spawn>; pid: number }> {
+  try { unlinkSync(READY_SIGNAL); } catch {}
+
+  writeFileSync(HOLDER_SCRIPT, `
+import { acquireLock } from ${JSON.stringify(PID_MODULE)};
+import { writeFileSync } from 'node:fs';
+const ok = acquireLock(process.pid);
+writeFileSync(${JSON.stringify(READY_SIGNAL)}, ok ? String(process.pid) : 'FAIL');
+await Bun.sleep(60000);
+`);
+
+  const proc = Bun.spawn(['bun', HOLDER_SCRIPT], {
+    stdio: ['ignore', 'ignore', 'ignore'],
+  });
+
+  for (let i = 0; i < 50; i++) {
+    await Bun.sleep(100);
+    if (existsSync(READY_SIGNAL)) {
+      const content = readFileSync(READY_SIGNAL, 'utf-8').trim();
+      if (content === 'FAIL') {
+        proc.kill();
+        await proc.exited;
+        throw new Error('Child process failed to acquire lock');
+      }
+      return { proc, pid: parseInt(content, 10) };
+    }
+  }
+  proc.kill();
+  await proc.exited;
+  throw new Error('Timed out waiting for child to acquire lock');
+}
+
+describe('Process Lock Manager', () => {
+  beforeEach(() => cleanup());
+  afterEach(() => cleanup());
+
+  // ── acquireLock ──────────────────────────────────────────────────
+
+  describe('acquireLock', () => {
+    test('returns true and creates lock file', () => {
+      expect(acquireLock(process.pid)).toBe(true);
+      expect(existsSync(LOCK_PATH)).toBe(true);
+    });
+
+    test('writes PID to lock file', () => {
+      acquireLock(process.pid);
+      const content = readFileSync(LOCK_PATH, 'utf-8').trim();
+      expect(content).toBe(String(process.pid));
+    });
+
+    test('creates ~/.jarvis dir if missing', () => {
+      // Dir almost certainly exists already, but acquireLock should not fail
+      expect(acquireLock(process.pid)).toBe(true);
+    });
+
+    test('second acquire in same process returns false', () => {
+      // First fd holds an exclusive flock; second open+flock is denied
+      expect(acquireLock(process.pid)).toBe(true);
+      expect(acquireLock(process.pid)).toBe(false);
+    });
+  });
+
+  // ── isLocked ─────────────────────────────────────────────────────
+
+  describe('isLocked', () => {
+    test('returns null when no lock file exists', () => {
+      expect(isLocked()).toBeNull();
+    });
+
+    test('returns null for stale file (file exists, no lock held)', () => {
+      mkdirSync(JARVIS_DIR, { recursive: true });
+      writeFileSync(LOCK_PATH, '99999');
+      // No flock held — probe should succeed → not locked
+      expect(isLocked()).toBeNull();
+    });
+
+    test('returns PID when lock is held by this process', () => {
+      acquireLock(process.pid);
+      // isLocked opens a second fd; flock is denied because our fd holds it
+      expect(isLocked()).toBe(process.pid);
+    });
+  });
+
+  // ── releaseLock ──────────────────────────────────────────────────
+
+  describe('releaseLock', () => {
+    test('releases lock and removes file', () => {
+      acquireLock(process.pid);
+      expect(existsSync(LOCK_PATH)).toBe(true);
+
+      releaseLock();
+      expect(existsSync(LOCK_PATH)).toBe(false);
+      expect(isLocked()).toBeNull();
+    });
+
+    test('is idempotent — safe to call without prior acquire', () => {
+      releaseLock();
+      releaseLock();
+      releaseLock();
+      // Should not throw
+    });
+
+    test('allows re-acquire after release', () => {
+      expect(acquireLock(process.pid)).toBe(true);
+      releaseLock();
+      expect(acquireLock(process.pid)).toBe(true);
+    });
+
+    test('multiple acquire/release cycles work', () => {
+      for (let i = 0; i < 5; i++) {
+        expect(acquireLock(process.pid)).toBe(true);
+        expect(isLocked()).toBe(process.pid);
+        releaseLock();
+        expect(isLocked()).toBeNull();
+      }
+    });
+  });
+
+  // ── readPid ──────────────────────────────────────────────────────
+
+  describe('readPid', () => {
+    test('returns null when no file exists', () => {
+      expect(readPid()).toBeNull();
+    });
+
+    test('returns PID from file', () => {
+      mkdirSync(JARVIS_DIR, { recursive: true });
+      writeFileSync(LOCK_PATH, '12345');
+      expect(readPid()).toBe(12345);
+    });
+
+    test('trims whitespace', () => {
+      mkdirSync(JARVIS_DIR, { recursive: true });
+      writeFileSync(LOCK_PATH, '  42\n');
+      expect(readPid()).toBe(42);
+    });
+
+    test('returns null for non-numeric content', () => {
+      mkdirSync(JARVIS_DIR, { recursive: true });
+      writeFileSync(LOCK_PATH, 'not-a-pid');
+      expect(readPid()).toBeNull();
+    });
+
+    test('returns null for empty file', () => {
+      mkdirSync(JARVIS_DIR, { recursive: true });
+      writeFileSync(LOCK_PATH, '');
+      expect(readPid()).toBeNull();
+    });
+
+    test('returns null for zero', () => {
+      mkdirSync(JARVIS_DIR, { recursive: true });
+      writeFileSync(LOCK_PATH, '0');
+      expect(readPid()).toBeNull();
+    });
+
+    test('returns null for negative PID', () => {
+      mkdirSync(JARVIS_DIR, { recursive: true });
+      writeFileSync(LOCK_PATH, '-1');
+      expect(readPid()).toBeNull();
+    });
+  });
+
+  // ── path getters ─────────────────────────────────────────────────
+
+  describe('path getters', () => {
+    test('getPidPath returns ~/.jarvis/jarvis.pid', () => {
+      expect(getPidPath()).toBe(join(homedir(), '.jarvis', 'jarvis.pid'));
+    });
+
+    test('getLogPath returns path and creates logs dir', () => {
+      const logPath = getLogPath();
+      expect(logPath).toBe(join(JARVIS_DIR, 'logs', 'jarvis.log'));
+      expect(existsSync(join(JARVIS_DIR, 'logs'))).toBe(true);
+    });
+
+    test('getLogDir returns logs directory', () => {
+      expect(getLogDir()).toBe(join(JARVIS_DIR, 'logs'));
+    });
+  });
+
+  // ── cross-process locking ────────────────────────────────────────
+
+  describe('cross-process locking', () => {
+    let childProc: ReturnType<typeof Bun.spawn> | null = null;
+
+    afterEach(async () => {
+      if (childProc) {
+        childProc.kill();
+        await childProc.exited;
+        childProc = null;
+      }
+      cleanup();
+    });
+
+    test('isLocked detects lock held by another process', async () => {
+      const { proc, pid } = await spawnLockHolder();
+      childProc = proc;
+
+      const result = isLocked();
+      expect(result).toBe(pid);
+    }, { timeout: 15000 });
+
+    test('acquireLock fails when another process holds lock', async () => {
+      const { proc } = await spawnLockHolder();
+      childProc = proc;
+
+      expect(acquireLock(process.pid)).toBe(false);
+    }, { timeout: 15000 });
+
+    test('lock is released when holder is SIGKILLed', async () => {
+      const { proc } = await spawnLockHolder();
+      childProc = proc;
+
+      // Lock is held
+      expect(isLocked()).not.toBeNull();
+
+      // SIGKILL — OS closes all fds, releasing the flock
+      proc.kill(9);
+      await proc.exited;
+      childProc = null;
+
+      // Lock is now free
+      expect(isLocked()).toBeNull();
+    }, { timeout: 15000 });
+
+    test('can acquire lock after previous holder crashes', async () => {
+      const { proc } = await spawnLockHolder();
+      childProc = proc;
+
+      proc.kill(9);
+      await proc.exited;
+      childProc = null;
+
+      // New instance should succeed immediately
+      expect(acquireLock(process.pid)).toBe(true);
+      expect(readPid()).toBe(process.pid);
+    }, { timeout: 15000 });
+
+    test('lock survives SIGTERM of holder (graceful)', async () => {
+      const { proc, pid } = await spawnLockHolder();
+      childProc = proc;
+
+      // SIGTERM — child exits, OS releases flock
+      proc.kill(15);
+      await proc.exited;
+      childProc = null;
+
+      // Lock freed after process exits
+      expect(isLocked()).toBeNull();
+      expect(acquireLock(process.pid)).toBe(true);
+    }, { timeout: 15000 });
+  });
+});

package/src/daemon/pid.ts

@@ -0,0 +1,224 @@
+/**
+ * Process Lock Manager for J.A.R.V.I.S. Daemon
+ *
+ * Uses flock()-based advisory locks to prevent duplicate daemon instances.
+ * Unlike PID-based checks, flock locks are automatically released by the OS
+ * when the process dies (even on SIGKILL, OOM, or crash), making this
+ * container-safe and race-free.
+ */
+
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import {
+  constants,
+  existsSync,
+  readFileSync,
+  unlinkSync,
+  mkdirSync,
+  openSync,
+  closeSync,
+  writeSync,
+  ftruncateSync,
+} from 'node:fs';
+import { cc } from 'bun:ffi';
+import flockSource from './flock.c' with { type: 'file' };
+
+const JARVIS_DIR = join(homedir(), '.jarvis');
+const LOG_DIR = join(JARVIS_DIR, 'logs');
+const LOCK_PATH = join(JARVIS_DIR, 'jarvis.pid');
+const LOG_PATH = join(LOG_DIR, 'jarvis.log');
+
+// ── flock() via Bun cc() ────────────────────────────────────────────
+// Compiled at startup by Bun's embedded TinyCC. Resolves libc via
+// system headers — works on Linux, macOS, and any POSIX platform
+// without hardcoding a shared library path.
+
+const isWindows = process.platform === 'win32';
+
+let flock: any = null;
+if (!isWindows) {
+  const lib = cc({
+    source: flockSource,
+    symbols: {
+      do_flock: { args: ['i32', 'i32'], returns: 'i32' },
+    },
+  });
+  flock = lib.symbols;
+}
+
+const LOCK_EX = 2;  // Exclusive lock
+const LOCK_NB = 4;  // Non-blocking
+const LOCK_UN = 8;  // Unlock
+
+// ── Lock state ───────────────────────────────────────────────────────
+
+// The open FD that holds the flock — kept alive for the process lifetime.
+// When the process exits (normally, SIGKILL, OOM, crash), the OS closes it
+// and the advisory lock is automatically released.
+let lockFd: number | null = null;
+
+// ── Public API ───────────────────────────────────────────────────────
+
+/**
+ * Acquire an exclusive lock on the lock file and write the PID.
+ * Returns true if the lock was acquired, false if another instance holds it.
+ */
+export function acquireLock(pid: number): boolean {
+  if (lockFd !== null) return false;
+
+  try {
+    mkdirSync(JARVIS_DIR, { recursive: true });
+
+    if (isWindows) {
+      const existingPid = readPid();
+      if (existingPid !== null && existingPid !== pid) {
+        try {
+          process.kill(existingPid, 0);
+          return false;
+        } catch {
+          // Process not running, stale lock file
+        }
+      }
+    }
+
+    // Open (or create) the lock file — don't truncate before locking
+    const fd = openSync(LOCK_PATH, constants.O_WRONLY | constants.O_CREAT, 0o644);
+
+    // Try non-blocking exclusive lock
+    if (!isWindows) {
+      const result = flock.do_flock(fd, LOCK_EX | LOCK_NB);
+      if (result !== 0) {
+        closeSync(fd);
+        return false;
+      }
+    }
+
+    // Lock acquired — truncate and write PID for display purposes
+    ftruncateSync(fd, 0);
+    writeSync(fd, String(pid));
+
+    // Keep the FD open — closing it would release the lock
+    lockFd = fd;
+    return true;
+  } catch (err) {
+    console.error(`[PID] Failed to acquire lock: ${err}`);
+    return false;
+  }
+}
+
+/**
+ * Check if the daemon lock is currently held.
+ * Returns the PID if locked (daemon running), null otherwise.
+ */
+export function isLocked(): number | null {
+  if (!existsSync(LOCK_PATH)) return null;
+
+  let fd: number;
+  try {
+    fd = openSync(LOCK_PATH, constants.O_RDONLY);
+  } catch {
+    return null;
+  }
+
+  try {
+    if (!isWindows) {
+      // Try non-blocking exclusive lock to probe
+      const result = flock.do_flock(fd, LOCK_EX | LOCK_NB);
+      if (result === 0) {
+        // Lock acquired — no daemon running. Release immediately.
+        flock.do_flock(fd, LOCK_UN);
+        closeSync(fd);
+        return null;
+      }
+    }
+    
+    // Lock held by another process (or we are on Windows) — daemon is running
+    closeSync(fd);
+    const pid = readPid();
+
+    if (isWindows && pid !== null) {
+      try {
+        process.kill(pid, 0);
+      } catch {
+        return null;
+      }
+    }
+
+    // Container safety: if PID is 1 and we're inside a container,
+    // the lock file is stale from a previous container lifecycle
+    if (pid === 1 && isInsideContainer()) {
+      releaseLock();
+      return null;
+    }
+
+    return pid;
+  } catch {
+    try { closeSync(fd); } catch { /* already closed */ }
+    return null;
+  }
+}
+
+/**
+ * Release the lock (close the FD) and remove the lock file.
+ */
+export function releaseLock(): void {
+  if (lockFd !== null) {
+    try {
+      closeSync(lockFd);
+    } catch {
+      // Already closed
+    }
+    lockFd = null;
+  }
+  try {
+    if (existsSync(LOCK_PATH)) unlinkSync(LOCK_PATH);
+  } catch { /* ignore */ }
+}
+
+/**
+ * Read the PID from the lock file. Returns null if no file or invalid content.
+ */
+export function readPid(): number | null {
+  if (!existsSync(LOCK_PATH)) return null;
+  try {
+    const content = readFileSync(LOCK_PATH, 'utf-8').trim();
+    const pid = parseInt(content, 10);
+    if (isNaN(pid) || pid <= 0) return null;
+    return pid;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the lock file path (for display purposes).
+ */
+export function getPidPath(): string {
+  return LOCK_PATH;
+}
+
+/**
+ * Get the log file path. Creates the log directory if needed.
+ */
+export function getLogPath(): string {
+  mkdirSync(LOG_DIR, { recursive: true });
+  return LOG_PATH;
+}
+
+/**
+ * Get the log directory path.
+ */
+export function getLogDir(): string {
+  return LOG_DIR;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+function isInsideContainer(): boolean {
+  if (existsSync('/.dockerenv')) return true;
+  try {
+    return readFileSync('/proc/1/cgroup', 'utf-8').includes('docker');
+  } catch {
+    return false;
+  }
+}

package/src/daemon/research-queue.ts

@@ -0,0 +1,155 @@
+/**
+ * ResearchQueue — Background Research Engine
+ *
+ * Manages a queue of topics for JARVIS to research during idle time.
+ * Topics come from conversations, explicit requests, or the agent itself.
+ * The heartbeat picks up the next topic when nothing urgent is happening.
+ */
+
+export type ResearchPriority = 'high' | 'normal' | 'low';
+export type ResearchStatus = 'queued' | 'in_progress' | 'completed' | 'failed';
+
+export type ResearchTopic = {
+  id: string;
+  topic: string;
+  reason: string;
+  source: string;       // 'user' | 'agent' | 'conversation'
+  priority: ResearchPriority;
+  status: ResearchStatus;
+  result?: string;
+  failReason?: string;
+  created_at: number;
+  completed_at?: number;
+};
+
+const MAX_QUEUE_SIZE = 50;
+
+export class ResearchQueue {
+  private topics: Map<string, ResearchTopic> = new Map();
+
+  /**
+   * Add a topic to the research queue.
+   */
+  addTopic(
+    topic: string,
+    reason: string,
+    source: string = 'user',
+    priority: ResearchPriority = 'normal'
+  ): ResearchTopic {
+    // Enforce max queue size (drop oldest low-priority)
+    if (this.topics.size >= MAX_QUEUE_SIZE) {
+      this.evictOldest();
+    }
+
+    const entry: ResearchTopic = {
+      id: crypto.randomUUID(),
+      topic,
+      reason,
+      source,
+      priority,
+      status: 'queued',
+      created_at: Date.now(),
+    };
+
+    this.topics.set(entry.id, entry);
+    console.log(`[ResearchQueue] Added: "${topic}" (${priority}, from ${source})`);
+    return entry;
+  }
+
+  /**
+   * Get the next highest-priority queued topic.
+   */
+  getNext(): ResearchTopic | null {
+    const queued = Array.from(this.topics.values())
+      .filter((t) => t.status === 'queued')
+      .sort((a, b) => {
+        // Priority order: high > normal > low
+        const pOrder: Record<ResearchPriority, number> = { high: 0, normal: 1, low: 2 };
+        const pDiff = pOrder[a.priority] - pOrder[b.priority];
+        if (pDiff !== 0) return pDiff;
+        // Older topics first within same priority
+        return a.created_at - b.created_at;
+      });
+
+    return queued[0] ?? null;
+  }
+
+  /**
+   * Mark a topic as in-progress.
+   */
+  startResearch(id: string): boolean {
+    const topic = this.topics.get(id);
+    if (!topic || topic.status !== 'queued') return false;
+    topic.status = 'in_progress';
+    return true;
+  }
+
+  /**
+   * Mark a topic as completed with a result.
+   */
+  complete(id: string, result: string): boolean {
+    const topic = this.topics.get(id);
+    if (!topic) return false;
+    topic.status = 'completed';
+    topic.result = result;
+    topic.completed_at = Date.now();
+    console.log(`[ResearchQueue] Completed: "${topic.topic}"`);
+    return true;
+  }
+
+  /**
+   * Mark a topic as failed.
+   */
+  fail(id: string, reason: string): boolean {
+    const topic = this.topics.get(id);
+    if (!topic) return false;
+    topic.status = 'failed';
+    topic.failReason = reason;
+    topic.completed_at = Date.now();
+    console.log(`[ResearchQueue] Failed: "${topic.topic}" — ${reason}`);
+    return true;
+  }
+
+  /**
+   * Remove a topic from the queue.
+   */
+  remove(id: string): boolean {
+    return this.topics.delete(id);
+  }
+
+  /**
+   * List all topics, optionally filtered by status.
+   */
+  list(status?: ResearchStatus): ResearchTopic[] {
+    const all = Array.from(this.topics.values());
+    if (status) return all.filter((t) => t.status === status);
+    return all;
+  }
+
+  /**
+   * Get count of queued topics.
+   */
+  queuedCount(): number {
+    return Array.from(this.topics.values()).filter((t) => t.status === 'queued').length;
+  }
+
+  private evictOldest(): void {
+    // Evict oldest completed, then oldest low-priority queued
+    const completed = Array.from(this.topics.values())
+      .filter((t) => t.status === 'completed' || t.status === 'failed')
+      .sort((a, b) => a.created_at - b.created_at);
+
+    if (completed.length > 0) {
+      this.topics.delete(completed[0]!.id);
+      return;
+    }
+
+    const low = Array.from(this.topics.values())
+      .filter((t) => t.priority === 'low' && t.status === 'queued')
+      .sort((a, b) => a.created_at - b.created_at);
+
+    if (low.length > 0) {
+      this.topics.delete(low[0]!.id);
+    }
+  }
+}