callstack / callstack/agent-device
refactor(daemon): extract the maestro adapter and durable-capture admission subtrees
- Dominant language
- TypeScript
- Stars
- 4.6k
- Forks
- 299
- Avg merge
- 10h 14m
- Merged PRs (30d)
- 537
Description
## Purpose
Two daemon subtrees are package-shaped by everything except one daemon-internal type.
- **`src/daemon/adapters/**`** — 12 files, 2,250 LOC. Its only inbound dependencies are `daemon-request.ts` (x2) and `touch-reference-frame.ts`. Its only inbound consumers are 2 files under `src/daemon/replay/internal/`. It is the Maestro daemon-side runtime port, and `packages/maestro` already exists.
- **The durable-capture admission family** — `durable-*`, `perf-*`, `audio-*`, `screen-*` admission/recovery modules, 18 files, ~1,038 LOC. Every one of them shares the **same three** dependencies: `durable-capture-admission-ledger.ts`, `durable-capture-runtime-recovery.ts`, `durable-capture-resource.ts`. #2317 already moved durable-capture resource mechanics into `capture-kit`; this is the daemon-side admission residue of the same design.
Both currently reach `src/daemon/daemon-request.ts`, and packages may not import `src/**` — so the real unit of work is the cut set, not the file list.
Umbrella: #2545.
## Required behavior
1. Measure the minimal cut set per subtree first: the smallest set of declarations that, once moved, leaves the subtree with no `src/**` import. Direct-dep counts alone hide it — `managed-device-allocation/` reaches `session-teardown-budget.ts`, and the family's three shared deps may reach the `session-*` cluster (24 files, 138 inbound files, the daemon's hotspot).
2. Move the declarations each subtree needs to the layer both sides sit on. If that layer turns out to be a session-spine type that no package should own, **stop and report it** rather than widening a package's surface to fit.
3. Then move the subtrees: `adapters/**` into `packages/maestro`, the admission family into `packages/capture-kit`. Pure moves carry their tests unchanged; the moved module's test file moves with it, mirroring source topology.
4. No compatibility re-export at the old path (`no-internal-package-reexports`); every consumer switches to the owning specifier.
5. Check the ADR 0022 classification before moving anything that the audit called daemon-policy-essential. Relocating policy into a package re-leaks it; `resource-cleanup` is the precedent for reclassification being an explicit, recorded act.
## Completion conditions
- `src/daemon/adapters/**` no longer exists; `packages/maestro` owns the daemon-side port and imports nothing under `src/**`.
- The admission family lives in `packages/capture-kit` with the same observable admission/recovery behavior, characterized before the move.
- `src/daemon` production file count and LOC both drop by the moved totals, reported in the PR.
- Daemon eager-closure budgets do not rise; #2469's tolerance question is respected, not worked around.
- R4/R5 stay 0, R6 unchanged or lower.
## Out of scope
- Artifact/HTTP transfer modules (~12 files, ~2,100 LOC) and the generic command handlers (`keyboard`/`gesture`/`focus`/`back`/`home`/`orientation`/`tv`/`viewport`/`scroll`, ~10 files, ~2,300 LOC). Both are worth a directory inside the daemon and explicitly **not** a package: the first was ruled a logical module in #2335, and the second shares four daemon-private seams (`context`, `request-generic-dispatch`, `runtime-admission`, `snapshot-runtime-capture-input`) that no package should acquire.
- `managed-device-allocation/` → `packages/managed-allocation`. File separately if the cut set comes out as small as it looks (3 files, 341 LOC, one root dep `src/managed-device-reachability.ts` which itself has 0 src deps).
## Dependencies
- **Blocked on deciding where `daemon-request.ts` lives** (contract-level vs daemon-private). That semantics is unresolved, so this issue is not implementation-ready: resolve it here or in the parent before scheduling.
- Wave B. Independent of the `cli-schema` orientation child.
Contributor guide
Research direction
Start by resolving where src/daemon/daemon-request.ts belongs, then measure the minimal dependency cut sets for src/daemon/adapters/** and the durable-/perf-/audio-/screen-* admission modules. Check ADR 0022 and characterize existing admission/recovery behavior before moving tests with their source topology. Done means the subtrees are owned by packages/maestro and packages/capture-kit, consumers use owning specifiers, and the stated closure, LOC, and R4/R5/R6 budgets hold.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- developer-experience, tooling
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100