Backend namespaces
bb 0.43.3SDK 0.4.104pinned e865697 (desktop-v0.43.3)
This page covers the single object a server entry receives: its 22 namespaces plus the onDispose method in declaration order, and a table of numeric limits. Exactly five root fields carry the experimental_ prefix; hosts and sdk do not, although their main members do.
Namespaces that do not exist
Common wrong guesses: bb.info, bb.ws, bb.threads, bb.dispatch, bb.metadata, bb.commands, bb.schedules, bb.services, bb.machines (it is bb.experimental_machines), bb.ai, bb.browsers, bb.host in the singular, bb.db, bb.defineCli (that is a free function).
WebSockets live in bb.http.experimental_websocket, browsers in bb.sdk.experimental_desktopBrowsers, cron in bb.background.schedule, and thread metadata in bb.sdk.threads.getPluginMetadata.
Numeric limits
| Limit | Value | Where |
|---|---|---|
a kv value | 256 KB | host-policy.ts |
| a thread metadata namespace | 256 KiB | backend-contract.ts |
| CLI output (stdout + stderr) | 1 MiB, rejected whole | backend-contract.ts |
requestInput | payload 64 KiB · title 160 chars · timeout 10 min by default, ceiling 1 hour | plugin-interaction-limits.ts |
| presentation row labels | 80 characters | host-policy.ts |
| tool instructions and any instruction contribution | 4096 characters | host-policy.ts |
a configure selection | 256 ids | host-policy.ts |
| a tool parameter override | 128 KiB | host-policy.ts |
experimental_bridgeOptions | 64 KiB, validated and frozen at registration | host-policy.ts |
| provider env entries | 32 names, [A-Z_][A-Z0-9_]* | host-policy.ts |
| the plugin factory | 30 s | plugin-runtime.ts |
| the dispatch hook | 10 s, fail-closed | plugin-hook-registry.ts |
a mention search | 2 s, isolated from failures | backend-contract.ts |
an environment resource | 16 KiB | backend-events.md |
| host RPC | 32 MiB in / 8 MiB out, 30 s by default, ceiling 30 minutes | plugin-host-rpc.ts |
| a host artifact | 256 MiB, sha256 verified | host-daemon-contract/src/protocol.ts |
| stopping a service | 5 s → degraded | plugin-runtime.ts |
The namespaces
bb.agentsstable Per-turn agent context contributions (design §4.4).bb.backgroundstable Long-lived services + cron schedules (design §4.8).bb.clistable Agent-facing `bb` CLI subcommand (design §4.4).bb.eventsstable Additive plugin lifecycle listeners (design §4.5). Announcements core makes: a handler's return value is ignored.bb.experimental_aiServicesexperimental AI services this plugin serves from its `bb.host` entry (helperbb.experimental_environmentsexperimental Environment targets: places a thread can run that this plugin provisions (plans/plugin-environment-providers.md). Experimental: see docs/api_to_audit.md.bb.experimental_hooksexperimental Questions core asks and acts on the answer to. Today: the dispatch checkpoint messages pass through on their way to a provider (a user's reason, or refuse.bb.experimental_machinesexperimental Machine providers provision execution machines. Experimental: see docs/api_to_audit.md.bb.experimental_serverAccessexperimentalbb.hostsstable Server-to-daemon host control-plane declarations.bb.httpstable HTTP routes under /api/v1/plugins/<id>/http/* (design §4.6).bb.logstable Leveled, plugin-scoped logger.bb.onDisposestable Register cleanup to run on reload/disable/shutdown. Hooks run LIFO. The sanctioned place to clear timers and close connections.bb.pluginIdstable The plugin's own id (namespaces storage, routes, commands).bb.providersstable Agent provider registration (docs/provider-plugin-api.md §1).bb.realtimestable Ephemeral push to connected frontends (design §4.7).bb.rpcstable RPC methods under /api/v1/plugins/<id>/rpc/<method> (design §4.6).bb.sdkstable The full BB SDK, bound to this server over loopback (design §4.1). Bind-gated: reading this before the host binds the SDK throws. The real server binds it before loading plugins, so it is available from the moment factories run there — but isolated harnesses may not, so prefer using it from handlers, services, and timers for portability. `threads.spawn` and `threads.fork` default `origin` to "plugin" and, for that origin, `originPluginId` to this plugin's id unless you set them. Seeding `pluginMetadata` always attributes the new thread to this plugin, overriding an explicit `origin` or `originPluginId`.bb.serverstable Read-only facts about the running server (loopback base URL).bb.settingsstable Declarative settings (design §4.2).bb.statusstable Plugin-reported status (needs-configuration).bb.storagestable Namespaced KV + per-plugin database (design §4.3).bb.uistable Host-rendered UI contributions (design §4.9).