feat(events-shim): wake idle Factory Droid, Cursor CLI and Amp sessions on each post

Merged
KH
6d ago
+808-25

Summary

@agent-relay/events-shim setup --droid, --cursor and --amp now wake an idle session of that CLI with each webhook post, with or without Agent Relay. All three reuse the listen --stop-hook <cli> wait from #2182.

This builds on #2182 (branch feat/events-shim-more-clis, not merged yet). The diff against main includes #2182's two commits. Only the last commit is new here.

  • Factory Droid: a Stop hook (7-day timeout) that answers decision: "block", so the post becomes Droid's next instruction. Droid reads ~/.factory/hooks.json and only falls back to the hooks key of settings.json when that file is absent. So the hook goes into whichever file Droid reads, and a person whose hooks live in settings.json keeps them. droid mcp add … --type http; the skill is installed to ~/.factory/skills.
  • Cursor CLI: a stop hook in ~/.cursor/hooks.json (loop_limit: null) that answers followup_message. Cursor ends a hook after an hour, so the wait stops a minute before that. Cursor waits for every stop hook before it submits a follow-up (measured: a 120 s neighbour delayed the wake to 110 s). So while Agent Relay's own cursor-hook --wait entry is installed, our hook never holds the turn and setup says posts are read when asked. Otherwise the two waits would block each other's messages. Before this change Cursor was when-asked.
  • Amp: setup writes ~/.config/amp/plugins/agent-relay-webhooks.ts. Its agent.end handler runs listen --stop-hook amp and returns action: "continue" with the post (maxContinuations raised from Amp's default 5). agent.start stops the wait when the person starts a turn. A post that was already claimed is returned at the end of that turn. Current Amp loads the plugin by default; older builds need PLUGINS=all.
  • Replicas and Capy: not added. Both run their agents in the cloud, and the desktop apps are clients (Capy's package describes itself as "runs your coding agents in the cloud"; Replicas.app wraps app.replicas.dev). There is no local session to wake. The hosted bind_replica / bind_capy_thread already cover their cloud chats.

Live proof (macOS, isolated HOMEs, interactive in detached tmux)

Each session got one first message, finished its turn and sat idle. Then a uniquely tagged JSON post went to its inbox, and the session answered WOKE <tag> by itself. Time-to-wake is measured from the POST to the reply appearing in the pane, so it includes the model's turn.

CLIVersionWakesTime to wake
Factory Droid1.12.13/37.9 s, 8.3 s, 10.8 s
Cursor CLI2026.10.225/59.0, 6.3, 7.3, 7.6, 7.2 s
Amp0.0.17947584292/25.7 s, 5.7 s

Also checked live:

  • Droid: pressing Esc cancels the hook process, and no listener is left behind.
  • Droid: text typed during the wait queues until the next post (hence the "press Esc first" caveat).
  • Cursor: a newer turn's hook takes over the older one.
  • Cursor: with an Agent Relay cursor-hook --wait entry present, our hook answers {} at once.
  • Amp: a turn the person starts mid-wait runs normally, and the next post still wakes the thread.
  • Amp: the listener exits once Amp quits.

Tests

npx vitest run packages/events-shim/src: 100 passed. New tests cover:

  • Droid: hooks go into settings.json beside the person's hooks while hooks.json is absent, or into hooks.json otherwise; setup refuses to overwrite a file it cannot parse; uninstall takes out only ours.
  • Cursor: hooks are written next to the person's own; the hold-back when Agent Relay's wait entry exists.
  • Amp: the plugin file and the MCP add.
  • The Amp plugin itself, run against a stand-in hook: it answers agent.end, and agent.start stops the wait.
  • listen --stop-hook droid|cursor|amp answer shapes; runs that don't end a finished turn; Droid's transcript release.

🤖 Generated with Claude Code


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.