kc-beta 0.1.0

package/bin/kc-beta.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+const subcommand = process.argv[2];
+
+(async () => {
+  if (subcommand === "onboard" || subcommand === "setup") {
+    const { onboard } = await import("../src/cli/onboard.js");
+    await onboard();
+  } 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();
+  }
+})();

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "kc-beta",
+  "version": "0.1.0",
+  "description": "KC Agent — LLM document verification agent (pure Node.js CLI)",
+  "type": "module",
+  "bin": {
+    "kc-beta": "bin/kc-beta.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "template/"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "ink": "^6.0.0",
+    "ink-text-input": "^6.0.0",
+    "ink-spinner": "^5.0.0",
+    "react": "^19.0.0",
+    "pdfjs-dist": "^4.0.0"
+  },
+  "keywords": [
+    "document-verification",
+    "llm",
+    "agent",
+    "cli"
+  ],
+  "author": "kitchen-engineer42",
+  "license": "MIT"
+}

package/src/agent/confidence-scorer.js

@@ -0,0 +1,120 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const DEFAULT_PRIORS = {
+  regex: 0.95,
+  python: 0.90,
+  llm: 0.75,
+  ocr: 0.65,
+  fallback: 0.50,
+};
+
+/**
+ * Structural component: composite confidence scoring for verification results.
+ *
+ * Formula: confidence = method_prior x source_presence x historical_accuracy x (1 - corner_case_proximity)
+ */
+export class ConfidenceScorer {
+  /**
+   * @param {string} workspacePath
+   * @param {import('./corner-case-registry.js').CornerCaseRegistry} [cornerCases]
+   */
+  constructor(workspacePath, cornerCases) {
+    this._workspace = workspacePath;
+    this._cornerCases = cornerCases || null;
+    this._priors = { ...DEFAULT_PRIORS };
+    /** @type {Record<string, number>} rule_id → accuracy */
+    this._historical = {};
+    this._calibrationPath = path.join(workspacePath, "confidence_calibration.json");
+    this._loadConfig();
+    this._loadCalibration();
+  }
+
+  _loadConfig() {
+    const envPath = path.join(this._workspace, ".env");
+    if (!fs.existsSync(envPath)) return;
+    const lines = fs.readFileSync(envPath, "utf-8").split("\n");
+    for (const line of lines) {
+      if (line.startsWith("CONFIDENCE_PRIORS=")) {
+        try {
+          const custom = JSON.parse(line.split("=")[1].trim());
+          if (typeof custom === "object") Object.assign(this._priors, custom);
+        } catch { /* ignore */ }
+      }
+    }
+  }
+
+  _loadCalibration() {
+    if (!fs.existsSync(this._calibrationPath)) return;
+    try {
+      const data = JSON.parse(fs.readFileSync(this._calibrationPath, "utf-8"));
+      this._historical = data.historical_accuracy || {};
+    } catch { /* ignore */ }
+  }
+
+  /**
+   * Compute composite confidence score (0.0 - 1.0).
+   * @param {object} opts
+   * @param {string} opts.ruleId
+   * @param {string} opts.extractedValue
+   * @param {string} [opts.sourceText]
+   * @param {string} [opts.extractionMethod]
+   * @param {string} [opts.documentName]
+   * @returns {number}
+   */
+  score({ ruleId, extractedValue, sourceText = "", extractionMethod = "llm", documentName = "" }) {
+    const methodPrior = this._priors[extractionMethod] ?? this._priors.fallback;
+
+    let sourcePresence = 1.0;
+    if (sourceText && extractedValue) {
+      sourcePresence = sourceText.includes(extractedValue) ? 1.0 : 0.7;
+    }
+
+    const historical = this._historical[ruleId] ?? 0.8;
+
+    let cornerProximity = 0.0;
+    if (this._cornerCases && documentName) {
+      const matches = this._cornerCases.match(documentName, ruleId);
+      if (matches.length > 0) {
+        cornerProximity = Math.min(0.3, 0.1 * matches.length);
+      }
+    }
+
+    const confidence = methodPrior * sourcePresence * historical * (1.0 - cornerProximity);
+    return Math.round(Math.max(0.0, Math.min(1.0, confidence)) * 1000) / 1000;
+  }
+
+  /**
+   * Auto-calibrate after QC cycle.
+   * @param {Record<string, {predicted_avg?: number, actual_accuracy?: number}>} qcResults
+   */
+  calibrate(qcResults) {
+    for (const [ruleId, data] of Object.entries(qcResults)) {
+      const actual = data.actual_accuracy;
+      if (actual != null) {
+        const old = this._historical[ruleId] ?? 0.8;
+        this._historical[ruleId] = Math.round((0.7 * actual + 0.3 * old) * 1000) / 1000;
+      }
+    }
+    this._saveCalibration();
+  }
+
+  _saveCalibration() {
+    fs.writeFileSync(
+      this._calibrationPath,
+      JSON.stringify({ historical_accuracy: this._historical }, null, 2),
+      "utf-8",
+    );
+  }
+
+  /**
+   * Classify confidence into low/medium/high band.
+   * @param {number} confidence
+   * @returns {string}
+   */
+  getBand(confidence) {
+    if (confidence >= 0.8) return "high";
+    if (confidence >= 0.5) return "medium";
+    return "low";
+  }
+}

