@hienlh/ppm 0.23.8 → 0.23.10

package/src/services/agent-transcript/agent-transcript-envelope.ts

@@ -0,0 +1,86 @@
+/**
+ * Turn a parsed step (Claude's `TimedChatEvent`, Codex's tail-parser output)
+ * into the wire `AgentTranscriptEnvelope`, and split a batch of them into
+ * pages small enough for one WS frame.
+ */
+import type { ChatEvent } from "../../types/chat.ts";
+import { redactTruncate } from "../../providers/codex-app-server/codex-redact.ts";
+import {
+  CATCH_UP_MAX_BYTES, CATCH_UP_MAX_EVENTS, TOOL_OUTPUT_MAX_CHARS,
+  type AgentTranscriptEnvelope,
+} from "../../shared/agent-transcript-protocol.ts";
+
+/**
+ * A history view can afford to show a tool's full output; a window is a new
+ * long-lived stream kept open for as long as the card is, so both providers'
+ * `tool_result` get the same redaction + 20k cap here regardless of what the
+ * underlying parser already did for its own output shape.
+ */
+export function capToolOutput(ev: ChatEvent): ChatEvent {
+  if (ev.type !== "tool_result") return ev;
+  const capped = redactTruncate(ev.output, TOOL_OUTPUT_MAX_CHARS);
+  return capped === ev.output ? ev : { ...ev, output: capped };
+}
+
+/** Assemble one wire envelope for an explicit, already-decided key. */
+export function makeEnvelope(k: string, ev: ChatEvent, ts: number, replace?: true): AgentTranscriptEnvelope {
+  return {
+    ev: capToolOutput(ev),
+    ts,
+    k,
+    ...(replace ? { replace: true as const } : {}),
+  };
+}
+
+export function buildEnvelope(
+  fileKey: string,
+  chunkStartOffset: number,
+  index: number,
+  ev: ChatEvent,
+  ts: number,
+  replace?: true,
+): AgentTranscriptEnvelope {
+  return makeEnvelope(`${fileKey}:${chunkStartOffset}:${index}`, ev, ts, replace);
+}
+
+/**
+ * An envelope tagged with which subscription file it came from and the file
+ * offset fully consumed once this specific envelope has been delivered. The
+ * hub uses this to attach an exact, per-page cursor — the offset a page's
+ * own content corresponds to — rather than the subscription's final offset
+ * after the whole tick's read, which a client that only received an earlier
+ * page would wrongly treat as "already seen" on reconnect.
+ */
+export interface TaggedEnvelope {
+  envelope: AgentTranscriptEnvelope;
+  fileKey: string;
+  consumedThrough: number;
+}
+
+/**
+ * Split `items` into pages of at most `CATCH_UP_MAX_EVENTS` entries and
+ * roughly `CATCH_UP_MAX_BYTES` of serialized JSON — "roughly" because the
+ * byte count is measured on each candidate event as it's added rather than
+ * re-serializing the whole page, which is cheap and close enough for a page
+ * size limit. A single event that alone exceeds the byte budget still gets
+ * its own page rather than being dropped or blocking forever.
+ */
+export function paginateTagged(items: TaggedEnvelope[]): TaggedEnvelope[][] {
+  if (items.length === 0) return [];
+  const pages: TaggedEnvelope[][] = [];
+  let i = 0;
+  while (i < items.length) {
+    let count = 0;
+    let bytes = 0;
+    while (i + count < items.length && count < CATCH_UP_MAX_EVENTS) {
+      const size = JSON.stringify(items[i + count]!.envelope).length;
+      if (count > 0 && bytes + size > CATCH_UP_MAX_BYTES) break;
+      bytes += size;
+      count++;
+    }
+    const take = count > 0 ? count : 1;
+    pages.push(items.slice(i, i + take));
+    i += take;
+  }
+  return pages;
+}

package/src/services/agent-transcript/agent-transcript-error-map.ts

