@hypabolic/crossbar 0.1.0

package/src/discovery/engine.ts

@@ -0,0 +1,247 @@
+/**
+ * Crossbar discovery engine.
+ *
+ * Sweeps a set of origins (host × port) with each non-cloud adapter's `fingerprint()`, picks the
+ * highest-confidence match per origin, and returns the deduplicated list of discovered servers.
+ *
+ * Design decisions:
+ *  - Bounded concurrency (default 8 parallel probes) to avoid overwhelming localhost or LAN.
+ *  - Cloud adapters (openai, anthropic) are skipped — they are configured, not probed.
+ *  - Tie-break: when two adapters return equal confidence, prefer the more specific one over
+ *    "openai-generic" (the catch-all fallback).
+ *  - Dedupe by normalised origin string (protocol + host + port, lower-cased, no trailing slash).
+ *  - `discoverLan` is an opt-in variant that accepts an explicit host list; no mDNS.
+ */
+
+import { CLOUD_KINDS } from "../core/capability.ts";
+import type { BackendAdapter } from "../core/backend-adapter.ts";
+import type { DiscoveredServer, Probe } from "../core/types.ts";
+import { createProbe } from "./probe.ts";
+
+/** Default localhost ports probed in order (from CAPABILITY-MATRIX.md). */
+export const DEFAULT_PROBE_PORTS: readonly number[] = [
+  11434, // Ollama
+  1234,  // LM Studio
+  8080,  // llama-server / llama-swap / llamafile
+  8000,  // vLLM
+  5000,  // TabbyAPI / oobabooga
+  5001,  // KoboldCpp
+  1337,  // Jan
+];
+
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_TIMEOUT_MS = 600;
+const DEFAULT_CONCURRENCY = 8;
+
+// ────────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ────────────────────────────────────────────────────────────────────────────────
+
+/** Normalise an origin to a consistent, dedupe-safe string. */
+function normalizeOrigin(protocol: string, host: string, port: number): string {
+  return `${protocol}//${host}:${port}`;
+}
+
+/**
+ * Run at most `concurrency` tasks at a time from an iterable of async thunks, collecting results.
+ * Rejected tasks are silently dropped (individual probe errors are already caught inside `probe`).
+ */
+async function runBounded<T>(
+  tasks: Array<() => Promise<T | null>>,
+  concurrency: number,
+): Promise<Array<T>> {
+  const results: Array<T> = [];
+  const queue = tasks.slice();
+
+  async function worker(): Promise<void> {
+    while (queue.length > 0) {
+      const task = queue.shift();
+      if (!task) break;
+      try {
+        const result = await task();
+        if (result !== null && result !== undefined) {
+          results.push(result);
+        }
+      } catch {
+        // Swallow; probe errors are already normalised to status:0 inside createProbe
+      }
+    }
+  }
+
+  const workers = Array.from({ length: Math.min(concurrency, tasks.length) }, () => worker());
+  await Promise.all(workers);
+  return results;
+}
+
+/**
+ * Given all fingerprint results for a single origin, select the best candidate:
+ *  1. Highest confidence wins.
+ *  2. Among equal-confidence candidates, prefer a specific adapter over "openai-generic".
+ */
+function selectBest(candidates: DiscoveredServer[]): DiscoveredServer | null {
+  if (candidates.length === 0) return null;
+
+  return candidates.reduce<DiscoveredServer>((best, candidate) => {
+    if (candidate.confidence > best.confidence) return candidate;
+    if (candidate.confidence === best.confidence) {
+      // Tie-break: demote openai-generic; keep the more specific one
+      if (best.kind === "openai-generic" && candidate.kind !== "openai-generic") {
+        return candidate;
+      }
+    }
+    return best;
+  }, candidates[0]!);
+}
+
+/** Builds the Probe used for one origin. Overridable for tests (default: real network probe). */
+export type ProbeFactory = (origin: string, timeoutMs: number) => Probe;
+
+/**
+ * Probe a single origin against every eligible adapter, return the best match or null.
+ * Exported so integration tests can exercise the real selection logic with a fake probe.
+ */
+export async function probeOrigin(
+  origin: string,
+  adapters: BackendAdapter[],
+  timeoutMs: number,
+  probeFactory?: ProbeFactory,
+): Promise<DiscoveredServer | null> {
+  const probe = probeFactory
+    ? probeFactory(origin, timeoutMs)
+    : createProbe(origin, { defaultTimeoutMs: timeoutMs });
+
+  // Run all adapter fingerprints concurrently for this single origin
+  const fingerprintResults = await Promise.all(
+    adapters.map(async (adapter): Promise<DiscoveredServer | null> => {
+      try {
+        return await adapter.fingerprint(origin, probe);
+      } catch {
+        return null;
+      }
+    }),
+  );
+
+  const candidates = fingerprintResults.filter((r): r is DiscoveredServer => r !== null);
+  return selectBest(candidates);
+}
+
+// ────────────────────────────────────────────────────────────────────────────────
+// Public API
+// ────────────────────────────────────────────────────────────────────────────────
+
+export interface DiscoverLocalhostOptions {
+  /** Override the default probe ports. */
+  ports?: number[];
+  /** Override the default host (127.0.0.1). */
+  host?: string;
+  /** Per-probe timeout in ms (default 600). */
+  timeoutMs?: number;
+  /** Abort signal to cancel a sweep in progress. */
+  signal?: AbortSignal;
+  /** Override how the per-origin Probe is built (tests inject a fake probe here). */
+  probeFactory?: ProbeFactory;
+}
+
+/**
+ * Sweep localhost (or a custom host) on the given ports, fingerprint each live origin, and return
+ * the deduplicated list of discovered servers — one per origin, highest-confidence adapter wins.
+ *
+ * Non-cloud adapters only; cloud adapters (openai, anthropic) are skipped — they are configured
+ * via Pi's own `/login`, not discovered by port sweeping.
+ */
+export async function discoverLocalhost(
+  adapters: BackendAdapter[],
+  opts?: DiscoverLocalhostOptions,
+): Promise<DiscoveredServer[]> {
+  const ports = opts?.ports ?? DEFAULT_PROBE_PORTS;
+  const host = opts?.host ?? DEFAULT_HOST;
+  const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const signal = opts?.signal;
+
+  // Filter to non-cloud adapters only
+  const localAdapters = adapters.filter((a) => !CLOUD_KINDS.has(a.kind));
+  if (localAdapters.length === 0) return [];
+
+  const origins = ports.map((port) => normalizeOrigin("http:", host, port));
+
+  // Build per-origin tasks for bounded concurrency
+  const tasks = origins.map((origin) => async (): Promise<DiscoveredServer | null> => {
+    if (signal?.aborted) return null;
+    return probeOrigin(origin, localAdapters, timeoutMs, opts?.probeFactory);
+  });
+
+  const allMatches = await runBounded(tasks, DEFAULT_CONCURRENCY);
+
+  // Dedupe by normalised origin (the fingerprint may produce the same baseUrl from different paths)
+  const seen = new Set<string>();
+  const deduplicated: DiscoveredServer[] = [];
+  for (const server of allMatches) {
+    const key = server.baseUrl.toLowerCase().replace(/\/+$/, "");
+    if (!seen.has(key)) {
+      seen.add(key);
+      deduplicated.push(server);
+    }
+  }
+
+  return deduplicated;
+}
+
+export interface DiscoverLanOptions {
+  /** Per-probe timeout in ms (default 600). */
+  timeoutMs?: number;
+  /** Ports to probe on each host (defaults to DEFAULT_PROBE_PORTS). */
+  ports?: number[];
+  /** Abort signal to cancel a sweep in progress. */
+  signal?: AbortSignal;
+  /** Override how the per-origin Probe is built (tests inject a fake probe here). */
+  probeFactory?: ProbeFactory;
+}
+
+/**
+ * Opt-in LAN discovery. Probes an explicit list of hosts × ports — no mDNS, just active TCP
+ * connect attempts. Call only when `CrossbarSettings.lanDiscovery` is true and the user has
+ * supplied host ranges or an explicit list.
+ *
+ * Follows the same fingerprinting and deduplication logic as `discoverLocalhost`.
+ */
+export async function discoverLan(
+  adapters: BackendAdapter[],
+  hosts: string[],
+  opts?: DiscoverLanOptions,
+): Promise<DiscoveredServer[]> {
+  if (hosts.length === 0) return [];
+
+  const ports = opts?.ports ?? DEFAULT_PROBE_PORTS;
+  const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const signal = opts?.signal;
+
+  const localAdapters = adapters.filter((a) => !CLOUD_KINDS.has(a.kind));
+  if (localAdapters.length === 0) return [];
+
+  // Enumerate host × port origins
+  const origins: string[] = [];
+  for (const host of hosts) {
+    for (const port of ports) {
+      origins.push(normalizeOrigin("http:", host, port));
+    }
+  }
+
+  const tasks = origins.map((origin) => async (): Promise<DiscoveredServer | null> => {
+    if (signal?.aborted) return null;
+    return probeOrigin(origin, localAdapters, timeoutMs, opts?.probeFactory);
+  });
+
+  const allMatches = await runBounded(tasks, DEFAULT_CONCURRENCY);
+
+  const seen = new Set<string>();
+  const deduplicated: DiscoveredServer[] = [];
+  for (const server of allMatches) {
+    const key = server.baseUrl.toLowerCase().replace(/\/+$/, "");
+    if (!seen.has(key)) {
+      seen.add(key);
+      deduplicated.push(server);
+    }
+  }
+
+  return deduplicated;
+}

