@tryinget/pi-activity-strip 0.2.0

package/LICENSE

@@ -0,0 +1,78 @@
+MIT License (with OpenAI/Anthropic/xAI/PRC Frontier Labs Rider)
+
+Copyright (c) contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+ADDITIONAL RIDER / RESTRICTION (OpenAI / Anthropic / xAI / PRC Frontier Labs):
+
+This rider is part of the "conditions" of this License. In the event of any
+conflict between this rider and any other portion of this License, this rider
+controls.
+
+"Restricted Parties" means OpenAI, L.L.C.; Anthropic, PBC; xAI Corp.; and the
+following PRC frontier AI labs and related entities: Baidu (including ERNIE-
+related entities), Alibaba and Alibaba Cloud (including Qwen-related entities),
+Tencent (including Hunyuan-related entities), ByteDance (including Doubao/Seed-
+related entities), DeepSeek, Zhipu AI, Moonshot AI, MiniMax, 01.AI
+(Lingyiwanwu), and iFlyTek. "Restricted Parties" also includes any of their
+respective Affiliates and any person or entity acting directly or indirectly
+on behalf of, for the benefit of, or under the direction of any of the
+foregoing (including any officer, director, employee, contractor, agent,
+consultant, service provider, or representative).
+
+Notwithstanding any other provision of this License, no rights are granted to
+any Restricted Party. Any purported license, sublicense, assignment, transfer,
+or other permission to any Restricted Party is null and void absent the
+express prior written permission of the copyright holders.
+
+You may not provide, disclose, distribute, sublicense, sell, lease, lend,
+host, make available, or otherwise permit access to the Software or any
+derivative work of the Software (as defined in applicable copyright law)
+(collectively, "Derivative Works") to or for any Restricted Party.
+
+For purposes of this rider, "use" includes, without limitation: copying,
+modifying, merging, publishing, distributing, sublicensing, selling,
+transferring, making available, hosting, deploying, executing, benchmarking,
+testing, analyzing, indexing, or incorporating the Software or any Derivative
+Works into any dataset, training corpus, evaluation harness, or pipeline for
+machine learning or other automated systems.
+
+This rider applies to the Software and all Derivative Works. As a condition of
+use, you agree that this rider is a precondition to exercising any rights
+under this License, and you agree that any distribution of the Software or any
+Derivative Works must include this rider provision unmodified.
+
+Any breach of this rider automatically and immediately terminates the
+permissions granted by this License. Upon termination, you must immediately
+cease all use and distribution of the Software and any Derivative Works and
+destroy all copies under your control.
+
+You agree that a breach of this rider would cause irreparable harm and that
+the copyright holders may seek injunctive or other equitable relief to enforce
+this rider, in addition to any other remedies available at law. To the maximum
+extent permitted by applicable law, the prevailing party in any action to
+enforce this rider shall be entitled to recover reasonable attorneys' fees and
+costs.
+
+For purposes of this rider, "Affiliate" means any entity that directly or
+indirectly controls, is controlled by, or is under common control with the
+specified party. "Control" means ownership of more than 50% of the voting
+securities or other ownership interest, or the power to direct management or
+policies by contract or otherwise.
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+---
+summary: "Top-row live activity strip for local Pi sessions running in Ghostty or other terminals."
+read_when:
+  - "Starting work in this package workspace."
+  - "Installing or verifying the activity strip in Pi."
+system4d:
+  container: "Monorepo package for a local broker + Electron overlay + Pi extension telemetry seam."
+  compass: "Make Pi session activity visible at a glance without changing the operator's normal terminal workflow."
+  engine: "Pi extension emits session telemetry -> local broker aggregates -> top-row Electron strip renders live state."
+  fog: "Main risks are runtime drift across Pi host versions, Electron availability, and stale-session behavior under real long-running work."
+---
+
+# @tryinget/pi-activity-strip
+
+A Pi extension package that gives you a **screen-top activity strip** showing what your live Pi sessions are doing.
+
+This package is designed for the exact workflow you asked for:
+- multiple Ghostty tabs
+- multiple Pi sessions
+- a persistent top-row ribbon
+- fine-grained live detail without changing how you normally run Pi
+
+## What it does
+
+- auto-starts a local top-row overlay when Pi starts in a TUI session
+- tracks each active Pi session independently
+- shows one card per live session
+- surfaces:
+  - repo/session label
+  - current phase
+  - current tool or target
+  - fine-grained detail text
+  - elapsed time plus last-seen freshness
+  - state color (`thinking`, `tool`, `waiting`, `done`, `error`)
+- keeps a local broker so multiple Pi processes can report into one strip
+
+## Architecture
+
+```text
+Pi session
+  -> activity-strip extension
+  -> local unix-socket broker
+  -> Electron top-row overlay
+```
+
+This is intentionally **local-first**.
+It does not require moving your workflow onto `pi-server` first.
+
+## Current scope
+
+Implemented now:
+- local per-host broker
+- primary-display top-row strip
+- one card per active Pi session
+- headless-safe telemetry publishing
+- explicit open/status/doctor/snapshot/fix-top/stop commands
+- local visual capture helpers so the agent can inspect the strip directly
+
+Not implemented yet:
+- multi-monitor strip replication
+- historical timeline / expand-on-hover detail
+- remote observers via `pi-server`
+
+## Installation in Pi
+
+From this package directory:
+
+```bash
+cd ~/ai-society/softwareco/owned/pi-extensions/packages/pi-activity-strip
+pi install "$PWD"
+```
+
+Then for **existing Pi tabs**:
+- run `/reload` in each tab you want tracked
+
+For **new Pi tabs**:
+- the package will load automatically from your Pi settings
+
+## Operator commands
+
+### Package-local CLI
+
+```bash
+npm run strip:open
+npm run strip:status
+npm run strip:doctor
+npm run strip:snapshot
+npm run strip:fix-top
+npm run strip:stop
+```
+
+or directly:
+
+```bash
+node ./bin/pi-activity-strip.mjs open
+node ./bin/pi-activity-strip.mjs status
+node ./bin/pi-activity-strip.mjs doctor
+node ./bin/pi-activity-strip.mjs snapshot
+node ./bin/pi-activity-strip.mjs fix-top
+```
+
+### Pi slash commands
+
+Inside Pi:
+
+```text
+/activity-strip
+/activity-strip status
+/activity-strip doctor
+/activity-strip fix-top
+/activity-strip stop
+/activity-strip-stop
+```
+
+In Pi with UI support:
+- `/activity-strip status` opens a detailed runtime status report when an editor surface is available
+- `/activity-strip doctor` opens the host-compatibility report
+
+## Verification commands
+
+### Package checks
+
+```bash
+npm install
+npm run check
+npm run release:check:quick
+```
+
+### Run the strip locally
+
+```bash
+npm run strip:open
+npm run strip:status
+npm run strip:doctor
+npm run strip:snapshot
+```
+
+### Capture what the agent should inspect
+
+```bash
+npm run capture:strip   # just the Pi activity strip window
+npm run capture:top     # top band of the focused output, including the strip + upper window area
+```
+
+These are specifically useful so the agent can inspect the current visual state without you manually posting screenshots.
+
+### Simulate multiple sessions
+
+```bash
+npm run demo:simulate
+```
+
+### Real Pi smoke on the live broker
+
+```bash
+npm run smoke:headless-live
+```
+
+This smoke:
+- opens the strip
+- runs a real headless Pi session with this extension loaded
+- exercises a real tool call
+- verifies that the broker observed the session while it was active
+
+### Compatibility diagnostics
+
+```bash
+npm run strip:doctor
+node ./bin/pi-activity-strip.mjs doctor --json
+```
+
+Use `doctor` before opening the strip when the host/display assumptions are uncertain. It reports:
+- whether a graphical session is present
+- whether Electron can be resolved
+- whether Niri-specific top-edge repair is available
+- whether the current setup is multi-display even though the strip remains primary-display-only
+
+## Environment controls
+
+- `PI_ACTIVITY_STRIP_AUTO_START=0`
+  - disable automatic strip opening on Pi session start
+- `PI_ACTIVITY_STRIP_CLICK_THROUGH=0`
+  - make the overlay clickable instead of mouse-transparent
+- `PI_ACTIVITY_STRIP_ELECTRON_BIN=/path/to/electron`
+  - override Electron binary discovery
+- `GLIMPSE_ELECTRON_BIN=/path/to/electron`
+  - shared Electron override also respected
+
+## Practical usage for your Ghostty tabs
+
+If you want this for all current tabs:
+
+1. install the package once with `pi install`
+2. run `/reload` inside each already-open Pi tab
+3. open the strip once with `/activity-strip` or `npm run strip:open`
+4. from then on, every loaded Pi session should report into the same top-row ribbon
+
+## References
+
+- [Project vision](docs/project/vision.md)
+- [Project resources](docs/project/resources.md)
+- [Verification notes](docs/project/verification.md)
+- [Next session prompt](next_session_prompt.md)

