@hienlh/ppm 0.23.8 → 0.23.10

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

@@ -0,0 +1,103 @@
+/**
+ * Message handlers for the `/ws/global` agent-transcript protocol (see
+ * `src/shared/agent-transcript-protocol.ts`). Per-client caps, `subId`
+ * bookkeeping and cross-hub client drop live in `agent-transcript-hub-registry.ts`;
+ * this module is only the four message shapes and their validation.
+ */
+import { assertSessionInProject } from "./session-ownership.ts";
+import { mapOwnershipErrorCode } from "./agent-transcript-error-map.ts";
+import { sendWsMessage, type AgentTranscriptWsLike } from "./agent-transcript-ws-like.ts";
+import { addTranscriptSubscription } from "./agent-transcript-session-hub.ts";
+import { addActivitySubscription } from "./agent-transcript-session-hub-activity.ts";
+import {
+  activitySubCountForClient, dropClientEverywhere, getOrCreateHub, maybeDropHub, projectPathFor,
+  registerActivitySub, registerTranscriptSub, totalActivitySubs, totalTranscriptSubs, transcriptSubCountForClient,
+  unregisterActivitySub, unregisterTranscriptSub,
+} from "./agent-transcript-hub-registry.ts";
+import {
+  MAX_TRANSCRIPT_SUBS_PER_CLIENT, MAX_TRANSCRIPT_SUBS_PER_SERVER,
+  type AgentActivitySubscribeMsg, type AgentActivityUnsubscribeMsg,
+  type AgentTranscriptErrorMsg, type AgentTranscriptSubscribeMsg, type AgentTranscriptUnsubscribeMsg,
+} from "../../shared/agent-transcript-protocol.ts";
+
+function sendError(ws: AgentTranscriptWsLike, subId: string, code: AgentTranscriptErrorMsg["code"]): void {
+  sendWsMessage(ws, { type: "agent-transcript:error", subId, code } satisfies AgentTranscriptErrorMsg);
+}
+
+export function handleAgentTranscriptSubscribe(ws: AgentTranscriptWsLike, msg: AgentTranscriptSubscribeMsg): void {
+  const { subId, projectName, providerId, sessionId, source, cursor } = msg;
+  if (typeof subId !== "string" || !subId) return;
+  if (
+    typeof projectName !== "string" || (providerId !== "claude" && providerId !== "codex") ||
+    typeof sessionId !== "string" || !source || typeof source !== "object" ||
+    (source.kind !== "card" && source.kind !== "member")
+  ) {
+    return sendError(ws, subId, "bad_request");
+  }
+
+  const projectPath = projectPathFor(projectName);
+  if (!projectPath) return sendError(ws, subId, "not_found");
+
+  // Replacing an existing subId costs nothing against the cap — drop it first.
+  unregisterTranscriptSub(ws, subId);
+
+  if (transcriptSubCountForClient(ws) >= MAX_TRANSCRIPT_SUBS_PER_CLIENT) return sendError(ws, subId, "limit");
+  if (totalTranscriptSubs() >= MAX_TRANSCRIPT_SUBS_PER_SERVER) return sendError(ws, subId, "limit");
+
+  const owned = assertSessionInProject({ providerId, sessionId, projectPath });
+  if (!owned.ok) return sendError(ws, subId, mapOwnershipErrorCode(owned.code));
+
+  const hub = getOrCreateHub(owned);
+  const result = addTranscriptSubscription(hub, ws, subId, source, cursor);
+  if (!result.ok) {
+    maybeDropHub(hub.key);
+    return sendError(ws, subId, result.code ?? "bad_request");
+  }
+
+  registerTranscriptSub(ws, subId, hub.key);
+  if (result.sendFailed) dropClientEverywhere(ws);
+}
+
+export function handleAgentTranscriptUnsubscribe(ws: AgentTranscriptWsLike, msg: AgentTranscriptUnsubscribeMsg): void {
+  if (typeof msg.subId === "string") unregisterTranscriptSub(ws, msg.subId);
+}
+
+export function handleAgentActivitySubscribe(ws: AgentTranscriptWsLike, msg: AgentActivitySubscribeMsg): void {
+  const { subId, projectName, providerId, sessionId } = msg;
+  if (typeof subId !== "string" || !subId) return;
+  if (typeof projectName !== "string" || (providerId !== "claude" && providerId !== "codex") || typeof sessionId !== "string") {
+    return sendError(ws, subId, "bad_request");
+  }
+  const projectPath = projectPathFor(projectName);
+  if (!projectPath) return sendError(ws, subId, "not_found");
+
+  // Replacing an existing subId costs nothing against the cap — drop it first.
+  unregisterActivitySub(ws, subId);
+
+  if (activitySubCountForClient(ws) >= MAX_TRANSCRIPT_SUBS_PER_CLIENT) return sendError(ws, subId, "limit");
+  if (totalActivitySubs() >= MAX_TRANSCRIPT_SUBS_PER_SERVER) return sendError(ws, subId, "limit");
+
+  const owned = assertSessionInProject({ providerId, sessionId, projectPath });
+  if (!owned.ok) return sendError(ws, subId, mapOwnershipErrorCode(owned.code));
+
+  const hub = getOrCreateHub(owned);
+  addActivitySubscription(hub, ws, subId);
+  registerActivitySub(ws, subId, hub.key);
+}
+
+export function handleAgentActivityUnsubscribe(ws: AgentTranscriptWsLike, msg: AgentActivityUnsubscribeMsg): void {
+  if (typeof msg.subId === "string") unregisterActivitySub(ws, msg.subId);
+}
+
+export function handleAgentTranscriptPing(ws: AgentTranscriptWsLike): void {
+  sendWsMessage(ws, { type: "pong" });
+}
+
+/** Socket closed: drop every transcript and activity subscription it held. */
+export function handleAgentTranscriptClientClosed(ws: AgentTranscriptWsLike): void {
+  dropClientEverywhere(ws);
+}
+
+export {
+  _debugHubSnapshotForTest, _getSessionHubForTest, _resetAgentTranscriptHubForTest,
+} from "./agent-transcript-hub-registry.ts";

