Developer Guide

Manifest fields

This page adapts the manifest guidance from the extension authoring guide into a field-by-field reference. Start with the common manifest shape from the markdown, then add only the optional fields your extension really uses.

✦

The authoring markdown shows the common manifest shape. This reference keeps that baseline and adds the optional public fields that the runtime also accepts today.

export const manifest = {
  apiVersion: 6,
  version: '1.0.0',
  key: 'my-extension',
  name: 'My Extension',
  category: 'device',
  icon: 'Heart',
  description: 'Short description',
  supportsPromptContributions: true,
  supportsLifecycleHooks: true,
  supportsArtifacts: true,
  supportsEmergencyStop: true,
  chatFooter: { order: 100 },
  chatPanel: { order: 100 },
  overlay: { order: 100 }, // v6+ — pairs with OverlayComponent
};

Required fields

New extensions should always define the core identity fields shown in the authoring guide. These are the fields the loader and app surfaces depend on first.

Required for new extensions

apiVersion

Use apiVersion, not formatVersion. New extensions should target API v6.

This tells the loader which public runtime contract your module expects. The docs and authoring markdown both target API v6 for new work.

If you ship an extension that expects a newer API than the app supports, the loader can reject it instead of failing later at runtime.

Author-controlled

version

Semver-like string such as 1.0.0.

Use this for your own extension versioning. It is not the runtime API version, and it does not replace apiVersion.

The field is treated as author metadata for installs, listings, and version history.

Core identity

key, name, category, icon, description

These fields define how the extension is stored, grouped, and labeled across the app.

key must stay stable and unique, because persistence, namespacing, and installs use it as the durable identifier.

name, icon, and description are the human-facing labels shown in settings, docs, and marketplace-style surfaces.

category controls grouping and should be one of toy, device, integration, or system.

UI and surface fields

These fields opt the extension into host-owned app surfaces. The app still owns the shell; your manifest tells it which surfaces to render and in what order.

Settings page

settings and SettingsComponent

Use settings for the default host form. Add SettingsComponent only when you need richer explanatory or custom layout.

settings lets the host render the normal extension settings form, including layouts and persistence. That is the default path when the standard form is enough.

SettingsComponent is the escape hatch for setup-heavy or mixed-content settings pages. The host still owns routing, chrome, enable or disable controls, and persistence flows.

Top-bar dropdown

showInTopBar and StatusComponent

Use showInTopBar to hide the extension from the top bar. Use StatusComponent when quickLayout is not enough.

The runtime treats the top-bar surface as host-owned. Setting showInTopBar to false hides the status icon entirely; otherwise the default is to show it.

StatusComponent lets the extension render richer compact UI inside that host shell when a few quick settings are not enough.

Chat footer area

chatFooter, FooterComponent, and chatBarActions

Use chatFooter for drawer registration, FooterComponent for richer footer UI, and chatBarActions only for tiny icon buttons.

chatFooter registers content in the drawer above the composer and uses order to sort multiple extensions.

FooterComponent is the richer UI path described in the authoring markdown. If you skip it, the host can fall back to status and quick-layout content.

chatBarActions is for tiny icon actions above the composer, not full footer controls or text-heavy helpers.

Chat side panel

chatPanel and PanelComponent

chatPanel opts the extension into the host-owned right-hand extension panel and uses an order value to place the section.

Add PanelComponent when the default shell needs a custom body such as device dashboards, richer controls, or live status readouts.

Fullscreen overlay (API v6+)

overlay and OverlayComponent

overlay opts the extension into the host's app-root overlay stack. Multiple extensions can register overlays — they composite simultaneously, z-ordered by overlay.order ascending (lower numbers render behind higher ones).

OverlayComponent is the component the host mounts via React portal to document.body. The wrapper defaults to position: fixed; inset: 0; pointer-events: none so the underlying app stays interactive. Opt back into pointer events inside your component when you need it.

Use this for hypnosis effects, sensor HUDs, full-screen camera previews — anything that needs to escape route content and panel chrome. Render null when you have nothing to show; the host always mounts you while the extension is enabled.

Requirement badges

requiresBluetooth and requiresApiKey

Optional metadata for surfaces that need to explain setup requirements to the user.

These flags let the app badge the extension as Bluetooth-dependent or API-key-dependent in settings and listing surfaces. They are declarative hints for the host UI rather than behavior switches.

Capability flags

These optional flags advertise which runtime features your extension intends to use. They are especially useful for settings, docs, and toy safety affordances.

Prompt policy hint

supportsPromptContributions

Set this when the extension contributes ambient prompt guidance.

The authoring guide uses this flag in the common manifest example for extensions that export getPromptContributions() or request-time prompt mutations.

Hook capability hint

supportsLifecycleHooks

Set this when the extension relies on lifecycle hooks such as onBeforeLLMRequest or onAfterAssistantMessage.

This advertises that the extension participates in turn lifecycle behavior beyond a simple tool call path.

Artifact capability hint

supportsArtifacts

Set this when the extension emits images or other app-owned artifacts.

The current public runtime uses this to signal support for ctx.runtime.emitImage(...).

Toy safety hint

supportsEmergencyStop

Toy-only hint that pairs with onEmergencyToyStop(ctx) and the host Toy E-Stop button.

The authoring guide is explicit here: declare support in the manifest and export the stop hook if the toy extension should participate in emergency stop handling.