@kkelly-offical/kkcode 0.1.2

package/src/session/compaction.mjs

@@ -0,0 +1,276 @@
+import { requestProvider } from "../provider/router.mjs"
+import { getConversationHistory, replaceMessages } from "./store.mjs"
+import { HookBus } from "../plugin/hook-bus.mjs"
+import { saveCheckpoint } from "./checkpoint.mjs"
+import { recordTurn } from "../usage/usage-meter.mjs"
+import { loadPricing, calculateCost } from "../usage/pricing.mjs"
+
+const COMPACTION_SYSTEM = `You are a conversation summarizer. Create a structured summary preserving all critical information for continued work.
+
+## Output Format
+
+<summary>
+<goal>The user's overall goal or current task</goal>
+<completed>
+- Completed task with specific details (file paths, function names, line numbers)
+</completed>
+<in_progress>Current work being done, if any</in_progress>
+<files_modified>
+- path/to/file: specific change description
+</files_modified>
+<key_decisions>
+- Decision and reasoning
+- User preferences or constraints
+</key_decisions>
+<errors_resolved>
+- Error description → fix applied
+</errors_resolved>
+<next_steps>
+- Specific next action items
+</next_steps>
+</summary>
+
+Rules:
+- Use the SAME LANGUAGE as the conversation
+- Preserve ALL file paths, function names, variable names, and technical identifiers exactly
+- Include specific code changes, not just "modified file X"
+- Omit tool call metadata and message formatting details
+- Be concise but never drop actionable information`
+
+const DEFAULT_THRESHOLD_MESSAGES = 50
+const DEFAULT_THRESHOLD_RATIO = 0.7
+const DEFAULT_KEEP_RECENT = 6
+const TOOL_RESULT_PREVIEW_LIMIT = 200
+
+// Estimate tokens from a string, accounting for CJK characters (~1.5 chars/token vs ~4 for Latin)
+export function estimateStringTokens(str) {
+  if (!str) return 0
+  let cjk = 0
+  for (let i = 0; i < str.length; i++) {
+    const code = str.charCodeAt(i)
+    if ((code >= 0x4E00 && code <= 0x9FFF) || (code >= 0x3000 && code <= 0x30FF) ||
+        (code >= 0xAC00 && code <= 0xD7AF)) cjk++
+  }
+  const latin = str.length - cjk
+  return Math.ceil(latin / 4 + cjk / 1.5)
+}
+
+const MSG_OVERHEAD = 4 // ~4 tokens per message for role/metadata
+
+export function estimateTokenCount(messages) {
+  let tokens = 0
+  for (const msg of messages) {
+    tokens += MSG_OVERHEAD
+    const content = msg.content
+    if (Array.isArray(content)) {
+      for (const block of content) {
+        if (block.type === "image") {
+          tokens += 1600 // conservative estimate for a typical image
+        } else if (block.type === "tool_use") {
+          tokens += estimateStringTokens(block.name || "")
+          tokens += estimateStringTokens(JSON.stringify(block.input || {}))
+        } else if (block.type === "tool_result") {
+          tokens += estimateStringTokens(String(block.content || ""))
+        } else {
+          tokens += estimateStringTokens(block.text || block.content || "")
+        }
+      }
+    } else {
+      tokens += estimateStringTokens(content || "")
+    }
+  }
+  return tokens
+}
+
+/**
+ * Pre-prune messages before LLM summarization.
+ * - Truncate large tool_result content to a short preview
+ * - Keep tool_use blocks intact (they show model intent)
+ * - Truncate very long plain-text assistant/user messages
+ */
+export function pruneForSummary(messages, previewLimit = TOOL_RESULT_PREVIEW_LIMIT) {
+  return messages.map((msg) => {
+    const content = msg.content
+    if (Array.isArray(content)) {
+      const pruned = content.map((block) => {
+        if (block.type === "tool_result") {
+          const raw = String(block.content || "")
+          if (raw.length > previewLimit) {
+            return {
+              ...block,
+              content: `${raw.slice(0, previewLimit)}... [truncated ${raw.length} chars]`
+            }
+          }
+        }
+        return block
+      })
+      return { ...msg, content: pruned }
+    }
+    // Truncate very long plain-text messages (e.g. large tool output pasted as text)
+    if (typeof content === "string" && content.length > 2000) {
+      return { ...msg, content: `${content.slice(0, 2000)}... [truncated ${content.length} chars]` }
+    }
+    return msg
+  })
+}
+
+const BUILTIN_CONTEXT = {
+  "gpt-5": 272000, "o3": 200000, "o1": 200000,
+  "claude-opus-4": 200000, "claude-3-5": 200000, "claude-3.5": 200000, "claude": 200000,
+  "gemini-2": 1048576, "gemini-1.5": 1048576, "gemini": 128000,
+  "gpt-4o": 128000, "gpt-4": 128000, "gpt-3.5": 16000,
+  "deepseek": 64000, "qwen": 128000
+}
+
+export function modelContextLimit(model, configState = null) {
+  const m = String(model || "").toLowerCase()
+  // 1) Check provider-level context_limit for the active provider
+  const providerCfg = configState?.config?.provider
+  if (providerCfg) {
+    // Per-model override from provider.model_context map
+    const mc = providerCfg.model_context
+    if (mc) {
+      if (mc[model]) return mc[model]
+      for (const key of Object.keys(mc)) {
+        if (m.startsWith(key.toLowerCase())) return mc[key]
+      }
+    }
+    // Provider-level context_limit
+    const active = providerCfg[providerCfg.default]
+    if (active?.context_limit > 0) return active.context_limit
+  }
+  // 2) Builtin prefix match
+  for (const [prefix, limit] of Object.entries(BUILTIN_CONTEXT)) {
+    if (m.includes(prefix)) return limit
+  }
+  return 128000
+}
+
+export function contextUtilization(messages, model, configState = null) {
+  const tokens = estimateTokenCount(messages)
+  const limit = modelContextLimit(model, configState)
+  const ratio = limit > 0 ? Math.min(1, tokens / limit) : 0
+  return {
+    tokens,
+    limit,
+    ratio,
+    percent: Math.round(ratio * 100)
+  }
+}
+
+export function supportsNativeCompaction(providerType, model) {
+  if (providerType !== "anthropic") return false
+  const m = String(model || "").toLowerCase()
+  return m.includes("claude") && (m.includes("opus") || m.includes("sonnet"))
+}
+
+export function shouldCompact({ messages, model, thresholdMessages = DEFAULT_THRESHOLD_MESSAGES, thresholdRatio = DEFAULT_THRESHOLD_RATIO, configState = null, realTokenCount = null }) {
+  if (messages.length >= thresholdMessages) return true
+  const limit = modelContextLimit(model, configState)
+  const tokens = realTokenCount != null ? realTokenCount : estimateTokenCount(messages)
+  return tokens >= limit * thresholdRatio
+}
+
+export async function compactSession({
+  sessionId,
+  model,
+  providerType,
+  configState,
+  keepRecent = DEFAULT_KEEP_RECENT,
+  baseUrl = null,
+  apiKeyEnv = null
+}) {
+  const history = await getConversationHistory(sessionId, 9999)
+  if (history.length <= keepRecent + 2) return { compacted: false, reason: "too few messages" }
+
+  // Find split point that doesn't break tool_use/tool_result pairs
+  let splitIdx = history.length - keepRecent
+  while (splitIdx > 0 && splitIdx < history.length) {
+    const msg = history[splitIdx]
+    const content = msg.content
+    if (Array.isArray(content) && content.some(b => b.type === "tool_result")) {
+      splitIdx-- // include the paired assistant tool_use message
+      continue
+    }
+    break
+  }
+  const toSummarize = history.slice(0, splitIdx)
+  const kept = history.slice(splitIdx)
+
+  // Layer 1: prune large tool outputs before sending to LLM
+  const pruned = pruneForSummary(toSummarize)
+  const summaryPrompt = pruned.map((m) => {
+    const content = m.content
+    if (Array.isArray(content)) {
+      return `[${m.role}]: ${content.map((b) => {
+        if (b.type === "text") return b.text || ""
+        if (b.type === "tool_use") return `[tool_use:${b.name}(${JSON.stringify(b.input || {}).slice(0, 120)})]`
+        if (b.type === "tool_result") return `[tool_result:${b.is_error ? "ERROR " : ""}${b.content || ""}]`
+        return ""
+      }).filter(Boolean).join("\n")}`
+    }
+    return `[${m.role}]: ${content}`
+  }).join("\n\n")
+
+  const hookPayload = await HookBus.sessionCompacting({
+    sessionId,
+    messageCount: history.length,
+    summarizeCount: toSummarize.length,
+    keepCount: kept.length
+  })
+  if (hookPayload?.skip) return { compacted: false, reason: "skipped by hook" }
+
+  let summaryText
+  let compactionUsage = null
+  try {
+    const response = await requestProvider({
+      configState,
+      providerType,
+      model,
+      system: COMPACTION_SYSTEM,
+      messages: [{ role: "user", content: summaryPrompt }],
+      tools: [],
+      baseUrl,
+      apiKeyEnv
+    })
+    summaryText = (response.text || "").trim()
+    compactionUsage = response.usage || null
+  } catch (error) {
+    return { compacted: false, reason: `compaction LLM call failed: ${error.message}` }
+  }
+
+  if (!summaryText) return { compacted: false, reason: "empty summary from LLM" }
+
+  // Replace all messages with: [summary] + [kept recent messages]
+  const summaryMessage = {
+    role: "user",
+    content: `<compaction-summary>\n${summaryText}\n</compaction-summary>`
+  }
+  await replaceMessages(sessionId, [summaryMessage, ...kept])
+
+  // Record compaction LLM usage so it's not "invisible"
+  if (compactionUsage) {
+    try {
+      const { pricing } = await loadPricing(configState)
+      const { amount } = calculateCost(pricing, model, compactionUsage)
+      await recordTurn({ sessionId, usage: compactionUsage, cost: amount })
+    } catch { /* best-effort */ }
+  }
+
+  await saveCheckpoint(sessionId, {
+    kind: "compaction",
+    iteration: 0,
+    compactedAt: Date.now(),
+    summarizeCount: toSummarize.length,
+    keepCount: kept.length,
+    summaryVersion: 1,
+    summaryLength: summaryText.length
+  })
+
+  return {
+    compacted: true,
+    summarizedCount: toSummarize.length,
+    keptCount: kept.length,
+    summaryLength: summaryText.length
+  }
+}

