diff --git a/dashboard/backend/api/routers/admin_users.py b/dashboard/backend/api/routers/admin_users.py index 6847f662..a53ac897 100644 --- a/dashboard/backend/api/routers/admin_users.py +++ b/dashboard/backend/api/routers/admin_users.py @@ -228,6 +228,61 @@ def get_user(user_id: int, _admin: dict = Depends(require_admin)): return {"user": payload} +@admin_router.get("/users/{user_id}/agent-activity") +def get_user_agent_activity( + user_id: int, + limit: int = Query(default=50, ge=1, le=100), + offset: int = Query(default=0, ge=0), + _admin: dict = Depends(require_admin), +): + """Return the admin projection from a user to traceable agent runs.""" + if users_module.user_store.get_user_admin(user_id) is None: + raise HTTPException(status_code=404, detail="User not found") + + # Trace persistence is durable in production while protocol runs are + # diskless. Read the durable projection first, then use local runs only to + # enrich matching rows that still exist after a deploy. + from dashboard.backend.domain.agents.repository import agent_store + from dashboard.backend.domain.runs.repository import run_store + from dashboard.backend.domain.traces.repository import trace_store + + agents = agent_store.list_agents(owner_user_id=user_id) + agent_ids = [agent["agent_id"] for agent in agents] + traces = trace_store.list_traces(agent_ids=agent_ids, limit=limit, offset=offset) + local_runs = { + run["run_id"]: run + for agent_id in agent_ids + for run in run_store.list_runs(agent_id) + } + activity = [] + traces_by_agent = {agent_id: [] for agent_id in agent_ids} + for trace in traces["items"]: + run = local_runs.get(trace.get("run_id"), {}) + traces_by_agent.setdefault(trace.get("agent_id"), []).append({ + "run_id": trace.get("run_id"), + "status": run.get("status") or trace.get("status"), + "created_at": run.get("created_at") or trace.get("created_at"), + "trace_id": trace.get("trace_id"), + "trace_status": trace.get("status"), + }) + for agent in agents: + activity.append({ + "agent_id": agent["agent_id"], + "name": agent.get("name") or agent["agent_id"], + "agent_type": agent.get("agent_type") or "external", + "created_at": agent.get("created_at"), + "runs": traces_by_agent.get(agent["agent_id"], []), + }) + return { + "user_id": user_id, + "agents": activity, + "limit": limit, + "offset": offset, + "has_more": traces["has_more"], + "next_cursor": traces["next_cursor"], + } + + @admin_router.patch("/users/{user_id}") def patch_user( user_id: int, diff --git a/dashboard/backend/domain/traces/repository.py b/dashboard/backend/domain/traces/repository.py index 9e4c2665..778aaad4 100644 --- a/dashboard/backend/domain/traces/repository.py +++ b/dashboard/backend/domain/traces/repository.py @@ -144,6 +144,7 @@ def list_traces( self, *, agent_id: Optional[str] = None, + agent_ids: Optional[Sequence[str]] = None, run_id: Optional[str] = None, status: Optional[str] = None, limit: int = 50, @@ -157,6 +158,13 @@ def list_traces( if value is not None: clauses.append(f"{column} = ?") params.append(value) + if agent_ids is not None: + ids = [str(value) for value in agent_ids] + if not ids: + return {"items": [], "has_more": False, "next_cursor": None} + placeholders = ", ".join("?" for _ in ids) + clauses.append(f"agent_id IN ({placeholders})") + params.extend(ids) where = f"WHERE {' AND '.join(clauses)}" if clauses else "" with self._get_connection() as conn: rows = conn.execute( diff --git a/dashboard/backend/domain/traces/repository_postgres.py b/dashboard/backend/domain/traces/repository_postgres.py index a6ac21f1..1675a336 100644 --- a/dashboard/backend/domain/traces/repository_postgres.py +++ b/dashboard/backend/domain/traces/repository_postgres.py @@ -136,6 +136,7 @@ def list_traces( self, *, agent_id: Optional[str] = None, + agent_ids: Optional[Sequence[str]] = None, run_id: Optional[str] = None, status: Optional[str] = None, limit: int = 50, @@ -149,6 +150,12 @@ def list_traces( if value is not None: clauses.append(f"{column} = %s") params.append(value) + if agent_ids is not None: + ids = [str(value) for value in agent_ids] + if not ids: + return {"items": [], "has_more": False, "next_cursor": None} + clauses.append("agent_id = ANY(%s)") + params.append(ids) where = f"WHERE {' AND '.join(clauses)}" if clauses else "" with self._get_connection() as conn: with conn.cursor() as cur: diff --git a/dashboard/backend/tests/test_admin_agent_activity_api.py b/dashboard/backend/tests/test_admin_agent_activity_api.py new file mode 100644 index 00000000..d671e9cd --- /dev/null +++ b/dashboard/backend/tests/test_admin_agent_activity_api.py @@ -0,0 +1,70 @@ +from fastapi.testclient import TestClient + +from dashboard.backend.api.auth import require_admin +from dashboard.backend.app import app + + +def test_admin_user_agent_activity_joins_agents_runs_and_traces(monkeypatch): + import dashboard.backend.api.routers.admin_users as module + import dashboard.backend.domain.agents.repository as agents + import dashboard.backend.domain.runs.repository as runs + import dashboard.backend.domain.traces.repository as traces + + class Users: + def get_user_admin(self, user_id): + return {"id": user_id} if user_id == 7 else None + + class Agents: + def list_agents(self, *, owner_user_id): + assert owner_user_id == 7 + return [{"agent_id": "agent-1", "name": "Momentum", "agent_type": "builtin", "created_at": "t1"}] + + class Runs: + def list_runs(self, agent_id): + assert agent_id == "agent-1" + return [{"run_id": "run-1", "status": "running", "created_at": "t2"}] + + class Traces: + def list_traces(self, *, agent_ids, limit, offset): + assert agent_ids == ["agent-1"] + assert limit == 50 + assert offset == 0 + return { + "items": [{ + "agent_id": "agent-1", + "run_id": "run-1", + "trace_id": "trace-1", + "status": "running", + "created_at": "t3", + }], + "has_more": False, + "next_cursor": None, + } + + monkeypatch.setattr(module.users_module, "user_store", Users()) + monkeypatch.setattr(agents, "agent_store", Agents()) + monkeypatch.setattr(runs, "run_store", Runs()) + monkeypatch.setattr(traces, "trace_store", Traces()) + app.dependency_overrides[require_admin] = lambda: {"id": 1, "is_admin": True} + try: + response = TestClient(app).get("/api/admin/users/7/agent-activity") + assert response.status_code == 200 + assert response.json()["agents"][0]["runs"][0]["trace_id"] == "trace-1" + finally: + app.dependency_overrides.pop(require_admin, None) + + +def test_admin_user_agent_activity_returns_404_for_unknown_user(monkeypatch): + import dashboard.backend.api.routers.admin_users as module + + class Users: + def get_user_admin(self, _user_id): + return None + + monkeypatch.setattr(module.users_module, "user_store", Users()) + app.dependency_overrides[require_admin] = lambda: {"id": 1, "is_admin": True} + try: + response = TestClient(app).get("/api/admin/users/999/agent-activity") + assert response.status_code == 404 + finally: + app.dependency_overrides.pop(require_admin, None) diff --git a/dashboard/backend/tests/test_admin_page_shell.py b/dashboard/backend/tests/test_admin_page_shell.py index 21cef449..bd144084 100644 --- a/dashboard/backend/tests/test_admin_page_shell.py +++ b/dashboard/backend/tests/test_admin_page_shell.py @@ -235,7 +235,13 @@ def test_pruned_css_carries_none_of_the_dead_mock_passes(): assert selector in ADMIN_CSS, selector -RAIL_ICONS = ("icon-chart", "icon-users", "icon-network", "icon-activity") +RAIL_ICONS = ( + "icon-chart", + "icon-users", + "icon-network", + "icon-activity", + "icon-file-text", +) HEADER_ICONS = ("icon-github", "icon-discord", "icon-chevron-right") SPRITE_ICONS = ( RAIL_ICONS diff --git a/dashboard/backend/tests/test_admin_users.py b/dashboard/backend/tests/test_admin_users.py index a5283ac7..80f5905c 100644 --- a/dashboard/backend/tests/test_admin_users.py +++ b/dashboard/backend/tests/test_admin_users.py @@ -195,6 +195,9 @@ def test_every_admin_route_refuses_a_non_admin(isolated_auth): ("GET", "/api/admin/users/{user_id}"): lambda: client.get( f"/api/admin/users/{user['id']}" ), + ("GET", "/api/admin/users/{user_id}/agent-activity"): lambda: client.get( + f"/api/admin/users/{user['id']}/agent-activity" + ), ("PATCH", "/api/admin/users/{user_id}"): lambda: client.patch( f"/api/admin/users/{user['id']}", json={"role": "admin"} ), diff --git a/dashboard/backend/tests/test_admin_users_frontend.py b/dashboard/backend/tests/test_admin_users_frontend.py index 0fb77290..4ca5fdc0 100644 --- a/dashboard/backend/tests/test_admin_users_frontend.py +++ b/dashboard/backend/tests/test_admin_users_frontend.py @@ -128,7 +128,7 @@ def test_profile_header_carries_badges_activation_week_and_milestones(): "Account signed upJul 1, 2026, 09:00 UTC", "Credential verifiedJul 1, 2026, 10:00 UTC", "Agent createdJul 1, 2026, 11:00 UTC", "Backtest completedJul 2, 2026, 10:00 UTC", ] - assert result["tabs"] == ["Overview", "Timeline", "Runs", "Usage", "Sessions"] + assert result["tabs"] == ["Overview", "Agents & traces", "Timeline", "Runs", "Usage", "Sessions"] # D5: account management lives on this page; the hand-off rides in the # hash query the shell parses and AdminCredits applies to its search form. assert "#account?user=ada.synthetic%40example.test" in result["account"] diff --git a/dashboard/backend/tests/test_app_composition.py b/dashboard/backend/tests/test_app_composition.py index b3975d84..4a75e345 100644 --- a/dashboard/backend/tests/test_app_composition.py +++ b/dashboard/backend/tests/test_app_composition.py @@ -141,6 +141,7 @@ ("GET", "/api/admin/stats"), ("GET", "/api/admin/users"), ("GET", "/api/admin/users/{user_id}"), + ("GET", "/api/admin/users/{user_id}/agent-activity"), ("PATCH", "/api/admin/users/{user_id}"), ("GET", "/api/admin/analytics/overview"), ("GET", "/api/admin/analytics/lifecycle"), diff --git a/dashboard/frontend/admin.html b/dashboard/frontend/admin.html index c3c39db4..66fa89b6 100644 --- a/dashboard/frontend/admin.html +++ b/dashboard/frontend/admin.html @@ -36,6 +36,7 @@ + @@ -162,7 +163,7 @@

