discoclaw 1.1.6 → 1.2.1

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/README.md

@@ -77,6 +77,14 @@ Voice is **off by default**. Enable with `DISCOCLAW_VOICE_ENABLED=1` plus API ke
 
 Full setup guide: [docs/voice.md](docs/voice.md)
 
+## Self-management — the bot maintains itself
+
+- **Self-update** — `!update` checks for new npm versions; `!update apply` downloads, installs, and restarts without leaving Discord
+- **Health checks** — `!health`, `!doctor`, `!status` for diagnostics
+- **Secret management** — `!secret` manages `.env` entries from DMs
+- **Model switching** — `!models` swaps AI models per role at runtime
+- **Restart** — `!restart` restarts the service on demand
+
 ## How it works
 
 DiscoClaw orchestrates the flow between Discord and AI runtimes (Claude Code by default, with `gemini-api`, OpenAI, Codex, and OpenRouter adapters available via `PRIMARY_RUNTIME`). For 1.0, `Claude CLI` on a source checkout is the explicitly supported default path, and `Codex CLI` on a source checkout is the explicitly supported secondary path. See [docs/audit/provider-auth-1.0-matrix.md](docs/audit/provider-auth-1.0-matrix.md) for the full consolidated matrix. The OpenAI-compatible and OpenRouter adapters can expose optional tool use when `OPENAI_COMPAT_TOOLS_ENABLED=1` is set, but OpenRouter support claims stop at the narrower audited boundary described below. It doesn't contain intelligence itself — it decides *when* to call the AI, *what context* to give it, and *what to do* with the output. When you send a message, the orchestrator:
@@ -406,15 +414,22 @@ Do not treat `codex --version`, `OPENAI_API_KEY` presence, `pnpm preflight*`, or
 
 ## Updating
 
-**Global install:**
+DiscoClaw can check for and apply updates from inside Discord — no SSH or terminal needed.
+
+| Command | Description |
+|---------|-------------|
+| `!update` | Check if a newer version is available on npm |
+| `!update apply` | Download the update, reinstall, and restart the service |
+| `!update audit` | Show npm-managed runtime audit details |
+| `!update help` | Show usage |
 
-If DiscoClaw is running, update from Discord:
+**Global install (from Discord):**
 
 ```
 !update apply
 ```
 
-Or from the command line:
+**Global install (from the command line):**
 
 ```bash
 npm update -g discoclaw

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/dist/discord/tool-aware-queue.js

@@ -72,7 +72,10 @@ export class ToolAwareQueue {
         switch (this.state) {
             case 'idle':
             case 'buffering_text':
-                // Discard buffered narration text.
+                // Flush buffered narration text before switching to tool_active.
+                if (this.buffer) {
+                    this.emit({ type: 'stream_text', text: this.buffer });
+                }
                 this.buffer = '';
                 this.state = 'tool_active';
                 this.emit({ type: 'show_activity', label });

package/dist/discord/tool-aware-queue.test.js

@@ -96,15 +96,16 @@ describe('ToolAwareQueue', () => {
         expect(actions[1]).toEqual({ type: 'stream_text', text: '!' });
         taq.dispose();
     });
-    it('text then tool: narration discarded, activity shown', () => {
+    it('text then tool: narration flushed as stream_text, then activity shown', () => {
         const { actions, emit } = collect();
         const taq = new ToolAwareQueue(emit, { flushDelayMs: 800, postToolDelayMs: 500 });
         taq.handleEvent({ type: 'text_delta', text: 'Let me read the file...' });
         taq.handleEvent({ type: 'tool_start', name: 'Read', input: { file_path: '/tmp/foo.ts' } });
-        // Narration was discarded, only show_activity emitted.
-        expect(actions).toHaveLength(1);
-        expect(actions[0]).toMatchObject({ type: 'show_activity' });
-        expect(actions[0].label).toContain('Reading');
+        // Narration flushed as stream_text, then show_activity emitted.
+        expect(actions).toHaveLength(2);
+        expect(actions[0]).toEqual({ type: 'stream_text', text: 'Let me read the file...' });
+        expect(actions[1]).toMatchObject({ type: 'show_activity' });
+        expect(actions[1].label).toContain('Reading');
         taq.dispose();
     });
     it('tool then text: activity during tool, text streams after', () => {
@@ -176,7 +177,7 @@ describe('ToolAwareQueue', () => {
         vi.advanceTimersByTime(5000);
         expect(actions).toHaveLength(0);
     });
-    it('post-tool delay prevents flashing narration between tools', () => {
+    it('inter-tool narration is flushed before second tool activity', () => {
         const { actions, emit } = collect();
         const taq = new ToolAwareQueue(emit, { flushDelayMs: 800, postToolDelayMs: 500 });
         taq.handleEvent({ type: 'tool_start', name: 'Read' });
@@ -186,8 +187,12 @@ describe('ToolAwareQueue', () => {
         // Before post-tool delay fires, second tool starts.
         vi.advanceTimersByTime(200);
         taq.handleEvent({ type: 'tool_start', name: 'Bash' });
-        // The narration text should not have been streamed.
-        expect(actions.filter((a) => a.type === 'stream_text')).toHaveLength(0);
+        // Inter-tool narration flushed as stream_text before second tool.
+        expect(actions.filter((a) => a.type === 'stream_text')).toHaveLength(1);
+        expect(actions.filter((a) => a.type === 'stream_text')[0]).toEqual({
+            type: 'stream_text',
+            text: 'Now let me run...',
+        });
         // Two show_activity actions.
         expect(actions.filter((a) => a.type === 'show_activity')).toHaveLength(2);
         taq.dispose();

package/package.json

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