@tryinget/pi-activity-strip 0.2.0 → 0.4.0

package/src/common/activity-order.mjs

@@ -0,0 +1,68 @@
+// ---
+// summary: "provides deterministic monitoring-first strip ordering while preserving operator-defined order"
+// read_when:
+//   - "changing activity grouping, calm-cadence reconciliation, or manual card order"
+// ---
+
+const ACTIVE_STATES = new Set(["thinking", "tool", "waiting"]);
+
+/** @param {{ state?: string; agentActive?: boolean }} session */
+export function isActiveSession(session) {
+  return Boolean(session?.agentActive || ACTIVE_STATES.has(String(session?.state ?? "")));
+}
+
+/** @param {{ state?: string; toolName?: string; toolTarget?: string }} session */
+export function isMonitoringSession(session) {
+  return Boolean(
+    session?.state === "success" &&
+      !String(session?.toolName ?? "").trim() &&
+      !String(session?.toolTarget ?? "").trim(),
+  );
+}
+
+/**
+ * Reconcile at the calm clock: green settled/monitoring cards first, then active cards,
+ * then other inactive cards. Preserve previous/manual order inside each group and append
+ * new cards deterministically.
+ * @param {Array<{ sessionId: string; state?: string; agentActive?: boolean; toolName?: string; toolTarget?: string; updatedAt?: number }>} sessions
+ * @param {string[]} previousOrder
+ * @param {{ regroup?: boolean }} [options]
+ */
+export function reconcileActivityOrder(sessions, previousOrder = [], { regroup = true } = {}) {
+  const byId = new Map(sessions.map((session) => [session.sessionId, session]));
+  const surviving = previousOrder.filter((id) => byId.has(id));
+  const known = new Set(surviving);
+  for (const session of sessions) {
+    if (!session.sessionId || known.has(session.sessionId)) continue;
+    surviving.push(session.sessionId);
+    known.add(session.sessionId);
+  }
+  if (!regroup) return surviving;
+
+  const priorIndex = new Map(surviving.map((id, index) => [id, index]));
+  const ordered = [...sessions].sort((left, right) => {
+    const leftPriority = isMonitoringSession(left) ? 2 : isActiveSession(left) ? 1 : 0;
+    const rightPriority = isMonitoringSession(right) ? 2 : isActiveSession(right) ? 1 : 0;
+    const groupDelta = rightPriority - leftPriority;
+    if (groupDelta) return groupDelta;
+    const leftPrior = priorIndex.get(left.sessionId);
+    const rightPrior = priorIndex.get(right.sessionId);
+    if (leftPrior != null || rightPrior != null) {
+      return (leftPrior ?? Number.MAX_SAFE_INTEGER) - (rightPrior ?? Number.MAX_SAFE_INTEGER);
+    }
+    const updateDelta = Number(right.updatedAt ?? 0) - Number(left.updatedAt ?? 0);
+    if (updateDelta) return updateDelta;
+    return left.sessionId.localeCompare(right.sessionId);
+  });
+  return ordered.map((session) => session.sessionId).filter((id) => byId.has(id));
+}
+
+/** @param {string[]} order @param {string} sessionId @param {-1 | 1} delta */
+export function moveOrderItem(order, sessionId, delta) {
+  const next = [...order];
+  const from = next.indexOf(sessionId);
+  const to = from + delta;
+  if (from < 0 || to < 0 || to >= next.length) return next;
+  [next[from], next[to]] = [next[to], next[from]];
+  return next;
+}

package/src/common/alignment-controller.mjs

