limbo-code 0.1.12__tar.gz → 0.1.14__tar.gz

{limbo_code-0.1.12 → limbo_code-0.1.14}/AGENTS.md

@@ -33,6 +33,8 @@ src/limbo/
 ├── goal_driver.py    # /goal orchestrator (frontend-agnostic, non-UI): turn → verify → next round
 ├── sessions.py       # Session JSONL save/load/list/export
 ├── trace.py          # Append-only JSONL run log (sessions/traces/)
+├── integrations/     # External mux/orchestrator lifecycle reporters: base.py (protocol
+│                     # + CompositeReporter + AgentState), herdr.py; create_reporters() fans out
 ├── skills.py         # SKILL.md discovery (user + project dirs)
 ├── user_paths.py     # Fence grants from paths in user messages
 ├── llm/              # catalog.py (provider/model specs), factory.py (dialect→client),

limbo_code-0.1.12/README.md → limbo_code-0.1.14/PKG-INFO

@@ -1,3 +1,17 @@
+Metadata-Version: 2.5
+Name: limbo-code
+Version: 0.1.14
+Summary: A minimal terminal AI coding agent
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: openai>=1.30
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pygments>=2.17
+Requires-Dist: textual>=8.0
+Requires-Dist: toml>=0.10
+Requires-Dist: tomlkit>=0.13
+Description-Content-Type: text/markdown
+
 # Limbo
 
 A minimal terminal AI coding agent.
@@ -169,6 +183,23 @@ Optional tool settings:
 bash_enabled = true
 ```
 
+Optional UI settings:
+
+```toml
+[ui]
+kitty_keyboard = "auto"   # auto (default) | enabled | disabled
+```
+
+`kitty_keyboard` controls Textual's kitty keyboard protocol. The default
+`auto` disables it only when Limbo runs inside the **herdr** multiplexer:
+herdr mirrors a pane's `REPORT_ALL_KEYS` request to the host terminal
+(e.g. Ghostty), and Ghostty then encodes IME commits as the physical commit
+key (space) while dropping the composed text — typing Chinese turns into
+spaces (pasting is unaffected). With the protocol disabled, herdr keeps
+IME-compatible host flags and committed IME text arrives as raw UTF-8. Use
+`enabled` to always keep the protocol (e.g. in a direct Ghostty/kitty
+terminal), or `disabled` to force raw/legacy input everywhere.
+
 ### Session storage
 
 Conversations are saved as JSONL files in `~/.limbo/sessions/` so you can

limbo_code-0.1.12/PKG-INFO → limbo_code-0.1.14/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.4
-Name: limbo-code
-Version: 0.1.12
-Summary: A minimal terminal AI coding agent
-Requires-Python: >=3.11
-Requires-Dist: httpx>=0.27
-Requires-Dist: openai>=1.30
-Requires-Dist: pydantic>=2.0
-Requires-Dist: pygments>=2.17
-Requires-Dist: textual>=8.0
-Requires-Dist: toml>=0.10
-Requires-Dist: tomlkit>=0.13
-Description-Content-Type: text/markdown
-
 # Limbo
 
 A minimal terminal AI coding agent.
@@ -183,6 +169,23 @@ Optional tool settings:
 bash_enabled = true
 ```
 
+Optional UI settings:
+
+```toml
+[ui]
+kitty_keyboard = "auto"   # auto (default) | enabled | disabled
+```
+
+`kitty_keyboard` controls Textual's kitty keyboard protocol. The default
+`auto` disables it only when Limbo runs inside the **herdr** multiplexer:
+herdr mirrors a pane's `REPORT_ALL_KEYS` request to the host terminal
+(e.g. Ghostty), and Ghostty then encodes IME commits as the physical commit
+key (space) while dropping the composed text — typing Chinese turns into
+spaces (pasting is unaffected). With the protocol disabled, herdr keeps
+IME-compatible host flags and committed IME text arrives as raw UTF-8. Use
+`enabled` to always keep the protocol (e.g. in a direct Ghostty/kitty
+terminal), or `disabled` to force raw/legacy input everywhere.
+
 ### Session storage
 
 Conversations are saved as JSONL files in `~/.limbo/sessions/` so you can

