discoclaw 0.1.0

package/dist/discord/user-turn-to-durable.js

@@ -0,0 +1,111 @@
+import { loadDurableMemory, saveDurableMemory, addItem } from './durable-memory.js';
+import { durableWriteQueue } from './durable-write-queue.js';
+import { extractFirstJsonValue } from './json-extract.js';
+const VALID_KINDS = new Set([
+    'preference', 'fact', 'project', 'constraint', 'person', 'tool', 'workflow',
+]);
+export const EXTRACTION_PROMPT = `You are a long-term memory extractor. Given a user message, decide whether it contains anything worth remembering permanently, and if so extract up to 3 items.
+
+## One-month test
+Only extract something if it would still be useful to know in a month. Most messages contain nothing worth storing — return [] liberally.
+
+## KEEP — stable, lasting facts
+- User preferences and opinions (editor, language, style, communication preferences)
+- Personal facts (name, location, timezone, family, pets, hobbies, job title)
+- Stable project context (project names, tech stacks, team structure, architecture decisions)
+- Cross-session conventions and workflows (branching strategy, deploy process, naming conventions)
+- Relationships between people, teams, or projects
+
+## EXCLUDE — transient task state
+- Current bugs being fixed, PRs in flight, features being built right now
+- One-time setup steps or installation instructions
+- Transient decisions that will resolve within days
+- Specific code line numbers, file paths, commit hashes, or error messages
+- Anything that reads like a status update rather than a lasting fact
+- In-progress test gaps or TODO items
+- Summaries of what was just done in the current session
+
+## Output format
+Return a JSON array of objects with "kind" and "text" fields. Valid kinds: preference, fact, project, constraint, person, tool, workflow. Max 3 items. If nothing passes the one-month test, return [].
+
+Only extract information the user explicitly stated.
+
+User message:
+{userMessage}
+
+JSON array:`;
+const MAX_ITEMS_PER_EXTRACTION = 3;
+export async function extractFromUserTurn(runtime, opts) {
+    const prompt = EXTRACTION_PROMPT.replace('{userMessage}', opts.userMessageText);
+    let finalText = '';
+    let deltaText = '';
+    for await (const evt of runtime.invoke({
+        prompt,
+        model: opts.model,
+        cwd: opts.cwd,
+        tools: [],
+        timeoutMs: opts.timeoutMs ?? 15_000,
+    })) {
+        if (evt.type === 'text_final') {
+            finalText = evt.text;
+        }
+        else if (evt.type === 'text_delta') {
+            deltaText += evt.text;
+        }
+        else if (evt.type === 'error') {
+            return [];
+        }
+    }
+    const raw = (finalText || deltaText).trim();
+    return parseExtractionResult(raw);
+}
+export function parseExtractionResult(raw) {
+    try {
+        const jsonArray = extractFirstJsonValue(raw, { arrayOnly: true });
+        if (!jsonArray)
+            return [];
+        const parsed = JSON.parse(jsonArray);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed
+            .filter((item) => item &&
+            typeof item === 'object' &&
+            typeof item.text === 'string' &&
+            item.text.trim().length > 0 &&
+            VALID_KINDS.has(item.kind))
+            .map((item) => ({ kind: item.kind, text: item.text.trim() }))
+            .slice(0, MAX_ITEMS_PER_EXTRACTION);
+    }
+    catch {
+        return [];
+    }
+}
+export async function applyUserTurnToDurable(opts) {
+    const items = await extractFromUserTurn(opts.runtime, {
+        userMessageText: opts.userMessageText,
+        model: opts.model,
+        cwd: opts.cwd,
+    });
+    if (items.length === 0)
+        return;
+    await durableWriteQueue.run(opts.userId, async () => {
+        const store = (await loadDurableMemory(opts.durableDataDir, opts.userId)) ?? {
+            version: 1,
+            updatedAt: 0,
+            items: [],
+        };
+        for (const item of items) {
+            const source = { type: 'summary' };
+            if (opts.channelId)
+                source.channelId = opts.channelId;
+            if (opts.messageId)
+                source.messageId = opts.messageId;
+            if (opts.guildId)
+                source.guildId = opts.guildId;
+            if (opts.channelName)
+                source.channelName = opts.channelName;
+            addItem(store, item.text, { ...source }, opts.durableMaxItems, item.kind);
+        }
+        await saveDurableMemory(opts.durableDataDir, opts.userId, store);
+    });
+}