package/src/agent/context.js

@@ -0,0 +1,124 @@
+const AGENT_IDENTITY = `\
+You are KC Agent, a document verification coding agent. You help users build \
+and manage document verification systems for financial institutions.
+
+You are direct and technical. You think step by step. When you don't know \
+something, you say so.
+
+## Tools
+
+You have the following tools:
+
+- **sandbox_exec**: Execute shell commands in your workspace directory. Use this \
+to run Python scripts, install packages, list files, etc. Pipes and redirects work.
+
+- **workspace_file**: Read, write, or list files in your workspace. Operations: \
+read (path), write (path + content), list (optional path).
+
+- **document_parse**: Parse documents (PDF, DOCX, images) and extract text. \
+Internally uses an escalation chain: text extraction → API parser → OCR models. \
+Starts cheap, escalates if needed. You don't choose the method — the tool handles it. \
+Use force_method only for testing or if the developer user requests a specific parser.
+
+- **worker_llm_call**: Call a worker LLM at a specified tier (tier1=most capable, \
+tier4=cheapest). Use for distillation testing — check if cheaper models can handle \
+extraction/judgment steps. Returns response with model used and token counts.
+
+- **workflow_run**: Execute a distilled workflow against a document. Automatically \
+attaches confidence scores and trace IDs. Results saved to output/results/.
+
+- **tier_downgrade**: Test a workflow step at a lower tier. Compares accuracy at \
+target tier vs. current baseline. Recommends downgrade if accuracy stays above threshold.
+
+- **evolution_cycle**: Run one diagnose-classify-fix iteration. Classifies failures \
+as systemic (>threshold) or corner case (<threshold). Routes corner cases to registry \
+automatically. Checks for repeated failure patterns across iterations.
+
+- **document_search**: Search for text across workspace documents. Supports plain text \
+and regex. Returns matching passages with file path and line number.
+
+- **rule_catalog**: CRUD on the rule registry. Enforces required fields (id, source_ref, \
+description). Operations: create, read, update, delete, list.
+
+- **qc_sample**: Draw adaptive sample from production results for review. Stratifies \
+by confidence band. All low-confidence reviewed, medium sampled, high spot-checked.
+
+- **dashboard_render**: Generate a self-contained HTML dashboard from project metrics. \
+Shows rules, confidence distribution, evolution history, QC results.
+
+- **agent_tool**: Spawn a sub-agent for independent parallel work. Give it a complete \
+task description — it has no context from your conversation. Sub-agent writes results \
+to sub_agents/{task_id}/. Use for parallel rule testing, batch processing, etc.
+
+Use tools to do real work. Write code to files, then run it. Check results by \
+reading output. Don't guess — verify.
+
+## Methodology
+
+### Document Parsing
+- Start with the simplest parser (text extraction). Escalate to OCR/vision only \
+when output is empty or garbled (<50 chars/page). Simple parsers fail less.
+- Once a parser works for a document type, lock it in. Don't re-evaluate unless \
+downstream extraction fails.
+- Tables need special handling — extract cell-by-cell, reconstruct as markdown or JSON.
+
+### Data Sensibility
+- Read 3-5 complete documents end-to-end BEFORE writing extraction logic. Read raw \
+parsed text, not PDF viewer. This saves hours of debugging bad assumptions.
+- After extraction, spot-check 10 random fields (3 high-confidence, 4 medium, \
+3 low) against source. If >1 out of 10 is wrong, STOP — don't continue.
+- Save every processing stage to disk (raw text → sections → entities → judgments). \
+Disk is cheap; debugging without intermediates is guesswork.
+
+### Rule Extraction
+- One rule = one pass/fail outcome. If a rule can produce two independent results, \
+split it. Rules must be self-contained and scoped to where in the document to look.
+- Work top-down (onion peeler): major areas → chapters → sections → atomic rules. \
+Stop when rules are atomic and testable.
+- Handle ambiguity explicitly. Extract as understood, note ambiguities, ask the \
+developer user. Ambiguous rules are often the most important — don't skip them.
+- After extraction, audit coverage: which regulation paragraphs are NOT covered?
+
+### Entity Extraction
+- Method selection: regex/Python first (free, instant, predictable formats). LLM \
+only when semantic understanding is required. Hybrid: regex first, LLM fallback.
+- Every extraction must capture: value, evidence (raw text), source location, \
+confidence, method used.
+- Postprocessing is deterministic code: date standardization, unit conversion, \
+Chinese numeral conversion. Build as reusable Python functions.
+
+### Evolution Loop
+- The cycle: test → observe → diagnose → classify → fix → retest → log.
+- Diagnose root cause into: parsing failure, extraction failure, judgment failure, \
+or scope failure. Each drives different fixes.
+- Systemic issue (>10% of docs) → rewrite code/prompts. Corner case (<10%) → \
+record in corner_cases.json with detection + resolution. Do NOT patch main \
+workflow for corner cases.
+- Stop when: accuracy meets threshold, or correction volume <5% and no new \
+failure patterns.
+
+### Reflection & Skill Writing
+- When you solve a hard problem (OCR approach, extraction pattern, edge case \
+handling), write it down as a reusable skill in rule_skills/. Future sessions \
+and rules benefit from your discoveries.
+- Skills capture methodology, not just code. Describe WHEN to use this approach, \
+WHY it works, and WHAT to watch out for.`;
+
+/**
+ * Builds the system prompt from multiple context sources.
+ * Combines: agent identity + methodology + pipeline state + workspace state.
+ */
+export class ContextAssembler {
+  /**
+   * @param {object} [opts]
+   * @param {string} [opts.pipelineState]
+   * @param {string} [opts.workspaceState]
+   * @returns {string}
+   */
+  build({ pipelineState, workspaceState } = {}) {
+    const parts = [AGENT_IDENTITY];
+    if (pipelineState) parts.push(pipelineState);
+    if (workspaceState) parts.push(workspaceState);
+    return parts.join("\n\n");
+  }
+}

