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

{limbo_code-0.1.13 → 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.13 → limbo_code-0.1.14}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: limbo-code
-Version: 0.1.13
+Version: 0.1.14
 Summary: A minimal terminal AI coding agent
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27

{limbo_code-0.1.13 → 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.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.13 → 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.

limbo_code-0.1.14/tests/test_herdr.py

@@ -0,0 +1,145 @@
+"""Tests for the Herdr integration reporter (limbo.integrations.herdr)."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+from limbo.integrations.herdr import AGENT, SOURCE, HerdrReporter
+
+FULL_ENV = {
+    "HERDR_ENV": "1",
+    "HERDR_PANE_ID": "w1:p2",
+    "HERDR_BIN_PATH": "/usr/local/bin/herdr",
+    "HERDR_SOCKET_PATH": "/tmp/herdr.sock",
+}
+
+
+def make_reporter(monkeypatch) -> tuple[HerdrReporter, list[list[str]]]:
+    """A reporter with Popen captured; returns (reporter, recorded argv)."""
+    calls: list[list[str]] = []
+
+    def fake_popen(cmd, **kwargs):
+        calls.append(list(cmd))
+
+        class _Proc:
+            def wait(self, timeout=None):
+                return 0
+
+        return _Proc()
+
+    monkeypatch.setattr(subprocess, "Popen", fake_popen)
+    reporter = HerdrReporter.from_env(FULL_ENV)
+    assert reporter is not None
+    return reporter, calls
+
+
+def test_from_env_outside_herdr_is_none():
+    assert HerdrReporter.from_env({}) is None
+    assert HerdrReporter.from_env({"HERDR_ENV": "0"}) is None
+
+
+def test_from_env_requires_pane_and_bin(monkeypatch):
+    # No herdr binary anywhere: even a full-looking env cannot activate.
+    monkeypatch.setattr(shutil, "which", lambda name: None)
+    assert HerdrReporter.from_env({"HERDR_ENV": "1"}) is None
+    assert (
+        HerdrReporter.from_env({"HERDR_ENV": "1", "HERDR_PANE_ID": "w1:p1"}) is None
+    )
+    assert (
+        HerdrReporter.from_env(
+            {"HERDR_ENV": "1", "HERDR_BIN_PATH": "/bin/herdr"}
+        )
+        is None
+    )
+
+
+def test_from_env_falls_back_to_path_lookup(monkeypatch):
+    # HERDR_BIN_PATH is not guaranteed to be set; find herdr on PATH.
+    monkeypatch.setattr(shutil, "which", lambda name: "/resolved/herdr")
+    env = {"HERDR_ENV": "1", "HERDR_PANE_ID": "w1:p1", "HERDR_BIN_PATH": ""}
+    reporter = HerdrReporter.from_env(env)
+    assert isinstance(reporter, HerdrReporter)
+    assert reporter._bin_path == "/resolved/herdr"
+
+
+def test_from_env_inside_herdr():
+    reporter = HerdrReporter.from_env(FULL_ENV)
+    assert isinstance(reporter, HerdrReporter)
+
+
+def test_report_state_command_and_seq(monkeypatch):
+    reporter, calls = make_reporter(monkeypatch)
+    reporter.report("working")
+    reporter.report("idle")
+
+    assert calls[0] == [
+        "/usr/local/bin/herdr",
+        "pane",
+        "report-agent",
+        "w1:p2",
+        "--source",
+        SOURCE,
+        "--agent",
+        AGENT,
+        "--state",
+        "working",
+        "--seq",
+        "1",
+    ]
+    # Strictly increasing seq across reports from the same source.
+    assert calls[1][calls[1].index("--seq") + 1] == "2"
+    assert calls[1][calls[1].index("--state") + 1] == "idle"
+
+
+def test_report_with_message_and_session(monkeypatch):
+    reporter, calls = make_reporter(monkeypatch)
+    reporter.report(
+        "blocked",
+        message="等待确认",
+        session_id="sess-1",
+        session_path="/tmp/sess-1.jsonl",
+    )
+    cmd = calls[0]
+    assert cmd[cmd.index("--message") + 1] == "等待确认"
+    assert cmd[cmd.index("--agent-session-id") + 1] == "sess-1"
+    assert cmd[cmd.index("--agent-session-path") + 1] == "/tmp/sess-1.jsonl"
+
+
+def test_report_session_command(monkeypatch):
+    reporter, calls = make_reporter(monkeypatch)
+    reporter.report("idle")
+    reporter.report_session("sess-2", "/tmp/sess-2.jsonl")
+    cmd = calls[1]
+    assert cmd[:3] == ["/usr/local/bin/herdr", "pane", "report-agent-session"]
+    assert cmd[cmd.index("--agent-session-id") + 1] == "sess-2"
+    assert cmd[cmd.index("--agent-session-path") + 1] == "/tmp/sess-2.jsonl"
+    # Session reports share the same increasing sequence as state reports.
+    assert cmd[cmd.index("--seq") + 1] == "2"
+
+
+def test_release_command(monkeypatch):
+    reporter, calls = make_reporter(monkeypatch)
+    reporter.release()
+    assert calls[0] == [
+        "/usr/local/bin/herdr",
+        "pane",
+        "release-agent",
+        "w1:p2",
+        "--source",
+        SOURCE,
+        "--agent",
+        AGENT,
+    ]
+
+
+def test_popen_failure_is_swallowed(monkeypatch):
+    def boom(cmd, **kwargs):
+        raise OSError("no such file")
+
+    monkeypatch.setattr(subprocess, "Popen", boom)
+    reporter = HerdrReporter.from_env(FULL_ENV)
+    assert reporter is not None
+    reporter.report("working")  # must not raise
+    reporter.report_session("s")  # must not raise
+    reporter.release()  # must not raise

limbo_code-0.1.14/tests/test_integrations.py

@@ -0,0 +1,60 @@
+"""Tests for the integration abstraction layer (limbo.integrations)."""
+
+from __future__ import annotations
+
+from limbo.integrations import CompositeReporter, create_reporters
+
+
+class FakeReporter:
+    def __init__(self):
+        self.calls: list[tuple] = []
+
+    def report(self, state, *, message=None, session_id=None, session_path=None):
+        self.calls.append(("report", state, message, session_id, session_path))
+
+    def report_session(self, session_id, session_path=None):
+        self.calls.append(("report_session", session_id, session_path))
+
+    def release(self):
+        self.calls.append(("release",))
+
+
+def test_empty_composite_is_a_safe_noop():
+    composite = CompositeReporter()
+    assert not composite
+    composite.report("working")  # must not raise
+    composite.report_session("s", "/tmp/s.jsonl")
+    composite.release()
+
+
+def test_composite_fans_out_to_all_reporters():
+    a, b = FakeReporter(), FakeReporter()
+    composite = CompositeReporter([a, b])
+    assert composite
+
+    composite.report("blocked", message="等待确认")
+    composite.report_session("sess-1", "/tmp/sess-1.jsonl")
+    composite.release()
+
+    expected = [
+        ("report", "blocked", "等待确认", None, None),
+        ("report_session", "sess-1", "/tmp/sess-1.jsonl"),
+        ("release",),
+    ]
+    assert a.calls == expected
+    assert b.calls == expected
+
+
+def test_create_reporters_outside_any_tool_is_empty():
+    assert not create_reporters({})
+
+
+def test_create_reporters_detects_herdr():
+    composite = create_reporters(
+        {
+            "HERDR_ENV": "1",
+            "HERDR_PANE_ID": "w1:p1",
+            "HERDR_BIN_PATH": "/bin/herdr",
+        }
+    )
+    assert composite