@kkelly-offical/kkcode 0.1.7 → 0.2.3-preview.1

package/package.json

@@ -1,46 +1,50 @@
-{
-  "name": "@kkelly-offical/kkcode",
-  "version": "0.1.7",
-  "description": "Team-first terminal AI coding agent CLI with LongAgent orchestration, GitHub integration and themed UX.",
-  "type": "module",
-  "packageManager": "pnpm@10.5.2",
-  "license": "GPL-3.0",
-  "author": "kkelly-offical",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/kkelly-offical/kkcode.git"
-  },
-  "homepage": "https://github.com/kkelly-offical/kkcode",
-  "bugs": {
-    "url": "https://github.com/kkelly-offical/kkcode/issues"
-  },
-  "keywords": [
-    "ai",
-    "coding-agent",
-    "cli",
-    "terminal",
-    "github",
-    "longagent",
-    "code-review",
-    "mcp"
-  ],
-  "bin": {
-    "kkcode": "./src/index.mjs"
-  },
-  "files": [
-    "src/",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=22"
-  },
-  "scripts": {
-    "start": "node ./src/index.mjs",
-    "test": "node --test",
-    "test:e2e": "node --test test/e2e/"
-  },
-  "dependencies": {
-    "commander": "^13.1.0",
-    "yaml": "^2.8.2"
-  }
-}
+{
+  "name": "@kkelly-offical/kkcode",
+  "version": "0.2.3-preview.1",
+  "description": "CLI-first personal assistant with dedicated coding and LongAgent modes for governed terminal workflows, MCP integrations, and extensible automation.",
+  "type": "module",
+  "packageManager": "pnpm@10.5.2",
+  "license": "GPL-3.0",
+  "author": "kkelly-offical",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kkelly-offical/kkcode.git"
+  },
+  "homepage": "https://github.com/kkelly-offical/kkcode",
+  "bugs": {
+    "url": "https://github.com/kkelly-offical/kkcode/issues"
+  },
+  "keywords": [
+    "ai",
+    "coding-agent",
+    "cli",
+    "terminal",
+    "github",
+    "longagent",
+    "code-review",
+    "mcp"
+  ],
+  "bin": {
+    "kkcode": "./src/index.mjs"
+  },
+  "files": [
+    "src/",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "start": "node ./src/index.mjs",
+    "lint": "node ./scripts/check-node-syntax.mjs",
+    "test": "node ./scripts/run-node-tests.mjs",
+    "test:e2e": "node --test test/e2e/*.mjs",
+    "typecheck": "node ./scripts/check-types.mjs",
+    "coverage": "node ./scripts/run-node-tests.mjs --coverage",
+    "release:verify": "node ./scripts/release-verify.mjs"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "yaml": "^2.8.2"
+  }
+}

package/src/agent/agent.mjs

@@ -1,220 +1,228 @@
-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"]
-})
+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 = { assistant: "assistant", plan: "plan", agent: "build", longagent: "longagent" }
+  const mapped = modeMap[mode]
+  return mapped ? registry.get(mapped) || null : null
+}
+
+defineAgent({
+  name: "assistant",
+  description: "Default CLI personal assistant for terminal-native personal work, local tasks, research, and lightweight automation",
+  mode: "primary",
+  permission: "full",
+  tools: 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", "webfetch", "websearch", "question", "enter_plan", "exit_plan"]
+})
+
+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/custom-agent-loader.mjs

@@ -3,6 +3,7 @@ import { access, readdir, readFile } from "node:fs/promises"
 import { pathToFileURL } from "node:url"
 import { parseYaml } from "../util/yaml.mjs"
 import { defineAgent, getAgent } from "./agent.mjs"
+import { userRootDir } from "../storage/paths.mjs"
 
 const state = {
   agents: new Map(),
@@ -82,12 +83,15 @@ async function loadMdAgent(filePath, scope) {
 
 async function loadAgentsFromDir(dir, scope) {
   if (!(await exists(dir))) return []
+  const resolvedDir = path.resolve(dir)
   const entries = await readdir(dir, { withFileTypes: true })
   const agents = []
   for (const entry of entries) {
     if (!entry.isFile()) continue
     const ext = path.extname(entry.name).toLowerCase()
-    const full = path.join(dir, entry.name)
+    const full = path.resolve(dir, entry.name)
+    // Path boundary check: ensure resolved path is within expected directory
+    if (!full.startsWith(resolvedDir + path.sep) && full !== resolvedDir) continue
     try {
       if (ext === ".yaml" || ext === ".yml") {
         const agent = await loadYamlAgent(full, scope)
@@ -107,8 +111,7 @@ async function loadAgentsFromDir(dir, scope) {
 export const CustomAgentRegistry = {
   async initialize(cwd = process.cwd()) {
     state.agents.clear()
-    const userRoot = process.env.USERPROFILE || process.env.HOME || cwd
-    const globalDir = path.join(userRoot, ".kkcode", "agents")
+    const globalDir = path.join(userRootDir(), "agents")
     const projectDir = path.join(cwd, ".kkcode", "agents")
 
     const [globalAgents, projectAgents] = await Promise.all([

package/src/agent/generator.mjs

@@ -1,7 +1,7 @@
 import { writeFile, mkdir } from "node:fs/promises"
 import { join } from "node:path"
-import { homedir } from "node:os"
 import { requestProvider } from "../provider/router.mjs"
+import { userRootDir } from "../storage/paths.mjs"
 
 const AGENT_GEN_SYSTEM = `You are an agent definition generator for kkcode, a terminal AI coding agent.
 Your task is to generate an agent definition file in YAML format based on the user's description.
@@ -96,7 +96,7 @@ export async function generateAgent({ description, configState, providerType, mo
  * Save an agent definition to the global agents directory.
  */
 export async function saveAgentGlobal(filename, content) {
-  const dir = join(homedir(), ".kkcode", "agents")
+  const dir = join(userRootDir(), "agents")
   await mkdir(dir, { recursive: true })
   const filePath = join(dir, filename)
   await writeFile(filePath, content, "utf-8")

package/src/agent/prompt/assistant.txt

@@ -0,0 +1,12 @@
+You are kkcode in ASSISTANT mode: a CLI-first personal assistant for terminal-native work. You can help with local files, directories, logs, system/runtime checks, web lookup/fetch, Git/GitHub assistance, notes, task organization, and bounded automation through the available tools.
+
+# Operating Contract
+- Prefer the lightest terminal-native path that fully answers or completes the user request.
+- Use existing permission, budget, audit, and tool boundaries; never bypass approvals.
+- Treat ordinary local inspection, summarization, command checks, repo hygiene, and research as first-class assistant work.
+- When the request is clearly code mutation, debugging, refactoring, or test repair, use the dedicated coding lane semantics from `agent` / `code` / `coding`.
+- When the request is broad, cross-module, staged, or needs ownership gates, recommend or use LongAgent rather than improvising.
+- Do not imply unsupported surfaces such as GUI desktop automation, IDE integration, remote platform control, or marketplace install flows.
+
+# Response Style
+Be concise, outcome-first, and practical. State what you checked, what changed or did not change, and the next useful action only when it matters.