@vellumai/assistant 0.3.0

package/src/workspace/heartbeat-service.ts

@@ -0,0 +1,345 @@
+import { getLogger } from '../util/logger.js';
+import { getAllWorkspaceGitServices, type WorkspaceGitService } from './git-service.js';
+import {
+  DefaultCommitMessageProvider,
+  type CommitContext,
+  type CommitMessageProvider,
+} from './commit-message-provider.js';
+import { getEnrichmentService } from './commit-message-enrichment-service.js';
+
+const log = getLogger('heartbeat');
+
+/** Threshold: commit if changes are older than this (ms). Default: 5 minutes. */
+const DEFAULT_AGE_THRESHOLD_MS = 5 * 60 * 1000;
+
+/** Threshold: commit if more than this many files have changed. Default: 20. */
+const DEFAULT_FILE_THRESHOLD = 20;
+
+/** How often the heartbeat runs (ms). Default: 5 minutes. */
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 5 * 60 * 1000;
+
+export interface HeartbeatServiceOptions {
+  /** Maximum age of uncommitted changes before auto-commit (ms). */
+  ageThresholdMs?: number;
+  /** Maximum number of changed files before auto-commit. */
+  fileThreshold?: number;
+  /** Interval between heartbeat checks (ms). */
+  intervalMs?: number;
+  /** Override for getting workspace git services (for testing). */
+  getServices?: () => ReadonlyMap<string, WorkspaceGitService>;
+  /** Override for getting the current timestamp (for testing). */
+  now?: () => number;
+  /** Custom commit message provider. */
+  commitMessageProvider?: CommitMessageProvider;
+}
+
+/**
+ * Result of a single heartbeat check cycle.
+ */
+export interface HeartbeatCheckResult {
+  /** Number of workspaces checked. */
+  checked: number;
+  /** Number of workspaces that had commits created. */
+  committed: number;
+  /** Number of workspaces skipped (clean or below thresholds). */
+  skipped: number;
+  /** Number of workspaces that failed during check. */
+  failed: number;
+}
+
+/**
+ * Tracks when changes were first detected in each workspace, so the heartbeat
+ * can determine whether changes are "old enough" to warrant an auto-commit.
+ */
+const firstSeenDirty = new Map<string, number>();
+
+/**
+ * Heartbeat service that periodically checks all tracked workspaces for
+ * uncommitted changes and auto-commits them when thresholds are met.
+ *
+ * This is a SAFETY NET -- turn-boundary commits (M2) handle the primary case.
+ * The heartbeat catches:
+ * - Long-running bash scripts that modify files without returning to the agent loop
+ * - Background processes that write to the workspace
+ * - Forgotten state from crashed or interrupted sessions
+ */
+export class HeartbeatService {
+  private readonly ageThresholdMs: number;
+  private readonly fileThreshold: number;
+  private readonly intervalMs: number;
+  private readonly getServices: () => ReadonlyMap<string, WorkspaceGitService>;
+  private readonly now: () => number;
+  private readonly commitMessageProvider: CommitMessageProvider;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  /** Tracks the currently in-flight check to prevent overlapping runs and allow clean shutdown. */
+  private activeCheck: Promise<HeartbeatCheckResult> | null = null;
+
+  constructor(options?: HeartbeatServiceOptions) {
+    this.ageThresholdMs = options?.ageThresholdMs ?? DEFAULT_AGE_THRESHOLD_MS;
+    this.fileThreshold = options?.fileThreshold ?? DEFAULT_FILE_THRESHOLD;
+    this.intervalMs = options?.intervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+    this.getServices = options?.getServices ?? getAllWorkspaceGitServices;
+    this.now = options?.now ?? Date.now;
+    this.commitMessageProvider = options?.commitMessageProvider ?? new DefaultCommitMessageProvider();
+  }
+
+  /**
+   * Start the periodic heartbeat timer.
+   * Idempotent -- calling start() when already running is a no-op.
+   */
+  start(): void {
+    if (this.timer) return;
+    log.info(
+      { intervalMs: this.intervalMs, ageThresholdMs: this.ageThresholdMs, fileThreshold: this.fileThreshold },
+      'Heartbeat service started',
+    );
+    this.timer = setInterval(() => {
+      this.check().catch((err) => {
+        log.error({ err }, 'Heartbeat check failed');
+      });
+    }, this.intervalMs);
+  }
+
+  /**
+   * Stop the periodic heartbeat timer and wait for any in-flight check to complete.
+   * This prevents races between the heartbeat check and shutdown commits.
+   */
+  async stop(): Promise<void> {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (this.activeCheck) {
+      await this.activeCheck;
+    }
+    log.info('Heartbeat service stopped');
+  }
+
+  /**
+   * Run a single heartbeat check across all tracked workspaces.
+   * For each workspace with uncommitted changes that exceed the age or file
+   * threshold, an auto-commit is created.
+   *
+   * If a previous check is still in-flight, this returns immediately with
+   * zeroed results to prevent overlapping commits on the same workspaces.
+   */
+  async check(): Promise<HeartbeatCheckResult> {
+    // Guard: skip if a previous check is still running
+    if (this.activeCheck) {
+      return { checked: 0, committed: 0, skipped: 0, failed: 0 };
+    }
+
+    const doCheck = async (): Promise<HeartbeatCheckResult> => {
+      const result: HeartbeatCheckResult = {
+        checked: 0,
+        committed: 0,
+        skipped: 0,
+        failed: 0,
+      };
+
+      const services = this.getServices();
+
+      for (const [workspaceDir, service] of services) {
+        // Only check workspaces that have been initialized (have a .git dir).
+        // Skip workspaces that haven't been used yet to avoid spurious init.
+        if (!service.isInitialized()) {
+          continue;
+        }
+
+        result.checked++;
+
+        try {
+          const committed = await this.checkWorkspace(workspaceDir, service);
+          if (committed) {
+            result.committed++;
+          } else {
+            result.skipped++;
+          }
+        } catch (err) {
+          log.warn({ err, workspaceDir }, 'Heartbeat check failed for workspace');
+          result.failed++;
+        }
+      }
+
+      if (result.committed > 0) {
+        log.info(result, 'Heartbeat check completed with commits');
+      }
+
+      return result;
+    };
+
+    this.activeCheck = doCheck();
+    try {
+      return await this.activeCheck;
+    } finally {
+      this.activeCheck = null;
+    }
+  }
+
+  /**
+   * Commit any pending changes in all tracked workspaces as a shutdown safety net.
+   * Called during graceful daemon shutdown to ensure no workspace state is lost.
+   */
+  async commitAllPending(): Promise<HeartbeatCheckResult> {
+    const result: HeartbeatCheckResult = {
+      checked: 0,
+      committed: 0,
+      skipped: 0,
+      failed: 0,
+    };
+
+    const services = this.getServices();
+
+    for (const [workspaceDir, service] of services) {
+      if (!service.isInitialized()) {
+        continue;
+      }
+
+      result.checked++;
+
+      try {
+        const now = this.now();
+        let shutdownFiles: string[] = [];
+        const { committed } = await service.commitIfDirty((st) => {
+          const uniqueFiles = [...new Set([...st.staged, ...st.modified, ...st.untracked])];
+          shutdownFiles = uniqueFiles;
+          log.info({ workspaceDir, totalChanges: uniqueFiles.length }, 'Committing pending changes on shutdown');
+
+          const ctx: CommitContext = {
+            workspaceDir,
+            trigger: 'shutdown',
+            changedFiles: uniqueFiles,
+            timestampMs: now,
+          };
+
+          return this.commitMessageProvider.buildImmediateMessage(ctx);
+        }, { bypassBreaker: true });
+
+        if (committed) {
+          firstSeenDirty.delete(workspaceDir);
+          result.committed++;
+
+          // Fire-and-forget enrichment
+          try {
+            const commitHash = await service.getHeadHash();
+            const shutdownCtx: CommitContext = {
+              workspaceDir,
+              trigger: 'shutdown',
+              changedFiles: shutdownFiles,
+              timestampMs: this.now(),
+            };
+            getEnrichmentService().enqueue({ workspaceDir, commitHash, context: shutdownCtx, gitService: service });
+          } catch (enrichErr) {
+            log.debug({ enrichErr }, 'Failed to enqueue shutdown enrichment (non-fatal)');
+          }
+        } else {
+          result.skipped++;
+        }
+      } catch (err) {
+        log.warn({ err, workspaceDir }, 'Shutdown commit failed for workspace');
+        result.failed++;
+      }
+    }
+
+    if (result.committed > 0) {
+      log.info(result, 'Shutdown commits completed');
+    }
+
+    return result;
+  }
+
+  /**
+   * Check a single workspace and commit if thresholds are exceeded.
+   *
+   * @returns true if a commit was created
+   */
+  private async checkWorkspace(
+    workspaceDir: string,
+    service: WorkspaceGitService,
+  ): Promise<boolean> {
+    const now = this.now();
+    let heartbeatFiles: string[] = [];
+    let heartbeatReason: string | undefined;
+
+    // Atomic status check + conditional commit within a single mutex lock.
+    const { committed, status } = await service.commitIfDirty((st) => {
+      const uniqueFiles = [...new Set([...st.staged, ...st.modified, ...st.untracked])];
+      const totalChanges = uniqueFiles.length;
+
+      // Track when we first saw this workspace as dirty
+      if (!firstSeenDirty.has(workspaceDir)) {
+        firstSeenDirty.set(workspaceDir, now);
+      }
+
+      const dirtyAge = now - firstSeenDirty.get(workspaceDir)!;
+
+      // Check thresholds: commit if changes are old enough OR if too many files changed
+      const ageExceeded = dirtyAge >= this.ageThresholdMs;
+      const fileCountExceeded = totalChanges >= this.fileThreshold;
+
+      if (!ageExceeded && !fileCountExceeded) {
+        log.debug(
+          { workspaceDir, totalChanges, dirtyAgeMs: dirtyAge },
+          'Changes below threshold, skipping heartbeat commit',
+        );
+        return null; // Don't commit yet
+      }
+
+      const reason = ageExceeded
+        ? `changes older than ${Math.round(dirtyAge / 1000)}s`
+        : `${totalChanges} files changed (threshold: ${this.fileThreshold})`;
+
+      heartbeatFiles = uniqueFiles;
+      heartbeatReason = reason;
+
+      log.info(
+        { workspaceDir, totalChanges, dirtyAgeMs: dirtyAge, reason },
+        'Heartbeat auto-committing workspace changes',
+      );
+
+      const ctx: CommitContext = {
+        workspaceDir,
+        trigger: 'heartbeat',
+        changedFiles: uniqueFiles,
+        timestampMs: now,
+        reason,
+      };
+
+      return this.commitMessageProvider.buildImmediateMessage(ctx);
+    });
+
+    if (committed) {
+      firstSeenDirty.delete(workspaceDir);
+
+      // Fire-and-forget enrichment
+      try {
+        const commitHash = await service.getHeadHash();
+        const hbCtx: CommitContext = {
+          workspaceDir,
+          trigger: 'heartbeat',
+          changedFiles: heartbeatFiles,
+          timestampMs: now,
+          reason: heartbeatReason,
+        };
+        getEnrichmentService().enqueue({ workspaceDir, commitHash, context: hbCtx, gitService: service });
+      } catch (enrichErr) {
+        log.debug({ enrichErr }, 'Failed to enqueue heartbeat enrichment (non-fatal)');
+      }
+
+      return true;
+    }
+
+    if (status.clean) {
+      firstSeenDirty.delete(workspaceDir);
+    }
+
+    return false;
+  }
+}
+
+/**
+ * @internal Test-only: clear the dirty tracking state
+ */
+export function _resetHeartbeatState(): void {
+  firstSeenDirty.clear();
+}

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

