Embedded library: theme Proxy throws "Theme not initialized" and initTheme() fails when PI_PACKAGE_DIR points at a shim

[wloonis]

Summary

When @earendil-works/pi-coding-agent is embedded as a library (not used through the TUI), code paths that touch the global theme throw

Theme not initialized. Call initTheme() first.

because initTheme() is only called by the TUI at startup, and the theme global is a throwing Proxy until then. Additionally, when a host does call initTheme(), theme file loading can fail because PI_PACKAGE_DIR may resolve to a shim directory that has no dist/modes/interactive/theme/.

Environment

• @earendil-works/pi-coding-agent 0.80.2
• Usage: embedded as a library with extensions enabled. The extension loader (and some shared code) reads theme, which is uninitialized in a non-TUI host.

Root cause

• dist/modes/interactive/theme/theme.js:601 — const THEME_KEY = Symbol.for("@earendil-works/pi-coding-agent:theme") is a global.
• dist/modes/interactive/theme/theme.js:609 — the global is a Proxy whose get trap throws "Theme not initialized. Call initTheme() first." until initTheme() runs.
• dist/modes/interactive/theme/theme.js:631 — initTheme(themeName, enableWatcher) calls loadTheme(), which reads theme JSON files from ${PI_PACKAGE_DIR}/dist/modes/interactive/theme/.
• The TUI calls initTheme() at startup. A library embedder that never touches the TUI still imports code paths that read theme (via the extension loader), and gets the throw.
• PI_PACKAGE_DIR resolution (ensurePiPackageDirShim) can land on a shim directory that only has a bare package.json and no dist/modes/interactive/theme/, so even calling initTheme() from a host fails to locate the theme files.

Reproduction

import { /* anything that pulls in the extension loader */ } from "@earendil-works/pi-coding-agent";
// create a session with extensions enabled; extension loading reads `theme`
// → throws "Theme not initialized. Call initTheme() first."

Proposal

• Make theme lazily resolve to a safe default / no-op when accessed outside the TUI (or auto-initialize on first access), so library embedders don't have to know about initTheme().
• Ensure initTheme() resolves the real package directory (not the shim) for theme file loading, so hosts that do call it succeed regardless of PI_PACKAGE_DIR pointing at a shim.

Workaround currently used by Archon (host side, not a real fix)

Archon's Pi provider temporarily repoints PI_PACKAGE_DIR to the real package directory (resolved via import.meta.resolve('@earendil-works/pi-coding-agent')) and calls initTheme(undefined, false) before creating sessions.

Happy to open a PR if there's interest.

[github-actions]

This issue was auto-closed. All issues from new contributors are auto-closed by default.

Maintainers review auto-closed issues daily and reopen worthwhile ones. Issues that do not meet the quality bar in CONTRIBUTING.md will not be reopened or receive a reply.

If a maintainer replies lgtmi on one of your issues, your future issues will stay open. If a maintainer replies lgtm, your future issues and PRs will stay open.

See CONTRIBUTING.md.

[wloonis]

Following up with a fix attempt (PR #6501 — auto-closed per the new-contributor policy; branch wloonis:fix/embedded-library-runtime-theme).

Repro:

import { theme } from "@earendil-works/pi-coding-agent/dist/modes/interactive/theme/theme.js";
theme.name; // throws "Theme not initialized. Call initTheme() first." in any non-TUI host

initTheme() is only called from TUI startup paths; library hosts never call it, so any shared code path that reads theme (e.g. the extension loader) throws.

Fix: lazily bootstrap the builtin dark theme on first theme access instead of throwing. An explicit initTheme() call still wins; if even the builtin can't load, the original error is preserved so misconfiguration stays visible. Regression test included.