@karajan-family/code 4.21.0

package/src/roles/base-role.js

@@ -0,0 +1,165 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getKarajanHome } from "../utils/paths.js";
+import { loadRoleInstructions } from "../prompts/prompt-resolver.js";
+
+const ROLE_EVENTS = {
+  START: "role:start",
+  END: "role:end",
+  ERROR: "role:error"
+};
+
+/**
+ * Legacy flat resolver. Kept for back-compat with external callers and
+ * existing tests that assert the 3-entry candidate list. New code should use
+ * `loadRoleInstructions()` from src/prompts/prompt-resolver.js, which
+ * additionally tries per-provider and per-role subdirectories.
+ */
+function resolveRoleMdPath(roleName, projectDir) {
+  const fileName = `${roleName}.md`;
+  const candidates = [];
+
+  if (projectDir) {
+    candidates.push(path.join(projectDir, ".karajan", "roles", fileName));
+  }
+
+  candidates.push(path.join(getKarajanHome(), "roles", fileName));
+
+  const builtIn = path.resolve(
+    path.dirname(new URL(import.meta.url).pathname),
+    "..",
+    "..",
+    "templates",
+    "roles",
+    fileName
+  );
+  candidates.push(builtIn);
+
+  return candidates;
+}
+
+async function loadFirstExisting(paths) {
+  for (const p of paths) {
+    try {
+      return await fs.readFile(p, "utf8");
+    } catch { /* file not found */
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * Base class for every pipeline role (coder, reviewer, planner, refactorer,
+ * researcher, architect, triage, discover, tester, security, impeccable,
+ * hu-reviewer, audit, solomon, commiter, karajan-brain, domain-curator).
+ *
+ * Conceptual mapping for developers coming from other ecosystems:
+ * `BaseRole` (and every subclass) is Karajan's equivalent of a **Flow** in the
+ * Genkit sense — a named, composable unit of work with a prompt, an invocation
+ * and a parsed output. The important difference: a Karajan Role executes over
+ * a **subprocess CLI** (`claude`, `codex`, `gemini`, `aider`, `opencode`), not
+ * by calling an HTTP provider API. No PTY, no long-lived session — each run
+ * is a fresh subprocess with state on disk under `~/.karajan/sessions/`.
+ *
+ * See `docs/COMPARISON.md` for the full positioning.
+ *
+ * @alias Flow — similar to Genkit Flow but executed over subprocess CLIs, not API calls.
+ */
+export class BaseRole {
+  constructor({ name, config, logger, emitter = null }) {
+    if (!name) throw new Error("Role name is required");
+    this.name = name;
+    this.config = config || {};
+    this.logger = logger;
+    this.emitter = emitter;
+    this.instructions = null;
+    this._initialized = false;
+    this._startTime = null;
+    this._output = null;
+  }
+
+  async init(context = {}) {
+    this.context = context;
+    const projectDir = this.config.projectDir || process.cwd();
+    // Subclasses (AgentRole) can override resolveProvider to expose the
+    // provider slug for the active role, which lets the prompt resolver
+    // pick a per-provider template variant when available.
+    const provider = typeof this.resolveProvider === "function"
+      ? this.resolveProvider()
+      : null;
+    const { instructions, path: templatePath, resolvedProvider, fellBack } = await loadRoleInstructions({
+      role: this.name,
+      provider,
+      projectDir,
+      logger: this.logger,
+    });
+    this.instructions = instructions;
+    this._templatePath = templatePath;
+    this._resolvedProvider = resolvedProvider;
+    this._promptFellBack = fellBack;
+    this._initialized = true;
+  }
+
+  async execute(_input) {
+    throw new Error(`${this.name}: execute() not implemented`);
+  }
+
+  report() {
+    return {
+      role: this.name,
+      ok: this._output?.ok ?? false,
+      result: this._output?.result ?? null,
+      summary: this._output?.summary ?? "",
+      timestamp: new Date().toISOString()
+    };
+  }
+
+  validate(output) {
+    if (!output) return { valid: false, reason: "Output is null or undefined" };
+    if (typeof output.ok !== "boolean") return { valid: false, reason: "Output.ok must be a boolean" };
+    return { valid: true, reason: "" };
+  }
+
+  async run(input) {
+    this._ensureInitialized();
+    this._startTime = Date.now();
+    this._emitEvent(ROLE_EVENTS.START, { input });
+
+    try {
+      const output = await this.execute(input);
+      this._output = output;
+
+      const validation = this.validate(output);
+      if (!validation.valid) {
+        throw new Error(`${this.name} output validation failed: ${validation.reason}`);
+      }
+
+      this._emitEvent(ROLE_EVENTS.END, { output: this.report() });
+      return output;
+    } catch (error) {
+      this._emitEvent(ROLE_EVENTS.ERROR, { error: error.message });
+      throw error;
+    }
+  }
+
+  _ensureInitialized() {
+    if (!this._initialized) {
+      throw new Error(`${this.name}: init() must be called before run()`);
+    }
+  }
+
+  _emitEvent(type, detail = {}) {
+    if (!this.emitter) return;
+    this.emitter.emit(type, {
+      role: this.name,
+      iteration: this.context?.iteration ?? 0,
+      sessionId: this.context?.sessionId ?? null,
+      elapsed: this._startTime ? Date.now() - this._startTime : 0,
+      timestamp: new Date().toISOString(),
+      ...detail
+    });
+  }
+}
+
+export { ROLE_EVENTS, resolveRoleMdPath, loadFirstExisting };

package/src/roles/coder-role.js

@@ -0,0 +1,107 @@
+import { AgentRole } from "./agent-role.js";
+import { buildCoderPromptLayout } from "../prompts/coder.js";
+import { joinLayout } from "../prompts/prompt-layout.js";
+import { isHostAgent } from "../utils/agent-detect.js";
+import { HostAgent } from "../agents/host-agent.js";
+import { detectProjectStack } from "../utils/stack-detect.js";
+import { detectTestFramework } from "../utils/project-detect.js";
+
+export class CoderRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "coder" });
+    this._askHost = opts.askHost || null;
+  }
+
+  resolveProvider() {
+    return this.config?.roles?.coder?.provider || this.config?.coder || "claude";
+  }
+
+  createAgentInstance(provider) {
+    // KJC-BUG-0129 (issues #1301/#1303): running INSIDE an agent does not
+    // make it "the host executor" — delegating sent the full instruction
+    // prompt through elicitInput as a hanging board "question". A CLI
+    // provider spawns as a subprocess ALWAYS; host delegation is explicit
+    // opt-in (roles.coder.host_delegation: true) for MCP-only setups.
+    if (this._askHost && isHostAgent(provider)) {
+      if (this.config?.roles?.coder?.host_delegation === true) {
+        this.logger.info(`Host-as-coder: delegating to host AI (roles.coder.host_delegation, skipping ${provider} subprocess)`);
+        return new HostAgent(this.config, this.logger, { askHost: this._askHost });
+      }
+      this.logger.info(`Running inside ${provider} — spawning it as a subprocess anyway (set roles.coder.host_delegation: true to delegate to the host)`);
+    }
+    return this._createAgent(provider, this.config, this.logger);
+  }
+
+  extractInput(input) {
+    if (typeof input === "string") {
+      return {
+        task: input,
+        reviewerFeedback: null, sonarSummary: null, deferredContext: null,
+        acceptanceTests: null,
+        adrs: null, specSection: null, reviewerFindings: null, huId: null,
+        projectDir: null,
+        onOutput: null
+      };
+    }
+    return {
+      task: input?.task || this.context?.task || "",
+      reviewerFeedback: input?.reviewerFeedback || null,
+      sonarSummary: input?.sonarSummary || null,
+      deferredContext: input?.deferredContext || null,
+      // Tests-first (v2.7.5): the coder reads these as the gate it
+      // must satisfy. Only the plan-backed HU path populates this;
+      // the standard single-task `kj run` flow leaves it null.
+      acceptanceTests: input?.acceptanceTests || null,
+      // PR F (v2.7.5): per-HU planning context. ADRs constrain HOW,
+      // specSection ties this HU to a SPEC heading, reviewerFindings
+      // are filtered to entries that mention this HU. All four are
+      // null for non-plan-backed runs, which keeps the legacy flow
+      // byte-for-byte identical.
+      adrs: Array.isArray(input?.adrs) ? input.adrs : null,
+      specSection: input?.specSection || null,
+      reviewerFindings: input?.reviewerFindings || null,
+      huId: input?.huId || null,
+      // PAR-E2 (KJC-TSK-0629): per-call project root. Worktree lanes pass
+      // their lane dir here; the shared role instance keeps its own config.
+      projectDir: input?.projectDir || null,
+      // PAR-H (KJC-TSK-0631): per-call subprocess env (lane slot vars).
+      env: input?.env || null,
+      onOutput: input?.onOutput || null
+    };
+  }
+
+  async buildPrompt({ task, reviewerFeedback, sonarSummary, deferredContext, acceptanceTests, adrs, specSection, reviewerFindings, huId, projectDir: laneProjectDir }) {
+    const projectDir = laneProjectDir || this.config?.projectDir || null;
+    // KJC sesgo-de-stack: pasar stack/testFramework al prompt para que
+    // el coder no asuma JS/vitest en proyectos Python / Go / Rust /
+    // Ruby. audit-role.js y tester-role.js ya lo hacen así.
+    let stack = null;
+    let testFramework = null;
+    if (projectDir) {
+      try { stack = await detectProjectStack(projectDir); } catch { /* best-effort */ }
+      try { testFramework = await detectTestFramework(projectDir); } catch { /* best-effort */ }
+    }
+    const layout = await buildCoderPromptLayout({
+      task, reviewerFeedback, sonarSummary, deferredContext, acceptanceTests,
+      adrs, specSection, reviewerFindings, huId,
+      coderRules: this.instructions,
+      methodology: this.config?.development?.methodology || "tdd",
+      serenaEnabled: Boolean(this.config?.serena?.enabled),
+      rtkAvailable: Boolean(this.config?.rtk?.available),
+      productContext: this.config?.productContext || null,
+      domainContext: this.config?.domainContext || null,
+      projectDir,
+      stack, testFramework,
+      provider: this._resolvedProvider || (typeof this.resolveProvider === "function" ? this.resolveProvider() : null)
+    });
+    // Φ1-D: prompt is the joined layout (identical for every agent);
+    // the buckets ride along so ClaudeAgent can system-split them.
+    return { prompt: joinLayout(layout), stablePrompt: layout.stable, volatilePrompt: layout.volatile };
+  }
+
+  buildSuccessResult(parsed, provider, agentResult) {
+    return { ...agentResult, output: agentResult.output || "", provider };
+  }
+
+  buildSummary() { return "Coder completed"; }
+}

