docs(01-03): complete daemon composition root plan — Phase 1 done
- Created 01-03-SUMMARY.md with self-check passed - Updated STATE.md: Phase 1 complete, 3/3 plans done - Updated ROADMAP.md: Phase 1 marked complete - daemon/index.ts: 1087 → 140 lines (87% reduction) - All 1077 tests pass, zero type errors
This commit is contained in:
William Valentin
@@ -0,0 +1,124 @@
|
||||
---
|
||||
phase: 01-daemon-decomposition
|
||||
plan: 03
|
||||
subsystem: infra
|
||||
tags: [daemon, refactoring, composition-root, services-extraction, typescript]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 01-01
|
||||
provides: "models.ts, memory.ts, tools.ts extraction reducing daemon/index.ts to ~458 lines"
|
||||
- phase: 01-02
|
||||
provides: "routing.ts, agents.ts, channels.ts extraction reducing daemon/index.ts to ~385 lines"
|
||||
provides:
|
||||
- "src/daemon/services.ts — skills, MCP, system prompt, pairing manager, gateway server, service startup, signal handlers"
|
||||
- "src/daemon/index.ts as thin 140-line composition root — imports, wiring, lifecycle, DaemonContext"
|
||||
- "Phase 1 complete: daemon fully decomposed into 8 focused modules"
|
||||
affects: [02-config-overlays, 03-live-ops-dashboard]
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "Callback-based late binding: getChannelAgents() callback passed to gateway for deferred token usage reporting"
|
||||
- "Type-only imports for values only used in DaemonContext type definition"
|
||||
- "Section dividers with Unicode box-drawing comments for scannable composition root"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- src/daemon/services.ts
|
||||
modified:
|
||||
- src/daemon/index.ts
|
||||
|
||||
key-decisions:
|
||||
- "Grouped skills, MCP, pairing, gateway, system prompt, and service startup into one services.ts rather than multiple tiny modules — related service-init code stays together"
|
||||
- "Used getChannelAgents callback for late-binding channel agents into gateway token usage reporting"
|
||||
- "Converted ModelRouter, McpManager, SkillRegistry, SkillInstaller, GatewayServer to type-only imports in index.ts"
|
||||
|
||||
patterns-established:
|
||||
- "Composition root pattern: daemon/index.ts is pure wiring — import → init → connect → return"
|
||||
- "Services module groups service initialization that shares config/lifecycle dependencies"
|
||||
|
||||
# Metrics
|
||||
duration: ~8min
|
||||
completed: 2026-02-10
|
||||
---
|
||||
|
||||
# Phase 1 Plan 3: Daemon Composition Root Summary
|
||||
|
||||
**Extracted services/skills/MCP/gateway/lifecycle into services.ts (269 lines), achieving 140-line composition root — 87% reduction from 1087-line baseline**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** ~8 min (across two sessions)
|
||||
- **Started:** 2026-02-10T04:19:31Z
|
||||
- **Completed:** 2026-02-10T04:27:00Z
|
||||
- **Tasks:** 2
|
||||
- **Files modified:** 2 (1 created, 1 modified)
|
||||
|
||||
## Accomplishments
|
||||
- Extracted 6 functions into `src/daemon/services.ts`: initSkills(), initMcp(), loadSystemPrompt(), initPairingManager(), createGateway(), startServices()
|
||||
- Reduced daemon/index.ts from 385 lines (post-Plan 02) to 140 lines — well under the 200-line target
|
||||
- daemon/index.ts is now a pure composition root: imports → init calls → wire → return DaemonContext
|
||||
- All 1077 tests pass, zero type errors, zero regressions
|
||||
- Cumulative reduction: 1087 → 140 lines (87% reduction, 947 lines extracted)
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1: Extract services/skills/gateway/MCP into services.ts, clean up index.ts** — `701fcfc` (refactor)
|
||||
2. **Task 2: Final validation** — No separate commit (validation-only task, all changes in Task 1)
|
||||
|
||||
## Files Created/Modified
|
||||
- `src/daemon/services.ts` — Skills registry/installer, MCP server manager, system prompt assembly, pairing manager, gateway server creation, channel/gateway startup, Tailscale serve, heartbeat monitor, signal handlers (269 lines)
|
||||
- `src/daemon/index.ts` — Thin composition root with organized imports, section dividers, DaemonContext return (140 lines)
|
||||
|
||||
## Decisions Made
|
||||
- Grouped all remaining service initialization (skills, MCP, pairing, gateway, system prompt, lifecycle startup) into a single `services.ts` rather than multiple tiny modules — these all share config/lifecycle dependencies and are called sequentially
|
||||
- Used `getChannelAgents()` callback pattern to handle late-binding of channel agents into gateway's token usage reporting — avoids circular dependency between channel registration and gateway creation
|
||||
- Converted `ModelRouter`, `McpManager`, `SkillRegistry`, `SkillInstaller`, `GatewayServer` to type-only imports in index.ts since they're only referenced in the DaemonContext type definition (values come from factory functions in extracted modules)
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None — plan executed exactly as written. daemon/index.ts was 385 lines as expected, extraction targets matched plan analysis, final line count (140) comfortably under the 200-line target.
|
||||
|
||||
## Issues Encountered
|
||||
None.
|
||||
|
||||
## User Setup Required
|
||||
None — no external service configuration required.
|
||||
|
||||
## Next Phase Readiness
|
||||
- **Phase 1 complete:** daemon/index.ts is a 140-line composition root
|
||||
- 8 daemon modules total: models.ts (251), memory.ts (99), tools.ts (89), routing.ts (239), agents.ts (48), channels.ts (102), services.ts (269), lifecycle.ts (34) — 1131 lines of extracted logic
|
||||
- All modules use consistent factory pattern with typed deps/result interfaces
|
||||
- Phase 2 (Config Overlays) can proceed — config loading changes are low-risk since daemon wiring is now modular
|
||||
- Phase 3 (Live Ops Dashboard) can proceed — metrics hooks can be wired into individual modules rather than the monolithic god file
|
||||
|
||||
## Module Summary (Final State)
|
||||
|
||||
| Module | Lines | Responsibility |
|
||||
|--------|-------|---------------|
|
||||
| index.ts | 140 | Composition root — imports, wiring, DaemonContext |
|
||||
| models.ts | 251 | Model client factory, GitHub mapping, auto-fallback, model router |
|
||||
| services.ts | 269 | Skills, MCP, system prompt, pairing, gateway, service startup |
|
||||
| routing.ts | 239 | Message router, agent cache, sandbox wiring, audio |
|
||||
| channels.ts | 102 | All channel adapter registration (8 adapters) |
|
||||
| memory.ts | 99 | Memory store, vector store, hybrid search, indexer |
|
||||
| tools.ts | 89 | Tool registry, builtin tools, web search, process/browser managers |
|
||||
| agents.ts | 48 | Agent config registry, agent router, sandbox manager |
|
||||
| lifecycle.ts | 34 | Lifecycle state management |
|
||||
| **Total** | **1271** | **Full daemon initialization** |
|
||||
|
||||
---
|
||||
*Phase: 01-daemon-decomposition*
|
||||
*Completed: 2026-02-10*
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- All 2 files verified present (services.ts, index.ts)
|
||||
- Task 1 commit verified (701fcfc)
|
||||
- Line counts match: index.ts=140, services.ts=269
|
||||
- Typecheck: clean
|
||||
- Tests: 1077/1077 passed
|
||||
Reference in New Issue
Block a user