feat(cli): per-message send_at scheduling on messages send + message-to (#623)

Adds optional `--send-at` (ISO 8601 string) to `cueapi messages send`
and `cueapi message-to` — ports the private-monorepo cueapi #623
server-side change that's already shipped on POST /v1/messages
(MessageCreate.send_at in app/schemas/message.py).

Server contract pinned:
- NULL send_at (default) → send now
- Future timestamp → message gates inbox-fetch + push delivery until
  send_at <= now()
- Past timestamps → forgiving fallback (treated as send-now)
- Same semantics as cue-fire send_at (PR #618, already shipped)

Wire format: send_at flows in the BODY of POST /v1/messages, NOT a
header. Mirrors the cue-fire send_at transport. Different from
idempotency_key, which is a header. Verify-server-transport-per-
endpoint pinned in tests so a refactor doesn't accidentally promote
it to a header.

Tests:
- messages_send: 2 new (send_at_omitted_by_default, send_at_passed_in_body)
- message_to: 2 new (send_at_passed_in_body, send_at_omitted_when_unset)
- 171/171 pass total

This unblocks the cueapi-action port (its messages-send shell branch
needs the underlying CLI flag to surface --send-at to GitHub Actions
callers). Parallels cueapi-python (already shipped) and cueapi-mcp
(just shipped via PR #33) ports of the same private-monorepo PR #623.

Author: mikemolinet

cueapi/cli.py

@@ -1932,6 +1932,19 @@ def messages() -> None:
         "different body returns HTTP 409 idempotency_key_conflict."
     ),
 )
+@click.option(
+    "--send-at",
+    "send_at",
+    default=None,
+    help=(
+        "Optional ISO 8601 timestamp to schedule this message for future delivery "
+        "(hosted PR #623, §13). Omitted = send now (server default). When set in the "
+        "future, the message sits in the recipient's inbox-query gate until "
+        "send-at <= now(); push-delivery dispatch is also gated. Past timestamps "
+        "are treated as send-now (forgiving fallback). Same semantics as cue-fire "
+        "--send-at (PR #618). Sent as a BODY field on POST /v1/messages."
+    ),
+)
 @click.pass_context
 def messages_send(
     ctx: click.Context,
@@ -1945,6 +1958,7 @@ def messages_send(
     reply_to_agent: Optional[str],
     metadata: Optional[str],
     idempotency_key: Optional[str],
+    send_at: Optional[str],
 ) -> None:
     """Send a message."""
     body: dict = {"to": to, "body": body_text}
@@ -1965,6 +1979,11 @@ def messages_send(
             body["metadata"] = json.loads(metadata)
         except json.JSONDecodeError:
             raise click.UsageError("--metadata must be valid JSON")
+    # send_at flows in the body (server contract: MessageCreate.send_at,
+    # app/schemas/message.py). Mirrors cue-fire send_at transport (also a
+    # body field). Different from idempotency_key, which is a header.
+    if send_at:
+        body["send_at"] = send_at
 
     headers: dict = {"X-Cueapi-From-Agent": from_agent}
     if idempotency_key:
@@ -2237,6 +2256,19 @@ def _resolve_recipient(client, recipient: str) -> str:
         "24h returns the existing message with HTTP 200 instead of 201."
     ),
 )
+@click.option(
+    "--send-at",
+    "send_at",
+    default=None,
+    help=(
+        "Optional ISO 8601 timestamp to schedule this message for future delivery "
+        "(hosted PR #623, §13). Omitted = send now (server default). When set in the "
+        "future, the message sits in the recipient's inbox-query gate until "
+        "send-at <= now(); push-delivery dispatch is also gated. Past timestamps "
+        "are treated as send-now (forgiving fallback). Same semantics as cue-fire "
+        "--send-at (PR #618). Sent as a BODY field on POST /v1/messages."
+    ),
+)
 @click.pass_context
 def message_to(
     ctx: click.Context,
@@ -2251,6 +2283,7 @@ def message_to(
     metadata: Optional[str],
     mode: str,
     idempotency_key: Optional[str],
+    send_at: Optional[str],
 ) -> None:
     """Send a message to a recipient by name, slug, or agent ID.
 
@@ -2280,6 +2313,11 @@ def message_to(
     # senders. `auto` is also redundant to send.
     if mode != "auto":
         body["delivery_mode"] = mode
+    # send_at flows in the body (server contract: MessageCreate.send_at).
+    # Mirrors cue-fire send_at transport. Different from idempotency_key,
+    # which is a header.
+    if send_at:
+        body["send_at"] = send_at
 
     headers: dict = {"X-Cueapi-From-Agent": from_agent}
     if idempotency_key:

tests/test_cli.py

@@ -1969,6 +1969,61 @@ def test_messages_send_with_all_optionals(monkeypatch):
     assert headers["Idempotency-Key"] == "idemp-key-1"
 
 
+def test_messages_send_send_at_omitted_by_default(monkeypatch):
+    # Wire-format must match pre-#623 senders when --send-at is not passed.
+    # Server contract: NULL send_at === deliver immediately.
+    holder: dict = {}
+    _patch_messages_client(
+        monkeypatch,
+        holder,
+        responses={
+            ("POST", "/messages"): lambda: _FakeResp(
+                201, {"id": "msg_x", "delivery_state": "queued"}
+            )
+        },
+    )
+    result = runner.invoke(
+        main,
+        ["messages", "send", "--from", "sender@x", "--to", "recipient@y", "--body", "hello"],
+    )
+    assert result.exit_code == 0, result.output
+    body = holder["client"].calls[-1][2]
+    assert "send_at" not in body
+
+
+def test_messages_send_send_at_passed_in_body(monkeypatch):
+    # send_at flows in the body (server contract: MessageCreate.send_at,
+    # app/schemas/message.py). Mirrors cue-fire send_at transport.
+    holder: dict = {}
+    _patch_messages_client(
+        monkeypatch,
+        holder,
+        responses={
+            ("POST", "/messages"): lambda: _FakeResp(
+                201, {"id": "msg_x", "delivery_state": "queued"}
+            )
+        },
+    )
+    future = "2099-01-01T00:00:00Z"
+    result = runner.invoke(
+        main,
+        [
+            "messages", "send",
+            "--from", "sender@x",
+            "--to", "recipient@y",
+            "--body", "hello",
+            "--send-at", future,
+        ],
+    )
+    assert result.exit_code == 0, result.output
+    body = holder["client"].calls[-1][2]
+    assert body["send_at"] == future
+    # Verify it's a body field, NOT a header (regression guard).
+    headers = holder["client"].calls[-1][3]
+    assert "Send-At" not in headers
+    assert "X-Cueapi-Send-At" not in headers
+
+
 def test_messages_send_omits_expects_reply_when_unset(monkeypatch):
     # Default false MUST NOT appear in the body — server's Pydantic default
     # is false, and sending `expects_reply: false` explicitly creates noise.
@@ -2611,6 +2666,56 @@ def test_message_to_omits_expects_reply_when_unset(monkeypatch):
     assert "expects_reply" not in body
 
 
+def test_message_to_send_at_passed_in_body(monkeypatch):
+    # Same parity as `messages send` — send_at flows in body, not header.
+    holder: dict = {}
+    _patch_messages_client(
+        monkeypatch,
+        holder,
+        responses={
+            ("POST", "/messages"): lambda: _FakeResp(
+                201, {"id": "msg_z", "delivery_state": "queued"}
+            )
+        },
+    )
+    future = "2099-01-01T00:00:00Z"
+    result = runner.invoke(
+        main,
+        [
+            "message-to", "agt_x",
+            "--from", "y@z",
+            "--body", "hi",
+            "--send-at", future,
+        ],
+    )
+    assert result.exit_code == 0, result.output
+    body = holder["client"].calls[-1][2]
+    assert body["send_at"] == future
+    headers = holder["client"].calls[-1][3]
+    assert "Send-At" not in headers
+    assert "X-Cueapi-Send-At" not in headers
+
+
+def test_message_to_send_at_omitted_when_unset(monkeypatch):
+    holder: dict = {}
+    _patch_messages_client(
+        monkeypatch,
+        holder,
+        responses={
+            ("POST", "/messages"): lambda: _FakeResp(
+                201, {"id": "msg_z", "delivery_state": "queued"}
+            )
+        },
+    )
+    result = runner.invoke(
+        main,
+        ["message-to", "agt_x", "--from", "y@z", "--body", "hi"],
+    )
+    assert result.exit_code == 0
+    body = holder["client"].calls[-1][2]
+    assert "send_at" not in body
+
+
 def test_message_to_priority_validated_by_click_intrange():
     result = runner.invoke(
         main,