kc-beta 0.1.0

package/src/agent/pipelines/production-qc.js

@@ -0,0 +1,99 @@
+import fs from "node:fs";
+import path from "node:path";
+import { PipelineEvent } from "./index.js";
+import { Pipeline } from "./base.js";
+
+const FREQUENCY_MAP = { high: 1.0, mid: 0.5, low: 0.2 };
+
+export class ProductionQCPipeline extends Pipeline {
+  constructor(workspace) {
+    super();
+    this._workspace = workspace;
+    this.batchesProcessed = 0;
+    this.totalDocuments = 0;
+    this.documentsReviewed = 0;
+    this.accuracyByRule = {};
+    this.confidenceDistribution = { low: 0, medium: 0, high: 0 };
+    this.issuesFound = [];
+    this.monitoringPhase = "initial";
+    this._samplingRate = 0.5;
+    this._accuracyThreshold = 0.9;
+    this._scanWorkspace();
+  }
+
+  _scanWorkspace() {
+    this._loadConfig();
+    this._scanQcResults();
+  }
+
+  _loadConfig() {
+    const envPath = path.join(this._workspace.cwd, ".env");
+    if (!fs.existsSync(envPath)) return;
+    for (const line of fs.readFileSync(envPath, "utf-8").split("\n")) {
+      if (line.startsWith("MONITOR_FREQUENCY=")) this._samplingRate = FREQUENCY_MAP[line.split("=")[1].trim().toLowerCase()] ?? 0.5;
+      if (line.startsWith("WORKFLOW_ACCURACY=")) try { this._accuracyThreshold = parseFloat(line.split("=")[1]); } catch { /* skip */ }
+    }
+  }
+
+  _scanQcResults() {
+    this.batchesProcessed = 0;
+    this.totalDocuments = 0;
+    this.documentsReviewed = 0;
+    this.accuracyByRule = {};
+    this.confidenceDistribution = { low: 0, medium: 0, high: 0 };
+    this.issuesFound = [];
+
+    const qcDir = path.join(this._workspace.cwd, "output", "qc");
+    if (!fs.existsSync(qcDir)) return;
+
+    for (const f of fs.readdirSync(qcDir).filter((f) => f.endsWith(".json")).sort()) {
+      try {
+        const data = JSON.parse(fs.readFileSync(path.join(qcDir, f), "utf-8"));
+        this.batchesProcessed++;
+        this.totalDocuments += typeof data.documents === "number" ? data.documents : (data.total || 0);
+        this.documentsReviewed += data.reviewed || 0;
+        if (data.accuracy_by_rule) Object.assign(this.accuracyByRule, data.accuracy_by_rule);
+        if (data.confidence) {
+          for (const band of ["low", "medium", "high"]) this.confidenceDistribution[band] += data.confidence[band] || 0;
+        }
+        if (Array.isArray(data.issues)) this.issuesFound.push(...data.issues);
+      } catch { /* skip */ }
+    }
+
+    // Determine monitoring phase
+    if (this.batchesProcessed < 3) this.monitoringPhase = "initial";
+    else if (this.issuesFound.length > 0) this.monitoringPhase = "active";
+    else if (Object.values(this.accuracyByRule).every((a) => a >= this._accuracyThreshold)) this.monitoringPhase = "stable";
+    else this.monitoringPhase = "active";
+  }
+
+  describeState() {
+    this._scanWorkspace();
+    const parts = ["## Current Phase: PRODUCTION_QC"];
+    parts.push(`### Progress\n- Batches: ${this.batchesProcessed}\n- Documents: ${this.totalDocuments}\n- Reviewed: ${this.documentsReviewed}\n- Monitoring: ${this.monitoringPhase}\n- Sampling rate: ${(this._samplingRate * 100).toFixed(0)}%`);
+
+    if (Object.keys(this.accuracyByRule).length) {
+      const lines = Object.entries(this.accuracyByRule).map(([r, a]) => `- ${r}: ${a}`);
+      parts.push("### Accuracy by rule\n" + lines.join("\n"));
+    }
+
+    if (this.monitoringPhase === "initial") {
+      parts.push("### What to do now\nRun workflows on input/ documents. Save results to output/. Review and save QC to output/qc/.");
+    } else if (this.monitoringPhase === "stable") {
+      parts.push("### Status: Stable\nWorkflows running reliably. Spot-check only.");
+    }
+    return parts.join("\n\n");
+  }
+
+  onToolResult(toolName, toolInput, result) {
+    if (result.isError) return null;
+    const wasStable = this.monitoringPhase === "stable";
+    if (toolName === "workspace_file" && (toolInput.path || "").includes("output/")) this._scanQcResults();
+    if (!wasStable && this.monitoringPhase === "stable") {
+      return new PipelineEvent({ type: "milestone", message: "Production QC reached stable monitoring phase." });
+    }
+    return null;
+  }
+
+  exitCriteriaMet() { return this.monitoringPhase === "stable"; }
+}

