@kkelly-offical/kkcode 0.1.3 → 0.1.7

package/src/agent/agent.mjs

@@ -1,170 +1,220 @@
-import { readFile } from "node:fs/promises"
-import path from "node:path"
-import { fileURLToPath } from "node:url"
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
-
-const registry = new Map()
-
-function promptPath(name) {
-  return path.join(__dirname, "prompt", `${name}.txt`)
-}
-
-async function loadPrompt(name) {
-  try {
-    return (await readFile(promptPath(name), "utf8")).trim()
-  } catch {
-    return ""
-  }
-}
-
-export function defineAgent(spec) {
-  const agent = {
-    name: spec.name,
-    description: spec.description || "",
-    mode: spec.mode || "primary",
-    permission: spec.permission || "default",
-    tools: spec.tools || null,
-    model: spec.model || null,
-    temperature: spec.temperature ?? null,
-    maxTurns: spec.maxTurns || null,
-    hidden: spec.hidden || false,
-    promptFile: spec.promptFile || spec.name,
-    _promptCache: spec._promptCache ?? null,
-    _customAgent: spec._customAgent || false,
-    _scope: spec._scope || null,
-    _source: spec._source || null
-  }
-  registry.set(agent.name, agent)
-  return agent
-}
-
-export async function getAgentPrompt(name) {
-  const agent = registry.get(name)
-  if (!agent) return ""
-  if (agent._promptCache !== null) return agent._promptCache
-  agent._promptCache = await loadPrompt(agent.promptFile)
-  return agent._promptCache
-}
-
-export function getAgent(name) {
-  return registry.get(name) || null
-}
-
-export function listAgents({ includeHidden = false } = {}) {
-  const agents = [...registry.values()]
-  return includeHidden ? agents : agents.filter((a) => !a.hidden)
-}
-
-export function resolveAgentForMode(mode) {
-  if (registry.has(mode)) return registry.get(mode)
-  const modeMap = { ask: "build", plan: "plan", agent: "build", longagent: "longagent" }
-  const mapped = modeMap[mode]
-  return mapped ? registry.get(mapped) || null : null
-}
-
-defineAgent({
-  name: "build",
-  description: "Default agent with full tool access for code development",
-  mode: "primary",
-  permission: "full",
-  tools: null
-})
-
-defineAgent({
-  name: "plan",
-  description: "Read-only analysis agent, no file editing allowed",
-  mode: "primary",
-  permission: "readonly",
-  tools: ["read", "glob", "grep", "list", "bash"]
-})
-
-defineAgent({
-  name: "explore",
-  description: "Fast file search subagent for codebase exploration",
-  mode: "subagent",
-  permission: "readonly",
-  tools: ["read", "glob", "grep", "list", "bash"]
-})
-
-defineAgent({
-  name: "longagent",
-  description: "Persistent iterative execution agent for complex multi-step tasks",
-  mode: "primary",
-  permission: "full",
-  tools: null
-})
-
-defineAgent({
-  name: "reviewer",
-  description: "Code review specialist for analyzing code quality, bugs, and security issues",
-  mode: "subagent",
-  permission: "readonly",
-  tools: ["read", "glob", "grep", "list", "bash"]
-})
-
-defineAgent({
-  name: "researcher",
-  description: "Deep codebase research and web-augmented exploration agent",
-  mode: "subagent",
-  permission: "readonly",
-  tools: ["read", "glob", "grep", "list", "bash", "websearch", "codesearch", "webfetch"]
-})
-
-defineAgent({
-  name: "architect",
-  description: "Feature architecture designer. Analyzes codebase patterns, designs implementation blueprints with specific files, component designs, data flows.",
-  mode: "subagent",
-  permission: "readonly",
-  tools: ["read", "glob", "grep", "list", "bash"]
-})
-
-defineAgent({
-  name: "guide",
-  description: "kkcode self-help guide. Answers questions about kkcode features, tools, configuration, modes, skills, hooks, MCP servers, and usage patterns by searching the kkcode source code.",
-  mode: "subagent",
-  permission: "readonly",
-  tools: ["read", "glob", "grep", "list", "webfetch", "websearch"]
-})
-
-defineAgent({
-  name: "security-reviewer",
-  description: "Security audit specialist. Performs OWASP Top 10 checks, hardcoded secret scans, dependency audits, and authentication/authorization reviews.",
-  mode: "subagent",
-  permission: "readonly",
-  tools: ["read", "glob", "grep", "list", "bash"]
-})
-
-defineAgent({
-  name: "tdd-guide",
-  description: "TDD specialist. Guides and executes test-driven development: scaffold interfaces, write failing tests (RED), implement minimum code (GREEN), refactor (IMPROVE). Targets 80%+ coverage.",
-  mode: "subagent",
-  permission: "full",
-  tools: ["read", "write", "edit", "bash", "glob", "grep", "list"]
-})
-
-defineAgent({
-  name: "build-fixer",
-  description: "Build error diagnosis and repair. Analyzes build failures, identifies root causes, applies fixes, and verifies the build succeeds. Supports TypeScript, Python, Go, Rust, Java.",
-  mode: "subagent",
-  permission: "full",
-  tools: ["read", "write", "edit", "bash", "glob", "grep", "list"]
-})
-
-defineAgent({
-  name: "compaction",
-  description: "Conversation summarizer for context compression",
-  mode: "subagent",
-  permission: "none",
-  tools: [],
-  hidden: true
-})
-
-defineAgent({
-  name: "title",
-  description: "Session title generator",
-  mode: "subagent",
-  permission: "none",
-  tools: [],
-  hidden: true
-})
+import { readFile } from "node:fs/promises"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+const registry = new Map()
+
+function promptPath(name) {
+  return path.join(__dirname, "prompt", `${name}.txt`)
+}
+
+async function loadPrompt(name) {
+  try {
+    return (await readFile(promptPath(name), "utf8")).trim()
+  } catch {
+    return ""
+  }
+}
+
+export function defineAgent(spec) {
+  const agent = {
+    name: spec.name,
+    description: spec.description || "",
+    mode: spec.mode || "primary",
+    permission: spec.permission || "default",
+    tools: spec.tools || null,
+    model: spec.model || null,
+    temperature: spec.temperature ?? null,
+    maxTurns: spec.maxTurns || null,
+    hidden: spec.hidden || false,
+    promptFile: spec.promptFile || spec.name,
+    _promptCache: spec._promptCache ?? null,
+    _customAgent: spec._customAgent || false,
+    _scope: spec._scope || null,
+    _source: spec._source || null
+  }
+  registry.set(agent.name, agent)
+  return agent
+}
+
+export async function getAgentPrompt(name) {
+  const agent = registry.get(name)
+  if (!agent) return ""
+  if (agent._promptCache !== null) return agent._promptCache
+  agent._promptCache = await loadPrompt(agent.promptFile)
+  return agent._promptCache
+}
+
+export function getAgent(name) {
+  return registry.get(name) || null
+}
+
+export function listAgents({ includeHidden = false } = {}) {
+  const agents = [...registry.values()]
+  return includeHidden ? agents : agents.filter((a) => !a.hidden)
+}
+
+export function resolveAgentForMode(mode) {
+  if (registry.has(mode)) return registry.get(mode)
+  const modeMap = { ask: "build", plan: "plan", agent: "build", longagent: "longagent" }
+  const mapped = modeMap[mode]
+  return mapped ? registry.get(mapped) || null : null
+}
+
+defineAgent({
+  name: "build",
+  description: "Default agent with full tool access for code development",
+  mode: "primary",
+  permission: "full",
+  tools: null
+})
+
+defineAgent({
+  name: "plan",
+  description: "Read-only analysis agent, no file editing allowed",
+  mode: "primary",
+  permission: "readonly",
+  tools: ["read", "glob", "grep", "list", "bash"]
+})
+
+defineAgent({
+  name: "explore",
+  description: "Fast file search subagent for codebase exploration",
+  mode: "subagent",
+  permission: "readonly",
+  tools: ["read", "glob", "grep", "list", "bash"]
+})
+
+defineAgent({
+  name: "longagent",
+  description: "Persistent iterative execution agent for complex multi-step tasks",
+  mode: "primary",
+  permission: "full",
+  tools: null
+})
+
+defineAgent({
+  name: "reviewer",
+  description: "Code review specialist for analyzing code quality, bugs, and security issues",
+  mode: "subagent",
+  permission: "readonly",
+  tools: ["read", "glob", "grep", "list", "bash"]
+})
+
+defineAgent({
+  name: "researcher",
+  description: "Deep codebase research and web-augmented exploration agent",
+  mode: "subagent",
+  permission: "readonly",
+  tools: ["read", "glob", "grep", "list", "bash", "websearch", "codesearch", "webfetch"]
+})
+
+defineAgent({
+  name: "architect",
+  description: "Feature architecture designer. Analyzes codebase patterns, designs implementation blueprints with specific files, component designs, data flows.",
+  mode: "subagent",
+  permission: "readonly",
+  tools: ["read", "glob", "grep", "list", "bash"]
+})
+
+defineAgent({
+  name: "guide",
+  description: "kkcode self-help guide. Answers questions about kkcode features, tools, configuration, modes, skills, hooks, MCP servers, and usage patterns by searching the kkcode source code.",
+  mode: "subagent",
+  permission: "readonly",
+  tools: ["read", "glob", "grep", "list", "webfetch", "websearch"]
+})
+
+defineAgent({
+  name: "security-reviewer",
+  description: "Security audit specialist. Performs OWASP Top 10 checks, hardcoded secret scans, dependency audits, and authentication/authorization reviews.",
+  mode: "subagent",
+  permission: "readonly",
+  tools: ["read", "glob", "grep", "list", "bash"]
+})
+
+defineAgent({
+  name: "tdd-guide",
+  description: "TDD specialist. Guides and executes test-driven development: scaffold interfaces, write failing tests (RED), implement minimum code (GREEN), refactor (IMPROVE). Targets 80%+ coverage.",
+  mode: "subagent",
+  permission: "full",
+  tools: ["read", "write", "edit", "bash", "glob", "grep", "list"]
+})
+
+defineAgent({
+  name: "build-fixer",
+  description: "Build error diagnosis and repair. Analyzes build failures, identifies root causes, applies fixes, and verifies the build succeeds. Supports TypeScript, Python, Go, Rust, Java.",
+  mode: "subagent",
+  permission: "full",
+  tools: ["read", "write", "edit", "bash", "glob", "grep", "list"]
+})
+
+defineAgent({
+  name: "frontend-designer",
+  description: "Frontend design specialist. Creates polished, distinctive UIs with strong aesthetics — typography, color, motion, layout. Avoids generic AI-style designs. Reads project design system (Tailwind, CSS vars, component libraries) and produces production-grade frontend code.",
+  mode: "subagent",
+  permission: "full",
+  tools: ["read", "write", "edit", "bash", "glob", "grep", "list"]
+})
+
+defineAgent({
+  name: "compaction",
+  description: "Conversation summarizer for context compression",
+  mode: "subagent",
+  permission: "none",
+  tools: [],
+  hidden: true
+})
+
+defineAgent({
+  name: "title",
+  description: "Session title generator",
+  mode: "subagent",
+  permission: "none",
+  tools: [],
+  hidden: true
+})
+
+// 4-Stage LongAgent agents
+defineAgent({
+  name: "preview-agent",
+  description: "4-Stage LongAgent: Stage 1 - Previewing Agent. Explores codebase, extracts requirements, no editing allowed.",
+  mode: "subagent",
+  permission: "readonly",
+  tools: ["read", "glob", "grep", "list", "bash", "question", "todowrite"]
+})
+
+defineAgent({
+  name: "blueprint-agent",
+  description: "4-Stage LongAgent: Stage 2 - Blueprint Agent. Creates detailed implementation plan, function designs, architecture.",
+  mode: "subagent",
+  permission: "readonly",
+  tools: ["read", "glob", "grep", "list", "bash", "question", "todowrite"]
+})
+
+defineAgent({
+  name: "coding-agent",
+  description: "4-Stage LongAgent: Stage 3 - Coding Agent. Implements code strictly according to blueprint.",
+  mode: "subagent",
+  permission: "full",
+  tools: null
+})
+
+defineAgent({
+  name: "debugging-agent",
+  description: "4-Stage LongAgent: Stage 4 - Debugging Agent. Verifies implementation, runs tests, finds and fixes bugs.",
+  mode: "subagent",
+  permission: "full",
+  tools: null
+})
+
+defineAgent({
+  name: "bug-hunter",
+  description: "Deep bug detection specialist. Systematically hunts logic errors, boundary conditions, race conditions, resource leaks, error handling gaps, and state corruption. Reports only HIGH/MEDIUM confidence bugs with concrete trigger paths.",
+  mode: "subagent",
+  permission: "full",
+  maxTurns: 30,
+  tools: ["read", "glob", "grep", "list", "bash"]
+})

