synapse-cli-agent 0.1.13__py3-none-any.whl

synapse/tools/session_tools.py

@@ -0,0 +1,204 @@
+"""跨会话引用工具 —— 让 Agent 能查阅其他会话的对话历史。
+
+通过工厂函数 ``build_session_tools`` 创建工具，注入 SessionStore 和
+checkpoint 路径依赖。
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any
+
+from langchain.tools import ToolRuntime
+from langchain_core.tools import tool
+
+from synapse.tool_output.repository import ToolOutputRepository
+
+
+def build_tool_result_reader_tool(tool_output_db_path: Path | str) -> Any:
+    """Create the guarded reader for reversible transformed output."""
+    results = ToolOutputRepository(tool_output_db_path)
+
+    @tool
+    def read_tool_result(
+        runtime: ToolRuntime,
+        ref: str,
+        offset: int = 0,
+        limit: int = 200,
+        query: str = "",
+        max_results: int = 20,
+        context_lines: int = 2,
+    ) -> str:
+        """读取当前会话被压缩工具输出的原文。
+
+        支持精确分页，或通过 query 在原文中进行本地关键词召回。仅接受工具
+        输出提供的 ``tool-output://...`` 引用，不能读取任意文件。
+
+        Args:
+            ref: 工具输出中的 ``tool-output://`` 引用。
+            offset: 精确分页的起始行号（0-indexed）。
+            limit: 精确分页行数，默认 200，最大 500。
+            query: 可选关键词；提供后返回相关片段。
+            max_results: 查询模式最多返回的命中行数，最大 50。
+            context_lines: 每个命中的相邻上下文行数，最大 10。
+        """
+        config = dict(getattr(runtime, "config", None) or {})
+        configurable = dict(config.get("configurable") or {})
+        thread_id = str(configurable.get("thread_id") or "")
+        record = results.get(ref, expected_thread_id=thread_id or None)
+        if record is None:
+            return "工具结果引用未找到、已损坏或无权读取。"
+        started = time.perf_counter()
+        if query.strip():
+            matches = results.search(
+                ref,
+                query,
+                expected_thread_id=thread_id or None,
+                max_results=min(50, max(1, int(max_results))),
+                context_lines=min(10, max(0, int(context_lines))),
+            )
+            if not matches:
+                return f"工具: {record.tool_name}\n引用: {record.ref}\n(没有匹配 {query!r} 的行)"
+            body = "\n".join(f"{line_no}: {line}" for line_no, line in matches)
+            result = (
+                f"工具: {record.tool_name}\n引用: {record.ref}\n查询: {query}\n{'─' * 40}\n{body}"
+            )
+            results.record_retrieval(
+                thread_id=thread_id or record.thread_id,
+                ref=ref,
+                mode="query",
+                returned_bytes=len(result.encode("utf-8")),
+                duration_ms=(time.perf_counter() - started) * 1000,
+            )
+            return result
+        start = max(0, int(offset))
+        count = min(500, max(1, int(limit)))
+        lines = record.content.splitlines()
+        selected = lines[start : start + count]
+        body = "\n".join(selected) or "(empty result)"
+        end = start + len(selected)
+        suffix = (
+            f"\n\n[还有 {len(lines) - end} 行，使用 offset={end} 继续读取]"
+            if end < len(lines)
+            else ""
+        )
+        result = (
+            f"工具: {record.tool_name}\n状态: {record.status}\n引用: {record.ref}\n"
+            f"行: {start}-{max(start, end - 1)} / {max(0, len(lines) - 1)}\n"
+            f"{'─' * 40}\n{body}{suffix}"
+        )
+        results.record_retrieval(
+            thread_id=thread_id or record.thread_id,
+            ref=ref,
+            mode="pagination",
+            returned_bytes=len(result.encode("utf-8")),
+            duration_ms=(time.perf_counter() - started) * 1000,
+        )
+        return result
+
+    return read_tool_result
+
+
+def build_session_tools(
+    sessions_path: Path | str,
+    checkpoint_path: Path | str,
+    tool_output_db_path: Path | str | None = None,
+) -> list[Any]:
+    """创建会话查阅工具列表。
+
+    Args:
+        sessions_path: sessions.sqlite 路径
+        checkpoint_path: checkpoints.sqlite 路径
+    Returns:
+        [list_sessions, read_session]
+    """
+    from synapse.sessions.store import SessionStore, format_session_table
+
+    store = SessionStore(sessions_path)
+    ckpt = Path(checkpoint_path)
+
+    @tool
+    def list_sessions(query: str = "", limit: int = 20) -> str:
+        """列出本地会话记录，支持按标题/ID 模糊搜索。
+
+        **默认禁止调用**。仅当用户明确要求查阅、搜索、对比其他会话时使用
+        （例如“列出最近会话”“找之前那个 bug 讨论”“看看某某会话”）。
+        闲聊、问候、普通编码/排障、意图不明、仅为“多了解上下文”时一律不要调用。
+
+        返回会话基本信息，不包含对话内容；获取对话内容请用 read_session。
+
+        Args:
+            query: 可选，按标题或 thread_id 搜索关键词。为空时返回最近会话。
+            limit: 最大返回数，默认 20。
+        """
+        if query.strip():
+            items = store.search(query, limit=limit)
+        else:
+            items = store.list_nonempty(limit=limit)
+        if not items:
+            return "(没有找到匹配的会话记录)"
+        return format_session_table(items)
+
+    @tool
+    def read_session(
+        thread_id: str,
+        max_turns: int = 0,
+        include_summary: bool = True,
+    ) -> str:
+        """读取指定会话的对话历史内容。
+
+        **默认禁止调用**。仅当用户明确要求读取某个会话内容时使用
+        （通常先由 list_sessions 得到 thread_id，或用户直接给出会话 ID）。
+        闲聊、问候、普通任务、未指明需要跨会话上下文时不要主动调用。
+
+        按轮次切分对话，每轮 = 一条用户消息 + 后续 AI/工具消息。
+        可指定只取最后 N 轮，避免上下文过长。
+
+        Args:
+            thread_id: 会话 ID（通过 list_sessions 获取）。
+            max_turns: 返回最近 N 轮。0 表示返回全部轮次。
+            include_summary: 是否在开头附带会话元信息。
+        """
+        from synapse.sessions.transcript import (
+            format_turns_as_text,
+            load_messages_from_sqlite_file,
+            split_messages_by_turns,
+        )
+
+        info = store.get(thread_id)
+        if info is None:
+            return (
+                f"会话未找到: {thread_id}\n"
+                f"提示：使用 list_sessions 查看可用会话列表，"
+                f"确保 thread_id 完全匹配。"
+            )
+
+        messages = load_messages_from_sqlite_file(ckpt, thread_id)
+        if not messages:
+            return (
+                f"会话 {thread_id} 没有对话记录。\n"
+                f"标题: {info.title}\n"
+                f"创建: {info.created_at}  更新: {info.updated_at}\n"
+                f"模型: {info.binding().display()}"
+            )
+
+        turns = split_messages_by_turns(messages)
+        body = format_turns_as_text(turns, max_turns=max_turns)
+
+        if include_summary:
+            bind = info.binding()
+            turns_display = min(max_turns, len(turns)) if max_turns else len(turns)
+            header = (
+                f"会话: {info.thread_id}\n"
+                f"标题: {info.title}\n"
+                f"模型: {bind.display()}\n"
+                f"轮次: {len(turns)}（显示 {turns_display} 轮）\n"
+                f"创建: {info.created_at}  更新: {info.updated_at}\n"
+                f"{'─' * 40}\n\n"
+            )
+            return header + body
+        return body
+
+    output_db = tool_output_db_path or (Path(sessions_path).parent / "tool-outputs.sqlite")
+    return [list_sessions, read_session, build_tool_result_reader_tool(output_db)]

synapse/ui/__init__.py

@@ -0,0 +1,10 @@
+"""UI package.
+
+- CLI rendering: Rich (``stream.RichStreamSink``)
+- TUI rendering: Textual (``tui.TextualStreamSink``)
+- Shared port: ``sink.StreamSink`` consumed by ``stream.stream_agent``
+"""
+
+from synapse.ui.sink import StreamSink
+
+__all__ = ["StreamSink"]

synapse/ui/bottombar/__init__.py

@@ -0,0 +1,73 @@
+"""Extensible bottombar package.
+
+Public layout/registry API lives in ``core``; built-in components live under
+``components/`` and are registered via ``DEFAULT_COMPONENT_INSTALLERS``.
+
+Add a component
+---------------
+1. Create ``components/foo.py`` with ``install(registry, ctx)``.
+2. Append ``foo.install`` to ``DEFAULT_COMPONENT_INSTALLERS`` in
+   ``components/__init__.py``.
+"""
+
+from __future__ import annotations
+
+from synapse.ui.bottombar.components import (
+    DEFAULT_COMPONENT_INSTALLERS,
+    install_default_components,
+    install_default_regions,
+)
+from synapse.ui.bottombar.context import BottomBarContext
+from synapse.ui.bottombar.core import (
+    DEFAULT_COL_GAP,
+    DEFAULT_REGION_GAP,
+    BottomBarAlign,
+    BottomBarComponent,
+    BottomBarLayout,
+    BottomBarRegion,
+    BottomBarRegionSpec,
+    BottomBarRegistry,
+    PackedRegion,
+    align_in_width,
+    center_in_width,
+    display_width,
+    join_region_parts,
+    layout_from_registry,
+    locate_component_span,
+    normalize_region_id,
+    pack_bottombar_regions,
+    pack_layout_from_registry,
+    pack_region_list,
+    render_packed_line,
+    render_region_text,
+    truncate_to_width,
+)
+
+__all__ = [
+    "DEFAULT_COL_GAP",
+    "DEFAULT_COMPONENT_INSTALLERS",
+    "DEFAULT_REGION_GAP",
+    "BottomBarAlign",
+    "BottomBarComponent",
+    "BottomBarContext",
+    "BottomBarLayout",
+    "BottomBarRegion",
+    "BottomBarRegionSpec",
+    "BottomBarRegistry",
+    "PackedRegion",
+    "align_in_width",
+    "center_in_width",
+    "display_width",
+    "install_default_components",
+    "install_default_regions",
+    "join_region_parts",
+    "layout_from_registry",
+    "locate_component_span",
+    "normalize_region_id",
+    "pack_bottombar_regions",
+    "pack_layout_from_registry",
+    "pack_region_list",
+    "render_packed_line",
+    "render_region_text",
+    "truncate_to_width",
+]

synapse/ui/bottombar/components/__init__.py

@@ -0,0 +1,143 @@
+"""Built-in bottombar components.
+
+Extension pattern
+-----------------
+1. Add ``components/my_widget.py`` with::
+
+       ID = "my_widget"
+
+       def install(registry, ctx) -> None:
+           registry.register_fn(ID, render, region=..., order=..., priority=...)
+
+2. Append ``my_widget.install`` to :data:`DEFAULT_COMPONENT_INSTALLERS` below.
+
+No other bottombar core files need to change.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from synapse.ui.bottombar.components import key_hints, mcp, mode, model
+from synapse.ui.bottombar.core import (
+    DEFAULT_COL_GAP,
+    BottomBarAlign,
+    BottomBarRegion,
+    BottomBarRegistry,
+)
+
+if TYPE_CHECKING:
+    from synapse.ui.bottombar.context import BottomBarContext
+
+ComponentInstaller = Callable[[BottomBarRegistry, "BottomBarContext"], None]
+
+# Order here is install order only (layout uses each component's region/order).
+# thread.install is available but not default (kept out of the chrome bar).
+DEFAULT_COMPONENT_INSTALLERS: list[ComponentInstaller] = [
+    key_hints.install,
+    mode.install,
+    model.install,
+    mcp.install,
+]
+
+
+def install_default_regions(registry: BottomBarRegistry) -> None:
+    """Ensure classic left / center / right region slots exist.
+
+    Layout: left = model/mcp (hug), right = key hints (flex fill).
+    Region ``fg`` is a fallback; host ``layout_from_registry`` left/right styles
+    override at paint time for theme-aware colors.
+    """
+    registry.register_region(
+        BottomBarRegion.LEFT.value,
+        order=10,
+        flex=0,
+        align=BottomBarAlign.LEFT,
+        priority=50,
+        gap_after=DEFAULT_COL_GAP,
+        fg="#8ab4f8",  # accent (model/mcp) — distinct from muted hints
+    )
+    registry.register_region(
+        BottomBarRegion.CENTER.value,
+        order=20,
+        flex=0,
+        align=BottomBarAlign.CENTER,
+        priority=10,
+        min_width=0,
+        gap_after=DEFAULT_COL_GAP,
+        fg="#f4b183",
+    )
+    registry.register_region(
+        BottomBarRegion.RIGHT.value,
+        order=30,
+        flex=1,
+        align=BottomBarAlign.RIGHT,
+        priority=30,
+        min_width=8,
+        gap_after=0,
+        fg="#5f6368",  # muted key hints
+    )
+
+
+def install_default_components(
+    registry: BottomBarRegistry,
+    ctx: BottomBarContext | None = None,
+    /,
+    *,
+    busy: Callable[[], bool] | None = None,
+    thread: Callable[[], str] | None = None,
+    mode: Callable[[], str] | None = None,
+    idle_hints: Callable[[], str] | None = None,
+    busy_hints: Callable[[], str] | None = None,
+    model: Callable[[], str] | None = None,
+    mcp: Callable[[], str] | None = None,
+    installers: list[ComponentInstaller] | None = None,
+) -> None:
+    """Install default regions + component modules.
+
+    Prefer passing :class:`BottomBarContext`. Keyword providers remain for tests.
+    """
+    from synapse.ui.bottombar.context import BottomBarContext as _Ctx
+
+    def _empty() -> str:
+        return ""
+
+    if ctx is None:
+        if busy is None:
+            raise TypeError(
+                "install_default_components requires ctx= or at least busy="
+            )
+        ctx = _Ctx(
+            busy=busy,
+            thread=thread or _empty,
+            mode=mode or _empty,
+            idle_hints=idle_hints
+            or (lambda: "Tab complete · / commands · Esc cancel · F2 model · F4 sessions · F9 delete"),
+            busy_hints=busy_hints
+            or (lambda: "Esc cancel · Enter queue guidance"),
+            model=model or _empty,
+            mcp=mcp or _empty,
+        )
+    else:
+        ctx = _Ctx(
+            busy=ctx.busy,
+            thread=thread or ctx.thread,
+            mode=mode or ctx.mode,
+            idle_hints=idle_hints or ctx.idle_hints,
+            busy_hints=busy_hints or ctx.busy_hints,
+            model=model or ctx.model,
+            mcp=mcp or ctx.mcp,
+        )
+
+    install_default_regions(registry)
+    for install in installers if installers is not None else DEFAULT_COMPONENT_INSTALLERS:
+        install(registry, ctx)
+
+
+__all__ = [
+    "DEFAULT_COMPONENT_INSTALLERS",
+    "ComponentInstaller",
+    "install_default_components",
+    "install_default_regions",
+]

