feat: auto-title chat session with auxiliary

Author: jahilldev

api/src/agent/agent.model.ts

@@ -7,6 +7,7 @@ export const AGENT_PHASES = [
   'VERIFY',
   'JUDGE',
   'CHAT',
+  'TITLE',
 ] as const;
 export type AgentPhase = (typeof AGENT_PHASES)[number];
 

api/src/agent/agent.service.ts

@@ -219,7 +219,11 @@ export class HermesAgentService implements OnModuleInit {
       },
     });
 
-    await this.persistEvents(run.id);
+    // Only runs owned by a job or chat session surface their events anywhere; ownerless
+    // utility runs (e.g. TITLE generation) skip persistence to avoid orphan AgentEvent rows.
+    if (opts.jobId || opts.sessionId) {
+      await this.persistEvents(run.id);
+    }
     this.langfuse.complete(run.id);
     this.metrics.recordAgentRun(opts.phase, status, raw.durationMs);
 

api/src/chat/chat.prompts.ts

@@ -25,3 +25,15 @@ export function buildChatPrompt(p: {
     `Respond to the latest user message above. Output only your reply in GitHub-flavored Markdown — no preamble, no sign-off.`,
   ].join('\n\n');
 }
+
+/**
+ * Prompt for auto-titling a chat from its first user message. Demands ONLY the title text so
+ * the (tool-less) run's stdout can be used near-verbatim after a light cleanup.
+ */
+export function buildTitlePrompt(firstMessage: string): string {
+  return [
+    `Generate a short, descriptive title for a chat conversation that opens with the message below.`,
+    `Rules:\n- Output ONLY the title — no quotes, no markdown, no trailing punctuation, no preamble.\n- 3 to 6 words, Title Case.\n- Do NOT use any tools; just reply with the title.`,
+    `--- FIRST MESSAGE ---\n${firstMessage}\n--- END ---`,
+  ].join('\n\n');
+}

api/src/chat/chat.service.spec.ts

@@ -5,6 +5,7 @@ import type { AppConfigService } from '../config/config.service.js';
 import type { HermesAgentService } from '../agent/agent.service.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
 import type { LangfuseService } from '../langfuse/langfuse.service.js';
+import { cleanTitle } from './chat.utility.js';
 
 const resolved = (value: unknown) => jest.fn((..._args: unknown[]) => Promise.resolve(value));
 
@@ -31,6 +32,7 @@ function setup(overrides: { session?: Record<string, unknown> | null } = {}) {
     chatMessage: {
       create: resolved(undefined),
       findMany: resolved([{ role: 'user', content: 'hello' }]),
+      count: resolved(1),
     },
     agentEvent: { findMany: resolved([] as unknown[]), createMany: resolved(undefined) },
   };
@@ -132,3 +134,28 @@ describe('ChatService', () => {
     expect(activity).toEqual({ 'run-a': [ev] });
   });
 });
+
+describe('cleanTitle', () => {
+  it('strips quotes, markdown, a Title: prefix and trailing punctuation', () => {
+    expect(cleanTitle('"Refactor the Auth Module."')).toBe('Refactor the Auth Module');
+    expect(cleanTitle('Title: **Dark Mode Toggle**')).toBe('Dark Mode Toggle');
+    expect(cleanTitle('### Fix Flaky Tests')).toBe('Fix Flaky Tests');
+  });
+
+  it('takes the first non-empty line and collapses whitespace', () => {
+    expect(cleanTitle('\n\n  Cache   Invalidation Strategy \nmore prose')).toBe(
+      'Cache Invalidation Strategy',
+    );
+  });
+
+  it('returns empty string when nothing usable remains', () => {
+    expect(cleanTitle('   \n  ')).toBe('');
+  });
+
+  it('caps very long output on a word boundary', () => {
+    const long = `${'word '.repeat(40)}`.trim();
+    const out = cleanTitle(long);
+    expect(out.length).toBeLessThanOrEqual(80);
+    expect(out.endsWith('word')).toBe(true);
+  });
+});

api/src/chat/chat.service.ts

@@ -12,8 +12,8 @@ import {
   type ChatSessionDetailDto,
   type ChatSessionSummaryDto,
 } from './chat.model.js';