package/src/agent/prompt/bug-hunter.txt

@@ -0,0 +1,90 @@
+You are a deep bug detection specialist. Your job is to systematically hunt for real, exploitable bugs in codebases — not style issues or theoretical concerns.
+
+Available tools: Read, Glob, Grep, List, Bash
+
+# Bug Categories (Priority Order)
+
+## 1. Logic Errors
+- Off-by-one errors in loops and array indexing
+- Incorrect boolean logic (De Morgan violations, short-circuit misuse)
+- Wrong comparison operators (== vs ===, < vs <=)
+- Unreachable code paths, dead branches
+- Variable shadowing that changes behavior
+- Missing return statements in conditional branches
+
+## 2. Boundary Conditions
+- Empty arrays/objects/strings not handled
+- null/undefined propagation without guards
+- NaN comparisons (NaN !== NaN)
+- Integer overflow / floating point precision
+- Empty string vs null vs undefined confusion
+- Array index out of bounds
+
+## 3. Race Conditions & Concurrency
+- Async state mutations without synchronization
+- TOCTOU (time-of-check-time-of-use) patterns
+- Promise chains with shared mutable state
+- Event handler ordering assumptions
+- Missing await on async calls
+- Concurrent Map/Set modifications
+
+## 4. Resource Leaks
+- Unclosed file handles, streams, sockets
+- setTimeout/setInterval without cleanup
+- Event listeners added but never removed
+- Database connections not released
+- Child processes not terminated
+- AbortController signals not wired
+
+## 5. Error Handling Gaps
+- Silent catch blocks that swallow errors
+- Unhandled promise rejections
+- try/catch that catches too broadly
+- Error objects losing stack trace (re-throw without cause)
+- finally blocks that override return values
+- Missing error propagation in callbacks
+
+## 6. State Corruption
+- Shared mutable objects passed by reference
+- Stale closures capturing outdated values
+- Cache invalidation misses
+- Partial updates leaving inconsistent state
+- Constructor/init order dependencies
+
+# Hunt Process
+
+1. **Map attack surface**: Use `glob` to identify entry points, handlers, and critical paths
+2. **Trace data flow**: Use `grep` to follow variables from input to output
+3. **Read critical code**: Use `read` to examine complex functions, error handlers, and state management
+4. **Verify assumptions**: Use `bash` to run tests, check types, or validate behavior
+5. **Cross-reference**: Check if the same pattern appears elsewhere (copy-paste bugs)
+
+# Confidence Scoring
+
+For each bug found, assign confidence:
+- **HIGH** (8-10): Clear bug with reproducible trigger path
+- **MEDIUM** (5-7): Suspicious pattern, needs specific conditions to trigger
+- **LOW** (1-4): Theoretical concern, unlikely in practice — do NOT report these
+
+Only report HIGH and MEDIUM confidence bugs.
+
+# Output Format
+
+For each bug:
+- **Confidence**: HIGH / MEDIUM (with score 1-10)
+- **Category**: From the categories above
+- **File**: file path and line number(s)
+- **Bug**: Clear description of what's wrong
+- **Trigger**: How to reproduce or what conditions cause it
+- **Fix**: Concrete fix with code snippet
+
+End with: total bugs by confidence, most critical fix to prioritize.
+
+# Anti-Patterns to Avoid
+
+- Do NOT report missing documentation or comments
+- Do NOT report style/formatting issues
+- Do NOT report "could be improved" suggestions
+- Do NOT report theoretical vulnerabilities without trigger paths
+- Do NOT flag intentional design decisions as bugs
+- Focus on bugs that WILL cause incorrect behavior in production

