kc-beta 0.1.2 → 0.3.0

package/src/agent/pipelines/initializer.js

@@ -1,9 +1,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import { fileURLToPath } from "node:url";
 import { Phase, PipelineEvent } from "./index.js";
 import { Pipeline } from "./base.js";
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const AGENT_MD_TEMPLATE = path.resolve(__dirname, "../../../template/AGENT.md");
+
 const REQUIRED_DIRS = ["rules", "samples", "input", "output", "logs", "workflows", "rule_skills"];
 
 const DEFAULT_ENV = `# === KC Agent Project Configuration ===
@@ -11,9 +15,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 +57,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}`);
@@ -74,6 +78,12 @@ export class ProjectInitializer extends Pipeline {
       fs.writeFileSync(manifestPath, JSON.stringify({ version: "0.1.0", entries: [] }, null, 2), "utf-8");
     }
 
+    // AGENT.md — per-project context (agent can modify)
+    const agentMdPath = path.join(this._workspace.cwd, "AGENT.md");
+    if (!fs.existsSync(agentMdPath) && fs.existsSync(AGENT_MD_TEMPLATE)) {
+      fs.copyFileSync(AGENT_MD_TEMPLATE, agentMdPath);
+    }
+
     this.workspaceCreated = true;
     this._checkRegulations();
     this._checkSamples();
@@ -81,22 +91,48 @@ export class ProjectInitializer extends Pipeline {
   }
 
   _checkRegulations() {
+    // Check workspace rules/
     const dir = path.join(this._workspace.cwd, "rules");
-    if (!fs.existsSync(dir)) { this.hasRegulations = false; return; }
-    this.hasRegulations = fs.readdirSync(dir, { withFileTypes: true }).some((e) => e.isFile());
+    if (fs.existsSync(dir) && fs.readdirSync(dir, { withFileTypes: true }).some((e) => e.isFile())) {
+      this.hasRegulations = true; return;
+    }
+    // Check project dir rules/ (case-insensitive)
+    if (this._workspace.projectDir) {
+      for (const name of ["rules", "Rules", "RULES", "regulations", "Regulations"]) {
+        const pdir = path.join(this._workspace.projectDir, name);
+        if (fs.existsSync(pdir) && fs.statSync(pdir).isDirectory() &&
+            fs.readdirSync(pdir, { withFileTypes: true }).some((e) => e.isFile())) {
+          this.hasRegulations = true; return;
+        }
+      }
+    }
+    this.hasRegulations = false;
   }
 
   _checkSamples() {
+    // Check workspace samples/
     const dir = path.join(this._workspace.cwd, "samples");
-    if (!fs.existsSync(dir)) { this.hasSamples = false; return; }
-    this.hasSamples = fs.readdirSync(dir, { withFileTypes: true }).some((e) => e.isFile());
+    if (fs.existsSync(dir) && fs.readdirSync(dir, { withFileTypes: true }).some((e) => e.isFile())) {
+      this.hasSamples = true; return;
+    }
+    // Check project dir samples/ (case-insensitive)
+    if (this._workspace.projectDir) {
+      for (const name of ["samples", "Samples", "SAMPLES", "sample", "Sample"]) {
+        const pdir = path.join(this._workspace.projectDir, name);
+        if (fs.existsSync(pdir) && fs.statSync(pdir).isDirectory() &&
+            fs.readdirSync(pdir, { withFileTypes: true }).some((e) => e.isFile())) {
+          this.hasSamples = true; return;
+        }
+      }
+    }
+    this.hasSamples = false;
   }
 
   _checkConfig() {
     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;
         }
       }