package/src/roles/commiter-role.js

@@ -0,0 +1,110 @@
+import { BaseRole } from "./base-role.js";
+import { stampStagedVerdict } from "../review/verdict-store.js";
+import {
+  ensureGitRepo,
+  currentBranch,
+  fetchBase,
+  ensureBranchUpToDateWithBase,
+  hasChanges,
+  commitAll,
+  pushBranch,
+  createPullRequest,
+  revParse,
+  hasRemote
+} from "../utils/git.js";
+
+function buildCommitMessage(task) {
+  const clean = String(task || "")
+    .replaceAll(/\s+/g, " ")
+    .trim();
+  const prefix = "feat: ";
+  const maxBody = 72 - prefix.length;
+  return `${prefix}${clean.slice(0, maxBody) || "update"}`;
+}
+
+function buildPrTitle(task) {
+  const clean = String(task || "")
+    .replaceAll(/\s+/g, " ")
+    .trim();
+  return clean.slice(0, 70) || "Karajan update";
+}
+
+export class CommiterRole extends BaseRole {
+  constructor({ config, logger, emitter = null }) {
+    super({ name: "commiter", config, logger, emitter });
+  }
+
+  async execute(input) {
+    const { task, commitMessage, push = false, createPr = false } = input || {};
+
+    const isRepo = await ensureGitRepo();
+    if (!isRepo) {
+      return {
+        ok: false,
+        result: { error: "Current directory is not a git repository" },
+        summary: "Commiter failed: not a git repo"
+      };
+    }
+
+    const branch = await currentBranch();
+    const changes = await hasChanges();
+
+    if (!changes) {
+      return {
+        ok: true,
+        result: { branch, committed: false, commitHash: null, prUrl: null },
+        summary: "No changes to commit"
+      };
+    }
+
+    const msg = commitMessage || buildCommitMessage(task);
+    // ENV-F1 (KJC-TSK-0643): CommiterRole runs after the HU review passed —
+    // stamp the pipeline's verdict so the v4 gate accepts this commit.
+    await commitAll(msg, null, {
+      beforeCommit: () => stampStagedVerdict({
+        projectDir: this.config?.projectDir || process.cwd(),
+        reviewer: this.config?.reviewer || "pipeline-reviewer",
+        summary: "kj pipeline (commiter role): review passed",
+      }),
+    });
+    const commitHash = await revParse("HEAD");
+
+    // KJC-BUG-0112: no `origin` remote (quickstart scenario) → skip
+    // push/PR instead of throwing on fetch.
+    const remoteAvailable = push ? await hasRemote() : false;
+    if (push && !remoteAvailable) {
+      this.logger?.info?.("No remote configured — skipping push/PR");
+    }
+    if (push && remoteAvailable) {
+      const baseBranch = this.config.base_branch || "main";
+      await fetchBase(baseBranch);
+      await ensureBranchUpToDateWithBase({
+        branch,
+        baseBranch,
+        autoRebase: true
+      });
+      await pushBranch(branch);
+    }
+
+    let prUrl = null;
+    if (push && createPr && remoteAvailable) {
+      const baseBranch = this.config.base_branch || "main";
+      prUrl = await createPullRequest({
+        baseBranch,
+        branch,
+        title: buildPrTitle(task),
+        body: `Task: ${task || "N/A"}`
+      });
+    }
+
+    const parts = [`Committed on ${branch}`];
+    if (push) parts.push("pushed");
+    if (prUrl) parts.push(`PR: ${prUrl}`);
+
+    return {
+      ok: true,
+      result: { branch, committed: true, commitHash, prUrl },
+      summary: parts.join(", ")
+    };
+  }
+}

