pi-keyboard 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# pi-keyboard
+
+Dynamic VIA/QMK keyboard RGB lighting indicator reflecting Pi's internal states.
+
+Ambient physical awareness of what your AI coding agent is doing right on your mechanical keyboard:
+
+| Pi State | Color & Effect | Trigger Condition |
+| :--- | :--- | :--- |
+| **Idle** | **White Breathing** (白色 呼吸灯) | Session started, ready & waiting for user input |
+| **Thinking** | **Blue Breathing** (蓝色 呼吸灯) | Model generating, reasoning, or executing tools |
+| **Unread Chat** | **Green Breathing** (绿色 呼吸灯) | Agent settled with a completed response for user |
+| **Need Approval** | **Yellow Blinking** (黄色 闪烁) | User prompt, question, or interactive permission gate |
+| **Error** | **Red Blinking** (红色 闪烁) | API failure, tool error, or abort |
+
+---
+
+## Zero Flash Wear (`--no-save`)
+
+All hardware updates are executed strictly in memory (`--no-save` mode). Lighting changes modify active RAM state on the keyboard's MCU without writing to EEPROM/Flash, avoiding storage wear across thousands of state transitions.
+
+---
+
+## Multi-Zone Control
+
+Supports discrete control for keyboard lighting channels:
+- **All Zones** (`all`): Both per-key backlight and underglow/side strips.
+- **Per-Key Matrix** (`matrix`): Keycap backlight (Channel 3 in VIA/QMK).
+- **Underglow / Side Strips** (`underglow`): Bottom and edge light strips (Channel 2 in VIA/QMK).
+
+---
+
+## Installation
+
+Install from this monorepo or local path:
+
+```bash
+pi install ~/Developer/FradSer/pi-packages/packages/keyboard
+```
+
+When published to npm:
+
+```bash
+pi install npm:pi-keyboard
+```
+
+---
+
+## Usage
+
+### Interactive Menu
+
+Type `/keyboard` in any Pi session:
+- **Toggle On / Off**
+- **Test Lighting States** (preview Idle, Thinking, Unread, Approval, Error)
+- **Active Zone Selection** (`all`, `matrix`, `underglow`)
+- **Brightness Scaling** (100%, 75%, 50%, 25%)
+- **Hardware Connection Info**
+
+### CLI Commands inside Pi
+
+```bash
+/keyboard on            # Enable lighting indicators
+/keyboard off           # Disable lighting indicators
+/keyboard status        # View active status and hardware info
+/keyboard test thinking # Test blue thinking light
+/keyboard test error    # Test red blinking light
+/keyboard test unread   # Test green unread chat light
+```
+
+---
+
+## Standalone CLI: `via-rgb`
+
+This package coordinates with the native macOS/Linux `via-rgb` binary (`~/.local/bin/via-rgb`), allowing shell scripts, cron jobs, Raycast, and Hammerspoon to control lighting outside Pi as well:
+
+```bash
+# Query status
+via-rgb status
+
+# Turn off / on
+via-rgb off
+via-rgb on -b 200
+
+# Set specific color & zone
+via-rgb --zone matrix set -c blue
+via-rgb --zone side set -c warmwhite
+```
+
+---
+
+## Configuration
+
+Settings are saved in `~/.pi/agent/keyboard.json`:
+
+```json
+{
+  "enabled": true,
+  "zone": "all",
+  "brightnessScale": 1.0,
+  "saveToEeprom": false
+}
+```

package/README.zh-CN.md

