@hanhnd/agent-kit 1.0.0

package/dist/tools/agent.d.ts

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

package/dist/tools/agent.js

@@ -0,0 +1,188 @@
+/**
+ * Agent Delegation Tools - Invoke external agent CLIs (Gemini, Claude)
+ * Supports handoff file injection and automatic fallback
+ */
+import { spawn } from 'child_process';
+import { randomUUID } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { z } from 'zod';
+import { getWorkspaceRoot } from '../utils.js';
+import { commandExists, validatePath } from './security.js';
+// Configurable timeout via environment variable (default: 5 minutes)
+const AGENT_TIMEOUT = parseInt(process.env.KIT_AGENT_TIMEOUT || '300000', 10);
+const jobRegistry = new Map();
+/**
+ * Generate a URL-safe slug from a task string (first ~6 words, max 48 chars)
+ */
+function taskSlug(task) {
+    return task
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, '')
+        .trim()
+        .split(/\s+/)
+        .slice(0, 6)
+        .join('-')
+        .slice(0, 48);
+}
+/**
+ * Initialize a live-streaming log file for an agent job.
+ * Writes the header synchronously so the file exists immediately,
+ * then opens an append-mode WriteStream for real-time chunk writing.
+ */
+function initAgentLog(workspaceRoot, slug, agent) {
+    const logsDir = path.join(workspaceRoot, '.agent-kit', 'logs', 'agents');
+    fs.mkdirSync(logsDir, { recursive: true });
+    const logFile = path.join(logsDir, `delegate-${slug}.log`);
+    const header = `Agent: ${agent}\nDate: ${new Date().toISOString()}\n${'─'.repeat(60)}\n\n`;
+    fs.writeFileSync(logFile, header, 'utf-8');
+    const logStream = fs.createWriteStream(logFile, { flags: 'a' });
+    logStream.on('error', () => { });
+    return { logPath: path.relative(workspaceRoot, logFile), logStream };
+}
+/**
+ * Register agent delegation tools with MCP server
+ */
+export function registerAgentTools(server) {
+    // ═══════════════════════════════════════════════════════════════
+    // TOOL: TRIGGER AGENT
+    // Delegates a task to an external agent CLI (gemini or claude).
+    // Auto-detects if task is a file path and reads it as context.
+    // Falls back to the alternate agent if requested one is missing.
+    // ═══════════════════════════════════════════════════════════════
+    server.tool('kit_trigger_agent', 'Delegate a task to an external agent CLI (gemini or claude). The task can be a direct message or a path to a handoff file (.agent-kit/handoffs/plans/plan-xyz.md). Falls back to the other agent CLI if the requested one is not installed.', {
+        agent: z.enum(['gemini', 'claude']).describe('The agent CLI to invoke: "gemini" or "claude"'),
+        task: z
+            .string()
+            .describe('Task message or path to a handoff file (e.g., ".agent-kit/handoffs/plans/plan-xyz.md")'),
+    }, async ({ agent, task }) => {
+        try {
+            const workspaceRoot = getWorkspaceRoot();
+            // Detect if task is a file path — resolve and read if it exists
+            let prompt = task;
+            const resolvedTask = path.resolve(workspaceRoot, task);
+            if (fs.existsSync(resolvedTask) && fs.statSync(resolvedTask).isFile()) {
+                try {
+                    validatePath(task, workspaceRoot);
+                    prompt = fs.readFileSync(resolvedTask, 'utf-8');
+                }
+                catch (err) {
+                    return {
+                        content: [{ type: 'text', text: `Error reading task file: ${err}` }],
+                    };
+                }
+            }
+            // Determine which agent to use — fallback if requested not available
+            let usedAgent = agent;
+            let fallbackReason;
+            if (!commandExists(agent)) {
+                const fallback = agent === 'gemini' ? 'claude' : 'gemini';
+                if (commandExists(fallback)) {
+                    usedAgent = fallback;
+                    fallbackReason = `${agent} CLI not installed, fell back to ${fallback}`;
+                }
+                else {
+                    const installHint = agent === 'gemini'
+                        ? 'Install Gemini CLI: https://github.com/google-gemini/gemini-cli'
+                        : 'Install Claude CLI: npm install -g @anthropic-ai/claude-code';
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    agent,
+                                    status: 'error',
+                                    output: '',
+                                    error: `Neither ${agent} nor the fallback agent CLI is installed. ${installHint}`,
+                                }, null, 2),
+                            },
+                        ],
+                    };
+                }
+            }
+            // Execute the agent CLI with the prompt
+            // Gemini: -y (--yolo) for auto-accept, -p for headless prompt
+            // Claude: --dangerously-skip-permissions for auto-accept, -p/--print for headless
+            const agentArgs = usedAgent === 'gemini'
+                ? ['-y', '-p', prompt]
+                : ['--dangerously-skip-permissions', '-p', prompt];
+            const slug = taskSlug(task);
+            const { logPath, logStream } = initAgentLog(workspaceRoot, slug, usedAgent);
+            const jobId = randomUUID();
+            const child = spawn(usedAgent, agentArgs, {
+                cwd: workspaceRoot,
+                env: { ...process.env, GEMINI_WORKSPACE: workspaceRoot },
+            });
+            const job = {
+                id: jobId,
+                agent: usedAgent,
+                process: child,
+                startedAt: new Date(),
+                chunks: [],
+                logStream,
+                timeoutHandle: setTimeout(() => {
+                    child.kill('SIGTERM');
+                }, AGENT_TIMEOUT),
+            };
+            jobRegistry.set(jobId, job);
+            try {
+                await new Promise((resolve, reject) => {
+                    child.stdout?.on('data', (data) => {
+                        job.chunks.push(data.toString());
+                        job.logStream.write(data);
+                    });
+                    child.stderr?.on('data', (data) => {
+                        job.chunks.push(data.toString());
+                        job.logStream.write(data);
+                    });
+                    child.on('close', (code) => {
+                        if (code === 0)
+                            resolve();
+                        else
+                            reject(new Error(`Process exited with code ${code}`));
+                    });
+                    child.on('error', reject);
+                });
+                const output = job.chunks.join('');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                agent: usedAgent,
+                                status: fallbackReason ? 'fallback' : 'success',
+                                log: logPath,
+                                output,
+                                ...(fallbackReason && { fallback_reason: fallbackReason }),
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                throw error;
+            }
+            finally {
+                job.logStream.end();
+                clearTimeout(job.timeoutHandle);
+                jobRegistry.delete(jobId);
+            }
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            agent,
+                            status: 'error',
+                            output: '',
+                            error: msg,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+    });
+}

