@termix-ssh/plugin-sdk 1.0.21 → 1.0.23

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 1.0.23
+
+Plugin API 1.14.0.
+
+### Added
+
+- `contributes.operations` declares a plugin's actions, events, resources and signals, so Automations, Fleets, the assistant, the CLI, the phone app and the command palette can find them with no wiring
+- `ctx.operations` registers handlers, runs other plugins' declared actions, emits events and provides approval rules, with the new `operations:provide`, `operations:invoke` and `operations:approve` capabilities
+- `@termix-ssh/plugin-sdk/operations` has the types, input checks, redaction and JSON Schema for declared actions
+- `contributes.hostSections` declares cards for the host page
+
+## 1.0.22
+
+Plugin API 1.13.0.
+
+### Added
+
+- `contributes.mobile` in the manifest says how a plugin shows in the Termix mobile app: `webview`, `native` or `none`, with an optional mobile bundle, screen sizes, views and a note
+- `termix-plugin build` bundles `src/mobile` into the `contributes.mobile.entry` file, and `validate` checks that it exists
+- `@termix-ssh/plugin-sdk/frame-host` runs one plugin view outside the shell, with core's bridge, registries and CSS, so the mobile app can show `webview` plugins
+- SSH transport providers get the host's owner, sync id, connection origin and local only flag in `claims` and `open`, and core's SSH relay takes a `syncId` instead of a host id
+- `ctx.sync.host.entities.idsOf` maps sync ids to the local ids of the user's own rows of one type
+- Rail items take `useStatus` for a small ok, warning or error dot on the icon
+- `shell.editHost(hostId)` opens the editor of a saved host
+- A sync entity can be read only with `load`, `write` and `erase`, so a plugin can sync rows a user does not own, like a shared library, down to linked desktops
+- `getFolderAuthOverride` and `setFolderAuthOverride` in `@termix-ssh/plugin-sdk/ui` read and set a user's own login for the shared hosts in a folder
+
+### Fixed
+
+- `@termix-ssh/plugin-sdk/ui` is built in production mode, so outside Termix it no longer sends requests to the Vite dev server path
+- `execCommand` buffers output and decodes it once as strict UTF-8 with a GBK fallback, exposed as `decodeCommandOutput`, so messages from a Windows host on a legacy codepage are readable instead of � characters
+
 ## 1.0.21
 
 Plugin API 1.12.0.

package/PLUGIN-GUIDE.md

@@ -1,6 +1,6 @@
 # Termix plugin guide
 
-SDK 1.0.21 | Plugin API 1.12.0
+SDK 1.0.23 | Plugin API 1.14.0
 
 This guide is for anyone, person or AI coding tool, building a Termix plugin. It ships inside
 `@termix-ssh/plugin-sdk`, so the copy in your `node_modules` always matches the SDK you have installed.
@@ -175,7 +175,49 @@ Unknown fields are refused at every level, so a typo fails validation. The schem
 
 `contributes` holds `tabs`, `panels`, `dashboardCards`, `actions`, `actionSlots`, `permissions`,
 `settings`, `protocols`, `auth`, `syncEntities`, `keybindingActions`, `http`, `guest`, `guestViews`,
