@hanhnd/agent-kit 1.0.39 → 1.0.41

package/dist/cli.js

@@ -15195,6 +15195,22 @@ async function withTimeout(promise, timeoutMs, createError) {
     if (timer) clearTimeout(timer);
   }
 }
+async function mapLimit(items, limit, worker) {
+  if (items.length === 0) return [];
+  const concurrency = Math.max(1, Math.floor(limit));
+  const results = new Array(items.length);
+  let nextIndex = 0;
+  async function runWorker() {
+    while (nextIndex < items.length) {
+      const currentIndex = nextIndex;
+      nextIndex++;
+      results[currentIndex] = await worker(items[currentIndex], currentIndex);
+    }
+  }
+  const runners = Array.from({ length: Math.min(concurrency, items.length) }, () => runWorker());
+  await Promise.all(runners);
+  return results;
+}
 
 // src/utils/paths.ts
 import * as os2 from "os";
@@ -15912,9 +15928,19 @@ var MemoryIndexer = class {
   }
   _ready = false;
   async indexFile(absolutePath) {
-    return this.indexFileRelativeTo(absolutePath, this.config.wikiDir);
+    const mutation = await this.prepareIndexFileRelativeTo(absolutePath, this.config.wikiDir);
+    return this.commitPreparedMutation(mutation);
   }
