kc-beta 0.1.2 → 0.2.1

package/src/agent/llm-client.js

@@ -1,102 +1,268 @@
+import { withRetry } from "./retry.js";
+
 /**
- * Thin LLM client using native fetch + SSE parsing.
- * Replaces the Python openai.AsyncOpenAI client.
- * Supports OpenAI-compatible APIs (SiliconFlow, Aliyun, OpenAI, etc.)
+ * Multi-protocol LLM client using native fetch + SSE parsing.
+ * Supports OpenAI-compatible APIs and Anthropic Messages API.
  */
 export class LLMClient {
   /**
    * @param {object} opts
    * @param {string} opts.apiKey
-   * @param {string} opts.baseUrl - e.g. "https://api.siliconflow.cn/v1"
+   * @param {string} opts.baseUrl - e.g. "https://api.siliconflow.cn/v1" or "https://api.anthropic.com"
+   * @param {string} [opts.authType] - "bearer" (default) | "x-api-key" (Anthropic)
+   * @param {string} [opts.apiFormat] - "openai" (default) | "anthropic"
    */
-  constructor({ apiKey, baseUrl }) {
+  constructor({ apiKey, baseUrl, authType = "bearer", apiFormat = "openai" }) {
     this.apiKey = apiKey;
     this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.authType = authType;
+    this.apiFormat = apiFormat;
   }
 
   /**
-   * Streaming chat completion. Yields parsed SSE chunk objects.
+   * Build auth headers based on provider type.
+   * @returns {object}
+   */
+  _buildHeaders() {
+    const headers = { "Content-Type": "application/json" };
+    if (this.authType === "x-api-key") {
+      headers["x-api-key"] = this.apiKey;
+      headers["anthropic-version"] = "2023-06-01";
+    } else if (this.authType === "aws-sigv4") {
+      throw new Error(
+        "AWS Bedrock authentication (SigV4) is not yet supported. " +
+        "Please use a different provider or an OpenAI-compatible proxy."
+      );
+    } else {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+    return headers;
+  }
+
+  /**
+   * Get the chat endpoint for the configured API format.
+   * @returns {string}
+   */
+  _getEndpoint() {
+    if (this.apiFormat === "anthropic") {
+      return `${this.baseUrl}/v1/messages`;
+    }
+    return `${this.baseUrl}/chat/completions`;
+  }
+
+  /**
+   * Build request body for the configured API format.
    * @param {object} opts
-   * @param {string} opts.model
-   * @param {Array} opts.messages
-   * @param {Array} [opts.tools]
-   * @param {number} [opts.maxTokens]
-   * @yields {object} Parsed chunk from the SSE stream
+   * @returns {object}
    */
-  async *streamChat({ model, messages, tools, maxTokens }) {
-    const body = {
-      model,
-      messages,
-      stream: true,
-    };
+  _buildStreamBody({ model, messages, tools, maxTokens }) {
+    if (this.apiFormat === "anthropic") {
+      return this._buildAnthropicBody({ model, messages, tools, maxTokens, stream: true });
+    }
+    return this._buildOpenaiBody({ model, messages, tools, maxTokens, stream: true });
+  }
+
+  _buildNonStreamBody({ model, messages, maxTokens }) {
+    if (this.apiFormat === "anthropic") {
+      return this._buildAnthropicBody({ model, messages, tools: null, maxTokens, stream: false });
+    }
+    return this._buildOpenaiBody({ model, messages, tools: null, maxTokens, stream: false });
+  }
+
+  _buildOpenaiBody({ model, messages, tools, maxTokens, stream }) {
+    const body = { model, messages, stream };
     if (maxTokens) body.max_tokens = maxTokens;
     if (tools && tools.length > 0) body.tools = tools;
+    return body;
+  }
 
-    const resp = await fetch(`${this.baseUrl}/chat/completions`, {
-      method: "POST",
-      headers: {
-        "Authorization": `Bearer ${this.apiKey}`,
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify(body),
-    });
-
-    if (!resp.ok) {
-      const text = await resp.text();
-      throw new Error(`LLM API error ${resp.status}: ${text}`);
+  _buildAnthropicBody({ model, messages, tools, maxTokens, stream }) {
+    // Anthropic: system message is a top-level field, not in messages array
+    let system = undefined;
+    const filteredMessages = [];
+    for (const msg of messages) {
+      if (msg.role === "system") {
+        system = (system ? system + "\n\n" : "") + msg.content;
+      } else if (msg.role === "tool") {
+        // Anthropic expects tool results as user messages with tool_result content blocks
+        filteredMessages.push({
+          role: "user",
+          content: [{
+            type: "tool_result",
+            tool_use_id: msg.tool_call_id,
+            content: msg.content,
+          }],
+        });
+      } else if (msg.role === "assistant" && msg.tool_calls) {
+        // Convert OpenAI tool_calls to Anthropic content blocks
+        const content = [];
+        if (msg.content) content.push({ type: "text", text: msg.content });
+        for (const tc of msg.tool_calls) {
+          let input = {};
+          try { input = JSON.parse(tc.function.arguments || "{}"); } catch { /* ignore */ }
+          content.push({
+            type: "tool_use",
+            id: tc.id,
+            name: tc.function.name,
+            input,
+          });
+        }
+        filteredMessages.push({ role: "assistant", content });
+      } else {
+        filteredMessages.push(msg);
+      }
     }
 
-    for await (const data of this._parseSSE(resp.body)) {
-      yield data;
+    const body = {
+      model,
+      messages: filteredMessages,
+      max_tokens: maxTokens || 8192,
+      stream,
+    };
+    if (system) body.system = system;
+    if (tools && tools.length > 0) {
+      // Convert OpenAI tool schema to Anthropic tool schema
+      body.tools = tools.map((t) => ({
+        name: t.function.name,
+        description: t.function.description || "",
+        input_schema: t.function.parameters || { type: "object", properties: {} },
+      }));
     }
+    return body;
   }
 
   /**
-   * Non-streaming chat completion. Returns the full response.
+   * Streaming chat completion. Yields parsed SSE chunk objects
+   * normalized to OpenAI shape: { choices: [{ delta: { content?, tool_calls? } }] }
    * @param {object} opts
    * @param {string} opts.model
    * @param {Array} opts.messages
+   * @param {Array} [opts.tools]
    * @param {number} [opts.maxTokens]
-   * @returns {object} The response object
+   * @yields {object} Normalized chunk
+   */
+  async *streamChat({ model, messages, tools, maxTokens }) {
+    const body = this._buildStreamBody({ model, messages, tools, maxTokens });
+
+    const resp = await withRetry(async () => {
+      const r = await fetch(this._getEndpoint(), {
+        method: "POST",
+        headers: this._buildHeaders(),
+        body: JSON.stringify(body),
+      });
+      if (!r.ok) {
+        const text = await r.text();
+        const err = new Error(`LLM API error ${r.status}: ${text}`);
+        err.status = r.status;
+        err.retryAfter = r.headers.get("retry-after");
+        throw err;
+      }
+      return r;
+    });
+
+    if (this.apiFormat === "anthropic") {
+      yield* this._parseAnthropicSSE(resp.body);
+    } else {
+      yield* this._parseOpenaiSSE(resp.body);
+    }
+  }
+
+  /**
+   * Non-streaming chat completion. Returns the full response
+   * normalized to OpenAI shape.
+   * @param {object} opts
+   * @returns {object}
    */
   async chat({ model, messages, maxTokens }) {
-    const body = {
-      model,
-      messages,
-    };
-    if (maxTokens) body.max_tokens = maxTokens;
+    const body = this._buildNonStreamBody({ model, messages, maxTokens });
 
-    const resp = await fetch(`${this.baseUrl}/chat/completions`, {
-      method: "POST",
-      headers: {
-        "Authorization": `Bearer ${this.apiKey}`,
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify(body),
+    const resp = await withRetry(async () => {
+      const r = await fetch(this._getEndpoint(), {
+        method: "POST",
+        headers: this._buildHeaders(),
+        body: JSON.stringify(body),
+      });
+      if (!r.ok) {
+        const text = await r.text();
+        const err = new Error(`LLM API error ${r.status}: ${text}`);
+        err.status = r.status;
+        err.retryAfter = r.headers.get("retry-after");
+        throw err;
+      }
+      return r;
     });
 
-    if (!resp.ok) {
-      const text = await resp.text();
-      throw new Error(`LLM API error ${resp.status}: ${text}`);
+    const data = await resp.json();
+
+    if (this.apiFormat === "anthropic") {
+      // Normalize Anthropic response to OpenAI shape
+      const textParts = [];
+      for (const block of data.content || []) {
+        if (block.type === "text") textParts.push(block.text);
+      }
+      return {
+        choices: [{
+          message: {
+            role: "assistant",
+            content: textParts.join(""),
+          },
+        }],
+        usage: data.usage ? {
+          prompt_tokens: data.usage.input_tokens || 0,
+          completion_tokens: data.usage.output_tokens || 0,
+        } : undefined,
+      };
     }
 
-    return resp.json();
+    return data;
   }
 
   /**
-   * Parse SSE stream from a ReadableStream.
-   * Handles the `data: {...}` format used by OpenAI-compatible APIs.
+   * List available models from the provider.
+   * @returns {Promise<Array<{id: string, name: string, ownedBy: string}>>}
+   */
+  async listModels() {
+    let endpoint;
+    if (this.apiFormat === "anthropic") {
+      endpoint = `${this.baseUrl}/v1/models`;
+    } else {
+      endpoint = `${this.baseUrl}/models`;
+    }
+
+    try {
+      const resp = await fetch(endpoint, {
+        method: "GET",
+        headers: this._buildHeaders(),
+        signal: AbortSignal.timeout(5000),
+      });
+
+      if (!resp.ok) return [];
+      const data = await resp.json();
+      return (data.data || []).map((m) => ({
+        id: m.id,
+        name: m.id,
+        ownedBy: m.owned_by || "",
+      }));
+    } catch {
+      return [];
+    }
+  }
+
+  // --- OpenAI SSE parsing ---
+
+  /**
+   * Parse SSE stream from OpenAI-compatible API.
    * @param {ReadableStream} body
-   * @yields {object} Parsed JSON from each data line
+   * @yields {object} Parsed chunk
    */
-  async *_parseSSE(body) {
+  async *_parseOpenaiSSE(body) {
     const decoder = new TextDecoder();
     let buffer = "";
 
     for await (const chunk of body) {
       buffer += decoder.decode(chunk, { stream: true });
       const lines = buffer.split("\n");
-      buffer = lines.pop(); // keep incomplete line
+      buffer = lines.pop();
 
       for (const line of lines) {
         const trimmed = line.trim();
@@ -113,19 +279,146 @@ export class LLMClient {
       }
     }
 
-    // Process any remaining buffer
     if (buffer.trim()) {
       const trimmed = buffer.trim();
       if (trimmed.startsWith("data: ")) {
         const data = trimmed.slice(6).trim();
         if (data !== "[DONE]") {
-          try {
-            yield JSON.parse(data);
-          } catch {
-            // Skip
+          try { yield JSON.parse(data); } catch { /* skip */ }
+        }
+      }
+    }
+  }
+
+  // --- Anthropic SSE parsing + normalization ---
+
+  /**
+   * Parse Anthropic SSE stream and normalize to OpenAI chunk shape.
+   * Anthropic SSE uses event types: message_start, content_block_start,
+   * content_block_delta, content_block_stop, message_delta, message_stop.
+   *
+   * Normalizes everything to: { choices: [{ delta: { content?, tool_calls? } }] }
+   * so engine.js needs no changes.
+   *
+   * @param {ReadableStream} body
+   * @yields {object} Normalized OpenAI-shaped chunk
+   */
+  async *_parseAnthropicSSE(body) {
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let currentEventType = "";
+
+    // State for accumulating tool call content blocks
+    let toolCallIndex = -1;
+
+    for await (const rawChunk of body) {
+      buffer += decoder.decode(rawChunk, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop();
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith(":")) continue;
+
+        if (trimmed.startsWith("event: ")) {
+          currentEventType = trimmed.slice(7).trim();
+          continue;
+        }
+
+        if (trimmed.startsWith("data: ")) {
+          const dataStr = trimmed.slice(6).trim();
+          let data;
+          try { data = JSON.parse(dataStr); } catch { continue; }
+
+          const normalized = this._normalizeAnthropicEvent(currentEventType, data, { toolCallIndex });
+          if (normalized) {
+            // Update tool call index tracking
+            if (normalized._newToolCallIndex !== undefined) {
+              toolCallIndex = normalized._newToolCallIndex;
+              delete normalized._newToolCallIndex;
+            }
+            yield normalized;
           }
         }
       }
     }
   }
+
+  /**
+   * Normalize a single Anthropic SSE event into OpenAI chunk shape.
+   * @param {string} eventType
+   * @param {object} data
+   * @param {object} state - Mutable state for tracking across events
+   * @returns {object|null} Normalized chunk or null if no output needed
+   */
+  _normalizeAnthropicEvent(eventType, data, state) {
+    switch (eventType) {
+      case "content_block_start": {
+        const block = data.content_block;
+        if (block?.type === "text") {
+          // Text block starting — no content yet
+          return null;
+        }
+        if (block?.type === "tool_use") {
+          state.toolCallIndex++;
+          const chunk = {
+            choices: [{
+              delta: {
+                tool_calls: [{
+                  index: state.toolCallIndex,
+                  id: block.id,
+                  type: "function",
+                  function: { name: block.name, arguments: "" },
+                }],
+              },
+            }],
+            _newToolCallIndex: state.toolCallIndex,
+          };
+          return chunk;
+        }
+        return null;
+      }
+
+      case "content_block_delta": {
+        const delta = data.delta;
+        if (delta?.type === "text_delta") {
+          return {
+            choices: [{ delta: { content: delta.text } }],
+          };
+        }
+        if (delta?.type === "input_json_delta") {
+          return {
+            choices: [{
+              delta: {
+                tool_calls: [{
+                  index: state.toolCallIndex,
+                  function: { arguments: delta.partial_json },
+                }],
+              },
+            }],
+          };
+        }
+        return null;
+      }
+
+      case "message_delta": {
+        // End of message — contains stop_reason and usage
+        return {
+          choices: [{
+            delta: {},
+            finish_reason: data.delta?.stop_reason === "end_turn" ? "stop" : (data.delta?.stop_reason || null),
+          }],
+        };
+      }
+
+      case "message_start":
+      case "content_block_stop":
+      case "message_stop":
+      case "ping":
+        return null;
+
+      default:
+        return null;
+    }
+  }
 }

package/src/agent/pipelines/base.js

@@ -11,4 +11,10 @@ export class Pipeline {
 
   /** Whether all requirements for leaving this phase are satisfied. */
   exitCriteriaMet() { throw new Error("Not implemented"); }
+
+  /** Serialize milestone state for persistence. Override in subclasses. */
+  exportState() { return {}; }
+
+  /** Restore milestone state from persisted data. Override in subclasses. */
+  importState(_data) { /* no-op by default */ }
 }

package/src/agent/pipelines/distillation.js

@@ -106,4 +106,22 @@ export class DistillationEngine extends Pipeline {
     if (!total) return false;
     return Object.keys(this.workflowsCreated).length >= total && this.workflowsPassing.length >= total;
   }
+
+  exportState() {
+    return {
+      skillsToDistill: this.skillsToDistill,
+      workflowsCreated: this.workflowsCreated,
+      workflowsTested: this.workflowsTested,
+      workflowsPassing: this.workflowsPassing,
+      tierAssignments: this.tierAssignments,
+    };
+  }
+
+  importState(data) {
+    if (Array.isArray(data.skillsToDistill) && data.skillsToDistill.length > this.skillsToDistill.length) this.skillsToDistill = data.skillsToDistill;
+    if (Array.isArray(data.workflowsPassing) && data.workflowsPassing.length > this.workflowsPassing.length) this.workflowsPassing = data.workflowsPassing;
+    if (data.workflowsCreated && typeof data.workflowsCreated === "object") Object.assign(this.workflowsCreated, data.workflowsCreated);
+    if (data.workflowsTested && typeof data.workflowsTested === "object") Object.assign(this.workflowsTested, data.workflowsTested);
+    if (data.tierAssignments && typeof data.tierAssignments === "object") Object.assign(this.tierAssignments, data.tierAssignments);
+  }
 }

package/src/agent/pipelines/extraction.js

@@ -87,4 +87,25 @@ export class RuleExtractionPipeline extends Pipeline {
     return this.regulationsScanned && this.rulesExtracted.length > 0 &&
       this.rulesWithTests.length >= Math.max(this.rulesExtracted.length * 0.8, 1) && this.coverageAudited;
   }
+
+  exportState() {
+    return {
+      regulationsScanned: this.regulationsScanned,
+      rulesExtracted: this.rulesExtracted,
+      rulesWithTests: this.rulesWithTests,
+      coverageAudited: this.coverageAudited,
+    };
+  }
+
+  importState(data) {
+    if (data.regulationsScanned) this.regulationsScanned = true;
+    if (data.coverageAudited) this.coverageAudited = true;
+    // Arrays: use imported as floor, then re-scan will reconcile
+    if (Array.isArray(data.rulesExtracted) && data.rulesExtracted.length > this.rulesExtracted.length) {
+      this.rulesExtracted = data.rulesExtracted;
+    }
+    if (Array.isArray(data.rulesWithTests) && data.rulesWithTests.length > this.rulesWithTests.length) {
+      this.rulesWithTests = data.rulesWithTests;
+    }
+  }
 }

package/src/agent/pipelines/initializer.js

@@ -11,9 +11,9 @@ const DEFAULT_ENV = `# === KC Agent Project Configuration ===
 # Language: en | zh
 LANGUAGE=en
 
-# === Worker LLM API (SiliconFlow) ===
-SILICONFLOW_API_KEY=
-SILICONFLOW_BASE_URL=https://api.siliconflow.cn/v1
+# === LLM API ===
+LLM_API_KEY=
+LLM_BASE_URL=https://api.siliconflow.cn/v1
 
 # === Worker LLM Tiers (highest capability to lowest) ===
 TIER1=Pro/zai-org/GLM-5, Pro/moonshotai/Kimi-K2.5
@@ -53,8 +53,8 @@ export class ProjectInitializer extends Pipeline {
     if (!fs.existsSync(envPath)) {
       let envContent = DEFAULT_ENV;
       const gc = this._loadGlobalConfig();
-      if (gc.api_key) envContent = envContent.replace("SILICONFLOW_API_KEY=", `SILICONFLOW_API_KEY=${gc.api_key}`);
-      if (gc.base_url) envContent = envContent.replace("SILICONFLOW_BASE_URL=https://api.siliconflow.cn/v1", `SILICONFLOW_BASE_URL=${gc.base_url}`);
+      if (gc.api_key) envContent = envContent.replace("LLM_API_KEY=", `LLM_API_KEY=${gc.api_key}`);
+      if (gc.base_url) envContent = envContent.replace("LLM_BASE_URL=https://api.siliconflow.cn/v1", `LLM_BASE_URL=${gc.base_url}`);
       if (gc.accuracy_threshold) {
         envContent = envContent.replace("SKILL_ACCURACY=0.9", `SKILL_ACCURACY=${gc.accuracy_threshold}`);
         envContent = envContent.replace("WORKFLOW_ACCURACY=0.9", `WORKFLOW_ACCURACY=${gc.accuracy_threshold}`);
@@ -96,7 +96,7 @@ export class ProjectInitializer extends Pipeline {
     const envPath = path.join(this._workspace.cwd, ".env");
     if (fs.existsSync(envPath)) {
       for (const line of fs.readFileSync(envPath, "utf-8").split("\n")) {
-        if (line.startsWith("SILICONFLOW_API_KEY=") && line.split("=")[1].trim()) {
+        if ((line.startsWith("LLM_API_KEY=") || line.startsWith("SILICONFLOW_API_KEY=")) && line.split("=")[1].trim()) {
           this.configReady = true; return;
         }
       }
@@ -154,4 +154,20 @@ export class ProjectInitializer extends Pipeline {
   exitCriteriaMet() {
     return this.workspaceCreated && this.configReady && this.hasRegulations && this.hasSamples;
   }
+
+  exportState() {
+    return {
+      workspaceCreated: this.workspaceCreated,
+      configReady: this.configReady,
+      hasRegulations: this.hasRegulations,
+      hasSamples: this.hasSamples,
+    };
+  }
+
+  importState(data) {
+    if (data.workspaceCreated) this.workspaceCreated = true;
+    if (data.configReady) this.configReady = true;
+    if (data.hasRegulations) this.hasRegulations = true;
+    if (data.hasSamples) this.hasSamples = true;
+  }
 }

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

@@ -94,4 +94,23 @@ export class ProductionQCPipeline extends Pipeline {
   }
 
   exitCriteriaMet() { return this.monitoringPhase === "stable"; }
+
+  exportState() {
+    return {
+      batchesProcessed: this.batchesProcessed,
+      totalDocuments: this.totalDocuments,
+      documentsReviewed: this.documentsReviewed,
+      monitoringPhase: this.monitoringPhase,
+      accuracyByRule: this.accuracyByRule,
+      issuesCount: this.issuesFound.length,
+    };
+  }
+
+  importState(data) {
+    if (typeof data.batchesProcessed === "number" && data.batchesProcessed > this.batchesProcessed) this.batchesProcessed = data.batchesProcessed;
+    if (typeof data.totalDocuments === "number" && data.totalDocuments > this.totalDocuments) this.totalDocuments = data.totalDocuments;
+    if (typeof data.documentsReviewed === "number" && data.documentsReviewed > this.documentsReviewed) this.documentsReviewed = data.documentsReviewed;
+    if (data.monitoringPhase) this.monitoringPhase = data.monitoringPhase;
+    if (data.accuracyByRule && typeof data.accuracyByRule === "object") Object.assign(this.accuracyByRule, data.accuracyByRule);
+  }
 }

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

@@ -77,4 +77,18 @@ export class SkillAuthoringPipeline extends Pipeline {
     if (!this.totalRules.length) return false;
     return this.skillsAuthored.length >= this.totalRules.length && this.skillsWithScripts.length >= this.skillsAuthored.length * 0.5;
   }
+
+  exportState() {
+    return {
+      totalRules: this.totalRules,
+      skillsAuthored: this.skillsAuthored,
+      skillsWithScripts: this.skillsWithScripts,
+    };
+  }
+
+  importState(data) {
+    if (Array.isArray(data.totalRules) && data.totalRules.length > this.totalRules.length) this.totalRules = data.totalRules;
+    if (Array.isArray(data.skillsAuthored) && data.skillsAuthored.length > this.skillsAuthored.length) this.skillsAuthored = data.skillsAuthored;
+    if (Array.isArray(data.skillsWithScripts) && data.skillsWithScripts.length > this.skillsWithScripts.length) this.skillsWithScripts = data.skillsWithScripts;
+  }
 }

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

@@ -106,4 +106,24 @@ export class SkillTestingPipeline extends Pipeline {
     if (!total) return false;
     return Object.keys(this.skillsTested).length >= total && this.skillsPassing.length >= total * this._accuracyThreshold;
   }
+
+  exportState() {
+    return {
+      skillsToTest: this.skillsToTest,
+      skillsTested: this.skillsTested,
+      skillsPassing: this.skillsPassing,
+      iterationCount: this.iterationCount,
+    };
+  }
+
+  importState(data) {
+    if (typeof data.iterationCount === "number" && data.iterationCount > this.iterationCount) this.iterationCount = data.iterationCount;
+    if (Array.isArray(data.skillsToTest) && data.skillsToTest.length > this.skillsToTest.length) this.skillsToTest = data.skillsToTest;
+    if (Array.isArray(data.skillsPassing) && data.skillsPassing.length > this.skillsPassing.length) this.skillsPassing = data.skillsPassing;
+    if (data.skillsTested && typeof data.skillsTested === "object") {
+      for (const [k, v] of Object.entries(data.skillsTested)) {
+        if (!this.skillsTested[k] || v > this.skillsTested[k]) this.skillsTested[k] = v;
+      }
+    }
+  }
 }