package/src/session/engine.mjs

@@ -0,0 +1,225 @@
+import { randomUUID } from "node:crypto"
+import { loadPricing, calculateCost } from "../usage/pricing.mjs"
+import { recordTurn } from "../usage/usage-meter.mjs"
+import { processTurnLoop } from "./loop.mjs"
+import { runLongAgent } from "./longagent.mjs"
+import { touchSession, setBudgetState } from "./store.mjs"
+import { appendEventLog } from "../storage/event-log.mjs"
+import { EventBus } from "../core/events.mjs"
+import { ToolRegistry } from "../tool/registry.mjs"
+import { resolveAgentForMode } from "../agent/agent.mjs"
+import { estimateStringTokens } from "./compaction.mjs"
+
+let sinkReady = false
+
+function estimateTokens(text) {
+  return Math.max(1, estimateStringTokens(text || ""))
+}
+
+export function resolveMode(inputMode = "agent") {
+  const mode = String(inputMode || "agent").toLowerCase()
+  if (["ask", "plan", "agent", "longagent"].includes(mode)) return mode
+  return "agent"
+}
+
+export function newSessionId() {
+  return `ses_${randomUUID().slice(0, 12)}`
+}
+
+function maybeRegisterSink() {
+  if (sinkReady) return
+  EventBus.registerSink(async (event) => {
+    await appendEventLog(event)
+  })
+  sinkReady = true
+}
+
+function evaluateBudget(config, meter) {
+  const budget = config.usage?.budget || {}
+  const warnings = []
+  const strategy = budget.strategy || "warn"
+  const warnAt = Number(budget.warn_at_percent || 80)
+  let exceeded = false
+
+  if (budget.session_usd && meter.session.cost > 0) {
+    const ratio = (meter.session.cost / budget.session_usd) * 100
+    if (ratio >= 100) exceeded = true
+    if (ratio >= warnAt) warnings.push(`session budget ${ratio.toFixed(1)}% (${meter.session.cost.toFixed(4)}/${budget.session_usd})`)
+  }
+  if (budget.global_usd && meter.global.cost > 0) {
+    const ratio = (meter.global.cost / budget.global_usd) * 100
+    if (ratio >= 100) exceeded = true
+    if (ratio >= warnAt) warnings.push(`global budget ${ratio.toFixed(1)}% (${meter.global.cost.toFixed(4)}/${budget.global_usd})`)
+  }
+  return { warnings, exceeded, strategy }
+}
+
+export async function executeTurn({
+  prompt,
+  contentBlocks = null,
+  mode,
+  model,
+  sessionId,
+  configState,
+  providerType = null,
+  baseUrl = null,
+  apiKeyEnv = null,
+  maxIterations = null,
+  signal = null,
+  output = null,
+  allowQuestion = true,
+  toolContext = {}
+}) {
+  maybeRegisterSink()
+
+  const resolvedProviderType = providerType || configState.config.provider.default
+  const agent = resolveAgentForMode(mode)
+  await ToolRegistry.initialize({
+    config: configState.config,
+    cwd: process.cwd()
+  })
+  await touchSession({
+    sessionId,
+    mode,
+    model,
+    providerType: resolvedProviderType,
+    cwd: process.cwd(),
+    status: mode === "longagent" ? "running-longagent" : "active"
+  })
+
+  const turn =
+    mode === "longagent"
+      ? await runLongAgent({
+          prompt,
+          model,
+          providerType: resolvedProviderType,
+          sessionId,
+          configState,
+          baseUrl,
+          apiKeyEnv,
+          agent,
+          maxIterations:
+            maxIterations === null
+              ? Number(configState.config.agent.longagent.max_iterations || 0)
+              : Number(maxIterations),
+          signal,
+          output,
+          allowQuestion,
+          toolContext
+        })
+      : await processTurnLoop({
+          prompt,
+          contentBlocks,
+          mode,
+          model,
+          providerType: resolvedProviderType,
+          sessionId,
+          configState,
+          baseUrl,
+          apiKeyEnv,
+          agent,
+          output,
+          signal,
+          allowQuestion,
+          toolContext
+        })
+
+  const usage = { ...turn.usage }
+  let estimated = false
+  if ((usage.input || 0) === 0 && (usage.output || 0) === 0) {
+    usage.input = estimateTokens(prompt)
+    usage.output = estimateTokens(turn.reply)
+    estimated = true
+  }
+
+  const pricingInfo = await loadPricing(configState)
+  const costInfo = calculateCost(pricingInfo.pricing, model, usage)
+  const meter = await recordTurn({ sessionId, usage, cost: costInfo.amount })
+  const budgetResult = evaluateBudget(configState.config, meter)
+
+  await setBudgetState(sessionId, {
+    lastTurnCost: costInfo.amount,
+    warnings: budgetResult.warnings,
+    exceeded: budgetResult.exceeded,
+    updatedAt: Date.now()
+  })
+
+  if (budgetResult.exceeded && budgetResult.strategy === "block") {
+    const msg = `budget exceeded — ${budgetResult.warnings.join("; ")}. strategy=block, stopping execution.`
+    return {
+      reply: msg,
+      mode,
+      model,
+      sessionId,
+      turnId: turn.turnId,
+      emittedText: turn.emittedText,
+      context: turn.context,
+      tokenMeter: { ...meter, estimated: estimated || costInfo.unknown },
+      cost: costInfo.amount,
+      costSavings: costInfo.savings,
+      pricingWarnings: pricingInfo.errors,
+      budgetWarnings: budgetResult.warnings,
+      budgetExceeded: true,
+      toolEvents: turn.toolEvents,
+      longagent: mode === "longagent"
+        ? {
+            status: turn.status,
+            phase: turn.phase,
+            gateStatus: turn.gateStatus,
+            currentGate: turn.currentGate,
+            lastGateFailures: turn.lastGateFailures || [],
+            iterations: turn.iterations,
+            recoveryCount: turn.recoveryCount,
+            progress: turn.progress,
+            elapsed: turn.elapsed,
+            stageIndex: turn.stageIndex,
+            stageCount: turn.stageCount,
+            currentStageId: turn.currentStageId,
+            planFrozen: turn.planFrozen,
+            taskProgress: turn.taskProgress,
+            stageProgress: turn.stageProgress,
+            remainingFilesCount: turn.remainingFilesCount,
+            fileChanges: turn.fileChanges || []
+          }
+        : null
+    }
+  }
+
+  return {
+    reply: turn.reply,
+    mode,
+    model,
+    sessionId,
+    turnId: turn.turnId,
+    emittedText: turn.emittedText,
+    context: turn.context,
+    tokenMeter: { ...meter, estimated: estimated || costInfo.unknown },
+    cost: costInfo.amount,
+    costSavings: costInfo.savings,
+    pricingWarnings: pricingInfo.errors,
+    budgetWarnings: budgetResult.warnings,
+    budgetExceeded: false,
+    toolEvents: turn.toolEvents,
+    longagent: mode === "longagent"
+      ? {
+          status: turn.status,
+          phase: turn.phase,
+          gateStatus: turn.gateStatus,
+          currentGate: turn.currentGate,
+          lastGateFailures: turn.lastGateFailures || [],
+          iterations: turn.iterations,
+          recoveryCount: turn.recoveryCount,
+          progress: turn.progress,
+          elapsed: turn.elapsed,
+          stageIndex: turn.stageIndex,
+          stageCount: turn.stageCount,
+          currentStageId: turn.currentStageId,
+          planFrozen: turn.planFrozen,
+          taskProgress: turn.taskProgress,
+          stageProgress: turn.stageProgress,
+          remainingFilesCount: turn.remainingFilesCount,
+          fileChanges: turn.fileChanges || []
+        }
+      : null
+  }
+}

