@fitchmultz/pi-subagents 0.0.0-stage → 0.44.4

package/src/pi-intercom/reply-tracker.ts

@@ -0,0 +1,211 @@
+import type { Message, SessionInfo } from "./types.ts";
+import { formatSessionTarget, resolveSessionTarget, shortSessionId } from "./session-targets.ts";
+
+export interface IntercomContext {
+  from: SessionInfo;
+  message: Message;
+  receivedAt: number;
+}
+
+function resolveBySenderTarget(contexts: IntercomContext[], to: string): IntercomContext[] {
+  const sessions = contexts.map((context) => context.from);
+  const resolution = resolveSessionTarget(sessions, to);
+  if (resolution.status === "none" || resolution.status === "prefix_too_short") {
+    return [];
+  }
+  const matchingIds = new Set(resolution.matches.map((session) => session.id));
+  return contexts.filter((context) => matchingIds.has(context.from.id));
+}
+
+function tooShortSenderTargetMessage(contexts: IntercomContext[], to: string): string | null {
+  const resolution = resolveSessionTarget(contexts.map((context) => context.from), to);
+  if (resolution.status !== "prefix_too_short") {
+    return null;
+  }
+  const matchingIds = new Set(resolution.matches.map((session) => session.id));
+  const matches = contexts.filter((context) => matchingIds.has(context.from.id));
+  return `Pending ask target "${to}" is too short. Use one of: ${pendingSenderOptions(matches, contexts)}.`;
+}
+
+function pendingSenderOptions(contexts: IntercomContext[], allContexts: IntercomContext[] = contexts): string {
+  const allSenders = allContexts.map((context) => context.from);
+  return contexts
+    .map((context) => `${context.from.name || shortSessionId(context.from.id)}: to: ${JSON.stringify(formatSessionTarget(context.from, allSenders))} or replyTo: ${JSON.stringify(context.message.id)}`)
+    .join(", ");
+}
+
+export function isDurableSupervisorQuestion(message: Message): boolean {
+  return message.content.text.includes(`Question ID: ${message.id}`);
+}
+
+export class ReplyTracker {
+  private readonly pendingAsks = new Map<string, IntercomContext>();
+  private readonly pendingTurnContexts: IntercomContext[] = [];
+  private currentTurnContext: IntercomContext | null = null;
+  private activeAgentContext: IntercomContext | null = null;
+  private readonly askTimeoutMs: number;
+
+  constructor(askTimeoutMs = 10 * 60 * 1000) {
+    this.askTimeoutMs = askTimeoutMs;
+  }
+
+  recordIncomingMessage(from: SessionInfo, message: Message, receivedAt = Date.now()): IntercomContext {
+    const context = { from, message, receivedAt };
+    if (message.expectsReply) {
+      this.pruneExpired(receivedAt);
+      this.pendingAsks.set(message.id, context);
+    }
+    return context;
+  }
+
+  queueTurnContext(context: IntercomContext): void {
+    if (!context.message.expectsReply) return;
+    if (this.hasTurnContext(context.message.id)) return;
+    this.pendingTurnContexts.push(context);
+  }
+
+  beginTurn(now = Date.now()): void {
+    this.pruneExpired(now);
+    this.currentTurnContext = this.pendingTurnContexts.shift() ?? null;
+    if (this.currentTurnContext) {
+      this.activeAgentContext = this.currentTurnContext;
+    }
+  }
+
+  currentTurn(): IntercomContext | null {
+    return this.currentTurnContext ?? this.activeAgentContext;
+  }
+
+  endTurn(): void {
+    this.currentTurnContext = null;
+  }
+
+  endAgent(): void {
+    this.currentTurnContext = null;
+    this.activeAgentContext = null;
+  }
+
+  reset(): void {
+    this.pendingAsks.clear();
+    this.pendingTurnContexts.length = 0;
+    this.currentTurnContext = null;
+    this.activeAgentContext = null;
+  }
+
+  expireSender(sessionId: string): number {
+    const expires = (context: IntercomContext) => context.from.id === sessionId && !isDurableSupervisorQuestion(context.message);
+    let expired = 0;
+    for (const [messageId, context] of this.pendingAsks) {
+      if (expires(context)) {
+        this.pendingAsks.delete(messageId);
+        expired += 1;
+      }
+    }
+    const beforeQueued = this.pendingTurnContexts.length;
+    for (let index = this.pendingTurnContexts.length - 1; index >= 0; index -= 1) {
+      if (expires(this.pendingTurnContexts[index]!)) {
+        this.pendingTurnContexts.splice(index, 1);
+      }
+    }
+    expired += beforeQueued - this.pendingTurnContexts.length;
+    if (this.currentTurnContext && expires(this.currentTurnContext)) {
+      this.currentTurnContext = null;
+      expired += 1;
+    }
+    if (this.activeAgentContext && expires(this.activeAgentContext)) {
+      this.activeAgentContext = null;
+      expired += 1;
+    }
+    return expired;
+  }
+
+  resolveReplyTarget(options: { to?: string; replyTo?: string }, now = Date.now()): IntercomContext {
+    this.pruneExpired(now);
+
+    const pending = Array.from(this.pendingAsks.values());
+    const contexts = this.currentTurnContext
+      ? [this.currentTurnContext, ...pending.filter((context) => context.message.id !== this.currentTurnContext?.message.id)]
+      : pending;
+
+    if (options.replyTo) {
+      const target = contexts.find((context) => context.message.id === options.replyTo);
+      if (!target) {
+        throw new Error(`No pending ask with replyTo "${options.replyTo}"`);
+      }
+      if (options.to) {
+        const tooShortMessage = tooShortSenderTargetMessage(contexts, options.to);
+        if (tooShortMessage) {
+          throw new Error(tooShortMessage);
+        }
+        const senderMatches = resolveBySenderTarget(contexts, options.to);
+        if (!senderMatches.some((context) => context.message.id === target.message.id)) {
+          throw new Error(`Pending ask "${options.replyTo}" is not from "${options.to}"`);
+        }
+      }
+      return target;
+    }
+
+    if (options.to) {
+      const tooShortMessage = tooShortSenderTargetMessage(contexts, options.to);
+      if (tooShortMessage) {
+        throw new Error(tooShortMessage);
+      }
+      const matches = resolveBySenderTarget(contexts, options.to);
+      if (matches.length === 1) {
+        return matches[0]!;
+      }
+      if (matches.length > 1) {
+        throw new Error(`Multiple pending asks from \"${options.to}\" — use one of: ${pendingSenderOptions(matches, contexts)}.`);
+      }
+      throw new Error(`No pending ask from \"${options.to}\"`);
+    }
+
+    if (this.currentTurnContext) {
+      return this.currentTurnContext;
+    }
+
+    if (pending.length === 1) {
+      return pending[0]!;
+    }
+
+    if (pending.length === 0) {
+      throw new Error("No active intercom context to reply to");
+    }
+
+    throw new Error("Multiple pending asks — specify `to`");
+  }
+
+  markReplied(replyTo: string): void {
+    this.removeContext(replyTo);
+  }
+
+  get hasReplyContext(): boolean {
+    return this.pendingAsks.size > 0 || this.pendingTurnContexts.length > 0 || this.currentTurnContext !== null || this.activeAgentContext !== null;
+  }
+
+  listPending(now = Date.now()): IntercomContext[] {
+    this.pruneExpired(now);
+    return Array.from(this.pendingAsks.values()).sort((a, b) => a.receivedAt - b.receivedAt);
+  }
+
+  private hasTurnContext(messageId: string): boolean {
+    return this.pendingTurnContexts.some((context) => context.message.id === messageId)
+      || this.currentTurnContext?.message.id === messageId
+      || this.activeAgentContext?.message.id === messageId;
+  }
+
+  private removeContext(messageId: string): void {
+    this.pendingAsks.delete(messageId);
+    for (let index = this.pendingTurnContexts.length - 1; index >= 0; index -= 1) {
+      if (this.pendingTurnContexts[index]?.message.id === messageId) this.pendingTurnContexts.splice(index, 1);
+    }
+    if (this.currentTurnContext?.message.id === messageId) this.currentTurnContext = null;
+    if (this.activeAgentContext?.message.id === messageId) this.activeAgentContext = null;
+  }
+
+  private pruneExpired(now: number): void {
+    for (const [messageId, context] of this.pendingAsks) {
+      if (!isDurableSupervisorQuestion(context.message) && now - context.receivedAt > this.askTimeoutMs) this.removeContext(messageId);
+    }
+  }
+}

