Host events

Lite plugin API 3.6.0. Background modules access host events through ctx.events on the injected BackgroundHost. Views and actions do not expose this interface; they communicate with the background through its message API.

Supported events

Event	Payload	Permission
file.opened	FileOpenedEvent	background.fileHistory: true and host approval

file.opened reports a successful workbench file open in the background’s current window and Space. Content reads, resource previews, View rerenders and failed opens do not emit this event. It provides metadata only, without file-content access.

Delivery and lifetime

Events are live notifications, without an initial snapshot, durable delivery or historical replay. Subscribing does not start a background or prompt for permission. Use background.autoStart for approved startup when the Space opens.

Each subscription can be disposed independently. Stopping the background destroys its subscriptions; revoking access ends delivery. Closing a View does not stop background listeners. A throwing listener does not prevent other listeners from running.

See the background guide for a subscription example and the Recent History plugin workflow.

Usage guide: background. API index.

Signatures, parameters and return types are generated from the SDK. Optional members are not available in every host and context.

FileOpenedEvent

Source

FileOpenedEvent.id

Supported hosts: Lite

Host-generated event identity, usable for deduplication.

readonly id: string;

FileOpenedEvent.path

Supported hosts: Lite

File path relative to the current Space.

readonly path: string;

FileOpenedEvent.timestamp

Supported hosts: Lite

Time of the successful open, in Unix milliseconds.

readonly timestamp: number;

PluginEventMap

Source

PluginEventMap.“file.opened”

Supported hosts: Lite

Successful file-open metadata. See FileOpenedEvent.

"file.opened": FileOpenedEvent;

Related types: FileOpenedEvent.

PluginEvents

Source

PluginEvents.on

Supported hosts: Lite

The event name determines the listener parameter type. Returns a Disposable; dispose() is idempotent. Unknown event names, non-function listeners and undeclared event permissions throw synchronously.

on<K extends keyof PluginEventMap>(type: K, listener: (event: PluginEventMap[K]) => void): Disposable;

Parameter	Type	Required
type	K	Yes
listener	(event: PluginEventMap[K]) => void	Yes

Returns: Disposable.

Related types: PluginEventMap, Disposable.