@kkelly-offical/kkcode 0.1.6 → 0.2.1

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}`)
+    })
+}

package/src/commands/config.mjs

@@ -1,9 +1,12 @@
 import path from "node:path"
-import { readFile, writeFile } from "node:fs/promises"
+import { readFile, writeFile, mkdir } from "node:fs/promises"
 import { Command } from "commander"
 import YAML from "yaml"
 import { importConfig } from "../config/import-config.mjs"
 import { validateConfig } from "../config/schema.mjs"
+import { loadConfig } from "../config/load-config.mjs"
+import { DEFAULT_CONFIG } from "../config/defaults.mjs"
+import { projectConfigCandidates } from "../storage/paths.mjs"
 
 function parseInput(file, raw) {
   if (file.endsWith(".json")) return JSON.parse(raw)
@@ -15,6 +18,72 @@ function stringifyOutput(file, data) {
   return YAML.stringify(data)
 }
 
+function getByPath(obj, keyPath) {
+  const keys = keyPath.split(".")
+  let current = obj
+  for (const key of keys) {
+    if (current == null || typeof current !== "object") return undefined
+    current = current[key]
+  }
+  return current
+}
+
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"])
+
+function setByPath(obj, keyPath, value) {
+  const keys = keyPath.split(".")
+  if (keys.some(k => FORBIDDEN_KEYS.has(k))) {
+    throw new Error(`forbidden key in path: ${keyPath}`)
+  }
+  let current = obj
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i]
+    if (current[key] == null || typeof current[key] !== "object") {
+      current[key] = {}
+    }
+    current = current[key]
+  }
+  current[keys[keys.length - 1]] = value
+}
+
+function coerceValue(raw) {
+  if (raw === "true") return true
+  if (raw === "false") return false
+  if (raw === "null") return null
+  if (raw !== "" && /^-?\d+(\.\d+)?$/.test(raw)) return Number(raw)
+  return raw
+}
+
+function isNonDefault(merged, defaults, keyPath) {
+  const mergedVal = getByPath(merged, keyPath)
+  const defaultVal = getByPath(defaults, keyPath)
+  return JSON.stringify(mergedVal) !== JSON.stringify(defaultVal)
+}
+
+function printTree(obj, defaults, prefix = "", indent = "") {
+  if (obj == null || typeof obj !== "object") {
+    const marker = isNonDefault(obj, defaults, prefix) ? " *" : ""
+    console.log(`${indent}${formatValue(obj)}${marker}`)
+    return
+  }
+  for (const [key, value] of Object.entries(obj)) {
+    const fullPath = prefix ? `${prefix}.${key}` : key
+    if (value != null && typeof value === "object" && !Array.isArray(value)) {
+      console.log(`${indent}${key}:`)
+      printTree(value, defaults, fullPath, indent + "  ")
+    } else {
+      const marker = isNonDefault(value, getByPath(defaults, fullPath), "") ? " *" : ""
+      console.log(`${indent}${key}: ${formatValue(value)}${marker}`)
+    }
+  }
+}
+
+function formatValue(v) {
+  if (v === null) return "null"
+  if (Array.isArray(v)) return JSON.stringify(v)
+  return String(v)
+}
+
 export function createConfigCommand() {
   const cmd = new Command("config").description("manage kkcode config")
 
@@ -40,5 +109,83 @@ export function createConfigCommand() {
       console.log(`imported config written: ${to}`)
     })
 
+  cmd
+    .command("show")
+    .description("show current effective config (merged)")
+    .option("--section <name>", "show only a specific top-level section")
+    .action(async (options) => {
+      const { config, source } = await loadConfig(process.cwd())
+      console.log("# effective config (user + project + defaults)")
+      if (source.userPath) console.log(`# user:    ${source.userPath}`)
+      if (source.projectPath) console.log(`# project: ${source.projectPath}`)
+      console.log("# entries marked with * differ from defaults\n")
+      const target = options.section ? { [options.section]: config[options.section] } : config
+      if (options.section && config[options.section] === undefined) {
+        console.error(`unknown section: ${options.section}`)
+        process.exitCode = 1
+        return
+      }
+      printTree(target, DEFAULT_CONFIG)
+    })
+
+  cmd
+    .command("get <key>")
+    .description("get a config value by dot-path (e.g. provider.default)")
+    .action(async (key) => {
+      const { config } = await loadConfig(process.cwd())
+      const value = getByPath(config, key)
+      if (value === undefined) {
+        console.error(`key not found: ${key}`)
+        process.exitCode = 1
+        return
+      }
+      if (value != null && typeof value === "object") {
+        console.log(YAML.stringify(value).trimEnd())
+      } else {
+        console.log(formatValue(value))
+      }
+    })
+
+  cmd
+    .command("set <key> <value>")
+    .description("set a config value in project config (e.g. provider.default anthropic)")
+    .action(async (key, rawValue) => {
+      const cwd = process.cwd()
+      const candidates = projectConfigCandidates(cwd)
+      let configPath = null
+      for (const c of candidates) {
+        try {
+          await readFile(c, "utf8")
+          configPath = c
+          break
+        } catch { /* not found */ }
+      }
+      if (!configPath) {
+        configPath = candidates[0]
+        await mkdir(path.dirname(configPath), { recursive: true })
+      }
+
+      let existing = {}
+      try {
+        const raw = await readFile(configPath, "utf8")
+        existing = parseInput(configPath, raw) || {}
+      } catch { /* new file */ }
+
+      const value = coerceValue(rawValue)
+      setByPath(existing, key, value)
+
+      const check = validateConfig(existing)
+      if (!check.valid) {
+        console.error("resulting config is invalid:")
+        for (const e of check.errors) console.error(`  - ${e}`)
+        process.exitCode = 1
+        return
+      }
+
+      await writeFile(configPath, stringifyOutput(configPath, existing), "utf8")
+      console.log(`${key} = ${formatValue(value)}`)
+      console.log(`written: ${configPath}`)
+    })
+
   return cmd
 }

