kc-beta 0.1.2 → 0.2.1

package/bin/kc-beta.js

@@ -1,16 +1,28 @@
 #!/usr/bin/env node
 
-const subcommand = process.argv[2];
+// Parse --en / --zh from anywhere in argv (session-only language override)
+const args = process.argv.slice(2);
+let languageOverride = null;
+const filtered = [];
+for (const arg of args) {
+  if (arg === "--en") languageOverride = "en";
+  else if (arg === "--zh") languageOverride = "zh";
+  else filtered.push(arg);
+}
+const subcommand = filtered[0];
 
 (async () => {
   if (subcommand === "onboard" || subcommand === "setup") {
     const { onboard } = await import("../src/cli/onboard.js");
     await onboard();
+  } else if (subcommand === "config") {
+    const { configEditor } = await import("../src/cli/config.js");
+    await configEditor();
   } else if (subcommand === "init") {
     const { init } = await import("../src/cli/init.js");
     await init();
   } else {
     const { main } = await import("../src/cli/index.js");
-    await main();
+    await main({ languageOverride });
   }
 })();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kc-beta",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "KC Agent — LLM document verification agent (pure Node.js CLI)",
   "type": "module",
   "bin": {

package/src/agent/context-window.js

@@ -0,0 +1,151 @@
+import { estimateTokens, estimateMessagesTokens } from "./token-counter.js";
+
+/**
+ * Automatic context windowing for long conversations.
+ * When messages approach the model's context limit, older messages
+ * are compressed into summaries while keeping recent messages intact.
+ */
+export class ContextWindow {
+  /**
+   * @param {object} opts
+   * @param {number} opts.contextLimit - Total model context limit in tokens
+   * @param {number} [opts.reserveForResponse=8192] - Tokens reserved for model output
+   * @param {number} [opts.recentWindowSize=30] - Number of recent messages to always keep
+   */
+  constructor({ contextLimit, reserveForResponse = 8192, recentWindowSize = 30 }) {
+    this.contextLimit = contextLimit;
+    this.reserveForResponse = reserveForResponse;
+    this.recentWindowSize = recentWindowSize;
+  }
+
+  /**
+   * Apply windowing to a message array if it exceeds the token budget.
+   * @param {Array<object>} messages - Full message history
+   * @param {string[]} [phaseSummaries] - Summaries from completed pipeline phases
+   * @returns {{ messages: Array, wasWindowed: boolean, removedCount: number }}
+   */
+  window(messages, phaseSummaries = []) {
+    const totalTokens = estimateMessagesTokens(messages);
+    const budget = this.contextLimit - this.reserveForResponse;
+
+    // If within budget, return as-is
+    if (totalTokens <= budget * 0.85) {
+      return { messages, wasWindowed: false, removedCount: 0 };
+    }
+
+    // Split into older and recent
+    const splitPoint = Math.max(0, messages.length - this.recentWindowSize);
+    const recentMessages = messages.slice(splitPoint);
+    const olderMessages = messages.slice(0, splitPoint);
+
+    if (olderMessages.length === 0) {
+      return { messages, wasWindowed: false, removedCount: 0 };
+    }
+
+    // Build a compact summary of older messages
+    const recentTokens = estimateMessagesTokens(recentMessages);
+    const summaryBudget = budget - recentTokens - 500; // 500 tokens buffer
+    const compactedSummary = this._compactMessages(olderMessages, phaseSummaries, summaryBudget);
+
+    const windowedMessages = [
+      {
+        role: "user",
+        content: `[Context Summary - Earlier conversation compressed]\n\n${compactedSummary}`,
+      },
+      {
+        role: "assistant",
+        content: "Understood. I have the context from the summary above. Continuing with the current work.",
+      },
+      ...recentMessages,
+    ];
+
+    return {
+      messages: windowedMessages,
+      wasWindowed: true,
+      removedCount: olderMessages.length,
+    };
+  }
+
+  /**
+   * Create a mechanical compact summary of messages.
+   * Groups into conversational turns and extracts key info.
+   * @param {Array<object>} messages
+   * @param {string[]} phaseSummaries
+   * @param {number} tokenBudget
+   * @returns {string}
+   */
+  _compactMessages(messages, phaseSummaries, tokenBudget) {
+    const parts = [];
+
+    // Phase summaries first (high signal)
+    if (phaseSummaries.length > 0) {
+      parts.push("## Phase History");
+      for (const s of phaseSummaries) {
+        parts.push(`- ${s}`);
+      }
+      parts.push("");
+    }
+
+    // Extract key events from older messages
+    parts.push("## Conversation Summary");
+    const turns = this._groupIntoTurns(messages);
+
+    for (const turn of turns) {
+      const line = this._summarizeTurn(turn);
+      if (line) {
+        parts.push(`- ${line}`);
+        // Check budget
+        if (estimateTokens(parts.join("\n")) > tokenBudget * 0.9) {
+          parts.push("- [earlier history truncated]");
+          break;
+        }
+      }
+    }
+
+    return parts.join("\n");
+  }
+
+  /**
+   * Group messages into user-turn blocks.
+   * Each turn: { user: string, tools: [{name, summary}], assistantSummary: string }
+   */
+  _groupIntoTurns(messages) {
+    const turns = [];
+    let current = null;
+
+    for (const msg of messages) {
+      if (msg.role === "user") {
+        if (current) turns.push(current);
+        current = { user: msg.content || "", tools: [], assistant: "" };
+      } else if (msg.role === "assistant" && current) {
+        if (msg.content) current.assistant = msg.content;
+        if (msg.tool_calls) {
+          for (const tc of msg.tool_calls) {
+            current.tools.push(tc.function?.name || "unknown");
+          }
+        }
+      }
+      // tool results are captured implicitly via tool names
+    }
+    if (current) turns.push(current);
+    return turns;
+  }
+
+  /**
+   * Summarize a single conversational turn into one line.
+   */
+  _summarizeTurn(turn) {
+    const userSnippet = (turn.user || "").slice(0, 80).replace(/\n/g, " ");
+    if (!userSnippet) return null;
+
+    let line = `User: "${userSnippet}"`;
+    if (turn.tools.length > 0) {
+      line += ` → Tools: ${turn.tools.join(", ")}`;
+    }
+    if (turn.assistant) {
+      const aSnippet = turn.assistant.slice(0, 60).replace(/\n/g, " ");
+      line += ` → "${aSnippet}..."`;
+    }
+    return line;
+  }
+}

package/src/agent/engine.js

@@ -18,6 +18,7 @@ import { DashboardRenderTool } from "./tools/dashboard-render.js";
 import { EvolutionCycleTool } from "./tools/evolution-cycle.js";
 import { TierDowngradeTool } from "./tools/tier-downgrade.js";
 import { AgentTool } from "./tools/agent-tool.js";
+import { WebSearchTool } from "./tools/web-search.js";
 import { SkillLoader } from "./skill-loader.js";
 import { Phase } from "./pipelines/index.js";
 import { ProjectInitializer } from "./pipelines/initializer.js";
@@ -26,6 +27,10 @@ import { SkillAuthoringPipeline } from "./pipelines/skill-authoring.js";
 import { SkillTestingPipeline } from "./pipelines/skill-testing.js";
 import { DistillationEngine as DistillationPipeline } from "./pipelines/distillation.js";
 import { ProductionQCPipeline } from "./pipelines/production-qc.js";
+import { EventLog } from "./event-log.js";
+import { ContextWindow } from "./context-window.js";
+import { SessionState } from "./session-state.js";
+import { estimateTokens, estimateMessagesTokens } from "./token-counter.js";
 
 // Phases where worker LLM tools are available (DISTILL mode)
 const DISTILL_PHASES = new Set([Phase.DISTILLATION, Phase.PRODUCTION_QC]);
@@ -57,8 +62,21 @@ export class AgentEngine {
     this.cornerCases = new CornerCaseRegistry(this.workspace.cwd);
     this.confidence = new ConfidenceScorer(this.workspace.cwd, this.cornerCases);
 
+    // Event log (append-only JSONL, source of truth)
+    this.eventLog = new EventLog(this.workspace.cwd);
+
+    // Context windowing
+    this.contextWindow = new ContextWindow({
+      contextLimit: config.kcContextLimit || 200000,
+      reserveForResponse: config.kcMaxTokens || 65536,
+    });
+
+    // Session state persistence
+    this.sessionState = new SessionState(this.workspace.cwd);
+
     // Build all tool instances (but register phase-appropriate ones)
     this._buildTools = this._createAllTools();
+    this._phaseSummaries = [];
 
     // Pipeline system (meta-meta skills as code)
     this.currentPhase = Phase.BOOTSTRAP;
@@ -85,8 +103,9 @@ export class AgentEngine {
    */
   _createAllTools() {
     const workerLlm = new WorkerLLMCallTool(this.workspace, {
-      apiKey: this.config.siliconflowApiKey,
-      baseUrl: this.config.siliconflowBaseUrl,
+      apiKey: this.config.llmApiKey,
+      baseUrl: this.config.llmBaseUrl,
+      authType: this.config.authType,
     });
 
     return {
@@ -97,8 +116,8 @@ export class AgentEngine {
         new DocumentParseTool(this.workspace, {
           mineruApiUrl: this.config.mineruApiUrl,
           mineruApiKey: this.config.mineruApiKey,
-          siliconflowApiKey: this.config.siliconflowApiKey,
-          siliconflowBaseUrl: this.config.siliconflowBaseUrl,
+          llmApiKey: this.config.llmApiKey,
+          llmBaseUrl: this.config.llmBaseUrl,
           ocrModel: this.config.ocrModelTier1,
         }),
         new DocumentSearchTool(this.workspace),
@@ -108,6 +127,7 @@ export class AgentEngine {
         new AgentTool(this.workspace, (sid) => new AgentEngine({
           client: this.client, config: this.config, sessionId: sid,
         })),
+        new WebSearchTool(this.config.tavilyApiKey),
       ],
       // Distillation+ only (DISTILL mode)
       distill: [
@@ -136,6 +156,144 @@ export class AgentEngine {
     }
   }
 
+  /**
+   * Get current context usage statistics.
+   * @returns {{ totalTokens: number, limit: number, percentage: number }}
+   */
+  getContextStats() {
+    const systemPrompt = this.context.build({
+      skillIndex: this._skillLoader.formatForContext(),
+      pipelineState: this.pipelines[this.currentPhase]?.describeState?.() || null,
+      workspaceState: `Your workspace directory is: ${this.workspace.cwd}`,
+    });
+    const systemTokens = estimateTokens(systemPrompt);
+    const messageTokens = estimateMessagesTokens(this.history.messages);
+    const totalTokens = systemTokens + messageTokens;
+    const limit = this.config.kcContextLimit || 200000;
+    return {
+      totalTokens,
+      limit,
+      percentage: Math.round((totalTokens / limit) * 100),
+    };
+  }
+
+  /**
+   * Compact conversation history by summarizing older messages via LLM.
+   * Keeps the most recent messages intact.
+   * @param {object} [opts]
+   * @param {number} [opts.recentCount=20] - Number of recent messages to keep
+   * @returns {Promise<{removedCount: number, retainedCount: number, summaryTokens: number}|null>}
+   */
+  async compact({ recentCount = 20 } = {}) {
+    if (this.history.messages.length <= recentCount) return null;
+
+    const olderMessages = this.history.messages.slice(0, -recentCount);
+    const recentMessages = this.history.messages.slice(-recentCount);
+
+    let summary;
+    try {
+      const summaryResp = await this.client.chat({
+        model: this.config.kcModel,
+        messages: [
+          {
+            role: "system",
+            content:
+              "You are a conversation summarizer. Produce a concise summary of the following conversation. " +
+              "Focus on: decisions made, files created or modified, current state of work, key findings, " +
+              "unresolved questions. Be specific about file paths, rule IDs, and results. Keep under 2000 tokens.",
+          },
+          {
+            role: "user",
+            content: `Summarize this conversation:\n\n${JSON.stringify(olderMessages)}`,
+          },
+        ],
+        maxTokens: 2048,
+      });
+      summary = summaryResp.choices?.[0]?.message?.content || null;
+    } catch {
+      // LLM summary failed — do mechanical fallback
+      summary = null;
+    }
+
+    if (!summary) {
+      // Mechanical fallback: extract tool names and outcomes
+      const lines = ["Previous conversation summary (mechanical):"];
+      for (const msg of olderMessages) {
+        if (msg.role === "user") {
+          lines.push(`- User: ${(msg.content || "").slice(0, 100)}`);
+        } else if (msg.role === "assistant" && msg.tool_calls) {
+          for (const tc of msg.tool_calls) {
+            lines.push(`- Tool call: ${tc.function?.name}`);
+          }
+        }
+      }
+      summary = lines.join("\n");
+    }
+
+    // Replace history
+    this.history._messages = [
+      { role: "user", content: `[Previous conversation summary]\n${summary}` },
+      { role: "assistant", content: "Understood. I have the context from the summary above. Continuing from where we left off." },
+      ...recentMessages,
+    ];
+    this.history._save();
+
+    // Log compaction event
+    this.eventLog.append("compact", {
+      removedCount: olderMessages.length,
+      retainedCount: recentMessages.length,
+      summary,
+    });
+
+    return {
+      removedCount: olderMessages.length,
+      retainedCount: recentMessages.length,
+      summaryTokens: estimateTokens(summary),
+    };
+  }
+
+  /**
+   * Restore an engine from a persisted session.
+   * @param {object} opts
+   * @param {import('./llm-client.js').LLMClient} opts.client
+   * @param {object} opts.config
+   * @param {string} opts.sessionId
+   * @returns {Promise<AgentEngine>}
+   */
+  static async resume({ client, config, sessionId }) {
+    const engine = new AgentEngine({ client, config, sessionId });
+    const state = engine.sessionState;
+
+    if (state.exists) {
+      const data = state.load();
+      engine.currentPhase = data.currentPhase || Phase.BOOTSTRAP;
+      engine._phaseSummaries = data.phaseSummaries || [];
+      engine._registerToolsForPhase(engine.currentPhase);
+
+      // Restore pipeline milestones
+      const milestones = data.pipelineMilestones || {};
+      for (const [phase, mData] of Object.entries(milestones)) {
+        if (engine.pipelines[phase]?.importState) {
+          engine.pipelines[phase].importState(mData);
+        }
+      }
+
+      engine.eventLog.append("session_resume", {
+        resumedPhase: engine.currentPhase,
+        resumedFromSeq: data.lastEventSeq,
+      });
+    }
+
+    return engine;
+  }
+
+  /**
+   * Save current session state for future resume.
+   */
+  saveState() {
+    this.sessionState.save(this);
+  }
+
   /**
    * Run one conversation turn. Yields AgentEvent objects.
    * Loops: LLM call -> tool execution -> LLM call ... until no tool calls.
@@ -144,6 +302,7 @@ export class AgentEngine {
    */
   async *runTurn(userMessage) {
     this.history.addUser(userMessage);
+    this.eventLog.append("user_message", { content: userMessage });
 
     // Pipeline state injection
     const pipeline = this.pipelines[this.currentPhase];
@@ -157,7 +316,21 @@ export class AgentEngine {
     const tools = this.toolRegistry.schemasOpenai();
 
     while (true) {
-      const messages = [{ role: "system", content: systemPrompt }, ...this.history.messages];
+      // Apply context windowing before sending to LLM
+      const windowed = this.contextWindow.window(this.history.messages, this._phaseSummaries);
+      const messages = [{ role: "system", content: systemPrompt }, ...windowed.messages];
+
+      if (windowed.wasWindowed) {
+        this.eventLog.append("context_windowed", {
+          removedCount: windowed.removedCount,
+          totalBefore: this.history.messages.length,
+        });
+      }
+
+      this.eventLog.append("llm_start", {
+        model: this.config.kcModel,
+        messageCount: messages.length,
+      });
 
       try {
         let collectedText = "";
@@ -194,6 +367,7 @@ export class AgentEngine {
           }
         }
 
+        // Log the complete assistant message (coalesced, not per-delta)
         const assistantMsg = { role: "assistant", content: collectedText || null };
         if (toolCallsAcc.size > 0) {
           assistantMsg.tool_calls = Array.from(toolCallsAcc.values()).map((tc) => ({
@@ -203,8 +377,14 @@ export class AgentEngine {
           }));
         }
         this.history.addRaw(assistantMsg);
+        this.eventLog.append("assistant_message", {
+          content: collectedText || null,
+          toolCalls: assistantMsg.tool_calls || [],
+        });
 
         if (toolCallsAcc.size === 0) {
+          this.eventLog.append("turn_complete", {});
+          this.saveState();
           yield new AgentEvent({ type: "turn_complete" });
           return;
         }
@@ -216,8 +396,16 @@ export class AgentEngine {
             inputData = tc.arguments ? JSON.parse(tc.arguments) : {};
           } catch { /* ignore */ }
 
+          this.eventLog.append("tool_start", { name: tc.name, input: inputData });
           yield new AgentEvent({ type: "tool_start", name: tc.name, input: inputData });
+
           const result = await this.toolRegistry.execute(tc.name, inputData);
+
+          this.eventLog.append("tool_result", {
+            name: tc.name,
+            output: result.content?.slice(0, 5000) || "",
+            isError: result.isError,
+          });
           yield new AgentEvent({
             type: "tool_result",
             name: tc.name,
@@ -236,8 +424,16 @@ export class AgentEngine {
             const pEvent = pipeline.onToolResult(tc.name, inputData, result);
             if (pEvent) {
               if (pEvent.type === "phase_ready" && pEvent.nextPhase) {
+                const phaseSummary = `[${this.currentPhase.toUpperCase()} completed]: ${pEvent.message || ""}`;
+                this._phaseSummaries.push(phaseSummary);
+                this.eventLog.append("phase_transition", {
+                  from: this.currentPhase,
+                  to: pEvent.nextPhase,
+                  summary: phaseSummary,
+                });
                 this.currentPhase = pEvent.nextPhase;
                 this._registerToolsForPhase(this.currentPhase);
+                this.saveState();
               }
               yield new AgentEvent({
                 type: "pipeline_event",
@@ -248,6 +444,7 @@ export class AgentEngine {
         }
 
       } catch (err) {
+        this.eventLog.append("error", { message: err.message });
         yield new AgentEvent({ type: "error", message: err.message });
         return;
       }

package/src/agent/event-log.js

@@ -0,0 +1,111 @@
+import fs from "node:fs";
+import path from "node:path";
+import { estimateTokens } from "./token-counter.js";
+
+/**
+ * Append-only JSONL event log for KC agent sessions.
+ * Each line is a JSON object: { seq, ts, type, data }
+ *
+ * This is the source of truth for session history. ConversationHistory
+ * and display logs become views over this log.
+ */
+export class EventLog {
+  /**
+   * @param {string} workspacePath - Session workspace directory
+   */
+  constructor(workspacePath) {
+    this._dir = path.join(workspacePath, "logs");
+    this._logPath = path.join(this._dir, "events.jsonl");
+    this._seq = 0;
+    this._estimatedTokens = 0;
+    this._initFromExisting();
+  }
+
+  /** Current sequence number */
+  get currentSeq() { return this._seq; }
+
+  /** Estimated total tokens across all events */
+  get estimatedTokens() { return this._estimatedTokens; }
+
+  /** Path to the log file */
+  get logPath() { return this._logPath; }
+
+  /**
+   * Initialize sequence counter and token estimate from existing log file.
+   */
+  _initFromExisting() {
+    if (!fs.existsSync(this._logPath)) return;
+    try {
+      const content = fs.readFileSync(this._logPath, "utf-8");
+      const lines = content.split("\n").filter((l) => l.trim());
+      for (const line of lines) {
+        try {
+          const event = JSON.parse(line);
+          if (event.seq > this._seq) this._seq = event.seq;
+          this._estimatedTokens += this._eventTokens(event);
+        } catch { /* skip malformed lines */ }
+      }
+    } catch { /* file read error, start fresh */ }
+  }
+
+  /**
+   * Append an event to the log.
+   * @param {string} type - Event type
+   * @param {object} [data] - Event payload
+   * @returns {number} The sequence number of the appended event
+   */
+  append(type, data = {}) {
+    this._seq++;
+    const event = {
+      seq: this._seq,
+      ts: new Date().toISOString(),
+      type,
+      data,
+    };
+
+    fs.mkdirSync(this._dir, { recursive: true });
+    fs.appendFileSync(this._logPath, JSON.stringify(event) + "\n", "utf-8");
+
+    this._estimatedTokens += this._eventTokens(event);
+    return this._seq;
+  }
+
+  /**
+   * Read events from the log with optional filtering.
+   * @param {object} [opts]
+   * @param {number} [opts.fromSeq] - Start reading from this sequence (inclusive)
+   * @param {number} [opts.toSeq] - Stop reading at this sequence (inclusive)
+   * @param {string[]} [opts.types] - Only return events of these types
+   * @returns {Array<object>}
+   */
+  read({ fromSeq = 0, toSeq = Infinity, types } = {}) {
+    if (!fs.existsSync(this._logPath)) return [];
+
+    const events = [];
+    const content = fs.readFileSync(this._logPath, "utf-8");
+    const lines = content.split("\n").filter((l) => l.trim());
+
+    for (const line of lines) {
+      try {
+        const event = JSON.parse(line);
+        if (event.seq < fromSeq || event.seq > toSeq) continue;
+        if (types && !types.includes(event.type)) continue;
+        events.push(event);
+      } catch { /* skip */ }
+    }
+
+    return events;
+  }
+
+  /**
+   * Estimate tokens for a single event (for running total).
+   * @param {object} event
+   * @returns {number}
+   */
+  _eventTokens(event) {
+    const dataStr = typeof event.data === "string"
+      ? event.data
+      : JSON.stringify(event.data || {});
+    return estimateTokens(dataStr);
+  }
+}