-  async indexFileRelativeTo(absolutePath, sourceRoot) {
+  makeSkippedMutation(source, skipped) {
+    return {
+      source,
+      chunksToUpsert: [],
+      embeddings: [],
+      idsToDelete: [],
+      stats: { indexed: 0, deleted: 0, skipped }
+    };
+  }
+  async prepareIndexFileRelativeTo(absolutePath, sourceRoot) {
     const source = path8.relative(sourceRoot, absolutePath);
     const existingChunkIds = this.store.hashesBySource(source);
     let text;
@@ -15922,7 +15948,7 @@ var MemoryIndexer = class {
       text = await fs6.promises.readFile(absolutePath, "utf8");
     } catch (err) {
       console.warn(`[memory-indexer] Cannot read file ${absolutePath}:`, err);
-      return { indexed: 0, deleted: 0, skipped: existingChunkIds.size };
+      return this.makeSkippedMutation(source, existingChunkIds.size);
     }
     let fileMtimeAt;
     try {
@@ -15942,21 +15968,30 @@ var MemoryIndexer = class {
         embeddings = await this.embedder.embed(toIndex.map((c) => c.content));
       } catch (err) {
         console.warn(`[memory-indexer] Embedding failed for ${absolutePath}:`, err);
-        return { indexed: 0, deleted: 0, skipped: existingChunkIds.size };
+        return this.makeSkippedMutation(source, existingChunkIds.size);
       }
     }
-    if (toIndex.length > 0) {
-      this.store.upsert(toIndex, embeddings);
-    }
-    if (toDelete.length > 0) {
-      this.store.deleteByIds(toDelete);
-    }
     return {
-      indexed: toIndex.length,
-      deleted: toDelete.length,
-      skipped: allChunks.length - toIndex.length
+      source,
+      chunksToUpsert: toIndex,
+      embeddings,
+      idsToDelete: toDelete,
+      stats: {
+        indexed: toIndex.length,
+        deleted: toDelete.length,
+        skipped: allChunks.length - toIndex.length
+      }
     };
   }
+  commitPreparedMutation(mutation) {
+    if (mutation.chunksToUpsert.length > 0) {
+      this.store.upsert(mutation.chunksToUpsert, mutation.embeddings);
+    }
+    if (mutation.idsToDelete.length > 0) {
+      this.store.deleteByIds(mutation.idsToDelete);
+    }
+    return mutation.stats;
+  }
   async indexDirectory(rootDir, opts = {}) {
     const totals = { indexed: 0, deleted: 0, skipped: 0 };
     let rootExists;
@@ -15998,8 +16033,13 @@ var MemoryIndexer = class {
         totals.deleted += 1;
       }
     }
-    for (const file of files) {
-      const stats = await this.indexFileRelativeTo(file, relativeBase);
+    const preparedMutations = await mapLimit(
+      files,
+      opts.fileConcurrency ?? 2,
+      (file) => this.prepareIndexFileRelativeTo(file, relativeBase)
+    );
+    for (const mutation of preparedMutations) {
+      const stats = this.commitPreparedMutation(mutation);
       totals.indexed += stats.indexed;
       totals.deleted += stats.deleted;
       totals.skipped += stats.skipped;

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

@@ -1,6 +1,6 @@
-export declare const HANDOFF_TYPES: readonly ["brainstorm", "clarification", "plan", "ticket", "research", "scenario", "investigation", "code"];
+export declare const HANDOFF_TYPES: readonly ["brainstorm", "clarification", "plan", "ticket", "research", "investigation", "code"];
 type HandoffType = (typeof HANDOFF_TYPES)[number];
-type CanonicalHandoffType = 'brainstorm' | 'clarification' | 'plan' | 'ticket' | 'research' | 'scenario' | 'investigation' | 'code';
+type CanonicalHandoffType = 'brainstorm' | 'clarification' | 'plan' | 'ticket' | 'research' | 'investigation' | 'code';
 export interface SavedHandoffFolderLocation {
     featureSlug: string;
     canonicalType: CanonicalHandoffType;

package/dist/core/handoffs/index.js

@@ -5,7 +5,6 @@ export const HANDOFF_TYPES = [
     'plan',
     'ticket',
     'research',
-    'scenario',
     'investigation',
     'code',
 ];

package/dist/entrypoints/server.js

@@ -23,13 +23,13 @@ registerIntegrationTools(server);
 registerCoreTools(server);
 registerAgentTools(server);
 const workspaceRoot = getWorkspaceRoot();
-const memoryIndexer = registerMemoryTools(server, workspaceRoot);
+const memorySubsystem = registerMemoryTools(server, workspaceRoot);
 // ═══════════════════════════════════════════════════════════════
 // START SERVER
 // ═══════════════════════════════════════════════════════════════
 const transport = new StdioServerTransport();
 await server.connect(transport);
 // Fire-and-forget startup indexing — must run after server.connect
-if (memoryIndexer) {
-    void memoryIndexer.startupIndex();
+if (memorySubsystem) {
+    void memorySubsystem.startWarmup();
 }

package/dist/mcp/agent.js

@@ -49,11 +49,18 @@ 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 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 folder (e.g., ".agent-kit/handoffs/feature-slug/plan")'),
+    server.registerTool('kit_trigger_agent', {
+        title: 'Delegate to External Agent',
+        description: '!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).',
+        inputSchema: {
+            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 folder (e.g., ".agent-kit/handoffs/feature-slug/plan")'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
     }, async ({ agent, task }, extra) => {
         const workspaceRoot = getWorkspaceRoot();
         let job;

package/dist/mcp/core.js

@@ -46,14 +46,19 @@ export function registerCoreTools(server) {
     // 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 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'),
-        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 folder, e.g. "user-auth" or "PROJ-123". Do NOT append version numbers (v2, v3, etc.).'),
+    server.registerTool('kit_save_handoff', {
+        title: 'Save Handoff Artifact',
+        description: `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.`,
+        inputSchema: {
+            type: z.enum(HANDOFF_TYPES).describe('Handoff type'),
+            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 folder, e.g. "user-auth" or "PROJ-123". Do NOT append version numbers (v2, v3, etc.).'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, async (args) => handleSaveHandoff(args, getWorkspaceRoot()));
 }
 // Export DEFAULT_EXTENSIONS for backward compatibility

package/dist/mcp/integration.js

@@ -74,14 +74,19 @@ async function callRestApi(url, auth, accept = 'application/json') {
 }
 export function registerIntegrationTools(server) {
     // TOOL: GET BITBUCKET PR
-    server.tool('kit_get_bitbucket_pr', 'Get Bitbucket PR details and optionally the diff. Accepts a full PR URL or a numeric PR ID with workspace + repoSlug.', {
-        input: z.string().describe('Bitbucket PR URL or numeric PR ID'),
-        workspace: z
-            .string()
-            .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'),
+    server.registerTool('kit_get_bitbucket_pr', {
+        title: 'Get Bitbucket PR',
+        description: 'Get Bitbucket PR details and optionally the diff. Accepts a full PR URL or a numeric PR ID with workspace + repoSlug.',
+        inputSchema: {
+            input: z.string().describe('Bitbucket PR URL or numeric PR ID'),
+            workspace: z
+                .string()
+                .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'),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     }, async ({ input, workspace, repoSlug, includeDiff }) => {
         try {
             let ws;
@@ -145,8 +150,13 @@ ${pr.description || 'No description'}`;
         }
     });
     // TOOL: JIRA GET TICKET
-    server.tool('kit_jira_get_ticket', 'Get ticket details from Jira using the Atlassian REST API', {
-        ticketId: z.string().describe('Jira ticket ID (e.g., PROJ-123)'),
+    server.registerTool('kit_jira_get_ticket', {
+        title: 'Get Jira Ticket',
+        description: 'Get ticket details from Jira using the Atlassian REST API',
+        inputSchema: {
+            ticketId: z.string().describe('Jira ticket ID (e.g., PROJ-123)'),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     }, async ({ ticketId }) => {
         try {
             const safeTicketId = ticketId.match(/^[A-Z]+-\d+$/)?.[0];

package/dist/mcp/memory.d.ts

@@ -1,16 +1,11 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { MemoryIndexer } from '../services/memory/indexer.js';
-import { MemoryStore } from '../services/memory/store.js';
-import type { MemoryConfig } from '../services/memory/types.js';
+import { type MemorySubsystem, type MemorySubsystemOverrides } from '../services/memory/subsystem.js';
 import { type ProjectSettings } from '../core/config/index.js';
 /**
  * Initializes the memory subsystem and registers all memory tools.
- * Returns the MemoryIndexer so the caller can fire startupIndex() after server.connect().
+ * Returns the MemorySubsystem so the caller can fire startWarmup() after server.connect().
  * Returns null when memory is disabled (settings.memory.enabled !== true).
  */
-export declare function registerMemoryTools(server: McpServer, workspaceRoot: string, overrides?: {
-    indexer?: MemoryIndexer;
-    store?: MemoryStore;
-    config?: MemoryConfig;
+export declare function registerMemoryTools(server: McpServer, workspaceRoot: string, overrides?: MemorySubsystemOverrides & {
     settings?: ProjectSettings;
-}): MemoryIndexer | null;
+}): MemorySubsystem | null;

package/dist/mcp/memory.js

@@ -1,29 +1,38 @@
 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 { createMemorySubsystem, } from '../services/memory/subsystem.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 { formatError, mcpJson, mcpText } from '../utils/utils.js';
-import { loadGlobalSettings, resolveConversationDigestConfig, resolveMemoryConfig, } from '../core/config/index.js';
+import { loadGlobalSettings, resolveConversationDigestConfig } from '../core/config/index.js';
 /**
- * Registers tool handlers onto an already-constructed indexer/store pair.
+ * Registers tool handlers against the current memory subsystem state.
  */
-function registerMemoryToolHandlers(server, indexer, store, config, workspaceRoot = process.cwd()) {
-    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'),
+function registerMemoryToolHandlers(server, subsystem, workspaceRoot = process.cwd()) {
+    const { config } = subsystem;
+    server.registerTool('kit_memory_search', {
+        title: 'Search Memory',
+        description: '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.',
+        inputSchema: {
+            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'),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     }, async ({ query, top_k }) => {
         try {
+            if (!subsystem.indexer || !subsystem.store) {
+                return mcpText(formatInitializationFailure(subsystem));
+            }
+            const { indexer, store } = subsystem;
             const results = await indexer.search(query, top_k ?? config.topK);
+            const lifecycleNote = formatLifecycleNote(subsystem);
             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}"`);
+                return mcpText(`${lifecycleNote}${degradedNote}No memories found for query: "${query}"`);
             }
             const formatted = results
                 .map((r) => {
@@ -34,17 +43,26 @@ function registerMemoryToolHandlers(server, indexer, store, config, workspaceRoo
                 return `### ${displaySource} (score: ${r.score.toFixed(3)})\n${content}`;
             })
                 .join('\n\n---\n\n');
-            return mcpText(`${degradedNote}${formatted}`);
+            return mcpText(`${lifecycleNote}${degradedNote}${formatted}`);
         }
         catch (err) {
             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'),
+    server.registerTool('kit_memory_recent', {
+        title: 'Recent Memory Sources',
+        description: '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".',
+        inputSchema: {
+            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'),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     }, async ({ n, source_type }) => {
         try {
+            if (!subsystem.store) {
+                return mcpText(formatInitializationFailure(subsystem));
+            }
+            const store = subsystem.store;
             const rows = store.getRecentSources({ limit: n ?? 5, sourceType: source_type });
             if (rows.length === 0)
                 return mcpText('No recent sources found.');
@@ -67,10 +85,22 @@ function registerMemoryToolHandlers(server, indexer, store, config, workspaceRoo
             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.', {
-        content: z.string().min(1).describe('Content to save to memory'),
+    server.registerTool('kit_memory_save', {
+        title: 'Save to Memory',
+        description: 'Save content to wiki/raw for inclusion after the next /wiki compile.',
+        inputSchema: {
+            content: z.string().min(1).describe('Content to save to memory'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     }, async ({ content }) => {
         try {
+            if (!subsystem.indexer) {
+                return mcpJson({
+                    saved: false,
+                    error: formatInitializationFailure(subsystem),
+                });
+            }
+            const indexer = subsystem.indexer;
             await indexer.save(content);
             return mcpJson({
                 saved: true,
@@ -85,9 +115,14 @@ function registerMemoryToolHandlers(server, indexer, store, config, workspaceRoo
             });
         }
     });
-    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'),
+    server.registerTool('kit_memory_digest_init', {
+        title: 'Initialize Conversation Digest',
+        description: 'Initialize or toggle local conversation digesting. Downloads/cache-loads the pinned local model only when explicitly invoked.',
+        inputSchema: {
+            model_id: z.string().optional().describe('Digest model id'),
+            enabled: z.boolean().optional().describe('Enable or disable conversation digesting'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async ({ model_id, enabled }) => {
         try {
             const existingConfig = resolveConversationDigestConfig(loadGlobalSettings());
@@ -109,22 +144,31 @@ function registerMemoryToolHandlers(server, indexer, store, config, workspaceRoo
         }
     });
 }
+function formatLifecycleNote(subsystem) {
+    if (subsystem.status.state === 'warming' || subsystem.status.state === 'initializing') {
+        return '⚠️ Memory index is warming — results may be stale until startup indexing completes.\n\n';
+    }
+    if (subsystem.status.state === 'degraded') {
+        return `⚠️ Memory index is degraded${subsystem.status.error ? `: ${subsystem.status.error}` : ''}.\n\n`;
+    }
+    return '';
+}
+function formatInitializationFailure(subsystem) {
+    const detail = subsystem.status.error ? `: ${subsystem.status.error}` : '';
+    return `Memory initialization failed${detail}`;
+}
 /**
  * Initializes the memory subsystem and registers all memory tools.
- * Returns the MemoryIndexer so the caller can fire startupIndex() after server.connect().
+ * Returns the MemorySubsystem so the caller can fire startWarmup() after server.connect().
  * Returns null when memory is disabled (settings.memory.enabled !== true).
  */
 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);
-    const store = overrides?.store ?? new MemoryStore(path.join(config.wikiDir, 'index.db'), config);
-    const indexer = overrides?.indexer ??
-        (() => {
-            const embedder = new Embedder(config.embeddingModel);
-            return new MemoryIndexer(store, embedder, config);
-        })();
-    registerMemoryToolHandlers(server, indexer, store, config, workspaceRoot);
-    return indexer;
+    const subsystem = createMemorySubsystem(workspaceRoot, { ...overrides, settings });
+    if (!subsystem)
+        return null;
+    registerMemoryToolHandlers(server, subsystem, workspaceRoot);
+    return subsystem;
 }

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

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

package/dist/mcp/registration.test.js

@@ -0,0 +1,77 @@
+import * as assert from 'node:assert/strict';
+import { describe, test } from 'node:test';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { registerCoreTools } from './core.js';
+import { registerAgentTools } from './agent.js';
+import { registerIntegrationTools } from './integration.js';
+const EXPECTED_NON_MEMORY_TOOLS = [
+    'kit_save_handoff',
+    'kit_trigger_agent',
+    'kit_get_bitbucket_pr',
+    'kit_jira_get_ticket',
+];
+async function buildClientWithTools() {
+    const server = new McpServer({ name: 'test-kit', version: '0.0.0' });
+    registerIntegrationTools(server);
+    registerCoreTools(server);
+    registerAgentTools(server);
+    const [serverTransport, clientTransport] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: 'test-client', version: '0.0.0' });
+    await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+    return client;
+}
+describe('MCP tool registration smoke tests', () => {
+    test('R1: all 4 non-memory tool names are registered', async () => {
+        const client = await buildClientWithTools();
+        const { tools } = await client.listTools();
+        const names = tools.map((t) => t.name);
+        for (const expected of EXPECTED_NON_MEMORY_TOOLS) {
+            assert.ok(names.includes(expected), `expected tool "${expected}" to be registered, got: ${names.join(', ')}`);
+        }
+    });
+    test('R2: each non-memory tool has a non-empty description and inputSchema (BC3)', async () => {
+        const client = await buildClientWithTools();
+        const { tools } = await client.listTools();
+        const byName = Object.fromEntries(tools.map((t) => [t.name, t]));
+        for (const name of EXPECTED_NON_MEMORY_TOOLS) {
+            const tool = byName[name];
+            assert.ok(tool, `tool "${name}" not found`);
+            assert.ok(tool.description && tool.description.length > 0, `tool "${name}" must have a non-empty description`);
+            assert.ok(tool.inputSchema, `tool "${name}" must have an inputSchema`);
+        }
+    });
+    test('R3: kit_trigger_agent (readOnlyHint:false) has correct annotations (BC5)', async () => {
+        const client = await buildClientWithTools();
+        const { tools } = await client.listTools();
+        const tool = tools.find((t) => t.name === 'kit_trigger_agent');
+        assert.ok(tool, 'kit_trigger_agent must be registered');
+        assert.ok(tool.annotations, 'kit_trigger_agent must have annotations');
+        assert.equal(tool.annotations.readOnlyHint, false, 'readOnlyHint must be false');
+        assert.equal(tool.annotations.destructiveHint, true, 'destructiveHint must be true');
+        assert.equal(tool.annotations.idempotentHint, false, 'idempotentHint must be false');
+        assert.equal(tool.annotations.openWorldHint, true, 'openWorldHint must be true');
+    });
+    test('R4: kit_save_handoff (readOnlyHint:false) has correct annotations (BC5)', async () => {
+        const client = await buildClientWithTools();
+        const { tools } = await client.listTools();
+        const tool = tools.find((t) => t.name === 'kit_save_handoff');
+        assert.ok(tool, 'kit_save_handoff must be registered');
+        assert.ok(tool.annotations, 'kit_save_handoff must have annotations');
+        assert.equal(tool.annotations.readOnlyHint, false, 'readOnlyHint must be false');
+        assert.equal(tool.annotations.destructiveHint, false, 'destructiveHint must be false');
+        assert.equal(tool.annotations.idempotentHint, true, 'idempotentHint must be true');
+        assert.equal(tool.annotations.openWorldHint, false, 'openWorldHint must be false');
+    });
+    test('R5: kit_get_bitbucket_pr (readOnlyHint:true) has correct annotations (BC5)', async () => {
+        const client = await buildClientWithTools();
+        const { tools } = await client.listTools();
+        const tool = tools.find((t) => t.name === 'kit_get_bitbucket_pr');
+        assert.ok(tool, 'kit_get_bitbucket_pr must be registered');
+        assert.ok(tool.annotations, 'kit_get_bitbucket_pr must have annotations');
+        assert.equal(tool.annotations.readOnlyHint, true, 'readOnlyHint must be true');
+        assert.equal(tool.annotations.idempotentHint, true, 'idempotentHint must be true');
+        assert.equal(tool.annotations.openWorldHint, true, 'openWorldHint must be true');
+    });
+});