citrus-code 0.1.0__py3-none-any.whl

citrus_code/cli/session_files.py

@@ -0,0 +1,75 @@
+"""CLI session discovery, launch settings, and an OS-held writer lock."""
+
+import os
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+if os.name == "nt":
+    import msvcrt
+else:
+    import fcntl
+
+
+ShellName = Literal["bash", "powershell"]
+
+
+class LaunchSettings(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+
+    version: Literal[1] = 1
+    shell: ShellName
+    tools: list[str] = Field(min_length=1)
+
+
+def settings_path(session_path: Path) -> Path:
+    return session_path.with_suffix(".settings.json")
+
+
+def load_settings(session_path: Path) -> LaunchSettings | None:
+    path = settings_path(session_path)
+    if not path.exists():
+        return None
+    return LaunchSettings.model_validate_json(path.read_bytes())
+
+
+def save_settings(session_path: Path, settings: LaunchSettings) -> None:
+    with settings_path(session_path).open("x", encoding="utf-8", newline="\n") as file:
+        file.write(settings.model_dump_json(indent=2) + "\n")
+
+
+def session_paths(directory: Path) -> list[Path]:
+    if not directory.exists():
+        return []
+    return sorted(directory.glob("*.jsonl"), key=lambda p: p.stat().st_mtime_ns, reverse=True)
+
+
+@contextmanager
+def session_lease(path: Path) -> Iterator[None]:
+    """The persistent lock file is reused; the OS releases locks on process exit."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.with_suffix(".jsonl.lock").open("a+b") as file:
+        try:
+            if os.fstat(file.fileno()).st_size == 0:
+                file.write(b"\0")
+                file.flush()
+            file.seek(0)
+            if os.name == "nt":
+                msvcrt.locking(file.fileno(), msvcrt.LK_NBLCK, 1)
+            else:
+                fcntl.flock(file.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError as exc:
+            raise RuntimeError(
+                f"无法取得会话写入锁，文件可能已由另一个 CLI 使用：{path}"
+            ) from exc
+        try:
+            yield
+        finally:
+            file.seek(0)
+            if os.name == "nt":
+                msvcrt.locking(file.fileno(), msvcrt.LK_UNLCK, 1)
+            else:
+                fcntl.flock(file.fileno(), fcntl.LOCK_UN)

citrus_code/cli/terminal.py

@@ -0,0 +1,280 @@
+"""Concurrent terminal input and Agent output, with cooperative cancellation."""
+
+import asyncio
+import os
+import signal
+from collections.abc import Iterator
+from contextlib import aclosing, contextmanager
+from dataclasses import dataclass
+from types import FrameType
+
+from prompt_toolkit import PromptSession
+from prompt_toolkit.auto_suggest import AutoSuggestFromHistory
+from prompt_toolkit.completion import WordCompleter
+from prompt_toolkit.formatted_text import FormattedText
+from prompt_toolkit.key_binding import KeyBindings, KeyPressEvent
+from prompt_toolkit.output import ColorDepth
+from prompt_toolkit.patch_stdout import patch_stdout
+
+from ..agent.events import AgentEndEvent
+from ..coding.coding_session import CodingSession
+from ..coding.session.recovery import recover_pending_tools
+from .render import Console
+from .preview import MarkdownPreview
+from .theme import PROMPT_STYLE, clean_text
+
+
+HELP = """命令：
+  /help                 显示帮助
+  /status               当前运行状态、分支和队列状态
+  /history              显示当前分支的对话
+  /tree                 列出节点；* 表示当前节点
+  /checkout <节点ID>    切换分支，支持唯一的 ID 前缀；需要空闲且无排队消息
+  /steer <消息>         向正在运行的 Agent 追加引导消息
+  /follow <消息>        排队，等待 Agent 正常完成后处理
+  /clear-queue          清空尚未接纳的排队消息
+  /recover              空闲时补齐当前分支末尾缺失的工具结果
+  /abort                取消当前任务，等待收尾
+  /quit                 取消当前任务并退出
+运行时直接输入普通文字也会作为引导消息排队。
+Ctrl+C：运行时取消当前任务；空闲时退出。Ctrl+D：退出。
+Enter：发送。Alt+Enter 或 Ctrl+J：换行。Tab：补全命令。
+"""
+
+
+class PromptInterrupted(Exception):
+    """Keep Ctrl+C local to the input task instead of stopping asyncio itself."""
+
+
+@dataclass(frozen=True)
+class RunOutcome:
+    exit_code: int
+    fatal: bool = False
+
+
+async def run_turn(session: CodingSession, console: Console, text: str) -> RunOutcome:
+    end: AgentEndEvent | None = None
+    try:
+        console.begin_turn(text)
+        async with aclosing(session.prompt(text)) as stream:
+            async for event in stream:
+                console.event(event)
+                if isinstance(event, AgentEndEvent):
+                    end = event
+        if end is None:
+            raise RuntimeError("Agent 事件流结束，但未收到结束事件")
+        if end.reason == "aborted":
+            return RunOutcome(130)
+        return RunOutcome(0 if end.reason == "stop" else 1)
+    except Exception as exc:
+        console.finish_response()
+        console.note(f"[运行失败] {type(exc).__name__}: {exc}")
+        console.note("本次 CLI 将退出。请检查会话文件后使用 --resume 重新加载。")
+        return RunOutcome(2, fatal=True)
+    finally:
+        console.finish_response()
+        console.phase = "就绪"
+
+
+@contextmanager
+def cancel_on_sigint(session: CodingSession, console: Console) -> Iterator[None]:
+    loop = asyncio.get_running_loop()
+
+    def on_signal(signum: int, frame: FrameType | None) -> None:
+        loop.call_soon_threadsafe(session.abort)
+        loop.call_soon_threadsafe(console.note, "[取消] 正在等待任务收尾……")
+
+    previous = signal.signal(signal.SIGINT, on_signal)
+    try:
+        yield
+    finally:
+        signal.signal(signal.SIGINT, previous)
+
+
+class InteractiveTerminal:
+    def __init__(self, session: CodingSession, console: Console) -> None:
+        self.session = session
+        self.console = console
+        self._active: asyncio.Task[RunOutcome] | None = None
+
+    async def _stop_active(self) -> int:
+        task = self._active
+        if task is None:
+            return 0
+        if not task.done():
+            if self.session.is_running:
+                self.session.abort()
+            else:
+                # A newly scheduled turn may not have entered Agent.prompt yet.
+                task.cancel()
+        results = await asyncio.gather(task, return_exceptions=True)
+        self._active = None
+        result = results[0]
+        if isinstance(result, RunOutcome):
+            return result.exit_code if result.fatal else 0
+        if not isinstance(result, asyncio.CancelledError):
+            self.console.note(f"[任务退出失败] {result}")
+            return 2
+        return 0
+
+    def _command(self, text: str) -> bool:
+        command, _, argument = text.partition(" ")
+        argument = argument.strip()
+        active = self._active is not None
+        if command in ("/quit", "/exit"):
+            return True
+        if command == "/help":
+            self.console.note(HELP)
+        elif command == "/abort":
+            self.session.abort()
+            self.console.note("[取消] 正在等待任务收尾……" if active else "当前没有运行中的任务。")
+        elif command == "/status":
+            self.console.status(self.session)
+        elif command == "/history":
+            self.console.history(self.session)
+        elif command == "/tree":
+            self.console.tree(self.session)
+        elif command in ("/steer", "/follow"):
+            if not active:
+                raise ValueError("当前没有运行中的任务，请直接输入新问题。")
+            if not argument:
+                raise ValueError(f"用法：{command} <消息>")
+            if command == "/steer":
+                self.session.steer(argument)
+            else:
+                self.session.follow_up(argument)
+            self.console.note("[已排队] 消息将在运行时接纳后保存。")
+        elif command == "/clear-queue":
+            self.session.agent.clear_all_queues()
+            self.console.note("已清空尚未接纳的排队消息。")
+        elif command == "/checkout":
+            if not argument:
+                raise ValueError("用法：/checkout <节点ID或唯一前缀>")
+            candidates = [
+                entry.id for entry in self.session.session_manager.get_entries()
+                if entry.id.startswith(argument)
+            ]
+            if len(candidates) != 1:
+                raise ValueError("节点不存在或前缀不唯一，请用 /tree 查看。")
+            self.session.checkout(candidates[0])
+            self.console.note(f"已切换到 {candidates[0]}。项目文件仍保持当前磁盘状态。")
+        elif command == "/recover":
+            if active or self.session.has_queued_messages():
+                raise ValueError("恢复需要空闲且没有排队消息。")
+            count = recover_pending_tools(self.session.session_manager)
+            self.session.agent.replace_messages(
+                self.session.session_manager.build_context().messages
+            )
+            self.console.note(f"已补齐 {count} 条执行状态未知的工具结果。")
+        else:
+            raise ValueError("未知命令。输入 /help 查看帮助。")
+        return False
+
+    def _toolbar(self) -> FormattedText:
+        active = self._active is not None
+        estimate = self.session.compaction.last_estimate if self.session.compaction is not None else None
+        context = f"上下文约 {estimate / 1000:.1f}k / 1M" if estimate is not None else "1M 上下文 · 60% 压缩"
+        queued = " · 有排队消息" if self.session.has_queued_messages() else ""
+        return FormattedText([
+            ("class:status.busy" if active else "class:status", f" {self.console.phase}"),
+            ("class:status.dim", clean_text(f" · {self.console.model_name} · {context}{queued}")),
+            ("class:status.dim", "\n Enter 发送  Alt+Enter 换行  /help 命令  Ctrl+C 取消  Ctrl+D 退出"),
+        ])
+
+    async def run(self) -> int:
+        bindings = KeyBindings()
+
+        @bindings.add("enter")
+        def submit(event: KeyPressEvent) -> None:
+            buffer = event.current_buffer
+            if buffer.complete_state is not None:
+                if buffer.complete_state.current_completion is not None:
+                    buffer.complete_state = None
+                elif buffer.complete_state.completions:
+                    buffer.apply_completion(buffer.complete_state.completions[0])
+                return
+            buffer.validate_and_handle()
+
+        @bindings.add("escape", "enter")
+        @bindings.add("c-j")
+        def newline(event: KeyPressEvent) -> None:
+            event.current_buffer.insert_text("\n")
+
+        prompt = PromptSession[str](
+            message=FormattedText([("class:prompt", "› ")]),
+            interrupt_exception=PromptInterrupted,
+            completer=WordCompleter(
+                ["/help", "/status", "/history", "/tree", "/checkout", "/steer",
+                 "/follow", "/clear-queue", "/recover", "/abort", "/quit"],
+                sentence=True,
+            ),
+            complete_while_typing=False,
+            multiline=True,
+            prompt_continuation="  ",
+            show_frame=True,
+            style=PROMPT_STYLE,
+            color_depth=ColorDepth.DEPTH_1_BIT if "NO_COLOR" in os.environ else None,
+            key_bindings=bindings,
+            auto_suggest=AutoSuggestFromHistory(),
+            bottom_toolbar=self._toolbar,
+            placeholder=FormattedText([("class:placeholder", "描述任务，或输入 /help")]),
+            reserve_space_for_menu=1,
+            refresh_interval=0.25,
+            erase_when_done=True,
+        )
+        prompt.app.min_redraw_interval = 0.08
+        preview = MarkdownPreview(self.console, prompt)
+        reader: asyncio.Task[str] | None = None
+        with patch_stdout(raw=True):
+            try:
+                while True:
+                    if reader is None:
+                        reader = asyncio.create_task(prompt.prompt_async(show_frame=True))
+                    waiting: set[asyncio.Task[str] | asyncio.Task[RunOutcome]] = {reader}
+                    if self._active is not None:
+                        waiting.add(self._active)
+                    done, _ = await asyncio.wait(waiting, return_when=asyncio.FIRST_COMPLETED)
+
+                    if self._active is not None and self._active in done:
+                        outcome = self._active.result()
+                        self._active = None
+                        if outcome.fatal:
+                            return outcome.exit_code
+
+                    if reader not in done:
+                        continue
+                    completed_reader = reader
+                    reader = None
+                    try:
+                        text = completed_reader.result().strip()
+                    except PromptInterrupted:
+                        if self._active is None:
+                            return 0
+                        self.session.abort()
+                        self.console.note("[取消] 正在等待任务收尾……")
+                        continue
+                    except EOFError:
+                        return await self._stop_active()
+
+                    if not text:
+                        continue
+                    if text.startswith("/"):
+                        try:
+                            if self._command(text):
+                                return await self._stop_active()
+                        except ValueError as exc:
+                            self.console.note(f"[提示] {exc}")
+                        except Exception as exc:
+                            self.console.note(f"[会话操作失败] {type(exc).__name__}: {exc}")
+                            return 2
+                    elif self._active is not None:
+                        self.session.steer(text)
+                        self.console.note("[已排队] 引导消息等待接纳。")
+                    else:
+                        self._active = asyncio.create_task(run_turn(self.session, self.console, text))
+            finally:
+                if reader is not None:
+                    reader.cancel()
+                    await asyncio.gather(reader, return_exceptions=True)
+                await self._stop_active()
+                preview.close()

citrus_code/cli/theme.py

@@ -0,0 +1,51 @@
+"""Shared terminal colors, original pi emblem, and safe display text."""
+
+import re
+
+from prompt_toolkit.styles import Style
+from rich.theme import Theme
+
+
+ACCENT = "#d79570"
+MUTED = "#8b929c"
+BORDER = "#50555e"
+SUCCESS = "#98c379"
+ERROR = "#e06c75"
+INFO = "#82b9d6"
+
+LOGO = "\n".join((
+    "  ▄▄▄▄▄▄▄▄▄",
+    "  ▀██▀▀▀██▀",
+    "   ██   ██ ",
+    "   ██   ██▄",
+    "   ▀▀   ▀▀▀",
+))
+
+RICH_THEME = Theme({
+    "accent": f"bold {ACCENT}", "muted": MUTED, "border": BORDER,
+    "success": SUCCESS, "error": ERROR, "info": INFO,
+    "markdown.h1": f"bold {ACCENT}", "markdown.h2": f"bold {ACCENT}",
+    "markdown.h3": f"bold {INFO}", "markdown.code": f"{ACCENT} on #25272c",
+    "markdown.link": f"underline {INFO}", "markdown.link_url": MUTED,
+    "markdown.block_quote": MUTED,
+})
+
+PROMPT_STYLE = Style.from_dict({
+    "prompt": f"bold {ACCENT}", "placeholder": MUTED,
+    "frame.border": BORDER, "bottom-toolbar": "noreverse",
+    "bottom-toolbar.text": MUTED, "status": SUCCESS,
+    "status.busy": ACCENT, "status.dim": MUTED,
+    "completion-menu.completion": "bg:#25272c #c9cdd3",
+    "completion-menu.completion.current": f"bg:#45404a {ACCENT}",
+    "auto-suggestion": MUTED,
+})
+
+_CONTROL_SEQUENCES = re.compile(
+    r"\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)|[@-_])"
+    r"|[\x00-\x08\x0b-\x1f\x7f-\x9f]"
+)
+
+
+def clean_text(text: str) -> str:
+    """Keep newlines and tabs, but strip embedded terminal commands."""
+    return _CONTROL_SEQUENCES.sub("", text)

citrus_code/coding/coding_session.py

@@ -0,0 +1,287 @@
+import time
+
+from collections.abc import AsyncGenerator
+from contextlib import aclosing
+from ..agent.agent import Agent
+from ..agent.hooks import AgentHooks
+from ..agent.types import AgentTool
+from ..ai.provider import Provider
+from ..ai.types import (
+    ModelOptions,
+    ModelSpec,
+    SystemMessage,
+    Message,
+    TextContent,
+    ToolResultMessage,
+)
+from .session import SessionManager
+from .compaction import CompactionController
+
+from .history import get_pending_tool_calls
+
+from ..agent.events import (
+    AgentEvent,
+    AgentStartEvent,
+    AssistantMessageCommittedEvent,
+    ContextCompactedEvent,
+    MessageAcceptedEvent,
+    ToolExecutionEndEvent,
+)
+
+class CodingSession:
+    def __init__(
+        self,
+        provider: Provider,
+        model: ModelSpec,
+        tools: list[AgentTool],
+        session_manager: SessionManager,
+        system_prompt: str | None = None,
+        options: ModelOptions | None = None,
+        max_turns: int | None = None,
+        hooks: AgentHooks | None = None,
+        auto_compact: bool = True,
+    ) -> None:
+        if provider.id != model.provider:
+            raise ValueError(
+                "The provider does not match the model"
+            )
+
+        context = session_manager.build_context()
+
+        if context.provider is not None:
+            if (
+                context.provider != model.provider
+                or context.model_id != model.id
+            ):
+                raise ValueError(
+                    "The selected model does not match "
+                    "the model recorded in the session"
+                )
+        self._provider_id = model.provider
+        self._model_id = model.id
+        self.compaction = (
+            CompactionController(provider, model, session_manager)
+            if auto_compact else None
+        )
+        self.agent = Agent(
+            provider=provider,
+            model=model,
+            tools=tools,
+            options=options,
+            max_turns=max_turns,
+            hooks=hooks,
+            prepare_context=self.compaction.prepare if self.compaction is not None else None,
+        )
+
+        self.session_manager = session_manager
+
+        if context.provider is None:
+            self.session_manager.append_model_change(
+                provider=model.provider,
+                model_id=model.id,
+            )
+
+        if not context.messages and system_prompt is not None:
+            self.session_manager.append_message(
+                SystemMessage(
+                    content=system_prompt,
+                    timestamp=int(time.time() * 1000),
+                )
+            )
+
+        restored_context = (
+            self.session_manager.build_context()
+        )
+
+        self.agent.replace_messages(
+            restored_context.messages
+        )
+
+
+    async def prompt(
+            self,
+            text: str,
+    ) -> AsyncGenerator[AgentEvent, None]:
+        if self.agent.state.is_running:
+            raise RuntimeError(
+                "The coding session is already running"
+            )
+
+        context = self.session_manager.build_context()
+
+        if get_pending_tool_calls(context.messages):
+            raise RuntimeError(
+                "The session has unfinished tool calls. "
+                "Recover the session before continuing."
+            )
+
+        if context.messages != self.agent.state.messages:
+            raise RuntimeError(
+                "Agent history does not match the session. "
+                "Restore the session before continuing."
+            )
+
+        expected_leaf_id = self.session_manager.leaf_id
+
+        stream = self.agent.prompt(text)
+
+        async with aclosing(stream):
+            async for event in stream:
+                if(
+                    self.session_manager.leaf_id
+                    !=expected_leaf_id
+                ):
+                    raise RuntimeError(
+                        "The session branch changed "
+                        "while the agent was running"
+                    )
+
+                message: Message | None = None
+                task_start = False
+
+                if isinstance(event, AgentStartEvent):
+                    message = self.agent.state.messages[-1]
+                    task_start = True
+
+                elif isinstance(
+                    event,
+                    (
+                        MessageAcceptedEvent,
+                        AssistantMessageCommittedEvent,
+                    ),
+                ):
+                    message = event.message
+                    task_start = isinstance(event, MessageAcceptedEvent) and event.source == "follow_up"
+
+                elif isinstance(
+                    event,
+                    ToolExecutionEndEvent,
+                ):
+                    message = event.result.message
+
+                elif isinstance(event, ContextCompactedEvent):
+                    if self.compaction is None:
+                        raise RuntimeError("Received compaction without a controller")
+                    expected_leaf_id = self.compaction.commit(event)
+
+                if message is not None:
+                    expected_leaf_id = (
+                        self.session_manager.append_message(
+                            message, task_start=task_start,
+                        )
+                    )
+
+                yield event
+
+
+
+    @property
+    def is_running(self) -> bool:
+        return self.agent.state.is_running
+
+    def abort(self) -> None:
+        self.agent.abort()
+
+    def steer(self, text: str) -> None:
+        self.agent.steer(text)
+
+    def follow_up(self, text: str) -> None:
+        self.agent.follow_up(text)
+
+    def has_queued_messages(self) -> bool:
+        return self.agent.has_queued_messages()
+
+    def checkout(self, entry_id: str) -> None:
+        if self.is_running:
+            raise RuntimeError(
+                "Cannot switch branches while running"
+            )
+
+        if self.has_queued_messages():
+            raise RuntimeError(
+                "Cannot switch branches while queued messages exist"
+            )
+
+        context = (
+            self.session_manager.build_context_at(entry_id)
+        )
+
+        if (
+            context.provider != self._provider_id
+            or context.model_id != self._model_id
+        ):
+            raise ValueError(
+                "The target branch uses a different model"
+            )
+
+        if not context.messages:
+            raise ValueError(
+                "Select a branch containing messages"
+            )
+
+        if get_pending_tool_calls(context.messages):
+            raise ValueError(
+                "The target branch has unfinished tool calls"
+            )
+
+        self.session_manager.checkout(entry_id)
+
+        self.agent.replace_messages(
+            context.messages
+        )
+
+    def recover_pending_tools(self) -> int:
+        if self.is_running:
+            raise RuntimeError(
+                "Cannot recover while running"
+            )
+        if self.has_queued_messages():
+            raise RuntimeError("Cannot recover while queued messages exist")
+
+        context = self.session_manager.build_context()
+
+        if(
+            context.provider != self._provider_id
+            or context.model_id !=self._model_id
+        ):
+            raise ValueError(
+                "The session model does not match "
+                "the current agent"
+            )
+
+        pending_calls = get_pending_tool_calls(
+            context.messages
+        )
+
+        for call in pending_calls:
+            message = ToolResultMessage(
+                tool_call_id=call.id,
+                tool_name=call.name,
+                content=[
+                    TextContent(
+                        text=(
+                            "The session was interrupted before "
+                            "a result was recorded for this tool call. "
+                            "Its execution status is unknown: "
+                            "it may not have started, may have "
+                            "partially run, or may have completed. "
+                            "Inspect the actual state before "
+                            "deciding whether to retry."
+                        )
+                    ),
+                ],
+                is_error=True,
+                timestamp=int(time.time() * 1000),
+            )
+
+            self.session_manager.append_message(message)
+
+        restored_context = (
+            self.session_manager.build_context()
+        )
+
+        self.agent.replace_messages(
+            restored_context.messages
+        )
+
+        return len(pending_calls)