feat(protocol): add JSON-RPC v2 contracts

control.go

@@ -35,6 +35,12 @@ const (
 	// local and encrypted relay session transports.
 	MsgPing = "ping"
 	MsgPong = "pong"
+
+	// MsgJSONRPCResponse is a migration bridge for encrypted relay responses.
+	// Local v2 transports may send JSON-RPC responses as raw frames; relay
+	// dispatch historically emits AgentMessage envelopes, so this type carries a
+	// JSON-RPC response payload without exposing decrypted content to the relay.
+	MsgJSONRPCResponse = "jsonrpc_response"
 )
 
 // ControlMessage is the wire format for relay control protocol messages.

schemas/asyncapi/agentd.websocket.yaml

@@ -0,0 +1,32 @@
+asyncapi: 3.0.0
+info:
+  title: AgentD v2 WebSocket Events
+  version: 2.0.0
+channels:
+  localDaemon:
+    address: /ws
+    messages:
+      AgentDEvent:
+        $ref: '#/components/messages/AgentDEvent'
+  relaySession:
+    address: /ws/client
+    messages:
+      RelayEnvelope:
+        $ref: '#/components/messages/RelayEnvelope'
+operations:
+  receiveLocalEvent:
+    action: receive
+    channel:
+      $ref: '#/channels/localDaemon'
+  receiveRelayEnvelope:
+    action: receive
+    channel:
+      $ref: '#/channels/relaySession'
+components:
+  messages:
+    AgentDEvent:
+      payload:
+        $ref: '../json-schema/agentd-event-envelope.schema.json'
+    RelayEnvelope:
+      payload:
+        $ref: '../json-schema/relay-envelope.schema.json'

schemas/fixtures/agentd-event.json

@@ -0,0 +1,15 @@
+{
+  "protocol": "agentd.event.v2",
+  "id": "evt_1",
+  "type": "session.replay.complete",
+  "seq": 123,
+  "session_id": "sess_1",
+  "trace_id": "0123456789abcdef0123456789abcdef",
+  "time": "2026-05-23T00:00:00Z",
+  "payload": {
+    "session_id": "sess_1",
+    "from_seq": 100,
+    "to_seq": 123,
+    "count": 24
+  }
+}

schemas/fixtures/jsonrpc-hello-request.json

@@ -0,0 +1,11 @@
+{
+  "jsonrpc": "2.0",
+  "id": "req_hello_1",
+  "method": "protocol.hello",
+  "params": {
+    "client": "agentd-web",
+    "supported_protocols": ["agentd.v2", "agentd.v1"],
+    "capabilities": ["jsonrpc.commands", "typed.events"]
+  },
+  "trace_id": "0123456789abcdef0123456789abcdef"
+}

schemas/fixtures/jsonrpc-hello-response.json

@@ -0,0 +1,11 @@
+{
+  "jsonrpc": "2.0",
+  "id": "req_hello_1",
+  "result": {
+    "protocol": "agentd.v2",
+    "selected_protocol": "agentd.v2",
+    "supported_protocols": ["agentd.v2", "agentd.v1"],
+    "capabilities": ["jsonrpc.commands", "typed.events", "transport.ping", "session.list", "session.replay", "session.snapshot", "relay.opaque"]
+  },
+  "trace_id": "0123456789abcdef0123456789abcdef"
+}

schemas/fixtures/relay-envelope.json

@@ -0,0 +1,6 @@
+{
+  "sid": "relay_session_1",
+  "seq": 1,
+  "enc": "AQIDBA==",
+  "tid": "0123456789abcdef0123456789abcdef"
+}

schemas/json-schema/agentd-command-envelope.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentd.dev/schemas/agentd-command-envelope.schema.json",
+  "title": "AgentD JSON-RPC Command Envelope",
+  "type": "object",
+  "required": ["jsonrpc", "id", "method"],
+  "properties": {
+    "jsonrpc": { "const": "2.0" },
+    "id": {
+      "oneOf": [
+        { "type": "string", "minLength": 1 },
+        { "type": "number" },
+        { "type": "null" }
+      ]
+    },
+    "method": {
+      "type": "string",
+      "pattern": "^[a-z][A-Za-z0-9]*(\\.[A-Za-z][A-Za-z0-9]*)+$"
+    },
+    "params": { "type": "object" },
+    "trace_id": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{32}$",
+      "not": { "const": "00000000000000000000000000000000" }
+    }
+  },
+  "additionalProperties": false
+}

