@theaiinc/yggdrasil-ratatoskr 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 The AI Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# @theaiinc/yggdrasil-ratatoskr
+
+Lightweight discovery and heartbeat daemon for Yggdrasil runner registration.
+
+Ratatoskr runs alongside an agent runner and continuously informs Yggdrasil about:
+
+- Runner availability
+- Network endpoints
+- Capabilities
+- Health status
+- IP changes
+- Shutdown events
+
+## Installation
+
+```bash
+npm install @theaiinc/yggdrasil-ratatoskr
+```
+
+## Quick Start
+
+```typescript
+import { Ratatoskr } from '@theaiinc/yggdrasil-ratatoskr';
+
+const ratatoskr = new Ratatoskr({
+  yggdrasilUrl: 'http://localhost:4000',
+});
+
+await ratatoskr.start();
+```
+
+Within seconds, Yggdrasil automatically knows that the runner exists, where it lives, what it can do, and whether it is healthy.
+
+## Advanced Usage
+
+```typescript
+import { Ratatoskr } from '@theaiinc/yggdrasil-ratatoskr';
+
+const ratatoskr = new Ratatoskr({
+  runnerId: 'runner-a',
+  name: 'MacBook Pro',
+  yggdrasilUrl: 'http://yggdrasil.prod:4000',
+  capabilities: ['browser', 'computer-use', 'llm'],
+  heartbeatInterval: 30,
+  leaseTtl: 60,
+  detectPublicIp: false,
+  endpointProvider: async () => {
+    return 'http://192.168.1.5:8080';
+  },
+  healthProvider: async () => {
+    return {
+      status: 'healthy',
+    };
+  },
+});
+
+await ratatoskr.start();
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `runnerId` | `string` | Auto-generated | Unique runner identifier |
+| `name` | `string` | `'unknown'` | Human-readable runner name |
+| `yggdrasilUrl` | `string` | (required) | Yggdrasil server URL |
+| `capabilities` | `string[]` | `[]` | List of runner capabilities |
+| `heartbeatInterval` | `number` | `30` | Heartbeat interval in seconds |
+| `leaseTtl` | `number` | `60` | Lease TTL in seconds |
+| `detectLocalIp` | `boolean` | `true` | Auto-detect local IP |
+| `detectPublicIp` | `boolean` | `false` | Auto-detect public IP |
+| `endpointProvider` | `() => Promise<string>` | `undefined` | Custom endpoint resolver |
+| `healthProvider` | `() => Promise<HealthResult>` | `undefined` | Custom health check |
+| `labels` | `Record<string, string>` | `{}` | Additional labels |
+| `metadata` | `Record<string, unknown>` | `{}` | Additional metadata |
+
+## Architecture
+
+```
+yggdrasil-ratatoskr
+│
+├── ratatoskr.ts          # Main entry point
+├── types/                # TypeScript interfaces and enums
+├── transports/           # Transport abstraction (HTTP, WebSocket, etc.)
+│   └── http-transport.ts # HTTP transport implementation
+└── services/
+    ├── registrar.ts           # Runner registration lifecycle
+    ├── heartbeat-sender.ts    # Periodic heartbeat sender
+    ├── endpoint-detector.ts   # IP/hostname change detection
+    ├── health-monitor.ts      # Health check orchestration
+    ├── lease-manager.ts       # Lease expiry tracking
+    └── retry-manager.ts       # Exponential backoff retry
+```
+
+## How It Works
+
+1. **`ratatoskr.start()`** — Registers the runner with Yggdrasil, begins heartbeats, starts monitoring IP and lease expiry, and registers shutdown handlers.
+2. **Heartbeats** — Sent every 30 seconds (configurable) to confirm the runner is alive.
+3. **Lease** — Each registration has a 60-second TTL. If Yggdrasil misses 2 heartbeats (~60s), the runner is marked `offline`.
+4. **IP Changes** — Detected every 10 seconds; if the local IP changes, Yggdrasil is notified via `POST /runners/update`.
+5. **Graceful Shutdown** — On SIGTERM/SIGINT, Ratatoskr deregisters the runner with `POST /runners/offline`.
+
+## Reliability
+
+Ratatoskr is designed to survive:
+
+- Temporary network outages
+- Yggdrasil restarts
+- IP changes
+- Laptop sleep/wake cycles
+- Docker container restarts
+
+It uses exponential backoff for retries, persistent runner IDs, and automatic re-registration.
+
+## API Endpoints (Yggdrasil)
+
+Ratatoskr expects these endpoints on the Yggdrasil server:
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `POST` | `/runners/register` | Register a new runner |
+| `POST` | `/runners/heartbeat` | Send a heartbeat |
+| `POST` | `/runners/update` | Update runner endpoint |
+| `POST` | `/runners/offline` | Deregister a runner |
+
+## License
+
+MIT

package/dist/src/index.d.ts

@@ -0,0 +1,12 @@
+export { Ratatoskr } from './ratatoskr.js';
+export { HttpTransport } from './transports/http-transport.js';
+export { EndpointDetector } from './services/endpoint-detector.js';
+export { HealthMonitor } from './services/health-monitor.js';
+export { HeartbeatSender } from './services/heartbeat-sender.js';
+export { LeaseManager } from './services/lease-manager.js';
+export { Registrar } from './services/registrar.js';
+export { RetryManager } from './services/retry-manager.js';
+export type { Transport } from './types/index.js';
+export type { RatatoskrConfig, RatatoskrState, RunnerRegistration, HeartbeatPayload, EndpointUpdatePayload, DeregisterPayload, HealthResult, } from './types/index.js';
+export { RunnerHealth } from './types/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAG3D,YAAY,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EACV,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,YAAY,GACb,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,11 @@
+export { Ratatoskr } from './ratatoskr.js';
+export { HttpTransport } from './transports/http-transport.js';
+export { EndpointDetector } from './services/endpoint-detector.js';
+export { HealthMonitor } from './services/health-monitor.js';
+export { HeartbeatSender } from './services/heartbeat-sender.js';
+export { LeaseManager } from './services/lease-manager.js';
+export { Registrar } from './services/registrar.js';
+export { RetryManager } from './services/retry-manager.js';
+// Export enum
+export { RunnerHealth } from './types/index.js';
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAc3D,cAAc;AACd,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/src/ratatoskr.d.ts

@@ -0,0 +1,71 @@
+import type { RatatoskrConfig, RatatoskrState, HealthResult } from './types/index.js';
+/**
+ * Ratatoskr — Lightweight discovery and heartbeat daemon.
+ *
+ * Runs alongside an agent runner and continuously informs Yggdrasil about
+ * runner availability, network endpoints, capabilities, health status,
+ * IP changes, and shutdown events.
+ */
+export declare class Ratatoskr {
+    private readonly config;
+    private readonly state;
+    private readonly transport;
+    private readonly endpointDetector;
+    private readonly healthMonitor;
+    private readonly leaseManager;
+    private readonly retryManager;
+    private readonly registrar;
+    private readonly heartbeatSender;
+    private endpointCheckTimer;
+    private leaseCheckTimer;
+    private shutdownHandlers;
+    private started;
+    constructor(config: RatatoskrConfig);
+    /**
+     * Start the Ratatoskr daemon.
+     *
+     * 1. Registers the runner with Yggdrasil
+     * 2. Begins sending heartbeats
+     * 3. Monitors for IP changes
+     * 4. Monitors lease expiry for re-registration
+     * 5. Registers shutdown handlers for graceful deregistration
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the Ratatoskr daemon and deregister from Yggdrasil.
+     */
+    stop(): Promise<void>;
+    /**
+     * Set a custom health provider.
+     */
+    setHealthProvider(provider: () => Promise<HealthResult>): void;
+    /**
+     * Returns the current runner state.
+     */
+    getState(): Readonly<RatatoskrState>;
+    /**
+     * Returns whether the daemon is currently running.
+     */
+    isRunning(): boolean;
+    /**
+     * Returns whether the runner is registered with Yggdrasil.
+     */
+    isRegistered(): boolean;
+    /**
+     * Check for endpoint changes and notify Yggdrasil if detected.
+     */
+    private checkEndpoint;
+    /**
+     * Register handlers for SIGTERM and SIGINT.
+     */
+    private registerShutdownHandlers;
+    /**
+     * Resolve the provided config with defaults.
+     */
+    private resolveConfig;
+    /**
+     * Initialize the internal state.
+     */
+    private initializeState;
+}
+//# sourceMappingURL=ratatoskr.d.ts.map

package/dist/src/ratatoskr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ratatoskr.d.ts","sourceRoot":"","sources":["../../src/ratatoskr.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,YAAY,EACb,MAAM,kBAAkB,CAAC;AAW1B;;;;;;GAMG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IACpD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,kBAAkB,CAA6C;IACvE,OAAO,CAAC,eAAe,CAA6C;IACpE,OAAO,CAAC,gBAAgB,CAAsB;IAC9C,OAAO,CAAC,OAAO,CAAkB;gBAErB,MAAM,EAAE,eAAe;IA0CnC;;;;;;;;OAQG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA6B5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB3B;;OAEG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;IAI9D;;OAEG;IACH,QAAQ,IAAI,QAAQ,CAAC,cAAc,CAAC;IAIpC;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,YAAY,IAAI,OAAO;IAIvB;;OAEG;YACW,aAAa;IAO3B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAchC;;OAEG;IACH,OAAO,CAAC,aAAa;IAmBrB;;OAEG;IACH,OAAO,CAAC,eAAe;CAUxB"}

package/dist/src/ratatoskr.js

@@ -0,0 +1,179 @@
+import { nanoid } from 'nanoid';
+import { RunnerHealth } from './types/index.js';
+import { HttpTransport } from './transports/http-transport.js';
+import { EndpointDetector } from './services/endpoint-detector.js';
+import { HealthMonitor } from './services/health-monitor.js';
+import { HeartbeatSender } from './services/heartbeat-sender.js';
+import { LeaseManager } from './services/lease-manager.js';
+import { Registrar } from './services/registrar.js';
+import { RetryManager } from './services/retry-manager.js';
+/**
+ * Ratatoskr — Lightweight discovery and heartbeat daemon.
+ *
+ * Runs alongside an agent runner and continuously informs Yggdrasil about
+ * runner availability, network endpoints, capabilities, health status,
+ * IP changes, and shutdown events.
+ */
+export class Ratatoskr {
+    config;
+    state;
+    transport;
+    endpointDetector;
+    healthMonitor;
+    leaseManager;
+    retryManager;
+    registrar;
+    heartbeatSender;
+    endpointCheckTimer;
+    leaseCheckTimer;
+    shutdownHandlers = [];
+    started = false;
+    constructor(config) {
+        this.config = this.resolveConfig(config);
+        this.state = this.initializeState();
+        this.transport = new HttpTransport(this.config.yggdrasilUrl, this.config.apiKey);
+        this.endpointDetector = new EndpointDetector(8080, this.config.detectPublicIp);
+        this.healthMonitor = new HealthMonitor();
+        if (config.healthProvider) {
+            this.healthMonitor.setHealthProvider(config.healthProvider);
+        }
+        this.leaseManager = new LeaseManager(this.config.leaseTtl);
+        this.retryManager = new RetryManager();
+        this.registrar = new Registrar(this.transport, this.endpointDetector, this.retryManager, this.leaseManager, this.state.runnerId, this.state.runnerName, this.config.capabilities, this.config.labels, this.config.metadata);
+        this.heartbeatSender = new HeartbeatSender(this.transport, this.healthMonitor, this.retryManager, this.state.runnerId, this.config.heartbeatInterval);
+    }
+    /**
+     * Start the Ratatoskr daemon.
+     *
+     * 1. Registers the runner with Yggdrasil
+     * 2. Begins sending heartbeats
+     * 3. Monitors for IP changes
+     * 4. Monitors lease expiry for re-registration
+     * 5. Registers shutdown handlers for graceful deregistration
+     */
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+        if (this.config.endpointProvider) {
+            const customEndpoint = await this.config.endpointProvider();
+            this.endpointDetector.setEndpoint(customEndpoint);
+        }
+        // 1. Register with Yggdrasil
+        await this.registrar.register();
+        // 2. Start heartbeats
+        this.heartbeatSender.start();
+        // 3. Monitor IP changes
+        this.endpointCheckTimer = setInterval(() => {
+            this.checkEndpoint();
+        }, 10_000);
+        // 4. Monitor lease expiry
+        this.leaseCheckTimer = setInterval(() => {
+            this.registrar.renewIfNeeded();
+        }, 5_000);
+        // 5. Register shutdown handlers
+        this.registerShutdownHandlers();
+    }
+    /**
+     * Stop the Ratatoskr daemon and deregister from Yggdrasil.
+     */
+    async stop() {
+        if (!this.started)
+            return;
+        this.started = false;
+        // Stop periodic checks
+        if (this.endpointCheckTimer !== undefined) {
+            clearInterval(this.endpointCheckTimer);
+            this.endpointCheckTimer = undefined;
+        }
+        if (this.leaseCheckTimer !== undefined) {
+            clearInterval(this.leaseCheckTimer);
+            this.leaseCheckTimer = undefined;
+        }
+        // Stop heartbeats
+        this.heartbeatSender.stop();
+        // Deregister from Yggdrasil
+        await this.registrar.deregister();
+    }
+    /**
+     * Set a custom health provider.
+     */
+    setHealthProvider(provider) {
+        this.healthMonitor.setHealthProvider(provider);
+    }
+    /**
+     * Returns the current runner state.
+     */
+    getState() {
+        return { ...this.state };
+    }
+    /**
+     * Returns whether the daemon is currently running.
+     */
+    isRunning() {
+        return this.started;
+    }
+    /**
+     * Returns whether the runner is registered with Yggdrasil.
+     */
+    isRegistered() {
+        return this.registrar.isRegistered();
+    }
+    /**
+     * Check for endpoint changes and notify Yggdrasil if detected.
+     */
+    async checkEndpoint() {
+        const update = await this.endpointDetector.detect();
+        if (update !== null) {
+            await this.registrar.updateEndpoint(update);
+        }
+    }
+    /**
+     * Register handlers for SIGTERM and SIGINT.
+     */
+    registerShutdownHandlers() {
+        const handler = async () => {
+            await this.stop();
+        };
+        process.on('SIGTERM', handler);
+        process.on('SIGINT', handler);
+        this.shutdownHandlers.push(() => {
+            process.removeListener('SIGTERM', handler);
+            process.removeListener('SIGINT', handler);
+        });
+    }
+    /**
+     * Resolve the provided config with defaults.
+     */
+    resolveConfig(config) {
+        return {
+            runnerId: config.runnerId ?? `runner-${nanoid(8)}`,
+            name: config.name ?? 'unknown',
+            yggdrasilUrl: config.yggdrasilUrl,
+            apiKey: config.apiKey ?? '',
+            capabilities: config.capabilities ?? [],
+            heartbeatInterval: config.heartbeatInterval ?? 30,
+            leaseTtl: config.leaseTtl ?? 60,
+            endpointProvider: config.endpointProvider ?? (() => Promise.resolve('')),
+            healthProvider: config.healthProvider ?? (() => Promise.resolve({ status: RunnerHealth.HEALTHY })),
+            detectLocalIp: config.detectLocalIp ?? true,
+            detectPublicIp: config.detectPublicIp ?? false,
+            labels: config.labels ?? {},
+            metadata: config.metadata ?? {},
+        };
+    }
+    /**
+     * Initialize the internal state.
+     */
+    initializeState() {
+        return {
+            runnerId: this.config.runnerId,
+            runnerName: this.config.name,
+            version: '0.1.0',
+            endpoint: 'pending',
+            lastHealth: RunnerHealth.HEALTHY,
+            running: false,
+        };
+    }
+}
+//# sourceMappingURL=ratatoskr.js.map

package/dist/src/ratatoskr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ratatoskr.js","sourceRoot":"","sources":["../../src/ratatoskr.ts"],"names":[],"mappings":"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"}

package/dist/src/runner.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=runner.d.ts.map

package/dist/src/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/runner.ts"],"names":[],"mappings":""}

package/dist/src/runner.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * Ratatoskr runner entrypoint.
+ *
+ * Starts the Ratatoskr daemon to register and heartbeat with Yggdrasil.
+ */
+import { Ratatoskr } from './index.js';
+const yggdrasilUrl = process.env['YGGDRASIL_URL'] || 'http://orchestration-controller:3000';
+const apiKey = process.env['API_KEY'] || '';
+const runnerName = process.env['RUNNER_NAME'] || `ratatoskr-${process.env['HOSTNAME'] || 'unknown'}`;
+const capabilities = (process.env['CAPABILITIES'] || 'http,health')
+    .split(',')
+    .map(c => c.trim())
+    .filter(c => c !== '');
+const ratatoskr = new Ratatoskr({
+    yggdrasilUrl,
+    ...(apiKey ? { apiKey } : {}),
+    name: runnerName,
+    capabilities,
+    heartbeatInterval: 15,
+    leaseTtl: 45,
+    detectLocalIp: true,
+    detectPublicIp: false,
+});
+ratatoskr.start()
+    .then(() => {
+    console.log(`[Ratatoskr] Started — runner: ${ratatoskr.getState().runnerId}, yggdrasil: ${yggdrasilUrl}`);
+})
+    .catch((err) => {
+    console.error('[Ratatoskr] Failed to start:', err);
+    process.exit(1);
+});
+// Keep the process alive
+process.on('SIGTERM', async () => {
+    console.log('[Ratatoskr] Shutting down...');
+    await ratatoskr.stop();
+    process.exit(0);
+});
+process.on('SIGINT', async () => {
+    console.log('[Ratatoskr] Shutting down...');
+    await ratatoskr.stop();
+    process.exit(0);
+});
+//# sourceMappingURL=runner.js.map

package/dist/src/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/runner.ts"],"names":[],"mappings":";AAEA;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,sCAAsC,CAAC;AAC5F,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;AAC5C,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,aAAa,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,SAAS,EAAE,CAAC;AACrG,MAAM,YAAY,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,aAAa,CAAC;KAChE,KAAK,CAAC,GAAG,CAAC;KACV,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;KAClB,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;AAEzB,MAAM,SAAS,GAAG,IAAI,SAAS,CAAC;IAC9B,YAAY;IACZ,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7B,IAAI,EAAE,UAAU;IAChB,YAAY;IACZ,iBAAiB,EAAE,EAAE;IACrB,QAAQ,EAAE,EAAE;IACZ,aAAa,EAAE,IAAI;IACnB,cAAc,EAAE,KAAK;CACtB,CAAC,CAAC;AAEH,SAAS,CAAC,KAAK,EAAE;KACd,IAAI,CAAC,GAAG,EAAE;IACT,OAAO,CAAC,GAAG,CAAC,iCAAiC,SAAS,CAAC,QAAQ,EAAE,CAAC,QAAQ,gBAAgB,YAAY,EAAE,CAAC,CAAC;AAC5G,CAAC,CAAC;KACD,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACb,OAAO,CAAC,KAAK,CAAC,8BAA8B,EAAE,GAAG,CAAC,CAAC;IACnD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC;AAEL,yBAAyB;AACzB,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;IAC/B,OAAO,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAC;IAC5C,MAAM,SAAS,CAAC,IAAI,EAAE,CAAC;IACvB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC;AAEH,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;IAC9B,OAAO,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAC;IAC5C,MAAM,SAAS,CAAC,IAAI,EAAE,CAAC;IACvB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/src/services/endpoint-detector.d.ts

@@ -0,0 +1,49 @@
+import type { EndpointUpdatePayload } from '../types/index.js';
+/**
+ * Detects and monitors the runner's network endpoint.
+ *
+ * Tracks local IP, hostname, and optionally public IP, emitting
+ * endpoint changes so the registrar can notify Yggdrasil.
+ */
+export declare class EndpointDetector {
+    private currentEndpoint;
+    private readonly port;
+    private readonly detectPublicIp;
+    private publicIpCache;
+    /**
+     * @param port - The port the runner serves on.
+     * @param detectPublicIp - Whether to fetch the public IP (default false).
+     */
+    constructor(port?: number, detectPublicIp?: boolean);
+    /**
+     * Returns the currently detected endpoint URL.
+     */
+    getCurrentEndpoint(): string;
+    /**
+     * Override the detected endpoint with a custom value.
+     * Used by custom endpoint providers.
+     */
+    setEndpoint(endpoint: string): void;
+    /**
+     * Performs a single endpoint detection and returns an update payload
+     * if the endpoint changed, or null if unchanged.
+     */
+    detect(): Promise<EndpointUpdatePayload | null>;
+    /**
+     * Resolves the best available endpoint for this runner.
+     */
+    private resolveEndpoint;
+    /**
+     * Builds a local endpoint from the first non-internal IPv4 address.
+     */
+    private buildLocalEndpoint;
+    /**
+     * Fetches the public IP from an external service.
+     */
+    private fetchPublicIp;
+    /**
+     * Returns the hostname of the current machine.
+     */
+    getHostname(): string;
+}
+//# sourceMappingURL=endpoint-detector.d.ts.map

package/dist/src/services/endpoint-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint-detector.d.ts","sourceRoot":"","sources":["../../../src/services/endpoint-detector.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE/D;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,aAAa,CAAqB;IAE1C;;;OAGG;gBACS,IAAI,GAAE,MAAa,EAAE,cAAc,GAAE,OAAe;IAMhE;;OAEG;IACH,kBAAkB,IAAI,MAAM;IAI5B;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAInC;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC;IAiBrD;;OAEG;YACW,eAAe;IAa7B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAiB1B;;OAEG;YACW,aAAa;IAc3B;;OAEG;IACH,WAAW,IAAI,MAAM;CAGtB"}

package/dist/src/services/endpoint-detector.js

@@ -0,0 +1,105 @@
+import * as os from 'os';
+import axios from 'axios';
+/**
+ * Detects and monitors the runner's network endpoint.
+ *
+ * Tracks local IP, hostname, and optionally public IP, emitting
+ * endpoint changes so the registrar can notify Yggdrasil.
+ */
+export class EndpointDetector {
+    currentEndpoint;
+    port;
+    detectPublicIp;
+    publicIpCache;
+    /**
+     * @param port - The port the runner serves on.
+     * @param detectPublicIp - Whether to fetch the public IP (default false).
+     */
+    constructor(port = 8080, detectPublicIp = false) {
+        this.port = port;
+        this.detectPublicIp = detectPublicIp;
+        this.currentEndpoint = this.buildLocalEndpoint();
+    }
+    /**
+     * Returns the currently detected endpoint URL.
+     */
+    getCurrentEndpoint() {
+        return this.currentEndpoint;
+    }
+    /**
+     * Override the detected endpoint with a custom value.
+     * Used by custom endpoint providers.
+     */
+    setEndpoint(endpoint) {
+        this.currentEndpoint = endpoint;
+    }
+    /**
+     * Performs a single endpoint detection and returns an update payload
+     * if the endpoint changed, or null if unchanged.
+     */
+    async detect() {
+        const oldEndpoint = this.currentEndpoint;
+        const newEndpoint = await this.resolveEndpoint();
+        if (newEndpoint === oldEndpoint) {
+            return null;
+        }
+        this.currentEndpoint = newEndpoint;
+        return {
+            runnerId: '', // filled in by the caller
+            oldEndpoint,
+            newEndpoint,
+        };
+    }
+    /**
+     * Resolves the best available endpoint for this runner.
+     */
+    async resolveEndpoint() {
+        if (this.detectPublicIp) {
+            try {
+                const publicIp = await this.fetchPublicIp();
+                return `http://${publicIp}:${this.port}`;
+            }
+            catch {
+                // Fall through to local endpoint
+            }
+        }
+        return this.buildLocalEndpoint();
+    }
+    /**
+     * Builds a local endpoint from the first non-internal IPv4 address.
+     */
+    buildLocalEndpoint() {
+        const interfaces = os.networkInterfaces();
+        for (const name of Object.keys(interfaces)) {
+            const netInterfaces = interfaces[name];
+            if (!netInterfaces)
+                continue;
+            for (const net of netInterfaces) {
+                if (net.family === 'IPv4' && !net.internal) {
+                    return `http://${net.address}:${this.port}`;
+                }
+            }
+        }
+        return `http://127.0.0.1:${this.port}`;
+    }
+    /**
+     * Fetches the public IP from an external service.
+     */
+    async fetchPublicIp() {
+        if (this.publicIpCache) {
+            return this.publicIpCache;
+        }
+        const response = await axios.get('https://api.ipify.org', {
+            timeout: 3000,
+        });
+        this.publicIpCache = response.data.trim();
+        return this.publicIpCache;
+    }
+    /**
+     * Returns the hostname of the current machine.
+     */
+    getHostname() {
+        return os.hostname();
+    }
+}
+//# sourceMappingURL=endpoint-detector.js.map