@hypabolic/crossbar 0.1.0

package/src/adapters/vllm.ts

@@ -0,0 +1,197 @@
+/**
+ * vLLM backend adapter for Crossbar.
+ *
+ * Implements the BackendAdapter contract for vLLM's OpenAI-compatible HTTP API:
+ *   - Fingerprint: GET /version → {"version":...} AND/OR GET /v1/models with owned_by:"vllm"
+ *   - List models: GET /v1/models → ModelCard[] {id, max_model_len, owned_by, root}
+ *   - Health: GET /health (empty 200 ⇒ healthy, 503 ⇒ loading)
+ *   - Inference base URL: server.baseUrl + "/v1"
+ *
+ * Capabilities NOT declared (vLLM serves a single fixed model at startup):
+ *   - IntrospectLoaded — no live introspection endpoint for the base model
+ *   - SwitchModel — no hot-swap on the base model
+ *   - LoadUnload — no explicit load/unload on the base model
+ *
+ * Uses ONLY the injected Probe — never calls fetch directly.
+ */
+
+import { Capability } from "../core/capability.ts";
+import type { BackendAdapter, PiApiType } from "../core/backend-adapter.ts";
+import type {
+  DiscoveredServer,
+  HealthStatus,
+  ModelDescriptor,
+  PiModelEntry,
+  Probe,
+  ServerCredential,
+} from "../core/types.ts";
+
+// ---------------------------------------------------------------------------
+// Internal shapes matching vLLM's API responses
+// ---------------------------------------------------------------------------
+
+interface VllmVersionResponse {
+  version?: string;
+}
+
+interface VllmModelCard {
+  id: string;
+  owned_by?: string;
+  max_model_len?: number;
+  root?: string;
+  parent?: string | null;
+}
+
+interface VllmModelsResponse {
+  data?: VllmModelCard[];
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_CONTEXT_WINDOW = 8192;
+const DEFAULT_MAX_TOKENS = 4096;
+
+// ---------------------------------------------------------------------------
+// VllmAdapter
+// ---------------------------------------------------------------------------
+
+class VllmAdapter implements BackendAdapter {
+  readonly kind = "vllm" as const;
+  readonly displayName = "vLLM";
+  readonly defaultPorts: readonly number[] = [8000];
+  readonly piApi: PiApiType = "openai-completions";
+  readonly capabilities: ReadonlySet<Capability> = new Set<Capability>([
+    Capability.ListModels,
+    Capability.Health,
+    Capability.PerModelCaps,
+    Capability.Streaming,
+  ]);
+
+  // --- fingerprint ----------------------------------------------------------
+
+  async fingerprint(baseUrl: string, probe: Probe): Promise<DiscoveredServer | null> {
+    // Strategy 1: GET /version → {"version": ...} unique to vLLM
+    const versionResult = await probe("/version");
+    if (versionResult.status !== 0) {
+      if (versionResult.ok) {
+        const body = versionResult.json as VllmVersionResponse | undefined;
+        if (body && typeof body.version === "string") {
+          // /version responded with a version string → high confidence vLLM
+          return {
+            kind: "vllm",
+            baseUrl,
+            auth: "none",
+            version: body.version,
+            label: `vLLM (${baseUrl.replace(/^https?:\/\//, "")})`,
+            confidence: 0.9,
+          };
+        }
+      }
+    }
+
+    // Strategy 2: GET /v1/models with owned_by:"vllm" and max_model_len
+    const modelsResult = await probe("/v1/models");
+    if (modelsResult.status === 0) return null;
+    if (!modelsResult.ok) return null;
+
+    const body = modelsResult.json as VllmModelsResponse | undefined;
+    const models = body?.data ?? [];
+    const hasVllmModel = models.some(
+      (m) => m.owned_by === "vllm" && typeof m.max_model_len === "number",
+    );
+    if (!hasVllmModel) return null;
+
+    return {
+      kind: "vllm",
+      baseUrl,
+      auth: "none",
+      label: `vLLM (${baseUrl.replace(/^https?:\/\//, "")})`,
+      confidence: 0.9,
+    };
+  }
+
+  // --- health ---------------------------------------------------------------
+
+  async health(
+    _server: DiscoveredServer,
+    _cred: ServerCredential,
+    probe: Probe,
+  ): Promise<HealthStatus> {
+    const r = await probe("/health");
+    if (r.status === 0) {
+      const s: HealthStatus = { state: "unreachable" };
+      if (r.error !== undefined) s.detail = r.error;
+      return s;
+    }
+    if (r.status === 401) return { state: "unauthorized" };
+    if (r.status === 503) return { state: "loading" };
+    if (!r.ok) return { state: "degraded", detail: `status ${r.status}` };
+    const status: HealthStatus = { state: "healthy" };
+    if (r.latencyMs !== undefined) status.latencyMs = r.latencyMs;
+    return status;
+  }
+
+  // --- listModels -----------------------------------------------------------
+
+  async listModels(
+    _server: DiscoveredServer,
+    cred: ServerCredential,
+    probe: Probe,
+  ): Promise<ModelDescriptor[]> {
+    const headers: Record<string, string> = {};
+    if (cred.mode === "apiKey" && cred.apiKey) {
+      headers["Authorization"] = `Bearer ${cred.apiKey}`;
+    }
+
+    const r = await probe("/v1/models", { method: "GET", headers });
+    if (!r.ok) {
+      if (r.status === 401) throw new Error("401 Unauthorized");
+      if (r.status === 0) throw new Error("server unreachable (status:0)");
+      throw new Error(`listModels failed: status ${r.status}`);
+    }
+
+    const body = r.json as VllmModelsResponse | undefined;
+    const rawModels = body?.data ?? [];
+
+    return rawModels.map((m): ModelDescriptor => {
+      return {
+        id: m.id,
+        name: m.id,
+        contextWindow: typeof m.max_model_len === "number" ? m.max_model_len : DEFAULT_CONTEXT_WINDOW,
+        maxTokens: DEFAULT_MAX_TOKENS,
+        input: ["text"],
+        reasoning: false,
+        embeddings: false,
+        raw: m,
+      };
+    });
+  }
+
+  // --- toPiModel ------------------------------------------------------------
+
+  toPiModel(_server: DiscoveredServer, model: ModelDescriptor): PiModelEntry {
+    return {
+      id: model.id,
+      name: model.name,
+      reasoning: model.reasoning ?? false,
+      input: model.input.length > 0 ? model.input : ["text"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: model.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
+      maxTokens: model.maxTokens ?? DEFAULT_MAX_TOKENS,
+    };
+  }
+
+  // --- inferenceBaseUrl -----------------------------------------------------
+
+  inferenceBaseUrl(server: DiscoveredServer): string {
+    return `${server.baseUrl}/v1`;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Singleton export
+// ---------------------------------------------------------------------------
+
+export const vllmAdapter: BackendAdapter = new VllmAdapter();

package/src/core/backend-adapter.ts

@@ -0,0 +1,123 @@
+/**
+ * The `BackendAdapter` contract — Crossbar's single most important interface and the FROZEN boundary
+ * every backend implementation codes against. Phase 2 fan-out (one adapter per backend) targets this
+ * file and nothing else; the conformance suite (tests/conformance) validates every adapter against it.
+ *
+ * Design tenets:
+ *  - Adapters are STATELESS. All state (selected server, credentials, last-known models) is owned by
+ *    the registry and passed in. An adapter instance is a singleton describing one backend *kind*.
+ *  - Adapters perform NO direct I/O. Every network call goes through the injected {@link Probe}, so the
+ *    same adapter runs unchanged in production, in discovery, and against test fixtures.
+ *  - Capabilities are HONEST. An optional method is present iff the matching {@link Capability} is in
+ *    `capabilities`. The orchestrator checks the set, never feature-sniffs the method.
+ *  - Pi mapping is OWNED by the adapter. `toPiModel` / `inferenceBaseUrl` are the only places that know
+ *    which built-in Pi API type and compat flags a backend needs; the shim stays generic.
+ *
+ * See ARCHITECTURE.md for how the registry, discovery engine, and provider shim consume this.
+ */
+
+import type { Capability, BackendKind } from "./capability.ts";
+import type {
+  DiscoveredServer,
+  HealthStatus,
+  LoadAction,
+  LoadedState,
+  ModelDescriptor,
+  PiModelEntry,
+  Probe,
+  ServerCredential,
+} from "./types.ts";
+
+/** Bumped on any breaking change to this interface. Adapters and the registry assert on it. */
+export const CONTRACT_VERSION = 1 as const;
+
+/** Which built-in Pi API type the adapter registers its models under. */
+export type PiApiType = "openai-completions" | "anthropic-messages";
+
+export interface BackendAdapter {
+  /** Stable identity. One adapter instance per kind. */
+  readonly kind: BackendKind;
+  /** Human-facing name, e.g. "LM Studio". */
+  readonly displayName: string;
+  /** Ports the discovery engine probes for this backend (empty for cloud kinds). */
+  readonly defaultPorts: readonly number[];
+  /** The Pi built-in API type all this backend's models register under. */
+  readonly piApi: PiApiType;
+  /** The capabilities this backend exposes. Drives UX and which optional methods are present. */
+  readonly capabilities: ReadonlySet<Capability>;
+
+  /**
+   * Decide whether `baseUrl` is *this* backend. MUST use only unauthenticated metadata endpoints
+   * (most local servers leave `/v1/models`, `/health`, `/props` public even when keyed). Return a
+   * {@link DiscoveredServer} with a confidence score, or `null` if this isn't our backend.
+   * Cloud adapters return `null` (they are configured, not probed).
+   */
+  fingerprint(baseUrl: string, probe: Probe): Promise<DiscoveredServer | null>;
+
+  /** Liveness / readiness. Present iff `capabilities` has {@link Capability.Health}. */
+  health?(server: DiscoveredServer, cred: ServerCredential, probe: Probe): Promise<HealthStatus>;
+
+  /** Enumerate available models. Required (every backend supports {@link Capability.ListModels}). */
+  listModels(server: DiscoveredServer, cred: ServerCredential, probe: Probe): Promise<ModelDescriptor[]>;
+
+  /** Snapshot of currently-loaded models. Present iff {@link Capability.IntrospectLoaded}. */
+  introspectLoaded?(
+    server: DiscoveredServer,
+    cred: ServerCredential,
+    probe: Probe,
+  ): Promise<LoadedState>;
+
+  /**
+   * Make `modelId` the active/served model. Present iff {@link Capability.SwitchModel}. Implementations
+   * range from a no-op + implicit load (Ollama) to a proxy swap that restarts an upstream (llama-swap).
+   * MUST reject if the switch cannot be confirmed (server down mid-switch, model not available).
+   */
+  switchModel?(
+    server: DiscoveredServer,
+    cred: ServerCredential,
+    modelId: string,
+    probe: Probe,
+  ): Promise<void>;
+
+  /** Explicit load/unload. Present iff {@link Capability.LoadUnload}. */
+  loadUnload?(
+    server: DiscoveredServer,
+    cred: ServerCredential,
+    modelId: string,
+    action: LoadAction,
+    probe: Probe,
+  ): Promise<void>;
+
+  /**
+   * Map one discovered model to the exact entry Pi's `registerProvider` expects. Owns api/compat-flag
+   * selection, cost zeros for local backends, and conservative defaults when caps are unknown.
+   */
+  toPiModel(server: DiscoveredServer, model: ModelDescriptor): PiModelEntry;
+
+  /**
+   * The base URL Pi should use for *inference* against this server. May differ from
+   * `server.baseUrl` (e.g. append `/v1` for OpenAI-compat backends, or point at the proxy front door).
+   */
+  inferenceBaseUrl(server: DiscoveredServer): string;
+}
+
+/** Narrowing helpers so the orchestrator never calls an absent optional method. */
+export const supports = (a: BackendAdapter, c: Capability): boolean => a.capabilities.has(c);
+
+export function canSwitch(
+  a: BackendAdapter,
+): a is BackendAdapter & Required<Pick<BackendAdapter, "switchModel">> {
+  return typeof a.switchModel === "function";
+}
+
+export function canIntrospect(
+  a: BackendAdapter,
+): a is BackendAdapter & Required<Pick<BackendAdapter, "introspectLoaded">> {
+  return typeof a.introspectLoaded === "function";
+}
+
+export function canLoadUnload(
+  a: BackendAdapter,
+): a is BackendAdapter & Required<Pick<BackendAdapter, "loadUnload">> {
+  return typeof a.loadUnload === "function";
+}

package/src/core/capability.ts

@@ -0,0 +1,53 @@
+/**
+ * Crossbar core enums — the capability vocabulary every {@link BackendAdapter} declares against.
+ *
+ * Locked Phase 1 contract. Adapters MUST NOT add new BackendKind / Capability values without an
+ * interface revision (bump CONTRACT_VERSION in ./backend-adapter.ts). See ARCHITECTURE.md.
+ */
+
+/**
+ * The set of capabilities a backend may expose. An adapter declares the subset it supports via
+ * {@link BackendAdapter.capabilities}; the UX is driven entirely off this set (hide "switch model"
+ * when absent, show last-known instead of live loaded state when introspection is missing, etc.).
+ */
+export enum Capability {
+  /** Can enumerate available models (`/v1/models`, `/api/tags`, ...). Effectively universal. */
+  ListModels = "listModels",
+  /** Can report which model(s) are currently resident/loaded right now (`/api/ps`, `state`, `/running`). */
+  IntrospectLoaded = "introspectLoaded",
+  /** Can change the active/served model at runtime (implicit request, JIT load, or proxy swap). */
+  SwitchModel = "switchModel",
+  /** Can explicitly load and unload a model (`keep_alive:0`, `/load`+`/unload`, `lms`, ...). */
+  LoadUnload = "loadUnload",
+  /** Exposes a health/liveness signal (`/health`, `GET /` text, ...). */
+  Health = "health",
+  /** Exposes per-model capability metadata (context window, vision, tools) beyond bare ids. */
+  PerModelCaps = "perModelCaps",
+  /** Supports streaming responses. Effectively universal for the chat path. */
+  Streaming = "streaming",
+}
+
+/** Authentication scheme a server requires. Crossbar only ever sends a bearer/api key or nothing. */
+export type AuthMode = "none" | "apiKey";
+
+/**
+ * Concrete backend identities Crossbar understands. `openai-generic` is the catch-all fallback for
+ * anything that merely exposes `/v1/models` (covers the long tail: Jan, llamafile, unknown servers).
+ */
+export type BackendKind =
+  | "ollama"
+  | "lmstudio"
+  | "llamacpp"
+  | "llamaswap"
+  | "vllm"
+  | "openai"
+  | "anthropic"
+  | "tabbyapi"
+  | "koboldcpp"
+  | "oobabooga"
+  | "jan"
+  | "llamafile"
+  | "openai-generic";
+
+/** Backends that are remote cloud services (configured, never port-probed). */
+export const CLOUD_KINDS: ReadonlySet<BackendKind> = new Set<BackendKind>(["openai", "anthropic"]);

package/src/core/index.ts

@@ -0,0 +1,36 @@
+/** Crossbar core contract — public surface for adapters, registry, discovery, and the Pi shim. */
+
+export {
+  Capability,
+  CLOUD_KINDS,
+  type AuthMode,
+  type BackendKind,
+} from "./capability.ts";
+
+export {
+  CONTRACT_VERSION,
+  canIntrospect,
+  canLoadUnload,
+  canSwitch,
+  supports,
+  type BackendAdapter,
+  type PiApiType,
+} from "./backend-adapter.ts";
+
+export type {
+  CrossbarConfigFile,
+  CrossbarSettings,
+  DiscoveredServer,
+  HealthState,
+  HealthStatus,
+  LoadAction,
+  LoadedModelInfo,
+  LoadedState,
+  ModelDescriptor,
+  PiModelEntry,
+  Probe,
+  ProbeInit,
+  ProbeResult,
+  ServerCredential,
+  ServerRecord,
+} from "./types.ts";

package/src/core/types.ts

@@ -0,0 +1,160 @@
+/**
+ * Crossbar core data shapes — the values that flow between discovery, the registry, adapters, and the
+ * Pi provider-registration shim. Locked Phase 1 contract. See ARCHITECTURE.md.
+ *
+ * The single hard tie to Pi is {@link PiModelEntry}: it is derived from Pi's exported `ProviderConfig`
+ * so the shim cannot drift from the real `pi.registerProvider` schema.
+ */
+
+import type { ProviderConfig } from "@earendil-works/pi-coding-agent";
+import type { AuthMode, BackendKind } from "./capability.ts";
+
+/** A single model entry exactly as Pi's `registerProvider` expects it. Derived from the real type. */
+export type PiModelEntry = NonNullable<ProviderConfig["models"]>[number];
+
+// ---------------------------------------------------------------------------------------------------
+// Probing primitive (injected, not imported) — keeps adapters testable and side-effect free.
+// ---------------------------------------------------------------------------------------------------
+
+export interface ProbeInit {
+  method?: "GET" | "POST" | "HEAD";
+  /** Header map. The orchestrator injects auth headers; adapters add content-type etc. as needed. */
+  headers?: Record<string, string>;
+  body?: string;
+  /** Per-request timeout. Discovery uses a short budget (default supplied by the engine). */
+  timeoutMs?: number;
+}
+
+export interface ProbeResult {
+  /** HTTP status, or 0 when the request never completed (connection refused / timeout). */
+  status: number;
+  ok: boolean;
+  headers: Record<string, string>;
+  /** Present when the body was read as text. */
+  text?: string;
+  /** Present when the body parsed as JSON. Adapters should narrow defensively. */
+  json?: unknown;
+  /** Round-trip latency in ms, when measured. */
+  latencyMs?: number;
+  /** Set when the request failed before a response (refused, DNS, timeout). */
+  error?: string;
+}
+
+/**
+ * The injected fetch primitive. `path` is resolved against the server base URL by the caller-provided
+ * implementation. Adapters MUST go through this rather than calling `fetch` directly so that timeouts,
+ * auth-header injection, redaction, and test fakes all live in one place.
+ */
+export type Probe = (path: string, init?: ProbeInit) => Promise<ProbeResult>;
+
+// ---------------------------------------------------------------------------------------------------
+// Credentials — secrets are resolved at call time; they are NEVER persisted to crossbar.json and NEVER
+// logged. Persistence of the key itself goes through Pi's authStorage (auth.json, 0600).
+// ---------------------------------------------------------------------------------------------------
+
+export interface ServerCredential {
+  mode: AuthMode;
+  /** Resolved secret, present only when mode === "apiKey". Treat as sensitive; never log or serialize. */
+  apiKey?: string;
+}
+
+// ---------------------------------------------------------------------------------------------------
+// Discovery & health
+// ---------------------------------------------------------------------------------------------------
+
+export interface DiscoveredServer {
+  kind: BackendKind;
+  /** Normalized origin used for fingerprinting & metadata calls (no trailing slash, no `/v1`). */
+  baseUrl: string;
+  auth: AuthMode;
+  version?: string;
+  /** Human label, e.g. "Ollama (127.0.0.1:11434)". */
+  label: string;
+  /** Fingerprint confidence 0..1; the engine prefers the highest-confidence match per origin. */
+  confidence: number;
+}
+
+export type HealthState = "healthy" | "loading" | "degraded" | "unauthorized" | "unreachable";
+
+export interface HealthStatus {
+  state: HealthState;
+  detail?: string;
+  latencyMs?: number;
+}
+
+// ---------------------------------------------------------------------------------------------------
+// Models & loaded state
+// ---------------------------------------------------------------------------------------------------
+
+export interface ModelDescriptor {
+  id: string;
+  name: string;
+  /** Context window in tokens, when the backend reports it. */
+  contextWindow?: number;
+  /** Max output tokens, when known. */
+  maxTokens?: number;
+  /** Input modalities. Defaults to ["text"] when the backend doesn't say. */
+  input: ("text" | "image")[];
+  /** Supports extended thinking / reasoning. */
+  reasoning?: boolean;
+  /** Supports tool/function calling. */
+  tools?: boolean;
+  /** Is an embeddings model (excluded from chat model registration). */
+  embeddings?: boolean;
+  /** Best-effort: was this model resident at list time (from introspection)? */
+  loaded?: boolean;
+  /** Original backend payload, retained for diagnostics. Never registered with Pi. */
+  raw?: unknown;
+}
+
+export interface LoadedModelInfo {
+  vramBytes?: number;
+  /** Unix ms when the model will be evicted (Ollama keep_alive, LM Studio TTL). */
+  expiresAt?: number;
+  /** Runtime context length if it differs from the model's max. */
+  contextLength?: number;
+}
+
+export interface LoadedState {
+  loadedModelIds: string[];
+  perModel?: Record<string, LoadedModelInfo>;
+  /** How this snapshot was obtained — drives whether the widget shows a live or last-known indicator. */
+  source: "introspection" | "last-known" | "unknown";
+}
+
+export type LoadAction = "load" | "unload";
+
+// ---------------------------------------------------------------------------------------------------
+// Persistence — crossbar.json (non-secret) lives at getAgentDir()/crossbar.json. Secrets are in auth.json.
+// ---------------------------------------------------------------------------------------------------
+
+export interface ServerRecord {
+  /** Stable Crossbar id. Doubles as the Pi provider name AND the auth.json key for this server. */
+  id: string;
+  kind: BackendKind;
+  /** Normalized origin (same shape as DiscoveredServer.baseUrl). */
+  baseUrl: string;
+  label: string;
+  auth: AuthMode;
+  enabled: boolean;
+  /** Unix ms. */
+  addedAt: number;
+  lastSeenAt?: number;
+  /** Cached for offline rendering / fast startup; refreshed on health poll. */
+  lastKnownModels?: ModelDescriptor[];
+  /** Cached loaded-model ids for the "currently loaded" widget when introspection is unavailable. */
+  lastKnownLoaded?: string[];
+}
+
+export interface CrossbarSettings {
+  /** Opt-in LAN host-range probing (default false — localhost only). */
+  lanDiscovery?: boolean;
+  /** Override the default localhost probe ports. */
+  probePorts?: number[];
+}
+
+export interface CrossbarConfigFile {
+  version: 1;
+  servers: ServerRecord[];
+  settings?: CrossbarSettings;
+}