@@ -0,0 +1,102 @@
+# pi-keyboard
+
+基于 VIA/QMK 协议的 Pi 键盘 RGB 状态指示灯插件。
+
+通过机械键盘的 RGB 灯光，实时提供 AI Coding Agent 运行状态的环境感知：
+
+| Pi 运行状态 | 灯光颜色与效果 | 触发时机 |
+| :--- | :--- | :--- |
+| **Idle (待命)** | **白色 呼吸灯** | 启动完成、等待用户输入新任务 |
+| **Thinking (运行)** | **蓝色 呼吸灯** | 模型生成中、深度思考中或正在执行工具 |
+| **Unread Chat (未读)** | **绿色 呼吸灯** | Agent 回答完成，等待用户查阅 |
+| **Need Approval (确认)** | **黄色 闪烁** | 提问、等待用户输入或交互式权限确认 |
+| **Error (异常)** | **红色 闪烁** | API 报错、工具执行失败或异常中断 |
+
+---
+
+## 零 Flash 损耗设计（`--no-save`）
+
+所有状态变更均以 `--no-save` 纯内存模式向键盘 MCU 发送指令，**不写入 Flash / EEPROM**。即使每天触发数千次思考与交互状态切换，也不会产生硬件擦写寿命损耗。
+
+---
+
+## 多分区独立控制
+
+支持精准控制键盘的不同发光区域：
+- **全部区域** (`all`)：按键背光与侧边底灯联动。
+- **按键背光矩阵** (`matrix`)：仅控制键帽背光（QMK 通道 3）。
+- **侧边底灯** (`underglow`)：仅控制外壳侧边/底部灯带（QMK 通道 2）。
+
+---
+
+## 安装方式
+
+从本地仓库安装：
+
+```bash
+pi install ~/Developer/FradSer/pi-packages/packages/keyboard
+```
+
+当发布到 npm 后也可直接安装：
+
+```bash
+pi install npm:pi-keyboard
+```
+
+---
+
+## 使用指南
+
+### 交互式菜单
+
+在 Pi 对话框中输入 `/keyboard`：
+- **开关切换**：开启或关闭状态指示灯
+- **状态效果测试**：预览测试待命、思考、未读、确认、错误各状态
+- **活动分区配置**：选择全部、仅背光或仅侧灯
+- **亮度比例调节**：100%、75%、50%、25% 亮度随心调节
+- **硬件连接信息**：查看识别到的键盘型号与 VIA 协议版本
+
+### 对话内快捷指令
+
+```bash
+/keyboard on            # 启用指示灯
+/keyboard off           # 关闭指示灯
+/keyboard status        # 查看当前配置与键盘硬件状态
+/keyboard test thinking # 预览测试蓝色思考呼吸灯
+/keyboard test error    # 预览测试红色报错闪烁灯
+/keyboard test unread   # 预览测试绿色未读呼吸灯
+```
+
+---
+
+## 独立命令行工具：`via-rgb`
+
+本插件配套安装了系统级命令 `via-rgb`（位于 `~/.local/bin/via-rgb`），在 Pi 之外也可用于 Shell、Raycast、Hammerspoon 或睡眠唤醒脚本：
+
+```bash
+# 查询当前状态
+via-rgb status
+
+# 开关灯光
+via-rgb off
+via-rgb on -b 200
+
+# 自定义颜色与分区
+via-rgb --zone matrix set -c blue
+via-rgb --zone side set -c warmwhite
+```
+
+---
+
+## 配置文件
+
+配置自动保存在 `~/.pi/agent/keyboard.json`：
+
+```json
+{
+  "enabled": true,
+  "zone": "all",
+  "brightnessScale": 1.0,
+  "saveToEeprom": false
+}
+```

package/features/keyboard.feature

@@ -0,0 +1,112 @@
+Feature: Pi Keyboard Lighting Indicator
+  As a Pi developer
+  I want my VIA/QMK keyboard lighting to dynamically reflect Pi's internal states
+  So that I have ambient physical awareness of agent status without looking at the terminal
+
+  Background:
+    Given a VIA-compatible keyboard with Raw-HID support
+    And the keyboard has RGB lighting configuration
+
+  Scenario: Pi transitions to idle state with white breathing light
+    Given Pi is in session startup or waiting for new user input
+    And no other Pi session is currently running
+    When the keyboard state machine updates to "idle"
+    Then the keyboard lighting is set to white color
+    And the effect mode is set to breathing
+    And the update is applied immediately in memory without saving to EEPROM
+
+  Scenario: Pi transitions to unread chat state with green breathing light
+    Given the agent has finished generating a response
+    And the user has not yet submitted new input or activated the thread
+    When the agent settles with a completed message
+    Then the keyboard state machine updates to "unread_chat"
+    And the keyboard lighting is set to green color
+    And the effect mode is set to breathing
+    And the update is applied with --no-save in memory
+
+  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 are running
+    Then the unread status is cleared
+    And the keyboard lighting transitions to white idle breathing
+
+  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 another background Pi session is currently running
+    Then the unread status is cleared
+    And the keyboard lighting transitions to blue thinking breathing
+
+  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
+    Then the keyboard state machine updates to "thinking"
+    And the keyboard lighting is set to blue color
+    And the effect mode is set to breathing
+    And the update is applied with --no-save in memory
+
+  Scenario: Pi transitions to need approval state with yellow blinking light
+    Given a tool call requires user confirmation or approval
+    When an interactive gate or question is prompted
+    Then the keyboard state machine updates to "need_approval"
+    And the keyboard lighting is set to yellow color
+    And the effect mode is set to blinking alert
+    And the update is applied with --no-save in memory
+
+  Scenario: Pi transitions to error state with red blinking light
+    Given an agent execution error, API failure, or turn error occurs
+    When a fatal error event is captured
+    Then the keyboard state machine updates to "error"
+    And the keyboard lighting is set to red color
+    And the effect mode is set to blinking alert
+    And the update is applied with --no-save in memory
+
+  Scenario: Non-fatal tool errors do not trigger red blinking light
+    Given the agent executes a bash command or test that returns a non-zero exit code
+    When the tool result arrives during ongoing turn reasoning
+    Then the keyboard lighting remains in "thinking" blue breathing state
+    And it does not trigger the red error alert
+
+  Scenario: Upstream provider rate limit (429) triggers red blinking error light
+    Given the model provider returns an HTTP 429 quota error or 500 failure
+    When the provider error response is received
+    Then the keyboard state machine transitions to "error" red blinking
+    And the subsequent agent settle event does not overwrite it with green
+
+  Scenario: User submits input and clears unread chat status
+    Given the keyboard is currently displaying unread chat state
+    When the user submits a new prompt in the conversation
+    Then the unread status is cleared
+    And the keyboard state machine transitions to "thinking"
+
+  Scenario: Target lighting zone selection
+    Given the user configures the target zone
+    When the zone is set to "matrix"
+    Then only channel 3 (key backlight) is updated
+    When the zone is set to "underglow"
+    Then only channel 2 (side strip) is updated
+    When the zone is set to "all"
+    Then both channel 2 and channel 3 are updated
+
+  Scenario: In-memory updates without EEPROM wear
+    Given any state transition is dispatched to hardware
+    When the HID command is executed
+    Then it operates strictly in RAM using no-save mode without sending save command 0x09
+
+  Scenario: State change deduplication prevents redundant HID writes
+    Given the keyboard is already displaying "thinking" state
+    When another turn or tool call event occurs while still "thinking"
+    Then redundant hardware HID commands are skipped
+
+  Scenario: Keyboard disconnection handling
+    Given the keyboard is unplugged or unavailable
+    When a state transition occurs
+    Then the driver fails gracefully without throwing unhandled exceptions or crashing Pi
+
+  Scenario: /keyboard command allows manual state testing and toggle
+    Given the /keyboard command is executed
+    When the user toggles lighting to "off"
+    Then all keyboard lighting updates are disabled
+    When the user runs "/keyboard test thinking"
+    Then the keyboard lighting displays the blue thinking state

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "pi-keyboard",
+  "version": "0.1.0",
+  "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",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "keyboard",
+    "lighting",
+    "via",
+    "qmk",
+    "rgb-status",
+    "ambient-indicator"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/FradSer/pi-packages.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "features",
+    "README.md",
+    "README.zh-CN.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  }
+}

