@theaiinc/yggdrasil 0.2.1 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 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,157 @@
+# @theaiinc/yggdrasil
+
+<p align="center">
+  <a href="https://github.com/theaiinc/yggdrasil"><img alt="GitHub Repo" src="https://img.shields.io/badge/github-theaiinc%2Fyggdrasil-181717?style=flat-square&logo=github"/></a>
+  <a href="https://www.npmjs.com/package/@theaiinc/yggdrasil"><img alt="npm" src="https://img.shields.io/npm/v/@theaiinc/yggdrasil?style=flat-square&logo=npm"/></a>
+  <a href="https://github.com/theaiinc/yggdrasil/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/theaiinc/yggdrasil?style=flat-square"/></a>
+</p>
+
+<p align="center">
+  <img src="./yggdrasil.svg" alt="Yggdrasil" width="300" />
+</p>
+
+Distributed runner orchestration controller — receives runner registrations and heartbeats, dispatches tasks, and manages a dynamic pool of Ratatoskr agents.
+
+Yggdrasil is the control plane for a fleet of runners. Each runner runs a [Ratatoskr](https://www.npmjs.com/package/@theaiinc/yggdrasil-ratatoskr) daemon that registers, heartbeats, and executes tasks. Yggdrasil tracks which runners are alive, assigns tasks to them, and handles lease expiry, updates, and health monitoring.
+
+> **Version note**: `@theaiinc/yggdrasil` and `@theaiinc/yggdrasil-ratatoskr` are always released at the same version number.
+
+## Installation
+
+```bash
+npm install @theaiinc/yggdrasil
+```
+
+## Quick Start
+
+```typescript
+import { Logger } from '@theaiinc/yggdrasil';
+
+const logger = new Logger({ level: 'info', format: 'simple', transports: ['console'] });
+logger.info('Yggdrasil ready');
+```
+
+### Running the controller
+
+```bash
+npx @theaiinc/yggdrasil
+```
+
+By default Yggdrasil listens on port 3000. Configure via environment variables:
+
+```bash
+PORT=3100 \
+API_KEYS=my-secret-key \
+LEASE_TTL_MS=60000 \
+npx @theaiinc/yggdrasil
+```
+
+## Architecture
+
+```mermaid
+graph LR
+    subgraph Runners
+        RT1[Ratatoskr<br/>runner-1]
+        RT2[Ratatoskr<br/>runner-2]
+        RTN[Ratatoskr<br/>runner-N]
+    end
+    subgraph ControlPlane
+        Y[Yggdrasil<br/>Controller<br/>POST /runners/register<br/>POST /runners/heartbeat<br/>POST /runners/task/:id/patch]
+    end
+    subgraph Consumers
+        OG[api-gateway<br/>orchestration layer]
+    end
+    RT1 <-->|HTTP| Y
+    RT2 <-->|HTTP| Y
+    RTN <-->|HTTP| Y
+    OG -->|GET /api/runners<br/>GET /runners/:id/tasks| Y
+    Y -->|POST /runners/:id/tasks<br/>PATCH /runners/:id/tasks/:tid| OG
+```
+
+## API Endpoints
+
+The controller serves these endpoints (consumed by Ratatoskr and pool orchestrators):
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/health` | Health check |
+| `GET` | `/runners` | List all runners |
+| `POST` | `/runners/register` | Register a new runner |
+| `POST` | `/runners/heartbeat` | Runner heartbeat |
+| `POST` | `/runners/update` | Update runner endpoint |
+| `POST` | `/runners/offline` | Deregister a runner (graceful shutdown) |
+| `GET` | `/runners/:id` | Get runner details |
+| `GET` | `/runners/:id/tasks` | List runner tasks |
+| `POST` | `/runners/:id/tasks` | Dispatch a task to a runner |
+| `PATCH` | `/runners/:id/tasks/:tid` | Update task status |
+| `POST` | `/version-check/:version` | Check version compliance |
+| `POST` | `/runners/:id/request-update` | Request runner update |
+| `GET` | `/admission` | Get admission state (circuit breaker) |
+| `GET` | `/metrics` | Prometheus metrics |
+
+## Configuration
+
+### Controller environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `3000` | HTTP listen port |
+| `API_KEYS` | `''` | Comma-separated API keys for runner auth |
+| `LEASE_TTL_MS` | `60000` | Milliseconds before an unresponsive runner is marked offline |
+| `HEARTBEAT_INTERVAL_MS` | `15000` | Expected heartbeat interval (for lease calculation) |
+| `NODE_ENV` | `development` | Environment name |
+| `LOG_LEVEL` | `info` | Log level (error, warn, info, debug) |
+| `LOG_FORMAT` | `simple` | Log format (json, simple) |
+| `EXPECTED_RUNNER_VERSION` | `''` | Expected runner version string (for version compliance checks) |
+| `METRICS_PREFIX` | `yggdrasil_` | Prefix for Prometheus metric names |
+
+### Exported types
+
+All wire protocol types are exported for consumers:
+
+- `RunnerInfo`, `RunnerTask`, `SystemResources`, `PendingUpdate`
+- `RegisterRunnerPayload`, `HeartbeatPayload`, `HeartbeatResponse`, `RequestUpdatePayload`
+- `LogLevel`, `LoggerConfig`
+
+### Exported utilities
+
+- `Logger` — Structured logger (JSON or simple format, console transport)
+
+## Prometheus Metrics
+
+Yggdrasil exposes Prometheus metrics at `GET /metrics`:
+
+| Metric | Type | Labels | Description |
+|--------|------|--------|-------------|
+| `yggdrasil_runners_registered` | Gauge | — | Number of registered runners |
+| `yggdrasil_runners_offline` | Gauge | — | Number of offline runners |
+| `yggdrasil_runner_info` | Gauge | `runner_id`, `name`, `version`, `status` | Runner metadata |
+| `yggdrasil_runner_uptime_seconds` | Gauge | `runner_id` | Runner uptime |
+| `yggdrasil_runner_cpu_percent` | Gauge | `runner_id` | CPU usage |
+| `yggdrasil_runner_memory_percent` | Gauge | `runner_id` | Memory usage |
+| `yggdrasil_runner_leases` | Gauge | `runner_id` | Lease expiry timestamp |
+| `yggdrasil_runner_tasks_running` | Gauge | `runner_id` | Running task count |
+| `yggdrasil_tasks_dispatched_total` | Counter | — | Total dispatched tasks |
+| `yggdrasil_tasks_completed_total` | Counter | `status` | Total completed tasks |
+
+## Lease Management
+
+Each runner registration includes a lease TTL. Yggdrasil expects heartbeats before the lease expires. On timeout:
+
+1. The runner is marked `offline`
+2. Its tasks transition to `failed`
+3. A configured `RUNNER_OFFLINE_HOOK` can be triggered (if set)
+4. The runner must re-register to come back online
+
+## Self-Update Protocol
+
+Yggdrasil supports requesting runner version updates:
+
+1. Admin calls `POST /runners/:id/request-update` with a version/command
+2. Yggdrasil stores the pending update on the runner's record
+3. On the next heartbeat, Ratatoskr sees `pendingUpdate` and triggers the update
+4. The update runs after all current tasks complete, then the runner restarts
+
+## License
+
+MIT — © 2026 The AI Inc

package/dist/src/index.d.ts

@@ -1,3 +1,8 @@
 export { Logger } from './services/logger.js';
-export type { LogLevel, LoggerConfig, } from './types/index.js';
+export { app, runners, sessions, realmRegistry, realmScheduler, realmProvisioner, realmLifecycle } from './orchestration-controller.js';
+export { RealmRegistry } from './services/realm-registry.js';
+export { RealmScheduler } from './services/realm-scheduler.js';
+export { RealmProvisioner } from './services/realm-provisioner.js';
+export { RealmLifecycleService } from './services/realm-lifecycle.js';
+export type { LogLevel, LoggerConfig, SessionType, SessionState, ObservationMethod, InputCapability, SessionDescriptor, CreateSessionRequest, CreateSessionResponse, SessionObservation, SessionInput, SessionInputResult, SessionHealth, RealmTemplateType, RealmState, RealmTemplate, Realm, RealmAllocation, RealmRegistration, RealmHeartbeat, RealmDeregistration, SystemResources, PendingUpdate, RunnerTask, RunnerInfo, RegisterRunnerPayload, HeartbeatPayload, HeartbeatResponse, RequestUpdatePayload, } from './types/index.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAG9C,YAAY,EACV,QAAQ,EACR,YAAY,GACb,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAExI,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAGtE,YAAY,EACV,QAAQ,EACR,YAAY,EAGZ,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,aAAa,EAGb,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,KAAK,EACL,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,mBAAmB,EAGnB,eAAe,EACf,aAAa,EACb,UAAU,EACV,UAAU,EAGV,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC"}

package/dist/src/index.js

@@ -1,3 +1,8 @@
 // Main entry point for @theaiinc/yggdrasil package
 export { Logger } from './services/logger.js';
+export { app, runners, sessions, realmRegistry, realmScheduler, realmProvisioner, realmLifecycle } from './orchestration-controller.js';
+export { RealmRegistry } from './services/realm-registry.js';
+export { RealmScheduler } from './services/realm-scheduler.js';
+export { RealmProvisioner } from './services/realm-provisioner.js';
+export { RealmLifecycleService } from './services/realm-lifecycle.js';
 //# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,mDAAmD;AAEnD,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,mDAAmD;AAEnD,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAExI,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/src/orchestration-controller.d.ts

@@ -1,2 +1,14 @@
-export {};
+import { RealmRegistry } from './services/realm-registry.js';
+import { RealmScheduler } from './services/realm-scheduler.js';
+import { RealmProvisioner } from './services/realm-provisioner.js';
+import { RealmLifecycleService } from './services/realm-lifecycle.js';
+import type { RunnerInfo, SessionDescriptor } from './types/index.js';
+declare const app: import("express-serve-static-core").Express;
+declare const runners: Map<string, RunnerInfo>;
+declare const realmRegistry: RealmRegistry;
+declare const realmScheduler: RealmScheduler;
+declare const realmProvisioner: RealmProvisioner;
+declare const realmLifecycle: RealmLifecycleService;
+declare const sessions: Map<string, SessionDescriptor>;
+export { app, runners, sessions, realmRegistry, realmScheduler, realmProvisioner, realmLifecycle };
 //# sourceMappingURL=orchestration-controller.d.ts.map

package/dist/src/orchestration-controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orchestration-controller.d.ts","sourceRoot":"","sources":["../../src/orchestration-controller.ts"],"names":[],"mappings":""}
+{"version":3,"file":"orchestration-controller.d.ts","sourceRoot":"","sources":["../../src/orchestration-controller.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAEtE,OAAO,KAAK,EAGV,UAAU,EAQV,iBAAiB,EAUlB,MAAM,kBAAkB,CAAC;AAE1B,QAAA,MAAM,GAAG,6CAAY,CAAC;AAGtB,QAAA,MAAM,OAAO,yBAAgC,CAAC;AAI9C,QAAA,MAAM,aAAa,eAAsB,CAAC;AAC1C,QAAA,MAAM,cAAc,gBAAyE,CAAC;AAC9F,QAAA,MAAM,gBAAgB,kBAAsC,CAAC;AAC7D,QAAA,MAAM,cAAc,uBAA2C,CAAC;AAichE,QAAA,MAAM,QAAQ,gCAAuC,CAAC;AAwXtD,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAAE,cAAc,EAAE,CAAC"}