@cleocode/core 2026.3.68 → 2026.3.70

package/dist/memory/embedding-local.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Local embedding provider using @xenova/transformers.
+ *
+ * Implements the EmbeddingProvider interface for brain memory vector search.
+ * Uses all-MiniLM-L6-v2 (22MB, 384 dimensions) — matches the brain_embeddings
+ * vec0 table schema. Model downloads on first call and is cached locally by
+ * the transformers library.
+ *
+ * @epic T134
+ * @task T136
+ * @why Ship vector search out-of-the-box without external API keys
+ * @what Local embedding provider using @xenova/transformers all-MiniLM-L6-v2
+ */
+import type { EmbeddingProvider } from './brain-embedding.js';
+/**
+ * Local embedding provider backed by @xenova/transformers.
+ *
+ * Produces 384-dimension Float32Array vectors compatible with the
+ * brain_embeddings vec0 table. The model is downloaded on first use
+ * and cached locally by the transformers library.
+ *
+ * Use {@link initDefaultProvider} (in brain-embedding.ts) to register an
+ * instance when brain.embedding.enabled=true and
+ * brain.embedding.provider='local'.
+ */
+export declare class LocalEmbeddingProvider implements EmbeddingProvider {
+    /** Number of dimensions produced — must match brain_embeddings vec0 table. */
+    readonly dimensions = 384;
+    /**
+     * Whether the pipeline has been successfully initialized and is ready to produce embeddings.
+     */
+    isAvailable(): boolean;
+    /**
+     * Convert a single text string into a 384-dimension float vector.
+     * Triggers model download on first call if not already cached.
+     *
+     * @param text - The text to embed.
+     * @returns A Float32Array of length 384.
+     */
+    embed(text: string): Promise<Float32Array>;
+    /**
+     * Embed multiple texts in sequence, reusing the cached pipeline.
+     *
+     * @param texts - Array of text strings to embed.
+     * @returns Array of Float32Array vectors, one per input text.
+     */
+    embedBatch(texts: string[]): Promise<Float32Array[]>;
+}
+/**
+ * Get or create the shared LocalEmbeddingProvider singleton.
+ *
+ * @returns The shared LocalEmbeddingProvider instance.
+ */
+export declare function getLocalEmbeddingProvider(): LocalEmbeddingProvider;
+//# sourceMappingURL=embedding-local.d.ts.map

package/dist/memory/embedding-local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-local.d.ts","sourceRoot":"","sources":["../../src/memory/embedding-local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAwB9D;;;;;;;;;;GAUG;AACH,qBAAa,sBAAuB,YAAW,iBAAiB;IAC9D,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,OAAwB;IAE3C;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;;;;;OAMG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAShD;;;;;OAKG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;CAS3D;AAKD;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,sBAAsB,CAKlE"}

package/dist/memory/embedding-local.js

