1. The plugin package

A plugin is one npm-shaped package: package.json with a bb block, source entries per tier, and a built dist/ artifact. The loader reads dist/ as data and imports only server.mjs. Where the built loader (packages/kernel-loader) departs from spec 01, the built behavior is the rule (stage-2/04 §1).

1.1 Identity and layout

Source layout (01 §2.1): package.json, src/contracts.ts, src/server.ts, src/app.tsx, src/host.ts, src/cli.ts, src/import.ts, src/reducers.ts, src/app.css, config.schema.json, skills/<name>/SKILL.md, assets/, docs/guide.md, dist/. Every entry is optional; at least one of server, app, host must be set.

1.2 Manifest: package.json#bb

The zod schema is packages/kernel-loader/src/manifest.ts (R35; @bb/plugin-build/manifest re-exports it). The parse is strict: an unknown key fails with its path. Every default is filled once; dist/manifest.json holds the resolved form plus packageName and version.

ServiceId is <pluginId>/<serviceName> (isServiceId). A provides entry also needs contracts; the build checks provides against the exported defineService ids (stage-2/04 §3).

1.3 contributes

SettingDescriptor (settingDescriptorSchema): every type has label (required) and description (default null).

HostRoleContribution: role ∈ provider-bridge, environment-provider, skill-discovery, terminal-backend, ai-service, rpc; name ^[a-z0-9][a-z0-9-]*$; launch = { kind: "module", export } or { kind: "exec", command, args }, default { kind: "module", export: <name> }; limits defaults maxRssBytes 1 GiB, idleMs 300000, startTimeoutMs 10000, stopGraceMs 5000, maxLineBytes 1 MiB, maxStderrLines 1000.

KindDeclaration: item: boolean; schema: { open, close, payload } (each JSON Schema or null); deltaPaths: string[] ([]); retention = { kind: "keep" } (default), { kind: "drop-deltas-after-close" }, or { kind: "keep-latest", per: "thread" \| "turn", n }; ignorable (false). An item kind needs open and close; a non-item kind needs payload.

contributes.commands.nouns (at dc07292bf): a noun may be dotted — ^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*$ (thread.queue, project.source); nounOf("thread.queue.create") is thread.queue (kernel-loader/src/manifest.ts).

1.4 Cross-field rules and validation order

manifestRuleIssues runs at build (parsePluginPackage) and at load (validateResolvedManifest on dist/manifest.json): at least one of server/app/host; replaces ≠ id and not reserved; contracts set when provides is non-empty; no id in both requires and uses; no own provides in requires/uses; eventKinds/interactionKinds keys prefixed by <id>/ or <replaces>/; every providers[].bridge names a provider-bridge role; every extensionKinds entry is in eventKinds; no duplicate host role; every cli.aliases target is in cli.commands.

readArtifact (artifacts/artifact.ts) classifies one package, in this order:

Spec 01 §2.7 verifies digests for every source except path:; the built loader skips bundled artifacts too.

1.5 Example: examples/plugins/hello-slot/package.json (trimmed)

{
  "name": "@get-bb/plugin-hello-slot",
  "version": "0.1.0",
  "type": "module",
  "exports": { "./contracts": { "source": "./src/contracts.ts", "types": "./dist/types/contracts.d.ts", "default": "./dist/contracts.mjs" } },
  "files": ["dist", "assets", "src"],
  "scripts": { "build": "bb plugin build . && tsc -p tsconfig.types.json" },
  "bb": {
    "id": "hello-slot",
    "name": "Hello Slot",
    "description": "Stage 1 smoke: greet over HTTP/SDK/CLI/tool, count in data.db, a root panel, a scratch environment provider.",
    "category": "developer",
    "server": "./src/server.ts", "app": "./src/app.tsx", "host": "./src/host.ts", "contracts": "./src/contracts.ts",
    "provides": { "hello-slot/greeter": { "version": "1.0.0" } },
    "contributes": {
      "database": true,
      "cli": { "commands": ["hello"] },
      "slots": ["root"],
      "hostRoles": [{ "role": "rpc", "name": "echo" }, { "role": "environment-provider", "name": "scratch" }],
      "hostCommands": ["host-greet"],
      "icons": { "plugin": "./assets/icon.svg", "named": { "wave": "./assets/wave.svg" } }
    }
  },
  "dependencies": { "@bb/ui": "workspace:*", "@get-bb/plugin-sdk": "workspace:*", "zod": "4.3.6" },
  "peerDependencies": { "react": "^19.0.0" }
}

