@hanhnd/agent-kit 1.0.31 → 1.0.33

package/dist/{memory → services/memory}/indexer.js

@@ -1,29 +1,8 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { chunkMarkdown } from './chunker.js';
-const LOCK_RETRY_MS = 50;
-const LOCK_TIMEOUT_MS = 500;
-async function acquireLock(lockPath) {
-    const deadline = Date.now() + LOCK_TIMEOUT_MS;
-    while (Date.now() < deadline) {
-        try {
-            fs.writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
-            return true;
-        }
-        catch {
-            await new Promise((r) => setTimeout(r, LOCK_RETRY_MS));
-        }
-    }
-    return false;
-}
-function releaseLock(lockPath) {
-    try {
-        fs.unlinkSync(lockPath);
-    }
-    catch {
-        // ignore
-    }
-}
+import { LOCK_RETRY_MS, LOCK_TIMEOUT_MS, RRF_K } from './constants.js';
+import { acquireLock, releaseLock } from '../../utils/files.js';
 export class MemoryIndexer {
     store;
     embedder;
@@ -39,19 +18,19 @@ export class MemoryIndexer {
     }
     async indexFileRelativeTo(absolutePath, sourceRoot) {
         const source = path.relative(sourceRoot, absolutePath);
-        const existingHashes = this.store.hashesBySource(source);
+        const existingChunkIds = this.store.hashesBySource(source);
         let text;
         try {
             text = fs.readFileSync(absolutePath, 'utf8');
         }
         catch (err) {
             console.warn(`[memory-indexer] Cannot read file ${absolutePath}:`, err);
-            return { indexed: 0, deleted: 0, skipped: existingHashes.size };
+            return { indexed: 0, deleted: 0, skipped: existingChunkIds.size };
         }
         const allChunks = chunkMarkdown(text, source, this.config);
-        const newHashes = new Set(allChunks.map((c) => c.id));
-        const toIndex = allChunks.filter((c) => !existingHashes.has(c.id));
-        const toDelete = [...existingHashes].filter((h) => !newHashes.has(h));
+        const currentChunkIds = new Set(allChunks.map((chunk) => chunk.id));
+        const toIndex = allChunks.filter((chunk) => !existingChunkIds.has(chunk.id));
+        const toDelete = [...existingChunkIds].filter((id) => !currentChunkIds.has(id));
         let embeddings = [];
         if (toIndex.length > 0) {
             try {
@@ -59,7 +38,7 @@ export class MemoryIndexer {
             }
             catch (err) {
                 console.warn(`[memory-indexer] Embedding failed for ${absolutePath}:`, err);
-                return { indexed: 0, deleted: 0, skipped: existingHashes.size };
+                return { indexed: 0, deleted: 0, skipped: existingChunkIds.size };
             }
         }
         if (toIndex.length > 0) {
@@ -135,24 +114,22 @@ export class MemoryIndexer {
         if (bm25Ids.size > 0) {
             denseResults = denseResults.filter((result) => bm25Ids.has(result.id));
         }
-        // RRF fusion (k=60)
-        const k = 60;
         const scoreMap = new Map();
         denseResults.forEach((r, rank) => {
-            scoreMap.set(r.id, { dense: 1 / (k + rank + 1), bm25: 0 });
+            scoreMap.set(r.id, { dense: 1 / (RRF_K + rank + 1), bm25: 0 });
         });
         bm25Results.forEach((r, rank) => {
             const existing = scoreMap.get(r.id);
             if (existing) {
-                existing.bm25 = 1 / (k + rank + 1);
+                existing.bm25 = 1 / (RRF_K + rank + 1);
             }
             else {
-                scoreMap.set(r.id, { dense: 0, bm25: 1 / (k + rank + 1) });
+                scoreMap.set(r.id, { dense: 0, bm25: 1 / (RRF_K + rank + 1) });
             }
         });
         const hasDense = this.store.vecAvailable && denseResults.length > 0;
         const numRetrievers = hasDense ? 2 : 1;
-        const maxScore = numRetrievers / 61;
+        const maxScore = numRetrievers / (RRF_K + 1);
         const ranked = [...scoreMap.entries()]
             .map(([id, scores]) => ({
             id,
@@ -193,7 +170,7 @@ export class MemoryIndexer {
         const savePath = path.join(rawDir, `conv_save_${datePart}.md`);
         const lockPath = `${savePath}.lock`;
         fs.mkdirSync(rawDir, { recursive: true });
-        const acquired = await acquireLock(lockPath);
+        const acquired = await acquireLock(lockPath, LOCK_TIMEOUT_MS, LOCK_RETRY_MS);
         if (!acquired) {
             console.warn('[memory-indexer] Could not acquire write lock, writing anyway (fail-open)');
         }
@@ -202,12 +179,13 @@ export class MemoryIndexer {
         }
         finally {
             if (acquired)
-                releaseLock(lockPath);
+                releaseLock(lockPath, { ignoreErrors: true });
         }
         return { indexed: 0, deleted: 0, skipped: 0 };
     }
     async startupIndex() {
         try {
+            await this.embedder.initialize();
             await this.indexDirectory(path.join(this.config.wikiDir, 'compiled'), {
                 relativeBase: this.config.wikiDir,
                 excludeFiles: ['index.md', 'log.md'],

package/dist/services/memory/indexer.test.d.ts

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

package/dist/{memory/__tests__ → services/memory}/indexer.test.js

@@ -5,18 +5,15 @@ import { syncBuiltinESMExports } from 'node:module';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { after, before, describe, test } from 'node:test';
-import { MemoryIndexer } from '../indexer.js';
-import { MemoryStore } from '../store.js';
-// Stub embedder — returns deterministic non-zero vectors without loading any model
+import { MemoryIndexer } from './indexer.js';
+import { MemoryStore } from './store.js';
+import { EmbeddingModelName } from './types.js';
 class StubEmbedder {
     async embed(texts) {
         return texts.map(() => new Float32Array(384).fill(0.05));
     }
-    get dimension() {
-        return 384;
-    }
-    isReady() {
-        return true;
+    initialize() {
+        return Promise.resolve();
     }
 }
 function makeConfig(wikiDir) {
@@ -26,7 +23,7 @@ function makeConfig(wikiDir) {
         topK: 5,
         chunkSize: 1500,
         overlapLines: 2,
-        embeddingModel: 'Xenova/bge-small-en-v1.5',
+        embeddingModel: EmbeddingModelName.SMALL,
         vectorDimension: 384,
     };
 }
@@ -140,7 +137,8 @@ describe('MemoryIndexer', () => {
         const compiledDir = path.join(testCfg.wikiDir, 'compiled');
         try {
             fs.mkdirSync(compiledDir, { recursive: true });
-            testStore.upsert([{
+            testStore.upsert([
+                {
                     id: 'stale-daily-file-0001',
                     source: '2026-05-18.md',
                     heading: 'Stale',
@@ -148,7 +146,8 @@ describe('MemoryIndexer', () => {
                     content: 'pre migration content',
                     lineStart: 1,
                     lineEnd: 2,
-                }], [new Float32Array(384)]);
+                },
+            ], [new Float32Array(384)]);
             assert.ok(testStore.hashesBySource('2026-05-18.md').size > 0);
             const stats = await testIndexer.indexDirectory(compiledDir, {
                 relativeBase: testCfg.wikiDir,
@@ -257,10 +256,7 @@ describe('MemoryIndexer', () => {
             fs.writeFileSync(secondPath, secondContent, 'utf8');
             const results = await testIndexer.search('duplicate source query', 2);
             assert.equal(results.length, 2);
-            assert.deepEqual(results.map((result) => result.chunk.source), [
-                'compiled/entities/first.md',
-                'compiled/entities/second.md',
-            ]);
+            assert.deepEqual(results.map((result) => result.chunk.source), ['compiled/entities/first.md', 'compiled/entities/second.md']);
             assert.equal(results[0].chunk.content, firstContent);
             assert.equal(results[1].chunk.content, secondContent);
         }

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

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

package/dist/{tools/__tests__ → services/memory}/memory.test.js

@@ -1,7 +1,8 @@
 import * as assert from 'node:assert/strict';
 import { describe, test } from 'node:test';
-import { resolveMemoryConfig } from '../config.js';
-import { registerMemoryToolHandlers } from '../memory.js';
+import { EmbeddingModelName } from './types.js';
+import { resolveMemoryConfig } from '../../core/config/index.js';
+import { registerMemoryTools } from '../../mcp/memory.js';
 // Minimal McpServer stub that captures tool registrations
 function makeMockServer() {
     const tools = new Map();
@@ -30,7 +31,7 @@ const BASE_CONFIG = {
     topK: 5,
     chunkSize: 1500,
     overlapLines: 2,
-    embeddingModel: 'Xenova/bge-small-en-v1.5',
+    embeddingModel: EmbeddingModelName.SMALL,
     vectorDimension: 384,
 };
 function makeIndexerStub(overrides = {}) {
@@ -48,12 +49,24 @@ function extractText(result) {
 }
 describe('kit_memory_search', () => {
     test('returns formatted full content and display source when results exist', async () => {
-        const chunk = makeChunk({ content: 'Important memory content', source: 'compiled/entities/foo.md' });
-        const searchResult = { chunk, score: 0.85, retriever: 'bm25', contentSource: 'file' };
+        const chunk = makeChunk({
+            content: 'Important memory content',
+            source: 'compiled/entities/foo.md',
+        });
+        const searchResult = {
+            chunk,
+            score: 0.85,
+            retriever: 'bm25',
+            contentSource: 'file',
+        };
         const indexer = makeIndexerStub({ search: async () => [searchResult] });
         const store = makeStoreStub(true);
         const { server, tools } = makeMockServer();
-        registerMemoryToolHandlers(server, indexer, store, BASE_CONFIG);
+        registerMemoryTools(server, { memory: { enabled: true } }, '/tmp', {
+            indexer,
+            store,
+            config: BASE_CONFIG,
+        });
         const result = await tools.get('kit_memory_search')({ query: 'test query' });
         const text = extractText(result);
         assert.ok(text.includes('Important memory content'), 'Result must include chunk content');
@@ -65,7 +78,11 @@ describe('kit_memory_search', () => {
         const indexer = makeIndexerStub({ search: async () => [] });
         const store = makeStoreStub(true);
         const { server, tools } = makeMockServer();
-        registerMemoryToolHandlers(server, indexer, store, BASE_CONFIG);
+        registerMemoryTools(server, { memory: { enabled: true } }, '/tmp', {
+            indexer,
+            store,
+            config: BASE_CONFIG,
+        });
         const result = await tools.get('kit_memory_search')({ query: 'nothing here' });
         const text = extractText(result);
         assert.ok(text.toLowerCase().includes('no memories') || text.includes('No memories'), `Expected "no memories" message, got: ${text.slice(0, 100)}`);
@@ -74,18 +91,31 @@ describe('kit_memory_search', () => {
         const indexer = makeIndexerStub({ search: async () => [] });
         const store = makeStoreStub(false);
         const { server, tools } = makeMockServer();
-        registerMemoryToolHandlers(server, indexer, store, BASE_CONFIG);
+        registerMemoryTools(server, { memory: { enabled: true } }, '/tmp', {
+            indexer,
+            store,
+            config: BASE_CONFIG,
+        });
         const result = await tools.get('kit_memory_search')({ query: 'test' });
         const text = extractText(result);
         assert.ok(text.includes('Vector search unavailable') || text.includes('keyword-only'), `Expected degraded warning in: ${text.slice(0, 200)}`);
     });
     test('prepends degraded warning when vecAvailable is false with results', async () => {
         const chunk = makeChunk({ content: 'Found content', source: 'test.md' });
-        const searchResult = { chunk, score: 0.5, retriever: 'bm25', contentSource: 'file' };
+        const searchResult = {
+            chunk,
+            score: 0.5,
+            retriever: 'bm25',
+            contentSource: 'file',
+        };
         const indexer = makeIndexerStub({ search: async () => [searchResult] });
         const store = makeStoreStub(false);
         const { server, tools } = makeMockServer();
-        registerMemoryToolHandlers(server, indexer, store, BASE_CONFIG);
+        registerMemoryTools(server, { memory: { enabled: true } }, '/tmp', {
+            indexer,
+            store,
+            config: BASE_CONFIG,
+        });
         const result = await tools.get('kit_memory_search')({ query: 'test' });
         const text = extractText(result);
         assert.ok(text.includes('Vector search unavailable') || text.includes('keyword-only'), `Expected degraded warning with results in: ${text.slice(0, 200)}`);
@@ -93,11 +123,20 @@ describe('kit_memory_search', () => {
     });
     test('prepends source-unavailable warning for fallback results', async () => {
         const chunk = makeChunk({ content: 'Stored chunk only', source: 'compiled/entities/foo.md' });
-        const searchResult = { chunk, score: 0.5, retriever: 'bm25', contentSource: 'fallback' };
+        const searchResult = {
+            chunk,
+            score: 0.5,
+            retriever: 'bm25',
+            contentSource: 'fallback',
+        };
         const indexer = makeIndexerStub({ search: async () => [searchResult] });
         const store = makeStoreStub(true);
         const { server, tools } = makeMockServer();
-        registerMemoryToolHandlers(server, indexer, store, BASE_CONFIG);
+        registerMemoryTools(server, { memory: { enabled: true } }, '/tmp', {
+            indexer,
+            store,
+            config: BASE_CONFIG,
+        });
         const result = await tools.get('kit_memory_search')({ query: 'test' });
         const text = extractText(result);
         assert.ok(text.includes('Source file unavailable'), `Expected fallback warning in: ${text}`);
@@ -113,7 +152,11 @@ describe('kit_memory_search', () => {
         });
         const store = makeStoreStub(true);
         const { server, tools } = makeMockServer();
-        registerMemoryToolHandlers(server, indexer, store, BASE_CONFIG);
+        registerMemoryTools(server, { memory: { enabled: true } }, '/tmp', {
+            indexer,
+            store,
+            config: BASE_CONFIG,
+        });
         await tools.get('kit_memory_search')({ query: 'test', top_k: 3 });
         assert.equal(capturedTopK, 3);
     });
@@ -127,17 +170,27 @@ describe('kit_memory_search', () => {
         });
         const store = makeStoreStub(true);
         const { server, tools } = makeMockServer();
-        registerMemoryToolHandlers(server, indexer, store, BASE_CONFIG);
+        registerMemoryTools(server, { memory: { enabled: true } }, '/tmp', {
+            indexer,
+            store,
+            config: BASE_CONFIG,
+        });
         await tools.get('kit_memory_search')({ query: 'test' });
         assert.equal(capturedTopK, BASE_CONFIG.topK);
     });
     test('returns error message when indexer.search throws', async () => {
         const indexer = makeIndexerStub({
-            search: async () => { throw new Error('search exploded'); },
+            search: async () => {
+                throw new Error('search exploded');
+            },
         });
         const store = makeStoreStub(true);
         const { server, tools } = makeMockServer();
-        registerMemoryToolHandlers(server, indexer, store, BASE_CONFIG);
+        registerMemoryTools(server, { memory: { enabled: true } }, '/tmp', {
+            indexer,
+            store,
+            config: BASE_CONFIG,
+        });
         const result = await tools.get('kit_memory_search')({ query: 'test' });
         const text = extractText(result);
         assert.ok(text.includes('kit_memory_search failed'), `Expected error prefix, got: ${text}`);
@@ -151,7 +204,11 @@ describe('kit_memory_save', () => {
         });
         const store = makeStoreStub(true);
         const { server, tools } = makeMockServer();
-        registerMemoryToolHandlers(server, indexer, store, BASE_CONFIG);
+        registerMemoryTools(server, { memory: { enabled: true } }, '/tmp', {
+            indexer,
+            store,
+            config: BASE_CONFIG,
+        });
         const result = await tools.get('kit_memory_save')({ content: 'Some important note' });
         const text = extractText(result);
         const parsed = JSON.parse(text);
@@ -161,11 +218,17 @@ describe('kit_memory_save', () => {
     });
     test('returns saved:false and error message when indexer.save throws', async () => {
         const indexer = makeIndexerStub({
-            save: async () => { throw new Error('disk full'); },
+            save: async () => {
+                throw new Error('disk full');
+            },
         });
         const store = makeStoreStub(true);
         const { server, tools } = makeMockServer();
-        registerMemoryToolHandlers(server, indexer, store, BASE_CONFIG);
+        registerMemoryTools(server, { memory: { enabled: true } }, '/tmp', {
+            indexer,
+            store,
+            config: BASE_CONFIG,
+        });
         const result = await tools.get('kit_memory_save')({ content: 'note' });
         const text = extractText(result);
         const parsed = JSON.parse(text);

package/dist/{memory → services/memory}/store.js

@@ -141,27 +141,19 @@ export class MemoryStore {
         }
     }
     hashesBySource(source) {
-        const rows = this.db
-            .prepare(`SELECT id FROM memory_chunks WHERE source = ?`)
-            .all(source);
+        const rows = this.db.prepare(`SELECT id FROM memory_chunks WHERE source = ?`).all(source);
         return new Set(rows.map((r) => r.id));
     }
     indexedSources() {
-        const rows = this.db
-            .prepare(`SELECT DISTINCT source FROM memory_chunks`)
-            .all();
+        const rows = this.db.prepare(`SELECT DISTINCT source FROM memory_chunks`).all();
         return rows.map((r) => r.source);
     }
     deleteBySource(source) {
-        const rows = this.db
-            .prepare(`SELECT rowid FROM memory_chunks WHERE source = ?`)
-            .all(source);
+        const rows = this.db.prepare(`SELECT rowid FROM memory_chunks WHERE source = ?`).all(source);
         const deleteAll = this.db.transaction(() => {
             if (this._vecAvailable && rows.length > 0) {
                 const placeholders = rows.map(() => '?').join(', ');
-                this.db
-                    .prepare(`DELETE FROM memory_vec WHERE rowid IN (${placeholders})`)
-                    .run(...rows.map((r) => r.rowid));
+                this.db.prepare(`DELETE FROM memory_vec WHERE rowid IN (${placeholders})`).run(...rows.map((r) => r.rowid));
             }
             this.db.prepare(`DELETE FROM memory_chunks WHERE source = ?`).run(source);
         });
@@ -171,15 +163,11 @@ export class MemoryStore {
         if (ids.length === 0)
             return;
         const placeholders = ids.map(() => '?').join(', ');
-        const rows = this.db
-            .prepare(`SELECT rowid FROM memory_chunks WHERE id IN (${placeholders})`)
-            .all(...ids);
+        const rows = this.db.prepare(`SELECT rowid FROM memory_chunks WHERE id IN (${placeholders})`).all(...ids);
         const deleteAll = this.db.transaction(() => {
             if (this._vecAvailable && rows.length > 0) {
                 const rPlaceholders = rows.map(() => '?').join(', ');
-                this.db
-                    .prepare(`DELETE FROM memory_vec WHERE rowid IN (${rPlaceholders})`)
-                    .run(...rows.map((r) => r.rowid));
+                this.db.prepare(`DELETE FROM memory_vec WHERE rowid IN (${rPlaceholders})`).run(...rows.map((r) => r.rowid));
             }
             this.db.prepare(`DELETE FROM memory_chunks WHERE id IN (${placeholders})`).run(...ids);
         });

package/dist/services/memory/store.test.d.ts

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

package/dist/{memory/__tests__ → services/memory}/store.test.js

@@ -3,14 +3,15 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { after, before, describe, test } from 'node:test';
-import { MemoryStore } from '../store.js';
+import { MemoryStore } from './store.js';
+import { EmbeddingModelName } from './types.js';
 const TEST_CONFIG = {
     enabled: true,
     wikiDir: '',
     topK: 5,
     chunkSize: 1500,
     overlapLines: 2,
-    embeddingModel: 'Xenova/bge-small-en-v1.5',
+    embeddingModel: EmbeddingModelName.SMALL,
     vectorDimension: 384,
 };
 function makeChunk(overrides = {}) {
@@ -54,8 +55,16 @@ describe('MemoryStore', () => {
         assert.ok(hashes.has('upsert-test-0001'));
     });
     test('deleteBySource removes all chunks for that source', () => {
-        const c1 = makeChunk({ id: 'del-src-0001', source: 'deleteme.md', content: 'delete source chunk 1' });
-        const c2 = makeChunk({ id: 'del-src-0002', source: 'deleteme.md', content: 'delete source chunk 2' });
+        const c1 = makeChunk({
+            id: 'del-src-0001',
+            source: 'deleteme.md',
+            content: 'delete source chunk 1',
+        });
+        const c2 = makeChunk({
+            id: 'del-src-0002',
+            source: 'deleteme.md',
+            content: 'delete source chunk 2',
+        });
         store.upsert([c1, c2], [new Float32Array(384), new Float32Array(384)]);
         store.deleteBySource('deleteme.md');
         const hashes = store.hashesBySource('deleteme.md');
@@ -124,7 +133,11 @@ describe('MemoryStore', () => {
         assert.equal(results[0].id, 'partial-found-0001');
     });
     test('indexedSources includes source after upsert', () => {
-        const chunk = makeChunk({ id: 'indexed-src-0001', source: 'indexed-source.md', content: 'indexed' });
+        const chunk = makeChunk({
+            id: 'indexed-src-0001',
+            source: 'indexed-source.md',
+            content: 'indexed',
+        });
         store.upsert([chunk], [new Float32Array(384)]);
         const sources = store.indexedSources();
         assert.ok(sources.includes('indexed-source.md'), `Expected 'indexed-source.md' in ${sources.join(', ')}`);

package/dist/{memory → services/memory}/types.d.ts

@@ -1,3 +1,9 @@
+import type { ConversationDigestSettings } from '../digest/types.js';
+export declare enum EmbeddingModelName {
+    TINY = "tiny",
+    SMALL = "small",
+    LARGE = "large"
+}
 export interface MemoryChunk {
     id: string;
     source: string;
@@ -19,12 +25,12 @@ export interface MemoryConfig {
     topK: number;
     chunkSize: number;
     overlapLines: number;
-    embeddingModel: string;
+    embeddingModel: EmbeddingModelName;
     vectorDimension: number;
+    conversationDigest?: ConversationDigestSettings;
 }
 export interface IndexStats {
     indexed: number;
     deleted: number;
     skipped: number;
 }
-export declare const DEFAULT_MEMORY_CONFIG: MemoryConfig;

package/dist/services/memory/types.js

@@ -0,0 +1,6 @@
+export var EmbeddingModelName;
+(function (EmbeddingModelName) {
+    EmbeddingModelName["TINY"] = "tiny";
+    EmbeddingModelName["SMALL"] = "small";
+    EmbeddingModelName["LARGE"] = "large";
+})(EmbeddingModelName || (EmbeddingModelName = {}));

package/dist/utils/async.d.ts

@@ -0,0 +1 @@
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, createError: () => Error): Promise<T>;

package/dist/utils/async.js

@@ -0,0 +1,15 @@
+export async function withTimeout(promise, timeoutMs, createError) {
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            reject(createError());
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([promise, timeout]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/utils/files.d.ts

@@ -0,0 +1,7 @@
+export declare function atomicWriteTextFile(filePath: string, content: string): void;
+export declare function atomicWriteJsonFile(filePath: string, value: unknown): void;
+export declare function acquireLock(lockPath: string, timeoutMs: number, retryMs: number): Promise<boolean>;
+export declare function releaseLock(lockPath: string, opts?: {
+    ignoreErrors?: boolean;
+}): void;
+export declare function tryAcquireProcessLock(lockPath: string): boolean;

package/dist/utils/files.js

@@ -0,0 +1,77 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export function atomicWriteTextFile(filePath, content) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tempPath, content, 'utf8');
+    fs.renameSync(tempPath, filePath);
+}
+export function atomicWriteJsonFile(filePath, value) {
+    atomicWriteTextFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+function tryWriteFileExclusive(filePath, content) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    try {
+        fs.writeFileSync(filePath, content, { flag: 'wx' });
+        return true;
+    }
+    catch (err) {
+        if (err.code === 'EEXIST')
+            return false;
+        throw err;
+    }
+}
+export async function acquireLock(lockPath, timeoutMs, retryMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            if (tryWriteFileExclusive(lockPath, String(process.pid)))
+                return true;
+        }
+        catch {
+            // Preserve fail-open retry behavior for transient lock-file write errors.
+        }
+        await new Promise((r) => setTimeout(r, retryMs));
+    }
+    return false;
+}
+export function releaseLock(lockPath, opts = {}) {
+    try {
+        fs.unlinkSync(lockPath);
+    }
+    catch (err) {
+        if (opts.ignoreErrors || err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+}
+export function tryAcquireProcessLock(lockPath) {
+    const lockContent = JSON.stringify({ pid: process.pid });
+    if (tryWriteFileExclusive(lockPath, lockContent))
+        return true;
+    let pid;
+    try {
+        const raw = fs.readFileSync(lockPath, 'utf8');
+        pid = JSON.parse(raw).pid;
+    }
+    catch {
+        // Unparseable lockfiles are treated as stale.
+    }
+    if (pid !== undefined) {
+        try {
+            process.kill(pid, 0);
+            return false;
+        }
+        catch (err) {
+            if (err.code !== 'ESRCH')
+                return false;
+        }
+    }
+    try {
+        fs.unlinkSync(lockPath);
+    }
+    catch {
+        // Ignore if another process already removed the stale lock.
+    }
+    return tryWriteFileExclusive(lockPath, lockContent);
+}

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

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