package/src/agent/pipelines/skill-authoring.js

@@ -0,0 +1,83 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Phase, PipelineEvent } from "./index.js";
+import { Pipeline } from "./base.js";
+
+export class SkillAuthoringPipeline extends Pipeline {
+  constructor(workspace) {
+    super();
+    this._workspace = workspace;
+    this.totalRules = [];
+    this.skillsAuthored = [];
+    this.skillsWithScripts = [];
+    this._scanWorkspace();
+  }
+
+  _scanWorkspace() {
+    this._loadRules();
+    this._scanSkills();
+  }
+
+  _loadRules() {
+    this.totalRules = [];
+    const rulesDir = path.join(this._workspace.cwd, "rules");
+    if (!fs.existsSync(rulesDir)) return;
+    for (const f of fs.readdirSync(rulesDir).filter((f) => f.endsWith(".json"))) {
+      try {
+        const data = JSON.parse(fs.readFileSync(path.join(rulesDir, f), "utf-8"));
+        const rules = Array.isArray(data) ? data : (data.rules || []);
+        for (const r of rules) { if (r.id) this.totalRules.push(r.id); }
+      } catch { /* skip */ }
+    }
+  }
+
+  _scanSkills() {
+    this.skillsAuthored = [];
+    this.skillsWithScripts = [];
+    const dir = path.join(this._workspace.cwd, "rule_skills");
+    if (!fs.existsSync(dir)) return;
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!e.isDirectory() || e.name.startsWith("__")) continue;
+      const skillPath = path.join(dir, e.name);
+      if (fs.existsSync(path.join(skillPath, "SKILL.md")) || fs.readdirSync(skillPath).some((f) => f.endsWith(".py"))) {
+        this.skillsAuthored.push(e.name);
+      }
+      const scriptsDir = path.join(skillPath, "scripts");
+      if (fs.existsSync(scriptsDir) && fs.readdirSync(scriptsDir).length > 0) {
+        this.skillsWithScripts.push(e.name);
+      }
+    }
+  }
+
+  describeState() {
+    this._scanWorkspace();
+    const total = this.totalRules.length;
+    const parts = ["## Current Phase: SKILL_AUTHORING"];
+    parts.push(`### Progress\n- Rules from extraction: ${total}\n- Skills authored: ${this.skillsAuthored.length}\n- Skills with scripts/: ${this.skillsWithScripts.length}`);
+
+    if (this.exitCriteriaMet()) {
+      parts.push("### Ready\nAll rules have skills. Proceed to SKILL_TESTING.");
+    } else if (this.skillsAuthored.length === 0) {
+      parts.push("### What to do now\nWrite a SKILL.md for each rule in rule_skills/{rule_id}/.\nDescribe: what to check, where to look, what to extract, how to judge.");
+    } else {
+      const remaining = this.totalRules.filter((r) => !this.skillsAuthored.includes(r));
+      parts.push(`### What to do now\n${total - this.skillsAuthored.length} rules still need skills. Remaining: ${remaining.slice(0, 10).join(", ")}`);
+    }
+    return parts.join("\n\n");
+  }
+
+  onToolResult(toolName, toolInput, result) {
+    if (result.isError) return null;
+    const wasReady = this.exitCriteriaMet();
+    if (toolName === "workspace_file" && (toolInput.path || "").includes("rule_skills/")) this._scanSkills();
+    if (!wasReady && this.exitCriteriaMet()) {
+      return new PipelineEvent({ type: "phase_ready", message: "Skill authoring complete. Ready for SKILL_TESTING.", nextPhase: Phase.SKILL_TESTING });
+    }
+    return null;
+  }
+
+  exitCriteriaMet() {
+    if (!this.totalRules.length) return false;
+    return this.skillsAuthored.length >= this.totalRules.length && this.skillsWithScripts.length >= this.skillsAuthored.length * 0.5;
+  }
+}