-import { buildChatPrompt } from './chat.prompts.js';
-import { eventsByRun, toMessageDto } from './chat.utility.js';
+import { buildChatPrompt, buildTitlePrompt } from './chat.prompts.js';
+import { cleanTitle, eventsByRun, toMessageDto } from './chat.utility.js';
 
 /**
  * Owns interactive chat sessions. Reuses HermesAgentService (CHAT phase) and the Langfuse
@@ -131,6 +131,8 @@ export class ChatService {
       throw new NotFoundException(`Chat session ${sessionId} not found`);
     }
 
+    const priorCount = await this.prisma.chatMessage.count({ where: { sessionId } });
+
     await this.prisma.chatMessage.create({ data: { sessionId, role: 'user', content } });
     await this.touch(sessionId);
 
@@ -146,6 +148,11 @@ export class ChatService {
       branchName: `chat-${sessionId.slice(0, 8)}`,
     });
 
+    // First message of an untitled session → auto-generate a title in the background.
+    if (priorCount === 0 && session.title === DEFAULT_CHAT_TITLE) {
+      void this.generateTitle(sessionId, ws.dir, content);
+    }
+
     const prompt = buildChatPrompt({ repoUrl: session.repoUrl, history });
 
     const runId = await new Promise<string>((resolve, reject) => {
@@ -195,6 +202,42 @@ export class ChatService {
     }
   }
 
+  /**
+   * Best-effort auto-title from the first user message via a short, tool-less agent run on the
+   * auxiliary model (falling back to the primary when no auxiliary is configured). Runs under the
+   * concurrency semaphore and is unowned (no jobId/sessionId), so it never shows as chat activity
+   * or as the session's active run. A failure or empty result leaves the default title in place.
+   */
+  private async generateTitle(sessionId: string, cwd: string, firstMessage: string): Promise<void> {
+    await this.acquire();
+
+    try {
+      const res = await this.agent.run({
+        phase: 'TITLE',
+        cwd,
+        prompt: buildTitlePrompt(firstMessage),
+        model: this.config.get('HERMES_AUXILIARY_MODEL') || this.config.get('HERMES_PRIMARY_MODEL'),
+        provider:
+          this.config.get('HERMES_AUXILIARY_PROVIDER') ||
+          this.config.get('HERMES_PRIMARY_PROVIDER'),
+      });
+
+      const title = res.status === 'SUCCEEDED' ? cleanTitle(res.stdout) : '';
+
+      // Only overwrite if still the default — a user/explicit title set meanwhile wins.
+      if (title.length > 0) {
+        await this.prisma.chatSession.updateMany({
+          where: { id: sessionId, title: DEFAULT_CHAT_TITLE },
+          data: { title },
+        });
+      }
+    } catch (e) {
+      this.logger.warn(`chat title generation failed: ${(e as Error).message}`);
+    } finally {
+      this.release();
+    }
+  }
+
   private authFor(session: ChatSession): RemoteAuth {
     return session.repoUrl ? { kind: 'ssh', url: session.repoUrl } : { kind: 'none' };
   }

api/src/chat/chat.utility.ts

@@ -2,6 +2,40 @@ import { type ChatMessage } from '@prisma/client';
 import { type LangfuseEvent } from '../langfuse/langfuse.model.js';
 import { type ChatMessageDto } from './chat.model.js';
 
+/**
+ * Normalizes a model's raw title output into a clean, short session title: takes the first
+ * non-empty line and strips quotes/markdown/`Title:` prefixes and trailing punctuation, then
+ * caps the length on a word boundary. Returns '' when nothing usable remains.
+ */
+export function cleanTitle(raw: string): string {
+  const firstLine = raw
+    .split('\n')
+    .map((l) => l.trim())
+    .find((l) => l.length > 0);
+
+  if (!firstLine) {
+    return '';
+  }
+
+  let t = firstLine
+    .replace(/^title:\s*/i, '')
+    .replace(/^[`*_#>\s-]+/, '')
+    .replace(/[`*_#]+$/, '')
+    .replace(/^["'“”‘’]+|["'“”‘’]+$/g, '')
+    .replace(/[.:;,]+$/, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  if (t.length > 80) {
+    t = t
+      .slice(0, 80)
+      .replace(/\s+\S*$/, '')
+      .trim();
+  }
+
+  return t;
+}
+
 export function toMessageDto(m: ChatMessage): ChatMessageDto {
   return {
     id: m.id,

api/src/metrics/metrics.model.ts

@@ -8,5 +8,6 @@ export type AgentPhaseLabel =
   | 'SUMMARY'
   | 'VERIFY'
   | 'JUDGE'
-  | 'CHAT';
+  | 'CHAT'
+  | 'TITLE';
 export type AgentRunStatusLabel = 'SUCCEEDED' | 'FAILED' | 'TIMED_OUT';