{limbo_code-0.1.12 → limbo_code-0.1.14}/src/limbo/agent.py

@@ -344,6 +344,11 @@ class Agent:
         """Stable id of the current session (the session file stem)."""
         return self._meta.id
 
+    @property
+    def session_path(self) -> Path:
+        """Path of the current session JSONL file."""
+        return self._session_file
+
     @property
     def session_meta(self) -> SessionMeta:
         """Metadata of the current session (title filled in on first save)."""

{limbo_code-0.1.12 → limbo_code-0.1.14}/src/limbo/app.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import argparse
+import os
 import sys
 from pathlib import Path
 
@@ -15,11 +16,24 @@ from limbo.sessions import (
     latest_session,
     load_session,
 )
-from limbo.ui.app import LimboApp
 
 DEFAULT_SESSION_DIR = Path.home() / ".limbo" / "sessions"
 
 
+def _apply_kitty_keyboard_workaround(config) -> None:
+    """Apply the `ui.kitty_keyboard` setting before Textual initializes.
+
+    Textual reads TEXTUAL_DISABLE_KITTY_KEY at import time, so this must run
+    before the first `textual` import. See KittyKeyboardMode for why typing
+    Chinese inside the herdr multiplexer turns into spaces when the kitty
+    keyboard protocol is enabled.
+    """
+    if config.ui.kitty_keyboard.disable_textual_kitty_key(
+        in_herdr=bool(os.environ.get("HERDR_ENV"))
+    ):
+        os.environ["TEXTUAL_DISABLE_KITTY_KEY"] = "1"
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(description="Limbo TUI coding agent")
     parser.add_argument(
@@ -55,6 +69,7 @@ def main() -> int:
     args = parser.parse_args()
 
     config = load_config()
+    _apply_kitty_keyboard_workaround(config)
     if args.model:
         config.llm.model = args.model
     spec = resolve_model(config.llm.model)
@@ -97,6 +112,8 @@ def main() -> int:
         if meta.workdir and Path(meta.workdir).is_dir():
             workdir = Path(meta.workdir)
 
+    from limbo.ui.app import LimboApp  # noqa: I001, PLC0415 - deferred so the kitty keyboard workaround runs first
+
     app = LimboApp(
         workdir=workdir,
         config=config,

{limbo_code-0.1.12 → limbo_code-0.1.14}/src/limbo/config.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import warnings
+from enum import Enum
 from pathlib import Path
 from typing import Any
 
@@ -132,12 +133,45 @@ class ProviderOverride(BaseModel):
     headers: dict[str, str] = Field(default_factory=dict)
 
 
+class KittyKeyboardMode(str, Enum):
+    """How Limbo negotiates Textual's kitty keyboard protocol.
+
+    Textual 8.2.8 requests the kitty keyboard protocol with ``REPORT_ALL_KEYS``.
+    Inside the herdr multiplexer, herdr mirrors that request to the host
+    terminal (e.g. Ghostty), and Ghostty then encodes IME commits as the
+    physical commit key (space) while dropping the composed text — typing
+    Chinese turns into spaces (pasting is unaffected, it bypasses the key
+    encoder). Disabling the protocol makes herdr negotiate IME-compatible host
+    flags so committed IME text arrives as raw UTF-8.
+    """
+
+    # Disable only inside the herdr multiplexer (detected via HERDR_ENV);
+    # keep the protocol everywhere else. Safe default for CJK users.
+    AUTO = "auto"
+    # Always request the kitty keyboard protocol (Textual's default behavior).
+    ENABLED = "enabled"
+    # Never request it — forces raw/legacy terminal input everywhere.
+    DISABLED = "disabled"
+
+    def disable_textual_kitty_key(self, *, in_herdr: bool) -> bool:
+        """Whether Textual's kitty keyboard protocol should be disabled."""
+        return self is KittyKeyboardMode.DISABLED or (
+            self is KittyKeyboardMode.AUTO and in_herdr
+        )
+
+
 class UIConfig(BaseModel):
     # Theme name: built-in "limbo-dark" (default) / "limbo-light", or any
     # Textual built-in theme (e.g. "textual-dark", "dracula", "nord").
     theme: str | None = None
     # Show the startup ASCII-art banner on fresh sessions.
     show_banner: bool = True
+    # Kitty keyboard protocol handling (see KittyKeyboardMode):
+    #   auto     - enable normally, except inside the herdr multiplexer where
+    #              it breaks IME/Chinese input (default)
+    #   enabled  - always request the kitty keyboard protocol
+    #   disabled - never request it (forces raw/legacy terminal input)
+    kitty_keyboard: KittyKeyboardMode = KittyKeyboardMode.AUTO
 
 
 class SafetyConfig(BaseModel):

limbo_code-0.1.14/src/limbo/integrations/__init__.py

@@ -0,0 +1,43 @@
+"""Integrations with external terminal multiplexers / agent orchestrators.
+
+Each integration lives in its own module (e.g. ``herdr``) and implements
+the ``IntegrationReporter`` protocol from ``base``. Its ``from_env()``
+returns ``None`` when Limbo is not running inside that tool, so the
+integration is a strict no-op elsewhere. ``create_reporters()`` collects
+every active integration into one ``CompositeReporter`` — the only object
+call sites ever touch.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+from limbo.integrations.base import (
+    AgentState,
+    CompositeReporter,
+    IntegrationReporter,
+)
+from limbo.integrations.herdr import HerdrReporter
+
+__all__ = [
+    "AgentState",
+    "CompositeReporter",
+    "HerdrReporter",
+    "IntegrationReporter",
+    "create_reporters",
+]
+
+
+def create_reporters(env: Mapping[str, str] | None = None) -> CompositeReporter:
+    """Detect active integrations from the environment.
+
+    Register new integrations here: append ``XReporter.from_env(env)`` when
+    it returns a reporter. Order is irrelevant; each reporter is
+    independent and fire-and-forget.
+    """
+    env = os.environ if env is None else env
+    reporters: list[IntegrationReporter] = []
+    if (herdr := HerdrReporter.from_env(env)) is not None:
+        reporters.append(herdr)
+    return CompositeReporter(reporters)

limbo_code-0.1.14/src/limbo/integrations/base.py

@@ -0,0 +1,87 @@
+"""Shared contract for terminal multiplexer / agent orchestrator integrations.
+
+Every integration (Herdr, future *mux tools, ...) implements
+``IntegrationReporter``: it receives semantic lifecycle state
+(``working``/``idle``/``blocked``) plus session identity, and maps that onto
+whatever the specific tool understands. Call sites (UI, agent loop) only
+ever talk to ``CompositeReporter`` — adding a new integration means writing
+one module here and registering it in ``create_reporters()``, with zero
+changes at call sites.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Literal, Protocol
+
+# Semantic lifecycle states every integration must be able to represent.
+# ``blocked`` means the agent is waiting on a user decision.
+AgentState = Literal["working", "idle", "blocked"]
+
+
+class IntegrationReporter(Protocol):
+    """One external tool interested in Limbo's lifecycle.
+
+    Implementations must be fire-and-forget: never block, never raise.
+    """
+
+    def report(
+        self,
+        state: AgentState,
+        *,
+        message: str | None = None,
+        session_id: str | None = None,
+        session_path: str | None = None,
+    ) -> None:
+        """Report lifecycle state (optionally carrying session identity)."""
+        ...
+
+    def report_session(
+        self, session_id: str, session_path: str | None = None
+    ) -> None:
+        """Report session identity when it changes independently of state."""
+        ...
+
+    def release(self) -> None:
+        """Release any held authority/resources (on agent exit)."""
+        ...
+
+
+class CompositeReporter:
+    """Fans lifecycle reports out to every active integration.
+
+    Always safe to call, even with zero reporters — call sites never need
+    to know which (if any) integrations are active.
+    """
+
+    def __init__(self, reporters: Iterable[IntegrationReporter] = ()):  # noqa: D107
+        self._reporters = list(reporters)
+
+    def __bool__(self) -> bool:
+        return bool(self._reporters)
+
+    def report(
+        self,
+        state: AgentState,
+        *,
+        message: str | None = None,
+        session_id: str | None = None,
+        session_path: str | None = None,
+    ) -> None:
+        for reporter in self._reporters:
+            reporter.report(
+                state,
+                message=message,
+                session_id=session_id,
+                session_path=session_path,
+            )
+
+    def report_session(
+        self, session_id: str, session_path: str | None = None
+    ) -> None:
+        for reporter in self._reporters:
+            reporter.report_session(session_id, session_path)
+
+    def release(self) -> None:
+        for reporter in self._reporters:
+            reporter.release()

limbo_code-0.1.14/src/limbo/integrations/herdr.py

@@ -0,0 +1,143 @@
+"""Herdr terminal multiplexer integration.
+
+When Limbo runs inside a Herdr pane, it inherits ``HERDR_ENV``,
+``HERDR_PANE_ID``, ``HERDR_BIN_PATH``, and ``HERDR_SOCKET_PATH``. This
+reporter uses Herdr's CLI to report semantic lifecycle state
+(``working``/``idle``/``blocked``) and native session identity, per
+https://herdr.dev/docs/integrations/#integrate-your-own-agent
+
+The integration is a strict no-op outside Herdr: ``from_env()`` returns
+``None`` unless ``HERDR_ENV=1`` and both the pane id and a usable ``herdr``
+binary (``HERDR_BIN_PATH``, else PATH) are present.
+Reports are fire-and-forget CLI invocations — they must never block or
+break the UI, and a missing/broken ``herdr`` binary is silently ignored.
+
+``--source`` must stay stable and unique to this integration; ``--seq`` is
+strictly increasing so Herdr can drop reports that arrive out of order
+(turn-end and steer follow-up hand-offs race between workers).
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from collections.abc import Mapping
+
+from limbo.integrations.base import AgentState
+
+SOURCE = "custom:limbo"
+AGENT = "limbo"
+
+
+class HerdrReporter:
+    """Fire-and-forget lifecycle reporter bound to one Herdr pane."""
+
+    def __init__(self, pane_id: str, bin_path: str):
+        self._pane_id = pane_id
+        self._bin_path = bin_path
+        self._seq = 0
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str] | None = None) -> HerdrReporter | None:
+        """Create a reporter when running inside a Herdr pane, else None.
+
+        ``HERDR_BIN_PATH`` is preferred (portable across PATH differences)
+        but is not guaranteed to be set — fall back to a PATH lookup.
+        """
+        env = os.environ if env is None else env
+        if env.get("HERDR_ENV") != "1":
+            return None
+        pane_id = env.get("HERDR_PANE_ID")
+        bin_path = env.get("HERDR_BIN_PATH") or shutil.which("herdr")
+        if not pane_id or not bin_path:
+            return None
+        return cls(pane_id, bin_path)
+
+    def report(
+        self,
+        state: AgentState,
+        *,
+        message: str | None = None,
+        session_id: str | None = None,
+        session_path: str | None = None,
+    ) -> None:
+        """Report lifecycle state (optionally with session identity)."""
+        cmd = [
+            self._bin_path,
+            "pane",
+            "report-agent",
+            self._pane_id,
+            "--source",
+            SOURCE,
+            "--agent",
+            AGENT,
+            "--state",
+            state,
+            "--seq",
+            str(self._next_seq()),
+        ]
+        if message:
+            cmd += ["--message", message]
+        if session_id:
+            cmd += ["--agent-session-id", session_id]
+        if session_path:
+            cmd += ["--agent-session-path", session_path]
+        self._run(cmd)
+
+    def report_session(
+        self, session_id: str, session_path: str | None = None
+    ) -> None:
+        """Report session identity when it changes independently of state
+        (``/new``, ``/sessions`` switch)."""
+        cmd = [
+            self._bin_path,
+            "pane",
+            "report-agent-session",
+            self._pane_id,
+            "--source",
+            SOURCE,
+            "--agent",
+            AGENT,
+            "--seq",
+            str(self._next_seq()),
+            "--agent-session-id",
+            session_id,
+        ]
+        if session_path:
+            cmd += ["--agent-session-path", session_path]
+        self._run(cmd)
+
+    def release(self) -> None:
+        """Release this source's lifecycle authority (on agent exit)."""
+        self._run(
+            [
+                self._bin_path,
+                "pane",
+                "release-agent",
+                self._pane_id,
+                "--source",
+                SOURCE,
+                "--agent",
+                AGENT,
+            ]
+        )
+
+    def _next_seq(self) -> int:
+        # Assigned synchronously before spawning, so sequence order matches
+        # call order even when deliveries race.
+        self._seq += 1
+        return self._seq
+
+    @staticmethod
+    def _run(cmd: list[str]) -> None:
+        try:
+            subprocess.Popen(
+                cmd,
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+        except OSError:
+            # A missing/broken herdr binary must never break the session.
+            pass

{limbo_code-0.1.12 → limbo_code-0.1.14}/src/limbo/ui/screens/main.py

@@ -41,6 +41,7 @@ from limbo.goal_driver import (
     GoalVerifyResultEvent,
     GoalVerifyStarted,
 )
+from limbo.integrations import AgentState, create_reporters
 from limbo.llm.client import LLMClient
 from limbo.llm.factory import create_llm_client
 from limbo.model_switch import (
@@ -111,6 +112,9 @@ class MainScreen(Screen[None]):
         self._compact_busy = False
         self._commands = SlashCommandRegistry()
         self._register_builtin_commands()
+        # External tool integrations (Herdr, ...): an empty composite
+        # outside any integrated environment, so all calls are no-ops.
+        self._integrations = create_reporters()
 
     @property
     def _agent_busy(self) -> bool:
@@ -140,6 +144,20 @@ class MainScreen(Screen[None]):
             resume=resume,
         )
 
+    # -- External tool integrations (no-op outside integrated environments) --
+
+    def _report_state(
+        self, state: AgentState, *, message: str | None = None
+    ) -> None:
+        """Report semantic lifecycle state to active integrations."""
+        self._integrations.report(state, message=message)
+
+    def _report_session(self) -> None:
+        """Report the current session identity (startup, /new, /sessions)."""
+        self._integrations.report_session(
+            self.agent.session_id, str(self.agent.session_path)
+        )
+
     def compose(self) -> ComposeResult:
         yield StatusBar(
             model=self.config.llm.model,
@@ -169,6 +187,8 @@ class MainScreen(Screen[None]):
             )
         self._refresh_goal_indicator()  # D6: silent resume, badge only
         self.query_one("#input", InputWidget).focus()
+        self._report_session()
+        self._report_state("idle")
 
     # -- slash command menu ---------------------------------------------------
 
@@ -332,6 +352,7 @@ class MainScreen(Screen[None]):
         self._pending_proposals = parsed or []
         if not self._pending_proposals:
             chat.add_info("未能解析模型的验收提议，请手动输入或跳过")
+        self._report_state("blocked", message="等待确认 /goal 验收命令")
         self.app.push_screen(
             VerifyPicker(self._pending_proposals), self._on_verify_picked
         )
@@ -345,6 +366,7 @@ class MainScreen(Screen[None]):
         if choice is None:
             chat.add_info("已跳过自动验收（单轮模式）；/goal clear 可退出 goal")
             self._refresh_goal_indicator()
+            self._report_state("idle")
             return
         if choice == VERIFY_EDIT:
             # Prefill the best proposal for editing; the next submission is
@@ -356,6 +378,7 @@ class MainScreen(Screen[None]):
             input_widget.focus()
             self._editing_verify = True
             chat.add_info("编辑验收命令后回车确认（清空回车则跳过）")
+            self._report_state("blocked", message="等待编辑 /goal 验收命令")
             return
         self._accept_verify(choice)
 
@@ -364,6 +387,7 @@ class MainScreen(Screen[None]):
         if is_dangerous(command, self.config.safety.dangerous_commands):
             chat.add_error(f"验收命令命中危险命令过滤，已拒绝：{command}")
             chat.add_info("goal 保持单轮模式；/goal clear 退出")
+            self._report_state("idle")
             return
         state = self.driver.set_verify(command)
         if state is None:
@@ -484,6 +508,7 @@ class MainScreen(Screen[None]):
         input_widget.disabled = True
         self._compact_busy = True
         statusbar.set_state("compacting…", "thinking")
+        self._report_state("working")
         try:
             async for event in self.agent.compact(trigger="manual"):
                 await self._process_agent_event(event)
@@ -492,6 +517,7 @@ class MainScreen(Screen[None]):
             input_widget.disabled = False
             input_widget.focus()
             statusbar.set_state("idle")
+            self._report_state("idle")
 
     def _show_help(self) -> None:
         self.query_one("#chat", ChatWidget).add_info(self._commands.help_text())
@@ -549,6 +575,7 @@ class MainScreen(Screen[None]):
         self.agent = self._new_agent()
         chat.clear()
         chat.add_info(f"已开始新会话 {self.agent.session_id}")
+        self._report_session()
 
     def _find_skill(self, name: str) -> Skill | None:
         if self._commands.get(f"/{name}") is not None:
@@ -602,6 +629,7 @@ class MainScreen(Screen[None]):
         self._render_history()
         meta = self.agent.session_meta
         chat.add_info(f"已切换到会话 {meta.id} · {meta.title or '(无标题)'}")
+        self._report_session()
 
     def _render_history(self) -> None:
         """Render the agent's restored history into the chat flow.
@@ -684,6 +712,7 @@ class MainScreen(Screen[None]):
     async def on_unmount(self) -> None:
         """Close owned resources on shutdown: the LLM client's HTTP pool and
         the agent's trace file handle."""
+        self._integrations.release()
         self.agent.close()
         close = getattr(self.llm_client, "close", None)
         if close is not None:
@@ -707,6 +736,7 @@ class MainScreen(Screen[None]):
             self._editing_verify = False
             chat = self.query_one("#chat", ChatWidget)
             if text.startswith("/"):
+                self._report_state("idle")
                 self._handle_command(text)
                 return
             command = text.strip()
@@ -715,6 +745,7 @@ class MainScreen(Screen[None]):
                 self._accept_verify(command)
             else:
                 chat.add_info("已跳过自动验收（单轮模式）；/goal clear 可退出 goal")
+                self._report_state("idle")
             return
         if text.startswith("/"):
             self._handle_command(text)
@@ -825,6 +856,7 @@ class MainScreen(Screen[None]):
         # go to the steer queue instead of being blocked. Single-flight is
         # owned by the goal driver (``running`` is set eagerly on call).
         statusbar.set_state("thinking…", "thinking")
+        self._report_state("working")
         # driver.run() sets ``running`` eagerly at call time, so the badge
         # refresh below already sees the loop as executing (rainbow on).
         events = self.driver.run(user_input, attachments)
@@ -858,6 +890,7 @@ class MainScreen(Screen[None]):
             # the user can keep typing without clicking.
             input_widget.focus()
             statusbar.set_state("idle")
+            self._report_state("idle")
             self._refresh_goal_indicator()
             # M2: a proposal round that ends without leftover steers pops
             # the verify-command confirmation picker.