Skip to content

feat: add fire + list_claimable + claim + claim_next#23

Open
mikemolinet wants to merge 1 commit intomainfrom
feat/fire-and-claim-methods
Open

feat: add fire + list_claimable + claim + claim_next#23
mikemolinet wants to merge 1 commit intomainfrom
feat/fire-and-claim-methods

Conversation

@mikemolinet
Copy link
Copy Markdown
Collaborator

Same change as the (now-closed) fork PR #22. Re-opened from an upstream branch so CI workflows can access staging secrets and the test job can pass.

Summary

Brings cueapi-sdk toward parity with @cueapi/mcp 0.3.0 + 0.4.0 surface. Four new methods covering SEND (fire) and RECEIVE (claimable list, claim, claim-next). Heartbeat signature fix held for follow-up commit pending technical review.

What's added

CuesResource:

  • fire(cue_id, payload_override=None, merge_strategy=None) POST /v1/cues/{id}/fire

ExecutionsResource:

  • list_claimable(task=None, agent=None) GET /v1/executions/claimable?task=&agent= (server-side filter)
  • claim(execution_id, worker_id=...) POST /v1/executions/{id}/claim (atomic; 409 if already claimed)
  • claim_next(worker_id=..., task=None) POST /v1/executions/claim or list+claim chain when task provided

Notable

  • list_claimable is server-side query params, not client-side filter. Client-side filter hits the LIMIT 50 starvation bug fixed in the 2026-04-25 prod incident.
  • claim_next(task=...) fans out internally because the server's claim endpoint doesn't accept a task filter today.

Tests

42 unit tests pass (was 30; +12 net). Mirrors the existing MagicMock pattern in tests/test_executions_resource.py.

Version

0.1.3 -> 0.2.0. Aligned cueapi/init.py (had drifted to 0.1.2) with pyproject.toml at the same time.

Pending follow-up (NOT in this PR)

ExecutionsResource.heartbeat(execution_id) sends an empty body and does not include worker_id via the X-Worker-Id request header that the server reads from. Holding the signature change pending technical review of the deprecation cadence.

Brings the Python SDK toward parity with the @cueapi/mcp 0.3.0 + 0.4.0
surface. Adds four new methods covering the SEND side (fire) and the
RECEIVE side (claimable list, claim, claim-next). Heartbeat signature
fix is held for a follow-up commit pending technical review.

CuesResource:
- fire(cue_id, payload_override=None, merge_strategy=None)
  POST /v1/cues/{id}/fire. 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).

ExecutionsResource:
- list_claimable(task=None, agent=None)
  GET /v1/executions/claimable?task=&agent=
  Filters server-side via query params (NOT client-side). Required for
  single-purpose workers; client-side filter after fetch hits the LIMIT
  50 starvation bug fixed in the 2026-04-25 prod incident.

- claim(execution_id, worker_id=...)
  POST /v1/executions/{id}/claim
  Atomic; returns 409 if already claimed.

- claim_next(worker_id=..., task=None)
  POST /v1/executions/claim (no task) OR list+claim chain (with task).
  Server's claim endpoint does not accept a task filter today; with task
  the SDK fans out (list_claimable filtered, pick oldest, claim by ID).
  Tiny race window between list and claim is bounded by the atomic claim
  returning 409, in which case the caller retries.

Version: 0.1.3 -> 0.2.0. Aligned cueapi/__init__.py (had drifted to
0.1.2) with pyproject.toml at the same time.

Tests: 42 unit tests pass (was 30; +12 net). Mirrors the existing
MagicMock pattern in tests/test_executions_resource.py.

Pending follow-up:
- ExecutionsResource.heartbeat(execution_id) currently sends an empty
  body and does not include worker_id via the X-Worker-Id request
  header that the server reads from. Worker-id is what the server uses
  to enforce ownership on heartbeat (returns 403 on mismatch); without
  it the race-protection check is silently bypassed. A signature change
  to add worker_id is held pending technical review of the deprecation
  cadence (additive kwarg-only with default-warn-on-omit vs hard
  signature change in a major bump).

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant