aboutsummaryrefslogtreecommitdiffstats
path: root/docs/superpowers
diff options
context:
space:
mode:
Diffstat (limited to 'docs/superpowers')
-rw-r--r--docs/superpowers/specs/2026-11-16-agent-lamp-design.md171
1 files changed, 171 insertions, 0 deletions
diff --git a/docs/superpowers/specs/2026-11-16-agent-lamp-design.md b/docs/superpowers/specs/2026-11-16-agent-lamp-design.md
new file mode 100644
index 0000000..c65536d
--- /dev/null
+++ b/docs/superpowers/specs/2026-11-16-agent-lamp-design.md
@@ -0,0 +1,171 @@
+# agent-lamp design
+
+Date: 2026-11-16. Status: approved in brainstorming, not yet built.
+
+## Goal
+
+Turn the IKEA TRADFRI colour bulb into a notification light for coding
+agents (Claude Code and opencode), so a glance at the room says whether an
+agent needs something. The bulb stops following the wallpaper accent:
+`udt-bulb` is retired and the bulb's only job becomes agent notifications.
+
+## States and colours
+
+| State | Meaning | Colour |
+|--------------|------------------------------------------|--------|
+| `permission` | agent waits for a permission decision | purple |
+| `question` | agent waits for user input (questions) | amber |
+| `error` | agent failed or is blocked | red |
+| `complete` | agent finished its turn | green |
+
+Colours are module constants in `#rrggbb`, tuned on the real bulb.
+
+Display rules, evaluated every tick over all active sessions:
+
+- No active state: restore the bulb to its pre-notification snapshot, exit.
+- One distinct colour: that colour, steady, full brightness.
+- One distinct colour, and it is `permission` or `question` waiting longer
+ than `ESCALATE` (120 s): soft breathe, brightness fading between high and
+ low. This is the "still waiting" signal.
+- Several distinct colours (e.g. an error in one agent and a permission in
+ another): slow crossfade cycle through them, about 4 s per colour.
+ Escalation is not shown in this mode; the cycle already draws the eye.
+
+## Architecture
+
+One executable Python script, `agent-lamp`, stdlib only, calling libcoap's
+`coap-client` for CoAP over DTLS-PSK (Python's stdlib cannot speak DTLS).
+Symlinked as `~/bin/agent-lamp`.
+
+### CLI
+
+ agent-lamp <state> <session> set or clear one session's state
+ agent-lamp claude read a Claude Code hook payload on stdin
+ agent-lamp reset clear every session, restore the bulb
+ agent-lamp --pair HOST CODE pair with the gateway, record colour bulbs
+ agent-lamp --selftest
+ agent-lamp --run internal: the renderer loop
+
+`<state>` accepts `permission`, `question`, `complete`, `error`, `clear`,
+plus the opencode-notifier aliases `user_message` and `user_cancelled`
+(both meaning `clear`). Any other word (e.g. `session_started`,
+`subagent_complete`) is ignored with exit 0, so callers never break.
+
+### Claude Code mapping (`agent-lamp claude`)
+
+Reads the hook JSON (`hook_event_name`, `session_id`, `notification_type`,
+`tool_name`):
+
+| Hook | State |
+|---------------------------------------------|--------------|
+| Notification, `permission_prompt` | `permission` |
+| Notification, `elicitation_dialog` | `question` |
+| PreToolUse, tool `AskUserQuestion` | `question` |
+| Stop | `complete` |
+| StopFailure | `error` |
+| PostToolUse, UserPromptSubmit, SessionEnd | `clear` |
+
+Other notification types (`idle_prompt`, `auth_success`) are ignored. All
+hooks are registered `async` in `~/.claude/settings.json` so the lamp never
+slows the agent.
+
+### opencode mapping
+
+The `@mohak34/opencode-notifier` plugin already runs one command for every
+event: `~/bin/notify-sound`. Its args become `["{event}", "{sessionID}"]`,
+and `notify-sound` forwards to `agent-lamp "$1" "$2"` in the background when
+it gets two arguments, before its quiet-mode check (quiet mutes sound, not
+the lamp). Claude Code calls `notify-sound claude` with one argument, so it
+is not forwarded and Claude events are never handled twice.
+
+Known limit: the notifier has no "permission granted" event, so an opencode
+permission stays purple until that session's next event or user message.
+
+### State
+
+`$XDG_RUNTIME_DIR/agent-lamp/state.json`, `{session: {"state": s, "since":
+epoch}}`, read and written under `flock` on `state.lock`. A session holds at
+most one state; a new event replaces it, `clear` removes only that session.
+`reset` empties the file.
+
+### Renderer
+
+Every state change spawns `agent-lamp --run` detached (`setsid`). `--run`
+takes a blocking `flock` on `run.lock`, so exactly one renderer drives the
+bulb and a late spawn waits its turn and then re-reads the state (it exits
+at once if empty). This avoids the race where an exiting renderer misses an
+event written while it restores the bulb.
+
+On start the renderer snapshots each bulb (`5850` on/off, `5851`
+brightness, `5709`/`5710` colour xy). Each tick it reads the state and
+applies the display rules, sending only what changed. When no state is left
+it restores the snapshot and exits, all while holding the state lock, so the
+decision to exit and the restore cannot interleave with a new event.
+
+"No lamp" mode: if `$XDG_RUNTIME_DIR/status.nolamp` holds `1`, the renderer
+restores the snapshot and idles (state kept). When the mode turns off it
+re-snapshots and resumes. The file is the quickshell `statusctl` mode
+format, read directly so quickshell need not be running.
+
+### Gateway facts carried over from udt-bulb (verified on the real bulb)
+
+- Hue and saturation run 0..65279, brightness 0..254, `5712` transition in
+ tenths of a second.
+- Any colour change switches a bulb on. Restoring an off bulb therefore sets
+ colour first, then `5850: 0`.
+- A request setting colour and brightness at once stalls mid-fade, and a
+ colour sent during a brightness fade is dropped. Colour and brightness go
+ in separate requests, colour first, and the renderer never overlaps them
+ (breathe changes brightness only, cycle changes colour only).
+- Pastel colours wash out to white; saturation is floored at 1.0.
+- After resume or login the gateway can take seconds to answer. A request
+ that fails is retried on the next tick rather than waited for.
+
+### Config
+
+`~/.config/agent-lamp/tradfri.json` (`host`, `identity`, `key`, `bulbs`),
+mode 0600, written by `--pair`. The existing `~/.config/udt/tradfri.json`
+is copied there once, so no re-pairing. No config or no `coap-client`:
+every command is a silent no-op.
+
+## Cross-repo changes (retiring udt-bulb)
+
+- unified-desktop-theme: delete `bin/udt-bulb`; drop it from `install.sh`
+ (link list and the post-install run) and from `udt-accent`'s helper lists;
+ remove the bulb section from its AGENTS.md (and README if mentioned).
+- rofi-scripts `bin/udt-powermenu.sh`: `udt-bulb off` becomes
+ `agent-lamp reset`.
+- hypr-theme `hypridle.conf`: `udt-bulb off` becomes `agent-lamp reset`;
+ `udt-bulb on` after sleep is dropped. `sections/autostart.lua`: the
+ shutdown hook runs `setsid -f agent-lamp reset` instead.
+- quickshell: `statusctl` gains a `nolamp` mode; the drawer gets a switch
+ for it beside the other status toggles. `notify-sound` gains the forward
+ to `agent-lamp`.
+- `~/.claude/settings.json`: async hooks calling `agent-lamp claude` for
+ Notification, PreToolUse (matcher `AskUserQuestion`), PostToolUse, Stop,
+ StopFailure, UserPromptSubmit, SessionEnd.
+- `~/.config/opencode/opencode-notifier.json`: command args
+ `["{event}", "{sessionID}"]`.
+- Global AGENTS.md: a short operational entry saying the lamp exists, is
+ driven automatically by hooks, and that `agent-lamp <state> <session>`
+ is available for manual signalling.
+- `~/.config/udt/tradfri.json` removed after the copy is verified.
+- my-dotfiles is a generated backup and is not touched.
+
+## Testing
+
+`agent-lamp --selftest`, asserts only, `coap` faked:
+
+- state-word mapping, including notifier aliases and ignored words;
+- Claude hook JSON to state for every row of the mapping table;
+- the display rule chosen for: empty, one colour, escalated one colour,
+ several colours;
+- `light_states` hue/saturation for a sample colour.
+
+On the real bulb, by hand: each state, escalation after 120 s, a two-colour
+cycle, nolamp toggle, and restore to both an on and an off bulb.
+
+## Out of scope
+
+Per-bulb assignment, a long-lived service, stale-session expiry (logout's
+`agent-lamp reset` clears leftovers), Zigbee without the gateway.