@yancyyu/openhermit 1.5.8

package/src/main/services/ccConnect/CcConnectClient.ts

@@ -0,0 +1,397 @@
+/**
+ * CcConnectClient — HTTP client for cc-connect Management API.
+ *
+ * Wraps all /api/v1/* endpoints needed by Hermit's team management layer.
+ * Default target: http://127.0.0.1:9820
+ */
+
+import { createLogger } from '@shared/utils/logger';
+
+import type {
+  CcAddPlatformRequest,
+  CcApiResponse,
+  CcConnectConfig,
+  CcCreateCronJobRequest,
+  CcCronJob,
+  CcGlobalProvider,
+  CcHeartbeatStatus,
+  CcModelEntry,
+  CcProjectDetail,
+  CcProjectListItem,
+  CcProjectSettingsUpdate,
+  CcProviderPresetsResponse,
+  CcSessionDetail,
+  CcSessionListItem,
+  CcStatus,
+} from '@shared/types/ccConnect';
+import { CC_CONNECT_DEFAULTS } from '@shared/types/ccConnect';
+
+const logger = createLogger('CcConnectClient');
+
+export class CcConnectClient {
+  private baseUrl: string;
+  private token: string;
+  private readonly timeoutMs: number;
+
+  constructor(config?: Partial<CcConnectConfig>) {
+    this.baseUrl = (
+      config?.baseUrl ??
+      process.env.CC_CONNECT_BASE_URL ??
+      CC_CONNECT_DEFAULTS.baseUrl
+    ).replace(/\/+$/, '');
+    this.token = (
+      config?.token ??
+      process.env.CC_CONNECT_TOKEN ??
+      process.env.CC_CONNECT_MANAGEMENT_TOKEN ??
+      ''
+    ).trim();
+    this.timeoutMs = 15_000;
+  }
+
+  // ===========================================================================
+  // Internal helpers
+  // ===========================================================================
+
+  private buildHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    };
+    if (this.token) {
+      headers['Authorization'] = `Bearer ${this.token}`;
+    }
+    return headers;
+  }
+
+  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: this.buildHeaders(),
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+
+      const text = await response.text();
+      if (!text.trim()) {
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}`);
+        }
+        return undefined as T;
+      }
+
+      let json: CcApiResponse<T>;
+      try {
+        json = JSON.parse(text) as CcApiResponse<T>;
+      } catch {
+        throw new Error(`cc-connect returned non-JSON: ${text.slice(0, 200)}`);
+      }
+
+      if (!response.ok || json.ok === false) {
+        throw new Error(json.error ?? `HTTP ${response.status}: ${text.slice(0, 200)}`);
+      }
+
+      return (json.data ?? json) as T;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  // ===========================================================================
+  // Status
+  // ===========================================================================
+
+  async getStatus(): Promise<CcStatus> {
+    return this.request<CcStatus>('GET', '/api/v1/status');
+  }
+
+  async isAvailable(): Promise<boolean> {
+    try {
+      await this.getStatus();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  // ===========================================================================
+  // Projects
+  // ===========================================================================
+
+  async listProjects(): Promise<CcProjectListItem[]> {
+    const data = await this.request<{ projects: CcProjectListItem[] }>('GET', '/api/v1/projects');
+    return data.projects ?? [];
+  }
+
+  async getProject(name: string): Promise<CcProjectDetail> {
+    return this.request<CcProjectDetail>('GET', `/api/v1/projects/${encodeURIComponent(name)}`);
+  }
+
+  async updateProject(
+    name: string,
+    settings: CcProjectSettingsUpdate
+  ): Promise<{ message: string; restart_required: boolean }> {
+    return this.request('PATCH', `/api/v1/projects/${encodeURIComponent(name)}`, settings);
+  }
+
+  async deleteProject(name: string): Promise<{ message: string; restart_required: boolean }> {
+    return this.request('DELETE', `/api/v1/projects/${encodeURIComponent(name)}`);
+  }
+
+  /**
+   * Stop a project: delete it from cc-connect and restart to activate changes.
+   * This effectively stops all sessions and agents for the project.
+   */
+  async stopProject(name: string): Promise<void> {
+    try {
+      const result = await this.deleteProject(name);
+      if (result.restart_required) {
+        await this.restart();
+      }
+      logger.info(`cc-connect project "${name}" stopped`);
+    } catch (err) {
+      // Project might already not exist — log but don't throw
+      logger.warn(`Failed to stop project "${name}": ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  /**
+   * Create a new project by adding a platform.
+   * If the project doesn't exist, cc-connect creates it automatically.
+   * Requires a restart afterwards for the new engine to start.
+   */
+  async createProject(
+    name: string,
+    agentType: string,
+    workDir: string,
+    platformType: string = 'bridge',
+    platformOptions: Record<string, string> = {}
+  ): Promise<{ message: string; restart_required: boolean }> {
+    const body: CcAddPlatformRequest = {
+      type: platformType,
+      options: platformOptions,
+      work_dir: workDir,
+      agent_type: agentType,
+    };
+    return this.request('POST', `/api/v1/projects/${encodeURIComponent(name)}/add-platform`, body);
+  }
+
+  // ===========================================================================
+  // Restart / Reload
+  // ===========================================================================
+
+  async restart(): Promise<void> {
+    await this.request('POST', '/api/v1/restart', {});
+    logger.info('cc-connect restart triggered');
+  }
+
+  async reload(): Promise<void> {
+    await this.request('POST', '/api/v1/reload', {});
+  }
+
+  /**
+   * Create project and restart cc-connect to activate it.
+   * Convenience wrapper around createProject + restart.
+   */
+  async createProjectAndStart(
+    name: string,
+    agentType: string,
+    workDir: string,
+    platformType: string = 'bridge',
+    platformOptions: Record<string, string> = {}
+  ): Promise<void> {
+    const result = await this.createProject(
+      name,
+      agentType,
+      workDir,
+      platformType,
+      platformOptions
+    );
+    if (result.restart_required) {
+      await this.restart();
+    }
+  }
+
+  // ===========================================================================
+  // Messages
+  // ===========================================================================
+
+  async sendMessage(projectName: string, sessionKey: string, message: string): Promise<void> {
+    await this.request('POST', `/api/v1/projects/${encodeURIComponent(projectName)}/send`, {
+      session_key: sessionKey,
+      message,
+    });
+  }
+
+  // ===========================================================================
+  // Sessions
+  // ===========================================================================
+
+  async listSessions(projectName: string): Promise<CcSessionListItem[]> {
+    const data = await this.request<{ sessions: CcSessionListItem[] }>(
+      'GET',
+      `/api/v1/projects/${encodeURIComponent(projectName)}/sessions`
+    );
+    return data.sessions ?? [];
+  }
+
+  async getSession(
+    projectName: string,
+    sessionId: string,
+    historyLimit: number = 500
+  ): Promise<CcSessionDetail> {
+    return this.request<CcSessionDetail>(
+      'GET',
+      `/api/v1/projects/${encodeURIComponent(projectName)}/sessions/${encodeURIComponent(sessionId)}?history_limit=${historyLimit}`
+    );
+  }
+
+  async createSession(projectName: string, name?: string): Promise<CcSessionDetail> {
+    return this.request<CcSessionDetail>(
+      'POST',
+      `/api/v1/projects/${encodeURIComponent(projectName)}/sessions`,
+      name ? { name } : {}
+    );
+  }
+
+  async deleteSession(projectName: string, sessionId: string): Promise<void> {
+    await this.request(
+      'DELETE',
+      `/api/v1/projects/${encodeURIComponent(projectName)}/sessions/${encodeURIComponent(sessionId)}`
+    );
+  }
+
+  // ===========================================================================
+  // Heartbeat
+  // ===========================================================================
+
+  async getHeartbeat(projectName: string): Promise<CcHeartbeatStatus> {
+    return this.request<CcHeartbeatStatus>(
+      'GET',
+      `/api/v1/projects/${encodeURIComponent(projectName)}/heartbeat`
+    );
+  }
+
+  async pauseHeartbeat(projectName: string): Promise<void> {
+    await this.request(
+      'POST',
+      `/api/v1/projects/${encodeURIComponent(projectName)}/heartbeat/pause`,
+      {}
+    );
+  }
+
+  async resumeHeartbeat(projectName: string): Promise<void> {
+    await this.request(
+      'POST',
+      `/api/v1/projects/${encodeURIComponent(projectName)}/heartbeat/resume`,
+      {}
+    );
+  }
+
+  // ===========================================================================
+  // Providers
+  // ===========================================================================
+
+  async listProviders(): Promise<CcGlobalProvider[]> {
+    const data = await this.request<{ providers: CcGlobalProvider[] }>('GET', '/api/v1/providers');
+    return data.providers ?? [];
+  }
+
+  async getProviderPresets(): Promise<CcProviderPresetsResponse> {
+    return this.request<CcProviderPresetsResponse>('GET', '/api/v1/providers/presets');
+  }
+
+  async addProvider(provider: CcGlobalProvider): Promise<{ name: string; message: string }> {
+    return this.request('POST', '/api/v1/providers', provider);
+  }
+
+  async updateProvider(
+    name: string,
+    patch: Partial<CcGlobalProvider>
+  ): Promise<{ message: string }> {
+    return this.request('PUT', `/api/v1/providers/${encodeURIComponent(name)}`, patch);
+  }
+
+  async deleteProvider(name: string): Promise<{ message: string }> {
+    return this.request('DELETE', `/api/v1/providers/${encodeURIComponent(name)}`);
+  }
+
+  // ===========================================================================
+  // Models
+  // ===========================================================================
+
+  async listModels(projectName: string): Promise<CcModelEntry[]> {
+    const data = await this.request<{ models: CcModelEntry[] }>(
+      'GET',
+      `/api/v1/projects/${encodeURIComponent(projectName)}/models`
+    );
+    return data.models ?? [];
+  }
+
+  // ===========================================================================
+  // Provider References (per-project)
+  // ===========================================================================
+
+  async getProviderRefs(projectName: string): Promise<string[]> {
+    const data = await this.request<{ provider_refs: string[] }>(
+      'GET',
+      `/api/v1/projects/${encodeURIComponent(projectName)}/provider-refs`
+    );
+    return data.provider_refs ?? [];
+  }
+
+  async setProviderRefs(projectName: string, providerRefs: string[]): Promise<void> {
+    await this.request('PUT', `/api/v1/projects/${encodeURIComponent(projectName)}/provider-refs`, {
+      provider_refs: providerRefs,
+    });
+  }
+
+  // ===========================================================================
+  // Global settings
+  // ===========================================================================
+
+  async getGlobalSettings(): Promise<Record<string, unknown>> {
+    return this.request<Record<string, unknown>>('GET', '/api/v1/settings');
+  }
+
+  async patchGlobalSettings(patch: Record<string, unknown>): Promise<Record<string, unknown>> {
+    return this.request<Record<string, unknown>>('PATCH', '/api/v1/settings', patch);
+  }
+
+  // ===========================================================================
+  // Cron jobs
+  // ===========================================================================
+
+  async listCronJobs(): Promise<CcCronJob[]> {
+    const data = await this.request<{ jobs: CcCronJob[] }>('GET', '/api/v1/cron');
+    return data.jobs ?? [];
+  }
+
+  async createCronJob(input: CcCreateCronJobRequest): Promise<CcCronJob> {
+    return this.request<CcCronJob>('POST', '/api/v1/cron', input);
+  }
+
+  async updateCronJob(id: string, patch: Partial<CcCreateCronJobRequest> & { enabled?: boolean }): Promise<CcCronJob> {
+    return this.request<CcCronJob>('PATCH', `/api/v1/cron/${encodeURIComponent(id)}`, patch);
+  }
+
+  async deleteCronJob(id: string): Promise<void> {
+    await this.request('DELETE', `/api/v1/cron/${encodeURIComponent(id)}`);
+  }
+
+  // ===========================================================================
+  // Configuration update
+  // ===========================================================================
+
+  updateConfig(config: Partial<CcConnectConfig>): void {
+    if (config.baseUrl) {
+      this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+    }
+    if (config.token !== undefined) {
+      this.token = config.token.trim();
+    }
+  }
+}

