feat(tools): add cueapi_get_execution for single-execution lookup#10
Closed
mikemolinet wants to merge 1 commit intocueapi:mainfrom
Closed
feat(tools): add cueapi_get_execution for single-execution lookup#10mikemolinet wants to merge 1 commit intocueapi:mainfrom
mikemolinet wants to merge 1 commit intocueapi:mainfrom
Conversation
Adds an MCP tool that wraps GET /v1/executions/{id}, the natural
follow-up to cueapi_fire_cue (which returns an execution_id) when an
agent wants to confirm delivery state without paginating
cueapi_list_executions to find the same row.
Reuses the existing executionIdSchema (already defined but previously
unused). Same complementary shape that cueapi_get_cue is to
cueapi_list_cues.
- src/tools.ts: +11 LoC (tool definition; reuses executionIdSchema)
- tests/tools.test.ts: +54 LoC (3 HTTP-contract tests mirroring the
existing get_cue / fire_cue patterns: GET method + path, no body
or query, url-encoded execution_id)
- README.md: add row to "Tools exposed" table + changelog entry
- package.json: bump 0.3.0 → 0.4.0
No backend changes — GET /v1/executions/{id} already exists in the
CueAPI backend (executions.py:204). All 53 tests pass (was 48).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Collaborator
Author
|
Superseded by #11, which folds cueapi_get_execution into the larger execution-lifecycle batch (5 tools + small CueAPIClient header-support mod). Closing here. |
mikemolinet
added a commit
that referenced
this pull request
May 2, 2026
…im-next/heartbeat
Closes the receive-claim-process-complete loop for MCP-host agents that
want to consume worker-transport executions from in-session, alongside
the SEND side that 0.3.0 added with cueapi_fire_cue.
Five new tools:
- cueapi_get_execution(execution_id)
Wraps GET /v1/executions/{id}. Single-row lookup; the natural
follow-up to cueapi_fire_cue's returned execution_id.
- cueapi_list_claimable_executions(task_name?, agent?)
Wraps GET /v1/executions/claimable with the task/agent QUERY PARAMS.
Filtering MUST be server-side — client-side filter after fetch hits
the LIMIT 50 starvation bug fixed in the 2026-04-25 prod incident
(see app/routers/executions.py:122-131).
- cueapi_claim_execution(execution_id, worker_id)
Wraps POST /v1/executions/{id}/claim. Atomic conditional UPDATE;
returns 409 if already claimed.
- cueapi_claim_next_execution(worker_id, task_name?)
Wraps POST /v1/executions/claim. Without task_name → single API
call. With task_name → internal fan-out (filtered list_claimable →
pick oldest → claim by ID), since the server's claim endpoint
doesn't yet accept a task filter. Tiny race window between list
and claim is bounded by the atomic claim returning 409 → caller
retries.
- cueapi_execution_heartbeat(execution_id, worker_id)
Wraps POST /v1/executions/{id}/heartbeat. Sends worker_id via
the X-Worker-Id REQUEST HEADER (the server's actual transport for
that field — declared as Header(None), not in the request body).
worker_id is REQUIRED in the MCP schema even though the server
permits omission, so misconfigured callers fail at the wrapper
instead of silently bypassing race protection.
Internal change:
- CueAPIClient.request() gains optional extraHeaders parameter
(~5 LoC). Defaults are merged first; extraHeaders override them;
Authorization is set last so a caller can never accidentally
clobber the bearer token. Used by execution_heartbeat today;
available for any future endpoint that needs custom headers.
Deferred from this PR:
- report_outcome enum refinement (PRD v3 §"Cowork feedback
dispositions" #4): server's OutcomeRequest only accepts success:
bool — there's no outcome_state field, and 'timed_out' from the
proposed enum isn't worker-reportable (server detects timeout via
heartbeat lapse; if a worker can call the API, it didn't time
out). Defer to a follow-up PR where we can resolve the
timed_out semantics + the breaking-vs-additive call separately.
Flagged back to PM for re-clarification.
All 65 tests pass (was 48; +17 net): 5 added to surface-coverage
list, 12 new HTTP-contract tests across 5 new describe blocks.
npm run build clean.
Supersedes #10 (cueapi_get_execution as a standalone PR — folded
into this batch).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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
1 participant
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.
Summary
Companion follow-up to #9 (
cueapi_fire_cue). Addscueapi_get_execution(execution_id)— fetches a single execution by ID, including state, outcome, and any attached evidence.The natural shape:
cueapi_fire_cuereturns anexecution_id; withoutget_execution, the only way to look that one row up is paginatingcueapi_list_executions. Same complementary shape thatcueapi_get_cuealready has tocueapi_list_cues.Changes
src/tools.tsexecutionIdSchema(already defined at line 72 but previously unused — looks like it was sitting there waiting for this)tests/tools.test.tscueapi_get_cue/cueapi_fire_cuepatterns (GET method + path, no body or query, url-encoded execution_id)README.mdpackage.json0.3.0→0.4.0(minor — additive new feature)Tool shape
Tests
npm test— all 53 tests pass (was 48; +5 net).npm run build— clean.Notes
GET /v1/executions/{id}(executions.py:204) — returns 404 if not found, otherwise the execution dict (same shape as items inlist_executions).listExecutionsSchemaor accidentally pipes args through, the handler could end up sending a body or query params on this single-row endpoint. Test pins the contract.