package/src/commands/doctor.mjs

@@ -8,6 +8,7 @@ import { auditStats } from "../storage/audit-store.mjs"
 import { fsckSessionStore, flushNow } from "../session/store.mjs"
 import { BackgroundManager } from "../orchestration/background-manager.mjs"
 import { McpRegistry } from "../mcp/registry.mjs"
+import { SkillRegistry } from "../skill/registry.mjs"
 
 const exec = promisify(execCb)
 
@@ -69,8 +70,19 @@ async function buildDoctorReport() {
   const storage = await fsckSessionStore()
   const backgroundTasks = await BackgroundManager.list()
   await McpRegistry.initialize(config)
+  await SkillRegistry.initialize({ ...config, skills: { ...(config.skills || {}), auto_seed: false } }, process.cwd())
   const mcpSnapshot = McpRegistry.healthSnapshot()
   const mcpHealthy = mcpSnapshot.filter((item) => item.ok).length
+  const skillList = SkillRegistry.list()
+  const skillSummary = {
+    enabled: config.skills?.enabled !== false,
+    autoSeed: config.skills?.auto_seed !== false,
+    total: skillList.length,
+    template: skillList.filter((s) => s.type === "template").length,
+    skillMd: skillList.filter((s) => s.type === "skill_md").length,
+    mcpPrompt: skillList.filter((s) => s.type === "mcp_prompt").length,
+    programmable: skillList.filter((s) => s.type === "mjs").length
+  }
 
   return {
     ok: storage.ok,
@@ -94,6 +106,7 @@ async function buildDoctorReport() {
       unhealthy: mcpSnapshot.length - mcpHealthy,
       servers: mcpSnapshot
     },
+    skills: skillSummary,
     storage: {
       sessions: storage,
       eventLog: events,
@@ -120,11 +133,18 @@ function printTextReport(report, themeWarnings = []) {
   }
   for (const p of report.runtime.providersConfigured) {
     console.log(
-      `provider:${p.name} type=${p.type} model=${p.model || "?"} key=${p.apiKeyEnv || "-"} (${p.apiKeyConfigured ? "set" : "missing"})`
+      `provider:${p.name} type=${p.type} model=${p.model || "?"} env=${p.apiKeyEnv || "-"} (${p.apiKeyConfigured ? "set" : "missing"})`
     )
   }
   console.log(`check node=${report.checks.node ? "ok" : "missing"} rg=${report.checks.rg ? "ok" : "missing"} git=${report.checks.git ? "ok" : "missing"}`)
   console.log(`mcp: configured=${report.mcp.configured} healthy=${report.mcp.healthy} unhealthy=${report.mcp.unhealthy}`)
+  console.log(`skills: total=${report.skills.total} template=${report.skills.template + report.skills.skillMd} mcp=${report.skills.mcpPrompt} programmable=${report.skills.programmable}`)
+  if (report.mcp.configured === 0) {
+    console.log("  mcp quickstart: kkcode mcp init --project --with-skills")
+  }
+  if (report.skills.total === 0) {
+    console.log("  skills quickstart: kkcode skill init --project")
+  }
   console.log(`sessions: ok=${report.storage.sessions.ok} index=${report.storage.sessions.sessionsInIndex} files=${report.storage.sessions.filesOnDisk}`)
   console.log(`events: active=${report.storage.eventLog.activeBytes} rotated=${report.storage.eventLog.rotatedFiles}`)
   console.log(`audit: total=${report.storage.audit.total} error1h=${report.storage.audit.error1h} error24h=${report.storage.audit.error24h}`)
@@ -138,11 +158,15 @@ export function createDoctorCommand() {
     .description("run environment diagnostics")
     .option("--json", "print structured diagnostics", false)
     .action(async (options) => {
-      const report = await buildDoctorReport()
-      if (options.json) {
-        console.log(JSON.stringify(report, null, 2))
-        return
+      try {
+        const report = await buildDoctorReport()
+        if (options.json) {
+          console.log(JSON.stringify(report, null, 2))
+          return
+        }
+        printTextReport(report, report.themeWarnings || [])
+      } finally {
+        McpRegistry.shutdown()
       }
-      printTextReport(report, report.themeWarnings || [])
     })
 }

package/src/commands/init.mjs

@@ -35,6 +35,23 @@ const PROVIDER_DEFAULTS = {
   "openai-compatible": { base_url: "", api_key_env: "", default_model: "" }
 }
 
+// Auto-detect available providers by checking environment variables
+function detectProvider() {
+  const registered = new Set(listProviders())
+  const checks = [
+    { provider: "anthropic", env: "ANTHROPIC_API_KEY" },
+    { provider: "openai", env: "OPENAI_API_KEY" }
+  ]
+  const available = []
+  for (const { provider, env } of checks) {
+    if (process.env[env] && registered.has(provider)) available.push(provider)
+  }
+  // Prefer anthropic if both are set, otherwise first available, fallback to openai
+  if (available.includes("anthropic")) return { provider: "anthropic", detected: available }
+  if (available.length) return { provider: available[0], detected: available }
+  return { provider: "openai", detected: [] }
+}
+
 function buildConfig(answers) {
   const config = {
     provider: {
@@ -56,7 +73,11 @@ function buildConfig(answers) {
 
 async function runInteractive(rl) {
   const providers = listProviders()
-  const provider = await askChoice(rl, "select default provider:", providers, "openai")
+  const { provider: detectedProvider, detected } = detectProvider()
+  if (detected.length) {
+    console.log(`\nauto-detected API keys: ${detected.join(", ")}`)
+  }
+  const provider = await askChoice(rl, "select default provider:", providers, detectedProvider)
   const defaults = PROVIDER_DEFAULTS[provider] || {}
 
   let baseUrl = ""
@@ -102,11 +123,16 @@ export function createInitCommand() {
 
       let answers
       if (options.yes) {
+        const { provider, detected } = detectProvider()
+        const defaults = PROVIDER_DEFAULTS[provider] || {}
+        if (detected.length) {
+          console.log(`auto-detected: ${detected.join(", ")} → using ${provider}`)
+        }
         answers = {
-          provider: "openai",
-          baseUrl: "",
-          apiKeyEnv: "OPENAI_API_KEY",
-          model: "gpt-5.3-codex",
+          provider,
+          baseUrl: defaults.base_url || "",
+          apiKeyEnv: defaults.api_key_env || "",
+          model: defaults.default_model || "",
           permissionPolicy: "ask"
         }
       } else {
@@ -134,7 +160,7 @@ export function createInitCommand() {
       const defaultProvider = config.provider.default
       const providerCfg = config.provider[defaultProvider] || {}
       if (providerCfg.api_key_env && !process.env[providerCfg.api_key_env]) {
-        console.log(`note: ${providerCfg.api_key_env} is not set in environment`)
+        console.log(`note: environment variable ${providerCfg.api_key_env} is not set`)
       }
       console.log("run 'kkcode doctor' for full diagnostics")
     })

package/src/commands/longagent.mjs

@@ -1,5 +1,8 @@
 import { Command } from "commander"
+import { readFile } from "node:fs/promises"
 import { LongAgentManager } from "../orchestration/longagent-manager.mjs"
+import { loadConfig } from "../config/load-config.mjs"
+import { eventLogPath } from "../storage/paths.mjs"
 
 export function createLongagentCommand() {
   const cmd = new Command("longagent").description("manage longagent sessions")
@@ -96,5 +99,119 @@ export function createLongagentCommand() {
       console.log(`stage retry requested: ${options.stage} (session=${out.sessionId})`)
     })
 
+  cmd
+    .command("logs")
+    .description("view longagent event logs")
+    .option("--session <id>", "filter by session id")
+    .option("-n, --lines <n>", "number of recent lines", "50")
+    .option("--json", "output raw JSON lines")
+    .action(async (options) => {
+      const logFile = eventLogPath()
+      let raw
+      try {
+        raw = await readFile(logFile, "utf8")
+      } catch {
+        console.error(`no event log found at ${logFile}`)
+        process.exitCode = 1
+        return
+      }
+      const allLines = raw.trim().split("\n").filter(Boolean)
+      let events = allLines.map((line) => {
+        try { return JSON.parse(line) } catch { return null }
+      }).filter(Boolean)
+
+      if (options.session) {
+        events = events.filter((e) => e.sessionId === options.session)
+      }
+      // filter longagent-related events
+      events = events.filter((e) =>
+        String(e.type || "").includes("longagent") ||
+        String(e.type || "").includes("stage") ||
+        String(e.type || "").includes("task")
+      )
+      const limit = Math.max(1, Number(options.lines) || 50)
+      events = events.slice(-limit)
+
+      if (options.json) {
+        for (const e of events) console.log(JSON.stringify(e))
+        return
+      }
+      if (!events.length) {
+        console.log("no longagent events found")
+        return
+      }
+      for (const e of events) {
+        const ts = e.timestamp ? new Date(e.timestamp).toISOString().slice(11, 19) : "??:??:??"
+        const sid = e.sessionId ? e.sessionId.slice(0, 12) : "????????????"
+        const payload = e.payload ? JSON.stringify(e.payload).slice(0, 120) : ""
+        console.log(`${ts} [${sid}] ${e.type || "unknown"}${payload ? " " + payload : ""}`)
+      }
+    })
+
+  cmd
+    .command("config")
+    .description("show effective longagent configuration")
+    .option("--full", "show full merged config (not just longagent section)")
+    .action(async (options) => {
+      const configState = await loadConfig()
+      if (options.full) {
+        console.log(JSON.stringify(configState.config, null, 2))
+        return
+      }
+      const la = configState.config.agent?.longagent || {}
+      console.log("## longagent config")
+      console.log(JSON.stringify(la, null, 2))
+      console.log("\n## sources")
+      console.log(`  user:    ${configState.source.userPath || "(none)"}`)
+      console.log(`  project: ${configState.source.projectPath || "(none)"}`)
+      console.log(`  env:     ${configState.source.envPath || "(none)"}`)
+      if (configState.errors.length) {
+        console.log("\n## errors")
+        for (const e of configState.errors) console.log(`  - ${e}`)
+      }
+    })
+
+  cmd
+    .command("start")
+    .description("launch a longagent session with a prompt")
+    .argument("<prompt>", "task description for longagent")
+    .option("--model <model>", "override model")
+    .option("--provider <type>", "override provider type")
+    .option("--max-iterations <n>", "max iterations (0=unlimited)", "0")
+    .action(async (prompt, options) => {
+      const configState = await loadConfig()
+      const providerKey = options.provider || configState.config.provider.default
+      const providerConf = configState.config.provider[providerKey] || {}
+      const model = options.model || providerConf.default_model
+      if (!model) {
+        console.error(`no model configured for provider "${providerKey}"`)
+        process.exitCode = 1
+        return
+      }
+      const { executeTurn } = await import("../session/engine.mjs")
+      const { newSessionId } = await import("../session/engine.mjs")
+      const sessionId = newSessionId()
+      console.log(`starting longagent session: ${sessionId}`)
+      console.log(`model: ${model}, provider: ${providerKey}`)
+      try {
+        const result = await executeTurn({
+          prompt,
+          mode: "longagent",
+          model,
+          sessionId,
+          configState: { config: configState.config, source: configState.source },
+          providerType: providerKey,
+          baseUrl: providerConf.base_url || null,
+          apiKeyEnv: providerConf.api_key_env || null,
+          maxIterations: Number(options.maxIterations) || 0,
+          output: { write: (t) => process.stdout.write(t) }
+        })
+        console.log(`\nsession ${sessionId} finished (status: ${result.status || "done"})`)
+      } catch (err) {
+        console.error(`longagent error: ${err.message}`)
+        process.exitCode = 1
+      }
+    })
+
   return cmd
 }