@theaiinc/yggdrasil 0.2.3 → 0.3.0

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":"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"}

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;
@@ -49,6 +237,8 @@ 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';
@@ -62,6 +252,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;

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

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

package/package.json

@@ -1,12 +1,24 @@
 {
   "name": "@theaiinc/yggdrasil",
-  "version": "0.2.3",
-  "description": "Distributed runner orchestration controller — registration, heartbeat, task dispatch, lease management, and Prometheus metrics for Ratatoskr agents",
+  "version": "0.3.0",
+  "description": "Distributed runner orchestration controller — registration, heartbeat, task dispatch, lease management, Realm lifecycle, and Prometheus metrics for Ratatoskr agents",
   "author": "The AI Inc",
   "license": "MIT",
   "type": "module",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theaiinc/yggdrasil.git",
+    "directory": "packages/yggdrasil"
+  },
+  "homepage": "https://github.com/theaiinc/yggdrasil/blob/main/packages/yggdrasil/README.md",
+  "bugs": {
+    "url": "https://github.com/theaiinc/yggdrasil/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsc -p ./tsconfig.json",
     "dev": "nodemon --exec \"node --loader ts-node/esm src/orchestration-controller.ts\"",