discoclaw 1.1.6 → 1.2.0

package/.env.example.full

@@ -397,6 +397,15 @@ DISCOCLAW_DISCORD_ACTIONS_DEFER=1
 # Comma-separated channel IDs to restrict cold-storage ingestion and retrieval.
 # When set, only messages from these channels are stored/searched. Empty = all channels.
 #COLD_STORAGE_CHANNEL_FILTER=
+# HyDE (Hypothetical Document Embedding) — generate a hypothetical answer before
+# embedding, improving semantic search when queries are short or use different
+# vocabulary than stored content. Only the vector leg is affected; FTS5 keyword
+# search still uses the raw query. Enabled by default; set to 0 to disable.
+#DISCOCLAW_COLD_STORAGE_HYDE_ENABLED=1
+# Model used to generate the hypothetical document. Any chat-capable model string
+# accepted by the AI runtime (e.g. "anthropic/claude-sonnet-4-5"). Falls back to a
+# sensible default when unset.
+#COLD_STORAGE_HYDE_MODEL=
 
 # ----------------------------------------------------------
 # Bot identity

package/dist/cold-storage/hyde.js

@@ -0,0 +1,50 @@
+const HYDE_SYSTEM_PROMPT = 'You are a retrieval assistant. Given a query, write a short hypothetical passage ' +
+    'that directly answers it as if the passage were already stored in a knowledge base. ' +
+    'Do not include preamble or meta-commentary — output only the passage.';
+const TIMEOUT_MS = 15_000;
+/**
+ * Generate a hypothetical answer to `query` via an OpenAI-compatible chat
+ * completions endpoint. Returns the generated text, or `null` on any failure.
+ */
+export async function generateHypotheticalAnswer(opts) {
+    const { apiKey, baseUrl, model, query, log } = opts;
+    const url = `${baseUrl.replace(/\/+$/, '')}/chat/completions`;
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                model,
+                messages: [
+                    { role: 'system', content: HYDE_SYSTEM_PROMPT },
+                    { role: 'user', content: query },
+                ],
+                max_tokens: 256,
+                temperature: 0.7,
+            }),
+            signal: controller.signal,
+        });
+        clearTimeout(timer);
+        if (!response.ok) {
+            const detail = await response.text().catch(() => '');
+            log?.warn({ status: response.status, detail }, 'hyde: chat completions API error, falling back to raw query');
+            return null;
+        }
+        const json = (await response.json());
+        const text = json.choices?.[0]?.message?.content?.trim() ?? '';
+        if (text.length === 0) {
+            log?.warn({}, 'hyde: empty response from model, falling back to raw query');
+            return null;
+        }
+        return text;
+    }
+    catch (err) {
+        log?.warn({ err }, 'hyde: generation failed, falling back to raw query');
+        return null;
+    }
+}

package/dist/cold-storage/hyde.test.js

