Kernel

The kernel starts bb, verifies plugins, resolves contracts, supplies stable ports, and keeps recovery available.

Purpose and boundary

The kernel is not a plugin. It owns only the functions that must remain available after a plugin failure.

The kernel owns these functions:

• Boot, discovery, verification, load, reload, rollback, and unload.
• The manifest schema and the generated contract.json schema.
• Contract declarations, claims, global winners, list order, and chain order.
• Safe mode, error surfaces, plugin logs, status, and cost records.
• Install sources, the artifact store, marketplaces, and core bb plugin verbs.
• The host daemon transport and the private host-role runtime.
• The stable ports bb.storage, bb.secrets, bb.preferences, bb.realtime, bb.http, bb.rpc, and bb.plugins.

The kernel does not own threads, workspaces, files, providers, agents, commands, settings presentation, mentions, or layout. First-party plugins own those domains through the normal plugin path. Plugins remain fully trusted. Artifact checks and role limits do not create a security sandbox.

Boot and loader

Boot has nine ordered phases. Each phase writes a diagnostic record before it starts the next phase.

The loader never imports plugin code during discovery, verification, indexing, or planning. It reads bb.plugin.json, contract.json, and artifact.json as data.

Required dependents start after their providers become ready. Optional and watched edges do not block activation. The loader restarts required dependents after a provider cutover. It restarts them in topological order.

The loader gives an old service generation a bounded drain. It rejects new calls and cancels calls after the deadline. The loader remounts a surface after a winner change. It does not preserve surface-local state.

The plugin manifest

Authors write bb.plugin.jsonc. The build writes a strict dist/bb.plugin.json file. The build also copies name and version into artifact.json for package-manager checks.

Fields

A contract declaration contains id, version, kind, replaceable, and stability. A replaceable backend declaration also contains defaultProvider. A replaceable surface declaration contains defaultClaimant.

A claim uses exactly one of surface or service. A keyed claim also contains key. A list or chain claim can contain before, after, and order hints. The winner store, not the manifest, holds the user's final choice and order.

Nested field shapes

Full annotated example

// bb.plugin.jsonc
{
  "$schema": "https://getbb.app/schemas/plugin-v2.schema.json",
  "schemaVersion": 2,

  // The plugin ID owns every new acme.github.* contract.
  "id": "acme.github",
  "version": "2.3.0",
  "name": "GitHub",
  "description": "Adds GitHub issues, pull requests, and review tools.",
  "category": "integrations",

  "engines": {
    "bb": "^2.0.0",
    "sdk": "^2.0.0"
  },

  // A fork uses a new ID and records the merge base.
  // "fork": { "parent": "bb.github", "parentRevision": "2.2.1" },

  "branding": {
    "icon": "./assets/icon.svg",
    "logo": {
      "light": "./assets/logo-light.svg",
      "dark": "./assets/logo-dark.svg"
    },
    "icons": {
      "pull-request": "./assets/pull-request.svg",
      "issue": "./assets/issue.svg"
    }
  },

  // Paths point to built files in the installed artifact.
  "artifacts": {
    "app": "./dist/app.mjs",
    "server": "./dist/server.mjs",
    "host": "./dist/host.mjs"
  },

  // Claims refer to contracts that another owner declared.
  "claims": [
    { "surface": "bb.thread-ui.sidePanels", "version": "^1.0.0", "order": 40 },
    { "surface": "bb.thread-ui.timeline.item", "version": "^1.0.0", "key": "acme.github.pullRequest" },
    { "service": "bb.agents.tool", "version": "^1.0.0", "key": "github.searchIssues" },
    { "service": "acme.github.issueCache", "version": "^1.2.0" }
  ],

  // Declarations create contracts that this plugin owns.
  "surfaces": [
    {
      "id": "acme.github.pullRequest.actions",
      "version": "1.0.0",
      "kind": "list",
      "replaceable": false,
      "props": "./contracts.ts#PullRequestActionProps",
      "stability": "stable"
    }
  ],
  "services": [
    {
      "id": "acme.github.issueCache",
      "version": "1.2.0",
      "kind": "single",
      "replaceable": true,
      "defaultProvider": "acme.github",
      "contract": "./contracts.ts#IssueCache",
      "stability": "stable"
    }
  ],

  // These edges apply to the server artifact.
  "requires": [
    { "service": "bb.threads", "range": "^1.0.0" }
  ],
  "optional": [
    { "service": "bb.secrets", "range": "^1.0.0" }
  ],
  "watched": [
    { "service": "bb.providers.provider", "range": "^1.0.0", "key": "github" }
  ],

  // Module imports select exact code and do not follow winners.
  "exports": {
    "./components": "./dist/components.mjs",
    "./contracts": "./dist/contracts.mjs"
  },

  // The Settings plugin renders this schema. The kernel validates it at install.
  "settings": {
    "schema": "./settings.schema.json",
    "fields": {
      "token": { "label": "GitHub token", "secret": true, "required": true },
      "defaultRepository": { "label": "Default repository" }
    }
  },

  // These declarations become ordinary Agent and Layout contract claims.
  "skills": ["./skills"],
  "themes": [
    {
      "id": "acme.github.dim",
      "name": "GitHub Dim",
      "description": "A low-contrast theme.",
      "css": "./assets/theme.css",
      "codeTheme": {
        "light": "./assets/code-light.json",
        "dark": "./assets/code-dark.json"
      }
    }
  ],

  // Roles are private links between this plugin's server and host artifacts.
  "hostRoles": [
    {
      "name": "git-credential",
      "contract": "./contracts.ts#GitCredentialRole",
      "scope": "host",
      "launch": { "kind": "module", "export": "gitCredential" },
      "limits": {
        "startTimeoutMs": 10000,
        "stopGraceMs": 5000,
        "idleMs": 300000,
        "maxRssBytes": 1073741824,
        "maxRequestBytes": 33554432,
        "maxResponseBytes": 8388608
      }
    }
  ]
}