@@ -0,0 +1,74 @@
+// ---
+// summary: "coalesces native-window alignment so stale async work cannot overwrite newer geometry"
+// read_when:
+//   - "changing Electron/Niri geometry reconciliation or testing rapid expansion transitions"
+// ---
+
+/**
+ * @param {{ is_floating?: boolean, layout?: { tile_pos_in_workspace_view?: unknown } } | null | undefined} window
+ */
+export function hasNiriFloatingPosition(window) {
+  const position = window?.layout?.tile_pos_in_workspace_view;
+  return window?.is_floating === true && Array.isArray(position) && position.length >= 2;
+}
+
+/**
+ * @param {{ is_floating?: boolean, layout?: { tile_pos_in_workspace_view?: unknown, window_size?: unknown } } | null | undefined} window
+ * @param {{x: number, y: number, width: number, height: number}} target
+ */
+export function isNiriWindowAligned(window, target) {
+  if (!hasNiriFloatingPosition(window)) return false;
+  const position = window?.layout?.tile_pos_in_workspace_view;
+  const size = window?.layout?.window_size;
+  return Boolean(
+    Array.isArray(position) &&
+      Array.isArray(size) &&
+      Number(size[0]) === target.width &&
+      Number(size[1]) === target.height &&
+      Math.abs(Number(position[0]) - target.x) < 1 &&
+      Math.abs(Number(position[1]) - target.y) < 1,
+  );
+}
+
+/**
+ * @param {(attempt: { generation: number, isCurrent: () => boolean }) => Promise<void>} run
+ */
+export function createLatestOnlyRunner(run) {
+  if (typeof run !== "function") throw new TypeError("run must be a function");
+
+  let requestedGeneration = 0;
+  /** @type {Promise<void> | null} */
+  let worker = null;
+
+  async function drain() {
+    while (true) {
+      const generation = requestedGeneration;
+      const isCurrent = () => generation === requestedGeneration;
+      try {
+        await run({ generation, isCurrent });
+      } catch {
+        // Alignment is best effort. A newer request must still be allowed to reconcile the window.
+      }
+      if (isCurrent()) return;
+    }
+  }
+
+  function request() {
+    requestedGeneration += 1;
+    if (!worker) {
+      worker = drain().finally(() => {
+        worker = null;
+      });
+    }
+    return requestedGeneration;
+  }
+
+  async function waitForIdle() {
+    await worker;
+  }
+
+  return {
+    request,
+    waitForIdle,
+  };
+}

package/src/common/card-display.mjs

@@ -0,0 +1,48 @@
+// ---
+// summary: "derives card display facts that depend on more than one session field"
+// read_when:
+//   - "changing stalled-session detection, duplicate label disambiguation, or card label rendering"
+// ---
+
+/**
+ * A session is stalled when it claims to be mid-activity but no lifecycle
+ * event has arrived for longer than the stall threshold. Wedged streams keep
+ * heartbeating liveness, so only real event time can expose them.
+ * @param {Record<string, unknown>} session
+ * @param {number} nowMs
+ * @param {number} stallMs
+ */
+export function isStalledSession(session, nowMs, stallMs) {
+  if (!session.agentActive) return false;
+  const state = String(session.state ?? "");
+  if (state !== "thinking" && state !== "tool" && state !== "waiting") return false;
+  const anchor = Number(session.lastEventAt || session.updatedAt || 0);
+  return anchor > 0 && nowMs - anchor > stallMs;
+}
+
+/**
+ * @param {Array<Record<string, unknown>>} sessions
+ * @returns {Set<string>}
+ */
+export function findDuplicateLabels(sessions) {
+  const counts = new Map();
+  for (const session of sessions) {
+    const label = String(session.repoLabel || "pi session");
+    counts.set(label, (counts.get(label) || 0) + 1);
+  }
+  return new Set([...counts.entries()].filter(([, count]) => count > 1).map(([label]) => label));
+}
+
+/**
+ * Two live processes can share one repo label; append a short process suffix
+ * so their cards stay distinguishable at a glance.
+ * @param {Record<string, unknown>} session
+ * @param {Set<string>} duplicateLabels
+ */
+export function disambiguatedRepoLabel(session, duplicateLabels) {
+  const label = String(session.repoLabel || "pi session");
+  const processId = Number(session.processId ?? 0);
+  return duplicateLabels.has(label) && processId > 0
+    ? `${label} · ${String(processId).slice(-4)}`
+    : label;
+}

package/src/common/compatibility.mjs

@@ -1,3 +1,9 @@
+// ---
+// summary: "detects desktop and Electron prerequisites and formats actionable activity-strip compatibility reports"
+// read_when:
+//   - "changing host detection, compatibility blockers, warnings, or doctor output"
+// ---
+
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { locateElectron } from "./electron.mjs";
@@ -85,6 +91,12 @@ export async function assessActivityStripCompatibility(options = {}) {
     );
   }
 
