@hanhnd/agent-kit 1.0.31 → 1.0.33

package/dist/services/digest/providers/llama-local.js

@@ -0,0 +1,135 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getLlama, LlamaChatSession, createModelDownloader } from 'node-llama-cpp';
+import { LLAMA_CONTEXT_SIZE, LLAMA_MAX_GENERATED_TOKENS, LLAMA_TEMPERATURE } from '../constants.js';
+import { getDigestModelSpec } from '../model-registry.js';
+import { withTimeout } from '../../../utils/async.js';
+import { MODEL_CACHE_DIR } from '../../../utils/paths.js';
+class LlamaLocalDigestProviderError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LlamaLocalDigestProviderError';
+    }
+}
+function titleFromSource(sourcePath) {
+    return path
+        .basename(sourcePath)
+        .replace(/\.[^.]+$/, '')
+        .replace(/[_-]+/g, ' ');
+}
+function trimConversationExport(content, maxInputChars) {
+    const trimmed = content.trim();
+    if (trimmed.length <= maxInputChars)
+        return trimmed;
+    return [
+        '[Earlier conversation content omitted to fit the local digest context window.]',
+        trimmed.slice(-maxInputChars),
+    ].join('\n\n');
+}
+function buildPrompt(input, maxInputChars) {
+    const conversationExport = trimConversationExport(input.content, maxInputChars);
+    return [
+        {
+            role: 'system',
+            content: [
+                '# ROLE',
+                'You write short project-memory wiki pages from developer transcripts.',
+                'Your output is temporary recall to prevent blind steps.',
+                '',
+                '# RULES',
+                '1. Read the end of the export FIRST to discover the ultimate resolution.',
+                '2. What the user says LAST ALWAYS overrides earlier agreements.',
+                '3. Capture absolute engineering conclusions, never conversational pleasantries.',
+                '4. Return Markdown only. Do not wrap output in code blocks (```markdown ... ```).',
+            ].join('\n'),
+        },
+        {
+            role: 'user',
+            content: [
+                'Generate a high-level project memory page. STRICTLY adhere to this architectural layout:',
+                '',
+                '<layout>',
+                '# Digest: ' + titleFromSource(input.sourcePath),
+                '- **Ultimate Core Resolution**: [Describe the final working state of the feature and what problem it solves in 1-2 sentences. No conversational filler.]',
+                '- **Architectural Changes**: [List 3-4 high-level engineering decisions made (e.g., shifts in hook timing, data isolation, atomic locks). Focus on systemic changes, NOT individual files.]',
+                '- **Component State**: [Briefly state how the Plugin side and the MCP/CLI side now interact based on the final decision.]',
+                '- **Considered & Rejected**: [List concepts proposed but discarded (e.g., initial hooks location, mocking strategies). Omit if empty.]',
+                '</layout>',
+                '',
+                '# CRITICAL RULES:',
+                '- DO NOT list individual file paths, line numbers, or specific test cases (EXCLUDE lists of files).',
+                '- Focus entirely on the SYSTEM DESIGN and ARCHITECTURE that the next engineer needs to know.',
+                '- Keep output under 300 tokens. Stop immediately after the last valid section.',
+                '',
+                'Source path: ' + input.sourcePath,
+                '<conversation_export format="memory-kit">',
+                conversationExport,
+                '</conversation_export>',
+            ].join('\n'),
+        },
+    ];
+}
+function stripCodeFence(text) {
+    const trimmed = text.trim();
+    const match = trimmed.match(/^```(?:markdown|md)?\s*\n([\s\S]*?)\n```$/i);
+    return match ? match[1].trim() : trimmed;
+}
+function sanitizeConversationDigestMarkdown(generatedText) {
+    return stripCodeFence(generatedText).trim() + '\n';
+}
+export async function createLlamaLocalDigestProvider(modelId) {
+    const spec = getDigestModelSpec(modelId);
+    const modelCacheDir = path.join(MODEL_CACHE_DIR, 'llama');
+    fs.mkdirSync(modelCacheDir, { recursive: true });
+    let modelFilePath;
+    try {
+        const downloader = await createModelDownloader({
+            modelUri: spec.ggufUri,
+            dirPath: modelCacheDir,
+        });
+        modelFilePath = downloader.entrypointFilePath;
+        if (!fs.existsSync(modelFilePath)) {
+            await downloader.download();
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new LlamaLocalDigestProviderError(`Failed to download model: ${message}`);
+    }
+    let llama;
+    let model;
+    try {
+        llama = await getLlama();
+        model = await llama.loadModel({ modelPath: modelFilePath });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new LlamaLocalDigestProviderError(`Failed to load model: ${message}`);
+    }
+    return {
+        id: 'llama-local',
+        async dispose() {
+            await model.dispose();
+        },
+        async generateDigestMarkdown(input, options) {
+            const messages = buildPrompt(input, options.maxInputChars);
+            const systemContent = messages[0].content;
+            const userContent = messages[1].content;
+            const context = await model.createContext({ contextSize: LLAMA_CONTEXT_SIZE });
+            try {
+                const session = new LlamaChatSession({
+                    contextSequence: context.getSequence(),
+                    systemPrompt: systemContent,
+                });
+                const response = await withTimeout(session.prompt(userContent, {
+                    maxTokens: LLAMA_MAX_GENERATED_TOKENS,
+                    temperature: LLAMA_TEMPERATURE,
+                }), options.timeoutMs, () => new LlamaLocalDigestProviderError(`Llama provider timed out after ${options.timeoutMs}ms`));
+                return sanitizeConversationDigestMarkdown(response);
+            }
+            finally {
+                await context.dispose();
+            }
+        },
+    };
+}

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

@@ -0,0 +1,117 @@
+export declare enum DigestModelId {
+    TINY = "tiny",
+    DEFAULT = "default",
+    LARGE = "large"
+}
+export interface ConversationDigestSettings {
+    enabled?: boolean;
+    initialized: boolean;
+    modelId: string;
+    initializedAt: string;
+}
+export interface DigestModelSpec {
+    id: DigestModelId;
+    ggufUri: string;
+    approxSizeBytes: number;
+    license: string;
+    sourceUrl: string;
+    enabled: boolean;
+}
+export interface ConversationDigestInput {
+    sourcePath: string;
+    content: string;
+    contentHash: string;
+}
+interface ConversationDigestOptions {
+    modelId: string;
+    maxInputChars: number;
+    timeoutMs: number;
+}
+export interface ConversationDigestInitResult {
+    initialized: boolean;
+    modelId: string;
+    initializedAt?: string;
+    error?: string;
+}
+export interface ConversationDigestProvider {
+    readonly id: string;
+    dispose?(): Promise<void>;
+    generateDigestMarkdown(input: ConversationDigestInput, options: ConversationDigestOptions): Promise<string>;
+}
+export interface DigestFileOptions {
+    workspaceRoot: string;
+    inputPath: string;
+    modelId: string;
+    outDir?: string;
+    maxInputChars?: number;
+    timeoutMs?: number;
+}
+export interface ProvisionalDigestResult {
+    markdown: string;
+    status: 'provisional';
+    contentHash: string;
+    indexed: boolean;
+    skipped: boolean;
+    error?: string;
+}
+export interface InitializeConversationDigestInput {
+    workspaceRoot: string;
+    modelId: string;
+    allowDownload: boolean;
+    enabled?: boolean;
+}
+export type DigestPendingResult = {
+    ok: true;
+    initialized: false;
+    action: 'noop';
+    reason: 'not-initialized';
+} | {
+    ok: true;
+    initialized: true;
+    action: 'noop';
+    reason: 'locked';
+} | {
+    ok: true;
+    initialized: true;
+    action: 'noop';
+    reason: 'no-pending';
+} | {
+    ok: true;
+    initialized: true;
+    action: 'digested';
+    count: number;
+    skipped: number;
+    errors: number;
+} | {
+    ok: false;
+    initialized: true;
+    action: 'error';
+    error: string;
+};
+export type DigestWorkerState = 'running' | 'complete' | 'failed' | 'not-initialized' | 'no-pending' | 'locked' | 'stale';
+export interface DigestWorkerStatus {
+    state: DigestWorkerState;
+    pid: number | null;
+    startedAt: string;
+    updatedAt: string;
+    pendingAtStart: number;
+    processed: number;
+    skipped: number;
+    errors: number;
+    lastError?: string;
+}
+export interface DigestPendingCandidateSummary {
+    initialized: boolean;
+    pending: number;
+    reason?: 'not-initialized' | 'no-pending';
+}
+export interface DigestPendingLauncherResult {
+    ok: boolean;
+    mode: 'background-launcher';
+    status: DigestWorkerStatus;
+    spawned: boolean;
+    pid?: number;
+    reason?: string;
+    error?: string;
+}
+export {};

package/dist/services/digest/types.js

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

package/dist/services/digest/worker.d.ts

@@ -0,0 +1,2 @@
+export declare function isDigestWorkerInvocation(args: string[]): boolean;
+export declare function runDigestFileInWorker(args: string[]): number | undefined;

package/dist/services/digest/worker.js

@@ -0,0 +1,51 @@
+import { spawnSync } from 'node:child_process';
+import { parseArgs, numberFlag } from '../../cli/utils/args.js';
+import { DEFAULT_DIGEST_TIMEOUT_MS, DIGEST_TIMEOUT_GRACE_MS, DIGEST_WORKER_FLAG, DIGEST_WORKER_RESULT_PREFIX, } from './constants.js';
+function isDigestWorkerResult(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    return typeof record.markdown === 'string' && record.status === 'provisional';
+}
+function parseDigestWorkerSuccess(stdout) {
+    const line = stdout
+        .split(/\r?\n/)
+        .reverse()
+        .find((candidate) => candidate.startsWith(DIGEST_WORKER_RESULT_PREFIX));
+    if (!line)
+        return false;
+    try {
+        return isDigestWorkerResult(JSON.parse(line.slice(DIGEST_WORKER_RESULT_PREFIX.length)));
+    }
+    catch {
+        return false;
+    }
+}
+export function isDigestWorkerInvocation(args) {
+    return parseArgs(args).flags.get(DIGEST_WORKER_FLAG) === true;
+}
+export function runDigestFileInWorker(args) {
+    const parsed = parseArgs(args);
+    if (parsed.flags.get(DIGEST_WORKER_FLAG) === true)
+        return undefined;
+    const entrypoint = process.argv[1];
+    if (!entrypoint)
+        return undefined;
+    const timeoutMs = numberFlag(parsed.flags, 'timeout-ms', DEFAULT_DIGEST_TIMEOUT_MS);
+    const result = spawnSync(process.execPath, [entrypoint, 'memory', 'digest-file', ...args, `--${DIGEST_WORKER_FLAG}`], {
+        cwd: process.cwd(),
+        encoding: 'utf8',
+        maxBuffer: 1024 * 1024 * 20,
+        timeout: timeoutMs + DIGEST_TIMEOUT_GRACE_MS,
+    });
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    const workerSucceeded = parseDigestWorkerSuccess(result.stdout);
+    if (result.stderr && !workerSucceeded)
+        process.stderr.write(result.stderr);
+    if (result.status === 0 || workerSucceeded)
+        return 0;
+    if (result.status !== null)
+        return result.status;
+    return 1;
+}

package/dist/{utils → services/integration}/credentials.js

@@ -14,7 +14,7 @@
  * Active profile: KIT_PROFILE env var (defaults to "default")
  */
 import * as fs from 'fs';
-import { CREDENTIALS_FILE } from './paths.js';
+import { CREDENTIALS_FILE } from '../../utils/paths.js';
 let cachedCredentials = null;
 /**
  * Parse a simple INI file into a map of profiles.

package/dist/{utils/parser.js → services/integration/parser/adf.js}

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
 export function adfToMarkdown(adf) {
     if (!adf || typeof adf !== 'object')
         return 'No description';
@@ -17,8 +18,7 @@ export function adfToMarkdown(adf) {
                 }
                 case 'heading': {
                     const level = node.attrs?.level || 1;
-                    result +=
-                        '#'.repeat(level) + ' ' + renderNodes(node.content, listDepth, node.type) + '\n\n';
+                    result += '#'.repeat(level) + ' ' + renderNodes(node.content, listDepth, node.type) + '\n\n';
                     break;
                 }
                 case 'text': {
@@ -61,10 +61,7 @@ export function adfToMarkdown(adf) {
                     break;
                 }
                 case 'blockquote':
-                    result +=
-                        '> ' +
-                            renderNodes(node.content, listDepth, node.type).trim().replace(/\n/g, '\n> ') +
-                            '\n\n';
+                    result += '> ' + renderNodes(node.content, listDepth, node.type).trim().replace(/\n/g, '\n> ') + '\n\n';
                     break;
                 case 'codeBlock':
                     result += `\`\`\`${node.attrs?.language || ''}\n${renderNodes(node.content, listDepth, node.type).trim()}\n\`\`\`\n\n`;

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

@@ -1,4 +1,2 @@
 import type { MemoryChunk, MemoryConfig } from './types.js';
-export declare function computeChunkId(content: string): string;
-export declare function cleanContentForEmbedding(text: string): string;
 export declare function chunkMarkdown(text: string, source: string, config: Pick<MemoryConfig, 'chunkSize' | 'overlapLines'>): MemoryChunk[];

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

@@ -1,8 +1,8 @@
-import { createHash } from 'crypto';
-export function computeChunkId(content) {
-    return createHash('sha256').update(content).digest('hex').slice(0, 16);
+import { sha256Hex } from '../../utils/hash.js';
+function computeChunkId(content) {
+    return sha256Hex(content).slice(0, 16);
 }
-export function cleanContentForEmbedding(text) {
+function cleanContentForEmbedding(text) {
     return text.replace(/<!--[\s\S]*?-->/g, '');
 }
 const HEADING_RE = /^(#{1,6}) (.+)$/;
@@ -116,9 +116,7 @@ export function chunkMarkdown(text, source, config) {
         const sectionText = section.lines.map((l) => l.text).join('\n');
         if (!sectionText.trim())
             continue;
-        const fullText = prevOverlapLines.length > 0
-            ? `${prevOverlapLines.join('\n')}\n${sectionText}`
-            : sectionText;
+        const fullText = prevOverlapLines.length > 0 ? `${prevOverlapLines.join('\n')}\n${sectionText}` : sectionText;
         const parts = splitSection(fullText, chunkSize);
         for (let pi = 0; pi < parts.length; pi++) {
             const part = parts[pi];

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

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

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

@@ -1,6 +1,6 @@
 import * as assert from 'node:assert/strict';
 import { describe, test } from 'node:test';
-import { chunkMarkdown, cleanContentForEmbedding, computeChunkId } from '../chunker.js';
+import { chunkMarkdown } from './chunker.js';
 const CFG = { chunkSize: 200, overlapLines: 2 };
 const SRC = 'test.md';
 describe('chunkMarkdown', () => {
@@ -70,36 +70,3 @@ describe('chunkMarkdown', () => {
         assert.ok(chunk.content.includes('Before.'), 'Text before comment must remain');
     });
 });
-describe('computeChunkId', () => {
-    test('returns 16-character hex string', () => {
-        const id = computeChunkId('hello world');
-        assert.equal(id.length, 16);
-        assert.match(id, /^[0-9a-f]{16}$/);
-    });
-    test('same content always produces same id', () => {
-        assert.equal(computeChunkId('abc'), computeChunkId('abc'));
-    });
-    test('different content produces different id', () => {
-        assert.notEqual(computeChunkId('abc'), computeChunkId('xyz'));
-    });
-});
-describe('cleanContentForEmbedding', () => {
-    test('strips HTML comment', () => {
-        assert.equal(cleanContentForEmbedding('hello <!-- comment --> world'), 'hello  world');
-    });
-    test('strips multiline HTML comment', () => {
-        const input = 'before <!-- line1\nline2 --> after';
-        const result = cleanContentForEmbedding(input);
-        assert.ok(!result.includes('line1'));
-        assert.ok(result.includes('before'));
-        assert.ok(result.includes('after'));
-    });
-    test('returns original string when no comments present', () => {
-        const text = 'plain text without comments';
-        assert.equal(cleanContentForEmbedding(text), text);
-    });
-    test('preserves fenced code block content', () => {
-        const text = '```js\nconst x = 1;\n```';
-        assert.equal(cleanContentForEmbedding(text), text);
-    });
-});

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

@@ -0,0 +1,5 @@
+import { type MemoryConfig } from './types.js';
+export declare const DEFAULT_MEMORY_CONFIG: MemoryConfig;
+export declare const LOCK_RETRY_MS = 50;
+export declare const LOCK_TIMEOUT_MS = 500;
+export declare const RRF_K = 60;

package/dist/services/memory/constants.js

@@ -0,0 +1,13 @@
+import { EmbeddingModelName } from './types.js';
+export const DEFAULT_MEMORY_CONFIG = {
+    enabled: false,
+    wikiDir: '',
+    topK: 5,
+    chunkSize: 1500,
+    overlapLines: 2,
+    embeddingModel: EmbeddingModelName.SMALL,
+    vectorDimension: 384,
+};
+export const LOCK_RETRY_MS = 50;
+export const LOCK_TIMEOUT_MS = 500;
+export const RRF_K = 60;

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

@@ -1,4 +1,4 @@
-export { FASTEMBED_CACHE_DIR, MODEL_CACHE_DIR as DEFAULT_MODEL_CACHE_DIR } from '../utils/paths.js';
+import { EmbeddingModelName } from './types.js';
 export declare class EmbedderError extends Error {
     constructor(message: string, cause?: unknown);
 }
@@ -6,9 +6,10 @@ export declare class Embedder {
     private readonly modelName;
     private pipeline;
     private _dimension;
-    constructor(modelName: string);
+    constructor(modelName: EmbeddingModelName);
     embed(texts: string[]): Promise<Float32Array[]>;
     get dimension(): number | undefined;
     isReady(): boolean;
+    initialize(): Promise<void>;
     private loadModel;
 }

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

@@ -1,5 +1,5 @@
-import { FASTEMBED_CACHE_DIR } from '../utils/paths.js';
-export { FASTEMBED_CACHE_DIR, MODEL_CACHE_DIR as DEFAULT_MODEL_CACHE_DIR } from '../utils/paths.js';
+import { FASTEMBED_CACHE_DIR } from '../../utils/paths.js';
+import { EmbeddingModelName } from './types.js';
 export class EmbedderError extends Error {
     constructor(message, cause) {
         super(message);
@@ -40,16 +40,25 @@ export class Embedder {
     isReady() {
         return this.pipeline !== null;
     }
+    async initialize() {
+        if (!this.pipeline) {
+            await this.loadModel();
+        }
+    }
     async loadModel() {
         try {
             const { EmbeddingModel, FlagEmbedding } = await import('fastembed');
             const modelMap = {
-                'Xenova/bge-small-en-v1.5': EmbeddingModel.BGESmallENV15,
-                'Xenova/bge-base-en-v1.5': EmbeddingModel.BGEBaseENV15,
-                'Xenova/all-MiniLM-L6-v2': EmbeddingModel.AllMiniLML6V2,
+                [EmbeddingModelName.TINY]: EmbeddingModel.AllMiniLML6V2,
+                [EmbeddingModelName.SMALL]: EmbeddingModel.BGESmallENV15,
+                [EmbeddingModelName.LARGE]: EmbeddingModel.BGEBaseENV15,
             };
             const model = modelMap[this.modelName] ?? EmbeddingModel.BGESmallENV15;
-            const embedder = await FlagEmbedding.init({ model: model, cacheDir: FASTEMBED_CACHE_DIR, showDownloadProgress: false });
+            const embedder = await FlagEmbedding.init({
+                model: model,
+                cacheDir: FASTEMBED_CACHE_DIR,
+                showDownloadProgress: false,
+            });
             this.pipeline = async (texts) => {
                 const result = [];
                 for await (const batch of embedder.embed(texts, texts.length)) {

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

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

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

@@ -0,0 +1,13 @@
+import * as assert from 'node:assert/strict';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { describe, test } from 'node:test';
+import { CREDENTIALS_FILE, MODEL_CACHE_DIR, FASTEMBED_CACHE_DIR } from '../../utils/paths.js';
+describe('Embedder cache paths', () => {
+    test('uses global Agent Kit home for user-level files', () => {
+        const home = path.join(os.homedir(), '.agent-kit');
+        assert.equal(CREDENTIALS_FILE, path.join(home, 'credentials'));
+        assert.equal(MODEL_CACHE_DIR, path.join(home, 'cache', 'models'));
+        assert.equal(FASTEMBED_CACHE_DIR, path.join(MODEL_CACHE_DIR, 'fastembed'));
+    });
+});

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

@@ -2,4 +2,4 @@ export { MemoryStore, StoreError } from './store.js';
 export { Embedder, EmbedderError } from './embedder.js';
 export { MemoryIndexer } from './indexer.js';
 export type { MemoryChunk, SearchResult, MemoryConfig, IndexStats } from './types.js';
-export { DEFAULT_MEMORY_CONFIG } from './types.js';
+export { DEFAULT_MEMORY_CONFIG } from './constants.js';

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

@@ -1,4 +1,4 @@
 export { MemoryStore, StoreError } from './store.js';
 export { Embedder, EmbedderError } from './embedder.js';
 export { MemoryIndexer } from './indexer.js';
-export { DEFAULT_MEMORY_CONFIG } from './types.js';
+export { DEFAULT_MEMORY_CONFIG } from './constants.js';

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

@@ -1,12 +1,15 @@
-import type { Embedder } from './embedder.js';
 import type { MemoryStore } from './store.js';
 import type { IndexStats, MemoryConfig, SearchResult } from './types.js';
+interface TextEmbedder {
+    embed(texts: string[]): Promise<Float32Array[]>;
+    initialize(): Promise<void>;
+}
 export declare class MemoryIndexer {
     private readonly store;
     private readonly embedder;
     private readonly config;
     private _ready;
-    constructor(store: MemoryStore, embedder: Embedder, config: MemoryConfig);
+    constructor(store: MemoryStore, embedder: TextEmbedder, config: MemoryConfig);
     indexFile(absolutePath: string): Promise<IndexStats>;
     private indexFileRelativeTo;
     indexDirectory(rootDir: string, opts?: {
@@ -18,3 +21,4 @@ export declare class MemoryIndexer {
     startupIndex(): Promise<void>;
     get ready(): boolean;
 }
+export {};