package/src/agent/corner-case-registry.js

@@ -0,0 +1,119 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Structural component: first-class data structure for edge cases.
+ * Corner cases (<10% failure rate) are stored here instead of patching
+ * main workflows. The EvolutionController routes failures here automatically.
+ * Persists to workspace/corner_cases.json.
+ */
+export class CornerCaseRegistry {
+  /**
+   * @param {string} workspacePath
+   */
+  constructor(workspacePath) {
+    this._path = path.join(workspacePath, "corner_cases.json");
+    /** @type {Array<CornerCase>} */
+    this._cases = [];
+    this._load();
+  }
+
+  _load() {
+    if (!fs.existsSync(this._path)) return;
+    try {
+      const data = JSON.parse(fs.readFileSync(this._path, "utf-8"));
+      this._cases = data.map((e) => ({
+        id: e.id,
+        ruleId: e.rule_id || e.ruleId,
+        detectionPattern: e.detection_pattern || e.detectionPattern || "",
+        resolution: e.resolution || "",
+        affectedDocuments: e.affected_documents || e.affectedDocuments || [],
+        discoveryDate: e.discovery_date || e.discoveryDate || new Date().toISOString(),
+        status: e.status || "active",
+      }));
+    } catch {
+      this._cases = [];
+    }
+  }
+
+  _save() {
+    const data = this._cases.map((c) => ({
+      id: c.id,
+      rule_id: c.ruleId,
+      detection_pattern: c.detectionPattern,
+      resolution: c.resolution,
+      affected_documents: c.affectedDocuments,
+      discovery_date: c.discoveryDate,
+      status: c.status,
+    }));
+    fs.writeFileSync(this._path, JSON.stringify(data, null, 2), "utf-8");
+  }
+
+  /**
+   * Add or update a corner case. Deduplicates by id.
+   * @param {CornerCase} cornerCase
+   */
+  add(cornerCase) {
+    if (!cornerCase.discoveryDate) {
+      cornerCase.discoveryDate = new Date().toISOString();
+    }
+    const idx = this._cases.findIndex((c) => c.id === cornerCase.id);
+    if (idx >= 0) {
+      this._cases[idx] = cornerCase;
+    } else {
+      this._cases.push(cornerCase);
+    }
+    this._save();
+  }
+
+  /**
+   * @param {string} caseId
+   * @returns {CornerCase|null}
+   */
+  get(caseId) {
+    return this._cases.find((c) => c.id === caseId) || null;
+  }
+
+  /**
+   * @param {string} ruleId
+   * @returns {Array<CornerCase>}
+   */
+  getByRule(ruleId) {
+    return this._cases.filter((c) => c.ruleId === ruleId && c.status === "active");
+  }
+
+  allActive() {
+    return this._cases.filter((c) => c.status === "active");
+  }
+
+  count() {
+    return this._cases.length;
+  }
+
+  /**
+   * Check if a document matches any known corner case patterns for a rule.
+   * @param {string} documentName
+   * @param {string} ruleId
+   * @returns {Array<CornerCase>}
+   */
+  match(documentName, ruleId) {
+    const matches = [];
+    for (const c of this.getByRule(ruleId)) {
+      if (c.detectionPattern && documentName.toLowerCase().includes(c.detectionPattern.toLowerCase())) {
+        matches.push(c);
+      }
+    }
+    return matches;
+  }
+}
+
+/**
+ * @typedef {object} CornerCase
+ * @property {string} id
+ * @property {string} ruleId
+ * @property {string} detectionPattern
+ * @property {string} resolution
+ * @property {string[]} affectedDocuments
+ * @property {string} discoveryDate
+ * @property {string} status - active | resolved | obsolete
+ */