package/src/config.ts

@@ -0,0 +1,65 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import type { KeyboardConfig, KeyboardZone } from "./types";
+
+export const DEFAULT_KEYBOARD_CONFIG: KeyboardConfig = {
+  enabled: true,
+  zone: "all",
+  brightnessScale: 1.0,
+  saveToEeprom: false, // strictly in-memory (--no-save) by default
+};
+
+export function keyboardConfigPath(): string {
+  return join(homedir(), ".pi", "agent", "keyboard.json");
+}
+
+export function readKeyboardConfig(): KeyboardConfig {
+  const filePath = keyboardConfigPath();
+  if (!existsSync(filePath)) {
+    return { ...DEFAULT_KEYBOARD_CONFIG };
+  }
+
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") {
+      return { ...DEFAULT_KEYBOARD_CONFIG };
+    }
+
+    const zone: KeyboardZone =
+      parsed.zone === "underglow" || parsed.zone === "matrix" || parsed.zone === "all"
+        ? parsed.zone
+        : DEFAULT_KEYBOARD_CONFIG.zone;
+
+    const brightnessScale =
+      typeof parsed.brightnessScale === "number" &&
+      parsed.brightnessScale >= 0.1 &&
+      parsed.brightnessScale <= 1.0
+        ? parsed.brightnessScale
+        : DEFAULT_KEYBOARD_CONFIG.brightnessScale;
+
+    return {
+      enabled: typeof parsed.enabled === "boolean" ? parsed.enabled : DEFAULT_KEYBOARD_CONFIG.enabled,
+      zone,
+      brightnessScale,
+      saveToEeprom:
+        typeof parsed.saveToEeprom === "boolean"
+          ? parsed.saveToEeprom
+          : DEFAULT_KEYBOARD_CONFIG.saveToEeprom,
+      cliPath: typeof parsed.cliPath === "string" ? parsed.cliPath : undefined,
+    };
+  } catch {
+    return { ...DEFAULT_KEYBOARD_CONFIG };
+  }
+}
+
+export function writeKeyboardConfig(config: KeyboardConfig): void {
+  const filePath = keyboardConfigPath();
+  try {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+  } catch {
+    // Non-fatal config write failure
+  }
+}

package/src/driver.ts

