comate-cli 0.1.0__py3-none-any.whl

comate_cli/__init__.py

@@ -0,0 +1,5 @@
+"""Comate CLI package."""
+
+from comate_cli.main import main
+
+__all__ = ["main"]

comate_cli/__main__.py

@@ -0,0 +1,5 @@
+from comate_cli.main import main
+
+
+if __name__ == "__main__":
+    main()

comate_cli/main.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import atexit
+import asyncio
+import logging
+import signal
+import subprocess
+import sys
+import termios
+import threading
+
+logger = logging.getLogger(__name__)
+
+
+class _TerminalStateGuard:
+    """Best-effort tty restore guard for abnormal shutdown paths."""
+
+    def __init__(self) -> None:
+        self._fd: int | None = None
+        self._attrs: list[int | list[int | bytes]] | None = None
+        self._enabled = False
+
+        stdin = sys.__stdin__
+        if stdin is None:
+            return
+        if not stdin.isatty():
+            return
+        try:
+            self._fd = stdin.fileno()
+            self._attrs = termios.tcgetattr(self._fd)
+            self._enabled = True
+        except Exception as exc:
+            logger.debug(f"Terminal guard disabled: failed to snapshot tty attrs: {exc}")
+
+    def restore(self, *, reason: str) -> None:
+        if not self._enabled or self._fd is None or self._attrs is None:
+            return
+
+        try:
+            termios.tcsetattr(self._fd, termios.TCSANOW, self._attrs)
+            return
+        except Exception as exc:
+            logger.warning(f"tty restore failed ({reason}): {exc}", exc_info=True)
+
+        try:
+            subprocess.run(
+                ["stty", "sane"],
+                stdin=sys.__stdin__,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                check=False,
+            )
+        except Exception as exc:
+            logger.warning(f"stty sane fallback failed ({reason}): {exc}", exc_info=True)
+
+
+class _ShutdownNoiseGuard:
+    """Suppress KeyboardInterrupt noise in interpreter shutdown phase."""
+
+    def __init__(self) -> None:
+        self._shutdown_armed = False
+        self._orig_unraisablehook = sys.unraisablehook
+
+    def install(self) -> None:
+        sys.unraisablehook = self._unraisablehook
+
+    def begin_shutdown(self) -> None:
+        if self._shutdown_armed:
+            return
+        self._shutdown_armed = True
+        self._ignore_sigint_until_exit()
+
+    def _ignore_sigint_until_exit(self) -> None:
+        if threading.current_thread() is not threading.main_thread():
+            return
+        try:
+            signal.signal(signal.SIGINT, signal.SIG_IGN)
+            logger.debug("SIGINT is now ignored for final shutdown")
+        except Exception as exc:
+            logger.debug(f"Failed to switch SIGINT to SIG_IGN during shutdown: {exc}")
+
+    def _unraisablehook(self, unraisable: object) -> None:
+        exc_value = getattr(unraisable, "exc_value", None)
+        if self._shutdown_armed and isinstance(exc_value, KeyboardInterrupt):
+            logger.debug("Suppressed unraisable KeyboardInterrupt during shutdown")
+            return
+
+        self._orig_unraisablehook(unraisable)
+
+
+def _parse_args(argv: list[str]) -> tuple[bool, str | None]:
+    rpc_stdio = False
+    session_id: str | None = None
+    for arg in argv:
+        if arg == "--rpc-stdio":
+            rpc_stdio = True
+            continue
+        if arg.startswith("-"):
+            continue
+        if session_id is None:
+            session_id = arg
+    return rpc_stdio, session_id
+
+
+def main(argv: list[str] | None = None) -> None:
+    run_argv = list(argv) if argv is not None else sys.argv[1:]
+
+    noise_guard = _ShutdownNoiseGuard()
+    noise_guard.install()
+
+    term_guard = _TerminalStateGuard()
+    atexit.register(term_guard.restore, reason="atexit")
+    atexit.register(noise_guard.begin_shutdown)
+
+    from comate_cli.terminal_agent.app import run
+
+    rpc_stdio, session_id = _parse_args(run_argv)
+    try:
+        asyncio.run(run(rpc_stdio=rpc_stdio, session_id=session_id))
+    except KeyboardInterrupt:
+        noise_guard.begin_shutdown()
+    finally:
+        noise_guard.begin_shutdown()
+        term_guard.restore(reason="main-finally")
+
+
+if __name__ == "__main__":
+    main()

