@bahulam/code 0.1.1 → 0.1.3

package/src/daemon/daemonize.mjs

@@ -0,0 +1,151 @@
+/**
+ * . — auto-daemon spawn + start-or-attach.
+ *
+ * Two entrypoints:
+ *
+ *   spawnDetachedDaemon(cwd, {prompt, extraEnv})
+ *     Forks a background bahulam child, detached from the current
+ *     terminal, with BAHULAM_DAEMON_EVENTLOG=1 forced so it starts a
+ *     socket server on session_info. Returns { pid, waitForSession() }
+ *     — the parent can await a session_id becoming visible in
+ *     ~/.bahulam/sessions/, or exit immediately (typical case: user
+ *     types `bahulam daemonize "fix this bug"`, we spawn + print the
+ *     session id + exit; they attach later with `bahulam attach <id>`).
+ *
+ *   findSessionForCwd(cwd)
+ *     Scans ~/.bahulam/sessions/<id>/meta.json for entries where meta.cwd
+ *     matches (after realpath), and where the pid is still alive and
+ *     the socket file exists. Returns the newest such session id or null.
+ *     Used by `bahulam` (no args) to decide start-vs-attach.
+ */
+
+import * as fs from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { spawn } from 'node:child_process';
+import { daemonSessionsRoot, daemonSocketPath } from '../core/paths.mjs';
+
+const POLL_INTERVAL_MS = 100;
+const DEFAULT_WAIT_MS = 15_000;
+
+/**
+ * Look for a live daemon session bound to `cwd`. A session is "live" if:
+ *   1. `~/.bahulam/sessions/<id>/meta.json` has `cwd` matching (realpath).
+ *   2. `~/.bahulam/sockets/<id>.sock` exists.
+ *   3. `meta.pid` is alive (`kill -0` succeeds — we don't send SIGTERM,
+ *      just probe existence with signal 0).
+ *
+ * Returns the newest matching session id or null. Newest = highest
+ * `opened_at` in meta.json (falls back to directory mtime).
+ */
+export async function findSessionForCwd(cwd) {
+  const root = daemonSessionsRoot();
+  let target;
+  try { target = fs.realpathSync(cwd); } catch { target = cwd; }
+
+  let entries;
+  try { entries = await fsp.readdir(root, { withFileTypes: true }); }
+  catch { return null; }
+
+  const candidates = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !entry.name.startsWith('sess_')) continue;
+    const sid = entry.name;
+    const dir = path.join(root, sid);
+    let meta;
+    try { meta = JSON.parse(await fsp.readFile(path.join(dir, 'meta.json'), 'utf-8')); }
+    catch { continue; }
+    if (!meta.cwd) continue;
+    let metaCwd;
+    try { metaCwd = fs.realpathSync(meta.cwd); } catch { metaCwd = meta.cwd; }
+    if (metaCwd !== target) continue;
+    if (!fs.existsSync(daemonSocketPath(sid))) continue;
+    if (!_pidAlive(meta.pid)) continue;
+    candidates.push({ sid, openedAt: meta.opened_at || '', pid: meta.pid });
+  }
+  if (candidates.length === 0) return null;
+  candidates.sort((a, b) => (b.openedAt || '').localeCompare(a.openedAt || ''));
+  return candidates[0].sid;
+}
+
+/**
+ * Spawn a detached bahulam child. The child inherits nothing on stdio
+ * (piped to /dev/null via 'ignore') — it lives in the background,
+ * writes its transcript to the event log, and any attach client renders
+ * from there.
+ *
+ * Returns { pid, waitForSession(ms?) → sess_id | null }. Caller can
+ * await the session_id becoming visible before exiting the parent so
+ * the printed "sess_..." line isn't stale.
+ */
+export function spawnDetachedDaemon({
+  cwd = process.cwd(),
+  prompt = null,
+  binPath = process.argv[1],   // the bahulam entrypoint that spawned US
+  extraEnv = {},
+} = {}) {
+  const beforeSet = _listCurrentSessionsSync();
+
+  const env = {
+    ...process.env,
+    BAHULAM_DAEMON_EVENTLOG: '1',
+    // Spawned children auto-quit after the first turn's agent_complete
+    // unless the operator opts into idle-hold. Cheap default that
+    // matches the "bahulam daemonize <prompt>; check back later"
+    // mental model. Override with BAHULAM_DAEMON_HOLD=1 to keep the
+    // socket up for follow-up send_message commands.
+    BAHULAM_DAEMON_SPAWNED: '1',
+    ...extraEnv,
+  };
+  if (prompt) env.BAHULAM_DAEMON_INITIAL_PROMPT = String(prompt);
+
+  const child = spawn(process.execPath, [binPath], {
+    cwd,
+    env,
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();  // parent can exit without waiting on child
+
+  return {
+    pid: child.pid,
+    async waitForSession(ms = DEFAULT_WAIT_MS) {
+      const deadline = Date.now() + ms;
+      while (Date.now() < deadline) {
+        // Find a session_id that's NEW since we spawned + belongs to our cwd.
+        const now = _listCurrentSessionsSync();
+        for (const sid of now) {
+          if (beforeSet.has(sid)) continue;
+          const dir = path.join(daemonSessionsRoot(), sid);
+          try {
+            const meta = JSON.parse(fs.readFileSync(path.join(dir, 'meta.json'), 'utf-8'));
+            if (meta.pid === child.pid) return sid;
+            // pid mismatch is fine early — the daemon may not have written
+            // meta.json yet; keep polling.
+          } catch { /* not written yet */ }
+        }
+        await new Promise(r => setTimeout(r, POLL_INTERVAL_MS));
+      }
+      return null;
+    },
+  };
+}
+
+// ── internals ────────────────────────────────────────────────────────
+
+function _pidAlive(pid) {
+  if (typeof pid !== 'number' || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (err) {
+    // EPERM = process exists but we can't signal it → still alive.
+    return err && err.code === 'EPERM';
+  }
+}
+
+function _listCurrentSessionsSync() {
+  try {
+    const root = daemonSessionsRoot();
+    const entries = fs.readdirSync(root, { withFileTypes: true });
+    return new Set(entries.filter(e => e.isDirectory() && e.name.startsWith('sess_')).map(e => e.name));
+  } catch { return new Set(); }
+}

package/src/daemon/event-tap.mjs

@@ -0,0 +1,197 @@
+/**
+ * Event tap — bridges SSE events from the agent loop to the relay.
+ *
+ * Each SSE event type is mapped to a relay event type. The mapping
+ * is a fixed table. Keeping it centralized avoids scattering
+ * relay-specific concerns across the agent loop. *   • Cache-invariance ( §7): this tap is READ-ONLY on the SSE
+ *     event. It never mutates `event`, never changes what stream-client
+ *     yields, and writes to a local file only. `/api/execute` body is
+ *     untouched.
+ *
+ * NOT in scope for .3:
+ *   • Broadcasting events to attached socket clients (.4).
+ *   • Compact snapshot writing (.4 — the daemon supervisor
+ *     decides when to snapshot; the tap doesn't).
+ *   • Deriving  events that don't have a direct SSE origin
+ *     (e.g. `attach_joined`, `input_lock_changed` — those come from
+ *     the socket server, not the SSE stream).
+ */
+
+import { createEventLog } from '../core/event-log.mjs';
+
+// ── env-var gate ─────────────────────────────────────────────────────
+
+function _enabled() {
+  const v = process.env.BAHULAM_DAEMON_EVENTLOG;
+  return v === '1' || v === 'true';
+}
+
+// ── per-session lazy log holder ──────────────────────────────────────
+//
+// One active log at a time. Session id change (via new turn's session_info)
+// closes the old log and opens a new one. `_current` is null when the tap
+// hasn't seen a session id yet — session_info events don't always arrive
+// before other events do, so we buffer nothing and simply drop events
+// that arrive before the id is known. First real event a re-attach sees
+// is session_started; anything before that is renderer-only anyway.
+
+let _current = null;  // { sessionId, log }
+
+function _openLogFor(sessionId) {
+  if (_current && _current.sessionId === sessionId) return _current.log;
+  if (_current) {
+    // Fire-and-forget close on the previous log. The write chain resolves
+    // internally; we don't await here because tapSseEvent is called from
+    // a hot loop that can't afford to block.
+    try { _current.log.close().catch(() => {}); } catch { /* ignore */ }
+  }
+  const log = createEventLog({ sessionId });
+  _current = { sessionId, log };
+  return log;
+}
+
+/** Test / bahulam-stop hook — close the active log and drop the ref. */
+export async function closeActiveEventLog() {
+  if (!_current) return;
+  const { log } = _current;
+  _current = null;
+  try { await log.close(); } catch { /* ignore */ }
+  _broadcasters.length = 0;
+}
+
+// ── broadcasters (.4) ─────────────────────────────────────────
+//
+// The socket server registers itself here so live events fan out to
+// attached clients as they're written to the durable log. Broadcasters
+// are fire-and-forget; a slow/broken one MUST NOT slow down or block
+// the tap. Each broadcaster is invoked in its own try/catch.
+//
+// Registration is process-global (one bahulamd = one process = one tap
+// registry). Multiple socket servers CAN register; the tap doesn't care.
+
+const _broadcasters = [];
+
+/**
+ * Register a broadcaster. Returns an unregister function.
+ * The broadcaster receives the fully-formed  event AFTER it has
+ * been written to the log (so `seq` and `ts` are populated).
+ */
+export function registerBroadcaster(fn) {
+  if (typeof fn !== 'function') throw new Error('registerBroadcaster: fn must be a function');
+  _broadcasters.push(fn);
+  return () => {
+    const i = _broadcasters.indexOf(fn);
+    if (i >= 0) _broadcasters.splice(i, 1);
+  };
+}
+
+// ── SSE →  event mapping ──────────────────────────────────────
+//
+// Table (protocol spec §5.1). Only events that map to a first-class
+//  type are logged. Everything else (status, thinking with
+// empty text, phase_update, worker_update, etc.) is renderer-transient
+// and doesn't belong in a durable event log.
+
+const SSE_TO_PRD092 = Object.freeze({
+  session_info:       'session_started',
+  turn_started:       'turn_started',
+  turn_ended:         'turn_ended',
+  thinking:           'thinking_delta',
+  tool_request:       'tool_call',
+  tool_call:          'tool_call',
+  tool_result:        'tool_result',
+  tool_done:          'tool_result',
+  approval_required:  'approval_required',
+  approval_decided:   'approval_decided',
+  file_diff:          'diff',
+  diff:               'diff',
+  test_result:        'test_result',
+  tokens_used:        'tokens_used',
+  usage_update:       'usage_update',
+  complete:           'agent_complete',
+});
+
+// Some SSE event bodies carry more than we want to log. Trim what makes
+// sense per type so we don't bloat the log with, e.g., a 200KB rendered
+// tool output when a summary would do. Everything else round-trips as-is.
+function _projectData(prd092Type, data) {
+  const src = data || {};
+  switch (prd092Type) {
+    case 'tool_call':
+      return {
+        name: src.tool || src.name,
+        tool_id: src.tool_call_id || src.tool_id || src.id,
+        args: src.args || src.tool_input || src.input || {},
+        subagent_id: src.subagent_id || undefined,
+        cwd: src.cwd || undefined,
+      };
+    case 'tool_result':
+      return {
+        tool_id: src.tool_call_id || src.tool_id || src.id,
+        ok: src.error ? false : (src.ok !== false),
+        summary: typeof src.output === 'string'
+          ? src.output.slice(0, 4096)
+          : (src.summary || undefined),
+        duration_ms: src.duration_ms || src.durationMs || undefined,
+        output_truncated: typeof src.output === 'string' && src.output.length > 4096 ? true : undefined,
+      };
+    case 'thinking_delta':
+      return { chunk: src.message || src.text || '' };
+    case 'session_started':
+      return {
+        cwd: src.cwd,
+        model: src.model,
+        product: src.product,
+        session_id_from_backend: src.session_id,
+      };
+    case 'agent_complete':
+      return { ok: src.error == null, summary: src.summary, duration_ms: src.duration_ms };
+    default:
+      return src;
+  }
+}
+
+// ── the tap ──────────────────────────────────────────────────────────
+
+/**
+ * Tap one SSE event to the  event log.
+ *
+ * @param {{type: string, data?: object}} event  the SSE frame from stream-client
+ * @param {object} opts
+ * @param {string} opts.sessionId  from session.id — required for log routing
+ * @param {string} [opts.turnId]   optional; stamped on turn-scoped events
+ *
+ * Failure modes are ALL silent — a broken tap must never affect the
+ * user-facing render path. If the env var isn't set or sessionId is
+ * missing we skip; if the file write throws internally, event-log.mjs
+ * logs to stderr and drops the event.
+ */
+export function tapSseEvent(event, { sessionId, turnId } = {}) {
+  if (!_enabled()) return;
+  if (!event || !event.type || !sessionId) return;
+  const prd092Type = SSE_TO_PRD092[event.type];
+  if (!prd092Type) return;
+  const log = _openLogFor(sessionId);
+  const data = _projectData(prd092Type, event.data);
+  let seq;
+  try {
+    seq = log.writeEvent(prd092Type, data, turnId ? { turnId } : undefined);
+  } catch (err) {
+    try { process.stderr.write(`[event-tap] writeEvent failed: ${err.message}\n`); } catch {}
+    return;
+  }
+  if (_broadcasters.length === 0) return;
+  const wireEvent = {
+    seq,
+    ts: new Date().toISOString(),
+    type: prd092Type,
+    session_id: sessionId,
+    v: 1,
+    ...(turnId ? { turn_id: turnId } : {}),
+    data,
+  };
+  for (const fn of _broadcasters) {
+    try { fn(wireEvent); }
+    catch (err) { try { process.stderr.write(`[event-tap] broadcaster failed: ${err.message}\n`); } catch {} }
+  }
+}

package/src/daemon/input-lock.mjs

@@ -0,0 +1,191 @@
+/**
+ *   — Input lock state (multi-attach input arbitration).
+ *
+ * Per PRD §6.5:
+ *   - The first attach implicitly holds the input lock.
+ *   - Later attaches join in WATCH mode (may render events, may
+ *     approve/deny, may NOT send_message / interrupt / switch_model).
+ *   - `take_input_lock` triggers a STEAL WITH GRACE:
+ *       1. Emit input_lock_changed { holder: current, pending_transfer: att_new }
+ *       2. Current holder has 3s to release_input_lock gracefully
+ *       3. After 3s (or on release) → holder := att_new,
+ *          emit input_lock_changed { holder: att_new }
+ *   - Approvals bypass the lock. That's an authorization act, not
+ *     a typing act; enforced by the socket-server, not this module.
+ *
+ * State model:
+ *   holder      : attach_id | null      currently owns typing input
+ *   since       : ISO-8601 UTC          when holder was assigned
+ *   pending     : attach_id | null      the challenger waiting on a steal
+ *   pendingTimer: NodeTimeout | null    the 3s grace timer
+ *
+ * All mutations go through the exported functions so the emitters
+ * (repl.mjs wiring) always publish an `input_lock_changed` event.
+ */
+
+const GRACE_MS = 3000;
+
+const _state = {
+  holder: null,        // attach_id | null
+  since: null,         // ISO string
+  pending: null,       // attach_id | null
+  pendingTimer: null,  // NodeTimeout | null
+};
+
+let _emit = null;      // (type, data) → void — set by wireEmit()
+
+/**
+ * Wire the event emitter. The daemon (repl.mjs) sets this to a function
+ * that writes to the event tap so `input_lock_changed` fans out to all
+ * attached clients.
+ */
+export function wireEmit(emitFn) {
+  _emit = typeof emitFn === 'function' ? emitFn : null;
+}
+
+function _now() { return new Date().toISOString(); }
+
+function _publish(extra = {}) {
+  if (!_emit) return;
+  try {
+    _emit('input_lock_changed', {
+      holder: _state.holder,
+      since: _state.since,
+      pending_transfer: _state.pending,
+      ...extra,
+    });
+  } catch { /* never blocks a state change */ }
+}
+
+// ── attach lifecycle ─────────────────────────────────────────────────
+
+/**
+ * First attach auto-takes the lock. Later attaches join in watch mode.
+ * Call from the socket-server hello handler.
+ *
+ * @param {string} attachId
+ * @returns {{holder: string, kind: 'holder'|'watch'}}
+ */
+export function onAttachJoined(attachId) {
+  if (_state.holder == null) {
+    _state.holder = attachId;
+    _state.since = _now();
+    _publish();
+    return { holder: attachId, kind: 'holder' };
+  }
+  return { holder: _state.holder, kind: 'watch' };
+}
+
+/**
+ * If the leaving attach was the holder, transfer the lock — to the pending
+ * challenger if there is one, else to nobody (holder=null). If it was a
+ * watcher, no state change.
+ */
+export function onAttachLeft(attachId) {
+  const wasHolder = _state.holder === attachId;
+  const wasPending = _state.pending === attachId;
+  if (wasPending) _clearPending();
+  if (!wasHolder) return;
+  if (_state.pending) {
+    _state.holder = _state.pending;
+    _state.since = _now();
+    _clearPending();
+  } else {
+    _state.holder = null;
+    _state.since = null;
+  }
+  _publish();
+}
+
+// ── commands ─────────────────────────────────────────────────────────
+
+/**
+ * `take_input_lock` command — steal-with-grace protocol.
+ *
+ * If the requester is already the holder → no-op (return current state).
+ * If there's no holder → immediate takeover.
+ * Otherwise → set pending, schedule 3s timer to force-transfer.
+ *
+ * Returns the state after the request is processed (not after the
+ * grace timer fires).
+ */
+export function takeInputLock(attachId) {
+  if (_state.holder === attachId) {
+    return { holder: attachId, pending: null, immediate: true };
+  }
+  if (_state.holder == null) {
+    _state.holder = attachId;
+    _state.since = _now();
+    _publish();
+    return { holder: attachId, pending: null, immediate: true };
+  }
+  // Someone else already requested — drop their pending in favor of the
+  // newer one (last-writer-wins). Restart the grace timer.
+  _clearPending();
+  _state.pending = attachId;
+  _publish();
+  _state.pendingTimer = setTimeout(() => {
+    // Grace elapsed → force transfer. Read pending BEFORE _clearPending
+    // (which nulls it) so the check + assign happen against the value at
+    // schedule time, not the intermediate cleared state.
+    if (_state.pending !== attachId) return;  // preempted by another take
+    _state.holder = attachId;
+    _state.since = _now();
+    _state.pending = null;
+    _state.pendingTimer = null;
+    _publish();
+  }, GRACE_MS);
+  // No .unref(): we want the daemon event loop to be kept alive by a
+  // pending grace transfer. In tests, connected sockets already keep
+  // the loop alive, so no diff. In prod, this prevents a bahulamd whose
+  // ONLY outstanding work is a grace-steal from exiting mid-transfer.
+  return { holder: _state.holder, pending: attachId, immediate: false, graceMs: GRACE_MS };
+}
+
+/**
+ * `release_input_lock` command — the current holder yields.
+ * If there's a pending challenger, they take the lock immediately.
+ * If not, the lock becomes null (next `take_input_lock` from anyone wins).
+ */
+export function releaseInputLock(attachId) {
+  if (_state.holder !== attachId) return { ignored: true, reason: 'not_holder' };
+  if (_state.pending) {
+    _state.holder = _state.pending;
+    _state.since = _now();
+    _clearPending();
+  } else {
+    _state.holder = null;
+    _state.since = null;
+  }
+  _publish();
+  return { holder: _state.holder };
+}
+
+// ── query ────────────────────────────────────────────────────────────
+
+/** Read current lock state. Used by socket-server to enforce writes. */
+export function currentHolder() { return _state.holder; }
+export function isHolder(attachId) { return _state.holder === attachId; }
+
+/** For tests and `bahulam status`. */
+export function snapshot() {
+  return {
+    holder: _state.holder,
+    since: _state.since,
+    pending: _state.pending,
+  };
+}
+
+/** Reset (tests only, or on daemon shutdown). */
+export function resetInputLock() {
+  _clearPending();
+  _state.holder = null;
+  _state.since = null;
+}
+
+// ── internal ─────────────────────────────────────────────────────────
+
+function _clearPending() {
+  if (_state.pendingTimer) { clearTimeout(_state.pendingTimer); _state.pendingTimer = null; }
+  _state.pending = null;
+}