@tryinget/pi-activity-strip 0.2.0

package/src/client/launcher.mjs

@@ -0,0 +1,116 @@
+import { spawn } from "node:child_process";
+import { setTimeout as delay } from "node:timers/promises";
+import { assessActivityStripCompatibility } from "../common/compatibility.mjs";
+import { ACTIVITY_STRIP_START_TIMEOUT_MS } from "../common/constants.mjs";
+import { getBrokerStatus } from "./broker-client.mjs";
+
+/** @param {import("../common/contracts.ts").BrokerResponse | null | undefined} result */
+function isBrokerReady(result) {
+  return Boolean(result?.ok && (!result.runtimeStatus || result.runtimeStatus.state === "ready"));
+}
+
+/** @param {import("../common/contracts.ts").BrokerResponse | null | undefined} result */
+function describeBrokerWait(result) {
+  if (!result?.ok) return "Activity strip broker did not answer.";
+  if (!result.runtimeStatus) {
+    return "Activity strip broker answered without overlay readiness metadata.";
+  }
+
+  const runtime = result.runtimeStatus;
+  const warnings =
+    Array.isArray(runtime.warnings) && runtime.warnings.length > 0
+      ? ` Warnings: ${runtime.warnings.join(" ")}`
+      : "";
+
+  if (runtime.state === "error") {
+    return runtime.error || `Activity strip overlay reported an error.${warnings}`;
+  }
+
+  if (runtime.state === "starting") {
+    return `Activity strip broker answered, but the overlay is still starting.${warnings}`;
+  }
+
+  return `Activity strip broker is running (state=${runtime.state}).${warnings}`;
+}
+
+/**
+ * @param {string} binPath
+ * @param {{
+ *   env?: NodeJS.ProcessEnv;
+ *   timeoutMs?: number;
+ *   getBrokerStatusImpl?: typeof getBrokerStatus;
+ *   assessCompatibilityImpl?: typeof assessActivityStripCompatibility;
+ *   spawnProcess?: (binPath: string, env: NodeJS.ProcessEnv) => void;
+ * }} [options]
+ */
+export async function ensureActivityStripRunning(binPath, options = {}) {
+  const mergedEnv = {
+    ...process.env,
+    ...options.env,
+  };
+  const getStatus = options.getBrokerStatusImpl || getBrokerStatus;
+  const assessCompatibility = options.assessCompatibilityImpl || assessActivityStripCompatibility;
+
+  let latestStatus = null;
+  try {
+    latestStatus = await getStatus({ timeoutMs: 250 });
+  } catch {
+    latestStatus = null;
+  }
+
+  if (isBrokerReady(latestStatus)) {
+    return { ok: true, started: false };
+  }
+
+  const compatibility = await assessCompatibility({ env: mergedEnv });
+  if (!compatibility.ok) {
+    return {
+      ok: false,
+      started: false,
+      error: compatibility.blockers.join(" "),
+    };
+  }
+
+  let started = false;
+  if (!latestStatus?.ok) {
+    const spawnProcess =
+      options.spawnProcess ||
+      ((targetBinPath, env) => {
+        const child = spawn(process.execPath, [targetBinPath, "open"], {
+          detached: true,
+          stdio: "ignore",
+          env,
+        });
+        child.unref();
+      });
+    spawnProcess(binPath, mergedEnv);
+    started = true;
+  }
+
+  const timeoutMs = options.timeoutMs ?? ACTIVITY_STRIP_START_TIMEOUT_MS;
+  const timeoutAt = Date.now() + timeoutMs;
+  while (Date.now() < timeoutAt) {
+    try {
+      latestStatus = await getStatus({ timeoutMs: 250 });
+    } catch {
+      latestStatus = null;
+    }
+    if (isBrokerReady(latestStatus)) {
+      return { ok: true, started };
+    }
+    if (latestStatus?.runtimeStatus?.state === "error") {
+      return {
+        ok: false,
+        started,
+        error: describeBrokerWait(latestStatus),
+      };
+    }
+    await delay(125);
+  }
+
+  return {
+    ok: false,
+    started,
+    error: `${describeBrokerWait(latestStatus)} Timeout: ${timeoutMs}ms.`,
+  };
+}

package/src/client/session-telemetry.mjs

