99 lines · 5.7 KB · Markdown
RawDownload

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 through runtime-targets.ts, mlx uses getEngineSpec) onto one consistent getEngineSpec(backend).X pattern. Keep runtime-targets.ts only for the multi-source discovery UI (/runtime/targets*). Also fold the five near-identical /runtime/*/upgrade handlers into one parameterized registration. Blast radius: frontend lib/api/studio.ts types vllm_bin/bundled_wheel from /runtime/vllm — unifying the shape needs that one frontend consumer updated too.
  • Step 7: Convert engine-coordinator.ts to Effect v4 LAST — largest state machine, most callers, highest risk (abort/lock/lifecycle-intent logic is only integration-tested end-to-end). Diff carefully against runtime-recipe-contracts.test.ts + stream-proxy-contracts.test.ts before/after. Note: the dead ensureActive/searchHuggingFace layer 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/fetch outside Next.js route handlers (those stay Promise-based per Next's contract); convert internal business logic to Effect.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-driven LlamacppOption-style table + EngineOptionsSection renderer.
  • cli/CLI_REFERENCE.md controller-API snapshot cut; points at the live /docs swagger (2026-07-01).
  • docker-compose.yml provisions a foreign postgres for litellm — left in place deliberately: deploy-remote.sh rsyncs 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) from frontend/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.ts module 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/venvs path above the managed venv — demote it.
  • createEngineJob remaps cuda/rocm jobs to backend: "vllm" — add "cuda"/"rocm" to EngineJob["backend"] instead.

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t