@hanhnd/agent-kit 1.0.33 → 1.0.35

package/dist/core/config/index.d.ts

@@ -24,6 +24,9 @@ export { MemoryConfig };
 export declare function resolveMemoryConfig(settings: ProjectSettings, workspaceRoot: string): MemoryConfig;
 export declare function loadProjectSettings(projectDir: string): ProjectSettings;
 export declare function writeProjectSettings(workspaceRoot: string, patch: Partial<ProjectSettings>): void;
+export declare function getGlobalSettingsFile(): string;
+export declare function loadGlobalSettings(): ProjectSettings;
+export declare function writeGlobalSettings(patch: Partial<ProjectSettings>): void;
 export declare function resolveConversationDigestConfig(settings: ProjectSettings): ConversationDigestSettings | undefined;
 /**
  * Sensitive files that agents are FORBIDDEN from reading/writing.

package/dist/core/config/index.js

@@ -3,6 +3,7 @@
  * Shared configuration constants and loaders
  */
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { DEFAULT_MEMORY_CONFIG } from '../../services/memory/constants.js';
 import { atomicWriteJsonFile } from '../../utils/files.js';
@@ -65,6 +66,25 @@ export function writeProjectSettings(workspaceRoot, patch) {
     const current = loadProjectSettings(workspaceRoot);
     atomicWriteJsonFile(settingsPath, { ...current, ...patch });
 }
