@elizaos/agent 2.0.0-alpha.98 → 2.0.0-beta.2

package/packages/agent/src/runtime/operations/health-checks.js

@@ -0,0 +1,186 @@
+/**
+ * Built-in health checks used by the runtime-operations health gate.
+ *
+ * Each check is a small, self-contained `HealthCheck`. The `HealthChecker`
+ * (in `health.ts`) runs them in parallel with per-check timeouts; required
+ * checks block promotion of a new/re-initialised runtime.
+ *
+ * Conventions:
+ *   - No shared mutable state across checks.
+ *   - Logger only (`[runtime-ops:health-checks]`).
+ *   - Treat optional/missing runtime surface as "not applicable, ok".
+ *   - Treat real failures (DB ping false, provider unreachable) as failures.
+ */
+import { logger, ModelType } from "@elizaos/core";
+import { isInsufficientCreditsError } from "../../api/credit-detection.js";
+const LOG_PREFIX = "[runtime-ops:health-checks]";
+function getDbAdapter(runtime) {
+    const adapter = runtime.adapter;
+    if (adapter == null || typeof adapter !== "object")
+        return null;
+    return adapter;
+}
+function asServiceRegistry(runtime) {
+    return runtime;
+}
+export function describeError(err) {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === "string")
+        return err;
+    try {
+        return JSON.stringify(err);
+    }
+    catch {
+        return String(err);
+    }
+}
+// ---------------------------------------------------------------------------
+// runtimeReadyCheck — character + agentId populated.
+// ---------------------------------------------------------------------------
+export const runtimeReadyCheck = {
+    name: "runtime-ready",
+    required: true,
+    timeoutMs: 1000,
+    async run(runtime) {
+        if (!runtime || typeof runtime !== "object") {
+            return { ok: false, reason: "runtime is not an object" };
+        }
+        const agentId = runtime.agentId;
+        if (typeof agentId !== "string" || agentId.length === 0) {
+            return { ok: false, reason: "runtime.agentId is empty" };
+        }
+        const character = runtime.character;
+        if (!character || typeof character !== "object") {
+            return { ok: false, reason: "runtime.character is missing" };
+        }
+        const name = typeof character.name === "string" ? character.name.trim() : "";
+        if (name.length === 0) {
+            return { ok: false, reason: "runtime.character.name is empty" };
+        }
+        return { ok: true };
+    },
+};
+// ---------------------------------------------------------------------------
+// essentialServicesCheck — no registered service is in a failed state.
+// ---------------------------------------------------------------------------
+export const essentialServicesCheck = {
+    name: "essential-services",
+    required: true,
+    timeoutMs: 2000,
+    async run(runtime) {
+        const reg = asServiceRegistry(runtime);
+        if (typeof reg.getRegisteredServiceTypes !== "function") {
+            // Older runtime build without the enumeration API. Cannot enforce
+            // anything reliably — silent pass beats a wrong fail.
+            logger.debug(`${LOG_PREFIX} runtime.getRegisteredServiceTypes unavailable; skipping`);
+            return { ok: true };
+        }
+        const types = reg.getRegisteredServiceTypes();
+        if (!Array.isArray(types) || types.length === 0) {
+            return { ok: true };
+        }
+        if (typeof reg.getServiceRegistrationStatus !== "function") {
+            return { ok: true };
+        }
+        for (const type of types) {
+            const status = reg.getServiceRegistrationStatus(type);
+            if (status === "failed") {
+                return {
+                    ok: false,
+                    reason: `service ${type} is in failed state`,
+                };
+            }
+        }
+        return { ok: true };
+    },
+};
+// ---------------------------------------------------------------------------
+// dbConnectionCheck — adapter.isReady() returns true (when adapter exists).
+// ---------------------------------------------------------------------------
+export const dbConnectionCheck = {
+    name: "db-connection",
+    required: true,
+    timeoutMs: 1500,
+    async run(runtime) {
+        const adapter = getDbAdapter(runtime);
+        if (!adapter) {
+            // Runtime without a database adapter (rare but supported) — pass.
+            return { ok: true };
+        }
+        if (typeof adapter.isReady !== "function") {
+            // Older adapter without isReady — best-effort pass; don't block on
+            // a missing API surface we cannot probe.
+            return { ok: true };
+        }
+        try {
+            const ready = await adapter.isReady();
+            if (ready === true)
+                return { ok: true };
+            return { ok: false, reason: "adapter.isReady() returned false" };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                reason: `adapter.isReady() threw: ${describeError(err)}`,
+                cause: err,
+            };
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// providerSmokeCheck — minimal useModel call to confirm the provider
+// pipeline is wired and reachable.
+// ---------------------------------------------------------------------------
+export const providerSmokeCheck = {
+    name: "provider-smoke",
+    required: true,
+    timeoutMs: 5000,
+    async run(runtime) {
+        if (typeof runtime.useModel !== "function") {
+            // Older / stripped runtime — no model surface to probe.
+            return { ok: true };
+        }
+        try {
+            // Tiny, deterministic prompt with a hard 1-token cap. Empty completions
+            // still count as "model responded" — we only need transport health.
+            await runtime.useModel(ModelType.TEXT_SMALL, {
+                prompt: "ping",
+                maxTokens: 1,
+                temperature: 0,
+            });
+            return { ok: true };
+        }
+        catch (err) {
+            if (isInsufficientCreditsError(err)) {
+                return {
+                    ok: false,
+                    reason: "provider quota exhausted",
+                    cause: err,
+                };
+            }
+            const name = err instanceof Error ? err.name : "";
+            // The AI SDK throws AI_NoOutputGeneratedError when the model returned
+            // zero tokens. That's still a healthy transport: the request reached
+            // the provider, the provider replied, just with no text. Treat as ok.
+            if (name === "AI_NoOutputGeneratedError") {
+                return { ok: true };
+            }
+            return {
+                ok: false,
+                reason: `provider unreachable: ${describeError(err)}`,
+                cause: err,
+            };
+        }
+    },
+};
+/**
+ * The full set of built-in checks pre-registered by the default checker.
+ * Order is not significant — checks run in parallel.
+ */
+export const builtInHealthChecks = [
+    runtimeReadyCheck,
+    essentialServicesCheck,
+    dbConnectionCheck,
+    providerSmokeCheck,
+];

package/packages/agent/src/runtime/operations/health.d.ts

@@ -0,0 +1,32 @@
+/**
+ * HealthChecker — the runtime-operations health gate.
+ *
+ * Reload strategies (hot/warm/cold) call `runForRuntime(newRuntime)` after
+ * applying their change. Promotion to primary is allowed only when every
+ * REQUIRED check passes. Optional checks surface in the report's `failed[]`
+ * but never flip `ok` to false.
+ *
+ * Execution model:
+ *   - All registered checks run in parallel (Promise.allSettled).
+ *   - Each check's `run(runtime)` is wrapped in a Promise.race against a
+ *     per-check timeout sentinel (`check.timeoutMs`).
+ *   - One slow optional check cannot block required checks from finishing.
+ *
+ * Logging prefix: `[runtime-ops:health]`.
+ */
+import { type AgentRuntime } from "@elizaos/core";
+import type { HealthCheck, HealthCheckReport } from "./types.ts";
+export declare class HealthChecker {
+    private readonly checks;
+    register(check: HealthCheck): void;
+    unregister(name: string): void;
+    /** Internal — exposed for tests so they can assert deterministic state. */
+    list(): readonly HealthCheck[];
+    runForRuntime(runtime: AgentRuntime): Promise<HealthCheckReport>;
+}
+/**
+ * Lazy per-process singleton, pre-registered with the four built-in checks.
+ * Tests can construct their own `HealthChecker` directly.
+ */
+export declare function getDefaultHealthChecker(): HealthChecker;
+//# sourceMappingURL=health.d.ts.map

package/packages/agent/src/runtime/operations/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../../../../../src/runtime/operations/health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAU,MAAM,eAAe,CAAC;AAE1D,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAWpB,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;IAEzD,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAiBlC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B,2EAA2E;IAC3E,IAAI,IAAI,SAAS,WAAW,EAAE;IAIxB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,iBAAiB,CAAC;CA8DvE;AAiDD;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,aAAa,CASvD"}

package/packages/agent/src/runtime/operations/health.js

@@ -0,0 +1,139 @@
+/**
+ * HealthChecker — the runtime-operations health gate.
+ *
+ * Reload strategies (hot/warm/cold) call `runForRuntime(newRuntime)` after
+ * applying their change. Promotion to primary is allowed only when every
+ * REQUIRED check passes. Optional checks surface in the report's `failed[]`
+ * but never flip `ok` to false.
+ *
+ * Execution model:
+ *   - All registered checks run in parallel (Promise.allSettled).
+ *   - Each check's `run(runtime)` is wrapped in a Promise.race against a
+ *     per-check timeout sentinel (`check.timeoutMs`).
+ *   - One slow optional check cannot block required checks from finishing.
+ *
+ * Logging prefix: `[runtime-ops:health]`.
+ */
+import { logger } from "@elizaos/core";
+import { builtInHealthChecks, describeError } from "./health-checks.js";
+const LOG_PREFIX = "[runtime-ops:health]";
+export class HealthChecker {
+    checks = new Map();
+    register(check) {
+        if (!check || typeof check.name !== "string" || check.name.length === 0) {
+            throw new Error(`${LOG_PREFIX} register: check.name is required`);
+        }
+        if (typeof check.run !== "function") {
+            throw new Error(`${LOG_PREFIX} register: check.run must be a function (${check.name})`);
+        }
+        if (typeof check.timeoutMs !== "number" || check.timeoutMs <= 0) {
+            throw new Error(`${LOG_PREFIX} register: check.timeoutMs must be > 0 (${check.name})`);
+        }
+        this.checks.set(check.name, check);
+    }
+    unregister(name) {
+        this.checks.delete(name);
+    }
+    /** Internal — exposed for tests so they can assert deterministic state. */
+    list() {
+        return Array.from(this.checks.values());
+    }
+    async runForRuntime(runtime) {
+        const registered = Array.from(this.checks.values());
+        if (registered.length === 0) {
+            return { passed: [], failed: [], ok: true };
+        }
+        const settled = await Promise.allSettled(registered.map((check) => runOne(check, runtime)));
+        const passed = [];
+        const failed = [];
+        settled.forEach((res, idx) => {
+            const check = registered[idx];
+            if (res.status === "fulfilled") {
+                const { name, required, durationMs, result } = res.value;
+                if (result.ok === true) {
+                    passed.push({ name, durationMs });
+                }
+                else {
+                    failed.push({
+                        name,
+                        required,
+                        reason: result.reason,
+                        durationMs,
+                    });
+                }
+            }
+            else {
+                // Should never hit — runOne catches everything — but fail safe.
+                failed.push({
+                    name: check.name,
+                    required: check.required,
+                    reason: `internal: ${describeError(res.reason)}`,
+                    durationMs: 0,
+                });
+            }
+        });
+        const ok = failed.every((f) => f.required === false);
+        if (failed.length > 0) {
+            logger.warn(`${LOG_PREFIX} report ok=${ok} passed=${passed.length} failed=${failed.length}`);
+            for (const f of failed) {
+                logger.warn(`${LOG_PREFIX} failed name=${f.name} required=${f.required} reason=${f.reason} durationMs=${f.durationMs}`);
+            }
+        }
+        else {
+            logger.debug(`${LOG_PREFIX} report ok=true passed=${passed.length} failed=0`);
+        }
+        return { passed, failed, ok };
+    }
+}
+async function runOne(check, runtime) {
+    const startedAt = Date.now();
+    let timeoutHandle;
+    const timeoutPromise = new Promise((resolve) => {
+        timeoutHandle = setTimeout(() => {
+            resolve({
+                ok: false,
+                reason: `timeout after ${check.timeoutMs}ms`,
+            });
+        }, check.timeoutMs);
+    });
+    try {
+        const result = await Promise.race([
+            Promise.resolve()
+                .then(() => check.run(runtime))
+                .catch((err) => ({
+                ok: false,
+                reason: `threw: ${describeError(err)}`,
+                cause: err,
+            })),
+            timeoutPromise,
+        ]);
+        return {
+            name: check.name,
+            required: check.required,
+            durationMs: Date.now() - startedAt,
+            result,
+        };
+    }
+    finally {
+        if (timeoutHandle)
+            clearTimeout(timeoutHandle);
+    }
+}
+// ---------------------------------------------------------------------------
+// Default singleton. Lazy, swappable in tests.
+// ---------------------------------------------------------------------------
+let cachedDefault = null;
+/**
+ * Lazy per-process singleton, pre-registered with the four built-in checks.
+ * Tests can construct their own `HealthChecker` directly.
+ */
+export function getDefaultHealthChecker() {
+    if (!cachedDefault) {
+        const checker = new HealthChecker();
+        for (const check of builtInHealthChecks) {
+            checker.register(check);
+        }
+        cachedDefault = checker;
+    }
+    return cachedDefault;
+}

package/packages/agent/src/runtime/operations/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * RuntimeOperation public surface.
+ *
+ * Implementations are sibling files; this barrel keeps consumers off the
+ * individual paths.
+ */
+export { type ClassifyContext, classifyOperation, defaultClassifier, } from "./classifier.ts";
+export type { ColdStrategyOptions } from "./cold-strategy.ts";
+export { createColdStrategy } from "./cold-strategy.ts";
+export { getDefaultHealthChecker, HealthChecker } from "./health.ts";
+export { builtInHealthChecks, dbConnectionCheck, essentialServicesCheck, providerSmokeCheck, runtimeReadyCheck, } from "./health-checks.ts";
+export { DefaultRuntimeOperationManager, type DefaultRuntimeOperationManagerOptions, type IntentClassifier, } from "./manager.ts";
+export { createHotStrategy, type HotStrategyDeps } from "./reload-hot.ts";
+export { FilesystemRuntimeOperationRepository, getDefaultRepository, } from "./repository.ts";
+export * from "./types.ts";
+export { _resetDefaultSecretsManagerForTesting, defaultSecretsManager, formatVaultRef, isVaultRef, parseVaultRef, persistProviderApiKey, resolveConfigEnvForProcess, resolveProviderApiKey, type VaultLike, vaultKeyForProviderApiKey, } from "./vault-bridge.ts";
+//# sourceMappingURL=index.d.ts.map

package/packages/agent/src/runtime/operations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/runtime/operations/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,KAAK,eAAe,EACpB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,8BAA8B,EAC9B,KAAK,qCAAqC,EAC1C,KAAK,gBAAgB,GACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EACL,oCAAoC,EACpC,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,OAAO,EACL,qCAAqC,EACrC,qBAAqB,EACrB,cAAc,EACd,UAAU,EACV,aAAa,EACb,qBAAqB,EACrB,0BAA0B,EAC1B,qBAAqB,EACrB,KAAK,SAAS,EACd,yBAAyB,GAC1B,MAAM,mBAAmB,CAAC"}

package/packages/agent/src/runtime/operations/index.js

@@ -0,0 +1,15 @@
+/**
+ * RuntimeOperation public surface.
+ *
+ * Implementations are sibling files; this barrel keeps consumers off the
+ * individual paths.
+ */
+export { classifyOperation, defaultClassifier, } from "./classifier.js";
+export { createColdStrategy } from "./cold-strategy.js";
+export { getDefaultHealthChecker, HealthChecker } from "./health.js";
+export { builtInHealthChecks, dbConnectionCheck, essentialServicesCheck, providerSmokeCheck, runtimeReadyCheck, } from "./health-checks.js";
+export { DefaultRuntimeOperationManager, } from "./manager.js";
+export { createHotStrategy } from "./reload-hot.js";
+export { FilesystemRuntimeOperationRepository, getDefaultRepository, } from "./repository.js";
+export * from "./types.js";
+export { _resetDefaultSecretsManagerForTesting, defaultSecretsManager, formatVaultRef, isVaultRef, parseVaultRef, persistProviderApiKey, resolveConfigEnvForProcess, resolveProviderApiKey, vaultKeyForProviderApiKey, } from "./vault-bridge.js";

package/packages/agent/src/runtime/operations/manager.d.ts

@@ -0,0 +1,70 @@
+/**
+ * DefaultRuntimeOperationManager — the single use case for state-changing
+ * lifecycle actions against the live runtime.
+ *
+ * Lifecycle:
+ *   1. Caller (route layer) hands us an OperationIntent (already validated).
+ *   2. We classify the intent into a ReloadTier.
+ *   3. If an op is already active we reject with `rejected-busy`. If an
+ *      idempotency key matches a record within retention we return
+ *      `deduped`. Otherwise we accept synchronously and run the op
+ *      asynchronously on the next microtask.
+ *   4. Each phase mutation is appended to the repo. The repo's active-op
+ *      slot is the single-flight gate; no extra in-memory mutex is used
+ *      across operations, but the manager serializes its own
+ *      `executeOperation` calls via a Promise chain.
+ */
+import type { AgentRuntime } from "@elizaos/core";
+import type { ClassifyContext } from "./classifier.ts";
+import type { HealthChecker } from "./health.ts";
+import type { OperationIntent, ReloadStrategy, ReloadTier, RuntimeOperation, RuntimeOperationListOptions, RuntimeOperationManager, RuntimeOperationRepository, StartOperationOutcome, StartOperationRequest } from "./types.ts";
+export type IntentClassifier = (intent: OperationIntent, ctx: ClassifyContext) => ReloadTier;
+export interface DefaultRuntimeOperationManagerOptions {
+    repository: RuntimeOperationRepository;
+    /**
+     * Resolves the *current* live runtime. Called per-operation so the
+     * manager always sees the latest reference (cold ops swap it).
+     */
+    runtime: () => AgentRuntime | null;
+    /**
+     * Snapshots the live config slice the classifier needs. Called once per
+     * `start()` so the classifier sees the state at submission time, not at
+     * execution time (which may be after another op completes).
+     */
+    classifyContext: () => ClassifyContext;
+    /**
+     * Defaults to `() => "cold"` (conservative). Wire `defaultClassifier`
+     * from `./classifier.js` to enable hot/warm tiering.
+     */
+    classifier?: IntentClassifier;
+    healthChecker: HealthChecker;
+    /**
+     * Tier → strategy. The cold strategy is required for Phase 1; warm/hot
+     * are optional and added by sibling agents.
+     */
+    strategies: Partial<Record<ReloadTier, ReloadStrategy>>;
+}
+export declare class DefaultRuntimeOperationManager implements RuntimeOperationManager {
+    private readonly repository;
+    private readonly runtime;
+    private readonly classifyContext;
+    private readonly classifier;
+    private readonly healthChecker;
+    private readonly strategies;
+    /**
+     * Serializes `executeOperation` invocations within a single process.
+     * The repo's active-op slot is the cross-process gate.
+     */
+    private executionChain;
+    private startChain;
+    constructor(opts: DefaultRuntimeOperationManagerOptions);
+    start(req: StartOperationRequest): Promise<StartOperationOutcome>;
+    private startLocked;
+    get(id: string): Promise<RuntimeOperation | null>;
+    list(opts?: RuntimeOperationListOptions): Promise<RuntimeOperation[]>;
+    findActive(): Promise<RuntimeOperation | null>;
+    private scheduleExecution;
+    private executeOperation;
+    private failOperation;
+}
+//# sourceMappingURL=manager.d.ts.map

package/packages/agent/src/runtime/operations/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../../../../src/runtime/operations/manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAGV,eAAe,EAEf,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,2BAA2B,EAC3B,uBAAuB,EACvB,0BAA0B,EAC1B,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,gBAAgB,GAAG,CAC7B,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,eAAe,KACjB,UAAU,CAAC;AAEhB,MAAM,WAAW,qCAAqC;IACpD,UAAU,EAAE,0BAA0B,CAAC;IACvC;;;OAGG;IACH,OAAO,EAAE,MAAM,YAAY,GAAG,IAAI,CAAC;IACnC;;;;OAIG;IACH,eAAe,EAAE,MAAM,eAAe,CAAC;IACvC;;;OAGG;IACH,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,aAAa,EAAE,aAAa,CAAC;IAC7B;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC;CACzD;AASD,qBAAa,8BAA+B,YAAW,uBAAuB;IAC5E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAwB;IACxD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmB;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA8C;IACzE;;;OAGG;IACH,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,UAAU,CAAoC;gBAE1C,IAAI,EAAE,qCAAqC;IASjD,KAAK,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC;YAgBzD,WAAW;IAmDnB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAIjD,IAAI,CAAC,IAAI,CAAC,EAAE,2BAA2B,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAIrE,UAAU,IAAI,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAIpD,OAAO,CAAC,iBAAiB;YAUX,gBAAgB;YAqGhB,aAAa;CAa5B"}

package/packages/agent/src/runtime/operations/manager.js

@@ -0,0 +1,202 @@
+/**
+ * DefaultRuntimeOperationManager — the single use case for state-changing
+ * lifecycle actions against the live runtime.
+ *
+ * Lifecycle:
+ *   1. Caller (route layer) hands us an OperationIntent (already validated).
+ *   2. We classify the intent into a ReloadTier.
+ *   3. If an op is already active we reject with `rejected-busy`. If an
+ *      idempotency key matches a record within retention we return
+ *      `deduped`. Otherwise we accept synchronously and run the op
+ *      asynchronously on the next microtask.
+ *   4. Each phase mutation is appended to the repo. The repo's active-op
+ *      slot is the single-flight gate; no extra in-memory mutex is used
+ *      across operations, but the manager serializes its own
+ *      `executeOperation` calls via a Promise chain.
+ */
+import crypto from "node:crypto";
+import { logger } from "@elizaos/core";
+const DEFAULT_CLASSIFIER = () => "cold";
+function strategyErrorCode(err) {
+    const code = err?.code;
+    return code === "vault-resolve-failed" ? code : "strategy-failed";
+}
+export class DefaultRuntimeOperationManager {
+    repository;
+    runtime;
+    classifyContext;
+    classifier;
+    healthChecker;
+    strategies;
+    /**
+     * Serializes `executeOperation` invocations within a single process.
+     * The repo's active-op slot is the cross-process gate.
+     */
+    executionChain = Promise.resolve();
+    startChain = Promise.resolve();
+    constructor(opts) {
+        this.repository = opts.repository;
+        this.runtime = opts.runtime;
+        this.classifyContext = opts.classifyContext;
+        this.classifier = opts.classifier ?? DEFAULT_CLASSIFIER;
+        this.healthChecker = opts.healthChecker;
+        this.strategies = opts.strategies;
+    }
+    async start(req) {
+        let outcome;
+        const run = this.startChain.then(async () => {
+            outcome = await this.startLocked(req);
+        });
+        this.startChain = run.then(() => undefined, () => undefined);
+        await run;
+        if (!outcome) {
+            throw new Error("[runtime-ops] start did not produce an outcome");
+        }
+        return outcome;
+    }
+    async startLocked(req) {
+        if (req.idempotencyKey) {
+            const existing = await this.repository.findByIdempotencyKey(req.idempotencyKey);
+            if (existing) {
+                logger.info(`[runtime-ops] Idempotent hit for key=${req.idempotencyKey} → ${existing.id}`);
+                return { kind: "deduped", operation: existing };
+            }
+        }
+        const active = await this.repository.findActive();
+        if (active) {
+            logger.info(`[runtime-ops] Rejected new op: active operation in flight ${active.id}`);
+            return { kind: "rejected-busy", activeOperationId: active.id };
+        }
+        const prepareResult = req.prepare ? await req.prepare() : undefined;
+        const preparedIntent = prepareResult === undefined ? req.intent : prepareResult;
+        const tier = this.classifier(preparedIntent, this.classifyContext());
+        const now = Date.now();
+        const op = {
+            id: crypto.randomUUID(),
+            kind: preparedIntent.kind,
+            intent: preparedIntent,
+            tier,
+            idempotencyKey: req.idempotencyKey,
+            status: "pending",
+            phases: [],
+            startedAt: now,
+        };
+        await this.repository.create(op);
+        logger.info(`[runtime-ops] Accepted op ${op.id} kind=${op.kind} tier=${op.tier}`);
+        // Schedule async; do NOT await. The route caller returns 202
+        // immediately and the client polls /events for status.
+        this.scheduleExecution(op.id);
+        return { kind: "accepted", operation: op };
+    }
+    async get(id) {
+        return this.repository.get(id);
+    }
+    async list(opts) {
+        return this.repository.list(opts);
+    }
+    async findActive() {
+        return this.repository.findActive();
+    }
+    scheduleExecution(id) {
+        this.executionChain = this.executionChain.then(() => this.executeOperation(id).catch((err) => {
+            logger.error(`[runtime-ops] Unhandled error executing op ${id}: ${err instanceof Error ? err.stack : String(err)}`);
+        }));
+    }
+    async executeOperation(id) {
+        const op = await this.repository.get(id);
+        if (!op) {
+            logger.warn(`[runtime-ops] executeOperation: op ${id} not found`);
+            return;
+        }
+        await this.repository.update(id, { status: "running" });
+        // Phase: validate (the route layer already validated; this records the
+        // gate boundary so the phase log is complete).
+        const validateAt = Date.now();
+        await this.repository.appendPhase(id, {
+            name: "validate",
+            status: "succeeded",
+            startedAt: validateAt,
+            finishedAt: validateAt,
+        });
+        const strategy = this.strategies[op.tier];
+        if (!strategy) {
+            await this.failOperation(id, {
+                message: `No strategy registered for tier=${op.tier}`,
+                code: "no-strategy-for-tier",
+            });
+            return;
+        }
+        const runtime = this.runtime();
+        if (!runtime) {
+            await this.failOperation(id, {
+                message: "No live runtime available to apply operation",
+                code: "no-runtime",
+            });
+            return;
+        }
+        const reportPhase = (phase) => this.repository.appendPhase(id, phase);
+        let newRuntime;
+        try {
+            newRuntime = await strategy.apply({
+                runtime,
+                intent: op.intent,
+                reportPhase,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.warn(`[runtime-ops] Strategy failed for op ${id}: ${message}`);
+            await this.failOperation(id, { message, code: strategyErrorCode(err) });
+            return;
+        }
+        // Phase: health-check.
+        const healthStart = Date.now();
+        await this.repository.appendPhase(id, {
+            name: "health-check",
+            status: "running",
+            startedAt: healthStart,
+        });
+        const report = await this.healthChecker.runForRuntime(newRuntime);
+        const healthEnd = Date.now();
+        if (!report.ok) {
+            await this.repository.updateLastPhase(id, {
+                status: "failed",
+                finishedAt: healthEnd,
+                detail: {
+                    passed: report.passed,
+                    failed: report.failed,
+                },
+            });
+            // The cold strategy has already swapped the runtime by the time we
+            // observe a failed health check. Surface the failure; rollback to the
+            // previous runtime is not implemented yet.
+            logger.warn(`[runtime-ops] Health check failed for op ${id}`);
+            await this.failOperation(id, {
+                message: "Required health checks failed",
+                code: "health-check-failed",
+            });
+            return;
+        }
+        await this.repository.updateLastPhase(id, {
+            status: "succeeded",
+            finishedAt: healthEnd,
+            detail: {
+                passed: report.passed,
+                failed: report.failed,
+            },
+        });
+        await this.repository.update(id, {
+            status: "succeeded",
+            finishedAt: Date.now(),
+        });
+        logger.info(`[runtime-ops] Operation ${id} succeeded`);
+    }
+    async failOperation(id, error) {
+        await this.repository.update(id, {
+            status: "failed",
+            finishedAt: Date.now(),
+            error,
+        });
+        logger.warn(`[runtime-ops] Operation ${id} failed: ${error.code ?? "unknown"} — ${error.message}`);
+    }
+}