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

package/packages/agent/src/runtime/operations/reload-hot.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Hot reload strategy.
+ *
+ * The fast path. Used when the change can be applied by mutating env vars and
+ * (best-effort) notifying plugins via their `applyConfig` lifecycle hook —
+ * no plugin reload, no service teardown, no full runtime swap.
+ *
+ * Bounded ~100ms. Idempotent: calling twice with the same intent is safe;
+ * env vars settle to the same values, notifications are best-effort.
+ *
+ * The strategy delegates env mutation to a caller-supplied `applyProviderEnv`
+ * which wraps the existing onboarding env-pump (`applyOnboardingConnectionConfig`
+ * + `createProviderSwitchConnection`). The plugin notify step iterates the
+ * runtime's plugins and invokes `plugin.applyConfig` when present; that hook
+ * is the one defined on the elizaOS Plugin contract for config-only updates.
+ */
+import type { AgentRuntime } from "@elizaos/core";
+import type { SecretsManager } from "@elizaos/vault";
+import type { ProviderSwitchIntent, ReloadStrategy } from "./types.ts";
+export interface HotStrategyDeps {
+    /**
+     * Apply env-var / config mutations for a provider switch. Defaults wrap the
+     * existing onboarding env-pump. The wrapper must be idempotent: same intent
+     * in → same env state out.
+     */
+    applyProviderEnv: (intent: ProviderSwitchIntent) => Promise<void>;
+    /**
+     * Best-effort plugin notify. Called after env mutation. Implementations
+     * iterate `runtime.plugins` and call each plugin's `applyConfig` hook (the
+     * elizaOS Plugin contract's config-only update path). Failures here are
+     * logged and surfaced as a warning phase, but do NOT fail the operation —
+     * env was already applied and plugins will pick up the new values on
+     * their next request.
+     */
+    notifyConfigChanged: (runtime: AgentRuntime, change: {
+        kind: string;
+        detail?: Record<string, unknown>;
+    }) => Promise<void>;
+}
+export declare function createHotStrategy(opts?: Partial<HotStrategyDeps> & {
+    secrets?: SecretsManager;
+}): ReloadStrategy;
+//# sourceMappingURL=reload-hot.d.ts.map

package/packages/agent/src/runtime/operations/reload-hot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reload-hot.d.ts","sourceRoot":"","sources":["../../../../../../src/runtime/operations/reload-hot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAU,MAAM,eAAe,CAAC;AAG1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAGV,oBAAoB,EAEpB,cAAc,EACf,MAAM,YAAY,CAAC;AAMpB,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,gBAAgB,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;;;;;OAOG;IACH,mBAAmB,EAAE,CACnB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,KACvD,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB;AAiJD,wBAAgB,iBAAiB,CAC/B,IAAI,GAAE,OAAO,CAAC,eAAe,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,cAAc,CAAA;CAAO,GACjE,cAAc,CAgEhB"}

package/packages/agent/src/runtime/operations/reload-hot.js