+export function getGlobalSettingsFile() {
+    return path.join(os.homedir(), '.agent-kit', 'settings.json');
+}
+export function loadGlobalSettings() {
+    const file = getGlobalSettingsFile();
+    if (fs.existsSync(file)) {
+        try {
+            return JSON.parse(fs.readFileSync(file, 'utf-8'));
+        }
+        catch (error) {
+            console.error(`[agent-kit] Warning: Failed to parse ${file}:`, error);
+        }
+    }
+    return {};
+}
+export function writeGlobalSettings(patch) {
+    const current = loadGlobalSettings();
+    atomicWriteJsonFile(getGlobalSettingsFile(), { ...current, ...patch });
+}
 export function resolveConversationDigestConfig(settings) {
     const digest = settings.memory?.conversationDigest;
     if (!digest?.initialized || typeof digest.modelId !== 'string' || typeof digest.initializedAt !== 'string') {

package/dist/core/handoffs/index.d.ts

@@ -1,16 +1,17 @@
-export declare const HANDOFF_TYPES: readonly ["brainstorm", "clarification", "plan", "ticket", "research", "scenario", "investigation"];
+export declare const HANDOFF_TYPES: readonly ["brainstorm", "clarification", "plan", "ticket", "research", "scenario", "investigation", "code"];
 type HandoffType = (typeof HANDOFF_TYPES)[number];
-type CanonicalHandoffType = 'brainstorm' | 'clarification' | 'plan' | 'ticket' | 'research' | 'scenario' | 'investigation';
-interface SavedHandoffLocation {
+type CanonicalHandoffType = 'brainstorm' | 'clarification' | 'plan' | 'ticket' | 'research' | 'scenario' | 'investigation' | 'code';
+export interface SavedHandoffFolderLocation {
     featureSlug: string;
     canonicalType: CanonicalHandoffType;
-    filePath: string;
+    folderPath: string;
     relativePath: string;
 }
-export declare function resolveHandoffPath(input: {
+export declare function resolveHandoffFolder(input: {
     workspaceRoot: string;
     type: HandoffType;
     slug: string;
-    content: string;
-}): SavedHandoffLocation;
+    primaryContent: string;
+}): SavedHandoffFolderLocation;
+export declare function validateHandoffFilename(name: string): string;
 export {};

package/dist/core/handoffs/index.js

@@ -7,6 +7,7 @@ export const HANDOFF_TYPES = [
     'research',
     'scenario',
     'investigation',
+    'code',
 ];
 const TICKET_ID_PATTERN = /\b[A-Z][A-Z0-9]+-\d+\b/;
 function findTicketId(value) {
@@ -44,18 +45,25 @@ function deriveFeatureSlug(input) {
         return contentTicketSlug;
     return sanitizeFeatureSlug(contentSlugCandidate(input.content)) || 'untitled-handoff';
 }
-export function resolveHandoffPath(input) {
+export function resolveHandoffFolder(input) {
     const canonicalType = normalizeHandoffType(input.type);
     const featureSlug = deriveFeatureSlug({
         requestedSlug: input.slug,
-        content: input.content,
+        content: input.primaryContent,
         type: canonicalType,
     });
-    const relativePath = path.join('.agent-kit', 'handoffs', featureSlug, `${canonicalType}.md`);
+    const relativePath = path.join('.agent-kit', 'handoffs', featureSlug, canonicalType);
     return {
         featureSlug,
         canonicalType,
-        filePath: path.join(input.workspaceRoot, relativePath),
+        folderPath: path.join(input.workspaceRoot, relativePath),
         relativePath,
     };
 }
+export function validateHandoffFilename(name) {
+    const normalized = name.trim().replace(/^["']|["']$/g, '');
+    if (!/^[A-Za-z0-9_-]+\.md$/.test(normalized)) {
+        throw new Error(`Unsafe handoff filename: ${name}`);
+    }
+    return normalized;
+}

package/dist/core/handoffs/index.test.d.ts

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

package/dist/core/handoffs/index.test.js

@@ -0,0 +1,88 @@
+import * as assert from 'node:assert/strict';
+import * as path from 'node:path';
+import { describe, test } from 'node:test';
+import { resolveHandoffFolder, validateHandoffFilename } from './index.js';
+const WORKSPACE = '/tmp/test-workspace';
+describe('resolveHandoffFolder', () => {
+    test('relativePath has no .md suffix', () => {
+        const result = resolveHandoffFolder({
+            workspaceRoot: WORKSPACE,
+            type: 'plan',
+            slug: 'my-feature',
+            primaryContent: '',
+        });
+        assert.ok(!result.relativePath.endsWith('.md'), `relativePath must not end with .md, got: ${result.relativePath}`);
+        assert.equal(result.relativePath, path.join('.agent-kit', 'handoffs', 'my-feature', 'plan'));
+    });
+    test('folderPath is absolute under workspaceRoot', () => {
+        const result = resolveHandoffFolder({
+            workspaceRoot: WORKSPACE,
+            type: 'brainstorm',
+            slug: 'auth',
+            primaryContent: '',
+        });
+        assert.equal(result.folderPath, path.join(WORKSPACE, '.agent-kit', 'handoffs', 'auth', 'brainstorm'));
+    });
+    test('ticket-ID extracted from primaryContent when slug is empty', () => {
+        const result = resolveHandoffFolder({
+            workspaceRoot: WORKSPACE,
+            type: 'plan',
+            slug: '',
+            primaryContent: '# Fix PROJ-456\n\nSome content.',
+        });
+        assert.equal(result.featureSlug, 'proj-456');
+    });
+    test('first-heading fallback when no ticket ID in slug or content', () => {
+        const result = resolveHandoffFolder({
+            workspaceRoot: WORKSPACE,
+            type: 'research',
+            slug: '',
+            primaryContent: '# My Feature\n\nDetail.',
+        });
+        assert.equal(result.featureSlug, 'my-feature');
+    });
+    test('"untitled-handoff" fallback when both slug and content are empty', () => {
+        const result = resolveHandoffFolder({ workspaceRoot: WORKSPACE, type: 'ticket', slug: '', primaryContent: '' });
+        assert.equal(result.featureSlug, 'untitled-handoff');
+    });
+    test('code handoff resolves under code folder', () => {
+        const result = resolveHandoffFolder({
+            workspaceRoot: WORKSPACE,
+            type: 'code',
+            slug: 'execution-decision-ledger',
+            primaryContent: '# Execution Report',
+        });
+        assert.equal(result.canonicalType, 'code');
+        assert.equal(result.relativePath, path.join('.agent-kit', 'handoffs', 'execution-decision-ledger', 'code'));
+        assert.equal(result.folderPath, path.join(WORKSPACE, '.agent-kit', 'handoffs', 'execution-decision-ledger', 'code'));
+    });
+});
+describe('validateHandoffFilename', () => {
+    test('"README.md" returns unchanged', () => {
+        assert.equal(validateHandoffFilename('README.md'), 'README.md');
+    });
+    test('"DETAIL.md" returns unchanged', () => {
+        assert.equal(validateHandoffFilename('DETAIL.md'), 'DETAIL.md');
+    });
+    test('"index.md" returns unchanged', () => {
+        assert.equal(validateHandoffFilename('index.md'), 'index.md');
+    });
+    test('"../etc/passwd" throws', () => {
+        assert.throws(() => validateHandoffFilename('../etc/passwd'), /Unsafe handoff filename/);
+    });
+    test('"sub/dir.md" throws', () => {
+        assert.throws(() => validateHandoffFilename('sub/dir.md'), /Unsafe handoff filename/);
+    });
+    test('"README" throws — missing .md extension', () => {
+        assert.throws(() => validateHandoffFilename('README'), /Unsafe handoff filename/);
+    });
+    test('empty string throws', () => {
+        assert.throws(() => validateHandoffFilename(''), /Unsafe handoff filename/);
+    });
+    test('"README.txt" throws — wrong extension', () => {
+        assert.throws(() => validateHandoffFilename('README.txt'), /Unsafe handoff filename/);
+    });
+    test('".hidden.md" throws — leading dot', () => {
+        assert.throws(() => validateHandoffFilename('.hidden.md'), /Unsafe handoff filename/);
+    });
+});

package/dist/entrypoints/server.js

@@ -10,7 +10,6 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { registerCoreTools } from '../mcp/core.js';
 import { registerAgentTools } from '../mcp/agent.js';
 import { registerIntegrationTools } from '../mcp/integration.js';
-import { loadProjectSettings } from '../core/config/index.js';
 import { registerMemoryTools } from '../mcp/memory.js';
 import { getWorkspaceRoot } from '../utils/utils.js';
 const server = new McpServer({
@@ -24,8 +23,7 @@ registerIntegrationTools(server);
 registerCoreTools(server);
 registerAgentTools(server);
 const workspaceRoot = getWorkspaceRoot();
-const settings = loadProjectSettings(workspaceRoot);
-const memoryIndexer = registerMemoryTools(server, settings, workspaceRoot);
+const memoryIndexer = registerMemoryTools(server, workspaceRoot);
 // ═══════════════════════════════════════════════════════════════
 // START SERVER
 // ═══════════════════════════════════════════════════════════════

package/dist/mcp/agent.d.ts

@@ -1,6 +1,6 @@
 /**
  * Agent Delegation Tools - Invoke external agent CLIs (Gemini, Claude, Codex)
- * Supports handoff file injection and automatic fallback
+ * Supports handoff folder references and automatic fallback
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare function registerAgentTools(server: McpServer): void;

package/dist/mcp/agent.js

@@ -1,6 +1,6 @@
 /**
  * Agent Delegation Tools - Invoke external agent CLIs (Gemini, Claude, Codex)
- * Supports handoff file injection and automatic fallback
+ * Supports handoff folder references and automatic fallback
  */
 import { spawn } from 'child_process';
 import { randomUUID } from 'crypto';
@@ -49,11 +49,11 @@ function initAgentLog(workspaceRoot, slug, agent) {
     return { logPath: path.relative(workspaceRoot, logFile), logStream };
 }
 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).', {
+    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 folder (.agent-kit/handoffs/feature-slug/plan).', {
         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")'),
+            .describe('Task message or path to a handoff folder (e.g., ".agent-kit/handoffs/feature-slug/plan")'),
     }, async ({ agent, task }, extra) => {
         const workspaceRoot = getWorkspaceRoot();
         let job;

package/dist/mcp/core.d.ts

@@ -2,7 +2,14 @@
  * Core Tools - Extension info and handoff persistence
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { mcpText } from '../utils/utils.js';
 import { DEFAULT_EXTENSIONS } from '../core/config/index.js';
+import { HANDOFF_TYPES } from '../core/handoffs/index.js';
+export declare function handleSaveHandoff(args: {
+    type: (typeof HANDOFF_TYPES)[number];
+    slug: string;
+    files: Record<string, string>;
+}, workspaceRoot: string): ReturnType<typeof mcpText>;
 /**
  * Register core tools with MCP server
  */

package/dist/mcp/core.js

@@ -6,41 +6,55 @@ import * as path from 'path';
 import { z } from 'zod';
 import { getWorkspaceRoot, mcpText } from '../utils/utils.js';
 import { DEFAULT_EXTENSIONS } from '../core/config/index.js';
-import { HANDOFF_TYPES, resolveHandoffPath } from '../core/handoffs/index.js';
+import { HANDOFF_TYPES, resolveHandoffFolder, validateHandoffFilename } from '../core/handoffs/index.js';
+export function handleSaveHandoff(args, workspaceRoot) {
+    try {
+        if (Object.keys(args.files).length === 0) {
+            return mcpText('Error saving handoff: files cannot be empty');
+        }
+        for (const name of Object.keys(args.files)) {
+            try {
+                validateHandoffFilename(name);
+            }
+            catch (err) {
+                return mcpText(`Error saving handoff: ${err instanceof Error ? err.message : err}`);
+            }
+        }
+        const primaryContent = args.files['README.md'] ?? Object.values(args.files)[0];
+        const location = resolveHandoffFolder({
+            workspaceRoot,
+            type: args.type,
+            slug: args.slug,
+            primaryContent,
+        });
+        fs.mkdirSync(location.folderPath, { recursive: true });
+        for (const [name, content] of Object.entries(args.files)) {
+            fs.writeFileSync(path.join(location.folderPath, name), content, 'utf8');
+        }
+        return mcpText(`✅ Saved to: ${location.folderPath}`);
+    }
+    catch (error) {
+        return mcpText(`Error saving handoff: ${error instanceof Error ? error.message : error}`);
+    }
+}
 /**
  * Register core tools with MCP server
  */
 export function registerCoreTools(server) {
     // ═══════════════════════════════════════════════════════════════
     // TOOL: SAVE HANDOFF
-    // Writes handoff artifacts to the workspace
-    // Returns the saved file path to use in next-step instructions
+    // Writes handoff artifacts to the workspace as a folder of files
+    // Returns the saved folder 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.`, {
+    server.tool('kit_save_handoff', `Save a handoff artifact to .agent-kit/handoffs/. Returns the saved folder 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'),
-        content: z.string().describe('Full markdown content to save'),
+        files: z
+            .record(z.string(), z.string())
+            .describe('Markdown files to write into the handoff folder. May include one or many files per call; repeated calls with the same type and slug add or overwrite the provided files. Filenames must match /^[A-Za-z0-9_-]+\\.md$/.'),
         slug: z
             .string()
-            .describe('Short identifier for the filename, e.g. "user-auth" or "PROJ-123". Do NOT append version numbers (v2, v3, etc.).'),
-    }, async ({ type, content, slug }) => {
-        try {
-            const location = resolveHandoffPath({
-                workspaceRoot: getWorkspaceRoot(),
-                type,
-                slug,
-                content,
-            });
-            const handoffDir = path.dirname(location.filePath);
-            if (!fs.existsSync(handoffDir)) {
-                fs.mkdirSync(handoffDir, { recursive: true });
-            }
-            fs.writeFileSync(location.filePath, content, 'utf8');
-            return mcpText(`✅ Saved to: ${location.filePath}`);
-        }
-        catch (error) {
-            return mcpText(`Error saving handoff: ${error}`);
-        }
-    });
+            .describe('Short identifier for the folder, e.g. "user-auth" or "PROJ-123". Do NOT append version numbers (v2, v3, etc.).'),
+    }, async (args) => handleSaveHandoff(args, getWorkspaceRoot()));
 }
 // Export DEFAULT_EXTENSIONS for backward compatibility
 export { DEFAULT_EXTENSIONS };

package/dist/mcp/core.test.d.ts

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

package/dist/mcp/core.test.js

@@ -0,0 +1,98 @@
+import * as assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, describe, test } from 'node:test';
+import { handleSaveHandoff } from './core.js';
+const tempDirs = [];
+function makeTempWorkspace() {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'core-test-'));
+    tempDirs.push(dir);
+    return dir;
+}
+afterEach(() => {
+    while (tempDirs.length > 0) {
+        const dir = tempDirs.pop();
+        if (dir)
+            fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+function resultText(result) {
+    return result.content[0].text;
+}
+describe('handleSaveHandoff', () => {
+    test('C1: README.md + DETAIL.md written under folder; returns folder path without .md', () => {
+        const workspace = makeTempWorkspace();
+        const result = handleSaveHandoff({ type: 'brainstorm', slug: 'auth', files: { 'README.md': '# Readme', 'DETAIL.md': '# Detail' } }, workspace);
+        const text = resultText(result);
+        assert.ok(text.startsWith('✅ Saved to:'), `expected success, got: ${text}`);
+        assert.ok(!text.endsWith('.md'), 'folder path must not end with .md');
+        const folderPath = text.replace('✅ Saved to: ', '');
+        assert.ok(fs.existsSync(path.join(folderPath, 'README.md')), 'README.md must exist');
+        assert.ok(fs.existsSync(path.join(folderPath, 'DETAIL.md')), 'DETAIL.md must exist');
+        assert.equal(fs.readFileSync(path.join(folderPath, 'README.md'), 'utf8'), '# Readme');
+        assert.equal(fs.readFileSync(path.join(folderPath, 'DETAIL.md'), 'utf8'), '# Detail');
+    });
+    test('C2: single README.md written under folder; returns folder path', () => {
+        const workspace = makeTempWorkspace();
+        const result = handleSaveHandoff({ type: 'ticket', slug: 'my-ticket', files: { 'README.md': '# Ticket content' } }, workspace);
+        const text = resultText(result);
+        assert.ok(text.startsWith('✅ Saved to:'), `expected success, got: ${text}`);
+        const folderPath = text.replace('✅ Saved to: ', '');
+        assert.ok(!text.endsWith('.md'), 'folder path must not end with .md');
+        assert.ok(fs.existsSync(path.join(folderPath, 'README.md')), 'README.md must exist');
+        assert.equal(fs.readFileSync(path.join(folderPath, 'README.md'), 'utf8'), '# Ticket content');
+    });
+    test('C3: empty files returns error containing "files cannot be empty"', () => {
+        const workspace = makeTempWorkspace();
+        const result = handleSaveHandoff({ type: 'plan', slug: 'x', files: {} }, workspace);
+        assert.match(resultText(result), /files cannot be empty/);
+    });
+    test('C4: path-traversal filename returns error containing "Unsafe handoff filename"', () => {
+        const workspace = makeTempWorkspace();
+        const result = handleSaveHandoff({ type: 'plan', slug: 'x', files: { '../escape.md': 'bad' } }, workspace);
+        assert.match(resultText(result), /Unsafe handoff filename/);
+    });
+    test('C5: filename without .md extension returns error containing "Unsafe handoff filename"', () => {
+        const workspace = makeTempWorkspace();
+        const result = handleSaveHandoff({ type: 'plan', slug: 'x', files: { README: 'bad' } }, workspace);
+        assert.match(resultText(result), /Unsafe handoff filename/);
+    });
+    test('C6: slug derived from README.md content ticket-ID when slug is empty', () => {
+        const workspace = makeTempWorkspace();
+        const result = handleSaveHandoff({ type: 'brainstorm', slug: '', files: { 'README.md': '# Fix PROJ-789\n\nDetails.' } }, workspace);
+        const text = resultText(result);
+        assert.ok(text.includes('proj-789'), `expected proj-789 in path, got: ${text}`);
+    });
+    test('C7: second call with same slug overwrites files without error (idempotent)', () => {
+        const workspace = makeTempWorkspace();
+        const args = { type: 'plan', slug: 'idem', files: { 'README.md': 'v1' } };
+        const r1 = handleSaveHandoff(args, workspace);
+        assert.ok(resultText(r1).startsWith('✅'), `first call failed: ${resultText(r1)}`);
+        const argsV2 = { type: 'plan', slug: 'idem', files: { 'README.md': 'v2' } };
+        const r2 = handleSaveHandoff(argsV2, workspace);
+        assert.ok(resultText(r2).startsWith('✅'), `second call failed: ${resultText(r2)}`);
+        const folderPath = resultText(r2).replace('✅ Saved to: ', '');
+        assert.equal(fs.readFileSync(path.join(folderPath, 'README.md'), 'utf8'), 'v2');
+    });
+    test('C8: code handoff writes REPORT.md and DECISIONS.md without README.md', () => {
+        const workspace = makeTempWorkspace();
+        const result = handleSaveHandoff({
+            type: 'code',
+            slug: 'execution-decision-ledger',
+            files: {
+                'REPORT.md': '# Code Execution Report',
+                'DECISIONS.md': '# Execution Decision Records',
+            },
+        }, workspace);
+        const text = resultText(result);
+        assert.ok(text.startsWith('✅ Saved to:'), `expected success, got: ${text}`);
+        const folderPath = text.replace('✅ Saved to: ', '');
+        assert.equal(folderPath, path.join(workspace, '.agent-kit', 'handoffs', 'execution-decision-ledger', 'code'));
+        assert.ok(fs.existsSync(path.join(folderPath, 'REPORT.md')), 'REPORT.md must exist');
+        assert.ok(fs.existsSync(path.join(folderPath, 'DECISIONS.md')), 'DECISIONS.md must exist');
+        assert.equal(fs.existsSync(path.join(folderPath, 'README.md')), false);
+        assert.equal(fs.readFileSync(path.join(folderPath, 'REPORT.md'), 'utf8'), '# Code Execution Report');
+        assert.equal(fs.readFileSync(path.join(folderPath, 'DECISIONS.md'), 'utf8'), '# Execution Decision Records');
+    });
+});

package/dist/mcp/memory.d.ts

@@ -8,8 +8,9 @@ import { type ProjectSettings } from '../core/config/index.js';
  * Returns the MemoryIndexer so the caller can fire startupIndex() after server.connect().
  * Returns null when memory is disabled (settings.memory.enabled !== true).
  */
-export declare function registerMemoryTools(server: McpServer, settings: ProjectSettings, workspaceRoot: string, overrides?: {
+export declare function registerMemoryTools(server: McpServer, workspaceRoot: string, overrides?: {
     indexer?: MemoryIndexer;
     store?: MemoryStore;
     config?: MemoryConfig;
+    settings?: ProjectSettings;
 }): MemoryIndexer | null;

package/dist/mcp/memory.js

@@ -1,31 +1,30 @@
+import * as fs from 'fs';
 import * as path from 'path';
 import { z } from 'zod';
 import { Embedder } from '../services/memory/embedder.js';
 import { MemoryIndexer } from '../services/memory/indexer.js';
 import { MemoryStore } from '../services/memory/store.js';
+import { SOURCE_TYPES } from '../services/memory/types.js';
 import { initializeConversationDigestModel } from '../services/digest/processor.js';
 import { DEFAULT_DIGEST_MODEL_ID } from '../services/digest/constants.js';
-import { mcpJson, mcpText } from '../utils/utils.js';
-import { loadProjectSettings, resolveConversationDigestConfig, resolveMemoryConfig, } from '../core/config/index.js';
+import { formatError, mcpJson, mcpText } from '../utils/utils.js';
+import { loadGlobalSettings, resolveConversationDigestConfig, resolveMemoryConfig, } from '../core/config/index.js';
 /**
  * Registers tool handlers onto an already-constructed indexer/store pair.
  */
 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'),
+    server.tool('kit_memory_search', 'Search persistent memory for factual or semantic matches (decisions, concepts, entities). Extract concise keywords only, removing stopwords and filler words from the user request before querying. Use kit_memory_recent for temporal or recency questions.', {
+        query: z.string().min(1).describe('Keyword-only search query with stopwords removed'),
         top_k: z.number().int().positive().optional().describe('Number of results to return'),
     }, async ({ query, top_k }) => {
         try {
             const results = await indexer.search(query, top_k ?? config.topK);
-            if (results.length === 0) {
-                const degradedNote = !store.vecAvailable
-                    ? '⚠️ Vector search unavailable — showing keyword-only results.\n\n'
-                    : '';
-                return mcpText(`${degradedNote}No memories found for query: "${query}"`);
-            }
             const degradedNote = !store.vecAvailable
                 ? '⚠️ Vector search unavailable — showing keyword-only results.\n\n'
                 : '';
+            if (results.length === 0) {
+                return mcpText(`${degradedNote}No memories found for query: "${query}"`);
+            }
             const formatted = results
                 .map((r) => {
                 const displaySource = r.chunk.source.replace(/^compiled\//, '');
@@ -38,8 +37,34 @@ function registerMemoryToolHandlers(server, indexer, store, config, workspaceRoo
             return mcpText(`${degradedNote}${formatted}`);
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            return mcpText(`kit_memory_search failed: ${message}`);
+            return mcpText(`kit_memory_search failed: ${formatError(err)}`);
+        }
+    });
+    server.tool('kit_memory_recent', 'Return the N most recently updated memory sources. Optionally filter by source type. Use for temporal questions like "what did we do last session" or "recent".', {
+        n: z.number().int().positive().max(50).optional().describe('How many recent sources to return (default 5)'),
+        source_type: z.enum(SOURCE_TYPES).optional().describe('Optional source type filter'),
+    }, async ({ n, source_type }) => {
+        try {
+            const rows = store.getRecentSources({ limit: n ?? 5, sourceType: source_type });
+            if (rows.length === 0)
+                return mcpText('No recent sources found.');
+            const blocks = [];
+            for (const row of rows) {
+                try {
+                    const content = fs.readFileSync(path.join(config.wikiDir, row.source), 'utf8');
+                    const displaySource = row.source.replace(/^compiled\//, '');
+                    blocks.push(`### ${displaySource}\n${content}`);
+                }
+                catch (err) {
+                    console.warn(`[memory] Skipping unavailable recent source ${row.source}:`, err);
+                }
+            }
+            if (blocks.length === 0)
+                return mcpText('No recent sources found.');
+            return mcpText(blocks.join('\n\n---\n\n'));
+        }
+        catch (err) {
+            return mcpText(`kit_memory_recent failed: ${formatError(err)}`);
         }
     });
     server.tool('kit_memory_save', 'Save content to wiki/raw for inclusion after the next /wiki compile.', {
@@ -54,8 +79,10 @@ function registerMemoryToolHandlers(server, indexer, store, config, workspaceRoo
             });
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            return mcpJson({ saved: false, error: message });
+            return mcpJson({
+                saved: false,
+                error: formatError(err),
+            });
         }
     });
     server.tool('kit_memory_digest_init', 'Initialize or toggle local conversation digesting. Downloads/cache-loads the pinned local model only when explicitly invoked.', {
@@ -63,7 +90,7 @@ function registerMemoryToolHandlers(server, indexer, store, config, workspaceRoo
         enabled: z.boolean().optional().describe('Enable or disable conversation digesting'),
     }, async ({ model_id, enabled }) => {
         try {
-            const existingConfig = resolveConversationDigestConfig(loadProjectSettings(workspaceRoot));
+            const existingConfig = resolveConversationDigestConfig(loadGlobalSettings());
             const result = await initializeConversationDigestModel({
                 workspaceRoot,
                 modelId: model_id ?? existingConfig?.modelId ?? DEFAULT_DIGEST_MODEL_ID,
@@ -78,8 +105,7 @@ function registerMemoryToolHandlers(server, indexer, store, config, workspaceRoo
             });
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            return mcpJson({ initialized: false, error: message });
+            return mcpJson({ initialized: false, error: formatError(err) });
         }
     });
 }
@@ -88,7 +114,8 @@ function registerMemoryToolHandlers(server, indexer, store, config, workspaceRoo
  * Returns the MemoryIndexer so the caller can fire startupIndex() after server.connect().
  * Returns null when memory is disabled (settings.memory.enabled !== true).
  */
-export function registerMemoryTools(server, settings, workspaceRoot, overrides) {
+export function registerMemoryTools(server, workspaceRoot, overrides) {
+    const settings = overrides?.settings ?? loadGlobalSettings();
     if (settings.memory?.enabled !== true)
         return null;
     const config = overrides?.config ?? resolveMemoryConfig(settings, workspaceRoot);