Conformance + reference operators: 201 Created for resource creation

POST /sessions and POST /sessions/{id}/messages both create new
resources identifiable by `session_id` / `message_id`, which is the
textbook 201 Created case per RFC 9110 §15.3.2. The conformance suite
was previously asserting 200 — that was forcing every operator to be
HTTP-incorrect to pass conformance. Pin to 201 instead.

- tests/conformance/test_sessions.py + test_messages.py: status_code
  expectations bumped from 200 to 201 for the create endpoints.
  Lifecycle verbs (join, invite, leave, end, reopen) keep 200.
- cli/src/server/protocol/sessions.ts (TypeScript reference operator):
  returns 201 for both create endpoints.
- examples/local-operator/asp_operator/app.py (Python reference
  operator): adds `status_code=201` to the matching `@app.post`
  decorators.
- cli/tests/sessions-routes.test.ts: assertions updated.

All three reference operators (TypeScript example, Python example,
in-tree robotnet-cli operator) now pass the updated 29/29
conformance suite. Idempotent-replay returns 201 on both calls
(first creates, replay returns the original 201 response) — Stripe-
style 201/200 split could be added later if useful but the simpler
"201 every time" is sufficient.

Author: nrcrews

cli/src/server/protocol/sessions.ts

@@ -64,12 +64,18 @@ export function buildSessionRoutes(
       ...(parsed.end_after_send === true ? { endAfterSend: true } : {}),
     });
 
-    return c.json({
-      session_id: result.session.id,
-      ...(result.messageSequence !== undefined
-        ? { sequence: result.messageSequence }
-        : {}),
-    });
+    // 201 Created per RFC 9110 §15.3.2: a new session resource is identified
+    // by `session_id`. Lifecycle verbs (join, invite, leave, end, reopen)
+    // mutate state without creating a top-level resource and stay 200.
+    return c.json(
+      {
+        session_id: result.session.id,
+        ...(result.messageSequence !== undefined
+          ? { sequence: result.messageSequence }
+          : {}),
+      },
+      201,
+    );
   });
 
   // ── GET / — list sessions for the calling agent ───────────────────────────
@@ -154,7 +160,12 @@ export function buildSessionRoutes(
     } catch (err) {
       return mapSessionError(c, err);
     }
-    return c.json({ message_id: result.messageId, sequence: result.sequence });
+    // 201 Created per RFC 9110 §15.3.2: a new message resource is identified
+    // by `message_id`.
+    return c.json(
+      { message_id: result.messageId, sequence: result.sequence },
+      201,
+    );
   });
 
   // ── POST /:id/leave ───────────────────────────────────────────────────────

cli/tests/sessions-routes.test.ts

@@ -74,7 +74,7 @@ describe("POST /sessions", () => {
       headers: agentHeaders(agent.token),
       body: JSON.stringify({}),
     });
-    assert.equal(res.status, 200);
+    assert.equal(res.status, 201);
     const body = (await json(res)) as { session_id: string };
     assert.ok(body.session_id.startsWith("sess_"));
   });
@@ -87,7 +87,7 @@ describe("POST /sessions", () => {
       headers: agentHeaders(alice.token),
       body: JSON.stringify({ invite: ["@bob.bot"] }),
     });
-    assert.equal(res.status, 200);
+    assert.equal(res.status, 201);
     const body = (await json(res)) as { session_id: string };
     const sess = s.sessionStore.get(body.session_id)!;
     const bob = sess.participants.find((p) => p.handle === "@bob.bot");
@@ -128,7 +128,7 @@ describe("POST /sessions", () => {
       headers: agentHeaders(alice.token),
       body: JSON.stringify({ invite: ["@bob.bot", "@ghost.bot"] }),
     });
-    assert.equal(res.status, 200);
+    assert.equal(res.status, 201);
     const body = (await json(res)) as { session_id: string };
     const sess = s.sessionStore.get(body.session_id)!;
     assert.equal(sess.participants.length, 2); // alice + bob
