@hanhnd/agent-kit 1.0.31 → 1.0.32

package/dist/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/memory/types.d.ts

@@ -1,3 +1,4 @@
+import type { ConversationDigestSettings } from './digest/types.js';
 export interface MemoryChunk {
     id: string;
     source: string;
@@ -21,10 +22,10 @@ export interface MemoryConfig {
     overlapLines: number;
     embeddingModel: string;
     vectorDimension: number;
+    conversationDigest?: ConversationDigestSettings;
 }
 export interface IndexStats {
     indexed: number;
     deleted: number;
     skipped: number;
 }
-export declare const DEFAULT_MEMORY_CONFIG: MemoryConfig;

package/dist/memory/types.js

@@ -1,9 +1 @@
-export const DEFAULT_MEMORY_CONFIG = {
-    enabled: false,
-    wikiDir: '',
-    topK: 5,
-    chunkSize: 1500,
-    overlapLines: 2,
-    embeddingModel: 'Xenova/bge-small-en-v1.5',
-    vectorDimension: 384,
-};
+export {};

package/dist/tools/__tests__/cli-digest-pending.test.d.ts

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

package/dist/tools/__tests__/cli-digest-pending.test.js

@@ -0,0 +1,51 @@
+import * as assert from 'node:assert/strict';
+import { afterEach, describe, test } from 'node:test';
+import { createTempDirTracker } from '../../__tests__/temp-dir.js';
+import { runMemoryCli } from '../../cli/memory.js';
+const tempDirs = createTempDirTracker();
+afterEach(() => {
+    tempDirs.cleanup();
+});
+describe('cmdDigestPending CLI', () => {
+    test('C22: no --hook flag → writes usage to stderr and returns 1', async () => {
+        const stderrChunks = [];
+        const origWrite = process.stderr.write.bind(process.stderr);
+        process.stderr.write = (chunk) => {
+            stderrChunks.push(String(chunk));
+            return true;
+        };
+        let code;
+        try {
+            code = await runMemoryCli(['digest-pending'], process.env);
+        }
+        finally {
+            process.stderr.write = origWrite;
+        }
+        assert.equal(code, 1);
+        assert.ok(stderrChunks.some((s) => s.includes('Usage')));
+    });
+    test('C23: --hook returns 0 and emits one JSON line matching DigestPendingResult', async () => {
+        const workspace = tempDirs.makeTempDir('cli-pending-c23-');
+        const stdoutChunks = [];
+        const origWrite = process.stdout.write.bind(process.stdout);
+        process.stdout.write = (chunk) => {
+            stdoutChunks.push(String(chunk));
+            return true;
+        };
+        let code;
+        try {
+            code = await runMemoryCli(['digest-pending', '--hook'], {
+                ...process.env,
+                WORKSPACE_DIR: workspace,
+            });
+        }
+        finally {
+            process.stdout.write = origWrite;
+        }
+        assert.equal(code, 0);
+        const output = stdoutChunks.join('');
+        const parsed = JSON.parse(output.trim());
+        assert.ok('ok' in parsed, 'result must have ok field');
+        assert.ok('action' in parsed, 'result must have action field');
+    });
+});

package/dist/tools/__tests__/cli-memory.test.d.ts

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

package/dist/tools/__tests__/cli-memory.test.js

@@ -0,0 +1,22 @@
+import * as assert from 'node:assert/strict';
+import { afterEach, describe, test } from 'node:test';
+import { createTempDirTracker } from '../../__tests__/temp-dir.js';
+import { runMemoryCli } from '../../cli/memory.js';
+const tempDirs = createTempDirTracker();
+afterEach(() => {
+    tempDirs.cleanup();
+});
+describe('memory CLI', () => {
+    test('digest-pending --hook returns 0 when settings are missing', async () => {
+        const workspace = tempDirs.makeTempDir('digest-pending-');
+        const code = await runMemoryCli(['digest-pending', '--hook'], {
+            ...process.env,
+            WORKSPACE_DIR: workspace,
+        });
+        assert.equal(code, 0);
+    });
+    test('unknown command returns 1', async () => {
+        const code = await runMemoryCli(['unknown'], process.env);
+        assert.equal(code, 1);
+    });
+});

package/dist/tools/__tests__/digest-init.test.d.ts

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

package/dist/tools/__tests__/digest-init.test.js

@@ -0,0 +1,32 @@
+import * as assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { afterEach, describe, test } from 'node:test';
+import { createTempDirTracker } from '../../__tests__/temp-dir.js';
+import { initializeConversationDigestModel } from '../../memory/digest/processor.js';
+const tempDirs = createTempDirTracker();
+afterEach(() => {
+    tempDirs.cleanup();
+});
+describe('initializeConversationDigestModel', () => {
+    test('rejects unknown model and leaves settings absent', async () => {
+        const workspace = tempDirs.makeTempDir('digest-init-');
+        const result = await initializeConversationDigestModel({
+            workspaceRoot: workspace,
+            modelId: 'unknown-model',
+            allowDownload: true,
+        });
+        assert.equal(result.initialized, false);
+        assert.equal(fs.existsSync(path.join(workspace, '.agent-kit', 'settings.json')), false);
+    });
+    test('requires explicit download permission and leaves settings absent', async () => {
+        const workspace = tempDirs.makeTempDir('digest-init-');
+        const result = await initializeConversationDigestModel({
+            workspaceRoot: workspace,
+            modelId: 'qwen2.5-1.5b-instruct-q4',
+            allowDownload: false,
+        });
+        assert.equal(result.initialized, false);
+        assert.equal(fs.existsSync(path.join(workspace, '.agent-kit', 'settings.json')), false);
+    });
+});

package/dist/tools/__tests__/memory.test.js

@@ -48,8 +48,16 @@ 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();
@@ -81,7 +89,12 @@ describe('kit_memory_search', () => {
     });
     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();
@@ -93,7 +106,12 @@ 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();
@@ -133,7 +151,9 @@ describe('kit_memory_search', () => {
     });
     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();
@@ -161,7 +181,9 @@ 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();

package/dist/tools/agent.js

@@ -24,16 +24,7 @@ function agentArgs(agent, prompt, workspaceRoot) {
         case 'claude':
             return ['--dangerously-skip-permissions', '-p', prompt];
         case 'codex':
-            return [
-                '--ask-for-approval',
-                'never',
-                '--sandbox',
-                'workspace-write',
-                '--cd',
-                workspaceRoot,
-                'exec',
-                prompt,
-            ];
+            return ['--ask-for-approval', 'never', '--sandbox', 'workspace-write', '--cd', workspaceRoot, 'exec', prompt];
     }
 }
 function taskSlug(task) {
@@ -59,9 +50,7 @@ function initAgentLog(workspaceRoot, slug, agent) {
 }
 export function registerAgentTools(server) {
     server.tool('kit_trigger_agent', '!Important: Trigger only when user explicitly asks to delegate a task to an external agent CLI (gemini, claude, or codex). The task can be a direct message or a path to a handoff file (.agent-kit/handoffs/feature-slug/plan.md).', {
-        agent: z
-            .enum(['gemini', 'claude', 'codex'])
-            .describe('The agent CLI to invoke: "gemini", "claude", or "codex"'),
+        agent: z.enum(['gemini', 'claude', 'codex']).describe('The agent CLI to invoke: "gemini", "claude", or "codex"'),
         task: z
             .string()
             .describe('Task message or path to a handoff file (e.g., ".agent-kit/handoffs/feature-slug/plan.md")'),

package/dist/tools/config.d.ts

@@ -2,7 +2,8 @@
  * Configuration utilities
  * Shared configuration constants and loaders
  */
-import { type MemoryConfig } from '../memory/types.js';
+import type { MemoryConfig } from '../memory/types.js';
+import type { ConversationDigestSettings } from '../memory/digest/types.js';
 /**
  * Default file extensions - expanded to support more languages
  * Used by kit_get_project_context and other tools
@@ -26,10 +27,9 @@ export declare function resolveMemoryConfig(settings: ProjectSettings, workspace
  * Allows project-specific customization
  */
 export declare function getFileExtensions(projectDir: string): string[];
-/**
- * Load project settings from .gemini/settings.json
- */
 export declare function loadProjectSettings(projectDir: string): ProjectSettings;
+export declare function writeProjectSettings(workspaceRoot: string, patch: Partial<ProjectSettings>): void;
+export declare function resolveConversationDigestConfig(settings: ProjectSettings): ConversationDigestSettings | undefined;
 /**
  * Sensitive files that agents are FORBIDDEN from reading/writing.
  */

package/dist/tools/config.js

@@ -4,7 +4,8 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { DEFAULT_MEMORY_CONFIG } from '../memory/types.js';
+import { DEFAULT_MEMORY_CONFIG } from '../memory/constants.js';
+import { atomicWriteJsonFile } from '../utils/files.js';
 /**
  * Default file extensions - expanded to support more languages
  * Used by kit_get_project_context and other tools
@@ -58,9 +59,6 @@ export function getFileExtensions(projectDir) {
     }
     return DEFAULT_EXTENSIONS;
 }
-/**
- * Load project settings from .gemini/settings.json
- */
 export function loadProjectSettings(projectDir) {
     const settingsPath = path.join(projectDir, '.agent-kit', 'settings.json');
     if (fs.existsSync(settingsPath)) {
@@ -73,6 +71,23 @@ export function loadProjectSettings(projectDir) {
     }
     return {};
 }
+export function writeProjectSettings(workspaceRoot, patch) {
+    const settingsPath = path.join(workspaceRoot, '.agent-kit', 'settings.json');
+    const current = loadProjectSettings(workspaceRoot);
+    atomicWriteJsonFile(settingsPath, { ...current, ...patch });
+}
+export function resolveConversationDigestConfig(settings) {
+    const digest = settings.memory?.conversationDigest;
+    if (!digest?.initialized || typeof digest.modelId !== 'string' || typeof digest.initializedAt !== 'string') {
+        return undefined;
+    }
+    return {
+        enabled: digest.enabled !== false,
+        initialized: true,
+        modelId: digest.modelId,
+        initializedAt: digest.initializedAt,
+    };
+}
 /**
  * Sensitive files that agents are FORBIDDEN from reading/writing.
  */
@@ -108,11 +123,4 @@ export const FORBIDDEN_PATTERNS = [
 /**
  * Directory name segments that are always blocked.
  */
-export const FORBIDDEN_DIRS = [
-    '.git',
-    '.ssh',
-    '.aws',
-    '.kube',
-    '.gnupg',
-    '.docker',
-];
+export const FORBIDDEN_DIRS = ['.git', '.ssh', '.aws', '.kube', '.gnupg', '.docker'];

package/dist/tools/core.js

@@ -17,9 +17,7 @@ export function registerCoreTools(server) {
     // Returns the saved file path to use in next-step instructions
     // ═══════════════════════════════════════════════════════════════
     server.tool('kit_save_handoff', `Save a handoff artifact to .agent-kit/handoffs/. Returns the saved file path to use in next-step instructions. Do NOT append version numbers (v2, v3, etc.) to the slug.`, {
-        type: z
-            .enum(HANDOFF_TYPES)
-            .describe('Handoff type'),
+        type: z.enum(HANDOFF_TYPES).describe('Handoff type'),
         content: z.string().describe('Full markdown content to save'),
         slug: z
             .string()

package/dist/tools/handoffs.js

@@ -42,8 +42,7 @@ export function deriveFeatureSlug(input) {
     const contentTicketSlug = findTicketId(input.content);
     if (contentTicketSlug)
         return contentTicketSlug;
-    return (sanitizeFeatureSlug(contentSlugCandidate(input.content)) ||
-        'untitled-handoff');
+    return sanitizeFeatureSlug(contentSlugCandidate(input.content)) || 'untitled-handoff';
 }
 export function resolveHandoffPath(input) {
     const canonicalType = normalizeHandoffType(input.type);

package/dist/tools/integration.js

@@ -81,11 +81,7 @@ export function registerIntegrationTools(server) {
             .optional()
             .describe('Bitbucket workspace slug (required for numeric ID if BITBUCKET_DEFAULT_WORKSPACE not set)'),
         repoSlug: z.string().optional().describe('Bitbucket repo slug (required for numeric ID)'),
-        includeDiff: z
-            .boolean()
-            .optional()
-            .default(true)
-            .describe('Include unified diff in response'),
+        includeDiff: z.boolean().optional().default(true).describe('Include unified diff in response'),
     }, async ({ input, workspace, repoSlug, includeDiff }) => {
         try {
             let ws;
@@ -180,9 +176,7 @@ ${pr.description || 'No description'}`;
 **Type:** ${ticket.fields.issuetype?.name || 'Unknown'}
 
 ### Description
-${typeof ticket.fields.description === 'string'
-                ? ticket.fields.description
-                : adfToMarkdown(ticket.fields.description)}
+${typeof ticket.fields.description === 'string' ? ticket.fields.description : adfToMarkdown(ticket.fields.description)}
 
 ### Labels
 ${ticket.fields.labels?.join(', ') || 'None'}`;

package/dist/tools/memory.d.ts

@@ -7,7 +7,7 @@ import { type ProjectSettings } from './config.js';
  * Registers tool handlers onto an already-constructed indexer/store pair.
  * Exported for unit testing with mocks.
  */
-export declare function registerMemoryToolHandlers(server: McpServer, indexer: MemoryIndexer, store: MemoryStore, config: MemoryConfig): void;
+export declare function registerMemoryToolHandlers(server: McpServer, indexer: MemoryIndexer, store: MemoryStore, config: MemoryConfig, workspaceRoot?: string): void;
 /**
  * Initializes the memory subsystem and registers all memory tools.
  * Returns the MemoryIndexer so the caller can fire startupIndex() after server.connect().

package/dist/tools/memory.js

@@ -3,13 +3,15 @@ import { z } from 'zod';
 import { Embedder } from '../memory/embedder.js';
 import { MemoryIndexer } from '../memory/indexer.js';
 import { MemoryStore } from '../memory/store.js';
+import { initializeConversationDigestModel } from '../memory/digest/processor.js';
+import { DEFAULT_DIGEST_MODEL_ID } from '../memory/digest/constants.js';
 import { mcpJson, mcpText } from '../utils/utils.js';
-import { resolveMemoryConfig } from './config.js';
+import { loadProjectSettings, resolveConversationDigestConfig, resolveMemoryConfig, } from './config.js';
 /**
  * Registers tool handlers onto an already-constructed indexer/store pair.
  * Exported for unit testing with mocks.
  */
-export function registerMemoryToolHandlers(server, indexer, store, config) {
+export function registerMemoryToolHandlers(server, indexer, store, config, workspaceRoot = process.cwd()) {
     server.tool('kit_memory_search', 'Search persistent memory for context relevant to the current question. Returns semantically relevant results using hybrid dense+BM25+RRF search.', {
         query: z.string().min(1).describe('Search query'),
         top_k: z.number().int().positive().optional().describe('Number of results to return'),
@@ -57,6 +59,30 @@ export function registerMemoryToolHandlers(server, indexer, store, config) {
             return mcpJson({ saved: false, error: message });
         }
     });
+    server.tool('kit_memory_digest_init', 'Initialize or toggle local conversation digesting. Downloads/cache-loads the pinned local model only when explicitly invoked.', {
+        model_id: z.string().optional().describe('Digest model id'),
+        enabled: z.boolean().optional().describe('Enable or disable conversation digesting'),
+    }, async ({ model_id, enabled }) => {
+        try {
+            const existingConfig = resolveConversationDigestConfig(loadProjectSettings(workspaceRoot));
+            const result = await initializeConversationDigestModel({
+                workspaceRoot,
+                modelId: model_id ?? existingConfig?.modelId ?? DEFAULT_DIGEST_MODEL_ID,
+                allowDownload: true,
+                enabled,
+            });
+            return mcpJson({
+                initialized: result.initialized,
+                model_id: result.modelId,
+                initialized_at: result.initializedAt,
+                error: result.error,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return mcpJson({ initialized: false, error: message });
+        }
+    });
 }
 /**
  * Initializes the memory subsystem and registers all memory tools.
@@ -70,6 +96,6 @@ export function registerMemoryTools(server, settings, workspaceRoot) {
     const store = new MemoryStore(path.join(config.wikiDir, 'index.db'), config);
     const embedder = new Embedder(config.embeddingModel);
     const indexer = new MemoryIndexer(store, embedder, config);
-    registerMemoryToolHandlers(server, indexer, store, config);
+    registerMemoryToolHandlers(server, indexer, store, config, workspaceRoot);
     return indexer;
 }

package/dist/tools/security.js

@@ -110,9 +110,7 @@ export function commandExists(cmd) {
 export async function findFilesAsync(dir, extensions, maxFiles, excludeDirs = ['node_modules', '.git', 'dist', 'build', 'coverage']) {
     const results = [];
     // Use queue instead of recursion to prevent stack overflow
-    const queue = [
-        { fullPath: dir, relativePath: '' },
-    ];
+    const queue = [{ fullPath: dir, relativePath: '' }];
     while (queue.length > 0 && results.length < maxFiles) {
         const current = queue.shift();
         let entries;
@@ -126,9 +124,7 @@ export async function findFilesAsync(dir, extensions, maxFiles, excludeDirs = ['
             if (results.length >= maxFiles)
                 break;
             const entryFullPath = path.join(current.fullPath, entry.name);
-            const entryRelPath = current.relativePath
-                ? path.join(current.relativePath, entry.name)
-                : entry.name;
+            const entryRelPath = current.relativePath ? path.join(current.relativePath, entry.name) : entry.name;
             if (entry.isDirectory()) {
                 if (!excludeDirs.includes(entry.name)) {
                     queue.push({ fullPath: entryFullPath, relativePath: entryRelPath });

package/dist/utils/args.d.ts

@@ -0,0 +1,7 @@
+export interface ParsedArgs {
+    flags: Map<string, string | boolean>;
+    positionals: string[];
+}
+export declare function parseArgs(args: string[]): ParsedArgs;
+export declare function stringFlag(flags: Map<string, string | boolean>, key: string): string | undefined;
+export declare function numberFlag(flags: Map<string, string | boolean>, key: string, defaultValue: number | string): number;

package/dist/utils/args.js

@@ -0,0 +1,31 @@
+export function parseArgs(args) {
+    const flags = new Map();
+    const positionals = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg.startsWith('--')) {
+            positionals.push(arg);
+            continue;
+        }
+        const key = arg.slice(2);
+        const next = args[index + 1];
+        if (!next || next.startsWith('--')) {
+            flags.set(key, true);
+            continue;
+        }
+        flags.set(key, next);
+        index += 1;
+    }
+    return { flags, positionals };
+}
+export function stringFlag(flags, key) {
+    const value = flags.get(key);
+    return typeof value === 'string' ? value : undefined;
+}
+export function numberFlag(flags, key, defaultValue) {
+    const value = Number(stringFlag(flags, key) ?? defaultValue);
+    if (!Number.isFinite(value)) {
+        throw new Error(`--${key} must be a finite number`);
+    }
+    return value;
+}

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,8 @@
+export declare function atomicWriteTextFile(filePath: string, content: string): void;
+export declare function atomicWriteJsonFile(filePath: string, value: unknown): void;
+export declare function tryWriteFileExclusive(filePath: string, content: string): boolean;
+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`);
+}
+export 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);
+}