@elizaos/ui 2.0.0-alpha.526 → 2.0.0-alpha.528

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

@@ -4,26 +4,48 @@
  * Storage layout:
  *   <stateDir>/runtime-operations/<id>.json   one JSON file per operation
  *
- * Atomic writes: write to <id>.json.tmp.<pid> then rename — same pattern
- * the Eliza config uses (config.ts:saveElizaConfig).
- *
  * In-memory caches are populated lazily at first access from disk and kept
  * in sync on every mutation. They make `findActive` and
  * `findByIdempotencyKey` O(1) on the hot path.
  *
- * Hydration also reaps abandoned operations: anything still `pending` or
- * `running` whose `startedAt` is older than 24h is force-marked `failed`
- * with code `"abandoned"` (the process must have died mid-flight).
+ * Hydration:
+ *   1. Reap abandoned ops — `pending`/`running` whose `startedAt` is older
+ *      than `ABANDONED_AFTER_MS` are force-marked `failed` with code
+ *      `"abandoned"` (the process died mid-flight).
+ *   2. Prune terminal ops — `succeeded`/`failed`/`rolled-back` records older
+ *      than `RETENTION_MS` or beyond the `MAX_RECORDS` cap are deleted from
+ *      disk and dropped from memory. Active ops are never pruned.
+ *
+ * Pruning also runs opportunistically after each `create` so a long-running
+ * process doesn't accumulate state between hydrations.
  */
 import type { OperationPhase, RuntimeOperation, RuntimeOperationListOptions, RuntimeOperationRepository } from "./types.js";