package/src/main/services/ccConnect/MessageBridge.ts

@@ -0,0 +1,162 @@
+/**
+ * MessageBridge — Routes cc-connect Bridge WebSocket messages to Hermit
+ * team members and broadcasts them as SSE events.
+ *
+ * Receives agent output from CcConnectBridge, maps session_key back to
+ * team/member using ProjectMappingStore, and emits SSE events.
+ */
+
+import { createLogger } from '@shared/utils/logger';
+
+import type {
+  CcBridgeIncomingMessage,
+  CcBridgeReplyMessage,
+  CcBridgeReplyStreamMessage,
+} from '@shared/types/ccConnect';
+import type { CcConnectBridge } from './CcConnectBridge';
+import type { ProjectMappingStore } from './ProjectMappingStore';
+
+const logger = createLogger('MessageBridge');
+
+export interface TeamMessageEvent {
+  teamName: string;
+  memberName: string;
+  type: 'reply' | 'reply_stream' | 'typing_start' | 'typing_stop' | 'card' | 'buttons';
+  content?: string;
+  delta?: string;
+  fullText?: string;
+  done?: boolean;
+  sessionKey: string;
+  timestamp: string;
+  raw?: unknown;
+}
+
+export type BroadcastFn = (channel: string, data: unknown) => void;
+
+export class MessageBridge {
+  private broadcastFn: BroadcastFn | null = null;
+
+  constructor(
+    private readonly bridge: CcConnectBridge,
+    private readonly mappingStore: ProjectMappingStore
+  ) {
+    this.bridge.on('reply', (msg: CcBridgeReplyMessage) => this.handleReply(msg));
+    this.bridge.on('reply_stream', (msg: CcBridgeReplyStreamMessage) =>
+      this.handleReplyStream(msg)
+    );
+    this.bridge.on('message', (msg: CcBridgeIncomingMessage) => this.handleGenericMessage(msg));
+  }
+
+  setBroadcast(fn: BroadcastFn): void {
+    this.broadcastFn = fn;
+  }
+
+  private resolveMapping(sessionKey: string): { teamName: string; memberName: string } | null {
+    // Session key format: bridge:hermit-{teamName}:{memberName}
+    // or look up by stored session key in mappings
+    const mapping = this.mappingStore.getAllMappings().find((m) => m.sessionKey === sessionKey);
+    if (mapping) {
+      return { teamName: mapping.teamName, memberName: mapping.memberName };
+    }
+
+    // Try parsing from session key pattern
+    const match = sessionKey.match(/^bridge:hermit-([^:]+):(.+)$/);
+    if (match) {
+      return { teamName: match[1], memberName: match[2] };
+    }
+
+    // Try matching cc-connect project name from any session key
+    for (const m of this.mappingStore.getAllMappings()) {
+      if (sessionKey.includes(m.ccProjectName)) {
+        return { teamName: m.teamName, memberName: m.memberName };
+      }
+    }
+
+    return null;
+  }
+
+  private handleReply(msg: CcBridgeReplyMessage): void {
+    const target = this.resolveMapping(msg.session_key);
+    if (!target) {
+      logger.warn(`No mapping found for session_key: ${msg.session_key}`);
+      return;
+    }
+
+    const event: TeamMessageEvent = {
+      teamName: target.teamName,
+      memberName: target.memberName,
+      type: 'reply',
+      content: msg.content,
+      sessionKey: msg.session_key,
+      timestamp: new Date().toISOString(),
+    };
+
+    this.broadcast(event);
+  }
+
+  private handleReplyStream(msg: CcBridgeReplyStreamMessage): void {
+    const target = this.resolveMapping(msg.session_key);
+    if (!target) return;
+
+    const event: TeamMessageEvent = {
+      teamName: target.teamName,
+      memberName: target.memberName,
+      type: 'reply_stream',
+      delta: msg.delta,
+      fullText: msg.full_text,
+      done: msg.done,
+      sessionKey: msg.session_key,
+      timestamp: new Date().toISOString(),
+    };
+
+    this.broadcast(event);
+  }
+
+  private handleGenericMessage(msg: CcBridgeIncomingMessage): void {
+    if (msg.type === 'typing_start' || msg.type === 'typing_stop') {
+      const target = this.resolveMapping(msg.session_key);
+      if (!target) return;
+
+      const event: TeamMessageEvent = {
+        teamName: target.teamName,
+        memberName: target.memberName,
+        type: msg.type,
+        sessionKey: msg.session_key,
+        timestamp: new Date().toISOString(),
+      };
+      this.broadcast(event);
+      return;
+    }
+
+    // For card, buttons, etc. — forward as raw
+    if ('session_key' in msg) {
+      const target = this.resolveMapping((msg as { session_key: string }).session_key);
+      if (!target) return;
+
+      const event: TeamMessageEvent = {
+        teamName: target.teamName,
+        memberName: target.memberName,
+        type: msg.type as TeamMessageEvent['type'],
+        sessionKey: (msg as { session_key: string }).session_key,
+        timestamp: new Date().toISOString(),
+        raw: msg,
+      };
+      this.broadcast(event);
+    }
+  }
+
+  private broadcast(event: TeamMessageEvent): void {
+    if (!this.broadcastFn) return;
+
+    // Broadcast as team-change for general team state updates
+    this.broadcastFn('team-change', {
+      type: 'message',
+      teamName: event.teamName,
+      memberName: event.memberName,
+      detail: event,
+    });
+
+    // Also broadcast as agent-message for message-specific listeners
+    this.broadcastFn('agent-message', event);
+  }
+}

