Engine system refactor + repo cleanup — live checklist
Autonomous, multi-session initiative (30-min cron loop, unattended). Read this
file first at the start of every iteration; update it before ending each
iteration. Never leave the repo broken — all local gates (npm run check:quality in frontend/, bun run typecheck + bun run test:integration in controller/) must pass before an iteration ends.
Completed work: the full iteration log (iters 1-23) is archived at
docs/archive/engine-refactor-iterations.md. Part A (/environments page) is
complete end-to-end. Part B steps 1-3, 5, 6 done. Everything below is what
remains.
Part B — engine system simplification (remaining)
- Step 4: Unify
routes.ts's backend-info access patterns (vllm goes direct to runtime files, sglang/llamacpp go throughruntime-targets.ts, mlx usesgetEngineSpec) onto one consistentgetEngineSpec(backend).Xpattern. Keepruntime-targets.tsonly for the multi-source discovery UI (/runtime/targets*). Also fold the five near-identical/runtime/*/upgradehandlers into one parameterized registration. Blast radius: frontendlib/api/studio.tstypesvllm_bin/bundled_wheelfrom/runtime/vllm— unifying the shape needs that one frontend consumer updated too. - Step 7: Convert
engine-coordinator.tsto Effect v4 LAST — largest state machine, most callers, highest risk (abort/lock/lifecycle-intent logic is only integration-tested end-to-end). Diff carefully againstruntime-recipe-contracts.test.ts+stream-proxy-contracts.test.tsbefore/after. Note: the deadensureActive/searchHuggingFacelayer and the line-packed formatting were already removed (2026-07-01); the file is now 304 formatted lines.
Part C — repo-wide sweep checklist (remaining)
- File size (no source file > 500 lines, tests exempt):
-
frontend/src/features/agent/runtime/session-runtime-controller.ts(709) — deferred: one cohesive closure, THE ordering authority, pinned by regression tests. Only touch in a dedicated pass. -
frontend/src/features/agent/runtime/pi-event-applier.ts(529) -
frontend/src/features/agent/ui/git-diff-panel.tsx(525) -
frontend/src/features/recipes/recipes-content/explore-tab-sections.tsx(518) -
controller/src/modules/engines/runtimes/runtime-targets.ts(516) — see Part B step 4 -
frontend/src/features/shell/left-sidebar.tsx(511) -
frontend/src/features/agent/ui/agent-browser-panel.tsx(503) -
frontend/src/features/agent/pi-runtime.ts(501)
-
- Effect-v4 coverage: audit raw
async/Promise/fetchoutside Next.js route handlers (those stay Promise-based per Next's contract); convert internal business logic toEffect.gen/Effect.tryPromise. Needs its own inventory pass. - React container/presentational conventions: not audited yet.
- Comments: sweep narrative/restating comments; keep regression why-comments.
Part D — cleanup backlog (from the 2026-07-01 full-repo audit)
Completed 2026-07-01 (waves 1-2): chat-pane satellite re-fold;
recipe-modal tab-content prop grouping + recipes-content model props;
engine-args single-sourcing (VLLM_ONLY_FLAG_KEYS / KNOWN_VLLM_EXTRA_ARG_KEYS /
EXTRA_ARG_FIELDS derived from one shared table); GPU contract unified on
*_mb/utilization_pct/temp_c with one normalizeGpuAliases frontend
shim; canvas/plan stores on createSessionScopedJsonStore;
skill-discovery/prompt-templates on discovery-core; vision flag threaded
into browserContextPrompt; ActiveSession derived via Pick;
runtime wire types schema-derived (no casts); isRecord single-sourced in
src/lib/guards; projects-nav barrel dropped; ui-kit single-consumer
components moved into features + model-card fetch hook extracted;
environments page in the feature layer; use-realtime-status wrapper and
dead test-seam exports deleted; engine-capabilities spread; store.ts
listeners behind initAppStoreListeners(); usage payloads typed end-to-end
and SortField/SortDirection moved into the usage feature.
Remaining:
- vLLM/SGLang recipe tabs hand-write JSX per field with parser catalogs
trapped in JSX (
tab-features.tsx) — move onto the data-drivenLlamacppOption-style table +EngineOptionsSectionrenderer. -
cli/CLI_REFERENCE.mdcontroller-API snapshot cut; points at the live/docsswagger (2026-07-01). -
docker-compose.ymlprovisions a foreign postgres for litellm — left in place deliberately:deploy-remote.shrsyncs it by path and the remote host runs it live; move only with a coordinated deploy change. - Desktop artifact versioning: electron-builder stamps artifacts and the
self-hosted update feed (
LOCAL_STUDIO_UPDATE_URL+ latest.yml) fromfrontend/package.json(0.2.9), while semantic-release tags an unrelated v1.57.x stream from commits. Two version streams that never meet — align them (bump frontend version in the desktop:dist flow from the latest tag, or add a release step that PRs the version bump). Until then the package.json versions must NOT be hand-edited: the update feed compares against them.
Open issues
engine-spec.ts→specs/*→backend-builder.ts→engine-spec.tsmodule cycle survives only because lookup defers to call time — move the arg/docker helpers the specs need into a leaf module.DEFAULT_CANONICAL_PYTHON_PATH(configs.ts) ranks a machine-specific/opt/venvspath above the managed venv — demote it.createEngineJobremaps cuda/rocm jobs tobackend: "vllm"— add "cuda"/"rocm" toEngineJob["backend"]instead.