feat(protocol): AXP Session schemas + optional session_id linkage (D-030)

docs/public-api-schema-index.md

@@ -170,6 +170,48 @@ Related artifacts:
 - `GET /v1/media/{upload_id}`
   - response: `api.media.get.response.v1.json`
 
+## Sessions (anti-messenger / D-030)
+
+A Session is a first-class orchestrator (separate from Intent) that holds Messages
+(delivered over DB + SSE, never Pub/Sub) and may spawn manual Intents. Protocol
+artifacts:
+
+- `schemas/protocol/session.envelope.v1.json`
+- `schemas/protocol/session.lifecycle.v1.json`
+- `schemas/protocol/session.event.v1.json`
+
+Intent/message schemas carry an optional `session_id` (and `parent_intent_id` on
+`intent.lifecycle.v1`) to back-link work spawned within a Session. These additions
+are optional and backward-compatible (v1 line unchanged).
+
+### Files
+
+- `schemas/public_api/api.sessions.create.request.v1.json`
+- `schemas/public_api/api.sessions.create.response.v1.json`
+- `schemas/public_api/api.sessions.get.response.v1.json`
+- `schemas/public_api/api.sessions.events.list.response.v1.json`
+- `schemas/public_api/api.sessions.messages.append.request.v1.json`
+- `schemas/public_api/api.sessions.list.response.v1.json`
+
+### Endpoint Mapping
+
+- `POST /v1/sessions`
+  - request: `api.sessions.create.request.v1.json`
+  - response: `api.sessions.create.response.v1.json`
+- `GET /v1/sessions`
+  - unified visitor inbox, scoped strictly by participation
+  - response: `api.sessions.list.response.v1.json`
+- `GET /v1/sessions/{session_id}`
+  - response: `api.sessions.get.response.v1.json`
+- `GET /v1/sessions/{session_id}/events`
+  - response: `api.sessions.events.list.response.v1.json`
+- `GET /v1/sessions/{session_id}/stream`
+  - transport: `text/event-stream` (SSE)
+  - event payload shape: same event object as `api.sessions.events.list.response.v1.json` item
+- `POST /v1/sessions/{session_id}/messages`
+  - request: `api.sessions.messages.append.request.v1.json`
+  - response: `api.sessions.get.response.v1.json`
+
 ## Track F Phase 1 Families (Draft Contracts)
 
 ### Files

docs/schema-versioning-rules.md

@@ -41,6 +41,9 @@ Rules apply to:
 - `intent.error.v1.json`
 - `intent.lifecycle.v1.json`
 - `intent.event.v1.json`
+- `session.envelope.v1.json`
+- `session.lifecycle.v1.json`
+- `session.event.v1.json`
 
 ## Required Public API Schemas (v1 line)
 
@@ -60,3 +63,9 @@ Rules apply to:
 - `api.inbox.reply.request.v1.json`
 - `api.inbox.delegate.request.v1.json`
 - `api.inbox.decision.request.v1.json`
+- `api.sessions.create.request.v1.json`
+- `api.sessions.create.response.v1.json`
+- `api.sessions.get.response.v1.json`
+- `api.sessions.events.list.response.v1.json`
+- `api.sessions.messages.append.request.v1.json`
+- `api.sessions.list.response.v1.json`

schemas/protocol/intent.envelope.v1.json

@@ -51,6 +51,11 @@
     "payload": {
       "type": "object"
     },
+    "session_id": {
+      "description": "Optional. Set when this intent is spawned within a Session orchestrator (see session.envelope.v1).",
+      "type": "string",
+      "format": "uuid"
+    },
     "metadata": {
       "type": "object",
       "additionalProperties": {

schemas/protocol/intent.event.v1.json

@@ -79,6 +79,11 @@
         "WAITING_FOR_TIME"
       ]
     },
+    "session_id": {
+      "description": "Optional. Set when the intent belongs to a Session orchestrator (see session.event.v1).",
+      "type": "string",
+      "format": "uuid"
+    },
     "payload": {
       "type": "object"
     },

schemas/protocol/intent.lifecycle.v1.json

@@ -70,6 +70,16 @@
       "type": "string",
       "maxLength": 128
     },
