refactor!: install only bub.core by default and streamline the agent kernel

[frostming]

What changed and why

Users who only embed the agent loop had to install all of Bub: the CLI, the Telegram channel, the plugin system, the TUI prompts and their dependencies. Importing the kernel also loaded the framework. This PR makes bub.core installable and importable on its own, inside the single bub package, and tidies the kernel's API while it is still in alpha.

Packaging: pip install bub installs only the kernel (breaking)

• dependencies now holds only republic, pydantic, loguru and typing-extensions. Everything else moves to a new app extra: pydantic-settings, pyyaml, pluggy, inquirer-textual, typer, rich, prompt-toolkit, python-telegram-bot, rapidfuzz, aiohttp and httpx[socks]. The CLI, channels and plugins need bub[app], and logfire implies it.
• The bub script is bub.__main__:main. It reads bub's own metadata, and if any app requirement is missing it exits with missing: … and an install hint instead of an ImportError. bub.__main__ imports nothing from the extra at import time.
• The dev group depends on bub[app], so uv sync, CI and tox keep a full environment. The Dockerfile (--extra app), install.sh / install.ps1 and bub install (uv add --extra app) request the extra.
• bub/__init__.py exports BubFramework, Settings, config, ensure_config, hookimpl and tool lazily through one _EXPORTS table, so import bub.core works without the extra. .env is now loaded by bub.configure, where settings read the environment, instead of bub.framework. bub.home still honors a BUB_HOME from .env; bub.hookimpl no longer loads .env.
• A new core-only-install CI job builds the wheel and checks two things: a plain install imports bub.core with no app dependencies, and the bub command asks for the extra.

Kernel layout (breaking, versus 0.6.0a1 and 0.5.x)

• bub.core holds the agent concepts: agent, commands, context, events, model, recorder, system_prompt, tape, tools, store and sidecars. The top-level aliases bub.tape, bub.tools, bub.store and bub.sidecars are removed; import from bub.core.*. bub.tool is unchanged.
• errors, prompt, streaming, tracing and turn stay top-level modules; bub.core imports them, and they need only the kernel's dependencies.
• The newest-first, deduplicated, rapidfuzz-backed tape search moves unchanged from FileTapeStore into bub.builtin.store.FuzzyFileTapeStore, which provide_tape_store returns. The kernel's FileTapeStore uses the plain substring query, so bub.core needs neither yaml nor rapidfuzz, and bub users see no change.

Agent events

• New RunFinished with status (ok, error or cancelled), steps, elapsed_ms and error. It follows every RunStarted when the run's stream closes, including a stream closed before it is iterated, and is recorded on the tape as loop.finish. Command prompts emit neither, as before.
• Events are renamed to *Started / *Finished: BeforeLlmCall → LLMCallStarted, AfterLlmCall → LLMCallFinished, BeforeToolCall → ToolCallStarted, AfterToolCall → ToolCallFinished and ChatCompleted → ChatFinished. The payloads LlmCallRequest, LlmCallResult and LlmCallDecision become LLMCall*. These payloads existed in 0.5.x, so plugins implementing before_llm_call that import LlmCallDecision must update. Hook names such as before_llm_call are unchanged.

Fewer layers in a run

A model run used to pass each event through AsyncStreamEvents(start) → _trace_events → AsyncStreamEvents(run_on) → _run_steps → AsyncStreamEvents(run_once) → _run_once → _stream_events. It is now AsyncStreamEvents(run_on) → _run_steps → run_once → _stream_events.

• start hands its invoke_agent span and tape-closing callback to run_on (new optional span / on_close arguments), which builds the run's only stream. A small _RunTracker records the span's output messages and how the run ended.
• run_once is an async generator that writes usage into the given StreamState, replacing the per-step stream whose usage / error were copied into the run's state. It remains the per-step override point.

Impacted modules

pyproject.toml, uv.lock, bub/__init__.py, bub.__main__, bub.configure, bub.framework, bub.core.* (now including tape, tools, store, sidecars and events), bub.builtin.store (new), bub.builtin.*, bub.hooks.*, bub.channels.cli, Dockerfile, website/public/install.{sh,ps1}, .github/workflows/main.yml, AGENTS.md, README and docs (install, SDK, tools, hooks, types, plugins, observability, deploy, distribution, tape-and-context; en + zh-cn).

Verification

• make check (lock, prek/ruff, mypy): passed
• uv run python -m pytest -q: passed. With the trace extra installed, 645 passed and 1 skipped (dev baseline: 616 passed, 20 skipped without OpenTelemetry). New tests:
  • core boundary: importing bub.core loads no app dependencies.
  • CLI entry: the app-extra check.
  • RunFinished: ok, error, early exit, never iterated and commands.
  • core vs builtin file store search.
• Built wheel, plain install: only the kernel's dependencies are installed. bub.core and the top-level modules work, and no app dependency is importable. bub and python -m bub exit 1 with the bub[app] hint. With bub[app] installed, bub --help works.
• Docs build (pinned pnpm 10.34.6): passed

Follow-up (not in this PR)

• The fuzzy search in the file store hasn't actually worked since feat: replace republic with any-llm-sdk #229. FileTapeStore.fetch_all calls super().fetch_all() with the query still attached, so the mixin's JSON substring filter removes typo'd matches before rapidfuzz sees them. That JSON is dumped with ensure_ascii=True, so non-ASCII queries never match either.
• StreamState.error is never assigned by the agent.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	bub	75797dc	Commit Preview URL Branch Preview URL	Oct 15 2026, 10:48 AM