@elizaos/agent 2.0.0-beta.2 → 2.0.11-beta.5

package/runtime/sandbox-character.js

@@ -0,0 +1,193 @@
+/**
+ * Cloud sandbox character loader (Path A).
+ *
+ * A Hetzner-provisioned container is meant to boot AS its assigned character
+ * (e.g. "Nyx"), not as the generic bundled "Eliza" preset. The full character
+ * config lives in the `agent_sandboxes.agent_config` column and is injected by
+ * the provisioner as the `ELIZA_AGENT_CHARACTER_JSON` env var. Without this,
+ * `buildCharacterFromConfig` falls back to the default style preset because
+ * `config.agents.list[0]` is empty in a fresh container.
+ *
+ * This module parses that env var and merges it onto `config.agents.list[0]`
+ * so the existing `buildCharacterFromConfig` path picks up the right name,
+ * system prompt, bio, examples, topics, adjectives and style. It returns the
+ * config unchanged when the env var is absent or unparseable,
+ * so it is inert for every non-provisioned runtime.
+ */
+import { logger } from "@elizaos/core";
+/**
+ * Whether this container should own (connect directly to) its platform
+ * connectors. Default false: the gateway owns the connection and forwards
+ * inbound events to the container (resolves the double-connect seam). Set
+ * ELIZA_SANDBOX_OWNS_CONNECTORS=1 only when the operator has linked the
+ * connector to the container and disabled the gateway's connection row.
+ */
+export function sandboxOwnsConnectors(env = process.env) {
+    return env.ELIZA_SANDBOX_OWNS_CONNECTORS?.trim() === "1";
+}
+function asStringArray(value) {
+    if (Array.isArray(value)) {
+        return value.filter((v) => typeof v === "string");
+    }
+    if (typeof value === "string" && value.trim())
+        return [value];
+    return undefined;
+}
+/**
+ * Resolve the routing agent id for this container: the id the gateways use to
+ * resolve `agent:<id>:server` and to address `/agents/<id>/message`. This MUST
+ * be the platform `character_id` (the same value the gateway's
+ * `discord_connections.character_id` carries), not the sandbox id. The
+ * provisioner injects it as SANDBOX_ROUTE_AGENT_ID. Falls back to null when
+ * absent (non-provisioned runtime), in which case the runtime keeps its
+ * name-derived agent id.
+ */
+export function resolveSandboxRouteAgentId(env = process.env) {
+    return env.SANDBOX_ROUTE_AGENT_ID?.trim() || null;
+}
+/**
+ * Apply the injected sandbox character (if any) onto the runtime config.
+ * Returns the same config object (mutated) for chaining convenience.
+ */
+export function applySandboxCharacterFromEnv(config, env = process.env) {
+    const raw = env.ELIZA_AGENT_CHARACTER_JSON?.trim();
+    if (!raw)
+        return config;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        logger.warn(`[sandbox-character] ELIZA_AGENT_CHARACTER_JSON is not valid JSON; booting with default character: ${err instanceof Error ? err.message : String(err)}`);
+        return config;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return config;
+    const name = parsed.name?.trim() ||
+        env.ELIZA_AGENT_NAME?.trim() ||
+        env.AGENT_NAME?.trim();
+    if (!name) {
+        logger.warn("[sandbox-character] Injected character has no name; booting with default character");
+        return config;
+    }
+    // The id MUST be the routing character_id so the runtime's agentId matches
+    // what the gateways resolve (`agent:<id>:server`) and address
+    // (`/agents/<id>/message`). Fall back to the embedded character id, then
+    // the sandbox id, then a name-derived slug.
+    const id = resolveSandboxRouteAgentId(env) ||
+        (typeof parsed.id === "string" && parsed.id.trim()) ||
+        env.SANDBOX_AGENT_ID?.trim() ||
+        name.toLowerCase().replace(/\s+/g, "-");
+    const entry = {
+        id,
+        default: true,
+        name,
+        ...(parsed.username ? { username: parsed.username } : {}),
+        ...(parsed.system ? { system: parsed.system } : {}),
+        ...(asStringArray(parsed.bio) ? { bio: asStringArray(parsed.bio) } : {}),
+        ...(asStringArray(parsed.topics)
+            ? { topics: asStringArray(parsed.topics) }
+            : {}),
+        ...(asStringArray(parsed.adjectives)
+            ? { adjectives: asStringArray(parsed.adjectives) }
+            : {}),
+        ...(asStringArray(parsed.postExamples)
+            ? { postExamples: asStringArray(parsed.postExamples) }
+            : {}),
+        ...(parsed.style ? { style: parsed.style } : {}),
+        ...(parsed.messageExamples
+            ? {
+                messageExamples: parsed.messageExamples,
+            }
+            : {}),
+    };
+    const agents = (config.agents ?? {});
+    const list = Array.isArray(agents.list) ? [...agents.list] : [];
+    // Replace any existing primary entry; the injected character is authoritative.
+    const existingIdx = list.findIndex((a) => a?.default) ?? -1;
+    if (existingIdx >= 0) {
+        list[existingIdx] = { ...list[existingIdx], ...entry };
+    }
+    else {
+        list.unshift(entry);
+    }
+    config.agents = { ...agents, list };
+    // Also surface the assistant name at the UI level so logging/prompts that
+    // read config.ui.assistant.name agree with the loaded character.
+    const ui = (config.ui ?? {});
+    config.ui = {
+        ...ui,
+        assistant: { ...(ui.assistant ?? {}), name },
+    };
+    // Connector ownership (Deliverable B / double-connect resolution). When the
+    // operator makes the container the connector owner, apply the per-character
+    // connector config so the runtime loads the connector plugin and connects
+    // directly. Otherwise the gateway keeps the connection and forwards inbound
+    // events to /agents/<id>/message here.
+    if (sandboxOwnsConnectors(env) &&
+        parsed.connectors &&
+        typeof parsed.connectors === "object" &&
+        !Array.isArray(parsed.connectors)) {
+        config.connectors = {
+            ...(config.connectors ?? {}),
+            ...parsed.connectors,
+        };
+        logger.info(`[sandbox-character] Container owns connectors (${Object.keys(parsed.connectors).join(", ")}); will connect directly`);
+    }
+    logger.info(`[sandbox-character] Loaded injected character "${name}" (id=${id}) from ELIZA_AGENT_CHARACTER_JSON`);
+    return config;
+}
+/** Connector bot-token env vars that trigger a direct platform connection. */
+const CONNECTOR_TOKEN_ENV_KEYS = [
+    "DISCORD_API_TOKEN",
+    "DISCORD_BOT_TOKEN",
+    "TELEGRAM_BOT_TOKEN",
+];
+/** Connector keys whose config blocks would let the runtime re-derive a token. */
+const CONNECTOR_CONFIG_KEYS = ["discord", "telegram"];
+/**
+ * Resolve the double-connect seam for a provisioned container.
+ *
+ * In the default (gateway-owned) mode the gateway holds the Discord/Telegram
+ * connection and forwards inbound events to this container; if the container
+ * ALSO connected with the same bot token we would get token contention and
+ * duplicate replies. So, unless the operator has explicitly made the
+ * container the connector owner (ELIZA_SANDBOX_OWNS_CONNECTORS=1), we strip
+ * the connector bot tokens from the environment AND clear the matching
+ * config.connectors blocks so the container runs purely as an inference
+ * target reached via /agents/<id>/message.
+ *
+ * IMPORTANT: callers must run this AFTER applyConnectorSecretsToEnv (which can
+ * repopulate the env tokens from config.connectors) and BEFORE plugin
+ * auto-enable / resolvePlugins.
+ *
+ * Skipped outside a provisioned container (ELIZA_CLOUD_PROVISIONED != "1"), so
+ * local dev and the in-worker path are unaffected.
+ */
+export function applySandboxConnectorOwnership(env = process.env, config) {
+    if (env.ELIZA_CLOUD_PROVISIONED !== "1")
+        return;
+    if (sandboxOwnsConnectors(env))
+        return;
+    const stripped = [];
+    for (const key of CONNECTOR_TOKEN_ENV_KEYS) {
+        if (env[key]) {
+            delete env[key];
+            stripped.push(key);
+        }
+    }
+    // Also drop the connector config blocks so nothing downstream
+    // (plugin auto-enable, a later applyConnectorSecretsToEnv) re-derives the
+    // token from config and reconnects.
+    if (config?.connectors && typeof config.connectors === "object") {
+        for (const key of CONNECTOR_CONFIG_KEYS) {
+            if (key in config.connectors) {
+                delete config.connectors[key];
+                stripped.push(`config.connectors.${key}`);
+            }
+        }
+    }
+    if (stripped.length > 0) {
+        logger.info(`[sandbox-character] Gateway owns connectors; not connecting directly (cleared ${stripped.join(", ")} to avoid double-connect). Set ELIZA_SANDBOX_OWNS_CONNECTORS=1 to connect from the container instead.`);
+    }
+}

