Manifest reference

The manifest is the helper's installation contract. It is different from the starter's local airdeck.build.json. Keep its identity, permissions and runtime resources accurate; the packer cannot infer the behavior of your executable.

Every plugin package has a manifest.json at its root.

A minimal manifest

{
  "id": "com.example.echo",
  "name": "Echo Beep",
  "version": "1.0.0",
  "api_version": 2,
  "entrypoint": "./echo-plugin",
  "permissions": [],
  "files": []
}

Identity and execution

The example manifests also use mode: "targeted" and types: []. Keep targeted routing for button-driven examples. Do not mark a community plugin as built-in.

Calling a capability

{
  "permissions": ["core.media.playback.control"],
  "uses": [{"id": "core.media", "min_version": "1.0.0", "max_version": "2.0.0"}]
}

All requested permissions are required. Users approve them before execution. Adding permissions in an update requires approval again; users can revoke grants in the helper.

Providing or depending on capabilities

capability_schemas lists source schema files. The packer validates them, embeds the contracts as capabilities, and includes schema files in the package. Provider capability and permission IDs must use the provider plugin ID namespace.

Consumers declare dependencies for the provider plugin and uses for its capability. min_version is inclusive and max_version is exclusive. See providers for a complete example.

Resource safety

Entrypoints and resources stay inside the package. Absolute paths, parent traversal and escaping symlinks are rejected by the packer. Explicitly list runtime dependencies: missing local files are not fetched automatically.

On Windows, native binaries use .exe. tools/build_examples.py selects the correct entrypoint and packs the runtime files. Changing an ID requires changing the ID reported by the code as well.

Routing and acknowledgement fields

mode is normally targeted for a button-driven plugin. types lists owned routed message types; leave it empty for an invoke-only starter. The helper also supports omni routing for broader event observation, but explicit plugin commands still target their owner. Do not use omni mode as a substitute for declaring required broker permissions.

ack defaults to true when omitted. With acknowledgement enabled, an invocation is expected to return success or error. ack: false is a fire-and-forget setting for specialized traffic; it reduces the caller's ability to observe failure. Keep the starter's default acknowledgement behavior.

poll_tier opts into host-scheduled refresh. Use the host scheduler instead of your own repeating timer. Use high, normal or low. The helper owns the configurable timing policy; do not implement an independent timer using a guessed interval.

builtin identifies helper-managed packages. Community manifests should not claim built-in status. Being bundled is not elevated broker authority and does not remove required permission checks.

Versioned requirement objects

A dependency contains id, required min_version, and optional exclusive max_version. A capability use contains id, min_version, optional exclusive max_version, and optional provider when a provider plugin owns it.

Specify an upper boundary when the next major version could break your code. Installing a matching plugin version and using a matching capability version are separate checks. See Versions and upgrades.

Source manifest versus packaged manifest

capability_schemas is a source packaging input. The packer validates those JSON files and embeds their contracts in capabilities in the archive manifest. The helper consumes the embedded contracts rather than running the generator during installation.

The starter builder also chooses the executable suffix/launcher and lists runtime resources in the packaged files. Inspect the final archive manifest when debugging installation, not only the source manifest in your editor.