@tryinget/pi-activity-strip 0.9.0 → 0.10.0

package/src/broker/server.mjs

@@ -58,28 +58,45 @@ export class ActivityStripBroker extends EventEmitter {
   }
 
   async start() {
+    // Linux sun_path has 108 bytes including the trailing NUL. Node can silently
+    // bind a truncated path, so reject before chmod/unlink can change the filesystem.
+    if (Buffer.byteLength(this.socketPath, "utf8") > 107) {
+      throw new RangeError("Activity strip socket path must not exceed 107 UTF-8 bytes.");
+    }
+
     fs.mkdirSync(this.socketDir, { recursive: true, mode: 0o700 });
     fs.chmodSync(this.socketDir, 0o700);
     safeUnlink(this.socketPath);
 
-    await new Promise((resolve, reject) => {
-      this.server.once("error", reject);
-      this.server.listen(this.socketPath, () => {
-        this.server.off("error", reject);
-        try {
-          fs.chmodSync(this.socketPath, 0o600);
+    let bound = false;
+    try {
+      await new Promise((resolve, reject) => {
+        this.server.once("error", reject);
+        this.server.listen(this.socketPath, () => {
+          this.server.off("error", reject);
+          bound = true;
           resolve(undefined);
-        } catch (error) {
-          reject(error);
-        }
+        });
       });
-    });
+      fs.chmodSync(this.socketPath, 0o600);
 
-    this.tick = setInterval(() => {
+      this.tick = setInterval(() => {
+        this.emitSnapshot();
+      }, ACTIVITY_STRIP_BROADCAST_TICK_MS);
+      this.tick.unref?.();
       this.emitSnapshot();
-    }, ACTIVITY_STRIP_BROADCAST_TICK_MS);
-    this.tick.unref?.();
-    this.emitSnapshot();
+    } catch (error) {
+      // Only a successful bind gives us a socket to clean up. On a failed bind,
+      // stop() could unlink the address of the listener that beat us to it.
+      if (bound) {
+        try {
+          await this.stop();
+        } catch {
+          // Preserve the startup failure even if cleanup also fails.
+        }
+      }
+      throw error;
+    }
   }
 
   emitSnapshot() {

package/src/client/launcher.mjs

@@ -8,13 +8,9 @@ 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 { isOverlayReady } from "../common/overlay-readiness.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.";
@@ -64,7 +60,7 @@ export async function ensureActivityStripRunning(binPath, options = {}) {
     latestStatus = null;
   }
 
-  if (isBrokerReady(latestStatus)) {
+  if (isOverlayReady(latestStatus)) {
     return { ok: true, started: false };
   }
 
@@ -101,7 +97,7 @@ export async function ensureActivityStripRunning(binPath, options = {}) {
     } catch {
       latestStatus = null;
     }
-    if (isBrokerReady(latestStatus)) {
+    if (isOverlayReady(latestStatus)) {
       return { ok: true, started };
     }
     if (latestStatus?.runtimeStatus?.state === "error") {

package/src/client/runtime-lock.mjs

@@ -13,6 +13,7 @@ import {
   ACTIVITY_STRIP_START_TIMEOUT_MS,
   ACTIVITY_STRIP_STOP_TIMEOUT_MS,
 } from "../common/constants.mjs";
+import { isOverlayReady } from "../common/overlay-readiness.mjs";
 import { requestBrokerShutdown } from "./broker-client.mjs";
 
 const execFileAsync = promisify(execFile);
@@ -123,7 +124,7 @@ export async function waitForStartedRuntime({
   const deadline = now() + timeoutMs;
   while (true) {
     const status = await getStatus();
-    if (status?.ok && (!status.runtimeStatus || status.runtimeStatus.state === "ready")) {
+    if (isOverlayReady(status)) {
       return { ok: true, started: controller.exitCode === undefined };
     }
     if (status?.runtimeStatus?.state === "error") return { ok: false, reason: "error", status };

package/src/common/agent-identity.mjs

@@ -21,8 +21,13 @@ export const AGENT_CATALOG = Object.freeze([
   { kind: "opencode", label: "opencode", commands: Object.freeze(["opencode"]) },
   { kind: "crush", label: "Crush", commands: Object.freeze(["crush"]) },
   { kind: "goose", label: "Goose", commands: Object.freeze(["goose"]) },
-  { kind: "cursor", label: "Cursor Agent", commands: Object.freeze(["cursor-agent"]) },
+  // Cursor's CLI installs both names; `agent` is the one its docs now lead with.
+  { kind: "cursor", label: "Cursor Agent", commands: Object.freeze(["cursor-agent", "agent"]) },
   { kind: "zcode", label: "zcode", commands: Object.freeze(["zcode"]) },
+  // The nodecode TUI; its gateway runs outside any terminal, so tab admission never sees it.
+  { kind: "nodecode", label: "Nodecode", commands: Object.freeze(["nodecode"]) },
+  // angelx is a Python launcher; the cockpit binary it starts, `angel`, is what holds the tab.
+  { kind: "angel", label: "angelx", commands: Object.freeze(["angel"]) },
 ]);
 
 /** Pi publishes its own telemetry, so its processes are never discovered this way. */

package/src/common/contracts.d.ts

@@ -169,6 +169,7 @@ export interface SessionStartContextLike {
 }
 
 export interface BeforeAgentStartEventLike {
+  messageType?: "user" | "custom";
   prompt?: string;
 }
 

package/src/common/contracts.ts

@@ -80,6 +80,17 @@ export interface BrokerSnapshot {
 
 export type ActivityStripRuntimeState = "starting" | "ready" | "error";
 
+/** A last native observation, not current capture/authorization or a cross-clock timer. */
+export interface NativeKeyboardObservation {
+  panelPid: number;
+  request: number;
+  origin: "hover" | "explicit";
+  reason: "acquired" | "activity" | "idle-expired" | "source-revoked";
+  nativeMs: number;
+  deadlineMs: number | null;
+  captured: boolean;
+}
+
 export interface ActivityStripRuntimeStatus {
   state: ActivityStripRuntimeState;
   backend?: "native-layer-shell";
@@ -114,12 +125,38 @@ export interface ActivityStripRuntimeStatus {
   akTaskError?: string | null;
   akTaskClaimCount?: number;
   akTaskDeferredCount?: number;
+  /** When the deferral list was last read; it is reused for up to AK_DEFERRED_REFRESH_MS (AK7943). */
+  akTaskDeferredReadAt?: number | null;
+  /** How long that list may be reused (AK_DEFERRED_REFRESH_MS). */
+  akTaskDeferredMaxAgeMs?: number;
   akTaskOrphanCount?: number;
   akTaskRenderedCount?: number;
   rendererVisibilityTransitionCount?: number;
   controllerPid?: number;
   panelPid?: number | null;
   panelExpanded?: boolean;
+  nativeKeyboardObservation?: NativeKeyboardObservation | null;
+  /** Optional observational extension; absent on older controllers, never input/AK authority. */
+  ribbonDiagnostics?: {
+    controllerStartupSourceSha256: string | null;
+    expectedPrivateProtocol: number;
+    panelBuild: {
+      state: string;
+      binarySha256?: string;
+      processStartTicks?: string;
+      privateProtocol?: number | null;
+      receiptedSourceSha256?: string | null;
+    };
+    visibilityReason: string;
+    panelBuildObservedAt?: number | null;
+    focus: string;
+    contextValid: boolean;
+    eligible: boolean;
+    interactionEpoch: number;
+    keyboardAuthorization: "none" | "hover" | "explicit";
+    captureExpiry: string;
+    nativeKeyboardObservation?: NativeKeyboardObservation | null;
+  };
   clickThrough?: boolean;
   panelMoveCount?: number;
   panelActivationCount?: number;
@@ -199,6 +236,7 @@ export interface SessionStartContextLike {
 }
 
 export interface BeforeAgentStartEventLike {
+  messageType?: "user" | "custom";
   prompt?: string;
 }
 

package/src/common/keyboard-observation.mjs

@@ -0,0 +1,35 @@
+/** Optional private-v2 observation. Never authorization, query text or a wall-clock countdown.
+ * @param {unknown} input */
+export function normalizeKeyboardObservation(input) {
+  if (!input || typeof input !== "object") return null;
+  const event = /** @type {Record<string, unknown>} */ (input);
+  const { protocol, type, request, origin, reason, nativeMs, deadlineMs, captured } = event;
+  const safe = (/** @type {unknown} */ value) => Number.isSafeInteger(value) && Number(value) >= 0;
+  if (
+    protocol !== 2 ||
+    type !== "keyboard-observation" ||
+    !safe(request) ||
+    Number(request) === 0 ||
+    !safe(nativeMs) ||
+    captured !== true ||
+    typeof reason !== "string" ||
+    !["acquired", "activity", "idle-expired", "source-revoked"].includes(reason)
+  )
+    return null;
+  if (origin === "hover") {
+    if (
+      !safe(deadlineMs) ||
+      (reason === "idle-expired" && Number(nativeMs) < Number(deadlineMs)) ||
+      (["acquired", "activity"].includes(reason) && Number(nativeMs) >= Number(deadlineMs))
+    )
+      return null;
+  } else if (origin !== "explicit" || deadlineMs !== null || reason === "idle-expired") return null;
+  return {
+    request: Number(request),
+    origin: /** @type {"hover" | "explicit"} */ (origin),
+    reason: /** @type {"acquired" | "activity" | "idle-expired" | "source-revoked"} */ (reason),
+    nativeMs: Number(nativeMs),
+    deadlineMs: deadlineMs === null ? null : Number(deadlineMs),
+    captured: true,
+  };
+}

package/src/common/overlay-readiness.mjs

@@ -0,0 +1,11 @@
+// ---
+// summary: "distinguishes broker liveness from an explicitly ready native overlay"
+// read_when:
+//   - "changing startup reuse, waiter success, or CLI status exit semantics"
+// ---
+
+/** A pong alone is not overlay readiness or artifact approval.
+ * @param {import("./contracts.ts").BrokerResponse | null | undefined} result */
+export function isOverlayReady(result) {
+  return result?.ok === true && result.runtimeStatus?.state === "ready";
+}

package/src/common/presence-apps.mjs

@@ -0,0 +1,57 @@
+// ---
+// summary: "decides which focused non-agent applications keep the activity strip present"
+// read_when:
+//   - "changing which applications keep the strip visible, or the presence env override"
+// ---
+
+/**
+ * Applications the operator works in beside the agents: the terminal family that hosts agent tabs
+ * (and plain shells, nodecode, angelx, Cursor's `agent`), and the password manager reached for in
+ * the middle of agent work. Focusing one of them keeps the strip on screen. Presence is a
+ * visibility policy only; it never claims that the window owns a card.
+ */
+export const DEFAULT_PRESENCE_APP_IDS = Object.freeze([
+  "com.mitchellh.ghostty",
+  "com.tryinget.ghosttysidequest",
+  "com.onepassword.OnePassword",
+  "1Password",
+]);
+
+/** @type {Map<string, {all: boolean; ids: Set<string>}>} */
+const parsed = new Map();
+
+/**
+ * `PI_ACTIVITY_STRIP_PRESENCE_APP_IDS` is a comma list applied to the defaults: `id` adds an app,
+ * `-id` removes one, `none` drops every default, `*` keeps the strip present over every app.
+ * App ids compare case-insensitively.
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function presenceAppsFor(env = process.env) {
+  const raw = String(env?.PI_ACTIVITY_STRIP_PRESENCE_APP_IDS ?? "");
+  const cached = parsed.get(raw);
+  if (cached) return cached;
+  const ids = new Set(DEFAULT_PRESENCE_APP_IDS.map((id) => id.toLowerCase()));
+  let all = false;
+  for (const entry of raw.split(",").map((value) => value.trim().toLowerCase())) {
+    if (!entry) continue;
+    if (entry === "*") all = true;
+    else if (entry === "none") {
+      ids.clear();
+      all = false;
+    } else if (entry.startsWith("-")) ids.delete(entry.slice(1).trim());
+    else ids.add(entry);
+  }
+  const result = { all, ids };
+  parsed.set(raw, result);
+  return result;
+}
+
+/** @param {unknown} appId @param {NodeJS.ProcessEnv} [env] */
+export function isPresenceApp(appId, env = process.env) {
+  const id = String(appId ?? "")
+    .trim()
+    .toLowerCase();
+  if (!id) return false;
+  const apps = presenceAppsFor(env);
+  return apps.all || apps.ids.has(id);
+}

package/src/common/recovery-identity.mjs

@@ -0,0 +1,85 @@
+// ---
+// summary: "Exact harness-qualified claimant identities for read-only recovery projections."
+// read_when: ["changing recovery claimant joins"]
+// ---
+
+export const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** One base-36 field of a Nodecode id: uppercase with no leading zero, so one spelling each.
+ * @param {string} field @param {number} least @param {number} most */
+function base36Field(field, least, most) {
+  return field.length >= least && field.length <= most && /^(?:0|[1-9A-Z][0-9A-Z]*)$/.test(field);
+}
+
+/** A decimal field of a Nodecode id, of at least `least`, in at most six digits.
+ * @param {string} field @param {number} least */
+function decimalField(field, least) {
+  return /^[1-9][0-9]{0,5}$/.test(field) && Number(field) >= least;
+}
+
+/** @param {string} time @param {string} random */
+function stamp(time, random) {
+  return base36Field(time, 7, 8) && base36Field(random, 1, 10);
+}
+
+/** AK owns this grammar: valid_nodecode_session_id in agent-kernel crates/ak-core/src/tasks.rs.
+ * A shell is `s-<random>`, a durable session `session-<time>-<random>`, a fork
+ * `fork-turn-<time>-<random>-<n>` and one more number when that name is taken. `s-GATEWAY` is the
+ * gateway's shared pseudo-session: it names no one session. Every other Nodecode id stays refused.
+ * @param {unknown} id */
+function validNodecodeId(id) {
+  if (typeof id !== "string" || id === "s-GATEWAY") return false;
+  const parts = id.split("-");
+  if (parts[0] === "s" && parts.length === 2) return base36Field(parts[1], 1, 8);
+  if (parts[0] === "session" && parts.length === 3) return stamp(parts[1], parts[2]);
+  if (parts[0] !== "fork" || parts[1] !== "turn") return false;
+  if (parts.length < 5 || parts.length > 6) return false;
+  const [, , time, random, n, taken] = parts;
+  return (
+    stamp(time, random) && decimalField(n, 1) && (taken === undefined || decimalField(taken, 2))
+  );
+}
+
+/** @param {string} id */
+const lowercaseUuid = (id) => (UUID.test(id) ? id.toLowerCase() : null);
+/** @param {string} id */
+const exactNodecodeId = (id) => (validNodecodeId(id) ? id : null);
+
+/** Each harness's AK prefix, and how its ids are spelled in a claimant (null: no such claimant).
+ * A UUID folds to lowercase; a Nodecode id is case-exact, so it is kept or refused, never folded. */
+const HARNESSES =
+  /** @type {Record<string, {prefix: string; spell: (id: string) => string | null}>} */ ({
+    pi: { prefix: "session-", spell: lowercaseUuid },
+    claude: { prefix: "claude-session-", spell: lowercaseUuid },
+    codex: { prefix: "codex-session-", spell: lowercaseUuid },
+    nodecode: { prefix: "nodecode-session-", spell: exactNodecodeId },
+  });
+
+/** Unknown harnesses and ids outside a harness's form have no published AK claimant mapping.
+ * @param {string} harness @param {string} id */
+export function claimantFor(harness, id) {
+  if (!Object.hasOwn(HARNESSES, harness)) return null;
+  const { prefix, spell } = HARNESSES[harness];
+  const spelled = spell(id);
+  return spelled === null ? null : `${prefix}${spelled}`;
+}
+
+/** @param {unknown} value */
+export function parseClaimant(value) {
+  if (typeof value !== "string") return null;
+  for (const [harness, { prefix, spell }] of Object.entries(HARNESSES)) {
+    if (!value.startsWith(prefix)) continue;
+    const id = spell(value.slice(prefix.length));
+    if (id !== null) return { harness, id, claimant: `${prefix}${id}` };
+  }
+  return null;
+}
+
+/** Strip publisher ids are explicitly namespaced; a bare UUID is Pi only.
+ * @param {unknown} value */
+export function publisherClaimant(value) {
+  if (typeof value !== "string") return null;
+  if (UUID.test(value)) return claimantFor("pi", value);
+  const match = /^agent:([^:]+):(.+)$/.exec(value);
+  return match ? claimantFor(match[1], match[2]) : null;
+}