AWPGitHub ↗
WIRE PROTOCOL · 0.1

Small envelope. Complete return path.

AWP uses UTF-8 JSON messages over an authenticated outbound WebSocket connection.

View canonical source on GitHub ↗

Common envelope

Every frame contains one JSON object. Unknown fields should be ignored unless processing them would be unsafe.

{
  "type": "awp",
  "version": "0.1",
  "id": "msg_01JABC123",
  "action": "event.deliver",
  "timestamp": "2026-07-19T12:00:00Z",
  "data": {}
}

Connection lifecycle

client.helloClient → Provider

Authenticate the device and advertise capabilities.

server.welcomeProvider → Client

Accept the connection and define heartbeat limits.

session.bindClient → Provider

Announce an opaque provider-scoped session.

event.deliverProvider → Client

Deliver an external event at least once.

event.ackClient → Provider

Report accepted, completed, failed, or rejected.

heartbeat.*Both directions

Keep the outbound WebSocket connection alive.

Delivery semantics

At least once

Stable event and delivery IDs allow safe retry and deduplication.

Provider scoped

Routing uses provider, device ID, and opaque AWP session ID.

Opaque payload

Application data remains provider-defined and untrusted.

Explicit outcome

Acknowledgements distinguish completed, failed, and rejected work.

Security boundary

  • Runtime session IDs never leave the local machine.
  • All non-local connections use TLS and bearer authentication.
  • Events resume only the permissions the session already had.
  • Payloads are untrusted input—not authorization or executable data.