---
title: "feat(admin): add agent detail dashboard and editor tabs"
type: feat
status: completed
date: 2026-04-28
origin: docs/brainstorms/2026-04-28-agent-detail-dashboard-editor-tabs-requirements.md
---

# feat(admin): add agent detail dashboard and editor tabs

## Overview

Elevate the agent workspace editor from a header badge destination into a first-class Agent Detail tab. `/agents/:agentId` remains the Dashboard route, `/agents/:agentId/editor` becomes the new Editor route, and old workspace deep links redirect forward while preserving folder selection.

---

## Problem Frame

Agent Detail currently treats monitoring and editing asymmetrically: the dashboard is the page, while workspace editing is a small `Workspace` badge that navigates to a separate builder screen. The requirements document asks for the Agent Detail page to mirror the Agent Template detail mental model: a top-level tab switcher where `Dashboard` and `Editor` are peer modes of a single agent context (see origin: `docs/brainstorms/2026-04-28-agent-detail-dashboard-editor-tabs-requirements.md`).

---

## Requirements Trace

- R1. Agent Detail exposes `Dashboard` and `Editor` tabs.
- R2. `/agents/:agentId` remains the Dashboard route.
- R3. `/agents/:agentId/editor` is the Editor route.
- R4. Editor renders the existing workspace editor beneath the same agent header and tab switcher.
- R5. Dashboard content remains the current metrics/activity experience.
- R6. `/agents/:agentId/workspace` redirects to Editor and preserves `folder`.
- R7. The old `Workspace` header badge is removed.
- R8. Existing non-editor header badges and controls remain.
- R9. The tab switcher follows the Agent Template detail tab pattern.

**Origin actors:** A1 (operator), A2 (agent author)
**Origin flows:** F1 (open an agent dashboard), F2 (switch from dashboard to editor), F3 (open an old workspace link)
**Origin acceptance examples:** AE1 (dashboard route), AE2 (editor route), AE3 (legacy workspace redirect), AE4 (remove Workspace badge)

---

## Scope Boundaries

- Do not redesign dashboard cards, charts, cost summaries, or recent activity.
- Do not change workspace editor file actions, import behavior, folder semantics, or runtime behavior.
- Do not add additional Agent Detail tabs for memory, knowledge, sub-agents, automations, or settings.
- Do not rename Agent Template's `Workspace` tab.
- Do not remove existing non-dashboard agent subroutes beyond updating legacy workspace redirects.

---

## Context & Research

### Relevant Code and Patterns

- `apps/admin/src/routes/_authed/_tenant/agents/$agentId.tsx` owns the current Agent Detail dashboard, including agent detail data, breadcrumbs, header badges, edit/delete dialog, metrics, and activity.
- `apps/admin/src/routes/_authed/_tenant/agents/$agentId_.workspace.tsx` currently validates `folder` search state and renders `AgentBuilderShell`.
- `apps/admin/src/components/agent-builder/AgentBuilderShell.tsx` wraps `WorkspaceEditor` in its own `PageLayout`, which is not suitable for the new embedded Editor tab without adjustment.
- `apps/admin/src/components/agent-builder/WorkspaceEditor.tsx` already supports `mode="agent"` and direct `{ agentId }` targets, so the Editor tab can embed the shared editor rather than reimplementing file behavior.
- `apps/admin/src/routes/_authed/_tenant/agent-templates/$templateId.$tab.tsx` is the visual precedent for detail-page tabs using `Tabs`, `TabsList`, `TabsTrigger`, and `Link`.
- `apps/admin/src/routes/_authed/_tenant/analytics.tsx` is the closest route-layout precedent for URL-backed tabs inside a shared `PageLayout` header.
- `apps/admin/src/routes/_authed/_tenant/agents/$agentId_.workspaces.tsx` is an existing redirect route that preserves `folder` search state via `Navigate`.
- `apps/admin/src/routeTree.gen.ts` is generated by the TanStack Router plugin and should be regenerated, not hand-maintained.

### Institutional Learnings

