pi-smart-router 0.1.0

package/src/infrastructure/hardware/hardware-probe.ts

@@ -0,0 +1,276 @@
+/**
+ * Hardware probe — T044, FR-012.
+ *
+ * Three-state gate: inspects platform/arch, unified memory, and battery
+ * to return `full_local`, `classification_only`, or `disabled`.
+ *
+ * Pure function of SystemInfo × config; side-effect-free for testability.
+ * Default SystemInfo provider reads from Node.js `os` and platform-specific
+ * power sources (macOS pmset, Linux /sys/class/power_supply, Windows WMI).
+ */
+
+import * as os from 'node:os';
+import { execSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export type HardwareProbeResult = 'full_local' | 'classification_only' | 'disabled';
+
+export interface HardwareProbeConfig {
+  readonly min_memory_gb_full: number;
+  readonly min_memory_gb_classification: number;
+  readonly battery_threshold_pct: number;
+}
+
+export interface SystemInfo {
+  readonly totalMemoryGb: number;
+  readonly arch: string;
+  readonly platform: NodeJS.Platform;
+  readonly batteryLevel: number | null;
+  readonly isOnAcPower: boolean | null;
+}
+
+/** Port for dependency injection in tests. */
+export interface SystemInfoPort {
+  getSystemInfo(): Promise<SystemInfo>;
+}
+
+// ─── Pure probe logic ────────────────────────────────────────────────────────
+
+function isSupportedPlatform(info: SystemInfo): boolean {
+  if (info.platform === 'darwin' && info.arch === 'arm64') {
+    return true;
+  }
+  if (info.platform === 'linux' && (info.arch === 'x64' || info.arch === 'arm64')) {
+    return true;
+  }
+  if (info.platform === 'win32' && (info.arch === 'x64' || info.arch === 'arm64')) {
+    return true;
+  }
+  return false;
+}
+
+export function probeHardware(
+  config: HardwareProbeConfig,
+  info: SystemInfo,
+): HardwareProbeResult {
+  if (!isSupportedPlatform(info)) {
+    return 'disabled';
+  }
+
+  if (
+    info.isOnAcPower === false &&
+    info.batteryLevel !== null &&
+    info.batteryLevel < config.battery_threshold_pct
+  ) {
+    return 'disabled';
+  }
+
+  if (info.totalMemoryGb >= config.min_memory_gb_full) {
+    return 'full_local';
+  }
+
+  if (info.totalMemoryGb >= config.min_memory_gb_classification) {
+    return 'classification_only';
+  }
+
+  return 'disabled';
+}
+
+// ─── Platform-specific system info providers ───────────────────────────────
+
+function parseBatteryInfo(output: string): {
+  batteryLevel: number | null;
+  isOnAcPower: boolean;
+} {
+  const pctMatch = /(\d+)%/.exec(output);
+  const batteryLevel = pctMatch?.[1] !== undefined
+    ? parseInt(pctMatch[1], 10)
+    : null;
+  const isOnAcPower = output.includes('AC Power');
+  return { batteryLevel, isOnAcPower };
+}
+
+function readLinuxPowerInfo(): {
+  batteryLevel: number | null;
+  isOnAcPower: boolean | null;
+} {
+  const powerSupplyDir = '/sys/class/power_supply';
+  if (!existsSync(powerSupplyDir)) {
+    return { batteryLevel: null, isOnAcPower: true };
+  }
+
+  try {
+    const entries = readdirSync(powerSupplyDir);
+    let batteryLevel: number | null = null;
+    let isOnAcPower: boolean | null = null;
+
+    for (const name of entries) {
+      const base = join(powerSupplyDir, name);
+      const typePath = join(base, 'type');
+      if (!existsSync(typePath)) {
+        continue;
+      }
+
+      const type = readFileSync(typePath, 'utf8').trim();
+      if (type !== 'Battery') {
+        continue;
+      }
+
+      const capacityPath = join(base, 'capacity');
+      if (existsSync(capacityPath)) {
+        const capacity = parseInt(readFileSync(capacityPath, 'utf8').trim(), 10);
+        if (!Number.isNaN(capacity)) {
+          batteryLevel = capacity;
+        }
+      }
+
+      const statusPath = join(base, 'status');
+      if (existsSync(statusPath)) {
+        const status = readFileSync(statusPath, 'utf8').trim();
+        isOnAcPower = status === 'Charging' || status === 'Full' || status === 'Not charging';
+      }
+      break;
+    }
+
+    if (batteryLevel === null && isOnAcPower === null) {
+      return { batteryLevel: null, isOnAcPower: true };
+    }
+
+    return { batteryLevel, isOnAcPower };
+  } catch {
+    return { batteryLevel: null, isOnAcPower: true };
+  }
+}
+
+function buildBaseSystemInfo(): Pick<SystemInfo, 'totalMemoryGb' | 'arch' | 'platform'> {
+  return {
+    totalMemoryGb: os.totalmem() / 1024 ** 3,
+    arch: os.arch(),
+    platform: os.platform(),
+  };
+}
+
+const macOsSystemInfoPort: SystemInfoPort = {
+  async getSystemInfo(): Promise<SystemInfo> {
+    let batteryLevel: number | null = null;
+    let isOnAcPower: boolean | null = null;
+
+    try {
+      const output = execSync('pmset -g batt', {
+        timeout: 2000,
+        encoding: 'utf8',
+      });
+      const parsed = parseBatteryInfo(output);
+      batteryLevel = parsed.batteryLevel;
+      isOnAcPower = parsed.isOnAcPower;
+    } catch {
+      isOnAcPower = true;
+    }
+
+    return {
+      ...buildBaseSystemInfo(),
+      batteryLevel,
+      isOnAcPower,
+    };
+  },
+};
+
+const linuxSystemInfoPort: SystemInfoPort = {
+  async getSystemInfo(): Promise<SystemInfo> {
+    const power = readLinuxPowerInfo();
+    return {
+      ...buildBaseSystemInfo(),
+      batteryLevel: power.batteryLevel,
+      isOnAcPower: power.isOnAcPower,
+    };
+  },
+};
+
+function readWindowsPowerInfo(): {
+  batteryLevel: number | null;
+  isOnAcPower: boolean | null;
+} {
+  try {
+    const output = execSync(
+      'powershell -NoProfile -Command "Get-CimInstance -ClassName Win32_Battery -ErrorAction SilentlyContinue | Select-Object -First 1 EstimatedChargeRemaining, BatteryStatus | ConvertTo-Json -Compress"',
+      { timeout: 3000, encoding: 'utf8' },
+    ).trim();
+
+    if (!output) {
+      return { batteryLevel: null, isOnAcPower: true };
+    }
+
+    const parsed = JSON.parse(output) as {
+      EstimatedChargeRemaining?: number;
+      BatteryStatus?: number;
+    };
+
+    const batteryLevel = typeof parsed.EstimatedChargeRemaining === 'number'
+      ? parsed.EstimatedChargeRemaining
+      : null;
+
+    let isOnAcPower: boolean | null = null;
+    if (typeof parsed.BatteryStatus === 'number') {
+      // 1 = discharging; other values indicate AC/charging/full states.
+      isOnAcPower = parsed.BatteryStatus !== 1;
+    }
+
+    if (batteryLevel === null && isOnAcPower === null) {
+      return { batteryLevel: null, isOnAcPower: true };
+    }
+
+    return { batteryLevel, isOnAcPower };
+  } catch {
+    return { batteryLevel: null, isOnAcPower: true };
+  }
+}
+
+const windowsSystemInfoPort: SystemInfoPort = {
+  async getSystemInfo(): Promise<SystemInfo> {
+    const power = readWindowsPowerInfo();
+    return {
+      ...buildBaseSystemInfo(),
+      batteryLevel: power.batteryLevel,
+      isOnAcPower: power.isOnAcPower,
+    };
+  },
+};
+
+const genericSystemInfoPort: SystemInfoPort = {
+  async getSystemInfo(): Promise<SystemInfo> {
+    return {
+      ...buildBaseSystemInfo(),
+      batteryLevel: null,
+      isOnAcPower: null,
+    };
+  },
+};
+
+export function getDefaultSystemInfoPort(): SystemInfoPort {
+  switch (os.platform()) {
+    case 'darwin':
+      return macOsSystemInfoPort;
+    case 'linux':
+      return linuxSystemInfoPort;
+    case 'win32':
+      return windowsSystemInfoPort;
+    default:
+      return genericSystemInfoPort;
+  }
+}
+
+export async function getDefaultSystemInfo(): Promise<SystemInfo> {
+  return getDefaultSystemInfoPort().getSystemInfo();
+}
+
+// ─── Convenience: probe with real system info ────────────────────────────────
+
+export async function probeHardwareDefault(
+  config: HardwareProbeConfig,
+): Promise<HardwareProbeResult> {
+  const info = await getDefaultSystemInfo();
+  return probeHardware(config, info);
+}

package/src/infrastructure/local/local-zero-tier.ts

@@ -0,0 +1,151 @@
+/**
+ * Local zero-tier readiness pings — T045, FR-012, FR-013.
+ *
+ * Pings LM Studio and Ollama HTTP endpoints in parallel to determine
+ * whether a local model is loaded and ready. Combined latency target <15ms.
+ *
+ * Never throws — unreachable services return `available: false`.
+ * Port-based HTTP for testability; default uses Node.js global fetch.
+ */
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface ServicePingResult {
+  readonly available: boolean;
+  readonly hasLoadedModel: boolean;
+  readonly latencyMs: number;
+}
+
+export interface LocalReadinessResult {
+  readonly lmStudio: ServicePingResult;
+  readonly ollama: ServicePingResult;
+  readonly anyModelReady: boolean;
+  readonly combinedLatencyMs: number;
+}
+
+export interface LocalZeroTierConfig {
+  readonly lmStudioBaseUrl: string;
+  readonly ollamaBaseUrl: string;
+  readonly pingTimeoutMs: number;
+}
+
+/** Port for HTTP fetch — allows stubbing in tests without network. */
+export interface HttpFetchPort {
+  fetch(url: string, init: { signal: AbortSignal }): Promise<{
+    ok: boolean;
+    json(): Promise<unknown>;
+  }>;
+}
+
+// ─── Defaults ────────────────────────────────────────────────────────────────
+
+export const DEFAULT_LOCAL_CONFIG: LocalZeroTierConfig = {
+  lmStudioBaseUrl: 'http://127.0.0.1:1234',
+  ollamaBaseUrl: 'http://127.0.0.1:11434',
+  pingTimeoutMs: 500,
+};
+
+const UNAVAILABLE: ServicePingResult = {
+  available: false,
+  hasLoadedModel: false,
+  latencyMs: 0,
+};
+
+// ─── Ping implementations ────────────────────────────────────────────────────
+
+interface LmStudioModelsResponse {
+  data?: readonly unknown[];
+}
+
+interface OllamaTagsResponse {
+  models?: readonly unknown[];
+}
+
+async function pingLmStudio(
+  baseUrl: string,
+  signal: AbortSignal,
+  httpFetch: HttpFetchPort,
+): Promise<ServicePingResult> {
+  const start = performance.now();
+  try {
+    const res = await httpFetch.fetch(`${baseUrl}/v1/models`, { signal });
+    const latencyMs = performance.now() - start;
+    if (!res.ok) {
+      return { available: true, hasLoadedModel: false, latencyMs };
+    }
+    const body = (await res.json()) as LmStudioModelsResponse;
+    const hasLoadedModel = Array.isArray(body.data) && body.data.length > 0;
+    return { available: true, hasLoadedModel, latencyMs };
+  } catch {
+    return { ...UNAVAILABLE, latencyMs: performance.now() - start };
+  }
+}
+
+async function pingOllama(
+  baseUrl: string,
+  signal: AbortSignal,
+  httpFetch: HttpFetchPort,
+): Promise<ServicePingResult> {
+  const start = performance.now();
+  try {
+    const res = await httpFetch.fetch(`${baseUrl}/api/tags`, { signal });
+    const latencyMs = performance.now() - start;
+    if (!res.ok) {
+      return { available: true, hasLoadedModel: false, latencyMs };
+    }
+    const body = (await res.json()) as OllamaTagsResponse;
+    const hasLoadedModel = Array.isArray(body.models) && body.models.length > 0;
+    return { available: true, hasLoadedModel, latencyMs };
+  } catch {
+    return { ...UNAVAILABLE, latencyMs: performance.now() - start };
+  }
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Default HTTP fetch port using Node.js global fetch.
+ */
+export const defaultHttpFetch: HttpFetchPort = {
+  fetch: (url, init) => globalThis.fetch(url, init),
+};
+
+/**
+ * Ping LM Studio and Ollama in parallel. Returns readiness state for each
+ * service and whether any local model is loaded and ready for inference.
+ *
+ * Combined latency target: <15ms on a healthy system.
+ */
+export async function pingLocalServices(
+  config: LocalZeroTierConfig = DEFAULT_LOCAL_CONFIG,
+  httpFetch: HttpFetchPort = defaultHttpFetch,
+): Promise<LocalReadinessResult> {
+  const overallStart = performance.now();
+  const controller = new AbortController();
+  const timeout = setTimeout(
+    () => controller.abort(),
+    config.pingTimeoutMs,
+  );
+
+  try {
+    const [lmStudio, ollama] = await Promise.all([
+      pingLmStudio(config.lmStudioBaseUrl, controller.signal, httpFetch),
+      pingOllama(config.ollamaBaseUrl, controller.signal, httpFetch),
+    ]);
+
+    const combinedLatencyMs = performance.now() - overallStart;
+    const anyModelReady = lmStudio.hasLoadedModel || ollama.hasLoadedModel;
+
+    return { lmStudio, ollama, anyModelReady, combinedLatencyMs };
+  } catch {
+    // FR-022: never crash — return both unavailable on unexpected error
+    return {
+      lmStudio: UNAVAILABLE,
+      ollama: UNAVAILABLE,
+      anyModelReady: false,
+      combinedLatencyMs: performance.now() - overallStart,
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}

package/src/infrastructure/persistence/memory-store.ts

@@ -0,0 +1,122 @@
+/**
+ * In-memory persistence store — fallback when SQLite is unavailable.
+ *
+ * Implements StorePort for process-local state. Data does not survive
+ * process restart. Used as a safety net per FR-025: when the SQLite
+ * state store is unavailable, degrade to in-memory rather than crash.
+ */
+
+import type { ModelProfile, PriceCatalog, RoutingDatasetRecord, RoutingOutcomeRecord, RoutingTelemetry, SessionPin } from '../../domain/types/entities.js';
+import type { ListDatasetOptions, ListOutcomeOptions, ListTelemetryOptions, StorePort } from '../../domain/types/store-port.js';
+import {
+  DEFAULT_HISTORY_LIMIT,
+  MAX_HISTORY_LIMIT,
+  TELEMETRY_MAX_ENTRIES,
+  makeTelemetryRoom,
+} from '../telemetry/telemetry-limits.js';
+import {
+  makeDatasetRoom,
+} from '../telemetry/dataset-limits.js';
+import {
+  makeOutcomeRoom,
+} from '../telemetry/outcome-limits.js';
+
+export class MemoryStore implements StorePort {
+  private readonly pins = new Map<string, SessionPin>();
+  private readonly models: readonly ModelProfile[];
+  private priceCatalog: PriceCatalog | null = null;
+  private readonly telemetry: RoutingTelemetry[] = [];
+  private readonly dataset: RoutingDatasetRecord[] = [];
+  private readonly outcomes: RoutingOutcomeRecord[] = [];
+
+  constructor(models: readonly ModelProfile[] = []) {
+    this.models = models;
+  }
+
+  async getSessionPin(sessionId: string): Promise<SessionPin | null> {
+    return this.pins.get(sessionId) ?? null;
+  }
+
+  async putSessionPin(pin: SessionPin): Promise<void> {
+    this.pins.set(pin.session_id, pin);
+  }
+
+  async deleteSessionPin(sessionId: string): Promise<void> {
+    this.pins.delete(sessionId);
+  }
+
+  async getModelProfiles(): Promise<readonly ModelProfile[]> {
+    return this.models;
+  }
+
+  async getPriceCatalog(): Promise<PriceCatalog | null> {
+    return this.priceCatalog;
+  }
+
+  async putPriceCatalog(catalog: PriceCatalog): Promise<void> {
+    this.priceCatalog = catalog;
+  }
+
+  appendTelemetry(entry: RoutingTelemetry): void {
+    makeTelemetryRoom(this.telemetry, TELEMETRY_MAX_ENTRIES);
+    this.telemetry.push(entry);
+  }
+
+  async listTelemetry(options?: ListTelemetryOptions): Promise<readonly RoutingTelemetry[]> {
+    const limit = clampHistoryLimit(options?.limit);
+    const sessionId = options?.sessionId;
+
+    const filtered = sessionId
+      ? this.telemetry.filter((entry) => entry.session_id === sessionId)
+      : this.telemetry;
+
+    return [...filtered]
+      .reverse()
+      .slice(0, limit);
+  }
+
+  appendDatasetRecord(entry: RoutingDatasetRecord): void {
+    makeDatasetRoom(this.dataset);
+    this.dataset.push(entry);
+  }
+
+  async listDatasetRecords(
+    options?: ListDatasetOptions,
+  ): Promise<readonly RoutingDatasetRecord[]> {
+    const limit = clampHistoryLimit(options?.limit);
+
+    return [...this.dataset]
+      .reverse()
+      .slice(0, limit);
+  }
+
+  appendOutcomeRecord(entry: RoutingOutcomeRecord): void {
+    makeOutcomeRoom(this.outcomes);
+    this.outcomes.push(entry);
+  }
+
+  async listOutcomeRecords(
+    options?: ListOutcomeOptions,
+  ): Promise<readonly RoutingOutcomeRecord[]> {
+    const limit = clampHistoryLimit(options?.limit);
+    const requestId = options?.requestId;
+    const sessionId = options?.sessionId;
+
+    const filtered = requestId
+      ? this.outcomes.filter((entry) => entry.request_id === requestId)
+      : sessionId
+        ? this.outcomes.filter((entry) => entry.session_id === sessionId)
+        : this.outcomes;
+
+    return [...filtered]
+      .reverse()
+      .slice(0, limit);
+  }
+}
+
+function clampHistoryLimit(limit: number | undefined): number {
+  if (limit === undefined) {
+    return DEFAULT_HISTORY_LIMIT;
+  }
+  return Math.min(Math.max(1, Math.floor(limit)), MAX_HISTORY_LIMIT);
+}