synapse/ui/bottombar/components/key_hints.py

@@ -0,0 +1,30 @@
+"""Bottombar component: contextual key hints (right)."""
+
+from __future__ import annotations
+
+from synapse.ui.bottombar.context import BottomBarContext
+from synapse.ui.bottombar.core import BottomBarRegion, BottomBarRegistry
+
+ID = "key_hints"
+REGION = BottomBarRegion.RIGHT
+ORDER = 10
+PRIORITY = 30  # shrink before model/mcp when narrow
+MIN_WIDTH = 12
+
+
+def install(registry: BottomBarRegistry, ctx: BottomBarContext) -> None:
+    """Register the contextual key-hint line."""
+
+    def render() -> str:
+        if ctx.busy():
+            return (ctx.busy_hints() or "").strip()
+        return (ctx.idle_hints() or "").strip()
+
+    registry.register_fn(
+        ID,
+        render,
+        region=REGION,
+        order=ORDER,
+        priority=PRIORITY,
+        min_width=MIN_WIDTH,
+    )

synapse/ui/bottombar/components/mcp.py

@@ -0,0 +1,64 @@
+"""Bottombar component: MCP status (left), colored by state."""
+
+from __future__ import annotations
+
+from rich.text import Text
+
+from synapse.ui.bottombar.context import BottomBarContext
+from synapse.ui.bottombar.core import BottomBarRegion, BottomBarRegistry
+
+ID = "mcp"
+REGION = BottomBarRegion.LEFT
+ORDER = 20
+PRIORITY = 55
+MIN_WIDTH = 6
+
+# Fallback palette (overridden by active theme when available).
+_C_GREEN = "#81c995"
+_C_ERROR = "#f28b82"
+_C_MUTED = "#5f6368"
+
+
+def _palette() -> tuple[str, str, str]:
+    """Return (green, error, muted) from the active theme when possible."""
+    try:
+        from synapse.ui.theme import get_theme
+
+        t = get_theme()
+        return (
+            str(getattr(t, "green", _C_GREEN) or _C_GREEN),
+            str(getattr(t, "error", _C_ERROR) or _C_ERROR),
+            str(getattr(t, "muted", _C_MUTED) or _C_MUTED),
+        )
+    except Exception:  # noqa: BLE001
+        return _C_GREEN, _C_ERROR, _C_MUTED
+
+
+def style_for_mcp_label(label: str) -> str:
+    """Map ``mcp on`` / ``mcp err`` / ``mcp off`` to a paint color."""
+    key = (label or "").strip().lower()
+    green, error, muted = _palette()
+    if key == "mcp on" or key.endswith(" on"):
+        return green
+    if key == "mcp err" or "err" in key or "error" in key:
+        return error
+    return muted
+
+
+def install(registry: BottomBarRegistry, ctx: BottomBarContext) -> None:
+    """Register mcp on/off/err label with state colors."""
+
+    def render() -> str | Text:
+        label = (ctx.mcp() or "").strip()
+        if not label:
+            return ""
+        return Text(label, style=style_for_mcp_label(label))
+
+    registry.register_fn(
+        ID,
+        render,
+        region=REGION,
+        order=ORDER,
+        priority=PRIORITY,
+        min_width=MIN_WIDTH,
+    )