package/src/discovery/probe.ts

@@ -0,0 +1,144 @@
+/**
+ * Real `Probe` factory for the Crossbar discovery engine.
+ *
+ * Wraps Node's global `fetch` with:
+ *  - URL resolution of `path` against `baseUrl`
+ *  - `Authorization: Bearer <key>` injection when `auth.mode === "apiKey"` (key never logged)
+ *  - Per-request timeout via AbortController (default 600 ms)
+ *  - Lossless error capture: refused / DNS / timeout → `{ status: 0, ok: false, error: "..." }`
+ *  - Response body read into `text` + best-effort `json`
+ *  - Lowercased `headers` map
+ *  - `latencyMs` measurement
+ *
+ * No network I/O outside the returned `Probe` function; the factory itself is pure.
+ */
+
+import type { Probe, ProbeInit, ProbeResult, ServerCredential } from "../core/types.ts";
+
+export const DEFAULT_DISCOVERY_TIMEOUT_MS = 600;
+
+export interface CreateProbeOptions {
+  auth?: ServerCredential;
+  defaultTimeoutMs?: number;
+}
+
+/**
+ * Build a `Probe` bound to `baseUrl`.
+ *
+ * @param baseUrl - Normalized server origin (no trailing slash).  `path` values starting with `/`
+ *                  are resolved against this origin; otherwise they are treated as relative paths.
+ * @param opts    - Optional auth credential and per-probe timeout override.
+ */
+export function createProbe(baseUrl: string, opts?: CreateProbeOptions): Probe {
+  const defaultTimeout = opts?.defaultTimeoutMs ?? DEFAULT_DISCOVERY_TIMEOUT_MS;
+  const auth = opts?.auth;
+
+  return async function probe(path: string, init?: ProbeInit): Promise<ProbeResult> {
+    // ── URL resolution ──────────────────────────────────────────────────────────
+    // Normalise baseUrl to have no trailing slash, then join with the path.
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = path.startsWith("http://") || path.startsWith("https://")
+      ? path
+      : `${base}${path.startsWith("/") ? path : `/${path}`}`;
+
+    // ── Request headers ─────────────────────────────────────────────────────────
+    const requestHeaders: Record<string, string> = {};
+
+    // Inject auth header when configured — key is never exposed in logs or results
+    if (auth?.mode === "apiKey" && auth.apiKey) {
+      requestHeaders["authorization"] = `Bearer ${auth.apiKey}`;
+    }
+
+    // Merge caller-supplied headers (allow override of everything except the auth key value,
+    // so callers can set content-type etc.)
+    if (init?.headers) {
+      for (const [k, v] of Object.entries(init.headers)) {
+        // Never let a caller accidentally expose the raw key by overriding authorization with it
+        requestHeaders[k.toLowerCase()] = v;
+      }
+    }
+
+    // ── Timeout ─────────────────────────────────────────────────────────────────
+    const timeoutMs = init?.timeoutMs ?? defaultTimeout;
+    const controller = new AbortController();
+    const timerId = setTimeout(() => controller.abort(), timeoutMs);
+
+    const startMs = Date.now();
+
+    try {
+      const fetchInit: RequestInit = {
+        method: init?.method ?? "GET",
+        headers: requestHeaders,
+        signal: controller.signal,
+      };
+      // Only set body when defined — exactOptionalPropertyTypes forbids undefined for BodyInit
+      if (init?.body !== undefined) {
+        fetchInit.body = init.body;
+      }
+
+      const response = await fetch(url, fetchInit);
+
+      const latencyMs = Date.now() - startMs;
+
+      // ── Collect response headers (lowercase keys) ────────────────────────────
+      const responseHeaders: Record<string, string> = {};
+      response.headers.forEach((value, key) => {
+        responseHeaders[key.toLowerCase()] = value;
+      });
+
+      // ── Read body ────────────────────────────────────────────────────────────
+      let text: string | undefined;
+      let json: unknown;
+
+      try {
+        text = await response.text();
+      } catch {
+        // Body read failure is non-fatal; leave text undefined
+      }
+
+      if (text !== undefined) {
+        try {
+          json = JSON.parse(text);
+        } catch {
+          // Not JSON; leave json undefined
+        }
+      }
+
+      const result: ProbeResult = {
+        status: response.status,
+        ok: response.ok,
+        headers: responseHeaders,
+        latencyMs,
+      };
+      // exactOptionalPropertyTypes: only set optional fields when they have a value
+      if (text !== undefined) result.text = text;
+      if (json !== undefined) result.json = json;
+      return result;
+    } catch (err: unknown) {
+      const latencyMs = Date.now() - startMs;
+
+      // Classify the failure — never include the api key in the error message
+      let errorMessage: string;
+      if (err instanceof Error) {
+        if (err.name === "AbortError") {
+          errorMessage = `Request timed out after ${timeoutMs}ms`;
+        } else {
+          // Scrub potential URL fragments that might contain keys; keep the message generic
+          errorMessage = err.message.replace(/authorization=[^\s&]*/gi, "authorization=[redacted]");
+        }
+      } else {
+        errorMessage = "Unknown fetch error";
+      }
+
+      return {
+        status: 0,
+        ok: false,
+        headers: {},
+        error: errorMessage,
+        latencyMs,
+      };
+    } finally {
+      clearTimeout(timerId);
+    }
+  };
+}

