@pixelbyte-software/pixcode 1.49.5 → 1.49.7

package/scripts/smoke/hermes-rest-gateway.mjs

@@ -0,0 +1,40 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+
+const read = (path) => fs.readFileSync(path, 'utf8');
+
+const service = read('server/services/hermes-gateway.js');
+const routes = read('server/modules/orchestration/hermes/hermes.routes.ts');
+const mcpServer = read('scripts/hermes/pixcode-mcp-server.mjs');
+const configureMcp = read('scripts/hermes/configure-pixcode-mcp.mjs');
+const settingsTab = read('src/components/settings/view/tabs/HermesSettingsTab.tsx');
+
+assert.match(service, /export async function ensureHermesGateway/, 'Pixcode should expose an API-managed Hermes gateway starter.');
+assert.match(service, /export async function probeHermesGateway/, 'Pixcode should probe Hermes through its REST API.');
+assert.match(service, /export function stopHermesGateway/, 'Pixcode should be able to stop a managed Hermes gateway process.');
+assert.match(service, /API_SERVER_ENABLED:\s*'true'/, 'Hermes gateway env should enable the API server.');
+assert.match(service, /API_SERVER_KEY/, 'Hermes gateway env should set a bearer key.');
+assert.match(service, /API_SERVER_PORT/, 'Hermes gateway env should choose a REST port.');
+assert.match(service, /spawn\(installStatus\.command,\s*\['gateway'\]/, 'Pixcode should start Hermes with `hermes gateway` for REST control.');
+assert.match(service, /\/health/, 'Gateway probe should call Hermes health.');
+assert.match(service, /\/v1\/capabilities/, 'Gateway probe should verify Hermes capabilities.');
+assert.match(service, /\/v1\/models/, 'Gateway probe should verify OpenAI-compatible model discovery.');
+assert.match(service, /\/v1\/runs/, 'Gateway probe should support a real run submission when requested.');
+
+assert.match(routes, /router\.get\('\/gateway\/status'/, 'Hermes router should expose gateway status.');
+assert.match(routes, /router\.post\('\/gateway\/start'/, 'Hermes router should expose gateway start.');
+assert.match(routes, /router\.post\('\/gateway\/probe'/, 'Hermes router should expose a REST probe endpoint.');
+assert.match(routes, /router\.post\('\/gateway\/stop'/, 'Hermes router should expose gateway stop.');
+assert.match(routes, /ensureHermesGateway/, 'Hermes router should use the managed gateway service.');
+assert.match(routes, /probeHermesGateway/, 'Hermes router should use the REST probe service.');
+
+assert.match(mcpServer, /pixcode_get_hermes_gateway_status/, 'Pixcode MCP should let Hermes inspect gateway status.');
+assert.match(mcpServer, /pixcode_probe_hermes_gateway/, 'Pixcode MCP should let Hermes trigger a REST probe.');
+assert.match(configureMcp, /pixcode_get_hermes_gateway_status/, 'Hermes MCP config should include gateway status tool.');
+assert.match(configureMcp, /pixcode_probe_hermes_gateway/, 'Hermes MCP config should include gateway probe tool.');
+
+assert.match(settingsTab, /gateway\/status/, 'Hermes settings should read gateway status.');
+assert.match(settingsTab, /gateway\/start/, 'Hermes settings should start the REST gateway via API.');
+assert.match(settingsTab, /gateway\/probe/, 'Hermes settings should run REST probe via API.');
+
+console.log('hermes REST gateway smoke passed');

package/scripts/smoke/hermes-rest-live.mjs

@@ -0,0 +1,42 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  ensureHermesGateway,
+  probeHermesGateway,
+  stopHermesGateway,
+} from '../../server/services/hermes-gateway.js';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const projectPath = path.resolve(process.argv[2] || repoRoot);
+const hermesHome = await fs.mkdtemp(path.join(os.tmpdir(), 'pixcode-hermes-rest-live-'));
+
+try {
+  const gateway = await ensureHermesGateway({
+    appRoot: repoRoot,
+    projectPath,
+    hermesHome,
+    pixcodeBaseUrl: 'http://127.0.0.1:9',
+    pixcodeApiKey: 'px_live_smoke_key',
+    port: Number(process.env.PIXCODE_HERMES_LIVE_PORT || 18642),
+  });
+  if (!gateway.running || !gateway.probe?.ok) {
+    throw new Error(`Hermes gateway did not start cleanly: ${JSON.stringify(gateway)}`);
+  }
+
+  const probe = await probeHermesGateway(projectPath);
+  if (!probe.ok) {
+    throw new Error(`Hermes REST probe failed: ${JSON.stringify(probe)}`);
+  }
+
+  console.log(JSON.stringify({
+    ok: true,
+    baseUrl: probe.baseUrl,
+    projectPath: probe.projectPath,
+    checks: Object.fromEntries(Object.entries(probe.checks).map(([name, check]) => [name, check.status])),
+  }, null, 2));
+} finally {
+  stopHermesGateway(projectPath);
+}

package/scripts/smoke/pixcode-workbench-1-48.mjs

@@ -56,6 +56,8 @@ assert.match(workbench, /WorkbenchCliPanel/, 'Right workbench panel should rende
 assert.match(workbench, /setIsTerminalOpen\(true\)/, 'CLI picker should give way to a full-height terminal after the user starts a provider.');
 assert.match(workbench, /onClose=\{closeTerminal\}/, 'Closing the workbench terminal should return to the CLI picker.');
 assert.match(workbench, /WorkbenchCliPanelToolbar/, 'CLI terminal should keep history and new-session actions visible.');
+assert.match(workbench, /onCloseTerminal=\{closeTerminal\}/, 'CLI terminal toolbar should keep a close button that returns to provider selection.');
+assert.match(workbench, /vscodeWorkbench\.cli\.closeTerminal/, 'CLI terminal close action should have a dedicated accessible label.');
 assert.match(workbench, /WORKBENCH_CLI_STATE_STORAGE_KEY/, 'CLI terminal should remember per-project open state across workspace switches.');
 assert.match(workbench, /function WorkbenchBottomTerminal/, 'Terminal activity should render as a bottom plain-shell panel.');
 assert.match(workbench, /BOTTOM_TERMINAL_MIN_HEIGHT/, 'Bottom terminal should support height resizing.');
@@ -74,9 +76,13 @@ assert.match(themeContext, /return true;/, 'Pixcode should default new installs
 assert.match(workbench, /openNewCliSessionPicker/, 'CLI terminal plus should return to provider selection before starting a fresh session.');
 assert.match(workbench, /terminateCurrentCliSession\(selectedProvider\)/, 'CLI terminal plus should terminate the existing provider PTY before showing selection.');
 assert.match(workbench, /forceNewSession=\{terminalLaunch\.forceNewSession\}/, 'Fresh CLI sessions should bypass the cached default PTY.');
+assert.doesNotMatch(workbench, /suspendAutoConnect/, 'Right CLI provider starts should auto-connect directly instead of showing the shell continue overlay.');
 assert.match(serverIndex, /\/api\/shell\/sessions\/terminate/, 'Backend should expose an authenticated endpoint to terminate cached provider PTYs immediately.');
 assert.match(serverIndex, /isPlainShell && !initialCommand/, 'Backend should spawn an interactive plain shell when no terminal command is provided.');
 assert.match(serverIndex, /pixcode:hermes:start/, 'Backend should expand Hermes terminal sentinels on the server host.');
+assert.match(serverIndex, /Hermes Agent is starting/, 'Hermes terminal should show an immediate startup line before the interactive app draws.');
+assert.match(serverIndex, /"\$HERMES_CMD" chat/, 'POSIX Hermes terminal should start the interactive chat command explicitly.');
+assert.match(serverIndex, /& \$script:HermesCmd chat/, 'Windows Hermes terminal should start the interactive chat command explicitly.');
 assert.doesNotMatch(serverIndex, /iex \(irm https:\/\/raw\.githubusercontent\.com\/NousResearch\/hermes-agent\/main\/scripts\/install\.ps1\)/, 'Windows Hermes install should avoid the old inline iex pattern.');
 assert.doesNotMatch(serverIndex, /scriptblock\]::Create\(\(irm https:\/\/raw\.githubusercontent\.com\/NousResearch\/hermes-agent\/main\/scripts\/install\.ps1\)\)/, 'Windows Hermes install should avoid scriptblock Invoke-RestMethod eval patterns.');
 assert.match(serverIndex, /Invoke-WebRequest[\s\S]+install\.ps1[\s\S]+-OutFile/, 'Windows Hermes install should download the installer to a file before running it.');
@@ -107,6 +113,8 @@ assert.match(hermesRoutes, /terminal-launches/, 'Hermes MCP should be able to re
 assert.match(hermesRoutes, /install-status/, 'Hermes settings and terminal UI should have an install-status endpoint.');
 assert.match(hermesRoutes, /router\.post\('\/install'/, 'Hermes should install through the backend API instead of terminal command paste.');
 assert.match(read('scripts/smoke/hermes-api-install.mjs'), /hermes API install smoke passed/, 'Hermes API install behavior should have a focused smoke test.');
+assert.match(workbench, /terminalStartupInput/, 'Hermes terminal launch prompts should be passed into the selected CLI.');
+assert.match(read('src/components/shell/hooks/useShellConnection.ts'), /startupInputRef/, 'Shell connections should support one-shot startup input for Hermes-triggered CLI work.');
 assert.match(serverIndex, /forceNewSession/, 'Shell backend should support explicit fresh-session launches from the workbench.');
 assert.match(serverIndex, /killProviderPtySessions/, 'Shell backend should terminate old provider PTYs when a fresh CLI session is requested.');
 

package/server/index.js

@@ -414,6 +414,7 @@ function getOrCreateHermesApiKey(userId) {
 
     return apiKeysDb.createApiKey(userId, 'Hermes Agent MCP', [
         'hermes:mcp',
+        'hermes:gateway',
         'projects:read',
         'providers:read',
         'terminal:launch',
@@ -483,7 +484,7 @@ function buildHermesShellCommand(kind, env) {
         if (kind === 'pixcode:hermes:install') {
             return `${setEnv}; ${resolveHermesCommand}; ${configure}; ${installHermesIfMissing}; Install-HermesIfMissing; Invoke-PixcodeHermesConfigure`;
         }
-        return `${setEnv}; ${resolveHermesCommand}; ${configure}; ${installHermesIfMissing}; Install-HermesIfMissing; Invoke-PixcodeHermesConfigure; & $script:HermesCmd`;
+        return `${setEnv}; ${resolveHermesCommand}; ${configure}; ${installHermesIfMissing}; Install-HermesIfMissing; Write-Host "Hermes Agent is starting..."; Invoke-PixcodeHermesConfigure; & $script:HermesCmd chat`;
     }
 
     const setEnv = [
@@ -515,7 +516,7 @@ function buildHermesShellCommand(kind, env) {
     if (kind === 'pixcode:hermes:install') {
         return `${setEnv} sh -lc ${quote(`${resolveHermesCommand} ${installHermesIfMissing} installHermesIfMissing && { node ${shellQuotePosix(configureScript)} || echo "Pixcode MCP configure failed; continuing."; }`)}`;
     }
-    return `${setEnv} sh -lc ${quote(`${resolveHermesCommand} ${installHermesIfMissing} installHermesIfMissing && { node ${shellQuotePosix(configureScript)} || echo "Pixcode MCP configure failed; starting Hermes anyway."; } && "$HERMES_CMD"`)}`;
+    return `${setEnv} sh -lc ${quote(`${resolveHermesCommand} ${installHermesIfMissing} installHermesIfMissing && printf "Hermes Agent is starting...\\n" && { node ${shellQuotePosix(configureScript)} || echo "Pixcode MCP configure failed; starting Hermes anyway."; } && exec "$HERMES_CMD" chat`)}`;
 }
 
 // Single WebSocket server that handles both paths

package/server/modules/orchestration/hermes/hermes.routes.ts

@@ -11,6 +11,12 @@ import {
   readHermesInstallStatus,
   snapshotHermesInstallDonePayload,
 } from '@/services/hermes-install-jobs.js';
+import {
+  ensureHermesGateway,
+  getHermesGatewayStatus,
+  probeHermesGateway,
+  stopHermesGateway,
+} from '@/services/hermes-gateway.js';
 
 const HERMES_TERMINAL_LAUNCH_LIMIT = 100;
 const HERMES_TERMINAL_LAUNCH_PROVIDERS = new Set(['claude', 'codex', 'cursor', 'gemini', 'qwen', 'opencode']);
@@ -91,6 +97,86 @@ export function createHermesRouter(options: HermesRouterOptions = {}): Router {
     res.json(readHermesInstallStatus());
   });
 
+  router.get('/gateway/status', (req, res) => {
+    const projectPath = typeof req.query.projectPath === 'string' ? req.query.projectPath : null;
+    res.json(getHermesGatewayStatus(projectPath));
+  });
+
+  router.post('/gateway/start', async (req: PixcodeRequest, res) => {
+    const apiKey = options.createHermesApiKey?.(readUserId(req)) ?? null;
+    if (!apiKey) {
+      res.status(500).json({
+        error: {
+          code: 'HERMES_API_KEY_UNAVAILABLE',
+          message: 'Pixcode could not create a Hermes MCP API key for this user.',
+        },
+      });
+      return;
+    }
+
+    const body = (req.body ?? {}) as Record<string, unknown>;
+    try {
+      const gateway = await ensureHermesGateway({
+        appRoot: options.appRoot ?? process.cwd(),
+        pixcodeApiKey: apiKey,
+        pixcodeBaseUrl: options.resolvePublicBaseUrl?.(req) ?? `http://127.0.0.1:${process.env.SERVER_PORT ?? process.env.PORT ?? '3001'}`,
+        projectPath: typeof body.projectPath === 'string' ? body.projectPath : undefined,
+      });
+      res.status(202).json(gateway);
+    } catch (error) {
+      res.status(500).json({
+        error: {
+          code: 'HERMES_GATEWAY_START_FAILED',
+          message: error instanceof Error ? error.message : String(error),
+        },
+      });
+    }
+  });
+
+  router.post('/gateway/probe', async (req: PixcodeRequest, res) => {
+    const body = (req.body ?? {}) as Record<string, unknown>;
+    const projectPath = typeof body.projectPath === 'string' ? body.projectPath : null;
+    const input = typeof body.input === 'string' ? body.input : undefined;
+    const shouldStart = body.startIfNeeded === true;
+
+    try {
+      if (shouldStart) {
+        const apiKey = options.createHermesApiKey?.(readUserId(req)) ?? null;
+        if (!apiKey) {
+          res.status(500).json({
+            error: {
+              code: 'HERMES_API_KEY_UNAVAILABLE',
+              message: 'Pixcode could not create a Hermes MCP API key for this user.',
+            },
+          });
+          return;
+        }
+        await ensureHermesGateway({
+          appRoot: options.appRoot ?? process.cwd(),
+          pixcodeApiKey: apiKey,
+          pixcodeBaseUrl: options.resolvePublicBaseUrl?.(req) ?? `http://127.0.0.1:${process.env.SERVER_PORT ?? process.env.PORT ?? '3001'}`,
+          projectPath: projectPath ?? undefined,
+        });
+      }
+
+      const probe = await probeHermesGateway(projectPath, { input });
+      res.status(probe.ok ? 200 : 503).json(probe);
+    } catch (error) {
+      res.status(500).json({
+        error: {
+          code: 'HERMES_GATEWAY_PROBE_FAILED',
+          message: error instanceof Error ? error.message : String(error),
+        },
+      });
+    }
+  });
+
+  router.post('/gateway/stop', (req, res) => {
+    const body = (req.body ?? {}) as Record<string, unknown>;
+    const projectPath = typeof body.projectPath === 'string' ? body.projectPath : null;
+    res.json(stopHermesGateway(projectPath));
+  });
+
   router.post('/install', (req: PixcodeRequest, res) => {
     const apiKey = options.createHermesApiKey?.(readUserId(req)) ?? null;
     if (!apiKey) {

package/server/services/hermes-gateway.js

@@ -0,0 +1,400 @@
+import { randomBytes } from 'node:crypto';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+
+import spawn from 'cross-spawn';
+
+import {
+    buildHermesPathEnv,
+    readHermesInstallStatus,
+} from './hermes-install-jobs.js';
+
+const DEFAULT_HOST = '127.0.0.1';
+const DEFAULT_PORT = 8642;
+const PORT_SCAN_LIMIT = 80;
+const STARTUP_TIMEOUT_MS = 30000;
+const FETCH_TIMEOUT_MS = 5000;
+const LOG_LIMIT = 800;
+
+const gateways = new Map();
+
+function nowIso() {
+    return new Date().toISOString();
+}
+
+function normalizeProjectPath(projectPath) {
+    return path.resolve(projectPath || os.homedir());
+}
+
+function appendGatewayLog(gateway, stream, chunk) {
+    const entry = { stream, chunk: String(chunk || ''), at: Date.now() };
+    gateway.logs.push(entry);
+    if (gateway.logs.length > LOG_LIMIT) {
+        gateway.logs.splice(0, gateway.logs.length - LOG_LIMIT);
+    }
+}
+
+function isGatewayRunning(gateway) {
+    return Boolean(gateway?.child && gateway.exitCode === null && gateway.exitSignal === null);
+}
+
+function gatewayBaseUrl(host, port) {
+    return `http://${host}:${port}`;
+}
+
+function makeApiServerKey() {
+    return `pixcode-hermes-${randomBytes(24).toString('hex')}`;
+}
+
+export function buildHermesGatewayEnv(baseEnv = process.env, options = {}) {
+    const host = options.host || DEFAULT_HOST;
+    const port = String(options.port || DEFAULT_PORT);
+    return buildHermesPathEnv(baseEnv, {
+        API_SERVER_ENABLED: 'true',
+        API_SERVER_HOST: host,
+        API_SERVER_PORT: port,
+        API_SERVER_KEY: options.apiServerKey || makeApiServerKey(),
+        API_SERVER_CORS_ORIGINS: options.corsOrigins || options.pixcodeBaseUrl || '',
+        PIXCODE_BASE_URL: options.pixcodeBaseUrl || '',
+        PIXCODE_API_KEY: options.pixcodeApiKey || '',
+        PIXCODE_APP_ROOT: options.appRoot || process.cwd(),
+        HERMES_HOME: options.hermesHome || '',
+        HERMES_INSTALL_DIR: options.installDir || '',
+    });
+}
+
+function isPortAvailable(port, host) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once('error', () => resolve(false));
+        server.once('listening', () => {
+            server.close(() => resolve(true));
+        });
+        server.listen(port, host);
+    });
+}
+
+async function findAvailablePort(preferredPort, host) {
+    const start = Number.isFinite(preferredPort) ? preferredPort : DEFAULT_PORT;
+    for (let offset = 0; offset < PORT_SCAN_LIMIT; offset += 1) {
+        const port = start + offset;
+        if (await isPortAvailable(port, host)) {
+            return port;
+        }
+    }
+    throw new Error(`No available Hermes API server port found from ${start} to ${start + PORT_SCAN_LIMIT - 1}.`);
+}
+
+function fetchJson(url, options = {}) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), options.timeoutMs || FETCH_TIMEOUT_MS);
+    return fetch(url, {
+        ...options,
+        signal: controller.signal,
+        headers: {
+            accept: 'application/json',
+            ...(options.headers || {}),
+        },
+    }).then(async (response) => {
+        const text = await response.text();
+        let body = null;
+        try {
+            body = text ? JSON.parse(text) : null;
+        } catch {
+            body = text;
+        }
+
+        return {
+            ok: response.ok,
+            status: response.status,
+            body,
+        };
+    }).finally(() => clearTimeout(timeout));
+}
+
+async function callGateway(gateway, endpoint, options = {}) {
+    return fetchJson(`${gateway.baseUrl}${endpoint}`, {
+        ...options,
+        headers: {
+            Authorization: `Bearer ${gateway.apiServerKey}`,
+            'content-type': 'application/json',
+            ...(options.headers || {}),
+        },
+    });
+}
+
+async function waitForGatewayReady(gateway) {
+    const started = Date.now();
+    let lastError = null;
+
+    while (Date.now() - started < STARTUP_TIMEOUT_MS) {
+        if (!isGatewayRunning(gateway)) {
+            throw new Error(gateway.error || `Hermes gateway exited with code ${gateway.exitCode ?? 'unknown'}.`);
+        }
+
+        try {
+            const probe = await probeHermesGateway(gateway.projectPath, { requireRunning: true });
+            if (probe.ok) {
+                return probe;
+            }
+            lastError = probe.error || 'Gateway probe failed.';
+        } catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+        }
+
+        await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+
+    throw new Error(`Hermes gateway did not become ready within ${STARTUP_TIMEOUT_MS / 1000}s: ${lastError || 'no response'}`);
+}
+
+function runProcess(command, args, options, onData) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            ...options,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        child.stdout?.on('data', (buf) => onData?.('stdout', buf.toString()));
+        child.stderr?.on('data', (buf) => onData?.('stderr', buf.toString()));
+        child.on('error', reject);
+        child.on('close', (code, signal) => {
+            if (signal) {
+                reject(new Error(`${command} killed by ${signal}`));
+                return;
+            }
+            resolve(code ?? 0);
+        });
+    });
+}
+
+async function configurePixcodeMcp({ appRoot, env, gateway }) {
+    const configureScript = path.join(appRoot, 'scripts', 'hermes', 'configure-pixcode-mcp.mjs');
+    const code = await runProcess(process.execPath, [configureScript], {
+        cwd: appRoot,
+        env,
+    }, (stream, chunk) => appendGatewayLog(gateway, stream, chunk));
+
+    if (code !== 0) {
+        throw new Error(`Pixcode MCP configuration exited with code ${code}`);
+    }
+}
+
+function snapshotGateway(gateway) {
+    if (!gateway) {
+        return {
+            running: false,
+            projectPath: null,
+            baseUrl: null,
+            host: null,
+            port: null,
+            pid: null,
+            startedAt: null,
+            exitedAt: null,
+            exitCode: null,
+            exitSignal: null,
+            error: null,
+            lastProbe: null,
+            logs: [],
+        };
+    }
+
+    return {
+        running: isGatewayRunning(gateway),
+        projectPath: gateway.projectPath,
+        baseUrl: gateway.baseUrl,
+        host: gateway.host,
+        port: gateway.port,
+        pid: gateway.child?.pid ?? null,
+        startedAt: gateway.startedAt,
+        exitedAt: gateway.exitedAt,
+        exitCode: gateway.exitCode,
+        exitSignal: gateway.exitSignal,
+        error: gateway.error,
+        lastProbe: gateway.lastProbe,
+        logs: gateway.logs.slice(-80),
+    };
+}
+
+export function getHermesGatewayStatus(projectPath) {
+    if (projectPath) {
+        return snapshotGateway(gateways.get(normalizeProjectPath(projectPath)));
+    }
+
+    const active = Array.from(gateways.values()).filter(isGatewayRunning);
+    return {
+        running: active.length > 0,
+        gateways: Array.from(gateways.values()).map(snapshotGateway),
+    };
+}
+
+export async function ensureHermesGateway(options = {}) {
+    const projectPath = normalizeProjectPath(options.projectPath);
+    const existing = gateways.get(projectPath);
+    if (isGatewayRunning(existing)) {
+        const probe = await probeHermesGateway(projectPath, { requireRunning: true }).catch((error) => ({
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        }));
+        if (probe.ok) {
+            return {
+                ...snapshotGateway(existing),
+                probe,
+            };
+        }
+        stopHermesGateway(projectPath);
+    }
+
+    const host = options.host || DEFAULT_HOST;
+    const port = await findAvailablePort(Number(options.port || process.env.HERMES_API_SERVER_PORT || DEFAULT_PORT), host);
+    const apiServerKey = options.apiServerKey || makeApiServerKey();
+    const appRoot = options.appRoot || process.cwd();
+    const env = buildHermesGatewayEnv(process.env, {
+        ...options,
+        host,
+        port,
+        apiServerKey,
+        appRoot,
+    });
+    const installStatus = readHermesInstallStatus(env);
+    if (!installStatus.installed || !installStatus.command) {
+        throw new Error(installStatus.error || 'Hermes Agent CLI is not installed.');
+    }
+
+    const gateway = {
+        id: `${projectPath}:${port}`,
+        projectPath,
+        host,
+        port,
+        baseUrl: gatewayBaseUrl(host, port),
+        apiServerKey,
+        command: installStatus.command,
+        child: null,
+        startedAt: nowIso(),
+        exitedAt: null,
+        exitCode: null,
+        exitSignal: null,
+        error: null,
+        lastProbe: null,
+        logs: [],
+    };
+    gateways.set(projectPath, gateway);
+
+    await configurePixcodeMcp({ appRoot, env, gateway });
+
+    const child = spawn(installStatus.command, ['gateway'], {
+        cwd: projectPath,
+        env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+    });
+    gateway.child = child;
+    appendGatewayLog(gateway, 'meta', `$ ${installStatus.command} gateway\n`);
+
+    child.stdout?.on('data', (buf) => appendGatewayLog(gateway, 'stdout', buf.toString()));
+    child.stderr?.on('data', (buf) => appendGatewayLog(gateway, 'stderr', buf.toString()));
+    child.on('error', (error) => {
+        gateway.error = error instanceof Error ? error.message : String(error);
+        appendGatewayLog(gateway, 'stderr', `${gateway.error}\n`);
+    });
+    child.on('exit', (code, signal) => {
+        gateway.exitCode = code;
+        gateway.exitSignal = signal;
+        gateway.exitedAt = nowIso();
+        appendGatewayLog(gateway, 'meta', `Hermes gateway exited with code ${code}${signal ? ` (${signal})` : ''}\n`);
+    });
+
+    const probe = await waitForGatewayReady(gateway);
+    return {
+        ...snapshotGateway(gateway),
+        probe,
+    };
+}
+
+export async function probeHermesGateway(projectPath, options = {}) {
+    const gateway = projectPath
+        ? gateways.get(normalizeProjectPath(projectPath))
+        : Array.from(gateways.values()).find(isGatewayRunning);
+
+    if (!isGatewayRunning(gateway)) {
+        const result = {
+            ok: false,
+            error: 'Hermes gateway is not running.',
+            projectPath: projectPath ? normalizeProjectPath(projectPath) : null,
+            baseUrl: null,
+            checks: {},
+        };
+        if (options.requireRunning) return result;
+        return result;
+    }
+
+    const checks = {};
+    try {
+        checks.health = await fetchJson(`${gateway.baseUrl}/health`);
+    } catch (error) {
+        checks.health = { ok: false, status: 0, error: error instanceof Error ? error.message : String(error) };
+    }
+
+    try {
+        checks.capabilities = await callGateway(gateway, '/v1/capabilities');
+    } catch (error) {
+        checks.capabilities = { ok: false, status: 0, error: error instanceof Error ? error.message : String(error) };
+    }
+
+    try {
+        checks.models = await callGateway(gateway, '/v1/models');
+    } catch (error) {
+        checks.models = { ok: false, status: 0, error: error instanceof Error ? error.message : String(error) };
+    }
+
+    if (typeof options.input === 'string' && options.input.trim()) {
+        try {
+            checks.run = await callGateway(gateway, '/v1/runs', {
+                method: 'POST',
+                body: JSON.stringify({
+                    input: options.input.trim(),
+                    session_id: options.sessionId || `pixcode-${Date.now()}`,
+                    instructions: options.instructions || 'Respond briefly for a Pixcode REST integration check.',
+                }),
+                timeoutMs: options.runTimeoutMs || 15000,
+            });
+        } catch (error) {
+            checks.run = { ok: false, status: 0, error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+
+    const ok = Boolean(
+        checks.health?.ok &&
+        checks.capabilities?.ok &&
+        checks.models?.ok &&
+        (!checks.run || checks.run.ok),
+    );
+    const result = {
+        ok,
+        projectPath: gateway.projectPath,
+        baseUrl: gateway.baseUrl,
+        checkedAt: nowIso(),
+        checks,
+        error: ok ? null : 'One or more Hermes REST checks failed.',
+    };
+    gateway.lastProbe = result;
+    return result;
+}
+
+export function stopHermesGateway(projectPath) {
+    const targets = projectPath
+        ? [gateways.get(normalizeProjectPath(projectPath))].filter(Boolean)
+        : Array.from(gateways.values());
+    let stopped = 0;
+    for (const gateway of targets) {
+        if (!isGatewayRunning(gateway)) continue;
+        try {
+            gateway.child.kill();
+            stopped += 1;
+        } catch (error) {
+            gateway.error = error instanceof Error ? error.message : String(error);
+        }
+    }
+    return { stopped };
+}