- `docs/plans/2026-04-26-008-refactor-template-agent-builder-parity-plan.md` established `WorkspaceEditor` as the shared editor surface and warns against creating route-local workspace editor forks.
- `docs/solutions/workflow-issues/agent-builder-smoke-cleanup-needs-manifest-regeneration-2026-04-26.md` notes that Agent Builder UI state can reflect workspace-derived data such as synthetic `agents` grouping, so this plan must preserve the existing workspace editor behavior and avoid storage/API changes.
- Prior route-removal plans document the route tree rule: regenerate `apps/admin/src/routeTree.gen.ts` through the admin build/dev pipeline and inspect the diff for only expected route additions/redirect changes.

### External References

External research skipped. This is an internal React/TanStack Router refactor with strong local patterns.

---

## Key Technical Decisions

- **Use URL-backed tabs.** `Dashboard` stays at `/agents/:agentId`; `Editor` lives at `/agents/:agentId/editor`. This preserves existing dashboard links and makes the editor shareable.
- **Share agent detail chrome without sharing dashboard data.** Extract the common header/tab/badge/edit behavior into a small component or hook so Dashboard and Editor render the same agent context while the editor route avoids dashboard-only activity and cost queries.
- **Let shared chrome expose agent context to route content.** Prefer a render-prop or hook shape that lets both routes use the loaded agent and refresh callback, while keeping dashboard-only data such as `hasRecentActivity` owned by the Dashboard route.
- **Embed `WorkspaceEditor` under Agent Detail chrome.** The Editor tab should not render a nested `PageLayout` title like `Agent Builder : Marco`; either use `WorkspaceEditor` directly or refactor `AgentBuilderShell` to expose an embedded editor boundary.
- **Keep legacy redirects explicit.** Retain compatibility files for old `/workspace` and related `/workspaces` links, redirecting to `/editor` with `folder` preserved.
- **Use source-target tests where component testing support is thin.** The admin test suite already uses Vitest source assertions for route/editor composition. Add focused target tests for route labels, redirects, and badge removal without introducing a new test framework.

---

## Open Questions

### Resolved During Planning

- **Should Agent Detail use a route layout or duplicated headers?** Use shared chrome via a component/hook rather than a larger route tree restructuring. This avoids risky file-route churn while still preventing header drift.
- **Should the legacy workspace route be deleted?** No. Keep it as a redirect compatibility route to satisfy AE3 and avoid broken bookmarks.
- **Should the editor route use `AgentBuilderShell` unchanged?** No. `AgentBuilderShell` includes its own page header, so the Editor tab should embed the shared `WorkspaceEditor` boundary under the Agent Detail header.

### Deferred to Implementation

- Exact component and hook names for the shared agent detail chrome.
- Whether the old `AgentBuilderShell` remains only for compatibility routes during the transition or is simplified after the Editor route lands.
- Exact responsive header layout if tabs and badges need small-screen wrapping adjustments.

---

## Implementation Units

- U1. **Extract Shared Agent Detail Chrome**

**Goal:** Create reusable Agent Detail header/tab/edit behavior that Dashboard and Editor routes can share without duplicating the current header logic.

**Requirements:** R1, R4, R8, R9; supports F1, F2, AE1, AE2

**Dependencies:** None

**Files:**
- Create: `apps/admin/src/components/agents/AgentDetailChrome.tsx` or equivalent shared component/hook files
- Modify: `apps/admin/src/routes/_authed/_tenant/agents/$agentId.tsx`
- Test: `apps/admin/src/components/agents/__tests__/AgentDetailChrome.target.test.ts` or equivalent target test

**Approach:**
- Extract the common agent detail responsibilities from `apps/admin/src/routes/_authed/_tenant/agents/$agentId.tsx`: agent loading/error handling, breadcrumb setup, agent switcher popover data, editable slug/title affordance, `AgentHeaderBadges`, automations badge, rollback button, and edit/delete dialog.
- Add a tab switcher labeled `Dashboard` and `Editor` to the shared header, using the existing `Tabs`/`TabsList`/`TabsTrigger` + `Link` pattern from Agent Template detail and Analytics.
- Keep the shared boundary narrow: it should provide the header and current agent context, but not own dashboard-only activity/cost queries.
- Shape the API so route content can access the loaded `agent`, `tenantId`, `tenantSlug`, and `refresh` callback without issuing a second agent detail query.
- Preserve the existing recent-activity edit warning on the Dashboard route. If the edit dialog remains available from the Editor route, do not silently hardcode the warning away; either pass an explicitly computed value or make the absence of dashboard activity state an intentional implementation decision.
- Preserve existing header badge callbacks and mutation refresh behavior. Header controls should continue to update the current agent and refresh agent details.

