feat(spec): sync protocol and public API schemas with Cloud implementation

schemas/protocol/intent.event.v1.json

@@ -33,7 +33,12 @@
         "intent.failed",
         "intent.canceled",
         "intent.transfer",
-        "intent.timeout"
+        "intent.timeout",
+        "intent.timed_out",
+        "intent.reminder",
+        "intent.escalated",
+        "intent.delivery_failed",
+        "intent.human_task_assigned"
       ]
     },
     "status": {
@@ -47,7 +52,8 @@
         "WAITING",
         "COMPLETED",
         "FAILED",
-        "CANCELED"
+        "CANCELED",
+        "TIMED_OUT"
       ]
     },
     "at": {

schemas/protocol/intent.lifecycle.v1.json

@@ -32,7 +32,8 @@
         "WAITING",
         "COMPLETED",
         "FAILED",
-        "CANCELED"
+        "CANCELED",
+        "TIMED_OUT"
       ]
     },
     "seq": {

schemas/public_api/api.agents.get.response.v1.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://axme.dev/schemas/public_api/api.agents.get.response.v1.json",
+  "title": "ApiAgentsGetResponseV1",
+  "description": "Response for GET /v1/agents/{address} — resolve a single registered agent address.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["ok", "agent"],
+  "properties": {
+    "ok": {
+      "type": "boolean",
+      "const": true
+    },
+    "agent": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["address", "service_account_id", "service_account_name", "status", "created_at"],
+      "properties": {
+        "address": {
+          "description": "Canonical agent address: agent://{org_slug}/{workspace_slug}/{sa_name}",
+          "type": "string",
+          "minLength": 10,
+          "maxLength": 383
+        },
+        "service_account_id": {
+          "type": "string",
+          "minLength": 3
+        },
+        "service_account_name": {
+          "type": "string",
+          "minLength": 2,
+          "maxLength": 120
+        },
+        "display_name": {
+          "type": ["string", "null"],
+          "maxLength": 255
+        },
+        "status": {
+          "type": "string",
+          "enum": ["active", "suspended", "deleted"]
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "updated_at": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    }
+  }
+}

schemas/public_api/api.agents.list.response.v1.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://axme.dev/schemas/public_api/api.agents.list.response.v1.json",
+  "title": "ApiAgentsListResponseV1",
+  "description": "Response for GET /v1/agents — list of registered agent addresses for the workspace.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["ok", "agents"],
+  "properties": {
+    "ok": {
+      "type": "boolean",
+      "const": true
+    },
+    "agents": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/AgentEntry" }
+    }
+  },
+  "$defs": {
+    "AgentEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["address", "service_account_id", "service_account_name", "status", "created_at"],
+      "properties": {
+        "address": {
+          "description": "Canonical agent address: agent://{org_slug}/{workspace_slug}/{sa_name}",
+          "type": "string",
+          "minLength": 10,
+          "maxLength": 383
+        },
+        "service_account_id": {
+          "type": "string",
+          "minLength": 3
+        },
+        "service_account_name": {
+          "type": "string",
+          "minLength": 2,
+          "maxLength": 120
+        },
+        "display_name": {
+          "type": ["string", "null"],
+          "maxLength": 255
+        },
+        "status": {
+          "type": "string",
+          "enum": ["active", "suspended", "deleted"]
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    }
+  }
+}

schemas/public_api/api.intents.create.request.v1.json

@@ -7,7 +7,6 @@
   "required": [
     "intent_type",
     "correlation_id",
-    "from_agent",
     "to_agent",
     "payload"
   ],
@@ -21,22 +20,79 @@
       "format": "uuid"
     },
     "from_agent": {
+      "description": "Deprecated — derived automatically from the API key. Accepted for backward compatibility but ignored by the server.",
       "type": "string",
       "minLength": 3,
-      "maxLength": 255
+      "maxLength": 383
     },
     "to_agent": {
       "type": "string",
       "minLength": 3,
-      "maxLength": 255
+      "maxLength": 383
     },
     "reply_to": {
       "type": "string",
       "minLength": 3,
-      "maxLength": 255
+      "maxLength": 383
     },
     "payload": {
       "type": "object"
+    },
+    "deadline_at": {
+      "description": "ISO-8601 UTC datetime after which the intent is automatically transitioned to TIMED_OUT.",
+      "type": "string",
+      "format": "date-time"
+    },
+    "remind_after_seconds": {
+      "description": "Seconds after submission before the first reminder is sent to the human holder.",
+      "type": "integer",
+      "minimum": 1
+    },
+    "remind_interval_seconds": {
+      "description": "Seconds between subsequent reminders after the first.",
+      "type": "integer",
+      "minimum": 1
+    },
+    "max_reminders": {
+      "description": "Maximum number of reminders before escalating.",
+      "type": "integer",
+      "minimum": 1
+    },
+    "escalate_to": {
+      "description": "Agent address or role alias to escalate to once max_reminders is reached.",
+      "type": "string",
+      "maxLength": 383
+    },
+    "max_delivery_attempts": {
+      "description": "Maximum delivery failures before transitioning to FAILED.",
+      "type": "integer",
+      "minimum": 1
+    },
+    "human_task": {
+      "description": "Structured task description shown to the human when the intent is assigned to a human participant.",
+      "$ref": "#/$defs/HumanTaskSpec"
+    }
+  },
+  "$defs": {
+    "HumanTaskSpec": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["title"],
+      "properties": {
+        "title": {
+          "type": "string",
+          "maxLength": 255
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 2000
+        },
+        "form_schema": {
+          "type": "object",
+          "description": "JSON Schema (draft 2020-12) for validating task_result submitted by the human.",
+          "additionalProperties": true
+        }
+      }
     }
   }
 }

schemas/public_api/api.intents.create.response.v1.json

@@ -22,16 +22,17 @@
     "status": {
       "type": "string",
       "enum": [
-        "CREATED",
-        "SUBMITTED",
-        "DELIVERED",
-        "ACKNOWLEDGED",
-        "IN_PROGRESS",
-        "WAITING",
-        "COMPLETED",
-        "FAILED",
-        "CANCELED"
-      ]
+            "CREATED",
+            "SUBMITTED",
+            "DELIVERED",
+            "ACKNOWLEDGED",
+            "IN_PROGRESS",
+            "WAITING",
+            "COMPLETED",
+            "FAILED",
+            "CANCELED",
+            "TIMED_OUT"
+          ]
     },
     "created_at": {
       "type": "string",

schemas/public_api/api.intents.get.response.v1.json

@@ -42,7 +42,8 @@
             "WAITING",
             "COMPLETED",
             "FAILED",
-            "CANCELED"
+            "CANCELED",
+            "TIMED_OUT"
           ]
         },
         "legacy_status": {
@@ -83,6 +84,58 @@
         },
         "payload": {
           "type": "object"
+        },
+        "deadline_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "remind_after_seconds": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "remind_interval_seconds": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "max_reminders": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "remind_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "escalate_to": {
+          "type": "string",
+          "maxLength": 383
+        },
+        "max_delivery_attempts": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "delivery_attempt": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "human_task": {
+          "type": "object",
+          "additionalProperties": true
+        },
+        "pending_with": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "type": {
+              "type": "string",
+              "enum": ["agent", "human", "internal"]
+            },
+            "ref": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            }
+          }
         }
       }
     }