flynn/.planning/STATE.md

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