package/dist/tools/config.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Configuration utilities
+ * Shared configuration constants and loaders
+ */
+/**
+ * Default file extensions - expanded to support more languages
+ * Used by kit_get_project_context and other tools
+ */
+export declare const DEFAULT_EXTENSIONS: string[];
+/**
+ * Project settings interface
+ */
+export interface ProjectSettings {
+    fileExtensions?: string[];
+    [key: string]: unknown;
+}
+/**
+ * Get file extensions - from settings.json or defaults
+ * 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;

package/dist/tools/config.js

@@ -0,0 +1,60 @@
+/**
+ * Configuration utilities
+ * Shared configuration constants and loaders
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Default file extensions - expanded to support more languages
+ * Used by kit_get_project_context and other tools
+ */
+export const DEFAULT_EXTENSIONS = [
+    '.ts',
+    '.js',
+    '.tsx',
+    '.jsx', // JavaScript/TypeScript
+    '.py', // Python
+    '.go', // Go
+    '.rs', // Rust
+    '.java',
+    '.kt', // Java/Kotlin
+    '.cpp',
+    '.c',
+    '.h',
+    '.hpp', // C/C++
+    '.php', // PHP
+    '.rb', // Ruby
+    '.swift', // Swift
+    '.vue',
+    '.svelte', // Frontend frameworks
+    '.json',
+    '.yaml',
+    '.yml', // Config files
+    '.md', // Documentation
+];
+/**
+ * Get file extensions - from settings.json or defaults
+ * Allows project-specific customization
+ */
+export function getFileExtensions(projectDir) {
+    const settings = loadProjectSettings(projectDir);
+    if (settings.fileExtensions && Array.isArray(settings.fileExtensions)) {
+        return settings.fileExtensions;
+    }
+    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)) {
+        try {
+            return JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+        }
+        catch (error) {
+            console.error(`[agent-kit] Warning: Failed to parse ${settingsPath}:`, error);
+        }
+    }
+    return {};
+}

