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

package/packages/agent/src/api/chat-text-helpers.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Chat text normalization helpers.
+ *
+ * Shared between server.ts and chat-routes.ts. Extracted to avoid
+ * duplication when both modules need stage-direction stripping and
+ * no-response detection.
+ */
+export declare function isNoResponsePlaceholder(text: string): boolean;
+export declare function stripAssistantStageDirections(input: string): string;
+export declare function isClientVisibleNoResponse(text: string): boolean;
+//# sourceMappingURL=chat-text-helpers.d.ts.map

package/packages/agent/src/api/chat-text-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-text-helpers.d.ts","sourceRoot":"","sources":["../../../../../src/api/chat-text-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAkIH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAG7D;AAiDD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKnE;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAG/D"}

package/packages/agent/src/api/chat-text-helpers.js

@@ -0,0 +1,184 @@
+/**
+ * Chat text normalization helpers.
+ *
+ * Shared between server.ts and chat-routes.ts. Extracted to avoid
+ * duplication when both modules need stage-direction stripping and
+ * no-response detection.
+ */
+// ---------------------------------------------------------------------------
+// Stage-direction vocabulary
+// ---------------------------------------------------------------------------
+const STAGE_DIRECTION_FIRST_WORDS = new Set([
+    "beam",
+    "beams",
+    "beaming",
+    "blink",
+    "blinks",
+    "blinking",
+    "blush",
+    "blushes",
+    "blushing",
+    "bow",
+    "bows",
+    "bowing",
+    "breathe",
+    "breathes",
+    "breathing",
+    "cheer",
+    "cheers",
+    "cheering",
+    "chuckle",
+    "chuckles",
+    "chuckling",
+    "clap",
+    "claps",
+    "clapping",
+    "cry",
+    "cries",
+    "crying",
+    "curtsy",
+    "curtsies",
+    "curtsying",
+    "dance",
+    "dances",
+    "dancing",
+    "frown",
+    "frowns",
+    "frowning",
+    "gasp",
+    "gasps",
+    "gasping",
+    "gesture",
+    "gestures",
+    "gesturing",
+    "giggle",
+    "giggles",
+    "giggling",
+    "glance",
+    "glances",
+    "glancing",
+    "grin",
+    "grins",
+    "grinning",
+    "laugh",
+    "laughs",
+    "laughing",
+    "lean",
+    "leans",
+    "leaning",
+    "look",
+    "looks",
+    "looking",
+    "nod",
+    "nods",
+    "nodding",
+    "pause",
+    "pauses",
+    "pausing",
+    "point",
+    "points",
+    "pointing",
+    "pose",
+    "poses",
+    "posing",
+    "pout",
+    "pouts",
+    "pouting",
+    "raise",
+    "raises",
+    "raising",
+    "shrug",
+    "shrugs",
+    "shrugging",
+    "sigh",
+    "sighs",
+    "sighing",
+    "smile",
+    "smiles",
+    "smiling",
+    "smirk",
+    "smirks",
+    "smirking",
+    "spin",
+    "spins",
+    "spinning",
+    "stare",
+    "stares",
+    "staring",
+    "stretch",
+    "stretches",
+    "stretching",
+    "sway",
+    "sways",
+    "swaying",
+    "tilt",
+    "tilts",
+    "tilting",
+    "wave",
+    "waves",
+    "waving",
+    "whisper",
+    "whispers",
+    "whispering",
+    "wink",
+    "winks",
+    "winking",
+    "yawn",
+    "yawns",
+    "yawning",
+]);
+// ---------------------------------------------------------------------------
+// Exported helpers
+// ---------------------------------------------------------------------------
+export function isNoResponsePlaceholder(text) {
+    const trimmed = text.trim();
+    return trimmed.length === 0 || /^\(?no response\)?$/i.test(trimmed);
+}
+function collapseInlineWhitespace(input) {
+    return input.replace(/[ \t]+/g, " ").trim();
+}
+function looksLikeStageDirection(input) {
+    const normalized = collapseInlineWhitespace(input)
+        .replace(/^[^A-Za-z]+/, "")
+        .replace(/[^A-Za-z'-]+$/, "");
+    if (!normalized)
+        return false;
+    const [firstWord = ""] = normalized.toLowerCase().split(/\s+/, 1);
+    return STAGE_DIRECTION_FIRST_WORDS.has(firstWord);
+}
+function stripWrappedStageDirections(input, pattern) {
+    return input.replace(pattern, (match, inner, offset, source) => {
+        const prev = source[offset - 1] ?? "";
+        const next = source[offset + match.length] ?? "";
+        const hasSafeLeftBoundary = offset === 0 || /[\s([{>"'"'.!?,;:-]/.test(prev);
+        const hasSafeRightBoundary = offset + match.length >= source.length ||
+            /[\s)\]}<"'"'.!?,;:-]/.test(next);
+        if (!hasSafeLeftBoundary ||
+            !hasSafeRightBoundary ||
+            !looksLikeStageDirection(inner)) {
+            return match;
+        }
+        return " ";
+    });
+}
+function tidyAssistantTextSpacing(input) {
+    const safe = input.length > 100_000 ? input.slice(0, 100_000) : input;
+    return safe
+        .replace(/[ \t]{1,1024}\n/g, "\n")
+        .replace(/\n[ \t]{1,1024}/g, "\n")
+        .replace(/[ \t]{2,1024}/g, " ")
+        .replace(/ ?([,.;!?])/g, "$1")
+        .replace(/\(\s{1,1024}/g, "(")
+        .replace(/\s{1,1024}\)/g, ")");
+}
+export function stripAssistantStageDirections(input) {
+    let normalized = input;
+    normalized = stripWrappedStageDirections(normalized, /\*([^*\n]+)\*/g);
+    normalized = stripWrappedStageDirections(normalized, /_([^_\n]+)_/g);
+    return tidyAssistantTextSpacing(normalized);
+}
+export function isClientVisibleNoResponse(text) {
+    if (isNoResponsePlaceholder(text))
+        return true;
+    return isNoResponsePlaceholder(stripAssistantStageDirections(text));
+}

package/packages/agent/src/api/client-chat-admin.d.ts

@@ -0,0 +1,19 @@
+import { type IAgentRuntime, type UUID } from "@elizaos/core";
+type ClientChatAdminState = {
+    runtime?: IAgentRuntime | {
+        getSetting?: (key: string) => unknown;
+    } | null;
+    adminEntityId?: UUID | null;
+    chatUserId?: UUID | null;
+    config?: {
+        agents?: {
+            defaults?: {
+                adminEntityId?: string;
+            };
+        };
+    } | null;
+    agentName: string;
+};
+export declare function resolveClientChatAdminEntityId<TState extends ClientChatAdminState>(state: TState): UUID;
+export {};
+//# sourceMappingURL=client-chat-admin.d.ts.map

package/packages/agent/src/api/client-chat-admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-chat-admin.d.ts","sourceRoot":"","sources":["../../../../../src/api/client-chat-admin.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAIlB,KAAK,IAAI,EACV,MAAM,eAAe,CAAC;AAIvB,KAAK,oBAAoB,GAAG;IAC1B,OAAO,CAAC,EAAE,aAAa,GAAG;QAAE,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC3E,aAAa,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAC5B,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,EAAE;QACP,MAAM,CAAC,EAAE;YACP,QAAQ,CAAC,EAAE;gBACT,aAAa,CAAC,EAAE,MAAM,CAAC;aACxB,CAAC;SACH,CAAC;KACH,GAAG,IAAI,CAAC;IACT,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,wBAAgB,8BAA8B,CAC5C,MAAM,SAAS,oBAAoB,EACnC,KAAK,EAAE,MAAM,GAAG,IAAI,CAgCrB"}

package/packages/agent/src/api/client-chat-admin.js

@@ -0,0 +1,27 @@
+import { logger, resolveCanonicalOwnerId, stringToUuid, } from "@elizaos/core";
+import { isUuidLike } from "./server-helpers.js";
+export function resolveClientChatAdminEntityId(state) {
+    const canonicalOwnerId = state.runtime && typeof state.runtime.getSetting === "function"
+        ? resolveCanonicalOwnerId(state.runtime)
+        : null;
+    if (canonicalOwnerId && isUuidLike(canonicalOwnerId)) {
+        state.adminEntityId = canonicalOwnerId;
+        state.chatUserId = state.adminEntityId;
+        return state.adminEntityId;
+    }
+    if (state.adminEntityId) {
+        state.chatUserId = state.adminEntityId;
+        return state.adminEntityId;
+    }
+    const configuredValue = state.config?.agents?.defaults?.adminEntityId;
+    const configured = typeof configuredValue === "string" ? configuredValue.trim() : undefined;
+    const nextAdminEntityId = configured && isUuidLike(configured)
+        ? configured
+        : stringToUuid(`${state.agentName}-admin-entity`);
+    if (configured && !isUuidLike(configured)) {
+        logger.warn(`[eliza-api] Invalid agents.defaults.adminEntityId "${configured}", using deterministic fallback`);
+    }
+    state.adminEntityId = nextAdminEntityId;
+    state.chatUserId = nextAdminEntityId;
+    return nextAdminEntityId;
+}

package/packages/agent/src/api/cloud-route-registry.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Cloud route registry — inverts the agent ↔ plugin-elizacloud dependency.
+ *
+ * plugin-elizacloud (or any other cloud provider) calls registerCloudRoutes()
+ * during plugin init. The agent's API server reads from this registry instead
+ * of importing plugin-elizacloud directly.
+ *
+ * This breaks the cycle: agent no longer needs plugin-elizacloud as a
+ * compile-time dependency; the registry is filled at runtime.
+ */
+export interface CloudRouteHandlers {
+    handleCloudBillingRoute?: (...args: unknown[]) => unknown;
+    handleCloudCompatRoute?: (...args: unknown[]) => unknown;
+    handleCloudRelayRoute?: (...args: unknown[]) => unknown;
+    handleCloudStatusRoutes?: (...args: unknown[]) => unknown;
+    handleCloudFeaturesRoute?: (...args: unknown[]) => unknown;
+    isCloudProvisionedContainer?: () => boolean;
+}
+export declare function registerCloudRoutes(handlers: CloudRouteHandlers): void;
+export declare function getCloudRoutes(): CloudRouteHandlers;
+export declare function clearCloudRoutes(): void;
+//# sourceMappingURL=cloud-route-registry.d.ts.map

package/packages/agent/src/api/cloud-route-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-route-registry.d.ts","sourceRoot":"","sources":["../../../../../src/api/cloud-route-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,kBAAkB;IACjC,uBAAuB,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAC1D,sBAAsB,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IACzD,qBAAqB,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IACxD,uBAAuB,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAC1D,wBAAwB,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;IAC3D,2BAA2B,CAAC,EAAE,MAAM,OAAO,CAAC;CAE7C;AAID,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAEtE;AAED,wBAAgB,cAAc,IAAI,kBAAkB,CAEnD;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}

package/packages/agent/src/api/cloud-route-registry.js

@@ -0,0 +1,20 @@
+/**
+ * Cloud route registry — inverts the agent ↔ plugin-elizacloud dependency.
+ *
+ * plugin-elizacloud (or any other cloud provider) calls registerCloudRoutes()
+ * during plugin init. The agent's API server reads from this registry instead
+ * of importing plugin-elizacloud directly.
+ *
+ * This breaks the cycle: agent no longer needs plugin-elizacloud as a
+ * compile-time dependency; the registry is filled at runtime.
+ */
+let registered = {};
+export function registerCloudRoutes(handlers) {
+    registered = { ...registered, ...handlers };
+}
+export function getCloudRoutes() {
+    return registered;
+}
+export function clearCloudRoutes() {
+    registered = {};
+}

package/packages/agent/src/api/compat-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compat-utils.d.ts","sourceRoot":"","sources":["../../../../../src/api/compat-utils.ts"],"names":[],"mappings":"AASA;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAiBjE;AAED,MAAM,MAAM,cAAc,GACtB,QAAQ,GACR,WAAW,GACX,MAAM,GACN,WAAW,GACX,MAAM,GACN,UAAU,CAAC;AAEf,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,OAAO,GAChB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA0BzC;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,CAAC;AAEjD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,iCAAiC,CAAC,IAAI,EAAE;IACtD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAkB1C;AAWD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,QAAQ,SAAY,GACnB,MAAM,CAeR"}
+{"version":3,"file":"compat-utils.d.ts","sourceRoot":"","sources":["../../../../../src/api/compat-utils.ts"],"names":[],"mappings":"AAMA;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAiBjE;AAED,MAAM,MAAM,cAAc,GACtB,QAAQ,GACR,WAAW,GACX,MAAM,GACN,WAAW,GACX,MAAM,GACN,UAAU,CAAC;AAEf,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,OAAO,GAChB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA0BzC;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,CAAC;AAEjD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,iCAAiC,CAAC,IAAI,EAAE;IACtD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAkB1C;AAWD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,QAAQ,SAAY,GACnB,MAAM,CAeR"}

package/packages/agent/src/api/compat-utils.js

@@ -1,8 +1,4 @@
-function asRecord(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return null;
-    return value;
-}
+import { asRecord } from "@elizaos/shared";
 function readString(value) {
     return typeof value === "string" ? value : "";
 }

package/packages/agent/src/api/config-env.d.ts

@@ -0,0 +1,43 @@
+interface PersistOptions {
+    /** Override state dir (mostly for tests). Defaults to `resolveStateDir()`. */
+    stateDir?: string;
+}
+interface ParsedConfigEnv {
+    /** Ordered list of raw lines (comments, blanks, key=value). */
+    lines: string[];
+    /** Map of key → index into `lines`, for in-place updates. */
+    index: Map<string, number>;
+}
+declare function parseConfigEnv(contents: string): ParsedConfigEnv;
+declare function serialiseConfigEnv(parsed: ParsedConfigEnv): string;
+/**
+ * Read the on-disk `config.env` into a plain record. Does NOT touch
+ * `process.env`. Missing file → empty record.
+ */
+export declare function readConfigEnv(stateDir?: string): Promise<Record<string, string>>;
+/**
+ * Synchronous variant for early startup paths such as `loadElizaConfig()`.
+ * Missing file → empty record. Does NOT touch `process.env`.
+ */
+export declare function readConfigEnvSync(stateDir?: string): Record<string, string>;
+/**
+ * Atomically write `key=value` into `config.env`, preserving all other
+ * entries, comments, and blank lines. Also updates `process.env[key]` so
+ * the in-flight process observes the new value immediately.
+ *
+ * Pass empty string to delete the key. Missing file → created with 0600.
+ *
+ * @throws if `key` is malformed or in the hijack-vector blocklist.
+ */
+export declare function persistConfigEnv(key: string, value: string, opts?: PersistOptions): Promise<void>;
+/** Exposed for tests and recovery tooling. */
+export declare const __testing: {
+    BLOCKED_CONFIG_ENV_KEYS: ReadonlySet<string>;
+    CONFIG_ENV_FILENAME: string;
+    BAK_SUFFIX: string;
+    TMP_SUFFIX: string;
+    parseConfigEnv: typeof parseConfigEnv;
+    serialiseConfigEnv: typeof serialiseConfigEnv;
+};
+export {};
+//# sourceMappingURL=config-env.d.ts.map

package/packages/agent/src/api/config-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-env.d.ts","sourceRoot":"","sources":["../../../../../src/api/config-env.ts"],"names":[],"mappings":"AAsEA,UAAU,cAAc;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,eAAe;IACvB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,6DAA6D;IAC7D,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5B;AAED,iBAAS,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CAoBzD;AAED,iBAAS,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAG3D;AAiED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAcjC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAqB3E;AAwBD;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,IAAI,CAAC,CAkDf;AAED,8CAA8C;AAC9C,eAAO,MAAM,SAAS;;;;;;;CAOrB,CAAC"}

package/packages/agent/src/api/config-env.js

@@ -0,0 +1,284 @@
+/**
+ * Atomic key/value writer for the on-disk `config.env` file.
+ *
+ * `config.env` lives under the Eliza state directory (default
+ * `~/.eliza/config.env`, or whatever `ELIZA_STATE_DIR`
+ * resolves to). It is an escape hatch for sensitive process-env-only
+ * material (e.g. cloud-wallet client address keys, `WALLET_SOURCE_*`
+ * bindings) that must not be mirrored into `eliza.json` but still needs
+ * to survive restarts.
+ *
+ * ── Crash safety ────────────────────────────────────────────────────
+ * Every write performs three on-disk steps:
+ *   1. Snapshot existing contents to `config.env.bak`.
+ *   2. Serialise the new contents to `config.env.tmp` and fsync.
+ *   3. Rename `config.env.tmp` → `config.env` (atomic on POSIX).
+ *
+ * Failure modes:
+ *   - Step 2 fails → no `config.env` mutation. `.bak` may exist but the
+ *     live file is untouched.
+ *   - Step 3 fails → `.bak` still holds the pre-image. Recover manually
+ *     via `cp ~/.eliza/config.env.bak ~/.eliza/config.env` or the
+ *     documented `bun run agent:repair-config` command.
+ *
+ * Concurrent writes in-process are serialised via a promise chain mutex.
+ * Cross-process coordination is NOT provided — callers must ensure only
+ * one agent runtime owns a given state dir (the PGlite postmaster lock
+ * already enforces this).
+ */
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveStateDir } from "../config/paths.js";
+const CONFIG_ENV_FILENAME = "config.env";
+const BAK_SUFFIX = ".bak";
+const TMP_SUFFIX = ".tmp";
+const KEY_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+/**
+ * Keys we refuse to write even though `config.env` is the designated
+ * escape hatch for sensitive process-env-only material. These are
+ * shell/runtime hijack vectors — they must never be set from the
+ * application layer, regardless of provenance.
+ */
+const BLOCKED_CONFIG_ENV_KEYS = new Set([
+    "NODE_OPTIONS",
+    "NODE_EXTRA_CA_CERTS",
+    "NODE_TLS_REJECT_UNAUTHORIZED",
+    "NODE_PATH",
+    "LD_PRELOAD",
+    "LD_LIBRARY_PATH",
+    "DYLD_INSERT_LIBRARIES",
+    "DYLD_LIBRARY_PATH",
+    "DYLD_FRAMEWORK_PATH",
+    "DYLD_FALLBACK_FRAMEWORK_PATH",
+    "DYLD_FALLBACK_LIBRARY_PATH",
+    "PATH",
+    "HOME",
+    "SHELL",
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "ALL_PROXY",
+    "NO_PROXY",
+    "SSL_CERT_FILE",
+    "SSL_CERT_DIR",
+    "CURL_CA_BUNDLE",
+]);
+function parseConfigEnv(contents) {
+    const lines = contents.length === 0 ? [] : contents.split(/\r?\n/);
+    // `split` on trailing newline produces an empty final element — drop it
+    // so we don't re-emit a double blank at EOF on every rewrite.
+    if (lines.length > 0 && lines[lines.length - 1] === "") {
+        lines.pop();
+    }
+    const index = new Map();
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? "";
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const key = line.slice(0, eq).trim();
+        if (!KEY_PATTERN.test(key))
+            continue;
+        // Last definition wins (standard dotenv behaviour).
+        index.set(key, i);
+    }
+    return { lines, index };
+}
+function serialiseConfigEnv(parsed) {
+    if (parsed.lines.length === 0)
+        return "";
+    return `${parsed.lines.join("\n")}\n`;
+}
+function encodeValue(value) {
+    // Quote values that contain whitespace, `#`, or non-printable characters,
+    // and escape embedded quotes/backslashes/newlines so the file round-trips
+    // through standard dotenv parsers.
+    if (value === "")
+        return "";
+    const needsQuoting = /[\s#"'\\]|^\s|\s$/.test(value) || /\n|\r/.test(value);
+    if (!needsQuoting)
+        return value;
+    const escaped = value
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, "\\n")
+        .replace(/\r/g, "\\r");
+    return `"${escaped}"`;
+}
+function validateKey(key) {
+    if (!KEY_PATTERN.test(key)) {
+        throw new Error(`persistConfigEnv: invalid key "${key}" — must match /^[A-Z][A-Z0-9_]*$/`);
+    }
+    if (BLOCKED_CONFIG_ENV_KEYS.has(key)) {
+        throw new Error(`persistConfigEnv: key "${key}" is a shell/runtime hijack vector and cannot be written`);
+    }
+}
+async function readIfExists(filePath) {
+    try {
+        return await fs.readFile(filePath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+async function writeAtomic(filePath, contents) {
+    const tmpPath = `${filePath}${TMP_SUFFIX}`;
+    const handle = await fs.open(tmpPath, "w", 0o600);
+    try {
+        await handle.writeFile(contents, "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await fs.rename(tmpPath, filePath);
+}
+// In-process serialisation. Cross-process coordination is out of scope.
+let writeChain = Promise.resolve();
+function serialise(fn) {
+    const next = writeChain.then(fn, fn);
+    writeChain = next.catch(() => undefined);
+    return next;
+}
+function resolveConfigEnvPath(stateDir) {
+    const dir = stateDir ?? resolveStateDir();
+    return path.join(dir, CONFIG_ENV_FILENAME);
+}
+/**
+ * Read the on-disk `config.env` into a plain record. Does NOT touch
+ * `process.env`. Missing file → empty record.
+ */
+export async function readConfigEnv(stateDir) {
+    const filePath = resolveConfigEnvPath(stateDir);
+    const raw = await readIfExists(filePath);
+    if (raw === null)
+        return {};
+    const parsed = parseConfigEnv(raw);
+    const out = {};
+    for (const [key, idx] of parsed.index) {
+        const line = parsed.lines[idx] ?? "";
+        const eq = line.indexOf("=");
+        if (eq < 0)
+            continue;
+        const rawValue = line.slice(eq + 1);
+        out[key] = decodeValue(rawValue);
+    }
+    return out;
+}
+/**
+ * Synchronous variant for early startup paths such as `loadElizaConfig()`.
+ * Missing file → empty record. Does NOT touch `process.env`.
+ */
+export function readConfigEnvSync(stateDir) {
+    const filePath = resolveConfigEnvPath(stateDir);
+    let raw;
+    try {
+        raw = fsSync.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return {};
+        }
+        throw err;
+    }
+    const parsed = parseConfigEnv(raw);
+    const out = {};
+    for (const [key, idx] of parsed.index) {
+        const line = parsed.lines[idx] ?? "";
+        const eq = line.indexOf("=");
+        if (eq < 0)
+            continue;
+        out[key] = decodeValue(line.slice(eq + 1));
+    }
+    return out;
+}
+function decodeValue(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return "";
+    const first = trimmed[0];
+    if ((first === '"' || first === "'") &&
+        trimmed.endsWith(first) &&
+        trimmed.length >= 2) {
+        const inner = trimmed.slice(1, -1);
+        if (first === '"') {
+            return inner
+                .replace(/\\n/g, "\n")
+                .replace(/\\r/g, "\r")
+                .replace(/\\"/g, '"')
+                .replace(/\\\\/g, "\\");
+        }
+        return inner;
+    }
+    return trimmed;
+}
+/**
+ * Atomically write `key=value` into `config.env`, preserving all other
+ * entries, comments, and blank lines. Also updates `process.env[key]` so
+ * the in-flight process observes the new value immediately.
+ *
+ * Pass empty string to delete the key. Missing file → created with 0600.
+ *
+ * @throws if `key` is malformed or in the hijack-vector blocklist.
+ */
+export async function persistConfigEnv(key, value, opts = {}) {
+    validateKey(key);
+    await serialise(async () => {
+        const filePath = resolveConfigEnvPath(opts.stateDir);
+        const dir = path.dirname(filePath);
+        await fs.mkdir(dir, { recursive: true });
+        const existing = (await readIfExists(filePath)) ?? "";
+        const parsed = parseConfigEnv(existing);
+        const isDelete = value === "";
+        const existingIdx = parsed.index.get(key);
+        if (isDelete) {
+            if (existingIdx === undefined) {
+                // Nothing to do — don't write a .bak for a no-op.
+                if (key in process.env)
+                    delete process.env[key];
+                return;
+            }
+            parsed.lines.splice(existingIdx, 1);
+            // Indices after removal are stale, but we're done mutating — no
+            // further lookups happen in this call.
+        }
+        else {
+            const encoded = `${key}=${encodeValue(value)}`;
+            if (existingIdx === undefined) {
+                parsed.lines.push(encoded);
+            }
+            else {
+                parsed.lines[existingIdx] = encoded;
+            }
+        }
+        const nextContents = serialiseConfigEnv(parsed);
+        // Snapshot pre-image for manual recovery before touching the live file.
+        if (existing.length > 0) {
+            await fs.writeFile(`${filePath}${BAK_SUFFIX}`, existing, {
+                encoding: "utf8",
+                mode: 0o600,
+            });
+        }
+        await writeAtomic(filePath, nextContents);
+        if (isDelete) {
+            delete process.env[key];
+        }
+        else {
+            process.env[key] = value;
+        }
+    });
+}
+/** Exposed for tests and recovery tooling. */
+export const __testing = {
+    BLOCKED_CONFIG_ENV_KEYS,
+    CONFIG_ENV_FILENAME,
+    BAK_SUFFIX,
+    TMP_SUFFIX,
+    parseConfigEnv,
+    serialiseConfigEnv,
+};