@@ -0,0 +1,285 @@
+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'
+  | 'missing_provider_api_key'
+  | 'breaker_open'
+  | 'insufficient_budget'
+  | 'missing_fast_model'
+  | 'provider_not_initialized'
+  | '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 PROVIDER_DEFAULT_FAST_MODELS: Record<string, string> = {
+  anthropic: 'claude-haiku-4-5-20251001',
+  openai: 'gpt-4o-mini',
+  gemini: 'gemini-2.0-flash',
+};
+
+// Providers that can be initialized without an API key (e.g., Ollama runs locally)
+const KEYLESS_PROVIDERS = new Set(['ollama']);
+
+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;
+
+    // ── Fallback check order (canonical) ──────────────────────────────
+    // 1. disabled
+    // 2. missing_provider_api_key  (except keyless providers like ollama)
+    // 3. breaker_open
+    // 4. insufficient_budget
+    // 5. missing_fast_model
+    // 6. provider_not_initialized
+    // 7. call provider → timeout / provider_error / invalid_output
+    // ──────────────────────────────────────────────────────────────────
+
+    // Step 1: Feature gate
+    if (!llmConfig.enabled) {
+      return buildDeterministicResult(context, 'disabled');
+    }
+    if (!llmConfig.useConfiguredProvider) {
+      return buildDeterministicResult(context, 'disabled');
+    }
+
+    // Step 2: API key preflight (skip for providers that run without a key)
+    if (!KEYLESS_PROVIDERS.has(config.provider)) {
+      const providerApiKey = config.apiKeys[config.provider];
+      if (!providerApiKey || providerApiKey === '') {
+        log.debug('Provider API key missing; falling back to deterministic');
+        return buildDeterministicResult(context, 'missing_provider_api_key');
+      }
+    }
+
+    // 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: Fast model preflight — resolve before any provider call
+    const fastModel = llmConfig.providerFastModelOverrides[config.provider]
+      ?? PROVIDER_DEFAULT_FAST_MODELS[config.provider];
+
+    if (!fastModel) {
+      log.debug(
+        { provider: config.provider },
+        'No fast model resolvable for provider; falling back to deterministic',
+      );
+      return buildDeterministicResult(context, 'missing_fast_model');
+    }
+
+    // Step 6 + 7: 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: {
+              model: fastModel,
+              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');
+      }
+
+      // Cap subject line to 72 chars deterministically (no fallback, no breaker failure)
+      const lines = text.split('\n');
+      if (lines[0].length > 72) {
+        log.debug(
+          { originalLength: lines[0].length },
+          'Capping LLM subject line to 72 chars',
+        );
+        lines[0] = lines[0].slice(0, 72);
+      }
+      const finalMessage = lines.join('\n');
+
+      this.recordSuccess();
+      return { message: finalMessage, source: 'llm' };
+    } catch (err: unknown) {
+      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/top-level-renderer.ts

@@ -0,0 +1,19 @@
+import type { TopLevelSnapshot } from './top-level-scanner.js';
+
+/**
+ * Render a workspace top-level snapshot into a compact XML-like block
+ * suitable for injection into user messages.
+ *
+ * Output is stable for equal input and kept concise to minimize token cost.
+ */
+export function renderWorkspaceTopLevelContext(snapshot: TopLevelSnapshot): string {
+  const lines: string[] = ['<workspace_top_level>'];
+  lines.push(`Root: ${snapshot.rootPath}`);
+  lines.push(`Directories: ${snapshot.directories.join(', ')}`);
+  lines.push(`Files: ${snapshot.files.join(', ')}`);
+  if (snapshot.truncated) {
+    lines.push('(list truncated — more entries exist)');
+  }
+  lines.push('</workspace_top_level>');
+  return lines.join('\n');
+}

package/src/workspace/top-level-scanner.ts

@@ -0,0 +1,41 @@
+import { readdirSync } from 'node:fs';
+
+/** Hard cap on returned entries to keep context bounded. */
+export const MAX_TOP_LEVEL_ENTRIES = 120;
+
+export interface TopLevelSnapshot {
+  rootPath: string;
+  directories: string[];
+  files: string[];
+  truncated: boolean;
+}
+
+/**
+ * Return a deterministic, bounded list of top-level directories
+ * under `rootPath`.  Hidden directories are included.  The result
+ * is sorted lexicographically.
+ */
+export function scanTopLevelDirectories(rootPath: string): TopLevelSnapshot {
+  let dirEntries: string[];
+  let fileEntries: string[];
+  try {
+    const all = readdirSync(rootPath, { withFileTypes: true });
+    dirEntries = all.filter((d) => d.isDirectory()).map((d) => d.name).sort();
+    fileEntries = all.filter((d) => d.isFile()).map((d) => d.name).sort();
+  } catch {
+    return { rootPath, directories: [], files: [], truncated: false };
+  }
+
+  const totalEntries = dirEntries.length + fileEntries.length;
+  const truncated = totalEntries > MAX_TOP_LEVEL_ENTRIES;
+
+  if (truncated) {
+    // Directories first, then fill remaining budget with files
+    const dirs = dirEntries.slice(0, MAX_TOP_LEVEL_ENTRIES);
+    const remaining = Math.max(0, MAX_TOP_LEVEL_ENTRIES - dirs.length);
+    const files = fileEntries.slice(0, remaining);
+    return { rootPath, directories: dirs, files, truncated };
+  }
+
+  return { rootPath, directories: dirEntries, files: fileEntries, truncated };
+}