Skip to content

feat(channel): gate sensor startup on end-to-end channel handshake#3

Merged
daibor merged 1 commit intomainfrom
feat/channel-handshake-gate
Apr 27, 2026
Merged

feat(channel): gate sensor startup on end-to-end channel handshake#3
daibor merged 1 commit intomainfrom
feat/channel-handshake-gate

Conversation

@daibor
Copy link
Copy Markdown
Collaborator

@daibor daibor commented Apr 27, 2026

Summary

  • Boot sends a single channel notification 5s post-init asking Claude to call the new confirm_channel_received tool. The ack is the proof that notifications/claude/channel is being delivered, so sensor polling (and the dedup state in ~/.world2agent/state.json) only starts on a known-good channel — every channel-enabled session opens with a clean baseline and no signals get silently swallowed by stale seen_ids from a previous non-channel launch.
  • Adds a "ready" channel notification right after applyConfig succeeds with the running sensor list, so users see one short Claude-authored confirmation that World2Agent is up and which sources it's watching.
  • start_sensors / reload_sensors await the same gate and return a clear help message if the channel never acked, so /world2agent:sensor-add can't half-write state in a non-channel session.
  • Persistent boot/lifecycle log at ~/.world2agent/channel.log for inspecting the handshake trace without re-instrumenting the bundle.
  • Bumps plugin manifest to 0.1.0-alpha.2.

Why the 5s delay

Empirically, channel notifications fired in the first ~1ms after oninitialized go missing from the session transcript — Claude Code finishes wiring up its channel listener slightly after the MCP init handshake completes. Notifications fired ≥100ms post-init are reliably consumed; 5s gives the listener plenty of headroom, and the confirm_channel_received ack typically arrives ~9s later.

Test plan

  • Launch with claude --dangerously-load-development-channels plugin:world2agent@world2agent-plugins, no sensor config changes — verify channel.log shows handshake fire → ack → sensor started, and Claude posts a one-sentence "World2Agent is ready" message.
  • Launch plain claude (no flag) — verify the plugin sits idle, sensor does not start, state.json is not written.
  • In a plain claude session, run /world2agent:sensor-add — verify the slash command's final reload_sensors call returns the channel-disabled help text and Claude tells the user to relaunch with the flag.
  • Tail ~/.world2agent/channel.log and confirm the boot trace lines describe the lifecycle in order (Connecting → Connected → handshake fire → ack → Starting sensor(s) → Started → Sending ready notification).
  • After a successful handshake, exit the session — verify the channel subprocess goes away (ps | grep world2agent).

🤖 Generated with Claude Code

Boot now sends a single channel notification 5s post-init asking Claude to
call the new confirm_channel_received tool. The ack proves that
notifications/claude/channel is being delivered before any sensor starts
polling, so dedup state in ~/.world2agent/state.json only accumulates
when the client is actively consuming signals — every channel-enabled
session starts clean from a known-good baseline.

- 30s deadline for the ack; absent that, sensors stay offline for the session
- After applyConfig succeeds, a "ready" channel notification announces the
  active sensor list so users get a single-sentence confirmation
- start_sensors / reload_sensors await channelReady and return a clear
  help message when the channel is offline, so /world2agent:sensor-add
  can't half-write state in a non-channel session
- Persistent boot/lifecycle log at ~/.world2agent/channel.log for debug
  inspection without re-instrumenting the bundle

Bumps plugin manifest to 0.1.0-alpha.2.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@daibor daibor merged commit 3501697 into main Apr 27, 2026
1 check passed
@daibor daibor deleted the feat/channel-handshake-gate branch April 27, 2026 10:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant