yee88 0.3.0__py3-none-any.whl

yee88/config_migrations.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .config import ConfigError, ensure_table, read_config, write_config
+from .logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def _ensure_subtable(
+    parent: dict[str, Any],
+    key: str,
+    *,
+    config_path: Path,
+    label: str,
+) -> dict[str, Any] | None:
+    value = parent.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, dict):
+        raise ConfigError(f"Invalid `{label}` in {config_path}; expected a table.")
+    return value
+
+
+def _migrate_legacy_telegram(config: dict[str, Any], *, config_path: Path) -> bool:
+    has_legacy = "bot_token" in config or "chat_id" in config
+    if not has_legacy:
+        return False
+
+    transports = ensure_table(config, "transports", config_path=config_path)
+    telegram = ensure_table(
+        transports,
+        "telegram",
+        config_path=config_path,
+        label="transports.telegram",
+    )
+
+    if "bot_token" in config and "bot_token" not in telegram:
+        telegram["bot_token"] = config["bot_token"]
+    if "chat_id" in config and "chat_id" not in telegram:
+        telegram["chat_id"] = config["chat_id"]
+
+    config.pop("bot_token", None)
+    config.pop("chat_id", None)
+    config.setdefault("transport", "telegram")
+    return True
+
+
+def _migrate_topics_scope(config: dict[str, Any], *, config_path: Path) -> bool:
+    transports = _ensure_subtable(
+        config,
+        "transports",
+        config_path=config_path,
+        label="transports",
+    )
+    if transports is None:
+        return False
+
+    telegram = _ensure_subtable(
+        transports,
+        "telegram",
+        config_path=config_path,
+        label="transports.telegram",
+    )
+    if telegram is None:
+        return False
+
+    topics = _ensure_subtable(
+        telegram,
+        "topics",
+        config_path=config_path,
+        label="transports.telegram.topics",
+    )
+    if topics is None:
+        return False
+    if "mode" not in topics:
+        return False
+
+    if "scope" not in topics:
+        mode = topics.get("mode")
+        if not isinstance(mode, str):
+            raise ConfigError(
+                f"Invalid `transports.telegram.topics.mode` in {config_path}; "
+                "expected a string."
+            )
+        cleaned = mode.strip()
+        mapping = {
+            "multi_project_chat": "main",
+            "per_project_chat": "projects",
+        }
+        if cleaned not in mapping:
+            raise ConfigError(
+                f"Invalid `transports.telegram.topics.mode` in {config_path}; "
+                "expected 'multi_project_chat' or 'per_project_chat'."
+            )
+        topics["scope"] = mapping[cleaned]
+
+    topics.pop("mode", None)
+    return True
+
+
+def migrate_config(config: dict[str, Any], *, config_path: Path) -> list[str]:
+    applied: list[str] = []
+    if _migrate_legacy_telegram(config, config_path=config_path):
+        applied.append("legacy-telegram")
+    if _migrate_topics_scope(config, config_path=config_path):
+        applied.append("topics-scope")
+    return applied
+
+
+def migrate_config_file(path: Path) -> list[str]:
+    config = read_config(path)
+    applied = migrate_config(config, config_path=path)
+    if applied:
+        write_config(config, path)
+        for migration in applied:
+            logger.info(
+                "config.migrated",
+                migration=migration,
+                path=str(path),
+            )
+    return applied