@@ -0,0 +1,166 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import {
+  KEYBOARD_STATE_DEFINITIONS,
+  type KeyboardConfig,
+  type KeyboardDeviceInfo,
+  type KeyboardState,
+} from "./types";
+
+const execFileAsync = promisify(execFile);
+
+let activeBlinkTimer: NodeJS.Timeout | null = null;
+let commandQueue: Promise<void> = Promise.resolve();
+
+export function resolveCliPath(customPath?: string): string {
+  if (customPath && existsSync(customPath)) {
+    return customPath;
+  }
+
+  const standardPaths = [
+    join(homedir(), ".local", "bin", "via-rgb"),
+    "/opt/homebrew/bin/via-rgb",
+    "/usr/local/bin/via-rgb",
+  ];
+
+  for (const p of standardPaths) {
+    if (existsSync(p)) {
+      return p;
+    }
+  }
+
+  return "via-rgb"; // fallback to PATH lookup
+}
+
+export interface HardwareApplyResult {
+  success: boolean;
+  state: KeyboardState;
+  zone: string;
+  error?: string;
+}
+
+export async function applyKeyboardState(
+  state: KeyboardState,
+  config: KeyboardConfig,
+): Promise<HardwareApplyResult> {
+  if (!config.enabled) {
+    return { success: true, state, zone: config.zone };
+  }
+
+  const def = KEYBOARD_STATE_DEFINITIONS[state];
+  if (!def) {
+    return { success: false, state, zone: config.zone, error: `Unknown state: ${state}` };
+  }
+
+  // Clear any ongoing software blink
+  if (activeBlinkTimer) {
+    clearInterval(activeBlinkTimer);
+    activeBlinkTimer = null;
+  }
+
+  const targetBrightness = Math.round(def.brightness * config.brightnessScale);
+  const cli = resolveCliPath(config.cliPath);
+
+  const baseArgs = ["--zone", config.zone];
+  if (!config.saveToEeprom) {
+    baseArgs.push("--no-save");
+  }
+
+  const task = async (): Promise<HardwareApplyResult> => {
+    try {
+      // Set color, effect, speed, brightness in memory
+      const setArgs = [
+        ...baseArgs,
+        "set",
+        "-b",
+        String(targetBrightness),
+        "-e",
+        String(def.effect),
+        "-s",
+        String(def.speed),
+        "-c",
+        `${def.hue} ${def.sat}`,
+      ];
+
+      await execFileAsync(cli, setArgs, { timeout: 3000 });
+
+      // If state specifies a blinking alert (yellow / red), run a short asynchronous strobe
+      if (def.pattern === "blinking" && (def.blinkCount ?? 0) > 0) {
+        startSoftwareStrobe(cli, baseArgs, targetBrightness, def.blinkCount ?? 4);
+      }
+
+      return { success: true, state, zone: config.zone };
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { success: false, state, zone: config.zone, error: msg };
+    }
+  };
+
+  // Queue to ensure strictly ordered HID writes
+  commandQueue = commandQueue.then(
+    async () => {
+      await task();
+    },
+    async () => {
+      await task();
+    },
+  );
+  await commandQueue;
+  return { success: true, state, zone: config.zone };
+}
+
+function startSoftwareStrobe(
+  cli: string,
+  baseArgs: string[],
+  maxBrightness: number,
+  cycles: number,
+): void {
+  let step = 0;
+  const totalSteps = cycles * 2;
+
+  activeBlinkTimer = setInterval(() => {
+    step++;
+    const isBright = step % 2 === 0;
+    const brightness = isBright ? maxBrightness : 0;
+
+    execFile(cli, [...baseArgs, "set", "-b", String(brightness)], { timeout: 1500 }, () => {});
+
+    if (step >= totalSteps) {
+      if (activeBlinkTimer) {
+        clearInterval(activeBlinkTimer);
+        activeBlinkTimer = null;
+      }
+      // Restore target brightness at the end
+      execFile(cli, [...baseArgs, "set", "-b", String(maxBrightness)], { timeout: 1500 }, () => {});
+    }
+  }, 180);
+}
+
+export async function fetchKeyboardStatus(
+  config: KeyboardConfig,
+): Promise<{
+  connected: boolean;
+  device?: KeyboardDeviceInfo;
+  protocolVersion?: string;
+  error?: string;
+}> {
+  const cli = resolveCliPath(config.cliPath);
+  try {
+    const { stdout } = await execFileAsync(cli, ["--json", "status"], { timeout: 3000 });
+    const parsed = JSON.parse(stdout);
+    return {
+      connected: true,
+      device: parsed.device,
+      protocolVersion: parsed.protocol_version,
+    };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      connected: false,
+      error: msg,
+    };
+  }
+}

package/src/global-sessions.ts

@@ -0,0 +1,78 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export interface SessionRecord {
+  sessionId: string;
+  pid: number;
+  cwd: string;
+  status: "running" | "idle" | "settled" | "exited";
+  updatedAt: number;
+}
+
+export function getRegistryDir(): string {
+  return path.join(os.homedir(), ".pi", "agent", "directory-sessions");
+}
+
+export function isProcessAlive(pid: number): boolean {
+  if (!pid || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Scans all directory session registries to check if any other session is currently running.
+ * Automatically checks PID vitality and excludes dead or stale processes.
+ */
+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
+
+  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 {
+        sessionFiles = fs.readdirSync(subDirPath);
+      } catch {
+        continue;
+      }
+
+      for (const file of sessionFiles) {
+        if (!file.endsWith(".json")) continue;
+        const filePath = path.join(subDirPath, file);
+
+        try {
+          const content = fs.readFileSync(filePath, "utf-8");
+          const record = JSON.parse(content) as SessionRecord;
+
+          if (!record || typeof record !== "object") continue;
+          if (record.pid === excludePid) continue;
+
+          // Check if process is alive and actively running
+          if (record.status === "running" && isProcessAlive(record.pid)) {
+            if (now - (record.updatedAt || 0) < maxStaleAgeMs) {
+              return true;
+            }
+          }
+        } catch {
+          // Ignore unreadable or corrupt temp files
+        }
+      }
+    }
+  } catch {
+    return false;
+  }
+
+  return false;
+}