@@ -0,0 +1,84 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { generateHypotheticalAnswer } from './hyde.js';
+function makeChatResponse(content) {
+    return new Response(JSON.stringify({
+        choices: [{ message: { content } }],
+    }), { status: 200, statusText: 'OK', headers: { 'Content-Type': 'application/json' } });
+}
+function defaultOpts(overrides = {}) {
+    return {
+        apiKey: 'test-key',
+        baseUrl: 'https://api.openai.com/v1',
+        model: 'gpt-4o-mini',
+        query: 'What is the capital of France?',
+        ...overrides,
+    };
+}
+describe('generateHypotheticalAnswer', () => {
+    const originalFetch = globalThis.fetch;
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+    });
+    it('returns generated text on success', async () => {
+        globalThis.fetch = vi.fn().mockResolvedValue(makeChatResponse('Paris is the capital of France.'));
+        const result = await generateHypotheticalAnswer(defaultOpts());
+        expect(result).toBe('Paris is the capital of France.');
+        expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+        const [url, init] = globalThis.fetch.mock.calls[0];
+        expect(url).toBe('https://api.openai.com/v1/chat/completions');
+        const body = JSON.parse(init.body);
+        expect(body.model).toBe('gpt-4o-mini');
+        expect(body.messages).toHaveLength(2);
+        expect(body.messages[1].content).toBe('What is the capital of France?');
+    });
+    it('returns null on API error', async () => {
+        globalThis.fetch = vi.fn().mockResolvedValue(new Response('Unauthorized', { status: 401, statusText: 'Unauthorized' }));
+        const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+        const result = await generateHypotheticalAnswer(defaultOpts({ log }));
+        expect(result).toBeNull();
+        expect(log.warn).toHaveBeenCalledTimes(1);
+    });
+    it('returns null on timeout', async () => {
+        globalThis.fetch = vi.fn().mockImplementation((_url, init) => new Promise((_resolve, reject) => {
+            init.signal?.addEventListener('abort', () => {
+                reject(new DOMException('The operation was aborted.', 'AbortError'));
+            });
+        }));
+        // Speed up the test by mocking timers
+        vi.useFakeTimers();
+        const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+        const promise = generateHypotheticalAnswer(defaultOpts({ log }));
+        await vi.advanceTimersByTimeAsync(16_000);
+        const result = await promise;
+        expect(result).toBeNull();
+        expect(log.warn).toHaveBeenCalledTimes(1);
+        vi.useRealTimers();
+    });
+    it('returns null on empty response', async () => {
+        globalThis.fetch = vi.fn().mockResolvedValue(makeChatResponse(''));
+        const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+        const result = await generateHypotheticalAnswer(defaultOpts({ log }));
+        expect(result).toBeNull();
+        expect(log.warn).toHaveBeenCalledTimes(1);
+    });
+    it('returns null on whitespace-only response', async () => {
+        globalThis.fetch = vi.fn().mockResolvedValue(makeChatResponse('   \n\t  '));
+        const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+        const result = await generateHypotheticalAnswer(defaultOpts({ log }));
+        expect(result).toBeNull();
+        expect(log.warn).toHaveBeenCalledTimes(1);
+    });
+    it('strips trailing slashes from baseUrl', async () => {
+        globalThis.fetch = vi.fn().mockResolvedValue(makeChatResponse('Some answer'));
+        await generateHypotheticalAnswer(defaultOpts({ baseUrl: 'https://api.openai.com/v1/' }));
+        const [url] = globalThis.fetch.mock.calls[0];
+        expect(url).toBe('https://api.openai.com/v1/chat/completions');
+    });
+    it('returns null on network error', async () => {
+        globalThis.fetch = vi.fn().mockRejectedValue(new Error('ECONNREFUSED'));
+        const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+        const result = await generateHypotheticalAnswer(defaultOpts({ log }));
+        expect(result).toBeNull();
+        expect(log.warn).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/config.js

@@ -787,6 +787,8 @@ export function parseConfig(env) {
             })(),
             coldStorageInjectMaxChars: parsePositiveInt(env, 'DISCOCLAW_COLD_STORAGE_INJECT_MAX_CHARS', 1500),
             coldStorageSearchLimit: parsePositiveInt(env, 'DISCOCLAW_COLD_STORAGE_SEARCH_LIMIT', 10),
+            coldStorageHydeEnabled: parseBoolean(env, 'DISCOCLAW_COLD_STORAGE_HYDE_ENABLED', true),
+            coldStorageHydeModel: parseTrimmedString(env, 'COLD_STORAGE_HYDE_MODEL'),
             summaryToDurableEnabled: parseBoolean(env, 'DISCOCLAW_SUMMARY_TO_DURABLE_ENABLED', true),
             shortTermMemoryEnabled: parseBoolean(env, 'DISCOCLAW_SHORTTERM_MEMORY_ENABLED', true),
             shortTermMaxEntries: parsePositiveInt(env, 'DISCOCLAW_SHORTTERM_MAX_ENTRIES', 20),

package/dist/discord/prompt-common.js

@@ -334,15 +334,6 @@ export async function buildDurableMemorySection(opts) {
         return '';
     }
 }
-// ---------------------------------------------------------------------------
-// Cold-storage prompt section
-// ---------------------------------------------------------------------------
-/**
- * Search cold storage and build a prompt section from the results.
- *
- * Returns an empty string when cold storage is disabled, unavailable,
- * or no results match the query. Never throws.
- */
 export async function buildColdStoragePromptSection(opts) {
     if (!opts.enabled || !opts.subsystem || !opts.query)
         return '';
@@ -352,15 +343,33 @@ export async function buildColdStoragePromptSection(opts) {
             return '';
     }
     try {
-        // Generate embedding for the query (3-second timeout — fail open on slow APIs)
+        // HyDE step: generate a hypothetical answer to embed instead of the raw query.
+        // Falls back to raw query if generator is absent, returns null, or times out.
+        let textToEmbed = opts.query;
+        if (opts.hydeGenerator) {
+            const HYDE_TIMEOUT_MS = 3_000;
+            try {
+                const hydeResult = await Promise.race([
+                    opts.hydeGenerator(opts.query),
+                    new Promise((resolve) => setTimeout(() => resolve(null), HYDE_TIMEOUT_MS)),
+                ]);
+                if (hydeResult != null) {
+                    textToEmbed = hydeResult;
+                }
+            }
+            catch (err) {
+                opts.log?.warn({ err }, 'cold-storage HyDE generation failed, falling back to raw query');
+            }
+        }
+        // Generate embedding (3-second timeout — fail open on slow APIs)
         const EMBED_TIMEOUT_MS = 3_000;
         const embeddings = await Promise.race([
-            opts.subsystem.embeddings.embed([opts.query]),
+            opts.subsystem.embeddings.embed([textToEmbed]),
             new Promise((_, reject) => setTimeout(() => reject(new Error('cold-storage embedding timeout')), EMBED_TIMEOUT_MS)),
         ]);
         if (embeddings.length === 0)
             return '';
-        // Search with both vector and FTS
+        // Search with both vector and FTS — raw query drives keyword leg unchanged
         const results = opts.subsystem.store.search({
             embedding: embeddings[0],
             query: opts.query,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discoclaw",
-  "version": "1.1.6",
+  "version": "1.2.0",
   "description": "Personal AI orchestrator that turns Discord into a persistent workspace",
   "license": "MIT",
   "repository": {