package/src/services/agent-transcript/agent-transcript-index-cache.ts

@@ -0,0 +1,85 @@
+/**
+ * Shared cache over `groupSubagentsByCard`, so the hub and
+ * `nested-subagent-spy.ts` cost one directory scan per session per refresh
+ * window between them, not one each. `groupSubagentsByCard` itself reads
+ * every `*.meta.json` in the subagents dir — cheap for one caller, not for
+ * two independent pollers doing it every tick.
+ *
+ * Refreshed at most every `INDEX_REFRESH_MS`, except a directory mtime change
+ * (a new agent spawned, one finished) forces an immediate refresh regardless
+ * of how recently the last one ran — the 2s floor bounds cost, the mtime
+ * check bounds staleness.
+ */
+import {
+  groupSubagentsByCard, indexTranscriptsByMember,
+  type SubagentTranscriptEntry,
+} from "../team-member-activity/subagent-transcript-index.ts";
+import { agentTranscriptClock } from "./agent-transcript-hub-clock.ts";
+import { statDirMtimeSafe } from "./agent-transcript-fs-io.ts";
+import { INDEX_REFRESH_MS } from "../../shared/agent-transcript-protocol.ts";
+
+/** Bounds how many distinct subagents dirs stay cached at once — a server with
+ *  many sessions ever subscribed-to should not keep every one of them forever. */
+const MAX_CACHE_ENTRIES = 200;
+
+interface CacheEntry {
+  groups: Map<string, SubagentTranscriptEntry[]>;
+  byMember: Map<string, SubagentTranscriptEntry>;
+  refreshedAt: number;
+  dirMtimeMs: number | null;
+}
+
+const cache = new Map<string, CacheEntry>();
+
+function evictOldestIfOverCapacity(): void {
+  if (cache.size < MAX_CACHE_ENTRIES) return;
+  let oldestKey: string | undefined;
+  let oldestAt = Infinity;
+  for (const [key, entry] of cache) {
+    if (entry.refreshedAt < oldestAt) {
+      oldestAt = entry.refreshedAt;
+      oldestKey = key;
+    }
+  }
+  if (oldestKey !== undefined) cache.delete(oldestKey);
+}
+
+function refresh(subagentsDir: string): CacheEntry {
+  evictOldestIfOverCapacity();
+  const entry: CacheEntry = {
+    groups: groupSubagentsByCard(subagentsDir),
+    byMember: indexTranscriptsByMember(subagentsDir),
+    refreshedAt: agentTranscriptClock.now(),
+    dirMtimeMs: statDirMtimeSafe(subagentsDir),
+  };
+  cache.set(subagentsDir, entry);
+  return entry;
+}
+
+function cached(subagentsDir: string): CacheEntry {
+  const now = agentTranscriptClock.now();
+  const existing = cache.get(subagentsDir);
+  if (!existing) return refresh(subagentsDir);
+
+  const currentMtime = statDirMtimeSafe(subagentsDir);
+  const mtimeChanged = currentMtime !== null && currentMtime !== existing.dirMtimeMs;
+  if (mtimeChanged || now - existing.refreshedAt >= INDEX_REFRESH_MS) return refresh(subagentsDir);
+  return existing;
+}
+
+/** Cached `groupSubagentsByCard(subagentsDir)`, refreshed per the policy above. */
+export function getCachedSubagentGroups(subagentsDir: string): Map<string, SubagentTranscriptEntry[]> {
+  return cached(subagentsDir).groups;
+}
+
+/** Cached `indexTranscriptsByMember(subagentsDir)`, same refresh policy as the
+ *  card-group index — the activity feed's team-member pass used to re-read
+ *  every `*.meta.json` itself, uncached, on top of the group scan above. */
+export function getCachedTranscriptsByMember(subagentsDir: string): Map<string, SubagentTranscriptEntry> {
+  return cached(subagentsDir).byMember;
+}
+
+/** Test-only: forget every cached entry. */
+export function _resetAgentTranscriptIndexCache(): void {
+  cache.clear();
+}

