pi-keyboard 0.1.0 → 0.1.1

package/features/keyboard.feature

@@ -27,6 +27,7 @@ Feature: Pi Keyboard Lighting Indicator
   Scenario: User activates thread and marks message as read
     Given the keyboard is currently displaying unread chat state
     When the user activates or focuses the terminal window
+    And no other Pi sessions have unread messages
     And no other Pi sessions are running
     Then the unread status is cleared
     And the keyboard lighting transitions to white idle breathing
@@ -34,10 +35,25 @@ Feature: Pi Keyboard Lighting Indicator
   Scenario: User activates thread while another session is running
     Given the keyboard is currently displaying unread chat state
     When the user activates or focuses the terminal window
+    And no other Pi sessions have unread messages
     And another background Pi session is currently running
     Then the unread status is cleared
     And the keyboard lighting transitions to blue thinking breathing
 
+  Scenario: All sessions must be read for unread green light to clear
+    Given multiple Pi sessions exist across terminal tabs
+    And one session finishes generating an unread response
+    When the user activates one session but another session still has unread messages
+    Then the keyboard lighting remains in green unread chat breathing state
+    When all active sessions are read or activated
+    Then the keyboard lighting transitions out of unread chat to idle or thinking
+
+  Scenario: User manual abort does not trigger red error light
+    Given an agent turn is actively executing
+    When the user cancels or aborts the turn via Ctrl+C or abort
+    Then the keyboard lighting does not trigger red error alert
+    And the lighting state transitions cleanly back to idle or thinking
+
   Scenario: Pi transitions to thinking state with blue breathing light
     Given a user has submitted a prompt or the agent is executing a turn
     When the agent starts thinking or executing tools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-keyboard",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Dynamic VIA/QMK keyboard RGB lighting indicator reflecting Pi states (idle, thinking, unread, need-approval, error)",
   "author": "Frad LEE <fradser@gmail.com>",
   "license": "MIT",

package/src/global-sessions.ts

@@ -1,12 +1,14 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import type { KeyboardState } from "./types";
 
