yee88 0.3.0__py3-none-any.whl

yee88/markdown.py

@@ -0,0 +1,298 @@
+from __future__ import annotations
+
+import os
+import textwrap
+from dataclasses import dataclass
+from pathlib import Path
+
+from .model import Action, ActionEvent, StartedEvent, TakopiEvent
+from .progress import ProgressState
+from .transport import RenderedMessage
+from .utils.paths import relativize_path
+
+STATUS = {"running": "▸", "update": "↻", "done": "✓", "fail": "✗"}
+HEADER_SEP = " · "
+HARD_BREAK = "  \n"
+
+MAX_PROGRESS_CMD_LEN = 300
+MAX_FILE_CHANGES_INLINE = 3
+
+
+@dataclass(frozen=True, slots=True)
+class MarkdownParts:
+    header: str
+    body: str | None = None
+    footer: str | None = None
+
+
+def assemble_markdown_parts(parts: MarkdownParts) -> str:
+    return "\n\n".join(
+        chunk for chunk in (parts.header, parts.body, parts.footer) if chunk
+    )
+
+
+def format_changed_file_path(path: str, *, base_dir: Path | None = None) -> str:
+    return f"`{relativize_path(path, base_dir=base_dir)}`"
+
+
+def format_elapsed(elapsed_s: float) -> str:
+    total = max(0, int(elapsed_s))
+    minutes, seconds = divmod(total, 60)
+    hours, minutes = divmod(minutes, 60)
+    if hours:
+        return f"{hours}h {minutes:02d}m"
+    if minutes:
+        return f"{minutes}m {seconds:02d}s"
+    return f"{seconds}s"
+
+
+def format_header(
+    elapsed_s: float, item: int | None, *, label: str, engine: str
+) -> str:
+    elapsed = format_elapsed(elapsed_s)
+    parts = [label, engine]
+    parts.append(elapsed)
+    if item is not None:
+        parts.append(f"step {item}")
+    return HEADER_SEP.join(parts)
+
+
+def shorten(text: str, width: int | None) -> str:
+    if width is None:
+        return text
+    if width <= 0:
+        return ""
+    if len(text) <= width:
+        return text
+    return textwrap.shorten(text, width=width, placeholder="…")
+
+
+def action_status(action: Action, *, completed: bool, ok: bool | None = None) -> str:
+    if not completed:
+        return STATUS["running"]
+    if ok is not None:
+        return STATUS["done"] if ok else STATUS["fail"]
+    detail = action.detail or {}
+    exit_code = detail.get("exit_code")
+    if isinstance(exit_code, int) and exit_code != 0:
+        return STATUS["fail"]
+    return STATUS["done"]
+
+
+def action_suffix(action: Action) -> str:
+    detail = action.detail or {}
+    exit_code = detail.get("exit_code")
+    if isinstance(exit_code, int) and exit_code != 0:
+        return f" (exit {exit_code})"
+    return ""
+
+
+def format_file_change_title(action: Action, *, command_width: int | None) -> str:
+    title = str(action.title or "")
+    detail = action.detail or {}
+
+    changes = detail.get("changes")
+    if isinstance(changes, list) and changes:
+        rendered: list[str] = []
+        for raw in changes:
+            path: str | None
+            kind: str | None
+            if isinstance(raw, dict):
+                path = raw.get("path")
+                kind = raw.get("kind")
+            else:
+                path = getattr(raw, "path", None)
+                kind = getattr(raw, "kind", None)
+            if not isinstance(path, str) or not path:
+                continue
+            verb = kind if isinstance(kind, str) and kind else "update"
+            rendered.append(f"{verb} {format_changed_file_path(path)}")
+
+        if rendered:
+            if len(rendered) > MAX_FILE_CHANGES_INLINE:
+                remaining = len(rendered) - MAX_FILE_CHANGES_INLINE
+                rendered = rendered[:MAX_FILE_CHANGES_INLINE] + [f"…({remaining} more)"]
+            inline = shorten(", ".join(rendered), command_width)
+            return f"files: {inline}"
+
+    fallback = title
+    relativized = relativize_path(fallback)
+    was_relativized = relativized != fallback
+    if was_relativized:
+        fallback = relativized
+    if (
+        fallback
+        and not (fallback.startswith("`") and fallback.endswith("`"))
+        and (was_relativized or os.sep in fallback or "/" in fallback)
+    ):
+        fallback = f"`{fallback}`"
+    return f"files: {shorten(fallback, command_width)}"
+
+
+def format_action_title(action: Action, *, command_width: int | None) -> str:
+    title = str(action.title or "")
+    kind = action.kind
+    if kind == "command":
+        title = shorten(title, command_width)
+        return f"`{title}`"
+    if kind == "tool":
+        title = shorten(title, command_width)
+        return f"tool: {title}"
+    if kind == "web_search":
+        title = shorten(title, command_width)
+        return f"searched: {title}"
+    if kind == "subagent":
+        title = shorten(title, command_width)
+        return f"subagent: {title}"
+    if kind == "file_change":
+        return format_file_change_title(action, command_width=command_width)
+    if kind in {"note", "warning"}:
+        return shorten(title, command_width)
+    return shorten(title, command_width)
+
+
+def format_action_line(
+    action: Action,
+    phase: str,
+    ok: bool | None,
+    *,
+    command_width: int | None,
+) -> str:
+    if phase != "completed":
+        status = STATUS["update"] if phase == "updated" else STATUS["running"]
+        return f"{status} {format_action_title(action, command_width=command_width)}"
+    status = action_status(action, completed=True, ok=ok)
+    suffix = action_suffix(action)
+    return (
+        f"{status} {format_action_title(action, command_width=command_width)}{suffix}"
+    )
+
+
+def render_event_cli(event: TakopiEvent) -> list[str]:
+    match event:
+        case StartedEvent(engine=engine):
+            return [str(engine)]
+        case ActionEvent() as action_event:
+            action = action_event.action
+            if action.kind == "turn":
+                return []
+            return [
+                format_action_line(
+                    action_event.action,
+                    action_event.phase,
+                    action_event.ok,
+                    command_width=MAX_PROGRESS_CMD_LEN,
+                )
+            ]
+        case _:
+            return []
+
+
+class MarkdownFormatter:
+    def __init__(
+        self,
+        *,
+        max_actions: int = 5,
+        command_width: int | None = MAX_PROGRESS_CMD_LEN,
+    ) -> None:
+        self.max_actions = max(0, int(max_actions))
+        self.command_width = command_width
+
+    def render_progress_parts(
+        self,
+        state: ProgressState,
+        *,
+        elapsed_s: float,
+        label: str = "working",
+    ) -> MarkdownParts:
+        step = state.action_count or None
+        header = format_header(
+            elapsed_s,
+            step,
+            label=label,
+            engine=state.engine,
+        )
+        body = self._assemble_body(self._format_actions(state))
+        return MarkdownParts(
+            header=header, body=body, footer=self._format_footer(state)
+        )
+
+    def render_final_parts(
+        self,
+        state: ProgressState,
+        *,
+        elapsed_s: float,
+        status: str,
+        answer: str,
+    ) -> MarkdownParts:
+        step = state.action_count or None
+        header = format_header(
+            elapsed_s,
+            step,
+            label=status,
+            engine=state.engine,
+        )
+        answer = (answer or "").strip()
+        body = answer if answer else None
+        return MarkdownParts(
+            header=header, body=body, footer=self._format_footer(state)
+        )
+
+    def _format_footer(self, state: ProgressState) -> str | None:
+        lines: list[str] = []
+        if state.context_line:
+            lines.append(state.context_line)
+        if state.resume_line:
+            lines.append(state.resume_line)
+        if not lines:
+            return None
+        return HARD_BREAK.join(lines)
+
+    def _format_actions(self, state: ProgressState) -> list[str]:
+        actions = list(state.actions)
+        actions = [] if self.max_actions == 0 else actions[-self.max_actions :]
+        return [
+            format_action_line(
+                action_state.action,
+                action_state.display_phase,
+                action_state.ok,
+                command_width=self.command_width,
+            )
+            for action_state in actions
+        ]
+
+    @staticmethod
+    def _assemble_body(lines: list[str]) -> str | None:
+        if not lines:
+            return None
+        return HARD_BREAK.join(lines)
+
+
+class MarkdownPresenter:
+    def __init__(self, *, formatter: MarkdownFormatter | None = None) -> None:
+        self._formatter = formatter or MarkdownFormatter()
+
+    def render_progress(
+        self,
+        state: ProgressState,
+        *,
+        elapsed_s: float,
+        label: str = "working",
+    ) -> RenderedMessage:
+        parts = self._formatter.render_progress_parts(
+            state, elapsed_s=elapsed_s, label=label
+        )
+        return RenderedMessage(text=assemble_markdown_parts(parts))
+
+    def render_final(
+        self,
+        state: ProgressState,
+        *,
+        elapsed_s: float,
+        status: str,
+        answer: str,
+    ) -> RenderedMessage:
+        parts = self._formatter.render_final_parts(
+            state, elapsed_s=elapsed_s, status=status, answer=answer
+        )
+        return RenderedMessage(text=assemble_markdown_parts(parts))

