William Valentin
99 lines
4.1 KiB
Markdown
99 lines
4.1 KiB
Markdown
# Requirements: Flynn Operator DX
|
|
|
|
**Defined:** 2026-02-09
|
|
**Core Value:** Make Flynn easier to reason about, configure, and monitor
|
|
|
|
## v1 Requirements
|
|
|
|
Requirements for this milestone. Each maps to roadmap phases.
|
|
|
|
### Daemon Decomposition
|
|
|
|
- [x] **DECO-01**: Model client creation logic extracted from daemon/index.ts into src/daemon/models.ts with the same public interface
|
|
- [x] **DECO-02**: Channel adapter setup logic extracted into src/daemon/channels.ts
|
|
- [x] **DECO-03**: Agent cache and factory logic extracted into src/daemon/agents.ts
|
|
- [x] **DECO-04**: Memory store and vector store initialization extracted into src/daemon/memory.ts
|
|
- [x] **DECO-05**: Tool registration and policy wiring extracted into src/daemon/tools.ts
|
|
- [x] **DECO-06**: Message routing logic extracted into src/daemon/routing.ts (test file already exists)
|
|
- [x] **DECO-07**: daemon/index.ts reduced to a thin composition root that imports and wires extracted modules
|
|
- [x] **DECO-08**: All 1077+ existing tests continue to pass after decomposition
|
|
|
|
### Config Overlays
|
|
|
|
- [x] **CONF-01**: User can set FLYNN_ENV environment variable to select a config overlay (e.g., docker, production)
|
|
- [x] **CONF-02**: Config loader merges environment-specific overlay file on top of base config with deep merge
|
|
- [x] **CONF-03**: flynn doctor validates that the selected environment overlay file exists when FLYNN_ENV is set
|
|
|
|
### Live Ops Dashboard
|
|
|
|
- [x] **DASH-01**: Dashboard shows core counters: messages processed, active sessions, queue depth, daemon uptime
|
|
- [x] **DASH-02**: Dashboard shows model call metrics: per-call latency, tokens/sec throughput, error rates by provider
|
|
- [x] **DASH-03**: Dashboard shows live event stream: scrollable log of errors and events with timestamps and context
|
|
- [x] **DASH-04**: Dashboard shows active request tracking: in-flight requests, recent tool executions, active agent sessions
|
|
- [x] **DASH-05**: Gateway exposes /health endpoint returning JSON status for liveness/readiness checks
|
|
|
|
## v2 Requirements
|
|
|
|
Deferred to future milestone. Tracked but not in current roadmap.
|
|
|
|
### Observability
|
|
|
|
- **OBSV-01**: Structured JSON logging framework (pino or similar) replacing console.log
|
|
- **OBSV-02**: Request tracing with correlation IDs across channel → agent → model → tool chain
|
|
- **OBSV-03**: Prometheus-compatible metrics endpoint for external monitoring
|
|
|
|
### Config
|
|
|
|
- **CONF-04**: Deep merge semantics for overlay files (objects merge, arrays replace)
|
|
- **CONF-05**: Convention-based overlay file discovery (config/default.yaml + config/{env}.yaml)
|
|
- **CONF-06**: Hot reload of config changes without daemon restart
|
|
|
|
### Code Quality
|
|
|
|
- **QUAL-01**: ESLint configuration with @typescript-eslint/recommended
|
|
- **QUAL-02**: Reduce `as any` casts by creating proper mock factories and wrapper types
|
|
- **QUAL-03**: Test coverage for security-sensitive file tools
|
|
|
|
## Out of Scope
|
|
|
|
| Feature | Reason |
|
|
|---------|--------|
|
|
| New channel adapters | Not the focus — separate milestone |
|
|
| Agent intelligence (sub-agents, planning) | Separate milestone |
|
|
| Companion apps (macOS, iOS, Android) | Massive scope, different project |
|
|
| Skill registry / marketplace | Community feature, premature |
|
|
| Onboard wizard | Operator already knows the system |
|
|
| Multi-tenant / team features | Single-operator tool |
|
|
|
|
## Traceability
|
|
|
|
Which phases cover which requirements. Updated during roadmap creation.
|
|
|
|
| Requirement | Phase | Status |
|
|
|-------------|-------|--------|
|
|
| DECO-01 | Phase 1 | Complete |
|
|
| DECO-02 | Phase 1 | Complete |
|
|
| DECO-03 | Phase 1 | Complete |
|
|
| DECO-04 | Phase 1 | Complete |
|
|
| DECO-05 | Phase 1 | Complete |
|
|
| DECO-06 | Phase 1 | Complete |
|
|
| DECO-07 | Phase 1 | Complete |
|
|
| DECO-08 | Phase 1 | Complete |
|
|
| CONF-01 | Phase 2 | Complete |
|
|
| CONF-02 | Phase 2 | Complete |
|
|
| CONF-03 | Phase 2 | Complete |
|
|
| DASH-01 | Phase 3 | Complete |
|
|
| DASH-02 | Phase 3 | Complete |
|
|
| DASH-03 | Phase 3 | Complete |
|
|
| DASH-04 | Phase 3 | Complete |
|
|
| DASH-05 | Phase 3 | Complete |
|
|
|
|
**Coverage:**
|
|
- v1 requirements: 16 total
|
|
- Mapped to phases: 16
|
|
- Unmapped: 0
|
|
|
|
---
|
|
*Requirements defined: 2026-02-09*
|
|
*Last updated: 2026-02-13 after Phase 3 completion*
|