package/src/agent/engine.js

@@ -0,0 +1,224 @@
+import { AgentEvent } from "./events.js";
+import { ContextAssembler } from "./context.js";
+import { ConversationHistory } from "./history.js";
+import { Workspace } from "./workspace.js";
+import { VersionManager } from "./version-manager.js";
+import { CornerCaseRegistry } from "./corner-case-registry.js";
+import { ConfidenceScorer } from "./confidence-scorer.js";
+import { ToolRegistry } from "./tools/registry.js";
+import { SandboxExecTool } from "./tools/sandbox-exec.js";
+import { WorkspaceFileTool } from "./tools/workspace-file.js";
+import { DocumentParseTool } from "./tools/document-parse.js";
+import { DocumentSearchTool } from "./tools/document-search.js";
+import { WorkerLLMCallTool } from "./tools/worker-llm-call.js";
+import { WorkflowRunTool } from "./tools/workflow-run.js";
+import { RuleCatalogTool } from "./tools/rule-catalog.js";
+import { QCSampleTool } from "./tools/qc-sample.js";
+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 { Phase } from "./pipelines/index.js";
+import { ProjectInitializer } from "./pipelines/initializer.js";
+import { RuleExtractionPipeline } from "./pipelines/extraction.js";
+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";
+
+/**
+ * The KC Agent conversation engine.
+ *
+ * Core loop: user message -> context assembly -> LLM API (streaming) ->
+ * tool execution (if any) -> repeat until no tool calls -> turn complete.
+ *
+ * Uses OpenAI-compatible API. Yields AgentEvent objects.
+ */
+export class AgentEngine {
+  /**
+   * @param {object} opts
+   * @param {import('./llm-client.js').LLMClient} opts.client
+   * @param {object} opts.config - Settings from loadSettings()
+   * @param {string} [opts.sessionId]
+   */
+  constructor({ client, config, sessionId }) {
+    this.client = client;
+    this.config = config;
+    this.context = new ContextAssembler();
+    this.toolRegistry = new ToolRegistry();
+
+    // Workspace + structural components
+    this.workspace = new Workspace(config.kcWorkspaceRoot, sessionId);
+    this.history = new ConversationHistory(this.workspace.cwd);
+    this.versionManager = new VersionManager(this.workspace.cwd);
+    this.cornerCases = new CornerCaseRegistry(this.workspace.cwd);
+    this.confidence = new ConfidenceScorer(this.workspace.cwd, this.cornerCases);
+
+    // Register tools
+    this.toolRegistry.register(new SandboxExecTool(this.workspace, config.kcExecTimeout));
+    this.toolRegistry.register(new WorkspaceFileTool(this.workspace, this.versionManager));
+    this.toolRegistry.register(new DocumentParseTool(this.workspace, {
+      mineruApiUrl: config.mineruApiUrl,
+      mineruApiKey: config.mineruApiKey,
+      siliconflowApiKey: config.siliconflowApiKey,
+      siliconflowBaseUrl: config.siliconflowBaseUrl,
+      ocrModel: config.ocrModelTier1,
+    }));
+    this.toolRegistry.register(new DocumentSearchTool(this.workspace));
+
+    const workerLlm = new WorkerLLMCallTool(this.workspace, {
+      apiKey: config.siliconflowApiKey,
+      baseUrl: config.siliconflowBaseUrl,
+    });
+    this.toolRegistry.register(workerLlm);
+    this.toolRegistry.register(new WorkflowRunTool(this.workspace, this.versionManager, this.confidence));
+    this.toolRegistry.register(new TierDowngradeTool(this.workspace, workerLlm));
+    this.toolRegistry.register(new EvolutionCycleTool(this.workspace, this.cornerCases));
+    this.toolRegistry.register(new RuleCatalogTool(this.workspace));
+    this.toolRegistry.register(new QCSampleTool(this.workspace));
+    this.toolRegistry.register(new DashboardRenderTool(this.workspace));
+    this.toolRegistry.register(new AgentTool(this.workspace, (sid) => new AgentEngine({ client, config, sessionId: sid })));
+
+    // Pipeline system (meta-meta skills as code)
+    this.currentPhase = Phase.BOOTSTRAP;
+    this.pipelines = {
+      [Phase.BOOTSTRAP]: new ProjectInitializer(this.workspace),
+      [Phase.EXTRACTION]: new RuleExtractionPipeline(this.workspace),
+      [Phase.SKILL_AUTHORING]: new SkillAuthoringPipeline(this.workspace),
+      [Phase.SKILL_TESTING]: new SkillTestingPipeline(this.workspace),
+      [Phase.DISTILLATION]: new DistillationPipeline(this.workspace),
+      [Phase.PRODUCTION_QC]: new ProductionQCPipeline(this.workspace),
+    };
+  }
+
+  /**
+   * Register additional tools (called after construction for tools that need extra deps).
+   * @param {import('./tools/base.js').BaseTool} tool
+   */
+  registerTool(tool) {
+    this.toolRegistry.register(tool);
+  }
+
+  /**
+   * Run one conversation turn. Yields AgentEvent objects.
+   * Loops: LLM call -> tool execution -> LLM call ... until no tool calls.
+   * @param {string} userMessage
+   * @yields {AgentEvent}
+   */
+  async *runTurn(userMessage) {
+    this.history.addUser(userMessage);
+
+    // Pipeline state injection
+    const pipeline = this.pipelines[this.currentPhase];
+    const pipelineState = pipeline?.describeState?.() || null;
+
+    const systemPrompt = this.context.build({
+      pipelineState,
+      workspaceState: `Your workspace directory is: ${this.workspace.cwd}`,
+    });
+    const tools = this.toolRegistry.schemasOpenai();
+
+    while (true) {
+      const messages = [{ role: "system", content: systemPrompt }, ...this.history.messages];
+
+      try {
+        let collectedText = "";
+        /** @type {Map<number, {id: string, name: string, arguments: string}>} */
+        const toolCallsAcc = new Map();
+
+        const stream = this.client.streamChat({
+          model: this.config.kcModel,
+          messages,
+          tools: tools.length > 0 ? tools : undefined,
+          maxTokens: this.config.kcMaxTokens,
+        });
+
+        for await (const chunk of stream) {
+          const delta = chunk.choices?.[0]?.delta;
+          if (!delta) continue;
+
+          // Stream text content
+          if (delta.content) {
+            yield new AgentEvent({ type: "text_delta", text: delta.content });
+            collectedText += delta.content;
+          }
+
+          // Accumulate tool calls from deltas
+          if (delta.tool_calls) {
+            for (const tcDelta of delta.tool_calls) {
+              const idx = tcDelta.index;
+              if (!toolCallsAcc.has(idx)) {
+                toolCallsAcc.set(idx, { id: tcDelta.id || "", name: "", arguments: "" });
+              }
+              const acc = toolCallsAcc.get(idx);
+              if (tcDelta.id) acc.id = tcDelta.id;
+              if (tcDelta.function?.name) acc.name = tcDelta.function.name;
+              if (tcDelta.function?.arguments) acc.arguments += tcDelta.function.arguments;
+            }
+          }
+        }
+
+        // Build assistant message for history
+        const assistantMsg = { role: "assistant", content: collectedText || null };
+        if (toolCallsAcc.size > 0) {
+          assistantMsg.tool_calls = Array.from(toolCallsAcc.values()).map((tc) => ({
+            id: tc.id,
+            type: "function",
+            function: { name: tc.name, arguments: tc.arguments },
+          }));
+        }
+        this.history.addRaw(assistantMsg);
+
+        // No tool calls → turn complete
+        if (toolCallsAcc.size === 0) {
+          yield new AgentEvent({ type: "turn_complete" });
+          return;
+        }
+
+        // Tool execution loop
+        for (const tc of toolCallsAcc.values()) {
+          let inputData = {};
+          try {
+            inputData = tc.arguments ? JSON.parse(tc.arguments) : {};
+          } catch { /* ignore parse errors */ }
+
+          yield new AgentEvent({ type: "tool_start", name: tc.name, input: inputData });
+          const result = await this.toolRegistry.execute(tc.name, inputData);
+          yield new AgentEvent({
+            type: "tool_result",
+            name: tc.name,
+            output: result.content,
+            isError: result.isError,
+          });
+
+          // Add tool result message
+          this.history.addRaw({
+            role: "tool",
+            tool_call_id: tc.id,
+            content: result.content,
+          });
+
+          // Pipeline controller: update state after tool execution
+          if (pipeline?.onToolResult) {
+            const pEvent = pipeline.onToolResult(tc.name, inputData, result);
+            if (pEvent) {
+              if (pEvent.type === "phase_ready" && pEvent.nextPhase) {
+                this.currentPhase = pEvent.nextPhase;
+              }
+              yield new AgentEvent({
+                type: "pipeline_event",
+                data: pEvent,
+              });
+            }
+          }
+        }
+
+        // Loop continues — send tool results back to LLM
+
+      } catch (err) {
+        yield new AgentEvent({ type: "error", message: err.message });
+        return;
+      }
+    }
+  }
+}

package/src/agent/events.js

@@ -0,0 +1,27 @@
+/**
+ * A single event emitted by the agent engine during a turn.
+ * The CLI renders these directly — no serialization needed.
+ */
+export class AgentEvent {
+  /**
+   * @param {object} opts
+   * @param {string} opts.type - Event type: text_delta, turn_complete, tool_start, tool_result, error, pipeline_event, phase_update, session_info, system_message, history_load
+   * @param {string} [opts.text] - Text content (text_delta)
+   * @param {string} [opts.name] - Tool name (tool_start, tool_result)
+   * @param {object} [opts.input] - Tool input (tool_start)
+   * @param {string} [opts.output] - Tool output (tool_result)
+   * @param {boolean} [opts.isError] - Whether tool errored (tool_result)
+   * @param {string} [opts.message] - Message (error, system_message)
+   * @param {object} [opts.data] - Generic payload (pipeline_event)
+   */
+  constructor({ type, text, name, input, output, isError, message, data }) {
+    this.type = type;
+    this.text = text ?? null;
+    this.name = name ?? null;
+    this.input = input ?? null;
+    this.output = output ?? null;
+    this.isError = isError ?? false;
+    this.message = message ?? null;
+    this.data = data ?? {};
+  }
+}