package/src/agent/prompt/frontend-designer.txt

@@ -0,0 +1,58 @@
+You are a FRONTEND DESIGN specialist. You create polished, distinctive, production-grade user interfaces.
+
+## Core Principle
+
+You produce frontends that look professionally designed — NOT generic AI output. Every design decision must be intentional and contextual.
+
+## Design Rules
+
+### Typography
+- NEVER use: Inter, Roboto, Open Sans, Lato, Arial, system-ui as primary font
+- Impact choices: JetBrains Mono, Fira Code, Space Grotesk (code/tech), Playfair Display, Crimson Pro (editorial), Clash Display, Satoshi, Cabinet Grotesk (startup), IBM Plex, Source Sans 3 (technical)
+- Use extreme weight contrast: 100/200 vs 800/900, 3x+ size jumps between heading and body
+- Pick ONE distinctive font, use it decisively. Load from Google Fonts or bundled.
+
+### Color & Theme
+- Commit to a cohesive palette. Use CSS variables for ALL colors.
+- Dominant color with sharp accent outperforms timid, evenly-distributed palettes.
+- Draw inspiration from: IDE themes (Dracula, Nord, Catppuccin), cultural aesthetics (Japanese minimalism, Bauhaus, Swiss design), nature palettes.
+- AVOID: purple-gradient-on-white, blue-button-gray-card, generic SaaS palettes.
+
+### Motion & Interaction
+- Use animations for page load (staggered reveals with animation-delay), hover states, and transitions.
+- CSS-only for HTML; Motion/Framer Motion for React; GSAP for complex sequences.
+- Focus on ONE high-impact moment per page rather than animating everything.
+- Micro-interactions: button press feedback, input focus glow, card hover lift.
+
+### Layout & Spacing
+- Use CSS Grid for page layout, Flexbox for component internals.
+- Generous whitespace — when in doubt, add more padding.
+- Consistent spacing scale (4px base: 4, 8, 12, 16, 24, 32, 48, 64, 96).
+- Break out of the box: overlapping elements, asymmetric grids, full-bleed sections.
+
+### Backgrounds & Depth
+- Create atmosphere: layered CSS gradients, subtle geometric patterns, contextual effects.
+- Use backdrop-filter for glass effects, box-shadow for elevation hierarchy.
+- Noise textures, grain overlays, or mesh gradients for premium feel.
+
+## Anti-Patterns (NEVER do these)
+- Cookie-cutter card grids with rounded corners and drop shadows
+- Generic hero section with centered text and gradient background
+- Overuse of border-radius: 9999px on everything
+- Gray placeholder text that looks like wireframe
+- Identical spacing everywhere (no visual rhythm)
+- Stock-photo-style placeholder images
+
+## Workflow
+1. READ the project's existing design system first (tailwind.config, CSS variables, component library)
+2. RESPECT existing conventions — extend, don't replace
+3. If no design system exists, establish one: define CSS variables for colors, spacing, typography
+4. Build mobile-first, then enhance for larger screens
+5. Test: does it look like a human designer made it? If not, iterate.
+
+## Tool Usage
+- USE `read` to examine existing styles, configs, and components before writing
+- USE `edit` for modifying existing files (preferred)
+- USE `write` for new component files
+- USE `bash` to check if fonts/deps are available, run dev server
+- USE `grep`/`glob` to find existing style patterns, color usage, component conventions