synapse/ui/bottombar/components/mode.py

@@ -0,0 +1,24 @@
+"""Bottombar component: optional mode tag (center)."""
+
+from __future__ import annotations
+
+from synapse.ui.bottombar.context import BottomBarContext
+from synapse.ui.bottombar.core import BottomBarRegion, BottomBarRegistry
+
+ID = "mode"
+REGION = BottomBarRegion.CENTER
+ORDER = 10
+PRIORITY = 10  # shrink first when narrow
+MIN_WIDTH = 0
+
+
+def install(registry: BottomBarRegistry, ctx: BottomBarContext) -> None:
+    """Register the optional mode label (empty string hides it)."""
+    registry.register_fn(
+        ID,
+        lambda: (ctx.mode() or "").strip(),
+        region=REGION,
+        order=ORDER,
+        priority=PRIORITY,
+        min_width=MIN_WIDTH,
+    )

synapse/ui/bottombar/components/model.py

@@ -0,0 +1,28 @@
+"""Bottombar component: model id + thinking level (left)."""
+
+from __future__ import annotations
+
+from synapse.ui.bottombar.context import BottomBarContext
+from synapse.ui.bottombar.core import BottomBarRegion, BottomBarRegistry
+
+ID = "model"
+REGION = BottomBarRegion.LEFT
+ORDER = 10
+PRIORITY = 60  # keep when narrow
+MIN_WIDTH = 8
+
+
+def install(registry: BottomBarRegistry, ctx: BottomBarContext) -> None:
+    """Register model · thinking label."""
+
+    def render() -> str:
+        return (ctx.model() or "").strip()
+
+    registry.register_fn(
+        ID,
+        render,
+        region=REGION,
+        order=ORDER,
+        priority=PRIORITY,
+        min_width=MIN_WIDTH,
+    )

