[codex] Export node control handler

[willwashburn]

Summary

• export the canonical node-control dispatcher via @relaycast/engine/node-control and the root engine entrypoint
• export NodeSocketLike, HandleNodeControlMessageArgs, and InvocationCompletionDeps for DO adapters
• document the DO adapter contract, completionDeps behavior, self-containment, and built-in reconnect replay/drain behavior
• constrain direct-node heartbeats so roster refresh cannot advertise broker handler semantics
• add direct conformance coverage for handleNodeControlMessage without the websocket route wrapper

Validation

• npx vitest run packages/engine/src/__tests__/conformance/node.test.ts
• npm run -w @relaycast/engine typecheck
• npm run -w @relaycast/engine lint
• npm run -w @relaycast/engine build
• node --input-type=module -e "const m = await import('@relaycast/engine/node-control'); if (typeof m.handleNodeControlMessage !== 'function') throw new Error('missing node-control handler'); console.log('node-control export ok')"
• node --input-type=module -e "const m = await import('@relaycast/engine'); if (typeof m.handleNodeControlMessage !== 'function') throw new Error('missing root handler'); console.log('root export ok')"
• npm run -w @relaycast/engine test
• npx turbo build

[gemini-code-assist]

Code Review

This pull request exposes the handleNodeControlMessage function and its associated types as a public API from @relaycast/engine/node-control to allow adapters to delegate node control frames directly. It also updates the documentation in README.md, adds a comprehensive conformance test, and refactors heartbeatNode in packages/engine/src/engine/node.ts to optimize database queries. I have no feedback to provide as the changes are clean, well-tested, and align with the repository's guidelines.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 63724292-deca-4a22-97fe-9706edacf78a

📥 Commits

Reviewing files that changed from the base of the PR and between f4cd5f5 and 1d871e0.

📒 Files selected for processing (6)

• README.md
• packages/engine/package.json
• packages/engine/src/__tests__/conformance/node.test.ts
• packages/engine/src/engine/node.ts
• packages/engine/src/index.ts
• packages/engine/src/node-control.ts

---

📝 Walkthrough

Walkthrough

This PR adds a public @relaycast/engine/node-control entrypoint, routes /v1/node/ws frames through handleNodeControlMessage, updates heartbeat persistence rules for broker and direct nodes, and adds conformance coverage for direct node-control dispatch.

Changes

Node control flow

Layer / File(s)	Summary
Public surface packages/engine/package.json, packages/engine/src/node-control.ts, packages/engine/src/index.ts, README.md	@relaycast/engine/node-control is added as a public subpath, re-exporting handleNodeControlMessage and related types, and the README switches /v1/node/ws guidance to that handler.
Handler typing and heartbeat rules packages/engine/src/engine/node.ts	handleNodeControlMessage now uses exported socket and argument interfaces, and heartbeatNode reuses the node role to gate roster updates while deriving activeAgents and handlersLive from role-based rules.
Direct conformance coverage packages/engine/src/__tests__/conformance/node.test.ts	A conformance test now calls handleNodeControlMessage directly with a FakeSocket and checks broker, agent, and direct-node register, heartbeat, and deregister behavior in the database.

Sequence Diagram(s)

sequenceDiagram
  participant NodeWsAdapter
  participant handleNodeControlMessage
  participant EngineDb
  participant NodeConnectionRegistry
  participant completionDeps
  NodeWsAdapter->>handleNodeControlMessage: raw frame + socket.send
  handleNodeControlMessage->>EngineDb: node.register / agent.register / inventory.sync
  handleNodeControlMessage->>NodeConnectionRegistry: drain queued invocations
  handleNodeControlMessage-->>completionDeps: optional fan-out / webhook effects

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• AgentWorkforce/relaycast#194: Also changes handleNodeControlMessage behavior in packages/engine/src/engine/node.ts, so the node-control handler flow is directly related.
• AgentWorkforce/relaycast#197: Also updates heartbeatNode logic in the same engine module, with overlapping persistence rules for node heartbeats.

Poem

I twitched my nose at the websocket glow,
and watched the node-control packets flow.
Broker, agent, direct node too,
hopped through the frames the proper way through.
🐇 Thump! The queue replied in time.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/node-control-export

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}