schemas/json-schema/agentd-command-response.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentd.dev/schemas/agentd-command-response.schema.json",
+  "title": "AgentD JSON-RPC Command Response",
+  "type": "object",
+  "required": ["jsonrpc", "id"],
+  "oneOf": [
+    { "required": ["result"], "not": { "required": ["error"] } },
+    { "required": ["error"], "not": { "required": ["result"] } }
+  ],
+  "properties": {
+    "jsonrpc": { "const": "2.0" },
+    "id": {
+      "oneOf": [
+        { "type": "string", "minLength": 1 },
+        { "type": "number" },
+        { "type": "null" }
+      ]
+    },
+    "result": {},
+    "error": {
+      "type": "object",
+      "required": ["code", "message"],
+      "properties": {
+        "code": { "type": "integer" },
+        "message": { "type": "string" },
+        "data": {
+          "type": "object",
+          "properties": {
+            "agentd_code": { "type": "string" },
+            "retryable": { "type": "boolean" },
+            "details": {}
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "trace_id": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{32}$",
+      "not": { "const": "00000000000000000000000000000000" }
+    }
+  },
+  "additionalProperties": false
+}

schemas/json-schema/agentd-event-envelope.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentd.dev/schemas/agentd-event-envelope.schema.json",
+  "title": "AgentD Typed Event Envelope",
+  "type": "object",
+  "required": ["protocol", "id", "type", "time", "payload"],
+  "properties": {
+    "protocol": { "const": "agentd.event.v2" },
+    "id": { "type": "string", "minLength": 1 },
+    "type": {
+      "type": "string",
+      "pattern": "^(error|[a-z][a-z0-9]*(\\.[a-z][a-z0-9]*)+)$"
+    },
+    "seq": { "type": "integer", "minimum": 0 },
+    "session_id": { "type": "string" },
+    "trace_id": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{32}$",
+      "not": { "const": "00000000000000000000000000000000" }
+    },
+    "time": { "type": "string", "format": "date-time" },
+    "payload": {}
+  },
+  "additionalProperties": false
+}

schemas/json-schema/relay-envelope.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentd.dev/schemas/relay-envelope.schema.json",
+  "title": "AgentD Relay Encrypted Envelope",
+  "type": "object",
+  "required": ["sid", "seq", "enc"],
+  "properties": {
+    "sid": { "type": "string", "minLength": 1 },
+    "seq": { "type": "integer", "minimum": 0 },
+    "enc": { "type": "string", "contentEncoding": "base64" },
+    "tid": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{32}$",
+      "not": { "const": "00000000000000000000000000000000" }
+    }
+  },
+  "additionalProperties": false
+}

schemas/openrpc/agentd.commands.json

