@theaiinc/yggdrasil 0.2.3 → 0.3.2

package/dist/src/services/realm-provisioner.js.map

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

package/dist/src/services/realm-registry.d.ts

@@ -0,0 +1,83 @@
+/**
+ * RealmRegistry — stores Realm templates advertised by runners and Realm instances.
+ *
+ * Responsibilities:
+ *   - Tracks RealmTemplate[] per runner (what CAN be spawned)
+ *   - Tracks Realm[] (what IS running)
+ *   - Provides lookup by runner, template type, owner, and pool tag
+ *
+ * Yggdrasil is stateless-in-memory in v1. A future version may add
+ * FileSessionStore or database-backed persistence.
+ */
+import type { Realm, RealmTemplate } from '../types/index.js';
+export interface RealmRegistryEntry {
+    realm: Realm;
+    template: RealmTemplate;
+}
+export declare class RealmRegistry {
+    /** Runner ID → realm templates they advertise. */
+    private readonly templatesByRunner;
+    /** Realm ID → realm instance + its template. */
+    private readonly realms;
+    /**
+     * Register or update realm templates for a runner.
+     */
+    setTemplates(runnerId: string, templates: RealmTemplate[]): void;
+    /**
+     * Get templates for a specific runner.
+     */
+    getTemplates(runnerId: string): RealmTemplate[];
+    /**
+     * Get all templates across all runners that match a given template type.
+     */
+    getTemplatesByType(type: string): Array<{
+        runnerId: string;
+        template: RealmTemplate;
+    }>;
+    /**
+     * Remove templates for a runner (e.g. on deregistration).
+     */
+    removeTemplates(runnerId: string): void;
+    /**
+     * Register a new realm instance.
+     */
+    addRealm(realm: Realm, template: RealmTemplate): void;
+    /**
+     * Get a realm instance by ID.
+     */
+    getRealm(realmId: string): Realm | undefined;
+    /**
+     * Get realm + template by ID.
+     */
+    getEntry(realmId: string): RealmRegistryEntry | undefined;
+    /**
+     * Find a running realm by owner ID and template type (persistent realm affinity).
+     * This is how ownerId becomes a scheduling primitive.
+     */
+    findRealmByOwner(ownerId: string, templateType: string): Realm | undefined;
+    /**
+     * Find an idle realm in a pool (by template type, no owner).
+     */
+    findPooledRealm(templateType: string, poolTag?: string): Realm | undefined;
+    /**
+     * List all realm instances.
+     */
+    listRealms(): Realm[];
+    /**
+     * List realms for a specific runner.
+     */
+    listRealmsByRunner(runnerId: string): Realm[];
+    /**
+     * Update realm state.
+     */
+    updateRealmState(realmId: string, state: Realm['state']): void;
+    /**
+     * Remove a realm.
+     */
+    removeRealm(realmId: string): void;
+    /**
+     * Clear all state (useful for testing).
+     */
+    clear(): void;
+}
+//# sourceMappingURL=realm-registry.d.ts.map

package/dist/src/services/realm-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realm-registry.d.ts","sourceRoot":"","sources":["../../../src/services/realm-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAmB,MAAM,mBAAmB,CAAC;AAE/E,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED,qBAAa,aAAa;IACxB,kDAAkD;IAClD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAsC;IAExE,gDAAgD;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyC;IAIhE;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,GAAG,IAAI;IAIhE;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,EAAE;IAI/C;;OAEG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,aAAa,CAAA;KAAE,CAAC;IAYtF;;OAEG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAMvC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,GAAG,IAAI;IAIrD;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAI5C;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIzD;;;OAGG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAa1E;;OAEG;IACH,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAe1E;;OAEG;IACH,UAAU,IAAI,KAAK,EAAE;IAIrB;;OAEG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,EAAE;IAM7C;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,IAAI;IAQ9D;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIlC;;OAEG;IACH,KAAK,IAAI,IAAI;CAId"}