A plugin imports @get-bb/plugin-sdk, @bb/ui, zod, and React types, nothing else (stage-2/04 intro). tsconfig.json sets customConditions: [] (D20). A minimal server-only manifest is the SDK fixture (packages/plugin-sdk/src/fixture/manifest.ts): id, provides, uses: { "threads/agent-config": "^1.0.0" }, contributes: { database, background: ["tick"], settings, hostRoles, hostCommands, hostSignals, slots }.

Dependencies as built: @get-bb/plugin-sdk is 1.0.0-next.0 and @bb/ui 0.0.0 (packages/plugin-sdk/package.json, packages/ui/package.json), both workspace:* in the tree; the published ranges are open (§0.6). The SDK and the example pin zod to 4.3.6. The collector needs zod 4 (the collector calls z.toJSONSchema, kernel-ui:boot/contributions.ts; inputs are z.strictObject) and each tier bundles the plugin's own copy (D18). React is a peer (^19.0.0; types @types/react ^19.2.0); happy-dom (^20.11.0) is a dev dependency for the app test (§9.3).

Starter configs (hello-slot's files; its tsconfig.json extends the monorepo tsconfig.base.json, inlined here):

// tsconfig.json
{ "compilerOptions": { "strict": true, "target": "ES2023", "lib": ["ES2023", "DOM", "DOM.Iterable"],
    "module": "NodeNext", "moduleResolution": "NodeNext", "jsx": "react-jsx", "types": ["node"],
    "isolatedModules": true, "verbatimModuleSyntax": true, "skipLibCheck": true, "customConditions": [],
    "noEmit": true, "rootDir": "src", "outDir": "dist/types" }, "include": ["src"] }
// tsconfig.types.json: extends ./tsconfig.json; noEmit false, declaration + emitDeclarationOnly true; include ["src/contracts.ts"]
// vitest.config.ts: defineConfig({ test: { include: ["src/**/*.test.ts"], testTimeout: 30_000, hookTimeout: 60_000 } })
//   — no `environment`: every file runs in node and app.test.ts installs happy-dom itself (§9.3)

1.6 Tiers and entry files

TIERS in packages/plugin-build/src/externals.ts lists the seven; TIER_OUTPUT maps each to its .mjs.

1.7 Build outputs: dist/

bb plugin build [dir] runs one esbuild pass per tier, a Tailwind pass for app, writes dist/ atomically (stage dir → swap), and prints the digest. bb plugin dev [dir] installs the dir as path: on the first successful build, watches (300 ms debounce), rebuilds unminified with sourcemaps, and reloads. Both are @bb/plugin-build functions mounted by the plugin-dev plugin.

meta.json = { artifactFormatVersion: 2, sdkMajor: 1, uiMajor: 1, sdkVersion, pluginId, pluginVersion, bbVersion, builtAt, digests }. The artifact digest is sha256(sorted "path\0digest\n"), printed sha256:<hex>; builtAt never moves it. app.css utilities carry the two-arm :where([data-bb-plugin="<id>"]) prefix; authored CSS must root every selector at [data-bb-plugin-effect="<id>"] (R34; 01 §3.3's "stays unscoped" is superseded). Build failures, not load failures: contributes.slots ≠ collector names; provides ≠ exported ids; authored CSS outside the effect root; /app or /testing imported from a Node tier; a sibling subpath other than /contracts; a color-literal token. contract.json and app.contributions.json are hook-driven (hooks: { contract, appContributions }); plugin-dev wires the real hooks. bb plugin pack [dir] writes a deterministic npm-shaped tarball (honors files / .npmignore / .gitignore; never ships .env*, .npmrc; refuses an unbuilt package). bb sdk types is a bundled offline handler (packages/cli/src/_pending/plugin-dev-cli.ts). bb plugin new and bb plugin types are spec verbs (01 §3.1) that @bb/plugin-build does not ship; hello-slot uses tsc -p tsconfig.types.json as the stand-in.

1.8 Install sources and the artifact store

Install = resolve → fetch → verify → Storage.unpack into plugins/store/<digest> → write versions/<v> → flip current → composition effect → reload. previous keeps the old pointer for rollback. Keep 3 versions per package (KEEP_VERSIONS). GC removes unreferenced store/ dirs after 7 days and orphaned .tmp-* stages after 1 hour. gc runs at boot and after update, rollback, and remove. Pointer files carry three lines <version>\n<digest>\n<resolution json>\n (README deviation 16; spec shows two). A system record is never replaced by an npm:/url: install of the same name (README deviation 14). Moved-tag refusal: an update whose same version resolves to a different integrity is refused unless force.

Composition effect (01 §3.5): install with no row naming the package → append a user-layer insert { id, name }; a row already names it → no tree change, reload that row. remove of a user-owned insert → delete the insert; of a base row → { id, disabled: true }; --purge refuses while the row is enabled.

1.9 Status

PluginStatus (status.ts, canonical per R13), thirteen values:

TierState, per server/app/host:

PluginRuntimeStatus (wire shape pluginStatusSchema): rowId, pluginId, packageName, version, digest, status, detail, generation, activation, isolation, trust, optional, tiers, stats, services, updatedAt. services holds one BackgroundServiceState per background service: state ∈ running \| backoff \| stopped \| crashed \| needs-configuration, restarts, lastError, startedAt, nextRestartAt. detail for waiting reads needs <id> <range> (have <version|none>). The needs-configuration fast path re-runs only on a kernel/preferences.changed for one of the plugin's contributes.settings keys (D8).

1.10 Placement

isolation = row.isolation            (composition override)
       else "worker"                 (source npm or url)
       else "inproc"                 (bundled and path:, always; R2)

contributes.database never changes placement (R2). A non-empty contributes.background starts a separate background worker that runs only the background export; the server entry stays where the rule puts it (D10). A row.isolation: inproc restate on a marketplace row is refused: the row stays worker with a degraded problem (resolve.ts). Every Stage 2 plugin is in-process (D7). Worker gaps: declared input .default()/.transform() do not reach a worker handler; kind: custom methods in a worker's contract.json are refused; per-worker limits are 256 active calls, 32 MiB in flight, 8 MiB per frame, 512 MB old-generation heap. Background services: start after running/degraded/needs-configuration; resolve → stopped; throw → crashed with backoff min(1000 ms × 2^n, 60 s); no kernel schedules table — loop while (!signal.aborted) { …; await sleep(ms, signal) } (D10).

1.11 Composition

Three layer kinds, applied in order over an empty list (01 §7.1, R29):

File format (composition/layers.ts layerFileSchema): version: 1 and rows:. Row fields are id (plugin id), name, config, disabled, inject (service ids), isolation (inproc \| worker), source (bundled \| path), optional, experimental: { summary }. Two op kinds: insert ({ insert: { after?, before?, rows } }) and patch (a plain row in a non-base layer). Rules: base-layer plain rows are one insert and each needs a name; an insert needs a name and refuses an existing id (row X already exists; use a patch); a patch on an unknown id fails (row X not found; use insert); optional and experimental are base-layer fields; every stated field replaces the field whole — no deep merge; there is no remove op. $env is the one expression: { $env: NAME, default: JsonValue }, resolved before config validation.

# ~/.bb/composition.yaml
version: 1
rows:
  - id: github
    disabled: false                        # enable an optional bundled row
  - id: ui-markdown
    config: { mermaid: false, katex: true }   # whole config restated
  - insert:
      after: ui-diff
      rows:
        - id: hello-slot
          name: "@get-bb/plugin-hello-slot"   # examples/hello-slot.composition.yaml uses the same insert as a --patch

Resolution (resolve.ts): name → install record, preferring the path: install when source: path or no bundled artifact exists; read the artifact; set isolation by source; resolve $env; validate and default-fill config against contributes.config through the JSON Schema port. A row whose bb.id differs from the installed id is incompatible. Tree checks: one enabled row per package, CLI-word and tool-name collisions, noun claims, requires cycles, replaces chains. Arbitration for duplicate service ids and exclusive slots is replaces → pin → priority → sorted id (container.order()); bb composition dump previews it. The composition file is not watched in the product (D8; the store-worker Storage proxy lacks watch, README deviation 19): an external edit needs kernel/plugins.reload or a restart. A layer that fails to parse is rejected whole; the previous tree stays booted and dump prints composition error (previous tree still booted).

1.12 Fork

bb plugin fork <id> [--as <newId>] [--detach] = kernel/plugins.fork { id, as: null, detach: false }. No build step. newId defaults to <id>-fork; it must match the id pattern, not be reserved, not equal the original, not be installed or named by a row, and ~/.bb/plugins/src/<newId> must not exist. The original must ship source (src/ or any declared entry file); a dist/-only package is refused with no source shipped for <id>.

Spec 01 §8.1 keeps dist/ for a detached fork; the built forkPluginSource (plugin-build/src/fork.ts) does not, because contracts.mjs declares the old ids. The rewrite is validated through the manifest schema before any byte is copied; a failing rewrite is a ForkError that leaves no directory. With replaces, the fork inherits the original's storage namespace (kv, data.db, preferences, logs), noun claims, CLI words, arbitration rank, and dependents' requires edges (01 §8.2); Loader.storageIdOf walks replaces to the chain root. Output: newId, sourceDir, and next: edit <dir>, then bb plugin dev <dir>. bb plugin revert <id> (fork or original) disables the fork row and re-enables an original the detach disabled. bb plugin remove <forkId> deletes the insert, the install row, and the plugins/src dir; --purge on a replaces fork refuses with storage belongs to <original>; purge that plugin instead.

1.13 Per-plugin storage

Under ~/.bb/ (data dir, Storage port; the loader never imports node:fs):

Server-tier API (PluginContext, ports.ts): ctx.storage.kv.get/set/delete/list(prefix); ctx.storage.database() → async SqliteHandle (exec, run, get, all, batch, close), requires contributes.database: true else precondition; ctx.storage.migrate(db, statements) (append-only, keyed by index, CREATE TABLE not IF NOT EXISTS) — the SDK wraps both as ctx.storage.openDatabase(migrations) (D13); ctx.log.debug/info/warn/error(message, fields?); ctx.secrets.resolve({ name }); ctx.hostClient(contract, name) for a declared hostRoles[].name. Settings are preferences: read kernel/preferences.get { key: "<id>/<key>", scope: "profile", threadId: null }, write with expectedUpdatedAt: number | null (#29). A secret setting holds plugin:<id>/<key>; bb secret put plugin:<id>/<key> writes the value. An in-process row's data.db writer is the store worker behind the sqlite envelope; a worker row holds a local driver (R2). The handle is per generation; a call after dispose rejects stale_handle. bb plugin remove <id> keeps storage; --purge deletes kv, preferences, data.db, logs.

1.14 The bb plugin and bb composition CLI

Both trees derive from kernel/plugins (service.ts, group plugin, extensible) and kernel/composition (composition/service.ts, group composition). Mutations take actors: ["human", "agent"]; a plugin actor gets forbidden. The plugin id is positional 0 on id-taking words.

Reserved names (stage-2/04 §4): kernel CLI groups auth, catalog, composition, guide, host (machine), import, plugin, preferences, realtime, runtime, secret, store, system, ui; extensible groups plugin, secret, host, runtime; a duplicate top-level word is dropped with a warning: line, never a failure (D6). Tool names default to <plugin_id>_<service>_<method> (snake_case, ≤ 64 chars); a collision is a plan-time degraded.