macro-ctrl

MacroCtrl is a Windows tray application that drives a four-key SayoDevice macro keypad, mapping agent sessions to keys with per-key LED feedback. It exposes a small HTTP API on port 10789 so external tools can push session events, read the current state, and reset the controller.

HTTP API

POST /event

Report a session state change. status is one of working, waiting, done, or inactive.

curl -X POST localhost:10789/event \
  -H 'Content-Type: application/json' \
  -d '{"session":"abc","status":"working"}'

GET /status

Return the command program, every slot, and a monotonic etag.

curl localhost:10789/status
# { "commandProgram": "calc.exe",
#   "slots": [ { "index": 0, "session": "abc", "status": "active" } ],
#   "etag": 7 }

POST /reset

Clear all slots and sessions. Requires If-Match with the current ETag, or ?force=true to bypass the check.

curl -X POST localhost:10789/reset -H 'If-Match: "7"'
curl -X POST 'localhost:10789/reset?force=true'

Configuration

MacroCtrl reads config.json from the application directory at startup. If the file is absent, the command program defaults to calc.exe and no sessions are excluded.

{
  "program": "calc.exe",
  "sessionExclude": [
    "copilot-call_*"
  ]
}

program is launched by the final keypad key. sessionExclude accepts simple wildcard patterns (* and ?); matching session IDs are ignored before they can claim or update a slot.

Controller Logic

MacroController routes session events to keypad slots. The final key is reserved for launching a bound application (e.g. calc.exe); every preceding key is a session slot. New sessions claim the first empty slot and are dropped when all slots are full. Each slot is a small state machine: working shows solid blue, waiting breathes orange, done shows solid green, and inactive fades out green before releasing the session. Pressing a waiting slot's hotkey activates it immediately and focuses its session. Every state change increments a version counter that is surfaced as the /status ETag and enforced by /reset.