feat!: make code mode a reusable core component

[frostming]

What & why

Code mode used to live in bub.builtin and depended on app-only parts: settings for model credentials, bub.home for stub files, and the BubAgent turn state. As a result, users of the kernel alone (pip install bub) could not use it. This PR moves it into bub.core.codemode as a reusable CodeMode component:

from bub.core import Agent
from bub.core.codemode import CodeMode

code_mode = CodeMode([search, fetch], models="openai:gpt-5")
agent = Agent(model=model, tools=[code_mode.run_code], system_prompt=["...", code_mode.prompt])

CodeMode accepts:

• Tools to expose: a fixed list, or a selector that returns tools for each turn state (None disables code mode).
• environment=: where code runs. The default is the local subprocess.
• models=: a default spec or a ModelResolver for the republic bridge.
• stub_dir=: write the stub to a file instead of inlining it in the prompt.
• media_tools=: include the attach_image/audio/video tools.
• name=: the name of the run_code tool.

Nested tool calls still emit ToolCallStarted/ToolCallFinished with context.code_mode=True.

Impacted modules

• New bub.core.codemode: CodeMode, stub, runner, runner_child, republic_bridge.
• LocalEnvironment and LocalProcess move to bub.environment. bub.builtin.environment keeps only environment_from_state.
• bub.builtin.codemode is now thin wiring: the CODE_MODE instance, the session setting, Bub's settings-based model resolution, and stub files under bub home. BubAgent uses CODE_MODE.prompt.

Breaking changes (no compatibility aliases)

• bub.builtin.codemode.code_runner → bub.core.codemode.runner
• bub.builtin.codemode.republic_bridge → bub.core.codemode.republic_bridge
• LocalEnvironment and LocalProcess → bub.environment

Verification

• uv run ruff check .
• uv run mypy src
• uv run pytest -q: 666 passed, 1 skipped
• New tests/test_core_codemode.py:
  • a kernel-only end-to-end run
  • a stub file written to stub_dir
  • per-state tool selection
  • model resolvers
  • import bub.core.codemode loads no app dependencies
• Docs: added a "Code mode in your own agent" section to the tools docs, in English and Chinese, and updated AGENTS.md.

🤖 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	88da205	Commit Preview URL Branch Preview URL	Oct 17 2026, 11:01 AM