compound-agent 1.5.0 → 1.6.0

package/dist/index.d.ts

@@ -2559,6 +2559,8 @@ declare function readLessons(repoRoot: string, options?: ReadLessonsOptions): Pr
 interface CachedEmbeddingData {
     embedding: Buffer;
     contentHash: string;
+    embeddingInsight?: Buffer | null;
+    contentHashInsight?: string | null;
 }
 
 /**
@@ -2691,7 +2693,11 @@ declare const MODEL_URI = "hf:ggml-org/embeddinggemma-300M-qat-q4_0-GGUF/embeddi
  */
 declare const MODEL_FILENAME = "hf_ggml-org_embeddinggemma-300M-qat-Q4_0.gguf";
 /**
- * Check if the embedding model is available locally.
+ * Check if the embedding model is available locally (fs existence only).
+ *
+ * Use this for cheap pre-flight checks (e.g. spawnBackgroundEmbed) where
+ * failure is handled gracefully. Use {@link isModelUsable} when you need
+ * runtime verification that the model can actually initialize.
  *
  * @returns true if model file exists
  */
@@ -2722,6 +2728,12 @@ type UsabilityResult = {
  * 4. Attempts to create embedding context
  * 5. Cleans up all resources after check
  *
+ * WARNING: This function allocates ~150MB of native C++ memory for the probe.
+ * NEVER call at module top-level in test files. When dispose() SIGABRTs in
+ * vitest workers, that memory is permanently leaked. For test skip-gating,
+ * use isModelAvailable() instead (zero native allocation). Reserve this
+ * function for production code paths where runtime verification is needed.
+ *
  * @returns UsabilityResult with usable status and actionable error if failed
  */
 declare function isModelUsable(): Promise<UsabilityResult>;
@@ -2841,7 +2853,7 @@ declare function unloadEmbedding(): void;
  * Subsequent calls use the cached model and complete in milliseconds.
  *
  * @param text - The text to embed
- * @returns A 768-dimensional vector (number[])
+ * @returns A 768-dimensional Float32Array vector
  * @throws Error if model download fails
  *
  * @example
@@ -2856,7 +2868,7 @@ declare function unloadEmbedding(): void;
  * @see {@link embedTexts} for batch embedding
  * @see {@link unloadEmbedding} for releasing memory
  */
-declare function embedText(text: string): Promise<number[]>;
+declare function embedText(text: string): Promise<Float32Array>;
 /**
  * Embed multiple texts into vectors.
  *
@@ -2884,7 +2896,7 @@ declare function embedText(text: string): Promise<number[]>;
  * @see {@link embedText} for single text embedding
  * @see {@link unloadEmbedding} for releasing memory
  */
-declare function embedTexts(texts: string[]): Promise<number[][]>;
+declare function embedTexts(texts: string[]): Promise<Float32Array[]>;
 
 /**
  * Multi-factor memory item ranking system
@@ -2948,8 +2960,9 @@ interface NoveltyOptions {
     threshold?: number;
 }
 /**
- * Check if an insight is novel (not a duplicate of existing lessons).
- * Uses keyword search to find potentially similar lessons.
+ * Check if an insight is novel (not a near-duplicate of existing lessons).
+ * Uses semantic embeddings with cosine similarity.
+ * Falls back to novel: true when model is unavailable or on error.
  */
 declare function isNovel(repoRoot: string, insight: string, options?: NoveltyOptions): Promise<NoveltyResult>;
 /** Result of specificity check */
@@ -3270,6 +3283,8 @@ interface IndexOptions {
     force?: boolean;
     /** Directory to index (default: 'docs') */
     docsDir?: string;
+    /** Embed chunks after indexing (default: false) */
+    embed?: boolean;
 }
 interface IndexResult {
     filesIndexed: number;
@@ -3277,6 +3292,7 @@ interface IndexResult {
     filesErrored: number;
     chunksCreated: number;
     chunksDeleted: number;
+    chunksEmbedded: number;
     durationMs: number;
 }
 /**
@@ -3310,6 +3326,124 @@ declare function searchKnowledgeVector(repoRoot: string, query: string, options?
  */
 declare function searchKnowledge(repoRoot: string, query: string, options?: KnowledgeSearchOptions): Promise<GenericScoredItem<KnowledgeChunk>[]>;
 
+/**
+ * Core embedding function for knowledge chunks.
+ *
+ * Embeds unembedded (or all) knowledge chunks using the local embedding model.
+ * Uses batch embedding and transactional writes for performance.
+ */
+interface EmbedChunksOptions {
+    /** Only embed chunks with no embedding (default: true) */
+    onlyMissing?: boolean;
+}
+interface EmbedChunksResult {
+    chunksEmbedded: number;
+    chunksSkipped: number;
+    durationMs: number;
+}
+/**
+ * Count chunks that have no embedding stored.
+ * @param repoRoot - Absolute path to repository root
+ */
+declare function getUnembeddedChunkCount(repoRoot: string): number;
+/**
+ * Embed knowledge chunks using the local embedding model.
+ *
+ * Processes chunks in batches of BATCH_SIZE for efficient embedding and
+ * wraps each batch's DB writes in a transaction (1 fsync per batch).
+ *
+ * @param repoRoot - Absolute path to repository root
+ * @param options - Embedding options
+ * @returns Stats about the embedding run
+ */
+declare function embedChunks(repoRoot: string, options?: EmbedChunksOptions): Promise<EmbedChunksResult>;
+
+/**
+ * PID-based lock file for embedding processes.
+ *
+ * Prevents concurrent embedding when background embed (ca init/setup)
+ * and post-commit hook run simultaneously.
+ *
+ * Lock file: {repoRoot}/.claude/.cache/embed.lock
+ * Content: { pid: number, startedAt: string } (ISO timestamp)
+ */
+interface LockAcquired {
+    acquired: true;
+    release: () => void;
+}
+interface LockBusy {
+    acquired: false;
+    holder: number;
+}
+type LockResult = LockAcquired | LockBusy;
+/**
+ * Acquire the embed lock for this process.
+ *
+ * Uses writeFileSync with 'wx' flag for atomic exclusive creation.
+ * On EEXIST: reads holder PID and checks staleness via process.kill(pid, 0).
+ * If stale (holder dead): overwrites lock. If alive: returns acquired: false.
+ */
+declare function acquireEmbedLock(repoRoot: string): LockResult;
+/** Check if an embed lock is currently held by a live process. */
+declare function isEmbedLocked(repoRoot: string): boolean;
+
+/**
+ * Embedding status file: tracks state of background embedding process.
+ *
+ * Status file lives at {repoRoot}/.claude/.cache/embed-status.json
+ */
+type EmbedStatus = {
+    state: 'idle';
+} | {
+    state: 'running';
+    startedAt: string;
+} | {
+    state: 'completed';
+    chunksEmbedded: number;
+    completedAt: string;
+    durationMs: number;
+} | {
+    state: 'failed';
+    error: string;
+    durationMs: number;
+};
+/** Write embedding status to disk. Creates parent directories if needed. */
+declare function writeEmbedStatus(repoRoot: string, status: EmbedStatus): void;
+/** Read embedding status from disk. Returns null on missing file or parse error. */
+declare function readEmbedStatus(repoRoot: string): EmbedStatus | null;
+
+/**
+ * Background embedding: spawn a detached worker or run embedding in-process.
+ *
+ * spawnBackgroundEmbed(repoRoot) - spawns detached child process (sync, non-blocking)
+ * runBackgroundEmbed(repoRoot)   - worker entry point that does the actual embedding
+ */
+interface SpawnEmbedResult {
+    spawned: boolean;
+    reason?: string;
+    pid?: number;
+}
+/**
+ * Spawn a detached background process to embed chunks.
+ * Synchronous -- fires and forgets.
+ *
+ * Pre-flight checks (lock, model, count) are advisory only. The worker
+ * acquires its own lock, so TOCTOU here cannot cause double-embedding --
+ * at worst we spawn a worker that exits immediately.
+ */
+declare function spawnBackgroundEmbed(repoRoot: string): SpawnEmbedResult;
+/**
+ * Worker entry point: acquire lock, embed chunks, write status, clean up.
+ */
+declare function runBackgroundEmbed(repoRoot: string): Promise<void>;
+/**
+ * Index docs/ and spawn background embedding if docs/ exists.
+ * Shared helper for init and setup commands.
+ *
+ * @returns SpawnEmbedResult or null if docs/ doesn't exist
+ */
+declare function indexAndSpawnEmbed(repoRoot: string): Promise<SpawnEmbedResult | null>;
+
 /**
  * Prime command - Context recovery for Claude Code with Beads-style trust language.
  *
@@ -3343,14 +3477,14 @@ declare const AuditFindingSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     file: string;
     source: "lesson" | "pattern" | "rule";
-    severity: "error" | "warning" | "info";
+    severity: "warning" | "error" | "info";
     issue: string;
     relatedLessonId?: string | undefined;
     suggestedFix?: string | undefined;
 }, {
     file: string;
     source: "lesson" | "pattern" | "rule";
-    severity: "error" | "warning" | "info";
+    severity: "warning" | "error" | "info";
     issue: string;
     relatedLessonId?: string | undefined;
     suggestedFix?: string | undefined;
@@ -3367,14 +3501,14 @@ declare const AuditReportSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         file: string;
         source: "lesson" | "pattern" | "rule";
-        severity: "error" | "warning" | "info";
+        severity: "warning" | "error" | "info";
         issue: string;
         relatedLessonId?: string | undefined;
         suggestedFix?: string | undefined;
     }, {
         file: string;
         source: "lesson" | "pattern" | "rule";
-        severity: "error" | "warning" | "info";
+        severity: "warning" | "error" | "info";
         issue: string;
         relatedLessonId?: string | undefined;
         suggestedFix?: string | undefined;
@@ -3401,7 +3535,7 @@ declare const AuditReportSchema: z.ZodObject<{
     findings: {
         file: string;
         source: "lesson" | "pattern" | "rule";
-        severity: "error" | "warning" | "info";
+        severity: "warning" | "error" | "info";
         issue: string;
         relatedLessonId?: string | undefined;
         suggestedFix?: string | undefined;
@@ -3417,7 +3551,7 @@ declare const AuditReportSchema: z.ZodObject<{
     findings: {
         file: string;
         source: "lesson" | "pattern" | "rule";
-        severity: "error" | "warning" | "info";
+        severity: "warning" | "error" | "info";
         issue: string;
         relatedLessonId?: string | undefined;
         suggestedFix?: string | undefined;
@@ -3511,7 +3645,7 @@ interface ClusterResult {
  * @param embeddings - Array of embedding vectors
  * @returns NxN similarity matrix
  */
-declare function buildSimilarityMatrix(embeddings: number[][]): number[][];
+declare function buildSimilarityMatrix(embeddings: ArrayLike<number>[]): number[][];
 /**
  * Cluster memory items by embedding similarity using single-linkage
  * agglomerative clustering.
@@ -3521,7 +3655,7 @@ declare function buildSimilarityMatrix(embeddings: number[][]): number[][];
  * @param threshold - Minimum similarity to merge clusters (default: 0.75)
  * @returns Clusters of similar items and noise (unclustered items)
  */
-declare function clusterBySimilarity(items: MemoryItem[], embeddings: number[][], threshold?: number): ClusterResult;
+declare function clusterBySimilarity(items: MemoryItem[], embeddings: ArrayLike<number>[], threshold?: number): ClusterResult;
 
 /**
  * I/O module for CctPattern persistence.
@@ -3561,4 +3695,4 @@ declare function writeCctPatterns(repoRoot: string, patterns: CctPattern[]): Pro
  */
 declare function synthesizePattern(cluster: MemoryItem[], clusterId: string): CctPattern;
 
-export { type ActionabilityResult, type AuditFinding, AuditFindingSchema, type AuditOptions, type AuditReport, AuditReportSchema, CANDIDATE_MULTIPLIER, CCT_PATTERNS_PATH, type CctPattern, CctPatternSchema, type ClusterResult, type Context, type CorrectionSignal, DB_PATH, DEFAULT_TEXT_WEIGHT, DEFAULT_VECTOR_WEIGHT, type DetectedCorrection, type DetectedSelfCorrection, type DetectedTestFailure, type EditEntry, type EditHistory, type HybridMergeOptions, type IndexOptions, type IndexResult, KNOWLEDGE_DB_PATH, KNOWLEDGE_SCHEMA_VERSION, type KnowledgeChunk, type KnowledgeDbOptions, type KnowledgeSearchOptions, LESSONS_PATH, type Lesson, LessonItemSchema, type LessonRecord, LessonSchema, type LessonType, MODEL_FILENAME, MODEL_URI, type MemoryItem, type MemoryItemRecord, MemoryItemRecordSchema, MemoryItemSchema, type MemoryItemType, MemoryItemTypeSchema, type NoveltyOptions, type NoveltyResult, type ParseError, type PatternItem, PatternItemSchema, type PlanRetrievalResult, type Preference, PreferenceItemSchema, type ProposeResult, type RankedLesson, type ReadLessonsOptions, type ReadLessonsResult, type ReadMemoryItemsResult, type ScoredChunk, type ScoredKeywordResult, type ScoredLesson, type SearchVectorOptions, type Severity, type Solution, SolutionItemSchema, type Source, type SpecificityResult, type TestResult, type UsabilityResult, VERSION, appendLesson, appendMemoryItem, buildSimilarityMatrix, calculateScore, chunkFile, closeDb, closeKnowledgeDb, clusterBySimilarity, collectCachedChunkEmbeddings, confirmationBoost, cosineSimilarity, detectSelfCorrection, detectTestFailure, detectUserCorrection, embedText, embedTexts, formatLessonsCheck, generateId, getCachedChunkEmbedding, getEmbedding, getPrimeContext, indexDocs, isActionable, isModelAvailable, isModelUsable, isNovel, isSpecific, loadSessionLessons, mergeHybridResults, normalizeBm25Rank, openKnowledgeDb, rankLessons, readCctPatterns, readLessons, readMemoryItems, rebuildIndex, recencyBoost, resolveModel, retrieveForPlan, runAudit, searchChunksKeywordScored, searchKeyword, searchKnowledge, searchKnowledgeVector, searchVector, setCachedChunkEmbedding, severityBoost, shouldPropose, synthesizePattern, unloadEmbedding, writeCctPatterns };
+export { type ActionabilityResult, type AuditFinding, AuditFindingSchema, type AuditOptions, type AuditReport, AuditReportSchema, CANDIDATE_MULTIPLIER, CCT_PATTERNS_PATH, type CctPattern, CctPatternSchema, type ClusterResult, type Context, type CorrectionSignal, DB_PATH, DEFAULT_TEXT_WEIGHT, DEFAULT_VECTOR_WEIGHT, type DetectedCorrection, type DetectedSelfCorrection, type DetectedTestFailure, type EditEntry, type EditHistory, type EmbedChunksOptions, type EmbedChunksResult, type EmbedStatus, type HybridMergeOptions, type IndexOptions, type IndexResult, KNOWLEDGE_DB_PATH, KNOWLEDGE_SCHEMA_VERSION, type KnowledgeChunk, type KnowledgeDbOptions, type KnowledgeSearchOptions, LESSONS_PATH, type Lesson, LessonItemSchema, type LessonRecord, LessonSchema, type LessonType, type LockResult, MODEL_FILENAME, MODEL_URI, type MemoryItem, type MemoryItemRecord, MemoryItemRecordSchema, MemoryItemSchema, type MemoryItemType, MemoryItemTypeSchema, type NoveltyOptions, type NoveltyResult, type ParseError, type PatternItem, PatternItemSchema, type PlanRetrievalResult, type Preference, PreferenceItemSchema, type ProposeResult, type RankedLesson, type ReadLessonsOptions, type ReadLessonsResult, type ReadMemoryItemsResult, type ScoredChunk, type ScoredKeywordResult, type ScoredLesson, type SearchVectorOptions, type Severity, type Solution, SolutionItemSchema, type Source, type SpawnEmbedResult, type SpecificityResult, type TestResult, type UsabilityResult, VERSION, acquireEmbedLock, appendLesson, appendMemoryItem, buildSimilarityMatrix, calculateScore, chunkFile, closeDb, closeKnowledgeDb, clusterBySimilarity, collectCachedChunkEmbeddings, confirmationBoost, cosineSimilarity, detectSelfCorrection, detectTestFailure, detectUserCorrection, embedChunks, embedText, embedTexts, formatLessonsCheck, generateId, getCachedChunkEmbedding, getEmbedding, getPrimeContext, getUnembeddedChunkCount, indexAndSpawnEmbed, indexDocs, isActionable, isEmbedLocked, isModelAvailable, isModelUsable, isNovel, isSpecific, loadSessionLessons, mergeHybridResults, normalizeBm25Rank, openKnowledgeDb, rankLessons, readCctPatterns, readEmbedStatus, readLessons, readMemoryItems, rebuildIndex, recencyBoost, resolveModel, retrieveForPlan, runAudit, runBackgroundEmbed, searchChunksKeywordScored, searchKeyword, searchKnowledge, searchKnowledgeVector, searchVector, setCachedChunkEmbedding, severityBoost, shouldPropose, spawnBackgroundEmbed, synthesizePattern, unloadEmbedding, writeCctPatterns, writeEmbedStatus };