@radaros/edge 0.3.19

package/dist/index.d.ts

@@ -0,0 +1,427 @@
+import { EventEmitter } from 'node:events';
+import { Agent, Toolkit, ToolDef } from '@radaros/core';
+
+/**
+ * Register all edge/IoT toolkits in the global ToolkitCatalog.
+ * Call this once at startup so they appear in the Admin UI.
+ *
+ * @example
+ * ```ts
+ * import { registerEdgeToolkits } from "@radaros/edge";
+ * registerEdgeToolkits();
+ * ```
+ */
+declare function registerEdgeToolkits(): void;
+
+interface EdgePreset {
+    /** Preset identifier. */
+    id: string;
+    /** Human-readable label. */
+    label: string;
+    /** Recommended Ollama model for this device class. */
+    recommendedModel: string;
+    /** Max tokens to generate per request. */
+    maxTokens: number;
+    /** Max context window (tokens) — limits conversation history. */
+    contextWindow: number;
+    /** Memory budget for the Node.js process in MB. */
+    memoryLimitMb: number;
+    /** Watchdog timeout in ms — restart agent if unresponsive longer than this. */
+    watchdogTimeoutMs: number;
+    /** Resource monitor polling interval in ms. */
+    monitorIntervalMs: number;
+    /** CPU temperature threshold (°C) — start throttling above this. */
+    thermalThrottleC: number;
+    /** Memory usage threshold (0-1) — start shedding tools above this. */
+    memoryThreshold: number;
+    /** Disable heavyweight features on edge by default. */
+    disableFeatures: string[];
+}
+/**
+ * Get an edge configuration preset by device identifier.
+ *
+ * @example
+ * ```ts
+ * const config = edgePreset("pi5-8gb");
+ * console.log(config.recommendedModel); // "phi3:mini"
+ * ```
+ */
+declare function edgePreset(id: string): EdgePreset;
+/** List all available preset IDs and labels. */
+declare function listEdgePresets(): Array<{
+    id: string;
+    label: string;
+}>;
+/** Create a custom preset by overriding fields of an existing one. */
+declare function customEdgePreset(base: string, overrides: Partial<EdgePreset>): EdgePreset;
+
+interface ResourceSnapshot {
+    timestamp: number;
+    cpu: {
+        temperature_c: number | null;
+        usage_percent: number;
+    };
+    memory: {
+        total_bytes: number;
+        used_bytes: number;
+        free_bytes: number;
+        usage_percent: number;
+    };
+    disk: {
+        total_bytes: number;
+        used_bytes: number;
+        free_bytes: number;
+        usage_percent: number;
+    };
+    uptime_seconds: number;
+}
+interface ResourceThresholds {
+    /** CPU temperature (°C) — emit "thermal-warning" above this. */
+    thermalThrottleC: number;
+    /** Memory usage ratio (0-1) — emit "memory-warning" above this. */
+    memoryThreshold: number;
+    /** Disk usage ratio (0-1) — emit "disk-warning" above this. */
+    diskThreshold: number;
+}
+/**
+ * Monitors system resources (CPU, memory, disk, temperature) at a
+ * configurable interval. Emits events when thresholds are exceeded.
+ */
+declare class ResourceMonitor extends EventEmitter {
+    private intervalMs;
+    private thresholds;
+    private timer;
+    private _lastSnapshot;
+    constructor(opts?: {
+        intervalMs?: number;
+        thresholds?: Partial<ResourceThresholds>;
+    });
+    get lastSnapshot(): ResourceSnapshot | null;
+    /** Take a single snapshot right now. */
+    snapshot(): ResourceSnapshot;
+    /** Start periodic monitoring. */
+    start(): void;
+    /** Stop periodic monitoring. */
+    stop(): void;
+    private check;
+}
+
+interface EdgeRuntimeConfig {
+    /** Edge preset ID or custom preset object. */
+    preset: string | EdgePreset;
+    /** Agent instance to manage. */
+    agent: Agent;
+    /** Port for the health check HTTP server (default 9090). */
+    healthPort?: number;
+    /** Disable the health check endpoint. */
+    disableHealthCheck?: boolean;
+    /** Callback when agent is restarted by the watchdog. */
+    onWatchdogRestart?: (reason: string) => void;
+    /** Toolkits that can be shed under memory pressure (by name). */
+    sheddableToolkits?: string[];
+}
+interface EdgeRuntimeStatus {
+    state: "starting" | "running" | "degraded" | "stopped";
+    uptime_ms: number;
+    watchdog_restarts: number;
+    resources: ResourceSnapshot | null;
+    degraded_reason: string | null;
+}
+/**
+ * EdgeRuntime — manages an Agent on constrained edge hardware.
+ *
+ * Features:
+ * - Watchdog: auto-detect unresponsive agent and emit restart event
+ * - Resource Monitor: CPU temp, memory, disk tracking with threshold events
+ * - Graceful degradation: shed non-critical tools under memory pressure
+ * - Health endpoint: lightweight HTTP `/health` for external monitoring
+ */
+declare class EdgeRuntime extends EventEmitter {
+    private config;
+    private preset;
+    private monitor;
+    private healthServer;
+    private watchdogTimer;
+    private lastActivity;
+    private startTime;
+    private watchdogRestarts;
+    private _state;
+    private degradedReason;
+    constructor(config: EdgeRuntimeConfig);
+    get state(): "starting" | "running" | "degraded" | "stopped";
+    /** Start the edge runtime: resource monitor, watchdog, and health endpoint. */
+    start(): Promise<void>;
+    /** Stop the runtime cleanly. */
+    stop(): Promise<void>;
+    /** Signal that the agent is alive — call this from agent hooks. */
+    heartbeat(): void;
+    /** Get current runtime status. */
+    getStatus(): EdgeRuntimeStatus;
+    /** Get the resource monitor for direct access. */
+    getMonitor(): ResourceMonitor;
+    private enterDegraded;
+    private startWatchdog;
+    private stopWatchdog;
+    private startHealthServer;
+}
+
+interface OllamaStatus {
+    running: boolean;
+    version?: string;
+    models?: string[];
+    error?: string;
+}
+interface ModelRecommendation {
+    model: string;
+    label: string;
+    parameterSize: string;
+    ramRequired: number;
+}
+/**
+ * Check whether Ollama is running and accessible.
+ */
+declare function checkOllama(baseUrl?: string): Promise<OllamaStatus>;
+/**
+ * Ensure Ollama is running. If not, attempt to start the `ollama serve` process.
+ * Returns the status after attempting to start.
+ */
+declare function ensureOllama(baseUrl?: string): Promise<OllamaStatus>;
+/**
+ * Pull a model if it's not already cached locally.
+ * Uses the Ollama HTTP API's /api/pull endpoint.
+ */
+declare function pullModel(model: string, opts?: {
+    baseUrl?: string;
+    onProgress?: (status: string) => void;
+}): Promise<{
+    success: boolean;
+    model: string;
+    error?: string;
+}>;
+/**
+ * Recommend the best model for the available RAM.
+ *
+ * @param ramMb - Available RAM in megabytes.
+ * @returns The best model that fits, or the smallest if none fit comfortably.
+ */
+declare function recommendModel(ramMb: number): ModelRecommendation;
+/** List all known model tiers with their RAM requirements. */
+declare function listModelTiers(): ModelRecommendation[];
+/**
+ * Check if a specific model is cached locally.
+ */
+declare function hasModel(model: string, baseUrl?: string): Promise<boolean>;
+
+interface EdgeCloudSyncConfig {
+    /** Cloud server base URL (e.g. "https://api.example.com"). */
+    cloudUrl: string;
+    /** Unique device/edge node identifier. */
+    deviceId: string;
+    /** Auth token for cloud API requests. */
+    authToken?: string;
+    /** Heartbeat interval in ms (default 30000). */
+    heartbeatIntervalMs?: number;
+    /** Local SQLite-like queue directory for offline events (default /tmp/radaros-edge-queue). */
+    queueDir?: string;
+    /** Max queued events before oldest are dropped (default 10000). */
+    maxQueueSize?: number;
+    /** Auto-flush interval in ms — attempt to push queued events (default 60000). */
+    flushIntervalMs?: number;
+}
+/**
+ * EdgeCloudSync — connects an edge device to a cloud RadarOS instance.
+ *
+ * Features:
+ * - Heartbeat: periodic POST with device status and resource metrics
+ * - Config pull: fetch agent/team blueprints from the cloud admin API
+ * - Event push: stream agent run results back to cloud
+ * - Offline-first: queue events locally when cloud is unreachable, flush on reconnect
+ */
+declare class EdgeCloudSync extends EventEmitter {
+    private config;
+    private heartbeatTimer;
+    private flushTimer;
+    private queue;
+    private queueFile;
+    private maxQueueSize;
+    private connected;
+    private backoffMs;
+    private readonly maxBackoff;
+    constructor(config: EdgeCloudSyncConfig);
+    /** Start heartbeat and flush timers. */
+    start(): void;
+    /** Stop all timers. */
+    stop(): void;
+    /** Push an event to the cloud. Queues locally if offline. */
+    pushEvent(type: string, payload: unknown): void;
+    /** Pull agent/team blueprints from the cloud admin API. */
+    pullConfig(): Promise<{
+        agents: unknown[];
+        teams: unknown[];
+        workflows: unknown[];
+    }>;
+    /** Send heartbeat with device status. */
+    sendHeartbeat(resources?: ResourceSnapshot): Promise<void>;
+    /** Attempt to flush all queued events to the cloud. */
+    flush(): Promise<{
+        sent: number;
+        failed: number;
+        remaining: number;
+    }>;
+    get isConnected(): boolean;
+    get queueSize(): number;
+    private cloudGet;
+    private cloudPost;
+    private getHeaders;
+    private onConnected;
+    private onDisconnected;
+    private persistQueue;
+    private loadQueue;
+}
+
+interface BleConfig {
+    /** Default scan timeout in ms (default 5000). */
+    scanTimeout?: number;
+    /** Filter scans to only these service UUIDs. */
+    serviceUuidFilter?: string[];
+}
+/**
+ * BleToolkit — Bluetooth Low Energy scanning and communication.
+ * Requires `@stoprocent/noble` as an optional peer dependency.
+ * Compatible with Raspberry Pi 5 and Pi 4.
+ */
+declare class BleToolkit extends Toolkit {
+    readonly name = "ble";
+    private scanTimeout;
+    private serviceFilter;
+    private connectedPeripherals;
+    constructor(config?: BleConfig);
+    getTools(): ToolDef[];
+    dispose(): void;
+}
+
+interface CameraConfig {
+    /** Default image width (default 1280). */
+    width?: number;
+    /** Default image height (default 720). */
+    height?: number;
+    /** Image rotation in degrees: 0, 90, 180, 270 (default 0). */
+    rotation?: number;
+    /** Output directory for captured images/videos (default /tmp/radaros-camera). */
+    outputDir?: string;
+    /** Output format: "jpg" | "png" (default "jpg"). */
+    format?: "jpg" | "png";
+}
+/**
+ * CameraToolkit — capture photos and video using `libcamera-still` / `libcamera-vid`.
+ * Most reliable approach for Raspberry Pi 5 and Pi Camera Module 3.
+ * Falls back to `raspistill` / `raspivid` if libcamera is not available.
+ */
+declare class CameraToolkit extends Toolkit {
+    readonly name = "camera";
+    private width;
+    private height;
+    private rotation;
+    private outputDir;
+    private format;
+    private streamProcess;
+    constructor(config?: CameraConfig);
+    private getCaptureCommand;
+    private getVideoCommand;
+    getTools(): ToolDef[];
+    dispose(): void;
+}
+
+interface GpioConfig {
+    /** GPIO chip number. Use 4 for Pi 5, 0 for Pi 4 and earlier. Default: 0. */
+    chipNumber?: number;
+    /** Allowlist of pin numbers agents may access. Empty = all pins allowed. */
+    allowedPins?: number[];
+    /** Max software PWM frequency in Hz (default 1000). */
+    maxPwmFrequency?: number;
+}
+/**
+ * GpioToolkit — Raspberry Pi GPIO control via node-libgpiod.
+ * Compatible with Pi 5 (chip 4) and Pi 4 (chip 0).
+ *
+ * Requires `node-libgpiod` as an optional peer dependency.
+ */
+declare class GpioToolkit extends Toolkit {
+    readonly name = "gpio";
+    private chipNumber;
+    private allowedPins;
+    private maxPwmFreq;
+    private activeWatchers;
+    constructor(config?: GpioConfig);
+    private assertPinAllowed;
+    getTools(): ToolDef[];
+    /** Stop all active watchers. */
+    dispose(): void;
+}
+
+interface SensorConfig {
+    /** I2C bus number (default 1 — standard on all Pi models). */
+    busNumber?: number;
+    /** Override addresses for known sensor types. */
+    addresses?: {
+        bme280?: number;
+        bmp180?: number;
+    };
+}
+/**
+ * SensorToolkit — read I2C sensors (BME280, BMP180, DHT22) on Raspberry Pi.
+ * Requires `i2c-bus` as an optional peer dependency.
+ */
+declare class SensorToolkit extends Toolkit {
+    readonly name = "sensor";
+    private busNumber;
+    private bme280Addr;
+    constructor(config?: SensorConfig);
+    getTools(): ToolDef[];
+}
+
+interface ServoConfig {
+    /** GPIO pin number for the servo signal. */
+    pin: number;
+    /** GPIO chip number (default 0, use 4 for Pi 5). */
+    chipNumber?: number;
+    /** Minimum pulse width in microseconds (default 500). */
+    minPulseUs?: number;
+    /** Maximum pulse width in microseconds (default 2500). */
+    maxPulseUs?: number;
+    /** PWM frequency in Hz (default 50 — standard for servos). */
+    frequency?: number;
+}
+/**
+ * ServoToolkit — control hobby servos via GPIO PWM on Raspberry Pi.
+ * Requires `node-libgpiod` as an optional peer dependency.
+ */
+declare class ServoToolkit extends Toolkit {
+    readonly name = "servo";
+    private pin;
+    private chipNumber;
+    private minPulseUs;
+    private maxPulseUs;
+    private frequency;
+    constructor(config: ServoConfig);
+    private pulseForDuration;
+    getTools(): ToolDef[];
+}
+
+interface SystemConfig {
+    /** Include per-process info in process list (default false — can be slow). */
+    includeProcessDetails?: boolean;
+}
+/**
+ * SystemToolkit — zero-dependency system information tools.
+ * Reads from `/proc/`, `/sys/`, and the Node.js `os` module.
+ * Works on Linux (Raspberry Pi) and degrades gracefully on macOS/Windows.
+ */
+declare class SystemToolkit extends Toolkit {
+    readonly name = "system";
+    private includeProcessDetails;
+    constructor(config?: SystemConfig);
+    getTools(): ToolDef[];
+}
+
+export { type BleConfig, BleToolkit, type CameraConfig, CameraToolkit, EdgeCloudSync, type EdgeCloudSyncConfig, type EdgePreset, EdgeRuntime, type EdgeRuntimeConfig, type EdgeRuntimeStatus, type GpioConfig, GpioToolkit, type ModelRecommendation, type OllamaStatus, ResourceMonitor, type ResourceSnapshot, type ResourceThresholds, type SensorConfig, SensorToolkit, type ServoConfig, ServoToolkit, type SystemConfig, SystemToolkit, checkOllama, customEdgePreset, edgePreset, ensureOllama, hasModel, listEdgePresets, listModelTiers, pullModel, recommendModel, registerEdgeToolkits };