package/src/index.ts

@@ -0,0 +1,158 @@
+/**
+ * @hypabolic/crossbar — Pi extension entry point.
+ *
+ * Wires the frozen core + Wave A/B/C modules into Pi's lifecycle:
+ *   session_start  → load crossbar.json, register saved servers, auto-discover localhost,
+ *                    install the loaded-model widget, start the health poll.
+ *   /crossbar      → open the discovery / onboarding overlay (alias /local).
+ *   session_shutdown → stop the poll, dispose the widget.
+ *
+ * Secrets live only in Pi's auth.json (via the CredentialStore bridge); crossbar.json holds metadata.
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+
+import type { DiscoveredServer, ModelDescriptor, ServerRecord } from "./core/index.ts";
+import { adapterFor, DISCOVERY_ADAPTERS } from "./adapters/index.ts";
+import { discoverLocalhost } from "./discovery/engine.ts";
+import { createProbe } from "./discovery/probe.ts";
+import { loadConfig, saveConfig } from "./registry/persistence.ts";
+import { createPiCredentialStore } from "./registry/pi-credential-store.ts";
+import { serverId } from "./registry/ids.ts";
+import { ServerRegistry } from "./registry/registry.ts";
+import { registerServer } from "./shim/provider-shim.ts";
+import { openOnboarding } from "./ui/onboarding.ts";
+import { installLoadedWidget, type LoadedWidgetHandle } from "./ui/loaded-widget.ts";
+
+const HEALTH_POLL_MS = 15_000;
+
+/** Minimal DiscoveredServer reconstructed from a persisted record for adapter calls. */
+function recordToServer(record: ServerRecord): DiscoveredServer {
+  return {
+    kind: record.kind,
+    baseUrl: record.baseUrl,
+    auth: record.auth,
+    label: record.label,
+    confidence: 1,
+  };
+}
+
+export default function crossbar(pi: ExtensionAPI): void {
+  let registry: ServerRegistry | undefined;
+  let widget: LoadedWidgetHandle | undefined;
+  let pollTimer: ReturnType<typeof setInterval> | undefined;
+
+  const discover = (): Promise<DiscoveredServer[]> => discoverLocalhost([...DISCOVERY_ADAPTERS]);
+
+  /** Best-effort: refresh a server's model list and (re)register it with Pi. Returns models used. */
+  async function refreshAndRegister(reg: ServerRegistry, record: ServerRecord): Promise<number> {
+    const adapter = adapterFor(record.kind);
+    const cred = await reg.resolveCredential(record);
+    let models: ModelDescriptor[] = record.lastKnownModels ?? [];
+    try {
+      const probe = createProbe(record.baseUrl, { auth: cred });
+      models = await adapter.listModels(recordToServer(record), cred, probe);
+      reg.updateHealthCache(record.id, { models, lastSeenAt: Date.now() });
+    } catch {
+      // Offline / unreachable — fall back to last-known models (may be empty).
+    }
+    if (models.length === 0) return 0; // nothing registrable (server offline, no cache)
+    await registerServer(pi, reg, record, models);
+    return models.length;
+  }
+
+  pi.on("session_start", async (_event, ctx: ExtensionContext) => {
+    // Rebuild cleanly on every start/reload.
+    if (pollTimer) {
+      clearInterval(pollTimer);
+      pollTimer = undefined;
+    }
+
+    const store = createPiCredentialStore(ctx.modelRegistry.authStorage);
+    const reg = new ServerRegistry({ store, persist: (cfg) => saveConfig(cfg) });
+    reg.load(await loadConfig());
+    registry = reg;
+
+    // 1) Register every enabled server from the saved config.
+    for (const record of reg.list()) {
+      if (!record.enabled) continue;
+      try {
+        await refreshAndRegister(reg, record);
+      } catch {
+        // Never let one bad server abort startup.
+      }
+    }
+
+    // 2) Auto-discover localhost; auto-register reachable no-auth servers, prompt for keyed ones.
+    try {
+      const found = await discover();
+      for (const srv of found) {
+        const id = serverId(srv.kind, srv.baseUrl);
+        if (reg.get(id)) continue; // already known
+        if (srv.auth !== "none") {
+          if (ctx.hasUI) {
+            ctx.ui.notify(`Crossbar: found ${srv.label} (needs an API key) — run /crossbar to add it.`, "info");
+          }
+          continue;
+        }
+        const record: ServerRecord = {
+          id,
+          kind: srv.kind,
+          baseUrl: srv.baseUrl,
+          label: srv.label,
+          auth: "none",
+          enabled: true,
+          addedAt: Date.now(),
+          lastSeenAt: Date.now(),
+        };
+        await reg.add(record);
+        const count = await refreshAndRegister(reg, record);
+        if (ctx.hasUI && count > 0) {
+          ctx.ui.notify(`Crossbar: registered ${srv.label} (${count} models).`, "info");
+        }
+      }
+    } catch {
+      // Discovery is best-effort; the user can always add servers via /crossbar.
+    }
+
+    // 3) Loaded-model widget + health poll (UI modes only).
+    if (ctx.hasUI) {
+      widget = installLoadedWidget(pi, ctx, reg);
+      await widget.refresh();
+      pollTimer = setInterval(() => {
+        void widget?.refresh();
+      }, HEALTH_POLL_MS);
+    }
+  });
+
+  pi.on("session_shutdown", async () => {
+    if (pollTimer) {
+      clearInterval(pollTimer);
+      pollTimer = undefined;
+    }
+    widget?.dispose();
+    widget = undefined;
+  });
+
+  const openCmd = async (_args: string, ctx: ExtensionCommandContext): Promise<void> => {
+    if (!registry) {
+      ctx.ui.notify("Crossbar is still initialising — try again in a moment.", "warning");
+      return;
+    }
+    await openOnboarding(pi, ctx, { registry, discover });
+    await widget?.refresh();
+  };
+
+  pi.registerCommand("crossbar", {
+    description: "Manage local & self-hosted model backends — discover, add, switch (Crossbar)",
+    handler: openCmd,
+  });
+  pi.registerCommand("local", {
+    description: "Alias for /crossbar",
+    handler: openCmd,
+  });
+}

