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, what backend is used to run it, where is the entry file, what is the minimum BT version, what permissions are required, how many parameters and return values are allowed to be transmitted in a single call, and the extension runtime mode.

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`.
`description`	String	Optional description text.
`author`	String	Optional author text.
`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.
`permissions`	Array	Array of capability permissions of the extended declaration. Only write the required permissions; do not write the unnecessary permissions.
`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"`.

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.

Permission Description

Permission	Description
`fs_read`	Allows declaration of read file path parameters.
`fs_write`	Allows declaration of write file path parameters.
`net`	Reserved for network communication capability declaration.
`http`	Reserved for HTTP client capability declarations.
`process`	Reserved for process capability declarations.
`env`	Reserved for environment variable capability declarations.

permissions Only string arrays can be used, such as ["fs_read", "fs_write"]. The permissions must be allowed at the same time as the permission configuration of the running process. The extension declares a certain permission, but when the running process prohibits this capability, the extension will fail to load.

Return Value

manifest.json is not a script function and has no runtime return value. When the verification is successful, BT will continue to read bindings and entry files; when the verification fails, the loading process returns a Chinese error and stops loading the extension.

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.

- 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.