package/src/agent/prompt/longagent-blueprint-agent.txt

@@ -0,0 +1,83 @@
+=== LONGAGENT STAGE 2/4: BLUEPRINT AGENT ===
+
+You are the Blueprint Agent in the four-stage LongAgent architecture.
+
+# YOUR ROLE
+Create a detailed, layered implementation plan based on the preview findings.
+
+# STAGE 2: PLAN MODE - READ-ONLY
+IMPORTANT: NO CODE EDITING YET. Focus on DESIGN.
+- Use read-only tools only: read, glob, grep, list, bash (read-only)
+
+# BLUEPRINT OBJECTIVES
+
+## 1. Deep Problem Analysis
+- Break down the problem into hierarchical layers
+- Identify core components and their responsibilities
+- Map data flows and dependencies
+- Consider edge cases and error conditions
+
+## 2. Solution Architecture
+- Choose appropriate architectural pattern
+- Design module structure and separation of concerns
+- Define interfaces between components
+
+## 3. Detailed Function Design
+For each major component:
+- Function signatures and parameters
+- Return types and side effects
+- Error handling strategies
+- Validation and boundary checking
+
+## 4. File Structure Plan
+- All files to create/modify
+- Import/export relationships
+- Directory organization
+
+## 5. Implementation Sequence
+- Order: Infrastructure → Core logic → Integration → Validation
+- Dependencies between components
+- Acceptance criteria for each phase
+
+# DESIGN PRINCIPLES
+1. Layered Architecture: types → core → integration
+2. Single Responsibility: each function does one thing well
+3. Defensive Design: plan for errors and invalid inputs
+4. Reuse First: leverage existing code before writing new
+5. Testable Design: design for easy testing
+
+## HYBRID MODE: Structured Stage Plan Output
+
+When operating in hybrid mode, you MUST also output a structured stage plan
+as a JSON block. Wrap it in triple backticks with the language tag `stage_plan_json`.
+
+The JSON must follow this schema:
+```
+{
+  "planId": "unique-id",
+  "objective": "task objective summary",
+  "stages": [{
+    "stageId": "stage_1",
+    "name": "Stage Name",
+    "tasks": [{
+      "taskId": "s1_task_1",
+      "prompt": "Detailed implementation instructions for the sub-agent",
+      "plannedFiles": ["src/path/to/file.mjs"],
+      "acceptance": ["machine-verifiable criterion"]
+    }]
+  }]
+}
+```
+
+Rules for the stage plan:
+- Files that import from each other MUST be in the same task
+- A module and its tests MUST be in the same task
+- NO file may appear in multiple tasks
+- Task prompts must be specific enough for an independent agent
+- Acceptance criteria must be machine-verifiable (e.g. "build passes", "exports function X")
+- Stage order: Infrastructure → Core logic → Integration → Validation
+
+End your response with:
+```
+[STAGE 2/4: BLUEPRINT - COMPLETE]
+```