package/src/index.ts

@@ -0,0 +1,260 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import { readKeyboardConfig, writeKeyboardConfig } from "./config";
+import { fetchKeyboardStatus } from "./driver";
+import { KeyboardStateMachine } from "./state-machine";
+import {
+  KEYBOARD_STATE_DEFINITIONS,
+  type KeyboardConfig,
+  type KeyboardState,
+  type KeyboardZone,
+} from "./types";
+
+let stateMachine: KeyboardStateMachine | null = null;
+
+function getStateMachine(): KeyboardStateMachine {
+  if (!stateMachine) {
+    const config = readKeyboardConfig();
+    stateMachine = new KeyboardStateMachine(config);
+  }
+  return stateMachine;
+}
+
+export default function (pi: ExtensionAPI): void {
+  const sm = getStateMachine();
+  let terminalInputDetached: (() => void) | undefined;
+
+  // Pi Lifecycle Hooks
+  pi.on("session_start", async (_event, ctx) => {
+    // Attach passive terminal input / focus observer to detect thread activation
+    if (ctx.hasUI && typeof ctx.ui.onTerminalInput === "function" && !terminalInputDetached) {
+      terminalInputDetached = ctx.ui.onTerminalInput((_data: string) => {
+        if (sm.isUnread()) {
+          void sm.onUserActivated();
+        }
+        return undefined; // Passive observer: never consume or block input
+      });
+    }
+
+    await sm.onSessionStart();
+  });
+
+  pi.on("agent_start", async (_event, _ctx) => {
+    await sm.onAgentStart();
+  });
+
+  pi.on("turn_start", async (_event, _ctx) => {
+    await sm.onTurnStart();
+  });
+
+  pi.on("after_provider_response", async (event, _ctx) => {
+    // Detect upstream provider errors (429 rate limit, 401 auth, 500 error, etc.)
+    if (event.status && event.status >= 400) {
+      await sm.onProviderResponse(event.status);
+    }
+  });
+
+  pi.on("tool_call", async (event, _ctx) => {
+    const input = event.input && typeof event.input === "object" ? (event.input as Record<string, unknown>) : undefined;
+    await sm.onToolCall(event.toolName, input);
+  });
+
+  pi.on("tool_result", async (_event, _ctx) => {
+    await sm.onToolResult();
+  });
+
+  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)) {
+      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)) {
+      await sm.onMessageEnd(msg?.stopReason, msg?.errorMessage);
+    }
+  });
+
+  pi.on("agent_settled", async (_event, ctx) => {
+    let hasError = sm.hasError();
+
+    // Inspect session branch entries to detect trailing assistant errors
+    const branch = ctx.sessionManager?.getBranch?.();
+    if (branch && branch.length > 0) {
+      for (let i = branch.length - 1; i >= 0; i--) {
+        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)) {
+            hasError = true;
+          }
+          break;
+        }
+      }
+    }
+
+    await sm.onAgentSettled(hasError);
+  });
+
+  pi.on("input", async (_event, _ctx) => {
+    await sm.onUserInput();
+  });
+
+  pi.on("session_shutdown", async (_event, _ctx) => {
+    terminalInputDetached?.();
+    terminalInputDetached = undefined;
+    await sm.onShutdown();
+  });
+
+  // Register /keyboard Command & Menu
+  pi.registerCommand("keyboard", {
+    description: "Manage VIA/QMK keyboard RGB lighting status indicators",
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      const trimmed = args.trim().toLowerCase();
+
+      if (trimmed === "on") {
+        sm.updateConfig({ enabled: true });
+        writeKeyboardConfig(sm.getConfig());
+        ctx.ui.notify("Keyboard lighting indicator enabled", "info");
+        return;
+      }
+
+      if (trimmed === "off") {
+        sm.updateConfig({ enabled: false });
+        writeKeyboardConfig(sm.getConfig());
+        ctx.ui.notify("Keyboard lighting indicator disabled", "info");
+        return;
+      }
+
+      if (trimmed === "status") {
+        await showStatus(ctx, sm);
+        return;
+      }
+
+      if (trimmed.startsWith("test")) {
+        const parts = trimmed.split(/\s+/);
+        const targetState = (parts[1] || "thinking") as KeyboardState;
+        if (targetState in KEYBOARD_STATE_DEFINITIONS) {
+          await sm.transitionTo(targetState, true);
+          ctx.ui.notify(`Testing state: ${KEYBOARD_STATE_DEFINITIONS[targetState].labelZh}`, "info");
+        } else {
+          ctx.ui.notify(`Unknown test state. Options: ${Object.keys(KEYBOARD_STATE_DEFINITIONS).join(", ")}`, "error");
+        }
+        return;
+      }
+
+      // Interactive Menu
+      await openKeyboardMenu(ctx, sm);
+    },
+  });
+}
+
+async function showStatus(ctx: ExtensionCommandContext, sm: KeyboardStateMachine): Promise<void> {
+  const config = sm.getConfig();
+  const hw = await fetchKeyboardStatus(config);
+  const current = sm.getCurrentState();
+
+  const lines = [
+    `Indicator Status : ${config.enabled ? "Enabled (On)" : "Disabled (Off)"}`,
+    `Current State    : ${sm.getStateLabel(current)}`,
+    `Active Zone      : ${config.zone.toUpperCase()}`,
+    `Brightness Scale : ${Math.round(config.brightnessScale * 100)}%`,
+    `Hardware Status  : ${hw.connected ? `Connected (${hw.device?.product || "VIA Keyboard"})` : "Not connected / Not detected"}`,
+  ];
+
+  ctx.ui.notify(lines.join("\n"), "info");
+}
+
+async function openKeyboardMenu(
+  ctx: ExtensionCommandContext,
+  sm: KeyboardStateMachine,
+): Promise<void> {
+  const config = sm.getConfig();
+  const current = sm.getCurrentState();
+
+  const toggleOption = config.enabled ? "Disable lighting indicator" : "Enable lighting indicator";
+  const mainOptions = [
+    toggleOption,
+    "Test Lighting States (Idle, Thinking, Unread, Approval, Error)",
+    `Set Active Zone (Current: ${config.zone.toUpperCase()})`,
+    `Set Brightness Scale (Current: ${Math.round(config.brightnessScale * 100)}%)`,
+    "View Hardware Status",
+  ];
+
+  const choice = await ctx.ui.select(
+    `Keyboard Lighting [${config.enabled ? "ON" : "OFF"} · State: ${sm.getStateLabel(current)}]`,
+    mainOptions,
+  );
+
+  if (!choice) return;
+
+  if (choice === toggleOption) {
+    const next = !config.enabled;
+    sm.updateConfig({ enabled: next });
+    writeKeyboardConfig(sm.getConfig());
+    ctx.ui.notify(`Keyboard lighting indicator is now ${next ? "ON" : "OFF"}`, "info");
+    return;
+  }
+
+  if (choice.startsWith("Test Lighting States")) {
+    const stateKeys = Object.keys(KEYBOARD_STATE_DEFINITIONS) as KeyboardState[];
+    const stateOptions = stateKeys.map((st) => KEYBOARD_STATE_DEFINITIONS[st].labelZh);
+    const stateChoice = await ctx.ui.select("Select a state to test on keyboard:", stateOptions);
+    if (stateChoice) {
+      const idx = stateOptions.indexOf(stateChoice);
+      const chosenState = stateKeys[idx];
+      if (chosenState) {
+        await sm.transitionTo(chosenState, true);
+        ctx.ui.notify(`Applied state: ${KEYBOARD_STATE_DEFINITIONS[chosenState].labelZh}`, "info");
+      }
+    }
+    return;
+  }
+
+  if (choice.startsWith("Set Active Zone")) {
+    const zoneOptions = [
+      "All Zones (Both Backlight & Underglow)",
+      "Per-Key Backlight Matrix (Channel 3)",
+      "Underglow / Side Strips (Channel 2)",
+    ];
+    const zoneChoice = await ctx.ui.select("Select target lighting zone:", zoneOptions);
+    if (zoneChoice) {
+      const zoneMap: Record<string, KeyboardZone> = {
+        "All Zones (Both Backlight & Underglow)": "all",
+        "Per-Key Backlight Matrix (Channel 3)": "matrix",
+        "Underglow / Side Strips (Channel 2)": "underglow",
+      };
+      const zone = zoneMap[zoneChoice] || "all";
+      sm.updateConfig({ zone });
+      writeKeyboardConfig(sm.getConfig());
+      ctx.ui.notify(`Active zone set to: ${zone.toUpperCase()}`, "info");
+    }
+    return;
+  }
+
+  if (choice.startsWith("Set Brightness Scale")) {
+    const scaleOptions = ["100% Brightness", "75% Brightness", "50% Brightness", "25% Brightness"];
+    const scaleChoice = await ctx.ui.select("Select brightness scale:", scaleOptions);
+    if (scaleChoice) {
+      const scaleMap: Record<string, number> = {
+        "100% Brightness": 1.0,
+        "75% Brightness": 0.75,
+        "50% Brightness": 0.50,
+        "25% Brightness": 0.25,
+      };
+      const scale = scaleMap[scaleChoice] ?? 1.0;
+      sm.updateConfig({ brightnessScale: scale });
+      writeKeyboardConfig(sm.getConfig());
+      ctx.ui.notify(`Brightness scale set to ${Math.round(scale * 100)}%`, "info");
+    }
+    return;
+  }
+
+  if (choice === "View Hardware Status") {
+    await showStatus(ctx, sm);
+  }
+}