package/src/agent/pipelines/skill-testing.js

@@ -0,0 +1,111 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Phase, PipelineEvent } from "./index.js";
+import { Pipeline } from "./base.js";
+
+export class SkillTestingPipeline extends Pipeline {
+  constructor(workspace) {
+    super();
+    this._workspace = workspace;
+    this.skillsToTest = [];
+    this.skillsTested = {};
+    this.skillsPassing = [];
+    this.iterationCount = 0;
+    this._accuracyThreshold = 0.9;
+    this._maxIterations = 20;
+    this._scanWorkspace();
+  }
+
+  _scanWorkspace() {
+    this._loadConfig();
+    this._loadSkills();
+    this._loadTestResults();
+    this._loadEvolutionLog();
+  }
+
+  _loadConfig() {
+    const envPath = path.join(this._workspace.cwd, ".env");
+    if (!fs.existsSync(envPath)) return;
+    for (const line of fs.readFileSync(envPath, "utf-8").split("\n")) {
+      if (line.startsWith("SKILL_ACCURACY=")) try { this._accuracyThreshold = parseFloat(line.split("=")[1]); } catch { /* skip */ }
+      if (line.startsWith("MAX_ITERATIONS=")) try { this._maxIterations = parseInt(line.split("=")[1]); } catch { /* skip */ }
+    }
+  }
+
+  _loadSkills() {
+    this.skillsToTest = [];
+    const dir = path.join(this._workspace.cwd, "rule_skills");
+    if (!fs.existsSync(dir)) return;
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (e.isDirectory() && !e.name.startsWith("__")) {
+        const p = path.join(dir, e.name);
+        if (fs.existsSync(path.join(p, "SKILL.md")) || fs.readdirSync(p).some((f) => f.endsWith(".py"))) {
+          this.skillsToTest.push(e.name);
+        }
+      }
+    }
+  }
+
+  _loadTestResults() {
+    this.skillsTested = {};
+    this.skillsPassing = [];
+    const outDir = path.join(this._workspace.cwd, "output");
+    if (!fs.existsSync(outDir)) return;
+    for (const f of fs.readdirSync(outDir).filter((f) => f.endsWith(".json"))) {
+      try {
+        const data = JSON.parse(fs.readFileSync(path.join(outDir, f), "utf-8"));
+        if (data.accuracy != null) {
+          const ruleId = data.rule_id || path.parse(f).name;
+          const acc = parseFloat(data.accuracy);
+          this.skillsTested[ruleId] = Math.max(this.skillsTested[ruleId] || 0, acc);
+        }
+      } catch { /* skip */ }
+    }
+    this.skillsPassing = Object.entries(this.skillsTested).filter(([, acc]) => acc >= this._accuracyThreshold).map(([id]) => id);
+  }
+
+  _loadEvolutionLog() {
+    const logDir = path.join(this._workspace.cwd, "logs", "evolution");
+    if (!fs.existsSync(logDir)) { this.iterationCount = 0; return; }
+    this.iterationCount = fs.readdirSync(logDir).filter((f) => f.endsWith(".json")).length;
+  }
+
+  describeState() {
+    this._scanWorkspace();
+    const total = this.skillsToTest.length;
+    const tested = Object.keys(this.skillsTested).length;
+    const passing = this.skillsPassing.length;
+    const failing = Object.entries(this.skillsTested).filter(([, acc]) => acc < this._accuracyThreshold);
+    const untested = this.skillsToTest.filter((s) => !(s in this.skillsTested));
+
+    const parts = ["## Current Phase: SKILL_TESTING"];
+    parts.push(`### Progress\n- Skills to test: ${total}\n- Tested: ${tested}\n- Passing (>=${this._accuracyThreshold}): ${passing}\n- Evolution iterations: ${this.iterationCount}/${this._maxIterations}`);
+
+    if (this.exitCriteriaMet()) {
+      parts.push("### Ready\nAll skills passing. Proceed to DISTILLATION.");
+    } else if (untested.length) {
+      parts.push(`### What to do now\nTest these skills: ${untested.slice(0, 10).join(", ")}`);
+    } else if (failing.length) {
+      parts.push("### What to do now — Evolution Cycle\nFailing skills:\n" +
+        failing.map(([id, acc]) => `- ${id}: ${acc.toFixed(2)}`).join("\n") +
+        "\n\nFollow: diagnose -> classify -> fix -> retest -> log");
+    }
+    return parts.join("\n\n");
+  }
+
+  onToolResult(toolName, toolInput, result) {
+    if (result.isError) return null;
+    const wasReady = this.exitCriteriaMet();
+    if (toolName === "workspace_file" || toolName === "evolution_cycle") this._scanWorkspace();
+    if (!wasReady && this.exitCriteriaMet()) {
+      return new PipelineEvent({ type: "phase_ready", message: "Skill testing complete. Ready for DISTILLATION.", nextPhase: Phase.DISTILLATION });
+    }
+    return null;
+  }
+
+  exitCriteriaMet() {
+    const total = this.skillsToTest.length;
+    if (!total) return false;
+    return Object.keys(this.skillsTested).length >= total && this.skillsPassing.length >= total * this._accuracyThreshold;
+  }
+}

