agentic-qe 3.15.16 → 3.15.18

package/dist/mcp/handlers/domain-handler-configs.d.ts

@@ -195,6 +195,9 @@ export interface DefectPredictResult {
     scanStatus?: 'partial' | 'complete';
     predictionMethod?: 'static-code-indicators';
     estimated?: boolean;
+    /** #1137: the run was stored, but pruning older runs failed. */
+    retention?: 'failed';
+    retentionError?: string;
     taskId: string;
     status: string;
     predictedDefects: Array<{

package/dist/mcp/handlers/domain-handler-configs.js

@@ -770,6 +770,7 @@ export const defectPredictConfig = {
             filesAnalyzed: data.filesAnalyzed, filesSkipped: data.filesSkipped,
             scanStatus: data.scanStatus,
         } : {}),
+        ...(data.retention === 'failed' ? { retention: 'failed', retentionError: String(data.retentionError ?? '') } : {}),
         predictedDefects: data.predictedDefects || [],
         riskScore: data.riskScore || 0,
         recommendations: data.recommendations || [],

package/dist/mcp/handlers/heartbeat-handlers.d.ts

@@ -20,7 +20,8 @@ export interface HeartbeatStatusResult {
     lastResult: {
         success: boolean;
         durationMs: number;
-        healthScore: number;
+        /** `null` when the run measured nothing (#1137). */
+        healthScore: number | null;
         trend: string;
         domainMetrics: Record<string, number | string>;
     } | null;
@@ -32,7 +33,8 @@ export interface HeartbeatTriggerParams {
 export interface HeartbeatTriggerResult {
     success: boolean;
     durationMs: number;
-    healthScore: number;
+    /** `null` when the run measured nothing (#1137). */
+    healthScore: number | null;
     trend: string;
     promoted: number;
     deprecated: number;

package/dist/mcp/protocol-server.js

@@ -897,7 +897,7 @@ export class MCPProtocolServer {
                 parameters: [
                     { name: 'testFiles', type: 'array', description: 'Nonempty list of concrete test file paths (relative to the project working directory or absolute). Expand glob patterns before calling; glob patterns are rejected.', items: { type: 'string' } },
                     { name: 'parallel', type: 'boolean', description: 'Enable parallel execution', default: true },
-                    { name: 'projectRoot', type: 'string', description: 'Optional directory inside the project to run every test file from (for example a monorepo package with its own vitest/jest config); relative testFiles are then relative to it. When omitted, each test file runs from its nearest directory with a vitest/jest config, never above the project root. Paths outside the project, including through symlinks, are rejected.' },
+                    { name: 'projectRoot', type: 'string', description: 'Optional directory inside the project to run every test file from (for example a monorepo package with its own vitest/jest config); relative testFiles are then relative to it. When omitted, each test file runs from its nearest directory with a vitest/jest config, never above the project root, even when a root config also lists that package in its projects. Either way the runner (jest or vitest) is the one the config of that directory sets up. Python test files (*.py) run with pytest (`python -m pytest`, or the interpreter in AQE_PYTHON) from their nearest pytest config (pytest.ini, pyproject.toml, setup.cfg, tox.ini). Paths outside the project, including through symlinks, are rejected.' },
                     saveResultsParameter('test_execute_parallel'),
                 ],
             },

package/dist/mcp/tools/learning-optimization/optimize.d.ts

@@ -48,6 +48,8 @@ export interface LearnResult {
     experienceIdsNotFound?: number;
     evidenceStatus?: 'insufficient-evidence';
     patternsLearned: number;
+    /** #1147: why nothing was learned from the requested experiences. */
+    noPatternReason?: string;
     newPatterns: LearnedPattern[];
     /** No baseline is recorded to compare against, so improvement is not measured (#1109). */
     improvement: number | null;
@@ -128,7 +130,10 @@ export interface DashboardResult {
     assignedPatternsExcluded?: number;
     /** #1121: untagged patterns mined before #1120 (rate selected over successes), excluded likewise. */
     legacyPatternsExcluded?: number;
-    /** Ranked by measured success rate; empty when no domain has a measured outcome. */
+    /**
+     * Ranked by measured success rate (#1147): domains with no measured outcome,
+     * or with 0% measured success, are left out.
+     */
     topPerformingDomains: DomainName[];
     evidenceStatus?: 'insufficient-evidence';
     unmeasured?: string[];

package/dist/mcp/tools/learning-optimization/optimize.js

@@ -15,6 +15,7 @@ import { MetricsOptimizerService } from '../../../domains/learning-optimization/
 import { TransferSpecialistService } from '../../../domains/learning-optimization/services/transfer-specialist.js';
 import { toErrorMessage } from '../../../shared/error-utils.js';
 import { partitionByRewardSource } from '../../../domains/learning-optimization/reward-source.js';
+import { rankTopPerformingDomains } from '../../../domains/learning-optimization/domain-ranking.js';
 // ============================================================================
 // Tool Implementation
 // ============================================================================
@@ -174,8 +175,21 @@ export class LearningOptimizeTool extends MCPToolBase {
         if (!readResult.success)
             throw readResult.error;
         const read = readResult.value;
+        const requested = new Set(experienceIds).size;
         const { measured, assignedExcluded } = partitionByRewardSource(read);
         const learned = measured.length > 0 ? await learningCoordinator.learnPattern(read) : null;
+        // #1147: say why nothing was learned instead of returning a bare 0.
+        let noPatternReason;
+        if (read.length === 0) {
+            noPatternReason = `None of the ${requested} requested experience ID(s) were found.`;
+        }
+        else if (measured.length === 0) {
+            noPatternReason = `None of the ${read.length} experience(s) read has a measured outcome` +
+                (assignedExcluded > 0 ? ` (${assignedExcluded} with an assigned reward excluded).` : '.');
+        }
+        else if (learned && !learned.success) {
+            noPatternReason = learned.error.message;
+        }
         const newPatterns = learned?.success
             ? [{
                     id: learned.value.id,
@@ -190,11 +204,12 @@ export class LearningOptimizeTool extends MCPToolBase {
         this.markAsRealData();
         return {
             experiencesProcessed: read.length,
-            experienceIdsNotFound: new Set(experienceIds).size - read.length,
+            experienceIdsNotFound: requested - read.length,
             measuredExperiences: measured.length,
             assignedRewardsExcluded: assignedExcluded,
             ...(measured.length === 0 ? { evidenceStatus: 'insufficient-evidence' } : {}),
             patternsLearned: newPatterns.length,
+            ...(noPatternReason ? { noPatternReason } : {}),
             newPatterns,
             improvement: null,
             unmeasured: ['improvement'],
@@ -464,17 +479,11 @@ export class LearningOptimizeTool extends MCPToolBase {
                 experiencesLast24h += mineResult.value.experienceCount;
                 assignedRewardsExcluded += mineResult.value.assignedRewardsExcluded ?? 0;
                 // #1109: only a measured success rate can rank a domain.
-                const { successRate } = mineResult.value;
-                if (successRate !== null) {
-                    domainPerformance.push({ domain, successRate });
-                }
+                domainPerformance.push({ domain, successRate: mineResult.value.successRate });
             }
         }
-        // Calculate top performing domains
-        domainPerformance.sort((a, b) => b.successRate - a.successRate);
-        const topPerformingDomains = domainPerformance
-            .slice(0, 3)
-            .map(d => d.domain);
+        // #1147: rank by measured success; a domain at 0% is not top-performing.
+        const { topPerformingDomains, measuredDomains } = rankTopPerformingDomains(domainPerformance);
         // Calculate overall learning rate from pattern stats
         // getPatternStats already leaves out patterns learned from assigned rewards.
         const totalPatterns = statsResult.success ? statsResult.value.totalPatterns : 0;
@@ -528,7 +537,7 @@ export class LearningOptimizeTool extends MCPToolBase {
         const unmeasured = [];
         if (overallLearningRate === null)
             unmeasured.push('overallLearningRate');
-        if (topPerformingDomains.length === 0)
+        if (measuredDomains === 0)
             unmeasured.push('topPerformingDomains');
         return {
             overallLearningRate,

package/dist/planning/goap-planner.js

@@ -656,6 +656,10 @@ export class GOAPPlanner {
             }
             // #1157: goal and condition keys can come from callers; an inherited
             // member such as `constructor` is not part of the world state.
+            // #1186: deliberately, a key resolves only through own properties of
+            // objects. An array's own `length` resolves (`items.length`), but a
+            // primitive has no world-state members, so `name.length` on a string
+            // is undefined and a condition on it is unmet.
             if (typeof current !== 'object' || !Object.hasOwn(current, part)) {
                 return undefined;
             }

package/dist/planning/plan-executor.js

@@ -123,8 +123,8 @@ export class PlanExecutor {
         // This allows async unified storage initialization
         if (!this.config.useUnified) {
             // Legacy mode: create separate database immediately
-            this.db = openDatabase(dbPath ?? ':memory:', { walMode: false });
-            this.db.pragma('journal_mode = WAL');
+            // #1164: openDatabase() set the journal mode (retrying contention, honouring AQE_DISABLE_WAL).
+            this.db = openDatabase(dbPath ?? ':memory:');
         }
     }
     // ==========================================================================
@@ -911,6 +911,10 @@ export class PlanExecutor {
             }
             // #1157: goal and condition keys can come from callers; an inherited
             // member such as `constructor` is not part of the world state.
+            // #1186: deliberately, a key resolves only through own properties of
+            // objects. An array's own `length` resolves (`items.length`), but a
+            // primitive has no world-state members, so `name.length` on a string
+            // is undefined and a condition on it is unmet.
             if (typeof current !== 'object' || !Object.hasOwn(current, part)) {
                 return undefined;
             }

package/dist/shared/embeddings/index.d.ts

@@ -28,8 +28,8 @@
  */
 export { NomicEmbedder, createNomicEmbedder } from './nomic-embedder';
 export type { NomicEmbedderConfig } from './nomic-embedder';
-export { OllamaClient } from './ollama-client';
+export { OllamaClient, isConfiguredOllamaModel } from './ollama-client';
 export { EmbeddingCache } from './embedding-cache';
-export type { CodeChunk, EmbeddingResult, EmbeddingBatchResult, OllamaEmbeddingRequest, OllamaEmbeddingResponse, OllamaHealthResponse, CacheStats, EmbeddingCacheEntry, BatchProgress, ProgressCallback, IEmbeddingProvider, } from './types';
+export type { CodeChunk, EmbeddingResult, EmbeddingBatchResult, OllamaEmbeddingRequest, OllamaEmbeddingResponse, OllamaHealthResponse, OllamaModelStatus, CacheStats, EmbeddingCacheEntry, BatchProgress, ProgressCallback, IEmbeddingProvider, } from './types';
 export { EMBEDDING_CONFIG } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/shared/embeddings/index.js

@@ -27,7 +27,7 @@
  * ```
  */
 export { NomicEmbedder, createNomicEmbedder } from './nomic-embedder.js';
-export { OllamaClient } from './ollama-client.js';
+export { OllamaClient, isConfiguredOllamaModel } from './ollama-client.js';
 export { EmbeddingCache } from './embedding-cache.js';
 export { EMBEDDING_CONFIG } from './types.js';
 //# sourceMappingURL=index.js.map

package/dist/shared/embeddings/nomic-embedder.d.ts

@@ -11,13 +11,15 @@
  * - Error handling and retries
  */
 import { EmbeddingCache } from './embedding-cache';
-import { CodeChunk, EmbeddingBatchResult, ProgressCallback, CacheStats, IEmbeddingProvider } from './types';
+import { CodeChunk, EmbeddingBatchResult, ProgressCallback, CacheStats, IEmbeddingProvider, OllamaModelStatus } from './types';
 /**
  * Configuration for NomicEmbedder
  */
 export interface NomicEmbedderConfig {
     /** Ollama base URL (default: http://localhost:11434) */
     ollamaBaseUrl?: string;
+    /** #1229: installed Ollama model to use (default: AQE_OLLAMA_EMBEDDING_MODEL, else found by name) */
+    ollamaModel?: string;
     /** Batch size for processing (default: 100) */
     batchSize?: number;
     /** Maximum cache size (default: 10000) */
@@ -100,6 +102,10 @@ export declare class NomicEmbedder implements IEmbeddingProvider {
      * Verify Ollama connection and model availability
      */
     healthCheck(): Promise<boolean>;
+    /** #1229: the installed Ollama model, or why there is none. */
+    checkModel(): Promise<OllamaModelStatus>;
+    /** Identifies the embedding space of this embedder's vectors (ADR-097). */
+    getModelId(): string;
     /**
      * Get Ollama server information
      */
@@ -112,7 +118,7 @@ export declare class NomicEmbedder implements IEmbeddingProvider {
      * Get configuration info
      */
     getConfig(): {
-        model: "all-MiniLM-L6-v2";
+        model: string;
         dimensions: 384;
         contextWindow: 8192;
         batchSize: number;

package/dist/shared/embeddings/nomic-embedder.js

@@ -17,7 +17,7 @@ import { EMBEDDING_CONFIG, } from './types.js';
 const PSEUDO_EMBEDDING_MODEL = 'pseudo-embedding';
 // Unversioned real-model entries may predate fallback provenance separation.
 const VERIFIED_MODEL_CACHE_NAMESPACE = 'verified-backend-v1';
-const cacheNamespace = (model) => model === EMBEDDING_CONFIG.MODEL ? VERIFIED_MODEL_CACHE_NAMESPACE : undefined;
+const cacheNamespace = (model) => model === PSEUDO_EMBEDDING_MODEL ? undefined : VERIFIED_MODEL_CACHE_NAMESPACE;
 /**
  * Nomic Embedder for generating code embeddings via Ollama
  */
@@ -45,7 +45,7 @@ export class NomicEmbedder {
      * ```
      */
     constructor(config = {}) {
-        this.client = new OllamaClient(config.ollamaBaseUrl);
+        this.client = new OllamaClient(config.ollamaBaseUrl, undefined, undefined, undefined, config.ollamaModel);
         this.cache = config.cache ?? new EmbeddingCache(config.maxCacheSize);
         this.batchSize = config.batchSize ?? EMBEDDING_CONFIG.BATCH_SIZE;
         this.enableFallback = config.enableFallback ?? true;
@@ -56,9 +56,9 @@ export class NomicEmbedder {
     async embed(text) {
         // Prefer genuine cached vectors, then select the active backend before a
         // single counted lookup so alternate namespaces do not inflate misses.
-        let model = this.cache.has(text, EMBEDDING_CONFIG.MODEL, VERIFIED_MODEL_CACHE_NAMESPACE) ||
+        let model = this.cache.has(text, this.getModelId(), VERIFIED_MODEL_CACHE_NAMESPACE) ||
             await this.isOllamaAvailable() || !this.enableFallback
-            ? EMBEDDING_CONFIG.MODEL : PSEUDO_EMBEDDING_MODEL;
+            ? this.getModelId() : PSEUDO_EMBEDDING_MODEL;
         const cached = this.cache.get(text, model, cacheNamespace(model));
         if (cached) {
             return cached;
@@ -66,7 +66,7 @@ export class NomicEmbedder {
         // Try Ollama first, fall back to pseudo-embedding if unavailable
         let embedding;
         if (await this.isOllamaAvailable()) {
-            model = EMBEDDING_CONFIG.MODEL;
+            model = this.getModelId();
             embedding = await this.client.generateEmbedding(text);
         }
         else if (this.enableFallback) {
@@ -75,7 +75,7 @@ export class NomicEmbedder {
         }
         else {
             throw new Error(`Ollama is not available and fallback is disabled. ` +
-                `Please run: ollama pull ${EMBEDDING_CONFIG.MODEL}`);
+                `Please run: ollama pull ${EMBEDDING_CONFIG.OLLAMA_PULL_NAME}`);
         }
         // Cache result
         this.cache.set(text, model, embedding, cacheNamespace(model));
@@ -137,7 +137,7 @@ export class NomicEmbedder {
         }
         else if (!this.enableFallback) {
             throw new Error(`Ollama is not available and fallback is disabled. ` +
-                `Please run: ollama pull ${EMBEDDING_CONFIG.MODEL}`);
+                `Please run: ollama pull ${EMBEDDING_CONFIG.OLLAMA_PULL_NAME}`);
         }
         // Process in batches
         for (let i = 0; i < chunks.length; i += this.batchSize) {
@@ -191,8 +191,8 @@ export class NomicEmbedder {
             const formattedText = this.formatForEmbedding(chunk);
             const chunkStartTime = Date.now();
             // Check cache
-            const cachedModel = useOllama || this.cache.has(formattedText, EMBEDDING_CONFIG.MODEL, VERIFIED_MODEL_CACHE_NAMESPACE)
-                ? EMBEDDING_CONFIG.MODEL : PSEUDO_EMBEDDING_MODEL;
+            const cachedModel = useOllama || this.cache.has(formattedText, this.getModelId(), VERIFIED_MODEL_CACHE_NAMESPACE)
+                ? this.getModelId() : PSEUDO_EMBEDDING_MODEL;
             const cachedEmbedding = this.cache.get(formattedText, cachedModel, cacheNamespace(cachedModel));
             if (cachedEmbedding) {
                 return {
@@ -213,7 +213,7 @@ export class NomicEmbedder {
                     embedding = this.generatePseudoEmbedding(formattedText);
                 }
                 // Cache the result
-                const model = useOllama ? EMBEDDING_CONFIG.MODEL : PSEUDO_EMBEDDING_MODEL;
+                const model = useOllama ? this.getModelId() : PSEUDO_EMBEDDING_MODEL;
                 this.cache.set(formattedText, model, embedding, cacheNamespace(model));
                 return {
                     chunkId: chunk.id,
@@ -300,6 +300,14 @@ export class NomicEmbedder {
     async healthCheck() {
         return await this.client.healthCheck();
     }
+    /** #1229: the installed Ollama model, or why there is none. */
+    async checkModel() {
+        return await this.client.checkModel();
+    }
+    /** Identifies the embedding space of this embedder's vectors (ADR-097). */
+    getModelId() {
+        return this.client.getModelId();
+    }
     /**
      * Get Ollama server information
      */
@@ -317,7 +325,7 @@ export class NomicEmbedder {
      */
     getConfig() {
         return {
-            model: EMBEDDING_CONFIG.MODEL,
+            model: this.getModelId(),
             dimensions: EMBEDDING_CONFIG.DIMENSIONS,
             contextWindow: EMBEDDING_CONFIG.CONTEXT_WINDOW,
             batchSize: this.batchSize,

package/dist/shared/embeddings/ollama-client.d.ts

@@ -2,7 +2,16 @@
  * Agentic QE v3 - Ollama API Client
  * Client for Ollama embeddings API with retry logic
  */
-import { OllamaHealthResponse } from './types';
+import { OllamaHealthResponse, OllamaModelStatus } from './types';
+/**
+ * #1229: whether an installed Ollama model is EMBEDDING_CONFIG.MODEL. Accepts
+ * the exact name with any namespace and tag (`Xenova/all-MiniLM-L6-v2:latest`)
+ * and Ollama's library name `all-minilm` with an L6 tag (`all-minilm:22m`).
+ * Other models are rejected, even 384-dimensional ones such as
+ * `all-minilm:33m` (all-MiniLM-L12-v2): their vectors are in another
+ * embedding space (ADR-097).
+ */
+export declare function isConfiguredOllamaModel(listed: string): boolean;
 /**
  * Client for Ollama API
  */
@@ -11,11 +20,28 @@ export declare class OllamaClient {
     private maxRetries;
     private retryDelayMs;
     private timeoutMs;
-    constructor(baseUrl?: string, maxRetries?: number, retryDelayMs?: number, timeoutMs?: number);
+    /** #1229: the Ollama model named by the user (AQE_OLLAMA_EMBEDDING_MODEL), if any. */
+    private readonly requestedModel?;
+    /** The installed Ollama model found by the last successful check. */
+    private installedModel;
+    constructor(baseUrl?: string, maxRetries?: number, retryDelayMs?: number, timeoutMs?: number, ollamaModel?: string | undefined);
+    /** The Ollama server this client talks to. */
+    getBaseUrl(): string;
+    /**
+     * Identifies the embedding space of this client's vectors. A model named by
+     * AQE_OLLAMA_EMBEDDING_MODEL that is not EMBEDDING_CONFIG.MODEL gets its own
+     * id, so its vectors are never compared with stored MiniLM vectors (ADR-097).
+     */
+    getModelId(): string;
     /**
      * Check if Ollama is running and the configured embedding model is available
      */
     healthCheck(): Promise<boolean>;
+    /**
+     * #1229: find the installed Ollama model to embed with, or say why there is
+     * none (Ollama unreachable, or reachable without the model).
+     */
+    checkModel(): Promise<OllamaModelStatus>;
     /**
      * Generate embedding for a single text prompt
      */

package/dist/shared/embeddings/ollama-client.js

@@ -5,6 +5,30 @@
 import { toError } from '../error-utils.js';
 import { EMBEDDING_CONFIG, } from './types.js';
 import { resolveOllamaBaseUrl } from '../llm/ollama-url.js';
+/** Tags of Ollama's `all-minilm` that are all-MiniLM-L6-v2 (33m / l12-v2 is the L12 model). */
+const ALL_MINILM_L6_TAG = /^(latest|22m(-.*)?|l6-v2(-.*)?)?$/i;
+/** Splits `namespace/name:tag` into the name part and the tag ('' when untagged). */
+function splitTag(listed) {
+    const colon = listed.lastIndexOf(':');
+    return colon > listed.lastIndexOf('/')
+        ? { base: listed.slice(0, colon), tag: listed.slice(colon + 1) }
+        : { base: listed, tag: '' };
+}
+/**
+ * #1229: whether an installed Ollama model is EMBEDDING_CONFIG.MODEL. Accepts
+ * the exact name with any namespace and tag (`Xenova/all-MiniLM-L6-v2:latest`)
+ * and Ollama's library name `all-minilm` with an L6 tag (`all-minilm:22m`).
+ * Other models are rejected, even 384-dimensional ones such as
+ * `all-minilm:33m` (all-MiniLM-L12-v2): their vectors are in another
+ * embedding space (ADR-097).
+ */
+export function isConfiguredOllamaModel(listed) {
+    const { base, tag } = splitTag(listed);
+    const name = base.slice(base.lastIndexOf('/') + 1).toLowerCase();
+    if (name === EMBEDDING_CONFIG.MODEL.toLowerCase())
+        return true;
+    return base.toLowerCase() === 'all-minilm' && ALL_MINILM_L6_TAG.test(tag);
+}
 /**
  * Client for Ollama API
  */
@@ -13,46 +37,85 @@ export class OllamaClient {
     maxRetries;
     retryDelayMs;
     timeoutMs;
-    constructor(baseUrl = resolveOllamaBaseUrl(EMBEDDING_CONFIG.DEFAULT_OLLAMA_URL), maxRetries = EMBEDDING_CONFIG.MAX_RETRIES, retryDelayMs = EMBEDDING_CONFIG.RETRY_DELAY_MS, timeoutMs = EMBEDDING_CONFIG.TIMEOUT_MS) {
+    /** #1229: the Ollama model named by the user (AQE_OLLAMA_EMBEDDING_MODEL), if any. */
+    requestedModel;
+    /** The installed Ollama model found by the last successful check. */
+    installedModel = null;
+    constructor(baseUrl = resolveOllamaBaseUrl(EMBEDDING_CONFIG.DEFAULT_OLLAMA_URL), maxRetries = EMBEDDING_CONFIG.MAX_RETRIES, retryDelayMs = EMBEDDING_CONFIG.RETRY_DELAY_MS, timeoutMs = EMBEDDING_CONFIG.TIMEOUT_MS, ollamaModel = process.env[EMBEDDING_CONFIG.OLLAMA_MODEL_ENV]) {
         this.baseUrl = baseUrl.replace(/\/$/, ''); // Remove trailing slash
         this.maxRetries = maxRetries;
         this.retryDelayMs = retryDelayMs;
         this.timeoutMs = timeoutMs;
+        this.requestedModel = ollamaModel?.trim() || undefined;
+    }
+    /** The Ollama server this client talks to. */
+    getBaseUrl() {
+        return this.baseUrl;
+    }
+    /**
+     * Identifies the embedding space of this client's vectors. A model named by
+     * AQE_OLLAMA_EMBEDDING_MODEL that is not EMBEDDING_CONFIG.MODEL gets its own
+     * id, so its vectors are never compared with stored MiniLM vectors (ADR-097).
+     */
+    getModelId() {
+        return !this.requestedModel || isConfiguredOllamaModel(this.requestedModel)
+            ? EMBEDDING_CONFIG.MODEL
+            : `ollama:${this.requestedModel}`;
     }
     /**
      * Check if Ollama is running and the configured embedding model is available
      */
     async healthCheck() {
+        return (await this.checkModel()).status === 'available';
+    }
+    /**
+     * #1229: find the installed Ollama model to embed with, or say why there is
+     * none (Ollama unreachable, or reachable without the model).
+     */
+    async checkModel() {
+        const wanted = this.requestedModel ?? EMBEDDING_CONFIG.MODEL;
+        let data;
         try {
-            return await this.fetchWithTimeout(`${this.baseUrl}/api/tags`, {
+            data = await this.fetchWithTimeout(`${this.baseUrl}/api/tags`, {
                 method: 'GET',
                 headers: { 'Content-Type': 'application/json' },
             }, 5000, // Shorter timeout for health check
-            async (response) => {
-                if (!response.ok)
-                    return false;
-                const data = await response.json();
-                // Check if configured embedding model is available
-                // Match the configured model exactly, allowing its existing tag suffix.
-                if (data.models) {
-                    return data.models.some((model) => model.name === EMBEDDING_CONFIG.MODEL ||
-                        model.name?.startsWith(`${EMBEDDING_CONFIG.MODEL}:`) ||
-                        model.model === EMBEDDING_CONFIG.MODEL ||
-                        model.model?.startsWith(`${EMBEDDING_CONFIG.MODEL}:`));
-                }
-                return false;
-            });
+            async (response) => response.ok
+                ? await response.json()
+                : { httpStatus: response.status });
         }
         catch {
-            return false;
+            return { status: 'unreachable', reason: `Ollama at ${this.baseUrl} is not reachable` };
         }
+        if (data && 'httpStatus' in data) {
+            return {
+                status: 'unreachable',
+                reason: `Ollama at ${this.baseUrl} answered HTTP ${data.httpStatus} when listing models`,
+            };
+        }
+        const requested = this.requestedModel;
+        const matches = requested
+            ? (listed) => listed === requested || (!splitTag(requested).tag && listed === `${requested}:latest`)
+            : isConfiguredOllamaModel;
+        for (const model of data?.models ?? []) {
+            const found = [model.name, model.model].find((listed) => !!listed && matches(listed));
+            if (found) {
+                this.installedModel = found;
+                return { status: 'available', model: found };
+            }
+        }
+        return {
+            status: 'missing',
+            reason: `model '${wanted}' not installed in Ollama at ${this.baseUrl}; ` +
+                `install it with: ollama pull ${requested ?? EMBEDDING_CONFIG.OLLAMA_PULL_NAME}`,
+        };
     }
     /**
      * Generate embedding for a single text prompt
      */
     async generateEmbedding(prompt) {
         const request = {
-            model: EMBEDDING_CONFIG.MODEL,
+            model: this.installedModel ?? this.requestedModel ?? EMBEDDING_CONFIG.MODEL,
             prompt,
         };
         let lastError = null;
@@ -133,10 +196,9 @@ export class OllamaClient {
      * Verify model is available and throw if not
      */
     async ensureModelAvailable() {
-        const isHealthy = await this.healthCheck();
-        if (!isHealthy) {
-            throw new Error(`Ollama model '${EMBEDDING_CONFIG.MODEL}' is not available. ` +
-                `Please run: ollama pull ${EMBEDDING_CONFIG.MODEL}`);
+        const check = await this.checkModel();
+        if (check.status !== 'available') {
+            throw new Error(`Ollama model '${this.requestedModel ?? EMBEDDING_CONFIG.MODEL}' is not available: ${check.reason}`);
         }
     }
 }

package/dist/shared/embeddings/types.d.ts

@@ -120,6 +120,21 @@ export declare const EMBEDDING_CONFIG: {
     readonly TIMEOUT_MS: 30000;
     /** Default Ollama URL */
     readonly DEFAULT_OLLAMA_URL: "http://localhost:11434";
+    /** #1229: Ollama library name of MODEL, used in install hints */
+    readonly OLLAMA_PULL_NAME: "all-minilm:22m";
+    /** #1229: env var naming the installed Ollama model to use for MODEL */
+    readonly OLLAMA_MODEL_ENV: "AQE_OLLAMA_EMBEDDING_MODEL";
+};
+/**
+ * #1229: whether Ollama has the configured embedding model. `reason` says why
+ * not: Ollama did not answer, or it answered without the model.
+ */
+export type OllamaModelStatus = {
+    status: 'available';
+    model: string;
+} | {
+    status: 'missing' | 'unreachable';
+    reason: string;
 };
 /**
  * Interface for embedding providers

package/dist/shared/embeddings/types.js

@@ -22,5 +22,9 @@ export const EMBEDDING_CONFIG = {
     TIMEOUT_MS: 30000,
     /** Default Ollama URL */
     DEFAULT_OLLAMA_URL: 'http://localhost:11434',
+    /** #1229: Ollama library name of MODEL, used in install hints */
+    OLLAMA_PULL_NAME: 'all-minilm:22m',
+    /** #1229: env var naming the installed Ollama model to use for MODEL */
+    OLLAMA_MODEL_ENV: 'AQE_OLLAMA_EMBEDDING_MODEL',
 };
 //# sourceMappingURL=types.js.map