package/bin/pi-activity-strip.mjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+import { execFile, spawn } from "node:child_process";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import {
+  getBrokerStatus,
+  isBrokerAlive,
+  requestBrokerShutdown,
+  sendBrokerMessage,
+} from "../src/client/broker-client.mjs";
+import {
+  assessActivityStripCompatibility,
+  formatCompatibilityReport,
+} from "../src/common/compatibility.mjs";
+import { ACTIVITY_STRIP_START_TIMEOUT_MS } from "../src/common/constants.mjs";
+import { locateElectron } from "../src/common/electron.mjs";
+import { makeMessage } from "../src/common/protocol.mjs";
+import { formatBrokerRuntimeStatus } from "../src/common/status-report.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const electronEntry = path.resolve(__dirname, "..", "src", "electron", "main.mjs");
+const execFileAsync = promisify(execFile);
+
+function usage() {
+  console.log(
+    `Usage: pi-activity-strip <open|status|doctor|snapshot|fix-top|stop|serve> [--json]\n\nCommands:\n  open      Start the top-row activity strip if it is not already running\n  status    Check broker + overlay readiness and surface runtime warnings\n  doctor    Inspect host compatibility assumptions before opening the strip\n  snapshot  Print the current broker snapshot as JSON\n  fix-top   Move the strip window flush to the top edge in Niri\n  stop      Ask the running strip to shut down\n  serve     Internal helper; starts the Electron shell in the foreground\n`,
+  );
+}
+
+async function moveStripToTop() {
+  const { stdout } = await execFileAsync("niri", ["msg", "-j", "windows"], {
+    env: process.env,
+  });
+  const windows = JSON.parse(stdout);
+  if (!Array.isArray(windows)) {
+    throw new Error("Unexpected niri windows payload");
+  }
+
+  const stripWindow = windows.find((window) => window?.title === "Pi Activity Strip");
+  if (!stripWindow?.id) {
+    throw new Error("Could not find Pi Activity Strip window in niri");
+  }
+
+  const currentY = Number(stripWindow.layout?.tile_pos_in_workspace_view?.[1] ?? 0);
+  if (Math.abs(currentY) < 1) {
+    return 0;
+  }
+
+  await execFileAsync(
+    "niri",
+    [
+      "msg",
+      "action",
+      "move-floating-window",
+      "--id",
+      String(stripWindow.id),
+      "-y",
+      String(-Math.round(currentY)),
+    ],
+    { env: process.env },
+  );
+
+  console.log("Moved activity strip to the top edge.");
+  return 0;
+}
+
+async function waitForBrokerReady(timeoutMs = ACTIVITY_STRIP_START_TIMEOUT_MS) {
+  const timeoutAt = Date.now() + timeoutMs;
+  /** @type {import("../src/common/contracts.ts").BrokerResponse | null} */
+  let latestStatus = null;
+
+  while (Date.now() < timeoutAt) {
+    try {
+      latestStatus = await getBrokerStatus();
+    } catch {
+      latestStatus = null;
+    }
+
+    if (
+      latestStatus?.ok &&
+      (!latestStatus.runtimeStatus || latestStatus.runtimeStatus.state === "ready")
+    ) {
+      return { ok: true };
+    }
+    if (latestStatus?.runtimeStatus?.state === "error") {
+      return { ok: false, error: formatBrokerRuntimeStatus(latestStatus) };
+    }
+
+    await delay(125);
+  }
+
+  return {
+    ok: false,
+    error: `${formatBrokerRuntimeStatus(latestStatus || { ok: false })}\nTimeout: ${timeoutMs}ms`,
+  };
+}
+
+/** @param {{ detached?: boolean }} [options] @returns {Promise<number>} */
+async function openStrip({ detached = true } = {}) {
+  if (await isBrokerAlive()) {
+    console.log("Activity strip is already running.");
+    return 0;
+  }
+
+  const compatibility = await assessActivityStripCompatibility();
+  if (!compatibility.ok) {
+    console.error(formatCompatibilityReport(compatibility));
+    return 1;
+  }
+
+  const electron = await locateElectron();
+  const child = spawn(electron, [electronEntry], {
+    detached,
+    stdio: detached ? "ignore" : "inherit",
+    env: process.env,
+  });
+
+  if (detached) {
+    child.unref();
+    const ready = await waitForBrokerReady();
+    if (!ready.ok) {
+      console.error(ready.error || "Activity strip did not become ready.");
+      return 1;
+    }
+    console.log("Started activity strip.");
+    return 0;
+  }
+
+  return await new Promise((resolve) => {
+    child.on("exit", (code) => resolve(typeof code === "number" ? code : 0));
+  });
+}
+
+async function main() {
+  const command = process.argv[2] ?? "open";
+  const jsonOutput = process.argv.includes("--json");
+
+  switch (command) {
+    case "open":
+      process.exitCode = await openStrip({ detached: true });
+      return;
+    case "serve":
+      process.exitCode = await openStrip({ detached: false });
+      return;
+    case "status": {
+      try {
+        const result = await getBrokerStatus({ expectReply: true });
+        if (jsonOutput) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(formatBrokerRuntimeStatus(result));
+        }
+        process.exitCode =
+          result?.ok && (!result.runtimeStatus || result.runtimeStatus.state === "ready") ? 0 : 1;
+      } catch {
+        console.log(
+          jsonOutput ? JSON.stringify({ ok: false, state: "stopped" }, null, 2) : "stopped",
+        );
+        process.exitCode = 1;
+      }
+      return;
+    }
+    case "doctor": {
+      const report = await assessActivityStripCompatibility();
+      if (jsonOutput) {
+        console.log(JSON.stringify(report, null, 2));
+      } else {
+        console.log(formatCompatibilityReport(report));
+      }
+      process.exitCode = report.ok ? 0 : 1;
+      return;
+    }
+    case "snapshot": {
+      try {
+        const result = await sendBrokerMessage(makeMessage("ping"), { expectReply: true });
+        console.log(JSON.stringify(result?.snapshot ?? { sessions: [] }, null, 2));
+        process.exitCode = result?.ok ? 0 : 1;
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+      }
+      return;
+    }
+    case "fix-top": {
+      try {
+        process.exitCode = await moveStripToTop();
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+      }
+      return;
+    }
+    case "stop": {
+      try {
+        const result = await requestBrokerShutdown();
+        console.log(result?.ok ? "stopping" : "not-running");
+        process.exitCode = result?.ok ? 0 : 1;
+      } catch {
+        console.log("not-running");
+        process.exitCode = 1;
+      }
+      return;
+    }
+    case "-h":
+    case "--help":
+      usage();
+      process.exitCode = 0;
+      return;
+    default:
+      usage();
+      console.error(`Unknown command: ${command}`);
+      process.exitCode = 1;
+  }
+}
+
+main().catch((error) => {
+  if (error instanceof Error) {
+    console.error(error.stack ?? error.message);
+  } else {
+    console.error(String(error));
+  }
+  process.exit(1);
+});