**Patterns to follow:**
- `apps/admin/src/routes/_authed/_tenant/agent-templates/$templateId.$tab.tsx` for centered segmented tabs in a detail header.
- `apps/admin/src/routes/_authed/_tenant/analytics.tsx` for URL-backed tabs inside shared page chrome.
- Existing `AgentHeaderBadges` children slot for retaining Automations and Rollback while removing Workspace.

**Test scenarios:**
- Happy path: Given active tab `dashboard`, the shared header exposes `Dashboard` and `Editor` tab labels and marks Dashboard active.
- Happy path: Given active tab `editor`, the shared header marks Editor active and links Dashboard back to `/agents/$agentId`.
- Integration: Header source still renders `AgentHeaderBadges`, `AgentRollbackButton`, and the Automations badge, preserving non-editor controls.
- Edge case: Loading/error handling remains present when the agent query has not produced an agent.

**Verification:**
- Both Dashboard and Editor can render the same agent name, slug, badges, and tabs through the shared chrome.

---

- U2. **Keep Dashboard Route as the Dashboard Tab**

**Goal:** Refactor the existing Agent Detail route so `/agents/:agentId` uses the shared chrome, removes the old Workspace badge, and preserves the current dashboard body.

**Requirements:** R1, R2, R5, R7, R8, R9; covers F1, AE1, AE4

**Dependencies:** U1

**Files:**
- Modify: `apps/admin/src/routes/_authed/_tenant/agents/$agentId.tsx`
- Test: `apps/admin/src/components/agents/__tests__/AgentDetailRoutes.target.test.ts` or equivalent target test

**Approach:**
- Keep `/agents/:agentId` as the route for metrics, activity chart, cost summary, and recent activity.
- Remove the `Workspace` badge/link from the header children once the `Editor` tab is present.
- Continue rendering Automations and Rollback controls in the shared header.
- Preserve dashboard-specific data flow: thread and run subscriptions, cost data, `hasRecentActivity`, and activity refresh stay in the dashboard route.
- Keep `AgentFormDialog` behavior equivalent, including the recent-activity warning derived from dashboard activity.

**Patterns to follow:**
- Current `apps/admin/src/routes/_authed/_tenant/agents/$agentId.tsx` body structure.
- Origin AE4: no separate `Workspace` badge when the new tabs exist.

**Test scenarios:**
- Covers AE1. Given `/agents/:agentId`, the route source renders Dashboard tab content through `AgentMetrics` and `AgentActivity`.
- Covers AE4. The dashboard header source no longer imports `FolderOpen` or renders a `Workspace` badge/link.
- Happy path: Automations link remains available with `search={{ type: "agent", agentId }}`.
- Integration: Activity subscriptions and refresh callbacks remain in the dashboard route after header extraction.

**Verification:**
- `/agents/:agentId` remains visually equivalent below the header, except for the new tab switcher and removed Workspace badge.

---

- U3. **Add the Editor Tab Route**

**Goal:** Add `/agents/:agentId/editor` as the first-class editor tab that embeds the existing agent workspace editor under Agent Detail chrome.

**Requirements:** R1, R3, R4, R8, R9; covers F2, AE2

**Dependencies:** U1

**Files:**
- Create: `apps/admin/src/routes/_authed/_tenant/agents/$agentId_.editor.tsx`
- Modify: `apps/admin/src/components/agent-builder/AgentBuilderShell.tsx` if needed to expose an embed-friendly boundary
- Test: `apps/admin/src/components/agents/__tests__/AgentDetailRoutes.target.test.ts` or equivalent target test

