@cavi-ai/api-client 0.1.0

package/src/core/sse/stream.ts

@@ -0,0 +1,118 @@
+export type SseMessage = {
+  data: string;
+  event?: string;
+  id?: string;
+  retry?: number;
+};
+
+export type SseMessageHandler = (message: SseMessage) => void;
+
+export function isSseContentType(contentType: string | null | undefined): boolean {
+  return (contentType ?? "").toLowerCase().includes("text/event-stream");
+}
+
+export function parseSseBlock(block: string): SseMessage | null {
+  const lines = block.split(/\r?\n/u);
+  const dataLines: string[] = [];
+  let event: string | undefined;
+  let id: string | undefined;
+  let retry: number | undefined;
+
+  for (const line of lines) {
+    if (!line || line.startsWith(":")) continue;
+    const separator = line.indexOf(":");
+    const field = separator >= 0 ? line.slice(0, separator) : line;
+    const rawValue = separator >= 0 ? line.slice(separator + 1) : "";
+    const value = rawValue.startsWith(" ") ? rawValue.slice(1) : rawValue;
+
+    if (field === "data") {
+      dataLines.push(value);
+    } else if (field === "event") {
+      event = value;
+    } else if (field === "id") {
+      id = value;
+    } else if (field === "retry") {
+      const parsed = Number(value);
+      if (Number.isFinite(parsed)) retry = parsed;
+    }
+  }
+
+  if (dataLines.length === 0) return null;
+  return {
+    data: dataLines.join("\n"),
+    ...(event !== undefined ? { event } : {}),
+    ...(id !== undefined ? { id } : {}),
+    ...(retry !== undefined ? { retry } : {}),
+  };
+}
+
+export function takeNextSseBlock(buffer: string): { block: string; rest: string } | null {
+  const lfBoundary = buffer.indexOf("\n\n");
+  const crlfBoundary = buffer.indexOf("\r\n\r\n");
+  if (lfBoundary < 0 && crlfBoundary < 0) return null;
+  if (crlfBoundary >= 0 && (lfBoundary < 0 || crlfBoundary < lfBoundary)) {
+    return { block: buffer.slice(0, crlfBoundary), rest: buffer.slice(crlfBoundary + 4) };
+  }
+  return { block: buffer.slice(0, lfBoundary), rest: buffer.slice(lfBoundary + 2) };
+}
+
+export function drainSseMessages(
+  buffer: string,
+  onMessage: SseMessageHandler,
+): string {
+  let current = buffer;
+  let next = takeNextSseBlock(current);
+  while (next) {
+    current = next.rest;
+    const message = parseSseBlock(next.block);
+    if (message) onMessage(message);
+    next = takeNextSseBlock(current);
+  }
+  return current;
+}
+
+export async function consumeSseStream(
+  body: ReadableStream<Uint8Array>,
+  signal: AbortSignal,
+  onMessage: SseMessageHandler,
+): Promise<void> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let buffer = "";
+  const onAbort = (): void => {
+    try {
+      void reader.cancel();
+    } catch {
+      // best effort
+    }
+  };
+  signal.addEventListener("abort", onAbort);
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) {
+        buffer += decoder.decode();
+        break;
+      }
+      buffer += decoder.decode(value, { stream: true });
+      buffer = drainSseMessages(buffer, onMessage);
+    }
+    buffer = drainSseMessages(buffer, onMessage);
+    const trailing = parseSseBlock(buffer);
+    if (trailing) onMessage(trailing);
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+  }
+}
+
+export function combineAbortSignals(a: AbortSignal, b: AbortSignal | undefined): AbortSignal {
+  if (!b) return a;
+  const controller = new AbortController();
+  if (a.aborted || b.aborted) {
+    controller.abort();
+    return controller.signal;
+  }
+  a.addEventListener("abort", () => controller.abort(), { once: true });
+  b.addEventListener("abort", () => controller.abort(), { once: true });
+  return controller.signal;
+}

package/src/core/ws/close.ts

