Update CLI chat session bridge (#697)

* feat: add CLI chat sessions with Python agent bridge

Introduce a new CLI chat mode that connects Web UI directly to Hermes
Agent's AIAgent via a Python bridge subprocess and Socket.IO, bypassing
the API Server /v1/responses path. Supports streaming, slash commands
(/new, /undo, /retry, /branch, /compress, /save, /title), interrupt,
and steer.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* feat: update CLI chat session bridge

* fix: extend agent bridge startup timeouts

* docs: update bridge chat session design

* feat: align bridge compression and provider registry

* chore: bump version to 0.5.20

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

packages/server/src/controllers/hermes/profiles.ts

@@ -7,6 +7,26 @@ import { SessionDeleter } from '../../services/hermes/session-deleter'
 import { getGatewayManagerInstance } from '../../services/gateway-bootstrap'
 import { logger } from '../../services/logger'
 import { smartCloneCleanup } from '../../services/hermes/profile-credentials'
+import { detectHermesHome } from '../../services/hermes/hermes-path'
+
+function profileExistsForManualSwitch(name: string): boolean {
+  const base = detectHermesHome()
+  if (!name || name === 'default') return true
+  return existsSync(join(base, 'profiles', name, 'config.yaml')) || existsSync(join(base, 'profiles', name))
+}
+
+async function useProfileWithFallback(name: string): Promise<string> {
+  try {
+    return await hermesCli.useProfile(name)
+  } catch (err: any) {
+    if (!profileExistsForManualSwitch(name)) throw err
+
+    const base = detectHermesHome()
+    writeFileSync(join(base, 'active_profile'), `${name}\n`, 'utf-8')
+    logger.warn(err, '[switchProfile] hermes profile use failed; wrote active_profile directly for existing profile "%s"', name)
+    return `Switched to profile ${name}`
+  }
+}
 
 export async function list(ctx: any) {
   try {
@@ -159,7 +179,7 @@ export async function switchProfile(ctx: any) {
     return
   }
   try {
-    const output = await hermesCli.useProfile(name)
+    const output = await useProfileWithFallback(name)
 
     // Verify the active_profile file immediately (Hermes CLI writes synchronously)
     // Quick verification with 2 retries to handle edge cases (filesystem delays, concurrency)
@@ -185,6 +205,16 @@ export async function switchProfile(ctx: any) {
     const mgr = getGatewayManagerInstance()
     if (mgr) { mgr.setActiveProfile(name) }
 
+    // Destroy all bridge sessions so they get recreated with the new profile config
+    try {
+      const { AgentBridgeClient } = await import('../../services/hermes/agent-bridge')
+      const bridge = new AgentBridgeClient()
+      await bridge.destroyAll()
+      logger.info('[switchProfile] destroyed all bridge sessions for profile "%s"', name)
+    } catch (err: any) {
+      logger.warn(err, '[switchProfile] failed to destroy bridge sessions')
+    }
+
     try {
       const detail = await hermesCli.getProfile(name)
       logger.debug('Profile detail.path = %s', detail.path)

packages/server/src/controllers/hermes/sessions.ts

@@ -1,19 +1,16 @@
 import * as hermesCli from '../../services/hermes/hermes-cli'
-import { listConversationSummaries, getConversationDetail } from '../../services/hermes/conversations'
-import { listConversationSummariesFromDb, getConversationDetailFromDb } from '../../db/hermes/conversations-db'
-import { listSessionSummaries, searchSessionSummaries, getUsageStatsFromDb, getSessionDetailFromDb } from '../../db/hermes/sessions-db'
+import { listSessionSummaries, getUsageStatsFromDb, getSessionDetailFromDb } from '../../db/hermes/sessions-db'
 import {
   listSessions as localListSessions,
   searchSessions as localSearchSessions,
   getSessionDetail as localGetSessionDetail,
   deleteSession as localDeleteSession,
   renameSession as localRenameSession,
-  useLocalSessionStore,
 } from '../../db/hermes/session-store'
 import { ExportCompressor } from '../../lib/context-compressor/export-compressor'
 import { getGatewayManagerInstance } from '../../services/gateway-bootstrap'
-import { deleteUsage, getUsage, getUsageBatch, getLocalUsageStats } from '../../db/hermes/usage-store'
-import type { LocalUsageStats, UsageStatsModelRow, UsageStatsDailyRow } from '../../db/hermes/usage-store'
+import { deleteUsage, getUsage, getUsageBatch } from '../../db/hermes/usage-store'
+import type { UsageStatsModelRow, UsageStatsDailyRow } from '../../db/hermes/usage-store'
 import { getModelContextLength } from '../../services/hermes/model-context'
 import { getActiveProfileName } from '../../services/hermes/hermes-profile'
 import { getGroupChatServer } from '../../routes/hermes/group-chat'
@@ -36,130 +33,75 @@ function filterPendingDeletedConversationSummaries(items: ConversationSummary[])
 
 export async function listConversations(ctx: any) {
   const source = (ctx.query.source as string) || undefined
-  const humanOnly = (ctx.query.humanOnly as string) !== 'false' && ctx.query.humanOnly !== '0'
   const limit = ctx.query.limit ? parseInt(ctx.query.limit as string, 10) : undefined
 
-  if (useLocalSessionStore()) {
-    const profile = getActiveProfileName()
-    const sessions = localListSessions(profile, source, limit && limit > 0 ? limit : 200)
-    const summaries: ConversationSummary[] = sessions.map(s => ({
-      id: s.id,
-      source: s.source,
-      model: s.model,
-      title: s.title,
-      started_at: s.started_at,
-      ended_at: s.ended_at,
-      last_active: s.last_active,
-      message_count: s.message_count,
-      tool_call_count: s.tool_call_count,
-      input_tokens: s.input_tokens,
-      output_tokens: s.output_tokens,
-      cache_read_tokens: s.cache_read_tokens,
-      cache_write_tokens: s.cache_write_tokens,
-      reasoning_tokens: s.reasoning_tokens,
-      billing_provider: s.billing_provider,
-      estimated_cost_usd: s.estimated_cost_usd,
-      actual_cost_usd: s.actual_cost_usd,
-      cost_status: s.cost_status,
-      preview: s.preview,
-      workspace: s.workspace || null,
-      is_active: s.ended_at == null && (Date.now() / 1000 - s.last_active) <= 300,
-      thread_session_count: 1,
-    }))
-    ctx.body = { sessions: filterPendingDeletedConversationSummaries(summaries) }
-    return
-  }
-
-  try {
-    const sessions = await listConversationSummariesFromDb({ source, humanOnly, limit })
-    ctx.body = { sessions: filterPendingDeletedConversationSummaries(sessions) }
-    return
-  } catch (err) {
-    logger.warn(err, 'Hermes Conversation DB: summary query failed, falling back to CLI export')
-  }
-
-  const sessions = await listConversationSummaries({ source, humanOnly, limit })
-  ctx.body = { sessions: filterPendingDeletedConversationSummaries(sessions) }
+  const profile = getActiveProfileName()
+  const sessions = localListSessions(profile, source, limit && limit > 0 ? limit : 200)
+  const summaries: ConversationSummary[] = sessions.map(s => ({
+    id: s.id,
+    source: s.source,
+    model: s.model,
+    title: s.title,
+    started_at: s.started_at,
+    ended_at: s.ended_at,
+    last_active: s.last_active,
+    message_count: s.message_count,
+    tool_call_count: s.tool_call_count,
+    input_tokens: s.input_tokens,
+    output_tokens: s.output_tokens,
+    cache_read_tokens: s.cache_read_tokens,
+    cache_write_tokens: s.cache_write_tokens,
+    reasoning_tokens: s.reasoning_tokens,
+    billing_provider: s.billing_provider,
+    estimated_cost_usd: s.estimated_cost_usd,
+    actual_cost_usd: s.actual_cost_usd,
+    cost_status: s.cost_status,
+    preview: s.preview,
+    workspace: s.workspace || null,
+    is_active: s.ended_at == null && (Date.now() / 1000 - s.last_active) <= 300,
+    thread_session_count: 1,
+  }))
+  ctx.body = { sessions: filterPendingDeletedConversationSummaries(summaries) }
 }
 
 export async function getConversationMessages(ctx: any) {
-  const source = (ctx.query.source as string) || undefined
   const humanOnly = (ctx.query.humanOnly as string) !== 'false' && ctx.query.humanOnly !== '0'
 
-  if (useLocalSessionStore()) {
-    const detail = localGetSessionDetail(ctx.params.id)
-    if (!detail) {
-      ctx.status = 404
-      ctx.body = { error: 'Conversation not found' }
-      return
-    }
-    const messages = detail.messages
-      .filter(m => {
-        if (humanOnly && m.role !== 'user' && m.role !== 'assistant') return false
-        if (!m.content) return false
-        return true
-      })
-      .map(m => ({
-        id: m.id,
-        session_id: m.session_id,
-        role: m.role as 'user' | 'assistant',
-        content: m.content,
-        timestamp: m.timestamp,
-      }))
-    ctx.body = {
-      session_id: ctx.params.id,
-      messages,
-      visible_count: messages.length,
-      thread_session_count: 1,
-    }
-    return
-  }
-
-  try {
-    const detail = await getConversationDetailFromDb(ctx.params.id, { source, humanOnly })
-    if (!detail) {
-      ctx.status = 404
-      ctx.body = { error: 'Conversation not found' }
-      return
-    }
-    ctx.body = detail
-    return
-  } catch (err) {
-    logger.warn(err, 'Hermes Conversation DB: detail query failed, falling back to CLI export')
-  }
-
-  const detail = await getConversationDetail(ctx.params.id, { source, humanOnly })
+  const detail = localGetSessionDetail(ctx.params.id)
   if (!detail) {
     ctx.status = 404
     ctx.body = { error: 'Conversation not found' }
     return
   }
-  ctx.body = detail
+  const messages = detail.messages
+    .filter(m => {
+      if (humanOnly && m.role !== 'user' && m.role !== 'assistant') return false
+      if (!m.content) return false
+      return true
+    })
+    .map(m => ({
+      id: m.id,
+      session_id: m.session_id,
+      role: m.role as 'user' | 'assistant',
+      content: m.content,
+      timestamp: m.timestamp,
+    }))
+  ctx.body = {
+    session_id: ctx.params.id,
+    messages,
+    visible_count: messages.length,
+    thread_session_count: 1,
+  }
 }
 
 export async function list(ctx: any) {
-  if (useLocalSessionStore()) {
-    const source = (ctx.query.source as string) || undefined
-    const limit = ctx.query.limit ? parseInt(ctx.query.limit as string, 10) : undefined
-    const profile = getActiveProfileName()
-    const sessions = localListSessions(profile, source, limit && limit > 0 ? limit : 2000)
-    ctx.body = { sessions: filterPendingDeletedSessions(sessions) }
-    return
-  }
-
   const source = (ctx.query.source as string) || undefined
   const limit = ctx.query.limit ? parseInt(ctx.query.limit as string, 10) : undefined
+  const profile = getActiveProfileName()
+  const effectiveLimit = limit && limit > 0 ? limit : 2000
 
-  try {
-    const sessions = await listSessionSummaries(source, limit && limit > 0 ? limit : 2000)
-    ctx.body = { sessions: filterPendingDeletedSessions(sessions) }
-    return
-  } catch (err) {
-    logger.warn(err, 'Hermes Session DB: summary query failed, falling back to CLI')
-  }
-
-  const sessions = await hermesCli.listSessions(source, limit)
-  ctx.body = { sessions: filterPendingDeletedSessions(sessions) }
+  const allSessions = localListSessions(profile, source, effectiveLimit)
+  ctx.body = { sessions: filterPendingDeletedSessions(allSessions.filter(s => s.source === 'api_server' || s.source === 'cli')) }
 }
 
 /**
@@ -169,58 +111,23 @@ export async function list(ctx: any) {
 export async function listHermesSessions(ctx: any) {
   const source = (ctx.query.source as string) || undefined
   const limit = ctx.query.limit ? parseInt(ctx.query.limit as string, 10) : undefined
+  const profile = getActiveProfileName()
+  const effectiveLimit = limit && limit > 0 ? limit : 2000
 
-  try {
-    const sessions = await listSessionSummaries(source, limit && limit > 0 ? limit : 2000)
-    ctx.body = { sessions: filterPendingDeletedSessions(sessions.filter(s => s.source !== 'api_server')) }
-    return
-  } catch (err) {
-    logger.warn(err, 'Hermes Session DB: summary query failed, falling back to CLI')
-  }
-
-  const sessions = await hermesCli.listSessions(source, limit)
-  ctx.body = { sessions: filterPendingDeletedSessions(sessions.filter(s => s.source !== 'api_server')) }
+  const allSessions = localListSessions(profile, source, effectiveLimit)
+  ctx.body = { sessions: filterPendingDeletedSessions(allSessions.filter(s => s.source !== 'api_server')) }
 }
 
 export async function search(ctx: any) {
-  if (useLocalSessionStore()) {
-    const q = typeof ctx.query.q === 'string' ? ctx.query.q : ''
-    const limit = ctx.query.limit ? parseInt(ctx.query.limit as string, 10) : undefined
-    const profile = getActiveProfileName()
-    const results = localSearchSessions(profile, q, limit && limit > 0 ? limit : 20)
-    ctx.body = { results: filterPendingDeletedSessions(results) }
-    return
-  }
-
   const q = typeof ctx.query.q === 'string' ? ctx.query.q : ''
-  const source = typeof ctx.query.source === 'string' && ctx.query.source.trim()
-    ? ctx.query.source.trim()
-    : undefined
   const limit = ctx.query.limit ? parseInt(ctx.query.limit as string, 10) : undefined
-
-  try {
-    const results = await searchSessionSummaries(q, source, limit && limit > 0 ? limit : 20)
-    ctx.body = { results: filterPendingDeletedSessions(results) }
-  } catch (err) {
-    logger.error(err, 'Hermes Session DB: search failed')
-    ctx.status = 500
-    ctx.body = { error: 'Failed to search sessions' }
-  }
+  const profile = getActiveProfileName()
+  const results = localSearchSessions(profile, q, limit && limit > 0 ? limit : 20)
+  ctx.body = { results: filterPendingDeletedSessions(results) }
 }
 
 export async function get(ctx: any) {
-  if (useLocalSessionStore()) {
-    const session = localGetSessionDetail(ctx.params.id)
-    if (!session) {
-      ctx.status = 404
-      ctx.body = { error: 'Session not found' }
-      return
-    }
-    ctx.body = { session }
-    return
-  }
-
-  const session = await hermesCli.getSession(ctx.params.id)
+  const session = localGetSessionDetail(ctx.params.id)
   if (!session) {
     ctx.status = 404
     ctx.body = { error: 'Session not found' }
@@ -262,21 +169,8 @@ export async function getHermesSession(ctx: any) {
 }
 
 export async function remove(ctx: any) {
-  if (useLocalSessionStore()) {
-    const sessionId = ctx.params.id
-    const ok = localDeleteSession(sessionId)
-    if (!ok) {
-      ctx.status = 500
-      ctx.body = { error: 'Failed to delete session' }
-      return
-    }
-    deleteUsage(sessionId)
-    ctx.body = { ok: true }
-    return
-  }
-
   const sessionId = ctx.params.id
-  const ok = await hermesCli.deleteSession(sessionId)
+  const ok = localDeleteSession(sessionId)
   if (!ok) {
     ctx.status = 500
     ctx.body = { error: 'Failed to delete session' }
@@ -307,27 +201,14 @@ export async function batchRemove(ctx: any) {
     errors: [] as Array<{ id: string; error: string }>
   }
 
-  if (useLocalSessionStore()) {
-    for (const id of validIds) {
-      const ok = localDeleteSession(id)
-      if (ok) {
-        deleteUsage(id)
-        results.deleted++
-      } else {
-        results.failed++
-        results.errors.push({ id, error: 'Failed to delete session' })
-      }
-    }
-  } else {
-    for (const id of validIds) {
-      const ok = await hermesCli.deleteSession(id)
-      if (ok) {
-        deleteUsage(id)
-        results.deleted++
-      } else {
-        results.failed++
-        results.errors.push({ id, error: 'Failed to delete session' })
-      }
+  for (const id of validIds) {
+    const ok = localDeleteSession(id)
+    if (ok) {
+      deleteUsage(id)
+      results.deleted++
+    } else {
+      results.failed++
+      results.errors.push({ id, error: 'Failed to delete session' })
     }
   }
 
@@ -354,30 +235,13 @@ export async function usageSingle(ctx: any) {
 }
 
 export async function rename(ctx: any) {
-  if (useLocalSessionStore()) {
-    const { title } = ctx.request.body as { title?: string }
-    if (!title || typeof title !== 'string') {
-      ctx.status = 400
-      ctx.body = { error: 'title is required' }
-      return
-    }
-    const ok = localRenameSession(ctx.params.id, title.trim())
-    if (!ok) {
-      ctx.status = 500
-      ctx.body = { error: 'Failed to rename session' }
-      return
-    }
-    ctx.body = { ok: true }
-    return
-  }
-
   const { title } = ctx.request.body as { title?: string }
   if (!title || typeof title !== 'string') {
     ctx.status = 400
     ctx.body = { error: 'title is required' }
     return
   }
-  const ok = await hermesCli.renameSession(ctx.params.id, title.trim())
+  const ok = localRenameSession(ctx.params.id, title.trim())
   if (!ok) {
     ctx.status = 500
     ctx.body = { error: 'Failed to rename session' }
@@ -393,20 +257,14 @@ export async function setWorkspace(ctx: any) {
     ctx.body = { error: 'workspace must be a string or null' }
     return
   }
-  if (useLocalSessionStore()) {
-    const { updateSession, getSession, createSession } = await import('../../db/hermes/session-store')
-    const { getActiveProfileName } = await import('../../services/hermes/hermes-profile')
-    const id = ctx.params.id
-    // Create session if it doesn't exist yet (user may set workspace before sending first message)
-    if (!getSession(id)) {
-      createSession({ id, profile: getActiveProfileName(), title: '' })
-    }
-    updateSession(id, { workspace: workspace || null } as any)
-    ctx.body = { ok: true }
-    return
+  const { updateSession, getSession, createSession } = await import('../../db/hermes/session-store')
+  const { getActiveProfileName } = await import('../../services/hermes/hermes-profile')
+  const id = ctx.params.id
+  if (!getSession(id)) {
+    createSession({ id, profile: getActiveProfileName(), title: '' })
   }
-  ctx.status = 501
-  ctx.body = { error: 'Workspace setting only supported in local session store mode' }
+  updateSession(id, { workspace: workspace || null } as any)
+  ctx.body = { ok: true }
 }
 
 export async function contextLength(ctx: any) {
@@ -418,11 +276,6 @@ export async function usageStats(ctx: any) {
   const rawDays = parseInt(String(ctx.query?.days ?? '30'), 10)
   const days = Number.isFinite(rawDays) && rawDays > 0 ? Math.min(rawDays, 365) : 30
 
-  // Local Web UI chat usage is kept in the dashboard DB and must be merged
-  // with Hermes' native state.db analytics for the same period.
-  const currentProfile = getActiveProfileName()
-  const local = getLocalUsageStats(currentProfile, days)
-
   let hermes = {
     input_tokens: 0,
     output_tokens: 0,
@@ -442,29 +295,6 @@ export async function usageStats(ctx: any) {
     logger.warn(err, 'usageStats: failed to load Hermes usage analytics from state.db')
   }
 
-  const totalInput = local.input_tokens + hermes.input_tokens
-  const totalOutput = local.output_tokens + hermes.output_tokens
-  const totalCacheRead = local.cache_read_tokens + hermes.cache_read_tokens
-  const totalCacheWrite = local.cache_write_tokens + hermes.cache_write_tokens
-  const totalReasoning = local.reasoning_tokens + hermes.reasoning_tokens
-  const totalSessions = local.sessions + hermes.sessions
-
-  const modelMap = new Map<string, UsageStatsModelRow>()
-  for (const m of [...local.by_model, ...hermes.by_model]) {
-    const model = (m.model || '').trim() || 'unknown'
-    const existing = modelMap.get(model)
-    if (existing) {
-      existing.input_tokens += m.input_tokens
-      existing.output_tokens += m.output_tokens
-      existing.cache_read_tokens += m.cache_read_tokens
-      existing.cache_write_tokens += m.cache_write_tokens
-      existing.reasoning_tokens += m.reasoning_tokens
-      existing.sessions += m.sessions
-    } else {
-      modelMap.set(model, { ...m, model })
-    }
-  }
-
   const dayMap = new Map<string, UsageStatsDailyRow>()
   const now = new Date()
   for (let i = days - 1; i >= 0; i--) {
@@ -473,7 +303,7 @@ export async function usageStats(ctx: any) {
     const key = d.toISOString().slice(0, 10)
     dayMap.set(key, { date: key, input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_write_tokens: 0, sessions: 0, errors: 0, cost: 0 })
   }
-  for (const d of [...local.by_day, ...hermes.by_day]) {
+  for (const d of hermes.by_day) {
     const existing = dayMap.get(d.date)
     if (existing) {
       existing.input_tokens += d.input_tokens; existing.output_tokens += d.output_tokens
@@ -483,16 +313,16 @@ export async function usageStats(ctx: any) {
   }
 
   ctx.body = {
-    total_input_tokens: totalInput,
-    total_output_tokens: totalOutput,
-    total_cache_read_tokens: totalCacheRead,
-    total_cache_write_tokens: totalCacheWrite,
-    total_reasoning_tokens: totalReasoning,
-    total_sessions: totalSessions,
+    total_input_tokens: hermes.input_tokens,
+    total_output_tokens: hermes.output_tokens,
+    total_cache_read_tokens: hermes.cache_read_tokens,
+    total_cache_write_tokens: hermes.cache_write_tokens,
+    total_reasoning_tokens: hermes.reasoning_tokens,
+    total_sessions: hermes.sessions,
     total_cost: hermes.cost,
     total_api_calls: hermes.total_api_calls,
     period_days: days,
-    model_usage: [...modelMap.values()].sort((a, b) => (b.input_tokens + b.output_tokens) - (a.input_tokens + a.output_tokens)),
+    model_usage: hermes.by_model.sort((a, b) => (b.input_tokens + b.output_tokens) - (a.input_tokens + a.output_tokens)),
     daily_usage: [...dayMap.values()],
   }
 }
@@ -545,20 +375,7 @@ export async function listWorkspaceFolders(ctx: any) {
 const exportCompressor = new ExportCompressor()
 
 export async function exportSession(ctx: any) {
-  let session: any = null
-
-  if (useLocalSessionStore()) {
-    session = localGetSessionDetail(ctx.params.id)
-  } else {
-    try {
-      session = await getSessionDetailFromDb(ctx.params.id)
-    } catch (err) {
-      logger.warn(err, 'Hermes Session DB: export detail query failed, falling back to CLI')
-    }
-    if (!session) {
-      session = await hermesCli.getSession(ctx.params.id)
-    }
-  }
+  const session = localGetSessionDetail(ctx.params.id)
 
   if (!session) {
     ctx.status = 404
@@ -630,38 +447,32 @@ export async function getConversationMessagesPaginated(ctx: any) {
   const offset = ctx.query.offset ? parseInt(ctx.query.offset as string, 10) : 0
   const limit = ctx.query.limit ? parseInt(ctx.query.limit as string, 10) : 50
 
-  if (useLocalSessionStore()) {
-    const { getSessionDetailPaginated } = await import('../../db/hermes/session-store')
-    const result = getSessionDetailPaginated(ctx.params.id, offset, limit)
+  const { getSessionDetailPaginated } = await import('../../db/hermes/session-store')
+  const result = getSessionDetailPaginated(ctx.params.id, offset, limit)
 
-    if (!result) {
-      ctx.status = 404
-      ctx.body = { error: 'Conversation not found' }
-      return
-    }
-
-    ctx.body = {
-      session: {
-        id: result.session.id,
-        source: result.session.source,
-        model: result.session.model,
-        title: result.session.title,
-        started_at: result.session.started_at,
-        ended_at: result.session.ended_at,
-        last_active: result.session.last_active,
-        message_count: result.session.message_count,
-        input_tokens: result.session.input_tokens,
-        output_tokens: result.session.output_tokens,
-      },
-      messages: result.messages,
-      total: result.total,
-      offset: result.offset,
-      limit: result.limit,
-      hasMore: result.hasMore,
-    }
+  if (!result) {
+    ctx.status = 404
+    ctx.body = { error: 'Conversation not found' }
     return
   }
 
-  ctx.status = 404
-  ctx.body = { error: 'Conversation not found' }
+  ctx.body = {
+    session: {
+      id: result.session.id,
+      source: result.session.source,
+      model: result.session.model,
+      title: result.session.title,
+      started_at: result.session.started_at,
+      ended_at: result.session.ended_at,
+      last_active: result.session.last_active,
+      message_count: result.session.message_count,
+      input_tokens: result.session.input_tokens,
+      output_tokens: result.session.output_tokens,
+    },
+    messages: result.messages,
+    total: result.total,
+    offset: result.offset,
+    limit: result.limit,
+    hasMore: result.hasMore,
+  }
 }

packages/server/src/db/hermes/session-store.ts

@@ -129,14 +129,16 @@ function mapMessageRow(row: Record<string, unknown>): HermesMessageRow {
 export function createSession(data: {
   id: string
   profile?: string
+  source?: string
   model?: string
   title?: string
   workspace?: string
 }): HermesSessionRow {
   const now = Math.floor(Date.now() / 1000)
+  const source = data.source || 'api_server'
   if (!isSqliteAvailable()) {
     return {
-      id: data.id, profile: data.profile || 'default', source: 'api_server',
+      id: data.id, profile: data.profile || 'default', source,
       user_id: null, model: data.model || '', title: data.title || null,
       started_at: now, ended_at: null, end_reason: null,
       message_count: 0, tool_call_count: 0,
@@ -148,8 +150,8 @@ export function createSession(data: {
   const db = getDb()!
   db.prepare(
     `INSERT INTO ${SESSIONS_TABLE} (id, profile, source, model, title, started_at, last_active, workspace)
-     VALUES (?, ?, 'api_server', ?, ?, ?, ?, ?)`,
-  ).run(data.id, data.profile || 'default', data.model || '', data.title || null, now, now, data.workspace || null)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+  ).run(data.id, data.profile || 'default', source, data.model || '', data.title || null, now, now, data.workspace || null)
   return getSession(data.id)!
 }
 

packages/server/src/db/hermes/sessions-db.ts

@@ -565,6 +565,10 @@ function aggregateSessionDetail(
   }
 }
 
+function chainOrderSql(ids: string[]): string {
+  return ids.map((_, index) => `WHEN ? THEN ${index}`).join(' ')
+}
+
 async function openSessionDb() {
   if (!SQLITE_AVAILABLE) {
     throw new Error(`node:sqlite requires Node >= 22.5, current: ${process.versions.node}`)
@@ -598,7 +602,7 @@ export async function getSessionMessagesFromDb(sessionId: string): Promise<{
     const messageRows = db.prepare(`
       SELECT * FROM messages
       WHERE session_id = ?
-      ORDER BY timestamp, id
+      ORDER BY id
     `).all(sessionId) as Record<string, unknown>[]
 
     return {
@@ -622,11 +626,12 @@ export async function getSessionDetailFromDb(sessionId: string): Promise<HermesS
 
     const ids = chain.map(session => session.id)
     const placeholders = ids.map(() => '?').join(', ')
+    const orderSql = chainOrderSql(ids)
     const messageRows = db.prepare(`
       SELECT * FROM messages
       WHERE session_id IN (${placeholders})
-      ORDER BY timestamp, id
-    `).all(...ids) as Record<string, unknown>[]
+      ORDER BY CASE session_id ${orderSql} ELSE ${ids.length} END, id
+    `).all(...ids, ...ids) as Record<string, unknown>[]
     const messages = messageRows.map(mapMessageRow)
     return aggregateSessionDetail(chain, messages, sessionId)
   } finally {
@@ -648,11 +653,12 @@ export async function getSessionDetailFromDbWithProfile(sessionId: string, profi
 
     const ids = chain.map(session => session.id)
     const placeholders = ids.map(() => '?').join(', ')
+    const orderSql = chainOrderSql(ids)
     const messageRows = db.prepare(`
       SELECT * FROM messages
       WHERE session_id IN (${placeholders})
-      ORDER BY timestamp, id
-    `).all(...ids) as Record<string, unknown>[]
+      ORDER BY CASE session_id ${orderSql} ELSE ${ids.length} END, id
+    `).all(...ids, ...ids) as Record<string, unknown>[]
     const messages = messageRows.map(mapMessageRow)
     return aggregateSessionDetail(chain, messages, sessionId)
   } finally {
@@ -672,7 +678,7 @@ export async function getExactSessionDetailFromDbWithProfile(sessionId: string,
     const messageRows = db.prepare(`
       SELECT * FROM messages
       WHERE session_id = ?
-      ORDER BY timestamp, id
+      ORDER BY id
     `).all(sessionId) as Record<string, unknown>[]
     const messages = messageRows.map(mapMessageRow)
     return aggregateSessionDetail([requested], messages, sessionId)
@@ -818,10 +824,6 @@ export async function getUsageStatsFromDb(
     const apiCallsExpr = tableHasColumn(db, 'sessions', 'api_call_count')
       ? 'COALESCE(SUM(api_call_count), 0)'
       : '0'
-    const sourceFilter = tableHasColumn(db, 'sessions', 'source')
-      ? " AND COALESCE(source, '') != 'api_server'"
-      : ''
-
     const totals = db.prepare(`
       SELECT
         COALESCE(SUM(input_tokens), 0) AS input_tokens,
@@ -833,7 +835,7 @@ export async function getUsageStatsFromDb(
         COUNT(*) AS sessions,
         ${apiCallsExpr} AS total_api_calls
       FROM sessions
-      WHERE started_at > ?${sourceFilter}
+      WHERE started_at > ?
     `).get(since) as Record<string, unknown> | undefined
 
     if (!totals) return empty
@@ -848,7 +850,7 @@ export async function getUsageStatsFromDb(
         COALESCE(SUM(reasoning_tokens), 0) AS reasoning_tokens,
         COUNT(*) AS sessions
       FROM sessions
-      WHERE started_at > ?${sourceFilter} AND model IS NOT NULL
+      WHERE started_at > ? AND model IS NOT NULL
       GROUP BY model
       ORDER BY COALESCE(SUM(input_tokens), 0) + COALESCE(SUM(output_tokens), 0) DESC
     `).all(since).map(row => ({
@@ -871,7 +873,7 @@ export async function getUsageStatsFromDb(
         COUNT(*) AS sessions,
         COALESCE(SUM(COALESCE(actual_cost_usd, estimated_cost_usd, 0)), 0) AS cost
       FROM sessions
-      WHERE started_at > ?${sourceFilter}
+      WHERE started_at > ?
       GROUP BY date
       ORDER BY date ASC
     `).all(since).map(row => ({

packages/server/src/index.ts

@@ -20,6 +20,7 @@ import { setGroupChatServer } from './routes/hermes/group-chat'
 import { setChatRunServer } from './routes/hermes/chat-run'
 import { GroupChatServer } from './services/hermes/group-chat'
 import { ChatRunSocket } from './services/hermes/chat-run-socket'
+import { startAgentBridgeManager } from './services/hermes/agent-bridge'
 import { logger } from './services/logger'
 
 // Injected by esbuild at build time; fallback to reading package.json in dev mode
@@ -46,6 +47,7 @@ process.on('unhandledRejection', (reason) => {
 let server: any = null
 let servers: any[] = []
 let chatRunServer: any = null
+let agentBridgeManager: any = null
 
 interface ListenResult {
   primary: any
@@ -94,6 +96,13 @@ export async function bootstrap() {
 
   await initGatewayManager()
   console.log('[bootstrap] gateway manager initialized')
+  try {
+    agentBridgeManager = await startAgentBridgeManager()
+    console.log('[bootstrap] agent bridge started')
+  } catch (err) {
+    logger.warn(err, '[bootstrap] agent bridge failed to start')
+    console.warn('[bootstrap] agent bridge failed to start:', err instanceof Error ? err.message : err)
+  }
   await new Promise(resolve => setTimeout(resolve, 1000))
   // Initialize all web-ui SQLite tables
   const { initAllStores } = await import('./db/hermes/init')
@@ -102,11 +111,6 @@ export async function bootstrap() {
   await new Promise(resolve => setTimeout(resolve, 1000))
   console.log('[bootstrap] all stores initialized')
 
-  // Sync Hermes sessions from all profiles (only if local DB is empty)
-  const { syncAllHermesSessionsOnStartup } = await import('./services/hermes/session-sync')
-  await syncAllHermesSessionsOnStartup()
-  console.log('[bootstrap] Hermes session sync completed')
-
   app.use(cors({ origin: config.corsOrigins }))
   app.use(bodyParser())
   console.log('[bootstrap] cors + bodyParser registered')
@@ -187,7 +191,7 @@ export async function bootstrap() {
     })
   })
 
-  bindShutdown(servers, groupChatServer, chatRunServer)
+  bindShutdown(servers, groupChatServer, chatRunServer, agentBridgeManager)
   startVersionCheck()
 }
 

packages/server/src/services/hermes/agent-bridge/README.md

@@ -0,0 +1,85 @@
+# Agent Bridge
+
+Optional backend-side bridge for talking to `~/.hermes/hermes-agent` by
+instantiating `run_agent.AIAgent` directly in a Python process.
+
+This is intentionally separate from the current Web UI chat path.
+
+## Python Service
+
+```bash
+python packages/server/src/services/hermes/agent-bridge/hermes_bridge.py
+```
+
+Default endpoint:
+
+```text
+ipc:///tmp/hermes-agent-bridge.sock
+```
+
+On Windows, the default endpoint is TCP because Python may not support Unix
+domain sockets there:
+
+```text
+tcp://127.0.0.1:18765
+```
+
+Override with:
+
+```bash
+HERMES_AGENT_BRIDGE_ENDPOINT=tcp://127.0.0.1:8765 python packages/server/src/services/hermes/agent-bridge/hermes_bridge.py
+```
+
+The service discovers Hermes Agent in this order:
+
+1. `--agent-root`
+2. `HERMES_AGENT_ROOT`
+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`
+
+Hermes home is resolved from `--hermes-home`, `HERMES_HOME`, then `~/.hermes`.
+
+Default agent root:
+
+```text
+~/.hermes/hermes-agent
+```
+
+You can pass both paths explicitly:
+
+```bash
+python packages/server/src/services/hermes/agent-bridge/hermes_bridge.py \
+  --agent-root ~/.hermes/hermes-agent \
+  --hermes-home ~/.hermes
+```
+
+The socket transport uses Python and Node standard libraries. No ZMQ dependency
+is required.
+
+## Backend Usage
+
+```ts
+import { AgentBridgeClient } from './services/hermes/agent-bridge'
+
+const bridge = new AgentBridgeClient()
+const run = await bridge.chat(sessionId, message)
+
+for await (const chunk of bridge.streamOutput(run.run_id)) {
+  if (chunk.delta) {
+    // forward chunk.delta to Socket.IO/SSE/etc.
+  }
+}
+```
+
+The external chat call only sends `session_id` and `message`. Provider, model,
+keys, tools, reasoning, and session DB are resolved by hermes-agent from the
+normal Hermes config and environment.
+
+The bridge instantiates `AIAgent` with `platform="cli"` by default so behavior
+matches CLI chat. Override it only if a caller intentionally needs a distinct
+platform identity:
+
+```bash
+HERMES_AGENT_BRIDGE_PLATFORM=agent-bridge python packages/server/src/services/hermes/agent-bridge/hermes_bridge.py
+```

packages/server/src/services/hermes/agent-bridge/client.ts

@@ -0,0 +1,330 @@
+import { setTimeout as delay } from 'timers/promises'
+import { createConnection, type Socket } from 'net'
+import { URL } from 'url'
+
+export const DEFAULT_AGENT_BRIDGE_ENDPOINT = process.platform === 'win32'
+  ? 'tcp://127.0.0.1:18765'
+  : 'ipc:///tmp/hermes-agent-bridge.sock'
+export const DEFAULT_AGENT_BRIDGE_TIMEOUT_MS = 120000
+
+function envPositiveInt(name: string): number | undefined {
+  const raw = process.env[name]
+  if (!raw) return undefined
+  const value = Number(raw)
+  return Number.isFinite(value) && value > 0 ? value : undefined
+}
+
+export type AgentBridgeStatus = 'running' | 'complete' | 'interrupted' | 'error'
+
+export interface AgentBridgeOptions {
+  endpoint?: string
+  timeoutMs?: number
+}
+
+export interface AgentBridgeRequestOptions {
+  timeoutMs?: number
+}
+
+export type AgentBridgeMessage =
+  | string
+  | Array<Record<string, unknown>>
+
+export interface AgentBridgeResponse {
+  ok: true
+  [key: string]: unknown
+}
+
+export interface AgentBridgeChatStarted extends AgentBridgeResponse {
+  run_id: string
+  session_id: string
+  status: AgentBridgeStatus
+}
+
+export interface AgentBridgeOutput extends AgentBridgeResponse {
+  run_id: string
+  session_id: string
+  status: AgentBridgeStatus
+  delta: string
+  cursor: number
+  output: string
+  done: boolean
+  result?: unknown
+  error?: string | null
+  events: Array<Record<string, unknown>>
+  event_cursor: number
+}
+
+export interface AgentBridgeRunResult extends AgentBridgeResponse {
+  run_id: string
+  session_id: string
+  status: AgentBridgeStatus
+  output: string
+  deltas: string[]
+  events: unknown[]
+  result?: unknown
+  error?: string | null
+}
+
+export interface AgentBridgeCommandResult extends AgentBridgeResponse {
+  session_id: string
+  command: string
+  handled: boolean
+  message?: string
+  new_session_id?: string
+  history?: unknown[]
+  retry?: boolean
+  retry_input?: AgentBridgeMessage
+  title?: string
+}
+
+export class AgentBridgeError extends Error {
+  response?: unknown
+}
+
+export class AgentBridgeClient {
+  readonly endpoint: string
+  readonly timeoutMs: number
+  private lock: Promise<unknown> = Promise.resolve()
+
+  constructor(options: AgentBridgeOptions = {}) {
+    this.endpoint = options.endpoint || process.env.HERMES_AGENT_BRIDGE_ENDPOINT || DEFAULT_AGENT_BRIDGE_ENDPOINT
+    this.timeoutMs = options.timeoutMs ?? envPositiveInt('HERMES_AGENT_BRIDGE_TIMEOUT_MS') ?? DEFAULT_AGENT_BRIDGE_TIMEOUT_MS
+  }
+
+  async connect(): Promise<this> {
+    return this
+  }
+
+  async close(): Promise<void> {
+    return undefined
+  }
+
+  private connectSocket(): Promise<Socket> {
+    return new Promise((resolveConnect, rejectConnect) => {
+      const endpoint = this.endpoint
+      let socket: Socket
+      if (endpoint.startsWith('ipc://')) {
+        socket = createConnection(endpoint.slice('ipc://'.length))
+      } else if (endpoint.startsWith('tcp://')) {
+        const url = new URL(endpoint)
+        socket = createConnection({
+          host: url.hostname || '127.0.0.1',
+          port: Number(url.port),
+        })
+      } else {
+        rejectConnect(new Error(`unsupported agent bridge endpoint: ${endpoint}`))
+        return
+      }
+
+      const cleanup = () => {
+        socket.off('connect', onConnect)
+        socket.off('error', onError)
+      }
+      const onConnect = () => {
+        cleanup()
+        resolveConnect(socket)
+      }
+      const onError = (err: Error) => {
+        cleanup()
+        socket.destroy()
+        rejectConnect(err)
+      }
+      socket.once('connect', onConnect)
+      socket.once('error', onError)
+    })
+  }
+
+  private readResponse(socket: Socket, timeoutMs: number): Promise<string> {
+    return new Promise((resolveRead, rejectRead) => {
+      let buffer = ''
+      const timeout = timeoutMs > 0
+        ? setTimeout(() => {
+            cleanup()
+            socket.destroy()
+            rejectRead(new Error(`Agent bridge request timed out after ${timeoutMs}ms`))
+          }, timeoutMs)
+        : null
+
+      const cleanup = () => {
+        if (timeout) clearTimeout(timeout)
+        socket.off('data', onData)
+        socket.off('error', onError)
+        socket.off('end', onEnd)
+        socket.off('close', onClose)
+      }
+      const finish = (line: string) => {
+        cleanup()
+        socket.end()
+        resolveRead(line)
+      }
+      const onData = (chunk: Buffer) => {
+        buffer += chunk.toString('utf8')
+        const idx = buffer.indexOf('\n')
+        if (idx >= 0) finish(buffer.slice(0, idx))
+      }
+      const onError = (err: Error) => {
+        cleanup()
+        socket.destroy()
+        rejectRead(err)
+      }
+      const onEnd = () => {
+        const line = buffer.trim()
+        if (line) finish(line)
+      }
+      const onClose = () => {
+        if (!buffer.trim()) {
+          cleanup()
+          rejectRead(new Error('Agent bridge socket closed without a response'))
+        }
+      }
+
+      socket.on('data', onData)
+      socket.once('error', onError)
+      socket.once('end', onEnd)
+      socket.once('close', onClose)
+    })
+  }
+
+  async request<T extends AgentBridgeResponse = AgentBridgeResponse>(
+    payload: Record<string, unknown>,
+    options: AgentBridgeRequestOptions = {},
+  ): Promise<T> {
+    const run = async (): Promise<T> => {
+      const timeoutMs = options.timeoutMs || this.timeoutMs
+      const socket = await this.connectSocket()
+      socket.write(`${JSON.stringify(payload)}\n`)
+      const raw = await this.readResponse(socket, timeoutMs)
+      const response = JSON.parse(raw) as { ok?: boolean; error?: string }
+      if (!response.ok) {
+        const error = new AgentBridgeError(response.error || 'Agent bridge request failed')
+        error.response = response
+        throw error
+      }
+      return response as T
+    }
+
+    const next = this.lock.then(run, run)
+    this.lock = next.catch(() => undefined)
+    return next
+  }
+
+  ping(): Promise<AgentBridgeResponse> {
+    return this.request({ action: 'ping' })
+  }
+
+  chat(
+    sessionId: string,
+    message: AgentBridgeMessage,
+    conversationHistory?: unknown[],
+    instructions?: string,
+    profile?: string,
+  ): Promise<AgentBridgeChatStarted> {
+    return this.request<AgentBridgeChatStarted>({
+      action: 'chat',
+      session_id: sessionId,
+      message,
+      ...(conversationHistory ? { conversation_history: conversationHistory } : {}),
+      ...(instructions ? { instructions } : {}),
+      ...(profile ? { profile } : {}),
+    })
+  }
+
+  command(sessionId: string, command: string): Promise<AgentBridgeCommandResult> {
+    return this.request<AgentBridgeCommandResult>({
+      action: 'command',
+      session_id: sessionId,
+      command,
+    })
+  }
+
+  getOutput(runId: string, cursor = 0, eventCursor = 0, options: AgentBridgeRequestOptions = {}): Promise<AgentBridgeOutput> {
+    return this.request<AgentBridgeOutput>({
+      action: 'get_output',
+      run_id: runId,
+      cursor,
+      event_cursor: eventCursor,
+    }, options)
+  }
+
+  async *streamOutput(
+    runId: string,
+    options: AgentBridgeRequestOptions & { intervalMs?: number } = {},
+  ): AsyncGenerator<AgentBridgeOutput> {
+    const intervalMs = options.intervalMs || 100
+    let cursor = 0
+    let eventCursor = 0
+    for (;;) {
+      const chunk = await this.getOutput(runId, cursor, eventCursor, options)
+      cursor = chunk.cursor
+      eventCursor = chunk.event_cursor
+      if (chunk.delta || chunk.done || (chunk.events && chunk.events.length > 0)) yield chunk
+      if (chunk.done) return
+      await delay(intervalMs)
+    }
+  }
+
+  async chatStream(
+    sessionId: string,
+    message: AgentBridgeMessage,
+    onDelta: (delta: string, chunk: AgentBridgeOutput) => void | Promise<void>,
+    options: AgentBridgeRequestOptions & { intervalMs?: number } = {},
+  ): Promise<AgentBridgeOutput> {
+    const started = await this.chat(sessionId, message)
+    let last: AgentBridgeOutput | null = null
+    for await (const chunk of this.streamOutput(started.run_id, options)) {
+      last = chunk
+      if (chunk.delta) await onDelta(chunk.delta, chunk)
+    }
+    if (!last) throw new Error(`Agent bridge run ${started.run_id} produced no output state`)
+    return last
+  }
+
+  getResult(runId: string, options: AgentBridgeRequestOptions = {}): Promise<AgentBridgeRunResult> {
+    return this.request<AgentBridgeRunResult>({ action: 'get_result', run_id: runId }, options)
+  }
+
+  interrupt(sessionId: string, message?: string): Promise<AgentBridgeResponse> {
+    return this.request({ action: 'interrupt', session_id: sessionId, message })
+  }
+
+  steer(sessionId: string, text: string): Promise<AgentBridgeResponse> {
+    return this.request({ action: 'steer', session_id: sessionId, text })
+  }
+
+  approvalRespond(approvalId: string, choice: string): Promise<AgentBridgeResponse> {
+    return this.request({ action: 'approval_respond', approval_id: approvalId, choice })
+  }
+
+  compressionRespond(
+    requestId: string,
+    payload: { messages?: unknown[]; system_message?: string; error?: string },
+  ): Promise<AgentBridgeResponse> {
+    return this.request({
+      action: 'compression_respond',
+      request_id: requestId,
+      ...payload,
+    }, { timeoutMs: this.timeoutMs })
+  }
+
+  destroyAll(): Promise<AgentBridgeResponse> {
+    return this.request({ action: 'destroy_all' })
+  }
+
+  getHistory(sessionId: string): Promise<AgentBridgeResponse> {
+    return this.request({ action: 'get_history', session_id: sessionId })
+  }
+
+  destroy(sessionId: string): Promise<AgentBridgeResponse> {
+    return this.request({ action: 'destroy', session_id: sessionId })
+  }
+
+  list(): Promise<AgentBridgeResponse> {
+    return this.request({ action: 'list' })
+  }
+
+  shutdown(): Promise<AgentBridgeResponse> {
+    return this.request({ action: 'shutdown' })
+  }
+}
+
+export default AgentBridgeClient

packages/server/src/services/hermes/agent-bridge/index.ts

@@ -0,0 +1,2 @@
+export * from './client'
+export * from './manager'

packages/server/src/services/hermes/agent-bridge/manager.ts

@@ -0,0 +1,360 @@
+import { execFileSync, spawn, type ChildProcess } from 'child_process'
+import { existsSync, readFileSync } from 'fs'
+import { dirname, isAbsolute, join, resolve } from 'path'
+import { logger } from '../../logger'
+import { detectHermesHome, getHermesBin } from '../hermes-path'
+import { DEFAULT_AGENT_BRIDGE_ENDPOINT } from './client'
+
+const DEFAULT_AGENT_BRIDGE_STARTUP_TIMEOUT_MS = 120000
+
+export interface AgentBridgeManagerOptions {
+  endpoint?: string
+  python?: string
+  agentRoot?: string
+  hermesHome?: string
+  startupTimeoutMs?: number
+}
+
+interface BridgeCommand {
+  command: string
+  argsPrefix: string[]
+  agentRoot?: string
+  hermesHome: string
+}
+
+function envPositiveInt(name: string): number | undefined {
+  const raw = process.env[name]
+  if (!raw) return undefined
+  const value = Number(raw)
+  return Number.isFinite(value) && value > 0 ? value : undefined
+}
+
+function pathCandidates(agentRoot?: string): string[] {
+  if (!agentRoot) return []
+  return process.platform === 'win32'
+    ? [
+        join(agentRoot, 'venv', 'Scripts', 'python.exe'),
+        join(agentRoot, 'venv', 'Scripts', 'python3.exe'),
+        join(agentRoot, '.venv', 'Scripts', 'python.exe'),
+        join(agentRoot, '.venv', 'Scripts', 'python3.exe'),
+      ]
+    : [
+        join(agentRoot, 'venv', 'bin', 'python3'),
+        join(agentRoot, 'venv', 'bin', 'python'),
+        join(agentRoot, '.venv', 'bin', 'python3'),
+        join(agentRoot, '.venv', 'bin', 'python'),
+      ]
+}
+
+function uvCandidates(agentRoot?: string): string[] {
+  return [
+    process.env.HERMES_AGENT_BRIDGE_UV,
+    process.env.UV,
+    ...(process.platform === 'win32'
+      ? [
+          agentRoot ? join(agentRoot, 'venv', 'Scripts', 'uv.exe') : '',
+          agentRoot ? join(agentRoot, 'venv', 'Scripts', 'uv.cmd') : '',
+          agentRoot ? join(agentRoot, '.venv', 'Scripts', 'uv.exe') : '',
+          agentRoot ? join(agentRoot, '.venv', 'Scripts', 'uv.cmd') : '',
+        ]
+      : [
+          agentRoot ? join(agentRoot, 'venv', 'bin', 'uv') : '',
+          agentRoot ? join(agentRoot, '.venv', 'bin', 'uv') : '',
+        ]),
+    'uv',
+  ].filter((value): value is string => !!value && value.trim().length > 0)
+}
+
+function resolveExecutable(command: string): string | undefined {
+  const trimmed = command.trim()
+  if (!trimmed) return undefined
+  if (isAbsolute(trimmed) || trimmed.includes('/') || trimmed.includes('\\')) {
+    return existsSync(trimmed) ? resolve(trimmed) : undefined
+  }
+  try {
+    const lookup = process.platform === 'win32'
+      ? execFileSync('where.exe', [trimmed], { encoding: 'utf-8', windowsHide: true })
+      : execFileSync('which', [trimmed], { encoding: 'utf-8' })
+    return lookup.split(/\r?\n/).map(line => line.trim()).find(Boolean)
+  } catch {
+    return undefined
+  }
+}
+
+function agentRootFromHermesBin(): string | undefined {
+  const hermesBin = resolveExecutable(getHermesBin())
+  if (!hermesBin) return undefined
+
+  const binDir = dirname(hermesBin)
+  const rootCandidates = [
+    resolve(binDir, '..'),
+    resolve(binDir, '..', '..'),
+    resolve(binDir, '..', 'hermes-agent'),
+    resolve(binDir, '..', '..', 'hermes-agent'),
+  ]
+  const root = rootCandidates.find(candidate => existsSync(join(candidate, 'run_agent.py')))
+  if (root) return root
+
+  try {
+    const first = readFileSync(hermesBin, 'utf-8').split(/\r?\n/, 1)[0]
+    const match = first.match(/^#!\s*(.+)$/)
+    const python = match?.[1]?.trim().split(/\s+/)[0]
+    if (python) {
+      const pyDir = dirname(python)
+      const shebangRootCandidates = [
+        resolve(pyDir, '..', '..'),
+        resolve(pyDir, '..', '..', 'hermes-agent'),
+      ]
+      return shebangRootCandidates.find(candidate => existsSync(join(candidate, 'run_agent.py')))
+    }
+  } catch {}
+  return undefined
+}
+
+function hermesBinPython(): string | undefined {
+  const hermesBin = resolveExecutable(getHermesBin())
+  if (!hermesBin) return undefined
+  try {
+    const first = readFileSync(hermesBin, 'utf-8').split(/\r?\n/, 1)[0]
+    const match = first.match(/^#!\s*(.+)$/)
+    const python = match?.[1]?.trim().split(/\s+/)[0]
+    return python && existsSync(python) ? python : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function firstExistingExecutable(candidates: string[]): string | undefined {
+  for (const candidate of candidates) {
+    if (!isAbsolute(candidate) && !candidate.includes('/') && !candidate.includes('\\')) {
+      const resolved = resolveExecutable(candidate)
+      if (resolved) return resolved
+      continue
+    }
+    try {
+      if (existsSync(candidate)) return candidate
+    } catch {}
+  }
+  return undefined
+}
+
+function resolveAgentRoot(explicit?: string, hermesHome = detectHermesHome()): string | undefined {
+  const candidates = [
+    explicit,
+    process.env.HERMES_AGENT_ROOT,
+    join(hermesHome, 'hermes-agent'),
+    agentRootFromHermesBin(),
+    process.cwd(),
+    join(process.cwd(), 'hermes-agent'),
+  ].filter((value): value is string => !!value && value.trim().length > 0)
+  return candidates.find(candidate => existsSync(join(candidate, 'run_agent.py')))
+}
+
+function bridgeCommand(options: AgentBridgeManagerOptions): BridgeCommand {
+  const hermesHome = options.hermesHome || detectHermesHome()
+  const agentRoot = resolveAgentRoot(options.agentRoot, hermesHome)
+  const explicitPython = options.python || process.env.HERMES_AGENT_BRIDGE_PYTHON
+  if (explicitPython) {
+    return { command: explicitPython, argsPrefix: [], agentRoot, hermesHome }
+  }
+
+  const venvPython = firstExistingExecutable(pathCandidates(agentRoot))
+  if (venvPython) {
+    return { command: venvPython, argsPrefix: [], agentRoot, hermesHome }
+  }
+
+  const shebangPython = hermesBinPython()
+  if (shebangPython && existsSync(shebangPython)) {
+    return { command: shebangPython, argsPrefix: [], agentRoot, hermesHome }
+  }
+
+  const uv = firstExistingExecutable(uvCandidates(agentRoot))
+  if (uv) {
+    const prefix = ['run']
+    if (agentRoot) prefix.push('--project', agentRoot)
+    prefix.push('python')
+    return { command: uv, argsPrefix: prefix, agentRoot, hermesHome }
+  }
+
+  const fallback = firstExistingExecutable([
+    process.env.PYTHON || '',
+    ...(process.platform === 'win32' ? ['py', 'python', 'python3'] : ['python3', 'python']),
+  ]) || (process.platform === 'win32' ? 'python' : 'python3')
+  return { command: fallback, argsPrefix: [], agentRoot, hermesHome }
+}
+
+function bridgeScriptPath(): string {
+  const candidates = [
+    // Built server: dist/server/index.js -> dist/server/agent-bridge/hermes_bridge.py
+    resolve(__dirname, 'agent-bridge', 'hermes_bridge.py'),
+    // ts-node/dev source tree.
+    resolve(__dirname, 'services/hermes/agent-bridge/hermes_bridge.py'),
+    resolve(process.cwd(), 'packages/server/src/services/hermes/agent-bridge/hermes_bridge.py'),
+  ]
+  const found = candidates.find(candidate => existsSync(candidate))
+  if (!found) {
+    throw new Error(`agent bridge Python script not found. Tried: ${candidates.join(', ')}`)
+  }
+  return found
+}
+
+export class AgentBridgeManager {
+  readonly endpoint: string
+  private readonly options: AgentBridgeManagerOptions
+  private child: ChildProcess | null = null
+  private starting: Promise<void> | null = null
+  private ready = false
+
+  constructor(options: AgentBridgeManagerOptions = {}) {
+    this.options = options
+    this.endpoint = options.endpoint || process.env.HERMES_AGENT_BRIDGE_ENDPOINT || DEFAULT_AGENT_BRIDGE_ENDPOINT
+  }
+
+  get running(): boolean {
+    return !!this.child && !this.child.killed && this.ready
+  }
+
+  async start(): Promise<void> {
+    if (this.running) return
+    if (this.starting) return this.starting
+    this.starting = this.startProcess()
+    try {
+      await this.starting
+    } finally {
+      this.starting = null
+    }
+  }
+
+  private async startProcess(): Promise<void> {
+    const script = bridgeScriptPath()
+    const command = bridgeCommand(this.options)
+    const args = [...command.argsPrefix, script, '--endpoint', this.endpoint]
+    const agentRoot = command.agentRoot
+    const hermesHome = command.hermesHome
+    if (agentRoot) args.push('--agent-root', agentRoot)
+    if (hermesHome) args.push('--hermes-home', hermesHome)
+
+    const env = {
+      ...process.env,
+      HERMES_AGENT_BRIDGE_ENDPOINT: this.endpoint,
+      HERMES_HOME: hermesHome,
+      ...(agentRoot ? { HERMES_AGENT_ROOT: agentRoot } : {}),
+    }
+
+    logger.info('[agent-bridge] starting: %s %s', command.command, args.join(' '))
+    const child = spawn(command.command, args, {
+      env,
+      cwd: process.cwd(),
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    })
+    this.child = child
+    this.ready = false
+
+    child.once('exit', (code, signal) => {
+      logger.warn('[agent-bridge] exited code=%s signal=%s', code, signal)
+      this.ready = false
+      if (this.child === child) this.child = null
+    })
+
+    child.stderr?.on('data', chunk => {
+      const text = String(chunk).trim()
+      if (text) logger.warn('[agent-bridge] %s', text)
+    })
+
+    await new Promise<void>((resolveReady, rejectReady) => {
+      let buffered = ''
+      const startupTimeoutMs = this.options.startupTimeoutMs
+        ?? envPositiveInt('HERMES_AGENT_BRIDGE_STARTUP_TIMEOUT_MS')
+        ?? DEFAULT_AGENT_BRIDGE_STARTUP_TIMEOUT_MS
+      const timeout = setTimeout(() => {
+        cleanup()
+        rejectReady(new Error(`agent bridge did not become ready within ${startupTimeoutMs}ms`))
+      }, startupTimeoutMs)
+
+      const cleanup = () => {
+        clearTimeout(timeout)
+        child.off('exit', onExitBeforeReady)
+        child.off('error', onError)
+      }
+
+      const onError = (err: Error) => {
+        cleanup()
+        child.stdout?.off('data', onStdout)
+        rejectReady(err)
+      }
+
+      const onExitBeforeReady = (code: number | null, signal: NodeJS.Signals | null) => {
+        cleanup()
+        child.stdout?.off('data', onStdout)
+        rejectReady(new Error(`agent bridge exited before ready code=${code} signal=${signal}`))
+      }
+
+      let readyResolved = false
+      const onStdout = (chunk: Buffer) => {
+        const text = chunk.toString('utf8')
+        buffered += text
+        for (;;) {
+          const newline = buffered.indexOf('\n')
+          if (newline < 0) break
+          const line = buffered.slice(0, newline).trim()
+          buffered = buffered.slice(newline + 1)
+          if (!line) continue
+          logger.info('[agent-bridge] %s', line)
+          if (!readyResolved) {
+            try {
+              const parsed = JSON.parse(line)
+              if (parsed?.event === 'ready') {
+                this.ready = true
+                readyResolved = true
+                cleanup()
+                resolveReady()
+                return
+              }
+            } catch {}
+          }
+        }
+      }
+
+      child.once('error', onError)
+      child.once('exit', onExitBeforeReady)
+      child.stdout?.on('data', onStdout)
+    })
+
+    logger.info('[agent-bridge] ready at %s', this.endpoint)
+  }
+
+  async stop(): Promise<void> {
+    const child = this.child
+    if (!child) return
+    this.ready = false
+    this.child = null
+
+    await new Promise<void>((resolveStop) => {
+      const timeout = setTimeout(() => {
+        if (!child.killed) child.kill('SIGKILL')
+        resolveStop()
+      }, 1500)
+      child.once('exit', () => {
+        clearTimeout(timeout)
+        resolveStop()
+      })
+      if (!child.killed) {
+        child.kill('SIGTERM')
+      }
+    })
+  }
+}
+
+let singleton: AgentBridgeManager | null = null
+
+export function getAgentBridgeManager(): AgentBridgeManager {
+  if (!singleton) singleton = new AgentBridgeManager()
+  return singleton
+}
+
+export async function startAgentBridgeManager(): Promise<AgentBridgeManager> {
+  const manager = getAgentBridgeManager()
+  await manager.start()
+  return manager
+}

packages/server/src/services/hermes/group-chat/agent-clients.ts

@@ -101,6 +101,8 @@ class AgentClient {
             reconnectionAttempts: Infinity,
             reconnectionDelay: 1000,
             reconnectionDelayMax: 30000,
+            randomizationFactor: 0.5,
+            timeout: 30000,
         })
 
         this.bindEvents()

packages/server/src/services/hermes/group-chat/index.ts

@@ -424,7 +424,13 @@ export class GroupChatServer {
         const servers = Array.isArray(httpServers) ? httpServers : [httpServers]
 
         this.io = new Server(servers[0], {
-            cors: { origin: '*' }
+            cors: { origin: '*' },
+            pingInterval: 25_000,
+            pingTimeout: 90_000,
+            connectionStateRecovery: {
+                maxDisconnectionDuration: 2 * 60_000,
+                skipMiddlewares: true,
+            },
         })
         servers.slice(1).forEach((httpServer) => this.io.attach(httpServer))
         this.nsp = this.io.of('/group-chat')

packages/server/src/services/shutdown.ts

@@ -27,7 +27,7 @@ function shouldStopGatewaysOnShutdown(signal: string): boolean {
   return shouldStop
 }
 
-export function bindShutdown(server: any, groupChatServer?: any, chatRunServer?: any): void {
+export function bindShutdown(server: any, groupChatServer?: any, chatRunServer?: any, agentBridgeManager?: any): void {
   let isShuttingDown = false
 
   const shutdown = async (signal: string) => {
@@ -58,6 +58,15 @@ export function bindShutdown(server: any, groupChatServer?: any, chatRunServer?:
         logger.info('Skipping gateway shutdown for %s', signal)
       }
 
+      if (agentBridgeManager) {
+        try {
+          await agentBridgeManager.stop()
+          logger.info('Agent bridge stopped')
+        } catch (err) {
+          logger.warn(err, 'Failed to stop agent bridge (non-fatal)')
+        }
+      }
+
       // Close ChatRunSocket first to abort all active runs and close EventSource connections
       if (chatRunServer) {
         chatRunServer.close()

packages/server/src/shared/providers.ts

@@ -62,13 +62,9 @@ export const PROVIDER_PRESETS: ProviderPreset[] = [
     base_url: 'https://generativelanguage.googleapis.com/v1beta/openai',
     models: [
       'gemini-3.1-pro-preview',
+      'gemini-3-pro-preview',
       'gemini-3-flash-preview',
       'gemini-3.1-flash-lite-preview',
-      'gemini-2.5-pro',
-      'gemini-2.5-flash',
-      'gemini-2.5-flash-lite',
-      'gemma-4-31b-it',
-      'gemma-4-26b-it',
     ],
   },
   {
@@ -76,7 +72,7 @@ export const PROVIDER_PRESETS: ProviderPreset[] = [
     value: 'deepseek',
     builtin: true,
     base_url: 'https://api.deepseek.com',
-    models: ['deepseek-v4-flash', 'deepseek-v4-pro'],
+    models: ['deepseek-v4-pro', 'deepseek-v4-flash', 'deepseek-chat', 'deepseek-reasoner'],
   },
   {
     label: 'Z.AI / GLM',
@@ -98,7 +94,6 @@ export const PROVIDER_PRESETS: ProviderPreset[] = [
     builtin: true,
     base_url: 'https://api.kimi.com/coding/v1',
     models: [
-      'kimi-for-coding',
       'kimi-k2.6',
       'kimi-k2.5',
       'kimi-k2-thinking',
@@ -124,7 +119,17 @@ export const PROVIDER_PRESETS: ProviderPreset[] = [
     value: 'xai',
     builtin: true,
     base_url: 'https://api.x.ai/v1',
-    models: ['grok-4.20-reasoning', 'grok-4-1-fast-reasoning'],
+    models: [
+      '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',
+    ],
   },
   {
     label: 'MiniMax',
@@ -146,12 +151,13 @@ export const PROVIDER_PRESETS: ProviderPreset[] = [
     builtin: true,
     base_url: 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1',
     models: [
+      'qwen3.6-plus',
+      'kimi-k2.5',
       'qwen3.5-plus',
       'qwen3-coder-plus',
       'qwen3-coder-next',
       'glm-5',
       'glm-4.7',
-      'kimi-k2.5',
       'MiniMax-M2.5',
     ],
   },
@@ -166,13 +172,13 @@ export const PROVIDER_PRESETS: ProviderPreset[] = [
     // returns HTTP 401 for those keys.
     base_url: 'https://coding-intl.dashscope.aliyuncs.com/v1',
     models: [
+      'qwen3.6-plus',
       'qwen3.5-plus',
-      'qwen3-max-2026-01-23',
-      'qwen3-coder-next',
       'qwen3-coder-plus',
+      'qwen3-coder-next',
+      'kimi-k2.5',
       'glm-5',
       'glm-4.7',
-      'kimi-k2.5',
       'MiniMax-M2.5',
     ],
   },
@@ -182,14 +188,15 @@ export const PROVIDER_PRESETS: ProviderPreset[] = [
     builtin: true,
     base_url: 'https://router.huggingface.co/v1',
     models: [
+      'moonshotai/Kimi-K2.5',
       'Qwen/Qwen3.5-397B-A17B',
       'Qwen/Qwen3.5-35B-A3B',
       'deepseek-ai/DeepSeek-V3.2',
-      'moonshotai/Kimi-K2.5',
       'MiniMaxAI/MiniMax-M2.5',
       'zai-org/GLM-5',
       'XiaomiMiMo/MiMo-V2-Flash',
       'moonshotai/Kimi-K2-Thinking',
+      'moonshotai/Kimi-K2.6',
     ],
   },
   {
@@ -214,14 +221,11 @@ export const PROVIDER_PRESETS: ProviderPreset[] = [
     builtin: true,
     base_url: 'https://api.xiaomimimo.com/v1',
     models: [
-      'mimo-v2-omni',
-      'mimo-v2-pro',
-      'mimo-v2-tts',
-      'mimo-v2.5',
       'mimo-v2.5-pro',
-      'mimo-v2.5-tts',
-      'mimo-v2.5-tts-voiceclone',
-      'mimo-v2.5-tts-voicedesign',
+      'mimo-v2.5',
+      'mimo-v2-pro',
+      'mimo-v2-omni',
+      'mimo-v2-flash',
     ],
   },
   {
@@ -243,18 +247,21 @@ export const PROVIDER_PRESETS: ProviderPreset[] = [
     builtin: true,
     base_url: 'https://ai-gateway.vercel.sh/v1',
     models: [
-      'anthropic/claude-opus-4.6',
+      'moonshotai/kimi-k2.6',
+      'alibaba/qwen3.6-plus',
+      'zai/glm-5.1',
+      'minimax/minimax-m2.7',
       'anthropic/claude-sonnet-4.6',
-      'anthropic/claude-sonnet-4.5',
+      'anthropic/claude-opus-4.7',
+      'anthropic/claude-opus-4.6',
       'anthropic/claude-haiku-4.5',
-      'openai/gpt-5',
-      'openai/gpt-4.1',
-      'openai/gpt-4.1-mini',
-      'google/gemini-3-pro-preview',
+      'openai/gpt-5.4',
+      'openai/gpt-5.4-mini',
+      'openai/gpt-5.3-codex',
+      'google/gemini-3.1-pro-preview',
       'google/gemini-3-flash',
-      'google/gemini-2.5-pro',
-      'google/gemini-2.5-flash',
-      'deepseek/deepseek-v3.2',
+      'google/gemini-3.1-flash-lite-preview',
+      'xai/grok-4.20-reasoning',
     ],
   },
   {
@@ -277,10 +284,10 @@ export const PROVIDER_PRESETS: ProviderPreset[] = [
     builtin: true,
     base_url: 'https://opencode.ai/zen/v1',
     models: [
+      'kimi-k2.5',
       'gpt-5.4-pro',
       'gpt-5.4',
       'gpt-5.3-codex',
-      'gpt-5.3-codex-spark',
       'gpt-5.2',
       'gpt-5.2-codex',
       'gpt-5.1',
@@ -308,7 +315,6 @@ export const PROVIDER_PRESETS: ProviderPreset[] = [
       'glm-5',
       'glm-4.7',
       'glm-4.6',
-      'kimi-k2.5',
       'kimi-k2-thinking',
       'kimi-k2',
       'qwen3-coder',
@@ -320,7 +326,20 @@ export const PROVIDER_PRESETS: ProviderPreset[] = [
     value: 'opencode-go',
     builtin: true,
     base_url: 'https://opencode.ai/zen/go/v1',
-    models: ['glm-5.1', 'glm-5', 'kimi-k2.5', 'mimo-v2-pro', 'mimo-v2-omni', 'minimax-m2.7', 'minimax-m2.5'],
+    models: [
+      'kimi-k2.6',
+      'kimi-k2.5',
+      'glm-5.1',
+      'glm-5',
+      'mimo-v2.5-pro',
+      'mimo-v2.5',
+      'mimo-v2-pro',
+      'mimo-v2-omni',
+      'minimax-m2.7',
+      'minimax-m2.5',
+      'qwen3.6-plus',
+      'qwen3.5-plus',
+    ],
   },
   {
     label: 'LongCat',
@@ -352,12 +371,13 @@ export const PROVIDER_PRESETS: ProviderPreset[] = [
       'moonshotai/kimi-k2.6',
       'xiaomi/mimo-v2.5-pro',
       'xiaomi/mimo-v2.5',
+      'tencent/hy3-preview',
       'anthropic/claude-opus-4.7',
       'anthropic/claude-opus-4.6',
       'anthropic/claude-sonnet-4.6',
       'anthropic/claude-sonnet-4.5',
       'anthropic/claude-haiku-4.5',
-      'openai/gpt-5.4',
+      'openai/gpt-5.5',
       'openai/gpt-5.4-mini',
       'openai/gpt-5.3-codex',
       'google/gemini-3-pro-preview',
@@ -374,10 +394,12 @@ export const PROVIDER_PRESETS: ProviderPreset[] = [
       'z-ai/glm-5v-turbo',
       'z-ai/glm-5-turbo',
       'x-ai/grok-4.20-beta',
+      'x-ai/grok-4.3',
       'nvidia/nemotron-3-super-120b-a12b',
       'arcee-ai/trinity-large-thinking',
-      'openai/gpt-5.4-pro',
+      'openai/gpt-5.5-pro',
       'openai/gpt-5.4-nano',
+      'deepseek/deepseek-v4-pro',
     ],
   },
   {