+export interface FilesystemRuntimeOperationRepositoryOptions {
+    /** Override the retention window for terminal ops. */
+    retentionMs?: number;
+    /** Override the cap on the number of terminal ops kept. */
+    maxRecords?: number;
+}
 export declare class FilesystemRuntimeOperationRepository implements RuntimeOperationRepository {
     private readonly dir;
     private readonly byId;
     private readonly byIdempotencyKey;
     private activeId;
-    private hydrated;
-    constructor(stateDir?: string);
+    private hydration;
+    private readonly retentionMs;
+    private readonly maxRecords;
+    constructor(stateDir?: string, opts?: FilesystemRuntimeOperationRepositoryOptions);
     private hydrate;
+    private runHydrate;
+    /**
+     * Drop terminal ops that exceed the retention window or fall outside the
+     * most-recent-N cap. Active (`pending`/`running`) ops are never touched —
+     * the abandoned-reaper in {@link runHydrate} is the only path that can
+     * transition them to terminal.
+     *
+     * Returns the number of ops removed.
+     */
+    pruneTerminal(now?: number): Promise<number>;
     private pathFor;
     private persist;
     private syncActiveSlot;

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

@@ -1 +1 @@
-{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../../../../../../agent/src/runtime/operations/repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,2BAA2B,EAC3B,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AAoCpB,qBAAa,oCACX,YAAW,0BAA0B;IAErC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4C;IACjE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAkC;IACnE,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,QAAQ,CAAS;gBAEb,QAAQ,GAAE,MAA0B;IAIhD,OAAO,CAAC,OAAO;IA8Cf,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,cAAc;IAWhB,MAAM,CAAC,EAAE,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAa3C,MAAM,CACV,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,gBAAgB,EAAE,IAAI,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC,CAAC,GAC1E,OAAO,CAAC,IAAI,CAAC;IAYV,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAc7D,eAAe,CACnB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,OAAO,CAAC,cAAc,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC;IAwBV,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAKjD,IAAI,CAAC,IAAI,CAAC,EAAE,2BAA2B,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAerE,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAYnE,UAAU,IAAI,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;CAcrD;AAID;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,oCAAoC,CAK3E"}
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../../../../../../agent/src/runtime/operations/repository.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAQH,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,2BAA2B,EAC3B,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AAepB,MAAM,WAAW,2CAA2C;IAC1D,sDAAsD;IACtD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA4CD,qBAAa,oCACX,YAAW,0BAA0B;IAErC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4C;IACjE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAkC;IACnE,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,SAAS,CAA8B;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAGlC,QAAQ,GAAE,MAA0B,EACpC,IAAI,GAAE,2CAAgD;IAWxD,OAAO,CAAC,OAAO;YAMD,UAAU;IAiExB;;;;;;;OAOG;IACG,aAAa,CAAC,GAAG,GAAE,MAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;IAkC9D,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,cAAc;IAWhB,MAAM,CAAC,EAAE,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB3C,MAAM,CACV,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,gBAAgB,EAAE,IAAI,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC,CAAC,GAC1E,OAAO,CAAC,IAAI,CAAC;IAYV,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAc7D,eAAe,CACnB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,OAAO,CAAC,cAAc,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC;IAmBV,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAKjD,IAAI,CAAC,IAAI,CAAC,EAAE,2BAA2B,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAerE,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAYnE,UAAU,IAAI,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;CAcrD;AAID;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,oCAAoC,CAK3E"}

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

@@ -4,73 +4,119 @@
  * Storage layout:
  *   <stateDir>/runtime-operations/<id>.json   one JSON file per operation
  *
- * Atomic writes: write to <id>.json.tmp.<pid> then rename — same pattern
- * the Eliza config uses (config.ts:saveElizaConfig).
- *
  * In-memory caches are populated lazily at first access from disk and kept
  * in sync on every mutation. They make `findActive` and
  * `findByIdempotencyKey` O(1) on the hot path.
  *
- * Hydration also reaps abandoned operations: anything still `pending` or
- * `running` whose `startedAt` is older than 24h is force-marked `failed`
- * with code `"abandoned"` (the process must have died mid-flight).
+ * Hydration:
+ *   1. Reap abandoned ops — `pending`/`running` whose `startedAt` is older
+ *      than `ABANDONED_AFTER_MS` are force-marked `failed` with code
+ *      `"abandoned"` (the process died mid-flight).
+ *   2. Prune terminal ops — `succeeded`/`failed`/`rolled-back` records older
+ *      than `RETENTION_MS` or beyond the `MAX_RECORDS` cap are deleted from
+ *      disk and dropped from memory. Active ops are never pruned.
+ *
+ * Pruning also runs opportunistically after each `create` so a long-running
+ * process doesn't accumulate state between hydrations.
  */
-import fs from "node:fs";
+import fs from "node:fs/promises";
 import path from "node:path";
 import { logger } from "@elizaos/core";
+import { formatError } from "@elizaos/shared";
 import { resolveStateDir } from "../../config/paths.js";
+import { readJsonFile, writeJsonAtomic } from "../../utils/atomic-json.js";
 const ABANDONED_AFTER_MS = 24 * 60 * 60 * 1000;
 const IDEMPOTENCY_RETENTION_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_RETENTION_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+const DEFAULT_MAX_RECORDS = 200;
+function readEnvNumber(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+function isTerminal(op) {
+    return op.status !== "pending" && op.status !== "running";
+}
+/**
+ * Strip the legacy plaintext `apiKey` field that older runtime-ops records
+ * carried on `ProviderSwitchIntent` before the vault migration. Returns the
+ * sanitized op plus a boolean signalling that the on-disk file needs
+ * rewriting. The vault key is preserved (or re-derivable) by the route at
+ * the next switch — we never re-emit the plaintext.
+ */
+function stripLegacyApiKey(op) {
+    if (op.intent.kind !== "provider-switch")
+        return { op, changed: false };
+    const intent = op.intent;
+    if (!("apiKey" in intent))
+        return { op, changed: false };
+    const { apiKey: _legacy, ...sanitizedIntent } = intent;
+    void _legacy;
+    return {
+        op: { ...op, intent: sanitizedIntent },
+        changed: true,
+    };
+}
 function operationsDirFor(stateDir) {
     return path.join(stateDir, "runtime-operations");
 }
-function ensureDir(dir) {
-    if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-    }
-}
-function readJsonFile(filePath) {
-    const raw = fs.readFileSync(filePath, "utf-8");
-    if (!raw.trim()) {
-        return null;
-    }
-    const parsed = JSON.parse(raw);
-    if (!parsed.id || !parsed.kind || !Array.isArray(parsed.phases)) {
+async function readOperationFile(filePath) {
+    const parsed = await readJsonFile(filePath);
+    if (!parsed?.id || !parsed.kind || !Array.isArray(parsed.phases)) {
         return null;
     }
     return parsed;
 }
-function writeJsonAtomic(filePath, op) {
-    const dir = path.dirname(filePath);
-    ensureDir(dir);
-    const tmpPath = `${filePath}.tmp.${process.pid}`;
-    const content = `${JSON.stringify(op, null, 2)}\n`;
-    fs.writeFileSync(tmpPath, content, { encoding: "utf-8", mode: 0o600 });
-    fs.renameSync(tmpPath, filePath);
-}
 export class FilesystemRuntimeOperationRepository {
     dir;
     byId = new Map();
     byIdempotencyKey = new Map();
     activeId = null;
-    hydrated = false;
-    constructor(stateDir = resolveStateDir()) {
+    hydration = null;
+    retentionMs;
+    maxRecords;
+    constructor(stateDir = resolveStateDir(), opts = {}) {
         this.dir = operationsDirFor(stateDir);
+        this.retentionMs =
+            opts.retentionMs ??
+                readEnvNumber("MILADY_RUNTIME_OPS_RETENTION_MS", DEFAULT_RETENTION_MS);
+        this.maxRecords =
+            opts.maxRecords ??
+                readEnvNumber("MILADY_RUNTIME_OPS_MAX_RECORDS", DEFAULT_MAX_RECORDS);
     }
     hydrate() {
-        if (this.hydrated)
-            return;
-        this.hydrated = true;
-        ensureDir(this.dir);
-        const entries = fs.readdirSync(this.dir);
+        if (this.hydration)
+            return this.hydration;
+        this.hydration = this.runHydrate();
+        return this.hydration;
+    }
+    async runHydrate() {
+        // mkdir is idempotent with recursive: true — no existence check needed.
+        await fs.mkdir(this.dir, { recursive: true, mode: 0o700 });
+        const entries = await fs.readdir(this.dir);
         const now = Date.now();
         for (const entry of entries) {
             if (!entry.endsWith(".json"))
                 continue;
             const fullPath = path.join(this.dir, entry);
-            const op = readJsonFile(fullPath);
-            if (!op)
+            const raw = await readOperationFile(fullPath);
+            if (!raw)
                 continue;
+            // Migration: strip legacy plaintext `apiKey` from
+            // ProviderSwitchIntent records written before the vault integration.
+            // Re-persist the sanitized record so the file on disk loses the
+            // secret too — pruning + idempotency keep working untouched.
+            const stripped = stripLegacyApiKey(raw);
+            const op = stripped.op;
+            if (stripped.changed) {
+                await writeJsonAtomic(fullPath, op, {
+                    trailingNewline: true,
+                    skipMkdir: true,
+                });
+                logger.info(`[runtime-ops] Migrated legacy plaintext apiKey out of ${op.id}`);
+            }
             // Reap abandoned operations: a process died with this op still "live".
             const isLive = op.status === "pending" || op.status === "running";
             const isStale = now - op.startedAt > ABANDONED_AFTER_MS;
@@ -84,7 +130,10 @@ export class FilesystemRuntimeOperationRepository {
                         code: "abandoned",
                     },
                 };
-                writeJsonAtomic(fullPath, reaped);
+                await writeJsonAtomic(fullPath, reaped, {
+                    trailingNewline: true,
+                    skipMkdir: true,
+                });
                 this.byId.set(reaped.id, reaped);
                 if (reaped.idempotencyKey) {
                     this.byIdempotencyKey.set(reaped.idempotencyKey, reaped.id);
@@ -100,12 +149,49 @@ export class FilesystemRuntimeOperationRepository {
                 this.activeId = op.id;
             }
         }
+        await this.pruneTerminal(now);
+    }
+    /**
+     * Drop terminal ops that exceed the retention window or fall outside the
+     * most-recent-N cap. Active (`pending`/`running`) ops are never touched —
+     * the abandoned-reaper in {@link runHydrate} is the only path that can
+     * transition them to terminal.
+     *
+     * Returns the number of ops removed.
+     */
+    async pruneTerminal(now = Date.now()) {
+        const terminal = Array.from(this.byId.values())
+            .filter(isTerminal)
+            .sort((a, b) => (b.finishedAt ?? b.startedAt) - (a.finishedAt ?? a.startedAt));
+        const toDrop = [];
+        for (let i = 0; i < terminal.length; i++) {
+            const op = terminal[i];
+            const tooOld = now - (op.finishedAt ?? op.startedAt) > this.retentionMs;
+            const beyondCap = i >= this.maxRecords;
+            if (tooOld || beyondCap)
+                toDrop.push(op);
+        }
+        if (toDrop.length === 0)
+            return 0;
+        await Promise.all(toDrop.map((op) => fs.rm(this.pathFor(op.id), { force: true }).catch((err) => {
+            logger.warn(`[runtime-ops] Failed to unlink ${op.id}: ${formatError(err)}`);
+        })));
+        for (const op of toDrop) {
+            this.byId.delete(op.id);
+            if (op.idempotencyKey)
+                this.byIdempotencyKey.delete(op.idempotencyKey);
+        }
+        logger.debug(`[runtime-ops] Pruned ${toDrop.length} terminal op(s)`);
+        return toDrop.length;
     }
     pathFor(id) {
         return path.join(this.dir, `${id}.json`);
     }
     persist(op) {
-        writeJsonAtomic(this.pathFor(op.id), op);
+        return writeJsonAtomic(this.pathFor(op.id), op, {
+            trailingNewline: true,
+            skipMkdir: true,
+        });
     }
     syncActiveSlot(op) {
         const isLive = op.status === "pending" || op.status === "running";
@@ -118,30 +204,33 @@ export class FilesystemRuntimeOperationRepository {
         }
     }
     async create(op) {
-        this.hydrate();
+        await this.hydrate();
         if (this.byId.has(op.id)) {
             throw new Error(`[runtime-ops] Operation already exists: ${op.id}`);
         }
-        this.persist(op);
+        await this.persist(op);
         this.byId.set(op.id, op);
         if (op.idempotencyKey) {
             this.byIdempotencyKey.set(op.idempotencyKey, op.id);
         }
         this.syncActiveSlot(op);
+        void this.pruneTerminal().catch((err) => {
+            logger.warn(`[runtime-ops] post-create prune failed: ${formatError(err)}`);
+        });
     }
     async update(id, patch) {
-        this.hydrate();
+        await this.hydrate();
         const current = this.byId.get(id);
         if (!current) {
             throw new Error(`[runtime-ops] Operation not found: ${id}`);
         }
         const next = { ...current, ...patch };
-        this.persist(next);
+        await this.persist(next);
         this.byId.set(id, next);
         this.syncActiveSlot(next);
     }
     async appendPhase(id, phase) {
-        this.hydrate();
+        await this.hydrate();
         const current = this.byId.get(id);
         if (!current) {
             throw new Error(`[runtime-ops] Operation not found: ${id}`);
@@ -150,34 +239,31 @@ export class FilesystemRuntimeOperationRepository {
             ...current,
             phases: [...current.phases, phase],
         };
-        this.persist(next);
+        await this.persist(next);
         this.byId.set(id, next);
     }
     async updateLastPhase(id, patch) {
-        this.hydrate();
+        await this.hydrate();
         const current = this.byId.get(id);
         if (!current) {
             throw new Error(`[runtime-ops] Operation not found: ${id}`);
         }
-        if (current.phases.length === 0) {
-            throw new Error(`[runtime-ops] Cannot update last phase — no phases on op ${id}`);
-        }
         const last = current.phases[current.phases.length - 1];
         if (!last) {
-            throw new Error(`[runtime-ops] Cannot update last phase — phase array empty on ${id}`);
+            throw new Error(`[runtime-ops] Cannot update last phase — no phases on op ${id}`);
         }
         const merged = { ...last, ...patch };
         const phases = [...current.phases.slice(0, -1), merged];
         const next = { ...current, phases };
-        this.persist(next);
+        await this.persist(next);
         this.byId.set(id, next);
     }
     async get(id) {
-        this.hydrate();
+        await this.hydrate();
         return this.byId.get(id) ?? null;
     }
     async list(opts) {
-        this.hydrate();
+        await this.hydrate();
         let ops = Array.from(this.byId.values());
         if (opts?.status) {
             ops = ops.filter((o) => o.status === opts.status);
@@ -192,7 +278,7 @@ export class FilesystemRuntimeOperationRepository {
         return ops;
     }
     async findByIdempotencyKey(key) {
-        this.hydrate();
+        await this.hydrate();
         const id = this.byIdempotencyKey.get(key);
         if (!id)
             return null;
@@ -205,7 +291,7 @@ export class FilesystemRuntimeOperationRepository {
         return op;
     }
     async findActive() {
-        this.hydrate();
+        await this.hydrate();
         if (!this.activeId)
             return null;
         const op = this.byId.get(this.activeId);

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

@@ -3,35 +3,30 @@
  * lifecycle action against the live runtime (provider switch, plugin
  * enable/disable, config reload, full restart).
  *
- * Design invariants (see docs/architecture/runtime-operations.md once written):
+ * Design invariants:
  *
- *   1. Single queue. One operation runs at a time, full-stop. New requests
- *      while an op is running return 409 with the active op's id.
+ *   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). Most provider switches collapse to hot
- *      or warm; only plugin allowlist changes go cold.
- *   3. Health-gated promotion. A new runtime (cold) or a re-initialised
- *      plugin (warm) only "wins" after health checks pass; failure rolls
- *      back to the previous configuration.
+ *      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. This is the substrate for an event-log WS later.
- *   5. Idempotency keys de-dupe retries. Same key in within the retention
- *      window returns the existing operation record.
- *
- * This module exports types only. Implementations live in sibling files:
- *   - manager.ts     — RuntimeOperationManager (the use case)
- *   - repository.ts  — RuntimeOperationRepository (filesystem-backed)
- *   - classifier.ts  — classifyOperation(intent) → ReloadTier
- *   - health.ts      — HealthCheck registry + runner
- *   - reload-hot.ts  — env-var swap + plugin notify
- *   - reload-warm.ts — per-plugin reinit (Phase 2)
- *   - reload-cold.ts — full runtime swap (delegates to existing handleRestart)
+ *      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;
-    apiKey?: 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 {
@@ -71,14 +66,15 @@ export type OperationKind = OperationIntent["kind"];
 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?: string;
+    code?: OperationErrorCode;
     cause?: string;
 }
 export interface OperationPhase {
-    /** Stable phase name — e.g. "validate", "persist-config", "health-check". */
-    name: string;
+    name: PhaseName;
     status: PhaseStatus;
     startedAt?: number;
     finishedAt?: number;
@@ -175,6 +171,12 @@ export interface ReloadStrategy {
 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. */

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

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

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

@@ -3,28 +3,16 @@
  * lifecycle action against the live runtime (provider switch, plugin
  * enable/disable, config reload, full restart).
  *
- * Design invariants (see docs/architecture/runtime-operations.md once written):
+ * Design invariants:
  *
- *   1. Single queue. One operation runs at a time, full-stop. New requests
- *      while an op is running return 409 with the active op's id.
+ *   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). Most provider switches collapse to hot
- *      or warm; only plugin allowlist changes go cold.
- *   3. Health-gated promotion. A new runtime (cold) or a re-initialised
- *      plugin (warm) only "wins" after health checks pass; failure rolls
- *      back to the previous configuration.
+ *      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. This is the substrate for an event-log WS later.
- *   5. Idempotency keys de-dupe retries. Same key in within the retention
- *      window returns the existing operation record.
- *
- * This module exports types only. Implementations live in sibling files:
- *   - manager.ts     — RuntimeOperationManager (the use case)
- *   - repository.ts  — RuntimeOperationRepository (filesystem-backed)
- *   - classifier.ts  — classifyOperation(intent) → ReloadTier
- *   - health.ts      — HealthCheck registry + runner
- *   - reload-hot.ts  — env-var swap + plugin notify
- *   - reload-warm.ts — per-plugin reinit (Phase 2)
- *   - reload-cold.ts — full runtime swap (delegates to existing handleRestart)
+ *      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,60 @@
+/**
+ * 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 } from "@elizaos/vault";
+import type { OperationErrorCode } from "./types.js";
+export declare class VaultResolveError extends Error {
+    readonly code: OperationErrorCode;
+    constructor(apiKeyRef: string, cause: unknown);
+}
+/** 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":["../../../../../../../agent/src/runtime/operations/vault-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACpE,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;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"}