6. Host tier — @get-bb/plugin-sdk/host

The host tier is plugin code that runs in a child process on a host machine (the core machine or an enrolled remote host). Node is allowed here. @get-bb/plugin-sdk/host is the authoring surface: defineHostEntry builds the entry's default export, defineHostRole and defineEnvironmentProvider build the rows the bootstrap selects, defineHostCommands / implementHostCommands / signalEmitter give typed commands and signals, and roleStorage / roleTempStorage open the role's private directory. SDK source: packages/plugin-sdk/src/host/index.ts. Kernel: packages/kernel-host (spec 05). Built wins; every deviation is marked.

Status legend in the tables: built (shipped and exercised by a kernel caller), served (the role process answers it, no kernel caller found), no-op, absent, unwired.

6.1 defineHostEntry and the bootstrap

The bootstrap is one program for every launch.kind: "module" role, including provider bridges: bin/bb-host-role.mjs → local/bootstrap.ts#main (05 §6.2). What it does, in order:

1. Parses the kernel-owned argv: --plugin --generation --artifact --role --name --export --data-dir --temp-dir --cwd [--env <envId> --write-roots <json> | --root <RootRef json>] --limits <RoleLimits json>.
2. umask 077, chdir(--cwd) (the scope root, or the temp dir for scope none), ignores SIGINT, installs SIGTERM → default.dispose() → exit(0).
3. Registers a resolver hook so the entry's bare @get-bb/plugin-sdk/* imports resolve from the host's own install, not the artifact cache (local/sdk-resolve.ts).
4. Imports <artifact>/meta.json#entry (default host.mjs) and selects the export: the named export --export if present, else default.roles[role][name]; neither → exit 1.
5. provider-bridge: the export must be a defineBridge() object; prints role/ready and hands stdio to runBridge. Every other role: serveRole prints role/ready then runs a JSON-RPC 2.0 line loop on stdio (@bb/bridge-kit peer; maxLineBytes from --limits).
6. Dispatch in serveRole: env/provision|reconnect|destroy|summarize when the export has a provision function (an EnvironmentProvider); <pluginId>/<command> → the export's property of that name called as (params ?? {}, ctx); role/dispose → abort lifecycle; anything else → JSON-RPC METHOD_NOT_FOUND. stdin EOF aborts lifecycle and ends the process.

Deviations from 05 §6.2 in the built bootstrap (local/bootstrap.ts): the export is duck-typed (an object with provision is a provider; kind: "provider-bridge" is a bridge; anything else is a command table), not validated with a Standard Schema; the spec's "or commands for the rpc role" fallback is not implemented, so only roles[role][name] is ever selected (D14); the child does not self-exit on idle — idle eviction is the supervisor's (§6.7). launch.kind: "exec" spawns command args directly with the same cwd/env/stdio discipline and no bootstrap code.

6.2 Roles

What each role is for (05 §6.1) and what drives it today:

One process per (pluginId, generation, role, name, scope); the scope comes from the caller that starts the role (RoleSpec.scope), not from the manifest.

6.3 Host commands and signals

The contract object lives in the plugin's contracts module and is the one thing both ends validate against (05 §4.7). The manifest carries names only (§6.8).

The server side (@get-bb/plugin-sdk/server, server/host-client.ts): ctx.hostClient(contract, name) returns TypedHostClient<C> — call(command, input, opts?: HostCallOptions) validates input before the frame leaves core and output after rpc.res arrives; onSignal(name, listener) validates the payload and logs instead of delivering a payload outside the schema (hostClient.onSignal: payload rejected by the signal schema); onExit(listener) receives HostExit { roleId, exitCode, signal }. HostCallOptions is { hostId?: string | null; timeoutMs?: number | null } (null = the core's own host / the loader's default deadline). name must be a contributes.hostRoles[].name of this plugin (precondition otherwise).