package/dist/tools/core.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Core Tools - Extension info and handoff persistence
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { DEFAULT_EXTENSIONS } from './config.js';
+/**
+ * Register core tools with MCP server
+ */
+export declare function registerCoreTools(server: McpServer): void;
+export { DEFAULT_EXTENSIONS };

package/dist/tools/core.js

@@ -0,0 +1,76 @@
+/**
+ * Core Tools - Extension info and handoff persistence
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { z } from 'zod';
+import { getExtensionRoot, getWorkspaceRoot } from '../utils.js';
+import { DEFAULT_EXTENSIONS } from './config.js';
+/**
+ * Register core tools with MCP server
+ */
+export function registerCoreTools(server) {
+    // ═══════════════════════════════════════════════════════════════
+    // TOOL: GET EXTENSION INFO
+    // Returns absolute paths so agents can use native Read tool
+    // for loading agent personas and skill files
+    // ═══════════════════════════════════════════════════════════════
+    server.tool('kit_get_extension_info', 'Get absolute paths to the agent-kit extension directories (agents, skills, commands, scripts). Use the returned paths with the native Read tool to load agent personas and skill modules.', {}, async () => {
+        try {
+            const root = getExtensionRoot();
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            extensionRoot: root,
+                            agentsDir: path.join(root, 'agents'),
+                            skillsDir: path.join(root, 'skills'),
+                            commandsDir: path.join(root, 'commands'),
+                            scriptsDir: path.join(root, 'scripts'),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `Error getting extension info: ${error}` }],
+            };
+        }
+    });
+    // ═══════════════════════════════════════════════════════════════
+    // TOOL: SAVE HANDOFF
+    // Writes brainstorm/plan/ticket artifacts to the workspace
+    // Returns the saved file path for use in next-step instructions
+    // ═══════════════════════════════════════════════════════════════
+    server.tool('kit_save_handoff', 'Save a brainstorm, plan, or ticket handoff artifact to .agent-kit/handoffs/. Returns the saved file path to use in next-step instructions.', {
+        type: z.enum(['brainstorm', 'plan', 'ticket']).describe('Handoff type'),
+        content: z.string().describe('Full markdown content to save'),
+        slug: z
+            .string()
+            .describe('Short identifier for the filename, e.g. "user-auth" or "PROJ-123"'),
+    }, async ({ type, content, slug }) => {
+        try {
+            const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+            const safeSlug = slug.replace(/[^a-zA-Z0-9-_]/g, '-').toLowerCase();
+            const filename = `${type}-${timestamp}-${safeSlug}.md`;
+            const handoffDir = path.join(getWorkspaceRoot(), '.agent-kit', 'handoffs', `${type}s`);
+            if (!fs.existsSync(handoffDir)) {
+                fs.mkdirSync(handoffDir, { recursive: true });
+            }
+            const filePath = path.join(handoffDir, filename);
+            fs.writeFileSync(filePath, content, 'utf8');
+            return {
+                content: [{ type: 'text', text: `✅ Saved to: ${filePath}` }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: `Error saving handoff: ${error}` }],
+            };
+        }
+    });
+}
+// Export DEFAULT_EXTENSIONS for backward compatibility
+export { DEFAULT_EXTENSIONS };

package/dist/tools/gemini.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Agent Delegation Tools - Invoke external agent CLIs (Gemini, Claude)
+ * Supports handoff file injection and automatic fallback
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Register agent delegation tools with MCP server
+ */
+export declare function registerGeminiTools(server: McpServer): void;