Agentic Trading Lab

Account Management Providers Activity - Agent traces + Agent traces
diff --git a/dashboard/frontend/js/admin-traces.js b/dashboard/frontend/js/admin-traces.js index 79f5840c..cfbd88c7 100644 --- a/dashboard/frontend/js/admin-traces.js +++ b/dashboard/frontend/js/admin-traces.js @@ -5,7 +5,7 @@ const SURFACE = 'traces'; const state = { traceId: null, trace: null, events: [], nextSequence: 0, - pollTimer: null, stale: false, listItems: [], listHasMore: false, listNextCursor: 0, + pollTimer: null, stale: false, context: {}, listItems: [], listHasMore: false, listNextCursor: 0, }; function shell() { @@ -133,12 +133,12 @@ return section; } - function renderTraceDetail(trace, events) { + function renderTraceDetail(trace, events, context = {}) { const section = node('section', 'trace-detail-panel'); const breadcrumb = node('nav', 'breadcrumb'); breadcrumb.setAttribute('aria-label', 'Breadcrumb'); - const back = node('a', '', 'Agent traces'); - back.setAttribute('href', '#traces'); + const back = node('a', '', context.user_id ? 'Back to user analytics' : 'Agent traces'); + back.setAttribute('href', context.user_id ? `#users/${encodeURIComponent(String(context.user_id))}` : '#traces'); breadcrumb.append(back, node('span', '', '/'), node('span', '', value(trace?.trace_id))); section.appendChild(breadcrumb); const head = node('div', 'page-head'); @@ -228,7 +228,7 @@ return shell().request(`/api/admin/traces/${encodeURIComponent(traceId)}`); } - async function loadDetail(traceId) { + async function loadDetail(traceId, context = {}) { stopPolling(); const seq = shell().nextSeq(SURFACE); try { @@ -238,6 +238,7 @@ if (terminal) trace = await refreshTraceEnvelope(traceId); if (!shell().isCurrent(SURFACE, seq)) return; state.traceId = traceId; + state.context = { ...context }; state.trace = trace; state.events = events; state.nextSequence = state.events.length ? state.events[state.events.length - 1].sequence_no : 0; @@ -245,7 +246,7 @@ const host = element('tracesView'); if (!host) return; shell().clear(host); - host.appendChild(renderTraceDetail(trace, state.events)); + host.appendChild(renderTraceDetail(trace, state.events, context)); if (trace.status === 'running') startPolling(); } catch (error) { if (await shell().handleAccessLost(error)) return; @@ -275,7 +276,7 @@ const host = element('tracesView'); if (host && state.trace) { shell().clear(host); - host.appendChild(renderTraceDetail(state.trace, state.events)); + host.appendChild(renderTraceDetail(state.trace, state.events, state.context)); } } state.stale = false; @@ -296,7 +297,7 @@ function onRoute(event) { if (event.detail.route !== SURFACE) return; - if (event.detail.id) loadDetail(event.detail.id); + if (event.detail.id) loadDetail(event.detail.id, event.detail.query || {}); else loadList(); } diff --git a/dashboard/frontend/js/admin-users.js b/dashboard/frontend/js/admin-users.js index 0cd76fbf..ab65843e 100644 --- a/dashboard/frontend/js/admin-users.js +++ b/dashboard/frontend/js/admin-users.js @@ -4,8 +4,8 @@ const USERS_PATH = '/api/admin/analytics/users'; const PAGE_SIZE = 50; - const SECTIONS = ['overview', 'timeline', 'runs', 'usage', 'sessions']; - const SECTION_LABELS = Object.freeze({ overview: 'Overview', timeline: 'Timeline', runs: 'Runs', usage: 'Usage', sessions: 'Sessions' }); + const SECTIONS = ['overview', 'agents', 'timeline', 'runs', 'usage', 'sessions']; + const SECTION_LABELS = Object.freeze({ overview: 'Overview', agents: 'Agents & traces', timeline: 'Timeline', runs: 'Runs', usage: 'Usage', sessions: 'Sessions' }); // Harvested from the retired admin-analytics.js:35-50 (deleted in PR C; see git history). const EVENT_LABELS = Object.freeze({ account_signed_up: 'Account signed up', @@ -446,6 +446,31 @@ const s = shell(); const rows = Array.isArray(items) ? items : []; if (!rows.length) return s.el('p', 'panel-empty', 'No activity in this section.'); + if (section === 'agents') { + const root = s.el('div', 'agent-activity-list'); + rows.forEach((agent) => { + const card = s.el('article', 'agent-activity-card'); + card.appendChild(s.el('h3', '', agent.name || agent.agent_id || s.DASH)); + card.appendChild(s.el('p', 'muted', `${agent.agent_type || 'external'} · ${agent.agent_id || s.DASH}`)); + const runs = s.el('ul', 'agent-run-list'); + (agent.runs || []).forEach((run) => { + const item = s.el('li'); + item.appendChild(s.el('span', '', `${run.run_id || s.DASH} · ${s.humanize(run.status || 'unknown')}`)); + if (run.trace_id) { + const link = s.el('a', 'module-link', run.trace_status === 'running' ? 'View live trace' : 'View trace'); + link.setAttribute('href', `#traces/${encodeURIComponent(String(run.trace_id))}?user_id=${encodeURIComponent(String(state.profile.userId))}&agent_id=${encodeURIComponent(String(agent.agent_id))}&run_id=${encodeURIComponent(String(run.run_id))}`); + item.appendChild(link); + } else { + item.appendChild(s.el('span', 'muted', 'Trace unavailable')); + } + runs.appendChild(item); + }); + if (!runs.children.length) runs.appendChild(s.el('li', 'panel-empty', 'No runs recorded.')); + card.appendChild(runs); + root.appendChild(card); + }); + return root; + } if (section === 'timeline') { const list = s.el('ol', 'timeline'); rows.forEach((item) => { @@ -527,12 +552,15 @@ sectionState.error = null; const seq = ++sectionState.requestSeq; renderSectionPanel(section); - const params = new URLSearchParams({ section, limit: String(PAGE_SIZE) }); + const params = new URLSearchParams({ section, limit: String(PAGE_SIZE) }); if (append) params.set('cursor', sectionState.nextCursor); try { - const payload = await s.request(`${USERS_PATH}/${encodeURIComponent(String(userId))}/activity?${params}`); + const path = section === 'agents' + ? `/api/admin/users/${encodeURIComponent(String(userId))}/agent-activity` + : `${USERS_PATH}/${encodeURIComponent(String(userId))}/activity?${params}`; + const payload = await s.request(path); if (String(state.profile.userId) !== String(userId) || seq !== sectionState.requestSeq) return; - const next = Array.isArray(payload.items) ? payload.items : []; + const next = section === 'agents' ? (Array.isArray(payload.agents) ? payload.agents : []) : (Array.isArray(payload.items) ? payload.items : []); sectionState.items = append ? sectionState.items.concat(next) : next; sectionState.nextCursor = payload.next_cursor || null; sectionState.loaded = true; diff --git a/docs/superpowers/plans/2026-10-09-user-agent-trace-navigation.md b/docs/superpowers/plans/2026-10-09-user-agent-trace-navigation.md new file mode 100644 index 00000000..915335e2 --- /dev/null +++ b/docs/superpowers/plans/2026-10-09-user-agent-trace-navigation.md @@ -0,0 +1,100 @@ +# User Agent Trace Navigation Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans (inline execution). Steps use checkbox (`- [ ]`) syntax. + +**Goal:** Add an Admin navigation path from User Analytics to a user's agents, runs, and live reasoning trace. + +**Architecture:** Reuse the existing admin user profile and trace API. Add a server-owned user-to-agent/run summary endpoint, then add profile-level links that navigate to the existing trace list/detail views. Keep trace storage and event contracts unchanged. + +**Tech Stack:** FastAPI, existing Agent/Run repositories, vanilla JavaScript Admin modules, pytest and the repository DOM harness. + +**Spec:** `docs/superpowers/specs/2026-10-07-agent-reasoning-trace-design.md` + +## Global Constraints + +- Keep trace data in the existing Agent Postgres/Neon boundary. +- Do not expose hidden chain-of-thought; display bounded reasoning summaries only. +- Reuse `require_admin`, existing AdminShell request/routing, and textContent-based DOM rendering. +- Preserve existing user analytics pagination and profile section behavior. +- Every loop ends with focused tests, a commit, and a push to PR #622. +- Do not add a second database or duplicate trace storage. + +--- + +### Task 1: Define the Admin user-agent-run contract + +**Files:** +- Create: `dashboard/backend/api/routers/admin_agent_activity.py` +- Modify: `dashboard/backend/api/router.py` +- Test: `dashboard/backend/tests/test_admin_agent_activity_api.py` +- Modify: `dashboard/backend/tests/test_app_composition.py` + +**Interfaces:** +- `GET /api/admin/users/{user_id}/agent-activity` +- Response: `{user_id, agents: [{agent_id, name, agent_type, created_at, runs: [{run_id, status, created_at, trace_id}]}]}` +- Endpoint is admin-only and returns empty arrays for a valid user with no agents. + +- [ ] Add authorization, empty-user, owned-agent, run-link, and missing-trace tests. +- [ ] Run the new API test and confirm it fails because the route is absent. +- [ ] Implement repository-backed aggregation using existing agent and run stores; resolve trace IDs through `trace_store.get_trace_for_run`. +- [ ] Register the router and route contract. +- [ ] Run focused API and route-composition tests. +- [ ] Commit `feat: expose admin user agent activity`. +- [ ] Push the branch and verify PR checks start. + +### Task 2: Render agent and run links in User Analytics profiles + +**Files:** +- Modify: `dashboard/frontend/js/admin-users.js` +- Modify: `dashboard/frontend/admin.css` +- Test: `dashboard/backend/tests/test_admin_users_frontend.py` + +**Interfaces:** +- The user profile gets an “Agent activity” section. +- Each agent displays name/id and its runs. +- A run with a trace links to `#traces/`. +- Running traces use copy such as “View live trace”; terminal traces use “View trace”. +- Loading, empty, error, and stale states remain explicit. + +- [ ] Add DOM tests for empty activity, agent rows, trace links, and safe special-character rendering. +- [ ] Run focused frontend tests and confirm failure before implementation. +- [ ] Add lazy loading on profile open/section selection via AdminShell. +- [ ] Render all labels using DOM nodes/textContent. +- [ ] Run focused frontend and existing Admin shell tests. +- [ ] Commit `feat: link user analytics to agent traces`. +- [ ] Push and verify PR checks. + +### Task 3: Add trace context and back navigation + +**Files:** +- Modify: `dashboard/frontend/js/admin-traces.js` +- Modify: `dashboard/backend/tests/test_admin_traces_frontend.py` + +**Interfaces:** +- Trace detail accepts optional `user_id`, `agent_id`, and `run_id` context in the hash query. +- Detail breadcrumb includes `Back to user analytics` when `user_id` is present. +- Existing direct `#traces` and `#traces/` behavior remains unchanged. + +- [ ] Add DOM tests for contextual breadcrumb and query-preserving navigation. +- [ ] Implement context-safe links and breadcrumb. +- [ ] Run frontend trace tests and route tests. +- [ ] Commit `feat: add user context to trace navigation`. +- [ ] Push and verify PR checks. + +### Task 4: Verify the complete operator flow + +**Files:** +- Modify: `dashboard/backend/tests/test_admin_user_trace_flow.py` +- Modify: `docs/superpowers/specs/2026-10-07-agent-reasoning-trace-design.md` + +**Interfaces:** +- Contract test covers User -> Agent -> Run -> Trace. +- Documentation records the Admin entry point and near-real-time polling behavior. + +- [ ] Add an API contract test with a user, agent, run, trace, and terminal event. +- [ ] Run the focused flow, trace, and Admin suites. +- [ ] Run `git diff --check` and frontend syntax checks. +- [ ] Update documentation with the navigation path. +- [ ] Commit `docs: document admin trace navigation`. +- [ ] Push and report local and remote CI status. + diff --git a/docs/superpowers/specs/2026-10-07-agent-reasoning-trace-design.md b/docs/superpowers/specs/2026-10-07-agent-reasoning-trace-design.md index 7e86c90d..eb7e8686 100644 --- a/docs/superpowers/specs/2026-10-07-agent-reasoning-trace-design.md +++ b/docs/superpowers/specs/2026-10-07-agent-reasoning-trace-design.md @@ -66,6 +66,23 @@ but remain physically co-located so Admin queries do not require cross-database joins. A later split is allowed only after measured volume or retention needs justify it. +### Admin navigation + +The operator path is layered rather than a second trace surface: + +```text +User Analytics -> User profile -> Agents & traces -> Run -> Reasoning trace +``` + +The profile's `Agents & traces` section reads the admin-only +`GET /api/admin/users/{user_id}/agent-activity` projection. It joins Agent, +Run, and Trace records by stable IDs in the application layer because those +records may live in different persistence boundaries. A run without a trace +remains visible and is labeled as unavailable. Runs with a running trace link +to the polling timeline, while completed and failed runs link to the same +timeline in read-only mode. The global `Agent traces` Admin entry remains the +cross-user operational view. + ## Data model ### `agent_traces` @@ -262,4 +279,3 @@ verification -> regression check -> short review note. - Exact retention duration and archival schedule. - SSE versus WebSocket after polling proves the event contract. - Additional event types for LLM provider requests and child Agents. -