@@ -0,0 +1,214 @@
+/** @typedef {import("../common/contracts.ts").SessionSnapshot} SessionSnapshot */
+/** @typedef {import("../common/contracts.ts").SessionTelemetryOptions} SessionTelemetryOptions */
+/** @typedef {import("../common/contracts.ts").SessionStartContextLike} SessionStartContextLike */
+/** @typedef {import("../common/contracts.ts").BeforeAgentStartEventLike} BeforeAgentStartEventLike */
+/** @typedef {import("../common/contracts.ts").TurnStartEventLike} TurnStartEventLike */
+/** @typedef {import("../common/contracts.ts").MessageUpdateEventLike} MessageUpdateEventLike */
+/** @typedef {import("../common/contracts.ts").ToolExecutionEventLike} ToolExecutionEventLike */
+import {
+  ACTIVITY_STRIP_HEARTBEAT_MS,
+  ACTIVITY_STRIP_SEND_THROTTLE_MS,
+} from "../common/constants.mjs";
+import {
+  compactWhitespace,
+  formatRepoLabel,
+  previewPath,
+  previewText,
+  truncate,
+} from "../common/format.mjs";
+import {
+  createInitialSnapshot,
+  describeToolCall,
+  extractToolResultText,
+  summarizeToolResult,
+} from "../common/telemetry.mjs";
+import { publishSessionSnapshot, removeSession } from "./broker-client.mjs";
+
+function now() {
+  return Date.now();
+}
+
+/** @param {MessageUpdateEventLike} event */
+function extractAssistantDelta(event) {
+  if (event?.assistantMessageEvent?.type !== "text_delta") return "";
+  return String(event.assistantMessageEvent.delta ?? "");
+}
+
+/** @param {SessionTelemetryOptions} [options] */
+export function createSessionTelemetry({ pi, cwd = process.cwd(), sessionName = "" } = {}) {
+  /** @type {SessionSnapshot} */
+  let snapshot = createInitialSnapshot({ cwd, sessionName });
+  /** @type {NodeJS.Timeout | null} */
+  let heartbeatTimer = null;
+  /** @type {NodeJS.Timeout | null} */
+  let flushTimer = null;
+  let disposed = false;
+  let pendingAssistant = "";
+
+  async function flush() {
+    flushTimer = null;
+    if (disposed) return;
+    snapshot.updatedAt = now();
+    snapshot.repoLabel = formatRepoLabel(
+      snapshot.cwd,
+      pi?.getSessionName?.() ?? snapshot.sessionName,
+    );
+    snapshot.sessionName = compactWhitespace(pi?.getSessionName?.() ?? snapshot.sessionName);
+    try {
+      await publishSessionSnapshot(snapshot);
+    } catch {
+      // Broker is optional at runtime; silent failure keeps pi stable.
+    }
+  }
+
+  function scheduleFlush(delayMs = ACTIVITY_STRIP_SEND_THROTTLE_MS) {
+    if (disposed) return;
+    if (flushTimer) return;
+    flushTimer = setTimeout(() => {
+      flush().catch(() => {});
+    }, delayMs);
+  }
+
+  function startHeartbeat() {
+    if (heartbeatTimer) return;
+    heartbeatTimer = setInterval(() => {
+      scheduleFlush(0);
+    }, ACTIVITY_STRIP_HEARTBEAT_MS);
+    heartbeatTimer.unref?.();
+  }
+
+  function stopHeartbeat() {
+    if (!heartbeatTimer) return;
+    clearInterval(heartbeatTimer);
+    heartbeatTimer = null;
+  }
+
+  /** @param {Partial<SessionSnapshot>} partial */
+  function update(partial) {
+    snapshot = {
+      ...snapshot,
+      ...partial,
+      updatedAt: now(),
+    };
+    scheduleFlush();
+  }
+
+  return {
+    getSnapshot() {
+      return snapshot;
+    },
+    /** @param {SessionStartContextLike} ctx */
+    async onSessionStart(ctx) {
+      update({
+        cwd: ctx?.cwd ?? snapshot.cwd,
+        sessionName: pi?.getSessionName?.() ?? snapshot.sessionName,
+        detail: previewPath(ctx?.cwd ?? snapshot.cwd, 72) || "Ready",
+      });
+      startHeartbeat();
+      await flush();
+    },
+    /** @param {BeforeAgentStartEventLike} event */
+    onBeforeAgentStart(event) {
+      pendingAssistant = "";
+      update({
+        agentActive: true,
+        agentStartedAt: now(),
+        state: "thinking",
+        phase: "Thinking",
+        lastPromptPreview: previewText(event?.prompt, 96),
+        detail: previewText(event?.prompt, 104) || "Thinking…",
+        errorMessage: "",
+        toolName: "",
+        toolTarget: "",
+      });
+    },
+    /** @param {TurnStartEventLike} event */
+    onTurnStart(event) {
+      update({
+        turnIndex: Number(event?.turnIndex ?? snapshot.turnIndex + 1) || snapshot.turnIndex + 1,
+        state: snapshot.agentActive ? snapshot.state : "thinking",
+      });
+    },
+    /** @param {MessageUpdateEventLike} event */
+    onMessageUpdate(event) {
+      const delta = extractAssistantDelta(event);
+      if (!delta) return;
+      pendingAssistant = truncate(`${pendingAssistant}${delta}`, 240);
+      if (snapshot.state === "tool" || snapshot.state === "waiting") return;
+      update({
+        state: "thinking",
+        phase: "Thinking",
+        assistantPreview: previewText(pendingAssistant, 104),
+        detail: previewText(pendingAssistant, 104) || snapshot.detail,
+      });
+    },
+    /** @param {ToolExecutionEventLike} event */
+    onToolExecutionStart(event) {
+      const toolName = String(event?.toolName ?? "tool");
+      const description = describeToolCall(toolName, event?.args ?? {});
+      update({
+        state: description.state,
+        phase: description.phase,
+        detail: description.detail,
+        toolName,
+        toolTarget: description.toolTarget,
+        errorMessage: "",
+      });
+    },
+    /** @param {ToolExecutionEventLike} event */
+    onToolExecutionUpdate(event) {
+      if (snapshot.state !== "tool" && snapshot.state !== "waiting") return;
+      const partial = previewText(extractToolResultText(event?.partialResult), 104);
+      if (!partial) return;
+      update({
+        detail: partial,
+      });
+    },
+    /** @param {ToolExecutionEventLike} event */
+    onToolExecutionEnd(event) {
+      const toolName = String(event?.toolName ?? snapshot.toolName ?? "tool");
+      const summary = summarizeToolResult(toolName, event?.result, Boolean(event?.isError));
+      update({
+        state: summary.state,
+        phase: summary.phase,
+        detail: summary.detail,
+        errorMessage: summary.errorMessage,
+        toolName,
+      });
+    },
+    onTurnEnd() {
+      if (!snapshot.agentActive) return;
+      update({
+        state: snapshot.errorMessage ? "error" : "thinking",
+        phase: snapshot.errorMessage ? "Needs attention" : "Thinking",
+        detail: snapshot.assistantPreview || snapshot.detail || "Thinking…",
+      });
+    },
+    onAgentSettled() {
+      const detail =
+        snapshot.errorMessage || snapshot.assistantPreview || snapshot.lastPromptPreview || "Done";
+      update({
+        agentActive: false,
+        agentStartedAt: null,
+        state: snapshot.errorMessage ? "error" : "success",
+        phase: snapshot.errorMessage ? "Stopped" : "Done",
+        detail,
+        toolName: "",
+        toolTarget: "",
+      });
+    },
+    async shutdown() {
+      disposed = true;
+      stopHeartbeat();
+      if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+      }
+      try {
+        await removeSession(snapshot.sessionId);
+      } catch {
+        // ignore broker absence on shutdown
+      }
+    },
+  };
+}