package/src/pi-intercom/session-targets.ts

@@ -0,0 +1,172 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+export interface TargetIdentity {
+  id: string;
+  name?: string;
+}
+
+export interface ProjectSessionIdentity extends TargetIdentity {
+  cwd: string;
+  projectId?: string;
+}
+
+export const MIN_SESSION_TARGET_PREFIX_LENGTH = 8;
+
+export interface TargetResolution<T extends TargetIdentity> {
+  status: "none" | "found" | "ambiguous" | "prefix_too_short";
+  target?: T;
+  matches: T[];
+  minLength?: number;
+}
+
+export function shortSessionId(sessionId: string): string {
+  return sessionId.slice(0, MIN_SESSION_TARGET_PREFIX_LENGTH);
+}
+
+function normalizedPath(value: string): string {
+  return path.resolve(value);
+}
+
+function resolveGitCommonDirectory(cwd: string): Promise<string | undefined> {
+  const env = { ...process.env };
+  delete env.GIT_DIR;
+  delete env.GIT_COMMON_DIR;
+  delete env.GIT_WORK_TREE;
+  return new Promise((resolve) => {
+    execFile("git", ["-C", cwd, "rev-parse", "--path-format=absolute", "--git-common-dir"], {
+      cwd: path.dirname(process.execPath),
+      encoding: "utf8",
+      env,
+      maxBuffer: 4096,
+      timeout: 500,
+    }, (error, stdout) => {
+      const gitDirectory = error ? "" : stdout.trim();
+      resolve(gitDirectory && !/[\0\r\n]/.test(gitDirectory)
+        ? normalizedPath(path.resolve(cwd, gitDirectory))
+        : undefined);
+    });
+  });
+}
+
+export async function resolveSessionProjectId(cwd: string): Promise<string> {
+  const gitDirectory = await resolveGitCommonDirectory(cwd);
+  const identity = gitDirectory ? `git:${gitDirectory}` : `cwd:${normalizedPath(cwd)}`;
+  return createHash("sha256").update(identity).digest("hex");
+}
+
+function normalizedNames(sessions: TargetIdentity[]): Set<string> {
+  return new Set(sessions
+    .map((session) => session.name?.trim().toLowerCase())
+    .filter((name): name is string => Boolean(name)));
+}
+
+export function formatSessionTarget(session: TargetIdentity, allSessions: TargetIdentity[] = [session]): string {
+  const ids = allSessions.map((candidate) => candidate.id.toLowerCase());
+  const names = normalizedNames(allSessions);
+  const id = session.id.toLowerCase();
+
+  for (let length = MIN_SESSION_TARGET_PREFIX_LENGTH; length < session.id.length; length += 1) {
+    const prefix = id.slice(0, length);
+    const uniqueIdPrefix = ids.filter((candidateId) => candidateId.startsWith(prefix)).length === 1;
+    if (uniqueIdPrefix && !names.has(prefix)) {
+      return session.id.slice(0, length);
+    }
+  }
+
+  return session.id;
+}
+
+export function formatTargetOptions(sessions: TargetIdentity[], allSessions: TargetIdentity[] = sessions): string {
+  return sessions
+    .map((session) => `${session.name || shortSessionId(session.id)} → ${formatSessionTarget(session, allSessions)}`)
+    .join(", ");
+}
+
+export function targetDisplayName(session: TargetIdentity, allSessions: TargetIdentity[] = [session]): string {
+  if (!session.name?.trim()) {
+    return session.id;
+  }
+
+  const lowerName = session.name.trim().toLowerCase();
+  const duplicateName = allSessions.some((candidate) =>
+    candidate.id !== session.id && candidate.name?.trim().toLowerCase() === lowerName
+  );
+  const nameConflictsWithOtherIdPrefix = allSessions.some((candidate) =>
+    candidate.id !== session.id && candidate.id.toLowerCase().startsWith(lowerName)
+  );
+
+  return duplicateName || nameConflictsWithOtherIdPrefix
+    ? `${session.name} (${formatSessionTarget(session, allSessions)})`
+    : session.name;
+}
+
+// The hint is deliberately a constant: it is appended to the system prompt,
+// which is the very start of the provider prompt-cache prefix. Any per-turn
+// variation there (live peer counts, checkout counts) invalidates the entire
+// cached context for every turn in which fleet membership changed, which is
+// expensive on large sessions. Live details belong behind intercom list.
+export const PEER_AWARENESS_HINT = `Other Pi sessions may be connected to this project. Use load_intercom({}) if needed, then intercom({ action: "list" }) before changing shared state or coordinating known overlapping work. Routine standalone read-only tasks do not need a peer check. Coordinate only when work overlaps; use subagent controls for managed child runs.`;
+
+export function filterProjectSessions<T extends ProjectSessionIdentity>(sessions: T[], currentSessionId: string): T[] {
+  const current = sessions.find((session) => session.id === currentSessionId);
+  if (!current) return [];
+
+  return sessions.filter((session) =>
+    session.id === currentSessionId
+    || session.cwd === current.cwd
+    || Boolean(current.projectId && session.projectId && session.projectId === current.projectId)
+  );
+}
+
+export function formatPeerAwarenessHint<T extends ProjectSessionIdentity>(sessions: T[], currentSessionId: string): string | undefined {
+  return filterProjectSessions(sessions, currentSessionId).some((session) => session.id !== currentSessionId)
+    ? PEER_AWARENESS_HINT
+    : undefined;
+}
+
+export function resolveSessionTarget<T extends TargetIdentity>(sessions: T[], rawTarget: string): TargetResolution<T> {
+  const target = rawTarget.trim();
+  const lowerTarget = target.toLowerCase();
+
+  const exactIdMatches = sessions.filter((session) => session.id.toLowerCase() === lowerTarget);
+  if (exactIdMatches.length === 1) {
+    return { status: "found", target: exactIdMatches[0], matches: exactIdMatches };
+  }
+  if (exactIdMatches.length > 1) {
+    return { status: "ambiguous", matches: exactIdMatches };
+  }
+
+  const nameMatches = sessions.filter((session) => session.name?.trim().toLowerCase() === lowerTarget);
+  const allPrefixMatches = sessions.filter((session) => session.id.toLowerCase().startsWith(lowerTarget));
+  const prefixMatches = target.length >= MIN_SESSION_TARGET_PREFIX_LENGTH ? allPrefixMatches : [];
+  if (target.length > 0 && target.length < MIN_SESSION_TARGET_PREFIX_LENGTH && allPrefixMatches.length > 0) {
+    if (nameMatches.length > 0) {
+      const matchesById = new Map<string, T>();
+      for (const session of [...nameMatches, ...allPrefixMatches]) {
+        matchesById.set(session.id, session);
+      }
+      const matches = Array.from(matchesById.values());
+      if (matches.length === 1) {
+        return { status: "found", target: matches[0], matches };
+      }
+      return { status: "ambiguous", matches };
+    }
+    return { status: "prefix_too_short", matches: allPrefixMatches, minLength: MIN_SESSION_TARGET_PREFIX_LENGTH };
+  }
+
+  const matchesById = new Map<string, T>();
+  for (const session of [...nameMatches, ...prefixMatches]) {
+    matchesById.set(session.id, session);
+  }
+  const matches = Array.from(matchesById.values());
+
+  if (matches.length === 1) {
+    return { status: "found", target: matches[0], matches };
+  }
+  if (matches.length > 1) {
+    return { status: "ambiguous", matches };
+  }
+  return { status: "none", matches: [] };
+}

