@bahulam/code 0.1.1 → 0.1.3

package/src/daemon/relay-client.mjs

@@ -0,0 +1,258 @@
+/**
+ * Relay WebSocket client — connects to the gateway relay and routes
+ * session events to attached CLI clients.
+ *
+ * On connect the client authenticates with a bearer token, then
+ * registers as a device on each active session. Events from the
+ * relay are dispatched to the appropriate session handler. *   • Heartbeat / keepalive via WebSocket ping (20s).
+ *   • Kill-switch check: BAHULAM_RELAY_KILL=1 env var, plus config
+ *     `remote.enabled = false` polled every 10s from the file so
+ *     `bahulam remote disable` in another terminal drops us fast.
+ *
+ * Deferred (Phase 2.5):
+ *   • ChaCha20-Poly1305 AEAD payload encryption. My envelope shape is
+ *     already compatible — swap the `control` field for `aead: {...}`
+ *     without changing the transport.
+ *   • X25519 wrap key derivation from paired peer_pubkeys.
+ *   • Signed command verification (Ed25519 signatures INSIDE the aead
+ *     payload per PRD §4).
+ *   • Session-key rotation.
+ *
+ * Non-fatal design principle: any relay error MUST NOT affect the local
+ * session. If the relay is down / unreachable / kicks us, the daemon
+ * keeps running for local attaches. Reconnect quietly in the background.
+ */
+
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+const YELLOW = '\x1b[33m';
+const GREEN = '\x1b[32m';
+
+const HEARTBEAT_MS = 20_000;
+const REVOKE_POLL_MS = 10_000;
+const BACKOFF_BASE_MS = 250;
+const BACKOFF_CAP_MS = 30_000;
+
+/**
+ * Start the relay bridge for a session. Returns { stop } — call to
+ * cleanly disconnect. Safe to call even without a valid config; if
+ * `remote.enabled = false` we log a note and return a stop() no-op.
+ *
+ * @param {object} opts
+ * @param {string}   opts.sessionId
+ * @param {object}   opts.remoteConfig    — from remote.mjs loadRemoteConfig()
+ * @param {Function} opts.registerBroadcaster — from event-tap.mjs
+ * @param {object}   opts.onCommand       — { approve, deny, interrupt, send_message, ... }
+ *                                            same shape as socket-server's onCommand.
+ */
+export function startRelayBridge({ sessionId, remoteConfig, registerBroadcaster, onCommand = {} } = {}) {
+  if (!remoteConfig?.enabled) {
+    return { stop: async () => {} };
+  }
+  if (!remoteConfig.device_id || !remoteConfig.token) {
+    process.stderr.write(`${YELLOW}[relay] remote enabled but device or token missing — skipping.${RESET}\n`);
+    return { stop: async () => {} };
+  }
+  if (typeof globalThis.WebSocket !== 'function') {
+    process.stderr.write(`${YELLOW}[relay] WebSocket not available in this Node runtime (need ≥22). Skipping.${RESET}\n`);
+    return { stop: async () => {} };
+  }
+
+  const url = _buildUrl(remoteConfig.relay_url, sessionId, remoteConfig.device_id, remoteConfig.token);
+  const state = {
+    stopped: false,
+    ws: null,
+    reconnectAttempt: 0,
+    heartbeatTimer: null,
+    revokeTimer: null,
+    unregisterBroadcaster: null,
+  };
+
+  function _log(msg) {
+    try { process.stderr.write(`${DIM}[relay] ${msg}${RESET}\n`); } catch {}
+  }
+
+  function _envelope(controlBody, to = 'session') {
+    return JSON.stringify({
+      v: 1,
+      sess: sessionId,
+      from: remoteConfig.device_id,
+      to,
+      // No AEAD until Phase 2.5 — send as a `control` field which
+      // gateway's relay.py forwards untouched (see routes/relay.py:_send_envelope).
+      // Payload is one  event/command exactly as it would appear
+      // on the local socket, but plaintext for now.
+      control: controlBody,
+    });
+  }
+
+  function _send(controlBody) {
+    if (!state.ws || state.ws.readyState !== 1 /* OPEN */) return false;
+    try { state.ws.send(_envelope(controlBody)); return true; }
+    catch (err) { _log(`send failed: ${err.message}`); return false; }
+  }
+
+  function _connect() {
+    if (state.stopped) return;
+    if (process.env.BAHULAM_RELAY_KILL === '1') {
+      _log('BAHULAM_RELAY_KILL=1 — refusing to dial');
+      return;
+    }
+    _log(`dial ${url.replace(/token=[^&]+/, 'token=***')}`);
+    const ws = new WebSocket(url, ['bahulam.v1']);
+    state.ws = ws;
+
+    ws.addEventListener('open', () => {
+      state.reconnectAttempt = 0;
+      try { process.stderr.write(`${GREEN}[relay] connected${RESET}\n`); } catch {}
+      // Send a `daemon_hello` control frame so peers (mobile) know who joined.
+      _send({ type: 'daemon_hello', device_id: remoteConfig.device_id, session_id: sessionId });
+      _startHeartbeat();
+      _startRevokePoll();
+    });
+
+    ws.addEventListener('message', ev => {
+      let env;
+      try { env = JSON.parse(String(ev.data)); }
+      catch { return; }
+      // Ignore our own broadcasts echoed back.
+      if (env.from === remoteConfig.device_id) return;
+      const control = env.control;
+      if (!control || !control.type) return;
+      _dispatchIncoming(control, env.from);
+    });
+
+    ws.addEventListener('close', ev => {
+      _stopHeartbeat();
+      state.ws = null;
+      if (state.stopped) return;
+      // Codes: 1008 policy (bad auth / bad envelope) → don't reconnect.
+      if (ev && (ev.code === 1008 || ev.code === 4001 || ev.code === 4003)) {
+        _log(`closed with policy code ${ev.code} (${ev.reason || 'no reason'}) — not reconnecting`);
+        return;
+      }
+      _scheduleReconnect(ev?.code);
+    });
+
+    ws.addEventListener('error', err => {
+      _log(`ws error: ${err?.message || err}`);
+      // 'close' will fire after, which triggers reconnect.
+    });
+  }
+
+  function _scheduleReconnect(closeCode) {
+    if (state.stopped) return;
+    state.reconnectAttempt += 1;
+    const base = Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * Math.pow(2, state.reconnectAttempt - 1));
+    const jitter = base * 0.5 * (Math.random() - 0.5);  // ±25%
+    const wait = Math.max(BACKOFF_BASE_MS, Math.floor(base + jitter));
+    _log(`reconnect in ${wait}ms (attempt ${state.reconnectAttempt}${closeCode ? `, close ${closeCode}` : ''})`);
+    setTimeout(() => { if (!state.stopped) _connect(); }, wait);
+  }
+
+  function _startHeartbeat() {
+    _stopHeartbeat();
+    state.heartbeatTimer = setInterval(() => {
+      // WebSocket doesn't have a JS-level ping in the browser API. Send a
+      // small control-frame keepalive instead. Gateway routes as any other
+      // envelope; peer clients can ignore type=keepalive.
+      _send({ type: 'keepalive', ts: Date.now() });
+    }, HEARTBEAT_MS);
+    if (typeof state.heartbeatTimer.unref === 'function') state.heartbeatTimer.unref();
+  }
+
+  function _stopHeartbeat() {
+    if (state.heartbeatTimer) { clearInterval(state.heartbeatTimer); state.heartbeatTimer = null; }
+  }
+
+  function _startRevokePoll() {
+    _stopRevokePoll();
+    state.revokeTimer = setInterval(() => {
+      // Re-read the local config; if remote was disabled or the device
+      // is missing, drop the connection. Fast reaction to `bahulam remote
+      // disable` in another terminal, or to `bahulam device revoke <self>`
+      // which clears the pairing block.
+      try {
+        const fresh = _reloadConfig();
+        if (!fresh?.enabled || fresh?.device_id !== remoteConfig.device_id) {
+          _log('local config changed (disabled or device mismatch) — disconnecting');
+          stop();
+        }
+      } catch { /* ignore, next poll retries */ }
+    }, REVOKE_POLL_MS);
+    if (typeof state.revokeTimer.unref === 'function') state.revokeTimer.unref();
+  }
+
+  function _stopRevokePoll() {
+    if (state.revokeTimer) { clearInterval(state.revokeTimer); state.revokeTimer = null; }
+  }
+
+  function _dispatchIncoming(control, fromDevice) {
+    const handler = onCommand[control.type];
+    if (typeof handler !== 'function') {
+      _log(`unknown control type from ${fromDevice}: ${control.type}`);
+      return;
+    }
+    // Pass fromDevice as the attach id so decisions get attributed.
+    Promise.resolve()
+      .then(() => handler(control.data || {}, `relay:${fromDevice}`))
+      .catch(err => _log(`handler for ${control.type} failed: ${err.message}`));
+  }
+
+  async function stop() {
+    if (state.stopped) return;
+    state.stopped = true;
+    _stopHeartbeat();
+    _stopRevokePoll();
+    if (state.unregisterBroadcaster) { try { state.unregisterBroadcaster(); } catch {} }
+    if (state.ws) {
+      try { state.ws.close(1000, 'client_stop'); } catch {}
+      state.ws = null;
+    }
+  }
+
+  // Register a broadcaster that forwards every daemon event to the relay.
+  // Return the unregister so stop() can clean up.
+  if (typeof registerBroadcaster === 'function') {
+    state.unregisterBroadcaster = registerBroadcaster(evt => {
+      // Forward every event as a control-frame envelope so mobile sees
+      // the same  §5.1 shape it does from the mock relay.
+      _send(evt);
+    });
+  }
+
+  _connect();
+  return { stop, _debug: state };
+}
+
+// ── helpers ──────────────────────────────────────────────────────────
+
+function _buildUrl(relayBase, sessionId, deviceId, token) {
+  // relay_url from config is like "wss://relay.bahulam.ai" or
+  // "wss://gateway.bahulam.ai" (the router mounts /relay/*). We append
+  // /relay/session/<sess_id>?device=&token= regardless.
+  const base = String(relayBase || '').replace(/\/+$/, '');
+  const enc = encodeURIComponent;
+  return `${base}/relay/session/${enc(sessionId)}?device=${enc(deviceId)}&token=${enc(token)}`;
+}
+
+// Re-read the config from disk on each poll so the daemon reacts to
+// out-of-band changes (bahulam remote disable, bahulam device revoke)
+// without needing a signal. Lazy dynamic import: cache the resolved
+// loader function so subsequent polls are one function call each.
+let _loadRemoteConfigCached = null;
+let _loadRemoteConfigPromise = null;
+
+function _reloadConfig() {
+  if (_loadRemoteConfigCached) return _loadRemoteConfigCached();
+  // First call: kick off the import in the background. Subsequent polls
+  // pick up the cached function once it's resolved. This poll returns
+  // null in the meantime (no config → stay connected, which is safe;
+  // the next poll in 10s will have the loader ready).
+  if (!_loadRemoteConfigPromise) {
+    _loadRemoteConfigPromise = import('../commands/remote.mjs')
+      .then(mod => { _loadRemoteConfigCached = mod.loadRemoteConfig || (() => null); })
+      .catch(() => { _loadRemoteConfigCached = () => null; });
+  }
+  return null;
+}

