@voltius/plugin-types 0.24.0 → 0.26.0

package/index.d.ts

@@ -81,6 +81,8 @@ export interface AppTheme {
   uiFontSize: number;
   terminalFontFamily: string;
   terminalFontSize: number;
+  /** xterm lineHeight multiplier; optional for themes saved before it existed (defaults to 1). */
+  terminalLineHeight?: number;
   ui: UITheme;
   terminal: TerminalTheme;
 }
@@ -111,7 +113,62 @@ export type PluginAuditAction =
   // what actually reached the host. Must be on the server's CLIENT_WHITELIST
   // before any client that emits it ships, or the team rows are 400ed and
   // silently dropped.
-  | "agent.plugin_tool_run";
+  | "agent.plugin_tool_run"
+  // Team membership and terminal sharing (P7). Membership is not an object
+  // edit, so these do not reuse agent.object_*: the trail has to stay
+  // filterable by what happened to a team.
+  | "agent.member_invited"
+  | "agent.member_removed"
+  | "agent.member_role_changed"
+  | "agent.session_shared"
+  | "agent.session_unshared"
+  | "agent.control_granted"
+  // A setting an agent changed. Local to the device: a settings verb's scope
+  // resolves no connection and no team, so runtime.ts files the row under the
+  // "personal" bucket audit.query reads. Nothing to add to the server's
+  // CLIENT_WHITELIST.
+  | "agent.setting_changed"
+  // Plugin lifecycle and import/export (P9). Local to the device: these verbs
+  // resolve no connection and no team, so runtime.ts files their rows under the
+  // "personal" bucket audit.query reads. Nothing to add to the server's
+  // CLIENT_WHITELIST.
+  | "agent.plugin_installed"
+  | "agent.plugin_removed"
+  | "agent.plugin_enabled"
+  | "agent.plugin_disabled"
+  | "agent.plugin_updated"
+  | "agent.plugin_configured"
+  | "agent.marketplace_source_changed"
+  | "agent.objects_imported"
+  | "agent.objects_exported";
+
+export type DomainResult<T> = { ok: true; result: T } | { ok: false; error: string };
+
+export interface PluginTeam {
+  id: string; name: string; ownerTier: string; myRoles: string[]; myRoleIds: string[]; vaultStatus: string;
+}
+
+export type PluginTeamMember =
+  | { state: "member"; userId: string; displayName: string; roles: string[]; roleIds: string[]; isOnline: boolean }
+  | { state: "pending"; invitationId: string; displayName: string; roles: string[]; isOnline: false };
+
+export interface PluginMemberKeyState {
+  userId: string; displayName: string; hasPublicKey: boolean; hasWrappedKey: boolean;
+}
+
+export interface PluginTeamKeyStatus {
+  teamId: string; vaultStatus: string; iHoldKey: boolean; members: PluginMemberKeyState[];
+}
+
+export interface PluginSharedSession {
+  multiplayerSessionId: string;
+  localSessionId: string | null;
+  connectionName: string;
+  isHost: boolean;
+  participants: { userId: string; displayName: string }[];
+  controlHolder: string;
+  controlRequester: string | null;
+}
 
 
 
@@ -817,8 +874,9 @@ export interface PortsAPI {
   reach(req: ReachPortRequest): Promise<ReachPortResponse>;
 }
 
