feat: support embedding Agent with instance tools, skills, and storage

[lodyai]

Summary

Embedding Bub in a Python application currently couples tool selection, skill discovery, and session recovery to builtin defaults. This change lets callers create bub.builtin.Agent with explicit tools, skill directories, and a tape store while reusing the existing agent loop.

• Use instance tools consistently for model schemas, name/alias resolution, interception, commands, and subagent filtering; an empty tool collection disables tools.
• Recover model and reasoning-effort state from the executing agent's store, with per-turn overrides taking precedence. Allow run_stream() to build its own state and always bind the executing agent.
• Expose BubFramework.plugin_manager for direct plugin registration, replacing the register_plugin() wrapper.
• Add English and Chinese SDK guides, including FastAPI integration, and docstrings for public BubFramework and Agent methods.

Related to #309.

Scope and compatibility

Configuration loading remains process-wide. System prompts are customized through hooks; the guides describe stream consumption, resource ownership, and application-managed session concurrency. This draft introduces no separate SDK package or Agent.run() API.

Callers of BubFramework.register_plugin() must switch to framework.plugin_manager.register(plugin_instance, name=...); direct registration expects an initialized instance rather than a framework-aware factory.

Validation

• Main pytest suite: 354 passed, 1 skipped; 4 process-cleanup cases run separately outside the sandbox and passed (358 passed total).
• Follow-up targeted tests after recovery-signature and documentation changes: 34 passed.
• Ruff and mypy src passed.
• Public-method docstring coverage checked with AST inspection; SDK guide example executed with a stubbed model.
• Website production build passed using pnpm_config_verify_deps_before_run=false make docs-test with existing dependencies. FastAPI snippets were syntax-checked; the FastAPI server was not exercised.

[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	d0b4724	Commit Preview URL Branch Preview URL	Sep 15 2026, 11:43 PM

[rainzee]

直接联系果然是最快的哈哈哈，翘首以盼了

[frostming]

直接联系果然是最快的哈哈哈，翘首以盼了

@rainzee 这个API体感怎样？有没有满足需求？我没有加system_prompt因为它可以通过注册插件实现：

class MyPlugin:
    def __init__(self, framework): pass
    
    @bub.hookimpl
    def system_prompt(self, prompt, state):
        return """..."""

但要注意BubFramework是可变有状态的，如果要会话隔离推荐每个会话用自己的BubFramework实例

[rainzee]

直接联系果然是最快的哈哈哈，翘首以盼了

@rainzee 这个API体感怎样？有没有满足需求？我没有加system_prompt因为它可以通过注册插件实现：

class MyPlugin:
    def __init__(self, framework): pass
    
    @bub.hookimpl
    def system_prompt(self, prompt, state):
        return """..."""

但要注意BubFramework是可变有状态的，如果要会话隔离推荐每个会话用自己的BubFramework实例

三态语义我很喜欢 None [] [x], 但是现在每次会话都要构建一个 BubFramework 是不是有点太贵了，每会话一个 Agent + 显式 tape_store 会不会更好，或者在什么情况下每个会话一个实例呢

[frostming]

每会话一个 Agent + 显式 tape_store 会不会更好，或者在什么情况下每个会话一个实例呢

Agent 和 tape_store是可以独立的，这个PR里已经支持，但register_plugin这种操作对整个BubFramework生效，所以做不到per-session plugin

我也考虑过 BubFramework.copy()，但并不容易做到，因为PluginManager是有状态且不支持copy

[rainzee]

每会话一个 Agent + 显式 tape_store 会不会更好，或者在什么情况下每个会话一个实例呢

Agent 和 tape_store是可以独立的，这个PR里已经支持，但register_plugin这种操作对整个BubFramework生效，所以做不到per-session plugin

我也考虑过 BubFramework.copy()，但并不容易做到，因为PluginManager是有状态且不支持copy

那确实，但是最重要的 sys prompts 又是跟 plugin 绑定，有点遗憾，不过 somehow 我觉得这样也是对的