package/dist/src/services/realm-registry.js

@@ -0,0 +1,136 @@
+/**
+ * RealmRegistry — stores Realm templates advertised by runners and Realm instances.
+ *
+ * Responsibilities:
+ *   - Tracks RealmTemplate[] per runner (what CAN be spawned)
+ *   - Tracks Realm[] (what IS running)
+ *   - Provides lookup by runner, template type, owner, and pool tag
+ *
+ * Yggdrasil is stateless-in-memory in v1. A future version may add
+ * FileSessionStore or database-backed persistence.
+ */
+export class RealmRegistry {
+    /** Runner ID → realm templates they advertise. */
+    templatesByRunner = new Map();
+    /** Realm ID → realm instance + its template. */
+    realms = new Map();
+    // ── Template management ──────────────────────────────────────────────
+    /**
+     * Register or update realm templates for a runner.
+     */
+    setTemplates(runnerId, templates) {
+        this.templatesByRunner.set(runnerId, templates);
+    }
+    /**
+     * Get templates for a specific runner.
+     */
+    getTemplates(runnerId) {
+        return this.templatesByRunner.get(runnerId) ?? [];
+    }
+    /**
+     * Get all templates across all runners that match a given template type.
+     */
+    getTemplatesByType(type) {
+        const results = [];
+        for (const [runnerId, templates] of this.templatesByRunner.entries()) {
+            for (const template of templates) {
+                if (template.type === type) {
+                    results.push({ runnerId, template });
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * Remove templates for a runner (e.g. on deregistration).
+     */
+    removeTemplates(runnerId) {
+        this.templatesByRunner.delete(runnerId);
+    }
+    // ── Realm instance management ────────────────────────────────────────
+    /**
+     * Register a new realm instance.
+     */
+    addRealm(realm, template) {
+        this.realms.set(realm.id, { realm, template });
+    }
+    /**
+     * Get a realm instance by ID.
+     */
+    getRealm(realmId) {
+        return this.realms.get(realmId)?.realm;
+    }
+    /**
+     * Get realm + template by ID.
+     */
+    getEntry(realmId) {
+        return this.realms.get(realmId);
+    }
+    /**
+     * Find a running realm by owner ID and template type (persistent realm affinity).
+     * This is how ownerId becomes a scheduling primitive.
+     */
+    findRealmByOwner(ownerId, templateType) {
+        for (const [, entry] of this.realms.entries()) {
+            if (entry.realm.ownerId === ownerId &&
+                entry.template.type === templateType &&
+                (entry.realm.state === 'running' || entry.realm.state === 'paused')) {
+                return entry.realm;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Find an idle realm in a pool (by template type, no owner).
+     */
+    findPooledRealm(templateType, poolTag) {
+        for (const [, entry] of this.realms.entries()) {
+            if (entry.realm.state === 'running' &&
+                entry.template.type === templateType &&
+                entry.realm.ownerId === undefined) {
+                if (poolTag === undefined || entry.realm.poolTag === poolTag) {
+                    return entry.realm;
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * List all realm instances.
+     */
+    listRealms() {
+        return Array.from(this.realms.values()).map((e) => e.realm);
+    }
+    /**
+     * List realms for a specific runner.
+     */
+    listRealmsByRunner(runnerId) {
+        return Array.from(this.realms.values())
+            .filter((e) => e.realm.runnerId === runnerId)
+            .map((e) => e.realm);
+    }
+    /**
+     * Update realm state.
+     */
+    updateRealmState(realmId, state) {
+        const entry = this.realms.get(realmId);
+        if (entry) {
+            entry.realm.state = state;
+            entry.realm.updatedAt = new Date().toISOString();
+        }
+    }
+    /**
+     * Remove a realm.
+     */
+    removeRealm(realmId) {
+        this.realms.delete(realmId);
+    }
+    /**
+     * Clear all state (useful for testing).
+     */
+    clear() {
+        this.templatesByRunner.clear();
+        this.realms.clear();
+    }
+}
+//# sourceMappingURL=realm-registry.js.map

package/dist/src/services/realm-registry.js.map

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

package/dist/src/services/realm-scheduler.d.ts

@@ -0,0 +1,47 @@
+/**
+ * RealmScheduler — makes allocation decisions for session requests.
+ *
+ * Yggdrasil owns all scheduling policy:
+ *   - Which realm type?
+ *   - Which owner?
+ *   - Reuse allowed?
+ *   - Spawn allowed?
+ *   - Priority?
+ *
+ * Ratatoskr reports facts (CPU, memory, realms, templates).
+ * Yggdrasil decides. Ratatoskr may veto ("I cannot do that") but
+ * must never suggest alternatives — that is orchestration.
+ *
+ * Current implementation:
+ *   Simple first-fit by template match + online status.
+ *
+ * Future:
+ *   Resource-aware, owner-aware, cost-aware, affinity-aware,
+ *   informed by Ratatoskr's /state endpoint.
+ */
+import type { CreateSessionRequest, RealmAllocation, SessionCapability, RunnerInfo } from '../types/index.js';
+import { RealmRegistry } from './realm-registry.js';
+export declare class RealmScheduler {
+    private readonly registry;
+    private readonly getRunner;
+    constructor(registry: RealmRegistry, getRunner: (runnerId: string) => RunnerInfo | undefined);
+    /**
+     * Decide how to allocate a realm for a session request.
+     *
+     * Yggdrasil decides:
+     *   - Which runner
+     *   - Which template
+     *   - Whether to spawn new or attach to existing
+     *
+     * Priority order:
+     *   1. Attach to existing realm owned by this owner (persistent realm)
+     *   2. Attach to a pooled idle realm (pre-warmed)
+     *   3. Spawn a new realm on a healthy runner
+     */
+    schedule(request: CreateSessionRequest): Promise<RealmAllocation>;
+    /**
+     * Resolve default capabilities for a template type when not explicitly provided.
+     */
+    static defaultCapabilitiesFor(type: string): SessionCapability[];
+}
+//# sourceMappingURL=realm-scheduler.d.ts.map

package/dist/src/services/realm-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realm-scheduler.d.ts","sourceRoot":"","sources":["../../../src/services/realm-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,UAAU,EACX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAoBpD,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADT,QAAQ,EAAE,aAAa,EACvB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,UAAU,GAAG,SAAS;IAG1E;;;;;;;;;;;;OAYG;IACG,QAAQ,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC;IAqDvE;;OAEG;IACH,MAAM,CAAC,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,EAAE;CAGjE"}

package/dist/src/services/realm-scheduler.js

@@ -0,0 +1,112 @@
+/**
+ * RealmScheduler — makes allocation decisions for session requests.
+ *
+ * Yggdrasil owns all scheduling policy:
+ *   - Which realm type?
+ *   - Which owner?
+ *   - Reuse allowed?
+ *   - Spawn allowed?
+ *   - Priority?
+ *
+ * Ratatoskr reports facts (CPU, memory, realms, templates).
+ * Yggdrasil decides. Ratatoskr may veto ("I cannot do that") but
+ * must never suggest alternatives — that is orchestration.
+ *
+ * Current implementation:
+ *   Simple first-fit by template match + online status.
+ *
+ * Future:
+ *   Resource-aware, owner-aware, cost-aware, affinity-aware,
+ *   informed by Ratatoskr's /state endpoint.
+ */
+/**
+ * Map from SessionType to the required RealmTemplateType.
+ */
+const SESSION_TO_TEMPLATE = {
+    'computer-use': 'ubuntu',
+    'phone-use': 'android',
+};
+/**
+ * Default capabilities for a template when none are explicitly advertised.
+ */
+const DEFAULT_TEMPLATE_CAPABILITIES = {
+    ubuntu: ['observe', 'mouse', 'keyboard', 'scroll', 'clipboard'],
+    android: ['observe', 'touch', 'keyboard', 'scroll'],
+    browser: ['observe', 'keyboard'],
+    windows: ['observe', 'mouse', 'keyboard', 'scroll'],
+};
+export class RealmScheduler {
+    registry;
+    getRunner;
+    constructor(registry, getRunner) {
+        this.registry = registry;
+        this.getRunner = getRunner;
+    }
+    /**
+     * Decide how to allocate a realm for a session request.
+     *
+     * Yggdrasil decides:
+     *   - Which runner
+     *   - Which template
+     *   - Whether to spawn new or attach to existing
+     *
+     * Priority order:
+     *   1. Attach to existing realm owned by this owner (persistent realm)
+     *   2. Attach to a pooled idle realm (pre-warmed)
+     *   3. Spawn a new realm on a healthy runner
+     */
+    async schedule(request) {
+        const templateType = SESSION_TO_TEMPLATE[request.type];
+        if (!templateType) {
+            throw new Error(`No realm template available for session type: ${request.type}`);
+        }
+        // Priority 1: Persistent realm affinity by owner
+        if (request.ownerId) {
+            const existing = this.registry.findRealmByOwner(request.ownerId, templateType);
+            if (existing) {
+                const entry = this.registry.getEntry(existing.id);
+                return {
+                    runnerId: existing.runnerId,
+                    template: entry.template,
+                    action: 'attach',
+                    realmId: existing.id,
+                };
+            }
+        }
+        // Priority 2: Pooled idle realm
+        const pooled = this.registry.findPooledRealm(templateType);
+        if (pooled) {
+            const entry = this.registry.getEntry(pooled.id);
+            return {
+                runnerId: pooled.runnerId,
+                template: entry.template,
+                action: 'attach',
+                realmId: pooled.id,
+            };
+        }
+        // Priority 3: Find a runner that can host this template type
+        const candidates = this.registry.getTemplatesByType(templateType);
+        if (candidates.length === 0) {
+            throw new Error(`No runner available that can host realm type: ${templateType}`);
+        }
+        // Pick first healthy runner with capacity
+        for (const candidate of candidates) {
+            const runner = this.getRunner(candidate.runnerId);
+            if (runner && runner.status === 'online') {
+                return {
+                    runnerId: candidate.runnerId,
+                    template: candidate.template,
+                    action: 'spawn',
+                };
+            }
+        }
+        throw new Error(`No online runner available for realm type: ${templateType}`);
+    }
+    /**
+     * Resolve default capabilities for a template type when not explicitly provided.
+     */
+    static defaultCapabilitiesFor(type) {
+        return DEFAULT_TEMPLATE_CAPABILITIES[type] ?? ['observe'];
+    }
+}
+//# sourceMappingURL=realm-scheduler.js.map

package/dist/src/services/realm-scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realm-scheduler.js","sourceRoot":"","sources":["../../../src/services/realm-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAUH;;GAEG;AACH,MAAM,mBAAmB,GAA2B;IAClD,cAAc,EAAE,QAAQ;IACxB,WAAW,EAAE,SAAS;CACvB,CAAC;AAEF;;GAEG;AACH,MAAM,6BAA6B,GAAwC;IACzE,MAAM,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,CAAC;IAC/D,OAAO,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,CAAC;IACnD,OAAO,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC;IAChC,OAAO,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,CAAC;CACpD,CAAC;AAEF,MAAM,OAAO,cAAc;IAEN;IACA;IAFnB,YACmB,QAAuB,EACvB,SAAuD;QADvD,aAAQ,GAAR,QAAQ,CAAe;QACvB,cAAS,GAAT,SAAS,CAA8C;IACvE,CAAC;IAEJ;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,QAAQ,CAAC,OAA6B;QAC1C,MAAM,YAAY,GAAG,mBAAmB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACvD,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,iDAAiD,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QACnF,CAAC;QAED,iDAAiD;QACjD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC,OAAO,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;YAC/E,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;gBAClD,OAAO;oBACL,QAAQ,EAAE,QAAQ,CAAC,QAAQ;oBAC3B,QAAQ,EAAE,KAAM,CAAC,QAAQ;oBACzB,MAAM,EAAE,QAAQ;oBAChB,OAAO,EAAE,QAAQ,CAAC,EAAE;iBACrB,CAAC;YACJ,CAAC;QACH,CAAC;QAED,gCAAgC;QAChC,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;QAC3D,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YAChD,OAAO;gBACL,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,QAAQ,EAAE,KAAM,CAAC,QAAQ;gBACzB,MAAM,EAAE,QAAQ;gBAChB,OAAO,EAAE,MAAM,CAAC,EAAE;aACnB,CAAC;QACJ,CAAC;QAED,6DAA6D;QAC7D,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,kBAAkB,CAAC,YAAY,CAAC,CAAC;QAClE,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,iDAAiD,YAAY,EAAE,CAAC,CAAC;QACnF,CAAC;QAED,0CAA0C;QAC1C,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;YAClD,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;gBACzC,OAAO;oBACL,QAAQ,EAAE,SAAS,CAAC,QAAQ;oBAC5B,QAAQ,EAAE,SAAS,CAAC,QAAQ;oBAC5B,MAAM,EAAE,OAAO;iBAChB,CAAC;YACJ,CAAC;QACH,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,8CAA8C,YAAY,EAAE,CAAC,CAAC;IAChF,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,sBAAsB,CAAC,IAAY;QACxC,OAAO,6BAA6B,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC5D,CAAC;CACF"}

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

@@ -12,6 +12,194 @@ export interface LoggerConfig {
     format: 'json' | 'simple';
     transports: string[];
 }
+/**
+ * Registration payload sent by a Realm instance (via Ratatoskr) to Yggdrasil.
+ * Realm announces itself after boot.
+ */
+export interface RealmRegistration {
+    realmId: string;
+    runnerId: string;
+    /** The template type this realm was spawned from (e.g. "ubuntu", "android"). */
+    template: RealmTemplateType;
+    /** Realm software version. */
+    version: string;
+    /** Capabilities this realm instance provides. */
+    capabilities: SessionCapability[];
+    /** Live endpoints for observation and input. */
+    endpoints: {
+        observation: string;
+        input: string;
+    };
+    /** Future: Veil-issued token for authenticating registrations. */
+    registrationToken?: string | undefined;
+    startedAt: string;
+}
+/**
+ * Periodic heartbeat from a Realm instance (via Ratatoskr) to Yggdrasil.
+ */
+export interface RealmHeartbeat {
+    realmId: string;
+    uptime: number;
+    healthy: boolean;
+    memoryMb?: number | undefined;
+    cpuPercent?: number | undefined;
+    activeSessions: number;
+}
+/**
+ * Deregistration payload sent by a Realm instance on shutdown.
+ */
+export interface RealmDeregistration {
+    realmId: string;
+    reason: 'shutdown' | 'error' | 'replaced';
+}
+/** Supported session types for interaction with execution environments. */
+export type SessionType = 'computer-use' | 'phone-use';
+/** Lifecycle states for a session. */
+export type SessionState = 'creating' | 'active' | 'paused' | 'completed' | 'failed' | 'terminated';
+/** Observation method chosen by Realm — consumers must not depend on a specific implementation. */
+export type ObservationMethod = 'accessibility_tree' | 'dom_snapshot' | 'screenshot' | 'video_stream' | 'hybrid';
+/** Input capabilities a session may expose. */
+export type InputCapability = 'mouse' | 'keyboard' | 'touch' | 'scroll' | 'drag' | 'clipboard';
+/**
+ * Capabilities a session may support — used for session contracts and Veil authorization.
+ * Broader than InputCapability: includes observation and device-level capabilities.
+ */
+export type SessionCapability = 'observe' | 'mouse' | 'keyboard' | 'touch' | 'scroll' | 'drag' | 'clipboard' | 'audio' | 'camera';
+/** Types of execution environments a runner can host. */
+export type RealmTemplateType = 'ubuntu' | 'android' | 'browser' | 'windows';
+/** Lifecycle states for a Realm instance. */
+export type RealmState = 'creating' | 'running' | 'paused' | 'unhealthy' | 'destroyed';
+/**
+ * A realm template advertised by a runner via Ratatoskr.
+ * Templates describe what kinds of environments a runner CAN spawn,
+ * not what is currently running.
+ */
+export interface RealmTemplate {
+    id: string;
+    type: RealmTemplateType;
+    /** Capabilities this template provides when a realm is spawned (e.g. ["observe", "mouse", "keyboard"]). */
+    capabilities: SessionCapability[];
+}
+/**
+ * A running Realm instance — the actual execution environment that sessions attach to.
+ *
+ * Sessions do NOT run on runners. Sessions run on realms. Realms run on runners.
+ */
+export interface Realm {
+    id: string;
+    templateId: string;
+    runnerId: string;
+    /** The entity that owns or requested this realm (used for persistent realm affinity). */
+    ownerId?: string | undefined;
+    state: RealmState;
+    endpoints: {
+        /** Full URL for observation (e.g. screenshots, a11y tree). */
+        observation: string;
+        /** Full URL for input (e.g. click, type, scroll). */
+        input: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+    /** Timestamp of the last heartbeat received from this realm. */
+    lastHeartbeat?: string | undefined;
+    /** Future: Veil-issued token for authenticating realm operations. */
+    registrationToken?: string | undefined;
+    /** Pool tag — if set, this realm can be reused for sessions matching the same template+owner. */
+    poolTag?: string | undefined;
+}
+/**
+ * Result of a scheduling decision. The scheduler returns an allocation;
+ * the provisioner acts on it.
+ */
+export interface RealmAllocation {
+    runnerId: string;
+    template: RealmTemplate;
+    /** Whether to spawn a new realm or attach to an existing one. */
+    action: 'spawn' | 'attach';
+    /** Set when attaching to an existing realm. */
+    realmId?: string | undefined;
+}
+/**
+ * Descriptor for an active session.
+ *
+ * Yggdrasil is the **control plane** — it creates/terminates/pauses/resumes sessions.
+ * Realm is the **data plane** — observation and input go DIRECTLY to Realm endpoints,
+ * NOT through Yggdrasil.
+ *
+ * Consumers (Cognition via ComputerUseRuntime) use observationEndpoint and
+ * inputEndpoint to talk to Realm directly. Yggdrasil never proxies observe/input calls.
+ */
+export interface SessionDescriptor {
+    id: string;
+    type: SessionType;
+    state: SessionState;
+    /** Full Realm URL for observation (e.g. screenshots, a11y tree, DOM). Consumers talk to Realm directly. */
+    observationEndpoint: string;
+    /** Full Realm URL for input (e.g. click, type, scroll). Consumers talk to Realm directly. */
+    inputEndpoint: string;
+    /** Capabilities this session supports (e.g. ["mouse", "keyboard"]). */
+    capabilities: SessionCapability[];
+    /** The observation method Realm chose (internal detail — informational only). */
+    observationMethod: ObservationMethod;
+    /** Realm ID backing this session. */
+    realmId: string;
+    /** Identity of the entity that owns this session. */
+    ownerId?: string | undefined;
+    /** Identities of participants allowed to interact with this session. */
+    participantIds?: string[] | undefined;
+    createdAt: string;
+    updatedAt: string;
+    metadata?: Record<string, unknown> | undefined;
+}
+/** Request to create a new interaction session. */
+export interface CreateSessionRequest {
+    type: SessionType;
+    ownerId?: string | undefined;
+    participantIds?: string[] | undefined;
+    /** Requested capabilities for this session. If omitted, type defaults apply. */
+    capabilities?: SessionCapability[] | undefined;
+    realmId?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}
+/** Response from creating a session. */
+export interface CreateSessionResponse {
+    sessionId: string;
+    descriptor: SessionDescriptor;
+}
+/** Observation payload returned by a session's observe endpoint. */
+export interface SessionObservation {
+    /** Base64-encoded screenshot (when method is screenshot or hybrid). */
+    screenshot?: string | undefined;
+    /** Accessibility tree snapshot (when method is accessibility_tree or hybrid). */
+    accessibilityTree?: unknown;
+    /** DOM snapshot (when method is dom_snapshot or hybrid). */
+    domSnapshot?: unknown;
+    /** Whether PII redaction was applied. */
+    piiRedacted?: boolean | undefined;
+    /** Timestamp of the observation. */
+    timestamp: string;
+    /** Structured data for JSON-based observation (e.g. UI element tree). */
+    data?: Record<string, unknown> | undefined;
+}
+/** Input action sent to a session. */
+export interface SessionInput {
+    type: InputCapability;
+    params: Record<string, unknown>;
+}
+/** Result of an input action. */
+export interface SessionInputResult {
+    success: boolean;
+    error?: string | undefined;
+}
+/** Session health reported by Ratatoskr to Yggdrasil. */
+export interface SessionHealth {
+    sessionId: string;
+    state: SessionState;
+    realmId: string;
+    lastObservationAt?: string | undefined;
+    lastInputAt?: string | undefined;
+    errorCount: number;
+}
 export interface SystemResources {
     cpu: {
         load1: number;
@@ -30,10 +218,16 @@ export interface SystemResources {
 }
 export interface PendingUpdate {
     version: string;
+    /** Shell command to execute for the update (e.g. 'npm update -g @theaiinc/yggdrasil-ratatoskr'). */
     command?: string;
+    /** URL to download a new binary/package from. */
     downloadUrl?: string;
+    /** New API key for Yggdrasil authentication. Runner applies this and starts using it immediately. */
+    apiKey?: string;
+    /** Arbitrary metadata (e.g. Docker image tag, commit hash). */
     metadata?: Record<string, unknown>;
 }
+export type UpdateStatus = 'idle' | 'pending' | 'applying' | 'failed' | 'applied';
 export interface RunnerTask {
     taskId: string;
     type: string;
@@ -49,12 +243,18 @@ export interface RunnerInfo {
     endpoint: string;
     version: string;
     capabilities: string[];
+    /** Realm templates this runner can spawn. */
+    realmTemplates: RealmTemplate[];
     labels: Record<string, string>;
     lastHeartbeat: Date;
     status: 'online' | 'offline';
     resources?: SystemResources;
     tasks: RunnerTask[];
     pendingUpdate?: PendingUpdate;
+    /** Latest update status reported by the runner via heartbeat. */
+    updateStatus?: UpdateStatus;
+    /** Tail of the runner's update log (last N chars). */
+    updateLog?: string;
 }
 export interface RegisterRunnerPayload {
     runnerId?: string;
@@ -62,6 +262,8 @@ export interface RegisterRunnerPayload {
     endpoint?: string;
     version?: string;
     capabilities?: string[];
+    /** Realm templates this runner can spawn. */
+    realmTemplates?: RealmTemplate[];
     labels?: Record<string, string>;
     metadata?: Record<string, unknown>;
     resources?: SystemResources;
@@ -73,6 +275,10 @@ export interface HeartbeatPayload {
     status?: string;
     resources?: SystemResources;
     tasks?: RunnerTask[];
+    /** Update status reported by the runner. */
+    updateStatus?: UpdateStatus;
+    /** Tail of the runner's update log. */
+    updateLog?: string;
 }
 export interface HeartbeatResponse {
     status: string;