SDK — Components I Ship
A biome can ship zero or more executable components. The current manifest declares them in xema.components[]; the earlier ships.apis[] model is retired.
Component kinds
| Kind | Purpose |
|---|---|
content | Materialized Agents, Skills, Workflows, schemas, and other packaged content |
web | Static bundle hosted by the Xema web shell |
adapter | Module implementing a declared host adapter protocol |
service | Long-running request-serving component |
worker | Long-running queue or event worker |
job | Finite, scheduled, or one-shot component |
Each component combines an artifact, entrypoint, protocol, execution modes, and runtime requirements. See the generated Manifest Reference for the exact shape.
When to ship executable code
Ship a service, worker, job, or adapter when the biome needs behavior that declarative content cannot express, such as:
- a long-running request, event, or queue consumer;
- a custom capability implementation;
- a provider adapter;
- domain persistence with non-trivial invariants;
- scheduled reconciliation;
- a protocol surface such as HTTP or a worker queue.
Do not ship a service merely to register Agents, Skills, Workflows, or contribution envelopes. A content component can materialize those.
Runtime requirements are part of the contract
An executable component must declare:
- allowed tenancy scopes and verified tenant context;
- minimum isolation and trust;
- allowed locality;
- state kind, persistence, consistency, and tenant fencing where durable;
- minimum and preferred resources plus optional accelerator needs;
- runtime kind and supported version;
- ingress, egress, raw-body, and device requirements;
- scaling mode, concurrency, readiness, graceful drain, and workload hints.
The operator and scheduler use these declarations when deciding whether and where the component can run. A requirement is not documentation-only metadata.
HTTP services and capabilities
An HTTP component declares its protocol revision, stable service name, authentication scopes, service dependencies, and any exposed capabilities.
Other biomes must not import its implementation or invent a direct dependency on its deployment address. Cross-biome operations use published clients where appropriate and the capability plane for domain actions, preserving authorization and audit.
Adapter components and the adapter host
An adapter component is a module that the adapter host loads and runs. First-party connectors are adapter components. The component declares the adapter protocol at revision v1 and targets the host ABI xema-adapter-host with version range ^1:
1{
2 "key": "connector-adapter",
3 "kind": "adapter",
4 "artifact": { "kind": "host-module", "path": "dist/connector-adapters/index.js" },
5 "entrypoint": { "kind": "module-export", "module": "dist/connector-adapters/index.js", "exportName": "default" },
6 "protocol": { "kind": "adapter", "revision": "v1" },
7 "hostAbi": { "name": "xema-adapter-host", "versionRange": "^1" },
8 "executionModes": ["shared-host", "isolated"]
9}The module's default export is the list of provider modules it contributes. A provider module can supply:
- a webhook verifier, an event mapper that turns the provider's payload into a canonical envelope, an idempotency-key extractor, and optionally an org resolver;
- resource listers, which feed pickers such as a repository or project chooser in the install flow;
- outbound actions, which are the connector's capabilities;
- installation-credential minting, for providers with app-style installs.
The adapter host calls those entry points for a loaded bundle; the module never opens its own webhook route. All inbound traffic comes through the connector gateway's single ingress edge.
The host is a runtime, not a service of its own. It runs when an installed biome has adapter components to mount, and with none installed there is nothing to run. Which biomes it mounts, and the state of each mount, are reported by the host. shared-host runs the module alongside others in one host process; isolated gives the module its own. A biome lists the modes it supports, and the operator picks within the component's declared runtime requirements.
Scaling and lifecycle
Horizontal components declare per-instance concurrency, readiness behavior, and a drain contract. This lets rollouts stop accepting new work and complete or hand off in-flight work deliberately.
The deployment profile supplies the physical replicas and substrate; the biome supplies the workload requirements.
Related pages
Previous: ← Lifecycle Hooks Next: Storage →