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

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

@@ -0,0 +1,203 @@
+/**
+ * RuntimeOperation contracts — the single model for any state-changing
+ * lifecycle action against the live runtime (provider switch, plugin
+ * enable/disable, config reload, full restart).
+ *
+ * Design invariants:
+ *
+ *   1. Single queue. One operation runs at a time. New requests while an op
+ *      is running return 409 with the active op's id.
+ *   2. Tiered execution. The use case classifies an intent into a reload
+ *      tier (hot / warm / cold).
+ *   3. Health-gated promotion. A new/re-initialised runtime only "wins"
+ *      after health checks pass.
+ *   4. Append-only phase log. Each phase mutation is a new entry — never
+ *      patched in place (except `updateLastPhase`, for running→succeeded).
+ *   5. Idempotency keys de-dupe retries within the retention window.
+ */
+import type { AgentRuntime } from "@elizaos/core";
+export interface ProviderSwitchIntent {
+    kind: "provider-switch";
+    provider: string;
+    /**
+     * Vault key that resolves to the provider's API key (e.g.
+     * `"providers.openai.api-key"`). The actual secret never travels through
+     * the intent — only this stable identifier — so persisted operation
+     * records cannot leak credentials. Resolved at apply-env time via
+     * `SecretsManager.get(apiKeyRef)`.
+     */
+    apiKeyRef?: string;
+    primaryModel?: string;
+}
+export interface ConfigReloadIntent {
+    kind: "config-reload";
+    /**
+     * Optional list of dotted config paths that changed. When present, the
+     * classifier can choose hot/warm based on which keys moved.
+     */
+    changedPaths?: readonly string[];
+}
+export interface PluginEnableIntent {
+    kind: "plugin-enable";
+    pluginId: string;
+}
+export interface PluginDisableIntent {
+    kind: "plugin-disable";
+    pluginId: string;
+}
+export interface RestartIntent {
+    kind: "restart";
+    reason: string;
+}
+export type OperationIntent = ProviderSwitchIntent | ConfigReloadIntent | PluginEnableIntent | PluginDisableIntent | RestartIntent;
+export type OperationKind = OperationIntent["kind"];
+/**
+ * Reload tiers, ordered by cost ascending.
+ *
+ *   hot  — env-var or in-memory swap; plugins notified via callback.
+ *          Bounded ~100ms. No service lifecycle touched.
+ *   warm — re-init of one or more plugins' services. Bounded 1–3s.
+ *          Other plugins keep their state.
+ *   cold — full runtime swap (current handleRestart). 15–60s.
+ *
+ * The classifier MUST upgrade conservatively when uncertain: hot → warm,
+ * warm → cold. Downgrading a cold change to warm risks corrupt state.
+ */
+export type ReloadTier = "hot" | "warm" | "cold";
+export type OperationStatus = "pending" | "running" | "succeeded" | "failed" | "rolled-back";
+export type PhaseStatus = "pending" | "running" | "succeeded" | "failed" | "skipped";
+export type PhaseName = "validate" | "cold-restart" | "apply-env" | "notify-plugins" | "health-check";
+export type OperationErrorCode = "abandoned" | "no-strategy-for-tier" | "no-runtime" | "strategy-failed" | "vault-resolve-failed" | "health-check-failed";
+export interface OperationError {
+    message: string;
+    code?: OperationErrorCode;
+    cause?: string;
+}
+export interface OperationPhase {
+    name: PhaseName;
+    status: PhaseStatus;
+    startedAt?: number;
+    finishedAt?: number;
+    error?: OperationError;
+    /** Optional structured detail surfaced to the UI / logs. */
+    detail?: Record<string, unknown>;
+}
+export interface RuntimeOperation {
+    id: string;
+    kind: OperationKind;
+    intent: OperationIntent;
+    tier: ReloadTier;
+    idempotencyKey?: string;
+    status: OperationStatus;
+    phases: OperationPhase[];
+    fromConfigVersion?: number;
+    toConfigVersion?: number;
+    startedAt: number;
+    finishedAt?: number;
+    error?: OperationError;
+}
+export interface RuntimeOperationListOptions {
+    limit?: number;
+    status?: OperationStatus;
+    /** When true, include rolled-back / failed ops in the result. */
+    includeTerminal?: boolean;
+}
+export interface RuntimeOperationRepository {
+    create(op: RuntimeOperation): Promise<void>;
+    /**
+     * Patch top-level fields. Phases are append-only — use appendPhase /
+     * updatePhase for those.
+     */
+    update(id: string, patch: Partial<Omit<RuntimeOperation, "id" | "phases" | "intent" | "kind">>): Promise<void>;
+    appendPhase(id: string, phase: OperationPhase): Promise<void>;
+    /**
+     * Update the LAST phase only (for transitioning pending → running →
+     * succeeded). Earlier phases are immutable once finished.
+     */
+    updateLastPhase(id: string, patch: Partial<OperationPhase>): Promise<void>;
+    get(id: string): Promise<RuntimeOperation | null>;
+    list(opts?: RuntimeOperationListOptions): Promise<RuntimeOperation[]>;
+    findByIdempotencyKey(key: string): Promise<RuntimeOperation | null>;
+    /** Returns the active (running) operation, if any. */
+    findActive(): Promise<RuntimeOperation | null>;
+}
+export type HealthCheckResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+    cause?: unknown;
+};
+export interface HealthCheck {
+    name: string;
+    /**
+     * Required checks block promotion. Optional checks are reported in the
+     * operation phase detail but do not fail the operation.
+     */
+    required: boolean;
+    /** Soft timeout in ms. The runner enforces it. */
+    timeoutMs: number;
+    run(runtime: AgentRuntime): Promise<HealthCheckResult>;
+}
+export interface HealthCheckReport {
+    passed: readonly {
+        name: string;
+        durationMs: number;
+    }[];
+    failed: readonly {
+        name: string;
+        required: boolean;
+        reason: string;
+        durationMs: number;
+    }[];
+    /** True only when every REQUIRED check passed. */
+    ok: boolean;
+}
+export interface ReloadContext {
+    runtime: AgentRuntime;
+    intent: OperationIntent;
+    /** Phase reporter — call for every meaningful step inside a strategy. */
+    reportPhase: (phase: OperationPhase) => Promise<void>;
+}
+export interface ReloadStrategy {
+    tier: ReloadTier;
+    /**
+     * Apply the change. Return the (possibly new) runtime to install as
+     * primary. For hot/warm, this is typically the same runtime; for cold,
+     * it's a freshly bootstrapped one.
+     */
+    apply(ctx: ReloadContext): Promise<AgentRuntime>;
+}
+export interface StartOperationRequest {
+    intent: OperationIntent;
+    idempotencyKey?: string;
+    /**
+     * Runs after the idempotency and active-operation gates pass, but before
+     * the operation is persisted and scheduled. Use for accepted-only side
+     * effects that must complete before the strategy can run.
+     */
+    prepare?: () => Promise<OperationIntent | undefined>;
+}
+export type StartOperationOutcome = 
+/** Newly accepted; will run async. Caller polls /events for status. */
+{
+    kind: "accepted";
+    operation: RuntimeOperation;
+}
+/** Idempotent hit — same key, same intent already in flight or done. */
+ | {
+    kind: "deduped";
+    operation: RuntimeOperation;
+}
+/** Another operation is currently active. Caller should retry later. */
+ | {
+    kind: "rejected-busy";
+    activeOperationId: string;
+};
+export interface RuntimeOperationManager {
+    start(req: StartOperationRequest): Promise<StartOperationOutcome>;
+    get(id: string): Promise<RuntimeOperation | null>;
+    list(opts?: RuntimeOperationListOptions): Promise<RuntimeOperation[]>;
+    findActive(): Promise<RuntimeOperation | null>;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

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

@@ -0,0 +1,18 @@
+/**
+ * RuntimeOperation contracts — the single model for any state-changing
+ * lifecycle action against the live runtime (provider switch, plugin
+ * enable/disable, config reload, full restart).
+ *
+ * Design invariants:
+ *
+ *   1. Single queue. One operation runs at a time. New requests while an op
+ *      is running return 409 with the active op's id.
+ *   2. Tiered execution. The use case classifies an intent into a reload
+ *      tier (hot / warm / cold).
+ *   3. Health-gated promotion. A new/re-initialised runtime only "wins"
+ *      after health checks pass.
+ *   4. Append-only phase log. Each phase mutation is a new entry — never
+ *      patched in place (except `updateLastPhase`, for running→succeeded).
+ *   5. Idempotency keys de-dupe retries within the retention window.
+ */
+export {};

package/packages/agent/src/runtime/operations/vault-bridge.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Vault bridge — the only place runtime-ops talks to `@elizaos/vault`.
+ *
+ * Enforces:
+ *   1. The naming convention for provider API key vault entries
+ *      (`providers.<normalizedProvider>.api-key`).
+ *   2. Sensitive flag on every write (so the secret is encrypted at rest).
+ *   3. Caller tagging for the audit log so a reader of
+ *      `<stateDir>/audit/vault.jsonl` can attribute every access to a
+ *      runtime-ops phase.
+ *
+ * The bridge owns NO mutable state. Either pass an explicit
+ * SecretsManager (tests), or call `defaultSecretsManager()` (production)
+ * which constructs a fresh manager backed by the OS-keychain vault.
+ */
+import { type SecretsManager, type Vault } from "@elizaos/vault";
+import type { OperationErrorCode } from "./types.ts";
+export declare class VaultResolveError extends Error {
+    readonly code: OperationErrorCode;
+    constructor(apiKeyRef: string, cause: unknown);
+}
+/** Format a stable vault key into the `vault://<key>` sentinel form. */
+export declare function formatVaultRef(key: string): string;
+/** Type guard: true when `value` is a `vault://<key>` sentinel string. */
+export declare function isVaultRef(value: unknown): value is string;
+/** Extract the underlying vault key from a sentinel; null if malformed. */
+export declare function parseVaultRef(value: string): string | null;
+/** Narrow surface of `Vault` used by the boot resolver — easier to stub. */
+export type VaultLike = Pick<Vault, "get" | "has">;
+/**
+ * Walk an env-shaped record and replace `vault://<key>` sentinels with the
+ * resolved vault values. Non-sentinel strings are passed through unchanged;
+ * non-string values are dropped (process.env only accepts strings).
+ *
+ * Returns `missing` for sentinel keys the vault does not contain — callers
+ * should warn but continue (the legacy hydrate-from-config-env path will run
+ * next and may still backfill from non-sentinel sources).
+ */
+export declare function resolveConfigEnvForProcess(envBag: Record<string, unknown> | undefined, vault: VaultLike): Promise<{
+    resolved: Record<string, string>;
+    missing: string[];
+}>;
+/** Stable vault key for a provider API key. */
+export declare function vaultKeyForProviderApiKey(normalizedProvider: string): string;
+/**
+ * Persist a provider API key in the vault under the canonical key name and
+ * return the vault key (the `apiKeyRef`).
+ *
+ * This is the single write path used by `provider-switch-routes.ts`. The
+ * route MUST persist the secret here BEFORE constructing the
+ * `ProviderSwitchIntent` so the intent never carries plaintext.
+ */
+export declare function persistProviderApiKey(opts: {
+    secrets: SecretsManager;
+    normalizedProvider: string;
+    apiKey: string;
+    caller: string;
+}): Promise<string>;
+/**
+ * Resolve a stored API key for the in-memory `process.env` write path.
+ *
+ * Returns `undefined` only when `apiKeyRef` is absent. If a ref is present,
+ * the operation must fail loudly when the vault cannot resolve it; otherwise a
+ * provider switch can appear successful while running with no key or a stale
+ * key from process.env.
+ *
+ * The caller is recorded on each successful read.
+ */
+export declare function resolveProviderApiKey(opts: {
+    secrets: SecretsManager;
+    apiKeyRef: string | undefined;
+    caller: string;
+}): Promise<string | undefined>;
+/**
+ * Lazy default manager. Production code paths construct a fresh manager
+ * the first time runtime-ops needs the vault; tests inject their own.
+ */
+export declare function defaultSecretsManager(): SecretsManager;
+/** Test hook: drop the cached manager. */
+export declare function _resetDefaultSecretsManagerForTesting(): void;
+//# sourceMappingURL=vault-bridge.d.ts.map

package/packages/agent/src/runtime/operations/vault-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault-bridge.d.ts","sourceRoot":"","sources":["../../../../../../src/runtime/operations/vault-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAiB,KAAK,cAAc,EAAE,KAAK,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAA0B;gBAE/C,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAQ9C;AAKD,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOlD;AAED,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAM1D;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG1D;AAED,4EAA4E;AAC5E,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;AAEnD;;;;;;;;GAQG;AACH,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC3C,KAAK,EAAE,SAAS,GACf,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAqBlE;AAED,+CAA+C;AAC/C,wBAAgB,yBAAyB,CAAC,kBAAkB,EAAE,MAAM,GAAG,MAAM,CAO5E;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,OAAO,EAAE,cAAc,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAOlB;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,OAAO,EAAE,cAAc,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO9B;AAID;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,cAAc,CAGtD;AAED,0CAA0C;AAC1C,wBAAgB,qCAAqC,IAAI,IAAI,CAE5D"}

package/packages/agent/src/runtime/operations/vault-bridge.js

@@ -0,0 +1,133 @@
+/**
+ * Vault bridge — the only place runtime-ops talks to `@elizaos/vault`.
+ *
+ * Enforces:
+ *   1. The naming convention for provider API key vault entries
+ *      (`providers.<normalizedProvider>.api-key`).
+ *   2. Sensitive flag on every write (so the secret is encrypted at rest).
+ *   3. Caller tagging for the audit log so a reader of
+ *      `<stateDir>/audit/vault.jsonl` can attribute every access to a
+ *      runtime-ops phase.
+ *
+ * The bridge owns NO mutable state. Either pass an explicit
+ * SecretsManager (tests), or call `defaultSecretsManager()` (production)
+ * which constructs a fresh manager backed by the OS-keychain vault.
+ */
+import { createManager } from "@elizaos/vault";
+export class VaultResolveError extends Error {
+    code = "vault-resolve-failed";
+    constructor(apiKeyRef, cause) {
+        super(`[runtime-ops:vault] failed to resolve ${apiKeyRef}: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.name = "VaultResolveError";
+    }
+}
+/** Sentinel prefix marking a config value that resolves through the vault. */
+const VAULT_REF_PREFIX = "vault://";
+/** Format a stable vault key into the `vault://<key>` sentinel form. */
+export function formatVaultRef(key) {
+    if (typeof key !== "string" || key.length === 0) {
+        throw new TypeError(`[runtime-ops:vault] formatVaultRef requires a non-empty key`);
+    }
+    return `${VAULT_REF_PREFIX}${key}`;
+}
+/** Type guard: true when `value` is a `vault://<key>` sentinel string. */
+export function isVaultRef(value) {
+    return (typeof value === "string" &&
+        value.startsWith(VAULT_REF_PREFIX) &&
+        value.length > VAULT_REF_PREFIX.length);
+}
+/** Extract the underlying vault key from a sentinel; null if malformed. */
+export function parseVaultRef(value) {
+    if (!isVaultRef(value))
+        return null;
+    return value.slice(VAULT_REF_PREFIX.length);
+}
+/**
+ * Walk an env-shaped record and replace `vault://<key>` sentinels with the
+ * resolved vault values. Non-sentinel strings are passed through unchanged;
+ * non-string values are dropped (process.env only accepts strings).
+ *
+ * Returns `missing` for sentinel keys the vault does not contain — callers
+ * should warn but continue (the legacy hydrate-from-config-env path will run
+ * next and may still backfill from non-sentinel sources).
+ */
+export async function resolveConfigEnvForProcess(envBag, vault) {
+    const resolved = {};
+    const missing = [];
+    if (!envBag)
+        return { resolved, missing };
+    for (const [envKey, value] of Object.entries(envBag)) {
+        if (typeof value !== "string")
+            continue;
+        if (!isVaultRef(value)) {
+            resolved[envKey] = value;
+            continue;
+        }
+        const vaultKey = parseVaultRef(value);
+        if (!vaultKey)
+            continue;
+        if (!(await vault.has(vaultKey))) {
+            missing.push(vaultKey);
+            continue;
+        }
+        resolved[envKey] = await vault.get(vaultKey);
+    }
+    return { resolved, missing };
+}
+/** Stable vault key for a provider API key. */
+export function vaultKeyForProviderApiKey(normalizedProvider) {
+    if (!normalizedProvider || normalizedProvider.includes(".")) {
+        throw new TypeError(`[runtime-ops:vault] invalid provider id: ${JSON.stringify(normalizedProvider)}`);
+    }
+    return `providers.${normalizedProvider}.api-key`;
+}
+/**
+ * Persist a provider API key in the vault under the canonical key name and
+ * return the vault key (the `apiKeyRef`).
+ *
+ * This is the single write path used by `provider-switch-routes.ts`. The
+ * route MUST persist the secret here BEFORE constructing the
+ * `ProviderSwitchIntent` so the intent never carries plaintext.
+ */
+export async function persistProviderApiKey(opts) {
+    const ref = vaultKeyForProviderApiKey(opts.normalizedProvider);
+    await opts.secrets.vault.set(ref, opts.apiKey, {
+        sensitive: true,
+        caller: opts.caller,
+    });
+    return ref;
+}
+/**
+ * Resolve a stored API key for the in-memory `process.env` write path.
+ *
+ * Returns `undefined` only when `apiKeyRef` is absent. If a ref is present,
+ * the operation must fail loudly when the vault cannot resolve it; otherwise a
+ * provider switch can appear successful while running with no key or a stale
+ * key from process.env.
+ *
+ * The caller is recorded on each successful read.
+ */
+export async function resolveProviderApiKey(opts) {
+    if (!opts.apiKeyRef)
+        return undefined;
+    try {
+        return await opts.secrets.vault.reveal(opts.apiKeyRef, opts.caller);
+    }
+    catch (err) {
+        throw new VaultResolveError(opts.apiKeyRef, err);
+    }
+}
+let cached = null;
+/**
+ * Lazy default manager. Production code paths construct a fresh manager
+ * the first time runtime-ops needs the vault; tests inject their own.
+ */
+export function defaultSecretsManager() {
+    if (!cached)
+        cached = createManager();
+    return cached;
+}
+/** Test hook: drop the cached manager. */
+export function _resetDefaultSecretsManagerForTesting() {
+    cached = null;
+}

package/packages/agent/src/runtime/owner-entity.d.ts

@@ -0,0 +1,4 @@
+import { type IAgentRuntime } from "@elizaos/core";
+export declare function resolveFallbackOwnerEntityId(runtime: Pick<IAgentRuntime, "agentId" | "character">): string;
+export declare function resolveOwnerEntityId(runtime: IAgentRuntime): Promise<string | null>;
+//# sourceMappingURL=owner-entity.d.ts.map

package/packages/agent/src/runtime/owner-entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner-entity.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/owner-entity.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAGnB,MAAM,eAAe,CAAC;AAMvB,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,SAAS,GAAG,WAAW,CAAC,GACpD,MAAM,CAGR;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAwBxB"}

package/packages/agent/src/runtime/owner-entity.js

@@ -0,0 +1,30 @@
+import { resolveCanonicalOwnerId, stringToUuid, } from "@elizaos/core";
+export function resolveFallbackOwnerEntityId(runtime) {
+    const agentName = runtime.character?.name?.trim() || runtime.agentId;
+    return stringToUuid(`${agentName}-admin-entity`);
+}
+export async function resolveOwnerEntityId(runtime) {
+    const configuredOwnerId = resolveCanonicalOwnerId(runtime);
+    if (configuredOwnerId) {
+        return configuredOwnerId;
+    }
+    try {
+        const roomIds = await runtime.getRoomsForParticipant(runtime.agentId);
+        for (const roomId of roomIds.slice(0, 10)) {
+            try {
+                const room = await runtime.getRoom(roomId);
+                if (!room?.worldId) {
+                    continue;
+                }
+                const world = await runtime.getWorld(room.worldId);
+                const metadata = (world?.metadata ?? {});
+                if (metadata.ownership?.ownerId) {
+                    return metadata.ownership.ownerId;
+                }
+            }
+            catch { }
+        }
+    }
+    catch { }
+    return resolveFallbackOwnerEntityId(runtime);
+}

package/packages/agent/src/runtime/pglite-error-compat.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pglite error utilities.
+ *
+ * These are defined locally because the published @elizaos/plugin-sql npm
+ * package (beta dist-tag) does not yet export them. Once the plugin-sql
+ * submodule ships a release that includes pglite/errors.ts, we can remove
+ * this file and import directly from "@elizaos/plugin-sql".
+ */
+export declare const PGLITE_ERROR_CODES: {
+    readonly ACTIVE_LOCK: "ELIZA_PGLITE_DATA_DIR_IN_USE";
+    readonly CORRUPT_DATA: "ELIZA_PGLITE_CORRUPT_DATA";
+    readonly MANUAL_RESET_REQUIRED: "ELIZA_PGLITE_MANUAL_RESET_REQUIRED";
+};
+export type PgliteErrorCode = (typeof PGLITE_ERROR_CODES)[keyof typeof PGLITE_ERROR_CODES];
+export declare class PgliteInitError extends Error {
+    readonly code: PgliteErrorCode;
+    readonly dataDir?: string;
+    constructor(code: PgliteErrorCode, message: string, options?: {
+        cause?: unknown;
+        dataDir?: string;
+    });
+}
+export declare function createPgliteInitError(code: PgliteErrorCode, message: string, options?: {
+    cause?: unknown;
+    dataDir?: string;
+}): PgliteInitError;
+export declare function getPgliteErrorCode(err: unknown): PgliteErrorCode | null;
+//# sourceMappingURL=pglite-error-compat.d.ts.map

package/packages/agent/src/runtime/pglite-error-compat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pglite-error-compat.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/pglite-error-compat.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,eAAO,MAAM,kBAAkB;;;;CAIrB,CAAC;AAEX,MAAM,MAAM,eAAe,GACzB,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC;AAE/D,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAgB,IAAI,EAAE,eAAe,CAAC;IACtC,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC;gBAG/B,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE;CAOlD;AAED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9C,eAAe,CAEjB;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAoCvE"}

package/packages/agent/src/runtime/pglite-error-compat.js

@@ -0,0 +1,54 @@
+/**
+ * Pglite error utilities.
+ *
+ * These are defined locally because the published @elizaos/plugin-sql npm
+ * package (beta dist-tag) does not yet export them. Once the plugin-sql
+ * submodule ships a release that includes pglite/errors.ts, we can remove
+ * this file and import directly from "@elizaos/plugin-sql".
+ */
+export const PGLITE_ERROR_CODES = {
+    ACTIVE_LOCK: "ELIZA_PGLITE_DATA_DIR_IN_USE",
+    CORRUPT_DATA: "ELIZA_PGLITE_CORRUPT_DATA",
+    MANUAL_RESET_REQUIRED: "ELIZA_PGLITE_MANUAL_RESET_REQUIRED",
+};
+export class PgliteInitError extends Error {
+    code;
+    dataDir;
+    constructor(code, message, options) {
+        super(message, { cause: options?.cause });
+        this.name = "PgliteInitError";
+        this.code = code;
+        this.dataDir = options?.dataDir;
+    }
+}
+export function createPgliteInitError(code, message, options) {
+    return new PgliteInitError(code, message, options);
+}
+export function getPgliteErrorCode(err) {
+    const seen = new Set();
+    let current = err;
+    while (current && !seen.has(current)) {
+        seen.add(current);
+        if (typeof current === "object" &&
+            current !== null &&
+            "code" in current &&
+            typeof current.code === "string") {
+            const code = current.code;
+            if (code === PGLITE_ERROR_CODES.ACTIVE_LOCK ||
+                code === PGLITE_ERROR_CODES.CORRUPT_DATA ||
+                code === PGLITE_ERROR_CODES.MANUAL_RESET_REQUIRED) {
+                return code;
+            }
+        }
+        if (current instanceof Error) {
+            current = current.cause;
+            continue;
+        }
+        if (typeof current === "object" && current !== null && "cause" in current) {
+            current = current.cause;
+            continue;
+        }
+        break;
+    }
+    return null;
+}

package/packages/agent/src/runtime/plugin-collector.d.ts

@@ -0,0 +1,22 @@
+export declare function resolvePluginPackageAlias(packageName: string): string;
+/** Maps Eliza channel names to plugin package names. */
+export declare const CHANNEL_PLUGIN_MAP: Readonly<Record<string, string>>;
+/** Maps environment variable names to model-provider plugin packages. */
+export declare const PROVIDER_PLUGIN_MAP: Readonly<Record<string, string>>;
+/**
+ * Optional feature plugins keyed by feature name.
+ *
+ * Mappings here support short IDs in allow-lists and feature toggles.
+ * Keep this map in sync with optional plugin registration and tests.
+ */
+export declare const OPTIONAL_PLUGIN_MAP: Readonly<Record<string, string>>;
+/**
+ * First-winning provenance for each package name in the load set — e.g.
+ * `plugins.allow[...]`, `env: SOLANA_PRIVATE_KEY`, `CORE_PLUGINS`.
+ * {@link collectPluginNames} fills this when the optional `reasons` map is passed.
+ *
+ * **Why:** Optional plugins often fail with "Cannot find module"; without the
+ * source, operators assume the framework is broken instead of fixing config/env.
+ */
+export type PluginLoadReasons = Map<string, string>;
+//# sourceMappingURL=plugin-collector.d.ts.map

package/packages/agent/src/runtime/plugin-collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-collector.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/plugin-collector.ts"],"names":[],"mappings":"AAiFA,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAErE;AAuBD,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAwB/D,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBhE,CAAC;AAeF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAqDhE,CAAC;AAMF;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC"}