package/src/roles/discover-role.js

@@ -0,0 +1,81 @@
+import { AgentRole } from "./agent-role.js";
+import { buildDiscoverPrompt, parseDiscoverOutput } from "../prompts/discover.js";
+
+function pluralize(count, singular, plural) {
+  return `${count} ${count === 1 ? singular : plural}`;
+}
+
+const MODE_FIELDS = {
+  momtest: { key: "momTestQuestions", fallback: [] },
+  wendel: { key: "wendelChecklist", fallback: [] },
+  classify: { key: "classification", fallback: null },
+  jtbd: { key: "jtbds", fallback: [] }
+};
+
+function buildSummary(parsed, mode) {
+  const gapCount = parsed.gaps?.length || 0;
+  const parts = [];
+  if (gapCount > 0) parts.push(`${pluralize(gapCount, "gap", "gaps")} found`);
+  if (mode === "momtest") {
+    const qCount = parsed.momTestQuestions?.length || 0;
+    if (qCount > 0) parts.push(`${pluralize(qCount, "Mom Test question", "Mom Test questions")}`);
+  }
+  if (mode === "wendel") {
+    const failCount = (parsed.wendelChecklist || []).filter(c => c.status === "fail").length;
+    if (failCount > 0) parts.push(`${pluralize(failCount, "Wendel condition", "Wendel conditions")} failed`);
+  }
+  if (mode === "classify" && parsed.classification) {
+    parts.push(`type: ${parsed.classification.type}, risk: ${parsed.classification.adoptionRisk}`);
+  }
+  if (mode === "jtbd") {
+    const jCount = parsed.jtbds?.length || 0;
+    if (jCount > 0) parts.push(`${pluralize(jCount, "JTBD", "JTBDs")} generated`);
+  }
+  if (parts.length === 0) return "Discovery complete: task is ready";
+  return `Discovery complete: ${parts.join(", ")} (verdict: ${parsed.verdict})`;
+}
+
+export class DiscoverRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "discover" });
+  }
+
+  async execute(input) {
+    const task = typeof input === "string" ? input : input?.task || this.context?.task || "";
+    const onOutput = typeof input === "string" ? null : input?.onOutput || null;
+    const mode = typeof input === "object" ? input?.mode || "gaps" : "gaps";
+    const context = typeof input === "object" ? input?.context || null : null;
+
+    const provider = this.resolveProvider();
+    const agent = this.createAgentInstance(provider);
+
+    const prompt = buildDiscoverPrompt({ task, instructions: this.instructions, mode, context });
+    const runArgs = { prompt, role: "discover" };
+    if (onOutput) runArgs.onOutput = onOutput;
+    const result = await agent.runTask(runArgs);
+
+    if (!result.ok) {
+      return {
+        ok: false,
+        result: { error: result.error || result.output || "Discovery failed", provider, mode },
+        summary: `Discovery failed: ${result.error || "unknown error"}`,
+        usage: result.usage
+      };
+    }
+
+    try {
+      const parsed = parseDiscoverOutput(result.output);
+      if (!parsed) {
+        return { ok: true, result: { verdict: "ready", gaps: [], mode, raw: result.output, provider }, summary: "Discovery complete (unstructured output)", usage: result.usage };
+      }
+
+      const resultObj = { verdict: parsed.verdict, gaps: parsed.gaps, mode, provider };
+      const fieldDef = MODE_FIELDS[mode];
+      if (fieldDef) resultObj[fieldDef.key] = parsed[fieldDef.key] ?? fieldDef.fallback;
+
+      return { ok: true, result: resultObj, summary: buildSummary(parsed, mode), usage: result.usage };
+    } catch {
+      return { ok: true, result: { verdict: "ready", gaps: [], mode, raw: result.output, provider }, summary: "Discovery complete (unstructured output)", usage: result.usage };
+    }
+  }
+}

