refactor!: ship the agent kernel as the separate bubling package

[frostming]

Stacked on #361 (refactor/core-boundary). Review that one first; this PR only contains the package split.

What changed and why

Users who only embed the agent loop still had to install all of bub: the CLI, the Telegram channel, the plugin system, the TUI prompts and their dependencies. #361 made bub.core independent of the rest of bub. This PR ships it as its own distribution, bubling, built from the same repository:

• packages/bubling/ is a uv workspace member ([tool.uv.workspace], bubling = { workspace = true }), so uv sync still installs both packages as editable and contributors work in a single checkout.
  • Its dependencies: republic, pydantic, loguru, typing-extensions, plus a trace extra for OpenTelemetry.
  • It ships py.typed.
• Lockstep releases with an exact pin: both packages use hatch-vcs on the same git tag (raw-options = { root = "../.." }).
  • The repository declares a range (bubling>=0.6.0a1, bubling[trace]), which only matters outside the workspace; dev builds such as 0.6.0a2.devN sort below 0.6.0a2, so the bound stays at 0.6.0a1.
  • On release, scripts/release.py pin <tag> rewrites those two requirements to bubling==<tag> / bubling[trace]==<tag>. The build then runs with SETUPTOOLS_SCM_PRETEND_VERSION=<tag>, because the rewrite dirties the checkout and hatch-vcs would otherwise produce a dev version.
  • scripts/release.py check <tag> dist fails the release unless all four distributions carry the tag's version and bub requires exactly that bubling.
  • So every published bub X depends on bubling==X.
• Breaking, only versus 0.6.0a1:
  • bub.core and bub.prompt are removed; import from bubling instead.
  • The aliases already released in 0.5.x (bub.errors, bub.tracing, bub.streaming, bub.store, bub.tape, bub.tools, bub.sidecars) are kept and now point to the bubling modules.
  • bub.turn re-exports TurnState.
• Tests:
  • The kernel-only tests moved to packages/bubling/tests/: agent loop, errors, tools, file and fork stores.
  • They carry a ~40-line copy of the HTTP provider fakes, so they import nothing from bub or tests/.
  • The AST check for forbidden imports in the old core agent test was removed. The import-linter contracts (now on bubling) and the standalone CI job cover the same ground.
• CI and release:
  • A new bubling-standalone job (Python 3.12–3.14) installs only bubling (uv run --isolated --no-project --with ./packages/bubling) and runs its tests.
  • The main test job runs both test suites, and mypy covers both source trees.
  • The release workflow (pin, build, check, publish) and make build now use uv build --all-packages.
  • The Dockerfile copies packages/.
• Docs: the SDK guide and FastAPI tutorial (en + zh-cn) install bubling and import from it. The references to bub.core / bub.prompt in the hooks, types, concepts and tutorial pages now point to bubling. Also updated: AGENTS.md (layout, commands, test placement), README, and a new packages/bubling/README.md.

Before merging / releasing

• Configure a PyPI trusted publisher for the new bubling project (pending publisher: this repo, on-release-main.yml, environment pypi). Otherwise uv publish fails when it uploads bubling.

Verification

• make check (lock, prek/ruff, mypy on 73 files across both trees, import contracts): passed
• uv run python -m pytest -q: 626 passed, 20 skipped
• Standalone: uv run --isolated --no-project --with ./packages/bubling --with pytest --with pytest-asyncio pytest packages/bubling/tests: 42 passed, and bub is not importable in that environment
• uv build --all-packages: both sdists and wheels build.
  • The bubling wheel contains only bubling/ plus py.typed.
  • Its sdist includes LICENSE, README, pyproject.toml and tests, and a wheel rebuilds from it.
  • bub's metadata requires bubling>=0.6.0a1, and its trace extra requires bubling[trace].
• Release rehearsal with 0.6.0a2: pin changes only the 2 requirement strings, and check passes on the pinned build.
  • check fails when the pin step is skipped, and when the tag doesn't match the built version.
  • Without the pretend version, the dirty checkout yields 0.6.0a2.dev5+g….d20261015.
• Docs build (pnpm build with the pinned pnpm 10.34.6): passed

🤖 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	243025c	Commit Preview URL Branch Preview URL	Oct 15 2026, 07:48 AM