pythinker-code 2.0.0__py3-none-any.whl

pythinker_code/notifications/manager.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import time
+import uuid
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+
+from pythinker_code.config import NotificationConfig
+from pythinker_code.utils.logging import logger
+
+from .models import (
+    NotificationDelivery,
+    NotificationEvent,
+    NotificationSinkState,
+    NotificationView,
+)
+from .store import NotificationStore
+
+
+class NotificationManager:
+    def __init__(self, root: Path, config: NotificationConfig) -> None:
+        self._config = config
+        self._store = NotificationStore(root)
+
+    @property
+    def store(self) -> NotificationStore:
+        return self._store
+
+    def new_id(self) -> str:
+        return f"n{uuid.uuid4().hex[:8]}"
+
+    def _initial_delivery(self, event: NotificationEvent) -> NotificationDelivery:
+        return NotificationDelivery(sinks={sink: NotificationSinkState() for sink in event.targets})
+
+    def find_by_dedupe_key(self, dedupe_key: str) -> NotificationView | None:
+        for view in self._store.list_views():
+            if view.event.dedupe_key == dedupe_key:
+                return view
+        return None
+
+    def publish(self, event: NotificationEvent) -> NotificationView:
+        if event.dedupe_key:
+            existing = self.find_by_dedupe_key(event.dedupe_key)
+            if existing is not None:
+                return existing
+        delivery = self._initial_delivery(event)
+        self._store.create_notification(event, delivery)
+        return NotificationView(event=event, delivery=delivery)
+
+    def recover(self) -> None:
+        now = time.time()
+        stale_after = self._config.claim_stale_after_ms / 1000
+        for view in self._store.list_views():
+            updated = False
+            delivery = view.delivery.model_copy(deep=True)
+            for sink_state in delivery.sinks.values():
+                if sink_state.status != "claimed" or sink_state.claimed_at is None:
+                    continue
+                if now - sink_state.claimed_at <= stale_after:
+                    continue
+                sink_state.status = "pending"
+                sink_state.claimed_at = None
+                updated = True
+            if updated:
+                self._store.write_delivery(view.event.id, delivery)
+
+    def has_pending_for_sink(self, sink: str) -> bool:
+        """Check whether any notification has a pending delivery for *sink*."""
+        for view in self._store.list_views():
+            sink_state = view.delivery.sinks.get(sink)
+            if sink_state is not None and sink_state.status == "pending":
+                return True
+        return False
+
+    def claim_for_sink(self, sink: str, *, limit: int = 8) -> list[NotificationView]:
+        self.recover()
+        claimed: list[NotificationView] = []
+        now = time.time()
+        for view in reversed(self._store.list_views()):
+            sink_state = view.delivery.sinks.get(sink)
+            if sink_state is None or sink_state.status == "acked":
+                continue
+            if sink_state.status == "claimed":
+                continue
+            delivery = view.delivery.model_copy(deep=True)
+            target_state = delivery.sinks[sink]
+            target_state.status = "claimed"
+            target_state.claimed_at = now
+            self._store.write_delivery(view.event.id, delivery)
+            claimed.append(NotificationView(event=view.event, delivery=delivery))
+            if len(claimed) >= limit:
+                break
+        return claimed
+
+    async def deliver_pending(
+        self,
+        sink: str,
+        *,
+        on_notification: Callable[[NotificationView], Awaitable[None] | None],
+        limit: int = 8,
+        before_claim: Callable[[], object] | None = None,
+    ) -> list[NotificationView]:
+        """Deliver pending notifications for one sink using a shared claim/ack flow.
+
+        If the handler raises for a notification, the error is logged and that
+        notification stays in ``claimed`` state (will be recovered later).
+        Delivery continues for remaining notifications.
+        """
+        if before_claim is not None:
+            before_claim()
+
+        delivered: list[NotificationView] = []
+        for view in self.claim_for_sink(sink, limit=limit):
+            try:
+                result = on_notification(view)
+                if result is not None:
+                    await result
+            except Exception:
+                logger.exception(
+                    "Notification handler failed for {sink}/{id}, leaving claimed for recovery",
+                    sink=sink,
+                    id=view.event.id,
+                )
+                continue
+            delivered.append(self.ack(sink, view.event.id))
+        return delivered
+
+    def ack(self, sink: str, notification_id: str) -> NotificationView:
+        view = self._store.merged_view(notification_id)
+        delivery = view.delivery.model_copy(deep=True)
+        sink_state = delivery.sinks.get(sink)
+        if sink_state is None:
+            return view
+        sink_state.status = "acked"
+        sink_state.acked_at = time.time()
+        sink_state.claimed_at = None
+        self._store.write_delivery(notification_id, delivery)
+        return NotificationView(event=view.event, delivery=delivery)
+
+    def ack_ids(self, sink: str, notification_ids: set[str]) -> None:
+        for notification_id in notification_ids:
+            try:
+                self.ack(sink, notification_id)
+            except (FileNotFoundError, ValueError):
+                continue

