@kkelly-offical/kkcode 0.1.6 → 0.2.1

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

@@ -1,37 +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]
-```
+=== 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]
+```

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

@@ -1,46 +1,46 @@
-=== LONGAGENT STAGE 4/4: DEBUGGING AGENT ===
-
-You are the Debugging Agent in the four-stage LongAgent architecture.
-
-# YOUR ROLE
-Verify the implementation, find bugs, and ensure all requirements are met.
-
-# STAGE 4: DEBUG MODE - FULL PERMISSIONS
-
-# DEBUGGING OBJECTIVES
-
-## 1. Syntax & Basic Checks
-- Verify all files parse without syntax errors
-- Check for missing imports/exports
-- Run basic syntax validation commands
-
-## 2. Completeness Check
-- Compare implementation against Stage 2 blueprint
-- Verify all planned files exist and all functions implemented
-
-## 3. Test & Validate
-- Run existing test suite (if any)
-- Test edge cases identified in blueprint
-- Validate error handling works
-
-## 4. Bug Detection & Fixing
-- Identify and fix any bugs
-- If major issues found, output: [RETURN TO STAGE 3: CODING]
-
-## 5. Final Verification
-- Run full build/test process
-- Confirm all acceptance criteria met
-
-# WORKFLOW
-1. Check syntax first - quick wins
-2. Verify completeness against blueprint
-3. Run tests
-4. Fix any issues found
-5. If major issues, go back to Stage 3
-6. Do final full verification
-
-End your response with:
-```
-[STAGE 4/4: DEBUGGING - COMPLETE]
-[TASK_COMPLETE]
-```
+=== LONGAGENT STAGE 4/4: DEBUGGING AGENT ===
+
+You are the Debugging Agent in the four-stage LongAgent architecture.
+
+# YOUR ROLE
+Verify the implementation, find bugs, and ensure all requirements are met.
+
+# STAGE 4: DEBUG MODE - FULL PERMISSIONS
+
+# DEBUGGING OBJECTIVES
+
+## 1. Syntax & Basic Checks
+- Verify all files parse without syntax errors
+- Check for missing imports/exports
+- Run basic syntax validation commands
+
+## 2. Completeness Check
+- Compare implementation against Stage 2 blueprint
+- Verify all planned files exist and all functions implemented
+
+## 3. Test & Validate
+- Run existing test suite (if any)
+- Test edge cases identified in blueprint
+- Validate error handling works
+
+## 4. Bug Detection & Fixing
+- Identify and fix any bugs
+- If major issues found, output: [RETURN TO STAGE 3: CODING]
+
+## 5. Final Verification
+- Run full build/test process
+- Confirm all acceptance criteria met
+
+# WORKFLOW
+1. Check syntax first - quick wins
+2. Verify completeness against blueprint
+3. Run tests
+4. Fix any issues found
+5. If major issues, go back to Stage 3
+6. Do final full verification
+
+End your response with:
+```
+[STAGE 4/4: DEBUGGING - COMPLETE]
+[TASK_COMPLETE]
+```

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

