@tryinget/pi-activity-strip 0.2.0

package/src/common/contracts.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[];
+}

package/src/common/electron.mjs

@@ -0,0 +1,51 @@
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { DEFAULT_ELECTRON_CANDIDATES } from "./constants.mjs";
+
+/** @param {string} targetPath */
+async function canExecute(targetPath) {
+  try {
+    await access(targetPath, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** @param {string} binaryName */
+async function findOnPath(binaryName) {
+  for (const entry of String(process.env.PATH ?? "")
+    .split(":")
+    .filter(Boolean)) {
+    const candidate = path.join(entry, binaryName);
+    if (await canExecute(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** @param {string | null} [explicitPath] */
+export async function locateElectron(explicitPath = null) {
+  if (explicitPath) {
+    if (await canExecute(explicitPath)) return explicitPath;
+    throw new Error(`Configured Electron binary is not executable: ${explicitPath}`);
+  }
+
+  const envBinary = process.env.GLIMPSE_ELECTRON_BIN || process.env.PI_ACTIVITY_STRIP_ELECTRON_BIN;
+  if (envBinary) {
+    if (await canExecute(envBinary)) return envBinary;
+    throw new Error(`Configured Electron binary is not executable: ${envBinary}`);
+  }
+
+  const localBinary = path.resolve(process.cwd(), "node_modules", ".bin", "electron");
+  if (await canExecute(localBinary)) return localBinary;
+
+  for (const candidate of DEFAULT_ELECTRON_CANDIDATES) {
+    const found = await findOnPath(candidate);
+    if (found) return found;
+  }
+
+  throw new Error(
+    "Could not find an Electron binary. Install electron (or electron39 on Arch) or set GLIMPSE_ELECTRON_BIN / PI_ACTIVITY_STRIP_ELECTRON_BIN.",
+  );
+}

package/src/common/format.mjs

@@ -0,0 +1,75 @@
+import path from "node:path";
+
+// biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape stripping requires an ESC control character pattern.
+const ANSI_RE = /\u001b\[[0-9;]*m/g;
+
+/** @param {unknown} value @param {number} [max] */
+export function truncate(value, max = 96) {
+  const text = String(value ?? "").trim();
+  if (text.length <= max) return text;
+  return `${text.slice(0, Math.max(0, max - 1))}…`;
+}
+
+/** @param {unknown} value */
+export function stripAnsi(value) {
+  return String(value ?? "").replaceAll(ANSI_RE, "");
+}
+
+/** @param {unknown} value */
+export function compactWhitespace(value) {
+  return stripAnsi(String(value ?? ""))
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** @param {unknown} value */
+export function lastNonEmptyLine(value) {
+  const lines = String(value ?? "")
+    .split(/\r?\n/g)
+    .map((line) => compactWhitespace(line))
+    .filter(Boolean);
+  return lines.at(-1) ?? "";
+}
+
+/** @param {unknown} targetPath */
+export function basenameLabel(targetPath) {
+  const normalized = String(targetPath ?? "").trim();
+  if (!normalized) return "(unknown)";
+  return path.basename(normalized) || normalized;
+}
+
+/** @param {unknown} targetPath @param {number} [max] */
+export function previewPath(targetPath, max = 64) {
+  const normalized = compactWhitespace(targetPath);
+  if (!normalized) return "";
+  if (normalized.length <= max) return normalized;
+
+  const base = path.basename(normalized);
+  if (base.length + 4 >= max) {
+    return truncate(base, max);
+  }
+
+  return truncate(`…/${base}`, max);
+}
+
+/** @param {unknown} command @param {number} [max] */
+export function previewCommand(command, max = 72) {
+  return truncate(compactWhitespace(command), max);
+}
+
+/** @param {unknown} value @param {number} [max] */
+export function previewText(value, max = 96) {
+  return truncate(lastNonEmptyLine(value) || compactWhitespace(value), max);
+}
+
+/** @param {unknown} cwd @param {unknown} explicitSessionName */
+export function formatRepoLabel(cwd, explicitSessionName) {
+  const sessionName = compactWhitespace(explicitSessionName);
+  if (sessionName) return truncate(sessionName, 36);
+
+  const normalized = String(cwd ?? "").trim();
+  if (!normalized) return "pi session";
+
+  const repo = path.basename(normalized) || normalized;
+  return truncate(repo, 36);
+}

package/src/common/protocol.mjs

@@ -0,0 +1,71 @@
+import { randomUUID } from "node:crypto";
+
+/** @typedef {import("./contracts.ts").SessionState} SessionState */
+/** @typedef {import("./contracts.ts").SessionSnapshot} SessionSnapshot */
+
+/** @type {Set<SessionState>} */
+const SESSION_STATES = new Set(["idle", "thinking", "tool", "waiting", "success", "error"]);
+
+/** @param {string} type @param {Record<string, unknown>} [payload] */
+export function makeMessage(type, payload = {}) {
+  return {
+    id: randomUUID(),
+    type,
+    ...payload,
+  };
+}
+
+/** @param {Partial<SessionSnapshot> | Record<string, unknown>} [session] @returns {SessionSnapshot} */
+export function normalizeSessionSnapshot(session = {}) {
+  const now = Date.now();
+  const updatedAt = Number(session.updatedAt ?? now) || now;
+  const startedAt = Number(session.startedAt ?? updatedAt) || updatedAt;
+  const agentStartedAt =
+    session.agentStartedAt == null ? null : Number(session.agentStartedAt) || null;
+  const rawState = typeof session.state === "string" ? session.state : "idle";
+  /** @type {SessionState} */
+  const state = SESSION_STATES.has(/** @type {SessionState} */ (rawState))
+    ? /** @type {SessionState} */ (rawState)
+    : "idle";
+
+  return {
+    sessionId: String(session.sessionId ?? ""),
+    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 ?? ""),
+    state,
+    turnIndex: Number(session.turnIndex ?? 0) || 0,
+    updatedAt,
+    startedAt,
+    agentStartedAt,
+    agentActive: Boolean(session.agentActive),
+    lastPromptPreview: String(session.lastPromptPreview ?? ""),
+    errorMessage: String(session.errorMessage ?? ""),
+  };
+}
+
+/** @param {SessionSnapshot[]} [sessions] @returns {SessionSnapshot[]} */
+export function sortSessions(sessions = []) {
+  const stateWeight = new Map([
+    ["tool", 0],
+    ["thinking", 1],
+    ["waiting", 2],
+    ["error", 3],
+    ["success", 4],
+    ["idle", 5],
+  ]);
+
+  return [...sessions].sort((left, right) => {
+    const leftWeight = stateWeight.get(left.state) ?? 99;
+    const rightWeight = stateWeight.get(right.state) ?? 99;
+    if (leftWeight !== rightWeight) return leftWeight - rightWeight;
+    if (left.updatedAt !== right.updatedAt) return right.updatedAt - left.updatedAt;
+    return left.repoLabel.localeCompare(right.repoLabel);
+  });
+}

package/src/common/status-report.mjs

@@ -0,0 +1,58 @@
+/** @typedef {import("./contracts.ts").BrokerResponse} BrokerResponse */
+
+/** @param {BrokerResponse | null | undefined} result */
+export function formatBrokerRuntimeStatus(result) {
+  if (!result?.ok) return "stopped";
+  const runtime = result.runtimeStatus;
+  if (!runtime) return "running (legacy broker: no overlay readiness metadata)";
+
+  const lines = [
+    runtime.state === "ready" ? "running (ready)" : `running (${runtime.state})`,
+    `display: ${runtime.displayServer || "unknown"}`,
+    `window manager: ${runtime.windowManager || "unknown"}`,
+    `alignment: ${runtime.alignmentMode || "unknown"}`,
+  ];
+
+  if (typeof runtime.displayCount === "number") {
+    lines.push(`displays: ${runtime.displayCount}`);
+  }
+  if (typeof runtime.windowVisible === "boolean") {
+    lines.push(`window visible: ${runtime.windowVisible ? "yes" : "no"}`);
+  }
+  if (runtime.error) {
+    lines.push(`error: ${runtime.error}`);
+  }
+  if (Array.isArray(runtime.warnings) && runtime.warnings.length > 0) {
+    lines.push("warnings:");
+    for (const warning of runtime.warnings) {
+      lines.push(`- ${warning}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * @param {BrokerResponse | null | undefined} result
+ * @returns {{ headline: string; level: "info" | "warning" | "error" }}
+ */
+export function summarizeBrokerRuntimeStatus(result) {
+  if (!result?.ok) {
+    return { headline: "Activity strip is stopped", level: "warning" };
+  }
+
+  const runtime = result.runtimeStatus;
+  if (!runtime) {
+    return { headline: "Activity strip is running", level: "info" };
+  }
+
+  if (runtime.state === "ready") {
+    return { headline: "Activity strip is running and ready", level: "info" };
+  }
+
+  if (runtime.state === "error") {
+    return { headline: "Activity strip reported an error", level: "error" };
+  }
+
+  return { headline: `Activity strip is ${runtime.state}`, level: "warning" };
+}

package/src/common/telemetry.mjs

@@ -0,0 +1,180 @@
+import { randomUUID } from "node:crypto";
+import os from "node:os";
+/** @typedef {import("./contracts.ts").SessionSnapshot} SessionSnapshot */
+/** @typedef {import("./contracts.ts").ToolCallDescription} ToolCallDescription */
+/** @typedef {import("./contracts.ts").ToolResultSummary} ToolResultSummary */
+import {
+  basenameLabel,
+  compactWhitespace,
+  formatRepoLabel,
+  previewCommand,
+  previewPath,
+  previewText,
+  truncate,
+} from "./format.mjs";
+
+/** @param {unknown} value */
+function asRecord(value) {
+  return value && typeof value === "object" ? /** @type {Record<string, unknown>} */ (value) : null;
+}
+
+/** @param {unknown} value @param {number} [depth] @returns {string} */
+export function extractToolResultText(value, depth = 0) {
+  if (value == null || depth > 4) return "";
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    return value
+      .map((entry) => extractToolResultText(entry, depth + 1))
+      .filter(Boolean)
+      .join("\n");
+  }
+
+  const record = asRecord(value);
+  if (!record) return "";
+  if (record.type === "text" && typeof record.text === "string") return record.text;
+
+  for (const key of [
+    "errorMessage",
+    "error",
+    "message",
+    "stdout",
+    "stderr",
+    "output",
+    "content",
+    "details",
+    "text",
+  ]) {
+    const text = extractToolResultText(record[key], depth + 1);
+    if (text) return text;
+  }
+
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return "";
+  }
+}
+
+export function createSessionId() {
+  return `${os.hostname()}-${process.pid}-${Date.now()}-${randomUUID().slice(0, 6)}`;
+}
+
+/** @param {{ cwd?: string; sessionName?: string }} [options] @returns {SessionSnapshot} */
+export function createInitialSnapshot({ cwd = process.cwd(), sessionName = "" } = {}) {
+  const now = Date.now();
+  return {
+    sessionId: createSessionId(),
+    processId: process.pid,
+    cwd,
+    repoLabel: formatRepoLabel(cwd, sessionName),
+    sessionName: compactWhitespace(sessionName),
+    phase: "Idle",
+    detail: previewPath(cwd, 72) || "Ready",
+    assistantPreview: "",
+    toolName: "",
+    toolTarget: "",
+    state: "idle",
+    turnIndex: 0,
+    updatedAt: now,
+    startedAt: now,
+    agentStartedAt: null,
+    agentActive: false,
+    lastPromptPreview: "",
+    errorMessage: "",
+  };
+}
+
+/** @param {string} toolName @param {Record<string, unknown>} [args] @returns {ToolCallDescription} */
+export function describeToolCall(toolName, args = {}) {
+  switch (toolName) {
+    case "bash":
+      return {
+        state: "tool",
+        phase: "Running bash",
+        detail: previewCommand(args.command, 104) || "Running shell command",
+        toolTarget: previewCommand(args.command, 72),
+      };
+    case "read":
+      return {
+        state: "tool",
+        phase: "Reading file",
+        detail: previewPath(args.path, 104) || "Reading file",
+        toolTarget: previewPath(args.path, 72),
+      };
+    case "write":
+      return {
+        state: "tool",
+        phase: "Writing file",
+        detail: previewPath(args.path, 104) || "Writing file",
+        toolTarget: previewPath(args.path, 72),
+      };
+    case "edit":
+      return {
+        state: "tool",
+        phase: "Editing file",
+        detail: previewPath(args.path, 104) || "Editing file",
+        toolTarget: previewPath(args.path, 72),
+      };
+    case "interview":
+      return {
+        state: "waiting",
+        phase: "Waiting for input",
+        detail: truncate("Interactive form is open", 104),
+        toolTarget: "form",
+      };
+    case "copy_to_clipboard":
+      return {
+        state: "tool",
+        phase: "Copying to clipboard",
+        detail: truncate("Preparing clipboard payload", 104),
+        toolTarget: "clipboard",
+      };
+    default:
+      return {
+        state: "tool",
+        phase: `Running ${toolName}`,
+        detail: previewText(JSON.stringify(args), 104) || `Running ${toolName}`,
+        toolTarget: basenameLabel(toolName),
+      };
+  }
+}
+
+/** @param {string} toolName @param {unknown} result @param {boolean} [isError] @returns {ToolResultSummary} */
+export function summarizeToolResult(toolName, result, isError = false) {
+  const record = asRecord(result);
+  if (isError) {
+    const errorText = extractToolResultText(
+      record?.errorMessage ??
+        record?.error ??
+        record?.message ??
+        record?.details ??
+        record?.content ??
+        result,
+    );
+    return {
+      state: "error",
+      phase: `${toolName} failed`,
+      detail: previewText(errorText, 104) || `${toolName} failed`,
+      errorMessage: previewText(errorText, 104),
+    };
+  }
+
+  const outputText = extractToolResultText(result);
+  if (toolName === "bash") {
+    return {
+      state: "thinking",
+      phase: "Processing output",
+      detail: previewText(outputText, 104) || "Command finished",
+      errorMessage: "",
+    };
+  }
+
+  return {
+    state: "thinking",
+    phase: "Continuing",
+    detail: previewText(outputText, 104) || `${toolName} finished`,
+    errorMessage: "",
+  };
+}