package/examples/simulate-sessions.mjs

@@ -0,0 +1,64 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { publishSessionSnapshot, removeSession } from "../src/client/broker-client.mjs";
+import { createInitialSnapshot } from "../src/common/telemetry.mjs";
+
+function makeSession(label, cwd, state, phase, detail, offset = 0) {
+  const snapshot = createInitialSnapshot({ cwd, sessionName: label });
+  snapshot.state = state;
+  snapshot.phase = phase;
+  snapshot.detail = detail;
+  snapshot.agentActive = state === "tool" || state === "thinking" || state === "waiting";
+  snapshot.agentStartedAt = snapshot.startedAt - offset;
+  snapshot.updatedAt = Date.now();
+  return snapshot;
+}
+
+const sessions = [
+  makeSession(
+    "api refactor",
+    "~/ai-society/softwareco/owned/pi-server",
+    "tool",
+    "Editing file",
+    "src/routes/session.ts",
+    18000,
+  ),
+  makeSession(
+    "vault replay",
+    "~/ai-society/softwareco/owned/pi-extensions/packages/pi-vault-client",
+    "thinking",
+    "Thinking",
+    "Replaying execution receipt and comparing current render path",
+    9000,
+  ),
+  makeSession(
+    "frontend polish",
+    "~/ai-society/softwareco/owned/pi-web",
+    "waiting",
+    "Waiting for input",
+    "interactive form is open",
+    22000,
+  ),
+];
+
+for (const session of sessions) {
+  await publishSessionSnapshot(session);
+}
+
+await delay(1500);
+sessions[0].detail = "tests/session-contract.test.mjs";
+sessions[0].updatedAt = Date.now();
+await publishSessionSnapshot(sessions[0]);
+
+await delay(1500);
+sessions[1].state = "success";
+sessions[1].phase = "Done";
+sessions[1].detail = "Replay matches stored receipt";
+sessions[1].agentActive = false;
+sessions[1].agentStartedAt = null;
+sessions[1].updatedAt = Date.now();
+await publishSessionSnapshot(sessions[1]);
+
+await delay(2000);
+for (const session of sessions) {
+  await removeSession(session.sessionId);
+}