feat(plugins): add saved hosts from connection targets

packages/plugin/src/boundaries.test.ts

@@ -92,6 +92,18 @@ function typeErrors(code: string): string[] {
     .map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"));
 }
 describe("plugin SDK import boundaries", () => {
+  it("exposes host handles and object-shaped additions from the client entry", () => {
+    expect(
+      typeErrors(`
+      import { addHost, observeHosts, useHosts, type PluginHost } from "@getpaseo/plugin/client";
+      const hosts: readonly PluginHost[] = useHosts();
+      const stop = observeHosts((value) => { void value[0]?.openSettings(); });
+      void addHost({ connection: "localhost:6767", label: "Local" });
+      void hosts; stop();
+    `),
+    ).toEqual([]);
+  });
+
   it("publishes process capabilities without their Windows implementation helpers", () => {
     expect(Object.keys(server).sort()).toEqual([
       "defineAgentTool",

packages/plugin/src/client/hosts.ts

@@ -16,8 +16,10 @@ export type PluginHostColor =
 export type PluginHostBadgeDisplay = "name" | "icon" | "hidden";
 export interface PluginHostAppearance {
   readonly color: PluginHostColor;
+  /** Null uses the automatic local or remote default. */
   readonly badgeDisplay: PluginHostBadgeDisplay | null;
 }
+/** Saved connection settings without credentials. Routed connections have no URI. */
 export type PluginHostConnection =
   | {
       readonly id: string;
@@ -75,11 +77,14 @@ export interface PluginHost extends PluginHostSummary {
   readonly createdAt: string;
   readonly updatedAt: string;
   update(patch: PluginHostPatch): Promise<void>;
+  /** Removes the host; throws for the desktop daemon host. */
   remove(): Promise<void>;
+  /** Removing the last connection removes the host. */
   removeConnection(connectionId: string): Promise<void>;
   openSettings(): void;
 }
 export interface PluginHostAddInput {
+  /** Shared host connection grammar; may contain a password for the probe. */
   connection: string;
   label?: string;
 }
@@ -89,3 +94,5 @@ export type PluginHostAddResult =
   | { status: "cancelled" };
 export declare function useHosts(): readonly PluginHost[];
 export declare function observeHosts(listener: (hosts: readonly PluginHost[]) => void): () => void;
+
+export declare function addHost(input: PluginHostAddInput): Promise<PluginHostAddResult>;

packages/plugin/src/client/index.ts

@@ -88,6 +88,7 @@ export interface PluginHostSummary {
 /** Live configured hosts. Supplied by the app's client bundle loader. */
 export declare const useHosts: typeof import("./hosts.js").useHosts;
 export declare const observeHosts: typeof import("./hosts.js").observeHosts;
+export declare const addHost: typeof import("./hosts.js").addHost;
 export type {
   PluginHost,
   PluginHostStatus,