agentdock-pi-plugin0.3.0

AgentDock pi extension

A pi coding agent extension that bridges AgentDock hardware to pi over BLE.

It connects to an AgentDock-XXXX device, forwards key and encoder events to the pi API, and pushes the agent state back to the device so the LED shows what the agent is doing.

Requirements

• Node.js 22 or newer
• Bluetooth LE support on the host
• The AgentDock firmware from ../firmware

On macOS, grant Bluetooth permission to the terminal application the first time the extension scans.

Install

Install it as a pi package:

pi install npm:agentdock-pi-plugin

To pin a version: pi install npm:agentdock-pi-plugin@0.3.0. Project scope: add -l. Remove with pi remove npm:agentdock-pi-plugin.

@stoprocent/noble is a native BLE binding installed as a dependency. On Linux you may need the Bluetooth headers first (for example libbluetooth-dev on Debian/Ubuntu).

Load without installing

During development:

pi --extension /absolute/path/to/agentdock/pi-plugin/index.ts

Or try the npm tarball for a single invocation:

pi -e npm:agentdock-pi-plugin

Usage

Run /dock inside pi to open the management panel:

• select or rebind a device
• edit the KEY2 / KEY3 macros
• test LED states (including auto, which plays the full seven-colour cycle once)
• set LED brightness and buzzer volume (applied live, persisted on the device)
• force a reconnect

Configuration is stored in ~/.pi/agent/agentdock.json:

{
  "preferredDevice": "AgentDock-A1B2",
  "macros": ["继续", "不对"],
  "brightness": 100,
  "volume": 100
}

brightness / volume are a display cache only: the device's own NVS is the source of truth, and the values reported by the device on connect overwrite the local ones.

Controls

Device input	pi action
KEY1 short press	Abort the current run
KEY1 long press	Toggle the device buzzer mute (device-local)
KEY2 short press	Send macro 0 (default 继续)
KEY2 long press	Demo mode: bugle fanfare + seven-colour breathing LED (3 s, device-local)
KEY3 short press	Send macro 1 (default 不对)
KEY3 long press	Toggle the encoder click sound (device-local)
Encoder push	Send 继续
Encoder rotate	Scroll the transcript by ±3 lines per step

LED states

State	Meaning
Dim blue	Idle
Green breathing	Agent is running
White double flash	Run finished
Red triple flash	A tool returned an error
Seven-colour breathing	Demo / auto LED test (3 s)
Very dim blue heartbeat	Not connected

Transcript scrolling

Scrolling relies on pi's fullscreen TUI internals. If the API is unavailable in your pi version, encoder events are logged and other features keep working.

Protocol

The extension talks to firmware/main/deck.c over a custom GATT service:

• Service: 8e7c1a10-c0de-4b1e-9f6a-000000000001
• EVENT notify (device → host): 8e7c1a10-c0de-4b1e-9f6a-000000000002
• STATE write (host → device): 8e7c1a10-c0de-4b1e-9f6a-000000000003

// device -> host
{"k":"key","id":2}
{"k":"enc","v":-1}
{"k":"cfg","b":100,"v":80,"m":0,"c":1}   // 设备设置快照 (连接后立即推一次)

// host -> device
{"t":"s","st":"busy"}     // idle | busy | done | error | demo
{"t":"cfg","b":80,"v":60} // 亮度 / 音量 0~100 (设备落 NVS)

Development

npm install
npm run typecheck   # tsc --noEmit
npm test            # vitest: 纯逻辑 + /dock 面板渲染与交互
npm run check:pack  # 校验 npm tarball 内容 (入口齐全、无测试泄漏)

Publishing is described in PUBLISHING.md, or in short:

npm version patch
npm publish --registry https://registry.npmjs.com/

单测不依赖真实蓝牙硬件: BLE 通道与 pi 的 ctx.ui 都是 mock 的, 主题用真实 ANSI 转义以保证宽度计算与线上一致。

Troubleshooting

• Extension logs are prefixed with [agentdock] in non-TUI modes.
• macOS: check System Settings → Privacy & Security → Bluetooth for the terminal application.
• The extension scans for 8 seconds and retries every 5 seconds. The device shows a dim blue heartbeat while it is not connected.
• Use npm run scan to list all visible BLE devices and verify that the device is advertising.