package/dist/discord/user-turn-to-durable.test.js

@@ -0,0 +1,273 @@
+import { describe, expect, it } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { parseExtractionResult, applyUserTurnToDurable, EXTRACTION_PROMPT } from './user-turn-to-durable.js';
+import { loadDurableMemory, addItem, saveDurableMemory } from './durable-memory.js';
+async function makeTmpDir() {
+    return fs.mkdtemp(path.join(os.tmpdir(), 'user-turn-durable-test-'));
+}
+function makeRuntime(responseText) {
+    return {
+        invoke: async function* () {
+            yield { type: 'text_final', text: responseText };
+        },
+    };
+}
+describe('parseExtractionResult', () => {
+    it('parses valid JSON array', () => {
+        const raw = '[{"kind":"fact","text":"Likes TypeScript"},{"kind":"preference","text":"Prefers dark mode"}]';
+        const items = parseExtractionResult(raw);
+        expect(items).toEqual([
+            { kind: 'fact', text: 'Likes TypeScript' },
+            { kind: 'preference', text: 'Prefers dark mode' },
+        ]);
+    });
+    it('returns empty on malformed JSON', () => {
+        expect(parseExtractionResult('not json at all')).toEqual([]);
+        expect(parseExtractionResult('{}')).toEqual([]);
+    });
+    it('filters out invalid kinds', () => {
+        const raw = '[{"kind":"invalid","text":"should be dropped"},{"kind":"fact","text":"kept"}]';
+        const items = parseExtractionResult(raw);
+        expect(items).toEqual([{ kind: 'fact', text: 'kept' }]);
+    });
+    it('filters out items with empty text', () => {
+        const raw = '[{"kind":"fact","text":""},{"kind":"fact","text":"  "},{"kind":"fact","text":"real"}]';
+        const items = parseExtractionResult(raw);
+        expect(items).toEqual([{ kind: 'fact', text: 'real' }]);
+    });
+    it('enforces cap of 3 items even if model returns more', () => {
+        const many = Array.from({ length: 10 }, (_, i) => ({ kind: 'fact', text: `Item ${i}` }));
+        const raw = JSON.stringify(many);
+        const items = parseExtractionResult(raw);
+        expect(items).toHaveLength(3);
+    });
+    it('handles JSON inside markdown fences', () => {
+        const raw = '```json\n[{"kind":"fact","text":"Extracted"}]\n```';
+        const items = parseExtractionResult(raw);
+        expect(items).toEqual([{ kind: 'fact', text: 'Extracted' }]);
+    });
+    it('returns empty array response', () => {
+        expect(parseExtractionResult('[]')).toEqual([]);
+    });
+    it('returns empty for non-array JSON object', () => {
+        expect(parseExtractionResult('{"key":"val"}')).toEqual([]);
+    });
+    it('extracts first array when trailing brackets exist', () => {
+        const raw = '[{"kind":"fact","text":"ok"}] some text [more stuff]';
+        const items = parseExtractionResult(raw);
+        expect(items).toEqual([{ kind: 'fact', text: 'ok' }]);
+    });
+    it('skips non-array json values and finds the first valid array', () => {
+        const raw = '{"note":"not an array"}\n[{"kind":"fact","text":"kept"}]';
+        const items = parseExtractionResult(raw);
+        expect(items).toEqual([{ kind: 'fact', text: 'kept' }]);
+    });
+    it('parses array from json fence with surrounding prose', () => {
+        const raw = 'Result below:\n```json\n[{"kind":"workflow","text":"Use squash merges"}]\n```\nThanks!';
+        const items = parseExtractionResult(raw);
+        expect(items).toEqual([{ kind: 'workflow', text: 'Use squash merges' }]);
+    });
+});
+describe('EXTRACTION_PROMPT', () => {
+    it('is exported', () => {
+        expect(typeof EXTRACTION_PROMPT).toBe('string');
+        expect(EXTRACTION_PROMPT.length).toBeGreaterThan(0);
+    });
+    it('contains the one-month test heuristic', () => {
+        expect(EXTRACTION_PROMPT).toContain('one-month test');
+        expect(EXTRACTION_PROMPT).toContain('still be useful to know in a month');
+    });
+    it('includes keep criteria for preferences and personal facts', () => {
+        expect(EXTRACTION_PROMPT).toContain('preferences');
+        expect(EXTRACTION_PROMPT).toContain('Personal facts');
+        expect(EXTRACTION_PROMPT).toContain('Stable project context');
+        expect(EXTRACTION_PROMPT).toContain('Cross-session conventions');
+    });
+    it('includes exclude criteria for transient task state', () => {
+        expect(EXTRACTION_PROMPT).toContain('bugs being fixed');
+        expect(EXTRACTION_PROMPT).toContain('PRs in flight');
+        expect(EXTRACTION_PROMPT).toContain('One-time setup steps');
+        expect(EXTRACTION_PROMPT).toContain('commit hashes');
+        expect(EXTRACTION_PROMPT).toContain('status update');
+    });
+    it('preserves the JSON output contract', () => {
+        expect(EXTRACTION_PROMPT).toContain('"kind"');
+        expect(EXTRACTION_PROMPT).toContain('"text"');
+        expect(EXTRACTION_PROMPT).toContain('preference, fact, project, constraint, person, tool, workflow');
+        expect(EXTRACTION_PROMPT).toContain('Max 3 items');
+        expect(EXTRACTION_PROMPT).toContain('return []');
+    });
+    it('contains the {userMessage} placeholder', () => {
+        expect(EXTRACTION_PROMPT).toContain('{userMessage}');
+    });
+});
+describe('applyUserTurnToDurable', () => {
+    it('writes extracted items to durable store', async () => {
+        const dir = await makeTmpDir();
+        const runtime = makeRuntime('[{"kind":"fact","text":"Likes cats"}]');
+        await applyUserTurnToDurable({
+            runtime,
+            userMessageText: 'I love cats',
+            userId: '42',
+            durableDataDir: dir,
+            durableMaxItems: 200,
+            model: 'haiku',
+            cwd: '/tmp',
+        });
+        const store = await loadDurableMemory(dir, '42');
+        expect(store).not.toBeNull();
+        expect(store.items).toHaveLength(1);
+        expect(store.items[0].text).toBe('Likes cats');
+        expect(store.items[0].kind).toBe('fact');
+        expect(store.items[0].source.type).toBe('summary');
+    });
+    it('does not duplicate existing items', async () => {
+        const dir = await makeTmpDir();
+        // Pre-seed a store with an existing item.
+        const existing = { version: 1, updatedAt: 0, items: [] };
+        addItem(existing, 'Likes cats', { type: 'summary' }, 200, 'fact');
+        await saveDurableMemory(dir, '42', existing);
+        const runtime = makeRuntime('[{"kind":"fact","text":"Likes cats"}]');
+        await applyUserTurnToDurable({
+            runtime,
+            userMessageText: 'I love cats',
+            userId: '42',
+            durableDataDir: dir,
+            durableMaxItems: 200,
+            model: 'haiku',
+            cwd: '/tmp',
+        });
+        const store = await loadDurableMemory(dir, '42');
+        expect(store.items).toHaveLength(1); // Still just 1, not 2.
+    });
+    it('respects maxItems cap', async () => {
+        const dir = await makeTmpDir();
+        // Pre-seed store at cap.
+        const existing = { version: 1, updatedAt: 0, items: [] };
+        addItem(existing, 'Item 1', { type: 'manual' }, 2, 'fact');
+        addItem(existing, 'Item 2', { type: 'manual' }, 2, 'fact');
+        await saveDurableMemory(dir, '42', existing);
+        const runtime = makeRuntime('[{"kind":"preference","text":"New preference"}]');
+        await applyUserTurnToDurable({
+            runtime,
+            userMessageText: 'Some message',
+            userId: '42',
+            durableDataDir: dir,
+            durableMaxItems: 2,
+            model: 'haiku',
+            cwd: '/tmp',
+        });
+        const store = await loadDurableMemory(dir, '42');
+        expect(store.items).toHaveLength(2); // Cap enforced.
+        expect(store.items.some((it) => it.text === 'New preference')).toBe(true);
+    });
+    it('handles runtime returning empty array gracefully', async () => {
+        const dir = await makeTmpDir();
+        const runtime = makeRuntime('[]');
+        await applyUserTurnToDurable({
+            runtime,
+            userMessageText: 'Nothing notable here',
+            userId: '42',
+            durableDataDir: dir,
+            durableMaxItems: 200,
+            model: 'haiku',
+            cwd: '/tmp',
+        });
+        // No file should be created — nothing to write.
+        const store = await loadDurableMemory(dir, '42');
+        expect(store).toBeNull();
+    });
+    it('concurrent calls for same user serialize correctly', async () => {
+        const dir = await makeTmpDir();
+        // Each invocation extracts a different fact.
+        let callCount = 0;
+        const runtime = {
+            invoke: async function* () {
+                const n = ++callCount;
+                yield { type: 'text_final', text: `[{"kind":"fact","text":"Fact ${n}"}]` };
+            },
+        };
+        await Promise.all([
+            applyUserTurnToDurable({
+                runtime, userMessageText: 'msg1', userId: '42',
+                durableDataDir: dir, durableMaxItems: 200, model: 'haiku', cwd: '/tmp',
+            }),
+            applyUserTurnToDurable({
+                runtime, userMessageText: 'msg2', userId: '42',
+                durableDataDir: dir, durableMaxItems: 200, model: 'haiku', cwd: '/tmp',
+            }),
+            applyUserTurnToDurable({
+                runtime, userMessageText: 'msg3', userId: '42',
+                durableDataDir: dir, durableMaxItems: 200, model: 'haiku', cwd: '/tmp',
+            }),
+        ]);
+        const store = await loadDurableMemory(dir, '42');
+        expect(store).not.toBeNull();
+        // All 3 facts should be stored (no overwrites from races).
+        expect(store.items).toHaveLength(3);
+    });
+    it('persists Discord metadata in source when provided', async () => {
+        const dir = await makeTmpDir();
+        const runtime = makeRuntime('[{"kind":"fact","text":"Likes cats"}]');
+        await applyUserTurnToDurable({
+            runtime,
+            userMessageText: 'I love cats',
+            userId: '42',
+            durableDataDir: dir,
+            durableMaxItems: 200,
+            model: 'haiku',
+            cwd: '/tmp',
+            channelId: 'ch1',
+            messageId: 'msg1',
+            guildId: 'g1',
+            channelName: 'dev',
+        });
+        const store = await loadDurableMemory(dir, '42');
+        expect(store).not.toBeNull();
+        expect(store.items[0].source).toEqual({
+            type: 'summary',
+            channelId: 'ch1',
+            messageId: 'msg1',
+            guildId: 'g1',
+            channelName: 'dev',
+        });
+    });
+    it('omits Discord metadata when not provided', async () => {
+        const dir = await makeTmpDir();
+        const runtime = makeRuntime('[{"kind":"fact","text":"Likes cats"}]');
+        await applyUserTurnToDurable({
+            runtime,
+            userMessageText: 'I love cats',
+            userId: '42',
+            durableDataDir: dir,
+            durableMaxItems: 200,
+            model: 'haiku',
+            cwd: '/tmp',
+        });
+        const store = await loadDurableMemory(dir, '42');
+        expect(store).not.toBeNull();
+        expect(store.items[0].source).toEqual({ type: 'summary' });
+    });
+    it('handles runtime error gracefully (no crash)', async () => {
+        const dir = await makeTmpDir();
+        const runtime = {
+            invoke: async function* () {
+                yield { type: 'error', message: 'API error' };
+            },
+        };
+        // Should not throw.
+        await applyUserTurnToDurable({
+            runtime,
+            userMessageText: 'Something',
+            userId: '42',
+            durableDataDir: dir,
+            durableMaxItems: 200,
+            model: 'haiku',
+            cwd: '/tmp',
+        });
+        const store = await loadDurableMemory(dir, '42');
+        expect(store).toBeNull();
+    });
+});