@@ -0,0 +1,181 @@
+/**
+ * Hot reload strategy.
+ *
+ * The fast path. Used when the change can be applied by mutating env vars and
+ * (best-effort) notifying plugins via their `applyConfig` lifecycle hook —
+ * no plugin reload, no service teardown, no full runtime swap.
+ *
+ * Bounded ~100ms. Idempotent: calling twice with the same intent is safe;
+ * env vars settle to the same values, notifications are best-effort.
+ *
+ * The strategy delegates env mutation to a caller-supplied `applyProviderEnv`
+ * which wraps the existing onboarding env-pump (`applyOnboardingConnectionConfig`
+ * + `createProviderSwitchConnection`). The plugin notify step iterates the
+ * runtime's plugins and invokes `plugin.applyConfig` when present; that hook
+ * is the one defined on the elizaOS Plugin contract for config-only updates.
+ */
+import { logger } from "@elizaos/core";
+import { formatErrorWithStack } from "@elizaos/shared";
+import { defaultSecretsManager, resolveProviderApiKey, } from "./vault-bridge.js";
+function buildPhase(name, status, startedAt, finishedAt, extra = {}) {
+    return {
+        name,
+        status,
+        startedAt,
+        finishedAt,
+        ...(extra.error ? { error: extra.error } : {}),
+        ...(extra.detail ? { detail: extra.detail } : {}),
+    };
+}
+function describeIntent(intent) {
+    switch (intent.kind) {
+        case "provider-switch":
+            return {
+                kind: "provider-switch",
+                detail: {
+                    provider: intent.provider,
+                    ...(intent.primaryModel ? { primaryModel: intent.primaryModel } : {}),
+                    ...(intent.apiKeyRef ? { apiKeyChanged: true } : {}),
+                },
+            };
+        case "config-reload":
+            return {
+                kind: "config-reload",
+                detail: {
+                    ...(intent.changedPaths
+                        ? { changedPaths: [...intent.changedPaths] }
+                        : {}),
+                },
+            };
+        case "plugin-enable":
+        case "plugin-disable":
+            return {
+                kind: intent.kind,
+                detail: { pluginId: intent.pluginId },
+            };
+        case "restart":
+            return { kind: "restart", detail: { reason: intent.reason } };
+    }
+}
+/**
+ * Default env-pump wrapper. Lazy-imports the onboarding env-pump to keep the
+ * dependency graph clean (the operations module sits below the api module
+ * in the layering, but the env-pump genuinely owns the canonical mutation).
+ *
+ * The intent carries `apiKeyRef` (a vault key), not the secret itself. The
+ * vault is consulted here on every hot reload and only the resolved
+ * plaintext is passed downstream to `createProviderSwitchConnection`.
+ */
+function makeDefaultApplyProviderEnv(secrets) {
+    return async (intent) => {
+        const { applyOnboardingConnectionConfig, createProviderSwitchConnection } = await import("../../api/provider-switch-config.js");
+        const { loadElizaConfig, saveElizaConfig } = await import("../../config/config.js");
+        const apiKey = await resolveProviderApiKey({
+            secrets,
+            apiKeyRef: intent.apiKeyRef,
+            caller: "runtime-ops:reload-hot",
+        });
+        const connection = createProviderSwitchConnection({
+            provider: intent.provider,
+            ...(apiKey ? { apiKey } : {}),
+            ...(intent.primaryModel ? { primaryModel: intent.primaryModel } : {}),
+        });
+        if (!connection) {
+            throw new Error(`[runtime-ops] hot reload: invalid provider "${intent.provider}"`);
+        }
+        const config = loadElizaConfig();
+        await applyOnboardingConnectionConfig(config, connection);
+        saveElizaConfig(config);
+    };
+}
+/**
+ * Default plugin notify. Iterates the runtime's plugins and calls
+ * `plugin.applyConfig` when defined. The hook receives the plugin's own
+ * config record (already attached to the plugin instance) and the runtime —
+ * matching the elizaOS Plugin contract.
+ *
+ * If no plugin defines `applyConfig`, this is a no-op log: env has been set
+ * and plugins will resolve the new values on their next call into the
+ * provider client.
+ */
+async function defaultNotifyConfigChanged(runtime, change) {
+    const plugins = runtime.plugins ?? [];
+    let notified = 0;
+    let failures = 0;
+    for (const plugin of plugins) {
+        if (typeof plugin.applyConfig !== "function")
+            continue;
+        try {
+            const pluginConfig = {};
+            if (plugin.config) {
+                for (const [key, value] of Object.entries(plugin.config)) {
+                    if (value === null || value === undefined)
+                        continue;
+                    pluginConfig[key] = String(value);
+                }
+            }
+            await plugin.applyConfig(pluginConfig, runtime);
+            notified += 1;
+        }
+        catch (err) {
+            failures += 1;
+            logger.warn(`[runtime-ops] hot reload: plugin "${plugin.name}" applyConfig failed: ${formatErrorWithStack(err)}`);
+        }
+    }
+    if (notified === 0 && failures === 0) {
+        logger.info(`[runtime-ops] no plugin reload hook found — env applied, plugins will pick up on next request (change=${change.kind})`);
+        return;
+    }
+    logger.info(`[runtime-ops] hot reload: notified ${notified} plugin(s), ${failures} failure(s) (change=${change.kind})`);
+}
+export function createHotStrategy(opts = {}) {
+    const secrets = opts.secrets ?? defaultSecretsManager();
+    const applyProviderEnv = opts.applyProviderEnv ?? makeDefaultApplyProviderEnv(secrets);
+    const notifyConfigChanged = opts.notifyConfigChanged ?? defaultNotifyConfigChanged;
+    return {
+        tier: "hot",
+        async apply(ctx) {
+            const envStarted = Date.now();
+            if (ctx.intent.kind !== "provider-switch") {
+                // Other hot-eligible intents (config-reload over env./vars./models.)
+                // flow through the plugin notify step only — env was already mutated
+                // by whoever scheduled the operation (e.g. the config writer).
+                await ctx.reportPhase(buildPhase("apply-env", "skipped", envStarted, Date.now(), {
+                    detail: { reason: `intent=${ctx.intent.kind}` },
+                }));
+            }
+            else {
+                try {
+                    await applyProviderEnv(ctx.intent);
+                    await ctx.reportPhase(buildPhase("apply-env", "succeeded", envStarted, Date.now(), {
+                        detail: { provider: ctx.intent.provider },
+                    }));
+                }
+                catch (err) {
+                    await ctx.reportPhase(buildPhase("apply-env", "failed", envStarted, Date.now(), {
+                        error: { message: formatErrorWithStack(err) },
+                    }));
+                    throw err;
+                }
+            }
+            const notifyStarted = Date.now();
+            const change = describeIntent(ctx.intent);
+            try {
+                await notifyConfigChanged(ctx.runtime, change);
+                await ctx.reportPhase(buildPhase("notify-plugins", "succeeded", notifyStarted, Date.now(), {
+                    detail: change.detail,
+                }));
+            }
+            catch (err) {
+                // Best-effort: env is already applied, so we surface this as a failed
+                // phase with a warning but do NOT throw — the operation still
+                // succeeds at the manager level.
+                logger.warn(`[runtime-ops] hot reload: notify-plugins failed (env already applied): ${formatErrorWithStack(err)}`);
+                await ctx.reportPhase(buildPhase("notify-plugins", "failed", notifyStarted, Date.now(), {
+                    error: { message: formatErrorWithStack(err) },
+                }));
+            }
+            return ctx.runtime;
+        },
+    };
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Filesystem-backed RuntimeOperationRepository.
+ *
+ * Storage layout:
+ *   <stateDir>/runtime-operations/<id>.json   one JSON file per operation
+ *
+ * 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:
+ *   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.ts";
+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 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;
+    create(op: RuntimeOperation): Promise<void>;
+    update(id: string, patch: Partial<Omit<RuntimeOperation, "id" | "phases" | "intent" | "kind">>): Promise<void>;
+    appendPhase(id: string, phase: OperationPhase): Promise<void>;
+    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>;
+    findActive(): Promise<RuntimeOperation | null>;
+}
+/**
+ * Lazy per-process singleton. Constructed on first call so tests can swap
+ * the env or provide their own repository before the manager is built.
+ */
+export declare function getDefaultRepository(): FilesystemRuntimeOperationRepository;
+//# sourceMappingURL=repository.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../../../../../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