@@ -0,0 +1,51 @@
+export type WebSocketCloseLike = {
+  code?: unknown;
+  reason?: unknown;
+};
+
+export type WebSocketCloseDescription = {
+  code: number | null;
+  reason: string | null;
+  message: string;
+};
+
+export function describeWebSocketClose(
+  event?: WebSocketCloseLike | null,
+  fallbackMessage = "websocket closed",
+): WebSocketCloseDescription {
+  const code =
+    typeof event?.code === "number" && Number.isFinite(event.code)
+      ? Math.round(event.code)
+      : null;
+  const reason =
+    typeof event?.reason === "string" && event.reason.trim().length > 0
+      ? event.reason.trim()
+      : null;
+
+  if (code !== null && reason) {
+    return {
+      code,
+      reason,
+      message: `${fallbackMessage} (${code}): ${reason}`,
+    };
+  }
+  if (code !== null) {
+    return {
+      code,
+      reason: null,
+      message: `${fallbackMessage} (${code})`,
+    };
+  }
+  if (reason) {
+    return {
+      code: null,
+      reason,
+      message: `${fallbackMessage}: ${reason}`,
+    };
+  }
+  return {
+    code: null,
+    reason: null,
+    message: fallbackMessage,
+  };
+}

package/src/core/ws/gateway-websocket.ts

@@ -0,0 +1,8 @@
+export {
+  GatewayRpcClient as GatewayWebSocketClient,
+  type GatewayConnectionState as GatewayWebSocketConnectionState,
+  type GatewayRpcClientOptions as GatewayWebSocketClientOptions,
+  type GatewayRpcTraceEntry as GatewayWebSocketTraceEntry,
+  type GatewayStreamEvent as GatewayWebSocketEvent,
+  type DeviceIdentity,
+} from "../gateway/rpc/client.js";

package/src/core/ws/index.ts

@@ -0,0 +1,3 @@
+export * from "./close.js";
+export * from "./gateway-websocket.js";
+export * from "./targets.js";

package/src/core/ws/targets.ts