As built: the loader's hostClient factory is unwired in the product — a call answers service_unavailable (D15; as-built §6 "Loader hostClient unwired"). Host tiers still start. In tests createTestPlugin wires host.role(name) to the same roles[role][name][command] dispatch the bootstrap uses and relays signals and exits. Also as built: 05 §4.7's rule that the loader refuses a host entry whose commands/signals exports differ from contributes.hostCommands/hostSignals has no implementation in kernel-loader, kernel-host or plugin-build; the manifest lists are parsed (kernel-loader/src/manifest.ts), each hostSignals name is subscribed for relay (loader/load.ts), and an undeclared <pluginId>/<command> is answered by the role process with METHOD_NOT_FOUND.

// contracts.ts — schemas only (examples/plugins/hello-slot/src/contracts.ts)
export const helloHost = defineHostCommands({
  id: "hello-slot",
  commands: { "host-greet": { input: z.strictObject({ name: z.string() }), output: hostGreetingSchema } },
});
// host.ts — the role process answers it; ctx is the RoleContext of §6.4
export default defineHostEntry({
  roles: [defineHostRole({ role: "rpc", name: "echo", contract: helloHost,
    commands: { "host-greet": async ({ name }, ctx) => ({ greeting: `Hello, ${name}`, pid: process.pid, role: ctx.name }) } })],
});

Server-side calls at dc07292bf. Core wires ctx.hostClient through createHostClients(...).clientFor (packages/core/src/core.ts); createRoleSpecs is shared by ctx.hostClient, kernel/host-runtime, and kernel/bridge-driver. The "unwired" status in D15 describes 6f3d4592f.

6.4 RoleContext

HostRuntime (port/host-runtime.ts, 05 §2.1) is the kernel's nine-member port, held by core and never by a plugin: fs (stat/read/write/list/search/mkdir/move/remove/exists/browse, every call scoped), exec (run buffered, spawn streaming), vcs (git, repoInfo, lock — a host-wide named mutex), pty (open/attach/list), watch (set, events), environments (provision/reconnect/destroy/cancel/loaded), artifacts (ensure/has/gc), roles (start/attach/list/stop), events (append, flush-before-result); plus hostId and info. A role process gets the narrowed, scope-bound form below (bindScope; pty and watch are absent inside a role process by design, BindablePorts). Built from local/bootstrap.ts#roleContextFor.

6.5 Environment providers

Containment rules a provider must follow (05 §5.2, §5.5; examples/plugins/hello-slot/src/host.ts):

• A persisted handle is input: the row may be stale, tampered with, or mis-routed from another provider. Re-derive the expected root from envId and refuse a handle whose kind or root differs (precondition) before any filesystem call.
• Do filesystem work through roleStorage(ctx) (§6.6) or the scoped ports; both refuse a path that escapes their root. A provider role's scope is none, so ctx.fs/exec/vcs are bound to the plugin root (dataDir).
• Destroy order: the kernel stops the env's bridges and ptys → the provider calls ctx.process.killByCwd(root, { graceMs: 2000 }) → the provider removes the directory → core applies destroy.completed. A result lost to a disconnect becomes destroy.lost; reconcile answers it on the next session.
• Per-environment mutation serialization (05 §4.5) is not implemented on the host; ctx.vcs.lock is the mutex you have (packages/kernel-host/README.md, "Deviations" part 2).

// a provider that owns a directory under the role's data dir (abridged from hello-slot `scratch`)
export const scratch = defineEnvironmentProvider<Record<string, never>>({
  name: "scratch", label: "Scratch directory", ownsRoot: true, options: z.strictObject({}),
  async provision({ envId, progress }, ctx) {
    const storage = roleStorage(ctx); const rel = `scratch/${envId}`;   // envId checked to be one path segment
    progress.step("mkdir", "creating", "started"); await storage.mkdir(rel); progress.step("mkdir", "created", "completed");
    return { kind: "local-path", root: storage.path(rel), writeRoots: [storage.path(rel)], persisted: {} };
  },
  async reconnect({ envId, handle }, ctx) { /* refuse a handle whose root ≠ storage.path(`scratch/${envId}`) */ return handle; },
  async destroy({ envId, handle }, ctx) { await roleStorage(ctx).remove(`scratch/${envId}`, { recursive: true }); },
  async summarize(handle) { return { label: "scratch", path: handle.kind === "local-path" ? handle.root : null, isRepo: false, isWorktree: false, branch: null, baseBranch: null, defaultBranch: null }; },
});

