feat(subscriptions): add inline_body kwarg (cueapi #791 / Item 1 parity) (#42)

Server-side Item 1 (hosted PR #791) added `subscriptions.inline_body`
opt-in body embedding for pull subscriptions — when True, the source
message body is embedded in the event payload as `payload.body`,
eliminating the extra GET /v1/messages/{id} round-trip on the consumer
side.

This SDK port wires the kwarg through `AgentsResource.subscriptions_create()`:
optional `inline_body: Optional[bool] = None`. When None (default), the
field is OMITTED from the wire body — server default of False applies.
When True or False, the value is passed through verbatim.

Docstring updates:
- Document the 32KB cap (bodies > 32KB → `payload.body_omitted =
  "size_too_large"` + `payload.body_size_bytes = N`, consumer falls
  back to fetch).
- Note that both pull and webhook subscription responses surface
  `inline_body` so list-callers can observe own state.

Tests (3 new):
- test_inline_body_omitted_when_none — default case, no payload noise
- test_inline_body_true_passes_through — opt-in path
- test_inline_body_false_explicit_passes_through — explicit-False path
  (distinct from None for callers who want to force the no-embed
  contract).

Out of scope:
- Parity-manifest refresh: manifest is dated 2026-05-07 and missing
  the entire PR-1b event-emit coverage (subscriptions_create/list/
  delete + events_pull). Filing a separate Backlog row for the
  manifest refresh + audit-date bump.

Backlog row: cmp1v3ck3.

Author: mikemolinet

cueapi/resources/agents.py

@@ -252,6 +252,7 @@ def subscriptions_create(
         event_type: str,
         delivery_target: str,
         webhook_url: Optional[str] = None,
+        inline_body: Optional[bool] = None,
     ) -> Dict[str, Any]:
         """Create a subscription for an agent (PR-1b event-emit primitive).
 
@@ -266,11 +267,22 @@ def subscriptions_create(
                 ``"webhook"`` (server POSTs to ``webhook_url`` with HMAC).
             webhook_url: Required when ``delivery_target="webhook"``;
                 HTTPS only. Ignored for pull subscriptions.
+            inline_body: Opt into body embedding on emitted events
+                (server Item 1, hosted PR #791). When ``True``, the source
+                message body is embedded in the event payload as
+                ``payload.body`` — eliminates the extra
+                ``GET /v1/messages/{id}`` round-trip on the consumer side.
+                Bodies > 32KB are NOT embedded; instead the payload carries
+                ``payload.body_omitted = "size_too_large"`` and
+                ``payload.body_size_bytes = N`` so consumers can fall back
+                to the fetch. Default ``None`` means "don't send the field"
+                — server default is ``False``.
 
         Returns:
             Subscription dict. For webhook subscriptions, the response
             includes ``webhook_secret`` ONE-TIME — save it now; the
-            server never re-exposes it.
+            server never re-exposes it. Both pull and webhook responses
+            surface ``inline_body`` so list-callers can observe own state.
 
         Errors:
             400 ``unknown_event_type`` / ``invalid_delivery_target`` /
@@ -282,6 +294,8 @@ def subscriptions_create(
         }
         if webhook_url is not None:
             body["webhook_url"] = webhook_url
+        if inline_body is not None:
+            body["inline_body"] = inline_body
         return self._client._post(f"/v1/agents/{ref}/subscriptions", json=body)
 
     def subscriptions_list(self, ref: str) -> Dict[str, Any]:

tests/test_agents_resource.py

@@ -346,6 +346,67 @@ def test_webhook_url_omitted_when_none(self):
         body = mock_client._post.call_args.kwargs["json"]
         assert "webhook_url" not in body
 
+    def test_inline_body_omitted_when_none(self):
+        # Server-side default is False; sending an unset kwarg should
+        # NOT put the field on the wire (avoid payload noise for
+        # callers who don't care about body embedding).
+        mock_client = MagicMock()
+        mock_client._post.return_value = {"id": "sub_uuid"}
+        r = AgentsResource(mock_client)
+
+        r.subscriptions_create(
+            "agt_x",
+            event_type="message.received",
+            delivery_target="pull",
+        )
+
+        body = mock_client._post.call_args.kwargs["json"]
+        assert "inline_body" not in body
+
+    def test_inline_body_true_passes_through(self):
+        # Opt-in: inline_body=True embeds message.body on emitted events
+        # (server Item 1, hosted PR #791).
+        mock_client = MagicMock()
+        mock_client._post.return_value = {
+            "id": "sub_uuid",
+            "delivery_target": "pull",
+            "inline_body": True,
+        }
+        r = AgentsResource(mock_client)
+
+        r.subscriptions_create(
+            "agt_x",
+            event_type="message.received",
+            delivery_target="pull",
+            inline_body=True,
+        )
+
+        body = mock_client._post.call_args.kwargs["json"]
+        assert body["inline_body"] is True
+
+    def test_inline_body_false_explicit_passes_through(self):
+        # Explicit False (distinct from None / unset) — caller may want
+        # to force the no-embed contract on a per-subscription basis.
+        # We pass it through verbatim; server treats False the same as
+        # the schema default but explicit is non-noisy.
+        mock_client = MagicMock()
+        mock_client._post.return_value = {
+            "id": "sub_uuid",
+            "delivery_target": "pull",
+            "inline_body": False,
+        }
+        r = AgentsResource(mock_client)
+
+        r.subscriptions_create(
+            "agt_x",
+            event_type="message.received",
+            delivery_target="pull",
+            inline_body=False,
+        )
+
+        body = mock_client._post.call_args.kwargs["json"]
+        assert body["inline_body"] is False
+
 
 class TestSubscriptionsList:
     def test_get_path(self):