William Valentin
982dcee5e0
- SUMMARY.md with task commits, decisions, self-check - STATE.md updated: phase 3 in_progress, 1/2 plans, test count 1107
101 lines
4.8 KiB
Markdown
101 lines
4.8 KiB
Markdown
# State: Flynn Operator DX
|
|
|
|
## Project Reference
|
|
|
|
**Core Value:** Make Flynn easier to reason about, configure, and monitor
|
|
**Milestone:** Operator DX
|
|
**Phases:** 3
|
|
|
|
## Current Position
|
|
|
|
**Phase:** 3 — Live Ops Dashboard
|
|
**Plan:** 1 of 2 complete (03-01 done)
|
|
**Status:** in_progress
|
|
**Progress:** ██████████ 2.5/3 phases (Phase 3: 1/2 plans)
|
|
|
|
## Phase Status
|
|
|
|
| Phase | Status | Plans |
|
|
|-------|--------|-------|
|
|
| 1 — Daemon Decomposition | **complete** | 3/3 plans complete |
|
|
| 2 — Config Overlays | **complete** | 2/2 plans complete |
|
|
| 3 — Live Ops Dashboard | **in_progress** | 1/2 plans complete |
|
|
|
|
## Performance Metrics
|
|
|
|
| Metric | Value |
|
|
|--------|-------|
|
|
| Test count | 1107 (verified after 03-01, +20 metrics tests from 1087 baseline) |
|
|
| daemon/index.ts lines | 140 (from 1087 baseline, -87%) |
|
|
| Total daemon modules | 9 files, 1271 lines |
|
|
| Plan 01-01 duration | 9 min |
|
|
| Plan 01-01 tasks | 3/3 |
|
|
| Plan 01-02 duration | ~25 min |
|
|
| Plan 01-02 tasks | 3/3 |
|
|
| Plan 01-03 duration | ~8 min |
|
|
| Plan 01-03 tasks | 2/2 |
|
|
| Plan 02-01 duration | 3 min |
|
|
| Plan 02-01 tasks | 2/2 |
|
|
| Plan 02-02 duration | ~1 min |
|
|
| Plan 02-02 tasks | 1/1 |
|
|
| Plan 03-01 duration | ~2 min |
|
|
| Plan 03-01 tasks | 2/2 |
|
|
|
|
## Accumulated Context
|
|
|
|
### Key Decisions
|
|
- Decompose god file incrementally, not rewrite
|
|
- Config overlays over separate files
|
|
- Extend existing vanilla JS dashboard
|
|
- Skip structured logging — dashboard will reveal what metrics matter
|
|
- Factory function pattern (initX(deps) → result) for daemon subsystem extraction
|
|
- initTools() kept synchronous — only shutdown callbacks are async
|
|
- Backward-compatible re-exports from daemon/index.ts for model functions
|
|
- Deps-interface factory pattern (ChannelsDeps, AgentsDeps) for explicit dependency injection
|
|
- registerChannels returns cronScheduler so Tier 1 cron tools can still be wired in startDaemon
|
|
- Lifecycle wiring stays in the module that owns the resource (agents.ts owns sandbox shutdown)
|
|
- Grouped skills/MCP/pairing/gateway/startup into services.ts rather than multiple tiny modules
|
|
- getChannelAgents callback for late-binding channel agents into gateway token usage reporting
|
|
- Type-only imports in index.ts for values only referenced in DaemonContext type definition
|
|
- Overlay merge before env expansion and Zod validation — overlays don't need required fields
|
|
- Arrays in overlays replace (not concat) — explicit override semantics
|
|
- resolveOverlayPath returns path without checking existence — callers decide error handling
|
|
- Doctor overlay check placed after checkConfigExists, before checkConfigParses — natural validation order
|
|
- Skip status when FLYNN_ENV not set — no noise for users without overlays
|
|
|
|
- MetricsCollector created inside GatewayServer constructor (self-contained, no services.ts changes needed)
|
|
- Ring buffers: 200 model calls, 500 events — configurable, bounded memory for long-running daemon
|
|
- Metrics passed as optional MetricsCollector instance to agent handler deps (not individual callbacks)
|
|
- startRequest before laneQueue.enqueue, endRequest in finally — tracks full queuing + execution time
|
|
- /health endpoint unauthenticated, placed before auth check for Docker HEALTHCHECK compatibility
|
|
|
|
### Technical Notes
|
|
- daemon/index.ts now 140 lines — thin composition root: imports → init calls → wire → return DaemonContext
|
|
- 8 extracted modules: models.ts (251), memory.ts (99), tools.ts (89), routing.ts (239), agents.ts (48), channels.ts (102), services.ts (269), lifecycle.ts (34)
|
|
- Factory pattern established for all modules: initX(deps) → result
|
|
- Tier 1 agent tools (session, agent list, message send, cron) remain in index.ts — they need deps from multiple init functions
|
|
- Web dashboard is vanilla JS SPA at src/gateway/ui/
|
|
- Config loader at src/config/loader.ts, schema at src/config/schema.ts (409 lines)
|
|
- deepMerge + overlay-aware loadConfig in loader.ts; resolveOverlayPath + overlay-aware loadConfigSafe in cli/shared.ts
|
|
- FLYNN_ENV maps to {configDir}/{env}.yaml sibling file; no env = no overlay (backward compatible)
|
|
- checkOverlayExists in doctor.ts: skip (no FLYNN_ENV) / pass (file found) / fail (file missing)
|
|
- MetricsCollector at src/gateway/metrics.ts: counters, model call ring buffer (200), event ring buffer (500), active request tracking
|
|
- 3 new RPC handlers: system.metrics (snapshot), system.events (filtered/limited), system.activeRequests (in-flight details)
|
|
- GET /health HTTP endpoint returns JSON status without auth (for monitoring/healthcheck)
|
|
|
|
### TODOs
|
|
_(none)_
|
|
|
|
### Blockers
|
|
_(none)_
|
|
|
|
## Session Continuity
|
|
|
|
**Last session:** Plan 03-01 (metrics collection backend) completed
|
|
**Stopped at:** Completed 03-01-PLAN.md — Phase 3 plan 1 of 2 done
|
|
**Next action:** Execute 03-02-PLAN.md (Dashboard UI)
|
|
|
|
---
|
|
*State initialized: 2026-02-09*
|
|
*Last updated: 2026-02-10T05:29Z*
|