pythinker_code/notifications/models.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import time
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+type NotificationCategory = Literal["task", "agent", "system"]
+type NotificationSeverity = Literal["info", "success", "warning", "error"]
+type NotificationSink = Literal["llm", "wire", "shell"]
+type NotificationDeliveryStatus = Literal["pending", "claimed", "acked"]
+
+
+class NotificationEvent(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    version: int = 1
+    id: str
+    category: NotificationCategory
+    type: str
+    source_kind: str
+    source_id: str
+    title: str
+    body: str
+    severity: NotificationSeverity = "info"
+    created_at: float = Field(default_factory=time.time)
+    payload: dict[str, Any] = Field(default_factory=dict)
+    targets: list[NotificationSink] = Field(default_factory=lambda: ["llm", "wire", "shell"])
+    dedupe_key: str | None = None
+
+
+class NotificationSinkState(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    status: NotificationDeliveryStatus = "pending"
+    claimed_at: float | None = None
+    acked_at: float | None = None
+
+
+class NotificationDelivery(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    sinks: dict[str, NotificationSinkState] = Field(default_factory=dict)
+
+
+class NotificationView(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    event: NotificationEvent
+    delivery: NotificationDelivery

pythinker_code/notifications/notifier.py

@@ -0,0 +1,41 @@
+import asyncio
+from collections.abc import Awaitable, Callable
+
+from pythinker_code.utils.logging import logger
+
+from .manager import NotificationManager
+from .models import NotificationSink, NotificationView
+
+
+class NotificationWatcher:
+    def __init__(
+        self,
+        manager: NotificationManager,
+        *,
+        sink: NotificationSink,
+        on_notification: Callable[[NotificationView], Awaitable[None] | None],
+        before_poll: Callable[[], object] | None = None,
+        interval_s: float = 1.0,
+    ) -> None:
+        self._manager = manager
+        self._sink = sink
+        self._on_notification = on_notification
+        self._before_poll = before_poll
+        self._interval_s = interval_s
+
+    async def poll_once(self) -> list[NotificationView]:
+        return await self._manager.deliver_pending(
+            self._sink,
+            on_notification=self._on_notification,
+            before_claim=self._before_poll,
+        )
+
+    async def run_forever(self) -> None:
+        while True:
+            try:
+                await self.poll_once()
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                logger.exception("NotificationWatcher poll failed")
+            await asyncio.sleep(self._interval_s)

pythinker_code/notifications/store.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from pythinker_code.utils.io import atomic_json_write
+from pythinker_code.utils.logging import logger
+
+from .models import NotificationDelivery, NotificationEvent, NotificationView
+
+_VALID_NOTIFICATION_ID = re.compile(r"^[a-z0-9]{2,20}$")
+
+
+def _validate_notification_id(notification_id: str) -> None:
+    if not _VALID_NOTIFICATION_ID.match(notification_id):
+        raise ValueError(f"Invalid notification_id: {notification_id!r}")
+
+
+class NotificationStore:
+    EVENT_FILE = "event.json"
+    DELIVERY_FILE = "delivery.json"
+
+    def __init__(self, root: Path):
+        self._root = root
+
+    @property
+    def root(self) -> Path:
+        return self._root
+
+    def _ensure_root(self) -> Path:
+        """Return the root directory, creating it if it does not exist."""
+        self._root.mkdir(parents=True, exist_ok=True)
+        return self._root
+
+    def notification_dir(self, notification_id: str) -> Path:
+        _validate_notification_id(notification_id)
+        path = self._ensure_root() / notification_id
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def notification_path(self, notification_id: str) -> Path:
+        _validate_notification_id(notification_id)
+        return self.root / notification_id
+
+    def event_path(self, notification_id: str) -> Path:
+        return self.notification_path(notification_id) / self.EVENT_FILE
+
+    def delivery_path(self, notification_id: str) -> Path:
+        return self.notification_path(notification_id) / self.DELIVERY_FILE
+
+    def create_notification(
+        self,
+        event: NotificationEvent,
+        delivery: NotificationDelivery,
+    ) -> None:
+        notification_dir = self.notification_dir(event.id)
+        atomic_json_write(event.model_dump(mode="json"), notification_dir / self.EVENT_FILE)
+        atomic_json_write(delivery.model_dump(mode="json"), notification_dir / self.DELIVERY_FILE)
+
+    def list_notification_ids(self) -> list[str]:
+        if not self.root.exists():
+            return []
+        notification_ids: list[str] = []
+        for path in sorted(self.root.iterdir()):
+            if not path.is_dir():
+                continue
+            if not (path / self.EVENT_FILE).exists():
+                continue
+            notification_ids.append(path.name)
+        return notification_ids
+
+    def read_event(self, notification_id: str) -> NotificationEvent:
+        return NotificationEvent.model_validate_json(
+            self.event_path(notification_id).read_text(encoding="utf-8")
+        )
+
+    def write_event(self, event: NotificationEvent) -> None:
+        atomic_json_write(event.model_dump(mode="json"), self.event_path(event.id))
+
+    def read_delivery(self, notification_id: str) -> NotificationDelivery:
+        path = self.delivery_path(notification_id)
+        if not path.exists():
+            return NotificationDelivery()
+        try:
+            return NotificationDelivery.model_validate_json(path.read_text(encoding="utf-8"))
+        except (OSError, ValidationError, ValueError, UnicodeDecodeError) as exc:
+            logger.warning(
+                "Failed to read notification delivery {path}; using defaults: {error}",
+                path=path,
+                error=exc,
+            )
+            return NotificationDelivery()
+
+    def write_delivery(self, notification_id: str, delivery: NotificationDelivery) -> None:
+        atomic_json_write(delivery.model_dump(mode="json"), self.delivery_path(notification_id))
+
+    def merged_view(self, notification_id: str) -> NotificationView:
+        return NotificationView(
+            event=self.read_event(notification_id),
+            delivery=self.read_delivery(notification_id),
+        )
+
+    def list_views(self) -> list[NotificationView]:
+        views: list[NotificationView] = []
+        for notification_id in self.list_notification_ids():
+            try:
+                views.append(self.merged_view(notification_id))
+            except (OSError, ValidationError, ValueError, UnicodeDecodeError) as exc:
+                logger.warning(
+                    "Skipping invalid notification {notification_id} from {path}: {error}",
+                    notification_id=notification_id,
+                    path=self.root / notification_id / self.EVENT_FILE,
+                    error=exc,
+                )
+        views.sort(key=lambda view: view.event.created_at, reverse=True)
+        return views

pythinker_code/notifications/wire.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from pythinker_code.wire.types import Notification
+
+from .models import NotificationView
+
+
+def to_wire_notification(view: NotificationView) -> Notification:
+    event = view.event
+    return Notification(
+        id=event.id,
+        category=event.category,
+        type=event.type,
+        source_kind=event.source_kind,
+        source_id=event.source_id,
+        title=event.title,
+        body=event.body,
+        severity=event.severity,
+        created_at=event.created_at,
+        payload=event.payload,
+    )

pythinker_code/plugin/__init__.py

@@ -0,0 +1,124 @@
+"""Plugin specification parsing and config injection."""
+
+import json
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class PluginError(Exception):
+    """Raised when plugin.json is invalid or an operation fails."""
+
+
+class PluginRuntime(BaseModel):
+    """Runtime information written by the host after installation."""
+
+    host: str
+    host_version: str
+
+
+class PluginToolSpec(BaseModel):
+    """A tool declared by a plugin."""
+
+    name: str
+    description: str
+    command: list[str]
+    parameters: dict[str, object] = Field(default_factory=dict)
+
+
+class PluginSpec(BaseModel):
+    """Parsed representation of a plugin.json file."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    name: str
+    version: str
+    description: str = ""
+    config_file: str | None = None
+    inject: dict[str, str] = Field(default_factory=dict)
+    tools: list[PluginToolSpec] = Field(default_factory=list)  # pyright: ignore[reportUnknownVariableType]
+    runtime: PluginRuntime | None = None
+
+
+PLUGIN_JSON = "plugin.json"
+
+
+def parse_plugin_json(path: Path) -> PluginSpec:
+    """Parse a plugin.json file and return a validated PluginSpec."""
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise PluginError(f"Failed to read {path}: {exc}") from exc
+
+    if "name" not in data:
+        raise PluginError(f"Missing required field 'name' in {path}")
+    if "version" not in data:
+        raise PluginError(f"Missing required field 'version' in {path}")
+    if data.get("inject") and not data.get("config_file"):
+        raise PluginError(f"'inject' requires 'config_file' in {path}")
+
+    try:
+        return PluginSpec.model_validate(data)
+    except Exception as exc:
+        raise PluginError(f"Invalid plugin.json schema in {path}: {exc}") from exc
+
+
+def inject_config(plugin_dir: Path, spec: PluginSpec, values: dict[str, str]) -> None:
+    """Inject host values into the plugin's config file.
+
+    Args:
+        plugin_dir: Root directory of the installed plugin.
+        spec: Parsed plugin spec.
+        values: Map of standard inject keys to actual values (e.g. {"api_key": "sk-xxx"}).
+    """
+    if not spec.inject or not spec.config_file:
+        return
+
+    config_path = (plugin_dir / spec.config_file).resolve()
+    if not config_path.is_relative_to(plugin_dir.resolve()):
+        raise PluginError(f"config_file escapes plugin directory: {spec.config_file}")
+    if not config_path.exists():
+        raise PluginError(f"Config file not found: {config_path}")
+
+    try:
+        config = json.loads(config_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise PluginError(f"Failed to read config file {config_path}: {exc}") from exc
+
+    for target_path, source_key in spec.inject.items():
+        if source_key not in values:
+            raise PluginError(f"Host does not provide required inject key '{source_key}'")
+        _set_nested(config, target_path, values[source_key])
+
+    config_path.write_text(
+        json.dumps(config, ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+
+
+def write_runtime(plugin_dir: Path, runtime: PluginRuntime) -> None:
+    """Write runtime info into plugin.json."""
+    plugin_json_path = plugin_dir / PLUGIN_JSON
+    try:
+        data = json.loads(plugin_json_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise PluginError(f"Failed to read {plugin_json_path}: {exc}") from exc
+    data["runtime"] = runtime.model_dump()
+    plugin_json_path.write_text(
+        json.dumps(data, ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+
+
+def _set_nested(obj: dict[str, Any], dotted_path: str, value: object) -> None:
+    """Set a value in a nested dict using dot-separated path.
+
+    Creates intermediate dicts if they don't exist.
+    """
+    keys = dotted_path.split(".")
+    for key in keys[:-1]:
+        if key not in obj or not isinstance(obj[key], dict):
+            obj[key] = {}
+        obj = obj[key]
+    obj[keys[-1]] = value

pythinker_code/plugin/manager.py

@@ -0,0 +1,153 @@
+"""Plugin installation, removal, and listing."""
+
+from __future__ import annotations
+
+import shutil
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pythinker_code.plugin import (
+    PLUGIN_JSON,
+    PluginError,
+    PluginRuntime,
+    PluginSpec,
+    inject_config,
+    parse_plugin_json,
+    write_runtime,
+)
+from pythinker_code.share import get_share_dir
+
+if TYPE_CHECKING:
+    from pythinker_code.auth.oauth import OAuthManager
+    from pythinker_code.config import Config
+
+
+def get_plugins_dir() -> Path:
+    """Return the plugins installation directory (~/.pythinker/plugins/)."""
+    return get_share_dir() / "plugins"
+
+
+def collect_host_values(config: Config, oauth: OAuthManager) -> dict[str, str]:
+    """Collect host values (api_key, base_url) for plugin injection.
+
+    Resolves credentials from the default provider, handling OAuth tokens
+    and static API keys.  Callers that run outside the normal startup flow
+    (e.g. ``install_cmd``) should apply environment-variable overrides
+    (``augment_provider_with_env_vars``) to the provider **before** calling
+    this function; the main app startup already does that.
+    """
+    values: dict[str, str] = {}
+    if not config.default_model or config.default_model not in config.models:
+        return values
+    model = config.models[config.default_model]
+    if model.provider not in config.providers:
+        return values
+    provider = config.providers[model.provider]
+    api_key = oauth.resolve_api_key(provider.api_key, provider.oauth)
+    if api_key:
+        values["api_key"] = api_key
+    values["base_url"] = provider.base_url
+    return values
+
+
+def _validate_name(name: str, plugins_dir: Path) -> Path:
+    """Resolve and validate plugin name, returning the safe destination path."""
+    dest = (plugins_dir / name).resolve()
+    if not dest.is_relative_to(plugins_dir.resolve()):
+        raise PluginError(f"Invalid plugin name: {name}")
+    return dest
+
+
+def install_plugin(
+    *,
+    source: Path,
+    plugins_dir: Path,
+    host_values: dict[str, str],
+    host_name: str,
+    host_version: str,
+) -> PluginSpec:
+    """Install a plugin from a source directory.
+
+    Stages the new copy to a temp dir first, so a failed upgrade
+    does not destroy the previous installation.
+    """
+    source_plugin_json = source / PLUGIN_JSON
+    if not source_plugin_json.exists():
+        raise PluginError(f"No plugin.json found in {source}")
+
+    spec = parse_plugin_json(source_plugin_json)
+    dest = _validate_name(spec.name, plugins_dir)
+
+    # Stage to a temp dir inside plugins_dir so rename is atomic on same fs
+    plugins_dir.mkdir(parents=True, exist_ok=True)
+    staging = Path(tempfile.mkdtemp(prefix=f".{spec.name}-", dir=plugins_dir))
+    try:
+        # Copy source into staging
+        staging_plugin = staging / spec.name
+        shutil.copytree(source, staging_plugin)
+
+        # Apply inject + runtime on the staged copy
+        inject_config(staging_plugin, spec, host_values)
+        runtime = PluginRuntime(host=host_name, host_version=host_version)
+        write_runtime(staging_plugin, runtime)
+
+        # Swap: remove old, move staged into place
+        if dest.exists():
+            shutil.rmtree(dest)
+        staging_plugin.rename(dest)
+    except Exception:
+        # On any failure, clean up staging but leave existing install intact
+        shutil.rmtree(staging, ignore_errors=True)
+        raise
+    finally:
+        # Clean up staging dir shell (may be empty after successful rename)
+        shutil.rmtree(staging, ignore_errors=True)
+
+    # Re-read to return the installed spec (with runtime)
+    return parse_plugin_json(dest / PLUGIN_JSON)
+
+
+def refresh_plugin_configs(plugins_dir: Path, host_values: dict[str, str]) -> None:
+    """Re-inject host values into all installed plugin config files.
+
+    Called at startup so that OAuth tokens and other credentials
+    stay fresh even after the initial install.
+    """
+    if not plugins_dir.is_dir():
+        return
+
+    for child in sorted(plugins_dir.iterdir()):
+        plugin_json = child / PLUGIN_JSON
+        if not child.is_dir() or not plugin_json.is_file():
+            continue
+        try:
+            spec = parse_plugin_json(plugin_json)
+            if spec.inject and spec.config_file:
+                inject_config(child, spec, host_values)
+        except Exception:
+            continue
+
+
+def list_plugins(plugins_dir: Path) -> list[PluginSpec]:
+    """List all installed plugins."""
+    if not plugins_dir.is_dir():
+        return []
+
+    plugins: list[PluginSpec] = []
+    for child in sorted(plugins_dir.iterdir()):
+        plugin_json = child / PLUGIN_JSON
+        if child.is_dir() and plugin_json.is_file():
+            try:
+                plugins.append(parse_plugin_json(plugin_json))
+            except PluginError:
+                continue
+    return plugins
+
+
+def remove_plugin(name: str, plugins_dir: Path) -> None:
+    """Remove an installed plugin."""
+    dest = _validate_name(name, plugins_dir)
+    if not dest.exists():
+        raise PluginError(f"Plugin '{name}' not found in {plugins_dir}")
+    shutil.rmtree(dest)