@pixelbyte-software/pixcode 1.49.10 → 1.49.11

package/scripts/hermes/pixcode-mcp-server.mjs

@@ -1,8 +1,12 @@
 #!/usr/bin/env node
+import path from 'node:path';
 import readline from 'node:readline';
+import { fileURLToPath } from 'node:url';
 
 const baseUrl = (process.env.PIXCODE_BASE_URL || '').replace(/\/$/, '');
 const apiKey = process.env.PIXCODE_API_KEY || '';
+const appRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const mcpServerPath = path.join(appRoot, 'scripts', 'hermes', 'pixcode-mcp-server.mjs');
 
 const tools = [
   {
@@ -133,6 +137,30 @@ async function pixcodeFetch(endpoint, options = {}) {
   return body;
 }
 
+async function readProviderStatus(provider) {
+  const body = await pixcodeFetch(`/api/providers/${encodeURIComponent(provider)}/auth/status?refresh=1`);
+  return body?.data ?? body;
+}
+
+async function ensureProviderPixcodeMcp(provider, projectPath) {
+  const body = await pixcodeFetch(`/api/providers/${encodeURIComponent(provider)}/mcp/servers`, {
+    method: 'POST',
+    body: JSON.stringify({
+      name: 'pixcode',
+      transport: 'stdio',
+      scope: 'project',
+      workspacePath: projectPath || process.cwd(),
+      command: process.execPath,
+      args: [mcpServerPath],
+      env: {
+        PIXCODE_BASE_URL: baseUrl,
+        PIXCODE_API_KEY: apiKey,
+      },
+    }),
+  });
+  return body?.data?.server ?? body?.server ?? body;
+}
+
 async function callTool(name, args = {}) {
   if (name === 'pixcode_list_projects') {
     const projects = await pixcodeFetch('/api/projects');
@@ -147,20 +175,50 @@ async function callTool(name, args = {}) {
 
   if (name === 'pixcode_get_provider_status') {
     const provider = String(args.provider || '');
-    const body = await pixcodeFetch(`/api/providers/${encodeURIComponent(provider)}/auth/status?refresh=1`);
-    return textResult(JSON.stringify(body?.data ?? body, null, 2));
+    const status = await readProviderStatus(provider);
+    return textResult(JSON.stringify(status, null, 2));
   }
 
   if (name === 'pixcode_open_cli_terminal') {
+    const provider = String(args.provider || '');
+    const projectPath = typeof args.projectPath === 'string' && args.projectPath.trim()
+      ? args.projectPath.trim()
+      : null;
+    const status = await readProviderStatus(provider);
+    if (status?.installed === false) {
+      return textResult(JSON.stringify({
+        launched: false,
+        provider,
+        reason: 'not_installed',
+        message: `${provider} CLI is not installed. Install it in Pixcode before launching a terminal.`,
+        status,
+      }, null, 2));
+    }
+
+    let mcpConfigured = false;
+    let mcpError = null;
+    try {
+      await ensureProviderPixcodeMcp(provider, projectPath);
+      mcpConfigured = true;
+    } catch (error) {
+      mcpError = error instanceof Error ? error.message : String(error);
+    }
+
     const body = await pixcodeFetch('/api/orchestration/hermes/terminal-launches', {
       method: 'POST',
       body: JSON.stringify({
-        provider: args.provider,
-        projectPath: args.projectPath || null,
+        provider,
+        projectPath,
         prompt: args.prompt || null,
       }),
     });
-    return textResult(JSON.stringify(body?.event ?? body, null, 2));
+    return textResult(JSON.stringify({
+      launched: true,
+      pixcodeMcpConfigured: mcpConfigured,
+      pixcodeMcpError: mcpError,
+      event: body?.event ?? body,
+      status,
+    }, null, 2));
   }
 
   if (name === 'pixcode_get_hermes_gateway_status') {

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

@@ -0,0 +1,104 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  ensureHermesGateway,
+  stopHermesGateway,
+} from '../../server/services/hermes-gateway.js';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'pixcode-hermes-persist-'));
+const fakeHermes = path.join(tempRoot, 'hermes');
+const projectPath = path.join(tempRoot, 'project');
+const hermesHome = path.join(tempRoot, 'home');
+const startCountFile = path.join(tempRoot, 'starts.txt');
+const failProbeFile = path.join(tempRoot, 'fail-probe');
+
+await fs.mkdir(projectPath, { recursive: true });
+await fs.writeFile(fakeHermes, `#!/usr/bin/env node
+import fs from 'node:fs';
+import http from 'node:http';
+
+if (process.argv.includes('--version')) {
+  console.log('Hermes Agent v0.0.0 smoke');
+  process.exit(0);
+}
+
+fs.appendFileSync(${JSON.stringify(startCountFile)}, '1\\n');
+
+const host = process.env.API_SERVER_HOST || '127.0.0.1';
+const port = Number(process.env.API_SERVER_PORT || 8642);
+const key = process.env.API_SERVER_KEY || '';
+const failProbeFile = ${JSON.stringify(failProbeFile)};
+
+const server = http.createServer(async (req, res) => {
+  const url = new URL(req.url || '/', 'http://127.0.0.1');
+  res.setHeader('content-type', 'application/json');
+  if (url.pathname !== '/health' && req.headers.authorization !== \`Bearer \${key}\`) {
+    res.statusCode = 401;
+    res.end(JSON.stringify({ error: 'bad auth' }));
+    return;
+  }
+  if (req.method === 'GET' && url.pathname === '/health') {
+    res.end(JSON.stringify({ ok: true }));
+    return;
+  }
+  if (req.method === 'GET' && url.pathname === '/v1/capabilities') {
+    if (fs.existsSync(failProbeFile)) {
+      res.statusCode = 503;
+      res.end(JSON.stringify({ error: 'temporary probe failure' }));
+      return;
+    }
+    res.end(JSON.stringify({ capabilities: ['chat'] }));
+    return;
+  }
+  if (req.method === 'GET' && url.pathname === '/v1/models') {
+    res.end(JSON.stringify({ data: [{ id: 'hermes-agent' }] }));
+    return;
+  }
+  res.statusCode = 404;
+  res.end(JSON.stringify({ error: url.pathname }));
+});
+
+server.listen(port, host);
+`, { mode: 0o755 });
+
+process.env.HERMES_CLI_PATH = fakeHermes;
+
+try {
+  const first = await ensureHermesGateway({
+    appRoot: repoRoot,
+    projectPath,
+    hermesHome,
+    pixcodeBaseUrl: 'http://127.0.0.1:9',
+    pixcodeApiKey: 'px_persist_smoke_key',
+    port: 18772,
+    allowSmokeHermes: true,
+    repairLaunchers: false,
+  });
+  assert.equal(first.running, true, 'first gateway should start');
+
+  await fs.writeFile(failProbeFile, '1');
+  const second = await ensureHermesGateway({
+    appRoot: repoRoot,
+    projectPath,
+    hermesHome,
+    pixcodeBaseUrl: 'http://127.0.0.1:9',
+    pixcodeApiKey: 'px_persist_smoke_key',
+    port: 18772,
+    allowSmokeHermes: true,
+    repairLaunchers: false,
+  });
+
+  const starts = (await fs.readFile(startCountFile, 'utf8')).trim().split('\\n').filter(Boolean).length;
+  assert.equal(starts, 1, 'existing Hermes gateway must not be killed and relaunched for a transient probe failure');
+  assert.equal(second.baseUrl, first.baseUrl, 'existing Hermes gateway base URL should be reused');
+  assert.equal(second.running, true, 'existing Hermes gateway should still be reported as running');
+  console.log('hermes gateway persistence smoke passed');
+} finally {
+  stopHermesGateway(projectPath);
+  delete process.env.HERMES_CLI_PATH;
+}

package/scripts/smoke/hermes-mcp-pixcode-roundtrip.mjs

@@ -7,6 +7,8 @@ import { fileURLToPath } from 'node:url';
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 const apiKey = 'px_smoke_key';
 const seen = [];
+const providerMcpUpserts = [];
+const terminalLaunches = [];
 
 function readJson(req) {
   return new Promise((resolve, reject) => {
@@ -50,6 +52,19 @@ const server = createServer(async (req, res) => {
     return;
   }
 
+  if (req.method === 'GET' && url.pathname === '/api/providers/qwen/auth/status') {
+    res.end(JSON.stringify({ data: { provider: 'qwen', installed: false, authenticated: false, error: 'Qwen Code CLI is not installed' } }));
+    return;
+  }
+
+  if (req.method === 'POST' && url.pathname === '/api/providers/codex/mcp/servers') {
+    const body = await readJson(req);
+    providerMcpUpserts.push(body);
+    res.statusCode = 201;
+    res.end(JSON.stringify({ data: { server: { provider: 'codex', name: body.name, scope: body.scope, transport: body.transport } } }));
+    return;
+  }
+
   if (req.method === 'GET' && url.pathname === '/api/orchestration/hermes/gateway/status') {
     res.end(JSON.stringify({ running: true, baseUrl: 'http://127.0.0.1:8642', projectPath: '/root/pixcode' }));
     return;
@@ -71,6 +86,7 @@ const server = createServer(async (req, res) => {
 
   if (req.method === 'POST' && url.pathname === '/api/orchestration/hermes/terminal-launches') {
     const body = await readJson(req);
+    terminalLaunches.push(body);
     res.statusCode = 201;
     res.end(JSON.stringify({
       event: {
@@ -170,6 +186,17 @@ try {
     arguments: { provider: 'codex', projectPath: '/root/pixcode', prompt: 'smoke' },
   });
   assert.match(launch.content[0].text, /hermes-mcp/, 'terminal launch should roundtrip through Pixcode API');
+  assert.match(launch.content[0].text, /"pixcodeMcpConfigured": true/, 'terminal launch should configure Pixcode MCP for the selected provider first');
+  assert.equal(providerMcpUpserts.length, 1, 'Codex launch should upsert a project-scoped Pixcode MCP server');
+  assert.equal(providerMcpUpserts[0].name, 'pixcode', 'Provider MCP server should be named pixcode');
+
+  const blockedLaunch = await callMcp(child, 'tools/call', {
+    name: 'pixcode_open_cli_terminal',
+    arguments: { provider: 'qwen', projectPath: '/root/pixcode', prompt: 'smoke' },
+  });
+  assert.match(blockedLaunch.content[0].text, /"launched": false/, 'uninstalled providers should not create terminal launches');
+  assert.match(blockedLaunch.content[0].text, /"reason": "not_installed"/, 'uninstalled provider response should explain the block');
+  assert.equal(terminalLaunches.length, 1, 'Only the installed Codex provider should be launched');
 
   assert(seen.every((entry) => entry.auth === `Bearer ${apiKey}`), 'all MCP calls should use the Pixcode bearer key');
   console.log('hermes MCP Pixcode roundtrip smoke passed');

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

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 
 import {
@@ -9,11 +10,14 @@ import {
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 const projectPath = path.resolve(process.argv[2] || repoRoot);
+const hermesHome = process.env.PIXCODE_HERMES_LIVE_HOME
+  || path.join(os.tmpdir(), `pixcode-hermes-live-${process.getuid?.() ?? 'user'}`);
 
 try {
   const gateway = await ensureHermesGateway({
     appRoot: repoRoot,
     projectPath,
+    hermesHome,
     pixcodeBaseUrl: 'http://127.0.0.1:9',
     pixcodeApiKey: 'px_live_chat_smoke_key',
     port: Number(process.env.PIXCODE_HERMES_LIVE_CHAT_PORT || 18652),

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

@@ -16,7 +16,12 @@ assert.match(service, /export function stopHermesGateway/, 'Pixcode should be ab
 assert.match(service, /\/v1\/chat\/completions/, 'Hermes UI chat should use the documented OpenAI-compatible chat completions endpoint first.');
 assert.match(service, /\/v1\/responses/, 'Hermes UI chat should use the stateful OpenAI-compatible responses endpoint before legacy chat fallback.');
 assert.match(service, /transport:\s*'responses'/, 'Hermes REST responses should report their transport for terminal proof output.');
-assert.match(service, /gatewayArgs[\s\S]+\['gateway', 'run', '--replace'\]/, 'Pixcode should start Hermes gateway in replace mode so an existing gateway does not crash REST chat.');
+assert.match(service, /resolveHermesGatewayHome/, 'Hermes REST gateway should run from a Pixcode-managed Hermes profile.');
+assert.match(service, /seedHermesGatewayHome/, 'Hermes REST gateway should seed the managed profile from the user Hermes profile.');
+assert.match(service, /PIXCODE_HERMES_GATEWAY_HOME/, 'Hermes REST gateway profile path should be overrideable for tests and advanced installs.');
+assert.match(service, /PIXCODE_MANAGED_HERMES_ENV_PREFIXES/, 'Managed Hermes gateway profile should strip messaging platform env vars.');
+assert.match(service, /copyHermesProfileEnv/, 'Managed Hermes gateway profile should copy a sanitized .env instead of raw platform credentials.');
+assert.match(service, /gatewayArgs[\s\S]+\['gateway', 'run', '--replace'\]/, 'Pixcode can use replace mode safely inside its managed Hermes gateway profile.');
 assert.match(service, /gatewayExitMessage/, 'Hermes gateway failures should include recent stderr/stdout instead of only exit code 1.');
 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.');
@@ -35,11 +40,14 @@ assert.match(routes, /router\.post\('\/gateway\/stop'/, 'Hermes router should ex
 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(routes, /runHermesGatewayPrompt/, 'Hermes router should send chat prompts through the REST gateway service.');
+assert.match(routes, /resolveHermesMcpBaseUrl/, 'Hermes MCP should be configured against the local Pixcode API URL instead of the browser request host.');
+assert.match(routes, /probeExisting:\s*false/, 'Hermes chat should reuse a running gateway instead of killing it on a transient probe failure.');
 
 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(configureMcp, /mcp-pixcode/, 'Hermes MCP config should enable the Pixcode MCP toolset for the real CLI.');
 
 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.');

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

@@ -65,10 +65,10 @@ 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.match(workbench, /HermesTerminalTranscript/, 'Hermes REST panel should render as a terminal transcript, not chat bubbles.');
-assert.match(workbench, /REST POST \//, 'Hermes terminal transcript should show the REST endpoint used for each reply.');
+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.');
@@ -89,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.');
@@ -118,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,
     });