@voltius/plugin-types 0.22.0 → 0.24.0

package/index.d.ts

@@ -94,6 +94,9 @@ export type PluginAuditAction =
   | "agent.session_opened"
   | "agent.session_closed"
   | "agent.command_run"
+  // Real keystrokes, not a shell line: a TUI interaction is not a command run,
+  // and a reviewer must be able to tell a C-c from an rm -rf.
+  | "agent.keys_sent"
   | "agent.action_denied"
   | "agent.file_created"
   | "agent.file_written"
@@ -203,6 +206,103 @@ export interface PluginSnippetInput {
   vault_id?: string;
 }
 
+/** One target for a snippet run: an open session, or a saved connection the run
+ *  connects on the fly. */
+export interface PluginSnippetTargetRef {
+  session_id?: string;
+  connection_id?: string;
+}
+
+export interface PluginSnippetRunResult {
+  targets: { label: string; ok: boolean; error?: string }[];
+  flatten_errors: string[];
+  /** Sessions this run opened for saved-connection targets, for reading back. */
+  opened_session_ids: string[];
+  /** Only on a dry run: the steps that would execute, per target, with the
+   *  variables resolved. A variable nobody supplied stays as its `{{name}}`. */
+  steps?: { label: string; steps: unknown[] }[];
+}
+
+export interface PluginKnownHost {
+  id: string;
+  host: string;
+  port: number;
+  fingerprint: string;
+  vault_id: string;
+  created_at: string;
+}
+
+export interface PluginTrustResult {
+  entry: PluginKnownHost;
+  superseded: PluginKnownHost[];
+  /** True when `replace` soft-deleted existing entries for this host:port. */
+  replaced: boolean;
+}
+
+export interface PluginHistoryEntry {
+  id: string;
+  command: string;
+  /** Epoch milliseconds. */
+  timestamp: number;
+  session_id: string;
+  session_name: string;
+  connection_id: string;
+}
+
+export interface PluginTransfer {
+  id: string;
+  label: string;
+  direction: "→" | "←";
+  status: "running" | "done" | "cancelled" | "error";
+  transferred: number;
+  total: number;
+  speed?: number;
+  eta?: number;
+  error?: string;
+  /** Name of the MCP client that started it; absent for the user's own. */
+  owner?: string;
+}
+
+export interface PluginSyncState {
+  status: "idle" | "syncing" | "success" | "error" | "offline";
+  lastSync: string | null;
+  error: string | null;
+  cloudActive: boolean;
+  blobSizeBytes: number | null;
+}
+
+export interface PluginHostPing {
+  connectionId: string;
+  status: "up" | "down" | "unknown";
+  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.
@@ -447,8 +547,11 @@ export interface SftpAPI {
   rename(target: FileTarget, from: string, to: string): Promise<void>;
   delete(target: FileTarget, path: string): Promise<void>;
   /** Copy one path between any two targets, in any direction, files or
-   *  directories. Host→host streams directly and never lands on this machine. */
-  transfer(src: FileEndpoint, dst: FileEndpoint): Promise<void>;
+   *  directories. Host→host streams directly and never lands on this machine.
+   *  `transferId` defaults to a fresh one; a caller that already has an id to
+   *  subscribe progress under (the transfer queue) can pass its own so the
+   *  backend's `sftp-progress-<id>` events reach it instead of going nowhere. */
+  transfer(src: FileEndpoint, dst: FileEndpoint, transferId?: string): Promise<void>;
   /** Release the handle held for `target`, if any. */
   disconnect(target: FileTarget): Promise<void>;
 }
@@ -817,7 +920,7 @@ export interface PluginAPI {
     delete(id: string, opts?: { cascade?: boolean }): Promise<void>;
   };
 
-  // Saved snippets (requires snippets:read / snippets:write)
+  // Saved snippets (requires snippets:read / snippets:write, and snippets:run for `run`)
   snippets: {
     list(): Promise<PluginSnippet[]>;
     create(input: PluginSnippetInput): Promise<PluginSnippet>;
@@ -825,6 +928,98 @@ export interface PluginAPI {
     update(id: string, patch: Partial<PluginSnippetInput>): Promise<void>;
     /** Rejects a team vault. */
     delete(id: string): Promise<void>;
+    /**
+     * Run a saved snippet against open sessions or saved connections (requires
+     * the gated snippets:run). Script steps are injected into a terminal, so the
+     * result carries per-target ok/error, not command output — read that with
+     * the session verbs, including on `opened_session_ids`. A user variable the
+     * snippet needs and `variables` does not supply is a rejection, not a prompt.
+     */
+    run(input: {
+      snippetId: string;
+      targets: PluginSnippetTargetRef[];
+      /** The snippet's own user variables. Keys that name a dynamic variable
+       *  ({{connection.host}}, {{clipboard}}, …) are ignored — those resolve per
+       *  target and cannot be supplied. */
+      variables?: Record<string, string>;
+      /** Report the steps that would run, without running anything. */
+      dryRun?: boolean;
+    }): Promise<PluginSnippetRunResult>;
+  };
+
+  /**
+   * The trust-on-first-use host key store (requires the gated
+   * known_hosts:read / known_hosts:write).
+   */
+  knownHosts: {
+    list(filter?: { host?: string; port?: number }): Promise<PluginKnownHost[]>;
+    delete(id: string): Promise<void>;
+    /**
+     * `replace` supersedes the stored keys for this host:port. Without it, a
+     * host that already has a stored key is rejected — a second key would be
+     * accepted alongside the first. Rejects a team vault.
+     */
+    trust(input: {
+      host: string; port: number; fingerprint: string; vaultId?: string; replace?: boolean;
+    }): Promise<PluginTrustResult>;
+  };
+
+  /**
+   * Command lines the user typed in a terminal (requires the gated history:read).
+   * Persisted, capped at 500 entries by the store.
+   */
+  history: {
+    search(filter: {
+      query?: string; connectionId?: string; sessionId?: string; limit?: number;
+    }): PluginHistoryEntry[];
+  };
+
+  /**
+   * File transfers in the app's queue — the user's own and any an MCP client
+   * started (requires the gated transfers:read / transfers:write). The list is
+   * capped at 30 entries by the store and is not persisted across restarts.
+   */
+  transfers: {
+    list(): PluginTransfer[];
+    /** False when the id is unknown, or the transfer is not currently running. */
+    cancel(id: string): boolean;
+    /** False when the id is unknown, or the transfer is still running, already done,
+     *  or not yet settled (a just-cancelled row still winding down). */
+    retry(id: string): boolean;
+  };
+
+  /**
+   * Host reachability as last observed by the app's own polling (requires the
+   * gated health:read). Reading NEVER triggers a probe: issue #90 was a probe
+   * storm that tripped `ufw limit` and locked users out of their own hosts.
+   */
+  health: {
+    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;
+  };
+
+  /**
+   * 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
+   * own blob storage and gist sync — this is the app's own cross-device sync.
+   */
+  appSync: {
+    status(): PluginSyncState;
   };
 
   /**
@@ -1007,8 +1202,13 @@ export interface PluginAPI {
     onActivated(cb: (session: PluginSession) => void): () => void;
     /** Send a command to a session. Runtime appends \n. Requires sessions:write. */
     sendCommand(sessionId: string, cmd: string): Promise<void>;
-    /** Open (connect) a saved connection by id. Resolves to the new sessionId. Requires sessions:write. */
-    open(connectionId: string): Promise<string>;
+    /** Write text to a session's terminal VERBATIM — no newline, no wrapper.
+     *  Use for keystrokes and control bytes; use sendCommand to run a line.
+     *  Requires terminal:write. */
+    sendInput(sessionId: string, data: string): Promise<void>;
+    /** Open (connect) a saved connection by id. Resolves to the new sessionId. Requires sessions:write.
+     *  `background: true` opens the tab without stealing the user's active one. */
+    open(connectionId: string, options?: { background?: boolean }): Promise<string>;
     /** Close (disconnect) a session by id. Requires sessions:write. */
     close(sessionId: string): Promise<void>;
   };
@@ -1021,6 +1221,10 @@ export interface PluginAPI {
     readSelection(sessionId: string): string;
     /** Subscribe to live decoded output for a session. Resolves to an unsubscribe fn. */
     onOutput(sessionId: string, cb: (text: string) => void): Promise<() => void>;
+    /** Whether the session's terminal is in application-cursor-keys mode
+     *  (DECCKM): arrows must be sent as ESC O x rather than ESC [ x.
+     *  False when the session has no mounted terminal. Requires terminal:read. */
+    appCursorMode(sessionId: string): boolean;
   };
 
   // Keychain — GATED (first-party only). OS-local, never synced.

package/package.json

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