package/src/pi-intercom/subagent-live-events.ts

@@ -0,0 +1,133 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { IntercomClient } from "./broker/client.ts";
+import type { SubagentIntercomConnection } from "../shared/types.ts";
+import { formatSessionTarget, resolveSessionTarget as resolveSessionTargetValue } from "./session-targets.ts";
+import { isAttachment, isHumanMessageOrigin, type Attachment, type HumanMessageOrigin } from "./types.ts";
+
+const SUBAGENT_LIVE_INTERCOM_EVENT = "subagent:live-intercom";
+const SUBAGENT_LIVE_INTERCOM_DELIVERY_EVENT = "subagent:live-intercom-delivery";
+const SUBAGENT_INTERCOM_HEALTH_REQUEST_EVENT = "subagent:intercom-health-request";
+const SUBAGENT_INTERCOM_HEALTH_RESPONSE_EVENT = "subagent:intercom-health-response";
+
+type PiEvents = ExtensionAPI["events"];
+
+type LiveEventDeps = {
+  events: PiEvents;
+  ensureConnected: () => Promise<IntercomClient>;
+  getConnection: () => { client: IntercomClient | null; connecting: boolean; started: boolean };
+  resolveSessionTarget: (client: IntercomClient, target: string) => Promise<string | null | undefined>;
+  currentSessionTargetMatches: (requestedTarget: string, resolvedTarget?: string, client?: IntercomClient) => boolean;
+  getLivenessCheck: () => () => boolean;
+};
+
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function emitLiveDelivery(events: PiEvents, requestId: string | undefined, delivered: boolean, reason?: string, receipt?: { id: string; accepted: boolean; queued?: boolean }): void {
+  if (!requestId) return;
+  events.emit(SUBAGENT_LIVE_INTERCOM_DELIVERY_EVENT, {
+    requestId,
+    delivered,
+    ...(receipt ? { messageId: receipt.id, accepted: receipt.accepted, queued: receipt.queued } : {}),
+    ...(reason ? { reason } : {}),
+  });
+}
+
+function parseLiveMessagePayload(payload: unknown): { requestId: string; to: string; message: string; delivery: "queue" | "steer"; messageId?: string; human?: HumanMessageOrigin; attachments?: Attachment[] } | undefined {
+  if (!payload || typeof payload !== "object") return undefined;
+  const parsed = payload as { requestId?: unknown; to?: unknown; message?: unknown; delivery?: unknown; messageId?: unknown; human?: unknown; attachments?: unknown };
+  if (typeof parsed.requestId !== "string" || typeof parsed.to !== "string" || typeof parsed.message !== "string") return undefined;
+  return {
+    requestId: parsed.requestId,
+    to: parsed.to,
+    message: parsed.message,
+    delivery: parsed.delivery === "queue" ? "queue" : "steer",
+    ...(typeof parsed.messageId === "string" ? { messageId: parsed.messageId } : {}),
+    ...(isHumanMessageOrigin(parsed.human) ? { human: parsed.human } : {}),
+    ...(Array.isArray(parsed.attachments) && parsed.attachments.every(isAttachment) ? { attachments: parsed.attachments } : {}),
+  };
+}
+
+async function relayLiveSubagentMessage(payload: unknown, deps: LiveEventDeps): Promise<void> {
+  const parsed = parseLiveMessagePayload(payload);
+  if (!parsed) return;
+  const isLive = deps.getLivenessCheck();
+    if (!isLive()) return;
+    let activeClient: IntercomClient;
+    let target: string;
+    try {
+      activeClient = await deps.ensureConnected();
+      target = await deps.resolveSessionTarget(activeClient, parsed.to) ?? parsed.to;
+    } catch (error) {
+      if (isLive()) emitLiveDelivery(deps.events, parsed.requestId, false, getErrorMessage(error));
+      return;
+    }
+    if (!isLive()) return;
+    if (deps.currentSessionTargetMatches(parsed.to, target, activeClient)) {
+      emitLiveDelivery(deps.events, parsed.requestId, false, "Cannot message the current session");
+      return;
+    }
+    try {
+      const result = await activeClient.send(target, { text: parsed.message, delivery: parsed.delivery, messageId: parsed.messageId, human: parsed.human, attachments: parsed.attachments });
+      if (isLive()) emitLiveDelivery(deps.events, parsed.requestId, result.delivered, result.reason, result);
+    } catch (error) {
+      if (isLive()) emitLiveDelivery(deps.events, parsed.requestId, false, getErrorMessage(error));
+    }
+}
+
+function parseHealthPayload(payload: unknown): { requestId: string; targets: string[] } | undefined {
+  if (!payload || typeof payload !== "object") return undefined;
+  const parsed = payload as { requestId?: unknown; targets?: unknown };
+  if (typeof parsed.requestId !== "string" || !Array.isArray(parsed.targets)) return undefined;
+  const targets = parsed.targets.filter((target): target is string => typeof target === "string" && target.trim().length > 0);
+  return { requestId: parsed.requestId, targets };
+}
+
+async function answerLiveIntercomHealth(payload: unknown, deps: LiveEventDeps): Promise<void> {
+  const parsed = parseHealthPayload(payload);
+  if (!parsed) return;
+  const isLive = deps.getLivenessCheck();
+  const connectionSnapshot = (): SubagentIntercomConnection => {
+    const { client, connecting, started } = deps.getConnection();
+    return { status: !started ? "unknown" : connecting ? "connecting" : client?.isConnected() ? "unknown" : "disconnected", ...(client?.sessionId ? { sessionId: client.sessionId } : {}) };
+  };
+  const respond = (health: unknown[], connection: SubagentIntercomConnection) => {
+    if (isLive()) deps.events.emit(SUBAGENT_INTERCOM_HEALTH_RESPONSE_EVENT, { requestId: parsed.requestId, health, connection });
+  };
+    if (!isLive()) return;
+    try {
+      // An empty target list is a read-only check of this bridge, not a reconnect request.
+      const activeClient = parsed.targets.length ? await deps.ensureConnected() : deps.getConnection().client;
+      if (!activeClient?.isConnected()) { respond([], connectionSnapshot()); return; }
+      const sessions = await activeClient.listSessions();
+      const health = parsed.targets.map((target) => {
+        const resolution = resolveSessionTargetValue(sessions, target);
+        if (resolution.status !== "found") return { target, status: resolution.status };
+        const session = resolution.target!;
+        return {
+          target,
+          status: "registered" as const,
+          resolvedTarget: formatSessionTarget(session, sessions),
+          sessionId: session.id,
+          ...(session.name ? { sessionName: session.name } : {}),
+          ...(session.status ? { sessionStatus: session.status } : {}),
+          ...(session.acceptsAsks !== undefined ? { acceptsAsks: session.acceptsAsks } : {}),
+          ...(session.pendingAsks !== undefined ? { pendingAsks: session.pendingAsks } : {}),
+          ...(session.lastSeen !== undefined ? { lastSeen: session.lastSeen } : {}),
+          ...(session.lastIntercomActivity !== undefined ? { lastIntercomActivity: session.lastIntercomActivity } : {}),
+        };
+      });
+      const registered = activeClient.isConnected() && sessions.some((session) => session.id === activeClient.sessionId);
+      respond(health, registered ? { status: "connected", sessionId: activeClient.sessionId! } : { ...connectionSnapshot(), reason: "Current broker registration was not confirmed." });
+    } catch (error) {
+      respond(parsed.targets.map((target) => ({ target, status: "missing" })), { ...connectionSnapshot(), reason: getErrorMessage(error) });
+    }
+}
+
+export function registerSubagentLiveEventHandlers(deps: LiveEventDeps): Array<() => void> {
+  return [
+    deps.events.on(SUBAGENT_LIVE_INTERCOM_EVENT, (payload) => relayLiveSubagentMessage(payload, deps)),
+    deps.events.on(SUBAGENT_INTERCOM_HEALTH_REQUEST_EVENT, (payload) => answerLiveIntercomHealth(payload, deps)),
+  ];
+}