@@ -0,0 +1,74 @@
+export type HttpWebSocketTargets = {
+  httpBase: string;
+  wsUrl: string;
+};
+
+/**
+ * Resolve paired HTTP and WebSocket targets from any supported input scheme:
+ * `http://`, `https://`, `ws://`, or `wss://`.
+ *
+ * HTTP(S) inputs preserve their pathname for `httpBase` and use `/ws` for the
+ * socket path. WS(S) inputs preserve their socket pathname and expose the HTTP
+ * origin as `httpBase`.
+ */
+export function resolveHttpWebSocketTargets(baseUrl: string): HttpWebSocketTargets {
+  const trimmed = baseUrl.replace(/\/+$/u, "");
+  const url = new URL(trimmed);
+
+  let httpProtocol: "http:" | "https:";
+  let wsProtocol: "ws:" | "wss:";
+  switch (url.protocol) {
+    case "http:":
+      httpProtocol = "http:";
+      wsProtocol = "ws:";
+      break;
+    case "https:":
+      httpProtocol = "https:";
+      wsProtocol = "wss:";
+      break;
+    case "ws:":
+      httpProtocol = "http:";
+      wsProtocol = "ws:";
+      break;
+    case "wss:":
+      httpProtocol = "https:";
+      wsProtocol = "wss:";
+      break;
+    default:
+      throw new Error(
+        `resolveHttpWebSocketTargets: unsupported scheme "${url.protocol.replace(/:$/u, "")}". Expected one of http, https, ws, wss.`,
+      );
+  }
+
+  const pathname =
+    url.pathname === "/" ? "" : url.pathname.replace(/\/+$/u, "");
+  const explicitWsInput = url.protocol === "ws:" || url.protocol === "wss:";
+  const httpBase = `${httpProtocol}//${url.host}${explicitWsInput ? "" : pathname}`;
+  const wsPath = explicitWsInput ? pathname || "/ws" : "/ws";
+  const wsUrl = `${wsProtocol}//${url.host}${wsPath}`;
+  return {
+    httpBase,
+    wsUrl,
+  };
+}
+
+/**
+ * Safe variant of {@link resolveHttpWebSocketTargets}; returns null for empty,
+ * malformed, or unsupported values.
+ */
+export function tryResolveHttpWebSocketTargets(
+  baseUrl: string,
+): HttpWebSocketTargets | null {
+  const trimmed = baseUrl.trim().replace(/\/+$/u, "");
+  if (!trimmed) {
+    return null;
+  }
+  try {
+    return resolveHttpWebSocketTargets(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+export const resolveGatewayTargets = resolveHttpWebSocketTargets;
+export const tryResolveGatewayTargets = tryResolveHttpWebSocketTargets;

package/src/extensions/README.md

@@ -0,0 +1,16 @@
+# Extensions
+
+Extensions live outside `core/**` and `contracts/**` because they are
+product-specific composition layers. They may depend on shared core primitives
+and global contracts, but core must not depend on them.
+
+## Folder Map
+
+- `cavi/` owns CAVI/HQ extension contracts, adapters, domain DTOs, fallback
+  snapshots, Project Board, operator-control, discourse, portal, library, and
+  registry behavior.
+
+Extension route literals belong in the extension's `contracts/paths.ts` or
+`contracts/surfaces.ts` owner files. Extension surface maps append to the core
+resolver with `createSurfacePathResolver`; adding an extension route to
+`src/contracts/**` is a boundary change and should fail hardening tests.

package/src/extensions/cavi/adapters/cavi-control-adapters/gateway-ws-loaders.ts

@@ -0,0 +1,33 @@
+import type { GatewayWebSocketClient } from "../../../../core/ws/index.js";
+import { createSessionLoaders } from "../../../../core/gateway/snapshots/session-loaders.js";
+import { createGatewaySystemLoaders } from "../../../../core/gateway/snapshots/system-loaders.js";
+import type { JsonHttpRequest } from "../../../../core/http/json-client.js";
+import {
+  createGatewayWsSnapshotLoaders,
+  type CreateGatewayWsSnapshotLoadersOptions,
+} from "./gateway-ws-snapshot-loaders.js";
+
+export function createGatewayWsLoaders(deps: {
+  client: GatewayWebSocketClient | null | undefined;
+  requestJson: JsonHttpRequest;
+  snapshotOptions?: CreateGatewayWsSnapshotLoadersOptions;
+}) {
+  const { client, requestJson } = deps;
+  const sessionLoaders = createSessionLoaders(client, { requestJson });
+  const systemLoaders = createGatewaySystemLoaders(client);
+  const snapshotLoaders = createGatewayWsSnapshotLoaders({
+    sessionLoaders,
+    systemLoaders,
+    requestJson,
+    options: deps.snapshotOptions,
+  });
+
+  return {
+    loadSessionsListRaw: sessionLoaders.loadSessionsListRaw,
+    loadSessionsUsageRaw: sessionLoaders.loadSessionsUsageRaw,
+    loadSessionsPreviewRaw: sessionLoaders.loadSessionsPreviewRaw,
+    loadSessionDetailRaw: sessionLoaders.loadSessionDetailRaw,
+    patchSessionRaw: sessionLoaders.patchSession,
+    ...snapshotLoaders,
+  };
+}

package/src/extensions/cavi/adapters/cavi-control-adapters/gateway-ws-snapshot-loaders.ts

@@ -0,0 +1,152 @@
+import type { SessionLoaders } from "../../../../core/gateway/snapshots/session-loaders.js";
+import {
+  createGatewaySnapshotLoaders,
+  resolveGatewaySnapshotFallbacks,
+  type GatewaySnapshotBindingResolver,
+  type GatewaySnapshotFallbackMode,
+  type GatewaySnapshotFallbacks,
+  type GatewaySnapshotFallbackOverrides,
+  type GatewaySnapshotFallbackProvider,
+  type GatewayCostHistoryFallback,
+} from "../../../../core/gateway/snapshots/loaders.js";
+import { type DataEnvelope, withFallback } from "../../../../core/gateway/envelope/index.js";
+import {
+  type JsonHttpRequest,
+  withQuery,
+} from "../../../../core/http/json-client.js";
+import { describeHttpContract } from "../../../../core/http/contracts.js";
+import { CAVI_CONTROL_API_ENDPOINTS } from "../../contracts/paths.js";
+import { createCaviSnapshotFallbackProvider } from "../../fallbacks/provider.js";
+import type {
+  GatewaySessionRunDetailSnapshot,
+  AgentRunsFilters,
+  GatewaySessionRunsSnapshot,
+  CostHistoryRange,
+  CostHistorySnapshot,
+  IncidentsSnapshot,
+  OverviewSnapshot,
+  RoutingMatrixSnapshot,
+} from "../../../../core/gateway/snapshots/contracts.js";
+import type { GatewaySystemLoaders } from "../../../../core/gateway/snapshots/system-loaders.js";
+
+export type CaviSnapshotFallbackMode = GatewaySnapshotFallbackMode | "compat";
+
+export type GatewayWsSnapshotLoaders = {
+  loadOverview: () => Promise<DataEnvelope<OverviewSnapshot>>;
+  loadAgentRuns: (
+    filters: AgentRunsFilters,
+  ) => Promise<DataEnvelope<GatewaySessionRunsSnapshot>>;
+  loadRunDetail: (
+    key: string,
+  ) => Promise<DataEnvelope<GatewaySessionRunDetailSnapshot>>;
+  loadRoutingMatrix: (
+    windowDays: number,
+  ) => Promise<DataEnvelope<RoutingMatrixSnapshot>>;
+  loadIncidents: () => Promise<DataEnvelope<IncidentsSnapshot>>;
+  loadCostHistory: (
+    range: CostHistoryRange,
+  ) => Promise<DataEnvelope<CostHistorySnapshot>>;
+};
+
+export type CreateGatewayWsSnapshotLoadersOptions = {
+  fallbackMode?: CaviSnapshotFallbackMode;
+  fallbackProvider?: GatewaySnapshotFallbackProvider | null;
+  snapshotFallbacks?: Partial<GatewaySnapshotFallbacks>;
+  costHistoryFallback?: GatewayCostHistoryFallback | null;
+  resolveBinding?: GatewaySnapshotBindingResolver | null;
+};
+
+export function resolveCaviSnapshotFallbacks(
+  options: CreateGatewayWsSnapshotLoadersOptions = {},
+): ReturnType<typeof resolveGatewaySnapshotFallbacks> {
+  const mode = options.fallbackMode ?? "empty";
+  const overrides: GatewaySnapshotFallbackOverrides = {
+    ...(options.snapshotFallbacks ?? {}),
+  };
+  if ("costHistoryFallback" in options) {
+    overrides.costHistory = options.costHistoryFallback ?? null;
+  }
+  const resolved = resolveGatewaySnapshotFallbacks({
+    mode: mode === "compat" ? "empty" : mode,
+    provider: options.fallbackProvider ??
+      (mode === "compat" ? createCaviSnapshotFallbackProvider() : null),
+    overrides,
+  });
+  return resolved;
+}
+
+function gatewayEnvelope<TData>(data: TData): DataEnvelope<TData> {
+  return {
+    data,
+    source: "gateway",
+    fetchedAt: Date.now(),
+    contractGaps: [],
+  };
+}
+
+export function createGatewayWsSnapshotLoaders(deps: {
+  sessionLoaders: SessionLoaders;
+  systemLoaders: GatewaySystemLoaders;
+  requestJson: JsonHttpRequest;
+  options?: CreateGatewayWsSnapshotLoadersOptions;
+}): GatewayWsSnapshotLoaders {
+  const { requestJson } = deps;
+  const fallbacks = resolveCaviSnapshotFallbacks(deps.options);
+  const coreLoaders = createGatewaySnapshotLoaders({
+    sessionLoaders: deps.sessionLoaders,
+    systemLoaders: deps.systemLoaders,
+    options: {
+      fallbacks: fallbacks.snapshots,
+      resolveBinding: deps.options?.resolveBinding ?? null,
+    },
+  });
+
+  return {
+    loadOverview: coreLoaders.loadOverview,
+    loadAgentRuns: async (filters: AgentRunsFilters) =>
+      await coreLoaders.loadAgentRuns(filters) as DataEnvelope<GatewaySessionRunsSnapshot>,
+    loadRunDetail: async (key: string) =>
+      await coreLoaders.loadRunDetail(key) as DataEnvelope<GatewaySessionRunDetailSnapshot>,
+    loadRoutingMatrix: async (windowDays: number) =>
+      await coreLoaders.loadRoutingMatrix(windowDays) as DataEnvelope<RoutingMatrixSnapshot>,
+    loadIncidents: coreLoaders.loadIncidents,
+
+    loadCostHistory: async (
+      range: CostHistoryRange,
+    ): Promise<DataEnvelope<CostHistorySnapshot>> =>
+      deps.options?.fallbackMode === "none"
+        ? gatewayEnvelope(
+            await requestJson<CostHistorySnapshot>(
+              withQuery(CAVI_CONTROL_API_ENDPOINTS.costHistory, { range }),
+            ),
+          )
+        : await withFallback({
+            area: "cost-history",
+            expectedContract: describeHttpContract(
+              "GET",
+              CAVI_CONTROL_API_ENDPOINTS.costHistory,
+            ),
+            note: "Cost history endpoint unavailable",
+            fallback: fallbacks.costHistory
+              ? (
+                  typeof fallbacks.costHistory === "function"
+                    ? fallbacks.costHistory(range)
+                    : fallbacks.costHistory
+                )
+              : {
+                  range,
+                  resolution: "none",
+                  generatedAt: Date.now(),
+                  buckets: [],
+                  totals: {
+                    totalTokens: 0,
+                    estimatedCostUsd: 0,
+                    totalErrors: 0,
+                  },
+                },
+            run: async () => await requestJson<CostHistorySnapshot>(
+              withQuery(CAVI_CONTROL_API_ENDPOINTS.costHistory, { range }),
+            ),
+          }),
+  };
+}

package/src/extensions/cavi/adapters/cavi-control-adapters/library-live.ts

@@ -0,0 +1,120 @@
+import type { FleetLibrarySnapshot, TeamLibraryStatus } from "../../domain/index.js";
+import type { JsonHttpRequest } from "../../../../core/http/json-client.js";
+import { requestLibraryApiJson } from "../../library/api.js";
+import type { PortalLibraryRef } from "../../contracts/portals.js";
+import { getPortalTeamIdentity } from "../../registry/canonical-team-registry.js";
+import { listPortalLibraryRefs } from "../../registry/portal-library-registry.js";
+
+function listTeamLibraryRefs(): PortalLibraryRef[] {
+  return listPortalLibraryRefs().filter(
+    (ref) => ref.scope === "team" && ref.ownerPortalId,
+  );
+}
+
+function resolveTeamMeta(ref: PortalLibraryRef): {
+  name: string;
+  lead: string;
+} {
+  if (ref.ownerPortalId) {
+    const team = getPortalTeamIdentity(ref.ownerPortalId);
+    return {
+      name: team.displayName || team.name || ref.libraryTeamId,
+      lead: team.lead ?? team.dispatchDefaultAlias ?? ref.ownerPortalId,
+    };
+  }
+
+  return { name: ref.libraryTeamId, lead: "unknown" };
+}
+
+type LibrarianStatusResponse = {
+  status: string;
+  inbox: number;
+  inbox_count: number;
+  pending: number;
+  pending_count: number;
+  processed: number;
+  rejected: number;
+  sigmund_status?: string;
+  last_ingest_at?: number | null;
+  total_processed?: number;
+};
+
+function numberFromStatus(
+  value: unknown,
+  fallback = 0,
+): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function buildTeamStatus(
+  ref: PortalLibraryRef,
+  fleetStatus: LibrarianStatusResponse,
+): TeamLibraryStatus {
+  const meta = resolveTeamMeta(ref);
+  return {
+    teamId: ref.libraryTeamId,
+    teamName: meta.name,
+    lead: meta.lead,
+    inboxCount: 0,
+    candidatesCount: 0,
+    promotedCount: 0,
+    rejectedCount: 0,
+    recentPromotions: [],
+    qmdHealth: {
+      lastIndexedAt: fleetStatus.last_ingest_at ?? null,
+      collectionSize: numberFromStatus(
+        fleetStatus.total_processed,
+        numberFromStatus(fleetStatus.processed),
+      ),
+      healthy: fleetStatus.status === "ok",
+    },
+  };
+}
+
+async function fetchFleetStatus(
+  requestJson: JsonHttpRequest,
+): Promise<LibrarianStatusResponse> {
+  return await requestLibraryApiJson<LibrarianStatusResponse>(
+    requestJson,
+    "/fleet-status",
+  );
+}
+
+function buildSigmundStatus(
+  data: LibrarianStatusResponse,
+): FleetLibrarySnapshot["sigmund"] {
+  const status =
+    data.sigmund_status === "online"
+      ? "online"
+      : data.sigmund_status === "offline"
+        ? "offline"
+      : data.status === "ok"
+        ? "online"
+        : "unknown";
+  return {
+    status: status as "online" | "offline" | "unknown",
+    lastIngestAt: data.last_ingest_at ?? null,
+    totalProcessed: numberFromStatus(
+      data.total_processed,
+      numberFromStatus(data.processed),
+    ),
+  };
+}
+
+export async function loadFleetLibraryLive(
+  requestJson: JsonHttpRequest,
+): Promise<FleetLibrarySnapshot> {
+  const teamLibraryRefs = listTeamLibraryRefs();
+  if (teamLibraryRefs.length === 0) {
+    throw new Error(
+      "Team registry config does not define team library refs. Load TEAM_REGISTRY_CONFIG before loading fleet library status.",
+    );
+  }
+  const fleetStatus = await fetchFleetStatus(requestJson);
+
+  return {
+    generatedAt: Date.now(),
+    teams: teamLibraryRefs.map((ref) => buildTeamStatus(ref, fleetStatus)),
+    sigmund: buildSigmundStatus(fleetStatus),
+  };
+}