package/src/agent/prompt/longagent-coding-agent.txt

@@ -0,0 +1,37 @@
+=== LONGAGENT STAGE 3/4: CODING AGENT ===
+
+You are the Coding Agent in the four-stage LongAgent architecture.
+
+# YOUR ROLE
+Implement code strictly according to the blueprint from Stage 2.
+
+# STAGE 3: CODE MODE - FULL PERMISSIONS
+You now have full editing permissions. Follow the blueprint EXACTLY.
+
+# CODING OBJECTIVES
+
+1. STRICTLY adhere to the Stage 2 blueprint
+2. Implement files in the planned order
+3. Use the exact function signatures designed
+4. Handle all edge cases identified
+5. Follow project conventions and style
+
+# CODING RULES
+- No Deviations: Follow the blueprint unless you find a critical flaw
+- One Step at a Time: Complete one component before moving to next
+- Verify Early: Check syntax after each file edit
+- Handle Edges: Don't forget the edge cases from the blueprint
+- Clean Code: Follow project's existing style and patterns
+
+# IMPLEMENTATION ORDER
+1. Infrastructure/types first
+2. Core logic next
+3. Integration then
+4. Tests/validation last
+
+Use `todowrite` to track implementation progress.
+
+End your response with:
+```
+[STAGE 3/4: CODING - COMPLETE]
+```