package/src/protocol.ts

@@ -0,0 +1,62 @@
+import type { KeyboardZone } from "./types";
+
+export const VIA_RAW_USAGE_PAGE = 0xff60;
+export const VIA_RAW_USAGE = 0x0061;
+
+export const CMD_GET_PROTOCOL_VERSION = 0x01;
+export const CMD_CUSTOM_SET_VALUE = 0x07;
+export const CMD_CUSTOM_GET_VALUE = 0x08;
+export const CMD_CUSTOM_SAVE = 0x09;
+
+export const CH_RGBLIGHT = 2; // Zone 1: Side strip / Underglow
+export const CH_RGB_MATRIX = 3; // Zone 2: Per-key RGB Matrix
+
+export const VAL_BRIGHTNESS = 1;
+export const VAL_EFFECT = 2;
+export const VAL_EFFECT_SPEED = 3;
+export const VAL_COLOR = 4;
+
+export function resolveChannels(zone: KeyboardZone): number[] {
+  switch (zone) {
+    case "underglow":
+      return [CH_RGBLIGHT];
+    case "matrix":
+      return [CH_RGB_MATRIX];
+    case "all":
+    default:
+      return [CH_RGBLIGHT, CH_RGB_MATRIX];
+  }
+}
+
+export function buildPacket(payload: number[]): Uint8Array {
+  const packet = new Uint8Array(32);
+  for (let i = 0; i < payload.length && i < 32; i++) {
+    packet[i] = payload[i];
+  }
+  return packet;
+}
+
+export function buildSetBrightnessPacket(channel: number, brightness: number): Uint8Array {
+  const val = Math.max(0, Math.min(255, Math.round(brightness)));
+  return buildPacket([CMD_CUSTOM_SET_VALUE, channel, VAL_BRIGHTNESS, val]);
+}
+
+export function buildSetEffectPacket(channel: number, effect: number): Uint8Array {
+  const val = Math.max(0, Math.min(255, Math.round(effect)));
+  return buildPacket([CMD_CUSTOM_SET_VALUE, channel, VAL_EFFECT, val]);
+}
+
+export function buildSetSpeedPacket(channel: number, speed: number): Uint8Array {
+  const val = Math.max(0, Math.min(255, Math.round(speed)));
+  return buildPacket([CMD_CUSTOM_SET_VALUE, channel, VAL_EFFECT_SPEED, val]);
+}
+
+export function buildSetColorPacket(channel: number, hue: number, sat: number): Uint8Array {
+  const h = Math.max(0, Math.min(255, Math.round(hue)));
+  const s = Math.max(0, Math.min(255, Math.round(sat)));
+  return buildPacket([CMD_CUSTOM_SET_VALUE, channel, VAL_COLOR, h, s]);
+}
+
+export function buildSavePacket(channel: number): Uint8Array {
+  return buildPacket([CMD_CUSTOM_SAVE, channel]);
+}