package/src/roles/domain-curator-role.js

@@ -0,0 +1,141 @@
+/**
+ * Domain Curator role.
+ * Discovers, proposes and synthesizes domain knowledge for the pipeline.
+ * Operates deterministically (loader + registry + synthesizer) — no LLM call needed
+ * unless the user wants to generate domain knowledge from scratch.
+ */
+
+import { loadDomains } from "../domains/domain-loader.js";
+import { DomainRegistry } from "../domains/domain-registry.js";
+import { synthesizeDomainContext } from "../domains/domain-synthesizer.js";
+
+export class DomainCuratorRole {
+  constructor({ config, logger }) {
+    this.config = config;
+    this.logger = logger;
+  }
+
+  /**
+   * Execute domain curation.
+   * @param {Object} input
+   * @param {string} input.task — the task description
+   * @param {string[]} input.domainHints — keywords from triage
+   * @param {Function & {interactive: boolean}} [input.askQuestion] — interactive question function
+   * @param {string} [input.projectDir] — project root
+   * @returns {Promise<{ok: boolean, result: Object, summary: string}>}
+   */
+  async execute({ task, domainHints = [], askQuestion = null, projectDir = null }) {
+    // 1. Load domains from filesystem
+    const fileDomains = await loadDomains(projectDir);
+
+    // 2. Search registry for additional matches
+    let registryDomains = [];
+    if (domainHints.length > 0) {
+      try {
+        const registry = await DomainRegistry.load();
+        registryDomains = registry.search(domainHints);
+      } catch {
+        this.logger.warn("Domain Curator: failed to load registry, continuing with file domains only");
+      }
+    }
+
+    // 3. Deduplicate (file domains take precedence over registry entries)
+    const allDomains = deduplicateDomains(fileDomains, registryDomains);
+
+    // 4. No domains found
+    if (allDomains.length === 0) {
+      if (askQuestion?.interactive) {
+        const answer = await askQuestion({
+          message: "No domain knowledge found for this task.\nDo you have domain documents to provide, or should the pipeline continue without domain context?",
+          type: "confirm"
+        });
+        // For now, just log. Future: support document ingestion.
+        if (answer === true) {
+          this.logger.info("Domain Curator: user indicated domain documents available — future feature");
+        }
+      } else {
+        this.logger.warn("Domain Curator: no domain knowledge found, continuing without domain context");
+      }
+
+      return {
+        ok: true,
+        result: {
+          selectedDomains: [],
+          domainContext: null,
+          domainsFound: 0,
+          domainsUsed: 0,
+          source: "none"
+        },
+        summary: "Domain Curator: no domains found"
+      };
+    }
+
+    // 5. Propose selection to user (if interactive) or use all
+    let selectedDomains;
+
+    if (askQuestion?.interactive && allDomains.length > 1) {
+      const options = allDomains.map(d => ({
+        id: d.name,
+        label: `${d.name} (v${d.version || "?"}) — ${d.description || "no description"}`,
+        default: true
+      }));
+
+      const selected = await askQuestion({
+        message: `Found ${allDomains.length} domain knowledge package(s):`,
+        type: "multi-select",
+        options,
+        defaults: allDomains.map(d => d.name)
+      });
+
+      if (Array.isArray(selected) && selected.length > 0) {
+        const selectedSet = new Set(selected);
+        selectedDomains = allDomains.filter(d => selectedSet.has(d.name));
+      } else {
+        selectedDomains = allDomains; // fallback to all
+      }
+    } else {
+      // Single domain or non-interactive: use all
+      selectedDomains = allDomains;
+    }
+
+    // 6. Synthesize context
+    const domainContext = synthesizeDomainContext({
+      task,
+      domainHints,
+      selectedDomains
+    });
+
+    const source = selectedDomains.some(d => d.origin === "project") ? "project+user" : "user";
+
+    return {
+      ok: true,
+      result: {
+        selectedDomains: selectedDomains.map(d => d.name),
+        domainContext: domainContext || null,
+        domainsFound: allDomains.length,
+        domainsUsed: selectedDomains.length,
+        source
+      },
+      summary: `Domain Curator: ${selectedDomains.length}/${allDomains.length} domain(s) selected`
+    };
+  }
+}
+
+/**
+ * Deduplicate domains — file domains override registry entries by name.
+ */
+function deduplicateDomains(fileDomains, registryDomains) {
+  const byName = new Map();
+
+  // Registry entries first (lower priority)
+  for (const rd of registryDomains) {
+    if (rd.name) byName.set(rd.name, rd);
+  }
+
+  // File domains override
+  for (const fd of fileDomains) {
+    if (fd.name) byName.set(fd.name, fd);
+  }
+
+  return Array.from(byName.values());
+}