@@ -0,0 +1,97 @@
+/**
+ * Local embedding provider using @xenova/transformers.
+ *
+ * Implements the EmbeddingProvider interface for brain memory vector search.
+ * Uses all-MiniLM-L6-v2 (22MB, 384 dimensions) — matches the brain_embeddings
+ * vec0 table schema. Model downloads on first call and is cached locally by
+ * the transformers library.
+ *
+ * @epic T134
+ * @task T136
+ * @why Ship vector search out-of-the-box without external API keys
+ * @what Local embedding provider using @xenova/transformers all-MiniLM-L6-v2
+ */
+import { EMBEDDING_DIMENSIONS } from './brain-embedding.js';
+/** Model identifier for all-MiniLM-L6-v2 via Xenova hub. */
+const MODEL_NAME = 'Xenova/all-MiniLM-L6-v2';
+/** Pipeline singleton — initialized lazily on first call. */
+let _pipeline = null;
+/** Whether the pipeline has been successfully initialized. */
+let _ready = false;
+/**
+ * Load the transformers feature-extraction pipeline lazily.
+ * Dynamic import prevents the heavy model from loading unless embedding is enabled.
+ */
+async function loadPipeline() {
+    if (_ready)
+        return;
+    // Dynamic import — only resolves when embedding is explicitly enabled
+    const { pipeline } = await import('@xenova/transformers');
+    _pipeline = await pipeline('feature-extraction', MODEL_NAME);
+    _ready = true;
+}
+/**
+ * Local embedding provider backed by @xenova/transformers.
+ *
+ * Produces 384-dimension Float32Array vectors compatible with the
+ * brain_embeddings vec0 table. The model is downloaded on first use
+ * and cached locally by the transformers library.
+ *
+ * Use {@link initDefaultProvider} (in brain-embedding.ts) to register an
+ * instance when brain.embedding.enabled=true and
+ * brain.embedding.provider='local'.
+ */
+export class LocalEmbeddingProvider {
+    /** Number of dimensions produced — must match brain_embeddings vec0 table. */
+    dimensions = EMBEDDING_DIMENSIONS;
+    /**
+     * Whether the pipeline has been successfully initialized and is ready to produce embeddings.
+     */
+    isAvailable() {
+        return _ready;
+    }
+    /**
+     * Convert a single text string into a 384-dimension float vector.
+     * Triggers model download on first call if not already cached.
+     *
+     * @param text - The text to embed.
+     * @returns A Float32Array of length 384.
+     */
+    async embed(text) {
+        await loadPipeline();
+        const output = await _pipeline(text, { pooling: 'mean', normalize: true });
+        // output.data is DataArray (AnyTypedArray | any[]). For feature-extraction
+        // with all-MiniLM-L6-v2, the runtime value is always Float32Array. Copy via
+        // Float32Array constructor which accepts any iterable of numbers.
+        return Float32Array.from(output.data);
+    }
+    /**
+     * Embed multiple texts in sequence, reusing the cached pipeline.
+     *
+     * @param texts - Array of text strings to embed.
+     * @returns Array of Float32Array vectors, one per input text.
+     */
+    async embedBatch(texts) {
+        await loadPipeline();
+        const results = [];
+        for (const text of texts) {
+            const output = await _pipeline(text, { pooling: 'mean', normalize: true });
+            results.push(Float32Array.from(output.data));
+        }
+        return results;
+    }
+}
+/** Module-level singleton instance. */
+let _instance = null;
+/**
+ * Get or create the shared LocalEmbeddingProvider singleton.
+ *
+ * @returns The shared LocalEmbeddingProvider instance.
+ */
+export function getLocalEmbeddingProvider() {
+    if (!_instance) {
+        _instance = new LocalEmbeddingProvider();
+    }
+    return _instance;
+}
+//# sourceMappingURL=embedding-local.js.map

