@theaiinc/yggdrasil 0.2.3 → 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

@@ -1,5 +1,15 @@
 # @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.
@@ -38,19 +48,24 @@ npx @theaiinc/yggdrasil
 
 ## Architecture
 
-```
-┌──────────────┐     HTTP (heartbeat, register, tasks)    ┌──────────────┐
-│  Ratatoskr   │◄─────────────────────────────────────────►│   Yggdrasil  │
-│  (runner)    │    POST /runners/register                 │  (controller)│
-│              │    POST /runners/heartbeat                │              │
-│              │    POST /runners/task/:id/patch           │              │
-└──────────────┘                                          └──────────────┘
-       │                                                         │
-       │  Runs agent tasks                                       │  API surface
-       │  (sub-agent LLM loop,                                   │  consumed by
-       │   shell, file, web tools)                               │  orchestration layer
-       ▼                                                         ▼
-   Docker / host                                            api-gateway
+```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

package/dist/src/index.d.ts

@@ -1,3 +1,8 @@
 export { Logger } from './services/logger.js';
-export type { LogLevel, LoggerConfig, SystemResources, PendingUpdate, RunnerTask, RunnerInfo, RegisterRunnerPayload, HeartbeatPayload, HeartbeatResponse, RequestUpdatePayload, } 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,EAGZ,eAAe,EACf,aAAa,EACb,UAAU,EACV,UAAU,EAGV,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,GACrB,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,5 +1,14 @@
-import type { RunnerInfo } from './types/index.js';
+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>;
-export { app, runners };
+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":"AAOA,OAAO,KAAK,EAGV,UAAU,EAMX,MAAM,kBAAkB,CAAC;AAE1B,QAAA,MAAM,GAAG,6CAAY,CAAC;AAGtB,QAAA,MAAM,OAAO,yBAAgC,CAAC;AA6a9C,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC"}
+{"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"}

package/dist/src/orchestration-controller.js

@@ -4,9 +4,18 @@ import compression from 'compression';
 import helmet from 'helmet';
 import { getLogger } from './services/logger.js';
 import { nanoid } from 'nanoid';
+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';
 const app = express();
 const logger = getLogger();
 const runners = new Map();
+// ─── Realm lifecycle services ───────────────────────────────────
+const realmRegistry = new RealmRegistry();
+const realmScheduler = new RealmScheduler(realmRegistry, (runnerId) => runners.get(runnerId));
+const realmProvisioner = new RealmProvisioner(realmRegistry);
+const realmLifecycle = new RealmLifecycleService(realmRegistry);
 // ─── API key authentication ─────────────────────────────────────
 const API_KEYS = (process.env['API_KEYS'] || '')
     .split(',')
@@ -58,63 +67,76 @@ app.get('/health', (_req, res) => {
         },
     });
 });