-export interface SessionRecord {
+export interface SessionGlowRecord {
   sessionId: string;
   pid: number;
   cwd: string;
-  status: "running" | "idle" | "settled" | "exited";
+  status: "running" | "idle" | "settled" | "error" | "need_approval" | "exited";
+  hasUnread: boolean;
   updatedAt: number;
 }
 
@@ -14,6 +16,15 @@ export function getRegistryDir(): string {
   return path.join(os.homedir(), ".pi", "agent", "directory-sessions");
 }
 
+export function getSessionFileKey(cwd: string): string {
+  const normalized = path.resolve(cwd || process.cwd());
+  return `--${normalized.replace(/^[/\\\\]/, "").replace(/[/\\\\:]/g, "-")}--`;
+}
+
+export function getDirectoryRegistryPath(cwd: string): string {
+  return path.join(getRegistryDir(), getSessionFileKey(cwd));
+}
+
 export function isProcessAlive(pid: number): boolean {
   if (!pid || pid <= 0) return false;
   try {
@@ -25,54 +36,186 @@ export function isProcessAlive(pid: number): boolean {
 }
 
 /**
- * Scans all directory session registries to check if any other session is currently running.
- * Automatically checks PID vitality and excludes dead or stale processes.
+ * Writes or updates the session's active glow and unread state in the registry.
  */
-export function hasOtherRunningSessions(excludePid: number = process.pid): boolean {
-  const baseDir = getRegistryDir();
-  if (!fs.existsSync(baseDir)) return false;
-
-  const now = Date.now();
-  const maxStaleAgeMs = 5 * 60 * 1000; // 5 minutes max stale threshold
-
+export function writeSessionGlowState(record: SessionGlowRecord): void {
   try {
-    const dirEntries = fs.readdirSync(baseDir, { withFileTypes: true });
-    for (const dirEntry of dirEntries) {
-      if (!dirEntry.isDirectory()) continue;
+    const dir = getDirectoryRegistryPath(record.cwd);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    const filePath = path.join(dir, `${record.sessionId}.json`);
+    const tmpPath = `${filePath}.tmp.${Date.now()}`;
 
-      const subDirPath = path.join(baseDir, dirEntry.name);
-      let sessionFiles: string[] = [];
+    // Merge with existing session data if present to avoid overwriting other fields
+    let merged: Record<string, unknown> = { ...record };
+    if (fs.existsSync(filePath)) {
       try {
-        sessionFiles = fs.readdirSync(subDirPath);
+        const existing = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        if (existing && typeof existing === "object") {
+          merged = { ...existing, ...record };
+        }
       } catch {
-        continue;
+        // use fresh record
       }
+    }
 
-      for (const file of sessionFiles) {
-        if (!file.endsWith(".json")) continue;
-        const filePath = path.join(subDirPath, file);
+    fs.writeFileSync(tmpPath, JSON.stringify(merged, null, 2), "utf-8");
+    fs.renameSync(tmpPath, filePath);
+  } catch {
+    // Best-effort write
+  }
+}
 
+/**
+ * Removes the session record upon clean shutdown.
+ */
+export function removeSessionGlowState(cwd: string, sessionId: string): void {
+  try {
+    const filePath = path.join(getDirectoryRegistryPath(cwd), `${sessionId}.json`);
+    if (fs.existsSync(filePath)) {
+      fs.unlinkSync(filePath);
+    }
+  } catch {
+    // Best-effort remove
+  }
+}
+
+export interface GlobalStateSummary {
+  effectiveState: KeyboardState;
+  hasAnyUnread: boolean;
+  hasAnyRunning: boolean;
+  hasAnyError: boolean;
+  hasAnyNeedApproval: boolean;
+  activeSessionCount: number;
+}
+
+/**
+ * Reads all active sessions across all project directories, prunes dead PIDs,
+ * and determines the single authoritative global lighting state.
+ *
+ * Precedence:
+ * 1. Fatal Error (any session has fatal error) -> "error" (Red Blinking)
+ * 2. Need Approval (any session is waiting for user confirmation) -> "need_approval" (Yellow Blinking)
+ * 3. Unread Chat (ANY active session has unread messages) -> "unread_chat" (Green Breathing)
+ * 4. Thinking / Running (any session is actively executing) -> "thinking" (Blue Breathing)
+ * 5. Idle (all sessions are read and idle) -> "idle" (White Breathing)
+ */
+export function evaluateGlobalLightingState(
+  selfSessionId?: string,
+  selfRecord?: Partial<SessionGlowRecord>,
+): GlobalStateSummary {
+  const baseDir = getRegistryDir();
+  const now = Date.now();
+  const maxStaleAgeMs = 5 * 60 * 1000; // 5 minutes
+
+  const allRecords: SessionGlowRecord[] = [];
+
+  if (fs.existsSync(baseDir)) {
+    try {
+      const dirEntries = fs.readdirSync(baseDir, { withFileTypes: true });
+      for (const dirEntry of dirEntries) {
+        if (!dirEntry.isDirectory()) continue;
+
+        const subDirPath = path.join(baseDir, dirEntry.name);
+        let sessionFiles: string[] = [];
         try {
-          const content = fs.readFileSync(filePath, "utf-8");
-          const record = JSON.parse(content) as SessionRecord;
+          sessionFiles = fs.readdirSync(subDirPath);
+        } catch {
+          continue;
+        }
+
+        for (const file of sessionFiles) {
+          if (!file.endsWith(".json")) continue;
+          const filePath = path.join(subDirPath, file);
 
-          if (!record || typeof record !== "object") continue;
-          if (record.pid === excludePid) continue;
+          try {
+            const content = fs.readFileSync(filePath, "utf-8");
+            const record = JSON.parse(content) as SessionGlowRecord;
 
-          // Check if process is alive and actively running
-          if (record.status === "running" && isProcessAlive(record.pid)) {
-            if (now - (record.updatedAt || 0) < maxStaleAgeMs) {
-              return true;
+            if (!record || typeof record !== "object") continue;
+
+            // Prune dead process IDs
+            if (!isProcessAlive(record.pid)) {
+              try {
+                fs.unlinkSync(filePath);
+              } catch {}
+              continue;
+            }
+
+            // Skip stale records
+            if (now - (record.updatedAt || 0) > maxStaleAgeMs) {
+              continue;
             }
+
+            // If this is self, use the latest in-memory selfRecord values
+            if (selfSessionId && record.sessionId === selfSessionId && selfRecord) {
+              allRecords.push({ ...record, ...selfRecord } as SessionGlowRecord);
+            } else {
+              allRecords.push(record);
+            }
+          } catch {
+            // Ignore unreadable files
           }
-        } catch {
-          // Ignore unreadable or corrupt temp files
         }
       }
+    } catch {
+      // Ignore base scan errors
     }
-  } catch {
-    return false;
   }
 
-  return false;
+  // Ensure self record is included if not found on disk yet
+  if (selfSessionId && selfRecord && !allRecords.some((r) => r.sessionId === selfSessionId)) {
+    allRecords.push({
+      sessionId: selfSessionId,
+      pid: process.pid,
+      cwd: process.cwd(),
+      status: "idle",
+      hasUnread: false,
+      updatedAt: now,
+      ...selfRecord,
+    } as SessionGlowRecord);
+  }
+
+  let hasAnyError = false;
+  let hasAnyNeedApproval = false;
+  let hasAnyUnread = false;
+  let hasAnyRunning = false;
+
+  for (const r of allRecords) {
+    if (r.status === "error") {
+      hasAnyError = true;
+    }
+    if (r.status === "need_approval") {
+      hasAnyNeedApproval = true;
+    }
+    if (r.hasUnread) {
+      hasAnyUnread = true;
+    }
+    if (r.status === "running") {
+      hasAnyRunning = true;
+    }
+  }
+
+  let effectiveState: KeyboardState = "idle";
+  if (hasAnyError) {
+    effectiveState = "error";
+  } else if (hasAnyNeedApproval) {
+    effectiveState = "need_approval";
+  } else if (hasAnyUnread) {
+    effectiveState = "unread_chat";
+  } else if (hasAnyRunning) {
+    effectiveState = "thinking";
+  } else {
+    effectiveState = "idle";
+  }
+
+  return {
+    effectiveState,
+    hasAnyUnread,
+    hasAnyRunning,
+    hasAnyError,
+    hasAnyNeedApproval,
+    activeSessionCount: allRecords.length,
+  };
 }

package/src/index.ts

@@ -25,19 +25,33 @@ function getStateMachine(): KeyboardStateMachine {
 export default function (pi: ExtensionAPI): void {
   const sm = getStateMachine();
   let terminalInputDetached: (() => void) | undefined;
+  let rawStdinListener: ((chunk: Buffer | string) => void) | undefined;
 
   // Pi Lifecycle Hooks
   pi.on("session_start", async (_event, ctx) => {
-    // Attach passive terminal input / focus observer to detect thread activation
+    const sessionId = (ctx as { sessionManager?: { getSessionId?: () => string } }).sessionManager?.getSessionId?.();
+    sm.setSessionContext(sessionId, ctx.cwd);
+
+    // Passive terminal input observer via extension UI context
     if (ctx.hasUI && typeof ctx.ui.onTerminalInput === "function" && !terminalInputDetached) {
       terminalInputDetached = ctx.ui.onTerminalInput((_data: string) => {
-        if (sm.isUnread()) {
+        if (sm.isUnread() || sm.hasError()) {
           void sm.onUserActivated();
         }
         return undefined; // Passive observer: never consume or block input
       });
     }
 
+    // Direct raw stdin focus / keypress observer for reliable thread activation
+    if (process.stdin.isTTY && !rawStdinListener) {
+      rawStdinListener = (_chunk: Buffer | string) => {
+        if (sm.isUnread() || sm.hasError()) {
+          void sm.onUserActivated();
+        }
+      };
+      process.stdin.on("data", rawStdinListener);
+    }
+
     await sm.onSessionStart();
   });
 
@@ -67,14 +81,18 @@ export default function (pi: ExtensionAPI): void {
 
   pi.on("turn_end", async (event, _ctx) => {
     const msg = event.message as { stopReason?: string; errorMessage?: string } | undefined;
-    if (msg?.stopReason === "error" || msg?.stopReason === "aborted" || Boolean(msg?.errorMessage)) {
+    if (msg?.stopReason === "aborted") {
+      await sm.onMessageEnd("aborted");
+    } else if (msg?.stopReason === "error" || Boolean(msg?.errorMessage)) {
       await sm.onMessageEnd(msg?.stopReason, msg?.errorMessage);
     }
   });
 
   pi.on("message_end", async (event, _ctx) => {
     const msg = event.message as { stopReason?: string; errorMessage?: string } | undefined;
-    if (msg?.stopReason === "error" || msg?.stopReason === "aborted" || Boolean(msg?.errorMessage)) {
+    if (msg?.stopReason === "aborted") {
+      await sm.onMessageEnd("aborted");
+    } else if (msg?.stopReason === "error" || Boolean(msg?.errorMessage)) {
       await sm.onMessageEnd(msg?.stopReason, msg?.errorMessage);
     }
   });
@@ -89,7 +107,9 @@ export default function (pi: ExtensionAPI): void {
         const entry = branch[i];
         if (entry && entry.type === "message" && entry.message && entry.message.role === "assistant") {
           const msg = entry.message as { stopReason?: string; errorMessage?: string };
-          if (msg.stopReason === "error" || msg.stopReason === "aborted" || Boolean(msg.errorMessage)) {
+          if (msg.stopReason === "aborted") {
+            hasError = false;
+          } else if (msg.stopReason === "error" || Boolean(msg.errorMessage)) {
             hasError = true;
           }
           break;
@@ -107,6 +127,12 @@ export default function (pi: ExtensionAPI): void {
   pi.on("session_shutdown", async (_event, _ctx) => {
     terminalInputDetached?.();
     terminalInputDetached = undefined;
+
+    if (rawStdinListener) {
+      process.stdin.off("data", rawStdinListener);
+      rawStdinListener = undefined;
+    }
+
     await sm.onShutdown();
   });
 
@@ -114,6 +140,9 @@ export default function (pi: ExtensionAPI): void {
   pi.registerCommand("keyboard", {
     description: "Manage VIA/QMK keyboard RGB lighting status indicators",
     handler: async (args: string, ctx: ExtensionCommandContext) => {
+      // Executing a command in the session confirms user activation
+      void sm.onUserActivated();
+
       const trimmed = args.trim().toLowerCase();
 
       if (trimmed === "on") {

package/src/state-machine.ts

@@ -1,5 +1,12 @@
+import crypto from "node:crypto";
 import { applyKeyboardState } from "./driver";
-import { hasOtherRunningSessions } from "./global-sessions";
+import {
+  evaluateGlobalLightingState,
+  removeSessionGlowState,
+  writeSessionGlowState,
+  type GlobalStateSummary,
+  type SessionGlowRecord,
+} from "./global-sessions";
 import {
   KEYBOARD_STATE_DEFINITIONS,
   type KeyboardConfig,
@@ -11,11 +18,32 @@ export class KeyboardStateMachine {
   private isProcessing = false;
   private hasUnreadChat = false;
   private hasFatalError = false;
+  private sessionId: string;
+  private cwd: string;
 
   constructor(
     private config: KeyboardConfig,
-    private checkOtherRunning: () => boolean = () => hasOtherRunningSessions(),
-  ) {}
+    sessionId?: string,
+    cwd?: string,
+    private evalGlobalState: (id: string, record: SessionGlowRecord) => GlobalStateSummary = (id, rec) =>
+      evaluateGlobalLightingState(id, rec),
+  ) {
+    this.sessionId = sessionId || crypto.randomUUID();
+    this.cwd = cwd || process.cwd();
+  }
+
+  public getSessionId(): string {
+    return this.sessionId;
+  }
+
+  public getCwd(): string {
+    return this.cwd;
+  }
+
+  public setSessionContext(sessionId?: string, cwd?: string): void {
+    if (sessionId) this.sessionId = sessionId;
+    if (cwd) this.cwd = cwd;
+  }
 
   public getConfig(): KeyboardConfig {
     return { ...this.config };
@@ -42,6 +70,34 @@ export class KeyboardStateMachine {
     return KEYBOARD_STATE_DEFINITIONS[state]?.labelZh ?? state;
   }
 
+  private buildSelfRecord(statusOverride?: SessionGlowRecord["status"]): SessionGlowRecord {
+    let status: SessionGlowRecord["status"] = "idle";
+    if (this.hasFatalError) {
+      status = "error";
+    } else if (this.isProcessing) {
+      status = "running";
+    } else if (this.hasUnreadChat) {
+      status = "settled";
+    }
+
+    return {
+      sessionId: this.sessionId,
+      pid: process.pid,
+      cwd: this.cwd,
+      status: statusOverride ?? status,
+      hasUnread: this.hasUnreadChat,
+      updatedAt: Date.now(),
+    };
+  }
+
+  private async syncAndEvaluate(statusOverride?: SessionGlowRecord["status"]): Promise<void> {
+    const record = this.buildSelfRecord(statusOverride);
+    writeSessionGlowState(record);
+
+    const summary = this.evalGlobalState(this.sessionId, record);
+    await this.transitionTo(summary.effectiveState);
+  }
+
   public async transitionTo(nextState: KeyboardState, force = false): Promise<void> {
     if (this.currentState === nextState && !force) {
       return;
@@ -58,26 +114,21 @@ export class KeyboardStateMachine {
     this.isProcessing = false;
     this.hasUnreadChat = false;
     this.hasFatalError = false;
-
-    if (this.checkOtherRunning()) {
-      await this.transitionTo("thinking");
-    } else {
-      await this.transitionTo("idle");
-    }
+    await this.syncAndEvaluate("idle");
   }
 
   public async onAgentStart(): Promise<void> {
     this.isProcessing = true;
     this.hasUnreadChat = false;
     this.hasFatalError = false;
-    await this.transitionTo("thinking");
+    await this.syncAndEvaluate("running");
   }
 
   public async onTurnStart(): Promise<void> {
     this.isProcessing = true;
     this.hasUnreadChat = false;
     this.hasFatalError = false;
-    await this.transitionTo("thinking");
+    await this.syncAndEvaluate("running");
   }
 
   public async onToolCall(toolName: string, _input?: Record<string, unknown>): Promise<void> {
@@ -89,15 +140,15 @@ export class KeyboardStateMachine {
       toolName === "question";
 
     if (isInteractive) {
-      await this.transitionTo("need_approval");
+      await this.syncAndEvaluate("need_approval");
     } else {
-      await this.transitionTo("thinking");
+      await this.syncAndEvaluate("running");
     }
   }
 
   public async onToolResult(): Promise<void> {
     if (this.isProcessing) {
-      await this.transitionTo("thinking");
+      await this.syncAndEvaluate("running");
     }
   }
 
@@ -106,16 +157,25 @@ export class KeyboardStateMachine {
       this.hasFatalError = true;
       this.isProcessing = false;
       this.hasUnreadChat = false;
-      await this.transitionTo("error");
+      await this.syncAndEvaluate("error");
     }
   }
 
   public async onMessageEnd(stopReason?: string, errorMessage?: string): Promise<void> {
-    if (stopReason === "error" || stopReason === "aborted" || Boolean(errorMessage)) {
+    if (stopReason === "aborted") {
+      // User manually stopped/cancelled session — NOT an error!
+      this.isProcessing = false;
+      this.hasFatalError = false;
+      this.hasUnreadChat = false;
+      await this.syncAndEvaluate("idle");
+      return;
+    }
+
+    if (stopReason === "error" || Boolean(errorMessage)) {
       this.hasFatalError = true;
       this.isProcessing = false;
       this.hasUnreadChat = false;
-      await this.transitionTo("error");
+      await this.syncAndEvaluate("error");
     }
   }
 
@@ -124,53 +184,44 @@ export class KeyboardStateMachine {
     if (hasError || this.hasFatalError) {
       this.hasFatalError = true;
       this.hasUnreadChat = false;
-      await this.transitionTo("error");
+      await this.syncAndEvaluate("error");
     } else {
+      this.hasFatalError = false;
       this.hasUnreadChat = true;
-      await this.transitionTo("unread_chat");
+      await this.syncAndEvaluate("settled");
     }
   }
 
+  /**
+   * Called when user focuses the terminal window or interacts (key press / FocusIn).
+   * Marks current session as read and re-evaluates global system status:
+   * - If any OTHER session still has unread messages -> stays in unread_chat (green)
+   * - Else if any session is running -> thinking (blue)
+   * - Else -> idle (white)
+   */
   public async onUserActivated(): Promise<void> {
-    if (!this.hasUnreadChat) {
-      return;
-    }
     this.hasUnreadChat = false;
-
-    if (this.hasFatalError) {
-      await this.transitionTo("error");
-      return;
-    }
-
-    if (this.isProcessing || this.checkOtherRunning()) {
-      await this.transitionTo("thinking");
-    } else {
-      await this.transitionTo("idle");
-    }
+    this.hasFatalError = false;
+    await this.syncAndEvaluate(this.isProcessing ? "running" : "idle");
   }
 
   public async onUserInput(): Promise<void> {
     this.hasUnreadChat = false;
     this.hasFatalError = false;
-    if (this.isProcessing || this.checkOtherRunning()) {
-      await this.transitionTo("thinking");
-    } else {
-      await this.transitionTo("idle");
-    }
+    this.isProcessing = true;
+    await this.syncAndEvaluate("running");
   }
 
   public async onError(): Promise<void> {
     this.isProcessing = false;
     this.hasFatalError = true;
     this.hasUnreadChat = false;
-    await this.transitionTo("error");
+    await this.syncAndEvaluate("error");
   }
 
   public async onShutdown(): Promise<void> {
-    if (this.checkOtherRunning()) {
-      await this.transitionTo("thinking");
-    } else {
-      await this.transitionTo("idle");
-    }
+    removeSessionGlowState(this.cwd, this.sessionId);
+    const summary = evaluateGlobalLightingState();
+    await this.transitionTo(summary.effectiveState);
   }
 }