@voltius/plugin-types 0.21.1 → 0.23.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"
@@ -114,7 +117,21 @@ export type PluginAuditAction =
 
 // ─── Types exposés aux plugins ─────────────────────────────────────────────
 
-export interface PluginConnection {
+/**
+ * Where a vault object is filed. Carried by every object a read verb returns and
+ * by everything the create verbs hand back, so a caller that relocated something
+ * with `objects.move` can observe where it landed — before this nothing could.
+ *
+ * `vault_id` is a `vaults.list()` id, "personal" when the object is in no other
+ * vault; `folder_id` is null at that vault's root. Both feed straight back into
+ * `PluginObjectMoveInput`.
+ */
+export interface PluginObjectPlacement {
+  vault_id?: string;
+  folder_id?: string | null;
+}
+
+export interface PluginConnection extends PluginObjectPlacement {
   id: string;
   name?: string;
   host: string;
@@ -150,14 +167,14 @@ export interface PluginConnectionInput {
   jump_hosts?: JumpHost[];
 }
 
-export interface PluginKey {
+export interface PluginKey extends PluginObjectPlacement {
   id: string;
   name?: string;
   key_type?: string;
   tags: string[];
 }
 
-export interface PluginIdentity {
+export interface PluginIdentity extends PluginObjectPlacement {
   id: string;
   name?: string;
   username: string;
@@ -165,6 +182,147 @@ export interface PluginIdentity {
   tags: string[];
 }
 
+export interface PluginSnippet extends PluginObjectPlacement {
+  id: string;
+  name: string;
+  steps: import("@/types").SnippetStep[];
+  description?: string;
+  tags: string[];
+  favorite: boolean;
+  /** Empty means the snippet offers itself everywhere. */
+  only_for_connection_tags: string[];
+  only_for_distros: string[];
+}
+
+export interface PluginSnippetInput {
+  name: string;
+  steps: import("@/types").SnippetStep[];
+  description?: string;
+  tags?: string[];
+  favorite?: boolean;
+  only_for_connection_tags?: string[];
+  only_for_distros?: string[];
+  folder_id?: string;
+  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;
+}
+
+/**
+ * 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.
+ */
+export interface PluginPortForward extends PluginObjectPlacement {
+  id: string;
+  name: string;
+  local_port: number;
+  remote_port: number;
+  remote_host: string;
+  tunnel_type: import("@/types").TunnelType;
+  bind_host: string;
+  target_host: string;
+  description?: string;
+  /** Connections this rule offers itself on. Empty means all of them. */
+  connection_ids: string[];
+}
+
+export interface PluginPortForwardInput {
+  name: string;
+  local_port: number;
+  remote_port: number;
+  remote_host: string;
+  tunnel_type: import("@/types").TunnelType;
+  bind_host?: string;
+  target_host?: string;
+  description?: string;
+  connection_ids?: string[];
+  folder_id?: string;
+  vault_id?: string;
+}
+
+/** A tunnel that is open right now on one session. Dies with the session. */
+export interface PluginActiveTunnel {
+  id: string;
+  tunnel_type: import("@/types").TunnelType;
+  local_port: number;
+  remote_port: number;
+  remote_host: string;
+  bind_host?: string;
+  target_host?: string;
+  /** "active", or the error it failed with. */
+  state: import("@/types").TunnelState;
+  bytes_transferred: number;
+}
+
 /** A vault the user organizes objects into. Unrelated to `api.vault`, which is plugin storage. */
 export interface PluginVault {
   id: string;
@@ -209,6 +367,17 @@ export interface PluginObjectMoveOutcome {
   created: number;
   /** Ids that no longer exist, or objects already where the call would put them. */
   skipped: number;
+  /**
+   * Where the objects ended up, so a move confirms itself without a follow-up
+   * read. `folder_id` is null at the destination vault's root.
+   *
+   * `vault_id` is null only when the call named no destination vault and no
+   * destination folder to take one from — every object kept the vault it had,
+   * and there is no single id to report. It is the adapter's own resolved
+   * target, not an echo of the request.
+   */
+  vault_id: string | null;
+  folder_id: string | null;
 }
 
 export interface OmniCommand {
@@ -352,8 +521,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>;
 }
@@ -722,6 +894,114 @@ export interface PluginAPI {
     delete(id: string, opts?: { cascade?: boolean }): Promise<void>;
   };
 
+  // Saved snippets (requires snippets:read / snippets:write, and snippets:run for `run`)
+  snippets: {
+    list(): Promise<PluginSnippet[]>;
+    create(input: PluginSnippetInput): Promise<PluginSnippet>;
+    /** Only the fields given are altered. Rejects a team vault. */
+    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 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;
+  };
+
+  /**
+   * Saved port-forwarding rules, and the tunnels open right now.
+   *
+   * A rule is a vault object; a tunnel is a live listening socket bound to one
+   * SSH session and gone when that session closes. `start` is what turns the
+   * first into the second (requires port_forwarding:read / port_forwarding:write,
+   * and sessions:read for the tunnel methods).
+   */
+  portForwards: {
+    list(): Promise<PluginPortForward[]>;
+    create(input: PluginPortForwardInput): Promise<PluginPortForward>;
+    /** Only the fields given are altered. Rejects a team vault. */
+    update(id: string, patch: Partial<PluginPortForwardInput>): Promise<void>;
+    /** Rejects a team vault. */
+    delete(id: string): Promise<void>;
+    /** Tunnels open on one session. */
+    tunnels(sessionId: string): Promise<PluginActiveTunnel[]>;
+    /** Opens a saved rule's tunnel on an open session. */
+    start(ruleId: string, sessionId: string): Promise<PluginActiveTunnel>;
+    stop(sessionId: string, tunnelId: string): Promise<void>;
+  };
+
   // Folders across all four trees (requires the gated folders:*)
   folders: {
     list(kind?: PluginFolderKind): PluginFolder[];
@@ -880,8 +1160,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>;
   };
@@ -894,6 +1179,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.21.1",
+  "version": "0.23.0",
   "description": "TypeScript definitions for the Voltius plugin API",
   "types": "index.d.ts",
   "files": [