package/src/agent/tools/agent-tool.js

@@ -0,0 +1,100 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { BaseTool, ToolResult } from "./base.js";
+
+/**
+ * Spawn a sub-agent for parallel work.
+ * Creates a child AgentEngine sharing the workspace filesystem
+ * but with independent conversation history.
+ * Results arrive via workspace files.
+ */
+export class AgentTool extends BaseTool {
+  constructor(workspace, engineFactory) {
+    super();
+    this._workspace = workspace;
+    this._engineFactory = engineFactory;
+    this._runningTasks = new Map();
+  }
+
+  get name() { return "agent_tool"; }
+  get description() {
+    return (
+      "Spawn a sub-agent for an independent task. Give it a complete, " +
+      "self-contained task description. The sub-agent works in the same " +
+      "workspace and writes results to files. Use this for parallel rule " +
+      "processing, batch testing, or any work that can run independently."
+    );
+  }
+
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        task_description: {
+          type: "string",
+          description: "Complete task description for the sub-agent. Be specific — it has no conversation context.",
+        },
+        task_id: { type: "string", description: "Optional task identifier (auto-generated if omitted)" },
+      },
+      required: ["task_description"],
+    };
+  }
+
+  async execute(input) {
+    const taskDesc = input.task_description || "";
+    const taskId = input.task_id || `task_${crypto.randomUUID().slice(0, 8)}`;
+
+    if (!taskDesc) return new ToolResult("No task_description provided", true);
+
+    // Create sub-agent output directory
+    const taskDir = path.join(this._workspace.cwd, "sub_agents", taskId);
+    fs.mkdirSync(taskDir, { recursive: true });
+    fs.writeFileSync(path.join(taskDir, "task.md"), taskDesc, "utf-8");
+
+    // Create child engine sharing the same workspace
+    let childEngine;
+    try {
+      childEngine = this._engineFactory(this._workspace.sessionId);
+    } catch (e) {
+      return new ToolResult(`Failed to create sub-agent: ${e.message}`, true);
+    }
+
+    // Run the sub-agent asynchronously (fire and forget)
+    const taskPromise = (async () => {
+      const resultEvents = [];
+      try {
+        for await (const event of childEngine.runTurn(taskDesc)) {
+          resultEvents.push({
+            type: event.type,
+            text: event.text,
+            name: event.name,
+            output: event.output,
+          });
+        }
+
+        fs.writeFileSync(
+          path.join(taskDir, "result.json"),
+          JSON.stringify(resultEvents, null, 2),
+          "utf-8",
+        );
+
+        const textParts = resultEvents.filter((e) => e.type === "text_delta").map((e) => e.text || "");
+        fs.writeFileSync(path.join(taskDir, "output.md"), textParts.join(""), "utf-8");
+        fs.writeFileSync(path.join(taskDir, "status.txt"), "completed", "utf-8");
+      } catch (e) {
+        fs.writeFileSync(path.join(taskDir, "status.txt"), `failed: ${e.message}`, "utf-8");
+      }
+    })();
+
+    this._runningTasks.set(taskId, taskPromise);
+    taskPromise.catch(() => {}).finally(() => this._runningTasks.delete(taskId));
+
+    return new ToolResult(JSON.stringify({
+      task_id: taskId,
+      status: "started",
+      output_dir: `sub_agents/${taskId}/`,
+      message: `Sub-agent started. Check sub_agents/${taskId}/status.txt for completion, output.md for text.`,
+    }, null, 2));
+  }
+}

