{ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://clawdis.dev/protocol.schema.json", "title": "Clawdis Gateway Protocol", "description": "Handshake, request/response, and event frames for the Gateway WebSocket.", "oneOf": [ { "$ref": "#/definitions/RequestFrame" }, { "$ref": "#/definitions/ResponseFrame" }, { "$ref": "#/definitions/EventFrame" } ], "discriminator": { "propertyName": "type", "mapping": { "req": "#/definitions/RequestFrame", "res": "#/definitions/ResponseFrame", "event": "#/definitions/EventFrame" } }, "definitions": { "ConnectParams": { "additionalProperties": false, "type": "object", "properties": { "minProtocol": { "minimum": 1, "type": "integer" }, "maxProtocol": { "minimum": 1, "type": "integer" }, "client": { "additionalProperties": false, "type": "object", "properties": { "name": { "minLength": 1, "type": "string" }, "version": { "minLength": 1, "type": "string" }, "platform": { "minLength": 1, "type": "string" }, "mode": { "minLength": 1, "type": "string" }, "instanceId": { "minLength": 1, "type": "string" } }, "required": [ "name", "version", "platform", "mode" ] }, "caps": { "default": [], "type": "array", "items": { "minLength": 1, "type": "string" } }, "auth": { "additionalProperties": false, "type": "object", "properties": { "token": { "type": "string" } } }, "locale": { "type": "string" }, "userAgent": { "type": "string" } }, "required": [ "minProtocol", "maxProtocol", "client" ] }, "HelloOk": { "additionalProperties": false, "type": "object", "properties": { "type": { "const": "hello-ok", "type": "string" }, "protocol": { "minimum": 1, "type": "integer" }, "server": { "additionalProperties": false, "type": "object", "properties": { "version": { "minLength": 1, "type": "string" }, "commit": { "minLength": 1, "type": "string" }, "host": { "minLength": 1, "type": "string" }, "connId": { "minLength": 1, "type": "string" } }, "required": [ "version", "connId" ] }, "features": { "additionalProperties": false, "type": "object", "properties": { "methods": { "type": "array", "items": { "minLength": 1, "type": "string" } }, "events": { "type": "array", "items": { "minLength": 1, "type": "string" } } }, "required": [ "methods", "events" ] }, "snapshot": { "additionalProperties": false, "type": "object", "properties": { "presence": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "host": { "minLength": 1, "type": "string" }, "ip": { "minLength": 1, "type": "string" }, "version": { "minLength": 1, "type": "string" }, "mode": { "minLength": 1, "type": "string" }, "lastInputSeconds": { "minimum": 0, "type": "integer" }, "reason": { "minLength": 1, "type": "string" }, "tags": { "type": "array", "items": { "minLength": 1, "type": "string" } }, "text": { "type": "string" }, "ts": { "minimum": 0, "type": "integer" }, "instanceId": { "minLength": 1, "type": "string" } }, "required": [ "ts" ] } }, "health": {}, "stateVersion": { "additionalProperties": false, "type": "object", "properties": { "presence": { "minimum": 0, "type": "integer" }, "health": { "minimum": 0, "type": "integer" } }, "required": [ "presence", "health" ] }, "uptimeMs": { "minimum": 0, "type": "integer" } }, "required": [ "presence", "health", "stateVersion", "uptimeMs" ] }, "policy": { "additionalProperties": false, "type": "object", "properties": { "maxPayload": { "minimum": 1, "type": "integer" }, "maxBufferedBytes": { "minimum": 1, "type": "integer" }, "tickIntervalMs": { "minimum": 1, "type": "integer" } }, "required": [ "maxPayload", "maxBufferedBytes", "tickIntervalMs" ] } }, "required": [ "type", "protocol", "server", "features", "snapshot", "policy" ] }, "RequestFrame": { "additionalProperties": false, "type": "object", "properties": { "type": { "const": "req", "type": "string" }, "id": { "minLength": 1, "type": "string" }, "method": { "minLength": 1, "type": "string" }, "params": {} }, "required": [ "type", "id", "method" ] }, "ResponseFrame": { "additionalProperties": false, "type": "object", "properties": { "type": { "const": "res", "type": "string" }, "id": { "minLength": 1, "type": "string" }, "ok": { "type": "boolean" }, "payload": {}, "error": { "additionalProperties": false, "type": "object", "properties": { "code": { "minLength": 1, "type": "string" }, "message": { "minLength": 1, "type": "string" }, "details": {}, "retryable": { "type": "boolean" }, "retryAfterMs": { "minimum": 0, "type": "integer" } }, "required": [ "code", "message" ] } }, "required": [ "type", "id", "ok" ] }, "EventFrame": { "additionalProperties": false, "type": "object", "properties": { "type": { "const": "event", "type": "string" }, "event": { "minLength": 1, "type": "string" }, "payload": {}, "seq": { "minimum": 0, "type": "integer" }, "stateVersion": { "additionalProperties": false, "type": "object", "properties": { "presence": { "minimum": 0, "type": "integer" }, "health": { "minimum": 0, "type": "integer" } }, "required": [ "presence", "health" ] } }, "required": [ "type", "event" ] }, "GatewayFrame": { "discriminator": "type", "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "type": { "const": "req", "type": "string" }, "id": { "minLength": 1, "type": "string" }, "method": { "minLength": 1, "type": "string" }, "params": {} }, "required": [ "type", "id", "method" ] }, { "additionalProperties": false, "type": "object", "properties": { "type": { "const": "res", "type": "string" }, "id": { "minLength": 1, "type": "string" }, "ok": { "type": "boolean" }, "payload": {}, "error": { "additionalProperties": false, "type": "object", "properties": { "code": { "minLength": 1, "type": "string" }, "message": { "minLength": 1, "type": "string" }, "details": {}, "retryable": { "type": "boolean" }, "retryAfterMs": { "minimum": 0, "type": "integer" } }, "required": [ "code", "message" ] } }, "required": [ "type", "id", "ok" ] }, { "additionalProperties": false, "type": "object", "properties": { "type": { "const": "event", "type": "string" }, "event": { "minLength": 1, "type": "string" }, "payload": {}, "seq": { "minimum": 0, "type": "integer" }, "stateVersion": { "additionalProperties": false, "type": "object", "properties": { "presence": { "minimum": 0, "type": "integer" }, "health": { "minimum": 0, "type": "integer" } }, "required": [ "presence", "health" ] } }, "required": [ "type", "event" ] } ] }, "PresenceEntry": { "additionalProperties": false, "type": "object", "properties": { "host": { "minLength": 1, "type": "string" }, "ip": { "minLength": 1, "type": "string" }, "version": { "minLength": 1, "type": "string" }, "mode": { "minLength": 1, "type": "string" }, "lastInputSeconds": { "minimum": 0, "type": "integer" }, "reason": { "minLength": 1, "type": "string" }, "tags": { "type": "array", "items": { "minLength": 1, "type": "string" } }, "text": { "type": "string" }, "ts": { "minimum": 0, "type": "integer" }, "instanceId": { "minLength": 1, "type": "string" } }, "required": [ "ts" ] }, "StateVersion": { "additionalProperties": false, "type": "object", "properties": { "presence": { "minimum": 0, "type": "integer" }, "health": { "minimum": 0, "type": "integer" } }, "required": [ "presence", "health" ] }, "Snapshot": { "additionalProperties": false, "type": "object", "properties": { "presence": { "type": "array", "items": { "additionalProperties": false, "type": "object", "properties": { "host": { "minLength": 1, "type": "string" }, "ip": { "minLength": 1, "type": "string" }, "version": { "minLength": 1, "type": "string" }, "mode": { "minLength": 1, "type": "string" }, "lastInputSeconds": { "minimum": 0, "type": "integer" }, "reason": { "minLength": 1, "type": "string" }, "tags": { "type": "array", "items": { "minLength": 1, "type": "string" } }, "text": { "type": "string" }, "ts": { "minimum": 0, "type": "integer" }, "instanceId": { "minLength": 1, "type": "string" } }, "required": [ "ts" ] } }, "health": {}, "stateVersion": { "additionalProperties": false, "type": "object", "properties": { "presence": { "minimum": 0, "type": "integer" }, "health": { "minimum": 0, "type": "integer" } }, "required": [ "presence", "health" ] }, "uptimeMs": { "minimum": 0, "type": "integer" } }, "required": [ "presence", "health", "stateVersion", "uptimeMs" ] }, "ErrorShape": { "additionalProperties": false, "type": "object", "properties": { "code": { "minLength": 1, "type": "string" }, "message": { "minLength": 1, "type": "string" }, "details": {}, "retryable": { "type": "boolean" }, "retryAfterMs": { "minimum": 0, "type": "integer" } }, "required": [ "code", "message" ] }, "AgentEvent": { "additionalProperties": false, "type": "object", "properties": { "runId": { "minLength": 1, "type": "string" }, "seq": { "minimum": 0, "type": "integer" }, "stream": { "minLength": 1, "type": "string" }, "ts": { "minimum": 0, "type": "integer" }, "data": { "type": "object", "patternProperties": { "^(.*)$": {} } } }, "required": [ "runId", "seq", "stream", "ts", "data" ] }, "SendParams": { "additionalProperties": false, "type": "object", "properties": { "to": { "minLength": 1, "type": "string" }, "message": { "minLength": 1, "type": "string" }, "mediaUrl": { "type": "string" }, "provider": { "type": "string" }, "idempotencyKey": { "minLength": 1, "type": "string" } }, "required": [ "to", "message", "idempotencyKey" ] }, "AgentParams": { "additionalProperties": false, "type": "object", "properties": { "message": { "minLength": 1, "type": "string" }, "to": { "type": "string" }, "sessionId": { "type": "string" }, "sessionKey": { "type": "string" }, "thinking": { "type": "string" }, "deliver": { "type": "boolean" }, "channel": { "type": "string" }, "timeout": { "minimum": 0, "type": "integer" }, "idempotencyKey": { "minLength": 1, "type": "string" } }, "required": [ "message", "idempotencyKey" ] }, "WakeParams": { "additionalProperties": false, "type": "object", "properties": { "mode": { "anyOf": [ { "const": "now", "type": "string" }, { "const": "next-heartbeat", "type": "string" } ] }, "text": { "minLength": 1, "type": "string" } }, "required": [ "mode", "text" ] }, "NodePairRequestParams": { "additionalProperties": false, "type": "object", "properties": { "nodeId": { "minLength": 1, "type": "string" }, "displayName": { "minLength": 1, "type": "string" }, "platform": { "minLength": 1, "type": "string" }, "version": { "minLength": 1, "type": "string" }, "remoteIp": { "minLength": 1, "type": "string" } }, "required": [ "nodeId" ] }, "NodePairListParams": { "additionalProperties": false, "type": "object", "properties": {} }, "NodePairApproveParams": { "additionalProperties": false, "type": "object", "properties": { "requestId": { "minLength": 1, "type": "string" } }, "required": [ "requestId" ] }, "NodePairRejectParams": { "additionalProperties": false, "type": "object", "properties": { "requestId": { "minLength": 1, "type": "string" } }, "required": [ "requestId" ] }, "NodePairVerifyParams": { "additionalProperties": false, "type": "object", "properties": { "nodeId": { "minLength": 1, "type": "string" }, "token": { "minLength": 1, "type": "string" } }, "required": [ "nodeId", "token" ] }, "CronJob": { "additionalProperties": false, "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "createdAtMs": { "minimum": 0, "type": "integer" }, "updatedAtMs": { "minimum": 0, "type": "integer" }, "schedule": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "kind": { "const": "at", "type": "string" }, "atMs": { "minimum": 0, "type": "integer" } }, "required": [ "kind", "atMs" ] }, { "additionalProperties": false, "type": "object", "properties": { "kind": { "const": "every", "type": "string" }, "everyMs": { "minimum": 1, "type": "integer" }, "anchorMs": { "minimum": 0, "type": "integer" } }, "required": [ "kind", "everyMs" ] }, { "additionalProperties": false, "type": "object", "properties": { "kind": { "const": "cron", "type": "string" }, "expr": { "minLength": 1, "type": "string" }, "tz": { "type": "string" } }, "required": [ "kind", "expr" ] } ] }, "sessionTarget": { "anyOf": [ { "const": "main", "type": "string" }, { "const": "isolated", "type": "string" } ] }, "wakeMode": { "anyOf": [ { "const": "next-heartbeat", "type": "string" }, { "const": "now", "type": "string" } ] }, "payload": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "kind": { "const": "systemEvent", "type": "string" }, "text": { "minLength": 1, "type": "string" } }, "required": [ "kind", "text" ] }, { "additionalProperties": false, "type": "object", "properties": { "kind": { "const": "agentTurn", "type": "string" }, "message": { "minLength": 1, "type": "string" }, "thinking": { "type": "string" }, "timeoutSeconds": { "minimum": 1, "type": "integer" }, "deliver": { "type": "boolean" }, "channel": { "anyOf": [ { "const": "last", "type": "string" }, { "const": "whatsapp", "type": "string" }, { "const": "telegram", "type": "string" } ] }, "to": { "type": "string" }, "bestEffortDeliver": { "type": "boolean" } }, "required": [ "kind", "message" ] } ] }, "isolation": { "additionalProperties": false, "type": "object", "properties": { "postToMain": { "type": "boolean" }, "postToMainPrefix": { "type": "string" } } }, "state": { "additionalProperties": false, "type": "object", "properties": { "nextRunAtMs": { "minimum": 0, "type": "integer" }, "runningAtMs": { "minimum": 0, "type": "integer" }, "lastRunAtMs": { "minimum": 0, "type": "integer" }, "lastStatus": { "anyOf": [ { "const": "ok", "type": "string" }, { "const": "error", "type": "string" }, { "const": "skipped", "type": "string" } ] }, "lastError": { "type": "string" }, "lastDurationMs": { "minimum": 0, "type": "integer" } } } }, "required": [ "id", "enabled", "createdAtMs", "updatedAtMs", "schedule", "sessionTarget", "wakeMode", "payload", "state" ] }, "CronListParams": { "additionalProperties": false, "type": "object", "properties": { "includeDisabled": { "type": "boolean" } } }, "CronStatusParams": { "additionalProperties": false, "type": "object", "properties": {} }, "CronAddParams": { "additionalProperties": false, "type": "object", "properties": { "name": { "type": "string" }, "enabled": { "type": "boolean" }, "schedule": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "kind": { "const": "at", "type": "string" }, "atMs": { "minimum": 0, "type": "integer" } }, "required": [ "kind", "atMs" ] }, { "additionalProperties": false, "type": "object", "properties": { "kind": { "const": "every", "type": "string" }, "everyMs": { "minimum": 1, "type": "integer" }, "anchorMs": { "minimum": 0, "type": "integer" } }, "required": [ "kind", "everyMs" ] }, { "additionalProperties": false, "type": "object", "properties": { "kind": { "const": "cron", "type": "string" }, "expr": { "minLength": 1, "type": "string" }, "tz": { "type": "string" } }, "required": [ "kind", "expr" ] } ] }, "sessionTarget": { "anyOf": [ { "const": "main", "type": "string" }, { "const": "isolated", "type": "string" } ] }, "wakeMode": { "anyOf": [ { "const": "next-heartbeat", "type": "string" }, { "const": "now", "type": "string" } ] }, "payload": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "kind": { "const": "systemEvent", "type": "string" }, "text": { "minLength": 1, "type": "string" } }, "required": [ "kind", "text" ] }, { "additionalProperties": false, "type": "object", "properties": { "kind": { "const": "agentTurn", "type": "string" }, "message": { "minLength": 1, "type": "string" }, "thinking": { "type": "string" }, "timeoutSeconds": { "minimum": 1, "type": "integer" }, "deliver": { "type": "boolean" }, "channel": { "anyOf": [ { "const": "last", "type": "string" }, { "const": "whatsapp", "type": "string" }, { "const": "telegram", "type": "string" } ] }, "to": { "type": "string" }, "bestEffortDeliver": { "type": "boolean" } }, "required": [ "kind", "message" ] } ] }, "isolation": { "additionalProperties": false, "type": "object", "properties": { "postToMain": { "type": "boolean" }, "postToMainPrefix": { "type": "string" } } } }, "required": [ "schedule", "sessionTarget", "wakeMode", "payload" ] }, "CronUpdateParams": { "additionalProperties": false, "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "patch": { "additionalProperties": false, "type": "object", "properties": { "name": { "type": "string" }, "enabled": { "type": "boolean" }, "schedule": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "kind": { "const": "at", "type": "string" }, "atMs": { "minimum": 0, "type": "integer" } }, "required": [ "kind", "atMs" ] }, { "additionalProperties": false, "type": "object", "properties": { "kind": { "const": "every", "type": "string" }, "everyMs": { "minimum": 1, "type": "integer" }, "anchorMs": { "minimum": 0, "type": "integer" } }, "required": [ "kind", "everyMs" ] }, { "additionalProperties": false, "type": "object", "properties": { "kind": { "const": "cron", "type": "string" }, "expr": { "minLength": 1, "type": "string" }, "tz": { "type": "string" } }, "required": [ "kind", "expr" ] } ] }, "sessionTarget": { "anyOf": [ { "const": "main", "type": "string" }, { "const": "isolated", "type": "string" } ] }, "wakeMode": { "anyOf": [ { "const": "next-heartbeat", "type": "string" }, { "const": "now", "type": "string" } ] }, "payload": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "kind": { "const": "systemEvent", "type": "string" }, "text": { "minLength": 1, "type": "string" } }, "required": [ "kind", "text" ] }, { "additionalProperties": false, "type": "object", "properties": { "kind": { "const": "agentTurn", "type": "string" }, "message": { "minLength": 1, "type": "string" }, "thinking": { "type": "string" }, "timeoutSeconds": { "minimum": 1, "type": "integer" }, "deliver": { "type": "boolean" }, "channel": { "anyOf": [ { "const": "last", "type": "string" }, { "const": "whatsapp", "type": "string" }, { "const": "telegram", "type": "string" } ] }, "to": { "type": "string" }, "bestEffortDeliver": { "type": "boolean" } }, "required": [ "kind", "message" ] } ] }, "isolation": { "additionalProperties": false, "type": "object", "properties": { "postToMain": { "type": "boolean" }, "postToMainPrefix": { "type": "string" } } } } } }, "required": [ "id", "patch" ] }, "CronRemoveParams": { "additionalProperties": false, "type": "object", "properties": { "id": { "minLength": 1, "type": "string" } }, "required": [ "id" ] }, "CronRunParams": { "additionalProperties": false, "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "mode": { "anyOf": [ { "const": "due", "type": "string" }, { "const": "force", "type": "string" } ] } }, "required": [ "id" ] }, "CronRunsParams": { "additionalProperties": false, "type": "object", "properties": { "id": { "minLength": 1, "type": "string" }, "limit": { "minimum": 1, "maximum": 5000, "type": "integer" } } }, "CronRunLogEntry": { "additionalProperties": false, "type": "object", "properties": { "ts": { "minimum": 0, "type": "integer" }, "jobId": { "minLength": 1, "type": "string" }, "action": { "const": "finished", "type": "string" }, "status": { "anyOf": [ { "const": "ok", "type": "string" }, { "const": "error", "type": "string" }, { "const": "skipped", "type": "string" } ] }, "error": { "type": "string" }, "runAtMs": { "minimum": 0, "type": "integer" }, "durationMs": { "minimum": 0, "type": "integer" }, "nextRunAtMs": { "minimum": 0, "type": "integer" } }, "required": [ "ts", "jobId", "action" ] }, "ChatHistoryParams": { "additionalProperties": false, "type": "object", "properties": { "sessionKey": { "minLength": 1, "type": "string" } }, "required": [ "sessionKey" ] }, "ChatSendParams": { "additionalProperties": false, "type": "object", "properties": { "sessionKey": { "minLength": 1, "type": "string" }, "message": { "minLength": 1, "type": "string" }, "thinking": { "type": "string" }, "deliver": { "type": "boolean" }, "attachments": { "type": "array", "items": {} }, "timeoutMs": { "minimum": 0, "type": "integer" }, "idempotencyKey": { "minLength": 1, "type": "string" } }, "required": [ "sessionKey", "message", "idempotencyKey" ] }, "ChatEvent": { "additionalProperties": false, "type": "object", "properties": { "runId": { "minLength": 1, "type": "string" }, "sessionKey": { "minLength": 1, "type": "string" }, "seq": { "minimum": 0, "type": "integer" }, "state": { "anyOf": [ { "const": "delta", "type": "string" }, { "const": "final", "type": "string" }, { "const": "error", "type": "string" } ] }, "message": {}, "errorMessage": { "type": "string" }, "usage": {}, "stopReason": { "type": "string" } }, "required": [ "runId", "sessionKey", "seq", "state" ] }, "TickEvent": { "additionalProperties": false, "type": "object", "properties": { "ts": { "minimum": 0, "type": "integer" } }, "required": [ "ts" ] }, "ShutdownEvent": { "additionalProperties": false, "type": "object", "properties": { "reason": { "minLength": 1, "type": "string" }, "restartExpectedMs": { "minimum": 0, "type": "integer" } }, "required": [ "reason" ] } } }