@@ -0,0 +1,33 @@
+/**
+ * Collapse the internal ownership/source error codes down to the four fixed
+ * codes the wire protocol allows — nothing past this point ever carries an
+ * internal enum name, a path, or an exception message.
+ */
+import type { OwnershipErrorCode } from "./session-ownership.ts";
+import type { SourceErrorCode } from "./agent-transcript-sources.ts";
+import type { AgentTranscriptErrorCode } from "../../shared/agent-transcript-protocol.ts";
+
+export function mapOwnershipErrorCode(code: OwnershipErrorCode): AgentTranscriptErrorCode {
+  switch (code) {
+    case "invalid_session_id":
+    case "invalid_provider":
+      return "bad_request";
+    case "invalid_project":
+    case "session_not_found":
+      return "not_found";
+  }
+}
+
+export function mapSourceErrorCode(code: SourceErrorCode): AgentTranscriptErrorCode {
+  switch (code) {
+    case "invalid_card_id":
+    case "invalid_team_name":
+    case "invalid_member_name":
+      return "bad_request";
+    case "card_not_found":
+    case "member_not_found":
+      return "not_found";
+    case "not_descendant":
+      return "forbidden";
+  }
+}

package/src/services/agent-transcript/agent-transcript-file-tail-feed.ts

@@ -0,0 +1,180 @@
+/**
+ * The read-a-chunk-of-new-bytes operation shared by catch-up (subscribe) and
+ * the live tick, over the state shape in `agent-transcript-file-tail-state.ts`.
+ *
+ * Every line is walked individually (not the whole newly-read chunk at once)
+ * so each produced envelope can be tagged with the exact file offset it made
+ * complete — the hub needs that to hand a client back a cursor for exactly
+ * what it was sent, not for however far the read happened to reach that tick.
+ */
+import { buildEnvelope } from "./agent-transcript-envelope.ts";
+import { agentTranscriptFsIo, statMtimeSafe } from "./agent-transcript-fs-io.ts";
+import { codexEnvelope, resetFileTailState, type FileTailState } from "./agent-transcript-file-tail-state.ts";
+import type { AgentTranscriptEnvelope } from "../../shared/agent-transcript-protocol.ts";
+
+/** Upper bound on bytes read from one file in one tick, so a multi-MB backlog
+ *  (a long teammate transcript, a large Codex rollout) cannot block the event
+ *  loop for the whole gap in one call — the remainder is picked up, as a plain
+ *  continuation (not another reset), on the next tick. */
+const PER_TICK_READ_BUDGET_BYTES = 512 * 1024;
+
+export interface FeedOutcome {
+  envelopes: AgentTranscriptEnvelope[];
+  /** Same length/order as `envelopes`: the file offset fully consumed once that envelope has been delivered. */
+  consumedThrough: number[];
+  /** Thread ids a Codex card's tail parser discovered since the last feed (nested spawns). */
+  links: string[];
+}
+
+/**
+ * Feed newly-read bytes through the file's parser, advancing `offset` only
+ * up to the last complete line. `growthAt` seeds/updates `lastGrowthAt` from
+ * the file's own mtime rather than "now" — reading a large, long-existing
+ * backlog for the very first time (a window opened on an already-finished
+ * agent) must not read as fresh activity just because THIS subscription is
+ * only just now catching up on it.
+ */
+function feedChunk(fstate: FileTailState, newChunk: Buffer, growthAt: number): FeedOutcome & { parserReset: boolean } {
+  const all = fstate.pendingBytes.length ? Buffer.concat([fstate.pendingBytes, newChunk]) : newChunk;
+  const lastNl = all.lastIndexOf(0x0a);
+  if (lastNl === -1) {
+    fstate.pendingBytes = all;
+    return { envelopes: [], consumedThrough: [], links: [], parserReset: false };
+  }
+  const consumed = all.subarray(0, lastNl + 1);
+  fstate.pendingBytes = all.subarray(lastNl + 1);
+  const chunkStartOffset = fstate.offset;
+  fstate.offset += consumed.length;
+  fstate.lastGrowthAt = growthAt;
+
+  const envelopes: AgentTranscriptEnvelope[] = [];
+  const consumedThrough: number[] = [];
+  const links: string[] = [];
+  let idx = 0;
+  let parserReset = false;
+  let pos = 0;
+  let fileOffset = chunkStartOffset;
+
+  while (pos < consumed.length) {
+    const nl = consumed.indexOf(0x0a, pos);
+    if (nl === -1) break; // unreachable: `consumed` always ends at a real newline
+    const lineBuf = consumed.subarray(pos, nl);
+    fileOffset += nl - pos + 1;
+    pos = nl + 1;
+    const line = lineBuf.toString("utf8").trim();
+    if (!line) continue;
+
+    if (fstate.ref.provider === "claude") {
+      for (const timed of fstate.claudeParser!.feed(line)) {
+        envelopes.push(buildEnvelope(fstate.ref.key, chunkStartOffset, idx++, timed.ev, timed.ts));
+        consumedThrough.push(fileOffset);
+      }
+      continue;
+    }
+
+    const fed = fstate.codexParser!.feed(`${line}\n`);
+    if (fed.reset) {
+      // A compaction/rollback record inside THIS SAME read means everything
+      // accumulated from earlier lines of it is no longer authoritative —
+      // the parser already dropped its own de-dupe state for this; the
+      // per-line loop just does the same to what it had already pushed out.
+      envelopes.length = 0;
+      consumedThrough.length = 0;
+      fstate.toolUseKeyById.clear();
+      parserReset = true;
+    }
+    for (const e of fed.events) {
+      const freshKey = `${fstate.ref.key}:${chunkStartOffset}:${idx++}`;
+      envelopes.push(codexEnvelope(fstate, freshKey, e));
+      consumedThrough.push(fileOffset);
+    }
+    links.push(...fed.links);
+  }
+
+  return { envelopes, consumedThrough, links, parserReset };
+}
+
+export interface ProcessFileResult extends FeedOutcome {
+  /** The client must discard prior state for this file: truncation, or a Codex compaction/rollback. */
+  reset: boolean;
+  /**
+   * True when the file still has unread bytes past `PER_TICK_READ_BUDGET_BYTES`
+   * after this call. The tick scheduler must keep polling at the live cadence
+   * while this is true — a finished-but-large transcript (idle by mtime, so
+   * `running: false`) would otherwise drain in slow idle-cadence chunks
+   * instead of catching up as fast as the budget allows.
+   */
+  hasMoreBacklog: boolean;
+}
+
+const EMPTY_RESULT: FeedOutcome = { envelopes: [], consumedThrough: [], links: [] };
+
+/**
+ * Read whatever is new for one file (from `fstate.offset` up to at most
+ * `PER_TICK_READ_BUDGET_BYTES` past it) and return the resulting steps.
+ * Handles both reset triggers: a file that shrank below the last known
+ * offset (rotated/truncated), and a Codex tail parser reporting its own
+ * history was rewritten mid-chunk. Never throws — a locked or vanished file,
+ * or a raced read past a boundary, degrades to "nothing new this tick"
+ * rather than reaching the caller (a single bad file must not take the
+ * whole subscription, or the process, down with it).
+ */
+export function processFileTail(fstate: FileTailState, now: number): ProcessFileResult {
+  let size: number;
+  try {
+    size = agentTranscriptFsIo.statSize(fstate.ref.path);
+  } catch {
+    return { ...EMPTY_RESULT, reset: false, hasMoreBacklog: false };
+  }
+
+  let truncated = false;
+  if (size < fstate.offset) {
+    resetFileTailState(fstate, now);
+    truncated = true;
+  }
+
+  let diskPos = fstate.offset + fstate.pendingBytes.length;
+  if (size < diskPos) {
+    fstate.pendingBytes = Buffer.alloc(0);
+    diskPos = fstate.offset;
+  }
+  if (size <= diskPos) return { ...EMPTY_RESULT, reset: truncated, hasMoreBacklog: false };
+
+  const growthAt = statMtimeSafe(fstate.ref.path) ?? now;
+  const toRead = Math.min(size - diskPos, PER_TICK_READ_BUDGET_BYTES);
+  let chunk: Buffer;
+  try {
+    chunk = agentTranscriptFsIo.readRange(fstate.ref.path, diskPos, toRead);
+  } catch {
+    return { ...EMPTY_RESULT, reset: truncated, hasMoreBacklog: size > diskPos };
+  }
+
+  const fed = feedChunk(fstate, chunk, growthAt);
+  const remainderAfterNormalRead = size > fstate.offset + fstate.pendingBytes.length;
+  if (!fed.parserReset) {
+    return {
+      envelopes: fed.envelopes, consumedThrough: fed.consumedThrough, links: fed.links,
+      reset: truncated, hasMoreBacklog: remainderAfterNormalRead,
+    };
+  }
+
+  // The parser's own history was rewritten (Codex compaction/rollback): the
+  // events already computed from this chunk reflect a mix of pre- and
+  // post-rewrite state, so re-derive the authoritative version from byte 0
+  // with a fresh parser rather than trying to patch up what we have. Bounded
+  // by the same read budget — a huge rewritten file resumes as a plain
+  // continuation (not another reset) on the next tick.
+  resetFileTailState(fstate, now);
+  let full: Buffer;
+  try {
+    full = agentTranscriptFsIo.readRange(fstate.ref.path, 0, Math.min(size, PER_TICK_READ_BUDGET_BYTES));
+  } catch {
+    return { ...EMPTY_RESULT, reset: true, hasMoreBacklog: size > 0 };
+  }
+  const fed2 = feedChunk(fstate, full, growthAt);
+  const remainderAfterResync = size > fstate.offset + fstate.pendingBytes.length;
+  return {
+    envelopes: fed2.envelopes, consumedThrough: fed2.consumedThrough, links: fed2.links,
+    reset: true, hasMoreBacklog: remainderAfterResync,
+  };
+}

