136 lines
3.8 KiB
Markdown
136 lines
3.8 KiB
Markdown
# Observability Redesign Implementation Instructions
|
|
|
|
## Role
|
|
|
|
You are Opus in the distribution platform orchestration flow. Codex is the
|
|
manager. Snarky owns product acceptance. You own layout and visual design
|
|
decisions and are the only role allowed to edit code during this phase.
|
|
|
|
## User Direction
|
|
|
|
The user clarified that the git setup required for the Opus implementation
|
|
branch is Opus responsibility.
|
|
|
|
If `/Users/agra/projects/distribution` is not yet a git repository, initialize a
|
|
local git repository, create a clean baseline commit from the current workspace,
|
|
and then create or switch to branch:
|
|
|
|
```txt
|
|
opus/observability-redesign
|
|
```
|
|
|
|
Use branches only. Do not create a worktree.
|
|
|
|
## Primary Task
|
|
|
|
Implement the observability dashboard redesign from:
|
|
|
|
```txt
|
|
.agents/runs/2026-06-02-observability-redesign/opus-proposal.md
|
|
```
|
|
|
|
The dashboard lives at:
|
|
|
|
```txt
|
|
.agents/observability/
|
|
```
|
|
|
|
It is served by:
|
|
|
|
```txt
|
|
.agents/scripts/observe.mjs
|
|
```
|
|
|
|
## Allowed Edit Scope
|
|
|
|
Application/dashboard edits are limited to:
|
|
|
|
- `.agents/observability/index.html`
|
|
- `.agents/observability/styles.css`
|
|
- `.agents/observability/app.js`
|
|
- `.agents/scripts/observe.mjs`
|
|
- `.agents/runs/2026-06-02-observability-redesign/implementation-log.md`
|
|
|
|
Creating `.git/` and committing/switching branches is allowed as setup for this
|
|
phase. Do not edit root mock files such as `index.html`, `styles.css`, or
|
|
`app.js`.
|
|
|
|
## Required Product Shape
|
|
|
|
Implement the proposal's operational cockpit direction:
|
|
|
|
- Replace the four metric cards with a compact sticky status bar and a "Now"
|
|
command band.
|
|
- Make the first viewport answer what is active, whether anything is blocked or
|
|
stalled, who is working, what happened recently, and what the manager should do
|
|
next.
|
|
- Pin active-agent liveness with status, lease countdown, heartbeat age, and
|
|
clear warning/dead states.
|
|
- Keep progress readable but bounded; it must not dominate the whole page.
|
|
- Keep the UI dense, calm, and operational. Avoid marketing layout, hero copy,
|
|
decorative nesting, and generic dashboard fluff.
|
|
- Support desktop and mobile without text overlap.
|
|
|
|
## Required Interactions
|
|
|
|
- Keep the existing `/api/status` polling model and static vanilla app.
|
|
- Add a one-second local ticker for freshness, heartbeat age, and lease
|
|
countdown text.
|
|
- Add pause/resume for auto-refresh.
|
|
- Keep the last good render on fetch error; do not replace the progress log with
|
|
an error message.
|
|
- Add progress expand/collapse.
|
|
- Preserve progress bottom-stick behavior and show a jump control when new lines
|
|
arrive while the user is scrolled up.
|
|
- Make run rows selectable. If the API supports `?run=`, use it to refocus
|
|
progress for the selected run; otherwise degrade gracefully.
|
|
- Add click-to-copy for run id, branch, and progress path with a short copied
|
|
state.
|
|
|
|
## Required Server/API Additions
|
|
|
|
Make only additive, optional changes:
|
|
|
|
- Per-agent liveness fields:
|
|
- `lease_remaining_ms`
|
|
- `heartbeat_age_ms`
|
|
- `lease_expired`
|
|
- `is_active`
|
|
- Summary fields:
|
|
- `active_role`
|
|
- `health`
|
|
- Active progress fields:
|
|
- `modified_at`
|
|
- `total_lines`
|
|
- `truncated`
|
|
- Support `/api/status?tail=N&run=<id>` so selected runs can show their own
|
|
progress.
|
|
- In progress selection, prefer the newest candidate progress artifact by mtime.
|
|
|
|
The frontend must remain missing-field safe.
|
|
|
|
## Validation Expectations
|
|
|
|
Before finishing, run:
|
|
|
|
```sh
|
|
node --check .agents/scripts/observe.mjs
|
|
node --check .agents/observability/app.js
|
|
node .agents/scripts/status.mjs --tail 20
|
|
```
|
|
|
|
If possible, start or reuse the local server and verify:
|
|
|
|
```sh
|
|
curl http://127.0.0.1:4317/api/status?tail=5
|
|
```
|
|
|
|
Write a short final implementation report to:
|
|
|
|
```txt
|
|
.agents/runs/2026-06-02-observability-redesign/implementation-log.md
|
|
```
|
|
|
|
Include changed files, validation commands/results, unresolved risks, and the
|
|
current git branch/status.
|