The parser rejects unknown fields. It reports all schema and cross-field errors in one result. The build rejects a claim that has no compatible declaration in contract.json.

contract.json

The build generates contract.json. Authors do not edit it. The file contains the full reviewable shape that short manifest rows reference.

{
  "$schema": "https://getbb.app/schemas/contract-v2.schema.json",
  "schemaVersion": 2,
  "plugin": { "id": "acme.github", "version": "2.3.0" },
  "manifestDigest": "sha256-...",
  "declarations": [
    {
      "id": "acme.github.issueCache",
      "owner": "acme.github",
      "tier": "server",
      "type": "service",
      "version": "1.2.0",
      "kind": "single",
      "replaceable": true,
      "defaultProvider": "acme.github",
      "stability": "stable",
      "methods": {
        "get": {
          "input": { "type": "object", "required": ["repo", "number"] },
          "output": { "$ref": "#/$defs/Issue" },
          "call": "query",
          "timeoutMs": 5000,
          "drain": "finish"
        },
        "invalidate": {
          "input": { "type": "object", "required": ["repo"] },
          "output": { "type": "null" },
          "call": "mutation",
          "timeoutMs": 5000,
          "drain": "cancel"
        }
      }
    },
    {
      "id": "acme.github.pullRequest.actions",
      "owner": "acme.github",
      "tier": "app",
      "type": "surface",
      "version": "1.0.0",
      "kind": "list",
      "replaceable": false,
      "stability": "stable",
      "props": { "$ref": "#/$defs/PullRequestActionProps" }
    }
  ],
  "hostRoles": [
    {
      "name": "git-credential",
      "scope": "host",
      "methods": {
        "read": {
          "input": { "$ref": "#/$defs/CredentialRequest" },
          "output": { "$ref": "#/$defs/CredentialResult" },
          "timeoutMs": 30000,
          "cancellable": true
        }
      },
      "signals": {
        "expired": { "payload": { "$ref": "#/$defs/CredentialExpired" } }
      }
    }
  ],
  "$defs": {
    "Issue": { "type": "object" },
    "PullRequestActionProps": { "type": "object" },
    "CredentialRequest": { "type": "object" },
    "CredentialResult": { "type": "object" },
    "CredentialExpired": { "type": "object" }
  }
}

The build resolves all TypeScript contract references into JSON Schema. It keeps TypeScript declaration names for diagnostics and generated types.

The kernel validates the manifest and contract.json as one unit. It checks these rules:

• Each declaration ID starts with the plugin ID.
• Each declaration appears once with one version and one kind.
• Each claim names a compatible ID, version, type, and key form.
• Each required, optional, or watched edge names a service range.
• Each default claimant implements the declared contract.
• Each backend default provider is installed or bundled with the owner.
• Each exported schema reference stays inside the artifact.
• Stable contracts use semver. Experimental contracts carry the explicit marker.

Contract identity uses the ID and semver. It never uses JavaScript object identity.

Claim registry and arbitration

The kernel keeps one normalized record for each declared contract and each claim. It keeps one global arbitration record for each replaceable contract or keyed contract key.

type ContractKind = "single" | "list" | "keyed" | "chain";
type EdgeKind = "required" | "optional" | "watched";

interface ContractRecord {
  id: string;
  ownerPluginId: string;
  version: string;
  tier: "app" | "server";
  type: "surface" | "service";
  kind: ContractKind;
  replaceable: boolean;
  stability: "stable" | "experimental";
  defaultClaimant?: string;
  defaultProvider?: string;
}

interface ClaimRecord {
  contractId: string;
  pluginId: string;
  pluginVersion: string;
  range: string;
  key?: string;
  generation?: string;
  state: "indexed" | "staged" | "ready" | "draining" | "failed" | "disabled";
}

interface ArbitrationRecord {
  contractId: string;
  key?: string;
  winner?: string;
  source: "default" | "user" | "fallback" | "safe-mode";
  orderedClaimants: string[];
  hiddenClaimants: string[];
  revision: number;
}

Kind rules

A collision on a non-replaceable single or keyed key fails before activation. The kernel does not use install time, activation time, or lexical order to select a winner.

A fresh install selects the declared default. A stored choice wins after compatibility checks. Fork lineage groups choices in the inspector. It does not change arbitration.

The 0.x replacement sentinels become stored arbitration data during migration. AUTOMATIC_REPLACEMENT_PROVIDER maps to source: "default", and BUILT_IN_REPLACEMENT_PROVIDER maps to the declared default claimant. The stored identity is the pair of contract ID and optional key. The kernel does not expose replacementProviderKey() in 2.0.

Winner transaction

1. The kernel verifies the candidate and starts a candidate generation.
2. The candidate registers all claimed implementations in a private stage.
3. The candidate reports readiness for each claimed service.
4. The kernel commits the candidate plugin as one atomic generation.
5. The kernel stops new calls to the old service winner.
6. The kernel drains old calls to the declared deadline.
7. The kernel changes the global winner record.
8. The kernel restarts required dependents in graph order.
9. The kernel reports the cutover result.

A failed candidate never changes the running winner. A failed winner triggers the same transaction to the declared default provider.

Frontend single winners receive the typed default component as Original. Backend winners never receive an Original service handle.

Safe mode and recovery

The command bb --safe starts safe mode. The recovery UI can also set the next boot to safe mode.

Safe mode applies these rules:

• The kernel loads only verified bundled default plugins.
• The kernel ignores user winner records, list rows, and chain rows.
• The kernel selects each declared default claimant or default provider.
• The kernel does not start user host roles or user server artifacts.
• The kernel keeps plugin management, logs, diagnostics, and boot routes available.
• The kernel does not delete plugin data or winner choices.

The user can disable a bad plugin, change a winner, roll back an update, or inspect a failure. The next normal boot uses the repaired stored state.

The kernel automatically offers safe mode after two failed boots with the same boot plan. It never changes stored winner choices without a user action.

Build outputs and artifact verification

bb plugin build writes a stage directory and swaps dist/ only after all checks succeed.

The build pins its bundler, CSS processor, SDK transform, and schema generator. App builds keep React and bb runtime imports as host-provided imports. Server and host builds keep only documented runtime packages as external imports.

The build validates SVG assets. It rejects scripts, external references, unsafe URLs, and unstable dimensions. The app CSS scan follows source imports and declared exported modules. It does not accept arbitrary package globs.

The component registry generator stays kernel build tooling. It creates the registry index and item files that package @bb/ui source exports. The generated registry records do not become runtime contracts or claims.

artifact.json contains these fields:

interface ArtifactManifest {
  schemaVersion: 2;
  plugin: { id: string; version: string; packageName?: string };
  builtWith: { bb: string; sdk: string; toolchain: Record<string, string> };
  createdAt: string;
  manifestDigest: string;
  contractDigest: string;
  files: Record<string, { sha256: string; bytes: number; mode: number }>;
  artifactDigest: string;
  source?: { kind: InstallSource["kind"]; resolved: string; integrity?: string };
  signature?: { keyId: string; algorithm: "ed25519"; value: string };
}

