feat: expose republic models and media attachments in code mode

[frostming]

Stacked on #349 (Republic 0.6 migration).

What changed and why

Code written by the model in run_code can now call models and show media to the model.

• republic module inside run_code (preset global, also importable as republic, republic.events, republic.decisions). It is a stdlib shim in code_runner_child.py:
  • media classes Image / Audio / Video, messages system() / user() / assistant()
  • get_model(spec=None) with chat() and stream(). Without a spec it uses the session model.
  • get_embedding_model(spec) (embed / embed_many) and get_decision_model(spec) (decide with Noul / Choice / Score)
  • Model calls are proxies. The shim forwards them as republic.<op> calls over the existing call_tool channel. RepublicSession (codemode/republic_bridge.py) then runs them with Bub's provider settings and credentials, so credentials never reach model-written code.
  • Streaming is pull-based. Bub pumps events into a queue and each stream_next returns every event that has arrived. Streams the code leaves open are closed when run_code ends.
  • Republic values travel as JSON objects with a "$republic" key.
• Code-only tools attach_image / attach_audio / attach_video.
  • They take a republic media object, or a file path in the environment, a URL, or a data URL, and load it themselves.
  • The media is attached to that run_code result, which becomes a multimodal tool message.
• Content results.
  • bub.tools.content_result() builds a JSON tool result ({"type": "tool_content", ...}) that carries text and media.
  • ToolExecutor does not re-render it, tape context turns it into a multimodal republic.tool message, and spilling bounds only its text.
• Environment.read_bytes(), non-abstract. The default runs the environment's python to print the file; LocalEnvironment reads the file directly.
• Agent-facing docs.
  • The code mode stub now documents the republic module and has a streaming example.
  • The code mode prompt mentions the attach tools and models.
  • Media parameters render as republic.Image | str.
  • Fixed: the stub builder now resolves $defs nested in a parameter schema.

Impacted modules

bub.builtin.codemode (__init__, code_runner_child, new republic_bridge), bub.tools, bub.environment, bub.builtin.environment, bub.builtin.context, bub.builtin.hook_impl (spill), website docs build/tools.mdx (en + zh-cn).

Limitations

• chat() / stream() do not support tools, tool_choice or output_schema.
• Model calls from code do not go through before_llm_call hooks or tracing spans.
• The code runner child now uses X | Y in isinstance, so the environment's Python must be 3.10+.

Verification

• uv run ruff check .: passed
• uv run mypy src: no issues
• uv run pytest -q: 596 passed, 20 skipped
• New tests in tests/test_codemode.py, tests/test_spill.py, tests/test_environment.py cover:
  • stub content
  • media attachment from a path, a URL and an object, plus load errors
  • multimodal tool messages
  • model proxy spec and credentials
  • streaming, stream errors and leaked-stream cleanup
  • spilling content results
  • the default read_bytes

🤖 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	3a3537b	Commit Preview URL Branch Preview URL	Oct 13 2026, 12:34 AM