feat: add fire + list_claimable + claim + claim_next#23
Open
mikemolinet wants to merge 1 commit intomainfrom
Open
feat: add fire + list_claimable + claim + claim_next#23mikemolinet wants to merge 1 commit intomainfrom
mikemolinet wants to merge 1 commit intomainfrom
Conversation
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]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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}/fireExecutionsResource:
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 providedNotable
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.