package/src/roles/hu-reviewer-role.js

@@ -0,0 +1,64 @@
+import { AgentRole } from "./agent-role.js";
+import { buildHuReviewerPrompt, parseHuReviewerOutput } from "../prompts/hu-reviewer.js";
+
+const EMPTY_BATCH = { total: 0, certified: 0, needs_rewrite: 0, needs_context: 0, consolidated_questions: "" };
+
+export class HuReviewerRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "hu-reviewer" });
+  }
+
+  resolveProvider() {
+    return (
+      this.config?.roles?.["hu-reviewer"]?.provider ||
+      this.config?.roles?.hu_reviewer?.provider ||
+      this.config?.roles?.coder?.provider ||
+      "claude"
+    );
+  }
+
+  extractInput(input) {
+    return {
+      stories: input?.stories || [],
+      context: input?.context || null,
+      onOutput: input?.onOutput || null
+    };
+  }
+
+  async buildPrompt({ stories, context }) {
+    const prompt = buildHuReviewerPrompt({
+      stories, instructions: this.instructions, context,
+      productContext: this.config?.productContext || null,
+      domainContext: this.config?.domainContext || null
+    });
+    return { prompt };
+  }
+
+  parseOutput(raw) { return parseHuReviewerOutput(raw); }
+
+  buildSuccessResult(parsed, provider) {
+    return { evaluations: parsed.evaluations, batch_summary: parsed.batch_summary, provider };
+  }
+
+  buildSummary(parsed) {
+    const bs = parsed.batch_summary;
+    const parts = [`${bs.total} HU(s) evaluated`];
+    if (bs.certified > 0) parts.push(`${bs.certified} certified`);
+    if (bs.needs_rewrite > 0) parts.push(`${bs.needs_rewrite} need rewrite`);
+    if (bs.needs_context > 0) parts.push(`${bs.needs_context} need context`);
+    return `HU Review complete: ${parts.join(", ")}`;
+  }
+
+  handleParseNull(agentResult, provider) {
+    return {
+      ok: true,
+      result: { evaluations: [], batch_summary: { ...EMPTY_BATCH }, raw: agentResult.output, provider },
+      summary: "HU Review complete (unstructured output)",
+      usage: agentResult.usage
+    };
+  }
+
+  handleParseError(_err, agentResult, provider) {
+    return this.handleParseNull(agentResult, provider);
+  }
+}