**Approach:**
- Create a TanStack route for `/_authed/_tenant/agents/$agentId_/editor`.
- Validate and preserve optional `folder` search state using the same plain TypeScript `validateSearch` style as the old workspace route.
- Render the shared Agent Detail chrome with active tab `editor`.
- Mount `WorkspaceEditor` with `target={{ agentId }}`, `mode="agent"`, `agentId`, `agentSlug`, `initialFolder`, `AGENT_WORKSPACE_DEFAULT_FILES`, and `bootstrapLabel="Create Default Files"`.
- Avoid rendering a nested `PageLayout` or the old `Agent Builder : <name>` title inside the Editor tab. If `AgentBuilderShell` remains useful, split it so the route can reuse the editor composition without the shell chrome.

**Patterns to follow:**
- `apps/admin/src/routes/_authed/_tenant/agents/$agentId_.workspace.tsx` for `folder` search parsing.
- `apps/admin/src/components/agent-builder/AgentBuilderShell.tsx` for the exact `WorkspaceEditor` props required for agent mode.
- `apps/admin/src/routes/_authed/_tenant/agent-templates/$templateId.$tab.tsx` for embedding `WorkspaceEditor` inside another page's chrome.

**Test scenarios:**
- Covers AE2. Given the editor route source, it uses the shared Agent Detail chrome with active tab `editor` and renders `WorkspaceEditor`.
- Happy path: `folder` search state is read and passed to the workspace editor as the initial folder.
- Edge case: The editor route does not render the old standalone `Agent Builder` page title or a nested `PageLayout`.
- Integration: Editor route passes agent slug into the workspace editor when available so existing workspace behavior remains unchanged.

**Verification:**
- Navigating to `/agents/:agentId/editor` shows the same agent header/tabs as Dashboard, with the workspace editor replacing dashboard content.

---

- U4. **Redirect Legacy Workspace Links and Regenerate Routes**

**Goal:** Preserve old workspace deep links while making `/editor` the canonical editor destination.

**Requirements:** R3, R6; covers F3, AE3

**Dependencies:** U3

**Files:**
- Modify: `apps/admin/src/routes/_authed/_tenant/agents/$agentId_.workspace.tsx`
- Modify: `apps/admin/src/routes/_authed/_tenant/agents/$agentId_.workspaces.tsx`
- Modify: `apps/admin/src/routeTree.gen.ts`
- Test: `apps/admin/src/components/agents/__tests__/AgentDetailRoutes.target.test.ts` or equivalent target test

**Approach:**
- Change `/agents/:agentId/workspace` from rendering the builder to redirecting to `/agents/:agentId/editor`.
- Preserve `folder` from search state in the redirect target.
- Update `/agents/:agentId/workspaces` to redirect directly to `/editor` as well, avoiding an unnecessary two-hop redirect through `/workspace`.
- Regenerate `apps/admin/src/routeTree.gen.ts` through the admin build/dev route-generation workflow and inspect the diff for expected route additions/redirect changes only.

**Patterns to follow:**
- Existing `apps/admin/src/routes/_authed/_tenant/agents/$agentId_.workspaces.tsx` `Navigate` redirect.
- Existing plans' route tree guidance: regenerate generated route tree artifacts rather than hand-editing them.

**Test scenarios:**
- Covers AE3. Given `/agents/:agentId/workspace?folder=skills`, the route redirects to `/agents/:agentId/editor?folder=skills`.
- Edge case: Missing `folder` search state redirects without adding a bogus folder value.
- Integration: Generated `routeTree.gen.ts` includes the new editor route and keeps compatibility route entries.

**Verification:**
- Old bookmarks and in-app links to workspace routes land on the Editor tab with folder intent preserved.

---

- U5. **Browser and Visual Verification**

**Goal:** Verify the final admin UX against the screenshots' intended hierarchy and catch layout issues that source tests cannot prove.

**Requirements:** R1, R4, R5, R7, R8, R9; covers AE1, AE2, AE4

**Dependencies:** U1, U2, U3, U4

**Files:**
- No production file changes expected unless verification reveals layout defects.

