vellum 0.2.13 → 0.2.14

package/src/workspace/git-service.ts

@@ -4,6 +4,7 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { getLogger } from '../util/logger.js';
 import { getConfig } from '../config/loader.js';
+import { PromiseGuard } from '../util/promise-guard.js';
 
 const execFileAsync = promisify(execFile);
 const log = getLogger('workspace-git');
@@ -133,7 +134,7 @@ export class WorkspaceGitService {
   private readonly workspaceDir: string;
   private readonly mutex: Mutex;
   private initialized = false;
-  private initPromise: Promise<void> | null = null;
+  private readonly initGuard = new PromiseGuard<void>();
   private consecutiveFailures = 0;
   private nextAllowedAttemptMs = 0;
   private initConsecutiveFailures = 0;
@@ -236,81 +237,38 @@ export class WorkspaceGitService {
     }
 
     // If initialization is in progress, wait for it
-    if (this.initPromise) {
-      return this.initPromise;
+    if (this.initGuard.active) {
+      return this.initGuard.run(() => { throw new Error('unreachable'); });
     }
 
     // Circuit breaker: skip if multiple recent init attempts have been failing.
-    // Checked AFTER initPromise so callers waiting on in-progress init aren't
+    // Checked AFTER initGuard.active so callers waiting on in-progress init aren't
     // blocked, and only activates after 2+ consecutive failures so that a
     // single transient failure allows immediate retry.
     if (this.isInitBreakerOpen()) {
       throw new Error('Init circuit breaker open: backing off after repeated failures');
     }
 
-    // Start initialization
-    this.initPromise = this.mutex.withLock(async () => {
-      // Double-check after acquiring lock
-      if (this.initialized) {
-        return;
-      }
-
-      const gitDir = join(this.workspaceDir, '.git');
-
-      if (existsSync(gitDir)) {
-        // Validate existing repo is not corrupted before marking as ready.
-        // A corrupted .git directory (e.g. missing HEAD) would cause all
-        // subsequent git operations to fail with confusing errors.
-        try {
-          await this.execGit(['rev-parse', '--git-dir']);
-        } catch (err: unknown) {
-          // Distinguish transient failures from genuine corruption.
-          // Transient errors (timeouts, permissions, missing git binary)
-          // should NOT destroy .git — they will resolve on retry via
-          // the initPromise clearing logic.
-          const errMsg = err instanceof Error ? err.message : String(err);
-          const execErr = err as ExecError;
-          const isTimeout = execErr.killed === true
-            || execErr.signal === 'SIGTERM'
-            || errMsg.includes('SIGTERM')
-            || errMsg.includes('timed out');
-          const isPermission = execErr.code === 'EACCES'
-            || errMsg.includes('EACCES')
-            || errMsg.toLowerCase().includes('permission denied');
-          const isMissingBinary = execErr.code === 'ENOENT'
-            || errMsg.includes('ENOENT');
-
-          if (isTimeout || isPermission || isMissingBinary) {
-            // Re-throw so initialization fails gracefully without
-            // destroying valid git history.
-            throw err;
-          }
-
-          // Genuine corruption (e.g. missing HEAD, broken refs) —
-          // remove corrupted .git and fall through to full init below.
-          log.warn(
-            { workspaceDir: this.workspaceDir, err: errMsg },
-            'Corrupted .git directory detected; reinitializing',
-          );
-          const { rmSync } = await import('node:fs');
-          rmSync(gitDir, { recursive: true, force: true });
+    return this.initGuard.run(
+      () => this.mutex.withLock(async () => {
+        // Double-check after acquiring lock
+        if (this.initialized) {
+          return;
         }
 
+        const gitDir = join(this.workspaceDir, '.git');
+
         if (existsSync(gitDir)) {
-          // .git exists and passed the corruption check, but we still
-          // need to verify that at least one commit exists. A partial
-          // init (e.g. git init succeeded but the initial commit failed)
-          // leaves .git present with an undefined HEAD. In that case,
-          // fall through to the initial commit logic below.
-          let headExists = false;
+          // Validate existing repo is not corrupted before marking as ready.
+          // A corrupted .git directory (e.g. missing HEAD) would cause all
+          // subsequent git operations to fail with confusing errors.
           try {
-            await this.execGit(['rev-parse', 'HEAD']);
-            headExists = true;
+            await this.execGit(['rev-parse', '--git-dir']);
           } catch (err: unknown) {
-            // Distinguish transient failures from genuine "no commits".
+            // Distinguish transient failures from genuine corruption.
             // Transient errors (timeouts, permissions, missing git binary)
-            // should NOT fall through to re-initialization — they will
-            // resolve on retry via the initPromise clearing logic.
+            // should NOT destroy .git — they will resolve on retry via
+            // the guard clearing logic.
             const errMsg = err instanceof Error ? err.message : String(err);
             const execErr = err as ExecError;
             const isTimeout = execErr.killed === true
@@ -324,68 +282,104 @@ export class WorkspaceGitService {
               || errMsg.includes('ENOENT');
 
             if (isTimeout || isPermission || isMissingBinary) {
+              // Re-throw so initialization fails gracefully without
+              // destroying valid git history.
               throw err;
             }
-            // Genuine "no commits" (unborn HEAD) — fall through to
-            // create the initial commit.
-          }
 
-          if (headExists) {
-            // HEAD resolves — repo is fully initialized.
-            // Run normalization for existing repos that may have been
-            // created before these helpers existed, or by external tools.
-            // These calls are OUTSIDE the rev-parse try/catch so that
-            // normalization errors are not misclassified as "no commits".
-            this.ensureGitignoreRulesLocked();
-            await this.ensureCommitIdentityLocked();
-            await this.ensureOnMainLocked();
-            this.initialized = true;
-            this.recordInitSuccess();
-            return;
+            // Genuine corruption (e.g. missing HEAD, broken refs) —
+            // remove corrupted .git and fall through to full init below.
+            log.warn(
+              { workspaceDir: this.workspaceDir, err: errMsg },
+              'Corrupted .git directory detected; reinitializing',
+            );
+            const { rmSync } = await import('node:fs');
+            rmSync(gitDir, { recursive: true, force: true });
           }
-        }
-        // Otherwise fall through to reinitialize / create initial commit
-      }
 
-      // Initialize new git repository
-      await this.execGit(['init', '-b', 'main']);
-
-      // Run normalization (gitignore + identity + branch enforcement).
-      // For fresh `git init -b main` the branch is already main, but
-      // in the corruption-recovery path we fall through here after
-      // removing .git, so branch enforcement is still useful.
-      this.ensureGitignoreRulesLocked();
-      await this.ensureCommitIdentityLocked();
-      await this.ensureOnMainLocked();
-
-      // Create initial commit synchronously within the lock to prevent
-      // races with the first commitChanges() call. Without this, the
-      // initial commit could run concurrently and consume edits meant
-      // for the first user-requested commit.
-      const status = await this.getStatusInternal();
-      const hasExistingFiles = status.untracked.length > 1 || // More than just .gitignore
-        status.untracked.some(f => f !== '.gitignore');
+          if (existsSync(gitDir)) {
+            // .git exists and passed the corruption check, but we still
+            // need to verify that at least one commit exists. A partial
+            // init (e.g. git init succeeded but the initial commit failed)
+            // leaves .git present with an undefined HEAD. In that case,
+            // fall through to the initial commit logic below.
+            let headExists = false;
+            try {
+              await this.execGit(['rev-parse', 'HEAD']);
+              headExists = true;
+            } catch (err: unknown) {
+              // Distinguish transient failures from genuine "no commits".
+              // Transient errors (timeouts, permissions, missing git binary)
+              // should NOT fall through to re-initialization — they will
+              // resolve on retry via the guard clearing logic.
+              const errMsg = err instanceof Error ? err.message : String(err);
+              const execErr = err as ExecError;
+              const isTimeout = execErr.killed === true
+                || execErr.signal === 'SIGTERM'
+                || errMsg.includes('SIGTERM')
+                || errMsg.includes('timed out');
+              const isPermission = execErr.code === 'EACCES'
+                || errMsg.includes('EACCES')
+                || errMsg.toLowerCase().includes('permission denied');
+              const isMissingBinary = execErr.code === 'ENOENT'
+                || errMsg.includes('ENOENT');
+
+              if (isTimeout || isPermission || isMissingBinary) {
+                throw err;
+              }
+              // Genuine "no commits" (unborn HEAD) — fall through to
+              // create the initial commit.
+            }
 
-      await this.execGit(['add', '-A']);
+            if (headExists) {
+              // HEAD resolves — repo is fully initialized.
+              // Run normalization for existing repos that may have been
+              // created before these helpers existed, or by external tools.
+              // These calls are OUTSIDE the rev-parse try/catch so that
+              // normalization errors are not misclassified as "no commits".
+              this.ensureGitignoreRulesLocked();
+              await this.ensureCommitIdentityLocked();
+              await this.ensureOnMainLocked();
+              this.initialized = true;
+              this.recordInitSuccess();
+              return;
+            }
+          }
+          // Otherwise fall through to reinitialize / create initial commit
+        }
 
-      const message = hasExistingFiles
-        ? 'Initial commit: migrated existing workspace'
-        : 'Initial commit: new workspace';
+        // Initialize new git repository
+        await this.execGit(['init', '-b', 'main']);
+
+        // Run normalization (gitignore + identity + branch enforcement).
+        // For fresh `git init -b main` the branch is already main, but
+        // in the corruption-recovery path we fall through here after
+        // removing .git, so branch enforcement is still useful.
+        this.ensureGitignoreRulesLocked();
+        await this.ensureCommitIdentityLocked();
+        await this.ensureOnMainLocked();
+
+        // Create initial commit synchronously within the lock to prevent
+        // races with the first commitChanges() call. Without this, the
+        // initial commit could run concurrently and consume edits meant
+        // for the first user-requested commit.
+        const status = await this.getStatusInternal();
+        const hasExistingFiles = status.untracked.length > 1 || // More than just .gitignore
+          status.untracked.some(f => f !== '.gitignore');
 
-      await this.execGit(['commit', '-m', message, '--allow-empty']);
+        await this.execGit(['add', '-A']);
 
-      this.initialized = true;
-      this.recordInitSuccess();
-    });
+        const message = hasExistingFiles
+          ? 'Initial commit: migrated existing workspace'
+          : 'Initial commit: new workspace';
 
-    // If initialization fails, clear the cached promise so subsequent
-    // calls can retry instead of permanently returning the rejected promise.
-    this.initPromise.catch(() => {
-      this.initPromise = null;
-      this.recordInitFailure();
-    });
+        await this.execGit(['commit', '-m', message, '--allow-empty']);
 
-    return this.initPromise;
+        this.initialized = true;
+        this.recordInitSuccess();
+      }),
+      () => this.recordInitFailure(),
+    );
   }
 
   /**
@@ -732,6 +726,29 @@ export class WorkspaceGitService {
     }
   }
 
+  /**
+   * Run an arbitrary read-only git command in the workspace directory.
+   * Uses the same clean env and timeout as other git operations.
+   * Does NOT acquire the mutex — callers must ensure they are not
+   * writing to the repo concurrently (or accept eventual-consistency).
+   */
+  async runReadOnlyGit(args: string[]): Promise<{ stdout: string; stderr: string }> {
+    await this.ensureInitialized();
+    return this.execGit(args);
+  }
+
+  /**
+   * Run a sequence of git commands atomically under the workspace mutex.
+   * Use this for write operations that need serialization with other
+   * git mutations (e.g. checkout + commit).
+   */
+  async runWithMutex(fn: (exec: (args: string[]) => Promise<{ stdout: string; stderr: string }>) => Promise<void>): Promise<void> {
+    await this.ensureInitialized();
+    await this.mutex.withLock(async () => {
+      await fn((args) => this.execGit(args));
+    });
+  }
+
   /**
    * Get the commit hash of the current HEAD.
    * This is a lightweight read-only operation that does not require the mutex.

package/src/tools/contacts/contact-merge.ts

@@ -1,55 +0,0 @@
-import type { ToolContext, ToolExecutionResult } from '../types.js';
-import { mergeContacts, getContact } from '../../contacts/contact-store.js';
-
-export async function executeContactMerge(
-  input: Record<string, unknown>,
-  _context: ToolContext,
-): Promise<ToolExecutionResult> {
-  const keepId = input.keep_id as string | undefined;
-  const mergeId = input.merge_id as string | undefined;
-
-  if (!keepId || typeof keepId !== 'string') {
-    return { content: 'Error: keep_id is required', isError: true };
-  }
-  if (!mergeId || typeof mergeId !== 'string') {
-    return { content: 'Error: merge_id is required', isError: true };
-  }
-
-  // Show what will be merged for clarity
-  const keepContact = getContact(keepId);
-  const mergeContact = getContact(mergeId);
-
-  if (!keepContact) {
-    return { content: `Error: Contact "${keepId}" not found`, isError: true };
-  }
-  if (!mergeContact) {
-    return { content: `Error: Contact "${mergeId}" not found`, isError: true };
-  }
-
-  try {
-    const merged = mergeContacts(keepId, mergeId);
-
-    const channelList = merged.channels
-      .map((ch) => `  - ${ch.type}: ${ch.address}${ch.isPrimary ? ' (primary)' : ''}`)
-      .join('\n');
-
-    return {
-      content: [
-        `Merged "${mergeContact.displayName}" into "${keepContact.displayName}".`,
-        ``,
-        `Surviving contact (${merged.id}):`,
-        `  Name: ${merged.displayName}`,
-        `  Importance: ${merged.importance.toFixed(2)}`,
-        `  Interactions: ${merged.interactionCount}`,
-        merged.relationship ? `  Relationship: ${merged.relationship}` : null,
-        merged.channels.length > 0 ? `  Channels:\n${channelList}` : null,
-        ``,
-        `Deleted contact: ${mergeContact.displayName} (${mergeId})`,
-      ].filter(Boolean).join('\n'),
-      isError: false,
-    };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return { content: `Error: ${msg}`, isError: true };
-  }
-}

package/src/tools/contacts/contact-search.ts

@@ -1,58 +0,0 @@
-import type { ToolContext, ToolExecutionResult } from '../types.js';
-import { searchContacts } from '../../contacts/contact-store.js';
-import type { ContactWithChannels } from '../../contacts/types.js';
-
-function formatContactSummary(c: ContactWithChannels): string {
-  const parts = [`- **${c.displayName}** (ID: ${c.id})`];
-  if (c.relationship) parts.push(`  Relationship: ${c.relationship}`);
-  parts.push(`  Importance: ${c.importance.toFixed(2)} | Interactions: ${c.interactionCount}`);
-  if (c.channels.length > 0) {
-    const channelList = c.channels
-      .map((ch) => `${ch.type}:${ch.address}${ch.isPrimary ? '*' : ''}`)
-      .join(', ');
-    parts.push(`  Channels: ${channelList}`);
-  }
-  return parts.join('\n');
-}
-
-export async function executeContactSearch(
-  input: Record<string, unknown>,
-  _context: ToolContext,
-): Promise<ToolExecutionResult> {
-  const query = input.query as string | undefined;
-  const channelAddress = input.channel_address as string | undefined;
-  const channelType = input.channel_type as string | undefined;
-  const relationship = input.relationship as string | undefined;
-  const limit = input.limit as number | undefined;
-
-  if (!query && !channelAddress && !relationship) {
-    return {
-      content: 'Error: At least one search criterion is required (query, channel_address, or relationship)',
-      isError: true,
-    };
-  }
-
-  try {
-    const results = searchContacts({
-      query,
-      channelAddress,
-      channelType,
-      relationship,
-      limit,
-    });
-
-    if (results.length === 0) {
-      return { content: 'No contacts found matching the search criteria.', isError: false };
-    }
-
-    const lines = [`Found ${results.length} contact(s):\n`];
-    for (const contact of results) {
-      lines.push(formatContactSummary(contact));
-    }
-
-    return { content: lines.join('\n'), isError: false };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return { content: `Error: ${msg}`, isError: true };
-  }
-}

package/src/tools/contacts/contact-upsert.ts

@@ -1,64 +0,0 @@
-import type { ToolContext, ToolExecutionResult } from '../types.js';
-import { upsertContact } from '../../contacts/contact-store.js';
-
-function formatContact(c: ReturnType<typeof upsertContact>): string {
-  const lines = [
-    `Contact ${c.id}`,
-    `  Name: ${c.displayName}`,
-  ];
-  if (c.relationship) lines.push(`  Relationship: ${c.relationship}`);
-  lines.push(`  Importance: ${c.importance.toFixed(2)}`);
-  if (c.responseExpectation) lines.push(`  Response expectation: ${c.responseExpectation}`);
-  if (c.preferredTone) lines.push(`  Preferred tone: ${c.preferredTone}`);
-  if (c.interactionCount > 0) lines.push(`  Interactions: ${c.interactionCount}`);
-  if (c.channels.length > 0) {
-    lines.push('  Channels:');
-    for (const ch of c.channels) {
-      const primary = ch.isPrimary ? ' (primary)' : '';
-      lines.push(`    - ${ch.type}: ${ch.address}${primary}`);
-    }
-  }
-  return lines.join('\n');
-}
-
-export async function executeContactUpsert(
-  input: Record<string, unknown>,
-  _context: ToolContext,
-): Promise<ToolExecutionResult> {
-  const displayName = input.display_name as string | undefined;
-  if (!displayName || typeof displayName !== 'string' || displayName.trim().length === 0) {
-    return { content: 'Error: display_name is required and must be a non-empty string', isError: true };
-  }
-
-  const importance = input.importance as number | undefined;
-  if (importance !== undefined && (typeof importance !== 'number' || importance < 0 || importance > 1)) {
-    return { content: 'Error: importance must be a number between 0 and 1', isError: true };
-  }
-
-  const rawChannels = input.channels as Array<{ type: string; address: string; is_primary?: boolean }> | undefined;
-  const channels = rawChannels?.map((ch) => ({
-    type: ch.type,
-    address: ch.address,
-    isPrimary: ch.is_primary,
-  }));
-
-  try {
-    const contact = upsertContact({
-      id: input.id as string | undefined,
-      displayName: displayName.trim(),
-      relationship: input.relationship as string | undefined,
-      importance,
-      responseExpectation: input.response_expectation as string | undefined,
-      preferredTone: input.preferred_tone as string | undefined,
-      channels,
-    });
-
-    return {
-      content: `${contact.created ? 'Created' : 'Updated'} contact:\n${formatContact(contact)}`,
-      isError: false,
-    };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return { content: `Error: ${msg}`, isError: true };
-  }
-}

package/src/tools/playbooks/index.ts

@@ -1,4 +0,0 @@
-export { executePlaybookCreate } from './playbook-create.js';
-export { executePlaybookList } from './playbook-list.js';
-export { executePlaybookUpdate } from './playbook-update.js';
-export { executePlaybookDelete } from './playbook-delete.js';

package/src/tools/playbooks/playbook-create.ts

@@ -1,96 +0,0 @@
-import { and, eq } from 'drizzle-orm';
-import { v4 as uuid } from 'uuid';
-import type { ToolContext, ToolExecutionResult } from '../types.js';
-import { getDb } from '../../memory/db.js';
-import { computeMemoryFingerprint } from '../../memory/fingerprint.js';
-import { memoryItems } from '../../memory/schema.js';
-import { enqueueMemoryJob } from '../../memory/jobs-store.js';
-import type { Playbook, PlaybookAutonomyLevel } from '../../playbooks/types.js';
-import { truncate } from '../../util/truncate.js';
-
-const VALID_AUTONOMY_LEVELS = new Set<string>(['auto', 'draft', 'notify']);
-
-export async function executePlaybookCreate(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
-  const trigger = input.trigger as string;
-  const action = input.action as string;
-
-  if (!trigger || typeof trigger !== 'string') {
-    return { content: 'Error: trigger is required and must be a string', isError: true };
-  }
-  if (!action || typeof action !== 'string') {
-    return { content: 'Error: action is required and must be a string', isError: true };
-  }
-
-  const channel = typeof input.channel === 'string' ? input.channel : '*';
-  const category = typeof input.category === 'string' ? input.category : 'general';
-  const autonomyLevel: PlaybookAutonomyLevel =
-    typeof input.autonomy_level === 'string' && VALID_AUTONOMY_LEVELS.has(input.autonomy_level)
-      ? (input.autonomy_level as PlaybookAutonomyLevel)
-      : 'draft';
-  const priority = typeof input.priority === 'number' ? input.priority : 0;
-
-  const playbook: Playbook = { trigger, channel, category, action, autonomyLevel, priority };
-  const statement = JSON.stringify(playbook);
-  const subject = truncate(`Playbook: ${trigger}`, 80, '');
-  const scopeId = context.memoryScopeId ?? 'default';
-
-  const fingerprint = computeMemoryFingerprint(scopeId, 'playbook', subject, statement);
-
-  try {
-    const db = getDb();
-
-    const existing = db
-      .select()
-      .from(memoryItems)
-      .where(and(eq(memoryItems.fingerprint, fingerprint), eq(memoryItems.scopeId, scopeId)))
-      .get();
-
-    if (existing) {
-      return {
-        content: `A playbook with this exact configuration already exists (ID: ${existing.id}).`,
-        isError: false,
-      };
-    }
-
-    const id = uuid();
-    const now = Date.now();
-
-    db.insert(memoryItems).values({
-      id,
-      kind: 'playbook',
-      subject,
-      statement,
-      status: 'active',
-      confidence: 0.95,
-      importance: 0.8,
-      fingerprint,
-      verificationState: 'user_confirmed',
-      scopeId,
-      firstSeenAt: now,
-      lastSeenAt: now,
-      lastUsedAt: null,
-    }).run();
-
-    enqueueMemoryJob('embed_item', { itemId: id });
-
-    const autonomyLabel = autonomyLevel === 'auto' ? 'execute automatically'
-      : autonomyLevel === 'draft' ? 'draft for review' : 'notify only';
-
-    return {
-      content: [
-        'Playbook created successfully.',
-        `  ID: ${id}`,
-        `  Trigger: ${trigger}`,
-        `  Channel: ${channel}`,
-        `  Category: ${category}`,
-        `  Action: ${action}`,
-        `  Autonomy: ${autonomyLabel}`,
-        `  Priority: ${priority}`,
-      ].join('\n'),
-      isError: false,
-    };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return { content: `Error creating playbook: ${msg}`, isError: true };
-  }
-}

package/src/tools/playbooks/playbook-delete.ts

@@ -1,52 +0,0 @@
-import { and, eq } from 'drizzle-orm';
-import type { ToolContext, ToolExecutionResult } from '../types.js';
-import { getDb } from '../../memory/db.js';
-import { memoryItems } from '../../memory/schema.js';
-import { parsePlaybookStatement } from '../../playbooks/types.js';
-
-export async function executePlaybookDelete(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
-  const playbookId = input.playbook_id as string;
-  if (!playbookId || typeof playbookId !== 'string') {
-    return { content: 'Error: playbook_id is required and must be a string', isError: true };
-  }
-
-  const scopeId = context.memoryScopeId ?? 'default';
-
-  try {
-    const db = getDb();
-
-    const existing = db
-      .select()
-      .from(memoryItems)
-      .where(and(
-        eq(memoryItems.id, playbookId),
-        eq(memoryItems.kind, 'playbook'),
-        eq(memoryItems.scopeId, scopeId),
-      ))
-      .get();
-
-    if (!existing) {
-      return { content: `Error: Playbook with ID "${playbookId}" not found`, isError: true };
-    }
-
-    const playbook = parsePlaybookStatement(existing.statement);
-    const triggerLabel = playbook?.trigger ?? existing.subject;
-
-    // Soft-delete by marking as superseded rather than hard-deleting,
-    // consistent with how other memory items are retired.
-    // Setting invalidAt so the cleanup job can eventually hard-delete it.
-    const now = Date.now();
-    db.update(memoryItems)
-      .set({ status: 'superseded', invalidAt: now })
-      .where(eq(memoryItems.id, existing.id))
-      .run();
-
-    return {
-      content: `Playbook deleted (ID: ${existing.id}, trigger: "${triggerLabel}").`,
-      isError: false,
-    };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return { content: `Error deleting playbook: ${msg}`, isError: true };
-  }
-}