GCS bridge methods

On the GCS half, Mission Control runs the bridge and the plugin’s iframe talks to it over postMessage. There are two kinds of message:

Requests the plugin sends, each answered by one response.
Events Mission Control pushes into the frame, with no response.

Plugins never receive unsolicited requests. For the agent-side event bus that an agent half publishes and subscribes on, see Event hooks and bus. For the typed SDK wrappers over these methods, see the TypeScript SDK.

Methods the plugin can call

The bridge resolves the capability each call needs from the method (and, where noted, from its arguments) and checks it against the plugin’s grants. A method not in this list is rejected with method_unknown.

Method	Capability	Notes
`ping`	none	Liveness check.
`i18n.t`	none	Resolve a locale key.
`notify`	`ui.slot.notification-channel`
`notification.publish`	`ui.slot.notification-channel`
`telemetry.subscribe`	`telemetry.subscribe.<topic>`	Requires a `topic` argument; the topic-scoped id is checked exactly.
`telemetry.unsubscribe`	none
`command.send`	`command.send`	With the command `vision.designate` it needs `vision.track.designate` instead. The operator confirms every command.
`recording.start`	`recording.write`
`recording.stop`	`recording.write`
`recording.mark`	`recording.write`
`mission.read`	`mission.read`
`mission.write`	`mission.write`	The operator confirms the write.
`events.subscribe`	`event.subscribe`	Requires a `topic` argument. Opens delivery of a GCS plugin-bus topic.
`events.publish`	`event.publish`	Requires a `topic` argument.
`events.unsubscribe`	none	Requires a `topic` argument.
`cloud.read`	`cloud.read`
`records.list`	`cloud.records`	The plugin’s own cloud records only.
`records.get`	`cloud.records`
`records.put`	`cloud.records`
`records.remove`	`cloud.records`
`cockpit.marks`	`ui.slot.video-overlay`	Draw vector marks (boxes, reticles, points, polylines, labels) into the shared cockpit overlay.
`cockpit.marks.clear`	none
`perception.read`	`perception.read`	Where detection runs for the bound drone.
`perception.subscribe`	`perception.subscribe`	Open the detection stream.
`perception.unsubscribe`	none
`perception.health`	`perception.read`	The perception session health.

The plugin never computes the capability id itself. The capability an envelope claims is ignored; the bridge re-resolves it.

Host-pushed events

Event	Capability	Payload	When
`theme.changed`	none	`Record<string, string>` of CSS variables	On mount and on every theme change.
`config.changed`	none	The plugin’s full config object	On mount (seeded from the agent’s config read-back), and after every accepted config write from the plugin, the parameter panel or the Skill Bar.
`capability.token`	none	A fresh capability token	When Mission Control rotates the plugin’s token. The SDK caches it; no plugin action is needed.
`telemetry.<topic>`	`telemetry.subscribe.<topic>`	Topic-specific payload	After the plugin subscribed to `<topic>`.
`perception.detections`	`perception.subscribe`	A detection batch	After the plugin opened the detection stream.

Other host-pushed topics (for example the video.overlay host props, or an agent plugin’s state read-back) arrive on the same channel and are read with ctx.events.subscribe(topic, handler).

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 SDK’s PluginClient builds these: it generates the id, attaches the protocol version, and waits for the correlated response.

Error envelopes

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

Code	Meaning
`permission_denied`	The required capability is not in the granted set.
`capability_denied`	The plugin’s capability token does not cover the request. The message carries the capability after a colon (for example `capability_denied:mission.write`).
`method_unknown`	The method is not in the bridge’s registry.
`schema_invalid`	The arguments failed validation (for example a missing `topic`).
`handler_unset`	The bridge knows the method but no handler is wired.
`handler_error`	The handler threw; the message carries the cause.
`refused`	Raised by the SDK when the host answered `{ ok: false }`: the operator denied a prompt, the command is not allowed, or a rate limit applied.

Branch on code, not on message.

There is also an origin_mismatch error, but the bridge never sends it to the plugin. A message from a window that is not the plugin’s iframe is dropped and recorded as a security event on the host side.

Theming

theme.changed arrives once on mount and again on every theme change. 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 apply them for you, so a plugin can scope them to its own root or ignore them.

i18n

A plugin ships a locale bundle in its archive; Mission Control streams the active bundle to the frame on mount. Format keys with ctx.i18n.t(key, params):

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

A missing key falls back to the key itself.

Next steps

TypeScript SDK

The typed wrappers over these methods.

Event hooks and bus

The agent-side event bus.

Permissions

The capabilities these methods check.

Start here

Tutorials

Reference

SDKs

Deep dives

Test and distribute

Methods the plugin can call

Host-pushed events

Wire shape

Error envelopes

Theming

i18n

Next steps

TypeScript SDK

Event hooks and bus

Permissions

​Methods the plugin can call

​Host-pushed events

​Wire shape

​Error envelopes

​Theming

​i18n

​Next steps

TypeScript SDK

Event hooks and bus

Permissions

Methods the plugin can call

Host-pushed events

Wire shape

Error envelopes

Theming

i18n

Next steps