feat(cues): add send_at + exit_criteria + idempotency_key to fire()

Extends the existing CuesResource.fire() method with three kwargs
covering recently-shipped server features:

  - send_at (str | datetime, cueapi #618)
      Per-fire scheduling — delay this fire to a specific timestamp
      instead of executing immediately.

  - exit_criteria (dict, cueapi #632)
      Per-fire termination conditions. Dict shape mirrors the API
      contract; SDK passes through verbatim.

  - idempotency_key (str, cueapi #683)
      Optional Idempotency-Key header. Same key + same body within
      24h returns the existing execution (HTTP 200) instead of a
      fresh fire; same key + different body returns 409
      idempotency_key_conflict. Sent as a request header, not a body
      field.

datetime is auto-serialized to ISO 8601 via .isoformat().

Backwards compatible — all three kwargs default to None, omitted from
the request body when unset. Existing fire(cue_id) and
fire(cue_id, payload_override=..., merge_strategy=...) calls are
unchanged.

6 new tests in test_cues.py::TestCueFire (no-args, payload-override,
merge_strategy=replace, send_at, idempotency_key replay returns same
exec, return-shape-is-dict-not-Cue). All run against staging via the
existing client + cue fixtures.

Source: drift audit handoff/cueapi-package-drift-2026-05-06; Backlog
rows "Parity port: PR #618 → cueapi-python", "PR #632 → cueapi-python",
implicit on idempotency from #683 (which dropped today; no separate
backlog row yet).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mikemolinet

cueapi/resources/cues.py

@@ -225,29 +225,70 @@ def fire(
         *,
         payload_override: Optional[Dict[str, Any]] = None,
         merge_strategy: Optional[str] = None,
+        send_at: Optional[Union[str, datetime]] = None,
+        exit_criteria: Optional[Dict[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
     ) -> Dict[str, Any]:
-        """Fire an existing cue immediately, optionally overriding its payload.
+        """Fire an existing cue, optionally overriding payload + scheduling.
 
-        For ad-hoc one-shot triggers and for using cues as a messaging channel
-        between agents (carry message/instruction/task/reply_cue_id in
-        payload_override).
+        ``POST /v1/cues/{cue_id}/fire``. Returns the created execution
+        dict (not a Cue) — fire creates an execution row, not a new cue.
+
+        Useful for ad-hoc one-shot triggers and for using cues as a
+        messaging channel between agents (carry message/instruction/task/
+        reply_cue_id in ``payload_override``).
 
         Args:
             cue_id: The cue ID to fire.
-            payload_override: Override the cue's default payload for this fire
-                only. Persisted on the resulting execution row, never on the
-                cue itself.
-            merge_strategy: How payload_override combines with the cue's stored
-                payload. "merge" (server default) shallow-merges with override
-                wins on key collisions. "replace" uses override as the final
-                payload, ignoring cue.payload.
+            payload_override: Override the cue's default payload for this
+                fire only. Persisted on the resulting execution row, never
+                on the cue itself.
+            merge_strategy: How ``payload_override`` combines with the
+                cue's stored payload. ``"merge"`` (server default) shallow-
+                merges with override wins on key collisions. ``"replace"``
+                uses override as the final payload, ignoring ``cue.payload``.
+            send_at: Optional ISO 8601 timestamp (or ``datetime``) to
+                delay this fire. If omitted, the execution is scheduled
+                immediately. Per-fire scheduling landed in cueapi #618.
+            exit_criteria: Optional per-fire termination conditions
+                (cueapi #632). Dict shape mirrors the API contract;
+                keys vary by criterion type.
+            idempotency_key: Optional ``Idempotency-Key`` header
+                (cueapi #683). Same key + same body within 24h returns
+                the existing execution with HTTP 200 instead of creating
+                a new fire; same key + different body returns 409
+                ``idempotency_key_conflict``.
 
         Returns:
-            The execution dict (id, scheduled_for, status, etc.).
+            The execution dict (id, scheduled_for, status, triggered_by,
+            etc.).
+
+        Examples:
+            >>> exec = client.cues.fire("cue_abc123")
+            >>> exec = client.cues.fire(
+            ...     "cue_abc123",
+            ...     payload_override={"task": "manual-trigger"},
+            ...     send_at="2026-05-07T12:00:00Z",
+            ...     idempotency_key="ci-run-456",
+            ... )
         """
         body: Dict[str, Any] = {}
         if payload_override is not None:
             body["payload_override"] = payload_override
         if merge_strategy is not None:
             body["merge_strategy"] = merge_strategy
-        return self._client._post(f"/v1/cues/{cue_id}/fire", json=body)
+        if send_at is not None:
+            body["send_at"] = (
+                send_at.isoformat() if isinstance(send_at, datetime) else send_at
+            )
+        if exit_criteria is not None:
+            body["exit_criteria"] = exit_criteria
+
+        headers = {}
+        if idempotency_key is not None:
+            headers["Idempotency-Key"] = idempotency_key
+
+        kwargs: Dict[str, Any] = {"json": body}
+        if headers:
+            kwargs["headers"] = headers
+        return self._client._post(f"/v1/cues/{cue_id}/fire", **kwargs)

tests/test_cues.py

@@ -118,3 +118,71 @@ def test_delete(self, client):
         client.cues.delete(cue.id)
         with pytest.raises(CueNotFoundError):
             client.cues.get(cue.id)
+
+
+class TestCueFire:
+    """Tests for the fire() method (manual trigger / per-fire override).
+
+    All tests run against a real cue (the ``cue`` fixture creates one for
+    each test). Fire creates an execution row; we don't poll the
+    execution status here — the worker/poller pipeline isn't exercised
+    by the SDK suite. We just verify the fire response shape and HTTP
+    success.
+    """
+
+    def test_fire_no_args(self, client, cue):
+        """Bare fire() — no payload override, no scheduling, immediate."""
+        execution = client.cues.fire(cue.id)
+        # Server returns the created execution dict
+        assert "id" in execution
+        assert execution["cue_id"] == cue.id
+        # Triggered manually should set triggered_by accordingly
+        assert execution.get("triggered_by") in ("manual_fire", "manual")
+        # Default scheduling is immediate (or close to it)
+        assert "scheduled_for" in execution
+
+    def test_fire_with_payload_override(self, client, cue):
+        """Fire with payload_override — execution carries the override."""
+        execution = client.cues.fire(
+            cue.id,
+            payload_override={"task": "manual", "trigger": "test"},
+        )
+        assert "id" in execution
+        # Default merge_strategy is server-side merge — we don't assert
+        # on the merged result here (that's a server test); just verify
+        # the call shape was accepted.
+
+    def test_fire_with_merge_strategy_replace(self, client, cue):
+        """Replace strategy — payload_override fully replaces stored payload."""
+        execution = client.cues.fire(
+            cue.id,
+            payload_override={"action": "replace-test"},
+            merge_strategy="replace",
+        )
+        assert "id" in execution
+
+    def test_fire_with_send_at(self, client, cue):
+        """send_at delays this fire to a specific timestamp (cueapi #618)."""
+        future = "2030-01-01T12:00:00Z"
+        execution = client.cues.fire(cue.id, send_at=future)
+        assert "id" in execution
+        # Server reflects the requested scheduled_for
+        # (allow some tolerance — server may normalize the timestamp)
+        assert "scheduled_for" in execution
+
+    def test_fire_with_idempotency_key(self, client, cue):
+        """Idempotency-Key replays the same fire (cueapi #683)."""
+        import uuid
+
+        key = f"sdk-test-{uuid.uuid4().hex[:8]}"
+        first = client.cues.fire(cue.id, idempotency_key=key)
+        second = client.cues.fire(cue.id, idempotency_key=key)
+        # Same key + same body → server returns the SAME execution
+        assert first["id"] == second["id"]
+
+    def test_fire_returns_dict_not_cue(self, client, cue):
+        """Sanity: fire returns the execution dict (not a typed Cue)."""
+        result = client.cues.fire(cue.id)
+        # Not a Cue object — fire creates an execution, not a new cue
+        assert not isinstance(result, Cue)
+        assert isinstance(result, dict)