To write a script plugin, see Plugin authoring.
Built-in Dart plugins
Dart plugins are registered inapp/lib/plugins/plugin_registry.dart in the kRegisteredPlugins list. The three that ship today are:
Add a Dart plugin
1
Add the package
Add it to the dependencies in
app/pubspec.yaml (and to dependency_overrides if it is a local package under packages/).2
Register it
Import it in
plugin_registry.dart and add an instance to kRegisteredPlugins.The YourSSHPlugin interface
Every Dart plugin implementsYourSSHPlugin from packages/yourssh_plugin_api:
buildUI(context, pluginContext)returns the plugin’s widget. Wrap it inYsPluginHost(fromyourssh_ui) so it keeps the app’s forui theme even when it is mounted outside the app’s root builder, as Snippets, DevOps and Web Tools do.onActivate(ctx)andonDeactivate()are lifecycle hooks.minApiVersionis checked at runtime against the app’s API version.
YourSSHPluginContext gives a plugin controlled access to the app: the active sessions, execCommand(sessionId, cmd), sendInput(sessionId, text) to type into a session’s terminal (Snippets uses it to insert a snippet), and namespaced savePreference and getPreference.
Dart plugins can be switched on and off with feature flags in Settings.
JavaScript script plugins
Script plugins live in~/.yourssh/plugins/, one folder each, with a plugin.json manifest. The runtime is the packages/yourssh_script_engine package.
Components
PluginManifestparses and validatesplugin.json: id, name, version, entry file, minimum app version and permissions. An unknown permission is rejected.PluginUiRegistrylets a plugin register UI throughui.register(id, spec); the app renders it in the plugin manager. A plugin can also declare a panel, an HTML view shown in the app. A panel is plugin-controlled HTML, so its messages to the app (running a command, listing sessions, reading a file) go through the same permission checks as the JavaScript bridges.- The plugin manager screens let users enable or disable a plugin, reload it and read its
console.logoutput.
Hooks
TheHookBus delivers typed events to plugin handlers in three styles:
The app wires the bus into
SshService, so plugins see terminal.output, terminal.input, session connect and disconnect events, and ssh.exec command events. The complete list of events and the permission each one needs is in Plugin authoring.
Bridges
Bridges are the Dart APIs a plugin can call from JavaScript:Permissions
A plugin must declare each permission in its manifest. The recognized permissions are:terminal.read, terminal.transform, terminal.intercept, terminal.inject, session.observe, session.control, ssh.exec, sftp.read, sftp.write, command.intercept, ui.notify, ui.statusbar, ui.panel, ui.clipboard.
PermissionGuard checks the manifest before it dispatches any bridge call. Observing is separate from changing: terminal.read observes output only, and rewriting it needs terminal.transform.
Consent
The first time a plugin loads, the app shows a consent dialog listing the permissions it asks for. The user must accept before the plugin runs.- Consent is bound to a SHA-256 hash of every file in the plugin folder. Change any file and the user is asked again.
- Stored grants are intersected with the manifest’s current permissions, so a plugin can’t gain a permission by editing its manifest.
- Pending consent requests queue in order.
manifest.entryand a panel’s HTML entry must stay inside the plugin folder. Paths with../, absolute paths and symlinks that escape are rejected.
Execution limits
The C bridge (packages/yourssh_script_engine/native/bridge/qjs_bridge.c) enforces hard limits on every plugin:
A call that exceeds its deadline raises
QuickJsTimeoutException.
Circuit breaker
PluginErrorTracker protects the app from a misbehaving plugin. An error counts 1, a timeout counts 5 and a success resets the count. At 10, the plugin’s hooks are skipped and the plugin is unloaded. The user can see what happened in the plugin’s console.
Reserved built-in ids
The ids of the built-in Dart plugins are reserved.PluginLoader never loads or prompts for a script plugin with a reserved id, so a script plugin can’t impersonate Snippets, DevOps Hub or Web Tools.
Only the macOS arm64 QuickJS library (
libqjsbridge.dylib) is prebuilt. See Build from source to rebuild it after changing the C bridge.