-`uiPresets`, `uses`, `layouts` and `themes`. Frontend `register*` calls need their ids declared here first.
+`uiPresets`, `uses`, `layouts`, `themes` and `mobile`. Frontend `register*` calls need their ids declared here first.
+
+### Mobile app
+
+`contributes.mobile` says how the plugin shows in the Termix mobile app. Leave it out and the app treats the
+plugin as having nothing to show (official plugins are mapped by the app itself).
+
+```json
+"mobile": { "mode": "webview", "views": ["hello"], "sizes": ["phone", "tablet"] }
+```
+
+| Field     | Notes                                                                                                                                             |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`    | `webview` (the app shows your UI from the server), `native` (the app has its own screens) or `none`.                                              |
+| `entry`   | `webview` only. A bundle made for the app, like `dist/mobile.js`, next to `frontend.js`. Unset: your normal frontend runs in a phone sized frame. |
+| `sizes`   | `webview` only. `phone`, `tablet` or both (the default).                                                                                          |
+| `views`   | `webview` only. Ids from your `tabs`, `panels` or `dashboardCards` the app offers. Default: every tab.                                            |
+| `feature` | `native` only. The app feature that stands in for the plugin. Default: the plugin id.                                                             |
+| `note`    | A locale key or plain text the app shows next to the plugin.                                                                                      |
+
+`build` makes `entry` from `src/mobile/index.tsx`, and it shares `frontend.css`.
+
+How a `webview` plugin runs in the app:
+
+- Only your plugin loads, with the same app object, SDK hooks and `/ui` kit as the web app. Each view opens
+  on its own screen: a tab with `host-context-menu` in `openFrom` opens from a host, the rest from the app's
+  plugin list.
+- Every request and socket goes through the app, which adds the login, proxy headers and client
+  certificate. The app only lets through your own `/plugin-api`, `/plugin-ws` and `/plugin-assets`, your
+  settings and a short list of core reads (hosts, folders, permissions, current user, version, health,
+  activity). Other core routes answer 403, so call your own backend instead.
+- Images load straight from the server, without proxy headers or a client certificate.
+- Nothing in `localStorage` survives closing the view. Keep preferences in settings.
+- Other plugins' views, extensions and components are not there, and neither is the shell (`useShell()`
+  is null). `/ui` names newer than the app's copy of the SDK make the view say it needs a newer app.
+- The app checks your `engine.api` against the plugin API of its own copy of the SDK. When the app's API
+  is too old for the range, it asks the user to update the app instead of opening the view. When the range
+  is for an older API major, it asks to update the plugin. Ask only for the API you use.
+- Turning a plugin off on the server hides it in the app the next time the app checks: when it comes back
+  to the front, when the list is pulled down, or when any request answers 503 with your `pluginId`.
+
+Termix 26.10.5 and older refuse any manifest with `mobile`, so a plugin that declares it needs
+`"engine": { "termix": ">=26.10.6", "api": "^1.13" }`.
 
 Capabilities and permissions are different things. A capability (`hosts:read`, with a colon) is what your
 code may reach. A permission (`hello.use`, with a dot) is what a user may do.
@@ -304,7 +346,7 @@ router.post("/notes", async (req, res) => {
 - `ctx.rbac.require("manage")` on a single route, `await ctx.rbac.has("manage")` in code. A full id like
   `hosts.edit` checks a core permission.
 - Host access: `ctx.hosts.checkAccess(hostId, "connect" | "view" | "edit" | "manage")`.
-- Transports: with `ssh:transport`, `ctx.ssh.transports.provide({ claims(hostId), open({ id, ip, port }) })`
+- Transports: with `ssh:transport`, `ctx.ssh.transports.provide({ claims(hostId, host), open(host) })`, where `host` has `id`, `ip`, `port` and on Termix 26.10.6+ also `userId`, `syncId`, `connectionOrigin` and `localOnly`
   returns a stream the SSH client uses instead of a direct, proxy or jump host connection. Core also serves
   `/plugin-ws/core/ssh-relay?hostId=` for callers with connect access, so one Termix can relay to another.
 - Managed hosts: with `hosts:lock`, `ctx.hosts.locks.provide({ isLocked, note, allowManualCreate })` makes
@@ -372,6 +414,70 @@ ctx.schedule.every(60_000, () => refresh(), { jitterMs: 5_000 });
 - Use a service: declare it in `requires`, then `ctx.services.get<T>("snippets.access")`. It returns
   nothing while no provider runs, so always handle that.
 
+### Operations
+
+Declare what your plugin can do in `contributes.operations`, and it shows up in Automations, Fleets, the
+assistant, the CLI, the phone app and the command palette with no other wiring. It also gets per host results,
+dry runs, run history, approvals and drift checks.
+
+```json
+"capabilities": ["operations:provide"],
+"engine": { "termix": ">=26.11.1-0", "api": "^1.13" },
+"contributes": {
+  "operations": {
+    "actions": [{
+      "id": "demo.restart",
+      "titleKey": "ops.restart.title",
+      "scope": "host",
+      "inputs": [{ "key": "name", "type": "string", "labelKey": "ops.restart.name", "required": true }],
+      "risk": "change",
+      "permission": "use",
+      "hostAccess": "edit",
+      "dryRun": "describe"
+    }]
+  }
+}
+```
+
+```ts
+ctx.operations.register("demo.restart", {
+  describe: (input) => `Would restart ${input.name}`,
+  run: async (input, { hostId, signal, log }) => {
+    return { summary: `Restarted ${input.name}`, changed: true };
+  },
+});
+```
+
+- Actions: `scope` is `host`, `resource` or `server`. `risk` is `read`, `change` or `destructive`. Host actions declare
+  `hostAccess`. Use `edit` for changes unless people with `connect` already do this today. A destructive action
+  must use `edit` or `manage` and needs a confirm.
+- Inputs use the settings field types, plus `required`, `pattern`, `optionsFrom` (a read action fills the choices)
+  and type `resource`. Keys you did not declare are refused before your handler runs. `secret` values reach the handler
+  but are never stored or shown. Mark private outputs `sensitive`.
+- `dryRun`: `native` calls `run` with `dryRun: true` and nothing may change. `describe` calls `describe` instead.
+- `check` names a read action that proves the result, used for drift. `undo` names the reverse action, and `run` returns
+  `undoInput`. `idempotent` lets a rollout retry it. `exclusive` allows one at a time per host. `when` limits it to
+  hosts by setting or OS.
+- `surfaces`: the assistant and MCP are off until you set them true. Only do that for actions safe for a model to
+  ask for. The rest are on unless you set them false.
+- Resources describe a kind of thing, such as a container: a read action on one host returns `{ rows }` as `data`, and
+  core draws the All hosts table and host page section. Attach actions with `scope: "resource"`.
+- Signals are status tiles: a read action returns `{ value, status, label }` as `data`, with status `ok`, `warn`, `fail` or
+  `unknown`. `fix` names the action offered when it is not ok. Keep these reads cheap, they run for every host.
+- Events: declare them, then call `ctx.operations.emit(id, payload, { hostId })`.
+- Handlers must watch `signal` and stop when it fires. Throw on failure; a failed run never counts against your
+  plugin's error budget. Throw an error with `code = "NEEDS_INTERACTION"` when a host needs a person to sign in first.
+- Handlers have no request and no session. Take what you need from the input and `hostId`.
+- Keep your REST routes. Inside one, call `ctx.operations.run(id, { hostId, input })` so a button press goes through
+  the same checks and lands in the same history.
+- To run another plugin's action, add `operations:invoke`, list it in `operations.invokes` and call
+  `ctx.operations.invoke(id, { hostId, input, via: "automation" })`. It acts as the current user and rules still apply.
+- `risk` is your plugin's claim. Plugins run in-process, so this is not a sandbox. Actions from plugins not signed as
+  official count as `change` when rules decide what needs a person, and stay off the assistant and MCP until an admin
+  allows them.
+- Set `engine.termix` to at least `>=26.11.1-0`. Keep `engine.api` as it was unless you import something new from
+  `/ui`, or the phone app will ask people to update to see your plugin.
+
 ### Shared packages
 
 These come from Termix and are never bundled: `@termix-ssh/plugin-sdk`, `express`, `ssh2`, `ws`, `multer`,
@@ -453,6 +559,23 @@ Other storage: `ctx.kv` for a few values, `ctx.settings` for settings, `ctx.secr
 `ctx.files.dataDir()` for files. To sync a table to a linked desktop, use `ctx.sync.registerEntity` and
 `contributes.syncEntities`. The entity name is part of the protocol and never changes.
 