@@ -115,10 +151,13 @@ export class ProjectInitializer extends Pipeline {
     const completed = [], pending = [];
     if (this.workspaceCreated) completed.push("Workspace structure created"); else pending.push("Workspace structure");
     if (this.configReady) completed.push("API keys configured"); else pending.push("API keys (check .env)");
-    if (this.hasRegulations) completed.push("Regulation documents in rules/"); else pending.push("Regulation documents in rules/");
-    if (this.hasSamples) completed.push("Sample documents in samples/"); else pending.push("Sample documents in samples/");
+    if (this.hasRegulations) completed.push("Regulation documents found"); else pending.push("Regulation documents (add to rules/ in workspace or project dir)");
+    if (this.hasSamples) completed.push("Sample documents found"); else pending.push("Sample documents (add to samples/ in workspace or project dir)");
 
     const parts = ["## Phase: BOOTSTRAP\nSet up the workspace and understand the developer user's verification scenario. Bundled methodology skills are available in the workspace skills/ directory."];
+    if (this._workspace.projectDir) {
+      parts.push(`**Project directory:** ${this._workspace.projectDir}\nUse scope="project" to read files from the user's project folder.`);
+    }
     if (completed.length) parts.push("### Done\n" + completed.map((c) => `- [x] ${c}`).join("\n"));
     if (pending.length) parts.push("### Needed\n" + pending.map((p) => `- [ ] ${p}`).join("\n"));
 
@@ -135,14 +174,20 @@ export class ProjectInitializer extends Pipeline {
     if (toolName === "workspace_file") {
       const op = toolInput.operation || "";
       const p = toolInput.path || "";
-      if (op === "write") {
+      const scope = toolInput.scope || "workspace";
+      if (op === "write" && scope === "workspace") {
         if (p.startsWith("rules/")) this.hasRegulations = true;
         else if (p.startsWith("samples/")) this.hasSamples = true;
         else if (p === ".env") this._checkConfig();
-      } else if (op === "list") {
+      } else if (op === "list" || op === "read") {
+        // Re-check after any list/read — project dir files may satisfy criteria
         this._checkRegulations();
         this._checkSamples();
       }
+    } else if (toolName === "document_parse") {
+      // Parsing a document from project dir counts as having files
+      this._checkRegulations();
+      this._checkSamples();
     }
 
     if (!wasReady && this.exitCriteriaMet()) {
@@ -154,4 +199,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;
+      }
+    }
+  }
 }

package/src/agent/retry.js

@@ -0,0 +1,83 @@
+/**
+ * Retry wrapper with exponential backoff and jitter.
+ * Designed for LLM API calls — retries transient errors, fails fast on auth/validation errors.
+ */
+
+const MAX_RETRIES = 10;
+const INITIAL_DELAY_MS = 1000;
+const MAX_DELAY_MS = 60000;
+const BACKOFF_MULTIPLIER = 2;
+const JITTER_FRACTION = 0.2;
+
+const RETRYABLE_STATUS = new Set([408, 429, 500, 502, 503, 504, 520, 522, 524]);
+const NON_RETRYABLE_STATUS = new Set([400, 401, 403, 404, 422]);
+
+/**
+ * Determine if an error is retryable.
+ * @param {Error} err
+ * @returns {boolean}
+ */
+function isRetryable(err) {
+  if (err.status) {
+    if (NON_RETRYABLE_STATUS.has(err.status)) return false;
+    if (RETRYABLE_STATUS.has(err.status)) return true;
+  }
+  // Network errors (ECONNRESET, ETIMEDOUT, fetch TypeError, AbortError)
+  const msg = err.message || "";
+  if (/ECONNRESET|ETIMEDOUT|ENOTFOUND|ECONNREFUSED|UND_ERR|fetch failed|network|socket hang up/i.test(msg)) {
+    return true;
+  }
+  if (err.name === "AbortError" || err.name === "TimeoutError") return true;
+  // If we have a status code and it's not in our known sets, retry server errors (5xx)
+  if (err.status && err.status >= 500) return true;
+  // Unknown errors without status — retry conservatively
+  return !err.status;
+}
+
+/**
+ * Calculate delay for a given attempt using exponential backoff with jitter.
+ * @param {number} attempt - 0-indexed attempt number
+ * @param {number|null} retryAfterSec - Retry-After header value in seconds
+ * @returns {number} Delay in milliseconds
+ */
+function calculateDelay(attempt, retryAfterSec) {
+  if (retryAfterSec && retryAfterSec > 0) {
+    return Math.min(retryAfterSec * 1000, MAX_DELAY_MS);
+  }
+  const base = Math.min(INITIAL_DELAY_MS * Math.pow(BACKOFF_MULTIPLIER, attempt), MAX_DELAY_MS);
+  const jitter = base * JITTER_FRACTION * Math.random();
+  return base + jitter;
+}
+
+/**
+ * Execute an async function with retry logic.
+ *
+ * @param {() => Promise<any>} fn - The async function to execute. Should throw with
+ *   an error that has `.status` and optionally `.retryAfter` properties on failure.
+ * @returns {Promise<any>} The successful result
+ * @throws {Error} The last error after all retries exhausted, or a non-retryable error immediately
+ */
+export async function withRetry(fn) {
+  let lastError;
+
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+
+      if (!isRetryable(err)) throw err;
+      if (attempt === MAX_RETRIES) break;
+
+      const retryAfterSec = err.retryAfter ? parseFloat(err.retryAfter) : null;
+      const delay = calculateDelay(attempt, retryAfterSec);
+
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+
+  const wrapper = new Error(`LLM API call failed after ${MAX_RETRIES + 1} attempts: ${lastError.message}`);
+  wrapper.cause = lastError;
+  wrapper.status = lastError.status;
+  throw wrapper;
+}

