@hanhnd/agent-kit 1.0.39 → 1.0.40

package/dist/services/memory/indexer.test.js

@@ -23,6 +23,28 @@ class FailEmbedder {
         return Promise.resolve();
     }
 }
+class TrackingEmbedder {
+    failForText;
+    active = 0;
+    maxActive = 0;
+    constructor(failForText = undefined) {
+        this.failForText = failForText;
+    }
+    async embed(texts) {
+        const failForText = this.failForText;
+        if (failForText && texts.some((text) => text.includes(failForText))) {
+            throw new Error('targeted embed failure');
+        }
+        this.active++;
+        this.maxActive = Math.max(this.maxActive, this.active);
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        this.active--;
+        return texts.map(() => new Float32Array(384).fill(0.05));
+    }
+    initialize() {
+        return Promise.resolve();
+    }
+}
 function makeConfig(wikiDir) {
     return {
         enabled: true,
@@ -378,6 +400,116 @@ describe('MemoryIndexer', () => {
             fs.rmSync(testDir, { recursive: true, force: true });
         }
     });
+    test('indexDirectory prepares changed files with bounded parallelism', async () => {
+        const testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'parallel-index-'));
+        const testCfg = makeConfig(path.join(testDir, 'wiki'));
+        const testStore = new MemoryStore(path.join(testCfg.wikiDir, 'index.db'), testCfg);
+        const trackingEmbedder = new TrackingEmbedder();
+        const testIndexer = new MemoryIndexer(testStore, trackingEmbedder, testCfg);
+        const compiledDir = path.join(testCfg.wikiDir, 'compiled');
+        try {
+            fs.mkdirSync(compiledDir, { recursive: true });
+            fs.writeFileSync(path.join(compiledDir, 'a.md'), '# A\nparallel alpha content', 'utf8');
+            fs.writeFileSync(path.join(compiledDir, 'b.md'), '# B\nparallel beta content', 'utf8');
+            fs.writeFileSync(path.join(compiledDir, 'c.md'), '# C\nparallel gamma content', 'utf8');
+            const stats = await testIndexer.indexDirectory(compiledDir, {
+                relativeBase: testCfg.wikiDir,
+                fileConcurrency: 2,
+            });
+            assert.ok(stats.indexed >= 3, `Expected at least 3 indexed chunks, got ${stats.indexed}`);
+            assert.equal(trackingEmbedder.maxActive, 2);
+        }
+        finally {
+            testStore.close();
+            fs.rmSync(testDir, { recursive: true, force: true });
+        }
+    });
+    test('indexDirectory serializes store mutations after parallel preparation', async () => {
+        const testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'serialized-writes-'));
+        const testCfg = makeConfig(path.join(testDir, 'wiki'));
+        const compiledDir = path.join(testCfg.wikiDir, 'compiled');
+        const calls = [];
+        let activeMutations = 0;
+        let maxActiveMutations = 0;
+        const fakeStore = {
+            vecAvailable: true,
+            hashesBySource: () => new Set(),
+            indexedSources: () => ['compiled/stale.md'],
+            deleteBySource: (source) => {
+                activeMutations++;
+                maxActiveMutations = Math.max(maxActiveMutations, activeMutations);
+                calls.push(`deleteBySource:${source}`);
+                activeMutations--;
+            },
+            upsert: (chunks) => {
+                activeMutations++;
+                maxActiveMutations = Math.max(maxActiveMutations, activeMutations);
+                calls.push(`upsert:${chunks[0]?.source}`);
+                activeMutations--;
+            },
+            deleteByIds: (ids) => {
+                activeMutations++;
+                maxActiveMutations = Math.max(maxActiveMutations, activeMutations);
+                calls.push(`deleteByIds:${ids.length}`);
+                activeMutations--;
+            },
+        };
+        try {
+            fs.mkdirSync(compiledDir, { recursive: true });
+            fs.writeFileSync(path.join(compiledDir, 'a.md'), '# A\nserialized alpha content', 'utf8');
+            fs.writeFileSync(path.join(compiledDir, 'b.md'), '# B\nserialized beta content', 'utf8');
+            const trackingEmbedder = new TrackingEmbedder();
+            const testIndexer = new MemoryIndexer(fakeStore, trackingEmbedder, testCfg);
+            await testIndexer.indexDirectory(compiledDir, {
+                relativeBase: testCfg.wikiDir,
+                fileConcurrency: 2,
+            });
+            assert.equal(maxActiveMutations, 1);
+            assert.equal(trackingEmbedder.maxActive, 2);
+            assert.deepEqual(calls.slice(0, 1), ['deleteBySource:compiled/stale.md']);
+            assert.ok(calls.filter((call) => call.startsWith('upsert:')).length >= 2);
+        }
+        finally {
+            fs.rmSync(testDir, { recursive: true, force: true });
+        }
+    });
+    test('indexDirectory isolates per-file embedding failure without deleting failed-file chunks', async () => {
+        const testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'failure-isolation-'));
+        const testCfg = makeConfig(path.join(testDir, 'wiki'));
+        const compiledDir = path.join(testCfg.wikiDir, 'compiled');
+        const upsertedSources = [];
+        const deletedIds = [];
+        const fakeStore = {
+            vecAvailable: true,
+            hashesBySource: (source) => (source === 'compiled/bad.md' ? new Set(['bad-old-id']) : new Set()),
+            indexedSources: () => ['compiled/good.md', 'compiled/bad.md'],
+            deleteBySource: () => undefined,
+            upsert: (chunks) => {
+                upsertedSources.push(...chunks.map((chunk) => chunk.source));
+            },
+            deleteByIds: (ids) => {
+                deletedIds.push(...ids);
+            },
+        };
+        try {
+            fs.mkdirSync(compiledDir, { recursive: true });
+            fs.writeFileSync(path.join(compiledDir, 'good.md'), '# Good\nindexable good content', 'utf8');
+            fs.writeFileSync(path.join(compiledDir, 'bad.md'), '# Bad\nexplode this content', 'utf8');
+            const testIndexer = new MemoryIndexer(fakeStore, new TrackingEmbedder('explode'), testCfg);
+            const stats = await testIndexer.indexDirectory(compiledDir, {
+                relativeBase: testCfg.wikiDir,
+                fileConcurrency: 2,
+            });
+            assert.ok(stats.indexed > 0, `Expected good file to be indexed, got ${stats.indexed}`);
+            assert.equal(stats.skipped, 1);
+            assert.ok(upsertedSources.includes('compiled/good.md'));
+            assert.ok(!upsertedSources.includes('compiled/bad.md'));
+            assert.deepEqual(deletedIds, []);
+        }
+        finally {
+            fs.rmSync(testDir, { recursive: true, force: true });
+        }
+    });
     test('deriveSourceType follows documented path conventions', () => {
         assert.equal(deriveSourceType('compiled/provisional/conversation-digests/abc.md'), 'digest');
         assert.equal(deriveSourceType('compiled/concepts/x.md'), 'concept');

package/dist/services/memory/memory.test.js

@@ -45,6 +45,7 @@ function makeIndexerStub(overrides = {}) {
     return {
         search: overrides.search ?? (async () => []),
         save: overrides.save ?? (async () => ({ indexed: 1, deleted: 0, skipped: 0 })),
+        startupIndex: overrides.startupIndex ?? (async () => undefined),
     };
 }
 function makeStoreStub(vecAvailable, overrides = {}) {
@@ -176,6 +177,44 @@ describe('kit_memory_search', () => {
         await tools.get('kit_memory_search')({ query: 'test', top_k: 3 });
         assert.equal(capturedTopK, 3);
     });
+    test('returns a warming note while subsystem warmup has not completed', async () => {
+        const indexer = makeIndexerStub({ search: async () => [] });
+        const store = makeStoreStub(true);
+        const { server, tools } = makeMockServer();
+        registerMemoryTools(server, '/tmp', {
+            settings: { memory: { enabled: true } },
+            indexer,
+            store,
+            config: BASE_CONFIG,
+        });
+        const result = await tools.get('kit_memory_search')({ query: 'test' });
+        const text = extractText(result);
+        assert.ok(text.includes('Memory index is warming'), `Expected warming note, got: ${text}`);
+    });
+    test('returns degraded note after warmup failure while preserving search results', async () => {
+        const chunk = makeChunk({ content: 'Degraded result', source: 'compiled/entities/degraded.md' });
+        const indexer = makeIndexerStub({
+            search: async () => [{ chunk, score: 0.7, retriever: 'bm25', contentSource: 'file' }],
+            startupIndex: async () => {
+                throw new Error('warmup failed');
+            },
+        });
+        const store = makeStoreStub(true);
+        const { server, tools } = makeMockServer();
+        const subsystem = registerMemoryTools(server, '/tmp', {
+            settings: { memory: { enabled: true } },
+            indexer,
+            store,
+            config: BASE_CONFIG,
+        });
+        assert.ok(subsystem);
+        await subsystem.startWarmup();
+        const result = await tools.get('kit_memory_search')({ query: 'test' });
+        const text = extractText(result);
+        assert.ok(text.includes('Memory index is degraded'), `Expected degraded note, got: ${text}`);
+        assert.ok(text.includes('warmup failed'), `Expected warmup error, got: ${text}`);
+        assert.ok(text.includes('Degraded result'), 'Result must still be included during degraded state');
+    });
     test('falls back to config.topK when top_k is not provided', async () => {
         let capturedTopK;
         const indexer = makeIndexerStub({
@@ -214,6 +253,25 @@ describe('kit_memory_search', () => {
         assert.ok(text.includes('kit_memory_search failed'), `Expected error prefix, got: ${text}`);
         assert.ok(text.includes('search exploded'), `Expected error message, got: ${text}`);
     });
+    test('returns initialization failure when store construction fails', async () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'memory-init-failure-'));
+        const occupiedWikiPath = path.join(tmpDir, 'wiki-file');
+        fs.writeFileSync(occupiedWikiPath, 'not a directory', 'utf8');
+        try {
+            const { server, tools } = makeMockServer();
+            const subsystem = registerMemoryTools(server, tmpDir, {
+                settings: { memory: { enabled: true } },
+                config: { ...BASE_CONFIG, wikiDir: occupiedWikiPath },
+            });
+            assert.ok(subsystem);
+            const result = await tools.get('kit_memory_search')({ query: 'test' });
+            const text = extractText(result);
+            assert.ok(text.includes('Memory initialization failed'), `Expected initialization failure, got: ${text}`);
+        }
+        finally {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
     test('description routes factual and temporal queries distinctly', () => {
         const indexer = makeIndexerStub();
         const store = makeStoreStub(true);

package/dist/services/memory/subsystem.d.ts

@@ -0,0 +1,19 @@
+import { type ProjectSettings } from '../../core/config/index.js';
+import { MemoryIndexer } from './indexer.js';
+import { MemoryStore } from './store.js';
+import type { MemoryConfig, MemoryLifecycleStatus } from './types.js';
+export interface MemorySubsystemOverrides {
+    indexer?: MemoryIndexer;
+    store?: MemoryStore;
+    config?: MemoryConfig;
+    settings?: ProjectSettings;
+}
+export interface MemorySubsystem {
+    readonly config: MemoryConfig;
+    readonly status: MemoryLifecycleStatus;
+    readonly indexer: MemoryIndexer | null;
+    readonly store: MemoryStore | null;
+    startWarmup(): Promise<void>;
+    close(): void;
+}
+export declare function createMemorySubsystem(workspaceRoot: string, overrides?: MemorySubsystemOverrides): MemorySubsystem | null;

package/dist/services/memory/subsystem.js

@@ -0,0 +1,67 @@
+import * as path from 'path';
+import { resolveMemoryConfig } from '../../core/config/index.js';
+import { Embedder } from './embedder.js';
+import { MemoryIndexer } from './indexer.js';
+import { MemoryStore } from './store.js';
+class DefaultMemorySubsystem {
+    config;
+    indexer;
+    store;
+    lifecycleStatus;
+    constructor(config, indexer, store, initialState, initialError) {
+        this.config = config;
+        this.indexer = indexer;
+        this.store = store;
+        this.lifecycleStatus = makeStatus(initialState, initialError);
+    }
+    get status() {
+        return this.lifecycleStatus;
+    }
+    async startWarmup() {
+        if (!this.indexer) {
+            this.lifecycleStatus = makeStatus('failed', this.lifecycleStatus.error ?? 'Memory indexer is unavailable');
+            return;
+        }
+        this.lifecycleStatus = makeStatus('warming');
+        try {
+            await this.indexer.startupIndex();
+            this.lifecycleStatus = makeStatus('ready');
+        }
+        catch (err) {
+            this.lifecycleStatus = makeStatus(this.store ? 'degraded' : 'failed', formatError(err));
+        }
+    }
+    close() {
+        this.store?.close();
+    }
+}
+function makeStatus(state, error) {
+    return {
+        state,
+        ready: state === 'ready',
+        warming: state === 'initializing' || state === 'warming',
+        degraded: state === 'degraded' || state === 'failed',
+        error,
+    };
+}
+function formatError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export function createMemorySubsystem(workspaceRoot, overrides = {}) {
+    const config = overrides.config ?? resolveMemoryConfig(overrides.settings ?? {}, workspaceRoot);
+    if (config.enabled !== true)
+        return null;
+    let store = overrides.store ?? null;
+    let indexer = overrides.indexer ?? null;
+    try {
+        store = store ?? new MemoryStore(path.join(config.wikiDir, 'index.db'), config);
+        if (!indexer) {
+            const embedder = new Embedder(config.embeddingModel);
+            indexer = new MemoryIndexer(store, embedder, config);
+        }
+        return new DefaultMemorySubsystem(config, indexer, store, 'initializing');
+    }
+    catch (err) {
+        return new DefaultMemorySubsystem(config, indexer, store, 'failed', formatError(err));
+    }
+}

package/dist/services/memory/types.d.ts

@@ -66,6 +66,26 @@ export interface IndexStats {
     deleted: number;
     skipped: number;
 }
+export type MemoryLifecycleState = 'disabled' | 'initializing' | 'warming' | 'ready' | 'degraded' | 'failed';
+export interface MemoryLifecycleStatus {
+    state: MemoryLifecycleState;
+    ready: boolean;
+    warming: boolean;
+    degraded: boolean;
+    error?: string;
+}
+export interface IndexDirectoryOptions {
+    relativeBase?: string;
+    excludeFiles?: string[];
+    fileConcurrency?: number;
+}
+export interface PreparedIndexMutation {
+    source: string;
+    chunksToUpsert: MemoryChunk[];
+    embeddings: Float32Array[];
+    idsToDelete: string[];
+    stats: IndexStats;
+}
 export interface RecentSource {
     source: string;
     fileMtimeAt: number;

package/dist/utils/async.d.ts

@@ -1 +1,2 @@
 export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, createError: () => Error): Promise<T>;
+export declare function mapLimit<T, R>(items: readonly T[], limit: number, worker: (item: T, index: number) => Promise<R>): Promise<R[]>;

package/dist/utils/async.js

@@ -13,3 +13,20 @@ export async function withTimeout(promise, timeoutMs, createError) {
             clearTimeout(timer);
     }
 }
+export async function mapLimit(items, limit, worker) {
+    if (items.length === 0)
+        return [];
+    const concurrency = Math.max(1, Math.floor(limit));
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    async function runWorker() {
+        while (nextIndex < items.length) {
+            const currentIndex = nextIndex;
+            nextIndex++;
+            results[currentIndex] = await worker(items[currentIndex], currentIndex);
+        }
+    }
+    const runners = Array.from({ length: Math.min(concurrency, items.length) }, () => runWorker());
+    await Promise.all(runners);
+    return results;
+}

package/dist/utils/async.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/async.test.js

@@ -0,0 +1,48 @@
+import * as assert from 'node:assert/strict';
+import { describe, test } from 'node:test';
+import { mapLimit } from './async.js';
+describe('mapLimit', () => {
+    test('returns an empty array for empty input', async () => {
+        const results = await mapLimit([], 3, async (item) => item);
+        assert.deepEqual(results, []);
+    });
+    test('preserves result order while workers resolve out of order', async () => {
+        const results = await mapLimit([30, 10, 20], 3, async (delayMs, index) => {
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+            return index;
+        });
+        assert.deepEqual(results, [0, 1, 2]);
+    });
+    test('caps active workers at the configured limit', async () => {
+        let active = 0;
+        let maxActive = 0;
+        await mapLimit([1, 2, 3, 4, 5], 2, async (item) => {
+            active++;
+            maxActive = Math.max(maxActive, active);
+            await new Promise((resolve) => setTimeout(resolve, 5));
+            active--;
+            return item;
+        });
+        assert.equal(maxActive, 2);
+    });
+    test('clamps invalid limits to one worker', async () => {
+        let active = 0;
+        let maxActive = 0;
+        await mapLimit([1, 2, 3], 0, async (item) => {
+            active++;
+            maxActive = Math.max(maxActive, active);
+            await new Promise((resolve) => setTimeout(resolve, 5));
+            active--;
+            return item;
+        });
+        assert.equal(maxActive, 1);
+    });
+    test('rejects with the original worker error', async () => {
+        const expected = new Error('worker failed');
+        await assert.rejects(mapLimit([1, 2], 2, async (item) => {
+            if (item === 2)
+                throw expected;
+            return item;
+        }), expected);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanhnd/agent-kit",
-  "version": "1.0.39",
+  "version": "1.0.40",
   "description": "Agent Kit MCP server for software development agent workflows",
   "type": "module",
   "main": "dist/server.js",