feat(messages): add send_at per-message scheduling (cueapi #623 parity)

[mikemolinet]

Summary

Adds send_at to MessagesResource.send(), covering server PR #623 (per-message scheduling).

Caller can now schedule message delivery to a specific timestamp instead of always-immediate:

client.messages.send(
    from_agent="sender@you",
    to="recipient@me",
    body="hi",
    send_at="2030-01-01T12:00:00Z",   # str
)

# or with a datetime:
from datetime import datetime, timezone
client.messages.send(
    from_agent="sender@you",
    to="recipient@me",
    body="hi",
    send_at=datetime(2030, 1, 1, 12, 0, tzinfo=timezone.utc),
)

Implementation notes

• Optional[Union[str, datetime]] — auto-serialized via .isoformat() (same convention as cues.create(at=...) and the new cues.fire(send_at=...) from PR feat(cues): add send_at + exit_criteria + idempotency_key to fire() #33).
• Sent as a body field, not a header — matches the server contract.
• Backwards compatible: defaults to None, omitted from the request body when unset. Existing call sites unchanged.

Tests

3 new mock-based tests in test_messages_resource.py::TestSendAt (matches existing test style in this file — asserts on the request body shape rather than against staging):

1. test_send_with_send_at_iso_string — ISO string flows verbatim
2. test_send_with_send_at_datetime_auto_isoformats — datetime → ISO 8601 with tz preserved
3. test_send_without_send_at_omits_field — unset means field NOT in body

Source

Drift audit handoff/cueapi-package-drift-2026-05-06. Backlog row "Parity port: PR #623 (POST /v1/messages send_at) → cueapi-python" (p1, CTO-SEC-DRIFT-AUDIT-AUTHORIZE 2026-05-06).

Related

• cueapi-python PR feat(cues): add send_at + exit_criteria + idempotency_key to fire() #33 — adds send_at + exit_criteria + idempotency_key to cues.fire() (cueapi #618 / #632 / #683 ports). Same datetime serialization pattern.
• cueapi-action PR security: pin GitHub Actions to commit SHAs #6 — exposes messages-send Action command but does not yet have a send-at input. Follow-up PR will add it once cueapi-cli ports --send-at (Action drift bounded by upstream).

Test plan

• All 3 new tests pass via mock
• No regressions in existing TestSend tests
• Pyright clean once it picks up the new signature

🤖 Generated with Claude Code