package/src/daemon/session-core.mjs

@@ -0,0 +1,179 @@
+/**
+ *  §6.1 / §6.8 — SessionCore: the daemon-owned view of a session.
+ *
+ * The daemon (bahulamd, .3+) owns:
+ *   1. The agent loop (SSE consumer → tool executor → event dispatch).
+ *   2. The event log ( §6.4).
+ *   3. The message history + cumulative usage — everything an attach
+ *      client needs to reconstruct the transcript on reconnect.
+ *
+ * The attach client () owns everything rendering-related:
+ *   spinner, per-line dedup, block-boundary tracking, sub-agent tool
+ *   window, input-history for arrow keys, one-shot toasts, etc.
+ *
+ * repl-state.mjs already holds both categories mixed together (see the
+ * `session` and `runtime` exports). This module is the *classification*
+ * of which fields the daemon persists across attach/detach and which
+ * belong to the attached client — plus a small snapshot/restore API
+ * bahulamd will call to write/read the periodic snapshot-<seq>.json
+ * files that seed a re-attaching client.
+ *
+ * IMPORTANT — cache invariance ( §7 note we keep repeating):
+ * NOTHING in this module gets sent to the LLM. The snapshot is written
+ * to local disk only. The daemon's outbound HTTP body to /api/execute
+ * is constructed exactly the same way it is today — via existing code
+ * paths that read session.agentHistory / session.messages. The
+ * BAHULAM_CAPTURE_REQUEST hook (see stream-client.mjs) exists so a
+ * later slice can hard-assert that byte identity.
+ */
+
+import { session as sharedSession } from '../terminal/repl-state.mjs';
+
+// ── field classification ─────────────────────────────────────────────
+
+/**
+ * Daemon-owned session fields. These persist across detach/attach and
+ * appear in snapshot-<seq>.json. Order and shape match repl-state.mjs
+ * so callers don't have to translate.
+ *
+ * A field belongs here if:
+ *   • Its value is the source of truth for what happened in the session
+ *     (message history, cumulative usage, cost, files touched, …).
+ *   • A re-attaching client needs it to render an accurate transcript.
+ *   • It doesn't change based on which attach is watching.
+ */
+export const DAEMON_OWNED_FIELDS = Object.freeze([
+  'id',
+  'startTime',
+  'inputTokens',
+  'outputTokens',
+  'toolCalls',
+  'subAgentToolCalls',
+  'totalToolCalls',
+  'totalPrimaryToolCalls',
+  'totalSubAgentToolCalls',
+  'turns',
+  'history',
+  'agentHistory',
+  'user',
+  'model',
+  'modelLimits',
+  'blockedOps',
+  'delegations',
+  'phases',
+  'filesChanged',
+  'filesRead',
+  'lastTurnDuration',
+  'toolCounts',
+  'subAgentCounts',
+  'savedUsd',
+  'lastTask',
+  'lastReasoning',
+  'budgetUsd',
+  'budgetExceeded',
+  'costBreakdown',
+  'totalCost',
+  'costAccurate',
+  'modelOverrides',
+  'modelMode',
+  'routePreference',
+  'isByok',
+  'subscriptionTier',
+  'creditsTotal',
+  'creditsIncluded',
+  'creditsPurchased',
+  'creditsLimit',
+  'creditsCharged',
+  'rateLimit',
+]);
+
+/**
+ * Client-owned session fields. These belong to whichever attach is
+ * currently connected and MUST NOT be included in snapshots — replaying
+ * them on re-attach would produce wrong UX (e.g. a "low credits" toast
+ * shown twice, arrow-key history from a stranger's terminal).
+ *
+ * A field belongs here if:
+ *   • It exists to dedup a per-attach UI effect (`*_LowWarned` flags).
+ *   • It's input state tied to a keyboard (`inputHistory`).
+ *   • It's a rendering flag whose value depends on the current visible
+ *     transcript, not the session's actual state (`inSubAgent`).
+ */
+export const CLIENT_OWNED_SESSION_FIELDS = Object.freeze([
+  'inputHistory',
+  'inSubAgent',
+  'creditsLowWarned',
+  'msgsLowWarned',
+  '_lastEmittedThinking',
+]);
+
+/**
+ * The `runtime` object in repl-state.mjs is ENTIRELY client-owned.
+ * It's stream buffers, spinner frames, explore-run counters, sub-agent
+ * live windows — all rendering. Listed here for completeness; the
+ * daemon never reads or writes runtime.*.
+ */
+export const CLIENT_OWNED_RUNTIME_FIELDS = Object.freeze([
+  'streamBuffer', 'streamedPartialText', 'streamTimer',
+  'renderedContentThisTurn', 'contentHeaderPrinted', 'afterContentFlush',
+  'pendingHead', 'lastRenderedBlock', 'renderedToolResults', 'renderedFileDiffPreviews',
+  'exploreRun', 'foldedSubAgentTools',
+  'spinInterval', 'spinText', 'spinFrame', 'spinPhase', 'spinStartedAt', 'spinToolCalls',
+  'subAgentWindow',
+]);
+
+// ── snapshot / restore ───────────────────────────────────────────────
+
+/**
+ * Extract the daemon-owned fields from a session-like object into a
+ * plain, JSON-serializable snapshot. Use `sharedSession` by default so
+ * bahulamd can call `snapshotSession()` with no arg and get the right
+ * thing; tests can pass an alternate source.
+ *
+ * Missing fields are omitted (not written as `undefined`) so the
+ * snapshot file stays clean. Nested objects/arrays are shallow-copied
+ * — callers that mutate history/agentHistory after snapshotting will
+ * see the mutation reflected. That's fine for the daemon (single
+ * writer, snapshot-then-continue pattern), but tests that reuse
+ * snapshots across mutations should structuredClone() the return.
+ */
+export function snapshotSession(source = sharedSession) {
+  const out = {};
+  for (const key of DAEMON_OWNED_FIELDS) {
+    if (source[key] !== undefined) out[key] = source[key];
+  }
+  return out;
+}
+
+/**
+ * Apply a snapshot back onto a session-like object. Only DAEMON_OWNED
+ * fields are copied — a maliciously crafted snapshot that includes
+ * runtime.* or CLIENT_OWNED_SESSION_FIELDS is silently ignored to
+ * prevent snapshot injection from replaying per-attach UI state.
+ *
+ * Fields the snapshot doesn't mention are left unchanged on `target`
+ * (not zeroed out). That way a partial snapshot from an older schema
+ * version still restores what it knows without wiping newer fields.
+ */
+export function restoreSession(snapshot, target = sharedSession) {
+  if (!snapshot || typeof snapshot !== 'object') return target;
+  for (const key of DAEMON_OWNED_FIELDS) {
+    if (Object.prototype.hasOwnProperty.call(snapshot, key)) {
+      target[key] = snapshot[key];
+    }
+  }
+  return target;
+}
+
+// ── introspection ────────────────────────────────────────────────────
+
+/**
+ * Classify a single field name. Useful in tests to guarantee every
+ * field in repl-state.mjs is accounted for (nothing accidentally lives
+ * in "neither" — new fields must be classified when added).
+ */
+export function classifyField(name) {
+  if (DAEMON_OWNED_FIELDS.includes(name)) return 'daemon';
+  if (CLIENT_OWNED_SESSION_FIELDS.includes(name)) return 'client';
+  return 'unclassified';
+}

