@vellumai/assistant 0.6.5 → 0.6.6

package/src/runtime/__tests__/client-registry.test.ts

@@ -0,0 +1,293 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+
+import {
+  __resetClientRegistryForTests,
+  ClientRegistry,
+  getClientRegistry,
+} from "../client-registry.js";
+
+describe("ClientRegistry", () => {
+  beforeEach(() => {
+    __resetClientRegistryForTests();
+  });
+
+  // ── register ──────────────────────────────────────────────────────────────
+
+  test("register creates a new entry with derived capabilities", () => {
+    const registry = new ClientRegistry();
+    const entry = registry.register({
+      clientId: "mac-1",
+      interfaceId: "macos",
+      hostHomeDir: "/Users/alice",
+      hostUsername: "alice",
+    });
+
+    expect(entry.clientId).toBe("mac-1");
+    expect(entry.interfaceId).toBe("macos");
+    expect(entry.capabilities).toContain("host_bash");
+    expect(entry.capabilities).toContain("host_file");
+    expect(entry.capabilities).toContain("host_cu");
+    expect(entry.capabilities).toContain("host_browser");
+    expect(entry.hostHomeDir).toBe("/Users/alice");
+    expect(entry.hostUsername).toBe("alice");
+    expect(entry.connectedAt).toBeGreaterThan(0);
+    expect(entry.lastActiveAt).toBeGreaterThanOrEqual(entry.connectedAt);
+  });
+
+  test("register derives empty capabilities for web interface", () => {
+    const registry = new ClientRegistry();
+    const entry = registry.register({
+      clientId: "web-1",
+      interfaceId: "cli",
+    });
+
+    expect(entry.capabilities).toEqual([]);
+  });
+
+  test("register derives host_browser capability for chrome-extension", () => {
+    const registry = new ClientRegistry();
+    const entry = registry.register({
+      clientId: "ext-1",
+      interfaceId: "chrome-extension",
+    });
+
+    expect(entry.capabilities).toEqual(["host_browser"]);
+  });
+
+  test("register refreshes lastActiveAt on re-register with same clientId", () => {
+    const registry = new ClientRegistry();
+    const first = registry.register({
+      clientId: "mac-1",
+      interfaceId: "macos",
+    });
+    const firstActive = first.lastActiveAt;
+
+    // Advance time slightly
+    const second = registry.register({
+      clientId: "mac-1",
+      interfaceId: "macos",
+      hostHomeDir: "/Users/bob",
+    });
+
+    // Same object reference — refreshed in place
+    expect(second).toBe(first);
+    expect(second.lastActiveAt).toBeGreaterThanOrEqual(firstActive);
+    expect(second.hostHomeDir).toBe("/Users/bob");
+    // connectedAt should NOT change on refresh
+    expect(second.connectedAt).toBe(first.connectedAt);
+  });
+
+  test("register does not increase size on re-register", () => {
+    const registry = new ClientRegistry();
+    registry.register({ clientId: "mac-1", interfaceId: "macos" });
+    registry.register({ clientId: "mac-1", interfaceId: "macos" });
+    expect(registry.size).toBe(1);
+  });
+
+  // ── unregister ────────────────────────────────────────────────────────────
+
+  test("unregister removes the entry", () => {
+    const registry = new ClientRegistry();
+    registry.register({ clientId: "mac-1", interfaceId: "macos" });
+    expect(registry.size).toBe(1);
+
+    registry.unregister("mac-1");
+    expect(registry.size).toBe(0);
+    expect(registry.get("mac-1")).toBeUndefined();
+  });
+
+  test("unregister is a no-op for unknown clientId", () => {
+    const registry = new ClientRegistry();
+    registry.register({ clientId: "mac-1", interfaceId: "macos" });
+    registry.unregister("unknown");
+    expect(registry.size).toBe(1);
+  });
+
+  // ── touch ─────────────────────────────────────────────────────────────────
+
+  test("touch updates lastActiveAt", () => {
+    const registry = new ClientRegistry();
+    const entry = registry.register({
+      clientId: "mac-1",
+      interfaceId: "macos",
+    });
+    const before = entry.lastActiveAt;
+    registry.touch("mac-1");
+    expect(entry.lastActiveAt).toBeGreaterThanOrEqual(before);
+  });
+
+  test("touch is a no-op for unknown clientId", () => {
+    const registry = new ClientRegistry();
+    // Should not throw
+    registry.touch("unknown");
+  });
+
+  // ── get ───────────────────────────────────────────────────────────────────
+
+  test("get returns the entry for a registered clientId", () => {
+    const registry = new ClientRegistry();
+    const entry = registry.register({
+      clientId: "mac-1",
+      interfaceId: "macos",
+    });
+    expect(registry.get("mac-1")).toBe(entry);
+  });
+
+  test("get returns undefined for unknown clientId", () => {
+    const registry = new ClientRegistry();
+    expect(registry.get("unknown")).toBeUndefined();
+  });
+
+  // ── listAll ───────────────────────────────────────────────────────────────
+
+  test("listAll returns entries sorted by lastActiveAt descending", () => {
+    const registry = new ClientRegistry();
+    registry.register({ clientId: "old", interfaceId: "cli" });
+    // Touch the second one to make it most recent
+    registry.register({ clientId: "new", interfaceId: "macos" });
+
+    const all = registry.listAll();
+    expect(all.length).toBe(2);
+    expect(all[0].lastActiveAt).toBeGreaterThanOrEqual(all[1].lastActiveAt);
+  });
+
+  test("listAll returns empty array when no clients registered", () => {
+    const registry = new ClientRegistry();
+    expect(registry.listAll()).toEqual([]);
+  });
+
+  // ── listByCapability ──────────────────────────────────────────────────────
+
+  test("listByCapability filters to clients with matching capability", () => {
+    const registry = new ClientRegistry();
+    registry.register({ clientId: "mac-1", interfaceId: "macos" });
+    registry.register({ clientId: "web-1", interfaceId: "cli" });
+    registry.register({ clientId: "ext-1", interfaceId: "chrome-extension" });
+
+    const bashCapable = registry.listByCapability("host_bash");
+    expect(bashCapable.length).toBe(1);
+    expect(bashCapable[0].clientId).toBe("mac-1");
+
+    const browserCapable = registry.listByCapability("host_browser");
+    expect(browserCapable.length).toBe(2);
+    // macOS now supports host_browser too
+    const ids = browserCapable.map((e) => e.clientId).sort();
+    expect(ids).toEqual(["ext-1", "mac-1"]);
+  });
+
+  test("listByCapability returns empty when no clients match", () => {
+    const registry = new ClientRegistry();
+    registry.register({ clientId: "web-1", interfaceId: "cli" });
+    expect(registry.listByCapability("host_bash")).toEqual([]);
+  });
+
+  // ── getMostRecentByCapability ─────────────────────────────────────────────
+
+  test("getMostRecentByCapability returns the most recently active client", () => {
+    const registry = new ClientRegistry();
+    const mac1 = registry.register({ clientId: "mac-1", interfaceId: "macos" });
+    const mac2 = registry.register({ clientId: "mac-2", interfaceId: "macos" });
+
+    // Ensure deterministic ordering — both may register within the same ms
+    mac1.lastActiveAt = Date.now() - 5000;
+    mac2.lastActiveAt = Date.now();
+
+    const best = registry.getMostRecentByCapability("host_bash");
+    expect(best).toBeDefined();
+    expect(best!.clientId).toBe("mac-2");
+  });
+
+  test("getMostRecentByCapability returns undefined when no clients match", () => {
+    const registry = new ClientRegistry();
+    registry.register({ clientId: "web-1", interfaceId: "cli" });
+    expect(registry.getMostRecentByCapability("host_bash")).toBeUndefined();
+  });
+
+  // ── toJSON ────────────────────────────────────────────────────────────────
+
+  test("toJSON serializes with ISO timestamps", () => {
+    const registry = new ClientRegistry();
+    const entry = registry.register({
+      clientId: "mac-1",
+      interfaceId: "macos",
+      hostHomeDir: "/Users/alice",
+      hostUsername: "alice",
+    });
+
+    const json = ClientRegistry.toJSON(entry);
+    expect(json.clientId).toBe("mac-1");
+    expect(json.interfaceId).toBe("macos");
+    expect(json.capabilities).toContain("host_bash");
+    expect(json.connectedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+    expect(json.lastActiveAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+    expect(json.hostHomeDir).toBe("/Users/alice");
+    expect(json.hostUsername).toBe("alice");
+  });
+
+  test("toJSON omits host fields when not present", () => {
+    const registry = new ClientRegistry();
+    const entry = registry.register({
+      clientId: "web-1",
+      interfaceId: "cli",
+    });
+
+    const json = ClientRegistry.toJSON(entry);
+    expect(json.hostHomeDir).toBeUndefined();
+    expect(json.hostUsername).toBeUndefined();
+  });
+
+  // ── evictStale ─────────────────────────────────────────────────────────────
+
+  test("evictStale removes entries older than maxAgeMs", () => {
+    const registry = new ClientRegistry();
+    const entry = registry.register({
+      clientId: "old-mac",
+      interfaceId: "macos",
+    });
+    // Backdate lastActiveAt by 1 hour
+    entry.lastActiveAt = Date.now() - 60 * 60 * 1000;
+
+    const evicted = registry.evictStale(30 * 60 * 1000); // 30 min threshold
+    expect(evicted).toBe(1);
+    expect(registry.size).toBe(0);
+  });
+
+  test("evictStale keeps fresh entries", () => {
+    const registry = new ClientRegistry();
+    registry.register({ clientId: "fresh", interfaceId: "macos" });
+
+    const evicted = registry.evictStale(30 * 60 * 1000);
+    expect(evicted).toBe(0);
+    expect(registry.size).toBe(1);
+  });
+
+  test("listAll triggers lazy eviction", () => {
+    const registry = new ClientRegistry();
+    const entry = registry.register({
+      clientId: "stale-cli",
+      interfaceId: "cli",
+    });
+    entry.lastActiveAt = Date.now() - 60 * 60 * 1000;
+
+    registry.register({ clientId: "fresh-mac", interfaceId: "macos" });
+
+    const all = registry.listAll();
+    expect(all.length).toBe(1);
+    expect(all[0].clientId).toBe("fresh-mac");
+  });
+
+  // ── singleton ─────────────────────────────────────────────────────────────
+
+  test("getClientRegistry returns a singleton", () => {
+    const a = getClientRegistry();
+    const b = getClientRegistry();
+    expect(a).toBe(b);
+  });
+
+  test("__resetClientRegistryForTests clears the singleton", () => {
+    const a = getClientRegistry();
+    __resetClientRegistryForTests();
+    const b = getClientRegistry();
+    expect(a).not.toBe(b);
+  });
+});

package/src/runtime/client-registry.ts

@@ -0,0 +1,261 @@
+/**
+ * Unified registry of active client connections.
+ *
+ * Tracks all clients currently connected to the assistant — macOS desktop
+ * (SSE), iOS (SSE), web (SSE), chrome-extension (WebSocket), CLI, and
+ * channel interfaces. Each entry records the interface type, derived
+ * capabilities, connection timestamps, and optional host environment fields.
+ *
+ * The registry is populated by:
+ *   - `handleSendMessage` in conversation-routes.ts (registers/refreshes on
+ *     every inbound message with the interface and transport metadata)
+ *
+ * Future enhancements:
+ *   - Deregister on SSE disconnect (events-routes.ts abort signal)
+ *   - Surface ChromeExtensionRegistry entries through `listAll()`
+ *   - Stale-client eviction sweep
+ *
+ * Consumers:
+ *   - `assistant clients list` CLI command (via `list_clients` IPC route)
+ *   - Future: deferred host tool routing (Phase 2)
+ */
+
+import type { HostProxyCapability, InterfaceId } from "../channels/types.js";
+import { supportsHostProxy } from "../channels/types.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("client-registry");
+
+/**
+ * Default staleness threshold: entries not refreshed within this window are
+ * evicted on the next read. 30 minutes is generous — messages refresh the
+ * entry on every turn, so any actively used client stays well within this.
+ */
+const DEFAULT_STALE_AGE_MS = 30 * 60 * 1000;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** All host-proxy capabilities checked against each interface on register. */
+const ALL_CAPABILITIES: HostProxyCapability[] = [
+  "host_bash",
+  "host_file",
+  "host_cu",
+  "host_browser",
+];
+
+export interface ClientEntry {
+  /** Stable identifier for this client connection. */
+  clientId: string;
+  /** Interface type (e.g. "macos", "ios", "web", "chrome-extension"). */
+  interfaceId: InterfaceId;
+  /** Host-proxy capabilities this client supports. */
+  capabilities: HostProxyCapability[];
+  /** Wall-clock timestamp (ms) when the client first connected. */
+  connectedAt: number;
+  /** Wall-clock timestamp (ms) of the most recent activity. */
+  lastActiveAt: number;
+  /** Home directory on the host machine (only for host-proxy interfaces). */
+  hostHomeDir?: string;
+  /** Username on the host machine (only for host-proxy interfaces). */
+  hostUsername?: string;
+}
+
+/** Serialized form returned by the IPC route / CLI command. */
+export interface ClientEntryJSON {
+  clientId: string;
+  interfaceId: InterfaceId;
+  capabilities: HostProxyCapability[];
+  connectedAt: string;
+  lastActiveAt: string;
+  hostHomeDir?: string;
+  hostUsername?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+export class ClientRegistry {
+  private clients = new Map<string, ClientEntry>();
+
+  /**
+   * Register or refresh a client connection.
+   *
+   * If a client with the same `clientId` already exists, its `lastActiveAt`
+   * and host environment fields are updated. Otherwise a new entry is created.
+   */
+  register(opts: {
+    clientId: string;
+    interfaceId: InterfaceId;
+    hostHomeDir?: string;
+    hostUsername?: string;
+  }): ClientEntry {
+    const existing = this.clients.get(opts.clientId);
+    const now = Date.now();
+
+    if (existing) {
+      existing.lastActiveAt = now;
+      if (opts.hostHomeDir !== undefined) {
+        existing.hostHomeDir = opts.hostHomeDir;
+      }
+      if (opts.hostUsername !== undefined) {
+        existing.hostUsername = opts.hostUsername;
+      }
+      log.debug(
+        { clientId: opts.clientId, interfaceId: opts.interfaceId },
+        "client refreshed",
+      );
+      return existing;
+    }
+
+    const capabilities = ALL_CAPABILITIES.filter((cap) =>
+      supportsHostProxy(opts.interfaceId, cap),
+    );
+
+    const entry: ClientEntry = {
+      clientId: opts.clientId,
+      interfaceId: opts.interfaceId,
+      capabilities,
+      connectedAt: now,
+      lastActiveAt: now,
+      hostHomeDir: opts.hostHomeDir,
+      hostUsername: opts.hostUsername,
+    };
+
+    this.clients.set(opts.clientId, entry);
+    log.info(
+      {
+        clientId: opts.clientId,
+        interfaceId: opts.interfaceId,
+        capabilities,
+      },
+      "client registered",
+    );
+    return entry;
+  }
+
+  /**
+   * Remove a client connection. No-op if the clientId is not registered.
+   */
+  unregister(clientId: string): void {
+    const entry = this.clients.get(clientId);
+    if (!entry) return;
+    this.clients.delete(clientId);
+    log.info(
+      { clientId, interfaceId: entry.interfaceId },
+      "client unregistered",
+    );
+  }
+
+  /**
+   * Update `lastActiveAt` for a client without changing other fields.
+   * No-op if the clientId is not registered.
+   */
+  touch(clientId: string): void {
+    const entry = this.clients.get(clientId);
+    if (entry) {
+      entry.lastActiveAt = Date.now();
+    }
+  }
+
+  /**
+   * Return a specific client entry, or `undefined` if not registered.
+   */
+  get(clientId: string): ClientEntry | undefined {
+    return this.clients.get(clientId);
+  }
+
+  /**
+   * Return all registered clients, sorted by `lastActiveAt` descending
+   * (most recently active first). Lazily evicts stale entries before
+   * returning so disconnected clients don't linger indefinitely.
+   */
+  listAll(): ClientEntry[] {
+    this.evictStale();
+    return Array.from(this.clients.values()).sort(
+      (a, b) => b.lastActiveAt - a.lastActiveAt,
+    );
+  }
+
+  /**
+   * Return all registered clients that support the given capability,
+   * sorted by `lastActiveAt` descending.
+   */
+  listByCapability(capability: HostProxyCapability): ClientEntry[] {
+    return this.listAll().filter((e) => e.capabilities.includes(capability));
+  }
+
+  /**
+   * Return the most recently active client that supports the given
+   * capability, or `undefined` if none exists.
+   */
+  getMostRecentByCapability(
+    capability: HostProxyCapability,
+  ): ClientEntry | undefined {
+    return this.listByCapability(capability)[0];
+  }
+
+  /**
+   * Remove entries whose `lastActiveAt` is older than `maxAgeMs`.
+   * Called lazily before reads to prevent unbounded map growth from
+   * churning client IDs that are never explicitly unregistered.
+   *
+   * @returns Number of evicted entries.
+   */
+  evictStale(maxAgeMs: number = DEFAULT_STALE_AGE_MS): number {
+    const cutoff = Date.now() - maxAgeMs;
+    let evicted = 0;
+    for (const [id, entry] of this.clients) {
+      if (entry.lastActiveAt < cutoff) {
+        this.clients.delete(id);
+        evicted++;
+        log.debug(
+          { clientId: id, interfaceId: entry.interfaceId },
+          "client evicted (stale)",
+        );
+      }
+    }
+    return evicted;
+  }
+
+  /**
+   * Number of currently registered clients.
+   */
+  get size(): number {
+    return this.clients.size;
+  }
+
+  /**
+   * Serialize a client entry to JSON (ISO timestamps).
+   */
+  static toJSON(entry: ClientEntry): ClientEntryJSON {
+    return {
+      clientId: entry.clientId,
+      interfaceId: entry.interfaceId,
+      capabilities: entry.capabilities,
+      connectedAt: new Date(entry.connectedAt).toISOString(),
+      lastActiveAt: new Date(entry.lastActiveAt).toISOString(),
+      ...(entry.hostHomeDir ? { hostHomeDir: entry.hostHomeDir } : {}),
+      ...(entry.hostUsername ? { hostUsername: entry.hostUsername } : {}),
+    };
+  }
+}
+
+// ── Module-level singleton ────────────────────────────────────────────────
+
+let instance: ClientRegistry | null = null;
+
+export function getClientRegistry(): ClientRegistry {
+  if (!instance) instance = new ClientRegistry();
+  return instance;
+}
+
+/**
+ * Test helper: reset the module-level singleton so each test starts with a
+ * fresh registry.
+ */
+export function __resetClientRegistryForTests(): void {
+  instance = null;
+}