bub 0.3.2__tar.gz → 0.3.3__tar.gz

{bub-0.3.2 → bub-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: bub
-Version: 0.3.2
+Version: 0.3.3
 Summary: A common shape for agents that live alongside people.
 Author-Email: Chojan Shang <psiace@apache.org>, Frost Ming <me@frostming.com>, Yihong <zouzou0208@gmail.com>
 Classifier: Intended Audience :: Developers
@@ -27,6 +27,8 @@ Requires-Dist: python-telegram-bot>=21.0
 Requires-Dist: loguru>=0.7.2
 Requires-Dist: rapidfuzz>=3.14.3
 Requires-Dist: aiohttp>=3.13.3
+Provides-Extra: logfire
+Requires-Dist: logfire>=4.31.0; extra == "logfire"
 Description-Content-Type: text/markdown
 
 # Bub
@@ -84,10 +86,10 @@ If `AGENTS.md` exists in the workspace, it is appended to the system prompt auto
 
 Key source files:
 
-- Turn orchestrator: [`src/bub/framework.py`](src/bub/framework.py)
-- Hook contract: [`src/bub/hookspecs.py`](src/bub/hookspecs.py)
-- Builtin hooks: [`src/bub/builtin/hook_impl.py`](src/bub/builtin/hook_impl.py)
-- Skill discovery: [`src/bub/skills.py`](src/bub/skills.py)
+- Turn orchestrator: [`src/bub/framework.py`](https://github.com/bubbuild/bub/blob/main/src/bub/framework.py)
+- Hook contract: [`src/bub/hookspecs.py`](https://github.com/bubbuild/bub/blob/main/src/bub/hookspecs.py)
+- Builtin hooks: [`src/bub/builtin/hook_impl.py`](https://github.com/bubbuild/bub/blob/main/src/bub/builtin/hook_impl.py)
+- Skill discovery: [`src/bub/skills.py`](https://github.com/bubbuild/bub/blob/main/src/bub/skills.py)
 
 ## What Sets It Apart
 
@@ -134,15 +136,16 @@ Lines starting with `,` enter internal command mode (`,help`, `,skill name=my-sk
 
 ## Configuration
 
-| Variable                    | Default                            | Description                                     |
-| --------------------------- | ---------------------------------- | ----------------------------------------------- |
-| `BUB_MODEL`                 | `openrouter:qwen/qwen3-coder-next` | Model identifier                                |
-| `BUB_API_KEY`               | —                                  | Provider key (optional with `bub login openai`) |
-| `BUB_API_BASE`              | —                                  | Custom provider endpoint                        |
-| `BUB_API_FORMAT`            | `completion`                       | `completion`, `responses`, or `messages`        |
-| `BUB_MAX_STEPS`             | `50`                               | Max tool-use loop iterations                    |
-| `BUB_MAX_TOKENS`            | `1024`                             | Max tokens per model call                       |
-| `BUB_MODEL_TIMEOUT_SECONDS` | —                                  | Model call timeout (seconds)                    |
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BUB_MODEL` | `openrouter:qwen/qwen3-coder-next` | Model identifier |
+| `BUB_API_KEY` | — | Provider key (optional with `bub login openai`) |
+| `BUB_API_BASE` | — | Custom provider endpoint |
+| `BUB_API_FORMAT` | `completion` | `completion`, `responses`, or `messages` |
+| `BUB_CLIENT_ARGS` | — | JSON object forwarded to the underlying model client |
+| `BUB_MAX_STEPS` | `50` | Max tool-use loop iterations |
+| `BUB_MAX_TOKENS` | `1024` | Max tokens per model call |
+| `BUB_MODEL_TIMEOUT_SECONDS` | — | Model call timeout (seconds) |
 
 ## Background
 
@@ -152,13 +155,13 @@ Read more: [Context from Tape](https://tape.systems) · [Socialized Evaluation a
 
 ## Docs
 
-- [Architecture](docs/architecture.md) — lifecycle, hook precedence, error handling
-- [Features](docs/features.md) — what ships today and current boundaries
-- [Channels](docs/channels/index.md) — CLI, Telegram, and custom adapters
-- [Skills](docs/skills.md) — discovery and authoring
-- [Extension Guide](docs/extension-guide.md) — hooks, tools, plugin packaging
-- [Deployment](docs/deployment.md) — Docker, environment, upgrades
-- [Posts](docs/posts/index.md) — design notes
+- [Architecture](https://bub.build/architecture/) — lifecycle, hook precedence, error handling
+- [Features](https://bub.build/features/) — what ships today and current boundaries
+- [Channels](https://bub.build/channels/) — CLI, Telegram, and custom adapters
+- [Skills](https://bub.build/skills/) — discovery and authoring
+- [Extension Guide](https://bub.build/extension-guide/) — hooks, tools, plugin packaging
+- [Deployment](https://bub.build/deployment/) — Docker, environment, upgrades
+- [Posts](https://bub.build/posts/) — design notes
 
 ## Development
 
@@ -168,8 +171,8 @@ uv run mypy src
 uv run pytest -q
 ```
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md).
+See [CONTRIBUTING.md](https://github.com/bubbuild/bub/blob/main/CONTRIBUTING.md).
 
 ## License
 
-[Apache-2.0](./LICENSE)
+[Apache-2.0](https://github.com/bubbuild/bub/blob/main/LICENSE)

{bub-0.3.2 → bub-0.3.3}/README.md

@@ -53,10 +53,10 @@ If `AGENTS.md` exists in the workspace, it is appended to the system prompt auto
 
 Key source files:
 
-- Turn orchestrator: [`src/bub/framework.py`](src/bub/framework.py)
-- Hook contract: [`src/bub/hookspecs.py`](src/bub/hookspecs.py)
-- Builtin hooks: [`src/bub/builtin/hook_impl.py`](src/bub/builtin/hook_impl.py)
-- Skill discovery: [`src/bub/skills.py`](src/bub/skills.py)
+- Turn orchestrator: [`src/bub/framework.py`](https://github.com/bubbuild/bub/blob/main/src/bub/framework.py)
+- Hook contract: [`src/bub/hookspecs.py`](https://github.com/bubbuild/bub/blob/main/src/bub/hookspecs.py)
+- Builtin hooks: [`src/bub/builtin/hook_impl.py`](https://github.com/bubbuild/bub/blob/main/src/bub/builtin/hook_impl.py)
+- Skill discovery: [`src/bub/skills.py`](https://github.com/bubbuild/bub/blob/main/src/bub/skills.py)
 
 ## What Sets It Apart
 
@@ -103,15 +103,16 @@ Lines starting with `,` enter internal command mode (`,help`, `,skill name=my-sk
 
 ## Configuration
 
-| Variable                    | Default                            | Description                                     |
-| --------------------------- | ---------------------------------- | ----------------------------------------------- |
-| `BUB_MODEL`                 | `openrouter:qwen/qwen3-coder-next` | Model identifier                                |
-| `BUB_API_KEY`               | —                                  | Provider key (optional with `bub login openai`) |
-| `BUB_API_BASE`              | —                                  | Custom provider endpoint                        |
-| `BUB_API_FORMAT`            | `completion`                       | `completion`, `responses`, or `messages`        |
-| `BUB_MAX_STEPS`             | `50`                               | Max tool-use loop iterations                    |
-| `BUB_MAX_TOKENS`            | `1024`                             | Max tokens per model call                       |
-| `BUB_MODEL_TIMEOUT_SECONDS` | —                                  | Model call timeout (seconds)                    |
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BUB_MODEL` | `openrouter:qwen/qwen3-coder-next` | Model identifier |
+| `BUB_API_KEY` | — | Provider key (optional with `bub login openai`) |
+| `BUB_API_BASE` | — | Custom provider endpoint |
+| `BUB_API_FORMAT` | `completion` | `completion`, `responses`, or `messages` |
+| `BUB_CLIENT_ARGS` | — | JSON object forwarded to the underlying model client |
+| `BUB_MAX_STEPS` | `50` | Max tool-use loop iterations |
+| `BUB_MAX_TOKENS` | `1024` | Max tokens per model call |
+| `BUB_MODEL_TIMEOUT_SECONDS` | — | Model call timeout (seconds) |
 
 ## Background
 
@@ -121,13 +122,13 @@ Read more: [Context from Tape](https://tape.systems) · [Socialized Evaluation a
 
 ## Docs
 
-- [Architecture](docs/architecture.md) — lifecycle, hook precedence, error handling
-- [Features](docs/features.md) — what ships today and current boundaries
-- [Channels](docs/channels/index.md) — CLI, Telegram, and custom adapters
-- [Skills](docs/skills.md) — discovery and authoring
-- [Extension Guide](docs/extension-guide.md) — hooks, tools, plugin packaging
-- [Deployment](docs/deployment.md) — Docker, environment, upgrades
-- [Posts](docs/posts/index.md) — design notes
+- [Architecture](https://bub.build/architecture/) — lifecycle, hook precedence, error handling
+- [Features](https://bub.build/features/) — what ships today and current boundaries
+- [Channels](https://bub.build/channels/) — CLI, Telegram, and custom adapters
+- [Skills](https://bub.build/skills/) — discovery and authoring
+- [Extension Guide](https://bub.build/extension-guide/) — hooks, tools, plugin packaging
+- [Deployment](https://bub.build/deployment/) — Docker, environment, upgrades
+- [Posts](https://bub.build/posts/) — design notes
 
 ## Development
 
@@ -137,8 +138,8 @@ uv run mypy src
 uv run pytest -q
 ```
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md).
+See [CONTRIBUTING.md](https://github.com/bubbuild/bub/blob/main/CONTRIBUTING.md).
 
 ## License
 
-[Apache-2.0](./LICENSE)
+[Apache-2.0](https://github.com/bubbuild/bub/blob/main/LICENSE)

{bub-0.3.2 → bub-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bub"
-version = "0.3.2"
+version = "0.3.3"
 description = "A common shape for agents that live alongside people."
 authors = [
     { name = "Chojan Shang", email = "psiace@apache.org" },
@@ -42,6 +42,11 @@ Documentation = "https://bub.build"
 [project.scripts]
 bub = "bub.__main__:app"
 
+[project.optional-dependencies]
+logfire = [
+    "logfire>=4.31.0",
+]
+
 [dependency-groups]
 dev = [
     "pytest>=7.2.0",

{bub-0.3.2 → bub-0.3.3}/src/bub/__init__.py

@@ -5,4 +5,4 @@ from bub.hookspecs import hookimpl
 from bub.tools import tool
 
 __all__ = ["BubFramework", "hookimpl", "tool"]
-__version__ = "0.3.2"
+__version__ = "0.3.3"

{bub-0.3.2 → bub-0.3.3}/src/bub/__main__.py

@@ -7,7 +7,21 @@ import typer
 from bub.framework import BubFramework
 
 
+def _instrument_bub() -> None:
+    try:
+        import logfire
+
+        logfire.configure()
+    except ImportError:
+        pass
+    else:
+        from loguru import logger
+
+        logger.configure(handlers=[logfire.loguru_handler()])
+
+
 def create_cli_app() -> typer.Typer:
+    _instrument_bub()
     framework = BubFramework()
     framework.load_hooks()
     app = framework.create_cli_app()

{bub-0.3.2 → bub-0.3.3}/src/bub/builtin/agent.py

@@ -28,7 +28,6 @@ from bub.types import State
 from bub.utils import workspace_from_state
 
 CONTINUE_PROMPT = "Continue the task."
-DEFAULT_BUB_HEADERS = {"HTTP-Referer": "https://bub.build/", "X-Title": "Bub"}
 HINT_RE = re.compile(r"\$([A-Za-z0-9_.-]+)")
 
 
@@ -222,7 +221,6 @@ class Agent:
         allowed_tools: Collection[str] | None = None,
         allowed_skills: Collection[str] | None = None,
     ) -> ToolAutoResult:
-        extra_options = {"extra_headers": DEFAULT_BUB_HEADERS} if self.settings.model.startswith("openrouter:") else {}
         prompt_text = prompt if isinstance(prompt, str) else _extract_text_from_parts(prompt)
         if allowed_tools is not None:
             allowed_tools = {name.casefold() for name in allowed_tools}
@@ -240,7 +238,6 @@ class Agent:
                 max_tokens=self.settings.max_tokens,
                 tools=model_tools(tools),
                 model=model,
-                **extra_options,
             )
 
     def _system_prompt(self, prompt: str, state: State, allowed_skills: set[str] | None = None) -> str:
@@ -284,6 +281,7 @@ def _build_llm(settings: AgentSettings, tape_store: AsyncTapeStore, tape_context
         fallback_models=settings.fallback_models,
         api_key_resolver=openai_codex_oauth_resolver(),
         tape_store=tape_store,
+        client_args=settings.client_args,
         api_format=settings.api_format,
         context=tape_context,
         verbose=settings.verbose,

{bub-0.3.2 → bub-0.3.3}/src/bub/builtin/hook_impl.py

@@ -117,7 +117,7 @@ class BuiltinImpl:
         app.command("chat")(cli.chat)
         app.add_typer(cli.login_app)
         app.command("hooks", hidden=True)(cli.list_hooks)
-        app.command("message", hidden=True)(app.command("gateway")(cli.gateway))
+        app.command("gateway")(cli.gateway)
 
     def _read_agents_file(self, state: State) -> str:
         workspace = state.get("_runtime_workspace", str(Path.cwd()))

{bub-0.3.2 → bub-0.3.3}/src/bub/builtin/settings.py

@@ -5,7 +5,7 @@ import pathlib
 import re
 from collections.abc import Callable
 from functools import lru_cache
-from typing import Literal
+from typing import Any, Literal
 
 from pydantic import Field
 from pydantic_settings import BaseSettings, PydanticBaseSettingsSource, SettingsConfigDict, YamlConfigSettingsSource
@@ -45,6 +45,7 @@ class AgentSettings(BaseSettings):
     max_steps: int = 50
     max_tokens: int = DEFAULT_MAX_TOKENS
     model_timeout_seconds: int | None = None
+    client_args: dict[str, Any] | None = None
     verbose: int = Field(default=0, description="Verbosity level for logging. Higher means more verbose.", ge=0, le=2)
 
     @classmethod

{bub-0.3.2 → bub-0.3.3}/src/bub/builtin/shell_manager.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import asyncio
 import contextlib
+import os
 import uuid
 from dataclasses import dataclass, field
 
@@ -38,6 +39,7 @@ class ShellManager:
             cwd=cwd,
             stdout=asyncio.subprocess.PIPE,
             stderr=asyncio.subprocess.PIPE,
+            executable="/bin/bash" if os.name != "nt" else None,
         )
         shell = ManagedShell(shell_id=f"bash-{uuid.uuid4().hex[:8]}", cmd=cmd, cwd=cwd, process=process)
         shell.read_tasks.extend([

{bub-0.3.2 → bub-0.3.3}/src/bub/builtin/store.py

@@ -37,7 +37,7 @@ class ForkTapeStore:
 
     @property
     def _current(self) -> TapeStore:
-        return current_store.get(_emtpy_store)
+        return current_store.get(_empty_store)
 
     @property
     def _fork_tape(self) -> str | None:
@@ -52,7 +52,7 @@ class ForkTapeStore:
 
     async def reset(self, tape: str) -> None:
         self._current.reset(tape)
-        if self._current is _emtpy_store or self._fork_tape != tape:
+        if self._current is _empty_store or self._fork_tape != tape:
             await self._parent.reset(tape)
             return
         current_tape_was_reset.set(True)
@@ -138,7 +138,7 @@ class EmptyTapeStore:
         pass
 
 
-_emtpy_store = EmptyTapeStore()
+_empty_store = EmptyTapeStore()
 
 
 class FileTapeStore(InMemoryQueryMixin):

{bub-0.3.2 → bub-0.3.3}/src/bub/builtin/tools.py

@@ -206,7 +206,9 @@ async def tape_search(param: SearchInput, *, context: ToolContext) -> str:
         if "[tape.search]" in entry_str:
             continue
         lines.append(entry_str)
-    return f"[tape.search]: {len(entries)} matches" + "".join(f"\n{line}" for line in lines)
+    return f"[tape.search]: {len(lines)} matches ({len(entries) - len(lines)} filtered)" + "".join(
+        f"\n{line}" for line in lines
+    )
 
 
 @tool(context=True, name="tape.reset")

{bub-0.3.2 → bub-0.3.3}/tests/test_builtin_agent.py

@@ -26,7 +26,12 @@ def test_build_llm_passes_codex_resolver_to_republic(monkeypatch) -> None:
     monkeypatch.setattr(agent_module, "LLM", FakeLLM)
     monkeypatch.setattr(openai_codex, "openai_codex_oauth_resolver", lambda: resolver)
 
-    settings = AgentSettings(model="openai:gpt-5-codex", api_key=None, api_base=None)
+    settings = AgentSettings(
+        model="openai:gpt-5-codex",
+        api_key=None,
+        api_base=None,
+        client_args={"extra_headers": {"HTTP-Referer": "https://openclaw.ai", "X-Title": "OpenClaw"}},
+    )
     tape_store = object()
 
     agent_module._build_llm(settings, tape_store, "ctx")
@@ -34,6 +39,9 @@ def test_build_llm_passes_codex_resolver_to_republic(monkeypatch) -> None:
     assert captured["args"] == ("openai:gpt-5-codex",)
     assert captured["kwargs"]["api_key"] is None
     assert captured["kwargs"]["api_base"] is None
+    assert captured["kwargs"]["client_args"] == {
+        "extra_headers": {"HTTP-Referer": "https://openclaw.ai", "X-Title": "OpenClaw"},
+    }
     assert captured["kwargs"]["api_key_resolver"] is resolver
     assert captured["kwargs"]["tape_store"] is tape_store
     assert captured["kwargs"]["context"] == "ctx"

{bub-0.3.2 → bub-0.3.3}/tests/test_framework.py

@@ -94,19 +94,19 @@ def test_get_system_prompt_uses_priority_order_and_skips_empty_results() -> None
     assert prompt == "low\n\nhigh"
 
 
-def test_builtin_cli_exposes_login_and_keeps_message_hidden_alias() -> None:
+def test_builtin_cli_exposes_login_and_gateway_command() -> None:
     framework = BubFramework()
     framework.load_hooks()
     app = framework.create_cli_app()
     runner = CliRunner()
 
     help_result = runner.invoke(app, ["--help"])
-    alias_result = runner.invoke(app, ["message", "--help"])
+    gateway_result = runner.invoke(app, ["gateway", "--help"])
 
     assert help_result.exit_code == 0
     assert "login" in help_result.stdout
     assert "gateway" in help_result.stdout
     assert "│ message" not in help_result.stdout
-    assert alias_result.exit_code == 0
-    assert "bub message" in alias_result.stdout
-    assert "Start message listeners" in alias_result.stdout
+    assert gateway_result.exit_code == 0
+    assert "bub gateway" in gateway_result.stdout
+    assert "Start message listeners" in gateway_result.stdout

{bub-0.3.2 → bub-0.3.3}/tests/test_settings.py

@@ -37,11 +37,12 @@ def test_settings_per_provider_keys() -> None:
     assert settings.api_base["openai"] == "https://api.openai.com"
 
 
-def test_settings_no_keys_returns_none() -> None:
+def test_settings_no_keys_return_none() -> None:
     settings = _settings_with_env({})
 
     assert settings.api_key is None
     assert settings.api_base is None
+    assert settings.client_args is None
 
 
 def test_settings_provider_names_are_lowercased() -> None:
@@ -74,6 +75,10 @@ api_key:
   openai: sk-yaml
 api_base:
   openai: https://api.openai.com
+client_args:
+  extra_headers:
+    HTTP-Referer: https://openclaw.ai
+    X-Title: OpenClaw
 """.strip(),
     )
 
@@ -85,6 +90,9 @@ api_base:
     assert settings.max_steps == 77
     assert settings.api_key == {"openai": "sk-yaml"}
     assert settings.api_base == {"openai": "https://api.openai.com"}
+    assert settings.client_args == {
+        "extra_headers": {"HTTP-Referer": "https://openclaw.ai", "X-Title": "OpenClaw"},
+    }
 
 
 def test_env_settings_override_yaml(tmp_path: Path) -> None:
@@ -94,6 +102,10 @@ def test_env_settings_override_yaml(tmp_path: Path) -> None:
 model: openai:gpt-5
 api_key: sk-yaml
 max_steps: 77
+client_args:
+  extra_headers:
+    HTTP-Referer: https://yaml.example
+    X-Title: YAML App
 """.strip(),
     )
 
@@ -103,6 +115,7 @@ max_steps: 77
             "BUB_HOME": str(tmp_path),
             "BUB_MODEL": "anthropic:claude-3-7-sonnet",
             "BUB_API_KEY": "sk-env",
+            "BUB_CLIENT_ARGS": '{"extra_headers":{"HTTP-Referer":"https://env.example","X-Title":"Env App"}}',
             "BUB_MAX_STEPS": "12",
         },
         clear=True,
@@ -112,6 +125,15 @@ max_steps: 77
     assert settings.model == "anthropic:claude-3-7-sonnet"
     assert settings.api_key == "sk-env"
     assert settings.max_steps == 12
+    assert settings.client_args == {
+        "extra_headers": {"HTTP-Referer": "https://env.example", "X-Title": "Env App"},
+    }
+
+
+def test_settings_client_args_can_be_disabled() -> None:
+    settings = _settings_with_env({"BUB_CLIENT_ARGS": "null"})
+
+    assert settings.client_args is None
 
 
 def test_load_settings_reads_yaml_from_bub_home(tmp_path: Path) -> None:

bub-0.3.3/tests/test_tape_search_output.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import pytest
+from republic import ToolContext
+
+import bub.builtin.tools as builtin_tools
+from bub.builtin.tools import tape_search
+
+
+@dataclass(frozen=True)
+class _FakeEntry:
+    date: str
+    payload: object
+
+
+class _FakeTapes:
+    def __init__(self, entries: list[_FakeEntry]) -> None:
+        self._entries = entries
+        self._store = object()
+
+    async def search(self, _query: object) -> list[_FakeEntry]:
+        return list(self._entries)
+
+
+class _FakeAgent:
+    def __init__(self, entries: list[_FakeEntry]) -> None:
+        self.tapes = _FakeTapes(entries)
+
+
+@pytest.mark.asyncio
+async def test_tape_search_reports_shown_matches_and_filtered_count(monkeypatch) -> None:
+    entries = [
+        _FakeEntry(date="2026-01-01T00:00:00Z", payload={"content": "ok"}),
+        _FakeEntry(date="2026-01-01T00:00:01Z", payload={"content": "[tape.search]: 1 matches"}),
+    ]
+    monkeypatch.setattr(builtin_tools, "_get_agent", lambda _context: _FakeAgent(entries))
+
+    output = await tape_search.run(query="x", context=ToolContext(tape="tape", run_id="run", state={}))
+
+    assert output.splitlines()[0] == "[tape.search]: 1 matches (1 filtered)"
+
+
+@pytest.mark.asyncio
+async def test_tape_search_reports_zero_filtered_explicitly(monkeypatch) -> None:
+    entries = [
+        _FakeEntry(date="2026-01-01T00:00:00Z", payload={"content": "a"}),
+        _FakeEntry(date="2026-01-01T00:00:01Z", payload={"content": "b"}),
+    ]
+    monkeypatch.setattr(builtin_tools, "_get_agent", lambda _context: _FakeAgent(entries))
+
+    output = await tape_search.run(query="x", context=ToolContext(tape="tape", run_id="run", state={}))
+
+    assert output.splitlines()[0] == "[tape.search]: 2 matches (0 filtered)"