package/dist/memory/embedding-local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-local.js","sourceRoot":"","sources":["../../src/memory/embedding-local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE5D,4DAA4D;AAC5D,MAAM,UAAU,GAAG,yBAAyB,CAAC;AAE7C,6DAA6D;AAC7D,IAAI,SAAS,GAAoE,IAAI,CAAC;AAEtF,8DAA8D;AAC9D,IAAI,MAAM,GAAG,KAAK,CAAC;AAEnB;;;GAGG;AACH,KAAK,UAAU,YAAY;IACzB,IAAI,MAAM;QAAE,OAAO;IACnB,sEAAsE;IACtE,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;IAC1D,SAAS,GAAG,MAAM,QAAQ,CAAC,oBAAoB,EAAE,UAAU,CAAC,CAAC;IAC7D,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,sBAAsB;IACjC,8EAA8E;IACrE,UAAU,GAAG,oBAAoB,CAAC;IAE3C;;OAEG;IACH,WAAW;QACT,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,MAAM,YAAY,EAAE,CAAC;QACrB,MAAM,MAAM,GAAG,MAAM,SAAU,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5E,2EAA2E;QAC3E,4EAA4E;QAC5E,kEAAkE;QAClE,OAAO,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,IAAoB,CAAC,CAAC;IACxD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,KAAe;QAC9B,MAAM,YAAY,EAAE,CAAC;QACrB,MAAM,OAAO,GAAmB,EAAE,CAAC;QACnC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,MAAM,GAAG,MAAM,SAAU,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5E,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,IAAoB,CAAC,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;CACF;AAED,uCAAuC;AACvC,IAAI,SAAS,GAAkC,IAAI,CAAC;AAEpD;;;;GAIG;AACH,MAAM,UAAU,yBAAyB;IACvC,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,SAAS,GAAG,IAAI,sBAAsB,EAAE,CAAC;IAC3C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/memory/embedding-queue.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Embedding Queue Manager
+ *
+ * Manages an async queue of embedding requests, processing them in batches
+ * via a worker thread to avoid blocking the main Node.js event loop.
+ *
+ * Architecture:
+ *   - {@link EmbeddingQueue} is a singleton — one worker thread per process
+ *   - {@link EmbeddingQueue.enqueue} adds items; the drain loop batches them
+ *   - Batches up to {@link BATCH_SIZE} items per processing cycle
+ *   - Falls back to `setImmediate` + direct embedding when worker threads
+ *     are unavailable or the worker script cannot be resolved
+ *   - Registers a `process.on('exit')` handler for graceful shutdown
+ *
+ * @epic T134
+ * @task T137
+ * @why Non-blocking embedding generation for observeBrain()
+ * @what Singleton queue + worker-thread batch processor
+ */
+/**
+ * Singleton embedding queue.
+ *
+ * Batches embedding requests and processes them via a worker thread,
+ * keeping heavy model inference off the main event loop.
+ *
+ * Use {@link getEmbeddingQueue} to obtain the shared instance.
+ */
+export declare class EmbeddingQueue {
+    private readonly queue;
+    private worker;
+    private workerAvailable;
+    private draining;
+    private shutdownPromise;
+    /**
+     * Store the observation ID → DB write callback so the worker result
+     * can be persisted back to brain_embeddings without coupling to SQLite here.
+     */
+    private readonly callbacks;
+    /** Initialise the worker thread if possible. Called lazily on first enqueue. */
+    private initWorker;
+    /**
+     * Add an observation to the embedding queue.
+     *
+     * The observation must already be persisted in brain_observations before
+     * calling this method. `onComplete` is called asynchronously with the
+     * generated vector once the worker finishes.
+     *
+     * @param observationId - The brain observation ID (e.g. `O-abc123-0`)
+     * @param text - Raw text to embed
+     * @param onComplete - Callback to persist the embedding vector
+     */
+    enqueue(observationId: string, text: string, onComplete: (observationId: string, embedding: Float32Array) => Promise<void>): void;
+    /** Schedule the next drain cycle via setImmediate. */
+    private scheduleDrain;
+    /**
+     * Process up to {@link BATCH_SIZE} items from the queue.
+     * Uses the worker thread when available, falls back to inline setImmediate.
+     */
+    private drain;
+    /**
+     * Inline fallback embedding — used when worker thread is unavailable.
+     * Runs directly on the main thread (but inside setImmediate to yield first).
+     */
+    private fallbackEmbed;
+    /**
+     * Flush the queue and terminate the worker thread.
+     *
+     * Waits for in-flight worker messages to drain, then terminates.
+     * Safe to call multiple times — subsequent calls return the same promise.
+     */
+    shutdown(): Promise<void>;
+    private doShutdown;
+}
+/**
+ * Get or create the shared EmbeddingQueue singleton.
+ *
+ * Registers a process `exit` handler on first call to flush and
+ * terminate the worker thread cleanly.
+ *
+ * @returns The shared EmbeddingQueue instance.
+ */
+export declare function getEmbeddingQueue(): EmbeddingQueue;
+/**
+ * Reset the singleton (for testing only).
+ * Shuts down the existing queue before clearing the reference.
+ *
+ * @internal
+ */
+export declare function resetEmbeddingQueue(): Promise<void>;
+//# sourceMappingURL=embedding-queue.d.ts.map

package/dist/memory/embedding-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-queue.d.ts","sourceRoot":"","sources":["../../src/memory/embedding-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA4CH;;;;;;;GAOG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;IACzC,OAAO,CAAC,MAAM,CAAqD;IACnE,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,eAAe,CAA8B;IAErD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAGtB;IAEJ,gFAAgF;YAClE,UAAU;IAgDxB;;;;;;;;;;OAUG;IACH,OAAO,CACL,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,GAC5E,IAAI;IASP,sDAAsD;IACtD,OAAO,CAAC,aAAa;IASrB;;;OAGG;YACW,KAAK;IAmCnB;;;OAGG;YACW,aAAa;IAW3B;;;;;OAKG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;YAMX,UAAU;CAkBzB;AAKD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAwBlD;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAKzD"}

package/dist/memory/embedding-queue.js