package/src/services/agent-transcript/agent-transcript-file-tail-state.ts

@@ -0,0 +1,100 @@
+/**
+ * Per-subscription, per-file read state: what a `FileTailState` carries and
+ * how it starts out / gets wiped on a reset. The read-a-chunk-of-new-bytes
+ * operation itself (shared by catch-up and the live tick) is
+ * `agent-transcript-file-tail-feed.ts` — kept apart so this file stays just
+ * the state shape or it would not fit the project's file-size guideline.
+ *
+ * The reported `offset` always sits on a line boundary. Bytes already read
+ * from disk but not yet newline-terminated stay in `pendingBytes`, in memory,
+ * NOT counted in `offset` — so a client that reconnects with an old cursor
+ * and a fresh server-side parser always resumes exactly at a line start. If
+ * that were not true, a cursor landing mid-line would either skip the rest of
+ * that line forever (offset counted past it) or feed a parser a fragment it
+ * cannot make sense of (a fresh parser's own internal buffering, if it had
+ * any, would not know a prefix was already spent elsewhere).
+ */
+import type { ChatEvent } from "../../types/chat.ts";
+import type { TranscriptFileRef } from "./agent-transcript-sources.ts";
+import { createAgentTranscriptLineParser } from "../subagent-transcript-merger.ts";
+import { createRolloutTailParser } from "../../providers/codex-app-server/codex-rollout-tail-parser.ts";
+import { makeEnvelope } from "./agent-transcript-envelope.ts";
+import { statMtimeSafe } from "./agent-transcript-fs-io.ts";
+import type { AgentTranscriptEnvelope } from "../../shared/agent-transcript-protocol.ts";
+
+export interface FileTailState {
+  ref: TranscriptFileRef;
+  offset: number;
+  pendingBytes: Buffer;
+  lastGrowthAt: number;
+  claudeParser?: ReturnType<typeof createAgentTranscriptLineParser>;
+  codexParser?: ReturnType<typeof createRolloutTailParser>;
+  /** Codex only: the `k` first issued for a toolUseId, so a later `replace`
+   *  record for the same id reuses it instead of minting an unmatchable one
+   *  (see `agent-transcript-file-tail-feed.ts`). */
+  toolUseKeyById: Map<string, string>;
+}
+
+/** Seed idle/liveness tracking from the file's own mtime, not "now" — a window
+ *  opened on an already-finished agent must not read as freshly active just
+ *  because that is when someone happened to subscribe. */
+function initialGrowthAt(path: string, now: number): number {
+  return statMtimeSafe(path) ?? now;
+}
+
+export function createFileTailState(ref: TranscriptFileRef, startOffset: number, now: number): FileTailState {
+  const midFile = startOffset > 0;
+  return {
+    ref,
+    offset: startOffset,
+    pendingBytes: Buffer.alloc(0),
+    lastGrowthAt: initialGrowthAt(ref.path, now),
+    claudeParser: ref.provider === "claude" ? createAgentTranscriptLineParser({ midFile, maxEvents: Infinity }) : undefined,
+    codexParser: ref.provider === "codex" ? createRolloutTailParser() : undefined,
+    toolUseKeyById: new Map(),
+  };
+}
+
+/** Wipe a file's tracked state back to "never read": a truncation/rotation or
+ *  a Codex compaction/rollback means nothing previously derived from it can
+ *  be trusted, so the next read starts over from byte 0 with fresh parsers. */
+export function resetFileTailState(fstate: FileTailState, now: number): void {
+  fstate.offset = 0;
+  fstate.pendingBytes = Buffer.alloc(0);
+  fstate.lastGrowthAt = now;
+  fstate.claudeParser = fstate.ref.provider === "claude" ? createAgentTranscriptLineParser({ midFile: false, maxEvents: Infinity }) : undefined;
+  fstate.codexParser = fstate.ref.provider === "codex" ? createRolloutTailParser() : undefined;
+  fstate.toolUseKeyById = new Map();
+}
+
+function toolUseIdOf(ev: ChatEvent): string | undefined {
+  return "toolUseId" in ev ? ev.toolUseId : undefined;
+}
+
+/**
+ * One Codex event → its envelope, reusing the id's first-issued key on a
+ * replace so the client's upsert-by-`k` lands on the entry it is meant to
+ * update instead of appending.
+ *
+ * Keyed by `${type}:${toolUseId}`, NOT by id alone: a single `CommandExecution`
+ * item emits a `tool_use` and a `tool_result` sharing the SAME id, and the
+ * tail parser flags the second one `replace` because it only tracks "has
+ * this id been seen", not "as which type". Keying on id alone made a
+ * `tool_result` reuse its own `tool_use`'s key — the client then replaced
+ * the tool_use IN PLACE with the result and the step vanished. `replace` is
+ * only ever honoured here when a PRIOR envelope of the SAME type for the
+ * SAME id exists; otherwise a fresh key is minted (and `replace` dropped —
+ * there is nothing for it to refer to).
+ */
+export function codexEnvelope(fstate: FileTailState, freshKey: string, e: { ev: ChatEvent; ts: number; replace?: boolean }): AgentTranscriptEnvelope {
+  const id = toolUseIdOf(e.ev);
+  if (!id) return makeEnvelope(freshKey, e.ev, e.ts, undefined);
+
+  const mapKey = `${e.ev.type}:${id}`;
+  if (e.replace) {
+    const original = fstate.toolUseKeyById.get(mapKey);
+    if (original) return makeEnvelope(original, e.ev, e.ts, true);
+  }
+  fstate.toolUseKeyById.set(mapKey, freshKey);
+  return makeEnvelope(freshKey, e.ev, e.ts, undefined);
+}

