@kkelly-offical/kkcode 0.1.7 → 0.2.1

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")

package/src/commands/chat.mjs

@@ -1,68 +1,109 @@
-import { Command } from "commander"
-import { buildContext, printContextWarnings } from "../context.mjs"
-import { executeTurn, newSessionId, resolveMode } from "../session/engine.mjs"
-import { renderStatusBar } from "../theme/status-bar.mjs"
+import { Command } from "commander"
+import { buildContext, printContextWarnings } from "../context.mjs"
+import { ensureEventSinks, executeTurn, formatPublicModeSummary, getPublicModeContract, newSessionId, resolveMode, resolvePromptMode, summarizeRouteDecision } from "../session/engine.mjs"
+import { emitRouteDecisionEvent } from "../session/routing-observability.mjs"
+import { renderStatusBar } from "../theme/status-bar.mjs"
 import { applyCommandTemplate, loadCustomCommands } from "../command/custom-commands.mjs"
 import { ToolRegistry } from "../tool/registry.mjs"
+import { SkillRegistry } from "../skill/registry.mjs"
+import { PermissionEngine } from "../permission/engine.mjs"
 import { HookBus, initHookBus } from "../plugin/hook-bus.mjs"
 import { listProviders } from "../provider/router.mjs"
+import { EventBus } from "../core/events.mjs"
+import { EVENT_TYPES } from "../core/constants.mjs"
+
+export function resolveChatExecutionMode(prompt, requestedMode) {
+  return resolvePromptMode(prompt, requestedMode)
+}
 
 export function createChatCommand() {
   const providers = listProviders()
   return new Command("chat")
-    .description("run one prompt in ask/plan/agent/longagent mode")
+    .description("run one prompt in assistant/plan/agent/code/longagent mode (assistant = default personal lane)")
     .argument("<prompt...>", "prompt text")
-    .option("--mode <mode>", "ask|plan|agent|longagent", "agent")
+    .option("--mode <mode>", "assistant|plan|agent|code|coding|longagent", "assistant")
     .option("--model <model>", "model id")
     .option("--provider-type <type>", `provider type (${providers.join("|")})`)
-    .option("--base-url <url>", "provider base url override")
-    .option("--api-key-env <name>", "api key env override")
-    .option("--max-iterations <n>", "longagent max iterations (0 = unlimited)")
-    .option("--session <id>", "session id")
-    .action(async (promptParts, options) => {
-      const ctx = await buildContext()
-      printContextWarnings(ctx)
-      let prompt = promptParts.join(" ").trim()
-      if (prompt.startsWith("/")) {
-        const commands = await loadCustomCommands(process.cwd())
-        const [name, ...argTokens] = prompt.slice(1).split(/\s+/)
-        const custom = commands.find((item) => item.name === name)
-        if (custom) {
-          const args = argTokens.join(" ").trim()
-          prompt = applyCommandTemplate(custom.template, args, {
-            path: process.cwd()
-          })
-        }
-      }
-
-      const mode = resolveMode(options.mode)
-      const providerType = options.providerType ?? ctx.configState.config.provider.default
-      const providerDefaults = ctx.configState.config.provider[providerType]
-      if (!providerDefaults) {
-        throw new Error(`unknown provider type: ${providerType}`)
-      }
-      const model = options.model ?? providerDefaults.default_model
-      const sessionId = options.session || newSessionId()
-
-      await ToolRegistry.initialize({
-        config: ctx.configState.config,
-        cwd: process.cwd()
-      })
-
-      await initHookBus()
-      const chatParams = await HookBus.chatParams({
-        prompt,
-        mode,
-        model,
-        providerType,
-        sessionId,
-        baseUrl: options.baseUrl ?? null,
-        apiKeyEnv: options.apiKeyEnv ?? null
-      })
-
+    .option("--base-url <url>", "provider base url override")
+    .option("--api-key-env <name>", "api key env override")
+    .option("--max-iterations <n>", "longagent max iterations (0 = unlimited)")
+    .option("--session <id>", "session id")
+    .action(async (promptParts, options) => {
+      const ctx = await buildContext()
+      printContextWarnings(ctx)
+      PermissionEngine.setTrusted(ctx.trustState?.trusted !== false)
+      let prompt = promptParts.join(" ").trim()
+      if (prompt.startsWith("/")) {
+        const commands = await loadCustomCommands(process.cwd())
+        const [name, ...argTokens] = prompt.slice(1).split(/\s+/)
+        const custom = commands.find((item) => item.name === name)
+        if (custom) {
+          const args = argTokens.join(" ").trim()
+          prompt = applyCommandTemplate(custom.template, args, {
+            path: process.cwd()
+          })
+        }
+      }
+
+      const mode = resolveMode(options.mode)
+      const providerType = options.providerType ?? ctx.configState.config.provider.default
+      const providerDefaults = ctx.configState.config.provider[providerType]
+      if (!providerDefaults) {
+        throw new Error(`unknown provider type: ${providerType}`)
+      }
+      const model = options.model ?? providerDefaults.default_model
+      const sessionId = options.session || newSessionId()
+
+      await ToolRegistry.initialize({
+        config: ctx.configState.config,
+        cwd: process.cwd()
+      })
+      await SkillRegistry.initialize(ctx.configState.config, process.cwd())
+
+      await initHookBus()
+      const chatParams = await HookBus.chatParams({
+        prompt,
+        mode,
+        model,
+        providerType,
+        sessionId,
+        baseUrl: options.baseUrl ?? null,
+        apiKeyEnv: options.apiKeyEnv ?? null
+      })
+
+      const routedMode = resolveChatExecutionMode(chatParams.prompt ?? prompt, chatParams.mode ?? mode)
+      const effectiveMode = routedMode.effectiveMode
+      const effectiveExplanation = routedMode.route.explanation || routedMode.route.reason
+      const requestedContract = getPublicModeContract(routedMode.requestedMode)
+      const effectiveContract = routedMode.effectiveContract || getPublicModeContract(effectiveMode)
+      ensureEventSinks()
+      await emitRouteDecisionEvent({
+        sessionId,
+        source: "chat",
+        requestedMode: routedMode.requestedMode,
+        route: routedMode.route,
+        prompt: chatParams.prompt ?? prompt
+      })
+
+      if (routedMode.route.changed) {
+        console.log(`mode routed: ${routedMode.requestedMode} -> ${effectiveMode} (${effectiveExplanation})`)
+      } else if (routedMode.route.forced && routedMode.route.suggestion) {
+        console.log(`mode kept: ${effectiveMode} (${effectiveExplanation}; suggested ${routedMode.route.suggestion})`)
+      } else if (routedMode.route.suggestion === "longagent" && (routedMode.requestedMode === "assistant" || routedMode.requestedMode === "agent")) {
+        console.log(`mode note: ${effectiveMode} (${effectiveExplanation}; consider --mode longagent)`)
+      } else {
+        console.log(`mode: ${effectiveMode} (${effectiveExplanation})`)
+      }
+      if (routedMode.requestedMode !== effectiveMode) {
+        console.log(`requested lane: ${requestedContract.summary}`)
+      }
+      console.log(`effective lane: ${formatPublicModeSummary(effectiveMode)}`)
+      console.log(`lane guarantee: ${effectiveContract.guarantee}`)
+      console.log(`route summary: ${summarizeRouteDecision(routedMode.route)}`)
+
       const result = await executeTurn({
         prompt: chatParams.prompt ?? prompt,
-        mode: chatParams.mode ?? mode,
+        mode: effectiveMode,
         model: chatParams.model ?? model,
         sessionId,
         configState: ctx.configState,
@@ -74,41 +115,41 @@ export function createChatCommand() {
           ? { write: (chunk) => process.stdout.write(String(chunk || "")) }
           : null
       })
-
+
       const status = renderStatusBar({
-        mode,
+        mode: effectiveMode,
         model: result.model,
-        permission: ctx.configState.config.permission.default_policy,
+        permission: ctx.configState.config.permission.mode || ctx.configState.config.permission.default_policy,
         tokenMeter: result.tokenMeter,
-        aggregation: ctx.configState.config.usage.aggregation,
-        cost: result.cost,
+        aggregation: ctx.configState.config.usage.aggregation,
+        cost: result.cost,
         showCost: ctx.configState.config.ui.status.show_cost,
         showTokenMeter: ctx.configState.config.ui.status.show_token_meter,
         theme: ctx.themeState.theme,
         layout: ctx.configState.config.ui.layout,
-        longagentState: mode === "longagent" ? result.longagent : null
+        longagentState: effectiveMode === "longagent" ? result.longagent : null
       })
-
+
       console.log(status)
       console.log("")
       const streamEnabled = ctx.configState.config.provider[chatParams.providerType ?? providerType]?.stream !== false
       if (!streamEnabled || !result.emittedText) {
         console.log(result.reply)
       }
-      console.log("")
-      if (result.toolEvents.length) {
-        console.log(`tool events: ${result.toolEvents.length}`)
-      }
-      if (result.pricingWarnings.length) {
-        for (const warning of result.pricingWarnings) {
-          console.log(`pricing warning: ${warning}`)
-        }
-      }
-      if (result.budgetWarnings.length) {
-        for (const warning of result.budgetWarnings) {
-          console.log(`budget warning: ${warning}`)
-        }
-      }
-      console.log(`session: ${sessionId}`)
-    })
-}
+      console.log("")
+      if (result.toolEvents.length) {
+        console.log(`tool events: ${result.toolEvents.length}`)
+      }
+      if (result.pricingWarnings.length) {
+        for (const warning of result.pricingWarnings) {
+          console.log(`pricing warning: ${warning}`)
+        }
+      }
+      if (result.budgetWarnings.length) {
+        for (const warning of result.budgetWarnings) {
+          console.log(`budget warning: ${warning}`)
+        }
+      }
+      console.log(`session: ${sessionId}`)
+    })
+}