package/src/services/agent-transcript/agent-transcript-session-hub-activity.ts

@@ -0,0 +1,103 @@
+/**
+ * Activity-subscription half of a session hub: "who is running right now",
+ * pushed every 3s while at least one client is watching. Independent of the
+ * transcript ticker — a running bar costs nothing extra when no window is
+ * open, and a window being open costs nothing extra for the bar.
+ */
+import { computeRunningAgents } from "./agent-transcript-activity.ts";
+import { agentTranscriptClock, agentTranscriptTimers } from "./agent-transcript-hub-clock.ts";
+import { sendWsMessage, type AgentTranscriptWsLike } from "./agent-transcript-ws-like.ts";
+import type { SessionHub } from "./agent-transcript-session-hub-types.ts";
+import { ACTIVITY_TICK_MS, type AgentActivityMsg } from "../../shared/agent-transcript-protocol.ts";
+
+function ensureActivityTicker(hub: SessionHub): void {
+  if (hub.activityHandle !== null) return;
+  hub.activityHandle = agentTranscriptTimers.setInterval(() => {
+    void tickActivity(hub);
+  }, ACTIVITY_TICK_MS);
+}
+
+function stopActivityTickerIfEmpty(hub: SessionHub): void {
+  if (hub.activitySubs.size > 0 || hub.activityHandle === null) return;
+  agentTranscriptTimers.clearInterval(hub.activityHandle);
+  hub.activityHandle = null;
+}
+
+export function addActivitySubscription(hub: SessionHub, ws: AgentTranscriptWsLike, subId: string): void {
+  let subIds = hub.activitySubs.get(ws);
+  if (!subIds) {
+    subIds = new Set();
+    hub.activitySubs.set(ws, subIds);
+  }
+  subIds.add(subId);
+  ensureActivityTicker(hub);
+  // Guarded the same way `tickActivity` is below: this runs un-awaited, so a
+  // throw anywhere in `computeRunningAgents` (a descendant read racing a
+  // delete, a locked rollout) would otherwise become an unhandled rejection
+  // rather than something this function can react to.
+  void (async () => {
+    try {
+      const now = agentTranscriptClock.now();
+      const running = await computeRunningAgents(hub.owned, now);
+      if (!hub.tokenStillValid(ws) || !pushActivity(ws, [subId], running)) hub.onSendFailure(ws);
+    } catch {
+      console.warn(`[agent-activity] hub=${hub.key} subId=${subId} initial compute failed`);
+    }
+  })();
+}
+
+export function removeActivitySubscription(hub: SessionHub, ws: AgentTranscriptWsLike, subId: string): boolean {
+  const subIds = hub.activitySubs.get(ws);
+  if (!subIds?.delete(subId)) return false;
+  if (subIds.size === 0) hub.activitySubs.delete(ws);
+  stopActivityTickerIfEmpty(hub);
+  return true;
+}
+
+export function dropAllActivityForWs(hub: SessionHub, ws: AgentTranscriptWsLike): number {
+  const subIds = hub.activitySubs.get(ws);
+  if (!subIds) return 0;
+  hub.activitySubs.delete(ws);
+  stopActivityTickerIfEmpty(hub);
+  return subIds.size;
+}
+
+export function activitySubIdsForWs(hub: SessionHub, ws: AgentTranscriptWsLike): string[] {
+  return [...(hub.activitySubs.get(ws)?.values() ?? [])];
+}
+
+/** Push an already-computed running list to one client's given subscriptions. */
+function pushActivity(ws: AgentTranscriptWsLike, subIds: string[], running: AgentActivityMsg["running"]): boolean {
+  for (const subId of subIds) {
+    const msg: AgentActivityMsg = { type: "agent-activity", subId, running };
+    if (!sendWsMessage(ws, msg)) return false;
+  }
+  return true;
+}
+
+/**
+ * One 3s wake: compute the running list once for the whole hub and fan it
+ * out to every subscriber — a per-session scan (Codex especially) is not
+ * cheap enough to repeat once per client watching the same session.
+ *
+ * Wrapped in its own try/catch because this is invoked as `void tickActivity(hub)`
+ * (fire-and-forget, from an un-awaited `setInterval` callback): a throw
+ * anywhere in `computeRunningAgents` — a descendant rollout that disappears
+ * or locks up between the stat and the read that bounds it — would otherwise
+ * surface as an unhandled promise rejection, counted the same way an
+ * uncaught exception is, on a 3s timer instead of the 250ms one the cursor fix covered.
+ */
+export async function tickActivity(hub: SessionHub): Promise<void> {
+  if (hub.activitySubs.size === 0) return;
+  try {
+    const now = agentTranscriptClock.now();
+    const running = await computeRunningAgents(hub.owned, now);
+    const failed: AgentTranscriptWsLike[] = [];
+    for (const [ws, subIds] of hub.activitySubs) {
+      if (!hub.tokenStillValid(ws) || !pushActivity(ws, [...subIds], running)) failed.push(ws);
+    }
+    for (const ws of failed) hub.onSendFailure(ws);
+  } catch {
+    console.warn(`[agent-activity] hub=${hub.key} tick failed`);
+  }
+}

