manifest.json

Function

manifest.json is the identity and runtime declaration of the extension package. It tells BT whether this package is a .bts extension, what the extension is called, which backend and entry file it uses, its minimum BT version, its call-size limits, and its runtime mode. Extensions are trusted local program dependencies and do not declare per-package permissions.

Syntax

Pure BT extension example:

WASM extension only needs to change the backend related fields to:

WASM shared runtime Configuration example:

Parameters

Field	Type	Description
`format`	String	Fixed to `bts`.
`format_version`	Number	Package format version, use `1`.
`name`	String	Extension package name, only lowercase letters, numbers and underscores can be used, and it starts with a lowercase letter.
`version`	String	Extend its own version, using three-stage SemVer, such as `1.0.0`.
`summary`	String	Optional short English catalog summary.
`description`	String	Optional description text.
`author`	String	Optional author text.
`developer`	Object	Optional stable developer identity with `id`, `name`, and optional `homepage`.
`repository`	String	Optional public source repository URL.
`license`	String	Optional SPDX license expression.
`locales`	Object	Optional localized display metadata keyed by canonical BCP 47 tags such as `zh-CN`.
`kind`	String	Backend type, can only be `bt` or `wasm`.
`abi`	String	Backend ABI, must match `kind`.
`bt_min_version`	String	Minimum BT version required by the extension.
`api_version`	Number	bindings semantic version, use `1`.
`entry`	String	The relative path within the package of the backend entry file.
`bindings`	String	bindings Relative path within the package describing the file.
`limits`	Object	The upper limit of the parameter and return value encoding size for a single call.
`runtime`	Object	Optional runtime mode configuration; default is equivalent to `mode: "thread_local"`.

Each locales.<tag> object accepts only summary, description, and developer_name. Language keys must use canonical BCP 47 casing; Simplified Chinese is zh-CN, matching README.zh-CN.md. Localization changes display text only and never changes extension names, API identifiers, configuration fields, or event names.

kind and abi

kind	abi	meaning
`bt`	`bts-bt-1`	The entry file is BT source code, and the functions and object methods are executed by pure BT Runner.
`wasm`	`bts-wasi-1`	The entry file is the WASM module, and the call is completed through WASI P1 and BtValueBinary.

If kind and abi do not match, the extension will report an error during the loading phase.

runtime runtime configuration

Field	Type	Default value	Description
`mode`	String	`thread_local`	Runtime mode, can only be `thread_local` or `shared`.
`workers`	Number	`1`	Shared mode worker number, range `1..=64`.
`queue_limit`	Number	`1024`	shared mode waiting queue length, range `1..=65536`.
`call_timeout_ms`	Number	`30000`	Shared mode single call timeout, range `1..=300000`.
`idle_ttl_ms`	Number	`300000`	Shared mode idle retention time, range `1..=3600000`.
`max_objects`	Number	`65536`	The upper limit of the number of shared mode service-level objects, range `1..=65536`.
`max_worker_objects`	Number	`4096`	The upper limit of the number of objects in a single worker in shared mode is in the range of `1..=4096` and cannot be greater than `max_objects`.
`max_inflight_calls`	Number	`64`	The upper limit of the number of calls in shared mode execution, the range is `1..=4096`.

When runtime is missing, the extension continues to use the current thread's local Runner cache and does not change existing extension behavior. The first version of mode=shared only allows kind=wasm. Pure BT extension declaration shared will report an error during the manifest verification phase.

The current version has been connected to the project level ExtensionService. The WASM extension that declares mode=shared will create an independent bounded worker queue. The entry function can return the original value or the extended object through the worker; when returning the extended object, the host will allocate host_object_id and route back to the local object ID of the worker who created the object before calling the object method. A Chinese error will be returned when the queue is full, the service is shut down, the call during execution exceeds the upper limit, the number of service-level objects or the number of single worker objects exceeds the upper limit.

call_timeout_ms does not just call the thread wait limit. The shared worker will enable the Wasmtime epoch interrupt. After the timeout, the host will mark the target worker, trigger the WASM trap, and rebuild the WASM Store/Instance after the worker returns to avoid timeout calls permanently occupying service capacity. Service statistics will include workers, queued, running, completed, failed, timed_out, objects and the number of objects per worker.

Return Value

manifest.json is not a script function and has no runtime return value. When validation succeeds, BT continues to read bindings and entry files; when validation fails, loading returns an English error and stops.

Code Examples

Correspondence between pure BT extension entry and manifest:

manifest.entry points to src/lib.bt containing this source code, manifest.kind writes bt, manifest.abi writes bts-bt-1.

Notes

entry and bindings must be safe relative paths within the package. Absolute paths, backslashes, empty paths, ., .. or paths with drive letters cannot be used.
entry cannot point to the same file as bindings.
The permissions field has been removed. A package that still contains it fails manifest validation and must be rebuilt in the new .bts format.
All installed extensions use the same host ABI. Their effective authority follows the BT process-wide policy and operating-system account, not package origin or registry membership.
Installing an extension means trusting its code. The official catalog reviews only the exact open-source versions it distributes; local, private, modified, and closed-source packages remain unrestricted and outside that review.
limits.max_args_bytes and limits.max_result_bytes cannot be 0 or exceed the host hard cap.
Unknown fields cannot appear in runtime to prevent extension authors from mistakenly thinking that unimplemented configurations have taken effect.
runtime.mode=shared does not change the BT request variable lifecycle, nor does it allow normal script global variables to be shared across requests.

- runtime.mode=shared already supports extended object host routing; when close() or dispose() is marked as lifecycle: "dispose" and the call succeeds, the host object handle becomes invalid.

call_timeout_ms of runtime.mode=shared will trigger the WASM interrupt and running state reconstruction of the target worker, and cannot be used to accurately cancel the long-term blocking host call.
Extension names, entry names, parameter names and method names should comply with BT's snake_case naming style.