package/src/session/instinct-manager.mjs

@@ -0,0 +1,172 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises"
+import path from "node:path"
+import { memoryDir } from "../storage/paths.mjs"
+
+/**
+ * Instinct Manager — automatic pattern learning system.
+ *
+ * Instincts are small, atomic learned behaviors extracted from sessions.
+ * Each instinct has a confidence score (0.3–0.9) that increases with repeated observation.
+ * High-confidence instincts are injected into the system prompt to guide future behavior.
+ */
+
+function instinctsPath(cwd) {
+  return path.join(memoryDir(cwd), "instincts.json")
+}
+
+function generateId() {
+  return "inst_" + Date.now().toString(36) + Math.random().toString(36).slice(2, 6)
+}
+
+async function loadStore(cwd) {
+  try {
+    const raw = await readFile(instinctsPath(cwd), "utf8")
+    return JSON.parse(raw)
+  } catch {
+    return { instincts: [], version: 1 }
+  }
+}
+
+async function saveStore(cwd, store) {
+  const dir = memoryDir(cwd)
+  await mkdir(dir, { recursive: true })
+  await writeFile(instinctsPath(cwd), JSON.stringify(store, null, 2) + "\n", "utf8")
+}
+
+/**
+ * Add or reinforce an instinct.
+ * If a similar pattern already exists (fuzzy match), increase its confidence.
+ * Otherwise create a new instinct at base confidence 0.3.
+ */
+export async function addInstinct(cwd, pattern, category = "workflow") {
+  const store = await loadStore(cwd)
+  const normalized = pattern.trim().toLowerCase()
+
+  // Fuzzy match: check if any existing instinct is substantially similar
+  const existing = store.instincts.find((inst) => {
+    const existingNorm = inst.pattern.trim().toLowerCase()
+    return existingNorm === normalized || similarity(existingNorm, normalized) > 0.8
+  })
+
+  if (existing) {
+    existing.observations = (existing.observations || 1) + 1
+    existing.confidence = Math.min(0.9, existing.confidence + 0.1)
+    existing.lastSeenAt = Date.now()
+  } else {
+    store.instincts.push({
+      id: generateId(),
+      pattern: pattern.trim(),
+      confidence: 0.3,
+      observations: 1,
+      category,
+      createdAt: Date.now(),
+      lastSeenAt: Date.now()
+    })
+  }
+
+  await saveStore(cwd, store)
+  return existing || store.instincts[store.instincts.length - 1]
+}
+
+/**
+ * List instincts at or above a minimum confidence threshold.
+ */
+export async function listInstincts(cwd, minConfidence = 0.0) {
+  const store = await loadStore(cwd)
+  return store.instincts
+    .filter((inst) => inst.confidence >= minConfidence)
+    .sort((a, b) => b.confidence - a.confidence)
+}
+
+/**
+ * Remove an instinct by ID.
+ */
+export async function removeInstinct(cwd, id) {
+  const store = await loadStore(cwd)
+  const before = store.instincts.length
+  store.instincts = store.instincts.filter((inst) => inst.id !== id)
+  if (store.instincts.length < before) {
+    await saveStore(cwd, store)
+    return true
+  }
+  return false
+}
+
+/**
+ * Export all instincts for team sharing.
+ */
+export async function exportInstincts(cwd) {
+  const store = await loadStore(cwd)
+  return {
+    exportedAt: Date.now(),
+    count: store.instincts.length,
+    instincts: store.instincts
+  }
+}
+
+/**
+ * Import instincts from a teammate's export.
+ * Merges by pattern similarity — existing patterns get reinforced, new ones get added at 0.3.
+ */
+export async function importInstincts(cwd, data) {
+  if (!data || !Array.isArray(data.instincts)) return { imported: 0, reinforced: 0 }
+  let imported = 0
+  let reinforced = 0
+  for (const inst of data.instincts) {
+    if (!inst.pattern) continue
+    const result = await addInstinct(cwd, inst.pattern, inst.category || "workflow")
+    if (result.observations > 1) reinforced++
+    else imported++
+  }
+  return { imported, reinforced }
+}
+
+/**
+ * Format high-confidence instincts for system prompt injection.
+ * Returns a prompt section string, or empty string if no qualifying instincts.
+ */
+export async function formatInstinctsForPrompt(cwd, minConfidence = 0.5) {
+  const instincts = await listInstincts(cwd, minConfidence)
+  if (instincts.length === 0) return ""
+
+  const lines = [
+    "",
+    "## Learned Patterns",
+    "",
+    "These patterns have been observed across your sessions. Follow them unless the user explicitly requests otherwise:",
+    ""
+  ]
+
+  for (const inst of instincts.slice(0, 20)) {
+    const conf = inst.confidence.toFixed(1)
+    lines.push(`- [${conf}] ${inst.pattern}`)
+  }
+
+  if (instincts.length > 20) {
+    lines.push(`  ... and ${instincts.length - 20} more learned patterns`)
+  }
+
+  return lines.join("\n")
+}
+
+// ── Simple string similarity (Dice coefficient) ──
+
+function similarity(a, b) {
+  if (a === b) return 1
+  if (a.length < 2 || b.length < 2) return 0
+  const bigrams = new Map()
+  for (let i = 0; i < a.length - 1; i++) {
+    const bi = a.slice(i, i + 2)
+    bigrams.set(bi, (bigrams.get(bi) || 0) + 1)
+  }
+  let matches = 0
+  for (let i = 0; i < b.length - 1; i++) {
+    const bi = b.slice(i, i + 2)
+    const count = bigrams.get(bi) || 0
+    if (count > 0) {
+      matches++
+      bigrams.set(bi, count - 1)
+    }
+  }
+  return (2 * matches) / (a.length + b.length - 2)
+}

package/src/session/instruction-loader.mjs

@@ -0,0 +1,25 @@
+import path from "node:path"
+import { access, readFile } from "node:fs/promises"
+
+const CANDIDATES = ["AGENTS.md", "CLAUDE.md", "CONTEXT.md", "KKCODE.md", ".kkcode.md", "kkcode.md"]
+
+async function exists(file) {
+  try {
+    await access(file)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export async function loadInstructions(cwd = process.cwd()) {
+  const blocks = []
+  for (const file of CANDIDATES) {
+    const target = path.join(cwd, file)
+    if (!(await exists(target))) continue
+    const content = (await readFile(target, "utf8")).trim()
+    if (!content) continue
+    blocks.push(`Instructions from ${target}\n${content}`)
+  }
+  return blocks
+}