mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
1114ee5ea0
* [13d03d5c] Add 5 coordination-event notification producers + wire at chokepoints (#472) (#474) * [13d03d5c] Add 5 coordination-event notification producer methods * [13d03d5c] Wire reassignment/collision/unblock/dependency-revival notifications * [13d03d5c] Wire stale-claim-reaped notification into orchestrator reaper * [13d03d5c] fix(runtime): guard reaper's UUID annotation + defensive attr access The stale-claim-reaped notification hook added a runtime-unquoted `UUID` type annotation (only imported under TYPE_CHECKING, so the module raised NameError on import) and a direct `t.assigned_to` attribute access that crashes against the minimal test doubles the existing reaper test suite uses. Quote the annotation and switch to getattr-defensive access, matching `_assignee_is_provider_parked`'s existing convention in the same file. * [13d03d5c] test(notification): unit coverage for 5 coordination-event producers One test per new send_* method (reassignment, collision-sequencing, unblock, dependency-revival, stale-claim-reaped) following the existing _FakeDb/_patch_db_context pattern, asserting subject/body/ related_task_id/priority/recipient-count, plus a no-recipients no-op case for reassignment. * [13d03d5c] test(task): prove reassign + unblock don't double-fire notifications Two chokepoint-level tests mocking NotificationService at its defining module: a repeated reassign() to the same already-current target skips the notification (guarded by comparing against the pre-mutation assignee), and a repeated unblock() on the same task only notifies once since the second call short-circuits on the status!=BLOCKED guard. * [13d03d5c] style(task): ruff format the collision-sequencing wiring block No behavior change — reflows the newly-added _notify_collision_sequencing call site to satisfy ruff format's line-length rules. * [13d03d5c] docs(backend): add coordination-event notification producers guide Documented the 5 new NotificationService producers (reassignment, collision-sequencing, unblock, dependency-revival, stale-claim-reaped) with fire conditions, double-fire prevention mechanisms, and implementation patterns. Updated backend README to link the new services guide for developers integrating new coordination events. --------- Co-authored-by: Backend Developer 1 <be-dev-1@roboco.tech> Co-authored-by: Backend Documenter <be-doc@roboco.tech> * [3ee8150b] Frontend: render coordination-event notifications + e2e smoke coverage (#475) * [69777c3a] test(e2e-smoke): add coverage for soft-block + unblock coordination notifications (#471) Co-authored-by: Frontend Developer 2 <fe-dev-2@roboco.tech> * [8eb82639] Render 5 coordination-event notification types with task deep-links (#470) * [8eb82639] feat(notifications): add APPROVAL type icon and deep-link component test Add missing APPROVAL member to the frontend NotificationType enum to match backend roboco/models/base.py, wire its icon into the existing typeIcons Record in the notifications page, and add a component test covering type rendering and the task deep-link. * [8eb82639] docs(notifications): document 5 coordination-event types and APPROVAL enum addition Added comprehensive reference guide explaining the 5 notification types (TASK_ASSIGNMENT, BLOCKER_ESCALATION, REVIEW_REQUEST, DOCUMENTATION_REQUEST, APPROVAL), their visual identities (icon + color), use cases, and deep-linking behavior to related tasks. Updated panel README with quick reference table. TypeScript Record pattern ensures exhaustive type coverage at build time. --------- Co-authored-by: Frontend Developer 1 <fe-dev-1@roboco.tech> Co-authored-by: Frontend Documenter <fe-doc@roboco.tech> --------- Co-authored-by: Frontend Developer 2 <fe-dev-2@roboco.tech> Co-authored-by: Frontend Developer 1 <fe-dev-1@roboco.tech> Co-authored-by: Frontend Documenter <fe-doc@roboco.tech> * [a27de2a8] fix(docs): reflow hard-wrapped notification-types.md to pass markdown gate (#479) (#481) The Python quality gate on assembled PR #477 was red because the newly added docs/frontend/components/notification-types.md (introduced by the frontend coordination-event rendering commit) had manually wrapped prose paragraphs, which scripts/reflow_md.py --check rejects as part of make quality. Reflowed the file with scripts/reflow_md.py --apply (whitespace only, no content change) so the check passes. ruff format/check, mypy, xenon, vulture, bandit, and the full pytest suite (10284 passed) all confirmed green on this commit; notification.py, task.py, and orchestrator.py are untouched. Co-authored-by: Backend Developer 1 <be-dev-1@roboco.tech> * [705419d5] Remove duplicate unblock notification and fix its dependent tests (#485) (#488) * [705419d5] fix(notifications): remove duplicate unblock notification, fix its tests The /unblock route was still calling delivery.notify_assignee_of_unblock() (TASK_ASSIGNMENT) after TaskService.unblock() already sent the send_unblock_notification() ALERT wired in by an earlier task — a real duplicate notification on every unblock. Delete the route-layer call and the now-dead NotificationDeliveryService.notify_assignee_of_unblock method, fix the integration test that mocked it, and fix/extend the e2e notification-coordination-events test to assert the persisted ALERT rows (exact subjects) for both the direct-unblock and dependency-revival producers instead of the old TASK_ASSIGNMENT assertion. * [705419d5] docs(backend): update coordination-events doc for unblock duplicate removal --------- Co-authored-by: Backend Developer 1 <be-dev-1@roboco.tech> Co-authored-by: Backend Documenter <be-doc@roboco.tech> * [6c142a73] docs(changelog): document restored coordination-event notification producers and add collision-sequencing double-fire test (#489) (#490) Co-authored-by: Backend Developer 2 <be-dev-2@roboco.tech> * [77719d3f] Seed system agent in e2e harness to fix unblock/dependency-revival notifications The e2e harness's seed_company omitted the system sentinel agent that production seeds via initial_data.py. The unblock and dependency-revival notification producers default to from_agent="system", which _resolve_agent_uuid looks up by slug in the DB. With no system row the resolver returns None and _create_notification silently skips the notification, so the two ALERT assertions got 0 rows instead of 1. The soft-block test passed because it uses NotificationDeliveryService which creates the notification directly with a real agent UUID as from_agent, bypassing the slug resolution path entirely. * [77719d3f] Use foundation UUID for system agent to avoid slug collision The first attempt seeded the system agent with a random UUID. Other tests (_seed_system_and_secretary, _seed_video_agents) check by the fixed foundation UUID via session.get(AgentTable, uuid); not finding it they INSERT their own system row, hitting ix_agents_slug. Using the foundation UUID makes their check find the seed_company row and skip. * [77719d3f] Fix dependency-revival notification event loop mismatch The dependency-revival test calls _unblock_dependents directly via stack.run_db, which creates a new asyncio event loop. Inside, _notify_dependency_revival -> NotificationService._create_notification opened its own session via get_db_context(), which reuses the singleton _DbHolder engine — bound to the FastAPI server's event loop. The asyncpg connection raised 'Future attached to a different loop' and the exception was silently caught + logged as a warning, so the notification never persisted and the test saw 0 rows. Fix: add an optional db_session parameter to _create_notification and the two send methods. When provided, use the caller's session directly and skip the internal commit (the caller owns the transaction). The TaskService's _notify_unblock and _notify_dependency_revival now pass self.session, keeping the notification in the same event loop + session as the task transition. * [77719d3f] Scope system-agent seeding to notification tests only Seeding the system sentinel in seed_company (commits 3bba7b32/617b7890) fixed the 0-notification bug but caused 3 i_documented gateway_timeout failures: every e2e test now paid notification-creation latency for system-origin notifications that were previously silently skipped, pushing the already-slow i_documented verb past its 120s timeout. Move system-agent seeding out of seed_company and into a scoped _seed_system_agent helper called only by the two coordination-event tests that exercise send_unblock_notification / send_dependency_revival_notification (both resolve from_agent='system' via DB lookup). dev_lifecycle and state_machine tests revert to the pre-fix behavior (system-origin notifications silently skipped, no extra latency). The event-loop fix (commit7b95d77d: pass db_session=self.session to _create_notification) is unchanged — dependency_revival still needs it because stack.run_db creates a new event loop while _DbHolder.engine is bound to the FastAPI server loop. * [77719d3f] Fix reassignment notification deadlock + suppressed-notification commit regression Two fixes in notification.py / task.py: 1. Cross-session self-deadlock in send_reassignment_notification: TaskService.reassign() flushes an uncommitted row lock on the task, then calls _notify_reassignment -> send_reassignment_notification -> _create_notification(db_session=None) which opens a SEPARATE session via get_db_context() and INSERTs a notification with related_task_id FK -> tasks.id. The FK key-share lock blocks on the request session's uncommitted exclusive lock, but the request can't commit until the notify returns -> 120s verb hard-cut. Fix: pass db_session=self.session so the notification joins the verb's own transaction, same pattern as the unblock/dependency-revival fix in7b95d77d. 2. Suppressed-notification commit regression: the7b95d77drefactor moved await db.commit() out of _create_notification_with_session into _create_notification's db_session=None branch, where it ran unconditionally — even when _create_notification_with_session returned early (suppressed: unresolvable from_agent / no recipients / refire-guard / dedup-hit). Fix: _create_notification_with_session now returns bool (False at each early return, True after delivery); _create_notification commits only when created is True. --------- Co-authored-by: Backend Developer 1 <be-dev-1@roboco.tech> Co-authored-by: Backend Documenter <be-doc@roboco.tech> Co-authored-by: Frontend Developer 2 <fe-dev-2@roboco.tech> Co-authored-by: Frontend Developer 1 <fe-dev-1@roboco.tech> Co-authored-by: Frontend Documenter <fe-doc@roboco.tech> Co-authored-by: Backend Developer 2 <be-dev-2@roboco.tech> Co-authored-by: Renn F <rennf93@users.noreply.github.com>
100 lines
4.5 KiB
Markdown
100 lines
4.5 KiB
Markdown
# RoboCo Control Panel
|
|
|
|
Next.js 16 control panel for the RoboCo AI agent system. Formerly a separate repository (`rennf93/roboco-panel`), now vendored under `panel/` in this monorepo so `docker compose up -d` brings up the whole stack from one place.
|
|
|
|
## Stack
|
|
|
|
- Next.js 16 (App Router, standalone output)
|
|
- TypeScript
|
|
- Tailwind CSS
|
|
- Radix UI primitives
|
|
- `dnd-kit` for drag/drop (kanban)
|
|
- pnpm for package management
|
|
|
|
## Running in production (the normal path)
|
|
|
|
Use the root-level Docker Compose:
|
|
|
|
```bash
|
|
# from the repo root (one level up from this directory)
|
|
docker compose up -d
|
|
```
|
|
|
|
The panel is built as part of the compose stack via `docker/panel.Dockerfile` and served internally on port 3000. Nginx (also in the compose stack) is the single externally-exposed service on `http://localhost:3000` and routes:
|
|
|
|
- `/api/*` and `/ws/*` → orchestrator (FastAPI, port 8000)
|
|
- everything else → the Next.js panel
|
|
|
|
The panel uses relative URLs (`/api/v1`, `/ws`) so nothing here needs a backend URL in `.env`.
|
|
|
|
## Running the panel alone for UI development
|
|
|
|
```bash
|
|
cd panel
|
|
pnpm install
|
|
pnpm dev
|
|
```
|
|
|
|
That gives you Next dev-server on `localhost:3000`, but you still need the orchestrator reachable at `localhost:8000` (or via nginx) for API calls to work. Easiest: `docker compose up -d` the backend services, then run `pnpm dev` against that.
|
|
|
|
## Build scripts
|
|
|
|
- `pnpm dev` — development server with hot reload
|
|
- `pnpm build` — production build (outputs `.next/standalone/`)
|
|
- `pnpm start` — run the standalone build
|
|
- `pnpm lint` — ESLint
|
|
|
|
## Where things live
|
|
|
|
- `src/app/` — Next.js App Router pages
|
|
- `src/components/` — React components (organized by feature: tasks, agents, channels, …)
|
|
- `src/lib/api/` — typed API client (thin wrappers over `fetch`)
|
|
- `src/lib/` — constants, utilities, WebSocket hooks
|
|
- `src/types/` — shared TypeScript types mirroring backend schemas (includes `NotificationType` enum)
|
|
- `src/hooks/` — reusable React hooks (see [Frontend hooks](../docs/frontend/hooks.md))
|
|
- `src/app/(dashboard)/notifications/` — notifications inbox page and components
|
|
|
|
## Hooks
|
|
|
|
The panel exposes public hooks under `@/hooks`. See [Frontend hooks](../docs/frontend/hooks.md) for full API reference and examples.
|
|
|
|
### `usePageRefresh`
|
|
|
|
Page-scoped refresh coordinator. Pages register data-refetch callbacks; the navbar refresh button in `src/components/layout/header.tsx` calls `refresh()` and reflects the combined `loading`/`disabled` state. The button is disabled when no callbacks are registered (the registry is empty) and while a refresh is in progress.
|
|
|
|
```tsx
|
|
import { usePageRefresh } from "@/hooks";
|
|
|
|
const { register, unregister, refresh, loading, disabled } = usePageRefresh();
|
|
```
|
|
|
|
- `disabled` is `true` when no callbacks are registered (there is nothing to refresh)
|
|
- `disabled` becomes `false` once a callback is registered
|
|
- `disabled` returns to `true` when all callbacks are unregistered
|
|
|
|
Wrap your page or layout in `PageRefreshProvider` from `@/components/providers` before consuming the hook. Dashboard pages should register their refetch callbacks and avoid adding inline "Refresh" buttons; see [`docs/frontend/components/page-refresh-provider.md`](../docs/frontend/components/page-refresh-provider.md) for the full wiring list and examples.
|
|
|
|
## Notifications
|
|
|
|
The panel renders five core **coordination-event notification types** that signal task lifecycle transitions between agents:
|
|
|
|
| Type | Icon | Color | Meaning |
|
|
|------|------|-------|---------|
|
|
| `TASK_ASSIGNMENT` | ListTodo | green | A task has been assigned to you |
|
|
| `BLOCKER_ESCALATION` | AlertTriangle | red | A developer is blocked and escalated |
|
|
| `REVIEW_REQUEST` | Check | purple | Your review is needed |
|
|
| `DOCUMENTATION_REQUEST` | Info | blue | Documentation is needed |
|
|
| `APPROVAL` | ShieldCheck | emerald | Board-level approval requested |
|
|
|
|
Each notification optionally carries a `related_task_id` rendered as a deep-link to `/tasks/{id}`. For full details on types, icons, and adding new types, see [`docs/frontend/components/notification-types.md`](../docs/frontend/components/notification-types.md).
|
|
|
|
## Dependency Management
|
|
|
|
### Version Alignment
|
|
|
|
When bumping **Next.js**, always update **eslint-config-next** to match the same version. These packages must stay in sync. See `UPGRADE.md` for detailed procedures and troubleshooting.
|
|
|
|
## Backend schema changes
|
|
|
|
When the backend changes response shapes, mirror them in `src/types/` and the relevant `src/lib/api/` module. Keep API paths relative so nginx routing keeps working.
|