packages/docs/roadmap.md
Direction and rationale for Eliza on elizaOS. Not exhaustive; see the Changelog for shipped changes with WHYs.
Goal: Beat the felt cost of always-on dev shells on laptop battery while staying more visually distinctive than a flat editor surface—better UX and DX, not a spec-sheet stunt.
powermetrics, Instruments). Our bar is excellent experience per watt for a local AI companion, not claiming victory in every head-to-head against a full IDE.VrmViewer visibility pause; desktop:getPowerState → VrmEngine.setLowPowerRenderMode; visibility-gated intervals (dashboard, stream, game logs, fine-tuning, cloud credits); vector 3D graph rAF pause when hidden; dev hooks opt-out so DX tooling does not accidentally burn watts (screenshot proxy, aggregated console).prefers-reduced-motion, optional idle frame cap for the avatar when motion fidelity matters less than battery, and clearer in-app copy when battery savings are active (so users trust the tradeoff).generateChatResponse, LLM onStreamChunk still appends token deltas; HandlerCallback text from actions uses replaceCallbackText: first callback freezes preCallbackText (streamed model output), each subsequent callback replaces only the suffix after that baseline via emitSnapshot / onSnapshot. Why: Matches Discord/Telegram progressive message UX (edit one bubble) without changing the elizaOS callback contract or adding a parallel WebSocket protocol. Docs: docs/runtime/action-callback-streaming.md, docs/changelog.mdx (2026-04-05). Code: packages/agent/src/api/chat-routes.ts.collectPluginNames() records the first reason each plugin entered the load set (plugins.allow, env auto-enable, features, etc.); resolvePlugins() includes (added by: …) when optional plugins fail to install so operators fix config/env instead of chasing phantom runtime bugs. Stagehand: findPluginBrowserStagehandDir() walks parents from the runtime file to find plugins/plugin-browser/stagehand-server — why fixed ../ depth failed for eliza/ submodule layouts. Docs: docs/plugin-resolution-and-node-path.md (optional plugins section), docs/guides/developer-diagnostics-and-workspace.md.CREATE INDEX statements run after ownership ALTER TABLE / column backfills so legacy DBs without domain / subject_* do not fail upgrades; runMigrationWithSavepoint uses explicit BEGIN/COMMIT so SAVEPOINT is valid under PGlite. Why: real databases hit migration errors during life-ops schema evolution. Tests: packages/agent/test/lifeops-pglite-schema.test.ts.fix-workspace-deps.mjs, replace-workspace-versions.mjs, restore-workspace-refs.mjs, workspace-prepare.mjs, and workspace-discovery.mjs reduce manual workspace surgery; root package.json exposes workspace:* / fix-deps aliases. Why: local ./eliza and plugins/* checkouts drift workspace:* and semver edges frequently. Docs: docs/guides/developer-diagnostics-and-workspace.md.NO_COLOR / FORCE_COLOR respected). Why: four-process desktop dev needs scannable effective env for humans/agents — not product UI. Docs: docs/apps/desktop-local-development.md, docs/guides/developer-diagnostics-and-workspace.md.cache/audio/, scripts/bin/* — Keeps large local media caches and optional binaries (e.g. yt-dlp) out of git; scripts/bin/.gitkeep preserves directory for PATH. Why: clones should not inherit multi-hundred-MB artifacts.three for Spark + VRM — apps/app/vite.config.ts sparkPatchPlugin (resolveId + splatDefines hoist) and optimizeDeps.include for three + three/examples/jsm/* so @sparkjsdev/spark and the avatar stack share one THREE.ShaderChunk. Why: nested three (e.g. under Electrobun) caused splatDefines resolution failures and “multiple Three.js instances” warnings; resolve.alias alone broke Rollup prod. Docs: docs/apps/desktop-vrm-three-and-spark.md, docs/changelog.mdx.eliza-1 fallback instead of missing default assets, Spark/world failures isolated so VRM still loads. Why: bundled module-init timing and optional splat backgrounds must not brick the companion avatar. Code: VrmViewer.tsx, VrmEngine.ts, state/vrm.ts.cloud-routes.ts uses cloudDisconnectEpoch (increment on disconnect, snapshot before poll) instead of cloud.enabled === false to skip persist. Why: the old guard blocked first login when cloud had never been enabled. Docs: docs/apps/desktop-vrm-three-and-spark.md (API section).alpha.12 — Root package.json pins @elizaos/plugin-openrouter to an exact known-good version (currently 2.0.0-alpha.13). Why: 2.0.0-alpha.12 published truncated dist/node and dist/browser ESM files: only utils/config is bundled, but exports still reference openrouterPlugin / default — Bun fails at load (symbol not declared). Why not patch dist in postinstall: the plugin implementation chunk is absent, not a one-line export typo; pinning is the correct mitigation until upstream republishes. Docs: docs/plugin-resolution-and-node-path.md (section Pinned: @elizaos/plugin-openrouter), docs/plugin-registry/llm/openrouter.md, docs/changelog.mdx, README.md. Code note: scripts/patch-deps.mjs (comment block next to other upstream workarounds).dev:desktop / dev:desktop:watch pre-allocate free loopback ports for ELIZA_API_PORT and ELIZA_PORT (Vite) before spawning API, Vite, and Electrobun so env, proxy, and renderer URL stay aligned. Embedded agent: Electrobun picks the next free port from the preferred ELIZA_PORT instead of default lsof + SIGKILL; optional ELIZA_AGENT_RECLAIM_STALE_PORT=1 restores reclaim. Runtime: eliza.ts / dev-server.ts sync process.env to the API’s actual bind port where safe. UI: injectApiBase on agent status for main + all surface windows. Why: two Eliza stacks or stray processes should not require manual port hunting or killing unrelated processes; dynamic binds must propagate to renderer and dev tooling. Docs: docs/apps/desktop-local-development.md, docs/apps/desktop.md (port sections). Code: scripts/lib/allocate-loopback-port.mjs, apps/app/electrobun/src/native/loopback-port.ts, agent.ts, index.ts, surface-windows.ts, vite.config.ts, dev-server.ts, eliza.ts.GET /api/dev/stack, desktop:stack-status, default-on screenshot proxy (/api/dev/cursor-screenshot, loopback + token), default-on aggregated console (.eliza/desktop-dev-console.log + /api/dev/console-log tail with basename allow-list). Why: multi-process dev is opaque to tools that cannot see the native window; explicit HTTP + file hooks avoid guessing ports and keep loopback/tokens bounded. Opt-out env vars documented. Docs: docs/apps/desktop-local-development.md (section IDE and agent observability). Rules: .cursor/rules/eliza-desktop-dev-observability.mdc.getMacOSMajorVersion() uses Darwin − 9 for 20–24 (macOS 11–15) and Darwin + 1 for ≥ 25 (macOS 26+ Tahoe). Why: os.release() is Darwin; Tahoe is macOS 26 on Darwin 25—the old single formula reported 16 and broke WKWebView WebGPU messaging and gating. Docs: docs/apps/electrobun-darwin-macos-webgpu-version.md. Tests: webgpu-browser-support.test.ts.menu-reset-eliza-applied and shared completeResetLocalStateAfterServerWipe. Why: WKWebView deferred renderer networking after native dialogs; users saw “nothing happens” after confirm. Reachable-base probe uses res.ok only. Docs: docs/apps/desktop-main-process-reset.md. Tests: menu-reset-from-main.test.ts, reset-main-process.test.ts.ELIZA_DISABLE_EDGE_TTS (registry + docs/cli/environment.md + TTS doc). Why: orchestrator auto-loads Edge TTS → node-edge-tts → Microsoft; “no API key” is not “offline.”packages/app-core/test/**/*.test.ts(x) and src/**/*.test.tsx; excludes app-core e2e under test/ from the default unit job. Why: new tests under test/state and test/runtime were skipped; a single hard-coded TSX path was brittle.actions/setup-node@v4 with check-latest: false everywhere; add Bun global cache and timeout-minutes to test, release, nightly, benchmark-tests, publish-npm. Why: avoid nodejs.org downloads and bounded job durations. See docs/build-and-release.md "Node.js and Bun in CI: WHYs".bash -euo pipefail) for fail-fast steps; retry loops for bun install with a final run so the step fails if all retries failed; crash dump uses the maintained ASAR CLI; find -print0 / while IFS= read -r -d '' for safe paths; DMG path via find+stat; node-gyp artifact removal before pack; size report includes eliza-dist; single Capacitor build step; packaged DMG E2E uses 240s CDP timeout in CI and dumps stdout/stderr on timeout. Why: Reproducible builds, clear failures, and debuggable CI; see docs/build-and-release.md "Release workflow: design and WHYs".NODE_PATH in three places so dynamic import("@elizaos/plugin-*") resolves from CLI (run-node.mjs child), direct eliza load (eliza.ts on load), and Electrobun (dev: walk up to find node_modules; packaged: ASAR node_modules). Why: Node does not search repo root when the entry is under dist/ or cwd is a subdir; without this, "Cannot find module" broke coding-agent and others. See docs/plugin-resolution-and-node-path.md.arch -x86_64 for the macos-x64 artifact so native .node binaries are x64. Why: CI runs on arm64; without Rosetta we shipped arm64 binaries and Intel users got "Cannot find module .../darwin/x64/...".copy-electrobun-plugins-and-deps.mjs walks each @elizaos package's package.json dependencies instead of a curated list. Why: Curated lists missed new plugin deps and caused silent failures in packaged app; auto-walk stays correct as plugins change.NODE_PATH set to repo root node_modules in eliza.ts, run-node.mjs, and agent.ts (Electrobun dev). Why: Dynamic import("@elizaos/plugin-*") from bundled eliza.js couldn't resolve packages at root; NODE_PATH tells Node where to look. No-op in packaged app (existsSync guard). See docs/plugin-resolution-and-node-path.md.patch-deps.mjs rewrites affected @elizaos plugins (and any similar package) so exports["."] no longer has "bun": "./src/index.ts" when that file doesn't exist. Why: The published tarball only ships dist/; Bun picks the "bun" condition first and fails. Removing the dead condition lets Bun use "import" → ./dist/index.js. See "Bun and published package exports" in docs/plugin-resolution-and-node-path.md.du | sort | head pipelines in the "Report packaged app size" step run in a subshell with || r=$? and allow exit 141; sort stderr silenced. Why: Under -euo pipefail, 141 would exit the step before we could allow it; subshell captures it. See docs/build-and-release.md./api/nfa/status and /api/nfa/learnings lazy-load @elizaos/plugin-bnb-identity and fall back when missing. Why: Core and tests work without the plugin; ambient type declaration keeps typecheck happy.@elizaos/plugin-openrouter publishes a release after alpha.12 with verified full dist/node/index.node.js (and browser) bundles, relax the exact pin. Currently pinned to alpha.13. Why: Staying on a hard pin forever misses real fixes; we only avoid broken tarballs until npm has a good artifact.@elizaos/plugin-discord) list typescript in dependencies instead of devDependencies; we skip it via DEP_SKIP to avoid bundle bloat. Why: Fixing upstream would reduce our skip list and keep plugin package.json correct.lipo or desktop packaging targets but adds build time and complexity; separate DMGs are acceptable for now.