@voltius/plugin-types 0.23.0 → 0.25.0

package/index.d.ts

@@ -111,7 +111,44 @@ 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";
+
+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;
+}
 
 
 
@@ -277,6 +314,32 @@ export interface PluginHostPing {
   latencyMs?: number;
 }
 
+export type PluginPanePosition = "left" | "right" | "top" | "bottom";
+
+export interface PluginPane {
+  paneId: string;
+  sessionId: string;
+  connectionName: string;
+  active: boolean;
+  maximized: boolean;
+}
+
+/** A titlebar item: a split tab with one entry per pane, or a standalone
+ *  session projected as a single-pane tab so callers read one uniform list. */
+export interface PluginPaneTab {
+  tabId: string;
+  kind: "split" | "session";
+  active: boolean;
+  panes: PluginPane[];
+  broadcastActive: boolean;
+  layout: PaneNode | null;
+}
+
+/** `tab` is null when the write left no tab behind (the last split collapsed). */
+export type PluginPaneResult =
+  | { ok: true; tab: PluginPaneTab | null }
+  | { ok: false; error: string };
+
 /**
  * A SAVED port-forwarding rule: a shape, not a live listener. Opening one is
  * `portForwards.start`, which needs an open session to hang the tunnel on.
@@ -971,6 +1034,64 @@ export interface PluginAPI {
     pingStatus(): PluginHostPing[];
   };
 
+  /**
+   * The terminal tab and pane layout (requires panes:read / panes:write).
+   *
+   * Ungated deliberately: these rearrange tabs and destroy nothing, which is
+   * strictly less than the ungated sessions:write, and detaching a pane leaves
+   * the session open. Writes never throw — they return a PluginPaneResult whose
+   * `error` says why, because every underlying store method fails silently.
+   */
+  panes: {
+    list(): PluginPaneTab[];
+    split(input: { sessionId: string; targetSessionId: string; position: PluginPanePosition }): PluginPaneResult;
+    move(input: { sessionId: string; targetSessionId: string; position: PluginPanePosition }): PluginPaneResult;
+    detach(sessionId: string): PluginPaneResult;
+    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

package/package.json

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