package/src/common/compatibility.mjs

@@ -0,0 +1,153 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { locateElectron } from "./electron.mjs";
+
+const execFileAsync = promisify(execFile);
+
+/** @param {NodeJS.ProcessEnv} [env] */
+export function detectDisplayServer(env = process.env) {
+  if (env.WAYLAND_DISPLAY) return "wayland";
+  if (env.DISPLAY) return "x11";
+  if (env.XDG_SESSION_TYPE === "wayland") return "wayland";
+  if (env.XDG_SESSION_TYPE === "x11") return "x11";
+  return "headless";
+}
+
+/** @param {NodeJS.ProcessEnv} [env] */
+export function detectWindowManager(env = process.env) {
+  if (env.NIRI_SOCKET) return "niri";
+  return (
+    env.XDG_CURRENT_DESKTOP ||
+    env.XDG_SESSION_DESKTOP ||
+    env.DESKTOP_SESSION ||
+    env.SWAYSOCK ||
+    null
+  );
+}
+
+/**
+ * @param {unknown} payload
+ * @returns {number | null}
+ */
+function inferDisplayCount(payload) {
+  if (Array.isArray(payload)) return payload.length;
+  if (payload && typeof payload === "object") {
+    const values = Object.values(payload);
+    if (values.every((entry) => entry && typeof entry === "object")) {
+      return values.length;
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {{ env?: NodeJS.ProcessEnv; execFileAsyncImpl?: typeof execFileAsync }} [options]
+ */
+export async function detectDisplayCount(options = {}) {
+  const env = options.env || process.env;
+  const execFileImpl = options.execFileAsyncImpl || execFileAsync;
+  if (!env.NIRI_SOCKET) {
+    return null;
+  }
+
+  try {
+    const { stdout } = await execFileImpl("niri", ["msg", "-j", "outputs"], { env });
+    return inferDisplayCount(JSON.parse(stdout));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {{
+ *   env?: NodeJS.ProcessEnv;
+ *   locateElectronImpl?: typeof locateElectron;
+ *   execFileAsyncImpl?: typeof execFileAsync;
+ * }} [options]
+ * @returns {Promise<import("./contracts.ts").ActivityStripCompatibilityReport>}
+ */
+export async function assessActivityStripCompatibility(options = {}) {
+  const env = options.env || process.env;
+  const locateElectronImpl = options.locateElectronImpl || locateElectron;
+  const displayServer = detectDisplayServer(env);
+  const windowManager = detectWindowManager(env);
+  const displayCount = await detectDisplayCount({
+    env,
+    execFileAsyncImpl: options.execFileAsyncImpl,
+  });
+  const blockers = [];
+  const warnings = [];
+  let electronPath = null;
+
+  if (displayServer === "headless") {
+    blockers.push(
+      "No graphical display session detected. Start Pi from a Wayland/X11 desktop before opening the activity strip.",
+    );
+  }
+
+  try {
+    electronPath = await locateElectronImpl();
+  } catch (error) {
+    blockers.push(error instanceof Error ? error.message : String(error));
+  }
+
+  if (displayCount && displayCount > 1) {
+    warnings.push(
+      `Detected ${displayCount} displays; the strip currently renders on the primary display only.`,
+    );
+  }
+
+  if (windowManager !== "niri") {
+    warnings.push(
+      "Top-edge repair is optimized for Niri. Other window managers fall back to generic Electron bounds and may need manual adjustment.",
+    );
+  }
+
+  return {
+    ok: blockers.length === 0,
+    displayServer,
+    windowManager: typeof windowManager === "string" ? windowManager : null,
+    electronPath,
+    displayCount,
+    alignmentMode: windowManager === "niri" ? "niri" : "generic",
+    primaryDisplayOnly: true,
+    clickThroughDefault: env.PI_ACTIVITY_STRIP_CLICK_THROUGH !== "0",
+    blockers,
+    warnings,
+  };
+}
+
+/**
+ * @param {import("./contracts.ts").ActivityStripCompatibilityReport} report
+ */
+export function formatCompatibilityReport(report) {
+  const lines = [
+    `Compatibility: ${report.ok ? "compatible" : "blocked"}`,
+    `Display server: ${report.displayServer}`,
+    `Window manager: ${report.windowManager || "unknown"}`,
+    `Electron: ${report.electronPath || "not found"}`,
+    `Alignment mode: ${report.alignmentMode}`,
+    `Primary-display only: ${report.primaryDisplayOnly ? "yes" : "no"}`,
+    `Click-through default: ${report.clickThroughDefault ? "yes" : "no"}`,
+  ];
+
+  if (typeof report.displayCount === "number") {
+    lines.push(`Detected displays: ${report.displayCount}`);
+  }
+
+  if (report.blockers.length > 0) {
+    lines.push("", "Blockers:");
+    for (const blocker of report.blockers) {
+      lines.push(`- ${blocker}`);
+    }
+  }
+
+  if (report.warnings.length > 0) {
+    lines.push("", "Warnings:");
+    for (const warning of report.warnings) {
+      lines.push(`- ${warning}`);
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/common/constants.mjs

@@ -0,0 +1,35 @@
+import os from "node:os";
+import path from "node:path";
+
+export const ACTIVITY_STRIP_NAME = "pi-activity-strip";
+export const ACTIVITY_STRIP_SOCKET_DIR = path.join(
+  os.homedir(),
+  ".pi",
+  "agent",
+  "state",
+  ACTIVITY_STRIP_NAME,
+);
+export const ACTIVITY_STRIP_SOCKET_PATH = path.join(
+  ACTIVITY_STRIP_SOCKET_DIR,
+  "activity-strip.sock",
+);
+export const ACTIVITY_STRIP_WIDTH_PADDING = 16;
+export const ACTIVITY_STRIP_HEIGHT = 84;
+export const ACTIVITY_STRIP_HEARTBEAT_MS = 2500;
+export const ACTIVITY_STRIP_STALE_AFTER_MS = 12000;
+export const ACTIVITY_STRIP_BROADCAST_TICK_MS = 1000;
+export const ACTIVITY_STRIP_SEND_THROTTLE_MS = 120;
+export const ACTIVITY_STRIP_CONNECT_TIMEOUT_MS = 450;
+export const ACTIVITY_STRIP_START_TIMEOUT_MS = 5000;
+export const DEFAULT_ELECTRON_CANDIDATES = [
+  "electron",
+  "electron39",
+  "electron38",
+  "electron37",
+  "electron36",
+  "electron35",
+  "electron34",
+  "electron33",
+  "electron32",
+  "electron31",
+];

package/src/common/contracts.d.ts

@@ -0,0 +1,142 @@
+export type SessionState = "idle" | "thinking" | "tool" | "waiting" | "success" | "error";
+
+export interface SessionSnapshot {
+  sessionId: string;
+  processId: number;
+  cwd: string;
+  repoLabel: string;
+  sessionName: string;
+  phase: string;
+  detail: string;
+  assistantPreview: string;
+  toolName: string;
+  toolTarget: string;
+  state: SessionState;
+  turnIndex: number;
+  updatedAt: number;
+  startedAt: number;
+  agentStartedAt: number | null;
+  agentActive: boolean;
+  lastPromptPreview: string;
+  errorMessage: string;
+}
+
+export interface BrokerSnapshot {
+  generatedAt: number;
+  sessions: SessionSnapshot[];
+}
+
+export type ActivityStripRuntimeState = "starting" | "ready" | "error";
+
+export interface ActivityStripRuntimeStatus {
+  state: ActivityStripRuntimeState;
+  startedAt: number;
+  readyAt?: number | null;
+  windowVisible?: boolean;
+  displayServer?: "wayland" | "x11" | "headless" | "unknown";
+  windowManager?: string | null;
+  displayCount?: number | null;
+  alignmentMode?: "niri" | "generic";
+  warnings?: string[];
+  error?: string | null;
+}
+
+export interface BrokerResponse {
+  ok?: boolean;
+  type?: string;
+  snapshot?: BrokerSnapshot;
+  runtimeStatus?: ActivityStripRuntimeStatus;
+  error?: string;
+}
+
+export interface BrokerClientOptions {
+  expectReply?: boolean;
+  timeoutMs?: number;
+  socketPath?: string;
+}
+
+export interface SessionStoreOptions {
+  staleAfterMs?: number;
+}
+
+export interface ActivityStripBrokerOptions {
+  socketPath?: string;
+  socketDir?: string;
+  store?: {
+    snapshot(): BrokerSnapshot;
+    upsert(session: Partial<SessionSnapshot> | Record<string, unknown>): boolean;
+    remove(sessionId: string): boolean;
+  };
+  getRuntimeStatus?: () => ActivityStripRuntimeStatus | undefined;
+}
+
+export interface ToolCallDescription {
+  state: "tool" | "waiting";
+  phase: string;
+  detail: string;
+  toolTarget?: string;
+}
+
+export interface ToolResultSummary {
+  state: "thinking" | "error";
+  phase: string;
+  detail: string;
+  errorMessage?: string;
+}
+
+export interface TelemetryPiLike {
+  getSessionName?: () => string | undefined;
+}
+
+export interface SessionStartContextLike {
+  cwd?: string;
+  hasUI?: boolean;
+  ui?: {
+    notify?: (message: string, level?: "info" | "warning" | "error") => void;
+    editor?: (title: string, text: string) => Promise<unknown>;
+  };
+}
+
+export interface BeforeAgentStartEventLike {
+  prompt?: string;
+}
+
+export interface TurnStartEventLike {
+  turnIndex?: number;
+}
+
+export interface AssistantMessageEventLike {
+  type?: string;
+  delta?: unknown;
+}
+
+export interface MessageUpdateEventLike {
+  assistantMessageEvent?: AssistantMessageEventLike;
+}
+
+export interface ToolExecutionEventLike {
+  toolName?: string;
+  args?: Record<string, unknown>;
+  partialResult?: unknown;
+  result?: unknown;
+  isError?: boolean;
+}
+
+export interface SessionTelemetryOptions {
+  pi?: TelemetryPiLike;
+  cwd?: string;
+  sessionName?: string;
+}
+
+export interface ActivityStripCompatibilityReport {
+  ok: boolean;
+  displayServer: "wayland" | "x11" | "headless" | "unknown";
+  windowManager: string | null;
+  electronPath: string | null;
+  displayCount: number | null;
+  alignmentMode: "niri" | "generic";
+  primaryDisplayOnly: boolean;
+  clickThroughDefault: boolean;
+  blockers: string[];
+  warnings: string[];
+}