package/src/services/agent-transcript/agent-transcript-fs-io.ts

@@ -0,0 +1,79 @@
+/**
+ * Filesystem seam the hub reads through, so a test can simulate a locked or
+ * vanished file without touching real disk I/O, and so the tick path never
+ * hides a surprise `fs` call behind a helper that looks pure.
+ *
+ * Every read is by explicit byte range — the hub never re-reads a file from
+ * the start just to find out how much it grew. Each subscription stats and
+ * reads its own files independently (one stat per (subscription, file) pair
+ * per tick) — several subscriptions watching the same underlying path are
+ * not de-duplicated against each other.
+ */
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+
+export interface AgentTranscriptFsIo {
+  /** Current file size in bytes. Throws if the file does not exist. */
+  statSize(path: string): number;
+  /** File mtime in epoch ms, for seeding "last known activity" without assuming `now`. Throws if missing. */
+  statMtimeMs(path: string): number;
+  /** Directory mtime in epoch ms, for the "did anything change" index-refresh check. Throws if missing. */
+  statDirMtimeMs(path: string): number;
+  /** Bytes `[start, start+length)`. `length <= 0` returns an empty buffer without opening the file. */
+  readRange(path: string, start: number, length: number): Buffer;
+}
+
+function realReadRange(path: string, start: number, length: number): Buffer {
+  if (length <= 0) return Buffer.alloc(0);
+  const fd = openSync(path, "r");
+  try {
+    const buf = Buffer.alloc(length);
+    const n = readSync(fd, buf, 0, length, start);
+    return buf.subarray(0, n);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export const realAgentTranscriptFsIo: AgentTranscriptFsIo = {
+  statSize: (path) => statSync(path).size,
+  statMtimeMs: (path) => statSync(path).mtimeMs,
+  statDirMtimeMs: (path) => statSync(path).mtimeMs,
+  readRange: realReadRange,
+};
+
+/** Mutable seam — reassign in a test, restore in `afterEach`. */
+export const agentTranscriptFsIo: AgentTranscriptFsIo = { ...realAgentTranscriptFsIo };
+
+export function resetAgentTranscriptFsIoForTest(): void {
+  agentTranscriptFsIo.statSize = realAgentTranscriptFsIo.statSize;
+  agentTranscriptFsIo.statMtimeMs = realAgentTranscriptFsIo.statMtimeMs;
+  agentTranscriptFsIo.statDirMtimeMs = realAgentTranscriptFsIo.statDirMtimeMs;
+  agentTranscriptFsIo.readRange = realAgentTranscriptFsIo.readRange;
+}
+
+/** `statSize`, or `null` for any error (missing file, permission, raced delete). */
+export function statSizeSafe(path: string): number | null {
+  try {
+    return agentTranscriptFsIo.statSize(path);
+  } catch {
+    return null;
+  }
+}
+
+/** `statMtimeMs`, or `null` for any error. */
+export function statMtimeSafe(path: string): number | null {
+  try {
+    return agentTranscriptFsIo.statMtimeMs(path);
+  } catch {
+    return null;
+  }
+}
+
+/** `statDirMtimeMs`, or `null` for any error. */
+export function statDirMtimeSafe(path: string): number | null {
+  try {
+    return agentTranscriptFsIo.statDirMtimeMs(path);
+  } catch {
+    return null;
+  }
+}

package/src/services/agent-transcript/agent-transcript-hub-clock.ts

@@ -0,0 +1,37 @@
+/**
+ * Test seams for the hub's two time-driven behaviors: "what time is it" and
+ * "call me back in N ms". Mutable singletons (same shape as
+ * `designWriteClock` in `design-write-rate-limit.ts`) rather than constructor
+ * parameters threaded through every function, so a unit test can swap either
+ * one out for the duration of a case and put it back.
+ *
+ * A test that wants deterministic ticks replaces `setInterval` with a no-op
+ * that never actually schedules anything, then drives the hub by calling its
+ * internal tick function directly while moving `clock.now` forward by hand —
+ * real wall-clock delays never enter the picture.
+ */
+
+export interface AgentTranscriptClock {
+  now(): number;
+}
+
+export const agentTranscriptClock: AgentTranscriptClock = {
+  now: () => Date.now(),
+};
+
+export interface AgentTranscriptTimers {
+  setInterval(fn: () => void, ms: number): unknown;
+  clearInterval(handle: unknown): void;
+}
+
+export const agentTranscriptTimers: AgentTranscriptTimers = {
+  setInterval: (fn, ms) => setInterval(fn, ms),
+  clearInterval: (handle) => clearInterval(handle as ReturnType<typeof setInterval>),
+};
+
+/** Restore both seams to their real implementations; call from `afterEach`. */
+export function resetAgentTranscriptClockForTest(): void {
+  agentTranscriptClock.now = () => Date.now();
+  agentTranscriptTimers.setInterval = (fn, ms) => setInterval(fn, ms);
+  agentTranscriptTimers.clearInterval = (handle) => clearInterval(handle as ReturnType<typeof setInterval>);
+}

package/src/services/agent-transcript/agent-transcript-hub-registry.ts

@@ -0,0 +1,153 @@
+/**
+ * Cross-hub bookkeeping for `agent-transcript-hub.ts`: which `SessionHub` a
+ * client's `subId` currently lives in (needed because a `subId` carries no
+ * session info on `unsubscribe`, and the same client can hold subscriptions
+ * on several different sessions at once), the server-wide subscription count,
+ * and dropping a client from every hub it touches at once.
+ */
+import { configService } from "../config.service.ts";
+import type { OwnedSession } from "./session-ownership.ts";
+import type { AgentTranscriptWsLike } from "./agent-transcript-ws-like.ts";
+import {
+  activitySubCount, createSessionHub, hubIsEmpty, transcriptSubCount, type SessionHub,
+} from "./agent-transcript-session-hub-types.ts";
+import { dropAllTranscriptForWs, removeTranscriptSubscription } from "./agent-transcript-session-hub.ts";
+import { dropAllActivityForWs, removeActivitySubscription } from "./agent-transcript-session-hub-activity.ts";
+
+const sessionHubs = new Map<string, SessionHub>();
+/** Which session hub a client's transcript/activity `subId` currently lives in. */
+const clientTranscriptSubs = new Map<AgentTranscriptWsLike, Map<string, string>>();
+const clientActivitySubs = new Map<AgentTranscriptWsLike, Map<string, string>>();
+
+export function hubKey(providerId: string, sessionId: string): string {
+  return `${providerId}\0${sessionId}`;
+}
+
+/** `ws.data.token` (snapshotted at upgrade) against the live config — see `server/index.ts` and `ws/global.ts`. */
+export function tokenStillValid(ws: AgentTranscriptWsLike): boolean {
+  const auth = configService.get("auth");
+  if (!auth.enabled) return true;
+  return (ws.data?.token ?? null) === auth.token;
+}
+
+export function totalTranscriptSubs(): number {
+  let n = 0;
+  for (const hub of sessionHubs.values()) n += transcriptSubCount(hub);
+  return n;
+}
+
+export function totalActivitySubs(): number {
+  let n = 0;
+  for (const hub of sessionHubs.values()) n += activitySubCount(hub);
+  return n;
+}
+
+export function projectPathFor(projectName: string): string | null {
+  return configService.get("projects").find((p) => p.name === projectName)?.path ?? null;
+}
+
+/**
+ * `owned` must come from an `assertSessionInProject` call made for THIS
+ * request's own claimed project — a hub already cached under the same
+ * `(providerId, sessionId)` is only ever reused once the caller has
+ * independently proven that pairing resolves to a project it may read,
+ * never trusted just because some earlier, different caller created it.
+ */
+export function getOrCreateHub(owned: OwnedSession): SessionHub {
+  const key = hubKey(owned.providerId, owned.sessionId);
+  const existing = sessionHubs.get(key);
+  if (existing) return existing;
+  const hub = createSessionHub(key, owned, dropClientEverywhere, unregisterTranscriptSub, tokenStillValid);
+  sessionHubs.set(key, hub);
+  return hub;
+}
+
+export function maybeDropHub(key: string): void {
+  const hub = sessionHubs.get(key);
+  if (hub && hubIsEmpty(hub)) sessionHubs.delete(key);
+}
+
+export function registerTranscriptSub(ws: AgentTranscriptWsLike, subId: string, key: string): void {
+  let bySubId = clientTranscriptSubs.get(ws);
+  if (!bySubId) {
+    bySubId = new Map();
+    clientTranscriptSubs.set(ws, bySubId);
+  }
+  bySubId.set(subId, key);
+}
+
+export function registerActivitySub(ws: AgentTranscriptWsLike, subId: string, key: string): void {
+  let bySubId = clientActivitySubs.get(ws);
+  if (!bySubId) {
+    bySubId = new Map();
+    clientActivitySubs.set(ws, bySubId);
+  }
+  bySubId.set(subId, key);
+}
+
+export function transcriptSubCountForClient(ws: AgentTranscriptWsLike): number {
+  return clientTranscriptSubs.get(ws)?.size ?? 0;
+}
+
+export function activitySubCountForClient(ws: AgentTranscriptWsLike): number {
+  return clientActivitySubs.get(ws)?.size ?? 0;
+}
+
+export function unregisterTranscriptSub(ws: AgentTranscriptWsLike, subId: string): void {
+  const key = clientTranscriptSubs.get(ws)?.get(subId);
+  if (!key) return;
+  clientTranscriptSubs.get(ws)!.delete(subId);
+  if (clientTranscriptSubs.get(ws)!.size === 0) clientTranscriptSubs.delete(ws);
+  const hub = sessionHubs.get(key);
+  if (hub) {
+    removeTranscriptSubscription(hub, ws, subId);
+    maybeDropHub(key);
+  }
+}
+
+export function unregisterActivitySub(ws: AgentTranscriptWsLike, subId: string): void {
+  const key = clientActivitySubs.get(ws)?.get(subId);
+  if (!key) return;
+  clientActivitySubs.get(ws)!.delete(subId);
+  if (clientActivitySubs.get(ws)!.size === 0) clientActivitySubs.delete(ws);
+  const hub = sessionHubs.get(key);
+  if (hub) {
+    removeActivitySubscription(hub, ws, subId);
+    maybeDropHub(key);
+  }
+}
+
+/** Drop everything a socket holds, in every hub it touches. Called on close, a stale token, or a failed send. */
+export function dropClientEverywhere(ws: AgentTranscriptWsLike): void {
+  const hubKeys = new Set<string>([
+    ...(clientTranscriptSubs.get(ws)?.values() ?? []),
+    ...(clientActivitySubs.get(ws)?.values() ?? []),
+  ]);
+  clientTranscriptSubs.delete(ws);
+  clientActivitySubs.delete(ws);
+  for (const key of hubKeys) {
+    const hub = sessionHubs.get(key);
+    if (!hub) continue;
+    dropAllTranscriptForWs(hub, ws);
+    dropAllActivityForWs(hub, ws);
+    maybeDropHub(key);
+  }
+}
+
+/** Test-only: forget every hub and client mapping between cases. */
+export function _resetAgentTranscriptHubForTest(): void {
+  sessionHubs.clear();
+  clientTranscriptSubs.clear();
+  clientActivitySubs.clear();
+}
+
+/** Test-only: peek at a hub's existence/subscription counts without exporting internal state. */
+export function _debugHubSnapshotForTest(providerId: "claude" | "codex", sessionId: string): { exists: boolean; transcriptSubs: number } {
+  const hub = sessionHubs.get(hubKey(providerId, sessionId));
+  return { exists: !!hub, transcriptSubs: hub ? transcriptSubCount(hub) : 0 };
+}
+
+/** Test-only: the raw hub, so a test can drive its tick functions directly instead of waiting on real timers. */
+export function _getSessionHubForTest(providerId: "claude" | "codex", sessionId: string): SessionHub | undefined {
+  return sessionHubs.get(hubKey(providerId, sessionId));
+}