package/src/main/services/ccConnect/ProjectMappingStore.ts

@@ -0,0 +1,148 @@
+/**
+ * ProjectMappingStore — Persists the mapping between Hermit team members
+ * and cc-connect project names.
+ *
+ * Storage: ~/.hermit/cc-connect-mappings.json
+ */
+
+import { getErrorMessage } from '@shared/utils/errorHandling';
+import { createLogger } from '@shared/utils/logger';
+import * as fs from 'fs';
+import * as path from 'path';
+
+import type { CcAgentType, CcProjectMapping } from '@shared/types/ccConnect';
+
+const logger = createLogger('ProjectMappingStore');
+
+/**
+ * Generate a deterministic cc-connect project name from team/member names.
+ * Format: hermit-{teamName}-{memberName} (slug-ified)
+ */
+export function buildCcProjectName(teamName: string, memberName: string): string {
+  const slug = (s: string) =>
+    s
+      .toLowerCase()
+      .replace(/[^a-z0-9\u4e00-\u9fff-]/g, '-')
+      .replace(/-+/g, '-')
+      .replace(/^-|-$/g, '');
+  return `hermit-${slug(teamName)}-${slug(memberName)}`;
+}
+
+export class ProjectMappingStore {
+  private mappings: CcProjectMapping[] = [];
+  private readonly filePath: string;
+
+  constructor(dataDir: string) {
+    this.filePath = path.join(dataDir, 'cc-connect-mappings.json');
+    this.load();
+  }
+
+  // ===========================================================================
+  // Read
+  // ===========================================================================
+
+  getProjectName(teamName: string, memberName: string): string | null {
+    const entry = this.mappings.find((m) => m.teamName === teamName && m.memberName === memberName);
+    return entry?.ccProjectName ?? null;
+  }
+
+  getTeamProjects(teamName: string): CcProjectMapping[] {
+    return this.mappings.filter((m) => m.teamName === teamName);
+  }
+
+  getAllMappings(): CcProjectMapping[] {
+    return [...this.mappings];
+  }
+
+  findByProjectName(ccProjectName: string): CcProjectMapping | null {
+    return this.mappings.find((m) => m.ccProjectName === ccProjectName) ?? null;
+  }
+
+  // ===========================================================================
+  // Write
+  // ===========================================================================
+
+  setMapping(
+    teamName: string,
+    memberName: string,
+    agentType: CcAgentType,
+    workDir: string,
+    ccProjectName?: string
+  ): CcProjectMapping {
+    const now = new Date().toISOString();
+    const existing = this.mappings.find(
+      (m) => m.teamName === teamName && m.memberName === memberName
+    );
+
+    if (existing) {
+      existing.agentType = agentType;
+      existing.workDir = workDir;
+      existing.updatedAt = now;
+      if (ccProjectName) existing.ccProjectName = ccProjectName;
+      this.save();
+      return existing;
+    }
+
+    const mapping: CcProjectMapping = {
+      teamName,
+      memberName,
+      ccProjectName: ccProjectName ?? buildCcProjectName(teamName, memberName),
+      agentType,
+      workDir,
+      createdAt: now,
+      updatedAt: now,
+    };
+    this.mappings.push(mapping);
+    this.save();
+    return mapping;
+  }
+
+  updateSessionKey(teamName: string, memberName: string, sessionKey: string): void {
+    const entry = this.mappings.find((m) => m.teamName === teamName && m.memberName === memberName);
+    if (entry) {
+      entry.sessionKey = sessionKey;
+      entry.updatedAt = new Date().toISOString();
+      this.save();
+    }
+  }
+
+  removeMapping(teamName: string, memberName: string): void {
+    this.mappings = this.mappings.filter(
+      (m) => !(m.teamName === teamName && m.memberName === memberName)
+    );
+    this.save();
+  }
+
+  removeTeamMappings(teamName: string): void {
+    this.mappings = this.mappings.filter((m) => m.teamName !== teamName);
+    this.save();
+  }
+
+  // ===========================================================================
+  // Persistence
+  // ===========================================================================
+
+  private load(): void {
+    try {
+      if (fs.existsSync(this.filePath)) {
+        const data = fs.readFileSync(this.filePath, 'utf-8');
+        this.mappings = JSON.parse(data) as CcProjectMapping[];
+      }
+    } catch (error) {
+      logger.warn(`Failed to load mappings from ${this.filePath}: ${getErrorMessage(error)}`);
+      this.mappings = [];
+    }
+  }
+
+  private save(): void {
+    try {
+      const dir = path.dirname(this.filePath);
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      fs.writeFileSync(this.filePath, JSON.stringify(this.mappings, null, 2), 'utf-8');
+    } catch (error) {
+      logger.warn(`Failed to save mappings to ${this.filePath}: ${getErrorMessage(error)}`);
+    }
+  }
+}