package/src/pi-intercom/topics.ts

@@ -0,0 +1,125 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Container, ScrollView, Text, matchesKey } from "@earendil-works/pi-tui";
+import { actionHints } from "../tui/action-hints.ts";
+import { isTopicSubscription, isTopicUpdate, type Message, type SessionInfo, type TopicSubscription, type TopicUpdate } from "./types.ts";
+
+interface TopicRecord { from: Pick<SessionInfo, "id" | "name">; update: TopicUpdate; connected: boolean; notifiedRevision?: number }
+const TOPIC_ENTRY = "intercom-topic";
+
+/** Latest inspectable state plus native audit entries; routine updates never enter model context. */
+export class IntercomTopics {
+	private pi: ExtensionAPI;
+	private getContext: () => ExtensionContext | null;
+	private records = new Map<string, TopicRecord>();
+	private disconnectedOwners = new Set<string>();
+	private render?: () => void;
+	private hydrate = new Set<string>();
+	readonly subscriptions = new Map<string, TopicSubscription>();
+	readonly published = new Map<string, TopicUpdate>();
+	constructor(pi: ExtensionAPI, getContext: () => ExtensionContext | null) { this.pi = pi; this.getContext = getContext; }
+
+	private save(data: object): void {
+		const ctx = this.getContext();
+		if (ctx) this.pi.appendEntry(TOPIC_ENTRY, { sessionId: ctx.sessionManager.getSessionId(), ...data });
+	}
+	start(ctx: ExtensionContext): void {
+		this.render = undefined;
+		this.records.clear(); this.disconnectedOwners.clear(); this.hydrate.clear(); this.subscriptions.clear(); this.published.clear();
+		for (const entry of ctx.sessionManager.getEntries()) {
+			if (entry.type !== "custom" || entry.customType !== TOPIC_ENTRY) continue;
+			const data = entry.data as { sessionId?: string; subscriptions?: TopicSubscription[]; published?: TopicUpdate; record?: TopicRecord };
+			if (data?.sessionId !== ctx.sessionManager.getSessionId()) continue;
+			if (Array.isArray(data.subscriptions) && data.subscriptions.every(isTopicSubscription)) {
+				this.subscriptions.clear(); for (const subscription of data.subscriptions) this.subscriptions.set(subscription.topic, subscription);
+			}
+			if (isTopicUpdate(data.published)) this.published.set(data.published.topic, data.published);
+			if (data.record && isTopicUpdate(data.record.update)) this.records.set(`${data.record.from.id}:${data.record.update.topic}`, { ...data.record, connected: false });
+		}
+		for (const topic of this.subscriptions.keys()) this.hydrate.add(topic);
+	}
+	subscribe(topic: string, awaitRelease?: boolean): void {
+		this.subscriptions.set(topic, { topic, ...(awaitRelease ? { awaitRelease } : {}) });
+		this.hydrate.add(topic);
+		this.save({ subscriptions: [...this.subscriptions.values()] });
+	}
+	unsubscribe(topic: string): void { this.subscriptions.delete(topic); this.save({ subscriptions: [...this.subscriptions.values()] }); }
+	publish(update: TopicUpdate, from: Pick<SessionInfo, "id" | "name">): void { this.published.set(update.topic, update); this.save({ published: update }); this.record(from, update); }
+	presence(): Required<Pick<SessionInfo, "subscriptions" | "topics">> { return { subscriptions: [...this.subscriptions.values()], topics: [...this.published.values()] }; }
+	private record(from: Pick<SessionInfo, "id" | "name">, update: TopicUpdate, connected = true): boolean {
+		const key = `${from.id}:${update.topic}`, previous = this.records.get(key);
+		if (previous && previous.update.revision >= update.revision) return false;
+		const record = { from: { id: from.id, name: from.name }, update, connected: connected && !this.disconnectedOwners.has(from.id), notifiedRevision: previous?.notifiedRevision };
+		this.records.set(key, record); this.save({ record }); this.render?.();
+		return true;
+	}
+	/** True means handled as quiet state (or unsubscribed/obsolete), not a conversation message. */
+	receive(from: SessionInfo, message: Message): boolean {
+		const update = message.topic;
+		if (!update) return false;
+		const subscription = this.subscriptions.get(update.topic);
+		if (!subscription) return true;
+		const key = `${from.id}:${update.topic}`;
+		if ((this.records.get(key)?.update.revision ?? 0) > update.revision) return true;
+		this.record(from, update);
+		if (update.event === "update" || update.event === "release" && !subscription.awaitRelease) return true;
+		const record = this.records.get(key)!;
+		if ((record.notifiedRevision ?? 0) >= update.revision) return true;
+		record.notifiedRevision = update.revision;
+		this.save({ record });
+		return false;
+	}
+	refresh(sessions: SessionInfo[]): void {
+		for (const session of sessions) this.disconnectedOwners.delete(session.id);
+		for (const record of this.records.values()) record.connected = sessions.some((session) => session.id === record.from.id);
+		for (const session of sessions) for (const update of session.topics ?? []) {
+			if (this.subscriptions.has(update.topic)) {
+				this.record(session, update);
+				const record = this.records.get(`${session.id}:${update.topic}`)!;
+				if (this.hydrate.has(update.topic) && (record.notifiedRevision ?? 0) < update.revision) {
+					record.notifiedRevision = update.revision; this.save({ record });
+				}
+			}
+		}
+		this.hydrate.clear();
+	}
+	disconnected(id?: string): void {
+		if (id) this.disconnectedOwners.add(id);
+		for (const record of this.records.values()) if (!id || record.from.id === id) { record.connected = false; this.disconnectedOwners.add(record.from.id); }
+		this.render?.();
+	}
+	inspect(topic?: string): string {
+		const subscriptions = [...this.subscriptions.values()].filter((item) => !topic || item.topic === topic);
+		const records = [...this.records.values()].filter((record) => !topic || record.update.topic === topic).sort((a, b) => b.update.updatedAt - a.update.updatedAt);
+		return ["Intercom topics · latest self-contained state (not a work queue or exclusive lock)",
+			`Subscriptions: ${subscriptions.map((item) => `${item.topic}${item.awaitRelease ? " (awaiting release)" : ""}`).join(", ") || "none"}`,
+			...records.map(({ from, update, connected }) => `\n${update.topic} · ${from.name ?? from.id} · ${connected ? "connected" : "disconnected / unavailable"}\n${update.resource ? `Resource: ${update.resource} · declared ${update.ownership ?? "state unknown"}${!connected && update.ownership !== "released" ? "; disconnect is not release" : ""}\n` : ""}${new Date(update.updatedAt).toISOString()} · ${update.event}\n${update.text}`),
+			...(!records.length ? ["No current records. Subscribe to an exact topic or publish a self-contained update."] : []),
+		].join("\n");
+	}
+	async open(ctx: ExtensionContext, notice?: string): Promise<void> {
+		await ctx.ui.custom((tui, _theme, _keys, done) => {
+			const text = new Text("", 0, 0);
+			const scroll = new ScrollView(text, { follow: "none", scrollbar: "hidden" });
+			const render = () => tui.requestRender();
+			this.render = render;
+			let closed = false;
+			const act = (delta?: number) => { if (closed) return; if (delta === undefined) done(undefined); else scroll.scrollBy(delta); tui.requestRender(); };
+			const view = new Container();
+			view.addChild({
+				invalidate() { scroll.invalidate(); },
+				render: (width) => { text.setText([notice, this.inspect()].filter(Boolean).join("\n\n")); const lines = scroll.render(width); const height = Math.max(1, tui.terminal.rows - 2); scroll.updateLayout(lines.length, height, render); return lines.slice(scroll.scrollTop, scroll.scrollTop + height); },
+			});
+			view.addChild(actionHints([
+				{ text: "↑", run: () => act(-1) }, "/", { text: "↓", run: () => act(1) }, " ", { text: "PgUp", run: () => act(-scroll.viewportHeight) }, "/",
+				{ text: "PgDn Read", run: () => act(scroll.viewportHeight) }, " · ", { text: "Esc Back", run: () => act() },
+			], undefined, "..."));
+			return {
+				invalidate() { view.invalidate(); },
+				dispose: () => { closed = true; if (this.render === render) this.render = undefined; },
+				render: (width) => view.render(width),
+				handleInput(data) { act(matchesKey(data, "escape") ? undefined : matchesKey(data, "pageUp") ? -scroll.viewportHeight : matchesKey(data, "pageDown") ? scroll.viewportHeight : matchesKey(data, "up") ? -1 : matchesKey(data, "down") ? 1 : 0); },
+				handleMouse(event) { if (event.type === "wheel") { act(event.wheelDelta ?? 0); return { handled: true }; } return view.handleMouse(event); },
+			};
+		}, { overlay: true, overlayOptions: { width: "100%", maxHeight: "100%", anchor: "top-left" } });
+	}
+}