@@ -0,0 +1,319 @@
+/**
+ * Filesystem-backed RuntimeOperationRepository.
+ *
+ * Storage layout:
+ *   <stateDir>/runtime-operations/<id>.json   one JSON file per operation
+ *
+ * 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:
+ *   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/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");
+}
+async function readOperationFile(filePath) {
+    const parsed = await readJsonFile(filePath);
+    if (!parsed?.id || !parsed.kind || !Array.isArray(parsed.phases)) {
+        return null;
+    }
+    return parsed;
+}
+export class FilesystemRuntimeOperationRepository {
+    dir;
+    byId = new Map();
+    byIdempotencyKey = new Map();
+    activeId = null;
+    hydration = null;
+    retentionMs;
+    maxRecords;
+    constructor(stateDir = resolveStateDir(), opts = {}) {
+        this.dir = operationsDirFor(stateDir);
+        this.retentionMs =
+            opts.retentionMs ??
+                readEnvNumber("ELIZA_RUNTIME_OPS_RETENTION_MS", DEFAULT_RETENTION_MS);
+        this.maxRecords =
+            opts.maxRecords ??
+                readEnvNumber("ELIZA_RUNTIME_OPS_MAX_RECORDS", DEFAULT_MAX_RECORDS);
+    }
+    hydrate() {
+        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 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;
+            if (isLive && isStale) {
+                const reaped = {
+                    ...op,
+                    status: "failed",
+                    finishedAt: now,
+                    error: {
+                        message: "Operation abandoned (process exited before completion)",
+                        code: "abandoned",
+                    },
+                };
+                await writeJsonAtomic(fullPath, reaped, {
+                    trailingNewline: true,
+                    skipMkdir: true,
+                });
+                this.byId.set(reaped.id, reaped);
+                if (reaped.idempotencyKey) {
+                    this.byIdempotencyKey.set(reaped.idempotencyKey, reaped.id);
+                }
+                logger.info(`[runtime-ops] Reaped abandoned operation on hydrate: ${reaped.id}`);
+                continue;
+            }
+            this.byId.set(op.id, op);
+            if (op.idempotencyKey) {
+                this.byIdempotencyKey.set(op.idempotencyKey, op.id);
+            }
+            if (isLive && !this.activeId) {
+                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) {
+        return writeJsonAtomic(this.pathFor(op.id), op, {
+            trailingNewline: true,
+            skipMkdir: true,
+        });
+    }
+    syncActiveSlot(op) {
+        const isLive = op.status === "pending" || op.status === "running";
+        if (isLive) {
+            this.activeId = op.id;
+            return;
+        }
+        if (this.activeId === op.id) {
+            this.activeId = null;
+        }
+    }
+    async create(op) {
+        await this.hydrate();
+        if (this.byId.has(op.id)) {
+            throw new Error(`[runtime-ops] Operation already exists: ${op.id}`);
+        }
+        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) {
+        await this.hydrate();
+        const current = this.byId.get(id);
+        if (!current) {
+            throw new Error(`[runtime-ops] Operation not found: ${id}`);
+        }
+        const next = { ...current, ...patch };
+        await this.persist(next);
+        this.byId.set(id, next);
+        this.syncActiveSlot(next);
+    }
+    async appendPhase(id, phase) {
+        await this.hydrate();
+        const current = this.byId.get(id);
+        if (!current) {
+            throw new Error(`[runtime-ops] Operation not found: ${id}`);
+        }
+        const next = {
+            ...current,
+            phases: [...current.phases, phase],
+        };
+        await this.persist(next);
+        this.byId.set(id, next);
+    }
+    async updateLastPhase(id, patch) {
+        await this.hydrate();
+        const current = this.byId.get(id);
+        if (!current) {
+            throw new Error(`[runtime-ops] Operation not found: ${id}`);
+        }
+        const last = current.phases[current.phases.length - 1];
+        if (!last) {
+            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 };
+        await this.persist(next);
+        this.byId.set(id, next);
+    }
+    async get(id) {
+        await this.hydrate();
+        return this.byId.get(id) ?? null;
+    }
+    async list(opts) {
+        await this.hydrate();
+        let ops = Array.from(this.byId.values());
+        if (opts?.status) {
+            ops = ops.filter((o) => o.status === opts.status);
+        }
+        else if (opts?.includeTerminal === false) {
+            ops = ops.filter((o) => o.status === "pending" || o.status === "running");
+        }
+        ops.sort((a, b) => b.startedAt - a.startedAt);
+        if (typeof opts?.limit === "number" && opts.limit >= 0) {
+            ops = ops.slice(0, opts.limit);
+        }
+        return ops;
+    }
+    async findByIdempotencyKey(key) {
+        await this.hydrate();
+        const id = this.byIdempotencyKey.get(key);
+        if (!id)
+            return null;
+        const op = this.byId.get(id);
+        if (!op)
+            return null;
+        if (Date.now() - op.startedAt > IDEMPOTENCY_RETENTION_MS) {
+            return null;
+        }
+        return op;
+    }
+    async findActive() {
+        await this.hydrate();
+        if (!this.activeId)
+            return null;
+        const op = this.byId.get(this.activeId);
+        if (!op) {
+            this.activeId = null;
+            return null;
+        }
+        if (op.status !== "pending" && op.status !== "running") {
+            this.activeId = null;
+            return null;
+        }
+        return op;
+    }
+}
+let cachedDefault = null;
+/**
+ * Lazy per-process singleton. Constructed on first call so tests can swap
+ * the env or provide their own repository before the manager is built.
+ */
+export function getDefaultRepository() {
+    if (!cachedDefault) {
+        cachedDefault = new FilesystemRuntimeOperationRepository();
+    }
+    return cachedDefault;
+}