@termix-ssh/plugin-sdk 1.0.13 → 1.0.17

package/dist/backend.d.ts

@@ -201,6 +201,346 @@ export interface SyncEntityRegistration {
  */
 export interface PluginSync {
     registerEntity: (entity: SyncEntityRegistration) => void;
+    /** Needs sync:provide. Takes over /sync/v2 and /sync/link. Removed on deactivate. */
+    provide: (provider: PluginSyncProvider) => () => void;
+    /** Needs sync:provide. The replica store, change feed and link registry. */
+    readonly host: PluginSyncHost;
+}
+/**
+ * The plugin that owns server and desktop sync. Core forwards every request
+ * under /sync to `handle` (an Express style handler) and answers 404 when no
+ * plugin provides it. Call `next()` to let core answer instead.
+ */
+export interface PluginSyncProvider {
+    handle: (req: unknown, res: unknown, next: (error?: unknown) => void) => void | Promise<void>;
+}
+/** A kind of data that syncs, as the sync provider sees it. */
+export interface SyncEntityInfo {
+    type: string;
+    owner: string;
+    order: number;
+    readOnly: boolean;
+    /** Whether the row would show in a load even if it exists. */
+    covers?: (syncId: string) => boolean;
+}
+/** A row ready for the wire, with its content hash. */
+export interface SyncWireRow {
+    syncId: string;
+    wire: SyncRow;
+    hash: string;
+}
+export interface SyncRecordInfo {
+    entityType: string;
+    syncId: string;
+    revision: number;
+    hash: string | null;
+    deleted: boolean;
+    error: string | null;
+    errorHash: string | null;
+    seq: number;
+}
+export interface SyncConflictInfo {
+    id: number;
+    entityType: string;
+    syncId: string;
+    localRow: string;
+    createdAt: string;
+}
+export interface SyncAccountInfo {
+    id: string;
+    username: string;
+    isAdmin: boolean;
+    active: boolean;
+}
+export interface SyncProxyHeader {
+    name: string;
+    value: string;
+}
+export interface SyncBasicAuth {
+    username: string;
+    password: string;
+}
+/** Extra per server connection options. Kept open so new ones need no migration. */
+export type SyncLinkOptions = Record<string, unknown>;
+/** One server a desktop is linked to, with a replica of its data. */
+export interface SyncLinkInfo {
+    id: number;
+    /** The local user the replica belongs to. */
+    userId: string;
+    serverUrl: string;
+    serverName: string | null;
+    serverVersion: string | null;
+    sessionToken: string | null;
+    customHeaders: SyncProxyHeader[];
+    basicAuth: SyncBasicAuth | null;
+    allowInvalidCertificate: boolean;
+    remoteUserId: string | null;
+    remoteUsername: string | null;
+    account: {
+        remoteUserId?: string;
+        username?: string;
+        isAdmin?: boolean;
+        roles?: string[];
+        permissions?: string[];
+    } | null;
+    disabledTypes: string[];
+    /** Extra connection options for this server, kept open for new ones. */
+    options: SyncLinkOptions;
+    knownTypes: string[];
+    cursor: number;
+    status: "idle" | "syncing" | "offline" | "error" | "signed_out";
+    lastError: string | null;
+    linkedAt: string;
+    lastSyncAt: string | null;
+}
+export interface SyncLinkCreate {
+    userId: string;
+    serverUrl: string;
+    serverName?: string | null;
+    serverVersion?: string | null;
+    sessionToken: string;
+    customHeaders?: SyncProxyHeader[];
+    basicAuth?: SyncBasicAuth | null;
+    allowInvalidCertificate?: boolean;
+    remoteUserId?: string | null;
+    remoteUsername?: string | null;
+}
+export type SyncLinkPatch = Partial<Pick<SyncLinkInfo, "serverName" | "serverVersion" | "sessionToken" | "customHeaders" | "basicAuth" | "allowInvalidCertificate" | "remoteUserId" | "remoteUsername" | "account" | "disabledTypes" | "options" | "knownTypes" | "cursor" | "status" | "lastError" | "lastSyncAt">>;
+export type SyncRemoteErrorKind = "offline" | "tls" | "proxy" | "basic_auth" | "signed_out" | "server";
+export interface SyncRemoteError extends Error {
+    readonly kind: SyncRemoteErrorKind;
+    readonly status?: number;
+}
+export interface SyncRemoteTarget {
+    serverUrl: string;
+    sessionToken?: string | null;
+    customHeaders?: SyncProxyHeader[];
+    basicAuth?: SyncBasicAuth | null;
+    allowInvalidCertificate?: boolean;
+}
+export interface SyncRemoteRequest {
+    method?: string;
+    body?: unknown;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface SyncPushOp {
+    entityType: string;
+    syncId: string;
+    baseRevision: number;
+    op: "upsert" | "delete";
+    row?: SyncRow;
+}
+export type SyncPushResult = {
+    syncId: string;
+    entityType: string;
+    status: "ok";
+    revision: number;
+} | {
+    syncId: string;
+    entityType: string;
+    status: "conflict";
+    revision: number;
+    deleted: boolean;
+    row: SyncRow | null;
+} | {
+    syncId: string;
+    entityType: string;
+    status: "rejected";
+    reason: string;
+};
+export interface SyncRemotePlugin {
+    id: string;
+    name: string;
+    version: string;
+    source: string;
+    artifact: boolean;
+    enabled: boolean;
+    active: boolean;
+    desktop: string;
+    syncEntities: string[];
+    granted: string[];
+}
+/**
+ * What the sync provider gets from core: the replica store, the change feed,
+ * the linked server registry, sessions and a few helpers. Core keeps all of
+ * it neutral; the provider decides when and how to use it. Needs sync:provide.
+ */
+export interface PluginSyncHost {
+    /** True on the desktop app's own backend. */
+    readonly embedded: boolean;
+    info: {
+        appName: () => Promise<string>;
+        version: () => string;
+    };
+    entities: {
+        list: () => SyncEntityInfo[];
+        get: (type: string) => SyncEntityInfo | undefined;
+        /** Registers core's own entities once. */
+        ensureCore: () => Promise<void>;
+        onChanged: (listener: () => void) => () => void;
+        onLocalWrite: (listener: () => void) => () => void;
+    };
+    /** Rows and bookkeeping of one local user's replica. */
+    replica: {
+        resolvers: (userId: string, onMissing?: () => void) => unknown;
+        loadRows: (type: string, userId: string, resolvers: unknown) => Promise<{
+            rows: Map<string, SyncWireRow>;
+            failed: Set<string>;
+        }>;
+        loadRow: (type: string, userId: string, syncId: string, resolvers: unknown) => Promise<SyncWireRow | null>;
+        writeRow: (type: string, userId: string, wire: SyncRow, resolvers: unknown) => Promise<void>;
+        deleteRow: (type: string, userId: string, syncId: string) => Promise<void>;
+        orderSelfReferences: (type: string, rows: SyncRow[]) => SyncRow[];
+        counts: (userId: string) => Promise<Record<string, number>>;
+        wipe: (userId: string) => Promise<void>;
+        regenerateSyncIds: (userId: string) => Promise<void>;
+        removeSharedCopies: (userId: string) => Promise<void>;
+        records: {
+            list: (userId: string) => Promise<Map<string, SyncRecordInfo>>;
+            put: (userId: string, type: string, syncId: string, values: {
+                revision: number;
+                hash: string | null;
+                deleted: boolean;
+            }) => Promise<void>;
+            setError: (userId: string, type: string, syncId: string, reason: string, hash: string) => Promise<void>;
+            clearErrors: (userId: string) => Promise<void>;
+            listErrors: (userId: string) => Promise<SyncRecordInfo[]>;
+            deleteForUser: (userId: string) => Promise<void>;
+            key: (type: string, syncId: string) => string;
+        };
+        conflicts: {
+            save: (userId: string, type: string, syncId: string, row: SyncRow, revision: number) => Promise<void>;
+            list: (userId: string) => Promise<SyncConflictInfo[]>;
+            get: (userId: string, id: number) => Promise<SyncConflictInfo | null>;
+            delete: (userId: string, id: number) => Promise<void>;
+        };
+    };
+    /** The server side: what changed for an account and what a desktop pushed. */
+    feed: {
+        withUserLock: <T>(userId: string, run: () => Promise<T>) => Promise<T>;
+        changes: (userId: string, cursor: number, limit: number, types?: string[]) => Promise<{
+            records: Array<{
+                seq: number;
+                entityType: string;
+                syncId: string;
+                revision: number;
+                deleted: boolean;
+                row: SyncRow | null;
+            }>;
+            hasMore: boolean;
+            nextCursor: number;
+            entityTypes: Array<{
+                type: string;
+                owner: string;
+                order: number;
+                readOnly: boolean;
+            }>;
+        }>;
+        parsePushOps: (body: unknown) => Promise<SyncPushOp[] | null>;
+        applyPush: (userId: string, ops: SyncPushOp[]) => Promise<SyncPushResult[]>;
+        /** Streams a change notice to the account's open event streams. */
+        listen: (userId: string, res: unknown) => Promise<() => void>;
+    };
+    /**
+     * The linked server registry, kept in core so it is there before plugins.
+     * One link per local user. Without a user, the active account is meant.
+     */
+    links: {
+        list: () => Promise<SyncLinkInfo[]>;
+        get: (userId?: string) => Promise<SyncLinkInfo | null>;
+        create: (link: SyncLinkCreate) => Promise<SyncLinkInfo>;
+        update: (patch: SyncLinkPatch, userId?: string) => Promise<SyncLinkInfo | null>;
+        remove: (userId?: string) => Promise<void>;
+    };
+    /** Desktop accounts: the local user and the replica user of each server. */
+    accounts: {
+        list: () => Promise<SyncAccountInfo[]>;
+        /** A new empty account, ready to be linked to a server. */
+        create: () => Promise<string>;
+        /** Which account the app signs in as from now on. */
+        setActive: (userId: string) => Promise<void>;
+        activeId: () => Promise<string | null>;
+        /** Deletes an account and all its data. The last one cannot go. */
+        remove: (userId: string) => Promise<void>;
+    };
+    http: {
+        json: <T>(target: SyncRemoteTarget, pathname: string, request?: SyncRemoteRequest) => Promise<T>;
+        fetch: (target: SyncRemoteTarget, pathname: string, request?: SyncRemoteRequest) => Promise<{
+            ok: boolean;
+            status: number;
+            body: AsyncIterable<Uint8Array> | null;
+        }>;
+        normalizeServerUrl: (input: string) => string | null;
+        isRemoteError: (error: unknown) => error is SyncRemoteError;
+    };
+    sessions: {
+        /** A long lived session for a linked desktop. Shows in the account's sessions. */
+        issueDesktop: (userId: string, options: {
+            days: number;
+            deviceInfo: string;
+        }) => Promise<string>;
+        revoke: (sessionId: string) => Promise<void>;
+        find: (sessionId: string) => Promise<{
+            expiresAt: string;
+            deviceInfo: string | null;
+        } | null>;
+        findUser: (userId: string) => Promise<{
+            id: string;
+            username: string;
+        } | null>;
+        /** The user and session behind a token, or null when it is not valid. */
+        verify: (token: string) => Promise<{
+            userId: string;
+            sessionId?: string;
+        } | null>;
+        /** Sets the sign in cookie on a response, like a login does. A name sets another cookie. */
+        setCookie: (req: unknown, res: unknown, value: string, options?: {
+            name?: string;
+            days?: number;
+        }) => void;
+        /** Removes the sign in cookie, without ending the session behind it. */
+        clearCookie: (req: unknown, res: unknown, name?: string) => void;
+        /** Express middleware that signs the request in and sets userId and sessionId. */
+        middleware: () => unknown;
+        /** Express middleware that lets a request through only on a desktop. */
+        desktopOnly: () => unknown;
+    };
+    hosts: {
+        findForSync: (userId: string, syncId: string) => Promise<{
+            id: number;
+            name: string | null;
+        } | null>;
+        statusBySyncId: (userId: string) => Promise<Record<string, unknown>>;
+    };
+    plugins: {
+        listForDesktop: () => Promise<{
+            plugins: SyncRemotePlugin[];
+            registryKeys: unknown;
+        }>;
+        /** Sends a plugin archive; false when there is no such plugin to share. */
+        sendPackage: (pluginId: string, res: unknown) => Promise<boolean>;
+        mirror: (link: SyncLinkInfo) => Promise<void>;
+        lastRemote: () => SyncRemotePlugin[];
+        localNames: () => Map<string, string>;
+    };
+    desktop: {
+        /** Tells the app's main process how to reach the linked origin. */
+        applyProxy: (link: SyncLinkInfo | null) => Promise<void>;
+        deviceName: () => string;
+    };
+    alerts: {
+        send: (alert: {
+            title: string;
+            body: string;
+            severity: "info" | "warning" | "error";
+            category: string;
+            dedupeKey: string;
+            link?: {
+                tab: string;
+            };
+        }) => Promise<void>;
+    };
 }
 /**
  * A plain key/value hand-off between plugins. `provide` and `revoke` only take
@@ -591,11 +931,40 @@ export interface PluginHostCreateInput {
     sshOptions?: HostSshOptions | null;
     /** Host settings by plugin id, the shape a Termix export carries. */
     pluginSettings?: Record<string, Record<string, unknown>>;
+    /**
+     * Each plugin's own host switch (its manifest enableKey), by plugin id.
+     * A plugin that is not running is skipped and logged; one with no switch
+     * is refused.
+     */
+    pluginEnable?: Record<string, boolean>;
+    /**
+     * Secrets, stored encrypted with the owner's data key and never returned
+     * in a PluginHostRecord. An empty string or null clears the stored value.
+     */
+    password?: string | null;
+    key?: string | null;
+    keyPassword?: string | null;
+    keyType?: string | null;
+    sudoPassword?: string | null;
+    /**
+     * Logins for plugin protocols (contributes.protocols), keyed by protocol
+     * id. null removes that protocol's login. Unknown protocol ids are skipped.
+     */
+    protocolAuth?: Record<string, PluginHostProtocolAuthInput | null>;
+}
+/** One protocol login on a host write. Absent keys keep what is stored. */
+export interface PluginHostProtocolAuthInput {
+    authType?: "direct" | "credential" | "none";
+    credentialId?: number | null;
+    username?: string | null;
+    password?: string | null;
+    /** The protocol's declared credentialFields, secret ones included. */
+    fields?: Record<string, string>;
 }
 /** Fields a plugin may change on a host the acting user owns. */
 export type PluginHostUpdateInput = Partial<PluginHostCreateInput>;
 /** Every key PluginHostCreateInput and PluginHostUpdateInput accept. */
-export declare const PLUGIN_HOST_INPUT_KEYS: readonly ["name", "ip", "port", "username", "authType", "credentialId", "overrideCredentialUsername", "connectionType", "tags", "folder", "pin", "notes", "jumpHosts", "enableSsh", "sshPort", "statusCheckEnabled", "statusCheckInterval", "forceKeyboardInteractive", "sshOptions", "pluginSettings"];
+export declare const PLUGIN_HOST_INPUT_KEYS: readonly ["name", "ip", "port", "username", "authType", "credentialId", "overrideCredentialUsername", "connectionType", "tags", "folder", "pin", "notes", "jumpHosts", "enableSsh", "sshPort", "statusCheckEnabled", "statusCheckInterval", "forceKeyboardInteractive", "sshOptions", "pluginSettings", "pluginEnable", "password", "key", "keyPassword", "keyType", "sudoPassword", "protocolAuth"];
 /** The same shape canAccessHost returns internally, without secrets. */
 export interface PluginHostAccess {
     hasAccess: boolean;
@@ -624,6 +993,31 @@ export interface PluginShareableRole {
     name: string;
     displayName: string | null;
 }
+/** One grant in ctx.hosts.setShares. */
+export interface PluginHostShareGrant {
+    target: PluginShareTarget;
+    permissionLevel: PluginHostShareLevel;
+    /** Omit for a grant that never expires. */
+    durationHours?: number;
+}
+/**
+ * Hosts a plugin manages itself, for example from a config file. Core refuses
+ * edits, deletes and share changes on a locked host from the UI, the API and
+ * other plugins, and marks it in host reads so a layout can show it read only.
+ * Pins and order stay with the user. Only the plugin that locks a host may
+ * still write it.
+ */
+export interface PluginHostLockProvider {
+    isLocked: (hostId: number) => boolean;
+    /** A short line shown under the managed note, or null. */
+    note: (hostId: number) => string | null;
+    /** False blocks adding hosts by hand (editor, import, other plugins). */
+    allowManualCreate: () => boolean;
+}
+export interface PluginHostLocksApi {
+    /** Registers this plugin's locks. Needs hosts:lock. Removed on deactivate. */
+    provide: (provider: PluginHostLockProvider) => () => void;
+}
 /**
  * Hosts the acting user can see, and the RBAC + sharing operations a plugin
  * needs to build a feature (like fleets) on top of hosts it does not own.
@@ -675,6 +1069,12 @@ export interface PluginHosts {
      * Refuses a host the caller does not hold "manage" on.
      */
     share: (hostId: number, targets: PluginShareTarget[], permissionLevel: PluginHostShareLevel, durationHours?: number) => Promise<PluginHostShareResult>;
+    /**
+     * Replaces every grant on a host the acting user owns with this list.
+     * Grants that stay keep their row and counters, missing ones are revoked.
+     * Needs hosts:write.
+     */
+    setShares: (hostId: number, grants: PluginHostShareGrant[]) => Promise<PluginHostShareResult>;
     /** Users the caller may pick as a share target, for building a picker UI. */
     listUsers: () => Promise<PluginShareableUser[]>;
     /** Non-system roles the caller may pick as a share target. */
@@ -736,6 +1136,19 @@ export interface PluginHosts {
     registerImportNormalizer: (normalizer: PluginHostImportNormalizer) => () => void;
     /** The recent activity list on the dashboard. */
     activity: PluginHostActivityApi;
+    /** Read only hosts this plugin manages. */
+    locks: PluginHostLocksApi;
+    /** Folder rows for the acting user. Needs hosts:write. */
+    folders: PluginHostFoldersApi;
+}
+export interface PluginHostFoldersApi {
+    /** Creates the folder row if missing and sets its color and icon. */
+    ensure: (name: string, style?: {
+        color?: string | null;
+        icon?: string | null;
+    }) => Promise<void>;
+    /** Removes the folder row and subfolders once no host is left in them. */
+    removeEmpty: (name: string) => Promise<boolean>;
 }
 export interface PluginHostImportOptions {
     /** Update a host that matches on ip, port and username instead of skipping it. */
@@ -1074,7 +1487,26 @@ export interface PluginNetwork {
         timeoutMs?: number;
     }) => Promise<boolean>;
 }
+/**
+ * A way to reach some hosts other than a plain TCP connection. `claims` is
+ * asked for every connection, so it must be quick. `open` returns a stream
+ * the SSH client runs over, like a relayed socket.
+ */
+export interface PluginSshTransportProvider {
+    claims: (hostId: number) => boolean;
+    open: (host: {
+        id: number;
+        ip: string;
+        port: number;
+    }) => Promise<import("node:stream").Duplex>;
+}
+export interface PluginSshTransports {
+    /** Needs ssh:transport. Removed on deactivate. */
+    provide: (provider: PluginSshTransportProvider) => () => void;
+}
 export interface PluginSsh {
+    /** Other ways to reach hosts, used by every connection to them. */
+    transports: PluginSshTransports;
     /**
      * Whether a TCP port answers through the host's jump host chain. Chains are
      * shared and closed when idle. The acting user must be able to connect to
@@ -1416,6 +1848,52 @@ export interface PluginSecondFactor {
     /** Removes the user's enrolment. Called by the admin reset. */
     reset?: (userId: string) => Promise<void>;
 }
+/** A login core is about to turn into a session. */
+export interface PluginAuthPolicyInput {
+    userId: string;
+    /** Login method id, `"proxy"` for a trusted proxy login. */
+    methodId: string;
+    /** The method signs in through an outside identity provider (SSO, LDAP). */
+    external: boolean;
+    deviceType: "web" | "desktop" | "mobile";
+    /** The device passed a second factor before and was remembered. */
+    trustedDevice: boolean;
+    /** The method itself proved a second factor, like a verified passkey. */
+    mfaSatisfied: boolean;
+    /** Every second factor core has, and whether this user set it up. */
+    secondFactors: {
+        id: string;
+        pluginId: string;
+        enrolled: boolean;
+    }[];
+}
+export interface PluginAuthPolicyDecision {
+    /** False turns remember me off and ignores remembered devices. */
+    allowRememberDevice?: boolean;
+    /** Caps how long the session lasts. */
+    maxSessionSeconds?: number;
+    /** Ends the session after this many seconds without a request. */
+    idleTimeoutSeconds?: number;
+    /**
+     * Requires a second factor even for users who have none: they get a
+     * session that can only set one up. `"new-device"` skips it on a
+     * remembered device.
+     */
+    secondFactor?: "always" | "new-device";
+}
+/**
+ * Login rules from a plugin. Core asks every provider and the strictest
+ * answer wins. A provider that throws refuses the login.
+ */
+export interface PluginAuthPolicyProvider {
+    evaluate: (input: PluginAuthPolicyInput) => PluginAuthPolicyDecision | Promise<PluginAuthPolicyDecision>;
+    /** Whether the login page should offer remember me. */
+    allowRememberDevice?: () => boolean;
+}
+export interface PluginAuthPolicyApi {
+    /** Needs auth:policy. Removed on deactivate. */
+    provide: (provider: PluginAuthPolicyProvider) => () => void;
+}
 export interface PluginUserTokenOptions {
     /** Why the token exists, kept in the audit log and on the session. */
     purpose: string;
@@ -1494,6 +1972,13 @@ export interface PluginAuth {
      * never outlive itself.
      */
     issueUserToken: (userId: string, options: PluginUserTokenOptions) => Promise<PluginUserToken>;
+    /** Login rules: idle timeout, session length, remember me, second factors. */
+    policy: PluginAuthPolicyApi;
+    /** Second factors from every running plugin. Needs no capability. */
+    listSecondFactors: () => {
+        id: string;
+        pluginId: string;
+    }[];
 }
 /** What a plugin may learn about a user. Needs users:read. */
 export interface PluginUsers {
@@ -1727,6 +2212,14 @@ export interface PluginSshKeyCredential {
     /** "<type> <base64>", derived from the private key when none was stored. Null when it cannot be. */
     publicKey: string | null;
 }
+/** A saved credential without its secrets. */
+export interface PluginCredentialSummary {
+    id: number;
+    name: string;
+    username: string | null;
+    authType: string;
+    folder: string | null;
+}
 /** A key pair to save as a new credential for the acting user. */
 export interface PluginSshKeyCredentialInput {
     name: string;
@@ -1747,6 +2240,12 @@ export interface PluginCredentials {
      * Needs credentials:use and the core credentials.view permission. Audited.
      */
     listSshKeys: () => Promise<PluginSshKeyCredential[]>;
+    /**
+     * The acting user's own credentials by name, with no secret material, so a
+     * plugin can point a host at one. Needs credentials:use and the core
+     * credentials.view permission. Audited.
+     */
+    list: () => Promise<PluginCredentialSummary[]>;
     /**
      * Saves a key pair as a new encrypted credential owned by the acting user
      * and returns its id. Needs credentials:write, the core credentials.create

package/dist/backend.js

@@ -65,6 +65,13 @@ export const PLUGIN_HOST_INPUT_KEYS = [
     "forceKeyboardInteractive",
     "sshOptions",
     "pluginSettings",
+    "pluginEnable",
+    "password",
+    "key",
+    "keyPassword",
+    "keyType",
+    "sudoPassword",
+    "protocolAuth",
 ];
 /** Thrown by ctx.ssh.startInteraction when no provider can start it. */
 export class PluginSshInteractionError extends Error {

package/dist/capabilities.js

@@ -33,6 +33,9 @@ export const CAPABILITY_CATALOG = [
     entry("users:impersonate", "high"),
     entry("db:core-refs", "high"),
     entry("auth:provide", "high"),
+    entry("auth:policy", "high"),
+    entry("sync:provide", "high"),
+    entry("ssh:transport", "high"),
     entry("device:serial", "high"),
     entry("notify:hub", "high"),
     entry("ui:layout", "high"),
@@ -46,6 +49,7 @@ export const CAPABILITY_CATALOG = [
     entry("network:probe", "medium"),
     entry("hosts:status-provide", "medium"),
     entry("hosts:activity-provide", "medium"),
+    entry("hosts:lock", "medium"),
     entry("users:read", "medium"),
     entry("events:core", "medium"),
     entry("notify:send", "medium"),

package/dist/frontend.d.ts

@@ -773,6 +773,43 @@ export interface SettingsComponentProps {
     setValue: (key: string, value: unknown) => void;
     running: boolean;
 }
+/** What a companion starts with. Read from the plugin's own settings. */
+export interface CompanionDefaults {
+    /** Open by itself the first time a matching tab shows. */
+    open?: boolean;
+    side?: "left" | "right" | "bottom";
+    /** Pixels of width, or height at the bottom. */
+    size?: number;
+    /** Show the edge button that opens and closes it. Default true. */
+    edgeButton?: boolean;
+}
+export interface CompanionProps {
+    /** The tab it sits beside. */
+    tab: PluginTabRecord;
+    host?: PluginHostRecord;
+    /** The host in the shape the connection APIs take. */
+    sshHost?: Record<string, unknown>;
+    /** The tab's surface handle (see TabHandle), read at call time. */
+    getHandle: () => TabHandle | null;
+    side: "left" | "right" | "bottom";
+    /** False while the tab is in the background or the panel is closed. */
+    isVisible: boolean;
+    close: () => void;
+    setSide: (side: "left" | "right" | "bottom") => void;
+}
+export interface CompanionOptions {
+    icon?: IconComponent;
+    titleKey?: string;
+    order?: number;
+    /** Tab types it applies to. Any tab with a host when empty. */
+    tabTypes?: string[];
+    when?: (tab: PluginTabRecord, host?: PluginHostRecord) => boolean;
+    /**
+     * A hook returning the starting state. It runs in the plugin's scope, so it
+     * can read the plugin's settings.
+     */
+    useDefaults?: () => CompanionDefaults;
+}
 export type ActionHandler = (...args: never[]) => unknown;
 export interface ActionSlotDefinition {
     id: string;
@@ -1001,6 +1038,14 @@ export interface TermixApp extends TermixAppInfo {
     registerRailItem: (item: RailItemContribution) => Disposer;
     registerPanel: (id: string, component: ComponentType<PanelProps>, options?: PanelOptions) => Disposer;
     registerTab: (type: string, component: ComponentType<TabProps>, options?: TabOptions) => Disposer;
+    /**
+     * A panel that sits beside any host tab the options match (a terminal, a
+     * desktop, ...), bound to that tab's host. The user opens, resizes and moves
+     * it; the tab keeps running underneath.
+     */
+    registerCompanion: (id: string, component: ComponentType<CompanionProps>, options?: CompanionOptions) => Disposer;
+    /** Opens a companion on a tab, or closes it when it is showing. */
+    toggleCompanion: (tab: PluginTabRecord, id?: string) => void;
     registerHostEditorSection: (section: HostEditorSectionContribution) => Disposer;
     registerHostAction: (action: HostActionContribution) => Disposer;
     registerHostProtocol: (protocol: HostProtocolContribution) => Disposer;

package/dist/host/{PluginsTab-OXQQ7M4I.js → PluginsTab-YAGYRBIE.js}

@@ -29,7 +29,7 @@ import {
   sortPlugins,
   uploadEntry,
   youtubeEmbedUrl
-} from "./chunk-54KCK6IZ.js";
+} from "./chunk-446UEDSK.js";
 import {
   ArrowDownWideNarrow,
   BookOpen,
@@ -107,8 +107,8 @@ import {
   updatePlugin,
   uploadPlugin,
   useConfirm
-} from "./chunk-ERGN4YW6.js";
-import "./chunk-CN5UBTBP.js";
+} from "./chunk-LQKK2JJA.js";
+import "./chunk-7LEJ3HYF.js";
 import {
   __toESM,
   define_import_meta_env_default,