synapse/ui/bottombar/components/thread.py

@@ -0,0 +1,29 @@
+"""Bottombar component: short thread / session id (left)."""
+
+from __future__ import annotations
+
+from synapse.ui.bottombar.context import BottomBarContext
+from synapse.ui.bottombar.core import BottomBarRegion, BottomBarRegistry
+
+ID = "thread"
+REGION = BottomBarRegion.LEFT
+ORDER = 30
+PRIORITY = 20  # drop before model/mcp when narrow
+MIN_WIDTH = 4
+
+
+def install(registry: BottomBarRegistry, ctx: BottomBarContext) -> None:
+    """Register the short thread label on the left."""
+
+    def render() -> str:
+        label = (ctx.thread() or "").strip()
+        return label
+
+    registry.register_fn(
+        ID,
+        render,
+        region=REGION,
+        order=ORDER,
+        priority=PRIORITY,
+        min_width=MIN_WIDTH,
+    )

synapse/ui/bottombar/context.py

@@ -0,0 +1,36 @@
+"""Host context passed into bottombar component installers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from rich.text import Text
+
+# Providers may return plain text or pre-styled Rich Text.
+LabelFn = Callable[[], str]
+RichLabelFn = Callable[[], str | Text]
+BoolFn = Callable[[], bool]
+
+
+@dataclass(slots=True)
+class BottomBarContext:
+    """Data sources for built-in (and custom) bottombar components.
+
+    App/host fills these callables; each component module only reads what it needs.
+    """
+
+    # True while the agent run is active (steer mode / cancelable).
+    busy: BoolFn
+    # Optional short session / thread label (left, with model/mcp).
+    thread: LabelFn
+    # Optional extra mode tag (e.g. "safe", "steer×2"); empty hides the piece.
+    mode: LabelFn
+    # Idle key-hint line (right).
+    idle_hints: LabelFn
+    # Busy key-hint line (right).
+    busy_hints: LabelFn
+    # Model id + thinking level (left; e.g. ``haha-grok-4.5 · max``).
+    model: LabelFn
+    # MCP chrome (left; ``mcp on`` / ``mcp off`` / ``mcp err``).
+    mcp: LabelFn