The verifier uses this order:

1. Resolve the exact source version, commit, built-in revision, or local path.
2. Materialize bytes in a new stage directory.
3. Reject links, path escapes, unsafe modes, and files outside size limits.
4. Verify package-manager integrity or the resolved Git commit when the source supplies it.
5. Verify each file digest and the artifact root digest.
6. Verify the optional publisher signature and the required bundled release signature.
7. Parse the manifest, contract.json, and artifact.json as strict data.
8. Check engine ranges, contract rules, and artifact path containment.
9. Promote the stage to an immutable content-addressed directory.

path: sources have a visible local-unverified trust mark. The development loop rehashes them before each reload. The kernel never imports from the mutable source directory during a normal install.

Install sources and marketplaces

The source parser accepts these canonical forms:

A Git source can use --subdirectory. The path must use safe POSIX relative syntax. A collection entry selects a safe relative subdirectory. Nested plugin roots remain distinct immutable artifacts.

The installer never runs package lifecycle scripts. It bounds command time and output. It stores npm and Git downloads in content-addressed caches. Promotion never overwrites an existing digest directory.

An interrupted promotion leaves the active install unchanged. The next operation removes only the incomplete stage. Update planning compares the stored resolved source with the latest compatible resolved source.

Marketplace file

{
  "$schema": "https://getbb.app/schemas/marketplace-v2.schema.json",
  "schemaVersion": 2,
  "name": "community",
  "displayName": "BB Community",
  "description": "Community plugins for bb.",
  "plugins": [
    {
      "id": "acme.github",
      "displayName": "GitHub",
      "description": "GitHub issues and pull requests.",
      "icon": { "url": "./icons/acme.github.svg", "sha256": "..." },
      "tags": ["github", "review"],
      "author": { "name": "Acme", "url": "https://example.com" },
      "source": { "npm": { "package": "@acme/bb-github", "range": "^2.0.0" } }
    }
  ]
}

The marketplace is an index, not a trust grant. The installer verifies the resolved plugin artifact separately. Removing a marketplace does not remove installed plugins. It converts their source records to direct resolved sources.

The bb plugin CLI

Core verbs remain available in safe mode. Plugin-contributed verbs belong to bb.commands.cli.

Mutating verbs accept --yes for planned actions and --json for automation. Machine output uses stable result objects and stable error codes.

The CLI reserves plugin, marketplace, and other core words. The bb.commands.cli keyed contract arbitrates all plugin-contributed top-level words.

Kernel port services

Kernel ports use service-token syntax for a uniform author experience. They are fixed, stable, non-replaceable services. The global winner store does not contain them.

The factory receives handles that are bound to the plugin ID, generation, actor, and lifecycle scope. All handles reject work after scope disposal.

Port summary

bb.storage

interface StoragePort {
  kv(namespace?: string): KvStore;
  database(name?: string): Promise<SqliteDatabase>;
  migrate(db: SqliteDatabase, plan: readonly Migration[]): Promise<MigrationResult>;
  usage(): Promise<{ bytes: number; databases: number; keys: number }>;
}

interface KvStore {
  get<T extends JsonValue>(key: string): Promise<T | undefined>;
  set(key: string, value: JsonValue): Promise<void>;
  delete(key: string): Promise<boolean>;
  list(options?: { prefix?: string; cursor?: string; limit?: number }): Promise<{
    keys: string[];
    cursor?: string;
  }>;
  compareAndSet(key: string, expected: JsonValue | undefined, value: JsonValue): Promise<boolean>;
  watch(prefix: string, listener: (change: KvChange) => void): Disposer;
}

interface Migration {
  id: string;
  statements: readonly string[];
  checksum: string;
}

interface SqliteDatabase {
  run(sql: string, params?: readonly JsonValue[]): Promise<SqliteRunResult>;
  get<T>(sql: string, params?: readonly JsonValue[]): Promise<T | undefined>;
  all<T>(sql: string, params?: readonly JsonValue[]): Promise<T[]>;
  batch(statements: readonly SqliteStatement[]): Promise<void>;
  transaction<T>(work: (tx: SqliteTransaction) => Promise<T>): Promise<T>;
  close(): Promise<void>;
}

