feat(agents): add roster() + presence() methods (cueapi #630 + #662 parity)#35
Merged
Merged
Conversation
…arity)
Adds two SDK methods to ``AgentsResource`` covering the Agent Directory
v0/v1/v2 surface:
- ``roster(*, if_none_match=None)`` — GET /v1/agents/roster
Lists every agent owned by the calling key with a presence block
(online, derived_status, bucketed_seen, default_live cue, labeled
sessions, etag). Supports ``If-None-Match`` header so cheap-poll
callers can skip the payload when the directory hasn't changed.
- ``presence(ref)`` — GET /v1/agents/{ref}/presence
Lighter than ``get(ref)`` — returns just the presence-relevant
fields (online, derived_status, bucketed_seen, default_live,
labeled_sessions, etag) without the full agent record. Designed
for UIs refreshing a single tile every few seconds without
re-fetching the directory or full agent record.
4 new mock-based tests in test_agents_resource.py:
- test_roster_no_etag — no If-None-Match header by default
- test_roster_with_if_none_match — header flows as ``If-None-Match``
- test_presence_by_id — opaque agent_id path
- test_presence_by_slug_form — slug@user path
Source: drift audit handoff/cueapi-package-drift-2026-05-06; Backlog
rows "Parity port: PR #630 (GET /v1/agents/roster) → cueapi-python"
+ "Parity port: PR #662 (GET /v1/agents/{ref}/presence) → cueapi-python"
(both p2, CTO-SEC-DRIFT-AUDIT-AUTHORIZE 2026-05-06).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
mikemolinet
added a commit
that referenced
this pull request
May 9, 2026
…t recent ports (#36) Manifest was 3 days stale; many endpoints listed as missing have been ported since the last audit. Moved from endpoints_missing → endpoints_covered (with PR refs): - POST /v1/cues/{id}/fire (PR #23; in-flight kwargs in #33) - POST /v1/executions/{id}/replay (PR #25) - GET /v1/executions/claimable (PR #23) - POST /v1/executions/{id}/claim (PR #23) - POST /v1/executions/claim (PR #23) - GET /v1/workers + DELETE /v1/workers/{id} (PR #26) - GET /v1/usage (PR #26) - POST /v1/agents + GET/PATCH/DELETE /v1/agents/{ref} + GET /v1/agents/{ref}/webhook-secret + GET /v1/agents/{ref}/inbox + /sent (PR #27) - POST /v1/messages + GET/read/ack (PR #28) Added in-flight refs (open PRs): - GET /v1/agents/roster (in-flight PR #35; cueapi #630 parity) - GET /v1/agents/{ref}/presence (in-flight PR #35; cueapi #662 parity) - send_at + exit_criteria + idempotency_key kwargs on fire (PR #33) - send_at kwarg on messages.send (PR #34) New endpoints_missing items (post-audit): - POST /v1/agents/{ref}/webhook-secret/regenerate (destructive; tracked) - DELETE /v1/messages bulk (cueapi #650; bounded by cueapi-cli upstream) - POST /v1/executions/{id}/live-claim (cueapi #664; handler-runtime, not SDK) New "in_flight_ports_2026_05_07" section listing all 4 currently-open SDK PRs with PR-overlap notes (PR #30/#33 lane-flagged with cueapi-main). Bumped sdk_version_at_audit 0.1.3 → 0.2.x. This refresh closes the Backlog row "Refresh cueapi-python parity-manifest.json" filed earlier today (Self-flag 2026-05-07). Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
mikemolinet
added a commit
that referenced
this pull request
May 12, 2026
…dy coverage, bump audit to 2026-05-12 (#43) Manifest was dated 2026-05-07 and missing the PR-1b event-emit endpoint coverage (4 endpoints) plus the body-verify Phase 2 + inline_body extensions that shipped 2026-05-09 → 2026-05-12. Brings the manifest back in sync with SDK head. Endpoints added to `endpoints_covered`: - POST /v1/agents/{ref}/subscriptions (subscriptions_create, PR #38; inline_body kwarg in PR #42 / cueapi #791 Item 1) - GET /v1/agents/{ref}/subscriptions (subscriptions_list, PR #38) - DELETE /v1/agents/{ref}/subscriptions/{sub_id} (subscriptions_delete, PR #38) - GET /v1/agents/{ref}/events (events_pull, PR #38) Updates to existing entries: - POST /v1/messages — added auto_verify body-verify Phase 2 (PR #39 + #40, cueapi/cueapi #795 + #798 parity) - POST /v1/cues/{id}/fire — note that #33 shipped (was "in-flight") - GET /v1/agents/roster — note that #35 shipped (was "in-flight") - GET /v1/agents/{ref}/presence — note that #35 shipped (was "in-flight") Replaced `in_flight_ports_2026_05_07` section with `ports_shipped_2026_05_08_to_2026_05_12` (now-resolved entries) plus a near-empty `ports_in_flight_2026_05_12` placeholder for future ports. Backlog row: cmp1vukmc. Out of scope: - `model_drift` section walk-through (Cue/Execution/Worker missing fields) — PR #31 just landed the Execution + Worker + Agent + Message additive models; a fuller `model_drift` refresh deserves a separate audit pass against the now-shipped models to figure out what's still drifting.
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
Adds two SDK methods to
AgentsResourcecovering the Agent Directory v0/v1/v2 surface:agents.roster(if_none_match=None)GET /v1/agents/rosteragents.presence(ref)GET /v1/agents/{ref}/presenceUse cases
roster(): directory UIs (Cue Bar, Dock CMA), sender-side recipient choice based on presencepresence(ref): UI tiles that refresh every few seconds without re-fetching the directory or full agent recordETag support on roster
roster()accepts anif_none_matchkwarg flowing as theIf-None-MatchHTTP header. When the server determines the directory hasn't changed since that ETag, it returns 304 Not Modified — the client lib will surface that as aCueAPIErrorwith status 304 (caller catches and reuses the cached payload).Tests
4 new mock-based tests in
test_agents_resource.py:test_roster_no_etag— noIf-None-Matchheader by defaulttest_roster_with_if_none_match— header flows correctly with weak-etag prefixtest_presence_by_id— opaqueagt_<12 alnum>pathtest_presence_by_slug_form—slug@userpathSource
Drift audit
handoff/cueapi-package-drift-2026-05-06. Backlog rows:Related
cues.fire()send_at/exit_criteria/idempotency_key (#618 + #632 + #683)messages.send()send_at (#623)Test plan
roster()andpresence()correctly added to public AgentsResource API🤖 Generated with Claude Code