package/runtime/sandbox-registry.d.ts

@@ -0,0 +1,96 @@
+/**
+ * SandboxRegistry (agent runtime) — self-registers a cloud-provisioned
+ * container in the shared Redis so the multi-tenant gateways
+ * (`gateway-discord`, `gateway-webhook`) can resolve `agent_id -> server URL`
+ * and forward inbound platform messages to THIS container.
+ *
+ * WHY this lives in `packages/agent` (and duplicates the logic in
+ * `packages/app-core/src/services/sandbox-registry.ts`):
+ * The published cloud image runs `packages/agent/dist/bin.js` as its
+ * entrypoint (see `packages/app-core/deploy/Dockerfile.ci` APP_ENTRYPOINT).
+ * That entrypoint boots the agent runtime in `packages/agent/src/runtime/eliza.ts`,
+ * which CANNOT import `@elizaos/app-core` without creating an
+ * `agent -> app-core -> agent` workspace cycle. The app-core copy therefore
+ * never executes in a provisioned container. This is a deliberate, minimal
+ * backport scoped to the container self-registration seam (Path A). Keep the
+ * two copies in lock-step.
+ *
+ * It writes two Redis keys with a short TTL; a periodic heartbeat refreshes
+ * the TTL while the container is alive, and `unregister()` deletes them on
+ * graceful shutdown if they still point at this container. If the container
+ * crashes, the keys expire naturally and the gateways stop routing to a dead
+ * address.
+ *
+ *   server:<serverName>:url = <serverUrl>   (resolver address)
+ *   agent:<agentId>:server  = <serverName>  (agent -> server pointer)
+ *
+ * Two transports are supported, selected by the URL scheme so the same
+ * registry works before and after the managed Redis is migrated off Upstash:
+ *   - `http(s)://` — Upstash REST API via `fetch` (the pipeline endpoint
+ *     applies both SET-with-EX commands atomically server-side).
+ *   - `redis(s)://` — native RESP over a TCP socket (e.g. a Railway Redis
+ *     public proxy). Auth is carried inline in the URL, so no separate token
+ *     is required. This mirrors what the gateways already do
+ *     (`gateway-discord` / `gateway-webhook` both speak native TCP Redis).
+ * Neither path adds a runtime dependency to the agent package (which is also
+ * bundled for mobile): REST uses `fetch`, TCP uses the `node:net` builtin.
+ */
+export interface SandboxRegistryConfig {
+    redisUrl: string;
+    /**
+     * Bearer token for the Upstash REST transport. Not required (and ignored)
+     * for a `redis://` / `rediss://` URL, which carries auth inline.
+     */
+    redisToken?: string;
+    agentId: string;
+    serverName: string;
+    serverUrl: string;
+    /**
+     * TTL for both Redis keys in seconds. Keep this at least 3x the heartbeat
+     * interval so one missed tick does not expire a healthy container.
+     */
+    ttlSeconds: number;
+}
+export declare class SandboxRegistry {
+    private readonly config;
+    private heartbeatTimer;
+    private readonly tcp;
+    constructor(config: SandboxRegistryConfig);
+    register(): Promise<void>;
+    refresh(): Promise<void>;
+    unregister(): Promise<void>;
+    startHeartbeat(intervalMs: number): void;
+    stopHeartbeat(): void;
+    /**
+     * Atomic two-key write. Both keys must succeed together — partial state
+     * would let gateways resolve `agent:X:server` to a stale `server:Y:url`
+     * value or miss a routing entry whose other half was just renewed. REST uses
+     * the Upstash pipeline endpoint; TCP pipelines both commands on one socket.
+     */
+    private writeKeys;
+    private get;
+    private command;
+    private pipeline;
+    /**
+     * Execute one or more commands over a native RESP/TCP connection and return
+     * the per-command replies (AUTH/SELECT preamble replies are stripped). One
+     * short-lived connection per call keeps the lifecycle trivial — the registry
+     * only writes twice per heartbeat (every 30s), so connection churn is
+     * negligible and there is no socket to leak if the container is killed.
+     */
+    private tcpExec;
+}
+/**
+ * Reads the SANDBOX_REGISTRY_* and SANDBOX_* env vars and returns a fully
+ * wired `SandboxRegistry`, or `null` if the sandbox context is not configured
+ * (e.g. local dev, non-Hetzner deployment). Caller must call `register()` and
+ * `startHeartbeat(...)` after a successful boot.
+ *
+ * This is the FEATURE FLAG for container self-registration: when the required
+ * env vars are absent (every non-provisioned runtime), this returns null and
+ * the runtime behaves exactly as before. Only a cloud-provisioned container
+ * carrying the full SANDBOX_REGISTRY_* set will register. A `redis://` URL
+ * needs no token (auth is inline); a `http(s)://` Upstash URL requires one.
+ */
+export declare function buildSandboxRegistryFromEnv(env?: NodeJS.ProcessEnv, ttlSeconds?: number): SandboxRegistry | null;
+//# sourceMappingURL=sandbox-registry.d.ts.map