comate_cli/terminal_agent/__init__.py

@@ -0,0 +1,2 @@
+"""Terminal agent example package."""
+

comate_cli/terminal_agent/animations.py

@@ -0,0 +1,283 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Sequence
+from enum import Enum
+
+from rich.console import RenderableType
+from rich.text import Text
+
+from comate_agent_sdk.agent.events import StopEvent, TextEvent, ToolCallEvent, ToolResultEvent, UserQuestionEvent
+
+DEFAULT_STATUS_PHRASES: tuple[str, ...] = (
+    "Vibing...",
+    "Thinking...",
+    "Reasoning...",
+    "Planning next move...",
+    "Reading context...",
+    "Connecting dots...",
+    "Synthesizing signal...",
+    "Spotting edge cases...",
+    "Checking assumptions...",
+    "Tracing dependencies...",
+    "Drafting response...",
+    "Polishing details...",
+    "Validating flow...",
+    "Cross-checking facts...",
+    "Refining intent...",
+    "Mapping tools...",
+    "Building confidence...",
+    "Stitching answer...",
+    "Finalizing output...",
+    "Almost there...",
+)
+
+BREATH_DOT_COLORS: tuple[str, ...] = (
+    "#4B5563",  # 暗灰
+    "#6B7280",  # 灰
+    "#9CA3AF",  # 浅灰
+    "#D1D5DB",  # 极浅灰
+    "#9CA3AF",  # 回退
+    "#6B7280",  # 回退
+)
+BREATH_DOT_GLYPHS: tuple[str, ...] = (
+    "○",
+    "●",
+)
+
+
+def breathing_dot_color(frame: int) -> str:
+    """Return the breathing dot color for a given animation frame."""
+    phase = (frame // 4) % len(BREATH_DOT_COLORS)
+    return BREATH_DOT_COLORS[phase]
+
+
+def breathing_dot_glyph(now_monotonic: float | None = None) -> str:
+    """Return the breathing dot glyph that switches once per second."""
+    now = time.monotonic() if now_monotonic is None else now_monotonic
+    phase = int(now) % len(BREATH_DOT_GLYPHS)
+    return BREATH_DOT_GLYPHS[phase]
+
+
+def _lerp_rgb(
+    start_rgb: tuple[int, int, int],
+    end_rgb: tuple[int, int, int],
+    ratio: float,
+) -> tuple[int, int, int]:
+    clamped = max(0.0, min(1.0, ratio))
+    r = int(start_rgb[0] + (end_rgb[0] - start_rgb[0]) * clamped)
+    g = int(start_rgb[1] + (end_rgb[1] - start_rgb[1]) * clamped)
+    b = int(start_rgb[2] + (end_rgb[2] - start_rgb[2]) * clamped)
+    return r, g, b
+
+
+def _cyan_sweep_text(
+    content: str,
+    frame: int,
+) -> Text:
+    """Create a cyan sweep (moving highlight) effect over text."""
+    text = Text()
+    if not content:
+        return text
+    total = len(content)
+    base_rgb = (95, 155, 190)
+    mid_rgb = (120, 200, 235)
+    high_rgb = (210, 245, 255)
+
+    window = max(3, total // 5)
+    cycle = max(total + window * 2, 16)
+    center = (frame % cycle) - window
+
+    for idx, ch in enumerate(content):
+        distance = abs(idx - center)
+        if distance <= window:
+            glow = 1.0 - (distance / window)
+            if glow >= 0.6:
+                r, g, b = _lerp_rgb(mid_rgb, high_rgb, (glow - 0.6) / 0.4)
+            else:
+                r, g, b = _lerp_rgb(base_rgb, mid_rgb, glow / 0.6)
+        else:
+            r, g, b = base_rgb
+        text.append(ch, style=f"bold rgb({r},{g},{b})")
+    return text
+
+
+class SubmissionAnimator:
+    """Animated status line shown after user submits a message."""
+
+    def __init__(
+        self,
+        console: object | None = None,
+        phrases: Sequence[str] | None = None,
+        refresh_interval: float = 0.12,
+        min_phrase_seconds: float = 2.4,
+        max_phrase_seconds: float = 3.0,
+    ) -> None:
+        del console
+        self._phrases = tuple(phrases) if phrases else DEFAULT_STATUS_PHRASES
+        self._refresh_interval = refresh_interval
+        self._min_phrase_seconds = max(0.6, min_phrase_seconds)
+        self._max_phrase_seconds = max(self._min_phrase_seconds, max_phrase_seconds)
+        self._status_hint: str | None = None
+        self._task: asyncio.Task[None] | None = None
+        self._stop_event: asyncio.Event | None = None
+        self._frame = 0
+        self._phrase_idx = 0
+        self._phrase_started_at_monotonic = 0.0
+        self._phrase_duration_seconds = 0.0
+        self._dirty = False
+        self._is_active = False
+
+    def _compute_phrase_duration(self, phrase_idx: int) -> float:
+        # Deterministic per phrase, bounded by [min, max], and never exceeds 3s by default.
+        span = self._max_phrase_seconds - self._min_phrase_seconds
+        if span <= 0:
+            return self._max_phrase_seconds
+        step = (phrase_idx * 17 + 11) % 100
+        ratio = step / 100.0
+        return self._min_phrase_seconds + span * ratio
+
+    async def start(self) -> None:
+        if self._task is not None:
+            return
+        self._frame = 0
+        self._phrase_idx = 0
+        self._phrase_started_at_monotonic = time.monotonic()
+        self._phrase_duration_seconds = self._phrase_duration_for_idx(0)
+        self._is_active = True
+        self._dirty = True
+        self._stop_event = asyncio.Event()
+        self._task = asyncio.create_task(self._run(), name="submission-animator")
+
+    def set_status_hint(self, hint: str | None) -> None:
+        if hint is None:
+            if self._status_hint is not None:
+                self._dirty = True
+            self._status_hint = None
+            return
+        normalized = hint.strip()
+        new_value = normalized or None
+        if new_value != self._status_hint:
+            self._dirty = True
+        self._status_hint = new_value
+
+    async def stop(self) -> None:
+        if self._task is None:
+            return
+        assert self._stop_event is not None
+        self._stop_event.set()
+        try:
+            await self._task
+        finally:
+            self._task = None
+            self._stop_event = None
+            self._is_active = False
+            self._dirty = True
+
+    @property
+    def is_active(self) -> bool:
+        return self._is_active
+
+    def consume_dirty(self) -> bool:
+        dirty = self._dirty
+        self._dirty = False
+        return dirty
+
+    def renderable(self) -> RenderableType:
+        if not self._is_active:
+            return Text("")
+
+        phrase = self._status_hint if self._status_hint else self._phrases[self._phrase_idx]
+        dot_color = breathing_dot_color(self._frame)
+        now_monotonic = time.monotonic()
+        dot = Text(
+            f"{breathing_dot_glyph(now_monotonic)} ",
+            style=f"bold {dot_color}",
+        )
+        sweep = _cyan_sweep_text(phrase, frame=self._frame)
+        return Text.assemble(dot, sweep)
+
+    async def _run(self) -> None:
+        assert self._stop_event is not None
+        while not self._stop_event.is_set():
+            now = time.monotonic()
+            if now - self._phrase_started_at_monotonic >= self._phrase_duration_seconds:
+                self._phrase_idx = (self._phrase_idx + 1) % len(self._phrases)
+                self._phrase_started_at_monotonic = now
+                self._phrase_duration_seconds = self._phrase_duration_for_idx(self._phrase_idx)
+            self._frame += 1
+            self._dirty = True
+            try:
+                await asyncio.wait_for(self._stop_event.wait(), timeout=self._refresh_interval)
+            except TimeoutError:
+                continue
+
+    def _phrase_duration_for_idx(self, phrase_idx: int) -> float:
+        return self._compute_phrase_duration(phrase_idx)
+
+
+class AnimationPhase(str, Enum):
+    IDLE = "idle"
+    SUBMITTING = "submitting"
+    TOOL_RUNNING = "tool_running"
+    ASSISTANT_STREAMING = "assistant_streaming"
+    DONE = "done"
+
+
+class StreamAnimationController:
+    """Controls submission animation lifecycle across stream events."""
+
+    def __init__(
+        self,
+        animator: SubmissionAnimator,
+        *,
+        min_visible_seconds: float = 0.35,
+    ) -> None:
+        self._animator = animator
+        self._min_visible_seconds = max(0.0, float(min_visible_seconds))
+        self._phase = AnimationPhase.IDLE
+        self._started_at_monotonic = 0.0
+        self._stopped = True
+        self._active_tool_call_ids: set[str] = set()
+
+    @property
+    def phase(self) -> AnimationPhase:
+        return self._phase
+
+    async def start(self) -> None:
+        self._active_tool_call_ids.clear()
+        self._animator.set_status_hint(None)
+        self._started_at_monotonic = time.monotonic()
+        self._phase = AnimationPhase.SUBMITTING
+        self._stopped = False
+        await self._animator.start()
+
+    async def shutdown(self) -> None:
+        await self._stop_if_needed(AnimationPhase.DONE)
+
+    async def on_event(self, event: object) -> None:
+        if self._stopped:
+            return
+
+        if isinstance(event, ToolCallEvent):
+            self._active_tool_call_ids.add(event.tool_call_id)
+            return
+
+        if isinstance(event, ToolResultEvent):
+            self._active_tool_call_ids.discard(event.tool_call_id)
+            return
+
+        if isinstance(event, UserQuestionEvent) or isinstance(event, StopEvent):
+            await self._stop_if_needed(AnimationPhase.DONE)
+
+    async def _stop_if_needed(self, next_phase: AnimationPhase) -> None:
+        if self._stopped:
+            return
+        elapsed = time.monotonic() - self._started_at_monotonic
+        if elapsed < self._min_visible_seconds:
+            await asyncio.sleep(self._min_visible_seconds - elapsed)
+        self._animator.set_status_hint(None)
+        await self._animator.stop()
+        self._stopped = True
+        self._phase = next_phase

comate_cli/terminal_agent/app.py

@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import signal
+import sys
+import threading
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+from rich.console import Console
+
+from comate_agent_sdk import Agent
+from comate_agent_sdk.agent import AgentConfig, ChatSession
+from comate_agent_sdk.context import EnvOptions
+from comate_agent_sdk.tools import tool
+
+from comate_cli.terminal_agent.event_renderer import EventRenderer
+from comate_cli.terminal_agent.logo import print_logo
+from comate_cli.terminal_agent.rpc_stdio import StdioRPCBridge
+from comate_cli.terminal_agent.status_bar import StatusBar
+from comate_cli.terminal_agent.tui import TerminalAgentTUI
+
+console = Console()
+logger = logging.getLogger(__name__)
+
+
+def _flush_langfuse_if_configured() -> None:
+    """Flush Langfuse pending events synchronously to prevent atexit thread-join errors on Ctrl+C."""
+    try:
+        from langfuse import get_client
+        get_client().flush()
+    except Exception:
+        pass
+
+
+@contextmanager
+def _sigint_guard() -> Iterator[None]:
+    """Temporarily ignore SIGINT in critical shutdown windows."""
+    if os.name == "nt":
+        yield
+        return
+    if threading.current_thread() is not threading.main_thread():
+        yield
+        return
+
+    try:
+        previous_handler = signal.getsignal(signal.SIGINT)
+        signal.signal(signal.SIGINT, signal.SIG_IGN)
+        logger.debug("SIGINT guard enabled for shutdown")
+    except Exception as exc:
+        logger.debug(f"Failed to enable SIGINT guard, fallback to unguarded shutdown: {exc}")
+        yield
+        return
+
+    try:
+        yield
+    finally:
+        try:
+            signal.signal(signal.SIGINT, previous_handler)
+            logger.debug("SIGINT guard restored")
+        except Exception as exc:
+            logger.warning(f"Failed to restore SIGINT handler: {exc}", exc_info=True)
+
+
+async def _shutdown_session(session: ChatSession, *, label: str) -> None:
+    start = time.monotonic()
+    try:
+        shutdown = getattr(session, "shutdown", None)
+        if callable(shutdown):
+            await shutdown()
+        else:
+            await session.close()
+    except Exception as exc:
+        logger.warning(f"Session shutdown failed ({label}): {exc}", exc_info=True)
+        return
+
+    elapsed = time.monotonic() - start
+    logger.info(f"Session shutdown completed ({label}) in {elapsed:.3f}s")
+
+
+async def _graceful_shutdown(*sessions: ChatSession) -> None:
+    unique_sessions: list[ChatSession] = []
+    seen_ids: set[int] = set()
+    for session in sessions:
+        sid = id(session)
+        if sid in seen_ids:
+            continue
+        seen_ids.add(sid)
+        unique_sessions.append(session)
+
+    start = time.monotonic()
+    with _sigint_guard():
+        for index, session in enumerate(unique_sessions, start=1):
+            label = f"{index}/{len(unique_sessions)} session_id={session.session_id}"
+            await _shutdown_session(session, label=label)
+        _flush_langfuse_if_configured()
+
+    elapsed = time.monotonic() - start
+    logger.info(f"Graceful shutdown completed in {elapsed:.3f}s")
+
+
+@tool("Add two numbers 涉及到加法运算 必须使用这个工具")
+async def add(a: int, b: int) -> int:
+    return a + b
+
+
+def _build_agent() -> Agent:
+    context7_api_key = os.getenv("CONTEXT7_API_KEY")
+    exa_api_key = os.getenv("EXA_API_KEY")
+
+    exa_tools = (
+        "web_search_exa,"
+        "web_search_advanced_exa,"
+        "get_code_context_exa,"
+        "crawling_exa"
+    )
+    exa_url = "https://mcp.exa.ai/mcp"
+    if exa_api_key:
+        exa_url = f"{exa_url}?exaApiKey={exa_api_key}&tools={exa_tools}"
+    else:
+        exa_url = f"{exa_url}?tools={exa_tools}"
+
+    return Agent(
+        config=AgentConfig(
+            role="software_engineering",
+            env_options=EnvOptions(system_env=True, git_env=True),
+            use_streaming_task=True,  # 启用流式 Task（实时显示嵌套工具调用）
+            mcp_servers={
+                "context7": {
+                    "type": "http",
+                    "url": "https://mcp.context7.com/mcp",
+                    "headers": {
+                        "CONTEXT7_API_KEY": context7_api_key,
+                    },
+                },
+                "wiretext": {
+                    "command": "npx",
+                    "args": ["-y", "@wiretext/mcp"]
+                },
+                "exa_search": {
+                    "type": "http",
+                    "url": exa_url,
+                },
+            },
+        )
+    )
+
+
+def _resolve_session(agent: Agent, session_id: str | None) -> tuple[ChatSession, str]:
+    if session_id:
+        return ChatSession.resume(agent, session_id=session_id), "resume"
+    return ChatSession(agent), "new"
+
+
+def _format_exit_usage_line(usage: object) -> str:
+    total_prompt_tokens = int(getattr(usage, "total_prompt_tokens", 0) or 0)
+    total_prompt_cached_tokens = int(
+        getattr(usage, "total_prompt_cached_tokens", 0) or 0
+    )
+    total_completion_tokens = int(getattr(usage, "total_completion_tokens", 0) or 0)
+    total_reasoning_tokens = int(getattr(usage, "total_reasoning_tokens", 0) or 0)
+
+    input_tokens = max(total_prompt_tokens - total_prompt_cached_tokens, 0)
+    total_tokens = input_tokens + total_completion_tokens
+
+    reasoning_part = f" (reasoning {total_reasoning_tokens:,})" if total_reasoning_tokens > 0 else ""
+    return (
+        f"Token usage: total={total_tokens:,} "
+        f"input={input_tokens:,} (+ {total_prompt_cached_tokens:,} cached) "
+        f"output={total_completion_tokens:,}{reasoning_part}"
+    )
+
+
+async def _preload_mcp_in_tui(session: ChatSession, renderer: EventRenderer) -> None:
+    """在 TUI 内部异步加载 MCP，通过 renderer 输出状态消息."""
+    if not session._agent.options.mcp_servers:
+        return
+    try:
+        await session._agent.ensure_mcp_tools_loaded()
+    except Exception as e:
+        renderer.append_system_message(f"MCP init failed: {e}", severity="error")
+        return
+
+    mgr = session._agent._mcp_manager
+    if mgr is None:
+        return
+
+    loaded = mgr.tool_infos
+    if loaded:
+        count = len(loaded)
+        aliases = sorted({i.server_alias for i in loaded})
+        renderer.append_system_message(f"MCP loaded: {', '.join(aliases)} ({count} tools)")
+
+
+async def run(*, rpc_stdio: bool = False, session_id: str | None = None) -> None:
+    agent = _build_agent()
+    session, mode = _resolve_session(agent, session_id)
+
+    if rpc_stdio:
+        bridge = StdioRPCBridge(session)
+        try:
+            await bridge.run()
+        finally:
+            await _graceful_shutdown(session)
+        return
+
+    print_logo(console)
+    # 不再阻塞等待 MCP，改为 TUI 内部异步加载
+    status_bar = StatusBar(session)
+    status_bar.set_mode(session.get_mode())
+    if mode == "resume":
+        await status_bar.refresh()
+
+    renderer = EventRenderer(project_root=Path.cwd())
+
+    # 配置 TUI logging handler（将 SDK 日志输出到 TUI）
+    from comate_cli.terminal_agent.logging_adapter import setup_tui_logging
+    setup_tui_logging(renderer)
+
+    tui = TerminalAgentTUI(session, status_bar, renderer)
+    tui.add_resume_history(mode)
+
+    # 把 MCP loading 作为 TUI 内部初始化任务
+    async def _mcp_loader() -> None:
+        await _preload_mcp_in_tui(session, renderer)
+
+    usage_line: str | None = None
+    active_session = session
+    try:
+        await tui.run(mcp_init=_mcp_loader)
+        active_session = tui.session
+        try:
+            usage = await active_session.get_usage()
+            usage_line = _format_exit_usage_line(usage)
+        except Exception as exc:
+            logger.warning(
+                f"Failed to collect usage for exit summary: {exc}",
+                exc_info=True,
+            )
+    finally:
+        if active_session is session:
+            await _graceful_shutdown(active_session)
+        else:
+            await _graceful_shutdown(session, active_session)
+
+    if usage_line:
+        console.print(f"[dim]{usage_line}[/]")
+
+    console.print(
+        f"[dim]To continue this session, run [bold cyan]comate resume "
+        f"{active_session.session_id}[/][/]"
+    )
+
+
+if __name__ == "__main__":
+    argv_session_id = sys.argv[1] if len(sys.argv) > 1 else None
+    asyncio.run(run(session_id=argv_session_id))