package/src/services/agent-transcript/agent-transcript-session-hub-read.ts

@@ -0,0 +1,194 @@
+/**
+ * The read-and-push half of a transcript subscription: one tick's worth of
+ * "what's new across every file this subscription watches, including any
+ * file the set itself grew by" turned into paged WS pushes with an exact
+ * per-page cursor. Split out from `agent-transcript-session-hub.ts` (the
+ * subscribe/unsubscribe/tick-scheduling half) to keep both files within the
+ * project's file-size guideline.
+ */
+import { resolveCodexDescendantFile, resolveSources } from "./agent-transcript-sources.ts";
+import { createFileTailState } from "./agent-transcript-file-tail-state.ts";
+import { processFileTail, type ProcessFileResult } from "./agent-transcript-file-tail-feed.ts";
+import { paginateTagged, type TaggedEnvelope } from "./agent-transcript-envelope.ts";
+import type { SessionHub, TranscriptSubscription } from "./agent-transcript-session-hub-types.ts";
+import { sendWsMessage, type AgentTranscriptWsLike } from "./agent-transcript-ws-like.ts";
+import {
+  IDLE_AFTER_MS, type AgentTranscriptCursor, type AgentTranscriptEventsMsg,
+} from "../../shared/agent-transcript-protocol.ts";
+
+type FileEntry = { key: string; result: ProcessFileResult };
+
+export function buildCursor(sub: TranscriptSubscription): AgentTranscriptCursor {
+  const cursor: AgentTranscriptCursor = {};
+  for (const [key, f] of sub.files) cursor[key] = f.offset;
+  return cursor;
+}
+
+export function isIdle(sub: TranscriptSubscription, now: number): boolean {
+  if (sub.files.size === 0) return false;
+  let latestGrowth = 0;
+  for (const f of sub.files.values()) latestGrowth = Math.max(latestGrowth, f.lastGrowthAt);
+  return now - latestGrowth >= IDLE_AFTER_MS;
+}
+
+/** Re-derive every file in a subscription from byte 0, for the rare case where any one of them reset. */
+function fullResync(sub: TranscriptSubscription, now: number): FileEntry[] {
+  const entries: FileEntry[] = [];
+  for (const [key, f] of sub.files) {
+    const fresh = createFileTailState(f.ref, 0, now);
+    const result = processFileTail(fresh, now);
+    sub.files.set(key, fresh);
+    entries.push({ key, result });
+  }
+  return entries;
+}
+
+/**
+ * Bring a Claude card subscription's file set up to date with the card's
+ * current group — a grandchild whose own transcript appears after subscribe
+ * must join the stream rather than wait for the window to be reopened. Runs
+ * every tick but stays cheap: `resolveSources` caches its own result for ~2s.
+ */
+function refreshClaudeCardFiles(hub: SessionHub, sub: TranscriptSubscription, now: number): void {
+  if (hub.owned.providerId !== "claude" || sub.source.kind !== "card") return;
+  const resolved = resolveSources(hub.owned, sub.source);
+  if (!Array.isArray(resolved)) return;
+  for (const ref of resolved) {
+    if (sub.files.has(ref.key)) continue;
+    sub.files.set(ref.key, createFileTailState(ref, 0, now));
+  }
+}
+
+/**
+ * Fold newly-discovered Codex descendant threads — surfaced as `links` from
+ * this tick's own reads — into the subscription, each re-validated through
+ * the exact same fail-closed descendant chain a directly-requested card goes
+ * through (`resolveCodexDescendantFile`), never a weaker check invented for
+ * the live-discovery path.
+ */
+function addDiscoveredCodexFiles(hub: SessionHub, sub: TranscriptSubscription, entries: FileEntry[], now: number): FileEntry[] {
+  if (hub.owned.providerId !== "codex" || sub.source.kind !== "card") return [];
+  const seen = new Set<string>();
+  const added: FileEntry[] = [];
+  for (const { result } of entries) {
+    for (const threadId of result.links) {
+      if (seen.has(threadId) || sub.files.has(threadId)) continue;
+      seen.add(threadId);
+      const ref = resolveCodexDescendantFile(hub.owned, threadId);
+      if (!ref) continue;
+      const fresh = createFileTailState(ref, 0, now);
+      sub.files.set(threadId, fresh);
+      added.push({ key: threadId, result: processFileTail(fresh, now) });
+    }
+  }
+  return added;
+}
+
+function tagEntries(entries: FileEntry[]): TaggedEnvelope[] {
+  const out: TaggedEnvelope[] = [];
+  for (const { key, result } of entries) {
+    for (let i = 0; i < result.envelopes.length; i++) {
+      out.push({ envelope: result.envelopes[i]!, fileKey: key, consumedThrough: result.consumedThrough[i]! });
+    }
+  }
+  return out;
+}
+
+/**
+ * One read across every file in the subscription, plus whatever the file set
+ * itself grew by this tick (new Claude group entries, newly-linked Codex
+ * descendants). If any file reports a reset, every file is re-derived from 0
+ * — a client wiping its view on `reset: true` must not lose content from a
+ * file that did not itself change.
+ */
+function readSubscription(hub: SessionHub, sub: TranscriptSubscription, now: number): { items: TaggedEnvelope[]; reset: boolean; hasMoreBacklog: boolean } {
+  refreshClaudeCardFiles(hub, sub, now);
+
+  let entries: FileEntry[] = [...sub.files.entries()].map(([key, f]) => ({ key, result: processFileTail(f, now) }));
+  const reset = entries.some(({ result }) => result.reset);
+  if (reset) entries = fullResync(sub, now);
+
+  entries = [...entries, ...addDiscoveredCodexFiles(hub, sub, entries, now)];
+
+  const hasMoreBacklog = entries.some(({ result }) => result.hasMoreBacklog);
+  return { items: tagEntries(entries), reset, hasMoreBacklog };
+}
+
+interface PushOutcome {
+  sent: boolean;
+  /** Whether a per-tick read budget left bytes unread — the caller must keep
+   *  polling at the live cadence, even for an otherwise-idle subscription. */
+  hasMoreBacklog: boolean;
+}
+
+/**
+ * Drain and send a subscription's current backlog, paging large ones. Every
+ * page's `cursor` reflects exactly the file offsets consumed by that page's
+ * own content — not the subscription's final offset after the whole tick's
+ * read — so a client that only received page k of a multi-page push before
+ * dropping resumes at page k+1 on reconnect, never past it.
+ *
+ * `alwaysSend` covers the subscribe-time call: a client that subscribed
+ * already caught up (cursor === current size) still gets one confirming
+ * message — silence would be indistinguishable from a subscribe that never
+ * reached the hub at all. A live tick with nothing new AND nothing left to
+ * catch up on sends nothing, or every idle subscription would cost a message
+ * every 250ms/2s forever.
+ */
+function pushUpdate(hub: SessionHub, ws: AgentTranscriptWsLike, sub: TranscriptSubscription, now: number, alwaysSend: boolean): PushOutcome {
+  const preTickCursor = buildCursor(sub);
+  const { items, reset, hasMoreBacklog } = readSubscription(hub, sub, now);
+  const pages = paginateTagged(items);
+  if (pages.length === 0) {
+    if (!reset && !alwaysSend && !hasMoreBacklog) return { sent: true, hasMoreBacklog: false };
+    pages.push([]);
+  }
+  const running = !isIdle(sub, now);
+  // On reset every file is being replaced from scratch, so the cursor for
+  // this push starts empty rather than carrying over pre-tick offsets that
+  // no longer describe what a client holding them has actually been sent.
+  const runningCursor: AgentTranscriptCursor = reset ? {} : { ...preTickCursor };
+  for (let i = 0; i < pages.length; i++) {
+    for (const item of pages[i]!) runningCursor[item.fileKey] = item.consumedThrough;
+    const msg: AgentTranscriptEventsMsg = {
+      type: "agent-transcript:events",
+      subId: sub.subId,
+      events: pages[i]!.map((item) => item.envelope),
+      cursor: { ...runningCursor },
+      available: true,
+      running,
+      // Not just "another page is already queued behind this one" — also
+      // true on the LAST page when the read budget left bytes unread, so the
+      // client keeps showing "still catching up" instead of "done".
+      ...(i < pages.length - 1 || hasMoreBacklog ? { more: true as const } : {}),
+      ...(reset && i === 0 ? { reset: true as const } : {}),
+    };
+    if (!sendWsMessage(ws, msg)) return { sent: false, hasMoreBacklog };
+  }
+  return { sent: true, hasMoreBacklog };
+}
+
+export type PushResult =
+  | { outcome: "ok"; hasMoreBacklog: boolean }
+  | { outcome: "send-failed"; hasMoreBacklog: boolean }
+  | { outcome: "error"; hasMoreBacklog: false };
+
+/**
+ * `pushUpdate`, but a throw anywhere in the read/parse/send path is caught
+ * and reported as `outcome: "error"` instead of reaching the caller — a
+ * single malformed record or a raced file error must never climb out of a
+ * WS message handler or a `setInterval` tick into an uncaught exception that
+ * takes the whole server down. Distinct from `"send-failed"` (the socket
+ * itself is gone) because the caller must react very differently: a
+ * send failure means the WHOLE client is unreachable and every hub should
+ * drop it; a thrown error means only THIS subscription's own read/parse
+ * broke, and every other subscription on the same socket must keep working.
+ */
+export function safePushUpdate(hub: SessionHub, ws: AgentTranscriptWsLike, sub: TranscriptSubscription, now: number, alwaysSend: boolean): PushResult {
+  try {
+    const { sent, hasMoreBacklog } = pushUpdate(hub, ws, sub, now, alwaysSend);
+    return sent ? { outcome: "ok", hasMoreBacklog } : { outcome: "send-failed", hasMoreBacklog };
+  } catch {
+    return { outcome: "error", hasMoreBacklog: false };
+  }
+}

