External/roboco
1
0
Fork 0
mirror of https://github.com/rennf93/roboco.git synced 2026-08-03 07:23:24 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
a402de61bc726379d1868748295525d0dad83226
roboco/docs/rag/tools/api-endpoints.md
T
Renzo FGitHubFrontend Developer 1Backend Developer 1Renn F
 547fe444f2 [4865ff8b] Add WebSocket support to the usage dashboard (#115) 
* [e7349d84] feat(dashboard): WS usage store, hook extension, status badge, and smooth animations (#111) (#113)

- Add src/store/usage-store.ts with typed UsageData interface, useUsageStore
  Zustand store, setUsageData, clearUsageData, and setWsState actions
- Export useUsageStore and UsageData from store/index.ts
- Extend use-rate-limit-websocket.ts: rename msg type to SystemWsMessage,
  add key_metrics field; add useEffect syncing wsState into useUsageStore;
  add USAGE_UPDATE/USAGE_SNAPSHOT handler dispatching to useUsageStore
  (RATE_LIMIT_HIT/LIFTED handling and onReconnect unchanged)
- Update CommandCenter to read key_metrics from useUsageStore when
  wsState === 'connected' and usageData non-null; falls back to
  useCeoOverview() (refetchInterval: 60000) when WS disconnected
- Update KeyMetricsPanel: add wsState prop, render connection status Badge
  matching AgentStreamViewer pattern (bg-green-500+Wifi / bg-yellow-500+
  Loader2 spin / bg-gray-500+WifiOff); add transition-all duration-300
  ease-in-out to metric value spans for smooth animated updates

Co-authored-by: Frontend Developer 1 <fe-dev-1@agents.roboco.dev>

* [c9745ee8] feat(events): add USAGE_UPDATE/SNAPSHOT event types, throttled publisher, /ws/system usage bridge (#112) (#114)

- Add EventType.USAGE_UPDATE='usage.update' and EventType.USAGE_SNAPSHOT='usage.snapshot'
  to the EventType StrEnum in roboco/models/events.py

- Create roboco/services/usage_events.py with _UsageThrottle class (5-second per-agent
  window using time.monotonic()) and publish_usage_update() / publish_usage_snapshot()
  helpers; lazy imports prevent circular dependency with roboco.events

- Extend orchestrator._sweep_token_snapshots() to publish USAGE_UPDATE per active agent
  (throttled) and a USAGE_SNAPSHOT aggregate after each sweep cycle; wrapped in
  contextlib.suppress so event errors never abort DB snapshot operations

- Add _handle_usage_event() to websocket_bridge.py following _handle_rate_limit_event
  pattern; register USAGE_UPDATE and USAGE_SNAPSHOT subscriptions in
  register_websocket_bridge_handlers() forwarding both to /ws/system via broadcast_system()

- Add unit tests: test_usage_events.py (throttle suppression, publish helpers) and
  test_websocket_bridge.py extended with _handle_usage_event coverage and updated
  registration assertion to include USAGE_UPDATE/USAGE_SNAPSHOT

Co-authored-by: Backend Developer 1 <be-dev-1@agents.roboco.dev>

* fix(usage-ws): reconcile the realtime token/cost contract end-to-end

The backend and frontend halves shipped mismatched contracts, so the usage
dashboard never received live data:

- The bridge forwarded the dotted event value ("usage.update") while the panel
  switched on "USAGE_UPDATE"; map both to the UPPER_SNAKE type string the same
  way the rate-limit handler does.
- The backend emitted token/cost telemetry but the frontend read a key_metrics
  field and fed the org-metrics panel. Rewire the frontend to consume the
  USAGE_SNAPSHOT token/cost payload into the "Token Usage & Cost" panel —
  WS-first with polling fallback and a connection-status badge — and revert the
  unrelated KeyMetricsPanel / CommandCenter wiring.

Backend cleanups in the same path:

- Replace the multi-argument publish helpers with typed UsageUpdate /
  UsageSnapshot payloads, removing the too-many-arguments lint suppressions.
- Extract _fetch_agent_tokens and _persist_token_snapshot from the token sweep,
  removing the too-many-statements suppression; label the live snapshot "live".

Hardening uncovered while fixing the above:

- _finalize_spawn_session pulled the full RAG stack into the
  session-finalization path through a transcript-parse import; move the pure
  parser into a dependency-light roboco.agent_sdk.transcript_usage module so
  finalization never imports the agent SDK server.
- Reduce _finalize_spawn_session complexity by extracting
  _resolve_final_token_usage, and widen the transcript-fallback guard so a read
  error can never abort finalization.

Also align KeyMetricsPanel with the metrics /dashboard/ceo actually returns: it
read velocity_24h / avg_time_to_done / active_agents, none of which
get_key_metrics() emits, so four of five rows rendered "—". Render
velocity_weekly, completion_rate, documentation_coverage and active_blockers.

* docs: note live usage push over /ws/system on the usage dashboard

* fix(usage): finalize on self-exit and de-duplicate transcript token counts

Two bugs left token capture broken even after the transcript-read fallback
landed — surfaced by a live agent run:

- Agents that self-exit (the normal i_am_idle -> container shutdown, exit 0)
  were never finalized. _finalize_spawn_session is only called from
  stop_agent(), but a graceful self-exit goes through _handle_stopped_container,
  which set the instance OFFLINE and returned without finalizing — leaving the
  spawn-session row open with zero tokens. Finalize there for both graceful
  (exit_reason="completed") and crash (exit_reason="crashed") exits.

- sum_transcript_usage double-counted. Claude Code logs one assistant message
  as several JSONL lines (one per content block — thinking / text / tool_use),
  each repeating the same message.usage, so summing every line roughly doubled
  the totals. De-duplicate by message.id.

Verified against a live agent transcript: the raw sum (12, 1068, 62502, 115828)
vs the de-duped (6, 516, 62502, 63336), which matches the session's
authoritative result.usage exactly.

* feat(usage): fall back to the transcript in the live token sweep

The 60s token sweep read only the agent SDK's /usage/status, which races
container teardown and reports zero mid-run — so live usage (and the
USAGE_SNAPSHOT pushed to /ws/system) stayed at zero for active agents.
Extract _resolve_active_tokens: try the SDK, then fall back to the durable
transcript (the same source finalize uses) so running agents report live.

* feat(usage): add GET /usage/sessions for the dashboard's Recent Sessions

The panel's Recent Sessions table was mock-only — the backend had no sessions
endpoint, so production always showed 'No sessions recorded yet'. Add
UsageService.get_recent_sessions + a /usage/sessions route returning the most
recent spawn-session rows (token totals + cost), and point the panel client
at it.

---------

Co-authored-by: Frontend Developer 1 <fe-dev-1@agents.roboco.dev>
Co-authored-by: Backend Developer 1 <be-dev-1@agents.roboco.dev>
Co-authored-by: Renn F <rennf93@users.noreply.github.com>
2026-06-11 23:19:50 +02:00

4.4 KiB
Raw Blame History

API Endpoints Reference

Base URL: http://{host}:{port}/api/v1

Tasks

Method Endpoint Description
GET /tasks List tasks (filtered)
GET /tasks/my My assigned tasks
GET /tasks/pending Pending tasks
GET /tasks/blocked Blocked tasks
GET /tasks/awaiting-qa Tasks awaiting QA
GET /tasks/awaiting-docs Tasks awaiting docs
GET /tasks/awaiting-pm-review Tasks awaiting PM
GET /tasks/awaiting-ceo-approval Tasks for CEO
GET /tasks/team/{team} Tasks by team
GET /tasks/{id} Get task details
GET /tasks/{id}/subtasks Get subtasks
POST /tasks Create task
PATCH /tasks/{id} Update task
DELETE /tasks/{id} Delete task
POST /tasks/{id}/claim Claim task
POST /tasks/{id}/start Start work
POST /tasks/{id}/pause Pause work
POST /tasks/{id}/resume Resume work
POST /tasks/{id}/block Block on task
POST /tasks/{id}/soft-block Block on external
POST /tasks/{id}/unblock Unblock task
POST /tasks/{id}/verify Submit verification
POST /tasks/{id}/submit-qa Submit for QA
POST /tasks/{id}/pass-qa Pass QA
POST /tasks/{id}/fail-qa Fail QA
POST /tasks/{id}/docs-complete Complete docs
POST /tasks/{id}/submit-pm-review Submit to PM
POST /tasks/{id}/complete Complete task
POST /tasks/{id}/cancel Cancel task
POST /tasks/{id}/activate Activate task
POST /tasks/{id}/escalate Escalate task
POST /tasks/{id}/escalate-to-ceo Escalate to CEO
POST /tasks/{id}/ceo-approve CEO approve
POST /tasks/{id}/ceo-reject CEO reject
POST /tasks/{id}/substitute Substitute agent
POST /tasks/{id}/progress Update progress

Git

Method Endpoint Description
GET /git/status Git status
GET /git/log Commit history
GET /git/branches List branches
GET /git/diff View diff
POST /git/commit Create commit
POST /git/push Push to remote
POST /git/branch/create Create branch
POST /git/checkout Checkout branch
POST /git/pr/create Create PR
POST /git/pr/merge Merge PR

Channels & Messages

Method Endpoint Description
GET /channels List channels
GET /channels/{slug}/history Channel history
POST /messages Send message
GET /messages/{id} Get message

Notifications

Method Endpoint Description
GET /notifications List notifications
GET /notifications/{id} Get notification
POST /notifications Send notification
POST /notifications/{id}/ack Acknowledge

Journals

Method Endpoint Description
GET /journals/me/entries My entries
POST /journals/me/entries Create entry
GET /journals/me/stats My stats
GET /journals/{agent}/entries Read team journal

System & realtime

Method Endpoint Description
GET /api/system/rate-limits Active per-provider rate-limit state ({ entries: [...] })
WS /ws/system Operator stream — rate-limit lifecycle (RATE_LIMIT_HIT / RATE_LIMIT_LIFTED) and live usage (USAGE_UPDATE / USAGE_SNAPSHOT) pushed to the usage dashboard
WS /ws/agents/{id}, /ws/channels/{id}, /ws/sessions/{id}, /ws/notifications/{id} Per-resource live streams

Documentation

Method Endpoint Description
POST /docs/write Write/update doc (RAG dedup)
GET /docs/read Read documentation
GET /docs/list List docs (by task or team)
DELETE /docs/delete Delete documentation

Knowledge Base

Method Endpoint Description
POST /optimal/search Semantic search
POST /optimal/query RAG query
POST /optimal/mentor/ask Ask mentor
GET /optimal/stats KB stats
POST /optimal/index/code Index code
POST /optimal/index/docs Bulk index docs

Health

Method Endpoint Description
GET /health Health check
GET /health/ready Readiness check
Reference in New Issue View Git Blame Copy Permalink