Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

8.7 KB
Raw Blame
/**
 * SessionEventRegistry — the harness session-event layer's public surface.
 *
 * Keyed by Claude Code session_id (extracted from body.metadata.user_id).
 * Each session gets a TranscriptTailer over its transcript file
 * (<claudeHome>/projects/<slug>/<sid>.jsonl); translated events fold into
 * per-session state via the pure reducer and fan out to subscribers.
 *
 * Failure posture: no public method ever throws. Unknown session state is
 * `undefined` — callers must treat that as "no injection". Zero filesystem
 * cost unless a caller opts in (proOnUltracode gates every call site).
 */

import { existsSync, readFileSync, readdirSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
import { log } from "../logger.js";
import { projectDirNameFor } from "../mcp-session/home-dir.js";
import { translateLine } from "./event-translator.js";
import { initialState, reduceEvent } from "./session-state.js";
import { TranscriptTailer } from "./transcript-tailer.js";
import type { HarnessEvent, SessionEventState } from "./types.js";

export type SessionEventSubscriber = (sessionId: string, event: HarnessEvent) => void;

export interface SessionEventRegistryOptions {
  /** Claude Code home dir (default ~/.claude). Test seam — homedir() can't be re-pointed in Bun. */
  claudeHome?: string;
  /** Tailer poll interval in ms (default 250). Test seam. */
  pollIntervalMs?: number;
}

/** How long a transcript-not-found result is cached before retrying. */
const MISS_TTL_MS = 5_000;
/** After this many misses, stop looking for the session's transcript. */
const MAX_MISSES = 5;
/** Sessions idle longer than this are swept (lossless — re-ensure re-backfills). */
const IDLE_SWEEP_MS = 30 * 60 * 1000;

interface SessionEntry {
  state: SessionEventState;
  tailer: TranscriptTailer;
  lastActivity: number;
}

/**
 * Extract the Claude Code session_id from request metadata. Claude Code embeds
 * it in `metadata.user_id` (e.g. "user_<hash>_account_<uuid>_session_<uuid>").
 * Returns undefined for any unrecognized shape — which callers must treat as
 * "unknown session" (no injection).
 */
export function extractSessionId(metadata: unknown): string | undefined {
  const userId = (metadata as { user_id?: unknown } | null | undefined)?.user_id;
  if (typeof userId !== "string") return undefined;
  // Real captured shape (RequestMeta trace, 2026-07-13): user_id is a
  // JSON-ENCODED STRING — {"device_id":"…","account_uuid":"","session_id":"<uuid>"}.
  // The suffix-regex below does NOT match it ("session_" is followed by `id":"`),
  // so JSON parsing must come first.
  try {
    const parsed = JSON.parse(userId) as { session_id?: unknown };
    if (typeof parsed?.session_id === "string" && parsed.session_id) {
      return parsed.session_id;
    }
  } catch {
    // not JSON — fall through to the plain user_…_session_<uuid> suffix format
  }
  const match = userId.match(
    /session_([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i
  );
  return match?.[1];
}

/** Claude Code's project-dir name for a cwd: the one rule, `projectDirNameFor`. */
export function slugFromCwd(cwd: string): string {
  return projectDirNameFor(cwd);
}

export class SessionEventRegistry {
  private sessions = new Map<string, SessionEntry>();
  private misses = new Map<string, { lastTry: number; count: number }>();
  private subscribers: SessionEventSubscriber[] = [];
  private claudeHome: string;
  private pollIntervalMs?: number;

  constructor(opts: SessionEventRegistryOptions = {}) {
    this.claudeHome = opts.claudeHome ?? join(homedir(), ".claude");
    this.pollIntervalMs = opts.pollIntervalMs;
  }

  /** Locate the session transcript and start tailing it. Safe to call per request. */
  ensureSession(sessionId: string): void {
    try {
      this.sweepIdle();
      const existing = this.sessions.get(sessionId);
      if (existing) {
        existing.lastActivity = Date.now();
        return;
      }

      const miss = this.misses.get(sessionId);
      if (miss) {
        if (miss.count >= MAX_MISSES) return; // gave up (logged once below)
        if (Date.now() - miss.lastTry < MISS_TTL_MS) return;
      }

      const filePath = this.locateTranscript(sessionId);
      if (!filePath) {
        const count = (miss?.count ?? 0) + 1;
        this.misses.set(sessionId, { lastTry: Date.now(), count });
        if (count === MAX_MISSES) {
          log(
            `[SessionEvents] transcript for session ${sessionId} not found after ${MAX_MISSES} attempts — giving up`
          );
        }
        return;
      }
      this.misses.delete(sessionId);

      const entry: SessionEntry = {
        state: initialState({ defaultEffort: this.readSettingsEffortLevel() }),
        tailer: new TranscriptTailer(filePath, (line) => this.onLine(sessionId, line), {
          pollIntervalMs: this.pollIntervalMs,
          onError: (err) => log(`[SessionEvents] tailer for ${sessionId} stopped: ${err}`),
        }),
        lastActivity: Date.now(),
      };
      this.sessions.set(sessionId, entry);
      entry.tailer.start(); // backfills from byte 0 → full state even on late attach
      log(`[SessionEvents] tailing ${filePath}`);
    } catch (err) {
      // The event layer must never break request handling.
      log(`[SessionEvents] ensureSession(${sessionId}) failed: ${err}`);
    }
  }

  /** Synchronous drain — closes the enter-event→request timing window. */
  sync(sessionId: string): void {
    try {
      const entry = this.sessions.get(sessionId);
      if (entry) {
        entry.lastActivity = Date.now();
        entry.tailer.syncNow();
      }
    } catch (err) {
      log(`[SessionEvents] sync(${sessionId}) failed: ${err}`);
    }
  }

  /** Current folded state. `undefined` = unknown session = no injection. */
  getState(sessionId: string): SessionEventState | undefined {
    return this.sessions.get(sessionId)?.state;
  }

  /** Subscribe to translated events (the bus). Returns an unsubscribe fn. */
  subscribe(fn: SessionEventSubscriber): () => void {
    this.subscribers.push(fn);
    return () => {
      this.subscribers = this.subscribers.filter((s) => s !== fn);
    };
  }

  /** Dispose every tailer (proxy shutdown). */
  disposeAll(): void {
    for (const entry of this.sessions.values()) {
      entry.tailer.dispose();
    }
    this.sessions.clear();
    this.misses.clear();
  }

  // ─── Internal ────────────────────────────────────────────────────────

  private onLine(sessionId: string, line: string): void {
    const event = translateLine(line);
    if (!event) return;
    const entry = this.sessions.get(sessionId);
    if (!entry) return;
    entry.state = reduceEvent(entry.state, event);
    log(
      `[SessionEvents] ${sessionId}: ${event.kind}${event.kind === "effort_changed" ? ` level=${event.level} scope=${event.scope}` : ""} → ultracodeActive=${entry.state.ultracodeActive}`
    );
    for (const fn of this.subscribers) {
      try {
        fn(sessionId, event);
      } catch {
        // Subscriber errors must not poison the fold loop.
      }
    }
  }

  /**
   * <claudeHome>/projects/<slugFromCwd(cwd)>/<sid>.jsonl, with a glob fallback
   * across projects/* — the filename is unique per session, only the directory
   * lookup can mismatch (e.g. Claude Code launched from a different cwd).
   */
  private locateTranscript(sessionId: string): string | undefined {
    const projectsDir = join(this.claudeHome, "projects");
    const primary = join(projectsDir, slugFromCwd(process.cwd()), `${sessionId}.jsonl`);
    if (existsSync(primary)) return primary;
    try {
      for (const dir of readdirSync(projectsDir)) {
        const candidate = join(projectsDir, dir, `${sessionId}.jsonl`);
        if (existsSync(candidate)) return candidate;
      }
    } catch {
      // projects dir missing/unreadable → treated as not found
    }
    return undefined;
  }

  /** Seed for new sessions: persisted default from <claudeHome>/settings.json. */
  private readSettingsEffortLevel(): string | undefined {
    try {
      const settings = JSON.parse(readFileSync(join(this.claudeHome, "settings.json"), "utf-8"));
      return typeof settings.effortLevel === "string" ? settings.effortLevel : undefined;
    } catch {
      return undefined;
    }
  }

  private sweepIdle(): void {
    const now = Date.now();
    for (const [sid, entry] of this.sessions) {
      if (now - entry.lastActivity > IDLE_SWEEP_MS) {
        entry.tailer.dispose();
        this.sessions.delete(sid);
      }
    }
  }
}

/** Process-wide singleton — constructed lazily-cheap (no fs work until ensureSession). */
export const sessionEvents = new SessionEventRegistry();