@hanhnd/agent-kit 1.0.16 → 1.0.18

package/dist/tools/agent.d.ts

@@ -3,7 +3,4 @@
  * 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

@@ -7,14 +7,11 @@ import { randomUUID } from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
 import { z } from 'zod';
-import { getWorkspaceRoot } from '../utils/utils.js';
+import { getWorkspaceRoot, mcpJson, mcpText } from '../utils/utils.js';
 import { commandExists, sanitizeOutput, 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()
@@ -25,11 +22,6 @@ function taskSlug(task) {
         .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 });
@@ -41,25 +33,19 @@ function initAgentLog(workspaceRoot, slug, agent) {
     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', '!Important: Trigger only when user explicitly asks to 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 }) => {
+    }, async ({ agent, task }, extra) => {
+        const workspaceRoot = getWorkspaceRoot();
+        let job;
+        let logPath;
+        let killChild;
         try {
-            const workspaceRoot = getWorkspaceRoot();
-            // Detect if task is a file path — resolve and read if it exists
+            // Resolve task: read file if path, otherwise use as-is
             let prompt = task;
             const resolvedTask = path.resolve(workspaceRoot, task);
             if (fs.existsSync(resolvedTask) && fs.statSync(resolvedTask).isFile()) {
@@ -68,12 +54,10 @@ export function registerAgentTools(server) {
                     prompt = fs.readFileSync(resolvedTask, 'utf-8');
                 }
                 catch (err) {
-                    return {
-                        content: [{ type: 'text', text: `Error reading task file: ${err}` }],
-                    };
+                    return mcpText(`Error reading task file: ${err}`);
                 }
             }
-            // Determine which agent to use — fallback if requested not available
+            // Resolve agent with fallback
             let usedAgent = agent;
             let fallbackReason;
             if (!commandExists(agent)) {
@@ -86,105 +70,87 @@ export function registerAgentTools(server) {
                     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),
-                            },
-                        ],
-                    };
+                    return mcpJson({
+                        agent,
+                        status: 'error',
+                        output: '',
+                        error: `Neither ${agent} nor the fallback agent CLI is installed. ${installHint}`,
+                    });
                 }
             }
-            // 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 { logPath: lp, logStream } = initAgentLog(workspaceRoot, taskSlug(task), usedAgent);
+            logPath = lp;
             const jobId = randomUUID();
             const child = spawn(usedAgent, agentArgs, {
                 cwd: workspaceRoot,
                 env: { ...process.env, GEMINI_WORKSPACE: workspaceRoot },
             });
-            const job = {
-                id: jobId,
+            job = {
                 agent: usedAgent,
                 process: child,
                 startedAt: new Date(),
                 chunks: [],
                 logStream,
-                timeoutHandle: setTimeout(() => {
-                    child.kill('SIGTERM');
-                }, AGENT_TIMEOUT),
+                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);
+            // Kill child if the MCP request is cancelled (e.g. user presses ESC)
+            killChild = () => {
+                child.kill('SIGTERM');
+                setTimeout(() => child.kill('SIGKILL'), 5000).unref();
+            };
+            if (extra.signal.aborted)
+                killChild();
+            else
+                extra.signal.addEventListener('abort', killChild);
+            await new Promise((resolve, reject) => {
+                child.stdout?.on('data', (data) => {
+                    job.chunks.push(data.toString());
+                    job.logStream.write(data);
                 });
-                const output = job.chunks.join('');
-                const safeOutput = sanitizeOutput(output);
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: JSON.stringify({
-                                agent: usedAgent,
-                                status: fallbackReason ? 'fallback' : 'success',
-                                log: logPath,
-                                output: safeOutput,
-                                ...(fallbackReason && { fallback_reason: fallbackReason }),
-                            }, null, 2),
-                        },
-                    ],
-                };
-            }
-            catch (error) {
-                throw error;
-            }
-            finally {
-                job.logStream.end();
-                clearTimeout(job.timeoutHandle);
-                jobRegistry.delete(jobId);
-            }
+                child.stderr?.on('data', (data) => {
+                    job.chunks.push(data.toString());
+                    job.logStream.write(data);
+                });
+                child.on('close', (code, signal) => {
+                    if (code === 0)
+                        resolve();
+                    else
+                        reject(new Error(`Process exited with code ${code}${signal ? ` (signal: ${signal})` : ''}`));
+                });
+                child.on('error', reject);
+            });
+            return mcpJson({
+                agent: usedAgent,
+                status: fallbackReason ? 'fallback' : 'success',
+                log: logPath,
+                output: sanitizeOutput(job.chunks.join('')),
+                ...(fallbackReason && { fallback_reason: fallbackReason }),
+            });
         }
         catch (error) {
+            if (extra.signal.aborted) {
+                return mcpJson({
+                    agent,
+                    status: 'cancelled',
+                    log: logPath,
+                    output: sanitizeOutput(job?.chunks.join('') ?? ''),
+                });
+            }
             const msg = error instanceof Error ? error.message : String(error);
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            agent,
-                            status: 'error',
-                            output: '',
-                            error: msg,
-                        }, null, 2),
-                    },
-                ],
-            };
+            return mcpJson({ agent, status: 'error', output: '', error: msg });
+        }
+        finally {
+            if (killChild)
+                extra.signal.removeEventListener('abort', killChild);
+            job?.logStream.end();
+            if (job)
+                clearTimeout(job.timeoutHandle);
         }
     });
 }

