code-puppy-core-plugins 0.0.104__tar.gz → 0.0.105__tar.gz

{code_puppy_core_plugins-0.0.104 → code_puppy_core_plugins-0.0.105}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code-puppy-core-plugins
-Version: 0.0.104
+Version: 0.0.105
 Summary: Official plugin bundle for Code Puppy
 Project-URL: Repository, https://github.com/mpfaffenberger/code_puppy_core_plugins
 Project-URL: Homepage, https://github.com/mpfaffenberger/code_puppy_core_plugins

{code_puppy_core_plugins-0.0.104 → code_puppy_core_plugins-0.0.105}/code_puppy_core_plugins/acp/README.md

@@ -130,6 +130,7 @@ Every file stays well under the 600-line cap and owns one concern.
 | `bridge.py` | `EventBridge`: registers `stream_event` / `pre_tool_call` / `post_tool_call` hooks and translates them into SDK `session/update`s via `connection.session_update`. (Hooks, **not** MessageBus — see *Event source*.) |
 | `permissions.py` | Wires Code Puppy's two approval edges to the client via the SDK's `request_permission`: the `tools.common` approval backend (files, cross-thread) and the `run_shell_command` hook (shell). Fails closed. |
 | `io_delegation.py` | `DelegatedFileSystemBackend` (sync, cross-thread) + `DelegatedCommandExecutor` (async terminal lifecycle) that plug into the core I/O seams, capability-gated. |
