@agenthippo-ai/agenthippo 0.2.3-dataplane → 1.110.9

package/out/gateway/bridge.js

@@ -6,9 +6,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GatewayBridge = void 0;
+exports.GatewayBridge = exports.MAX_GATEWAY_ID_CHARS = void 0;
 exports.isIdeThreadCompositeRouteKey = isIdeThreadCompositeRouteKey;
 exports.parseIdeThreadIdFromCompositeRouteKey = parseIdeThreadIdFromCompositeRouteKey;
+exports.findOversizedRunField = findOversizedRunField;
 exports.buildIdeSessionRouteKey = buildIdeSessionRouteKey;
 exports.extractRouteLabelFromGatewaySessionKey = extractRouteLabelFromGatewaySessionKey;
 exports.looksLikeGatewayChannelRouteKey = looksLikeGatewayChannelRouteKey;
@@ -52,6 +53,29 @@ function parseIdeThreadIdFromCompositeRouteKey(routeKey) {
     const id = routeKey.slice(idx + IDE_THREAD_ROUTE_MARKER.length).trim();
     return id.length > 0 ? id : undefined;
 }
+/** Max length for gateway-supplied identifiers that become filenames or route-index keys. */
+exports.MAX_GATEWAY_ID_CHARS = 512;
+const BOUNDED_RUN_FIELDS = [
+    "agentId", "sessionKey", "sessionId", "channel", "accountId",
+    "target", "threadId", "groupId", "senderUsername", "senderName", "senderId",
+];
+/**
+ * Name the first `agent.run` identifier that is present but not a sane bounded string.
+ * Returns undefined when every field is absent or valid.
+ */
+function findOversizedRunField(params) {
+    const record = params;
+    for (const field of BOUNDED_RUN_FIELDS) {
+        const value = record[field];
+        if (value === undefined || value === null) {
+            continue;
+        }
+        if (typeof value !== "string" || value.length > exports.MAX_GATEWAY_ID_CHARS) {
+            return field;
+        }
+    }
+    return undefined;
+}
 function buildIdeSessionRouteKey(sessionKey, sessionId) {
     const sk = sessionKey?.trim();
     const sid = sessionId?.trim();
@@ -409,10 +433,24 @@ class GatewayBridge extends events_1.EventEmitter {
      */
     async handleAgentRun(frame) {
         const params = frame.params;
-        if (!params?.message) {
+        if (!params?.message || typeof params.message !== "string") {
             this.client.respond(frame.id, undefined, false, { code: "INVALID_PARAMS", message: "message is required" });
             return;
         }
+        if (params.message.length > client_js_1.MAX_GATEWAY_MESSAGE_CHARS) {
+            this.client.respond(frame.id, undefined, false, {
+                code: "MESSAGE_TOO_LARGE",
+                message: `message exceeds ${client_js_1.MAX_GATEWAY_MESSAGE_CHARS} characters`,
+            });
+            return;
+        }
+        // These land in filenames, route-index keys and JSON stores. An over-long or non-string
+        // value from the gateway is rejected here rather than truncated downstream.
+        const oversizedField = findOversizedRunField(params);
+        if (oversizedField) {
+            this.client.respond(frame.id, undefined, false, { code: "INVALID_PARAMS", message: `${oversizedField} is not a valid string` });
+            return;
+        }
         const agentId = params.agentId || this.getDefaultAgentId();
         if (!agentId) {
             this.client.respond(frame.id, undefined, false, { code: "NO_AGENT", message: "No agent available" });

package/out/gateway/client.js

@@ -3,7 +3,7 @@
  *  Copyright (c) AgentHippo.ai. All rights reserved.
  *--------------------------------------------------------------------------------------------*/
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GatewayClient = void 0;
+exports.GatewayClient = exports.MAX_GATEWAY_MESSAGE_CHARS = exports.MAX_GATEWAY_FRAME_BYTES = void 0;
 exports.createAgentIDEGatewayClient = createAgentIDEGatewayClient;
 exports.createEphemeralGatewayClient = createEphemeralGatewayClient;
 /* eslint-disable local/code-no-unexternalized-strings */
@@ -15,6 +15,27 @@ exports.createEphemeralGatewayClient = createEphemeralGatewayClient;
  */
 const events_1 = require("events");
 const protocol_js_1 = require("./protocol.js");
+/**
+ * Largest inbound frame we will parse. Without a bound here a hostile or wedged gateway can OOM
+ * the extension host by streaming one unbounded frame into `JSON.parse`.
+ *
+ * This does NOT limit attachment size. Images, PDFs and other media travel as REFERENCES —
+ * `MediaAttachment.url` / `.path` pointing at gateway-side storage (e.g. `~/.openclaw/media/`) —
+ * so a 50 MB PDF adds a few hundred bytes to the frame, not 50 MB. The cap therefore only bounds
+ * the JSON control frame, and is set well above any legitimate one so that a real message is
+ * never dropped (a channel like Slack caps messages at ~40k characters).
+ *
+ * Overridable for operators who front the gateway with something unusual; values below 1 MiB are
+ * ignored so a typo cannot silently break normal traffic.
+ */
+exports.MAX_GATEWAY_FRAME_BYTES = (() => {
+    const configured = Number(process.env.AGENTHIPPO_GATEWAY_MAX_FRAME_BYTES);
+    return Number.isFinite(configured) && configured >= 1024 * 1024
+        ? configured
+        : 16 * 1024 * 1024;
+})();
+/** Largest inbound `agent.run` message we hand to an engine, in characters. */
+exports.MAX_GATEWAY_MESSAGE_CHARS = 256 * 1024;
 function formatWebSocketCloseDetails(ev) {
     if (!ev) {
         return "WebSocket closed";
@@ -157,6 +178,18 @@ class GatewayClient extends events_1.EventEmitter {
         this.ws.send(JSON.stringify(frame));
     }
     handleMessage(data) {
+        // Bound before parsing — an oversized frame is dropped, never buffered into an object.
+        const byteLength = typeof data === "string"
+            ? Buffer.byteLength(data, "utf8")
+            : 0;
+        if (byteLength > exports.MAX_GATEWAY_FRAME_BYTES) {
+            // Loud, not silent: to a channel user a dropped frame looks like the agent ignoring
+            // them, so name the limit and the override rather than failing quietly.
+            this.emit("error", new Error(`Gateway frame of ${byteLength} bytes exceeds the ${exports.MAX_GATEWAY_FRAME_BYTES}-byte limit and was dropped. ` +
+                `Attachments normally travel as references, so this suggests inline payloads; ` +
+                `raise AGENTHIPPO_GATEWAY_MAX_FRAME_BYTES if this traffic is expected.`));
+            return;
+        }
         let frame;
         try {
             frame = JSON.parse(data);

package/out/gateway/installSource.js

@@ -0,0 +1,68 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) AgentHippo.ai. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANYWHERE_INSTALL_SOURCE_FORMS = exports.ANYWHERE_CONFIG_TEMPLATE_ENV = exports.ANYWHERE_SETUP_SCRIPT_ENV = exports.ANYWHERE_INSTALL_SOURCE_ENV = void 0;
+exports.validateAnywhereInstallSource = validateAnywhereInstallSource;
+/**
+ * Validation for `agentide.anywhere.installSource`, kept in its own module (no `vscode` import) so
+ * the rule can be tested directly rather than through the extension host.
+ */
+/**
+ * Environment variable carrying the install source into the setup terminal.
+ *
+ * The value is never interpolated into the command STRING. `"$AH_INSTALL_SOURCE"` (POSIX) and
+ * `$env:AH_INSTALL_SOURCE` (PowerShell) expand to one argument after the shell has finished
+ * parsing, so no character in the value can become syntax — which is the property the old
+ * blocklist (`[;`|$&\n\r]`, missing the double quote) failed to deliver.
+ */
+exports.ANYWHERE_INSTALL_SOURCE_ENV = 'AH_INSTALL_SOURCE';
+/** Same treatment for the two bundled paths we pass alongside it. */
+exports.ANYWHERE_SETUP_SCRIPT_ENV = 'AH_SETUP_SCRIPT';
+exports.ANYWHERE_CONFIG_TEMPLATE_ENV = 'AH_CONFIG_TEMPLATE';
+/**
+ * Strict allowlist for `agentide.anywhere.installSource`.
+ *
+ * This value names a package that is installed globally and whose `postinstall` script runs with
+ * the user's privileges, so it is a code-execution setting, not a string. The setting is declared
+ * `"scope": "application"` so a workspace cannot set it at all; this is the second gate, and it is
+ * an ALLOWLIST rather than a character blocklist — a blocklist has to be right about every shell
+ * metacharacter forever, and the previous one already missed `"`, which was enough to escape
+ * `--source "${installSource}"` and run arbitrary commands in the user's setup terminal.
+ *
+ * Accepted shapes, and nothing else:
+ *  - npm specifier: `pkg`, `pkg@1.2.3`, `pkg@latest`, `pkg@^1.2.3`, `@scope/pkg@2026.7.28`
+ *  - `github:owner/repo` optionally `#ref`
+ *  - an https:// URL ending in a tarball extension (a pinned artifact)
+ *  - an absolute or explicitly-relative local path (a developer's clone)
+ */
+const NPM_SPECIFIER = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(?:@[a-zA-Z0-9^~*><=][a-zA-Z0-9.^~*+><=|_-]*)?$/;
+const GITHUB_SPECIFIER = /^github:[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*(?:#[A-Za-z0-9._/-]+)?$/;
+const TARBALL_URL = /^https:\/\/[A-Za-z0-9._-]+(?::\d+)?\/[A-Za-z0-9._~!$'()*+,;=:@%/-]*\.(?:tgz|tar\.gz)$/;
+const POSIX_PATH = /^(?:\.{1,2})?\/[^\0<>"'`;|&$\n\r]*$/;
+const WINDOWS_PATH = /^[A-Za-z]:[\\/][^\0<>"'`;|&$\n\r]*$/;
+/** Named in every refusal so the message tells the user what they CAN write. */
+exports.ANYWHERE_INSTALL_SOURCE_FORMS = 'accepted forms are: an npm specifier (e.g. @agenthippo-ai/hippoclaw@2026.7.28), ' +
+    'github:owner/repo[#ref], an https:// .tgz/.tar.gz URL, or a local path';
+function validateAnywhereInstallSource(source) {
+    const refuse = (why) => ({
+        ok: false,
+        reason: `${why} — ${exports.ANYWHERE_INSTALL_SOURCE_FORMS}`,
+    });
+    const value = source.trim();
+    if (!value) {
+        return refuse('it is empty');
+    }
+    if (value !== source) {
+        return refuse('it has leading or trailing whitespace');
+    }
+    if (NPM_SPECIFIER.test(value) ||
+        GITHUB_SPECIFIER.test(value) ||
+        TARBALL_URL.test(value) ||
+        POSIX_PATH.test(value) ||
+        WINDOWS_PATH.test(value)) {
+        return { ok: true };
+    }
+    return refuse('it is not one of the accepted forms');
+}

package/out/gateway/lifecycle.js

@@ -36,7 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GatewayLifecycleManager = exports.AGENT_ANYWHERE_LABEL = void 0;
+exports.GatewayLifecycleManager = exports.validateAnywhereInstallSource = exports.ANYWHERE_SETUP_SCRIPT_ENV = exports.ANYWHERE_INSTALL_SOURCE_ENV = exports.ANYWHERE_CONFIG_TEMPLATE_ENV = exports.AGENT_ANYWHERE_LABEL = void 0;
 exports.detectGateway = detectGateway;
 /* eslint-disable local/code-no-unexternalized-strings */
 /**
@@ -57,9 +57,11 @@ const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const index_1 = require("../utils/index");
 const agentEnvFile_js_1 = require("../utils/agentEnvFile.js");
+const secretsPreflight_js_1 = require("./secretsPreflight.js");
 const windowsCommandLine_js_1 = require("../utils/windowsCommandLine.js");
 const gateway_scope_errors_js_1 = require("./gateway-scope-errors.js");
 const openclaw_channel_routing_js_1 = require("./openclaw-channel-routing.js");
+const branding_js_1 = require("../branding.js");
 const execAsync = (0, util_1.promisify)(child_process_1.exec);
 const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
 const IS_WINDOWS = process.platform === "win32";
@@ -228,6 +230,7 @@ const STALE_GATEWAY_LOCK_MIN_AGE_MS = 30_000;
 /** PID file for fast status checks (~1-2ms vs 100ms+ for shell commands) */
 const GATEWAY_PID_FILE = index_1.PID_FILES.gateway();
 const FORK_CLI_NAME = "hippoclaw";
+const GATEWAY_NPM_PACKAGE_DIRS = ["@agenthippo-ai/hippoclaw", "openclaw"];
 const MANAGED_GATEWAY_STATE_DIR = path.join(os.homedir(), ".agenthippo", "gateway");
 const MANAGED_GATEWAY_MANIFEST_PATH = path.join(MANAGED_GATEWAY_STATE_DIR, "install.json");
 const GATEWAY_INSTALL_STATUS_FILE = path.join(MANAGED_GATEWAY_STATE_DIR, "install-status.json");
@@ -239,6 +242,11 @@ const MANAGED_OPENCLAW_WRAPPER_PATH = path.join(MANAGED_GATEWAY_WRAPPER_DIR, IS_
 const MANAGED_GATEWAY_WRAPPER_MARKER = IS_WINDOWS
     ? "REM Managed by Agent Anywhere"
     : "# Managed by Agent Anywhere";
+const installSource_js_1 = require("./installSource.js");
+Object.defineProperty(exports, "ANYWHERE_CONFIG_TEMPLATE_ENV", { enumerable: true, get: function () { return installSource_js_1.ANYWHERE_CONFIG_TEMPLATE_ENV; } });
+Object.defineProperty(exports, "ANYWHERE_INSTALL_SOURCE_ENV", { enumerable: true, get: function () { return installSource_js_1.ANYWHERE_INSTALL_SOURCE_ENV; } });
+Object.defineProperty(exports, "ANYWHERE_SETUP_SCRIPT_ENV", { enumerable: true, get: function () { return installSource_js_1.ANYWHERE_SETUP_SCRIPT_ENV; } });
+Object.defineProperty(exports, "validateAnywhereInstallSource", { enumerable: true, get: function () { return installSource_js_1.validateAnywhereInstallSource; } });
 function installSourceNeedsBuild(source) {
     if (!source) {
         return false;
@@ -495,6 +503,11 @@ function addManagedOpenclawRoot(roots, candidate) {
         roots.add(candidate);
     }
 }
+function addManagedGatewayPackageRoots(roots, nodeModulesDir) {
+    for (const pkgDir of GATEWAY_NPM_PACKAGE_DIRS) {
+        addManagedOpenclawRoot(roots, path.join(nodeModulesDir, pkgDir));
+    }
+}
 /** Scan nvm version dirs when `npm root -g` is unavailable in the extension host PATH. */
 function collectNvmOpenclawPackageRoots() {
     const home = os.homedir();
@@ -509,7 +522,7 @@ function collectNvmOpenclawPackageRoots() {
             if (!entry.isDirectory()) {
                 continue;
             }
-            candidates.push(path.join(versionsDir, entry.name, "lib", "node_modules", "openclaw"));
+            candidates.push(...GATEWAY_NPM_PACKAGE_DIRS.map((pkgDir) => path.join(versionsDir, entry.name, "lib", "node_modules", pkgDir)));
         }
     }
     catch {
@@ -533,15 +546,17 @@ async function getManagedOpenclawRoots() {
                     continue;
                 }
                 // Windows npm uses node_modules/ directly (no lib/ prefix); Unix uses lib/node_modules/
-                const candidate = path.join(bootstrapNodeRoot, entry.name, ...(IS_WINDOWS ? ["node_modules"] : ["lib", "node_modules"]), "openclaw");
-                if (!fs.existsSync(candidate)) {
-                    continue;
-                }
-                try {
-                    roots.add(fs.realpathSync(candidate));
-                }
-                catch {
-                    roots.add(candidate);
+                for (const pkgDir of GATEWAY_NPM_PACKAGE_DIRS) {
+                    const candidate = path.join(bootstrapNodeRoot, entry.name, ...(IS_WINDOWS ? ["node_modules"] : ["lib", "node_modules"]), pkgDir);
+                    if (!fs.existsSync(candidate)) {
+                        continue;
+                    }
+                    try {
+                        roots.add(fs.realpathSync(candidate));
+                    }
+                    catch {
+                        roots.add(candidate);
+                    }
                 }
             }
         }
@@ -550,8 +565,7 @@ async function getManagedOpenclawRoots() {
         }
     }
     // Windows npm uses node_modules/ directly (no lib/ prefix); Unix uses lib/node_modules/
-    const legacyManaged = path.join(os.homedir(), ".npm-global", ...(IS_WINDOWS ? ["node_modules"] : ["lib", "node_modules"]), "openclaw");
-    addManagedOpenclawRoot(roots, legacyManaged);
+    addManagedGatewayPackageRoots(roots, path.join(os.homedir(), ".npm-global", ...(IS_WINDOWS ? ["node_modules"] : ["lib", "node_modules"])));
     for (const nvmManaged of collectNvmOpenclawPackageRoots()) {
         addManagedOpenclawRoot(roots, nvmManaged);
     }
@@ -559,7 +573,7 @@ async function getManagedOpenclawRoots() {
         const { stdout } = await execAsync("npm root -g", { timeout: 3_000 });
         const npmRoot = stdout.trim();
         if (npmRoot) {
-            addManagedOpenclawRoot(roots, path.join(npmRoot, "openclaw"));
+            addManagedGatewayPackageRoots(roots, npmRoot);
         }
     }
     catch {
@@ -1141,7 +1155,7 @@ class GatewayLifecycleManager {
         // Auto-start if configured and installed
         const autoStart = this.getConfig("autoStart", false);
         if (autoStart && this._lastDetection?.installed && !this._lastDetection?.running) {
-            this.log("Auto-starting gateway (agentide.anywhere.autoStart = true)");
+            this.log(`Auto-starting gateway (${(0, branding_js_1.toSettingsDisplayKey)("agentide.anywhere.autoStart")} = true)`);
             await this.start();
         }
     }
@@ -1763,15 +1777,18 @@ class GatewayLifecycleManager {
         const installSource = this.getConfig("installSource", "");
         const port = this.getGatewayPort();
         if (!installSource) {
-            vscode.window.showErrorMessage(`${exports.AGENT_ANYWHERE_LABEL}: Install source not configured. Set "agentide.anywhere.installSource" in settings.`);
+            vscode.window.showErrorMessage(`${exports.AGENT_ANYWHERE_LABEL}: Install source not configured. Set "${(0, branding_js_1.toSettingsDisplayKey)("agentide.anywhere.installSource")}" in settings.`);
             return false;
         }
-        // Security: validate installSource to prevent command injection.
-        // Allowed: npm package names, scoped packages, git repos, local paths, version specifiers.
-        // Reject: semicolons, backticks, pipes, $(), &&, ||, newlines, etc.
-        if (/[;`|$&\n\r]/.test(installSource) || /\$\(/.test(installSource)) {
-            vscode.window.showErrorMessage(`${exports.AGENT_ANYWHERE_LABEL}: Invalid install source - contains disallowed characters. Check "agentide.anywhere.installSource" in settings.`);
-            this.log(`Rejected installSource due to suspicious characters: ${installSource}`);
+        // Security: this value names a package that is installed globally and whose postinstall
+        // script runs as the user. It is validated against an ALLOWLIST of specifier shapes (see
+        // validateAnywhereInstallSource) and then passed to the setup terminal through an
+        // environment variable rather than being interpolated into a command string.
+        const sourceCheck = (0, installSource_js_1.validateAnywhereInstallSource)(installSource);
+        if (!sourceCheck.ok) {
+            vscode.window.showErrorMessage(`${exports.AGENT_ANYWHERE_LABEL}: Refusing to install from "${installSource}" — ${sourceCheck.reason}. ` +
+                `Fix "${(0, branding_js_1.toSettingsDisplayKey)("agentide.anywhere.installSource")}" in your user settings.`);
+            this.log(`Rejected installSource (${sourceCheck.reason}): ${installSource}`);
             return false;
         }
         if (this._gatewayInstallInProgress) {
@@ -1816,46 +1833,77 @@ class GatewayLifecycleManager {
             ];
             const templatePath = templateCandidates.find((p) => fs.existsSync(p));
             let terminalOptions;
+            // NOTE ON WHY THIS IS NOT execFile/spawn WITH AN ARGV ARRAY.
+            // The setup runs in a VISIBLE terminal (the user watches npm/git progress and answers
+            // prompts), and it must run under a LOGIN shell: node/npm/pnpm on macOS commonly live on
+            // a PATH built by ~/.zprofile, and `getAnywhereSetupShellArgs` uses `-lic`/`-lc` for
+            // exactly that reason. A bare argv exec would break every nvm/volta install.
+            // So the shell stays — but no untrusted value is ever spliced into the command text.
+            // `installSource` (and the two bundled paths) travel in the terminal's ENVIRONMENT and
+            // are referenced as `"$VAR"` / `$env:VAR`, which the shell expands AFTER parsing: the
+            // value becomes exactly one argument and none of its characters can become syntax.
+            const setupEnv = {
+                ...anywhereSetupTerminalEnv(),
+                [installSource_js_1.ANYWHERE_INSTALL_SOURCE_ENV]: installSource,
+                ...(scriptPath ? { [installSource_js_1.ANYWHERE_SETUP_SCRIPT_ENV]: scriptPath } : {}),
+                ...(templatePath ? { [installSource_js_1.ANYWHERE_CONFIG_TEMPLATE_ENV]: templatePath } : {}),
+            };
             if (scriptPath && IS_WINDOWS) {
                 // Windows: run PowerShell script
-                const args = [`-Source "${installSource}"`];
+                const args = [`-Source $env:${installSource_js_1.ANYWHERE_INSTALL_SOURCE_ENV}`];
                 if (templatePath) {
-                    args.push(`-ConfigTemplate "${templatePath}"`);
+                    args.push(`-ConfigTemplate $env:${installSource_js_1.ANYWHERE_CONFIG_TEMPLATE_ENV}`);
                 }
-                const psCmd = `& "${scriptPath}" ${args.join(" ")}; Write-Host ""; Write-Host "You can close this window."`;
+                const psCmd = `& $env:${installSource_js_1.ANYWHERE_SETUP_SCRIPT_ENV} ${args.join(" ")}; Write-Host ""; Write-Host "You can close this window."`;
                 terminalOptions = {
                     name: AGENT_ANYWHERE_SETUP_TERMINAL,
                     shellPath: "powershell.exe",
                     shellArgs: ["-NoProfile", "-NoExit", "-ExecutionPolicy", "Bypass", "-Command", psCmd],
+                    env: {
+                        [installSource_js_1.ANYWHERE_INSTALL_SOURCE_ENV]: installSource,
+                        [installSource_js_1.ANYWHERE_SETUP_SCRIPT_ENV]: scriptPath,
+                        ...(templatePath ? { [installSource_js_1.ANYWHERE_CONFIG_TEMPLATE_ENV]: templatePath } : {}),
+                    },
                 };
             }
             else if (scriptPath) {
                 // macOS/Linux: run bash script
-                const args = [`--source "${installSource}"`];
+                const args = [`--source "$${installSource_js_1.ANYWHERE_INSTALL_SOURCE_ENV}"`];
                 if (templatePath) {
-                    args.push(`--config-template "${templatePath}"`);
+                    args.push(`--config-template "$${installSource_js_1.ANYWHERE_CONFIG_TEMPLATE_ENV}"`);
                 }
-                const setupCmd = `bash "${scriptPath}" ${args.join(" ")}`;
+                const setupCmd = `bash "$${installSource_js_1.ANYWHERE_SETUP_SCRIPT_ENV}" ${args.join(" ")}`;
                 const holdOpenCmd = `${setupCmd}; echo ""; echo "Press Enter to close..."; read`;
                 terminalOptions = {
                     name: AGENT_ANYWHERE_SETUP_TERMINAL,
                     shellPath: getAnywhereSetupShellPath(),
                     shellArgs: getAnywhereSetupShellArgs(holdOpenCmd),
-                    env: anywhereSetupTerminalEnv(),
+                    env: setupEnv,
                 };
             }
             else {
                 // Fallback: raw npm install (script not bundled)
                 this.log("Setup script not found, falling back to npm install");
-                const fallbackCmd = `npm install -g ${installSource}`;
+                const fallbackCmd = `npm install -g "$${installSource_js_1.ANYWHERE_INSTALL_SOURCE_ENV}"`;
                 const holdOpenCmd = `${fallbackCmd}; echo ""; echo "Press Enter to close..."; read`;
                 terminalOptions = IS_WINDOWS
-                    ? { name: AGENT_ANYWHERE_SETUP_TERMINAL, shellPath: "cmd.exe", shellArgs: ["/c", `${fallbackCmd} && echo. && echo Setup complete. && pause`] }
+                    // cmd.exe is the one shell here that expands `%VAR%` DURING parsing rather than
+                    // after it, so the env indirection alone is not a boundary on Windows — the
+                    // allowlist above is what makes this safe (it admits no `&`, `|`, `^`, quote or
+                    // whitespace outside a path shape). Kept as cmd.exe because this fallback only
+                    // fires when the bundled setup script is missing, and PowerShell is not
+                    // guaranteed present on every Windows host we support.
+                    ? {
+                        name: AGENT_ANYWHERE_SETUP_TERMINAL,
+                        shellPath: "cmd.exe",
+                        shellArgs: ["/c", `npm install -g "%${installSource_js_1.ANYWHERE_INSTALL_SOURCE_ENV}%" && echo. && echo Setup complete. && pause`],
+                        env: { [installSource_js_1.ANYWHERE_INSTALL_SOURCE_ENV]: installSource },
+                    }
                     : {
                         name: AGENT_ANYWHERE_SETUP_TERMINAL,
                         shellPath: getAnywhereSetupShellPath(),
                         shellArgs: getAnywhereSetupShellArgs(holdOpenCmd),
-                        env: anywhereSetupTerminalEnv(),
+                        env: setupEnv,
                     };
             }
             // Run in a visible terminal so user can see progress
@@ -2119,6 +2167,93 @@ class GatewayLifecycleManager {
         const doc = await vscode.workspace.openTextDocument(this.configPath);
         await vscode.window.showTextDocument(doc);
     }
+    /**
+     * Check that every enabled channel's env-sourced secrets resolve before spawning the
+     * gateway. On missing secrets, offer to disable the affected channels (config is backed
+     * up first) or to open ~/.agent-hippo/.env with the missing keys stubbed in.
+     *
+     * Configs that are not strict JSON (OpenClaw accepts JSON5 with comments) are left to
+     * the gateway itself: rewriting them would destroy comments, and the fail-fast exit
+     * detection in doStart still surfaces the error promptly.
+     */
+    async preflightChannelSecrets(gatewayEnv) {
+        let content;
+        try {
+            content = fs.readFileSync(this.configPath, "utf-8");
+        }
+        catch {
+            return "continue"; // No config yet — nothing to resolve.
+        }
+        const config = (0, secretsPreflight_js_1.parseStrictJsonConfig)(content);
+        if (config === undefined) {
+            return "continue";
+        }
+        const missing = (0, secretsPreflight_js_1.collectMissingChannelEnvSecrets)(config, gatewayEnv);
+        if (missing.length === 0) {
+            return "continue";
+        }
+        const envFilePath = (0, agentEnvFile_js_1.getAgentHomeEnvFilePath)();
+        const channelNames = missing.map((m) => m.channel).join(", ");
+        const varNames = [...new Set(missing.flatMap((m) => m.envVars))];
+        this.log(`Channel secrets preflight: ${channelNames} missing ${varNames.join(", ")}`);
+        const disableAndStart = `Disable ${channelNames} & Start`;
+        const addSecrets = "Add Secrets";
+        const choice = await vscode.window.showErrorMessage(`${exports.AGENT_ANYWHERE_LABEL}: The ${channelNames} channel needs ${varNames.join(", ")}, which ${varNames.length === 1 ? "is" : "are"} not set in ${envFilePath} or the IDE environment. Add the secret${varNames.length === 1 ? "" : "s"} or disable the channel to start the gateway.`, disableAndStart, addSecrets);
+        if (choice === disableAndStart) {
+            const updated = (0, secretsPreflight_js_1.disableChannelsInConfigText)(content, missing.map((m) => m.channel));
+            if (!updated) {
+                void vscode.window.showErrorMessage(`${exports.AGENT_ANYWHERE_LABEL}: Could not update ${this.configPath}. Set "enabled": false on the ${channelNames} channel manually, then start again.`);
+                return "abort";
+            }
+            const backupPath = `${this.configPath}.bak-missing-secrets`;
+            try {
+                fs.copyFileSync(this.configPath, backupPath);
+                fs.writeFileSync(this.configPath, updated, { encoding: "utf-8", mode: IS_WINDOWS ? undefined : 0o600 });
+            }
+            catch (err) {
+                const detail = err instanceof Error ? err.message : String(err);
+                void vscode.window.showErrorMessage(`${exports.AGENT_ANYWHERE_LABEL}: Could not update ${this.configPath} (${detail}).`);
+                return "abort";
+            }
+            this.log(`Disabled channels missing secrets: ${channelNames} (backup: ${backupPath})`);
+            void vscode.window.showInformationMessage(`${exports.AGENT_ANYWHERE_LABEL}: Disabled the ${channelNames} channel (backup: ${path.basename(backupPath)}). To re-enable: add ${varNames.join(", ")} to ${envFilePath}, set "enabled": true in the config, then restart the gateway.`);
+            return "continue";
+        }
+        if (choice === addSecrets) {
+            await this.openEnvFileWithSecretStubs(envFilePath, varNames);
+        }
+        return "abort";
+    }
+    /** Append stub lines for missing secret keys to ~/.agent-hippo/.env and open it. */
+    async openEnvFileWithSecretStubs(envFilePath, keys) {
+        try {
+            let content = "";
+            try {
+                content = fs.readFileSync(envFilePath, "utf-8");
+            }
+            catch {
+                // New file.
+            }
+            const toAdd = keys.filter((key) => !new RegExp(`^\\s*#?\\s*${key}=`, "m").test(content));
+            if (toAdd.length) {
+                const separator = content.length && !content.endsWith("\n") ? "\n" : "";
+                const block = [
+                    `# Added by ${exports.AGENT_ANYWHERE_LABEL} — fill in, then start the gateway again.`,
+                    ...toAdd.map((key) => `${key}=`),
+                ].join("\n");
+                fs.writeFileSync(envFilePath, `${content}${separator}${block}\n`, {
+                    encoding: "utf-8",
+                    mode: IS_WINDOWS ? undefined : 0o600,
+                });
+            }
+            const doc = await vscode.workspace.openTextDocument(vscode.Uri.file(envFilePath));
+            await vscode.window.showTextDocument(doc, { preview: false });
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            void vscode.window.showErrorMessage(`${exports.AGENT_ANYWHERE_LABEL}: Could not open ${envFilePath} (${detail}).`);
+        }
+    }
     async startGatewayViaHiddenWindowsProcess(spawnExe, spawnArgs, logPath, errorLogPath, gatewayEnv) {
         const argumentLine = (0, windowsCommandLine_js_1.buildWindowsArgumentLine)(spawnArgs);
         const argumentClause = argumentLine.length > 0
@@ -2301,6 +2436,13 @@ class GatewayLifecycleManager {
                 this.log(`Gateway env: ${key} present for child process`);
             }
         }
+        // Channel secrets preflight: an enabled channel referencing an unset env var makes the
+        // gateway crash at startup (SecretRefResolutionError) with the reason buried in the log.
+        // Catch it here and offer a fix instead of spawning a process that cannot survive.
+        if ((await this.preflightChannelSecrets(gatewayEnv)) === "abort") {
+            this.setStatus("installed");
+            return;
+        }
         let startedPid;
         if (isWindowsLaunch) {
             startedPid = await this.startGatewayViaHiddenWindowsProcess(spawnExe, spawnArgs, logPath, errorLogPath, gatewayEnv);
@@ -2378,7 +2520,12 @@ class GatewayLifecycleManager {
                         processAlive &&
                         sawLaunchedProcessAlive &&
                         elapsed < startupTimeoutMs + launchGraceMs;
-                    if (trackingPid && sawLaunchedProcessAlive && !processAlive && !isWindowsLaunch) {
+                    // A gateway that crashes at boot (e.g. unresolvable secrets) can exit before
+                    // the first aliveness sample, so don't require sawLaunchedProcessAlive: on
+                    // Unix the exit handler nulling this.process is just as definitive. Without
+                    // this, an instant crash silently spins until the startup timeout.
+                    const launchedProcessGone = !processAlive && (sawLaunchedProcessAlive || this.process === null);
+                    if (trackingPid && launchedProcessGone && !isWindowsLaunch) {
                         this.setStatus("error");
                         this.log(`Gateway process exited before opening port ${port}`);
                         await showGatewayStartFailedToast(logPath);
@@ -2609,16 +2756,8 @@ class GatewayLifecycleManager {
                 encoding: "utf-8",
                 mode: IS_WINDOWS ? undefined : 0o600,
             });
+            // Application-scoped setting: user scope is the only writable target.
             const gwConfig = vscode.workspace.getConfiguration("agentide.gateway");
-            if (vscode.workspace.workspaceFolders && vscode.workspace.workspaceFolders.length > 0) {
-                try {
-                    await gwConfig.update("token", newToken, vscode.ConfigurationTarget.Workspace);
-                }
-                catch (err) {
-                    this.log(`Workspace token update skipped: ${err instanceof Error ? err.message : String(err)}`);
-                }
-            }
-            // Always persist user scope so empty-window mode (no workspace) still works.
             await gwConfig.update("token", newToken, vscode.ConfigurationTarget.Global);
             await this.restartGateway();
             void vscode.window.showInformationMessage(`${exports.AGENT_ANYWHERE_LABEL}: Auth reset; gateway restarted. If you use the Web UI, paste the new token in Control UI settings.`);
@@ -2702,19 +2841,14 @@ class GatewayLifecycleManager {
             await gwConfig.update("url", wsUrl, vscode.ConfigurationTarget.Global);
         }
         // For local gateways, apply gateway.auth.token from ~/.openclaw/openclaw.json.
-        // Prefer workspace scope when a workspace exists; otherwise use user scope in empty-window mode.
+        // The setting is application-scoped (a credential must never land in a committable
+        // .vscode/settings.json), and VS Code rejects any non-user write for that scope.
         // Remote URLs: do not override — token must come from settings / env for that host.
         const localGateway = /127\.0\.0\.1|localhost|\[::1\]/i.test(wsUrl);
         const fileToken = this.readGatewayToken();
         if (fileToken && localGateway) {
-            if (vscode.workspace.workspaceFolders && vscode.workspace.workspaceFolders.length > 0) {
-                await gwConfig.update("token", fileToken, vscode.ConfigurationTarget.Workspace);
-                this.log("Gateway token applied from openclaw.json (workspace scope)");
-            }
-            else {
-                await gwConfig.update("token", fileToken, vscode.ConfigurationTarget.Global);
-                this.log("Gateway token applied from openclaw.json (global scope; no workspace open)");
-            }
+            await gwConfig.update("token", fileToken, vscode.ConfigurationTarget.Global);
+            this.log("Gateway token applied from openclaw.json (user scope)");
         }
         await this._bridgeRef.connect();
         this.setBridgeConnected(this._bridgeRef.isConnected);

package/out/gateway/outboundPaths.js

@@ -47,7 +47,10 @@ exports.GATEWAY_OUTBOUND_FILENAME = 'gateway-outbound.json';
 exports.AGENTHIPPO_GATEWAY_OUTBOUND_FILE_ENV = 'AGENTHIPPO_GATEWAY_OUTBOUND_FILE';
 /** Sanitize gateway session keys for use as `.agent-hippo/sessions/<id>/` directory names. */
 function safeGatewaySessionDirId(value) {
-    return value.replace(/[<>:"/\\|?*\x00-\x1F]/g, '_').slice(0, 160) || 'session';
+    const sanitized = value.replace(/[<>:"/\\|?*\x00-\x1F]/g, '_').slice(0, 160);
+    // Dot-only keys ("." / "..") would resolve outside the per-session directory — the key is
+    // gateway-supplied, so that is a path traversal. Map each dot to "_" to stay collision-free.
+    return sanitized.replace(/^\.+$/, m => '_'.repeat(m.length)) || 'session';
 }
 function getGatewayOutboundFilePath(workspaceRoot, sessionDirId) {
     return path.join(workspaceRoot, branding_js_1.AGENTIDE_DIR_NAME, 'sessions', sessionDirId, exports.GATEWAY_OUTBOUND_FILENAME);