@@ -252,7 +252,7 @@ describe("POST /sessions/:id/messages", () => {
       headers: agentHeaders(alice.token),
       body: JSON.stringify({ content: "hello!" }),
     });
-    assert.equal(res.status, 200);
+    assert.equal(res.status, 201);
     const body = (await json(res)) as { message_id: string; sequence: number };
     assert.ok(body.message_id.startsWith("msg_"));
     assert.equal(typeof body.sequence, "number");

examples/local-operator/asp_operator/app.py

@@ -81,7 +81,10 @@ def auth_handle(request: Request) -> str:
 
     # ---- Sessions ------------------------------------------------------
 
-    @app.post("/sessions")
+    # 201 Created per RFC 9110 §15.3.2: a new session resource is identified
+    # by `session_id`. Lifecycle verbs (join, invite, leave, end, reopen)
+    # mutate state without creating a top-level resource and stay 200.
+    @app.post("/sessions", status_code=201)
     async def post_sessions(body: CreateSessionBody, request: Request):
         creator = auth_handle(request)
         if body.end_after_send and body.initial_message is None:
@@ -130,7 +133,9 @@ async def post_invite(session_id: str, body: InviteBody, request: Request):
             raise HTTPException(status_code=404, detail="not found")
         return {"invited": invited}
 
-    @app.post("/sessions/{session_id}/messages")
+    # 201 Created per RFC 9110 §15.3.2: a new message resource is identified
+    # by `message_id`.
+    @app.post("/sessions/{session_id}/messages", status_code=201)
     async def post_message(session_id: str, body: SendMessageBody, request: Request):
         sender = auth_handle(request)
         try:

tests/conformance/test_messages.py

@@ -22,7 +22,7 @@ async def _join_session(alice, bob) -> str:
 async def test_send_message_returns_message_id_and_sequence(alice, bob):
     sid = await _join_session(alice, bob)
     resp = await alice.send_message(sid, "hello")
-    assert resp.status_code == 200
+    assert resp.status_code == 201
     body = resp.json()
     assert body["message_id"].startswith("msg_")
     assert isinstance(body["sequence"], int)
@@ -75,8 +75,10 @@ async def test_idempotency_key_dedupes_retries(alice, bob):
     r1 = await alice.send_message(sid, "duplicate", idempotency_key=key)
     r2 = await alice.send_message(sid, "duplicate", idempotency_key=key)
 
-    assert r1.status_code == 200
-    assert r2.status_code == 200
+    # Both calls return 201 (idempotent replay returns the original 201, not 200) —
+    # spec accepts either, but the local operator currently returns 201 on both.
+    assert r1.status_code == 201
+    assert r2.status_code == 201
     assert r1.json()["message_id"] == r2.json()["message_id"]
     assert r1.json()["sequence"] == r2.json()["sequence"]
 
@@ -95,7 +97,7 @@ async def test_multipart_content_is_supported(alice, bob):
         {"type": "data", "data": {"action": "review_complete", "doc_id": "abc"}},
     ]
     resp = await alice.send_message(sid, parts)
-    assert resp.status_code == 200
+    assert resp.status_code == 201
 
     event = await bob.expect_event("session.message", session_id=sid)
     received = event["payload"]["content"]

tests/conformance/test_sessions.py

@@ -15,7 +15,7 @@
 async def test_create_session_returns_session_id(alice, bob):
     """POST /sessions with one invitee returns a session_id (Appendix C.1)."""
     resp = await alice.create_session(invite=[bob.handle])
-    assert resp.status_code == 200
+    assert resp.status_code == 201
     body = resp.json()
     assert "session_id" in body
     assert body["session_id"].startswith("sess_")
@@ -24,7 +24,7 @@ async def test_create_session_returns_session_id(alice, bob):
 async def test_create_session_with_zero_invitees(alice):
     """A session with zero invitees is permitted (Whitepaper §6.3)."""
     resp = await alice.create_session()
-    assert resp.status_code == 200
+    assert resp.status_code == 201
     assert "session_id" in resp.json()