admin/Hermes-ui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add Hermes Agent package fallback and xAI OAuth (#808)

Browse Source
This commit is contained in:
ekko
2026-05-17 09:45:56 +08:00
committed by GitHub
parent 0c2bafc619
commit 53f0301da4
22 changed files with 871 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/server/src/controllers/hermes/providers.ts
+6 -1
View File
@@ -6,7 +6,8 @@ import { updateConfigYaml, saveEnvValue, PROVIDER_ENV_MAP } from '../../services
import { PROVIDER_PRESETS } from '../../shared/providers'
import { logger } from '../../services/logger'
const OPTIONAL_API_KEY_PROVIDERS = new Set(['cliproxyapi'])
const OPTIONAL_API_KEY_PROVIDERS = new Set(['cliproxyapi', 'xai-oauth'])
const DIRECT_CONFIG_PROVIDERS = new Set(['xai-oauth'])
async function clearStoredAuthProvider(poolKey: string) {
try {
@@ -82,6 +83,10 @@ export async function create(ctx: any) {
if (PROVIDER_ENV_MAP[poolKey].base_url_env) { await saveEnvValue(PROVIDER_ENV_MAP[poolKey].base_url_env, base_url) }
config.model.default = model
config.model.provider = poolKey
} else if (DIRECT_CONFIG_PROVIDERS.has(poolKey)) {
if (PROVIDER_ENV_MAP[poolKey].base_url_env) { await saveEnvValue(PROVIDER_ENV_MAP[poolKey].base_url_env, base_url) }
config.model.default = model
config.model.provider = poolKey
} else {
if (!Array.isArray(config.custom_providers)) { config.custom_providers = [] }
const existing = (config.custom_providers as any[]).find(
packages/server/src/controllers/hermes/xai-auth.ts
+334
View File
@@ -0,0 +1,334 @@
import { createHash, randomBytes, randomUUID } from 'crypto'
import { createServer, type Server } from 'http'
import { request as httpsRequest, type RequestOptions } from 'https'
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
import { URL } from 'url'
import { getActiveAuthPath } from '../../services/hermes/hermes-profile'
import { logger } from '../../services/logger'
import { updateConfigYaml } from '../../services/config-helpers'
const XAI_OAUTH_ISSUER = 'https://auth.x.ai'
const XAI_OAUTH_DISCOVERY_URL = `${XAI_OAUTH_ISSUER}/.well-known/openid-configuration`
const XAI_OAUTH_CLIENT_ID = 'b1a00492-073a-47ea-816f-4c329264a828'
const XAI_OAUTH_SCOPE = 'openid profile email offline_access grok-cli:access api:access'
const XAI_DEFAULT_BASE_URL = 'https://api.x.ai/v1'
const XAI_REDIRECT_HOST = '127.0.0.1'
const XAI_REDIRECT_PORT = 56121
const XAI_REDIRECT_PATH = '/callback'
const POLL_MAX_DURATION = 15 * 60 * 1000
interface XaiSession {
id: string
status: 'pending' | 'approved' | 'expired' | 'error'
authorizeUrl: string
redirectUri: string
codeVerifier: string
state: string
tokenEndpoint: string
discovery: Record<string, string>
server: Server
error?: string
createdAt: number
}
interface AuthJson {
version?: number
active_provider?: string
providers?: Record<string, any>
credential_pool?: Record<string, any[]>
updated_at?: string
}
const sessions = new Map<string, XaiSession>()
function cleanupExpiredSessions() {
const now = Date.now()
sessions.forEach((session, id) => {
if (now - session.createdAt > POLL_MAX_DURATION + 60000) {
closeServer(session)
sessions.delete(id)
}
})
}
function closeServer(session: XaiSession) {
try { session.server.close() } catch {}
}
function base64Url(input: Buffer): string {
return input.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
}
function makeCodeVerifier(): string {
return base64Url(randomBytes(48))
}
function makeCodeChallenge(verifier: string): string {
return base64Url(createHash('sha256').update(verifier).digest())
}
function validateXaiEndpoint(raw: string, field: string): string {
const url = new URL(raw)
if (url.protocol !== 'https:') throw new Error(`xAI discovery returned non-HTTPS ${field}`)
const host = url.hostname.toLowerCase()
if (host !== 'x.ai' && !host.endsWith('.x.ai')) {
throw new Error(`xAI discovery ${field} host is not on x.ai`)
}
return raw
}
async function requestJson(url: string, options: {
method?: string
headers?: Record<string, string>
body?: string
timeoutMs?: number
} = {}): Promise<{ status: number; text: string; json: any }> {
const target = new URL(url)
const timeoutMs = options.timeoutMs || 15000
const body = options.body || ''
const headers: Record<string, string> = {
Accept: 'application/json',
...(options.headers || {}),
}
if (body && !headers['Content-Length']) headers['Content-Length'] = Buffer.byteLength(body).toString()
const requestOptions: RequestOptions = {
hostname: target.hostname,
port: Number(target.port || 443),
path: `${target.pathname}${target.search}`,
method: options.method || 'GET',
headers,
timeout: timeoutMs,
}
return await new Promise((resolve, reject) => {
const req = httpsRequest(requestOptions, (res) => {
const chunks: Buffer[] = []
res.on('data', chunk => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)))
res.on('end', () => {
const text = Buffer.concat(chunks).toString('utf-8')
let json: any = null
try { json = text ? JSON.parse(text) : null } catch {}
resolve({ status: res.statusCode || 0, text, json })
})
})
req.once('timeout', () => req.destroy(new Error(`Request timed out after ${timeoutMs}ms`)))
req.once('error', reject)
if (body) req.write(body)
req.end()
})
}
async function discoverXai(): Promise<Record<string, string>> {
const res = await requestJson(XAI_OAUTH_DISCOVERY_URL, { timeoutMs: 15000 })
if (res.status < 200 || res.status >= 300) throw new Error(`xAI discovery failed: ${res.status}`)
const payload = res.json as Record<string, unknown>
if (!payload || typeof payload !== 'object') throw new Error('xAI discovery returned invalid JSON')
const authorizationEndpoint = String(payload.authorization_endpoint || '').trim()
const tokenEndpoint = String(payload.token_endpoint || '').trim()
if (!authorizationEndpoint || !tokenEndpoint) throw new Error('xAI discovery missing endpoints')
return {
authorization_endpoint: validateXaiEndpoint(authorizationEndpoint, 'authorization_endpoint'),
token_endpoint: validateXaiEndpoint(tokenEndpoint, 'token_endpoint'),
}
}
function loadAuthJson(authPath: string): AuthJson {
try { return JSON.parse(readFileSync(authPath, 'utf-8')) as AuthJson } catch { return { version: 1 } }
}
function saveAuthJson(authPath: string, data: AuthJson): void {
data.updated_at = new Date().toISOString()
const dir = authPath.substring(0, authPath.lastIndexOf('/'))
if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
writeFileSync(authPath, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 })
}
async function saveTokens(session: XaiSession, tokenData: any) {
const accessToken = String(tokenData.access_token || '').trim()
const refreshToken = String(tokenData.refresh_token || '').trim()
if (!accessToken || !refreshToken) throw new Error('xAI token response missing access_token or refresh_token')
const lastRefresh = new Date().toISOString()
const tokens = {
access_token: accessToken,
refresh_token: refreshToken,
id_token: String(tokenData.id_token || '').trim(),
expires_in: tokenData.expires_in,
token_type: String(tokenData.token_type || 'Bearer').trim() || 'Bearer',
}
const authPath = getActiveAuthPath()
const auth = loadAuthJson(authPath)
if (!auth.providers) auth.providers = {}
auth.providers['xai-oauth'] = {
tokens,
last_refresh: lastRefresh,
auth_mode: 'oauth_pkce',
discovery: session.discovery,
redirect_uri: session.redirectUri,
}
if (!auth.credential_pool) auth.credential_pool = {}
auth.credential_pool['xai-oauth'] = [{
id: `xai-oauth-${Date.now()}`,
label: 'xAI Grok OAuth (SuperGrok Subscription)',
auth_type: 'oauth',
source: 'loopback_pkce',
priority: 0,
access_token: accessToken,
refresh_token: refreshToken,
base_url: XAI_DEFAULT_BASE_URL,
}]
saveAuthJson(authPath, auth)
await updateConfigYaml((config) => {
if (typeof config.model !== 'object' || config.model === null) config.model = {}
config.model.provider = 'xai-oauth'
config.model.default = config.model.default || 'grok-4.3'
delete config.model.base_url
delete config.model.api_key
return config
})
}
async function exchangeCode(session: XaiSession, code: string) {
const res = await requestJson(session.tokenEndpoint, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
body: new URLSearchParams({
grant_type: 'authorization_code',
code,
redirect_uri: session.redirectUri,
client_id: XAI_OAUTH_CLIENT_ID,
code_verifier: session.codeVerifier,
}).toString(),
timeoutMs: 20000,
})
if (res.status < 200 || res.status >= 300) {
throw new Error(`xAI token exchange failed: ${res.status}${res.text ? ` ${res.text}` : ''}`)
}
await saveTokens(session, res.json)
}
function startCallbackServer(sessionId: string, preferredPort = XAI_REDIRECT_PORT): Promise<{ server: Server; redirectUri: string }> {
return new Promise((resolve, reject) => {
const server = createServer((req, res) => {
const session = sessions.get(sessionId)
const url = new URL(req.url || '/', `http://${XAI_REDIRECT_HOST}`)
if (req.method === 'OPTIONS') {
res.writeHead(204, {
'Access-Control-Allow-Origin': 'https://auth.x.ai',
'Access-Control-Allow-Methods': 'GET, OPTIONS',
'Access-Control-Allow-Headers': 'Content-Type',
})
res.end()
return
}
if (!session || url.pathname !== XAI_REDIRECT_PATH) {
res.writeHead(404)
res.end('Not found.')
return
}
res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
res.end('<html><body><h1>xAI authorization received.</h1>You can close this tab.</body></html>')
void (async () => {
try {
const error = url.searchParams.get('error')
if (error) throw new Error(url.searchParams.get('error_description') || error)
if (url.searchParams.get('state') !== session.state) throw new Error('xAI OAuth state mismatch')
const code = url.searchParams.get('code')
if (!code) throw new Error('xAI OAuth callback missing code')
await exchangeCode(session, code)
session.status = 'approved'
closeServer(session)
} catch (err: any) {
logger.error(err, 'xAI OAuth callback failed')
session.status = 'error'
session.error = err?.message || String(err)
closeServer(session)
}
})()
})
server.once('error', (err: any) => {
if (preferredPort !== 0 && err?.code === 'EADDRINUSE') {
startCallbackServer(sessionId, 0).then(resolve, reject)
} else {
reject(err)
}
})
server.listen(preferredPort, XAI_REDIRECT_HOST, () => {
const address = server.address()
const port = typeof address === 'object' && address ? address.port : preferredPort
resolve({ server, redirectUri: `http://${XAI_REDIRECT_HOST}:${port}${XAI_REDIRECT_PATH}` })
})
})
}
export async function start(ctx: any) {
try {
cleanupExpiredSessions()
const sessionId = randomUUID()
const discovery = await discoverXai()
const codeVerifier = makeCodeVerifier()
const state = randomUUID().replace(/-/g, '')
const nonce = randomUUID().replace(/-/g, '')
const { server, redirectUri } = await startCallbackServer(sessionId)
const authorizeUrl = `${discovery.authorization_endpoint}?${new URLSearchParams({
response_type: 'code',
client_id: XAI_OAUTH_CLIENT_ID,
redirect_uri: redirectUri,
scope: XAI_OAUTH_SCOPE,
code_challenge: makeCodeChallenge(codeVerifier),
code_challenge_method: 'S256',
state,
nonce,
plan: 'generic',
referrer: 'hermes-web-ui',
}).toString()}`
sessions.set(sessionId, {
id: sessionId,
status: 'pending',
authorizeUrl,
redirectUri,
codeVerifier,
state,
tokenEndpoint: discovery.token_endpoint,
discovery,
server,
createdAt: Date.now(),
})
ctx.body = { session_id: sessionId, authorization_url: authorizeUrl, expires_in: 900 }
} catch (err: any) {
ctx.status = 500
ctx.body = { error: err.message }
}
}
export async function poll(ctx: any) {
const session = sessions.get(ctx.params.sessionId)
if (!session) { ctx.status = 404; ctx.body = { error: 'Session not found' }; return }
if (Date.now() - session.createdAt > POLL_MAX_DURATION) {
session.status = 'expired'
closeServer(session)
}
ctx.body = { status: session.status, error: session.error || null }
}
export async function status(ctx: any) {
try {
const auth = loadAuthJson(getActiveAuthPath())
const provider = auth.providers?.['xai-oauth']
const pool = auth.credential_pool?.['xai-oauth']
ctx.body = {
authenticated: !!(
provider?.tokens?.access_token ||
provider?.access_token ||
(Array.isArray(pool) && pool.some((entry: any) => entry?.access_token))
),
last_refresh: provider?.last_refresh,
}
} catch {
ctx.body = { authenticated: false }
}
}
packages/server/src/routes/hermes/xai-auth.ts
+8
View File
@@ -0,0 +1,8 @@
import Router from '@koa/router'
import * as ctrl from '../../controllers/hermes/xai-auth'
export const xaiAuthRoutes = new Router()
xaiAuthRoutes.post('/api/hermes/auth/xai/start', ctrl.start)
xaiAuthRoutes.get('/api/hermes/auth/xai/poll/:sessionId', ctrl.poll)
xaiAuthRoutes.get('/api/hermes/auth/xai/status', ctrl.status)
packages/server/src/routes/index.ts
+2
View File
@@ -20,6 +20,7 @@ import { logRoutes } from './hermes/logs'
import { codexAuthRoutes } from './hermes/codex-auth'
import { nousAuthRoutes } from './hermes/nous-auth'
import { copilotAuthRoutes } from './hermes/copilot-auth'
import { xaiAuthRoutes } from './hermes/xai-auth'
import { gatewayRoutes } from './hermes/gateways'
import { weixinRoutes } from './hermes/weixin'
import { fileRoutes } from './hermes/files'
@@ -62,6 +63,7 @@ export function registerRoutes(app: any, requireAuth: (ctx: Context, next: Next)
app.use(codexAuthRoutes.routes())
app.use(nousAuthRoutes.routes())
app.use(copilotAuthRoutes.routes())
app.use(xaiAuthRoutes.routes())
app.use(gatewayRoutes.routes())
app.use(weixinRoutes.routes())
app.use(groupChatRoutes.routes()) // Must be before proxy
packages/server/src/services/config-helpers.ts
+1
View File
@@ -22,6 +22,7 @@ export const PROVIDER_ENV_MAP: Record<string, { api_key_env: string; base_url_en
'alibaba-coding-plan': { api_key_env: 'ALIBABA_CODING_PLAN_API_KEY', base_url_env: 'ALIBABA_CODING_PLAN_BASE_URL' },
anthropic: { api_key_env: 'ANTHROPIC_API_KEY', base_url_env: '' },
xai: { api_key_env: 'XAI_API_KEY', base_url_env: '' },
'xai-oauth': { api_key_env: '', base_url_env: '' },
xiaomi: { api_key_env: 'XIAOMI_API_KEY', base_url_env: '' },
'xiaomi-token-plan': { api_key_env: '', base_url_env: '' },
gemini: { api_key_env: 'GEMINI_API_KEY', base_url_env: '' },
packages/server/src/services/hermes/agent-bridge/README.md
+9 -2
View File
@@ -1,7 +1,7 @@
# Agent Bridge
Optional backend-side bridge for talking to `~/.hermes/hermes-agent` by
instantiating `run_agent.AIAgent` directly in a Python process.
Optional backend-side bridge for talking to Hermes Agent by instantiating
`run_agent.AIAgent` directly in a Python process.
This is intentionally separate from the current Web UI chat path.
@@ -37,6 +37,7 @@ The service discovers Hermes Agent in this order:
3. the installed `hermes` command path
4. current working directory and parent directories
5. common locations such as `~/.hermes/hermes-agent`, `~/hermes-agent`, and `/opt/hermes-agent`
6. the `hermes-agent` package installed in the selected Python environment
Hermes home is resolved from `--hermes-home`, `HERMES_HOME`, then `~/.hermes`.
@@ -54,6 +55,12 @@ python packages/server/src/services/hermes/agent-bridge/hermes_bridge.py \
--hermes-home ~/.hermes
```
If no source checkout containing `run_agent.py` is found, the bridge falls back
to importing `run_agent` from the Python environment. This supports package
installs such as `pip install hermes-agent`. The Node manager prefers the source
checkout's virtualenv when a checkout exists, then the Python interpreter from
the installed `hermes` command, then the system Python.
The socket transport uses Python and Node standard libraries. No ZMQ dependency
is required.
packages/server/src/services/hermes/agent-bridge/hermes_bridge.py
+26 -9
View File
@@ -11,6 +11,7 @@ from __future__ import annotations
import argparse
import copy
import importlib.util
import json
import os
import queue
@@ -116,10 +117,17 @@ def _candidate_agent_roots(raw: str | None = None) -> list[Path]:
return unique
def _discover_agent_root(raw: str | None = None) -> Path:
def _find_agent_root(raw: str | None = None) -> Path | None:
for candidate in _candidate_agent_roots(raw):
if (candidate / "run_agent.py").exists():
return candidate
return None
def _discover_agent_root(raw: str | None = None) -> Path:
root = _find_agent_root(raw)
if root is not None:
return root
attempted = ", ".join(str(path) for path in _candidate_agent_roots(raw))
raise RuntimeError(
"hermes-agent run_agent.py not found. Pass --agent-root or set "
@@ -154,8 +162,8 @@ def _jsonable(value: Any) -> Any:
return str(value)
def _agent_root() -> Path:
return _discover_agent_root(os.environ.get("HERMES_AGENT_ROOT"))
def _agent_root() -> Path | None:
return _find_agent_root(os.environ.get("HERMES_AGENT_ROOT"))
def _hermes_home() -> Path:
@@ -216,7 +224,11 @@ def _profile_dotenv_keys() -> set[str]:
def _set_path_env(agent_root: str | None = None, hermes_home: str | None = None) -> None:
os.environ["HERMES_AGENT_ROOT"] = str(_discover_agent_root(agent_root))
resolved_root = _discover_agent_root(agent_root) if agent_root else _find_agent_root()
if resolved_root is not None:
os.environ["HERMES_AGENT_ROOT"] = str(resolved_root)
else:
os.environ.pop("HERMES_AGENT_ROOT", None)
resolved_home = _discover_hermes_home(hermes_home)
os.environ["HERMES_HOME"] = str(resolved_home)
os.environ["HERMES_AGENT_BRIDGE_BASE_HOME"] = str(_normalize_base_home(resolved_home))
@@ -224,11 +236,16 @@ def _set_path_env(agent_root: str | None = None, hermes_home: str | None = None)
def _ensure_agent_imports() -> None:
root = _agent_root()
if not (root / "run_agent.py").exists():
raise RuntimeError(f"hermes-agent run_agent.py not found under {root}")
root_s = str(root)
if root_s not in sys.path:
sys.path.insert(0, root_s)
if root is not None:
root_s = str(root)
if root_s not in sys.path:
sys.path.insert(0, root_s)
elif importlib.util.find_spec("run_agent") is None:
raise RuntimeError(
"hermes-agent run_agent.py not found in source locations and the "
"current Python environment cannot import run_agent. Install "
"hermes-agent or pass --agent-root/HERMES_AGENT_ROOT."
)
os.environ.setdefault("HERMES_HOME", str(_hermes_home()))
os.environ.setdefault("HERMES_AGENT_BRIDGE_BASE_HOME", str(_hermes_home()))
packages/server/src/services/hermes/agent-bridge/manager.ts
+6
View File
@@ -47,6 +47,12 @@ function pathCandidates(agentRoot?: string): string[] {
}
function uvCandidates(agentRoot?: string): string[] {
if (!agentRoot) {
return [
process.env.HERMES_AGENT_BRIDGE_UV,
process.env.UV,
].filter((value): value is string => !!value && value.trim().length > 0)
}
return [
process.env.HERMES_AGENT_BRIDGE_UV,
process.env.UV,
packages/server/src/services/hermes/model-context.ts
+1 -1
View File
@@ -1,5 +1,4 @@
import { resolve, join } from 'path'
import { homedir } from 'os'
import { readFileSync, existsSync, statSync } from 'fs'
import yaml from 'js-yaml'
import { PROVIDER_PRESETS } from '../../shared/providers'
@@ -44,6 +43,7 @@ const MODEL_CACHE_PROVIDER_ALIASES: Record<string, string[]> = {
'glm-coding-plan': ['zai-coding-plan'],
'kimi-coding': ['kimi-for-coding'],
'kimi-coding-cn': ['kimi-for-coding'],
'xai-oauth': ['xai'],
}
// --- Config YAML helpers (js-yaml) ---
packages/server/src/services/hermes/plugins.ts
+19 -4
View File
@@ -222,15 +222,31 @@ function extractError(err: any): string {
export async function listHermesPlugins(): Promise<HermesPluginsResponse> {
const command = resolveAgentBridgeCommand()
const agentRoot = command.agentRoot || ''
const env = {
const env: NodeJS.ProcessEnv = {
...process.env,
HERMES_AGENT_ROOT_RESOLVED: agentRoot,
HERMES_HOME: getActiveProfileDir(),
}
if (!agentRoot) {
delete env.PYTHONHOME
delete env.PYTHONPATH
}
const pythonArgs = [
...command.argsPrefix,
...(agentRoot ? ['-I'] : []),
'-c',
PYTHON_BRIDGE,
]
const displayArgs = [
...command.argsPrefix,
...(agentRoot ? ['-I'] : []),
'-c',
'<plugin-discovery>',
].join(' ')
const errors: string[] = []
try {
const { stdout, stderr } = await execFileAsync(command.command, [...command.argsPrefix, '-I', '-c', PYTHON_BRIDGE], {
const { stdout, stderr } = await execFileAsync(command.command, pythonArgs, {
cwd: process.cwd(),
env,
windowsHide: true,
@@ -246,8 +262,7 @@ export async function listHermesPlugins(): Promise<HermesPluginsResponse> {
}
return parsed
} catch (err: any) {
const args = [...command.argsPrefix, '-I', '-c', '<plugin-discovery>'].join(' ')
errors.push(`${command.command} ${args}: ${extractError(err)}`)
errors.push(`${command.command} ${displayArgs}: ${extractError(err)}`)
}
throw new Error(`Failed to discover Hermes plugins.\n${errors.join('\n')}`)
packages/server/src/shared/providers.ts
+13 -6
View File
@@ -120,15 +120,22 @@ export const PROVIDER_PRESETS: ProviderPreset[] = [
builtin: true,
base_url: 'https://api.x.ai/v1',
models: [
'grok-4.3',
'grok-4.20-0309-reasoning',
'grok-4.20-0309-non-reasoning',
'grok-4.20-multi-agent-0309',
],
},
{
label: 'xAI Grok OAuth (SuperGrok Subscription)',
value: 'xai-oauth',
builtin: true,
base_url: 'https://api.x.ai/v1',
models: [
'grok-4.3',
'grok-4.20-0309-reasoning',
'grok-4.20-0309-non-reasoning',
'grok-4.20-multi-agent-0309',
'grok-4-1-fast',
'grok-4-1-fast-non-reasoning',
'grok-4-fast',
'grok-4-fast-non-reasoning',
'grok-4',
'grok-code-fast-1',
],
},
{