@@ -1,63 +1,63 @@
-=== LONGAGENT STAGE 1/4: PREVIEWING AGENT ===
-
-You are the Previewing Agent in the four-stage LongAgent architecture.
-
-# YOUR ROLE
-You are responsible for understanding the task, exploring the codebase, and extracting critical information.
-
-# STAGE 1: PREVIEW MODE - READ-ONLY
-IMPORTANT: You are in READ-ONLY mode. NO EDITING ALLOWED.
-
-CRITICAL CONSTRAINTS:
-- NO file editing (edit, write, multiedit, patch)
-- NO commands that modify filesystem or system state
-- NO git operations (commit, push, etc.)
-- ONLY use: read, glob, grep, list, bash (read-only)
-- This is ZERO-EXCEPTION rule
-
-# EXPLORATION OBJECTIVES
-
-## 1. Understand User Request
-- Extract core requirements from user input
-- Identify key constraints, goals, and expected outcomes
-- Note any specific files, functions, or patterns mentioned
-
-## 2. Explore Project Structure
-- Use `glob` to map the entire codebase
-- Understand directory organization and file naming conventions
-- Identify project type (e.g., Node.js, Python, React, etc.)
-- Locate configuration files (package.json, tsconfig.json, etc.)
-
-## 3. Analyze Existing Code
-- Search for relevant existing code using `grep`
-- Read critical files to understand current implementation
-- Identify patterns, utilities, and functions that can be reused
-- Look for tests to understand expected behavior
-- Trace dependencies and import relationships
-
-## 4. Extract Key Information
-- Project structure summary
-- Relevant file paths
-- Existing patterns and utilities
-- Potential challenges or constraints
-- Dependencies and their versions
-
-# OUTPUT FORMAT
-
-Present findings structurally:
-- Project Overview (type, stack, config)
-- Critical Files Identified (to modify/create/reference)
-- Reusable Assets (existing functions, patterns, dependencies)
-- Constraints & Considerations
-
-# WORKFLOW
-1. Explore thoroughly - don't rush
-2. Use parallel tool calls for efficiency
-3. Focus on understanding, not solving
-4. Document everything clearly
-5. NO EDITING - STAY IN READ-ONLY MODE
-
-End your response with:
-```
-[STAGE 1/4: PREVIEW - COMPLETE]
-```
+=== LONGAGENT STAGE 1/4: PREVIEWING AGENT ===
+
+You are the Previewing Agent in the four-stage LongAgent architecture.
+
+# YOUR ROLE
+You are responsible for understanding the task, exploring the codebase, and extracting critical information.
+
+# STAGE 1: PREVIEW MODE - READ-ONLY
+IMPORTANT: You are in READ-ONLY mode. NO EDITING ALLOWED.
+
+CRITICAL CONSTRAINTS:
+- NO file editing (edit, write, multiedit, patch)
+- NO commands that modify filesystem or system state
+- NO git operations (commit, push, etc.)
+- ONLY use: read, glob, grep, list, bash (read-only)
+- This is ZERO-EXCEPTION rule
+
+# EXPLORATION OBJECTIVES
+
+## 1. Understand User Request
+- Extract core requirements from user input
+- Identify key constraints, goals, and expected outcomes
+- Note any specific files, functions, or patterns mentioned
+
+## 2. Explore Project Structure
+- Use `glob` to map the entire codebase
+- Understand directory organization and file naming conventions
+- Identify project type (e.g., Node.js, Python, React, etc.)
+- Locate configuration files (package.json, tsconfig.json, etc.)
+
+## 3. Analyze Existing Code
+- Search for relevant existing code using `grep`
+- Read critical files to understand current implementation
+- Identify patterns, utilities, and functions that can be reused
+- Look for tests to understand expected behavior
+- Trace dependencies and import relationships
+
+## 4. Extract Key Information
+- Project structure summary
+- Relevant file paths
+- Existing patterns and utilities
+- Potential challenges or constraints
+- Dependencies and their versions
+
+# OUTPUT FORMAT
+
+Present findings structurally:
+- Project Overview (type, stack, config)
+- Critical Files Identified (to modify/create/reference)
+- Reusable Assets (existing functions, patterns, dependencies)
+- Constraints & Considerations
+
+# WORKFLOW
+1. Explore thoroughly - don't rush
+2. Use parallel tool calls for efficiency
+3. Focus on understanding, not solving
+4. Document everything clearly
+5. NO EDITING - STAY IN READ-ONLY MODE
+
+End your response with:
+```
+[STAGE 1/4: PREVIEW - COMPLETE]
+```

package/src/command/custom-commands.mjs

@@ -1,6 +1,7 @@
 import path from "node:path"
 import { access, readdir, readFile } from "node:fs/promises"
 import { renderTemplate } from "../util/template.mjs"
+import { userRootDir } from "../storage/paths.mjs"
 
 async function exists(target) {
   try {
@@ -34,8 +35,7 @@ async function loadDir(dir, scope) {
 }
 
 export async function loadCustomCommands(cwd = process.cwd()) {
-  const userRoot = process.env.USERPROFILE || process.env.HOME || cwd
-  const userDir = path.join(userRoot, ".kkcode", "commands")
+  const userDir = path.join(userRootDir(), "commands")
   const projectDir = path.join(cwd, ".kkcode", "commands")
   const [globalCommands, projectCommands] = await Promise.all([loadDir(userDir, "global"), loadDir(projectDir, "project")])
   const map = new Map()

package/src/commands/agent.mjs

@@ -68,4 +68,4 @@ export function createAgentCommand() {
     })
 
   return cmd
-}
+}

package/src/commands/background.mjs

@@ -9,16 +9,100 @@ async function withContext(action) {
   return action(ctx)
 }
 