+| `themes.py` | Read-only theme catalog: the `_code_puppy/themes/list` ext method, the `codePuppy/theme` session `_meta`, and the `_code_puppy/themes/changed` poll (`ThemeWatcher`). |
 | `state.py` | Process-wide run context: the SDK connection + its loop, the active session id, and the open-tool-call stack — so the permission/I/O seams (plain module functions) can reach the running connection and correlate events. |
 
 ```
@@ -319,6 +320,73 @@ change.
 
 ---
 
+## Theme catalog (`_code_puppy/themes/*`)
+
+You can list Code Puppy's color themes and track the active one without reading
+its config. The catalog is read-only: there is no setter.
+
+### `_code_puppy/themes/list`
+
+Send this request before or after `session/new`. It needs no session. Send
+`{}` or omit `params`; extra keys are ignored.
+
+The result has this shape:
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "active": "ocean",          // or null
+  "themes": [
+    {
+      "id": "ocean",
+      "label": "Ocean",
+      "icon": "...",
+      "blurb": "...",
+      "appearance": "dark",   // "dark" or "light"
+      "palette": { "bg": "#rrggbb", "fg": "#rrggbb", "ansi": ["#rrggbb", "...16 entries"] },
+      "roles": { "background": "#rrggbb", "surface": "#rrggbb", "text": "#rrggbb",
+                 "mutedText": "#rrggbb", "accent": "#rrggbb", "success": "#rrggbb",
+                 "error": "#rrggbb", "warning": "#rrggbb", "running": "#rrggbb",
+                 "diffAdd": "#rrggbb", "diffRemove": "#rrggbb" }
+    }
+    // ...more themes
+  ]
+}
+```
+
+Themes appear in this order: curated themes in menu order, then `default`. The `surprise`
+theme is excluded. The `default` entry has `null` for `appearance`, `palette`,
+and `roles`, because it restores the terminal's own colors.
+
+`active` is the ID of the catalog theme stored in the `theme_active_theme`
+config key. It is `null` when the key is unset, and also when the key holds
+`legacy-custom` or `surprise`.
+
+For the mapping from palette to roles, see
+[`theme/README.md`](../theme/README.md). This page does not repeat it.
+
+### `_meta` on session responses
+
+`session/new`, `session/load`, and `session/resume` results include
+`_meta["codePuppy/theme"] = {"active": <id or null>}`. Use it to paint the first
+frame without waiting for the list request.
+
+### `_code_puppy/themes/changed`
+
+When the active theme changes, the agent sends this notification with params
+`{"active": <id or null>}`. It sends one notification per change. The agent
+reads the config value every 2 seconds from the moment the client connects.
+The first reading is a baseline, so no notification is sent for it.
+
+### Unknown methods and older CLIs
+
+Any other `_code_puppy/*` method, such as `_code_puppy/themes/set`, returns
+JSON-RPC error `-32601` (method not found). Older Code Puppy CLIs omit the
+`_meta` key and return `-32601` for the list request. Clients should fall back
+to a bundled copy of the catalog when either happens.
+
+---
+
 ## Testing
 
 `tests/test_acp_plugin.py` drives `CodePuppyAgent` directly against a fake SDK

{code_puppy_core_plugins-0.0.104 → code_puppy_core_plugins-0.0.105}/code_puppy_core_plugins/acp/agent.py

@@ -49,6 +49,7 @@ from code_puppy_core_plugins.acp import (
     replay,
     session_config,
     state,
+    themes,
 )
 from code_puppy_core_plugins.acp.bridge import EventBridge
 from code_puppy_core_plugins.acp.session import ACPSession
@@ -77,6 +78,7 @@ class CodePuppyAgent(Agent):
         self._sessions: Dict[str, ACPSession] = {}
         self._bridge = EventBridge()
         self._client_caps: Optional[ClientCapabilities] = None
+        self._theme_watcher = themes.ThemeWatcher()
 
     # ---- Connection lifecycle ---------------------------------------------
     def on_connect(self, conn: Any) -> None:
@@ -89,6 +91,11 @@ class CodePuppyAgent(Agent):
         state.set_connection(conn, asyncio.get_running_loop())
         self._bridge.register()
         permissions.install()
+        try:
+            self._theme_watcher.start()
+        except Exception as error:  # noqa: BLE001
+            # Startup must never fail on the theme watcher; log the class only.
+            logger.debug("ACP theme watcher not started: %s", type(error).__name__)
 
     def shutdown(self) -> None:
         """Unwire this agent's event hooks. Call once the connection ends.
@@ -98,6 +105,7 @@ class CodePuppyAgent(Agent):
         connection leaves the global callback registry clean.
         """
         self._bridge.unregister()
+        self._theme_watcher.stop()
 
     # ---- Handshake --------------------------------------------------------
     async def initialize(
@@ -159,6 +167,7 @@ class CodePuppyAgent(Agent):
         return NewSessionResponse(
             session_id=session_id,
             config_options=session_config.config_options() or None,
+            field_meta=themes.session_meta(),
         )
 
     async def load_session(
@@ -185,6 +194,7 @@ class CodePuppyAgent(Agent):
         self._announce_commands_soon(session_id)
         return LoadSessionResponse(
             config_options=session_config.config_options() or None,
+            field_meta=themes.session_meta(),
         )
 
     async def resume_session(
@@ -205,6 +215,7 @@ class CodePuppyAgent(Agent):
         self._announce_commands_soon(session_id)
         return ResumeSessionResponse(
             config_options=session_config.config_options() or None,
+            field_meta=themes.session_meta(),
         )
 
     async def fork_session(
@@ -373,6 +384,10 @@ class CodePuppyAgent(Agent):
         reset_model_fallback_warnings(scope=session_id)
         return CloseSessionResponse()
 
+    async def ext_method(self, method: str, params: dict[str, Any]) -> dict[str, Any]:
+        """Route ext requests (currently only themes) to the theme catalog."""
+        return await themes.handle_ext_method(method, params)
+
     # ---- Prompt turn ------------------------------------------------------
     async def prompt(
         self, prompt: List[Any], session_id: str, **kwargs: Any

code_puppy_core_plugins-0.0.105/code_puppy_core_plugins/acp/themes.py

@@ -0,0 +1,99 @@
+"""ACP theme catalog: the ``code_puppy/themes/list`` ext method, session meta, and change pushes.
+
+Read-only by design: the client lists themes and reads the active one; there is no setter.
+
+Depends on: catalog.py :: build_catalog(), read_active_theme_id(), SCHEMA_VERSION
+Depends on: state.py :: get_connection()
+Called by: agent.py :: CodePuppyAgent.ext_method(), new_session(), load_session(), resume_session(), on_connect(), shutdown()
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, Optional
+
+from acp import RequestError
+
+from code_puppy_core_plugins.acp import state
+from code_puppy_core_plugins.theme.catalog import (
+    SCHEMA_VERSION,
+    build_catalog,
+    read_active_theme_id,
+)
+
+logger = logging.getLogger(__name__)
+
+EXT_LIST = "code_puppy/themes/list"
+EXT_CHANGED = "code_puppy/themes/changed"
+META_KEY = "codePuppy/theme"
+POLL_SECONDS = 2.0
+
+# Distinct from None: None is a valid "no active theme" observation.
+_NO_BASELINE: Any = object()
+
+
+async def handle_ext_method(method: str, params: Any) -> dict[str, Any]:
+    """Serve the theme list; any other ext method is not found."""
+    if method != EXT_LIST:
+        # The wire name carries the SDK's leading underscore; the error reports it.
+        raise RequestError.method_not_found("_" + method)
+    return {
+        "schemaVersion": SCHEMA_VERSION,
+        "active": read_active_theme_id(),
+        "themes": build_catalog(),
+    }
+
+
+def session_meta() -> dict[str, Any]:
+    """Return the active theme as ACP ``_meta`` for session responses."""
+    return {META_KEY: {"active": read_active_theme_id()}}
+
+
+class ThemeWatcher:
+    """Polls the active theme and pushes a notification when it changes.
+
+    The first observation is the baseline and sends nothing, so a client that
+    has not yet read the list is never told about a theme it did not ask about.
+    """
+
+    def __init__(self, poll_seconds: float = POLL_SECONDS) -> None:
+        self._poll_seconds = poll_seconds
+        self._task: Optional[asyncio.Task[None]] = None
+        self._last: Any = _NO_BASELINE
+
+    def start(self) -> None:
+        """Start the poll loop on the running event loop; no-op if already running."""
+        if self._task is not None and not self._task.done():
+            return
+        self._task = asyncio.get_running_loop().create_task(self._run())
+
+    def stop(self) -> None:
+        """Cancel the poll loop; safe when never started or already stopped."""
+        if self._task is not None:
+            self._task.cancel()
+            self._task = None
+
+    async def poll_once(self) -> None:
+        """Read the active theme and notify the client if it changed since last poll."""
+        # Broad catches are deliberate: a theme failure must never kill the poll loop.
+        try:
+            value = await asyncio.to_thread(read_active_theme_id)
+        except Exception as error:
+            logger.debug("ACP theme poll failed: %s", type(error).__name__)
+            return
+        previous, self._last = self._last, value
+        if previous is _NO_BASELINE or previous == value:
+            return
+        connection = state.get_connection()
+        if connection is None:
+            return
+        try:
+            await connection.ext_notification(EXT_CHANGED, {"active": value})
+        except Exception as error:
+            logger.debug("ACP theme notify failed: %s", type(error).__name__)
+
+    async def _run(self) -> None:
+        while True:
+            await self.poll_once()
+            await asyncio.sleep(self._poll_seconds)

{code_puppy_core_plugins-0.0.104 → code_puppy_core_plugins-0.0.105}/code_puppy_core_plugins/theme/README.md

@@ -73,6 +73,7 @@ Green Screen ports the canonical phosphor colors from [vybestack/llxprt-code](ht
 | `osc_palette.py` | OSC escape sequences for terminal-wide bg/fg/ANSI palette (Level 3) |
 | `picker.py` | prompt_toolkit split-panel TUI with live preview |
 | `register_callbacks.py` | `/theme` command handler, glue only |
+| `catalog.py` | Pure, read-only catalog for ACP clients (wire dicts, semantic roles, active-theme read) |
 | `__init__.py` | Re-applies persisted (L1 + L2 + L3) on plugin load |
 
 ## How each level works (the spicy bits)
@@ -84,3 +85,38 @@ Green Screen ports the canonical phosphor colors from [vybestack/llxprt-code](ht
 **Level 3** — fires xterm OSC sequences (`\\033]10;#fg\\007`, `\\033]11;#bg\\007`, `\\033]4;N;#hex\\007`) which modern terminals honor terminal-wide. Auto-resets on exit via `atexit`. Persists across restarts via JSON in `puppy.cfg`. Supported in iTerm2, Terminal.app, Alacritty, kitty, ode, GNOME Terminal, Windows Terminal. Unsupported terminals silently ignore.
 
 Plays nice with `/colors` — same color pool, same config keys for banners.
+
+## Theme catalog
+
+`catalog.py` is a pure, read-only catalog for ACP clients. It never applies a
+palette, emits OSC sequences, or writes config. Its only config access is the
+read in `read_active_theme_id()`.
+
+| Function | Purpose |
+|----------|---------|
+| `build_catalog()` | Returns fresh wire dicts: curated themes in menu order, then `default`. `surprise` is excluded. |
+| `semantic_roles(palette)` | Maps a `bg`/`fg`/`ansi` palette to the semantic roles below. |
+| `appearance_for(bg_hex)` | Returns `dark` when the WCAG relative luminance of `bg` is below 0.179, else `light`. |
+| `active_theme_id(raw)` | Returns `raw` if it is a catalog id, else `None`. |
+| `read_active_theme_id()` | Reads `ACTIVE_THEME_CONFIG_KEY` and returns `active_theme_id(...)`. Never raises. |
+
+### Role mapping
+
+| Role | Source | AA adjustment |
+|------|--------|---------------|
+| `background` | `bg` | None (base color) |
+| `surface` | `bg` blended 8% toward `fg` | None (exempt) |
+| `text` | `fg` | Yes |
+| `mutedText` | `ansi[8]` | Yes |
+| `accent` | `ansi[4]` | Yes |
+| `success` | `ansi[2]` | Yes |
+| `error` | `ansi[1]` | Yes |
+| `warning` | `ansi[3]` | Yes |
+| `running` | `ansi[6]` | Yes |
+| `diffAdd` | `ansi[2]` | Yes |
+| `diffRemove` | `ansi[1]` | Yes |
+
+AA adjustment: if a role has less than 4.5:1 contrast against `background`, it
+is blended toward `#ffffff` on dark themes or `#000000` on light themes in 5%
+steps. The first step that reaches 4.5:1 is used. The input palette is never
+modified, and output values are lowercase `#rrggbb`.

code_puppy_core_plugins-0.0.105/code_puppy_core_plugins/theme/catalog.py

@@ -0,0 +1,183 @@
+"""Pure, read-only theme catalog for ACP clients.
+
+Depends on: themes.py :: MENU, CURATED_THEMES, DEFAULT
+Never applies palettes, emits OSC sequences, or writes config.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from code_puppy.config import get_value
+
+from .themes import CURATED_THEMES, DEFAULT, MENU
+
+# Called by: register_callbacks.py :: _apply_theme(), _active_terminal_palette(),
+# _apply_default_theme_on_first_run()
+ACTIVE_THEME_CONFIG_KEY = "theme_active_theme"
+SCHEMA_VERSION = 1
+
+_AA_MIN_CONTRAST = 4.5
+_SURFACE_BLEND = 0.08
+_DARK_LUMINANCE_CUTOFF = 0.179
+_ADJUST_STEPS = 20  # 5% blend increments toward white or black
+_WHITE = (255, 255, 255)
+_BLACK = (0, 0, 0)
+_HEX_RE = re.compile(r"#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})")
+
+
+def appearance_for(bg_hex: str) -> str:
+    return "dark" if _is_dark(_rgb(bg_hex)) else "light"
+
+
+def semantic_roles(palette: dict[str, Any]) -> dict[str, str]:
+    """Map a bg/fg/ansi palette to semantic role colors.
+
+    Non-background roles are blended toward white (dark bg) or black (light bg)
+    in 5% steps until they reach WCAG AA (4.5:1) against the background. The
+    input palette is never mutated.
+    """
+    bg = _rgb(palette["bg"])
+    fg = _rgb(palette["fg"])
+    ansi = [_rgb(color) for color in palette["ansi"]]
+    adjust_target = _WHITE if _is_dark(bg) else _BLACK
+    adjustable = {
+        "text": fg,
+        "mutedText": ansi[8],
+        "accent": ansi[4],
+        "success": ansi[2],
+        "error": ansi[1],
+        "warning": ansi[3],
+        "running": ansi[6],
+        "diffAdd": ansi[2],
+        "diffRemove": ansi[1],
+    }
+    roles = {
+        "background": _hex(bg),
+        "surface": _hex(_blend(bg, fg, _SURFACE_BLEND)),
+    }
+    for role, color in adjustable.items():
+        roles[role] = _hex(_meet_aa(color, bg, adjust_target))
+    return roles
+
+
+def build_catalog() -> list[dict[str, Any]]:
+    """Return fresh wire dicts: curated themes in menu order, then default.
+
+    Every call builds new containers, so callers cannot mutate shared state.
+    """
+    entries = [_curated_entry(theme_id) for theme_id in _curated_ids()]
+    entries.append(_default_entry())
+    return entries
+
+
+def active_theme_id(raw: object) -> str | None:
+    if isinstance(raw, str) and (raw == "default" or raw in _curated_ids()):
+        return raw
+    return None
+
+
+def read_active_theme_id() -> str | None:
+    try:
+        return active_theme_id(get_value(ACTIVE_THEME_CONFIG_KEY))
+    except Exception:
+        return None
+
+
+def _curated_ids() -> list[str]:
+    # Resolved per call so a theme added to MENU/CURATED_THEMES reaches ACP without edits here.
+    return [name for name, _ in MENU if name in CURATED_THEMES]
+
+
+def _curated_entry(theme_id: str) -> dict[str, Any]:
+    theme = CURATED_THEMES[theme_id]
+    palette = _normalised_palette(theme["terminal_palette"])
+    return {
+        "id": theme_id,
+        "label": theme["label"],
+        "icon": theme["icon"],
+        "blurb": theme["blurb"],
+        "appearance": appearance_for(palette["bg"]),
+        "palette": palette,
+        "roles": semantic_roles(palette),
+    }
+
+
+def _default_entry() -> dict[str, Any]:
+    return {
+        "id": "default",
+        "label": DEFAULT["label"],
+        "icon": DEFAULT["icon"],
+        "blurb": DEFAULT["blurb"],
+        "appearance": None,
+        "palette": None,
+        "roles": None,
+    }
+
+
+def _normalised_palette(palette: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "bg": _canonical(palette["bg"]),
+        "fg": _canonical(palette["fg"]),
+        "ansi": [_canonical(color) for color in palette["ansi"]],
+    }
+
+
+def _meet_aa(
+    color: tuple[int, int, int], bg: tuple[int, int, int], target: tuple[int, int, int]
+) -> tuple[int, int, int]:
+    if _contrast(color, bg) >= _AA_MIN_CONTRAST:
+        return color
+    for step in range(1, _ADJUST_STEPS + 1):
+        candidate = _blend(color, target, step / _ADJUST_STEPS)
+        if _contrast(candidate, bg) >= _AA_MIN_CONTRAST:
+            return candidate
+    # Only reachable if the target fails AA, which cannot happen: white clears
+    # 4.5:1 on any bg below the dark cutoff, and black on any bg at or above it.
+    return target
+
+
+def _is_dark(rgb: tuple[int, int, int]) -> bool:
+    return _luminance(rgb) < _DARK_LUMINANCE_CUTOFF
+
+
+def _rgb(color: str) -> tuple[int, int, int]:
+    match = _HEX_RE.fullmatch(color)
+    if match is None:
+        raise ValueError(f"not a hex color: {color!r}")
+    digits = match.group(1)
+    if len(digits) == 3:
+        digits = "".join(digit * 2 for digit in digits)
+    return (int(digits[0:2], 16), int(digits[2:4], 16), int(digits[4:6], 16))
+
+
+def _hex(rgb: tuple[int, int, int]) -> str:
+    return "#" + "".join(f"{channel:02x}" for channel in rgb)
+
+
+def _canonical(color: str) -> str:
+    return _hex(_rgb(color))
+
+
+def _blend(
+    start: tuple[int, int, int], end: tuple[int, int, int], amount: float
+) -> tuple[int, int, int]:
+    r, g, b = (round(s + (e - s) * amount) for s, e in zip(start, end))
+    return (r, g, b)
+
+
+def _linearise(value: float) -> float:
+    if value <= 0.03928:
+        return value / 12.92
+    return ((value + 0.055) / 1.055) ** 2.4
+
+
+def _luminance(rgb: tuple[int, int, int]) -> float:
+    r, g, b = (_linearise(channel / 255) for channel in rgb)
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b
+
+
+def _contrast(first: tuple[int, int, int], second: tuple[int, int, int]) -> float:
+    lighter, darker = sorted((_luminance(first), _luminance(second)), reverse=True)
+    return (lighter + 0.05) / (darker + 0.05)

{code_puppy_core_plugins-0.0.104 → code_puppy_core_plugins-0.0.105}/code_puppy_core_plugins/theme/register_callbacks.py

@@ -24,13 +24,14 @@ from typing import TYPE_CHECKING
 
 from code_puppy.callbacks import register_callback
 
+from .catalog import ACTIVE_THEME_CONFIG_KEY
+
 # NOTE: Keep heavy theme/TUI imports inside callers so plugin discovery stays
 # fast; the deferred style import saves startup time. Caveat: theme/__init__.py
 # still eagerly imports style modules/reapplies config, so prompt_toolkit remains
 # on the startup path until that sweep is deferred too.
 
 _INTERACTIVE_TIMEOUT_SECONDS = 300  # 5 min — generous; user is browsing
-_ACTIVE_THEME_CONFIG_KEY = "theme_active_theme"
 _DEFAULT_THEME_NAME = "tokyo-night"
 _LEGACY_THEME_NAME = "legacy-custom"
 
@@ -118,7 +119,7 @@ def _apply_theme(theme_name: str, *, announce: bool = True) -> None:
         if terminal_palette:
             osc.apply_palette(terminal_palette)
 
-    set_config_value(_ACTIVE_THEME_CONFIG_KEY, theme_name)
+    set_config_value(ACTIVE_THEME_CONFIG_KEY, theme_name)
     if announce:
         _announce_applied(theme_name)
 
@@ -129,7 +130,7 @@ def _active_terminal_palette() -> tuple[str, dict] | None:
 
     from . import osc_palette as osc
 
-    active_theme = get_value(_ACTIVE_THEME_CONFIG_KEY)
+    active_theme = get_value(ACTIVE_THEME_CONFIG_KEY)
     if not active_theme or active_theme in {"default", _LEGACY_THEME_NAME}:
         return None
     palette = osc.get_saved_palette()
@@ -272,7 +273,7 @@ def _apply_default_theme_on_first_run() -> None:
     """Apply Tokyo Night once, preserving explicit and legacy theme choices."""
     from code_puppy.config import get_value
 
-    if get_value(_ACTIVE_THEME_CONFIG_KEY):
+    if get_value(ACTIVE_THEME_CONFIG_KEY):
         return
 
     from code_puppy.config import set_config_value
@@ -282,7 +283,7 @@ def _apply_default_theme_on_first_run() -> None:
     if osc.get_saved_palette():
         # Theme persistence predates the active-theme marker. Treat an existing
         # palette as an intentional choice and migrate without changing it.
-        set_config_value(_ACTIVE_THEME_CONFIG_KEY, _LEGACY_THEME_NAME)
+        set_config_value(ACTIVE_THEME_CONFIG_KEY, _LEGACY_THEME_NAME)
         return
 
     _apply_theme(_DEFAULT_THEME_NAME, announce=False)

{code_puppy_core_plugins-0.0.104 → code_puppy_core_plugins-0.0.105}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "code-puppy-core-plugins"
-version = "0.0.104"
+version = "0.0.105"
 description = "Official plugin bundle for Code Puppy"
 readme = "README.md"
 requires-python = ">=3.11,<3.15"