Protocol messages

Overview

Every MDK Protocol message uses the same envelope regardless of which layers are talking. This page shows the envelope shape and one worked example.

Envelope

{
  "id":        "uuid-v4",
  "version":   "0.2.0",
  "type":      "request | response | event",
  "action":    "<protocol action>",
  "sender":    "<component identity>",
  "target":    "<component identity> | null",
  "deviceId":  "string | null",
  "timestamp": 1711640000000,
  "payload":   {}
}

External consumers (UI or AI agents) only provide deviceId. Kernel resolves the target Worker identity internally.

A concrete request and response pair, end to end:

// request: Gateway asks Kernel to reboot device wm-001
{
  "id": "8d1c-e3a4",
  "version": "0.2.0",
  "type": "request",
  "action": "command.request",
  "sender": "gateway",
  "target": null,
  "deviceId": "wm-001",
  "timestamp": 1711640000000,
  "payload": { "command": "reboot" }
}

// response: Kernel relays the Worker's terminal result
{
  "id": "1f9b-77c2",
  "version": "0.2.0",
  "type": "response",
  "action": "command.result",
  "sender": "kernel:kernel:shard-1",
  "target": "gateway",
  "deviceId": "wm-001",
  "timestamp": 1711640002145,
  "payload": { "status": "SUCCESS", "elapsedMs": 2145 }
}

Next steps

• Learn more about actions and command targeting:
  • The Kernel README holds the full action catalogue (worker discovery, scheduled polling, command dispatch, kernel queries, and the write action lifecycle) and command targeting rules (payload.scope's device, worker, and rack values, and the 1024-target cap)
  • Approval-gated writes details the write action lifecycle's full cross-layer flow, and use the write-actions how-to to submit and approve actions from a Gateway consumer
• How MDK works: for the architectural narrative explaining when each action fires
• See the Kernel MDK Protocol spec for every action, direction, and purpose
• Kernel modules: the per-module specs that route and execute these actions
• Build a Worker: implement the Worker side of this protocol