Skip to content

HeyAira Bridge 0.0.3 coordination protocol

This document defines the first coordination contract for the Bridge runtime. It deliberately does not choose cmux, OpenMux, or another terminal adapter.

Ownership

  • HeyAira Server owns the durable task queue, assignment, leases, and retry decisions.
  • HeyAira Bridge owns local readiness, sleep-prevention state, agent profiles, runtime sessions, process identifiers, and the observed execution state.
  • HeyAira MCP remains the interface for agent work, memory, and questions. The Bridge API is for delivery and execution lifecycle events.

Delivery direction

The Bridge makes only outbound connections. Tailscale can provide the private network boundary, but it is not an authorization mechanism.

The normal delivery path is a server-pushed command stream over the existing outbound authenticated connection (long-poll first; SSE/WebSocket can be added behind the same contract). Heartbeat remains the liveness and recovery path. The Bridge must not expose an unauthenticated listener on the Mac.

Offer and acceptance

  1. The Bridge publishes a readiness snapshot with capacity, active sessions, and sleep-prevention mode.
  2. The server sends a short-lived task offer containing offer_id, task_id, the selected profile_id, an expiry, and task metadata.
  3. The Bridge validates local capacity and profile availability, then replies with accepted or rejected.
  4. The Bridge immediately emits an acknowledgement of that acceptance or rejection. Acceptance is therefore not the same thing as completion.
  5. The Bridge reports task and session state transitions as execution proceeds. A lease expiry or disconnect lets the server retry safely.

The minimum offer states are offered, accepted, rejected, expired, and acknowledged. The minimum task states are queued, offered, accepted, running, waiting_for_input, completed, failed, and cancelled.

Session lifecycle

The Bridge keeps the local truth for each configured runtime session:

configured -> launching -> ready -> offered -> accepted -> running -> waiting_for_input -> completed|failed -> stopped

waiting_for_input may return to running. A session can return to ready after a task only if the underlying process remains healthy; otherwise it is stopped and must be launched again.

Agent profiles

An agent profile is configuration, not an active process. It identifies the model, adapter, workspace, agent.md identity/hash, skill identities/hashes, permission policy, and credential references. A runtime session references a profile and additionally records its PID, loaded profile revision, task, last event, and exit reason. Secrets and credential values never belong in the profile payload or diagnostic context.

Sleep prevention

Sleep prevention is a local, user-controlled setting with three modes:

  • off
  • while_ready
  • while_task_active

The Bridge reports the selected mode and effective state to the server. It must not silently prevent sleep or change macOS power policy without the user enabling it.

Notifications

Notifications are derived from meaningful lifecycle events such as a Bridge failure, task acceptance, waiting for input, or task completion. Heartbeats are not notification events.

The safe event envelope contains an event ID, event type, severity, node ID, optional task ID, short title/body, deduplication key, and optional deep link. It does not contain credentials, authorization headers, private keys, or raw task content. The Mac Bridge delivers local events through macOS native notifications. Mobile delivery is server-routed through an iOS/APNs channel; the Bridge never contacts a phone or watch directly. Apple Watch support is handled by the Apple notification ecosystem or a later companion app.

The concrete external secret-store adapter is documented in BRIDGE_OPENBAO.md. OpenBao is not initialized or enabled by this protocol change; APNs remains disabled until the external vault, process-manager wiring, and live-device checks are independently accepted.