package/src/registry/ids.ts

@@ -0,0 +1,68 @@
+/**
+ * Stable, deterministic server ID generation.
+ *
+ * IDs are derived from kind + host + port so the same physical server always gets the same id
+ * across restarts. The id is also used as the Pi provider name and as the auth.json key.
+ */
+
+import { CLOUD_KINDS } from "../core/capability.ts";
+import type { BackendKind } from "../core/capability.ts";
+
+/**
+ * Sanitize a URL component to be safe for use in an id string.
+ * Replaces any character that isn't alphanumeric with a hyphen, collapses runs.
+ */
+function sanitize(s: string): string {
+  return s.replace(/[^a-z0-9]+/gi, "-").replace(/^-+|-+$/g, "").toLowerCase();
+}
+
+/**
+ * Generate a stable id for a server of the given kind at the given base URL.
+ *
+ * Cloud kinds (openai, anthropic) have no meaningful host/port variation:
+ *   → `crossbar-openai`, `crossbar-anthropic`
+ *
+ * Local kinds embed the host and port:
+ *   → `crossbar-ollama-127-0-0-1-11434`
+ *
+ * The id is fully deterministic: same kind + baseUrl → same id every time.
+ */
+export function serverId(kind: BackendKind, baseUrl: string): string {
+  if (CLOUD_KINDS.has(kind)) {
+    return `crossbar-${kind}`;
+  }
+
+  let host: string;
+  let port: string;
+  try {
+    const u = new URL(baseUrl);
+    host = u.hostname;
+    port = u.port || defaultPortForProtocol(u.protocol);
+  } catch {
+    // Fallback: sanitize the raw string
+    return `crossbar-${kind}-${sanitize(baseUrl)}`;
+  }
+
+  const hostPart = sanitize(host);
+  const portPart = sanitize(port);
+
+  const parts = ["crossbar", kind, hostPart];
+  if (portPart) parts.push(portPart);
+  return parts.join("-");
+}
+
+function defaultPortForProtocol(protocol: string): string {
+  if (protocol === "https:") return "443";
+  if (protocol === "http:") return "80";
+  return "";
+}
+
+/**
+ * Derive the env-var name for the api-key associated with a server id.
+ * The env var name is the id uppercased with hyphens replaced by underscores,
+ * so `crossbar-ollama-127-0-0-1-11434` → `CROSSBAR_OLLAMA_127_0_0_1_11434`.
+ * This is the name used for the `$ENV` handoff in Pi's registerProvider apiKey field.
+ */
+export function envVarFor(id: string): string {
+  return id.toUpperCase().replace(/-/g, "_");
+}