package/dist/tools/gemini.js

@@ -0,0 +1,111 @@
+/**
+ * Agent Delegation Tools - Invoke external agent CLIs (Gemini, Claude)
+ * Supports handoff file injection and automatic fallback
+ */
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { z } from 'zod';
+import { getWorkspaceRoot } from '../utils.js';
+import { commandExists, validatePath } from './security.js';
+// Configurable timeout via environment variable (default: 5 minutes)
+const AGENT_TIMEOUT = parseInt(process.env.KIT_AGENT_TIMEOUT || '300000', 10);
+/**
+ * Register agent delegation tools with MCP server
+ */
+export function registerGeminiTools(server) {
+    // ═══════════════════════════════════════════════════════════════
+    // TOOL: TRIGGER AGENT
+    // Delegates a task to an external agent CLI (gemini or claude).
+    // Auto-detects if task is a file path and reads it as context.
+    // Falls back to the alternate agent if requested one is missing.
+    // ═══════════════════════════════════════════════════════════════
+    server.tool('kit_trigger_agent', 'Delegate a task to an external agent CLI (gemini or claude). The task can be a direct message or a path to a handoff file (.agent-kit/handoffs/plans/plan-xyz.md). Falls back to the other agent CLI if the requested one is not installed.', {
+        agent: z.enum(['gemini', 'claude']).describe('The agent CLI to invoke: "gemini" or "claude"'),
+        task: z
+            .string()
+            .describe('Task message or path to a handoff file (e.g., ".agent-kit/handoffs/plans/plan-xyz.md")'),
+    }, async ({ agent, task }) => {
+        try {
+            const workspaceRoot = getWorkspaceRoot();
+            // Detect if task is a file path — resolve and read if it exists
+            let prompt = task;
+            const resolvedTask = path.resolve(workspaceRoot, task);
+            if (fs.existsSync(resolvedTask) && fs.statSync(resolvedTask).isFile()) {
+                try {
+                    validatePath(task, workspaceRoot);
+                    prompt = fs.readFileSync(resolvedTask, 'utf-8');
+                }
+                catch (err) {
+                    return {
+                        content: [{ type: 'text', text: `Error reading task file: ${err}` }],
+                    };
+                }
+            }
+            // Determine which agent to use — fallback if requested not available
+            let usedAgent = agent;
+            let fallbackReason;
+            if (!commandExists(agent)) {
+                const fallback = agent === 'gemini' ? 'claude' : 'gemini';
+                if (commandExists(fallback)) {
+                    usedAgent = fallback;
+                    fallbackReason = `${agent} CLI not installed, fell back to ${fallback}`;
+                }
+                else {
+                    const installHint = agent === 'gemini'
+                        ? 'Install Gemini CLI: https://github.com/google-gemini/gemini-cli'
+                        : 'Install Claude CLI: npm install -g @anthropic-ai/claude-code';
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    agent,
+                                    status: 'error',
+                                    output: '',
+                                    error: `Neither ${agent} nor the fallback agent CLI is installed. ${installHint}`,
+                                }, null, 2),
+                            },
+                        ],
+                    };
+                }
+            }
+            // Execute the agent CLI with the prompt
+            const output = execFileSync(usedAgent, ['-p', prompt], {
+                encoding: 'utf8',
+                timeout: AGENT_TIMEOUT,
+                maxBuffer: 10 * 1024 * 1024, // 10MB
+                cwd: workspaceRoot,
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            agent: usedAgent,
+                            status: fallbackReason ? 'fallback' : 'success',
+                            output,
+                            ...(fallbackReason && { fallback_reason: fallbackReason }),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            agent,
+                            status: 'error',
+                            output: '',
+                            error: msg,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+    });
+}

package/dist/tools/integration.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Integration Tools - Bitbucket, Jira
+ * Tools: kit_get_bitbucket_pr, kit_jira_get_ticket
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerIntegrationTools(server: McpServer): void;