Event hooks - ADOS Documentation

On the GCS half the host runs the bridge; the plugin consumes two flavors of message:

Events: pushed from the host, no response expected (config.changed, theme.changed, telemetry.<topic>).
Responses: returned by the host in reply to a plugin request.

Plugins subscribe to events and send requests; they never receive unsolicited requests.

Events the host pushes

Method	Capability	Args	When
`theme.changed`	none	`Record<string, string>` of CSS variables	Initial mount and on every host theme change.
`config.changed`	none	the plugin’s full config object	Operator saves a new config.
`telemetry.<topic>`	`telemetry.subscribe.<topic>`	topic-specific payload	After the plugin subscribed to `<topic>`.

Subscribe via ctx.client.on("config.changed", handler) or the typed wrappers ctx.config.onChange, ctx.theme.onChange, and ctx.telemetry.subscribe. For any other host-pushed topic (for example the video.overlay host props the host forwards to a video overlay iframe, or an agent plugin’s state read-back), use the generic ctx.events.subscribe(topic, handler), which returns an unsubscribe function and does no request/response round-trip.

Requests the plugin can send

The SDK context exposes these high-level wrappers. Each delegates to a single PluginClient; drop to ctx.client.request(method, capability, args) for anything else.

Wrapper	Method	Capability	Returns
`ctx.telemetry.subscribe(topic, handler)`	`telemetry.subscribe`	`telemetry.subscribe.<topic>`	unsubscribe function
`ctx.command.send(command, args)`	`command.send`	`command.send`	host-defined
`ctx.notifications.publish(payload)`	`notification.publish`	`ui.slot.notification-channel`	host-defined
`ctx.recording.mark(payload)`	`recording.mark`	`recording.write`	host-defined
`ctx.mission.read(missionId)`	`mission.read`	`mission.read`	mission body
`ctx.mission.write(update)`	`mission.write`	`mission.write`	host-defined

The host registry also recognizes telemetry.unsubscribe, recording.start and recording.stop (capability recording.write), events.subscribe and events.publish (event.subscribe / event.publish, both require a topic arg), cloud.read and cloud.write, plus three always-allowed methods that need no capability: ping, notify, and i18n.t. A method that is not in the registry is rejected with method_unknown. The host re-resolves the required capability from the method (and, for telemetry, from the topic) and checks the granted set. The plugin never computes the capability id itself.

Wire shape

interface RpcEnvelope<TArgs = unknown> {
  id: string;
  type: "request" | "response" | "event";
  method: string;
  capability: string;
  args: TArgs;
  version: 1;
  error?: { code: string; message: string };
}

The plugin never builds these by hand. The SDK’s PluginClient generates the id, attaches the protocol version, and waits for the correlated response.

Error envelopes

When the host rejects a request it returns a response with error: { code, message }. The SDK throws a HostError whose code field carries the machine-readable code:

Code	Meaning
`permission_denied`	The required capability is not in the granted set.
`capability_denied`	The per-request capability token failed validation, or its claimed capability set does not cover the request. The message carries the reason after a colon (e.g. `capability_denied:token_expired`).
`method_unknown`	The method is not in the host’s registry.
`schema_invalid`	Args failed schema validation.
`handler_unset`	The host knows the method but no handler is wired.
`handler_error`	The host’s handler threw; the message carries the cause.

Branch on code, not on message. Messages are for log lines.

There is also an origin_mismatch error, but the host never sends it to the plugin. When a message arrives from a window that is not the trusted iframe, the bridge drops it and records a security event host-side rather than replying. A plugin will never see it on the wire.

Theming

theme.changed arrives once on mount and again on every theme toggle. The payload is a Record<string, string> of CSS variables. Apply them by walking the entries:

ctx.theme.onChange((vars) => {
  for (const [key, value] of Object.entries(vars)) {
    document.documentElement.style.setProperty(key, value);
  }
});

The SDK does not auto-apply because plugins choose how granular they want to be (full root, scoped to a panel, or ignored).

i18n

Plugin authors ship a locale bundle in their archive; the host streams the active bundle to the plugin on mount. The SDK formats keys with ctx.i18n.t(key, params):

ctx.i18n.t("anomaly.cellLow", { voltage: 3.4 });
// "Cell low: 3.4 V"

Missing keys fall back to the key itself; missing parameters render the {name} placeholder so it is visible in QA.

​Events the host pushes

​Requests the plugin can send

​Wire shape

​Error envelopes

​Theming

​i18n

​See also

Events the host pushes

Requests the plugin can send

Wire shape

Error envelopes

Theming

i18n

See also