Storage starts fresh for a fork. A plugin shares data only through an exported service. The kernel contains keys and database names inside the plugin data root.

bb.secrets

interface SecretsPort {
  ref(name: string): SecretRef;
  has(name: string): Promise<boolean>;
  read(ref: SecretRef, options?: { signal?: AbortSignal }): Promise<SecretValue | undefined>;
  require(ref: SecretRef, options?: { signal?: AbortSignal }): Promise<SecretValue>;
  watch(name: string, listener: (state: "set" | "unset") => void): Disposer;
}

interface SecretRef {
  pluginId: string;
  name: string;
}

interface SecretValue {
  expose<T>(use: (value: string) => Promise<T> | T): Promise<T>;
}

Plugin code can read only its own declared secrets. It cannot list secret values. Only a human or an approved kernel flow can write or remove secret values. Logs, errors, traces, and RPC serialization redact SecretValue.

bb.preferences

export type PreferenceKey = `${string}/${string}`;

export type PreferenceAddress =
  | { key: PreferenceKey; scope: "profile" }
  | { key: PreferenceKey; scope: "thread"; threadId: string };

export interface PreferenceCell<T extends JsonValue = JsonValue> {
  address: PreferenceAddress;
  value: T;
  source: "stored" | "default";
  /** `null` means that no stored row exists. */
  revision: string | null;
  updatedAt: number | null;
}

export interface PreferenceQuery {
  ownerPluginId?: string;
  scope?: "profile" | "thread";
  threadId?: string;
  prefix?: string;
}

export interface PreferenceWriteOptions {
  /** Omit this member for a last-write-wins update. */
  expectedRevision?: string | null;
}

export interface PreferenceChange<T extends JsonValue = JsonValue> {
  previous: PreferenceCell<T>;
  current: PreferenceCell<T>;
  cause: "set" | "clear" | "default-changed";
}

export interface PreferencesPort {
  get<T extends JsonValue>(address: PreferenceAddress): Promise<PreferenceCell<T>>;
  set<T extends JsonValue>(
    address: PreferenceAddress,
    value: T,
    options?: PreferenceWriteOptions,
  ): Promise<PreferenceCell<T>>;
  clear(
    address: PreferenceAddress,
    options?: PreferenceWriteOptions,
  ): Promise<PreferenceCell>;
  list(query?: PreferenceQuery): Promise<readonly PreferenceCell[]>;
  reload(query?: PreferenceQuery): Promise<readonly PreferenceCell[]>;
  watch<T extends JsonValue>(
    query: PreferenceQuery,
    listener: (change: PreferenceChange<T>) => void,
  ): Disposer;
}

The port reads each declared preference schema from the plugin manifest. It validates stored values and manifest defaults.

The port has no presentation. The bb.settings plugin supplies the default settings UI.

The port stores profile and thread cells. It uses <ownerPluginId>/<name> keys.

A plugin actor can write only keys in its namespace. A human actor can write any visible preference.

The port rejects undeclared keys and secret keys. Secret writes use the human-only bb.secrets flow.

expectedRevision supports compare-and-set updates. null requires that no stored row exists.

watch() reports committed effective changes. A preference change does not restart a healthy plugin.

The contracts package exports PreferencesPort, PreferenceAddress, PreferenceCell, PreferenceQuery, and PreferenceChange.

bb.realtime

interface RealtimePort {
  declare<E extends EventContract>(event: E): RealtimeEventHandle<E>;
  publish<E extends EventContract>(event: E, payload: InputOf<E>, target?: RealtimeTarget): Promise<PublishResult>;
  subscribe<E extends EventContract>(event: E, listener: (payload: OutputOf<E>, meta: EventMeta) => void): Disposer;
  command<C extends ClientCommandContract>(input: {
    target: RealtimeTarget;
    command: C;
    input: InputOf<C>;
    timeoutMs?: number;
  }): Promise<{ delivered: number; outcomes: ClientCommandOutcome[] }>;
  connection(listener: (state: "connected" | "disconnected") => void): Disposer;
}

type RealtimeTarget =
  | { kind: "all" }
  | { kind: "session"; sessionId: string }
  | { kind: "thread"; threadId: string };

command() replaces the old separate hub concept. It keeps actor and session attribution. Thread state streams belong to bb.threads, not this transport port.