yee88/config_watch.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from collections.abc import Awaitable, Callable, Iterable
+
+from watchfiles import awatch
+
+from .config import ConfigError
+from .ids import RESERVED_CHAT_COMMANDS
+from .logging import get_logger
+from .runtime_loader import RuntimeSpec, build_runtime_spec
+from .settings import TakopiSettings, load_settings
+from .transport_runtime import TransportRuntime
+
+logger = get_logger(__name__)
+
+__all__ = [
+    "ConfigReload",
+    "config_status",
+    "watch_config",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class ConfigReload:
+    settings: TakopiSettings
+    runtime_spec: RuntimeSpec
+    config_path: Path
+
+
+def config_status(path: Path) -> tuple[str, tuple[int, int] | None]:
+    try:
+        stat = path.stat()
+    except FileNotFoundError:
+        return "missing", None
+    except OSError:
+        return "missing", None
+    if not path.is_file():
+        return "invalid", None
+    return "ok", (stat.st_mtime_ns, stat.st_size)
+
+
+def _matches_config_path(candidate: str, config_path: Path) -> bool:
+    try:
+        return Path(candidate).resolve(strict=False) == config_path
+    except OSError:
+        return False
+
+
+def _reload_config(
+    config_path: Path,
+    default_engine_override: str | None,
+    reserved: tuple[str, ...],
+) -> ConfigReload:
+    settings, resolved_path = load_settings(config_path)
+    spec = build_runtime_spec(
+        settings=settings,
+        config_path=resolved_path,
+        default_engine_override=default_engine_override,
+        reserved=reserved,
+    )
+    return ConfigReload(
+        settings=settings,
+        runtime_spec=spec,
+        config_path=resolved_path,
+    )
+
+
+async def watch_config(
+    *,
+    config_path: Path,
+    runtime: TransportRuntime,
+    default_engine_override: str | None = None,
+    reserved: Iterable[str] = RESERVED_CHAT_COMMANDS,
+    on_reload: Callable[[ConfigReload], Awaitable[None]] | None = None,
+) -> None:
+    # Mutmut sets MUTANT_UNDER_TEST; disable watchers to avoid native crashes.
+    if os.environ.get("MUTANT_UNDER_TEST"):
+        return
+    reserved_tuple = tuple(reserved)
+    config_path = config_path.expanduser().resolve()
+    watch_root = config_path.parent
+    status, signature = config_status(config_path)
+    last_status = status
+    if status != "ok":
+        logger.warning("config.watch.unavailable", path=str(config_path), status=status)
+
+    async for changes in awatch(watch_root):
+        if not any(_matches_config_path(path, config_path) for _, path in changes):
+            continue
+
+        status, current = config_status(config_path)
+        if status != "ok":
+            if status != last_status:
+                logger.warning(
+                    "config.watch.unavailable",
+                    path=str(config_path),
+                    status=status,
+                )
+            last_status = status
+            signature = None
+            continue
+
+        if last_status != "ok":
+            logger.info("config.watch.available", path=str(config_path))
+        last_status = status
+
+        if current == signature:
+            continue
+
+        try:
+            reload = _reload_config(
+                config_path,
+                default_engine_override,
+                reserved_tuple,
+            )
+        except ConfigError as exc:
+            logger.warning("config.reload.failed", error=str(exc))
+            signature = current
+            continue
+        except Exception as exc:  # pragma: no cover - safety net
+            logger.exception(
+                "config.reload.crashed",
+                error=str(exc),
+                error_type=exc.__class__.__name__,
+            )
+            signature = current
+            continue
+
+        reload.runtime_spec.apply(runtime, config_path=reload.config_path)
+        logger.info("config.reload.applied", path=str(reload.config_path))
+        if on_reload is not None:
+            try:
+                await on_reload(reload)
+            except Exception as exc:  # pragma: no cover - safety net
+                logger.exception(
+                    "config.reload.callback_failed",
+                    error=str(exc),
+                    error_type=exc.__class__.__name__,
+                )
+
+        _, signature = config_status(config_path)
+        if signature is None:
+            signature = current

yee88/context.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class RunContext:
+    project: str | None = None
+    branch: str | None = None

yee88/directives.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .config import ProjectsConfig
+from .context import RunContext
+from .model import EngineId
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedDirectives:
+    prompt: str
+    engine: EngineId | None
+    project: str | None
+    branch: str | None
+
+
+class DirectiveError(RuntimeError):
+    pass
+
+
+def parse_directives(
+    text: str,
+    *,
+    engine_ids: tuple[EngineId, ...],
+    projects: ProjectsConfig,
+) -> ParsedDirectives:
+    if not text:
+        return ParsedDirectives(prompt="", engine=None, project=None, branch=None)
+
+    lines = text.splitlines()
+    idx = next((i for i, line in enumerate(lines) if line.strip()), None)
+    if idx is None:
+        return ParsedDirectives(prompt=text, engine=None, project=None, branch=None)
+
+    line = lines[idx].lstrip()
+    tokens = line.split()
+    if not tokens:
+        return ParsedDirectives(prompt=text, engine=None, project=None, branch=None)
+
+    engine_map = {engine.lower(): engine for engine in engine_ids}
+    project_map = {alias.lower(): alias for alias in projects.projects}
+
+    engine: EngineId | None = None
+    project: str | None = None
+    branch: str | None = None
+    consumed = 0
+
+    for token in tokens:
+        if token.startswith("/"):
+            name = token[1:]
+            if "@" in name:
+                name = name.split("@", 1)[0]
+            if not name:
+                break
+            key = name.lower()
+            engine_candidate = engine_map.get(key)
+            project_candidate = project_map.get(key)
+            if engine_candidate is not None:
+                if engine is not None:
+                    raise DirectiveError("multiple engine directives")
+                engine = engine_candidate
+                consumed += 1
+                continue
+            if project_candidate is not None:
+                if project is not None:
+                    raise DirectiveError("multiple project directives")
+                project = project_candidate
+                consumed += 1
+                continue
+            break
+        if token.startswith("@"):
+            value = token[1:]
+            if not value:
+                break
+            if branch is not None:
+                raise DirectiveError("multiple @branch directives")
+            branch = value
+            consumed += 1
+            continue
+        break
+
+    if consumed == 0:
+        return ParsedDirectives(prompt=text, engine=None, project=None, branch=None)
+
+    if consumed < len(tokens):
+        remainder = " ".join(tokens[consumed:])
+        lines[idx] = remainder
+    else:
+        lines.pop(idx)
+
+    prompt = "\n".join(lines).strip()
+    return ParsedDirectives(
+        prompt=prompt, engine=engine, project=project, branch=branch
+    )
+
+
+def parse_context_line(
+    text: str | None, *, projects: ProjectsConfig
+) -> RunContext | None:
+    if not text:
+        return None
+    ctx: RunContext | None = None
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("`") and stripped.endswith("`") and len(stripped) > 1:
+            stripped = stripped[1:-1].strip()
+        elif stripped.startswith("`"):
+            stripped = stripped[1:].strip()
+        elif stripped.endswith("`"):
+            stripped = stripped[:-1].strip()
+        if not stripped.lower().startswith("ctx:"):
+            continue
+        content = stripped.split(":", 1)[1].strip()
+        if not content:
+            continue
+        tokens = content.split()
+        if not tokens:
+            continue
+        project = tokens[0]
+        branch = None
+        if len(tokens) >= 2:
+            if tokens[1] == "@" and len(tokens) >= 3:
+                branch = tokens[2]
+            elif tokens[1].startswith("@"):
+                branch = tokens[1][1:]
+        project_key = project.lower()
+        if project_key not in projects.projects:
+            raise DirectiveError(
+                f"unknown project {project!r} in ctx line; start a new thread or "
+                "add it back to your config"
+            )
+        ctx = RunContext(project=project_key, branch=branch)
+    return ctx
+
+
+def format_context_line(
+    context: RunContext | None, *, projects: ProjectsConfig
+) -> str | None:
+    if context is None or context.project is None:
+        return None
+    project_cfg = projects.projects.get(context.project)
+    alias = project_cfg.alias if project_cfg is not None else context.project
+    if context.branch:
+        return f"`ctx: {alias} @{context.branch}`"
+    return f"`ctx: {alias}`"

yee88/engines.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from .backends import EngineBackend
+from .config import ConfigError
+from .plugins import ENGINE_GROUP, list_ids, load_plugin_backend
+from .ids import RESERVED_ENGINE_IDS
+
+
+def _validate_engine_backend(backend: object, ep) -> None:
+    if not isinstance(backend, EngineBackend):
+        raise TypeError(f"{ep.value} is not an EngineBackend")
+    if backend.id != ep.name:
+        raise ValueError(
+            f"{ep.value} engine id {backend.id!r} does not match entrypoint {ep.name!r}"
+        )
+
+
+def get_backend(
+    engine_id: str, *, allowlist: Iterable[str] | None = None
+) -> EngineBackend:
+    if engine_id.lower() in RESERVED_ENGINE_IDS:
+        raise ConfigError(f"Engine id {engine_id!r} is reserved.")
+    backend = load_plugin_backend(
+        ENGINE_GROUP,
+        engine_id,
+        allowlist=allowlist,
+        validator=_validate_engine_backend,
+        kind_label="engine",
+    )
+    assert backend is not None
+    return backend
+
+
+def list_backends(*, allowlist: Iterable[str] | None = None) -> list[EngineBackend]:
+    backends: list[EngineBackend] = []
+    for engine_id in list_backend_ids(allowlist=allowlist):
+        try:
+            backends.append(get_backend(engine_id, allowlist=allowlist))
+        except ConfigError:
+            continue
+    if not backends:
+        raise ConfigError("No engine backends are available.")
+    return backends
+
+
+def list_backend_ids(*, allowlist: Iterable[str] | None = None) -> list[str]:
+    return list_ids(
+        ENGINE_GROUP,
+        allowlist=allowlist,
+        reserved_ids=RESERVED_ENGINE_IDS,
+    )

yee88/events.py

@@ -0,0 +1,170 @@
+"""Event factory helpers for runner implementations."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .model import (
+    Action,
+    ActionEvent,
+    ActionKind,
+    ActionLevel,
+    ActionPhase,
+    CompletedEvent,
+    EngineId,
+    ResumeToken,
+    StartedEvent,
+)
+
+
+class EventFactory:
+    __slots__ = ("engine", "_resume")
+
+    def __init__(self, engine: EngineId) -> None:
+        self.engine = engine
+        self._resume: ResumeToken | None = None
+
+    @property
+    def resume(self) -> ResumeToken | None:
+        return self._resume
+
+    def started(
+        self,
+        token: ResumeToken,
+        *,
+        title: str | None = None,
+        meta: dict[str, Any] | None = None,
+    ) -> StartedEvent:
+        if token.engine != self.engine:
+            raise RuntimeError(f"resume token is for engine {token.engine!r}")
+        if self._resume is not None and self._resume != token:
+            raise RuntimeError(
+                f"resume token mismatch: {self._resume.value} vs {token.value}"
+            )
+        self._resume = token
+        return StartedEvent(engine=self.engine, resume=token, title=title, meta=meta)
+
+    def action(
+        self,
+        *,
+        phase: ActionPhase,
+        action_id: str,
+        kind: ActionKind,
+        title: str,
+        detail: dict[str, Any] | None = None,
+        ok: bool | None = None,
+        message: str | None = None,
+        level: ActionLevel | None = None,
+    ) -> ActionEvent:
+        action = Action(
+            id=action_id,
+            kind=kind,
+            title=title,
+            detail=detail or {},
+        )
+        return ActionEvent(
+            engine=self.engine,
+            action=action,
+            phase=phase,
+            ok=ok,
+            message=message,
+            level=level,
+        )
+
+    def action_started(
+        self,
+        *,
+        action_id: str,
+        kind: ActionKind,
+        title: str,
+        detail: dict[str, Any] | None = None,
+    ) -> ActionEvent:
+        return self.action(
+            phase="started",
+            action_id=action_id,
+            kind=kind,
+            title=title,
+            detail=detail,
+        )
+
+    def action_updated(
+        self,
+        *,
+        action_id: str,
+        kind: ActionKind,
+        title: str,
+        detail: dict[str, Any] | None = None,
+    ) -> ActionEvent:
+        return self.action(
+            phase="updated",
+            action_id=action_id,
+            kind=kind,
+            title=title,
+            detail=detail,
+        )
+
+    def action_completed(
+        self,
+        *,
+        action_id: str,
+        kind: ActionKind,
+        title: str,
+        ok: bool,
+        detail: dict[str, Any] | None = None,
+        message: str | None = None,
+        level: ActionLevel | None = None,
+    ) -> ActionEvent:
+        return self.action(
+            phase="completed",
+            action_id=action_id,
+            kind=kind,
+            title=title,
+            detail=detail,
+            ok=ok,
+            message=message,
+            level=level,
+        )
+
+    def completed(
+        self,
+        *,
+        ok: bool,
+        answer: str,
+        resume: ResumeToken | None = None,
+        error: str | None = None,
+        usage: dict[str, Any] | None = None,
+    ) -> CompletedEvent:
+        resolved_resume = resume if resume is not None else self._resume
+        return CompletedEvent(
+            engine=self.engine,
+            ok=ok,
+            answer=answer,
+            resume=resolved_resume,
+            error=error,
+            usage=usage,
+        )
+
+    def completed_ok(
+        self,
+        *,
+        answer: str,
+        resume: ResumeToken | None = None,
+        usage: dict[str, Any] | None = None,
+    ) -> CompletedEvent:
+        return self.completed(ok=True, answer=answer, resume=resume, usage=usage)
+
+    def completed_error(
+        self,
+        *,
+        error: str,
+        answer: str = "",
+        resume: ResumeToken | None = None,
+        usage: dict[str, Any] | None = None,
+    ) -> CompletedEvent:
+        return self.completed(
+            ok=False,
+            answer=answer,
+            resume=resume,
+            error=error,
+            usage=usage,
+        )

yee88/ids.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import re
+
+ID_PATTERN = r"^[a-z0-9_]{1,32}$"
+_ID_RE = re.compile(ID_PATTERN)
+
+RESERVED_CLI_COMMANDS = frozenset({"config", "doctor", "init", "plugins"})
+RESERVED_CHAT_COMMANDS = frozenset(
+    {"cancel", "file", "new", "agent", "model", "reasoning", "trigger", "topic", "ctx"}
+)
+RESERVED_ENGINE_IDS = RESERVED_CLI_COMMANDS | RESERVED_CHAT_COMMANDS
+RESERVED_COMMAND_IDS = RESERVED_CLI_COMMANDS | RESERVED_CHAT_COMMANDS
+
+
+def is_valid_id(value: str) -> bool:
+    return bool(_ID_RE.fullmatch(value))