@pixelbyte-software/pixcode 1.49.9 → 1.49.11

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

@@ -65,8 +65,11 @@ assert.match(workbench, /BOTTOM_TERMINAL_MIN_HEIGHT/, 'Bottom terminal should su
 assert.match(workbench, /isBottomTerminalMinimized/, 'Bottom terminal should support minimizing without closing.');
 assert.match(workbench, /isPlainShell/, 'Bottom terminal should open the selected project folder without starting the selected AI CLI.');
 assert.doesNotMatch(workbench, /HERMES_AGENT_START_COMMAND/, 'Hermes Agent should not launch from the bottom terminal through a server-side sentinel.');
-assert.match(workbench, /HermesApiChatPanel/, 'Hermes Agent should render a REST-backed chat panel in the bottom area.');
-assert.match(workbench, /\/api\/orchestration\/hermes\/gateway\/chat/, 'Hermes chat panel should send prompts through the Pixcode gateway chat API.');
+assert.doesNotMatch(workbench, /HermesApiChatPanel|HermesTerminalTranscript/, 'Hermes Agent should use the real PTY terminal UI, not a custom REST chat transcript.');
+assert.doesNotMatch(workbench, /REST POST \/|transport=|response=|gateway=http/, 'Hermes terminal UI must not expose REST debug internals to the user.');
+assert.match(workbench, /command="hermes"/, 'Hermes Agent bottom panel should launch the actual `hermes` CLI in a PTY.');
+assert.match(workbench, /Pixcode MCP Live/, 'Hermes terminal should show a user-facing Pixcode MCP live badge.');
+assert.doesNotMatch(workbench, /ml-auto border-blue-500\/40 bg-blue-500\/10/, 'Hermes REST panel must not use right-aligned chat bubbles.');
 assert.match(workbench, /terminal-launches\/stream/, 'Hermes CLI launch requests should arrive through an EventSource stream.');
 assert.doesNotMatch(workbench, /HERMES_TERMINAL_LAUNCH_POLL_MS|setInterval\([\s\S]*terminal-launches/, 'Hermes CLI launch requests should not be polled every few seconds.');
 assert.doesNotMatch(workbench, /Project-scoped agent terminal\. Installs Hermes when missing/, 'Right CLI panel should not show the old Hermes card.');
@@ -86,6 +89,8 @@ assert.match(serverIndex, /\/api\/shell\/sessions\/terminate/, 'Backend should e
 assert.match(serverIndex, /isPlainShell && !initialCommand/, 'Backend should spawn an interactive plain shell when no terminal command is provided.');
 assert.doesNotMatch(serverIndex, /pixcode:hermes:start/, 'Backend should not need a Hermes terminal sentinel for the workbench Hermes panel.');
 assert.doesNotMatch(serverIndex, /hermesCommand/, 'Provider shell starts should not reference the removed Hermes sentinel variable.');
+assert.match(serverIndex, /configure-pixcode-mcp\.mjs/, 'Hermes PTY launches should configure Pixcode MCP before starting the CLI.');
+assert.match(serverIndex, /resolveHermesMcpBaseUrl/, 'Hermes MCP should use the local Pixcode API base URL from the host process.');
 assert.doesNotMatch(hermesInstallJobs, /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(hermesInstallJobs, /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(hermesInstallJobs, /downloadHermesInstaller/, 'Windows Hermes install should download the installer through backend API code before running it.');
@@ -115,12 +120,18 @@ assert.match(hermesRoutes, /createHermesRouter/, 'Hermes should have a dedicated
 assert.match(hermesRoutes, /terminal-launches/, 'Hermes MCP should be able to request visible Pixcode CLI terminal launches.');
 assert.match(hermesRoutes, /terminal-launches\/stream/, 'Hermes MCP terminal launch requests should stream to the workbench over SSE.');
 assert.match(hermesRoutes, /hermesTerminalLaunchEmitter/, 'Hermes terminal launch stream should broadcast new events instead of relying on polling.');
-assert.match(hermesRoutes, /router\.post\('\/gateway\/chat'/, 'Hermes should expose a REST chat endpoint for the bottom panel.');
+assert.match(hermesRoutes, /router\.post\('\/gateway\/chat'/, 'Hermes should still expose a REST chat endpoint for health checks and integrations.');
 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(read('src/components/shell/hooks/useShellConnection.ts'), /isCliReadyForStartupInput/, 'Hermes-triggered CLI input should wait until the provider TUI is ready.');
+assert.doesNotMatch(read('src/components/shell/hooks/useShellConnection.ts'), /TERMINAL_INIT_DELAY_MS \* 3/, 'Hermes-triggered CLI input should not be sent on a blind fixed delay.');
+assert.match(shellTerminal, /handleTerminalPaste/, 'Terminal should support browser paste events.');
+assert.match(shellTerminal, /handleCopyPasteShortcut/, 'Terminal should normalize Ctrl/Cmd copy and paste shortcuts.');
+assert.match(shellTerminal, /event\.shiftKey/, 'Terminal should support Ctrl+Shift+C/V style shortcuts.');
+assert.match(shellTerminal, /copyTerminalSelection/, 'Terminal should copy selected terminal text through shortcuts.');
 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

@@ -390,6 +390,34 @@ function resolvePublicBaseUrl(request) {
     return `${proto}://${String(host).split(',')[0].trim()}`;
 }
 
+function resolveHermesMcpBaseUrl() {
+    const configured = process.env.PIXCODE_INTERNAL_BASE_URL || process.env.PIXCODE_HERMES_BASE_URL;
+    if (configured) return configured.replace(/\/$/, '');
+
+    return `http://127.0.0.1:${process.env.SERVER_PORT || process.env.PORT || '3001'}`;
+}
+
+function quoteBashArg(value) {
+    return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
+
+function quotePowerShellArg(value) {
+    return `"${String(value).replace(/`/g, '``').replace(/\$/g, '`$').replace(/"/g, '`"')}"`;
+}
+
+function isHermesCliCommand(command) {
+    return typeof command === 'string' && command.trim() === 'hermes';
+}
+
+function buildHermesCliCommand(command) {
+    const configureScript = path.join(APP_ROOT, 'scripts', 'hermes', 'configure-pixcode-mcp.mjs');
+    if (os.platform() === 'win32') {
+        return `& ${quotePowerShellArg(process.execPath)} ${quotePowerShellArg(configureScript)} *> $null; ${command}`;
+    }
+
+    return `${quoteBashArg(process.execPath)} ${quoteBashArg(configureScript)} >/dev/null 2>&1; exec ${command}`;
+}
+
 function getOrCreateHermesApiKey(userId) {
     if (!userId) return null;
 
@@ -2182,10 +2210,14 @@ function handleShellConnection(ws, request) {
                 const provider = data.provider || 'claude';
                 const initialCommand = data.initialCommand;
                 const isPlainShell = data.isPlainShell || (!!initialCommand && !hasSession) || provider === 'plain-shell';
+                const isHermesCliLaunch = isPlainShell && isHermesCliCommand(initialCommand);
                 const forceNewSession = Boolean(data.forceNewSession);
                 const shellPermissionMode = normalizeShellPermissionMode(data.permissionMode);
                 const shellSkipPermissions = Boolean(data.skipPermissions);
                 const shellPermissionFlags = buildProviderShellPermissionFlags(provider, shellPermissionMode, shellSkipPermissions);
+                const hermesApiKey = isHermesCliLaunch
+                    ? getOrCreateHermesApiKey(request.user?.id ?? request.user?.userId ?? null)
+                    : null;
                 urlDetectionBuffer = '';
                 announcedAuthUrls.clear();
 
@@ -2314,7 +2346,9 @@ function handleShellConnection(ws, request) {
                     let shellCommand;
                     if (isPlainShell) {
                         // Plain shell mode without an initial command must stay interactive.
-                        shellCommand = initialCommand || null;
+                        shellCommand = isHermesCliLaunch
+                            ? buildHermesCliCommand(initialCommand)
+                            : initialCommand || null;
                     } else if (provider === 'cursor') {
                         const command = buildProviderShellCommand('cursor-agent', shellPermissionFlags);
                         if (hasSession && sessionId) {
@@ -2429,6 +2463,11 @@ function handleShellConnection(ws, request) {
                         TERM: 'xterm-256color',
                         COLORTERM: 'truecolor',
                         FORCE_COLOR: '3',
+                        ...(isHermesCliLaunch ? {
+                            PIXCODE_BASE_URL: resolveHermesMcpBaseUrl(),
+                            PIXCODE_API_KEY: hermesApiKey || '',
+                            PIXCODE_APP_ROOT: APP_ROOT,
+                        } : {}),
                     });
 
                     shellProcess = pty.spawn(shell, shellArgs, {

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

@@ -60,6 +60,13 @@ function readUserId(req: PixcodeRequest) {
   return req.user?.id ?? req.user?.userId ?? null;
 }
 
+function resolveHermesMcpBaseUrl() {
+  const configured = process.env.PIXCODE_INTERNAL_BASE_URL || process.env.PIXCODE_HERMES_BASE_URL;
+  if (configured) return configured.replace(/\/$/, '');
+
+  return `http://127.0.0.1:${process.env.SERVER_PORT ?? process.env.PORT ?? '3001'}`;
+}
+
 function readAfterId(req: Request) {
   const after = Number.parseInt(typeof req.query.after === 'string' ? req.query.after : '0', 10);
   return Number.isFinite(after) ? after : 0;
@@ -137,7 +144,7 @@ export function createHermesRouter(options: HermesRouterOptions = {}): Router {
       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'}`,
+        pixcodeBaseUrl: resolveHermesMcpBaseUrl(),
         projectPath: typeof body.projectPath === 'string' ? body.projectPath : undefined,
       });
       res.status(202).json(gateway);
@@ -172,7 +179,7 @@ export function createHermesRouter(options: HermesRouterOptions = {}): Router {
         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'}`,
+          pixcodeBaseUrl: resolveHermesMcpBaseUrl(),
           projectPath: projectPath ?? undefined,
         });
       }
@@ -224,8 +231,9 @@ export function createHermesRouter(options: HermesRouterOptions = {}): Router {
       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'}`,
+        pixcodeBaseUrl: resolveHermesMcpBaseUrl(),
         projectPath,
+        probeExisting: false,
       });
       const run = await runHermesGatewayPrompt(projectPath, {
         input,
@@ -272,7 +280,7 @@ export function createHermesRouter(options: HermesRouterOptions = {}): Router {
       appRoot: options.appRoot ?? process.cwd(),
       force: Boolean(body.force),
       pixcodeApiKey: apiKey,
-      pixcodeBaseUrl: options.resolvePublicBaseUrl?.(req) ?? `http://127.0.0.1:${process.env.SERVER_PORT ?? process.env.PORT ?? '3001'}`,
+      pixcodeBaseUrl: resolveHermesMcpBaseUrl(),
       skipBrowser: body.skipBrowser !== false,
     });
 

package/server/services/hermes-gateway.js

@@ -1,4 +1,5 @@
 import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
 import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
@@ -18,6 +19,27 @@ const FETCH_TIMEOUT_MS = 5000;
 const RUN_TIMEOUT_MS = 120000;
 const RUN_POLL_INTERVAL_MS = 1000;
 const LOG_LIMIT = 800;
+const PIXCODE_MANAGED_HERMES_ENV_PREFIXES = [
+    'API_SERVER_',
+    'BLUEBUBBLES_',
+    'DINGTALK_',
+    'DISCORD_',
+    'EMAIL_',
+    'FEISHU_',
+    'MATTERMOST_',
+    'MATRIX_',
+    'MSGRAPH_',
+    'QQ_',
+    'SIGNAL_',
+    'SLACK_',
+    'SMS_',
+    'TELEGRAM_',
+    'TWILIO_',
+    'WECOM_',
+    'WEIXIN_',
+    'WHATSAPP_',
+    'YUANBAO_',
+];
 
 const gateways = new Map();
 
@@ -53,6 +75,96 @@ function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+function resolveSourceHermesHome(env = process.env) {
+    if (env.HERMES_HOME?.trim()) {
+        return path.resolve(env.HERMES_HOME);
+    }
+
+    const defaultHome = path.join(os.homedir(), '.hermes');
+    try {
+        const activeProfile = fs.readFileSync(path.join(defaultHome, 'active_profile'), 'utf8').trim();
+        if (activeProfile && activeProfile !== 'default' && /^[a-z0-9][a-z0-9_-]{0,63}$/.test(activeProfile)) {
+            return path.join(defaultHome, 'profiles', activeProfile);
+        }
+    } catch {
+        // Default Hermes profile is fine when no sticky active profile exists.
+    }
+
+    return defaultHome;
+}
+
+function resolveHermesGatewayHome(env = process.env, options = {}) {
+    const configured = options.hermesHome || env.PIXCODE_HERMES_GATEWAY_HOME;
+    if (configured) {
+        return path.resolve(configured);
+    }
+
+    return path.join(os.homedir(), '.hermes', 'profiles', 'pixcode');
+}
+
+function copyHermesProfileFile(sourceHome, targetHome, fileName, options = {}) {
+    const source = path.join(sourceHome, fileName);
+    const target = path.join(targetHome, fileName);
+    if (!fs.existsSync(source)) return false;
+    if (!options.overwrite && fs.existsSync(target)) return false;
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.copyFileSync(source, target);
+    return true;
+}
+
+function shouldStripManagedGatewayEnvLine(line) {
+    const match = String(line || '').match(/^\s*(?:export\s+)?([A-Z0-9_]+)\s*=/);
+    if (!match) return false;
+    return PIXCODE_MANAGED_HERMES_ENV_PREFIXES.some((prefix) => match[1].startsWith(prefix));
+}
+
+function copyHermesProfileEnv(sourceHome, targetHome) {
+    const source = path.join(sourceHome, '.env');
+    const target = path.join(targetHome, '.env');
+    if (!fs.existsSync(source)) return false;
+
+    const sourceText = fs.readFileSync(source, 'utf8');
+    const sanitized = sourceText
+        .split(/\r?\n/)
+        .filter((line) => !shouldStripManagedGatewayEnvLine(line))
+        .join('\n')
+        .replace(/\s*$/, '\n');
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, sanitized);
+    return true;
+}
+
+function seedHermesGatewayHome({ sourceHome, targetHome, gateway }) {
+    fs.mkdirSync(targetHome, { recursive: true });
+    if (path.resolve(sourceHome) === path.resolve(targetHome)) {
+        appendGatewayLog(gateway, 'meta', `Using Hermes gateway profile at ${targetHome}\n`);
+        return;
+    }
+
+    const copied = [];
+    for (const file of ['config.yaml', 'SOUL.md']) {
+        if (copyHermesProfileFile(sourceHome, targetHome, file, { overwrite: false })) {
+            copied.push(file);
+        }
+    }
+    if (copyHermesProfileEnv(sourceHome, targetHome)) {
+        copied.push('.env (without messaging platform credentials)');
+    }
+    for (const file of ['auth.json']) {
+        if (copyHermesProfileFile(sourceHome, targetHome, file, { overwrite: true })) {
+            copied.push(file);
+        }
+    }
+
+    appendGatewayLog(
+        gateway,
+        'meta',
+        copied.length > 0
+            ? `Seeded Pixcode Hermes gateway profile from ${sourceHome}: ${copied.join(', ')}\n`
+            : `Using Pixcode Hermes gateway profile at ${targetHome}\n`,
+    );
+}
+
 export function buildHermesGatewayEnv(baseEnv = process.env, options = {}) {
     const host = options.host || DEFAULT_HOST;
     const port = String(options.port || DEFAULT_PORT);
@@ -173,6 +285,29 @@ function extractRunOutput(body) {
     return null;
 }
 
+function extractResponsesOutput(body) {
+    if (!body || typeof body !== 'object') return null;
+
+    const output = Array.isArray(body.output) ? body.output : [];
+    for (const item of output) {
+        if (!item || typeof item !== 'object') continue;
+        if (item.type === 'message' || item.role === 'assistant') {
+            const text = extractTextFromValue(item.content);
+            if (text) return text;
+        }
+        const text = extractTextFromValue(item.output_text)
+            || extractTextFromValue(item.text)
+            || extractTextFromValue(item.message)
+            || extractTextFromValue(item.output);
+        if (text) return text;
+    }
+
+    return extractTextFromValue(body.output_text)
+        || extractTextFromValue(body.message)
+        || extractTextFromValue(body.response)
+        || null;
+}
+
 function extractChatCompletionOutput(body) {
     if (!body || typeof body !== 'object') return null;
     const choices = Array.isArray(body.choices) ? body.choices : [];
@@ -244,6 +379,21 @@ function makeChatCompletionRequest(options) {
     };
 }
 
+function makeResponsesRequest(options) {
+    const input = String(options.input || '').trim();
+    return {
+        model: options.model || 'hermes-agent',
+        input,
+        instructions: options.instructions || [
+            'You are Hermes Agent running inside Pixcode.',
+            'Use Pixcode MCP tools when they help inspect projects, launch CLIs, or perform workspace actions.',
+            'Keep answers concise and include concrete next steps when work is blocked.',
+        ].join(' '),
+        conversation: options.sessionId || undefined,
+        store: true,
+    };
+}
+
 async function waitForGatewayReady(gateway) {
     const started = Date.now();
     let lastError = null;
@@ -307,6 +457,7 @@ function snapshotGateway(gateway) {
             running: false,
             projectPath: null,
             baseUrl: null,
+            hermesHome: null,
             host: null,
             port: null,
             pid: null,
@@ -324,6 +475,7 @@ function snapshotGateway(gateway) {
         running: isGatewayRunning(gateway),
         projectPath: gateway.projectPath,
         baseUrl: gateway.baseUrl,
+        hermesHome: gateway.hermesHome,
         host: gateway.host,
         port: gateway.port,
         pid: gateway.child?.pid ?? null,
@@ -353,16 +505,24 @@ export async function ensureHermesGateway(options = {}) {
     const projectPath = normalizeProjectPath(options.projectPath);
     const existing = gateways.get(projectPath);
     if (isGatewayRunning(existing)) {
+        if (options.probeExisting !== true) {
+            return {
+                ...snapshotGateway(existing),
+                probe: existing.lastProbe,
+            };
+        }
+
         const probe = await probeHermesGateway(projectPath, { requireRunning: true }).catch((error) => ({
             ok: false,
             error: error instanceof Error ? error.message : String(error),
         }));
-        if (probe.ok) {
+        if (probe.ok || options.replaceUnhealthy !== true) {
             return {
                 ...snapshotGateway(existing),
                 probe,
             };
         }
+
         stopHermesGateway(projectPath);
     }
 
@@ -370,14 +530,20 @@ export async function ensureHermesGateway(options = {}) {
     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 sourceHermesHome = options.sourceHermesHome || resolveSourceHermesHome(process.env);
+    const hermesHome = resolveHermesGatewayHome(process.env, options);
     const env = buildHermesGatewayEnv(process.env, {
         ...options,
         host,
         port,
         apiServerKey,
         appRoot,
+        hermesHome,
+    });
+    const installStatus = readHermesInstallStatus(env, {
+        allowSmokeHermes: options.allowSmokeHermes === true,
+        repairLaunchers: options.repairLaunchers !== false,
     });
-    const installStatus = readHermesInstallStatus(env);
     if (!installStatus.installed || !installStatus.command) {
         throw new Error(installStatus.error || 'Hermes Agent CLI is not installed.');
     }
@@ -388,6 +554,7 @@ export async function ensureHermesGateway(options = {}) {
         host,
         port,
         baseUrl: gatewayBaseUrl(host, port),
+        hermesHome,
         apiServerKey,
         command: installStatus.command,
         child: null,
@@ -401,16 +568,18 @@ export async function ensureHermesGateway(options = {}) {
     };
     gateways.set(projectPath, gateway);
 
+    seedHermesGatewayHome({ sourceHome: sourceHermesHome, targetHome: hermesHome, gateway });
     await configurePixcodeMcp({ appRoot, env, gateway });
 
-    const child = spawn(installStatus.command, ['gateway'], {
+    const gatewayArgs = options.gatewayArgs || ['gateway', 'run', '--replace'];
+    const child = spawn(installStatus.command, gatewayArgs, {
         cwd: projectPath,
         env,
         stdio: ['ignore', 'pipe', 'pipe'],
         windowsHide: true,
     });
     gateway.child = child;
-    appendGatewayLog(gateway, 'meta', `$ ${installStatus.command} gateway\n`);
+    appendGatewayLog(gateway, 'meta', `$ ${installStatus.command} ${gatewayArgs.join(' ')}\n`);
 
     child.stdout?.on('data', (buf) => appendGatewayLog(gateway, 'stdout', buf.toString()));
     child.stderr?.on('data', (buf) => appendGatewayLog(gateway, 'stderr', buf.toString()));
@@ -516,6 +685,46 @@ export async function runHermesGatewayPrompt(projectPath, options = {}) {
         throw new Error('Hermes prompt is required.');
     }
 
+    const responsesRequest = makeResponsesRequest({ ...options, input });
+    const responseRun = await callGateway(gateway, '/v1/responses', {
+        method: 'POST',
+        body: JSON.stringify(responsesRequest),
+        timeoutMs: options.responsesTimeoutMs || options.timeoutMs || RUN_TIMEOUT_MS,
+    }).catch((error) => {
+        if (!isGatewayRunning(gateway)) {
+            throw new Error(gatewayExitMessage(gateway));
+        }
+        throw error;
+    });
+
+    if (!isGatewayRunning(gateway)) {
+        throw new Error(gatewayExitMessage(gateway));
+    }
+
+    if (responseRun.ok) {
+        const status = extractRunStatus(responseRun.body) || 'completed';
+        const message = extractResponsesOutput(responseRun.body);
+        return {
+            ok: status === 'completed' || status === 'succeeded',
+            projectPath: gateway.projectPath,
+            baseUrl: gateway.baseUrl,
+            sessionId: options.sessionId || responsesRequest.conversation || null,
+            runId: null,
+            responseId: responseRun.body?.id || null,
+            status,
+            message,
+            error: (status === 'completed' || status === 'succeeded') ? null : extractTextFromValue(responseRun.body?.error) || message || 'Hermes response failed.',
+            raw: responseRun.body,
+            transport: 'responses',
+            endpoint: '/v1/responses',
+            httpStatus: responseRun.status,
+        };
+    }
+
+    if (responseRun.status && responseRun.status !== 404 && responseRun.status !== 405) {
+        throw new Error(`Hermes /v1/responses failed with HTTP ${responseRun.status}: ${JSON.stringify(responseRun.body)}`);
+    }
+
     const chatRequest = makeChatCompletionRequest({ ...options, input });
     const chat = await callGateway(gateway, '/v1/chat/completions', {
         method: 'POST',
@@ -544,6 +753,8 @@ export async function runHermesGatewayPrompt(projectPath, options = {}) {
             message,
             raw: chat.body,
             transport: 'chat.completions',
+            endpoint: '/v1/chat/completions',
+            httpStatus: chat.status,
         };
     }
 
@@ -584,6 +795,8 @@ export async function runHermesGatewayPrompt(projectPath, options = {}) {
             message: extractRunOutput(create.body),
             raw: create.body,
             transport: 'runs',
+            endpoint: '/v1/runs',
+            httpStatus: create.status,
         };
     }
 
@@ -623,6 +836,8 @@ export async function runHermesGatewayPrompt(projectPath, options = {}) {
         error: status === 'completed' ? null : extractTextFromValue(latest?.error) || message || 'Hermes run failed.',
         raw: latest,
         transport: 'runs',
+        endpoint: '/v1/runs',
+        httpStatus: create.status,
     };
 }
 

package/server/services/hermes-install-jobs.js

@@ -12,6 +12,7 @@ const POSIX_INSTALLER_URL = 'https://raw.githubusercontent.com/NousResearch/herm
 const WINDOWS_INSTALLER_URL = 'https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1';
 const FINISHED_TTL_MS = 10 * 60 * 1000;
 const HARD_TIMEOUT_MS = 20 * 60 * 1000;
+const HERMES_VERSION_TIMEOUT_MS = 20 * 1000;
 const jobs = new Map();
 
 function pathSeparator() {
@@ -125,13 +126,22 @@ function pushHermesCommandFiles(candidates, dir) {
     }
 }
 
+function hermesVersionTimeoutMs(env = process.env) {
+    const configured = Number(env.HERMES_VERSION_TIMEOUT_MS);
+    if (Number.isFinite(configured) && configured >= 1000) {
+        return configured;
+    }
+
+    return HERMES_VERSION_TIMEOUT_MS;
+}
+
 function runHermesVersion(candidate, env) {
     try {
         const result = spawn.sync(candidate, ['--version'], {
             encoding: 'utf8',
             env,
             stdio: ['ignore', 'pipe', 'pipe'],
-            timeout: 5000,
+            timeout: hermesVersionTimeoutMs(env),
             windowsHide: true,
         });
         if (result.error || result.status !== 0) {
@@ -144,8 +154,40 @@ function runHermesVersion(candidate, env) {
     }
 }
 
-export function isUsableHermesCommand(candidate, env = process.env) {
-    return runHermesVersion(candidate, buildHermesEnv(env)).ok;
+function isHermesSmokeCommandOutput(output) {
+    return /Hermes Agent v0\.0\.0\s+smoke/i.test(String(output || ''))
+        || /pixcode-hermes-(?:chat-api|smoke)/i.test(String(output || ''));
+}
+
+function isExplicitHermesCliPath(candidate, env = process.env) {
+    if (!candidate || !env.HERMES_CLI_PATH || !path.isAbsolute(candidate)) return false;
+    try {
+        return path.resolve(candidate) === path.resolve(env.HERMES_CLI_PATH);
+    } catch {
+        return false;
+    }
+}
+
+function isTemporaryHermesLauncher(candidate) {
+    if (!candidate || !path.isAbsolute(candidate)) return false;
+    const normalized = path.resolve(candidate);
+    const tempRoot = path.resolve(os.tmpdir());
+    return normalized === tempRoot || normalized.startsWith(`${tempRoot}${path.sep}`);
+}
+
+function shouldRepairHermesLauncher(command, env = process.env, options = {}) {
+    if (options.repairLaunchers === false) return false;
+    if (!command || command === 'hermes') return false;
+    if (isExplicitHermesCliPath(command, env)) return false;
+    if (isTemporaryHermesLauncher(command)) return false;
+    return true;
+}
+
+export function isUsableHermesCommand(candidate, env = process.env, options = {}) {
+    const result = runHermesVersion(candidate, buildHermesEnv(env));
+    if (!result.ok) return false;
+    if (!options.allowSmokeHermes && isHermesSmokeCommandOutput(result.output)) return false;
+    return true;
 }
 
 function isHermesPythonLauncher(candidate) {
@@ -313,8 +355,9 @@ export function hermesCommandCandidates(env = process.env) {
     return [...new Set(candidates.filter(Boolean))];
 }
 
-export function readHermesInstallStatus(env = process.env) {
+export function readHermesInstallStatus(env = process.env, options = {}) {
     const hermesEnv = buildHermesEnv(env);
+    const rejected = [];
 
     for (const candidate of hermesCommandCandidates(hermesEnv)) {
         const isBareCommand = candidate === 'hermes';
@@ -324,8 +367,16 @@ export function readHermesInstallStatus(env = process.env) {
 
         const result = runHermesVersion(candidate, hermesEnv);
         if (result.ok) {
-            repairHermesCommandLaunchers(candidate, hermesEnv);
             const version = formatHermesVersionOutput(result.output);
+            if (!options.allowSmokeHermes && isHermesSmokeCommandOutput(result.output)) {
+                rejected.push(`${candidate} (${version || 'smoke-test Hermes launcher'})`);
+                continue;
+            }
+
+            if (shouldRepairHermesLauncher(candidate, hermesEnv, options)) {
+                repairHermesCommandLaunchers(candidate, hermesEnv);
+            }
+
             return {
                 installed: true,
                 command: candidate,
@@ -339,7 +390,9 @@ export function readHermesInstallStatus(env = process.env) {
         installed: false,
         command: null,
         version: null,
-        error: 'Hermes Agent CLI is not installed or is not on PATH.',
+        error: rejected.length > 0
+            ? `Only smoke-test Hermes launchers were found and rejected: ${rejected.join(', ')}. Install or repair Hermes Agent.`
+            : 'Hermes Agent CLI is not installed or is not on PATH.',
     };
 }