bb.background

interface BackgroundPort {
  service(name: string, definition: BackgroundService): Disposer;
  schedule(name: string, cron: string, handler: ScheduledTask): Disposer;
}

interface BackgroundService {
  start(signal: AbortSignal): void | Promise<void>;
}

type ScheduledTask = (context: {
  signal: AbortSignal;
  scheduledAt: string;
}) => void | Promise<void>;

The kernel restarts a failed service with bounded backoff. It stores each five-field cron schedule by plugin ID and name. Generation disposal stops services and removes the active schedule registration.

bb.http

interface HttpPort {
  route<I, O>(definition: HttpRoute<I, O>, handler: HttpHandler<I, O>): Disposer;
  url(path?: string): URL;
  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
}

interface HttpRoute<I, O> {
  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
  path: `/${string}`;
  auth: "local" | "token" | "none";
  input?: StandardSchema<I>;
  output?: StandardSchema<O>;
  maxBodyBytes?: number;
  timeoutMs?: number;
}

type HttpHandler<I, O> = (input: I, context: HttpContext) => Promise<O> | O;

interface HttpContext {
  actor: Actor;
  session?: Session;
  signal: AbortSignal;
  request: Request;
}

Routes mount below /api/plugins/<pluginId>/. A route cannot shadow a kernel or another plugin route. The kernel derives OpenAPI data from route schemas and contract.json.

bb.rpc

interface RpcPort {
  register<C extends RpcContract>(contract: C, handlers: RpcHandlers<C>): Disposer;
  call<C extends RpcContract, M extends keyof C["methods"]>(
    pluginId: string,
    contract: C,
    method: M,
    input: RpcInput<C, M>,
    options?: { signal?: AbortSignal; timeoutMs?: number },
  ): Promise<RpcOutput<C, M>>;
}

interface RpcContract {
  id: string;
  version: string;
  methods: Record<string, { input: StandardSchema; output: StandardSchema }>;
}

interface RpcError {
  code: string;
  message: string;
  issues?: readonly { path: string; message: string }[];
  traceId: string;
}

The contract ID and semver select an RPC contract. The caller does not supply an untyped method schema. App calls cross a typed transport. Server-to-server service calls remain direct in-process calls.

The contracts package exports JsonValue, Standard Schema types, RPC method types, RpcError, and defineRpcContract(). The app package exports useRpc(), useRealtime(), and useRealtimeConnectionState() as typed adapters for these ports. The connection hook reports "connecting", "connected", or "reconnecting".

bb.plugins

interface PluginsPort {
  list(options?: { state?: PluginState; includeBuiltins?: boolean }): Promise<PluginSummary[]>;
  get(pluginId: string): Promise<PluginDetail | undefined>;
  status(): Promise<KernelStatus>;
  contracts(options?: { owner?: string; tier?: "app" | "server" }): Promise<ContractRecord[]>;
  claims(contractId?: string): Promise<ClaimRecord[]>;
  winners(contractId?: string): Promise<ArbitrationRecord[]>;
  edges(pluginId?: string): Promise<DependencyEdge[]>;
  hostRoles(pluginId?: string): Promise<HostRoleStatus[]>;
  diagnostics(pluginId: string, options?: DiagnosticQuery): Promise<PluginDiagnostics>;
  watch(listener: (event: PluginIntrospectionEvent) => void): Disposer;
  reportStatus(status: PluginReportedStatus): Disposer;
}

interface PluginReportedStatus {
  state: "ready" | "degraded" | "needs-configuration";
  message?: string;
  detail?: JsonValue;
}

This service provides introspection. It does not install, remove, enable, reload, or select winners. Kernel UI and CLI flows use privileged control commands for those operations.

Scope and cleanup

The old broad scope object becomes the factory lifecycle context. It is not a claimable service.

interface PluginScope {
  pluginId: string;
  generation: string;
  signal: AbortSignal;
  actor: Actor;
  session: Session;
  effect(register: () => void | Disposer | Promise<void | Disposer>): Disposer;
  child(meta: Record<string, string>): PluginScope;
  dispose(reason?: string): Promise<void>;
}

All factory registrations become scope effects. The factory can also return one disposer. The runtime runs child disposal first. It then runs effects in last-in, first-out order.

Host daemon and host roles

