@hanhnd/agent-kit 1.0.25 → 1.0.27

package/dist/kit-server.js

@@ -3223,8 +3223,8 @@ var require_utils = __commonJS({
       }
       return ind;
     }
-    function removeDotSegments(path5) {
-      let input = path5;
+    function removeDotSegments(path6) {
+      let input = path6;
       const output = [];
       let nextSlash = -1;
       let len = 0;
@@ -3423,8 +3423,8 @@ var require_schemes = __commonJS({
         wsComponent.secure = void 0;
       }
       if (wsComponent.resourceName) {
-        const [path5, query] = wsComponent.resourceName.split("?");
-        wsComponent.path = path5 && path5 !== "/" ? path5 : void 0;
+        const [path6, query] = wsComponent.resourceName.split("?");
+        wsComponent.path = path6 && path6 !== "/" ? path6 : void 0;
         wsComponent.query = query;
         wsComponent.resourceName = void 0;
       }
@@ -7277,8 +7277,8 @@ function getErrorMap() {
 
 // ../../node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
-  const { data, path: path5, errorMaps, issueData } = params;
-  const fullPath = [...path5, ...issueData.path || []];
+  const { data, path: path6, errorMaps, issueData } = params;
+  const fullPath = [...path6, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -7394,11 +7394,11 @@ var errorUtil;
 
 // ../../node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
-  constructor(parent, value, path5, key) {
+  constructor(parent, value, path6, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value;
-    this._path = path5;
+    this._path = path6;
     this._key = key;
   }
   get path() {
@@ -11036,10 +11036,10 @@ function assignProp(target, prop, value) {
     configurable: true
   });
 }
-function getElementAtPath(obj, path5) {
-  if (!path5)
+function getElementAtPath(obj, path6) {
+  if (!path6)
     return obj;
-  return path5.reduce((acc, key) => acc?.[key], obj);
+  return path6.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -11359,11 +11359,11 @@ function aborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path5, issues) {
+function prefixIssues(path6, issues) {
   return issues.map((iss) => {
     var _a;
     (_a = iss).path ?? (_a.path = []);
-    iss.path.unshift(path5);
+    iss.path.unshift(path6);
     return iss;
   });
 }
@@ -20991,7 +20991,7 @@ var StdioServerTransport = class {
 
 // src/tools/core.ts
 import * as fs from "fs";
-import * as path from "path";
+import * as path2 from "path";
 
 // src/utils/utils.ts
 function getWorkspaceRoot() {
@@ -21045,13 +21045,66 @@ var FORBIDDEN_DIRS = [
   ".docker"
 ];
 
+// src/tools/handoffs.ts
+import * as path from "path";
+var HANDOFF_TYPES = [
+  "brainstorm",
+  "clarification",
+  "plan",
+  "ticket",
+  "research",
+  "scenario",
+  "investigation"
+];
+var TICKET_ID_PATTERN = /\b[A-Z][A-Z0-9]+-\d+\b/;
+function findTicketId(value) {
+  return value.match(TICKET_ID_PATTERN)?.[0].toLowerCase() ?? null;
+}
+function sanitizeFeatureSlug(value) {
+  return value.replace(/[^a-zA-Z0-9-_]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase();
+}
+function contentSlugCandidate(content) {
+  const heading = content.split(/\r?\n/).map((line) => line.replace(/^#+\s*/, "").trim()).find((line) => line.length > 0);
+  return heading ?? content.replace(/\s+/g, " ").trim().slice(0, 80);
+}
+function normalizeHandoffType(type) {
+  if (!HANDOFF_TYPES.includes(type)) {
+    throw new Error(`Unsupported handoff type: ${type}`);
+  }
+  return type;
+}
+function deriveFeatureSlug(input) {
+  const requestedTicketSlug = findTicketId(input.requestedSlug);
+  if (requestedTicketSlug) return requestedTicketSlug;
+  const requestedSlug = sanitizeFeatureSlug(input.requestedSlug);
+  if (requestedSlug) return requestedSlug;
+  const contentTicketSlug = findTicketId(input.content);
+  if (contentTicketSlug) return contentTicketSlug;
+  return sanitizeFeatureSlug(contentSlugCandidate(input.content)) || "untitled-handoff";
+}
+function resolveHandoffPath(input) {
+  const canonicalType = normalizeHandoffType(input.type);
+  const featureSlug = deriveFeatureSlug({
+    requestedSlug: input.slug,
+    content: input.content,
+    type: canonicalType
+  });
+  const relativePath = path.join(".agent-kit", "handoffs", featureSlug, `${canonicalType}.md`);
+  return {
+    featureSlug,
+    canonicalType,
+    filePath: path.join(input.workspaceRoot, relativePath),
+    relativePath
+  };
+}
+
 // src/tools/core.ts
 function registerCoreTools(server2) {
   server2.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.`,
     {
-      type: external_exports.enum(["brainstorm", "clarify", "plan", "ticket", "research"]).describe("Handoff type"),
+      type: external_exports.enum(HANDOFF_TYPES).describe("Handoff type"),
       content: external_exports.string().describe("Full markdown content to save"),
       slug: external_exports.string().describe(
         'Short identifier for the filename, e.g. "user-auth" or "PROJ-123". Do NOT append version numbers (v2, v3, etc.).'
@@ -21059,24 +21112,18 @@ function registerCoreTools(server2) {
     },
     async ({ type, content, slug }) => {
       try {
-        const safeSlug = slug.replace(/[^a-zA-Z0-9-_]/g, "-").toLowerCase();
-        const handoffDir = path.join(getWorkspaceRoot(), ".agent-kit", "handoffs", `${type}s`);
+        const location = resolveHandoffPath({
+          workspaceRoot: getWorkspaceRoot(),
+          type,
+          slug,
+          content
+        });
+        const handoffDir = path2.dirname(location.filePath);
         if (!fs.existsSync(handoffDir)) {
           fs.mkdirSync(handoffDir, { recursive: true });
         }
-        const files = fs.readdirSync(handoffDir);
-        const slugPattern = new RegExp(`^${type}-([0-9T-]{19}-)?${safeSlug}\\.md$`);
-        const existingFile = files.filter((f) => slugPattern.test(f)).sort().pop();
-        let filePath;
-        if (existingFile) {
-          filePath = path.join(handoffDir, existingFile);
-        } else {
-          const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
-          const filename = `${type}-${timestamp}-${safeSlug}.md`;
-          filePath = path.join(handoffDir, filename);
-        }
-        fs.writeFileSync(filePath, content, "utf8");
-        return mcpText(`\u2705 Saved to: ${filePath}`);
+        fs.writeFileSync(location.filePath, content, "utf8");
+        return mcpText(`\u2705 Saved to: ${location.filePath}`);
       } catch (error2) {
         return mcpText(`Error saving handoff: ${error2}`);
       }
@@ -21088,27 +21135,27 @@ function registerCoreTools(server2) {
 import { spawn } from "child_process";
 import { randomUUID } from "crypto";
 import * as fs2 from "fs";
-import * as path3 from "path";
+import * as path4 from "path";
 
 // src/tools/security.ts
 import { execFileSync } from "child_process";
-import * as path2 from "path";
+import * as path3 from "path";
 function sanitize(input) {
   return String(input).replace(/[;&|`$<>\\]/g, "").trim().slice(0, 500);
 }
 function validatePath(filePath, baseDir = process.cwd()) {
-  const resolved = path2.resolve(baseDir, filePath);
-  const root = path2.resolve(baseDir);
-  if (resolved !== root && !resolved.startsWith(root + path2.sep)) {
+  const resolved = path3.resolve(baseDir, filePath);
+  const root = path3.resolve(baseDir);
+  if (resolved !== root && !resolved.startsWith(root + path3.sep)) {
     throw new Error(`Path traversal detected: ${filePath}`);
   }
-  const segments = resolved.split(path2.sep);
+  const segments = resolved.split(path3.sep);
   for (const segment of segments) {
     if (FORBIDDEN_DIRS.some((d) => segment.toLowerCase() === d.toLowerCase())) {
       throw new Error(`Access to sensitive directory is FORBIDDEN: ${segment}`);
     }
   }
-  const fileName = path2.basename(resolved);
+  const fileName = path3.basename(resolved);
   const isExactForbidden = FORBIDDEN_FILES.some((f) => fileName.toLowerCase() === f.toLowerCase());
   const isPatternForbidden = FORBIDDEN_PATTERNS.some((re) => re.test(fileName));
   if (isExactForbidden || isPatternForbidden) {
@@ -21182,10 +21229,10 @@ function taskSlug(task) {
   return task.toLowerCase().replace(/[^a-z0-9\s]/g, "").trim().split(/\s+/).slice(0, 6).join("-").slice(0, 48);
 }
 function initAgentLog(workspaceRoot, slug, agent) {
-  const logsDir = path3.join(workspaceRoot, ".agent-kit", "logs", "agents");
+  const logsDir = path4.join(workspaceRoot, ".agent-kit", "logs", "agents");
   fs2.mkdirSync(logsDir, { recursive: true });
   const now = (/* @__PURE__ */ new Date()).toISOString();
-  const logFile = path3.join(logsDir, `delegate-${now}-${slug}.log`);
+  const logFile = path4.join(logsDir, `delegate-${now}-${slug}.log`);
   const header = `Agent: ${agent}
 Date: ${now}
 ${"\u2500".repeat(60)}
@@ -21195,16 +21242,16 @@ ${"\u2500".repeat(60)}
   const logStream = fs2.createWriteStream(logFile, { flags: "a" });
   logStream.on("error", () => {
   });
-  return { logPath: path3.relative(workspaceRoot, logFile), logStream };
+  return { logPath: path4.relative(workspaceRoot, logFile), logStream };
 }
 function registerAgentTools(server2) {
   server2.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/plans/plan-xyz.md).",
+    "!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).",
     {
       agent: external_exports.enum(["gemini", "claude", "codex"]).describe('The agent CLI to invoke: "gemini", "claude", or "codex"'),
       task: external_exports.string().describe(
-        'Task message or path to a handoff file (e.g., ".agent-kit/handoffs/plans/plan-xyz.md")'
+        'Task message or path to a handoff file (e.g., ".agent-kit/handoffs/feature-slug/plan.md")'
       )
     },
     async ({ agent, task }, extra) => {
@@ -21214,7 +21261,7 @@ function registerAgentTools(server2) {
       let killChild;
       try {
         let prompt = task;
-        const resolvedTask = path3.resolve(workspaceRoot, task);
+        const resolvedTask = path4.resolve(workspaceRoot, task);
         if (fs2.existsSync(resolvedTask) && fs2.statSync(resolvedTask).isFile()) {
           try {
             validatePath(task, workspaceRoot);
@@ -21321,8 +21368,8 @@ import { writeFileSync as writeFileSync3 } from "fs";
 // src/utils/credentials.ts
 import * as fs3 from "fs";
 import * as os from "os";
-import * as path4 from "path";
-var CREDENTIALS_FILE = path4.join(os.homedir(), ".claude", "credentials");
+import * as path5 from "path";
+var CREDENTIALS_FILE = path5.join(os.homedir(), ".claude", "credentials");
 var cachedCredentials = null;
 function parseIni(content) {
   const result = {};

package/dist/tools/agent.js

@@ -58,13 +58,13 @@ 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/plans/plan-xyz.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 file (.agent-kit/handoffs/feature-slug/plan.md).', {
         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/plans/plan-xyz.md")'),
+            .describe('Task message or path to a handoff file (e.g., ".agent-kit/handoffs/feature-slug/plan.md")'),
     }, async ({ agent, task }, extra) => {
         const workspaceRoot = getWorkspaceRoot();
         let job;

package/dist/tools/core.js

@@ -6,6 +6,7 @@ import * as path from 'path';
 import { z } from 'zod';
 import { getWorkspaceRoot, mcpText } from '../utils/utils.js';
 import { DEFAULT_EXTENSIONS } from './config.js';
+import { HANDOFF_TYPES, resolveHandoffPath } from './handoffs.js';
 /**
  * Register core tools with MCP server
  */
@@ -17,7 +18,7 @@ export function registerCoreTools(server) {
     // ═══════════════════════════════════════════════════════════════
     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.`, {
         type: z
-            .enum(['brainstorm', 'clarify', 'plan', 'ticket', 'research'])
+            .enum(HANDOFF_TYPES)
             .describe('Handoff type'),
         content: z.string().describe('Full markdown content to save'),
         slug: z
@@ -25,28 +26,18 @@ export function registerCoreTools(server) {
             .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 safeSlug = slug.replace(/[^a-zA-Z0-9-_]/g, '-').toLowerCase();
-            const handoffDir = path.join(getWorkspaceRoot(), '.agent-kit', 'handoffs', `${type}s`);
+            const location = resolveHandoffPath({
+                workspaceRoot: getWorkspaceRoot(),
+                type,
+                slug,
+                content,
+            });
+            const handoffDir = path.dirname(location.filePath);
             if (!fs.existsSync(handoffDir)) {
                 fs.mkdirSync(handoffDir, { recursive: true });
             }
-            const files = fs.readdirSync(handoffDir);
-            const slugPattern = new RegExp(`^${type}-([0-9T-]{19}-)?${safeSlug}\\.md$`);
-            const existingFile = files
-                .filter((f) => slugPattern.test(f))
-                .sort()
-                .pop();
-            let filePath;
-            if (existingFile) {
-                filePath = path.join(handoffDir, existingFile);
-            }
-            else {
-                const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
-                const filename = `${type}-${timestamp}-${safeSlug}.md`;
-                filePath = path.join(handoffDir, filename);
-            }
-            fs.writeFileSync(filePath, content, 'utf8');
-            return mcpText(`✅ Saved to: ${filePath}`);
+            fs.writeFileSync(location.filePath, content, 'utf8');
+            return mcpText(`✅ Saved to: ${location.filePath}`);
         }
         catch (error) {
             return mcpText(`Error saving handoff: ${error}`);

package/dist/tools/handoffs.d.ts

@@ -0,0 +1,22 @@
+export declare const HANDOFF_TYPES: readonly ["brainstorm", "clarification", "plan", "ticket", "research", "scenario", "investigation"];
+export type HandoffType = (typeof HANDOFF_TYPES)[number];
+export type CanonicalHandoffType = 'brainstorm' | 'clarification' | 'plan' | 'ticket' | 'research' | 'scenario' | 'investigation';
+export interface SavedHandoffLocation {
+    featureSlug: string;
+    canonicalType: CanonicalHandoffType;
+    filePath: string;
+    relativePath: string;
+}
+export declare function sanitizeFeatureSlug(value: string): string;
+export declare function normalizeHandoffType(type: HandoffType): CanonicalHandoffType;
+export declare function deriveFeatureSlug(input: {
+    requestedSlug: string;
+    content: string;
+    type: CanonicalHandoffType;
+}): string;
+export declare function resolveHandoffPath(input: {
+    workspaceRoot: string;
+    type: HandoffType;
+    slug: string;
+    content: string;
+}): SavedHandoffLocation;

package/dist/tools/handoffs.js

@@ -0,0 +1,62 @@
+import * as path from 'path';
+export const HANDOFF_TYPES = [
+    'brainstorm',
+    'clarification',
+    'plan',
+    'ticket',
+    'research',
+    'scenario',
+    'investigation',
+];
+const TICKET_ID_PATTERN = /\b[A-Z][A-Z0-9]+-\d+\b/;
+function findTicketId(value) {
+    return value.match(TICKET_ID_PATTERN)?.[0].toLowerCase() ?? null;
+}
+export function sanitizeFeatureSlug(value) {
+    return value
+        .replace(/[^a-zA-Z0-9-_]/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '')
+        .toLowerCase();
+}
+function contentSlugCandidate(content) {
+    const heading = content
+        .split(/\r?\n/)
+        .map((line) => line.replace(/^#+\s*/, '').trim())
+        .find((line) => line.length > 0);
+    return heading ?? content.replace(/\s+/g, ' ').trim().slice(0, 80);
+}
+export function normalizeHandoffType(type) {
+    if (!HANDOFF_TYPES.includes(type)) {
+        throw new Error(`Unsupported handoff type: ${type}`);
+    }
+    return type;
+}
+export function deriveFeatureSlug(input) {
+    const requestedTicketSlug = findTicketId(input.requestedSlug);
+    if (requestedTicketSlug)
+        return requestedTicketSlug;
+    const requestedSlug = sanitizeFeatureSlug(input.requestedSlug);
+    if (requestedSlug)
+        return requestedSlug;
+    const contentTicketSlug = findTicketId(input.content);
+    if (contentTicketSlug)
+        return contentTicketSlug;
+    return (sanitizeFeatureSlug(contentSlugCandidate(input.content)) ||
+        'untitled-handoff');
+}
+export function resolveHandoffPath(input) {
+    const canonicalType = normalizeHandoffType(input.type);
+    const featureSlug = deriveFeatureSlug({
+        requestedSlug: input.slug,
+        content: input.content,
+        type: canonicalType,
+    });
+    const relativePath = path.join('.agent-kit', 'handoffs', featureSlug, `${canonicalType}.md`);
+    return {
+        featureSlug,
+        canonicalType,
+        filePath: path.join(input.workspaceRoot, relativePath),
+        relativePath,
+    };
+}

package/package.json

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