@@ -0,0 +1,138 @@
+{
+  "openrpc": "1.3.2",
+  "info": {
+    "title": "AgentD v2 Command Plane",
+    "version": "2.0.0"
+  },
+  "methods": [
+    {
+      "name": "protocol.hello",
+      "summary": "Negotiate AgentD protocol version and capabilities.",
+      "paramStructure": "by-name",
+      "params": [
+        {
+          "name": "client",
+          "schema": { "type": "string" }
+        },
+        {
+          "name": "supported_protocols",
+          "schema": {
+            "type": "array",
+            "items": { "enum": ["agentd.v2", "agentd.v1"] }
+          }
+        },
+        {
+          "name": "capabilities",
+          "schema": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      ],
+      "result": {
+        "name": "result",
+        "schema": {
+          "type": "object",
+          "required": ["protocol", "selected_protocol", "supported_protocols", "capabilities"],
+          "properties": {
+            "protocol": { "const": "agentd.v2" },
+            "selected_protocol": { "enum": ["agentd.v2", "agentd.v1"] },
+            "supported_protocols": {
+              "type": "array",
+              "items": { "enum": ["agentd.v2", "agentd.v1"] }
+            },
+            "capabilities": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    {
+      "name": "transport.ping",
+      "summary": "Application-level liveness probe for foreground recovery.",
+      "paramStructure": "by-name",
+      "params": [
+        {
+          "name": "sent_at_unix_ms",
+          "schema": { "type": "integer" }
+        }
+      ],
+      "result": {
+        "name": "result",
+        "schema": {
+          "type": "object",
+          "required": ["type", "received_at_unix_ms"],
+          "properties": {
+            "type": { "const": "pong" },
+            "received_at_unix_ms": { "type": "integer" },
+            "sent_at_unix_ms": { "type": "integer" }
+          }
+        }
+      }
+    },
+    { "name": "session.list", "summary": "List daemon sessions.", "params": [], "result": { "name": "result", "schema": { "type": "object" } } },
+    { "name": "session.start", "summary": "Start a session.", "params": [], "result": { "name": "result", "schema": { "type": "object" } } },
+    { "name": "session.stop", "summary": "Stop a session.", "params": [], "result": { "name": "result", "schema": { "type": "object" } } },
+    { "name": "session.interrupt", "summary": "Interrupt a running session.", "params": [], "result": { "name": "result", "schema": { "type": "object" } } },
+    { "name": "session.resume", "summary": "Resume a session.", "params": [], "result": { "name": "result", "schema": { "type": "object" } } },
+    { "name": "session.delete", "summary": "Delete a session.", "params": [], "result": { "name": "result", "schema": { "type": "object" } } },
+    { "name": "session.rename", "summary": "Rename a session.", "params": [], "result": { "name": "result", "schema": { "type": "object" } } },
+    { "name": "session.fork", "summary": "Fork a session.", "params": [], "result": { "name": "result", "schema": { "type": "object" } } },
+    {
+      "name": "session.snapshot",
+      "summary": "Request daemon-authoritative session snapshot.",
+      "paramStructure": "by-name",
+      "params": [
+        {
+          "name": "session_id",
+          "required": true,
+          "schema": { "type": "string", "minLength": 1 }
+        },
+        {
+          "name": "after_seq",
+          "schema": {
+            "type": "integer",
+            "minimum": 0
+          }
+        },
+        {
+          "name": "cursor",
+          "schema": { "type": "string" }
+        }
+      ],
+      "result": { "name": "result", "schema": { "type": "object" } }
+    },
+    {
+      "name": "session.replay",
+      "summary": "Request replay after a cursor.",
+      "paramStructure": "by-name",
+      "params": [
+        {
+          "name": "session_id",
+          "required": true,
+          "schema": { "type": "string", "minLength": 1 }
+        },
+        {
+          "name": "after_seq",
+          "schema": {
+            "type": "integer",
+            "minimum": 0
+          }
+        },
+        {
+          "name": "cursor",
+          "schema": { "type": "string" }
+        }
+      ],
+      "result": { "name": "result", "schema": { "type": "object" } }
+    },
+    { "name": "approval.decide", "summary": "Submit an approval decision.", "params": [], "result": { "name": "result", "schema": { "type": "object" } } },
+    { "name": "approval.setMode", "summary": "Set approval mode.", "params": [], "result": { "name": "result", "schema": { "type": "object" } } },
+    { "name": "prompt.answer", "summary": "Answer an interactive prompt.", "params": [], "result": { "name": "result", "schema": { "type": "object" } } },
+    { "name": "budget.extend", "summary": "Extend a session budget.", "params": [], "result": { "name": "result", "schema": { "type": "object" } } },
+    { "name": "models.list", "summary": "List available models.", "params": [], "result": { "name": "result", "schema": { "type": "object" } } },
+    { "name": "providers.list", "summary": "List configured providers.", "params": [], "result": { "name": "result", "schema": { "type": "object" } } }
+  ]
+}