The host daemon supplies transport and contained machine ports. Domain plugins define role behavior. The kernel does not include provider, workspace, or AI protocol verbs in its public plugin API.

Role identity

A host role has the private ID <pluginId>.host.<name>. It never enters the global winner store. A public server service can require one role with the same plugin owner.

The server half owns the public service token. Consumers do not know that the service uses a host. This rule keeps one public identity for a capability that uses two tiers.

interface HostRolesPort {
  use<C extends HostRoleContract>(name: string, contract: C, target: HostTarget): Promise<HostRoleClient<C>>;
  watch(name: string, listener: (event: HostRoleEvent) => void): Disposer;
}

interface HostRoleClient<C extends HostRoleContract> {
  call<M extends keyof C["methods"]>(
    method: M,
    input: HostInput<C, M>,
    options?: { signal?: AbortSignal; timeoutMs?: number | null },
  ): Promise<HostOutput<C, M>>;
  onSignal<S extends keyof C["signals"]>(name: S, listener: HostSignalListener<C, S>): Disposer;
  retain(): HostRoleLease;
  dispose(): Promise<void>;
}

type HostTarget =
  | { kind: "host"; hostId: string }
  | { kind: "environment"; environmentId: string };

Host factory and context

export default defineHostPlugin((api) => {
  api.roles.provide("git-credential", GitCredentialRole, {
    read: async (input, context) => readCredential(input, context),
  });
});

interface HostRoleContext {
  pluginId: string;
  generation: string;
  role: string;
  hostId: string;
  target: HostTarget;
  signal: AbortSignal;
  paths: { dataDir: string; tempDir: string };
  fs: ScopedFs;
  exec: ScopedExec;
  vcs: ScopedVcs;
  process: ScopedProcess;
  watch(paths: string[], options: WatchOptions, listener: WatchListener): Disposer;
  emitSignal(name: string, payload: JsonValue): void;
  retain(): HostRoleLease;
  log: PluginLogger;
}

The role gets only the ports allowed by its target scope. Paths stay inside the declared root and write roots. The daemon removes runtime-owned environment variables before it starts a role.

Daemon protocol

The server and daemon use one versioned session. The protocol supports these generic operations:

Provider model, health, usage, installation, bridge, tool-call, and interaction verbs move to bb.providers roles. The daemon carries their typed role calls. It does not define their domain grammar.

Each role process has call, input, output, line, memory, start, idle, and stop limits. The daemon kills a role that violates a hard transport limit. It does not automatically restart a failed role. The next required call starts a new verified generation.

Error surfaces and rollback

The kernel uses stable error codes. A plugin can add only codes below its own plugin ID.

An app surface error boundary shows the plugin ID, surface ID, trace ID, and fallback result. It never shows secret values or an unfiltered stack.

The kernel keeps the current and previous verified artifacts for each managed plugin. A rollback stages the previous artifact through the normal winner transaction. It never restores storage from another plugin ID.

Diagnostics and cost attribution

The kernel assigns every operation a pluginId, generation, contract ID, call ID, trace ID, and tier. It keeps bounded structured logs and aggregate cost samples.

interface PluginDiagnostics {
  pluginId: string;
  generation: string;
  state: PluginState;
  boot: { verifyMs: number; loadMs: number; readyMs: number };
  app: { mounts: number; renderMs: number; longTasks: number; errors: number };
  server: { calls: number; callMs: number; errors: number; activeCalls: number };
  host: { starts: number; calls: number; callMs: number; exits: number; peakRssBytes?: number };
  io: { httpInBytes: number; httpOutBytes: number; realtimeBytes: number; storageBytes: number };
  restarts: { count: number; reasons: Record<string, number> };
  logs: DiagnosticLogSummary;
  sampledAt: string;
}

The kernel records these measures:

• Manifest, contract, and artifact verification time.
• Factory start, readiness, commit, drain, disposal, and restart time.
• Service and RPC call count, duration, failure code, cancellation, and bytes.
• Surface mount count, render duration, long tasks, and error-boundary events.
• Host role starts, exits, peak memory, calls, output, and lease time.
• HTTP, realtime, storage, and secret-read counts. Secret values never enter diagnostics.

The first release reports cost. It does not enforce a budget. The inspector can compare a fork with its recorded parent revision.

Covers

This table maps every allocated old item to its 2.0 home.

<!-- GENERATED_COVERS_START -->