+function escapePrometheusLabelValue(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+}
+function runnerLabels(id, name) {
+    return `runner="${escapePrometheusLabelValue(id)}",name="${escapePrometheusLabelValue(name)}"`;
+}
 app.get('/metrics', (_req, res) => {
-    const online = Array.from(runners.values()).filter(r => r.status === 'online');
+    // Snapshot runner state once so concurrent heartbeats cannot produce duplicate
+    // series with different values within a single scrape response.
+    const snapshot = Array.from(runners.entries());
+    const online = snapshot.filter(([, r]) => r.status === 'online');
+    const offlineCount = snapshot.length - online.length;
+    const tasksRunning = snapshot.reduce((sum, [, r]) => sum + r.tasks.filter(t => t.status === 'running').length, 0);
     const metrics = [
         '# HELP yggdrasil_runners_total Total number of registered runners',
         '# TYPE yggdrasil_runners_total gauge',
-        `yggdrasil_runners_total ${runners.size}`,
+        `yggdrasil_runners_total ${snapshot.length}`,
         '# HELP yggdrasil_runners_online Number of online runners',
         '# TYPE yggdrasil_runners_online gauge',
         `yggdrasil_runners_online ${online.length}`,
         '# HELP yggdrasil_runners_offline Number of offline runners',
         '# TYPE yggdrasil_runners_offline gauge',
-        `yggdrasil_runners_offline ${runners.size - online.length}`,
+        `yggdrasil_runners_offline ${offlineCount}`,
         '# HELP yggdrasil_uptime_seconds Server uptime in seconds',
-        '# TYPE yggdrasil_uptime_seconds counter',
+        '# TYPE yggdrasil_uptime_seconds gauge',
         `yggdrasil_uptime_seconds ${process.uptime()}`,
         '# HELP yggdrasil_tasks_running Number of currently running tasks across all runners',
         '# TYPE yggdrasil_tasks_running gauge',
-        `yggdrasil_tasks_running ${Array.from(runners.values()).reduce((sum, r) => sum + r.tasks.filter(t => t.status === 'running').length, 0)}`,
+        `yggdrasil_tasks_running ${tasksRunning}`,
     ];
-    // Expected runner version info (exposing the controller's expectation)
     if (EXPECTED_RUNNER_VERSION) {
-        metrics.push(`# HELP yggdrasil_expected_runner_version Expected runner version (always 1) — label carries the expected version`);
-        metrics.push(`# TYPE yggdrasil_expected_runner_version info`);
-        metrics.push(`yggdrasil_expected_runner_version{version="${EXPECTED_RUNNER_VERSION}"} 1`);
-    }
-    // Per-runner resource metrics
-    for (const [id, runner] of runners.entries()) {
-        if (runner.resources && runner.status === 'online') {
-            const labels = `runner="${id}",name="${runner.name}"`;
-            metrics.push(`# HELP yggdrasil_runner_cpu_percent CPU usage percent per runner`);
-            metrics.push(`# TYPE yggdrasil_runner_cpu_percent gauge`);
-            metrics.push(`yggdrasil_runner_cpu_percent{${labels}} ${runner.resources.cpu.percent}`);
-            metrics.push(`# HELP yggdrasil_runner_memory_percent Memory usage percent per runner`);
-            metrics.push(`# TYPE yggdrasil_runner_memory_percent gauge`);
-            metrics.push(`yggdrasil_runner_memory_percent{${labels}} ${runner.resources.memory.percent}`);
-            metrics.push(`# HELP yggdrasil_runner_memory_used_bytes Memory used bytes per runner`);
-            metrics.push(`# TYPE yggdrasil_runner_memory_used_bytes gauge`);
-            metrics.push(`yggdrasil_runner_memory_used_bytes{${labels}} ${runner.resources.memory.used}`);
+        metrics.push('# HELP yggdrasil_expected_runner_version Expected runner version (always 1) — label carries the expected version', '# TYPE yggdrasil_expected_runner_version gauge', `yggdrasil_expected_runner_version{version="${escapePrometheusLabelValue(EXPECTED_RUNNER_VERSION)}"} 1`);
+    }
+    const onlineWithResources = online.filter(([, r]) => r.resources);
+    if (onlineWithResources.length > 0) {
+        metrics.push('# HELP yggdrasil_runner_cpu_percent CPU usage percent per runner', '# TYPE yggdrasil_runner_cpu_percent gauge');
+        for (const [id, runner] of onlineWithResources) {
+            metrics.push(`yggdrasil_runner_cpu_percent{${runnerLabels(id, runner.name)}} ${runner.resources.cpu.percent}`);
+        }
+        metrics.push('# HELP yggdrasil_runner_memory_percent Memory usage percent per runner', '# TYPE yggdrasil_runner_memory_percent gauge');
+        for (const [id, runner] of onlineWithResources) {
+            metrics.push(`yggdrasil_runner_memory_percent{${runnerLabels(id, runner.name)}} ${runner.resources.memory.percent}`);
+        }
+        metrics.push('# HELP yggdrasil_runner_memory_used_bytes Memory used bytes per runner', '# TYPE yggdrasil_runner_memory_used_bytes gauge');
+        for (const [id, runner] of onlineWithResources) {
+            metrics.push(`yggdrasil_runner_memory_used_bytes{${runnerLabels(id, runner.name)}} ${runner.resources.memory.used}`);
         }
     }
-    // Per-runner version info (one gauge per runner with version label)
-    for (const [id, runner] of runners.entries()) {
-        const verLabels = `runner="${id}",name="${runner.name}",version="${runner.version}"`;
-        metrics.push(`# HELP yggdrasil_runner_version_info Runner version (always 1) — labels carry version`);
-        metrics.push(`# TYPE yggdrasil_runner_version_info gauge`);
-        metrics.push(`yggdrasil_runner_version_info{${verLabels}} 1`);
-        // Outdated flag: 1 if EXPECTED_RUNNER_VERSION is set and runner version differs
-        if (EXPECTED_RUNNER_VERSION && runner.version !== EXPECTED_RUNNER_VERSION) {
-            const outdatedLabels = `runner="${id}",name="${runner.name}",current="${runner.version}",expected="${EXPECTED_RUNNER_VERSION}"`;
-            metrics.push(`# HELP yggdrasil_runner_outdated Outdated runner flag (1 = version mismatch)`);
-            metrics.push(`# TYPE yggdrasil_runner_outdated gauge`);
+    const outdatedRunners = EXPECTED_RUNNER_VERSION
+        ? snapshot.filter(([, r]) => r.version !== EXPECTED_RUNNER_VERSION)
+        : [];
+    const pendingUpdateRunners = snapshot.filter(([, r]) => r.pendingUpdate);
+    if (snapshot.length > 0) {
+        metrics.push('# HELP yggdrasil_runner_version_info Runner version (always 1) — labels carry version', '# TYPE yggdrasil_runner_version_info gauge');
+        for (const [id, runner] of snapshot) {
+            const verLabels = `${runnerLabels(id, runner.name)},version="${escapePrometheusLabelValue(runner.version)}"`;
+            metrics.push(`yggdrasil_runner_version_info{${verLabels}} 1`);
+        }
+    }
+    if (outdatedRunners.length > 0) {
+        metrics.push('# HELP yggdrasil_runner_outdated Outdated runner flag (1 = version mismatch)', '# TYPE yggdrasil_runner_outdated gauge');
+        for (const [id, runner] of outdatedRunners) {
+            const outdatedLabels = `${runnerLabels(id, runner.name)},current="${escapePrometheusLabelValue(runner.version)}",expected="${escapePrometheusLabelValue(EXPECTED_RUNNER_VERSION)}"`;
             metrics.push(`yggdrasil_runner_outdated{${outdatedLabels}} 1`);
         }
-        if (runner.pendingUpdate) {
-            const updLabels = `runner="${id}",name="${runner.name}",current_version="${runner.version}",target_version="${runner.pendingUpdate.version}"`;
-            metrics.push(`# HELP yggdrasil_runner_pending_update Pending update flag per runner (1 = update pending)`);
-            metrics.push(`# TYPE yggdrasil_runner_pending_update gauge`);
+    }
+    if (pendingUpdateRunners.length > 0) {
+        metrics.push('# HELP yggdrasil_runner_pending_update Pending update flag per runner (1 = update pending)', '# TYPE yggdrasil_runner_pending_update gauge');
+        for (const [id, runner] of pendingUpdateRunners) {
+            const updLabels = `${runnerLabels(id, runner.name)},current_version="${escapePrometheusLabelValue(runner.version)}",target_version="${escapePrometheusLabelValue(runner.pendingUpdate.version)}"`;
             metrics.push(`yggdrasil_runner_pending_update{${updLabels}} 1`);
         }
     }
@@ -125,14 +147,20 @@ app.get('/metrics', (_req, res) => {
 app.post('/runners/register', (req, res) => {
     const body = req.body;
     const runnerId = body.runnerId || nanoid();
-    // Upsert: preserve existing tasks when re-registering (lease expiry, reconnect)
+    // Upsert: preserve existing tasks and templates when re-registering (lease expiry, reconnect)
     const existing = runners.get(runnerId);
+    const templates = (body.realmTemplates ?? []).map(t => ({
+        id: t.id,
+        type: t.type,
+        capabilities: (t.capabilities ?? []),
+    }));
     runners.set(runnerId, {
         runnerId,
         name: body.name || 'unknown',
         endpoint: body.endpoint || 'unknown',
         version: body.version || '0.1.0',
         capabilities: body.capabilities || [],
+        realmTemplates: templates,
         labels: body.labels || {},
         lastHeartbeat: new Date(),
         status: 'online',
@@ -140,6 +168,8 @@ app.post('/runners/register', (req, res) => {
         // Preserve existing tasks on re-registration
         tasks: existing?.tasks ?? body.tasks ?? [],
     });
+    // Sync realm templates into the registry
+    realmRegistry.setTemplates(runnerId, templates);
     logger.info('Runner registered', { runnerId, name: body.name, endpoint: body.endpoint, reRegistered: !!existing });
     res.status(201).json({ runnerId, status: existing ? 're-registered' : 'registered' });
 });
@@ -222,6 +252,7 @@ app.post('/runners/offline', (req, res) => {
         return;
     }
     runners.get(runnerId).status = 'offline';
+    realmRegistry.removeTemplates(runnerId);
     logger.info('Runner went offline', { runnerId });
     res.json({ status: 'offline' });
 });
@@ -291,6 +322,7 @@ app.get('/api/runners', (_req, res) => {
             endpoint: r.endpoint,
             version: r.version,
             capabilities: r.capabilities,
+            realmTemplates: r.realmTemplates,
             labels: r.labels,
             status: r.status,
             lastHeartbeat: r.lastHeartbeat,
@@ -308,10 +340,270 @@ app.get('/api/runners/:runnerId', (req, res) => {
     }
     res.json(runner);
 });
+// ─── Session management ─────────────────────────────────────────
+const sessions = new Map();
+function validateApiKey(req) {
+    if (API_KEYS.length === 0)
+        return true;
+    const apiKey = req.headers['x-api-key'];
+    return !!apiKey && API_KEYS.includes(apiKey);
+}
+/**
+ * Create a new interaction session.
+ *
+ * Flow:
+ *   1. Validate request
+ *   2. RealmScheduler decides which realm/realm template to use
+ *   3. RealmProvisioner ensures the realm exists (spawn or attach)
+ *   4. Create SessionDescriptor with realm endpoints
+ *   5. Mark active and register
+ */
+app.post('/api/v1/sessions', async (req, res) => {
+    const body = req.body;
+    if (!body.type || !['computer-use', 'phone-use'].includes(body.type)) {
+        res.status(400).json({ error: 'Invalid or missing session type. Must be "computer-use" or "phone-use".' });
+        return;
+    }
+    try {
+        // Step 1: Schedule — decide realm allocation
+        const allocation = await realmScheduler.schedule(body);
+        // Step 2: Provision — ensure realm exists
+        const realm = await realmProvisioner.ensureRealm(allocation, body.ownerId);
+        // Step 3: Create session attached to realm
+        const sessionId = `session-${nanoid(12)}`;
+        const now = new Date().toISOString();
+        const descriptor = {
+            id: sessionId,
+            type: body.type,
+            state: 'creating',
+            observationEndpoint: realm.endpoints.observation,
+            inputEndpoint: realm.endpoints.input,
+            capabilities: body.capabilities ?? (body.type === 'computer-use'
+                ? ['mouse', 'keyboard', 'scroll', 'clipboard']
+                : ['touch', 'keyboard', 'scroll']),
+            observationMethod: 'screenshot',
+            realmId: realm.id,
+            ...(body.ownerId !== undefined ? { ownerId: body.ownerId } : {}),
+            ...(body.participantIds !== undefined ? { participantIds: body.participantIds } : {}),
+            createdAt: now,
+            updatedAt: now,
+            metadata: {
+                ...body.metadata,
+                runnerId: realm.runnerId,
+                allocationAction: allocation.action,
+            },
+        };
+        descriptor.state = 'active';
+        sessions.set(sessionId, descriptor);
+        logger.info('Session created', {
+            sessionId,
+            type: body.type,
+            realmId: realm.id,
+            runnerId: realm.runnerId,
+            allocationAction: allocation.action,
+        });
+        const response = { sessionId, descriptor };
+        res.status(201).json(response);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        logger.error('Failed to create session', { error: message });
+        res.status(503).json({ error: `Unable to create session: ${message}` });
+    }
+});
+/**
+ * Get session details.
+ */
+app.get('/api/v1/sessions/:sessionId', (req, res) => {
+    const session = sessions.get(req.params.sessionId);
+    if (!session) {
+        res.status(404).json({ error: 'Session not found' });
+        return;
+    }
+    res.json(session);
+});
+/**
+ * List all sessions, optionally filtered by type or state.
+ */
+app.get('/api/v1/sessions', (req, res) => {
+    const { type, state } = req.query;
+    let result = Array.from(sessions.values());
+    if (type) {
+        result = result.filter((s) => s.type === type);
+    }
+    if (state) {
+        result = result.filter((s) => s.state === state);
+    }
+    res.json({ sessions: result, count: result.length });
+});
+/**
+ * Update session state (pause, resume, terminate).
+ */
+app.patch('/api/v1/sessions/:sessionId', (req, res) => {
+    const session = sessions.get(req.params.sessionId);
+    if (!session) {
+        res.status(404).json({ error: 'Session not found' });
+        return;
+    }
+    const body = req.body;
+    const validTransitions = {
+        creating: ['active', 'failed', 'terminated'],
+        active: ['paused', 'completed', 'failed', 'terminated'],
+        paused: ['active', 'terminated'],
+        completed: [],
+        failed: ['terminated'],
+        terminated: [],
+    };
+    if (body.state) {
+        const allowed = validTransitions[session.state] || [];
+        if (!allowed.includes(body.state)) {
+            res.status(400).json({
+                error: `Invalid state transition from "${session.state}" to "${body.state}". Allowed: ${allowed.join(', ')}`,
+            });
+            return;
+        }
+        session.state = body.state;
+    }
+    if (body.metadata) {
+        session.metadata = { ...session.metadata, ...body.metadata };
+    }
+    session.updatedAt = new Date().toISOString();
+    logger.info('Session state updated', { sessionId: session.id, state: session.state });
+    res.json(session);
+});
+/**
+ * Delete/terminate a session.
+ */
+app.delete('/api/v1/sessions/:sessionId', (req, res) => {
+    const session = sessions.get(req.params.sessionId);
+    if (!session) {
+        res.status(404).json({ error: 'Session not found' });
+        return;
+    }
+    session.state = 'terminated';
+    session.updatedAt = new Date().toISOString();
+    logger.info('Session terminated', { sessionId: session.id });
+    res.json({ status: 'terminated', sessionId: session.id });
+});
+// ─── Realm management API ────────────────────────────────────────
+/**
+ * List all realms managed by Yggdrasil.
+ */
+app.get('/api/v1/realms', (_req, res) => {
+    const realms = realmRegistry.listRealms();
+    res.json({ realms, count: realms.length });
+});
+/**
+ * Get a realm by ID.
+ */
+app.get('/api/v1/realms/:realmId', (req, res) => {
+    const realm = realmRegistry.getRealm(req.params.realmId);
+    if (!realm) {
+        res.status(404).json({ error: 'Realm not found' });
+        return;
+    }
+    res.json(realm);
+});
+/**
+ * Update realm state and endpoints (called by runners when a realm becomes ready).
+ */
+app.patch('/api/v1/realms/:realmId', (req, res) => {
+    const realm = realmRegistry.getRealm(req.params.realmId);
+    if (!realm) {
+        res.status(404).json({ error: 'Realm not found' });
+        return;
+    }
+    const body = req.body;
+    if (body.state) {
+        realmRegistry.updateRealmState(realm.id, body.state);
+    }
+    if (body.endpoints) {
+        realmProvisioner.updateRealmEndpoints(realm.id, body.state ?? realm.state, body.endpoints);
+    }
+    const updated = realmRegistry.getRealm(realm.id);
+    res.json(updated);
+});
+/**
+ * Destroy a realm.
+ */
+app.delete('/api/v1/realms/:realmId', async (req, res) => {
+    const realm = realmRegistry.getRealm(req.params.realmId);
+    if (!realm) {
+        res.status(404).json({ error: 'Realm not found' });
+        return;
+    }
+    await realmProvisioner.destroyRealm(realm.id);
+    res.json({ status: 'destroyed', realmId: realm.id });
+});
+// ─── Realm lifecycle routes (relayed by Ratatoskr) ─────────────────
+/**
+ * Register a realm that has just come online.
+ * Called by Ratatoskr on behalf of a Realm instance.
+ */
+app.post('/api/v1/realms/register', (req, res) => {
+    const body = req.body;
+    if (!body.realmId || !body.runnerId || !body.template) {
+        res.status(400).json({ error: 'realmId, runnerId, and template are required' });
+        return;
+    }
+    const registration = {
+        realmId: body.realmId,
+        runnerId: body.runnerId,
+        template: body.template,
+        version: body.version ?? '0.1.0',
+        capabilities: (body.capabilities ?? []),
+        endpoints: body.endpoints ?? { observation: '', input: '' },
+        registrationToken: body.registrationToken,
+        startedAt: body.startedAt ?? new Date().toISOString(),
+    };
+    const realm = realmLifecycle.registerRealm(registration, body.template);
+    res.status(201).json(realm);
+});
+/**
+ * Heartbeat from a realm instance (relayed by Ratatoskr).
+ */
+app.post('/api/v1/realms/heartbeat', (req, res) => {
+    const body = req.body;
+    if (!body.realmId) {
+        res.status(400).json({ error: 'realmId is required' });
+        return;
+    }
+    const heartbeat = {
+        realmId: body.realmId,
+        uptime: body.uptime ?? 0,
+        healthy: body.healthy ?? true,
+        memoryMb: body.memoryMb,
+        cpuPercent: body.cpuPercent,
+        activeSessions: body.activeSessions ?? 0,
+    };
+    const realm = realmLifecycle.heartbeatRealm(heartbeat);
+    if (!realm) {
+        res.status(404).json({ error: 'Realm not found' });
+        return;
+    }
+    res.json({ status: 'ok', realmId: realm.id, state: realm.state });
+});
+/**
+ * Deregister a realm on shutdown (relayed by Ratatoskr).
+ */
+app.post('/api/v1/realms/deregister', (req, res) => {
+    const body = req.body;
+    if (!body.realmId) {
+        res.status(400).json({ error: 'realmId is required' });
+        return;
+    }
+    const deregistration = {
+        realmId: body.realmId,
+        reason: body.reason ?? 'shutdown',
+    };
+    realmLifecycle.deregisterRealm(deregistration);
+    res.json({ status: 'deregistered', realmId: deregistration.realmId });
+});
 // ─── Lease-based offline detection ──────────────────────────────
 const LEASE_TTL_MS = parseInt(process.env['LEASE_TTL_MS'] || '60000', 10);
 const EXPECTED_RUNNER_VERSION = process.env['EXPECTED_RUNNER_VERSION'] || '';
 if (typeof process.env.VITEST === 'undefined') {
+    // Runner lease TTL check
     setInterval(() => {
         const now = Date.now();
         const stale = [];
@@ -333,6 +625,8 @@ if (typeof process.env.VITEST === 'undefined') {
             });
         }
     }, 10_000);
+    // Realm stale detection
+    realmLifecycle.startStaleDetection();
 }
 // ─── Start server ───────────────────────────────────────────────
 const PORT = parseInt(process.env['PORT'] || '3000', 10);
@@ -347,5 +641,5 @@ if (typeof process.env.VITEST === 'undefined') {
         });
     });
 }
-export { app, runners };
+export { app, runners, sessions, realmRegistry, realmScheduler, realmProvisioner, realmLifecycle };
 //# sourceMappingURL=orchestration-controller.js.map