+A registered table syncs the rows each user owns, both ways. For data you keep for the whole server (a shared
+library, rows other users share), register a read only entity with `table: null`, `readOnly: true` and `load`,
+`write` and `erase` (Termix 26.10.6+). `load(userId)` returns the rows that user should get, each with a
+`syncId`. The desktop keeps them with `write` and drops them with `erase`, and never pushes them back:
+
+```ts
+ctx.sync.registerEntity({
+  type: "sharedIcons",
+  table: null,
+  readOnly: true,
+  order: 70,
+  load: (userId) => iconsVisibleTo(userId),
+  write: (userId, row) => storeCopy(userId, row),
+  erase: (userId, syncId) => dropCopy(userId, syncId),
+});
+```
+
 ## Frontend
 
 ```tsx
@@ -903,6 +1026,7 @@ To run your own registry instead, see https://docs.termix.site/develop/registrie
 | `@termix-ssh/plugin-sdk/db`                                          | `defineTable` and column builders                                                              |
 | `@termix-ssh/plugin-sdk/manifest`                                    | `PluginManifest` type and manifest checks                                                      |
 | `@termix-ssh/plugin-sdk/capabilities`                                | The capability catalog                                                                         |
+| `@termix-ssh/plugin-sdk/operations`                                  | Types, input checks and JSON Schema for declared actions                                       |
 | `@termix-ssh/plugin-sdk/settings`                                    | Settings field validation                                                                      |
 | `@termix-ssh/plugin-sdk/testing`                                     | `createMockCtx`, `createTestDb`, `renderWithApp`, `createFakeContext`                          |
 | `@termix-ssh/plugin-sdk/vitest-preset`                               | `pluginVitestConfig`                                                                           |
@@ -934,6 +1058,8 @@ To run your own registry instead, see https://docs.termix.site/develop/registrie
 | `desktop:local`          | high     | Use the user's own computer, desktop app only                 |
 | `hosts:export`           | high     | Export hosts with their saved logins                          |
 | `notify:hub`             | high     | Receive every alert (the alerts hub only)                     |
+| `operations:invoke`      | high     | Run other plugins' declared actions, listed in `invokes`      |
+| `operations:approve`     | high     | Decide which actions need a person                            |
 | `ui:layout`              | high     | Replace the whole app layout                                  |
 | `hosts:write`            | medium   | Add and edit hosts                                            |
 | `hosts:status-provide`   | medium   | Be the source of host status dots                             |
@@ -949,6 +1075,7 @@ To run your own registry instead, see https://docs.termix.site/develop/registrie
 | `users:read`             | medium   | Usernames, roles and UI language                              |
 | `events:core`            | medium   | Listen to core events                                         |
 | `notify:send`            | medium   | Send alerts                                                   |
+| `operations:provide`     | medium   | Offer declared actions and events                             |
 | `audit:read`             | medium   | Read the audit log                                            |
 | `desktop:window`         | medium   | Open windows in the desktop app                               |
 | `hosts:read`             | low      | Read hosts the user can see                                   |

package/cli/commands/build.mjs

@@ -25,6 +25,43 @@ const FRONTEND_ENTRIES = [
   "src/frontend/index.mjs",
   "src/frontend/index.js",
 ];
+const MOBILE_ENTRIES = [
+  "src/mobile/index.tsx",
+  "src/mobile/index.ts",
+  "src/mobile/index.mjs",
+  "src/mobile/index.js",
+];
+
+/** Builds a bundle that runs in a browser against core's shared modules. */
+async function buildBrowserBundle(entry, outfile, outDir) {
+  await esbuild.build({
+    entryPoints: [entry],
+    outfile,
+    bundle: true,
+    format: "esm",
+    platform: "browser",
+    target: "es2022",
+    jsx: "automatic",
+    sourcemap: true,
+    logLevel: "warning",
+    external: FRONTEND_EXTERNALS,
+    // Vite replaces these in the dev server; a plugin bundle has to have
+    // them too, or code that reads them throws when the plugin loads.
+    define: {
+      "process.env.NODE_ENV": '"production"',
+      "import.meta.env.DEV": "false",
+      "import.meta.env.PROD": "true",
+      "import.meta.env.MODE": '"production"',
+      "import.meta.env.SSR": "false",
+      "import.meta.env":
+        '{"DEV":false,"PROD":true,"MODE":"production","SSR":false,"BASE_URL":"/"}',
+    },
+    plugins: [
+      externalRequireInterop(FRONTEND_EXTERNALS),
+      staticUrlImports({ outDir }),
+    ],
+  });
+}
 
 /**
  * A bundled CommonJS package that calls require("react/jsx-runtime") (or any
@@ -192,15 +229,12 @@ export async function buildTailwind(cwd, outDir) {
   // build() adds to what a compiler already emitted, so each half gets its own.
   const compiler = () =>
     compile(input, { base: path.dirname(THEME_CSS), onDependency: () => {} });
-  const scanner = new Scanner({
-    sources: [
-      {
-        base: path.join(cwd, "src", "frontend"),
-        pattern: "**/*",
-        negated: false,
-      },
-    ],
-  });
+  // The mobile bundle uses the same stylesheet.
+  const sources = ["frontend", "mobile"]
+    .map((dir) => path.join(cwd, "src", dir))
+    .filter((dir, index) => index === 0 || fs.existsSync(dir))
+    .map((base) => ({ base, pattern: "**/*", negated: false }));
+  const scanner = new Scanner({ sources });
   // Flattened and minified the way core's own CSS is, so it does not rely
   // on native CSS nesting.
   const emit = async (candidates, options) =>
@@ -297,33 +331,18 @@ export async function build({ cwd }) {
 
   const frontendEntry = resolveEntry(cwd, FRONTEND_ENTRIES);
   if (frontendEntry) {
-    await esbuild.build({
-      entryPoints: [frontendEntry],
-      outfile: path.join(outDir, "frontend.js"),
-      bundle: true,
-      format: "esm",
-      platform: "browser",
-      target: "es2022",
-      jsx: "automatic",
-      sourcemap: true,
-      logLevel: "warning",
-      external: FRONTEND_EXTERNALS,
-      // Vite replaces these in the dev server; a plugin bundle has to have
-      // them too, or code that reads them throws when the plugin loads.
-      define: {
-        "process.env.NODE_ENV": '"production"',
-        "import.meta.env.DEV": "false",
-        "import.meta.env.PROD": "true",
-        "import.meta.env.MODE": '"production"',
-        "import.meta.env.SSR": "false",
-        "import.meta.env":
-          '{"DEV":false,"PROD":true,"MODE":"production","SSR":false,"BASE_URL":"/"}',
-      },
-      plugins: [
-        externalRequireInterop(FRONTEND_EXTERNALS),
-        staticUrlImports({ outDir }),
-      ],
-    });
+    await buildBrowserBundle(
+      frontendEntry,
+      path.join(outDir, "frontend.js"),
+      outDir,
+    );
+  }
+
+  // A bundle the mobile app loads in its WebView, next to the frontend one.
+  const mobileEntry = resolveEntry(cwd, MOBILE_ENTRIES);
+  const mobileOut = manifest.contributes?.mobile?.entry;
+  if (mobileEntry && typeof mobileOut === "string") {
+    await buildBrowserBundle(mobileEntry, path.join(cwd, mobileOut), outDir);
   }
 
   if (frontendEntry) await buildTailwind(cwd, outDir);

package/cli/commands/validate.mjs

@@ -28,6 +28,10 @@ export async function validate({ cwd }) {
     // A theme only plugin has no frontend code.
     ...(isThemeOnly(raw) ? [] : [raw.frontend ?? "dist/frontend.js"]),
     raw.locales ?? "locales",
+    // Built from src/mobile by termix-plugin build.
+    ...(typeof raw.contributes?.mobile?.entry === "string"
+      ? [raw.contributes.mobile.entry]
+      : []),
   ];
   for (const rel of referenced) {
     if (!fs.existsSync(path.join(cwd, rel))) {

package/dist/backend.d.ts

@@ -13,6 +13,7 @@ import type { HostSshOptions } from "./ssh-options.js";
 export type { HostSshOptions } from "./ssh-options.js";
 import type { PluginManifest, PluginSettingsField } from "./manifest.js";
 import type { PluginTableDefinition } from "./db.js";
+import type { OperationResult, OperationRisk, OperationSurfaces } from "./operations.js";
 /**
  * Thrown when a plugin calls a guarded member without the capability.
  *
@@ -149,8 +150,24 @@ export interface SyncWriteEvent {
 export interface SyncEntityRegistration {
     /** Stable wire name. Never change it: records on both sides match on it. */
     type: string;
-    /** The table, as returned by ctx.db.define. */
+    /** The table, as returned by ctx.db.define. Null for an entity with `load`. */
     table: unknown;
+    /**
+     * Server to desktop only: a desktop never pushes these rows. Required with
+     * `load`.
+     */
+    readOnly?: boolean;
+    /**
+     * Builds the rows the user gets instead of reading the rows they own in
+     * `table`, for data kept for the whole server (a shared library, rows other
+     * users share with them). Rows are on the wire: plaintext, each with a
+     * syncId. Needs `readOnly: true`, `write` and `erase`.
+     */
+    load?: (userId: string) => Promise<SyncRow[]>;
+    /** Keeps a copy of an inbound row on the desktop, for an entity with `load`. */
+    write?: (userId: string, wire: SyncRow) => Promise<void>;
+    /** Drops the desktop copy with this syncId, for an entity with `load`. */
+    erase?: (userId: string, syncId: string) => Promise<void>;
     /** Column holding the owning user id. Defaults to "userId". */
     userColumn?: string;
     /** Fields stored encrypted with the owner's data key. Plaintext on the wire. */
@@ -391,6 +408,8 @@ export interface PluginSyncHost {
         ensureCore: () => Promise<void>;
         onChanged: (listener: () => void) => () => void;
         onLocalWrite: (listener: () => void) => () => void;
+        /** Local ids of the user's own rows of a type, by sync id. Termix 26.10.6+. */
+        idsOf?: (type: string, userId: string, syncIds: string[]) => Promise<Record<string, number>>;
     };
     /** Rows and bookkeeping of one local user's replica. */
     replica: {
@@ -1503,13 +1522,20 @@ export interface PluginNetwork {
  * asked for every connection, so it must be quick. `open` returns a stream
  * the SSH client runs over, like a relayed socket.
  */
+/** The host a transport is asked about. Fields past port come from Termix 26.10.6. */
+export interface PluginSshTransportHost {
+    id: number;
+    ip: string;
+    port: number;
+    /** Owner of the host row. */
+    userId?: string | null;
+    syncId?: string | null;
+    connectionOrigin?: "local" | "remote" | null;
+    localOnly?: boolean;
+}
 export interface PluginSshTransportProvider {
-    claims: (hostId: number) => boolean;
-    open: (host: {
-        id: number;
-        ip: string;
-        port: number;
-    }) => Promise<import("node:stream").Duplex>;
+    claims: (hostId: number, host?: PluginSshTransportHost) => boolean;
+    open: (host: PluginSshTransportHost) => Promise<import("node:stream").Duplex>;
 }
 export interface PluginSshTransports {
     /** Needs ssh:transport. Removed on deactivate. */
@@ -2655,6 +2681,110 @@ export interface PluginSummary {
 export interface PluginPlugins {
     list: () => Promise<PluginSummary[]>;
 }
+/** What a handler gets besides its input. */
+export interface PluginOperationContext {
+    hostId?: number;
+    /** The row a resource action targets. */
+    resourceKey?: string;
+    /** Null for a background read. */
+    runId: string | null;
+    /** Nothing may change when this is set. */
+    dryRun: boolean;
+    /** Fires when the run is cancelled, times out or the plugin stops. */
+    signal: AbortSignal;
+    log: (line: string) => void;
+}
+export interface PluginOperationHandler {
+    run: (input: Record<string, unknown>, context: PluginOperationContext) => Promise<OperationResult> | OperationResult;
+    /** The dry run text for an action declared with dryRun "describe". */
+    describe?: (input: Record<string, unknown>, context: PluginOperationContext) => string | Promise<string>;
+}
+export interface PluginOperationInvokeOptions {
+    hostId?: number;
+    resourceKey?: string;
+    input?: Record<string, unknown>;
+    dryRun?: boolean;
+    /** A person agreed to a destructive action. */
+    confirmed?: boolean;
+    idempotencyKey?: string;
+    batchId?: string;
+    /** What this plugin is doing: automation, assistant, mcp, rollout and so on. */
+    via?: string;
+}
+export interface PluginOperationOutcome {
+    runId: string | null;
+    status: string;
+    summary?: string;
+    changed?: boolean;
+    data?: unknown;
+    error?: string;
+    errorCode?: string;
+    approvalId?: string;
+}
+export interface PluginOperationApprovalInput {
+    actionId: string;
+    pluginId: string;
+    risk: OperationRisk;
+    /** What rules should use. Plugins not signed as official count as change. */
+    effectiveRisk: OperationRisk;
+    origin: {
+        kind: string;
+        pluginId?: string;
+        via?: string;
+    };
+    userId: string;
+    hostId?: number;
+    hostTags?: string[];
+    batchId?: string;
+}
+export interface PluginOperationApprovalDecision {
+    decision: "allow" | "approve" | "deny";
+    reason?: string;
+    allowSelf?: boolean;
+    expiresInMinutes?: number;
+}
+export interface PluginOperationEvent {
+    id: string;
+    eventId: string;
+    pluginId: string;
+    hostId?: number;
+    severity?: string;
+    payload?: unknown;
+    runId?: string;
+    depth: number;
+    at: string;
+}
+/**
+ * Declared actions and events. See contributes.operations in the manifest.
+ * register and emit need operations:provide. invoke, list and onEvent need
+ * operations:invoke, and invoke only reaches ids in the manifest's invokes list.
+ */
+export interface PluginOperations {
+    register: (id: string, handler: PluginOperationHandler) => void;
+    /**
+     * Runs one of this plugin's own actions from its route, so a button press
+     * goes through the same checks and lands in the same history.
+     */
+    run: (actionId: string, options?: PluginOperationInvokeOptions) => Promise<PluginOperationOutcome>;
+    invoke: (actionId: string, options?: PluginOperationInvokeOptions) => Promise<PluginOperationOutcome>;
+    list: (options?: {
+        lang?: string;
+        surface?: keyof OperationSurfaces;
+    }) => Promise<unknown>;
+    emit: (eventId: string, payload?: unknown, options?: {
+        hostId?: number;
+    }) => Promise<void>;
+    onEvent: (subscription: {
+        pattern: string;
+        handler: (event: PluginOperationEvent) => void | Promise<void>;
+        userId?: string;
+        cooldownMs?: number;
+    }) => () => void;
+    /** Rules for what needs a person. Needs operations:approve. */
+    approvals: {
+        provide: (provider: (input: PluginOperationApprovalInput) => PluginOperationApprovalDecision | null | undefined | Promise<PluginOperationApprovalDecision | null | undefined>) => () => void;
+    };
+}
 export interface PluginContext {
     readonly pluginId: string;
     readonly manifest: PluginManifest;
@@ -2695,6 +2825,8 @@ export interface PluginContext {
     readonly schedule: PluginSchedule;
     /** Core's notification channels. Needs notify:send. */
     readonly notify: PluginNotify;
+    /** Declared actions and events, reachable from every surface. */
+    readonly operations: PluginOperations;
     /** Outbound HTTP through core's SSRF guard. Needs network:outbound. */
     readonly fetch: PluginFetch;
     /** Plain reachability checks. Needs network:probe. */

package/dist/capabilities.js

@@ -38,6 +38,8 @@ export const CAPABILITY_CATALOG = [
     entry("ssh:transport", "high"),
     entry("device:serial", "high"),
     entry("notify:hub", "high"),
+    entry("operations:invoke", "high"),
+    entry("operations:approve", "high"),
     entry("ui:layout", "high"),
     entry("hosts:write", "medium"),
     entry("hosts:export", "high"),
@@ -53,6 +55,7 @@ export const CAPABILITY_CATALOG = [
     entry("users:read", "medium"),
     entry("events:core", "medium"),
     entry("notify:send", "medium"),
+    entry("operations:provide", "medium"),
     entry("audit:read", "medium"),
     entry("desktop:window", "medium"),
     entry("desktop:local", "high"),

package/dist/frontend.d.ts

@@ -185,6 +185,8 @@ export interface ShellApi {
      * user reviews and saves it. Absent in some shells.
      */
     openHostEditor?: (draft?: HostDraft) => void;
+    /** Opens the editor of a saved host. Termix 26.10.6+, absent in some shells. */
+    editHost?: (hostId: number) => void;
     /** Opens a rail view in the left sidebar. */
     openRailView: (id: string) => void;
     /** Closes a rail view wherever it is shown. */
@@ -412,6 +414,11 @@ export interface RailItemContribution {
      * Zero or nothing shows no badge.
      */
     useBadge?: () => number | null | undefined;
+    /**
+     * A hook for a small status dot on the icon: "ok" (green), "warning" or
+     * "error". Nothing shows no dot. Layouts from Termix 26.10.6 draw it.
+     */
+    useStatus?: () => "ok" | "warning" | "error" | null | undefined;
 }
 export interface PanelProps {
     /**