package/src/state-machine.ts

@@ -0,0 +1,176 @@
+import { applyKeyboardState } from "./driver";
+import { hasOtherRunningSessions } from "./global-sessions";
+import {
+  KEYBOARD_STATE_DEFINITIONS,
+  type KeyboardConfig,
+  type KeyboardState,
+} from "./types";
+
+export class KeyboardStateMachine {
+  private currentState: KeyboardState = "idle";
+  private isProcessing = false;
+  private hasUnreadChat = false;
+  private hasFatalError = false;
+
+  constructor(
+    private config: KeyboardConfig,
+    private checkOtherRunning: () => boolean = () => hasOtherRunningSessions(),
+  ) {}
+
+  public getConfig(): KeyboardConfig {
+    return { ...this.config };
+  }
+
+  public updateConfig(newConfig: Partial<KeyboardConfig>): void {
+    this.config = { ...this.config, ...newConfig };
+    this.applyCurrentState(true);
+  }
+
+  public getCurrentState(): KeyboardState {
+    return this.currentState;
+  }
+
+  public isUnread(): boolean {
+    return this.hasUnreadChat;
+  }
+
+  public hasError(): boolean {
+    return this.hasFatalError;
+  }
+
+  public getStateLabel(state: KeyboardState = this.currentState): string {
+    return KEYBOARD_STATE_DEFINITIONS[state]?.labelZh ?? state;
+  }
+
+  public async transitionTo(nextState: KeyboardState, force = false): Promise<void> {
+    if (this.currentState === nextState && !force) {
+      return;
+    }
+    this.currentState = nextState;
+    await this.applyCurrentState(force);
+  }
+
+  private async applyCurrentState(force = false): Promise<void> {
+    await applyKeyboardState(this.currentState, this.config);
+  }
+
+  public async onSessionStart(): Promise<void> {
+    this.isProcessing = false;
+    this.hasUnreadChat = false;
+    this.hasFatalError = false;
+
+    if (this.checkOtherRunning()) {
+      await this.transitionTo("thinking");
+    } else {
+      await this.transitionTo("idle");
+    }
+  }
+
+  public async onAgentStart(): Promise<void> {
+    this.isProcessing = true;
+    this.hasUnreadChat = false;
+    this.hasFatalError = false;
+    await this.transitionTo("thinking");
+  }
+
+  public async onTurnStart(): Promise<void> {
+    this.isProcessing = true;
+    this.hasUnreadChat = false;
+    this.hasFatalError = false;
+    await this.transitionTo("thinking");
+  }
+
+  public async onToolCall(toolName: string, _input?: Record<string, unknown>): Promise<void> {
+    this.isProcessing = true;
+    const isInteractive =
+      toolName.includes("confirm") ||
+      toolName.includes("ask") ||
+      toolName.includes("prompt") ||
+      toolName === "question";
+
+    if (isInteractive) {
+      await this.transitionTo("need_approval");
+    } else {
+      await this.transitionTo("thinking");
+    }
+  }
+
+  public async onToolResult(): Promise<void> {
+    if (this.isProcessing) {
+      await this.transitionTo("thinking");
+    }
+  }
+
+  public async onProviderResponse(status?: number): Promise<void> {
+    if (typeof status === "number" && status >= 400) {
+      this.hasFatalError = true;
+      this.isProcessing = false;
+      this.hasUnreadChat = false;
+      await this.transitionTo("error");
+    }
+  }
+
+  public async onMessageEnd(stopReason?: string, errorMessage?: string): Promise<void> {
+    if (stopReason === "error" || stopReason === "aborted" || Boolean(errorMessage)) {
+      this.hasFatalError = true;
+      this.isProcessing = false;
+      this.hasUnreadChat = false;
+      await this.transitionTo("error");
+    }
+  }
+
+  public async onAgentSettled(hasError = false): Promise<void> {
+    this.isProcessing = false;
+    if (hasError || this.hasFatalError) {
+      this.hasFatalError = true;
+      this.hasUnreadChat = false;
+      await this.transitionTo("error");
+    } else {
+      this.hasUnreadChat = true;
+      await this.transitionTo("unread_chat");
+    }
+  }
+
+  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");
+    }
+  }
+
+  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");
+    }
+  }
+
+  public async onError(): Promise<void> {
+    this.isProcessing = false;
+    this.hasFatalError = true;
+    this.hasUnreadChat = false;
+    await this.transitionTo("error");
+  }
+
+  public async onShutdown(): Promise<void> {
+    if (this.checkOtherRunning()) {
+      await this.transitionTo("thinking");
+    } else {
+      await this.transitionTo("idle");
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,98 @@
+export type KeyboardState =
+  | "idle"
+  | "unread_chat"
+  | "thinking"
+  | "need_approval"
+  | "error";
+
+export type KeyboardZone = "all" | "underglow" | "matrix";
+
+export type KeyboardPattern = "breathing" | "blinking" | "solid";
+
+export interface KeyboardStateDefinition {
+  state: KeyboardState;
+  label: string;
+  labelZh: string;
+  hue: number;
+  sat: number;
+  effect: number; // 1 = solid, 2 = breathing
+  speed: number;
+  brightness: number;
+  pattern: KeyboardPattern;
+  blinkCount?: number;
+}
+
+export interface KeyboardConfig {
+  enabled: boolean;
+  zone: KeyboardZone;
+  brightnessScale: number; // 0.1 to 1.0 (default 1.0)
+  saveToEeprom: boolean; // default false: strictly in-memory (--no-save)
+  cliPath?: string;
+}
+
+export interface KeyboardDeviceInfo {
+  vendorId: string;
+  productId: string;
+  product?: string;
+  manufacturer?: string;
+}
+
+export const KEYBOARD_STATE_DEFINITIONS: Record<KeyboardState, KeyboardStateDefinition> = {
+  idle: {
+    state: "idle",
+    label: "White Breathing (Idle)",
+    labelZh: "白色 呼吸灯 (空闲待命)",
+    hue: 0,
+    sat: 0, // White
+    effect: 2, // Breathing
+    speed: 100,
+    brightness: 180,
+    pattern: "breathing",
+  },
+  unread_chat: {
+    state: "unread_chat",
+    label: "Green Breathing (Unread Chat)",
+    labelZh: "绿色 呼吸灯 (未读消息)",
+    hue: 85, // Green
+    sat: 255,
+    effect: 2, // Breathing
+    speed: 150,
+    brightness: 220,
+    pattern: "breathing",
+  },
+  thinking: {
+    state: "thinking",
+    label: "Blue Breathing (Thinking)",
+    labelZh: "蓝色 呼吸灯 (正在思考/执行)",
+    hue: 170, // Blue
+    sat: 255,
+    effect: 2, // Breathing
+    speed: 200,
+    brightness: 255,
+    pattern: "breathing",
+  },
+  need_approval: {
+    state: "need_approval",
+    label: "Yellow Blinking (Need Approval / Question)",
+    labelZh: "黄色 闪烁 (需要确认/提问)",
+    hue: 43, // Yellow
+    sat: 255,
+    effect: 1, // Alert / Fast pulse
+    speed: 255,
+    brightness: 255,
+    pattern: "blinking",
+    blinkCount: 4,
+  },
+  error: {
+    state: "error",
+    label: "Red Blinking (Error)",
+    labelZh: "红色 闪烁 (异常错误)",
+    hue: 0, // Red
+    sat: 255,
+    effect: 1, // Alert / Fast pulse
+    speed: 255,
+    brightness: 255,
+    pattern: "blinking",
+    blinkCount: 4,
+  },
+};