@@ -0,0 +1,271 @@
+/**
+ * Embedding Queue Manager
+ *
+ * Manages an async queue of embedding requests, processing them in batches
+ * via a worker thread to avoid blocking the main Node.js event loop.
+ *
+ * Architecture:
+ *   - {@link EmbeddingQueue} is a singleton — one worker thread per process
+ *   - {@link EmbeddingQueue.enqueue} adds items; the drain loop batches them
+ *   - Batches up to {@link BATCH_SIZE} items per processing cycle
+ *   - Falls back to `setImmediate` + direct embedding when worker threads
+ *     are unavailable or the worker script cannot be resolved
+ *   - Registers a `process.on('exit')` handler for graceful shutdown
+ *
+ * @epic T134
+ * @task T137
+ * @why Non-blocking embedding generation for observeBrain()
+ * @what Singleton queue + worker-thread batch processor
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Maximum items processed per worker message cycle. */
+const BATCH_SIZE = 10;
+/** How long to wait between drain cycles when the queue is non-empty (ms). */
+const DRAIN_INTERVAL_MS = 50;
+/**
+ * Resolve the absolute path to the compiled embedding-worker script.
+ *
+ * Strategy (cheap-first):
+ * 1. Adjacent to this file (tsc dev: `dist/memory/embedding-worker.js`)
+ * 2. Falls back to null when the file cannot be found (esbuild bundle context)
+ */
+function resolveWorkerPath() {
+    try {
+        // In ESM, __dirname is not available — use import.meta.url
+        const currentDir = dirname(fileURLToPath(import.meta.url));
+        const candidate = join(currentDir, 'embedding-worker.js');
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+        // Also try ../ for cases where the queue is loaded from a subdirectory
+        const parentCandidate = join(currentDir, '..', 'memory', 'embedding-worker.js');
+        if (existsSync(parentCandidate)) {
+            return parentCandidate;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Singleton embedding queue.
+ *
+ * Batches embedding requests and processes them via a worker thread,
+ * keeping heavy model inference off the main event loop.
+ *
+ * Use {@link getEmbeddingQueue} to obtain the shared instance.
+ */
+export class EmbeddingQueue {
+    queue = [];
+    worker = null;
+    workerAvailable = false;
+    draining = false;
+    shutdownPromise = null;
+    /**
+     * Store the observation ID → DB write callback so the worker result
+     * can be persisted back to brain_embeddings without coupling to SQLite here.
+     */
+    callbacks = new Map();
+    /** Initialise the worker thread if possible. Called lazily on first enqueue. */
+    async initWorker() {
+        if (this.workerAvailable || this.worker !== null)
+            return;
+        const workerPath = resolveWorkerPath();
+        if (!workerPath) {
+            // esbuild bundle context — worker file not available, use fallback
+            this.workerAvailable = false;
+            return;
+        }
+        try {
+            const { Worker } = await import('node:worker_threads');
+            const worker = new Worker(workerPath);
+            worker.on('message', (msg) => {
+                const cb = this.callbacks.get(msg.id);
+                if (!cb)
+                    return;
+                this.callbacks.delete(msg.id);
+                if (msg.embedding) {
+                    const vector = Float32Array.from(msg.embedding);
+                    cb(msg.id, vector).catch(() => {
+                        // Persistence is best-effort; observation already saved without vector
+                    });
+                }
+                // On error, skip silently — observation exists without embedding
+            });
+            worker.on('error', () => {
+                // Worker crashed — disable worker path, drain remaining via fallback
+                this.worker = null;
+                this.workerAvailable = false;
+                this.callbacks.clear();
+            });
+            worker.on('exit', () => {
+                this.worker = null;
+                this.workerAvailable = false;
+            });
+            this.worker = worker;
+            this.workerAvailable = true;
+        }
+        catch {
+            // worker_threads unavailable (rare)
+            this.workerAvailable = false;
+        }
+    }
+    /**
+     * Add an observation to the embedding queue.
+     *
+     * The observation must already be persisted in brain_observations before
+     * calling this method. `onComplete` is called asynchronously with the
+     * generated vector once the worker finishes.
+     *
+     * @param observationId - The brain observation ID (e.g. `O-abc123-0`)
+     * @param text - Raw text to embed
+     * @param onComplete - Callback to persist the embedding vector
+     */
+    enqueue(observationId, text, onComplete) {
+        if (this.shutdownPromise)
+            return; // queue is shutting down
+        this.callbacks.set(observationId, onComplete);
+        this.queue.push({ observationId, text });
+        if (!this.draining) {
+            this.scheduleDrain();
+        }
+    }
+    /** Schedule the next drain cycle via setImmediate. */
+    scheduleDrain() {
+        setImmediate(() => {
+            this.drain().catch(() => {
+                // Drain errors are non-fatal
+                this.draining = false;
+            });
+        });
+    }
+    /**
+     * Process up to {@link BATCH_SIZE} items from the queue.
+     * Uses the worker thread when available, falls back to inline setImmediate.
+     */
+    async drain() {
+        this.draining = true;
+        // Ensure worker is initialised (no-op after first call)
+        await this.initWorker();
+        while (this.queue.length > 0) {
+            const batch = this.queue.splice(0, BATCH_SIZE);
+            if (this.workerAvailable && this.worker) {
+                // Dispatch to worker thread — results arrive via 'message' event
+                for (const item of batch) {
+                    this.worker.postMessage({ id: item.observationId, text: item.text });
+                }
+            }
+            else {
+                // Fallback: process inline via setImmediate to yield to event loop
+                for (const item of batch) {
+                    setImmediate(() => {
+                        this.fallbackEmbed(item).catch(() => {
+                            // Silently skip — observation already persisted without embedding
+                            this.callbacks.delete(item.observationId);
+                        });
+                    });
+                }
+            }
+            if (this.queue.length > 0) {
+                // Yield to event loop between batches
+                await new Promise((resolve) => setTimeout(resolve, DRAIN_INTERVAL_MS));
+            }
+        }
+        this.draining = false;
+    }
+    /**
+     * Inline fallback embedding — used when worker thread is unavailable.
+     * Runs directly on the main thread (but inside setImmediate to yield first).
+     */
+    async fallbackEmbed(item) {
+        const cb = this.callbacks.get(item.observationId);
+        if (!cb)
+            return;
+        this.callbacks.delete(item.observationId);
+        const { getLocalEmbeddingProvider } = await import('./embedding-local.js');
+        const provider = getLocalEmbeddingProvider();
+        const vector = await provider.embed(item.text);
+        await cb(item.observationId, vector);
+    }
+    /**
+     * Flush the queue and terminate the worker thread.
+     *
+     * Waits for in-flight worker messages to drain, then terminates.
+     * Safe to call multiple times — subsequent calls return the same promise.
+     */
+    shutdown() {
+        if (this.shutdownPromise)
+            return this.shutdownPromise;
+        this.shutdownPromise = this.doShutdown();
+        return this.shutdownPromise;
+    }
+    async doShutdown() {
+        // Drain remaining queue items
+        if (this.queue.length > 0) {
+            await this.drain();
+        }
+        // Terminate the worker
+        if (this.worker) {
+            try {
+                await this.worker.terminate();
+            }
+            catch {
+                // Worker may already be gone
+            }
+            this.worker = null;
+        }
+        this.callbacks.clear();
+    }
+}
+/** Module-level singleton. */
+let _instance = null;
+/**
+ * Get or create the shared EmbeddingQueue singleton.
+ *
+ * Registers a process `exit` handler on first call to flush and
+ * terminate the worker thread cleanly.
+ *
+ * @returns The shared EmbeddingQueue instance.
+ */
+export function getEmbeddingQueue() {
+    if (!_instance) {
+        _instance = new EmbeddingQueue();
+        // Best-effort flush on process exit (synchronous handlers only get ~50ms)
+        process.on('exit', () => {
+            _instance?.shutdown().catch(() => {
+                // exit handler — cannot await
+            });
+        });
+        // For SIGTERM/SIGINT give the queue time to flush
+        const gracefulShutdown = () => {
+            if (_instance) {
+                _instance
+                    .shutdown()
+                    .catch(() => { })
+                    .finally(() => process.exit(0));
+            }
+            else {
+                process.exit(0);
+            }
+        };
+        process.once('SIGTERM', gracefulShutdown);
+        process.once('SIGINT', gracefulShutdown);
+    }
+    return _instance;
+}
+/**
+ * Reset the singleton (for testing only).
+ * Shuts down the existing queue before clearing the reference.
+ *
+ * @internal
+ */
+export async function resetEmbeddingQueue() {
+    if (_instance) {
+        await _instance.shutdown();
+        _instance = null;
+    }
+}
+//# sourceMappingURL=embedding-queue.js.map

package/dist/memory/embedding-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-queue.js","sourceRoot":"","sources":["../../src/memory/embedding-queue.ts"],"names":[],"mappings":"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"}

package/dist/memory/embedding-worker.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Embedding Worker Thread Script
+ *
+ * Runs inside a `worker_threads.Worker` to perform embedding generation
+ * off the main thread. Receives messages with text to embed, calls
+ * LocalEmbeddingProvider, and sends results back via parentPort.
+ *
+ * Message protocol:
+ *   Inbound:  { id: string; text: string }
+ *   Outbound: { id: string; embedding: number[] } on success
+ *             { id: string; error: string }       on failure
+ *
+ * @epic T134
+ * @task T137
+ * @why Prevent @xenova/transformers model inference from blocking the main thread
+ * @what Worker thread script for async embedding generation
+ */
+export {};
+//# sourceMappingURL=embedding-worker.d.ts.map

package/dist/memory/embedding-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-worker.d.ts","sourceRoot":"","sources":["../../src/memory/embedding-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG"}

package/dist/memory/embedding-worker.js

@@ -0,0 +1,58 @@
+/**
+ * Embedding Worker Thread Script
+ *
+ * Runs inside a `worker_threads.Worker` to perform embedding generation
+ * off the main thread. Receives messages with text to embed, calls
+ * LocalEmbeddingProvider, and sends results back via parentPort.
+ *
+ * Message protocol:
+ *   Inbound:  { id: string; text: string }
+ *   Outbound: { id: string; embedding: number[] } on success
+ *             { id: string; error: string }       on failure
+ *
+ * @epic T134
+ * @task T137
+ * @why Prevent @xenova/transformers model inference from blocking the main thread
+ * @what Worker thread script for async embedding generation
+ */
+import { parentPort } from 'node:worker_threads';
+if (!parentPort) {
+    throw new Error('embedding-worker.ts must be run as a worker thread');
+}
+const port = parentPort;
+/**
+ * Handle a single embedding request from the queue manager.
+ * Imports LocalEmbeddingProvider lazily so the model loads once
+ * per worker lifetime.
+ */
+async function handleRequest(req) {
+    try {
+        const { getLocalEmbeddingProvider } = await import('./embedding-local.js');
+        const provider = getLocalEmbeddingProvider();
+        const vector = await provider.embed(req.text);
+        // Transfer as plain number[] — structured clone handles Float32Array
+        const response = {
+            id: req.id,
+            embedding: Array.from(vector),
+        };
+        port.postMessage(response);
+    }
+    catch (err) {
+        const response = {
+            id: req.id,
+            error: err instanceof Error ? err.message : String(err),
+        };
+        port.postMessage(response);
+    }
+}
+port.on('message', (req) => {
+    handleRequest(req).catch((err) => {
+        // Catch any unhandled rejection in handleRequest itself
+        const response = {
+            id: req.id,
+            error: err instanceof Error ? err.message : String(err),
+        };
+        port.postMessage(response);
+    });
+});
+//# sourceMappingURL=embedding-worker.js.map

package/dist/memory/embedding-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-worker.js","sourceRoot":"","sources":["../../src/memory/embedding-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAoBjD,IAAI,CAAC,UAAU,EAAE,CAAC;IAChB,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,IAAI,GAAG,UAAU,CAAC;AAExB;;;;GAIG;AACH,KAAK,UAAU,aAAa,CAAC,GAAkB;IAC7C,IAAI,CAAC;QACH,MAAM,EAAE,yBAAyB,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;QAC3E,MAAM,QAAQ,GAAG,yBAAyB,EAAE,CAAC;QAC7C,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC9C,qEAAqE;QACrE,MAAM,QAAQ,GAAkB;YAC9B,EAAE,EAAE,GAAG,CAAC,EAAE;YACV,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC;SAC9B,CAAC;QACF,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,QAAQ,GAAgB;YAC5B,EAAE,EAAE,GAAG,CAAC,EAAE;YACV,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACxD,CAAC;QACF,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC7B,CAAC;AACH,CAAC;AAED,IAAI,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,GAAkB,EAAE,EAAE;IACxC,aAAa,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QAC/B,wDAAwD;QACxD,MAAM,QAAQ,GAAgB;YAC5B,EAAE,EAAE,GAAG,CAAC,EAAE;YACV,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACxD,CAAC;QACF,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}