Changes at dc07292bf (kernel-host/src/port/environment-provider.ts, host-runtime.ts): provision receives source: ProjectSource | null — null when the project has no source on this host; a provider that needs one refuses with host/source_required (env-local's local-dir and git-worktree do). The role answers env/describe {} → {label, ownsRoot, optionsSchema} (the bootstrap converts the zod options to JSON Schema) for provider discovery (05 §6.5). EnvironmentsPort gains summarize({providerId, handle}) → EnvironmentSummary and describe({providerId}) → ProviderDescriptor. Provision progress reaches core as env.progress {envId, step, output} notifications; the host no longer appends an environment/provision-progress event.

6.6 Host storage

Every HostStorage method (packages/kernel-store/src/storage.ts); paths are relative to the root, and every call contains them lexically and physically — a path that escapes the root or crosses a symlink out of it is forbidden (storage-local.ts):

6.7 Limits and process hygiene

Role-RPC admission per (pluginId, generation) on a host (port/schemas.ts, local/roles.ts#admit, local/role-rpc.ts, rpc/role-client.ts; 05 §4.7): 256 active calls (service_unavailable past it), 32 MiB in-flight input (host/too_large), 8 MiB per result (host/too_large, checked on both the local and remote client), 30 s default per call (timeout); timeoutMs: null on the remote client waits indefinitely for a retained long call.

RoleLimits (manifest limits, defaults filled by the loader, DEFAULT_ROLE_LIMITS): maxRssBytes 1 GiB, idleMs 300 000, startTimeoutMs 10 000, stopGraceMs 5 000, maxLineBytes 1 MiB, maxStderrLines 1 000. The supervisor (local/roles.ts): waits for the role/ready line within startTimeoutMs else SIGKILL + host/role_start_failed; SIGKILLs a process that emits a stdout line over maxLineBytes; relays only lines that start with {; stops an idle process after idleMs when no host-side lease is held (any line in either direction resets the clock; idleMs: 0 disables); stop = leader SIGTERM → group → SIGKILL after stopGraceMs; never restarts — the next call that needs the role starts it again; every exit is forwarded to core as roles.exited {roleId, pluginId, role, name, exit, stderr}. maxRssBytes is carried in the spec but no enforcement was found in local/roles.ts.

Process env of a role child (local/shell-env.ts#roleProcessEnv, local/process.ts#sanitizeInheritedEnv; 05 §7, R18), in four layers: (1) the sanitized inherited env (05 §7: every BB_*, NODE_ENV, and npm_config_* dropped); (2) the login-shell PATH, captured once per host boot; (3) RoleSpec.env, the role's own non-BB_* keys; (4) the kernel overlay BB_CLI, BB_HOST_ID, and BB_SERVER_URL when the host has one. RoleSpec.env may carry no BB_* key at all (roleSpecSchema refine; stricter than 05 §7's BB_BRIDGE_RECORD exception). The per-thread names (BB_THREAD_ID, BB_PROJECT_ID, BB_ENVIRONMENT_ID, BB_THREAD_STORAGE) and plugin-contributed BB_* values from threads/agent-config are merged at bridge spawn only (mergeThreadEnv; a contributed kernel-owned name is overwritten and logged) — a role process is not a thread and never sees them. KERNEL_ENV_NAMES is the kernel-owned list. Also: umask 077; own process group where supported; cwd = scope root or the temp dir; call ctx.process.killByCwd before removing any directory (05 §5.5).

6.8 Manifest keys for the host tier

package.json#bb (01 §2.2, §2.6; kernel-loader/src/manifest.ts; R9):

There is no hostRoots key and no bridgeEntries key (R9; 05 §6.5). Declared roles are not capabilities: a host can run a plugin's roles once artifacts.ensure of its host entry succeeded there (05 §6.5).

6.9 Types index

Testing (@get-bb/plugin-sdk/testing, covered in its own section): fakeRoleContext(init) builds a RoleContext whose fs/exec/vcs/process throw host/unsupported unless supplied and records signals, events and logs; createTestPlugin(...).host.role(name) dispatches roles[role][name][command] exactly as the bootstrap does.