package/src/services/agent-transcript/agent-transcript-session-hub-types.ts

@@ -0,0 +1,81 @@
+/**
+ * Shared state for one `(providerId, sessionId)` hub: the subscriptions
+ * currently reading it, and the two lazily-started tickers (live transcript
+ * push, activity feed) that exist only while something is subscribed.
+ */
+import type { OwnedSession } from "./session-ownership.ts";
+import type { FileTailState } from "./agent-transcript-file-tail-state.ts";
+import type { AgentTranscriptWsLike } from "./agent-transcript-ws-like.ts";
+import type { AgentTranscriptSourceKind } from "../../shared/agent-transcript-protocol.ts";
+
+export interface TranscriptSubscription {
+  subId: string;
+  source: AgentTranscriptSourceKind;
+  files: Map<string, FileTailState>;
+  nextTickAt: number;
+}
+
+export interface SessionHub {
+  key: string;
+  owned: OwnedSession;
+  /** By socket, then by that socket's own `subId` — a client may hold several subscriptions. */
+  subscriptions: Map<AgentTranscriptWsLike, Map<string, TranscriptSubscription>>;
+  activitySubs: Map<AgentTranscriptWsLike, Set<string>>;
+  tickHandle: unknown | null;
+  activityHandle: unknown | null;
+  /**
+   * Owned by the top-level registry (`agent-transcript-hub.ts`), which is the
+   * only layer that knows a socket's subscriptions can span several session
+   * hubs at once. A failed push or a stale auth token must drop the client
+   * everywhere, not just in the hub that happened to detect it.
+   */
+  onSendFailure: (ws: AgentTranscriptWsLike) => void;
+  /**
+   * Owned by the top-level registry, same reason as `onSendFailure` — drop
+   * ONE subscription's bookkeeping everywhere it is tracked (this hub's own
+   * map AND the registry's per-client `subId` index), not just here. Used
+   * when a single subscription's own tick throws: the rest of that socket's
+   * subscriptions, on this hub or any other, must keep working.
+   */
+  onSubscriptionError: (ws: AgentTranscriptWsLike, subId: string) => void;
+  /** True while `ws`'s token snapshot still matches the live config. */
+  tokenStillValid: (ws: AgentTranscriptWsLike) => boolean;
+}
+
+export function createSessionHub(
+  key: string,
+  owned: OwnedSession,
+  onSendFailure: (ws: AgentTranscriptWsLike) => void,
+  onSubscriptionError: (ws: AgentTranscriptWsLike, subId: string) => void,
+  tokenStillValid: (ws: AgentTranscriptWsLike) => boolean,
+): SessionHub {
+  return {
+    key,
+    owned,
+    subscriptions: new Map(),
+    activitySubs: new Map(),
+    tickHandle: null,
+    activityHandle: null,
+    onSendFailure,
+    onSubscriptionError,
+    tokenStillValid,
+  };
+}
+
+/** Total transcript subscriptions across every client on this hub. */
+export function transcriptSubCount(hub: SessionHub): number {
+  let n = 0;
+  for (const subs of hub.subscriptions.values()) n += subs.size;
+  return n;
+}
+
+/** Total activity subscriptions across every client on this hub. */
+export function activitySubCount(hub: SessionHub): number {
+  let n = 0;
+  for (const subs of hub.activitySubs.values()) n += subs.size;
+  return n;
+}
+
+export function hubIsEmpty(hub: SessionHub): boolean {
+  return hub.subscriptions.size === 0 && hub.activitySubs.size === 0;
+}