+function printTaskSummary(task) {
+  const summary = BackgroundManager.summarize(task)
+  if (!summary) return
+  console.log(`[${summary.status}] ${summary.id} :: ${summary.description}`)
+  console.log(`  attempt=${summary.attempt} subagent=${summary.subagent || "-"} execution_mode=${summary.execution_mode || "-"} session=${summary.session_id || "-"}`)
+  if (summary.interruption_reason) {
+    console.log(`  interruption=${summary.interruption_reason}`)
+  }
+  if (summary.result_preview) {
+    console.log(`  preview=${summary.result_preview}`)
+  }
+  console.log(`  next=${summary.next_action}`)
+}
+
 export function createBackgroundCommand() {
   const cmd = new Command("background").description("inspect background delegated tasks")
 
   cmd
     .command("list")
     .description("list background tasks")
-    .action(async () => {
+    .option("--json", "print raw JSON")
+    .option("--status <status>", "filter by status")
+    .action(async (options) => {
       await withContext(async () => {
-        const list = await BackgroundManager.list()
-        console.log(JSON.stringify(list, null, 2))
+        const list = (await BackgroundManager.list()).filter((task) => {
+          if (!options.status) return true
+          return String(task.status || "") === String(options.status || "")
+        })
+        if (options.json) {
+          console.log(JSON.stringify(list, null, 2))
+          return
+        }
+        const aggregate = BackgroundManager.summarizeList(list)
+        console.log(`summary: total=${aggregate.total} active=${aggregate.active} pending=${aggregate.counts.pending} running=${aggregate.counts.running} completed=${aggregate.counts.completed} interrupted=${aggregate.counts.interrupted} error=${aggregate.counts.error}`)
+        if (aggregate.recent_terminal.length) {
+          console.log(`recent terminal: ${aggregate.recent_terminal.map((item) => `${item.id}:${item.status}`).join(" | ")}`)
+        }
+        if (!list.length) {
+          console.log("no background tasks")
+          return
+        }
+        for (const task of list) {
+          printTaskSummary(task)
+        }
+      })
+    })
+
+  cmd
+    .command("output")
+    .description("print the terminal result payload for one background task")
+    .requiredOption("--id <id>", "task id")
+    .action(async (options) => {
+      await withContext(async () => {
+        const task = await BackgroundManager.get(options.id)
+        if (!task) {
+          console.error(`not found: ${options.id}`)
+          process.exitCode = 1
+          return
+        }
+        if (!task.result) {
+          console.log(JSON.stringify(BackgroundManager.summarize(task), null, 2))
+          return
+        }
+        console.log(JSON.stringify(task.result, null, 2))
+      })
+    })
+
+  cmd
+    .command("wait")
+    .description("wait for one background task to reach a terminal state")
+    .requiredOption("--id <id>", "task id")
+    .option("--timeout <ms>", "wait timeout in milliseconds", "30000")
+    .option("--json", "print raw JSON")
+    .action(async (options) => {
+      await withContext(async (ctx) => {
+        const task = await BackgroundManager.waitForTask(options.id, {
+          timeoutMs: Number(options.timeout || 30000),
+          config: ctx.configState.config
+        })
+        if (!task) {
+          console.error(`not found: ${options.id}`)
+          process.exitCode = 1
+          return
+        }
+        if (!["completed", "cancelled", "error", "interrupted"].includes(task.status)) {
+          console.error(`timeout waiting for task: ${options.id} (status=${task.status})`)
+          process.exitCode = 1
+          return
+        }
+        if (options.json) {
+          console.log(JSON.stringify(task, null, 2))
+          return
+        }
+        printTaskSummary(task)
       })
     })
 
@@ -26,6 +110,7 @@ export function createBackgroundCommand() {
     .command("show")
     .description("show one background task")
     .requiredOption("--id <id>", "task id")
+    .option("--json", "print raw JSON")
     .action(async (options) => {
       await withContext(async () => {
         const task = await BackgroundManager.get(options.id)
@@ -34,7 +119,47 @@ export function createBackgroundCommand() {
           process.exitCode = 1
           return
         }
-        console.log(JSON.stringify(task, null, 2))
+        if (options.json) {
+          console.log(JSON.stringify(task, null, 2))
+          return
+        }
+        printTaskSummary(task)
+        const summary = BackgroundManager.summarize(task)
+        if (summary?.log_tail?.length) {
+          console.log("  log tail:")
+          for (const line of summary.log_tail) {
+            console.log(`    ${line}`)
+          }
+        }
+        if (task.result) {
+          console.log("  result:")
+          console.log(JSON.stringify(task.result, null, 2))
+        }
+      })
+    })
+
+  cmd
+    .command("logs")
+    .description("show recent log lines for one background task")
+    .requiredOption("--id <id>", "task id")
+    .option("--tail <n>", "number of lines to show", "20")
+    .action(async (options) => {
+      await withContext(async () => {
+        const task = await BackgroundManager.get(options.id)
+        if (!task) {
+          console.error(`not found: ${options.id}`)
+          process.exitCode = 1
+          return
+        }
+        const tailCount = Math.max(1, Number(options.tail || 20))
+        const lines = Array.isArray(task.logs) ? task.logs.slice(-tailCount) : []
+        if (!lines.length) {
+          console.log(`no logs yet: ${options.id}`)
+          return
+        }
+        for (const line of lines) {
+          console.log(line)
+        }
       })
     })
 
@@ -54,6 +179,22 @@ export function createBackgroundCommand() {
       })
     })
 
+  cmd
+    .command("stop")
+    .description("alias for cancel")
+    .requiredOption("--id <id>", "task id")
+    .action(async (options) => {
+      await withContext(async () => {
+        const ok = await BackgroundManager.cancel(options.id)
+        if (!ok) {
+          console.error(`not found: ${options.id}`)
+          process.exitCode = 1
+          return
+        }
+        console.log(`cancel requested: ${options.id}`)
+      })
+    })
+
   cmd
     .command("retry")
     .description("retry one interrupted/error background task")