vellum 0.2.0 → 0.2.2

package/src/workspace/provider-commit-message-generator.ts

@@ -0,0 +1,242 @@
+import { getLogger } from '../util/logger.js';
+import { getConfig } from '../config/loader.js';
+import type { CommitContext } from './commit-message-provider.js';
+import { DefaultCommitMessageProvider } from './commit-message-provider.js';
+import type { Message } from '../providers/types.js';
+
+const log = getLogger('commit-message-llm');
+
+export type CommitMessageSource = 'llm' | 'deterministic';
+export type LLMFallbackReason =
+  | 'disabled'
+  | 'provider_not_initialized'
+  | 'breaker_open'
+  | 'insufficient_budget'
+  | 'timeout'
+  | 'provider_error'
+  | 'invalid_output';
+
+export interface GenerateCommitMessageResult {
+  message: string;
+  source: CommitMessageSource;
+  reason?: LLMFallbackReason;
+}
+
+interface GenerateOptions {
+  deadlineMs?: number;
+  changedFiles: string[];
+  diffSummary?: string;
+}
+
+const SYSTEM_PROMPT = `You generate concise git commit messages for workspace file changes.
+Rules:
+- Write a single short subject line (max 72 chars), optionally followed by a blank line and 2-4 concise bullet points
+- No markdown headings or formatting
+- Only mention files and changes actually provided
+- Total output must be under 300 characters
+- If you cannot determine a meaningful message, respond with exactly: FALLBACK`;
+
+const deterministicProvider = new DefaultCommitMessageProvider();
+
+function buildDeterministicResult(
+  context: CommitContext,
+  reason: LLMFallbackReason,
+): GenerateCommitMessageResult {
+  return {
+    message: deterministicProvider.buildImmediateMessage(context).message,
+    source: 'deterministic',
+    reason,
+  };
+}
+
+export class ProviderCommitMessageGenerator {
+  private consecutiveFailures = 0;
+  private nextAllowedAttemptMs = 0;
+
+  private isBreakerOpen(): boolean {
+    const config = getConfig();
+    const { openAfterFailures } = config.workspaceGit.commitMessageLLM.breaker;
+    if (this.consecutiveFailures < openAfterFailures) return false;
+    return Date.now() < this.nextAllowedAttemptMs;
+  }
+
+  private recordSuccess(): void {
+    if (this.consecutiveFailures > 0) {
+      log.info(
+        { previousFailures: this.consecutiveFailures },
+        'Commit message LLM breaker closed: succeeded after failures',
+      );
+    }
+    this.consecutiveFailures = 0;
+    this.nextAllowedAttemptMs = 0;
+  }
+
+  private recordFailure(): void {
+    const config = getConfig();
+    const { backoffBaseMs, backoffMaxMs } = config.workspaceGit.commitMessageLLM.breaker;
+    this.consecutiveFailures++;
+    const delay = Math.min(
+      backoffBaseMs * Math.pow(2, this.consecutiveFailures - 1),
+      backoffMaxMs,
+    );
+    this.nextAllowedAttemptMs = Date.now() + delay;
+    log.warn(
+      { consecutiveFailures: this.consecutiveFailures, backoffMs: delay },
+      'Commit message LLM breaker opened: backing off',
+    );
+  }
+
+  async generateCommitMessage(
+    context: CommitContext,
+    options: GenerateOptions,
+  ): Promise<GenerateCommitMessageResult> {
+    const config = getConfig();
+    const llmConfig = config.workspaceGit.commitMessageLLM;
+
+    // Step 1: Feature gate
+    if (!llmConfig.enabled) {
+      return buildDeterministicResult(context, 'disabled');
+    }
+
+    // Step 2: Provider gate
+    if (!llmConfig.useConfiguredProvider) {
+      return buildDeterministicResult(context, 'disabled');
+    }
+
+    // Step 3: Circuit breaker
+    if (this.isBreakerOpen()) {
+      log.debug(
+        { consecutiveFailures: this.consecutiveFailures },
+        'Commit message LLM breaker open; falling back to deterministic',
+      );
+      return buildDeterministicResult(context, 'breaker_open');
+    }
+
+    // Step 4: Budget check
+    if (options.deadlineMs !== undefined) {
+      const remaining = options.deadlineMs - Date.now();
+      if (remaining < llmConfig.minRemainingTurnBudgetMs) {
+        log.debug(
+          { remainingMs: remaining, minBudgetMs: llmConfig.minRemainingTurnBudgetMs },
+          'Insufficient budget for LLM commit message',
+        );
+        return buildDeterministicResult(context, 'insufficient_budget');
+      }
+    }
+
+    // Step 5: Call the provider
+    try {
+      const { getProvider } = await import('../providers/registry.js');
+
+      let provider;
+      try {
+        provider = getProvider(config.provider);
+      } catch {
+        log.debug({ provider: config.provider }, 'Provider not initialized; falling back to deterministic');
+        return buildDeterministicResult(context, 'provider_not_initialized');
+      }
+
+      // Build prompt
+      const fileList = options.changedFiles
+        .slice(0, llmConfig.maxFilesInPrompt)
+        .join('\n');
+      const truncatedSuffix = options.changedFiles.length > llmConfig.maxFilesInPrompt
+        ? `\n... and ${options.changedFiles.length - llmConfig.maxFilesInPrompt} more files`
+        : '';
+
+      let userText = `Changed files:\n${fileList}${truncatedSuffix}`;
+      if (options.diffSummary) {
+        const diffBytes = new TextEncoder().encode(options.diffSummary).length;
+        const diff = diffBytes > llmConfig.maxDiffBytes
+          ? new TextDecoder().decode(new TextEncoder().encode(options.diffSummary).slice(0, llmConfig.maxDiffBytes)) + '\n... (truncated)'
+          : options.diffSummary;
+        userText += `\n\nDiff summary:\n${diff}`;
+      }
+
+      const messages: Message[] = [
+        {
+          role: 'user',
+          content: [{ type: 'text', text: userText }],
+        },
+      ];
+
+      // AbortController with timeout
+      const ac = new AbortController();
+      const timer = setTimeout(() => ac.abort(), llmConfig.timeoutMs);
+
+      let response;
+      try {
+        response = await provider.sendMessage(
+          messages,
+          undefined,
+          SYSTEM_PROMPT,
+          {
+            signal: ac.signal,
+            config: { max_tokens: llmConfig.maxTokens, temperature: llmConfig.temperature },
+          },
+        );
+      } catch (err: unknown) {
+        clearTimeout(timer);
+        if (ac.signal.aborted) {
+          log.warn('Commit message LLM timed out; falling back to deterministic');
+          this.recordFailure();
+          return buildDeterministicResult(context, 'timeout');
+        }
+        throw err;
+      }
+      clearTimeout(timer);
+
+      // Extract text from response
+      const textBlocks = response.content.filter((b) => b.type === 'text');
+      const text = textBlocks
+        .map((b) => (b as { type: 'text'; text: string }).text)
+        .join('')
+        .trim();
+
+      // Validate output
+      if (!text || text === 'FALLBACK' || text.length > 500) {
+        log.debug(
+          { outputLength: text?.length ?? 0, isFallback: text === 'FALLBACK' },
+          'LLM output invalid; falling back to deterministic',
+        );
+        this.recordFailure();
+        return buildDeterministicResult(context, 'invalid_output');
+      }
+
+      // Validate single-line subject: first line must be <= 72 chars
+      const firstLine = text.split('\n')[0];
+      if (firstLine.length > 72) {
+        log.debug(
+          { subjectLength: firstLine.length },
+          'LLM subject line too long; falling back to deterministic',
+        );
+        this.recordFailure();
+        return buildDeterministicResult(context, 'invalid_output');
+      }
+
+      this.recordSuccess();
+      return { message: text, source: 'llm' };
+    } catch (err: unknown) {
+      // Step 6: Any error -> deterministic fallback
+      log.warn(
+        { err: err instanceof Error ? err.message : String(err) },
+        'Commit message LLM provider error; falling back to deterministic',
+      );
+      this.recordFailure();
+      return buildDeterministicResult(context, 'provider_error');
+    }
+  }
+}
+
+let instance: ProviderCommitMessageGenerator | null = null;
+
+export function getCommitMessageGenerator(): ProviderCommitMessageGenerator {
+  if (!instance) {
+    instance = new ProviderCommitMessageGenerator();
+  }
+  return instance;
+}
+
+export function _resetCommitMessageGenerator(): void {
+  instance = null;
+}