+    "session_id": {
+      "description": "Optional. Set when this intent was spawned by a Session orchestrator (see session.lifecycle.v1). Absent for standalone agent-to-agent intents.",
+      "type": "string",
+      "format": "uuid"
+    },
+    "parent_intent_id": {
+      "description": "Optional. Parent intent in a multi-intent hierarchy spawned within a Session.",
+      "type": "string",
+      "format": "uuid"
+    },
     "metadata": {
       "type": "object",
       "additionalProperties": {

schemas/protocol/message.envelope.v3.json

@@ -30,6 +30,14 @@
       ],
       "format": "uuid"
     },
+    "session_id": {
+      "description": "Optional. Set when this message belongs to a Session orchestrator (see session.envelope.v1).",
+      "type": [
+        "string",
+        "null"
+      ],
+      "format": "uuid"
+    },
     "from": {
       "type": "string",
       "minLength": 3,

schemas/protocol/session.envelope.v1.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://axme.dev/schemas/protocol/session.envelope.v1.json",
+  "title": "SessionEnvelopeV1",
+  "description": "Wire envelope identifying a Session. A Session is a first-class orchestrator (separate from Intent) that holds Messages and may spawn Intents.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "session_id",
+    "correlation_id",
+    "created_at",
+    "owner_agent"
+  ],
+  "properties": {
+    "version": {
+      "type": "string",
+      "const": "v1"
+    },
+    "session_id": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "correlation_id": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "owner_agent": {
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 255
+    },
+    "visitor_ref": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255
+    },
+    "parent_session_id": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      }
+    }
+  }
+}

schemas/protocol/session.event.v1.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://axme.dev/schemas/protocol/session.event.v1.json",
+  "title": "SessionEventV1",
+  "description": "Append-only event in a Session event log. Monotonic seq per session. Sessions orchestrate Messages over DB+SSE and may spawn Intents; intent linkage is carried via intent_id on the relevant events.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "session_id",
+    "seq",
+    "event_type",
+    "at"
+  ],
+  "properties": {
+    "session_id": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "event_type": {
+      "type": "string",
+      "enum": [
+        "session.created",
+        "session.message",
+        "session.owner_intervened",
+        "session.intent_spawned",
+        "session.intent_resolved",
+        "session.resolved",
+        "session.reopened",
+        "session.closed",
+        "session.pruned"
+      ]
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "OPEN",
+        "WAITING_OWNER",
+        "RESOLVED",
+        "CLOSED",
+        "PRUNED"
+      ]
+    },
+    "at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "actor": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255
+    },
+    "intent_id": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "message_id": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "payload": {
+      "type": "object"
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": {
+        "type": [
+          "string",
+          "number",
+          "integer",
+          "boolean",
+          "null"
+        ]
+      }
+    }
+  }
+}

schemas/protocol/session.lifecycle.v1.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://axme.dev/schemas/protocol/session.lifecycle.v1.json",
+  "title": "SessionLifecycleV1",
+  "description": "Lifecycle state of a Session. Unlike Intent (forward-only, terminal-final), a Session is bidirectional: a RESOLVED session may transition back to OPEN when the visitor returns.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "session_id",
+    "correlation_id",
+    "status",
+    "seq",
+    "created_at",
+    "updated_at"
+  ],
+  "properties": {
+    "session_id": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "correlation_id": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "OPEN",
+        "WAITING_OWNER",
+        "RESOLVED",
+        "CLOSED",
+        "PRUNED"
+      ]
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "owner_agent": {
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 255
+    },
+    "visitor_ref": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255
+    },
+    "parent_session_id": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "last_activity_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": {
+        "type": [
+          "string",
+          "number",
+          "integer",
+          "boolean",
+          "null"
+        ]
+      }
+    }
+  }
+}

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

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://axme.dev/schemas/public_api/api.sessions.create.request.v1.json",
+  "title": "ApiSessionsCreateRequestV1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "to_agent",
+    "correlation_id"
+  ],
+  "properties": {
+    "to_agent": {
+      "description": "The owner's published agent address (or resolved internal agent address) the visitor is opening a conversation with.",
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 383
+    },
+    "correlation_id": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "from_agent": {
+      "description": "Deprecated — the visitor identity is derived from the authenticated visitor session. Accepted for backward compatibility but ignored by the server.",
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 383
+    },
+    "parent_session_id": {
+      "description": "Optional parent session for multi-session coordination.",
+      "type": "string",
+      "format": "uuid"
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": {
+        "type": [
+          "string",
+          "number",
+          "integer",
+          "boolean",
+          "null"
+        ]
+      }
+    }
+  }
+}