package/dist/tools/core.js

@@ -4,7 +4,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { z } from 'zod';
-import { getWorkspaceRoot } from '../utils/utils.js';
+import { getWorkspaceRoot, mcpText } from '../utils/utils.js';
 import { DEFAULT_EXTENSIONS } from './config.js';
 /**
  * Register core tools with MCP server
@@ -32,14 +32,10 @@ export function registerCoreTools(server) {
             }
             const filePath = path.join(handoffDir, filename);
             fs.writeFileSync(filePath, content, 'utf8');
-            return {
-                content: [{ type: 'text', text: `✅ Saved to: ${filePath}` }],
-            };
+            return mcpText(`✅ Saved to: ${filePath}`);
         }
         catch (error) {
-            return {
-                content: [{ type: 'text', text: `Error saving handoff: ${error}` }],
-            };
+            return mcpText(`Error saving handoff: ${error}`);
         }
     });
 }

package/dist/tools/integration.js

@@ -5,6 +5,7 @@
 import { writeFileSync } from 'fs';
 import { z } from 'zod';
 import { getCredential } from '../utils/credentials.js';
+import { mcpText } from '../utils/utils.js';
 import { adfToMarkdown } from '../utils/parser.js';
 import { sanitize } from './security.js';
 // Zod schema for Bitbucket PR REST API response
@@ -54,63 +55,22 @@ const JiraTicketSchema = z.object({
     errorMessages: z.array(z.string()).optional(),
     fields: JiraFieldsSchema,
 });
-function buildJiraBasicAuth() {
-    const email = getCredential('ATLASSIAN_USER_EMAIL');
-    const token = getCredential('ATLASSIAN_API_TOKEN');
-    if (!email || !token) {
-        throw new Error('Missing ATLASSIAN_USER_EMAIL or ATLASSIAN_API_TOKEN');
-    }
+function buildBasicAuth(emailVar, tokenVar) {
+    const email = getCredential(emailVar);
+    const token = getCredential(tokenVar);
+    if (!email || !token)
+        throw new Error(`Missing ${emailVar} or ${tokenVar}`);
     return 'Basic ' + Buffer.from(`${email}:${token}`).toString('base64');
 }
-function buildBitbucketBasicAuth() {
-    const email = getCredential('BITBUCKET_USER_EMAIL');
-    const token = getCredential('BITBUCKET_API_TOKEN');
-    if (!email || !token) {
-        throw new Error('Missing BITBUCKET_USER_EMAIL or BITBUCKET_API_TOKEN');
-    }
-    return 'Basic ' + Buffer.from(`${email}:${token}`).toString('base64');
-}
-async function callAtlassianRestApi(url) {
-    const auth = buildJiraBasicAuth();
-    const resp = await fetch(url, { headers: { Authorization: auth, Accept: 'application/json' } });
-    if (resp.status === 401) {
-        throw new Error('❌ Auth failed: check ATLASSIAN_USER_EMAIL and ATLASSIAN_API_TOKEN');
-    }
-    if (resp.status === 404) {
-        throw new Error(`❌ Not found: ${url}`);
-    }
-    if (!resp.ok) {
-        throw new Error(`❌ API error ${resp.status}: ${await resp.text()}`);
-    }
-    return await resp.json();
-}
-async function callBitbucketRestApi(url) {
-    const auth = buildBitbucketBasicAuth();
-    const resp = await fetch(url, { headers: { Authorization: auth, Accept: 'application/json' } });
-    if (resp.status === 401) {
-        throw new Error('❌ Auth failed: check BITBUCKET_USER_EMAIL and BITBUCKET_API_TOKEN');
-    }
-    if (resp.status === 404) {
-        throw new Error(`❌ Not found: ${url}`);
-    }
-    if (!resp.ok) {
-        throw new Error(`❌ API error ${resp.status}: ${await resp.text()}`);
-    }
-    return await resp.json();
-}
-async function callBitbucketDiffApi(url) {
-    const auth = buildBitbucketBasicAuth();
-    const resp = await fetch(url, { headers: { Authorization: auth, Accept: 'text/plain' } });
-    if (resp.status === 401) {
-        throw new Error('❌ Auth failed: check BITBUCKET_USER_EMAIL and BITBUCKET_API_TOKEN');
-    }
-    if (resp.status === 404) {
+async function callRestApi(url, auth, accept = 'application/json') {
+    const resp = await fetch(url, { headers: { Authorization: auth, Accept: accept } });
+    if (resp.status === 401)
+        throw new Error(`❌ Auth failed (401): ${url}`);
+    if (resp.status === 404)
         throw new Error(`❌ Not found: ${url}`);
-    }
-    if (!resp.ok) {
+    if (!resp.ok)
         throw new Error(`❌ API error ${resp.status}: ${await resp.text()}`);
-    }
-    return await resp.text();
+    return accept === 'text/plain' ? resp.text() : resp.json();
 }
 export function registerIntegrationTools(server) {
     // TOOL: GET BITBUCKET PR
@@ -128,22 +88,9 @@ export function registerIntegrationTools(server) {
             .describe('Include unified diff in response'),
     }, async ({ input, workspace, repoSlug, includeDiff }) => {
         try {
-            const bbEmail = getCredential('BITBUCKET_USER_EMAIL');
-            const bbToken = getCredential('BITBUCKET_API_TOKEN');
-            if (!bbEmail || !bbToken) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `❌ Missing BITBUCKET_USER_EMAIL or BITBUCKET_API_TOKEN. Set them in ~/.claude/agent-kit or as environment variables.`,
-                        },
-                    ],
-                };
-            }
             let ws;
             let repo;
             let prId;
-            // Try URL parse
             const urlMatch = input.match(/bitbucket\.org\/([^/]+)\/([^/]+)\/pull-requests\/(\d+)/);
             if (urlMatch) {
                 ws = urlMatch[1];
@@ -156,29 +103,16 @@ export function registerIntegrationTools(server) {
                 repo = repoSlug;
             }
             if (!ws) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `❌ workspace is required. Pass it as a parameter or set BITBUCKET_DEFAULT_WORKSPACE in your MCP env config.`,
-                        },
-                    ],
-                };
+                return mcpText(`❌ workspace is required. Pass it as a parameter or set BITBUCKET_DEFAULT_WORKSPACE in your MCP env config.`);
             }
             if (!repo || !prId) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `❌ Could not parse PR URL. Expected: bitbucket.org/{ws}/{repo}/pull-requests/{id}`,
-                        },
-                    ],
-                };
+                return mcpText(`❌ Could not parse PR URL. Expected: bitbucket.org/{ws}/{repo}/pull-requests/{id}`);
             }
             const safeWs = sanitize(ws);
             const safeRepo = sanitize(repo);
+            const auth = buildBasicAuth('BITBUCKET_USER_EMAIL', 'BITBUCKET_API_TOKEN');
             const prUrl = `https://api.bitbucket.org/2.0/repositories/${safeWs}/${safeRepo}/pullrequests/${prId}`;
-            const jsonData = await callBitbucketRestApi(prUrl);
+            const jsonData = await callRestApi(prUrl, auth);
             const parseResult = BitbucketPrSchema.safeParse(jsonData);
             if (!parseResult.success) {
                 throw new Error(`Failed to parse PR response: ${parseResult.error.message}`);
@@ -192,7 +126,7 @@ export function registerIntegrationTools(server) {
 ${pr.description || 'No description'}`;
             if (includeDiff) {
                 const diffUrl = `https://api.bitbucket.org/2.0/repositories/${safeWs}/${safeRepo}/pullrequests/${prId}/diff`;
-                const diff = await callBitbucketDiffApi(diffUrl);
+                const diff = (await callRestApi(diffUrl, auth, 'text/plain'));
                 const DIFF_FILE_THRESHOLD = 50_000;
                 if (diff.length < DIFF_FILE_THRESHOLD) {
                     output += `\n\n### Diff\n\`\`\`diff\n${diff}\n\`\`\``;
@@ -208,11 +142,10 @@ ${pr.description || 'No description'}`;
                     }
                 }
             }
-            return { content: [{ type: 'text', text: output }] };
+            return mcpText(output);
         }
         catch (error) {
-            const errorMsg = error instanceof Error ? error.message : String(error);
-            return { content: [{ type: 'text', text: errorMsg }] };
+            return mcpText(error instanceof Error ? error.message : String(error));
         }
     });
     // TOOL: JIRA GET TICKET
@@ -220,60 +153,23 @@ ${pr.description || 'No description'}`;
         ticketId: z.string().describe('Jira ticket ID (e.g., PROJ-123)'),
     }, async ({ ticketId }) => {
         try {
-            const cloudId = getCredential('ATLASSIAN_CLOUD_ID');
-            const userEmail = getCredential('ATLASSIAN_USER_EMAIL');
-            const apiToken = getCredential('ATLASSIAN_API_TOKEN');
-            if (!cloudId || !userEmail || !apiToken) {
-                const missing = [
-                    !cloudId && 'ATLASSIAN_CLOUD_ID',
-                    !userEmail && 'ATLASSIAN_USER_EMAIL',
-                    !apiToken && 'ATLASSIAN_API_TOKEN',
-                ]
-                    .filter(Boolean)
-                    .join(', ');
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `❌ Missing ${missing}. Create an API Token at id.atlassian.com/manage-profile/security/api-tokens.`,
-                        },
-                    ],
-                };
-            }
             const safeTicketId = ticketId.match(/^[A-Z]+-\d+$/)?.[0];
             if (!safeTicketId) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `❌ Invalid ticket ID format: ${ticketId}\n\nExpected format: PROJ-123`,
-                        },
-                    ],
-                };
+                return mcpText(`❌ Invalid ticket ID format: ${ticketId}\n\nExpected format: PROJ-123`);
             }
+            const cloudId = getCredential('ATLASSIAN_CLOUD_ID');
+            if (!cloudId)
+                throw new Error('Missing ATLASSIAN_CLOUD_ID');
+            const auth = buildBasicAuth('ATLASSIAN_USER_EMAIL', 'ATLASSIAN_API_TOKEN');
             const url = `https://api.atlassian.com/ex/jira/${cloudId}/rest/api/3/issue/${safeTicketId}`;
-            const jsonData = await callAtlassianRestApi(url);
+            const jsonData = await callRestApi(url, auth);
             const parseResult = JiraTicketSchema.safeParse(jsonData);
             if (!parseResult.success) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `❌ Invalid Jira response format: ${parseResult.error.message}`,
-                        },
-                    ],
-                };
+                return mcpText(`❌ Invalid Jira response format: ${parseResult.error.message}`);
             }
             const ticket = parseResult.data;
             if (ticket.errorMessages && ticket.errorMessages.length > 0) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `❌ Ticket not found: ${ticketId}\n\n${ticket.errorMessages.join('\n')}`,
-                        },
-                    ],
-                };
+                return mcpText(`❌ Ticket not found: ${ticketId}\n\n${ticket.errorMessages.join('\n')}`);
             }
             const output = `## 🎫 ${ticketId}: ${ticket.fields.summary}
 
@@ -290,11 +186,10 @@ ${typeof ticket.fields.description === 'string'
 
 ### Labels
 ${ticket.fields.labels?.join(', ') || 'None'}`;
-            return { content: [{ type: 'text', text: output }] };
+            return mcpText(output);
         }
         catch (error) {
-            const errorMsg = error instanceof Error ? error.message : String(error);
-            return { content: [{ type: 'text', text: `Error: ${errorMsg}` }] };
+            return mcpText(`Error: ${error instanceof Error ? error.message : String(error)}`);
         }
     });
 }

package/dist/utils/utils.d.ts

@@ -1 +1,10 @@
 export declare function getWorkspaceRoot(): string;
+type McpTextResult = {
+    content: [{
+        type: 'text';
+        text: string;
+    }];
+};
+export declare function mcpText(text: string): McpTextResult;
+export declare function mcpJson(obj: unknown): McpTextResult;
+export {};

package/dist/utils/utils.js

@@ -6,3 +6,9 @@ export function getWorkspaceRoot() {
         process.env.PWD ||
         process.cwd());
 }
+export function mcpText(text) {
+    return { content: [{ type: 'text', text }] };
+}
+export function mcpJson(obj) {
+    return mcpText(JSON.stringify(obj, null, 2));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanhnd/agent-kit",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "description": "Super Engineer - Team of AI Agents for software development (Claude Code Plugin)",
   "type": "module",
   "main": "dist/kit-server.js",