package/src/workspace/turn-commit.ts

@@ -11,6 +11,14 @@
 
 import { getWorkspaceGitService } from './git-service.js';
 import { getLogger } from '../util/logger.js';
+import {
+  DefaultCommitMessageProvider,
+  type CommitContext,
+  type CommitMessageProvider,
+} from './commit-message-provider.js';
+import { getEnrichmentService } from './commit-message-enrichment-service.js';
+import { getCommitMessageGenerator } from './provider-commit-message-generator.js';
+import type { CommitMessageSource, LLMFallbackReason } from './provider-commit-message-generator.js';
 
 const log = getLogger('turn-commit');
 
@@ -25,46 +33,6 @@ export interface TurnCommitMetadata {
   filesChanged: number;
 }
 
-/**
- * Build a commit message with structured metadata for a turn boundary commit.
- *
- * Format:
- * ```
- * Turn: <summary>
- *
- * Session: sess_xyz
- * Turn: 5
- * Timestamp: 2026-02-18T15:30:00Z
- * Files: 3 changed
- * ```
- */
-function buildCommitMessage(summary: string, metadata: TurnCommitMetadata): string {
-  return [
-    `Turn: ${summary}`,
-    '',
-    `Session: ${metadata.sessionId}`,
-    `Turn: ${metadata.turnNumber}`,
-    `Timestamp: ${metadata.timestamp}`,
-    `Files: ${metadata.filesChanged} changed`,
-  ].join('\n');
-}
-
-/**
- * Build a short summary of what changed from a list of file paths.
- */
-function buildChangeSummary(files: string[]): string {
-  if (files.length === 0) {
-    return 'workspace changes';
-  }
-  if (files.length === 1) {
-    return files[0];
-  }
-  if (files.length <= 3) {
-    return files.join(', ');
-  }
-  return `${files.slice(0, 2).join(', ')} and ${files.length - 2} more`;
-}
-
 /**
  * Attempt a turn-boundary commit for the workspace.
  *
@@ -77,40 +45,121 @@ function buildChangeSummary(files: string[]): string {
  * @param workspaceDir - Absolute path to the workspace directory
  * @param sessionId - Session/conversation identifier
  * @param turnNumber - 1-based turn number within the session
+ * @param provider - Optional commit message provider (defaults to deterministic)
+ * @param deadlineMs - Optional absolute deadline (Date.now()) after which the commit should be skipped
  */
 export async function commitTurnChanges(
   workspaceDir: string,
   sessionId: string,
   turnNumber: number,
+  provider?: CommitMessageProvider,
+  deadlineMs?: number,
 ): Promise<void> {
+  const messageProvider = provider ?? new DefaultCommitMessageProvider();
   try {
     const gitService = getWorkspaceGitService(workspaceDir);
+    const commitStartMs = Date.now();
+
+    // Attempt LLM message generation BEFORE entering commitIfDirty so
+    // the LLM call never runs while holding the git mutex.
+    // Only attempt LLM when:
+    //   1. No custom provider was injected (respect caller contract)
+    //   2. The workspace actually has pending changes (avoid wasting budget)
+    let llmMessage: string | undefined;
+    let commitMessageSource: CommitMessageSource = 'deterministic';
+    let llmFallbackReason: LLMFallbackReason | undefined;
+
+    if (!provider) {
+      // Guard: skip pre-check if deadline already elapsed to avoid unnecessary mutex contention
+      let preClean = false;
+      if (!deadlineMs || Date.now() < deadlineMs) {
+        try {
+          const preStatus = await gitService.getStatus();
+          preClean = preStatus.clean;
+        } catch {
+          // If we can't determine status, assume dirty so we don't skip the commit
+        }
+      }
+
+      if (!preClean) {
+        try {
+          const generator = getCommitMessageGenerator();
+          const result = await generator.generateCommitMessage(
+            {
+              workspaceDir,
+              trigger: 'turn',
+              sessionId,
+              turnNumber,
+              changedFiles: [], // File list unavailable outside the git mutex; generator handles empty arrays
+              timestampMs: Date.now(),
+            },
+            { deadlineMs, changedFiles: [] },
+          );
+          commitMessageSource = result.source;
+          llmFallbackReason = result.reason;
+          if (result.source === 'llm') {
+            llmMessage = result.message;
+          }
+        } catch (llmErr) {
+          // Never let LLM errors affect the commit path
+          log.debug({ err: llmErr }, 'LLM commit message generation failed (non-fatal)');
+          llmFallbackReason = 'provider_error';
+        }
+      }
+    }
 
-    // Atomic status check + commit within a single mutex lock to prevent
-    // TOCTOU races with heartbeat commits.
     const { committed, status } = await gitService.commitIfDirty((st) => {
       const uniqueFiles = [...new Set([...st.staged, ...st.modified, ...st.untracked])];
-      const timestamp = new Date().toISOString();
-      const summary = buildChangeSummary(uniqueFiles);
 
-      const metadata: TurnCommitMetadata = {
+      const ctx: CommitContext = {
+        workspaceDir,
+        trigger: 'turn',
         sessionId,
         turnNumber,
-        timestamp,
-        filesChanged: uniqueFiles.length,
+        changedFiles: uniqueFiles,
+        timestampMs: Date.now(),
       };
 
-      return { message: buildCommitMessage(summary, metadata) };
-    });
+      // Use LLM message if available, otherwise deterministic
+      if (llmMessage) {
+        return { message: llmMessage };
+      }
+      return messageProvider.buildImmediateMessage(ctx);
+    }, deadlineMs !== undefined ? { deadlineMs } : undefined);
+
+    const commitDurationMs = Date.now() - commitStartMs;
 
     if (committed) {
       const uniqueFiles = [...new Set([...status.staged, ...status.modified, ...status.untracked])];
       log.info(
-        { sessionId, turnNumber, filesChanged: uniqueFiles.length },
+        {
+          sessionId,
+          turnNumber,
+          filesChanged: uniqueFiles.length,
+          durationMs: commitDurationMs,
+          commitMessageSource,
+          ...(llmFallbackReason ? { llmFallbackReason } : {}),
+        },
         'Turn-boundary commit created',
       );
+
+      // Fire-and-forget enrichment — never blocks turn completion
+      try {
+        const commitHash = await gitService.getHeadHash();
+        const ctx: CommitContext = {
+          workspaceDir,
+          trigger: 'turn',
+          sessionId,
+          turnNumber,
+          changedFiles: uniqueFiles,
+          timestampMs: Date.now(),
+        };
+        getEnrichmentService().enqueue({ workspaceDir, commitHash, context: ctx, gitService });
+      } catch (enrichErr) {
+        log.debug({ enrichErr }, 'Failed to enqueue enrichment (non-fatal)');
+      }
     } else {
-      log.debug({ sessionId, turnNumber }, 'No workspace changes to commit for turn');
+      log.debug({ sessionId, turnNumber, durationMs: commitDurationMs }, 'No workspace changes to commit for turn');
     }
   } catch (err) {
     // Never let commit failures propagate — they must not affect the turn

package/src/tools/contacts/index.ts

@@ -1,4 +0,0 @@
-// Side-effect imports — each module calls registerTool() at the top level.
-import './contact-upsert.js';
-import './contact-search.js';
-import './contact-merge.js';

package/src/tools/document/index.ts

@@ -1,5 +0,0 @@
-export * from './document-tool.js';
-
-import { documentCreateTool, documentUpdateTool } from './document-tool.js';
-
-export const allDocumentTools = [documentCreateTool, documentUpdateTool];

package/src/tools/followups/index.ts

@@ -1,3 +0,0 @@
-export { followupCreateTool } from './followup_create.js';
-export { followupListTool } from './followup_list.js';
-export { followupResolveTool } from './followup_resolve.js';

package/src/tools/subagent/index.ts

@@ -1,5 +0,0 @@
-export { subagentSpawnTool } from './spawn.js';
-export { subagentStatusTool } from './status.js';
-export { subagentAbortTool } from './abort.js';
-export { subagentMessageTool } from './message.js';
-export { subagentReadTool } from './read.js';