+  if (windowManager === "niri" && displayCount === 0) {
+    blockers.push(
+      "Niri reports no connected display outputs. Turn on or reconnect the monitor before opening the activity strip.",
+    );
+  }
+
   try {
     electronPath = await locateElectronImpl();
   } catch (error) {
@@ -111,7 +123,7 @@ export async function assessActivityStripCompatibility(options = {}) {
     displayCount,
     alignmentMode: windowManager === "niri" ? "niri" : "generic",
     primaryDisplayOnly: true,
-    clickThroughDefault: env.PI_ACTIVITY_STRIP_CLICK_THROUGH !== "0",
+    clickThroughDefault: env.PI_ACTIVITY_STRIP_CLICK_THROUGH === "1",
     blockers,
     warnings,
   };
@@ -128,7 +140,7 @@ export function formatCompatibilityReport(report) {
     `Electron: ${report.electronPath || "not found"}`,
     `Alignment mode: ${report.alignmentMode}`,
     `Primary-display only: ${report.primaryDisplayOnly ? "yes" : "no"}`,
-    `Click-through default: ${report.clickThroughDefault ? "yes" : "no"}`,
+    `Click-through mode: ${report.clickThroughDefault ? "enabled by environment" : "disabled (interactive default)"}`,
   ];
 
   if (typeof report.displayCount === "number") {

package/src/common/constants.mjs

@@ -1,3 +1,9 @@
+// ---
+// summary: "defines shared socket paths, window dimensions, timing thresholds, and Electron binary candidates"
+// read_when:
+//   - "tuning activity-strip runtime defaults or locating shared configuration values"
+// ---
+
 import os from "node:os";
 import path from "node:path";
 
@@ -15,6 +21,10 @@ export const ACTIVITY_STRIP_SOCKET_PATH = path.join(
 );
 export const ACTIVITY_STRIP_WIDTH_PADDING = 16;
 export const ACTIVITY_STRIP_HEIGHT = 84;
+export const ACTIVITY_STRIP_EXPANDED_HEIGHT = 252;
+export const ACTIVITY_STRIP_ORDER_REFRESH_MS = 15_000;
+export const ACTIVITY_STRIP_WORKSPACE_SYNC_MS = 1500;
+export const ACTIVITY_STRIP_NIRI_ANIMATION_SETTLE_MS = 450;
 export const ACTIVITY_STRIP_HEARTBEAT_MS = 2500;
 export const ACTIVITY_STRIP_STALE_AFTER_MS = 12000;
 export const ACTIVITY_STRIP_BROADCAST_TICK_MS = 1000;
@@ -33,3 +43,5 @@ export const DEFAULT_ELECTRON_CANDIDATES = [
   "electron32",
   "electron31",
 ];
+export const ACTIVITY_STRIP_EVENT_STALL_MS = 15 * 60_000;
+export const ACTIVITY_STRIP_FLUSH_RETRY_DELAYS_MS = [250, 750];

package/src/common/contracts.d.ts

@@ -1,7 +1,14 @@
+// ---
+// summary: "declares the public TypeScript shapes shared by activity-strip runtime and JavaScript consumers"
+// read_when:
+//   - "checking emitted declaration contracts for sessions, broker messages, telemetry, or compatibility"
+// ---
+
 export type SessionState = "idle" | "thinking" | "tool" | "waiting" | "success" | "error";
 
 export interface SessionSnapshot {
   sessionId: string;
+  publisherId: string;
   processId: number;
   cwd: string;
   repoLabel: string;
@@ -14,6 +21,7 @@ export interface SessionSnapshot {
   state: SessionState;
   turnIndex: number;
   updatedAt: number;
+  lastEventAt: number;
   startedAt: number;
   agentStartedAt: number | null;
   agentActive: boolean;
@@ -65,9 +73,10 @@ export interface ActivityStripBrokerOptions {
   store?: {
     snapshot(): BrokerSnapshot;
     upsert(session: Partial<SessionSnapshot> | Record<string, unknown>): boolean;
-    remove(sessionId: string): boolean;
+    remove(sessionId: string, publisherId?: string): boolean;
   };
   getRuntimeStatus?: () => ActivityStripRuntimeStatus | undefined;
+  focusSession?: (sessionId: string) => Promise<{ ok: boolean; error?: string; windowId?: number }>;
 }
 
 export interface ToolCallDescription {
@@ -95,6 +104,9 @@ export interface SessionStartContextLike {
     notify?: (message: string, level?: "info" | "warning" | "error") => void;
     editor?: (title: string, text: string) => Promise<unknown>;
   };
+  sessionManager?: {
+    getSessionId?: () => string;
+  };
 }
 
 export interface BeforeAgentStartEventLike {
@@ -105,6 +117,11 @@ export interface TurnStartEventLike {
   turnIndex?: number;
 }
 
+export interface TurnEndEventLike {
+  turnIndex?: number;
+  message?: unknown;
+}
+
 export interface AssistantMessageEventLike {
   type?: string;
   delta?: unknown;
@@ -126,6 +143,10 @@ export interface SessionTelemetryOptions {
   pi?: TelemetryPiLike;
   cwd?: string;
   sessionName?: string;
+  transport?: {
+    publish: (session: SessionSnapshot) => Promise<unknown>;
+    remove: (session: { sessionId: string; publisherId: string }) => Promise<unknown>;
+  };
 }
 
 export interface ActivityStripCompatibilityReport {

package/src/common/contracts.ts

@@ -1,7 +1,14 @@
+// ---
+// summary: "defines source TypeScript contracts for session telemetry, broker transport, and runtime compatibility"
+// read_when:
+//   - "changing shared activity-strip types or the interfaces consumed through JSDoc imports"
+// ---
+
 export type SessionState = "idle" | "thinking" | "tool" | "waiting" | "success" | "error";
 
 export interface SessionSnapshot {
   sessionId: string;
+  publisherId: string;
   processId: number;
   cwd: string;
   repoLabel: string;
@@ -14,6 +21,7 @@ export interface SessionSnapshot {
   state: SessionState;
   turnIndex: number;
   updatedAt: number;
+  lastEventAt: number;
   startedAt: number;
   agentStartedAt: number | null;
   agentActive: boolean;
@@ -65,9 +73,10 @@ export interface ActivityStripBrokerOptions {
   store?: {
     snapshot(): BrokerSnapshot;
     upsert(session: Partial<SessionSnapshot> | Record<string, unknown>): boolean;
-    remove(sessionId: string): boolean;
+    remove(sessionId: string, publisherId?: string): boolean;
   };
   getRuntimeStatus?: () => ActivityStripRuntimeStatus | undefined;
+  focusSession?: (sessionId: string) => Promise<{ ok: boolean; error?: string; windowId?: number }>;
 }
 
 export interface ToolCallDescription {
@@ -95,6 +104,9 @@ export interface SessionStartContextLike {
     notify?: (message: string, level?: "info" | "warning" | "error") => void;
     editor?: (title: string, text: string) => Promise<unknown>;
   };
+  sessionManager?: {
+    getSessionId?: () => string;
+  };
 }
 
 export interface BeforeAgentStartEventLike {
@@ -105,6 +117,11 @@ export interface TurnStartEventLike {
   turnIndex?: number;
 }
 
+export interface TurnEndEventLike {
+  turnIndex?: number;
+  message?: unknown;
+}
+
 export interface AssistantMessageEventLike {
   type?: string;
   delta?: unknown;
@@ -126,6 +143,10 @@ export interface SessionTelemetryOptions {
   pi?: TelemetryPiLike;
   cwd?: string;
   sessionName?: string;
+  transport?: {
+    publish: (session: SessionSnapshot) => Promise<unknown>;
+    remove: (session: { sessionId: string; publisherId: string }) => Promise<unknown>;
+  };
 }
 
 export interface ActivityStripCompatibilityReport {

package/src/common/electron.mjs

@@ -1,3 +1,9 @@
+// ---
+// summary: "resolves an executable Electron binary from explicit settings, local dependencies, or PATH candidates"
+// read_when:
+//   - "changing Electron discovery order, environment overrides, or executable checks"
+// ---
+
 import { constants } from "node:fs";
 import { access } from "node:fs/promises";
 import path from "node:path";

package/src/common/format.mjs

@@ -1,3 +1,9 @@
+// ---
+// summary: "provides ANSI-safe truncation, whitespace compaction, and concise path, command, and session labels"
+// read_when:
+//   - "changing text previews or labels displayed in activity-strip telemetry"
+// ---
+
 import path from "node:path";
 
 // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape stripping requires an ESC control character pattern.