package/src/agent/session-state.js

@@ -0,0 +1,79 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Persists session state (phase, pipeline milestones, phase summaries)
+ * to enable cross-session resume.
+ *
+ * Stored as: workspace/{sessionId}/session-state.json
+ */
+export class SessionState {
+  /**
+   * @param {string} workspacePath - Session workspace directory
+   */
+  constructor(workspacePath) {
+    this._path = path.join(workspacePath, "session-state.json");
+  }
+
+  /** Whether a session state file exists */
+  get exists() {
+    return fs.existsSync(this._path);
+  }
+
+  /**
+   * Save engine state to disk.
+   * @param {import('./engine.js').AgentEngine} engine
+   */
+  save(engine) {
+    const state = {
+      version: 1,
+      sessionId: engine.workspace.sessionId,
+      currentPhase: engine.currentPhase,
+      projectDir: engine.workspace.projectDir || null,
+      phaseSummaries: engine._phaseSummaries || [],
+      lastEventSeq: engine.eventLog?.currentSeq || 0,
+      createdAt: this._loadRaw()?.createdAt || new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      pipelineMilestones: this._extractMilestones(engine.pipelines),
+    };
+
+    fs.writeFileSync(this._path, JSON.stringify(state, null, 2), "utf-8");
+  }
+
+  /**
+   * Load session state from disk.
+   * @returns {object} The persisted state
+   */
+  load() {
+    return this._loadRaw() || {};
+  }
+
+  /**
+   * Read raw file contents.
+   */
+  _loadRaw() {
+    if (!this.exists) return null;
+    try {
+      return JSON.parse(fs.readFileSync(this._path, "utf-8"));
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Serialize pipeline milestones for persistence.
+   * @param {object} pipelines - Map of phase -> pipeline instance
+   * @returns {object}
+   */
+  _extractMilestones(pipelines) {
+    const milestones = {};
+    for (const [phase, pipeline] of Object.entries(pipelines)) {
+      if (pipeline?.exportState) {
+        try {
+          milestones[phase] = pipeline.exportState();
+        } catch { /* skip if not implemented */ }
+      }
+    }
+    return milestones;
+  }
+}

package/src/agent/skill-loader.js

@@ -130,7 +130,19 @@ export class SkillLoader {
 
       const frontmatter = match[1];
       const name = frontmatter.match(/^name:\s*(.+)$/m)?.[1]?.trim() || "";
-      const description = frontmatter.match(/^description:\s*(.+)$/m)?.[1]?.trim() || "";
+
+      // Handle both single-line and multi-line (YAML >) descriptions
+      let description = "";
+      const descMatch = frontmatter.match(/^description:\s*(.+)$/m);
+      if (descMatch && descMatch[1].trim() === ">") {
+        // Multi-line: capture indented lines after "description: >"
+        const multiMatch = frontmatter.match(/^description:\s*>\s*\n((?:[ \t]+.+\n?)*)/m);
+        if (multiMatch) {
+          description = multiMatch[1].replace(/^[ \t]+/gm, "").replace(/\n/g, " ").trim();
+        }
+      } else if (descMatch) {
+        description = descMatch[1].trim();
+      }
       return { name, description };
     } catch {
       return {};

package/src/agent/token-counter.js

@@ -0,0 +1,62 @@
+/**
+ * Lightweight token estimation without external dependencies.
+ * Uses character-based heuristics: ~4 chars per token for Latin text,
+ * ~1.5 tokens per CJK character.
+ */
+
+// CJK Unified Ideographs and extensions
+const CJK_REGEX = /[\u4e00-\u9fff\u3400-\u4dbf\uf900-\ufaff]/g;
+
+/**
+ * Estimate the number of tokens in a string.
+ * @param {string} text
+ * @returns {number}
+ */
+export function estimateTokens(text) {
+  if (!text) return 0;
+  const cjkMatches = text.match(CJK_REGEX);
+  const cjkCount = cjkMatches ? cjkMatches.length : 0;
+  const nonCjkLength = text.length - cjkCount;
+  return Math.ceil(nonCjkLength / 4) + Math.ceil(cjkCount * 1.5);
+}
+
+/**
+ * Estimate total tokens for an array of OpenAI-format messages.
+ * Accounts for per-message overhead (~4 tokens for role/formatting).
+ * @param {Array<object>} messages
+ * @returns {number}
+ */
+export function estimateMessagesTokens(messages) {
+  let total = 0;
+  for (const msg of messages) {
+    total += 4; // role + formatting overhead
+    if (typeof msg.content === "string") {
+      total += estimateTokens(msg.content);
+    } else if (Array.isArray(msg.content)) {
+      // Anthropic-style content blocks
+      for (const block of msg.content) {
+        if (block.text) total += estimateTokens(block.text);
+        if (block.content) total += estimateTokens(block.content);
+      }
+    }
+    if (msg.tool_calls) {
+      for (const tc of msg.tool_calls) {
+        total += estimateTokens(tc.function?.name || "");
+        total += estimateTokens(tc.function?.arguments || "");
+      }
+    }
+  }
+  return total;
+}
+
+/**
+ * Format a token count for display (e.g., "45.2k").
+ * @param {number} tokens
+ * @returns {string}
+ */
+export function formatTokenCount(tokens) {
+  if (tokens >= 1000) {
+    return (tokens / 1000).toFixed(1) + "k";
+  }
+  return tokens.toString();
+}

package/src/agent/tools/document-parse.js

@@ -12,13 +12,13 @@ const MIN_CHARS_PER_PAGE = 50;
  * Level 3: OCR models via SiliconFlow — fallback via vision models
  */
 export class DocumentParseTool extends BaseTool {
-  constructor(workspace, { mineruApiUrl, mineruApiKey, siliconflowApiKey, siliconflowBaseUrl, ocrModel } = {}) {
+  constructor(workspace, { mineruApiUrl, mineruApiKey, llmApiKey, llmBaseUrl, ocrModel } = {}) {
     super();
     this._workspace = workspace;
     this._mineruApiUrl = mineruApiUrl || "";
     this._mineruApiKey = mineruApiKey || "";
-    this._sfApiKey = siliconflowApiKey || "";
-    this._sfBaseUrl = siliconflowBaseUrl || "https://api.siliconflow.cn/v1";
+    this._vlmApiKey = llmApiKey || "";
+    this._vlmBaseUrl = (llmBaseUrl || "").replace(/\/+$/, "");
     this._ocrModel = ocrModel || "";
   }
 
@@ -36,13 +36,18 @@ export class DocumentParseTool extends BaseTool {
     return {
       type: "object",
       properties: {
-        path: { type: "string", description: "Relative path to the document in the workspace" },
+        path: { type: "string", description: "Relative path to the document" },
         pages: { type: "string", description: "Page range to extract, e.g. '1-5', '3', '10-20'. Omit for all pages." },
         force_method: {
           type: "string",
-          enum: ["pdfjs", "mineru", "ocr"],
+          enum: ["pdfjs", "vlm", "mineru", "ocr"],
           description: "Force a specific parsing method, skipping the escalation chain.",
         },
+        scope: {
+          type: "string",
+          enum: ["workspace", "project"],
+          description: "Which directory to find the file in. 'workspace' (default) or 'project' (user's project folder).",
+        },
       },
       required: ["path"],
     };
@@ -52,11 +57,19 @@ export class DocumentParseTool extends BaseTool {
     const pathStr = input.path || "";
     const pages = input.pages;
     const force = input.force_method;
+    const scope = input.scope || "workspace";
 
     if (!pathStr) return new ToolResult("No path provided", true);
+    if (scope === "project" && !this._workspace.projectDir) {
+      return new ToolResult("No project directory available", true);
+    }
 
     let resolved;
-    try { resolved = this._workspace.resolvePath(pathStr); }
+    try {
+      resolved = scope === "project"
+        ? this._workspace.resolveProjectPath(pathStr)
+        : this._workspace.resolvePath(pathStr);
+    }
     catch (e) { return new ToolResult(e.message, true); }
 
     if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) {
@@ -76,13 +89,21 @@ export class DocumentParseTool extends BaseTool {
     if (force) return this._runMethod(force, resolved, pageRange);
 
     // Escalation chain
-    // Level 1: pdfjs-dist
+    // Level 1: pdfjs-dist (free, local text extraction)
     let result = await this._tryPdfjs(resolved, pageRange);
     if (result && this._qualityOk(result)) {
       return new ToolResult(this._formatOutput(result, "pdfjs", resolved));
     }
 
-    // Level 2: MineRU API
+    // Level 2: Provider VLM (vision model via API — more convenient than local OCR)
+    if (this._vlmApiKey && this._ocrModel) {
+      result = await this._tryVlm(resolved, pageRange);
+      if (result && this._qualityOk(result)) {
+        return new ToolResult(this._formatOutput(result, "vlm", resolved));
+      }
+    }
+
+    // Level 3: MineRU API (optional fallback)
     if (this._mineruApiUrl) {
       result = await this._tryMineru(resolved, pageRange);
       if (result && this._qualityOk(result)) {
@@ -90,12 +111,6 @@ export class DocumentParseTool extends BaseTool {
       }
     }
 
-    // Level 3: OCR via SiliconFlow
-    if (this._sfApiKey && this._ocrModel) {
-      result = await this._tryOcr(resolved, pageRange);
-      if (result) return new ToolResult(this._formatOutput(result, "ocr", resolved));
-    }
-
     if (result) return new ToolResult(this._formatOutput(result, "pdfjs (low quality)", resolved));
 
     return new ToolResult(
@@ -108,7 +123,7 @@ export class DocumentParseTool extends BaseTool {
     let result;
     if (method === "pdfjs") result = await this._tryPdfjs(filePath, pageRange);
     else if (method === "mineru") result = await this._tryMineru(filePath, pageRange);
-    else if (method === "ocr") result = await this._tryOcr(filePath, pageRange);
+    else if (method === "ocr" || method === "vlm") result = await this._tryVlm(filePath, pageRange);
     else return new ToolResult(`Unknown method: ${method}`, true);
 
     if (result) return new ToolResult(this._formatOutput(result, method, filePath));
@@ -145,12 +160,80 @@ export class DocumentParseTool extends BaseTool {
     return null;
   }
 
-  async _tryOcr(filePath, pageRange) {
-    // OCR requires sending page images to a vision model API.
-    // Without a native image renderer, we delegate to the agent
-    // to use sandbox_exec for custom OCR pipelines.
-    // For now, return null to signal OCR is not available natively.
-    return null;
+  async _tryVlm(filePath, pageRange) {
+    // Send page images to a VLM provider for OCR/interpretation.
+    // Renders PDF pages to PNG via pdfjs canvas, then sends base64 to VLM API.
+    if (!this._vlmApiKey || !this._ocrModel || !this._vlmBaseUrl) return null;
+
+    try {
+      const pdfjsLib = await import("pdfjs-dist/legacy/build/pdf.mjs");
+      const data = new Uint8Array(fs.readFileSync(filePath));
+      const doc = await pdfjsLib.getDocument({ data, useSystemFonts: true }).promise;
+
+      const start = pageRange ? pageRange[0] : 0;
+      const end = pageRange ? pageRange[1] : doc.numPages - 1;
+      const pages = [];
+
+      for (let i = Math.max(0, start); i <= Math.min(end, doc.numPages - 1); i++) {
+        const page = await doc.getPage(i + 1);
+        const viewport = page.getViewport({ scale: 2.0 }); // Higher res for OCR
+
+        // Use OffscreenCanvas or node-canvas if available, otherwise skip
+        let imageBase64;
+        try {
+          // In Node.js, pdfjs can render to a canvas-like object
+          // We'll use the simpler approach: convert page to image via the API
+          const { createCanvas } = await import("canvas").catch(() => ({ createCanvas: null }));
+          if (!createCanvas) {
+            // No canvas available — fall back to sending raw text content hint + page number
+            pages.push(`--- Page ${i + 1} (VLM) ---`);
+            continue;
+          }
+          const canvas = createCanvas(viewport.width, viewport.height);
+          const ctx = canvas.getContext("2d");
+          await page.render({ canvasContext: ctx, viewport }).promise;
+          imageBase64 = canvas.toBuffer("image/png").toString("base64");
+        } catch {
+          continue;
+        }
+
+        if (!imageBase64) continue;
+
+        // Call VLM API with the page image
+        const baseUrl = this._vlmBaseUrl.replace(/\/+$/, "");
+        const resp = await fetch(`${baseUrl}/chat/completions`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${this._vlmApiKey}`,
+          },
+          body: JSON.stringify({
+            model: this._ocrModel,
+            messages: [
+              { role: "system", content: "Extract all text from this document page. Preserve structure: headings, paragraphs, tables (as markdown), lists. Output clean text only." },
+              { role: "user", content: [
+                { type: "image_url", image_url: { url: `data:image/png;base64,${imageBase64}` } },
+                { type: "text", text: "Extract all text from this page." },
+              ]},
+            ],
+            max_tokens: 4096,
+          }),
+          signal: AbortSignal.timeout(60000),
+        });
+
+        if (resp.ok) {
+          const result = await resp.json();
+          const text = result.choices?.[0]?.message?.content || "";
+          if (text.trim()) {
+            pages.push(`--- Page ${i + 1} ---\n${text.trim()}`);
+          }
+        }
+      }
+
+      return pages.length > 0 ? pages.join("\n\n") : null;
+    } catch {
+      return null;
+    }
   }
 
   _qualityOk(text) {