@tryinget/pi-activity-strip 0.4.0 → 0.5.0

package/src/common/protocol.mjs

@@ -5,6 +5,7 @@
 // ---
 
 import { randomUUID } from "node:crypto";
+import { canonicalGhosttyTerminalKey, normalizeGhosttySurfaceId } from "./terminal-identity.mjs";
 
 /** @typedef {import("./contracts.ts").SessionState} SessionState */
 /** @typedef {import("./contracts.ts").SessionSnapshot} SessionSnapshot */
@@ -12,6 +13,21 @@ import { randomUUID } from "node:crypto";
 /** @type {Set<SessionState>} */
 const SESSION_STATES = new Set(["idle", "thinking", "tool", "waiting", "success", "error"]);
 
+const MAX_CLOCK_SKEW_MS = 60_000;
+
+/** @param {unknown} value @param {number} maxLength */
+function boundedString(value, maxLength) {
+  return String(value ?? "").slice(0, maxLength);
+}
+
+/** @param {unknown} value @param {number} fallback @param {number} now */
+function finiteTimestamp(value, fallback, now) {
+  const timestamp = Number(value);
+  return Number.isFinite(timestamp) && timestamp >= 0 && timestamp <= now + MAX_CLOCK_SKEW_MS
+    ? timestamp
+    : fallback;
+}
+
 /** @param {string} type @param {Record<string, unknown>} [payload] */
 export function makeMessage(type, payload = {}) {
   return {
@@ -23,30 +39,46 @@ export function makeMessage(type, payload = {}) {
 
 /** @param {Partial<SessionSnapshot> | Record<string, unknown>} [session] @returns {SessionSnapshot} */
 export function normalizeSessionSnapshot(session = {}) {
+  if (!session || typeof session !== "object") session = {};
   const now = Date.now();
-  const updatedAt = Number(session.updatedAt ?? now) || now;
-  const lastEventAt = Number(session.lastEventAt ?? updatedAt) || updatedAt;
-  const startedAt = Number(session.startedAt ?? updatedAt) || updatedAt;
+  const updatedAt = finiteTimestamp(session.updatedAt, now, now);
+  const lastEventAt = finiteTimestamp(session.lastEventAt, updatedAt, now);
+  const startedAt = finiteTimestamp(session.startedAt, updatedAt, now);
+  const normalizedAgentStartedAt = finiteTimestamp(session.agentStartedAt, 0, now);
   const agentStartedAt =
-    session.agentStartedAt == null ? null : Number(session.agentStartedAt) || null;
+    session.agentStartedAt == null || !normalizedAgentStartedAt ? null : normalizedAgentStartedAt;
   const rawState = typeof session.state === "string" ? session.state : "idle";
   /** @type {SessionState} */
   const state = SESSION_STATES.has(/** @type {SessionState} */ (rawState))
     ? /** @type {SessionState} */ (rawState)
     : "idle";
 
+  const terminalKey = canonicalGhosttyTerminalKey(session);
+  const terminalKind = terminalKey ? "ghostty-surface" : "unbound";
+  const terminalFamily = terminalKey ? String(session.terminalFamily) : "";
+  const terminalSurfaceId = terminalKey ? normalizeGhosttySurfaceId(session.terminalSurfaceId) : "";
+  const rawPublisherSequence = Number(session.publisherSequence ?? 0);
+  const publisherSequence =
+    Number.isSafeInteger(rawPublisherSequence) && rawPublisherSequence >= 0
+      ? rawPublisherSequence
+      : 0;
   return {
-    sessionId: String(session.sessionId ?? ""),
-    publisherId: String(session.publisherId ?? ""),
+    sessionId: boundedString(session.sessionId, 256),
+    publisherId: boundedString(session.publisherId, 256),
+    publisherSequence,
     processId: Number(session.processId ?? 0) || 0,
-    cwd: String(session.cwd ?? ""),
-    repoLabel: String(session.repoLabel ?? "pi session"),
-    sessionName: String(session.sessionName ?? ""),
-    phase: String(session.phase ?? "Idle"),
-    detail: String(session.detail ?? "Ready"),
-    assistantPreview: String(session.assistantPreview ?? ""),
-    toolName: String(session.toolName ?? ""),
-    toolTarget: String(session.toolTarget ?? ""),
+    terminalKind,
+    terminalKey,
+    terminalFamily,
+    terminalSurfaceId,
+    cwd: boundedString(session.cwd, 4096),
+    repoLabel: boundedString(session.repoLabel ?? "pi session", 256),
+    sessionName: boundedString(session.sessionName, 256),
+    phase: boundedString(session.phase ?? "Idle", 512),
+    detail: boundedString(session.detail ?? "Ready", 2048),
+    assistantPreview: boundedString(session.assistantPreview, 2048),
+    toolName: boundedString(session.toolName, 256),
+    toolTarget: boundedString(session.toolTarget, 2048),
     state,
     turnIndex: Number(session.turnIndex ?? 0) || 0,
     updatedAt,
@@ -54,8 +86,8 @@ export function normalizeSessionSnapshot(session = {}) {
     startedAt,
     agentStartedAt,
     agentActive: Boolean(session.agentActive),
-    lastPromptPreview: String(session.lastPromptPreview ?? ""),
-    errorMessage: String(session.errorMessage ?? ""),
+    lastPromptPreview: boundedString(session.lastPromptPreview, 2048),
+    errorMessage: boundedString(session.errorMessage, 2048),
   };
 }
 

package/src/common/session-cards.mjs

@@ -0,0 +1,102 @@
+// ---
+// summary: "projects publisher snapshots into stable operator-facing terminal cards"
+// read_when:
+//   - "changing publisher aggregation, card identity, or membership comparison"
+// ---
+
+import { isActiveSession } from "./activity-order.mjs";
+import { canonicalGhosttyTerminalKey } from "./terminal-identity.mjs";
+
+/** @typedef {import("./contracts.ts").SessionSnapshot} SessionSnapshot */
+/** @typedef {Partial<SessionSnapshot> & Record<string, unknown>} SessionLike */
+
+/** @param {SessionLike} session */
+export function sessionRecordKey(session) {
+  const sessionId = String(session?.sessionId ?? "");
+  const publisherId = String(session?.publisherId ?? "");
+  return publisherId ? `${sessionId}|${publisherId}` : sessionId;
+}
+
+/** @param {SessionLike} session */
+export function sessionCardId(session) {
+  const terminalKey = canonicalGhosttyTerminalKey(session);
+  if (terminalKey) return `terminal:${terminalKey}`;
+  const sessionId = String(session?.sessionId ?? "").trim();
+  return sessionId ? `session:${sessionId}` : "";
+}
+
+/** @param {SessionLike} session */
+export function sessionMembershipKey(session) {
+  return `${sessionRecordKey(session)}→${sessionCardId(session)}`;
+}
+
+/** @param {SessionLike} session */
+function attentionRank(session) {
+  if (isActiveSession(session)) return 3;
+  if (session?.state === "error") return 2;
+  if (session?.state === "success") return 1;
+  return 0;
+}
+
+/** @param {SessionLike} left @param {SessionLike} right */
+export function comparePublisherRepresentatives(left, right) {
+  const rankDelta = attentionRank(right) - attentionRank(left);
+  if (rankDelta) return rankDelta;
+  const eventDelta = Number(right?.lastEventAt ?? 0) - Number(left?.lastEventAt ?? 0);
+  if (eventDelta) return eventDelta;
+  const turnDelta = Number(right?.turnIndex ?? 0) - Number(left?.turnIndex ?? 0);
+  if (turnDelta) return turnDelta;
+  const startDelta = Number(right?.startedAt ?? 0) - Number(left?.startedAt ?? 0);
+  if (startDelta) return startDelta;
+  return sessionRecordKey(left).localeCompare(sessionRecordKey(right));
+}
+
+/**
+ * @param {SessionLike[]} [sessions]
+ * @param {Set<string> | null} [allowedCardIds]
+ * @returns {Array<SessionLike & {cardId: string; publisherCount: number; publisherIds: string[]; publisherRecordKeys: string[]}>}
+ */
+export function projectSessionCards(sessions = [], allowedCardIds = null) {
+  /** @type {Map<string, SessionLike[]>} */
+  const groups = new Map();
+  for (const session of sessions) {
+    const cardId = sessionCardId(session);
+    if (!cardId || (allowedCardIds && !allowedCardIds.has(cardId))) continue;
+    const group = groups.get(cardId) ?? [];
+    group.push(session);
+    groups.set(cardId, group);
+  }
+
+  /** @type {Array<SessionLike & {cardId: string; publisherCount: number; publisherIds: string[]; publisherRecordKeys: string[]}>} */
+  const cards = [];
+  for (const [cardId, group] of groups) {
+    const ordered = [...group].sort(comparePublisherRepresentatives);
+    const representative = ordered[0];
+    if (!representative) continue;
+    cards.push({
+      ...representative,
+      cardId,
+      publisherCount: group.length,
+      publisherIds: group.map((session) => String(session.publisherId ?? "")).filter(Boolean),
+      publisherRecordKeys: group.map(sessionRecordKey),
+    });
+  }
+  return cards;
+}
+
+/** @param {SessionLike[]} [left] @param {SessionLike[]} [right] */
+export function haveSameRecordMembership(left = [], right = []) {
+  if (left.length !== right.length) return false;
+  const leftKeys = left.map(sessionMembershipKey).sort();
+  const rightKeys = right.map(sessionMembershipKey).sort();
+  return leftKeys.every((key, index) => key === rightKeys[index]);
+}
+
+/** @param {SessionLike[]} [left] @param {SessionLike[]} [right] */
+export function haveSameCardMembership(left = [], right = []) {
+  const leftKeys = [...new Set(left.map(sessionCardId).filter(Boolean))].sort();
+  const rightKeys = [...new Set(right.map(sessionCardId).filter(Boolean))].sort();
+  return (
+    leftKeys.length === rightKeys.length && leftKeys.every((key, index) => key === rightKeys[index])
+  );
+}

package/src/common/status-report.mjs

@@ -14,6 +14,7 @@ export function formatBrokerRuntimeStatus(result) {
 
   const lines = [
     runtime.state === "ready" ? "running (ready)" : `running (${runtime.state})`,
+    `backend: ${runtime.backend || "unknown"}`,
     `display: ${runtime.displayServer || "unknown"}`,
     `window manager: ${runtime.windowManager || "unknown"}`,
     `alignment: ${runtime.alignmentMode || "unknown"}`,
@@ -23,7 +24,7 @@ export function formatBrokerRuntimeStatus(result) {
     lines.push(`displays: ${runtime.displayCount}`);
   }
   if (typeof runtime.windowVisible === "boolean") {
-    lines.push(`window visible: ${runtime.windowVisible ? "yes" : "no"}`);
+    lines.push(`surface visible: ${runtime.windowVisible ? "yes" : "no"}`);
   }
   if (runtime.error) {
     lines.push(`error: ${runtime.error}`);

package/src/common/telemetry.mjs

@@ -67,18 +67,25 @@ export function createSessionId() {
   return `${os.hostname()}-${process.pid}-${Date.now()}-${randomUUID().slice(0, 6)}`;
 }
 
-/** @param {{ cwd?: string; sessionName?: string; sessionId?: string; publisherId?: string }} [options] @returns {SessionSnapshot} */
+/** @param {{ cwd?: string; sessionName?: string; sessionId?: string; publisherId?: string; terminalIdentity?: {terminalKind?: string; terminalKey?: string; terminalFamily?: string; terminalSurfaceId?: string} }} [options] @returns {SessionSnapshot} */
 export function createInitialSnapshot({
   cwd = process.cwd(),
   sessionName = "",
   sessionId = "",
   publisherId = "",
+  terminalIdentity = {},
 } = {}) {
   const now = Date.now();
   return {
     sessionId: sessionId.trim() || createSessionId(),
     publisherId: publisherId.trim() || randomUUID(),
+    publisherSequence: 0,
     processId: process.pid,
+    terminalKind:
+      terminalIdentity.terminalKind === "ghostty-surface" ? "ghostty-surface" : "unbound",
+    terminalKey: String(terminalIdentity.terminalKey ?? ""),
+    terminalFamily: String(terminalIdentity.terminalFamily ?? ""),
+    terminalSurfaceId: String(terminalIdentity.terminalSurfaceId ?? ""),
     cwd,
     repoLabel: formatRepoLabel(cwd, sessionName),
     sessionName: compactWhitespace(sessionName),

package/src/common/terminal-identity.mjs

@@ -0,0 +1,149 @@
+// ---
+// summary: "derives bounded terminal-surface identities for activity-strip publisher and focus contracts"
+// read_when:
+//   - "changing terminal card identity, Ghostty surface admission, or title matching"
+// ---
+
+import fs from "node:fs";
+import path from "node:path";
+
+const UINT64_MAX = 18_446_744_073_709_551_615n;
+const GHOSTTY_MAIN_APP_ID = "com.mitchellh.ghostty";
+const GHOSTTY_LEGACY_APP_ID = "com.tryinget.ghosttysidequest";
+
+/** @typedef {{terminalKind: "ghostty-surface" | "unbound"; terminalKey: string; terminalFamily: string; terminalSurfaceId: string}} TerminalIdentity */
+/** @typedef {{env?: NodeJS.ProcessEnv; hasUI?: boolean; stdinIsTTY?: boolean; ttyPath?: string; processId?: number; ancestorExecutable?: string}} TerminalIdentityOptions */
+
+/** @param {string} filePath */
+function safeReadFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+/** @param {string} filePath */
+function safeReadLink(filePath) {
+  try {
+    return fs.readlinkSync(filePath);
+  } catch {
+    return "";
+  }
+}
+
+/** @param {number} pid */
+function readParentPid(pid) {
+  const value = safeReadFile(path.join("/proc", String(pid), "stat"));
+  const lastParen = value.lastIndexOf(")");
+  if (lastParen < 0) return 0;
+  const fields = value
+    .slice(lastParen + 2)
+    .trim()
+    .split(/\s+/);
+  const parentPid = Number.parseInt(fields[1] ?? "", 10);
+  return Number.isInteger(parentPid) && parentPid > 0 ? parentPid : 0;
+}
+
+/** @param {unknown} value */
+export function normalizeGhosttySurfaceId(value) {
+  try {
+    const normalized = BigInt(String(value ?? "").trim());
+    return normalized >= 0n && normalized <= UINT64_MAX ? normalized.toString(10) : "";
+  } catch {
+    return "";
+  }
+}
+
+/** @param {unknown} executable */
+export function classifyGhosttyFamily(executable) {
+  const normalized = String(executable ?? "").toLowerCase();
+  if (!normalized) return "";
+  if (normalized.includes("ghostty-sidequest")) return "legacy";
+  if (path.basename(normalized) === "ghostty" || normalized.includes("ghostty-origin"))
+    return "main";
+  return "";
+}
+
+/** @param {unknown} family */
+export function appIdForGhosttyFamily(family) {
+  if (family === "main") return GHOSTTY_MAIN_APP_ID;
+  if (family === "legacy") return GHOSTTY_LEGACY_APP_ID;
+  return "";
+}
+
+/** @param {number} [processId] */
+export function findGhosttyAncestorExecutable(processId = process.pid) {
+  let pid = Number(processId) || 0;
+  for (let depth = 0; depth < 12 && pid > 0; depth += 1) {
+    pid = readParentPid(pid);
+    if (pid <= 0) break;
+    const command = safeReadFile(path.join("/proc", String(pid), "comm"))
+      .trim()
+      .toLowerCase();
+    if (command === "ghostty") return safeReadLink(path.join("/proc", String(pid), "exe"));
+  }
+  return "";
+}
+
+/** @returns {TerminalIdentity} */
+export function unboundTerminalIdentity() {
+  return {
+    terminalKind: "unbound",
+    terminalKey: "",
+    terminalFamily: "",
+    terminalSurfaceId: "",
+  };
+}
+
+/**
+ * Admit a terminal binding only for an interactive TUI attached to a real TTY and a recognized
+ * Ghostty process family. Headless descendants commonly inherit Ghostty environment variables, so
+ * GHOSTTY_SURFACE_ID alone is not evidence of an operator-visible terminal.
+ * @param {TerminalIdentityOptions} [options]
+ * @returns {TerminalIdentity}
+ */
+export function resolveTerminalIdentity({
+  env = process.env,
+  hasUI = false,
+  stdinIsTTY = Boolean(process.stdin.isTTY),
+  ttyPath = safeReadLink("/proc/self/fd/0"),
+  processId = process.pid,
+  ancestorExecutable,
+} = {}) {
+  if (
+    !hasUI ||
+    !stdinIsTTY ||
+    !ttyPath.startsWith("/dev/") ||
+    String(env.TERM_PROGRAM ?? "").toLowerCase() !== "ghostty"
+  ) {
+    return unboundTerminalIdentity();
+  }
+  const surfaceId = normalizeGhosttySurfaceId(env.GHOSTTY_SURFACE_ID);
+  const executable = ancestorExecutable ?? findGhosttyAncestorExecutable(processId);
+  const family = classifyGhosttyFamily(executable);
+  if (!surfaceId || !family) return unboundTerminalIdentity();
+  return {
+    terminalKind: "ghostty-surface",
+    terminalKey: `ghostty:${family}:${surfaceId}`,
+    terminalFamily: family,
+    terminalSurfaceId: surfaceId,
+  };
+}
+
+/** @param {Partial<TerminalIdentity> | Record<string, unknown>} identity */
+export function canonicalGhosttyTerminalKey(identity) {
+  if (identity?.terminalKind !== "ghostty-surface") return "";
+  const family = String(identity.terminalFamily ?? "");
+  if (family !== "main" && family !== "legacy") return "";
+  const surfaceId = normalizeGhosttySurfaceId(identity.terminalSurfaceId);
+  if (!surfaceId) return "";
+  const expectedKey = `ghostty:${family}:${surfaceId}`;
+  return String(identity.terminalKey ?? "") === expectedKey ? expectedKey : "";
+}
+
+/** @param {Partial<TerminalIdentity> | Record<string, unknown>} identity */
+export function terminalTitleSegment(identity) {
+  if (!canonicalGhosttyTerminalKey(identity)) return "";
+  return `gs:${identity.terminalFamily}:${normalizeGhosttySurfaceId(identity.terminalSurfaceId)}`;
+}