yee88/model.py

@@ -0,0 +1,77 @@
+"""Takopi domain model types (events, actions, resume tokens)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+type EngineId = str
+
+type ActionKind = Literal[
+    "command",
+    "tool",
+    "file_change",
+    "web_search",
+    "subagent",
+    "note",
+    "turn",
+    "warning",
+    "telemetry",
+]
+
+type TakopiEventType = Literal[
+    "started",
+    "action",
+    "completed",
+]
+
+type ActionPhase = Literal["started", "updated", "completed"]
+type ActionLevel = Literal["debug", "info", "warning", "error"]
+
+
+@dataclass(frozen=True, slots=True)
+class ResumeToken:
+    engine: EngineId
+    value: str
+
+
+@dataclass(frozen=True, slots=True)
+class Action:
+    id: str
+    kind: ActionKind
+    title: str
+    detail: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class StartedEvent:
+    type: Literal["started"] = field(default="started", init=False)
+    engine: EngineId
+    resume: ResumeToken
+    title: str | None = None
+    meta: dict[str, Any] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ActionEvent:
+    type: Literal["action"] = field(default="action", init=False)
+    engine: EngineId
+    action: Action
+    phase: ActionPhase
+    ok: bool | None = None
+    message: str | None = None
+    level: ActionLevel | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class CompletedEvent:
+    type: Literal["completed"] = field(default="completed", init=False)
+    engine: EngineId
+    ok: bool
+    answer: str
+    resume: ResumeToken | None = None
+    error: str | None = None
+    usage: dict[str, Any] | None = None
+
+
+type TakopiEvent = StartedEvent | ActionEvent | CompletedEvent

yee88/plugins.py

@@ -0,0 +1,312 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from importlib.metadata import EntryPoint, entry_points
+import re
+from typing import Any
+from collections.abc import Callable
+
+from .ids import ID_PATTERN, is_valid_id
+
+ENGINE_GROUP = "yee88.engine_backends"
+TRANSPORT_GROUP = "yee88.transport_backends"
+COMMAND_GROUP = "yee88.command_backends"
+
+_CANONICAL_NAME_RE = re.compile(r"[-_.]+")
+
+
+@dataclass(frozen=True, slots=True)
+class PluginLoadError:
+    group: str
+    name: str
+    value: str
+    distribution: str | None
+    error: str
+
+
+class PluginLoadFailed(RuntimeError):
+    def __init__(self, error: PluginLoadError) -> None:
+        super().__init__(error.error)
+        self.error = error
+
+
+class PluginNotFound(LookupError):
+    def __init__(self, group: str, name: str, available: Iterable[str]) -> None:
+        self.group = group
+        self.name = name
+        self.available = tuple(sorted(available))
+        message = f"{group} plugin {name!r} not found"
+        if self.available:
+            message = f"{message}. Available: {', '.join(self.available)}."
+        super().__init__(message)
+
+
+_LOAD_ERRORS: dict[tuple[str, str, str, str | None, str], PluginLoadError] = {}
+_LOADED: dict[tuple[str, str], Any] = {}
+
+
+def _error_key(error: PluginLoadError) -> tuple[str, str, str, str | None, str]:
+    return (error.group, error.name, error.value, error.distribution, error.error)
+
+
+def _record_error(error: PluginLoadError) -> None:
+    key = _error_key(error)
+    _LOAD_ERRORS.setdefault(key, error)
+
+
+def get_load_errors() -> tuple[PluginLoadError, ...]:
+    return tuple(_LOAD_ERRORS.values())
+
+
+def clear_load_errors(*, group: str | None = None, name: str | None = None) -> None:
+    if group is None and name is None:
+        _LOAD_ERRORS.clear()
+        return
+    remaining: dict[tuple[str, str, str, str | None, str], PluginLoadError] = {}
+    for key, error in _LOAD_ERRORS.items():
+        if group is not None and error.group != group:
+            remaining[key] = error
+            continue
+        if name is not None and error.name != name:
+            remaining[key] = error
+            continue
+    _LOAD_ERRORS.clear()
+    _LOAD_ERRORS.update(remaining)
+
+
+def reset_plugin_state() -> None:
+    clear_load_errors()
+    _LOADED.clear()
+
+
+def _select_entrypoints(group: str) -> list[EntryPoint]:
+    return list(entry_points().select(group=group))
+
+
+def entrypoint_distribution_name(ep: EntryPoint) -> str | None:
+    dist = getattr(ep, "dist", None)
+    if dist is None:
+        return None
+    name = getattr(dist, "name", None)
+    if name:
+        return name
+    metadata = getattr(dist, "metadata", None)
+    if metadata is None:
+        return None
+    try:
+        return metadata["Name"]
+    except (KeyError, TypeError):
+        return None
+
+
+def normalize_allowlist(allowlist: Iterable[str] | None) -> set[str] | None:
+    if allowlist is None:
+        return None
+    cleaned = {
+        _CANONICAL_NAME_RE.sub("-", item.strip()).lower()
+        for item in allowlist
+        if item and item.strip()
+    }
+    return cleaned or None
+
+
+def is_entrypoint_allowed(ep: EntryPoint, allowlist: set[str] | None) -> bool:
+    if allowlist is None:
+        return True
+    dist_name = entrypoint_distribution_name(ep)
+    if dist_name is None:
+        return False
+    return _CANONICAL_NAME_RE.sub("-", dist_name).lower() in allowlist
+
+
+def _entrypoint_sort_key(ep: EntryPoint) -> tuple[str, str, str]:
+    dist = entrypoint_distribution_name(ep) or ""
+    return (ep.name, dist, ep.value)
+
+
+def _normalize_reserved(reserved: Iterable[str] | None) -> set[str] | None:
+    if reserved is None:
+        return None
+    cleaned = {item.strip().lower() for item in reserved if item and item.strip()}
+    return cleaned or None
+
+
+def _discover_entrypoints(
+    group: str,
+    *,
+    allowlist: Iterable[str] | None = None,
+    reserved_ids: Iterable[str] | None = None,
+) -> tuple[dict[str, EntryPoint], dict[str, list[EntryPoint]]]:
+    allow = normalize_allowlist(allowlist)
+    reserved = _normalize_reserved(reserved_ids)
+    raw_eps = _select_entrypoints(group)
+    eps = [ep for ep in raw_eps if is_entrypoint_allowed(ep, allow)]
+    eps.sort(key=_entrypoint_sort_key)
+
+    by_name: dict[str, EntryPoint] = {}
+    duplicates: dict[str, list[EntryPoint]] = {}
+
+    for ep in eps:
+        if not is_valid_id(ep.name):
+            _record_error(
+                PluginLoadError(
+                    group=group,
+                    name=ep.name,
+                    value=ep.value,
+                    distribution=entrypoint_distribution_name(ep),
+                    error=(f"invalid plugin id {ep.name!r}; must match {ID_PATTERN}"),
+                )
+            )
+            continue
+        if reserved is not None and ep.name.lower() in reserved:
+            _record_error(
+                PluginLoadError(
+                    group=group,
+                    name=ep.name,
+                    value=ep.value,
+                    distribution=entrypoint_distribution_name(ep),
+                    error=f"reserved plugin id {ep.name!r} is not allowed",
+                )
+            )
+            continue
+        existing = by_name.get(ep.name)
+        if existing is None:
+            by_name[ep.name] = ep
+            continue
+        duplicates.setdefault(ep.name, [existing]).append(ep)
+
+    for name, items in duplicates.items():
+        providers = ", ".join(
+            sorted(
+                {entrypoint_distribution_name(item) or "<unknown>" for item in items}
+            )
+        )
+        message = f"duplicate plugin id {name!r} from {providers}"
+        for item in items:
+            _record_error(
+                PluginLoadError(
+                    group=group,
+                    name=name,
+                    value=item.value,
+                    distribution=entrypoint_distribution_name(item),
+                    error=message,
+                )
+            )
+        by_name.pop(name, None)
+
+    return by_name, duplicates
+
+
+def list_entrypoints(
+    group: str,
+    *,
+    allowlist: Iterable[str] | None = None,
+    reserved_ids: Iterable[str] | None = None,
+) -> list[EntryPoint]:
+    by_name, _ = _discover_entrypoints(
+        group, allowlist=allowlist, reserved_ids=reserved_ids
+    )
+    return [by_name[name] for name in sorted(by_name)]
+
+
+def list_ids(
+    group: str,
+    *,
+    allowlist: Iterable[str] | None = None,
+    reserved_ids: Iterable[str] | None = None,
+) -> list[str]:
+    return sorted(
+        ep.name
+        for ep in list_entrypoints(
+            group, allowlist=allowlist, reserved_ids=reserved_ids
+        )
+    )
+
+
+def load_entrypoint(
+    group: str,
+    name: str,
+    *,
+    allowlist: Iterable[str] | None = None,
+    validator: Callable[[Any, EntryPoint], None] | None = None,
+) -> Any:
+    by_name, duplicates = _discover_entrypoints(group, allowlist=allowlist)
+    if name in duplicates:
+        items = duplicates[name]
+        providers = ", ".join(
+            sorted(
+                {entrypoint_distribution_name(item) or "<unknown>" for item in items}
+            )
+        )
+        error = PluginLoadError(
+            group=group,
+            name=name,
+            value=items[0].value,
+            distribution=entrypoint_distribution_name(items[0]),
+            error=f"duplicate plugin id {name!r} from {providers}",
+        )
+        _record_error(error)
+        raise PluginLoadFailed(error)
+
+    ep = by_name.get(name)
+    if ep is None:
+        raise PluginNotFound(group, name, by_name)
+
+    key = (group, name)
+    if key in _LOADED:
+        return _LOADED[key]
+
+    try:
+        loaded = ep.load()
+        if validator is not None:
+            validator(loaded, ep)
+    except PluginLoadFailed:
+        raise
+    except Exception as exc:
+        error = PluginLoadError(
+            group=group,
+            name=ep.name,
+            value=ep.value,
+            distribution=entrypoint_distribution_name(ep),
+            error=str(exc),
+        )
+        _record_error(error)
+        raise PluginLoadFailed(error) from exc
+
+    _LOADED[key] = loaded
+    clear_load_errors(group=group, name=name)
+    return loaded
+
+
+def load_plugin_backend(
+    group: str,
+    name: str,
+    *,
+    allowlist: Iterable[str] | None = None,
+    validator: Callable[[Any, EntryPoint], None] | None = None,
+    kind_label: str,
+    required: bool = True,
+) -> Any | None:
+    try:
+        return load_entrypoint(
+            group,
+            name,
+            allowlist=allowlist,
+            validator=validator,
+        )
+    except PluginNotFound as exc:
+        if not required:
+            return None
+        if exc.available:
+            available = ", ".join(exc.available)
+            message = f"Unknown {kind_label} {name!r}. Available: {available}."
+        else:
+            message = f"Unknown {kind_label} {name!r}."
+        from .config import ConfigError
+
+        raise ConfigError(message) from exc
+    except PluginLoadFailed as exc:
+        from .config import ConfigError
+
+        raise ConfigError(f"Failed to load {kind_label} {name!r}: {exc}") from exc

yee88/presenter.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from .progress import ProgressState
+from .transport import RenderedMessage
+
+
+class Presenter(Protocol):
+    def render_progress(
+        self,
+        state: ProgressState,
+        *,
+        elapsed_s: float,
+        label: str = "working",
+    ) -> RenderedMessage: ...
+
+    def render_final(
+        self,
+        state: ProgressState,
+        *,
+        elapsed_s: float,
+        status: str,
+        answer: str,
+    ) -> RenderedMessage: ...