package/runtime/sandbox-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-registry.d.ts","sourceRoot":"","sources":["../../src/runtime/sandbox-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAiBH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,eAAe;IAId,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHnC,OAAO,CAAC,cAAc,CAA+C;IACrE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAU;gBAED,MAAM,EAAE,qBAAqB;IAIpD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAOzB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBjC,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAmBxC,aAAa,IAAI,IAAI;IAOrB;;;;;OAKG;YACW,SAAS;YAST,GAAG;YAKH,OAAO;YAuBP,QAAQ;IA0BtB;;;;;;OAMG;YACW,OAAO;CA+DtB;AAuFD;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,UAAU,SAAK,GACd,eAAe,GAAG,IAAI,CA8BxB"}

package/runtime/sandbox-registry.js

@@ -0,0 +1,346 @@
+/**
+ * SandboxRegistry (agent runtime) — self-registers a cloud-provisioned
+ * container in the shared Redis so the multi-tenant gateways
+ * (`gateway-discord`, `gateway-webhook`) can resolve `agent_id -> server URL`
+ * and forward inbound platform messages to THIS container.
+ *
+ * WHY this lives in `packages/agent` (and duplicates the logic in
+ * `packages/app-core/src/services/sandbox-registry.ts`):
+ * The published cloud image runs `packages/agent/dist/bin.js` as its
+ * entrypoint (see `packages/app-core/deploy/Dockerfile.ci` APP_ENTRYPOINT).
+ * That entrypoint boots the agent runtime in `packages/agent/src/runtime/eliza.ts`,
+ * which CANNOT import `@elizaos/app-core` without creating an
+ * `agent -> app-core -> agent` workspace cycle. The app-core copy therefore
+ * never executes in a provisioned container. This is a deliberate, minimal
+ * backport scoped to the container self-registration seam (Path A). Keep the
+ * two copies in lock-step.
+ *
+ * It writes two Redis keys with a short TTL; a periodic heartbeat refreshes
+ * the TTL while the container is alive, and `unregister()` deletes them on
+ * graceful shutdown if they still point at this container. If the container
+ * crashes, the keys expire naturally and the gateways stop routing to a dead
+ * address.
+ *
+ *   server:<serverName>:url = <serverUrl>   (resolver address)
+ *   agent:<agentId>:server  = <serverName>  (agent -> server pointer)
+ *
+ * Two transports are supported, selected by the URL scheme so the same
+ * registry works before and after the managed Redis is migrated off Upstash:
+ *   - `http(s)://` — Upstash REST API via `fetch` (the pipeline endpoint
+ *     applies both SET-with-EX commands atomically server-side).
+ *   - `redis(s)://` — native RESP over a TCP socket (e.g. a Railway Redis
+ *     public proxy). Auth is carried inline in the URL, so no separate token
+ *     is required. This mirrors what the gateways already do
+ *     (`gateway-discord` / `gateway-webhook` both speak native TCP Redis).
+ * Neither path adds a runtime dependency to the agent package (which is also
+ * bundled for mobile): REST uses `fetch`, TCP uses the `node:net` builtin.
+ */
+import net from "node:net";
+import { logger } from "@elizaos/core";
+/** Hard cap on a single TCP register/refresh round-trip. */
+const REGISTRY_TCP_TIMEOUT_MS = 10_000;
+function formatErr(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function isTcpRedisUrl(url) {
+    return /^rediss?:\/\//i.test(url);
+}
+export class SandboxRegistry {
+    config;
+    heartbeatTimer = null;
+    tcp;
+    constructor(config) {
+        this.config = config;
+        this.tcp = isTcpRedisUrl(config.redisUrl);
+    }
+    async register() {
+        await this.writeKeys();
+        logger.info(`[sandbox-registry] Registered ${this.config.serverName} -> ${this.config.serverUrl} (agent ${this.config.agentId}, ttl ${this.config.ttlSeconds}s, transport ${this.tcp ? "tcp" : "rest"})`);
+    }
+    async refresh() {
+        await this.writeKeys();
+    }
+    async unregister() {
+        const { serverName, serverUrl, agentId } = this.config;
+        const serverUrlKey = `server:${serverName}:url`;
+        const agentServerKey = `agent:${agentId}:server`;
+        const [registeredUrl, registeredServer] = await Promise.all([
+            this.get(serverUrlKey),
+            this.get(agentServerKey),
+        ]);
+        const keysToDelete = [];
+        if (registeredUrl === serverUrl)
+            keysToDelete.push(serverUrlKey);
+        if (registeredServer === serverName)
+            keysToDelete.push(agentServerKey);
+        if (keysToDelete.length > 0) {
+            await this.command(["DEL", ...keysToDelete]);
+        }
+        logger.info(`[sandbox-registry] Unregistered ${serverName} (agent ${agentId})`);
+    }
+    startHeartbeat(intervalMs) {
+        if (this.heartbeatTimer)
+            return;
+        this.heartbeatTimer = setInterval(() => {
+            void this.refresh().catch((err) => {
+                logger.warn(`[sandbox-registry] Heartbeat refresh failed: ${formatErr(err)}`);
+            });
+        }, intervalMs);
+        if (typeof this.heartbeatTimer === "object" &&
+            "unref" in this.heartbeatTimer) {
+            this.heartbeatTimer.unref();
+        }
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    /**
+     * Atomic two-key write. Both keys must succeed together — partial state
+     * would let gateways resolve `agent:X:server` to a stale `server:Y:url`
+     * value or miss a routing entry whose other half was just renewed. REST uses
+     * the Upstash pipeline endpoint; TCP pipelines both commands on one socket.
+     */
+    async writeKeys() {
+        const { serverName, serverUrl, agentId, ttlSeconds } = this.config;
+        const ttl = String(ttlSeconds);
+        await this.pipeline([
+            ["SET", `server:${serverName}:url`, serverUrl, "EX", ttl],
+            ["SET", `agent:${agentId}:server`, serverName, "EX", ttl],
+        ]);
+    }
+    async get(key) {
+        const result = await this.command(["GET", key]);
+        return typeof result === "string" ? result : null;
+    }
+    async command(args) {
+        if (this.tcp) {
+            const [reply] = await this.tcpExec([args]);
+            return reply;
+        }
+        const res = await fetch(this.config.redisUrl, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.config.redisToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(args),
+        });
+        if (!res.ok) {
+            throw new Error(`Upstash command failed: ${res.status} ${await res.text()}`);
+        }
+        const json = (await res.json());
+        if (json.error)
+            throw new Error(`Upstash error: ${json.error}`);
+        return json.result;
+    }
+    async pipeline(commands) {
+        if (this.tcp) {
+            await this.tcpExec(commands);
+            return;
+        }
+        const res = await fetch(`${this.config.redisUrl}/pipeline`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.config.redisToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(commands),
+        });
+        if (!res.ok) {
+            throw new Error(`Upstash pipeline failed: ${res.status} ${await res.text()}`);
+        }
+        const json = (await res.json());
+        if (Array.isArray(json)) {
+            for (const entry of json) {
+                if (entry?.error)
+                    throw new Error(`Upstash error: ${entry.error}`);
+            }
+        }
+    }
+    /**
+     * Execute one or more commands over a native RESP/TCP connection and return
+     * the per-command replies (AUTH/SELECT preamble replies are stripped). One
+     * short-lived connection per call keeps the lifecycle trivial — the registry
+     * only writes twice per heartbeat (every 30s), so connection churn is
+     * negligible and there is no socket to leak if the container is killed.
+     */
+    async tcpExec(commands) {
+        const url = new URL(this.config.redisUrl);
+        const secure = url.protocol === "rediss:";
+        const host = url.hostname;
+        const port = url.port ? Number(url.port) : 6379;
+        const username = decodeURIComponent(url.username || "");
+        const password = decodeURIComponent(url.password || "");
+        const db = url.pathname.length > 1 ? url.pathname.slice(1) : "";
+        const preamble = [];
+        if (password) {
+            // Redis 6+ ACL AUTH takes an optional username; the default user accepts
+            // the single-arg form too. Send the username only when it is explicit.
+            preamble.push(username ? ["AUTH", username, password] : ["AUTH", password]);
+        }
+        if (db)
+            preamble.push(["SELECT", db]);
+        const all = [...preamble, ...commands];
+        // `node:tls` is imported lazily (only for `rediss://`) so the mobile
+        // bundle — which never reaches the TCP path — stays free of it.
+        const socket = secure
+            ? (await import("node:tls")).connect({ host, port, servername: host })
+            : net.connect({ host, port });
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let buffer = Buffer.alloc(0);
+            const finish = (err, replies) => {
+                if (settled)
+                    return;
+                settled = true;
+                socket.destroy();
+                if (err)
+                    reject(err);
+                else
+                    resolve(replies ?? []);
+            };
+            socket.setTimeout(REGISTRY_TCP_TIMEOUT_MS, () => finish(new Error("Redis TCP timeout")));
+            socket.on("error", (err) => finish(err));
+            const onConnect = () => {
+                socket.write(encodeRespCommands(all));
+            };
+            socket.once(secure ? "secureConnect" : "connect", onConnect);
+            socket.on("data", (chunk) => {
+                buffer = Buffer.concat([buffer, chunk]);
+                const parsed = parseRespReplies(buffer, all.length);
+                if (!parsed)
+                    return; // need more bytes
+                const firstErr = parsed.replies.find((r) => r instanceof RespError);
+                if (firstErr) {
+                    finish(new Error(`Redis error: ${firstErr.message}`));
+                    return;
+                }
+                // Strip the AUTH/SELECT preamble replies; return only command results.
+                finish(null, parsed.replies.slice(preamble.length));
+            });
+        });
+    }
+}
+/** A RESP `-ERR ...` reply, kept distinct so callers can detect failures. */
+class RespError {
+    message;
+    constructor(message) {
+        this.message = message;
+    }
+}
+/** Encode commands as a single RESP2 buffer (inline pipelining). */
+function encodeRespCommands(commands) {
+    const parts = [];
+    for (const args of commands) {
+        parts.push(Buffer.from(`*${args.length}\r\n`));
+        for (const arg of args) {
+            const bytes = Buffer.from(arg);
+            parts.push(Buffer.from(`$${bytes.length}\r\n`));
+            parts.push(bytes);
+            parts.push(Buffer.from("\r\n"));
+        }
+    }
+    return Buffer.concat(parts);
+}
+/**
+ * Parse exactly `expected` top-level RESP replies from `buffer`. Returns the
+ * replies (with `-ERR` mapped to {@link RespError}) once all are present, or
+ * `null` when more bytes are still needed. Supports the reply types Redis
+ * returns for SET/GET/DEL/AUTH/SELECT: simple string, error, integer, bulk
+ * string (and null bulk), plus RESP3 null.
+ */
+function parseRespReplies(buffer, expected) {
+    const replies = [];
+    let offset = 0;
+    const parseOne = () => {
+        if (offset >= buffer.length)
+            return null;
+        const type = buffer[offset];
+        const lineEnd = buffer.indexOf("\r\n", offset);
+        if (lineEnd === -1)
+            return null;
+        const line = buffer.toString("utf8", offset + 1, lineEnd);
+        const afterLine = lineEnd + 2;
+        switch (type) {
+            case 0x2b: // '+' simple string
+                return { value: line, next: afterLine };
+            case 0x2d: // '-' error
+                return { value: new RespError(line), next: afterLine };
+            case 0x3a: // ':' integer
+                return { value: Number(line), next: afterLine };
+            case 0x5f: // '_' RESP3 null
+                return { value: null, next: afterLine };
+            case 0x24: {
+                // '$' bulk string
+                const len = Number(line);
+                if (len === -1)
+                    return { value: null, next: afterLine };
+                const end = afterLine + len;
+                if (buffer.length < end + 2)
+                    return null; // bulk + trailing CRLF
+                return {
+                    value: buffer.toString("utf8", afterLine, end),
+                    next: end + 2,
+                };
+            }
+            default:
+                // Unexpected/array reply — not produced by the registry's commands.
+                return {
+                    value: new RespError(`unsupported RESP type ${String.fromCharCode(type)}`),
+                    next: afterLine,
+                };
+        }
+    };
+    while (replies.length < expected) {
+        const savedOffset = offset;
+        const one = parseOne();
+        if (!one) {
+            offset = savedOffset;
+            return null;
+        }
+        replies.push(one.value);
+        offset = one.next;
+    }
+    return { replies };
+}
+/**
+ * Reads the SANDBOX_REGISTRY_* and SANDBOX_* env vars and returns a fully
+ * wired `SandboxRegistry`, or `null` if the sandbox context is not configured
+ * (e.g. local dev, non-Hetzner deployment). Caller must call `register()` and
+ * `startHeartbeat(...)` after a successful boot.
+ *
+ * This is the FEATURE FLAG for container self-registration: when the required
+ * env vars are absent (every non-provisioned runtime), this returns null and
+ * the runtime behaves exactly as before. Only a cloud-provisioned container
+ * carrying the full SANDBOX_REGISTRY_* set will register. A `redis://` URL
+ * needs no token (auth is inline); a `http(s)://` Upstash URL requires one.
+ */
+export function buildSandboxRegistryFromEnv(env = process.env, ttlSeconds = 90) {
+    const redisUrl = env.SANDBOX_REGISTRY_REDIS_URL?.trim();
+    const redisToken = env.SANDBOX_REGISTRY_REDIS_TOKEN?.trim();
+    // The routing key MUST be the platform character_id (SANDBOX_ROUTE_AGENT_ID)
+    // so it matches what the gateways resolve. Fall back to the sandbox id only
+    // when the route id is not injected (older provisioner).
+    const agentId = env.SANDBOX_ROUTE_AGENT_ID?.trim() || env.SANDBOX_AGENT_ID?.trim();
+    const serverName = env.SANDBOX_SERVER_NAME?.trim();
+    const serverUrl = env.SANDBOX_PUBLIC_URL?.trim();
+    const tcp = !!redisUrl && isTcpRedisUrl(redisUrl);
+    if (!redisUrl ||
+        (!tcp && !redisToken) ||
+        !agentId ||
+        !serverName ||
+        !serverUrl) {
+        return null;
+    }
+    return new SandboxRegistry({
+        redisUrl,
+        redisToken,
+        agentId,
+        serverName,
+        serverUrl,
+        ttlSeconds,
+    });
+}