package/src/agent/tools/base.js

@@ -0,0 +1,35 @@
+/**
+ * Result of a tool execution.
+ */
+export class ToolResult {
+  /**
+   * @param {string} content - Output text
+   * @param {boolean} [isError] - Whether the tool errored
+   */
+  constructor(content, isError = false) {
+    this.content = content;
+    this.isError = isError;
+  }
+}
+
+/**
+ * Abstract base class for all KC Agent tools.
+ * Subclass this to add a new tool. Register it with ToolRegistry.
+ */
+export class BaseTool {
+  /** @returns {string} Tool name */
+  get name() { throw new Error("Not implemented"); }
+
+  /** @returns {string} Tool description */
+  get description() { throw new Error("Not implemented"); }
+
+  /** @returns {object} JSON Schema for tool input */
+  get inputSchema() { throw new Error("Not implemented"); }
+
+  /**
+   * Execute the tool with the given input.
+   * @param {object} input
+   * @returns {Promise<ToolResult>}
+   */
+  async execute(input) { throw new Error("Not implemented"); }
+}

package/src/agent/tools/dashboard-render.js

@@ -0,0 +1,146 @@
+import fs from "node:fs";
+import path from "node:path";
+import { BaseTool, ToolResult } from "./base.js";
+
+/**
+ * Generate a self-contained HTML dashboard from project metrics.
+ * Aggregates: accuracy by rule, confidence distribution, evolution timeline, QC results.
+ */
+export class DashboardRenderTool extends BaseTool {
+  constructor(workspace) {
+    super();
+    this._workspace = workspace;
+  }
+
+  get name() { return "dashboard_render"; }
+  get description() {
+    return (
+      "Generate a self-contained HTML dashboard from project metrics. " +
+      "Aggregates accuracy, confidence distribution, evolution history, " +
+      "and QC results. Saves to output/dashboards/."
+    );
+  }
+
+  get inputSchema() {
+    return {
+      type: "object",
+      properties: {
+        output_path: { type: "string", description: "Output file path (default: output/dashboards/dashboard.html)" },
+      },
+    };
+  }
+
+  async execute(input) {
+    const outputPath = input.output_path || "output/dashboards/dashboard.html";
+    const metrics = this._collectMetrics();
+    const html = this._renderHtml(metrics);
+
+    try {
+      const resolved = this._workspace.resolvePath(outputPath);
+      fs.mkdirSync(path.dirname(resolved), { recursive: true });
+      fs.writeFileSync(resolved, html, "utf-8");
+      return new ToolResult(`Dashboard saved to ${outputPath} (${html.length} bytes)`);
+    } catch (e) {
+      return new ToolResult(e.message, true);
+    }
+  }
+
+  _collectMetrics() {
+    const ws = this._workspace.cwd;
+    const metrics = {
+      generated_at: new Date().toISOString(),
+      rules: [],
+      confidence_distribution: { low: 0, medium: 0, high: 0 },
+      evolution_iterations: 0,
+      qc_batches: 0,
+    };
+
+    const catalogPath = path.join(ws, "rules", "catalog.json");
+    if (fs.existsSync(catalogPath)) {
+      try {
+        const rules = JSON.parse(fs.readFileSync(catalogPath, "utf-8"));
+        if (Array.isArray(rules)) {
+          metrics.rules = rules.map((r) => ({ id: r.id || "?", description: (r.description || "").slice(0, 60) }));
+        }
+      } catch { /* skip */ }
+    }
+
+    const resultsDir = path.join(ws, "output", "results");
+    if (fs.existsSync(resultsDir)) {
+      for (const f of fs.readdirSync(resultsDir).filter((f) => f.endsWith(".json"))) {
+        try {
+          const data = JSON.parse(fs.readFileSync(path.join(resultsDir, f), "utf-8"));
+          const band = data.confidence_band || "medium";
+          if (band in metrics.confidence_distribution) metrics.confidence_distribution[band]++;
+        } catch { /* skip */ }
+      }
+    }
+
+    const evoDir = path.join(ws, "logs", "evolution");
+    if (fs.existsSync(evoDir)) {
+      metrics.evolution_iterations = fs.readdirSync(evoDir).filter((f) => f.endsWith(".json")).length;
+    }
+
+    const qcDir = path.join(ws, "output", "qc");
+    if (fs.existsSync(qcDir)) {
+      metrics.qc_batches = fs.readdirSync(qcDir).filter((f) => f.endsWith(".json")).length;
+    }
+
+    return metrics;
+  }
+
+  _renderHtml(metrics) {
+    const rulesHtml = metrics.rules.map((r) => `<tr><td>${r.id}</td><td>${r.description}</td></tr>`).join("\n");
+    const conf = metrics.confidence_distribution;
+    const total = conf.low + conf.medium + conf.high;
+
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>KC Agent Dashboard</title>
+<style>
+body { font-family: -apple-system, sans-serif; max-width: 900px; margin: 0 auto; padding: 20px; background: #0a0a0a; color: #e5e5e5; }
+h1 { color: #a3a3a3; font-size: 1.5em; }
+h2 { color: #737373; font-size: 1.1em; margin-top: 2em; }
+.card { background: #171717; border: 1px solid #262626; border-radius: 8px; padding: 16px; margin: 12px 0; }
+.metric { display: inline-block; margin-right: 32px; }
+.metric .value { font-size: 2em; font-weight: bold; color: #22c55e; }
+.metric .label { font-size: 0.85em; color: #737373; }
+table { width: 100%; border-collapse: collapse; }
+th, td { text-align: left; padding: 8px; border-bottom: 1px solid #262626; }
+th { color: #737373; font-size: 0.85em; }
+.bar { height: 20px; border-radius: 4px; display: inline-block; }
+.bar-low { background: #ef4444; }
+.bar-med { background: #eab308; }
+.bar-high { background: #22c55e; }
+.timestamp { color: #525252; font-size: 0.8em; }
+</style>
+</head>
+<body>
+<h1>KC Agent Dashboard</h1>
+<p class="timestamp">Generated: ${metrics.generated_at}</p>
+<div class="card">
+<div class="metric"><span class="value">${metrics.rules.length}</span><br><span class="label">Rules</span></div>
+<div class="metric"><span class="value">${total}</span><br><span class="label">Results</span></div>
+<div class="metric"><span class="value">${metrics.evolution_iterations}</span><br><span class="label">Evolution Cycles</span></div>
+<div class="metric"><span class="value">${metrics.qc_batches}</span><br><span class="label">QC Batches</span></div>
+</div>
+<h2>Confidence Distribution</h2>
+<div class="card">
+<div>Low: ${conf.low} &nbsp; <span class="bar bar-low" style="width:${conf.low * 5}px"></span></div>
+<div>Medium: ${conf.medium} &nbsp; <span class="bar bar-med" style="width:${conf.medium * 5}px"></span></div>
+<div>High: ${conf.high} &nbsp; <span class="bar bar-high" style="width:${conf.high * 5}px"></span></div>
+</div>
+<h2>Rules</h2>
+<div class="card">
+<table>
+<tr><th>ID</th><th>Description</th></tr>
+${rulesHtml || '<tr><td colspan="2">No rules in catalog yet</td></tr>'}
+</table>
+</div>
+</body>
+</html>`;
+  }
+}