0a15785c98
Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
68 lines
3.9 KiB
Markdown
68 lines
3.9 KiB
Markdown
---
|
|
spec: docs/specs/ui/subagent-observability.md
|
|
created: 2026-08-25
|
|
status: done
|
|
---
|
|
|
|
# Implementation Plan: Subagent active header status
|
|
|
|
## Overview
|
|
|
|
The collapsed subagent header already has a `GridSpinner` while `isSubagentEffectivelyActive` is true, but `task:working` is gated on `isActive && !hasExpandableContent`. A live wave with nested children therefore looks like a settled type + description row. This plan keeps Working + spinner on every active header, adds a red `IconX` after failed or cancelled finishes, and shows a muted completion check after success. Identity chips stay settled-card metadata. Unit tests cover the new states; existing `/e2e:subagent` specs assert the settled header. No backend or mock-agent change.
|
|
|
|
## Frontend
|
|
|
|
### `apps/web/components/task/chat/messages/tool-subagent-message.tsx`
|
|
|
|
- Delete `showInlineWorking`. Render `t("task:working")` whenever `isActive`, next to the existing `GridSpinner`, including when `hasExpandableContent` is true.
|
|
- Pass `metadata?.status` into `SubagentHeader`. When not active, if `normalizeToolCallStatus(status)` is `error` or `cancelled`, render a shrink-0 red `IconX` (`h-3.5 w-3.5 text-red-500`) with `aria-label` `task:failed` or `task:cancelled`. Pattern: `ExecuteStatusIcon` in `tool-execute-message.tsx`, but reuse `task:failed` / `task:cancelled` instead of command keys, and never render `IconCheck`.
|
|
- Keep `SubagentMetaRow` and the UUID/model/duration chip timing (`!isActive`). Preserve terminal nested payload precedence in `isSubagentEffectivelyActive`.
|
|
|
|
### Mobile design contract
|
|
|
|
- Desktop and mobile share the same header. No overlay, drawer, or navigation change.
|
|
- Nearest exemplar: `ExecuteStatusIcon` plus the existing subagent header (`min-h-11` expandable hit target below `sm`).
|
|
- Status glyph stays `shrink-0` so type, description, and Working truncate first.
|
|
- Parity proof: `mobile-subagent.spec.ts` asserts the settled header at phone width.
|
|
|
|
## Tests
|
|
|
|
- **What:** active card with children still shows Working + Loading spinner; complete card shows one Completed check; failed/cancelled show the labelled red mark.
|
|
**File:** `apps/web/components/task/chat/messages/tool-subagent-message.test.tsx`.
|
|
**How:** extend `ToolSubagentMessage` / expansion cases. Active + `childMessages` must show `task:working` and `role=status` name `Loading`. Complete + children must not. Failed/cancelled fixtures assert `getByLabelText` for Failed / Cancelled and no spinner.
|
|
|
|
## E2E Tests
|
|
|
|
- **Scenario:** GIVEN `/e2e:subagent` completes, WHEN the card is visible, THEN there is no Loading status, no Working copy, one Completed check, and the metadata row is visible.
|
|
**Files:** `apps/web/e2e/tests/chat/subagent.spec.ts` and `apps/web/e2e/tests/chat/mobile-subagent.spec.ts`.
|
|
- Do not add a mock-agent scenario. The existing `scenarioSubagent` window is ~150ms; active-with-children and failed/cancelled are unit-tested.
|
|
|
|
## Verification Results
|
|
|
|
- `pnpm --filter @kandev/web test -- components/task/chat/messages/tool-subagent-message.test.tsx` — 52 passed.
|
|
- `pnpm exec eslint` + `pnpm run typecheck` on the two unit files — pass.
|
|
- `pnpm e2e:run --host --project chromium -- tests/chat/subagent.spec.ts` — 1 passed.
|
|
- `pnpm e2e:run --host --project mobile-chrome -- tests/chat/mobile-subagent.spec.ts` — 1 passed.
|
|
|
|
## Implementation Waves And Parallel Candidates
|
|
|
|
Wave 1:
|
|
|
|
- [x] [task-01-header-status-ui](task-01-header-status-ui.md)
|
|
|
|
Wave 2:
|
|
|
|
- [x] [task-02-subagent-status-e2e](task-02-subagent-status-e2e.md)
|
|
|
|
Sequential. E2E asserts the settled header produced by task 01.
|
|
|
|
## Risks
|
|
|
|
- Fresh worktrees need `cd apps && pnpm install --frozen-lockfile` before any pnpm command.
|
|
- E2E runs the production Vite build. Rebuild after the UI change (`pnpm e2e:run` does this; a stale `apps/web/dist` will miss the header).
|
|
- Do not invent `task:subagentFailed` keys. Reuse `task:working`, `task:failed`, `task:cancelled`, and `common:loadingIndicatorLabel`.
|
|
|
|
## Open Questions
|
|
|
|
None.
|