**Approach:**
- Use the admin dev server with the ignored env file copied from the main checkout per `AGENTS.md`.
- Open an existing agent detail page and compare the header hierarchy against the intended mock: title and badges remain, `Dashboard`/`Editor` appears as the primary mode switch, and no `Workspace` badge remains.
- Switch to Editor and confirm the workspace editor fills the content area without a nested standalone builder title.
- Open an old `/workspace?folder=...` link and confirm it lands on the Editor tab with the intended folder selected.

**Patterns to follow:**
- `AGENTS.md` admin dev-server instructions for worktree env setup and port selection.
- Template Detail screenshot/pattern for tab placement and visual weight.

**Test scenarios:**
- Test expectation: none -- this unit is manual/browser verification of layout and routing after automated source tests.

**Verification:**
- Dashboard and Editor are visually peer tabs on desktop.
- Header badges remain usable and do not overlap the tab switcher.
- Workspace editor scroll and pane sizing remain usable inside the Agent Detail content area.

---

## System-Wide Impact

- **Interaction graph:** Agent Detail dashboard, new editor route, legacy workspace redirect routes, shared `WorkspaceEditor`, and generated TanStack route tree are affected.
- **Error propagation:** Agent detail load errors should remain visible through the shared chrome; workspace editor errors continue to be handled by `WorkspaceEditor`.
- **State lifecycle risks:** `folder` search state must survive redirects and reach `WorkspaceEditor`; dashboard activity subscriptions should not start on the Editor tab.
- **API surface parity:** No GraphQL, REST, workspace-files, or runtime API changes are planned.
- **Integration coverage:** Source tests cover route composition and redirect intent; browser verification covers layout, active tab state, and editor embedding.
- **Unchanged invariants:** Dashboard URL remains `/agents/:agentId`; workspace file operations remain owned by `WorkspaceEditor`; old workspace URLs remain compatible.

---

## Risks & Dependencies

| Risk | Mitigation |
|------|------------|
| Extracting header chrome accidentally drops a badge mutation or edit-dialog behavior | Keep U1 focused on moving existing behavior, and add target tests that assert key controls remain wired into shared chrome. |
| The editor tab duplicates the agent detail query or loses refresh coupling with header controls | Have shared chrome expose loaded agent context and refresh callbacks to route content. |
| The recent-activity edit warning disappears outside the dashboard route | Treat this explicitly in U1: preserve it on Dashboard and make any Editor-route behavior intentional rather than an accidental regression. |
| Editor route renders nested page chrome or loses available height | Embed `WorkspaceEditor` directly or split `AgentBuilderShell`; verify with browser layout in U5. |
| Old workspace links lose `folder` state | Preserve `validateSearch` on redirect routes and test the `folder=skills` case explicitly. |
| Generated route tree includes unrelated churn | Regenerate via the admin build/dev workflow and inspect the generated diff before committing. |

---

## Documentation / Operational Notes

- No public docs update is required; this is an admin navigation refinement.
- If implementation changes visible screenshots or demos in future docs, update those artifacts separately.

---

## Sources & References

- **Origin document:** `docs/brainstorms/2026-04-28-agent-detail-dashboard-editor-tabs-requirements.md`
- Related code: `apps/admin/src/routes/_authed/_tenant/agents/$agentId.tsx`
- Related code: `apps/admin/src/routes/_authed/_tenant/agents/$agentId_.workspace.tsx`
- Related code: `apps/admin/src/components/agent-builder/AgentBuilderShell.tsx`
- Related code: `apps/admin/src/components/agent-builder/WorkspaceEditor.tsx`
- Related code: `apps/admin/src/routes/_authed/_tenant/agent-templates/$templateId.$tab.tsx`
- Related code: `apps/admin/src/routes/_authed/_tenant/analytics.tsx`
- Institutional learning: `docs/plans/2026-04-26-008-refactor-template-agent-builder-parity-plan.md`
- Institutional learning: `docs/solutions/workflow-issues/agent-builder-smoke-cleanup-needs-manifest-regeneration-2026-04-26.md`