package/src/daemon/session-list.mjs

@@ -0,0 +1,26 @@
+import { readdir, readFile } from 'node:fs/promises';
+ * Session list — reads local session metadata from ~/.bahulam/sessions/
+ * and presents them for attach/stop operations.  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const sessions = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory() || !entry.name.startsWith('sess_')) continue;
+      try {
+        const meta = JSON.parse(await readFile(join(dir, entry.name, 'meta.json'), 'utf-8'));
+        sessions.push({ id: entry.name, ...meta });
+      } catch { /* no meta.json, skip */ }
+    }
+    if (sessions.length === 0) {
+      process.stderr.write('No daemon sessions.\n');
+      return;
+    }
+    for (const s of sessions) {
+      const pid = s.pid ? ` (pid ${s.pid})` : '';
+      const cwd = s.cwd || '?';
+      const model = s.model || '?';
+      process.stderr.write(`  ${s.id}  ${cwd}  ${model}${pid}\n`);
+    }
+  } catch (err) {
+    process.stderr.write(`No daemon sessions: ${err.message}\n`);
+  }
+}

package/src/daemon/session-publisher.mjs

@@ -0,0 +1,78 @@
+/**
+ * .  — session_directory publisher (daemon side).
+ *
+ * POSTs to the gateway's /v1/session-directory endpoint on session
+ * lifecycle transitions so mobile clients + the web dashboard can see
+ * daemons that aren't currently connected to the relay.
+ *
+ * The gateway's /relay/sessions endpoint shows LIVE relay connections
+ * (in-memory hub state). This publisher covers the gap: daemons that
+ * started, ran, and now sit idle waiting for input still appear.
+ *
+ * Fire-and-forget: a publish failure MUST NOT interrupt the turn or
+ * crash the daemon. Errors log to stderr and the next transition retries.
+ *
+ * Called by:
+ *   - src/core/headless.mjs on session_info (status=running)
+ *   - src/core/headless.mjs on agent_complete (status=idle if held,
+ *                                              closed if exiting)
+ *   - src/terminal/repl.mjs on session_info (running) and REPL exit (closed)
+ *
+ * We hit the GATEWAY (BAHULAM_GATEWAY_URL) rather than Supabase directly
+ * because (a) the daemon has a Bahulam bearer token, not a Supabase
+ * JWT, and (b) the gateway already knows how to resolve that bearer to
+ * a user_id via /internal/whoami. Same trust chain as pair/device/remote.
+ */
+
+import * as os from 'node:os';
+
+const GATEWAY = (process.env.BAHULAM_GATEWAY_URL || 'https://gateway.bahulam.ai').replace(/\/+$/, '').replace(/\/v1$/, '');
+
+/** One publish. Returns nothing; errors log to stderr. */
+export async function publishSessionDirectory({
+  sessionId,
+  token,
+  cwd = null,
+  model = null,
+  hostHint = null,
+  status = 'running',
+  origin = 'local',
+} = {}) {
+  if (!sessionId || !token) return;
+  try {
+    const res = await fetch(`${GATEWAY}/v1/session-directory`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        session_id: sessionId,
+        origin,
+        host_hint: hostHint || _defaultHostHint(),
+        cwd_display: cwd,
+        model,
+        status,
+      }),
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      try { process.stderr.write(`[session-directory] publish ${status} failed (${res.status}): ${body.slice(0, 200)}\n`); } catch {}
+    }
+  } catch (err) {
+    try { process.stderr.write(`[session-directory] network error: ${err.message}\n`); } catch {}
+  }
+}
+
+/** Convenience: mark a session closed. Best-effort; call from exit paths. */
+export async function markSessionClosed({ sessionId, token }) {
+  return publishSessionDirectory({ sessionId, token, status: 'closed' });
+}
+
+function _defaultHostHint() {
+  try {
+    const user = process.env.USER || process.env.USERNAME || 'user';
+    const host = (os.hostname() || 'host').split('.')[0];
+    return `${user}@${host}`;
+  } catch { return 'unknown'; }
+}