-/** A local audit row, projected. Drops the internal id, actor id, team/vault
- *  ids and IP — none of which a plugin or an external client has any use for. */
+/** A local or team-server audit row, projected. Drops the internal id, actor
+ *  id, team/vault ids and IP — none of which a plugin or an external client
+ *  has any use for. */
 export interface PluginAuditRow {
   action: string;
   actor_name: string;
@@ -832,6 +890,10 @@ export interface PluginAuditRow {
 
 export interface PluginAuditQuery {
   actions?: string[];
+  /** Reads that team's server-side log instead of the device's local sink. */
+  teamId?: string;
+  vaultId?: string;
+  actorId?: string;
   /** ISO 8601. */
   from?: string;
   to?: string;
@@ -1013,6 +1075,48 @@ export interface PluginAPI {
     focus(sessionId: string, maximize?: boolean): PluginPaneResult;
   };
 
+  /**
+   * Teams, members and vault-key distribution (requires team:read / team:write).
+   *
+   * Writes are bounded by the caller's own server-side role bits: a member
+   * without PERM_MANAGE_MEMBERS is refused by the server, not by this layer.
+   * `keyStatus` reports the window where a member can be keyed but has not
+   * been yet, and never repairs it.
+   */
+  team: {
+    list(): Promise<PluginTeam[]>;
+    members(teamId: string): Promise<PluginTeamMember[]>;
+    /** Every team the caller can see when `teamId` is omitted. */
+    keyStatus(teamId?: string): Promise<PluginTeamKeyStatus[]>;
+    /** Exactly one of `email` or `userId`. */
+    invite(input: { teamId: string; email?: string; userId?: string; role?: string }):
+      Promise<DomainResult<{ status: "pending" | "already_member" | "invited"; key: PluginMemberKeyState | null }>>;
+    removeMember(teamId: string, userId: string): Promise<DomainResult<null>>;
+    /** Replaces every role the member holds with `role`, a role id or role name
+     *  as reported by `list` and `members`. An unresolvable role is refused
+     *  before any role is removed. */
+    setMemberRole(teamId: string, userId: string, role: string): Promise<DomainResult<null>>;
+  };
+
+  /**
+   * Live terminal sharing (requires sharing:read / sharing:write).
+   *
+   * Team-scoped only: the invite-link path mints a bearer token and is not
+   * exposed. Writes return a DomainResult rather than throwing.
+   */
+  sharing: {
+    list(): Promise<PluginSharedSession[]>;
+    /** Why `share` would refuse this session, or null when it may proceed —
+     *  callable before an approval is asked for, so a doomed share raises no
+     *  card and records nothing. */
+    shareRefusal(sessionId: string): string | null;
+    share(input: { sessionId: string; vaultIds: string[]; allowedRoles?: string[] }):
+      Promise<DomainResult<{ multiplayerSessionId: string }>>;
+    unshare(sessionId: string): Promise<DomainResult<null>>;
+    /** Only approves a control request the participant already made. */
+    handoffControl(sessionId: string, userId: string): Promise<DomainResult<null>>;
+  };
+
   /**
    * The state of the user's own configuration sync (requires sync:read).
    * Distinct from the plugin-scoped `sync` domain above, which is a plugin's
@@ -1095,11 +1199,34 @@ export interface PluginAPI {
       metadata?: Record<string, unknown>,
       localMetadata?: Record<string, unknown>,
     ): void;
-    /** This device's local rows only. Team-vault rows are server-backed and
-     *  are not returned here. */
+    /** Local rows by default; pass `teamId` to read that team's server-side log instead. */
     query(filters: PluginAuditQuery): Promise<{ logs: PluginAuditRow[]; total: number }>;
   };
 
+  // App settings — read the manifest and current values (requires the gated
+  // "settings:read"); write one (requires the gated "settings:write").
+  settings: {
+    list(filter?: { section?: string; prefix?: string; writableOnly?: boolean }): SettingView[];
+    get(key: string): SettingView | undefined;
+    /** The sentence a guarded write must be refused with, or undefined when
+     *  writing `value` does not weaken any safeguard (re-enabling one never
+     *  does). Read-only — requires "settings:read". */
+    consequenceOf(key: string, value: unknown): string | undefined;
+    /** Writes, then RE-READS: a store setter may clamp or normalise, so
+     *  `effective` is the value that actually landed, not the one asked for,
+     *  and `coerced` says whether the two differ. Neither reports whether the
+     *  setting's value moved — writing the value it already held is a
+     *  successful write with `coerced: false`. */
+    set(key: string, value: unknown): DomainResult<{
+      key: string; requested: unknown; effective: unknown; coerced: boolean;
+    }>;
+  };
+
+  // The user's own plan and billing state (requires the gated "account:read")
+  account: {
+    subscription(): Promise<SubscriptionView>;
+  };
+
   // Themes (requires "themes")
   themes: {
     register(theme: PluginTheme): void;
@@ -1313,12 +1440,39 @@ export interface PluginAPI {
     importStates(encKey: string, blobs: string[]): Promise<void>;
   };
 
-  // Inter-plugin communication (always available)
+  // Inter-plugin communication (always available), plus plugin inventory and
+  // lifecycle (requires the gated "plugins:manage"). Configuration is limited
+  // to keys the target plugin declares in `contributes.configuration`; raw
+  // api.storage is deliberately not reachable.
   plugins: {
     /** Publish this plugin's public API surface so other plugins can consume it. */
     expose(publicApi: unknown): void;
     /** Get another plugin's exposed API. Returns null if not loaded or not exposed. */
     getApi(pluginId: string): unknown | null;
+
+    list(): Promise<PluginView[]>;
+    install(id: string): Promise<DomainResult<PluginView>>;
+    uninstall(id: string): Promise<DomainResult<{ id: string }>>;
+    setEnabled(id: string, enabled: boolean): Promise<DomainResult<PluginView>>;
+    update(id: string): Promise<DomainResult<PluginView>>;
+    config(id: string): Promise<DomainResult<Record<string, unknown>>>;
+    configure(id: string, key: string, value: unknown): Promise<DomainResult<{ key: string; effective: unknown }>>;
+    sources(): Promise<SourceView[]>;
+    search(query?: string): Promise<MarketplacePlugin[]>;
+    addSource(url: string): Promise<DomainResult<SourceView>>;
+    removeSource(id: string): Promise<DomainResult<{ id: string }>>;
+  };
+
+  // Bulk export (requires the gated "importexport:read") and import (requires
+  // the gated "importexport:write"). A bundle carrying secrets is only ever
+  // returned encrypted.
+  importExport: {
+    export(opts: {
+      vaultIds: string[]; types: ExportType[]; format: "json" | "csv"; passphrase?: string;
+    }): Promise<DomainResult<ExportResult>>;
+    import(opts: {
+      content: string; vaultId: string; passphrase?: string; dryRun: boolean;
+    }): Promise<DomainResult<ImportResult>>;
   };
 
   // MCP tool contributions — GATED (mcp:contribute). Tools run with THIS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltius/plugin-types",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "TypeScript definitions for the Voltius plugin API",
   "types": "index.d.ts",
   "files": [