@thispointon/kondi-chat 0.1.2

package/src/engine/consultants.ts

@@ -0,0 +1,347 @@
+/**
+ * Consultants — domain-expert personas the agent can call on demand.
+ *
+ * A consultant is a triple of (model, system prompt, optional context
+ * strategy). The agent decides when to ask for help and passes a
+ * specific question; the consultant's response comes back through the
+ * normal tool-call channel. Because consultants are configured in a JSON
+ * file, users can add new experts without touching TypeScript.
+ *
+ * Consultants are deliberately stateless and pure text-in/text-out — they
+ * do NOT have access to the main agent's tool set, memory, or session.
+ * If you need a consultant that can read files or run commands, spawn a
+ * sub-agent via `spawn_agent` instead; that path is heavier but fully
+ * agentic. Consultants are for opinion, not for execution.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import type { ProviderId } from '../types.ts';
+import type { Ledger } from '../audit/ledger.ts';
+import { callLLM } from '../providers/llm-caller.ts';
+import type { ToolExecutionResult } from './tools.ts';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface Consultant {
+  /** Short machine identifier used in the `consult` tool call. */
+  role: string;
+  /** Human-readable name shown in listings. */
+  name: string;
+  /**
+   * One-line description of when the agent should consult this expert.
+   * Surfaced to the agent so it can decide whether a given problem warrants
+   * this particular perspective.
+   */
+  description: string;
+  /** Provider + model that runs this persona. */
+  provider: ProviderId;
+  model: string;
+  /**
+   * The full system prompt that defines the persona. This is where the
+   * expertise actually lives — the choice of model is secondary to a
+   * well-written system prompt describing priorities, vocabulary, and
+   * what to flag.
+   */
+  system: string;
+  /** Soft cap on output tokens for this consultant. Default 2048. */
+  maxOutputTokens?: number;
+  /**
+   * Static text that should be included in this consultant's context on
+   * every call. Good for: project-specific constraints the consultant
+   * should always know ("target DO-178C DAL-B", "monorepo of 40k LOC
+   * TypeScript", etc.), vocabulary, stable decisions. Appended to the
+   * system prompt so it benefits from provider-side prompt caching.
+   */
+  contextText?: string;
+  /**
+   * Files to read from the working directory on every consultation and
+   * inject as context. Paths are relative to the working dir. Each file
+   * is capped at `contextFileMaxBytes` (default 50 KB) to prevent a
+   * stray large file from blowing the prompt budget; the total load is
+   * capped at `contextTotalMaxBytes` (default 200 KB).
+   *
+   * Use for slow-changing reference material like specs, design docs,
+   * or the README. Do NOT use for active source files the agent is
+   * editing — that path belongs in the per-call `context` argument so
+   * the consultant sees the current state, not a stale snapshot.
+   */
+  contextFiles?: string[];
+  /** Per-file byte cap (default 50_000). */
+  contextFileMaxBytes?: number;
+  /** Total context byte cap across all contextFiles (default 200_000). */
+  contextTotalMaxBytes?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Default roster — created on first run so the file exists to edit
+// ---------------------------------------------------------------------------
+
+const DEFAULT_CONSULTANTS: Consultant[] = [
+  {
+    role: 'aerospace-engineer',
+    name: 'Senior Aerospace Engineer',
+    description:
+      'Review designs and implementations for flight-safety, fault tolerance, margins, ' +
+      'redundancy, and certification implications. Use for avionics, flight control, ' +
+      'propulsion, actuation, or any safety-critical embedded code.',
+    provider: 'openai',
+    model: 'gpt-5.4',
+    system:
+      'You are a senior aerospace engineer with 30 years of experience across avionics, ' +
+      'flight control software, propulsion control, and safety-critical embedded systems. ' +
+      'When reviewing a design or implementation, think explicitly about: failure modes ' +
+      '(FMEA), single points of failure, margins (timing, current, thermal, structural), ' +
+      'redundancy and voting, fault containment, fail-operational vs fail-safe behavior, ' +
+      'flight envelope, bus loading and real-time scheduling, certification implications ' +
+      '(DO-178C DAL, DO-254), and what the pilot sees when it breaks. Be blunt about risks. ' +
+      'If the question is outside your domain, say so explicitly rather than guess. ' +
+      'Output: numbered concerns in priority order, each with severity (LOW/MED/HIGH/BLOCKING) ' +
+      'and a concrete mitigation.',
+    maxOutputTokens: 2048,
+    // Example of persistent context — commented out because these paths
+    // likely don't exist in your project. Edit consultants.json to point
+    // at real spec files once you have them:
+    //
+    //   "contextText": "Target platform: ARM Cortex-R52 triple-core lockstep. DO-178C DAL-B.",
+    //   "contextFiles": ["specs/fmea.md", "specs/safety-case.md"]
+  },
+  {
+    role: 'security-auditor',
+    name: 'Application Security Auditor',
+    description:
+      'Review code for security vulnerabilities: OWASP top-10, authn/authz, input validation, ' +
+      'secrets handling, injection, SSRF, crypto misuse, race conditions, supply-chain risks. ' +
+      'Use when touching auth flows, user input, cryptography, file I/O, or network requests.',
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-5-20250929',
+    system:
+      'You are an application security auditor with a red-team background. Review the ' +
+      'supplied code or design against: OWASP top-10, authentication and authorization ' +
+      'flows, input validation and parser differentials, injection (SQL, command, path, ' +
+      'template), SSRF and DNS rebinding, cryptography misuse and weak randomness, secrets ' +
+      'handling, TOCTOU and race conditions, deserialization risks, dependency/supply-chain ' +
+      'integrity, and denial-of-service surface. Be specific about exploit scenarios. ' +
+      'Output: numbered findings in severity order (INFO/LOW/MED/HIGH/CRITICAL), each with ' +
+      'a one-line attack description and a concrete remediation.',
+    maxOutputTokens: 2048,
+  },
+  {
+    role: 'database-architect',
+    name: 'Database Architect',
+    description:
+      'Review schemas, queries, migrations, and data access patterns. Use for questions ' +
+      'about indexes, transaction isolation, migration safety on large tables, query plans, ' +
+      'normalization trade-offs, partitioning, or OLTP-vs-OLAP boundaries.',
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-5-20250929',
+    system:
+      'You are a database architect fluent in Postgres, MySQL, SQLite, and general RDBMS ' +
+      'theory. When reviewing a schema, query, or migration, think about: index coverage, ' +
+      'query plan stability, lock scope and duration, isolation levels and phantom reads, ' +
+      'migration safety on large tables (NOT NULL backfills, column drops, type changes), ' +
+      'transaction semantics, normalization vs denormalization trade-offs, JSON/JSONB usage, ' +
+      'partitioning, read-replica consistency, and OLTP/OLAP mixing. Point out anti-patterns ' +
+      'directly. Output: numbered concerns by severity, each with a concrete fix.',
+    maxOutputTokens: 2048,
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Loader
+// ---------------------------------------------------------------------------
+
+/**
+ * Load consultants from `<storageDir>/consultants.json`. If the file
+ * doesn't exist, seed it with the default roster so users have a
+ * starting point to edit.
+ */
+export function loadConsultants(storageDir: string): Consultant[] {
+  const path = join(storageDir, 'consultants.json');
+  if (!existsSync(path)) {
+    try {
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, JSON.stringify(DEFAULT_CONSULTANTS, null, 2));
+    } catch {
+      /* non-fatal — fall back to in-memory defaults */
+    }
+    return [...DEFAULT_CONSULTANTS];
+  }
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf-8'));
+    if (!Array.isArray(raw)) return [...DEFAULT_CONSULTANTS];
+    return raw.filter(
+      (c): c is Consultant =>
+        typeof c?.role === 'string' &&
+        typeof c?.name === 'string' &&
+        typeof c?.provider === 'string' &&
+        typeof c?.model === 'string' &&
+        typeof c?.system === 'string',
+    );
+  } catch {
+    return [...DEFAULT_CONSULTANTS];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Execution
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the `consult` tool. Three behaviors based on `args`:
+ *
+ *   1. No `role` provided → return a roster listing so the agent can
+ *      decide who to ask next. Pure discovery call, cheap.
+ *   2. Unknown `role` → return an error listing the valid roles.
+ *   3. Valid `role` + `question` → invoke the consultant's LLM with the
+ *      system prompt from the JSON, return the response as tool content.
+ *
+ * Consultation is logged to the ledger as `phase: 'consult'` with the
+ * consultant's role in the promptSummary so `/routing` and `/cost` can
+ * attribute the spend.
+ */
+export async function executeConsult(
+  args: Record<string, unknown>,
+  consultants: Consultant[],
+  ledger: Ledger,
+  workingDir: string,
+): Promise<ToolExecutionResult> {
+  const role = typeof args.role === 'string' ? args.role.trim() : '';
+  const question = typeof args.question === 'string' ? args.question : '';
+  const callerContext = typeof args.context === 'string' ? args.context : '';
+
+  if (!role) {
+    return { content: formatRoster(consultants) };
+  }
+
+  const consultant = consultants.find(c => c.role === role);
+  if (!consultant) {
+    return {
+      content:
+        `Unknown consultant role: ${role}\n\n` +
+        `Available roles:\n${consultants.map(c => `  - ${c.role} — ${c.description}`).join('\n')}`,
+      isError: true,
+    };
+  }
+
+  if (!question) {
+    return {
+      content: `consult requires a "question" when a role is specified. You asked for ${consultant.name} but didn't pass a question.`,
+      isError: true,
+    };
+  }
+
+  // Assemble the persistent context block (contextText + contextFiles).
+  // Failures loading a file are reported inline so the consultant — and
+  // the orchestrating agent — can see that a reference is missing, but
+  // they do not abort the call.
+  const persistent = assemblePersistentContext(consultant, workingDir);
+  const systemPrompt = persistent
+    ? `${consultant.system}\n\n--- Project reference (persistent) ---\n${persistent}`
+    : consultant.system;
+
+  const userMessage = callerContext
+    ? `${question}\n\n--- Context from caller ---\n${callerContext}`
+    : question;
+
+  try {
+    const response = await callLLM({
+      provider: consultant.provider,
+      model: consultant.model,
+      systemPrompt,
+      userMessage,
+      maxOutputTokens: consultant.maxOutputTokens ?? 2048,
+      temperature: 0.2,
+    });
+    ledger.record(
+      'consult',
+      response,
+      `consult ${consultant.role}: ${question.slice(0, 160)}`,
+    );
+    return {
+      content:
+        `[${consultant.name} · ${response.model}]\n\n${response.content || '(no response)'}`,
+    };
+  } catch (error) {
+    return {
+      content: `Consultation with ${consultant.role} failed: ${(error as Error).message}`,
+      isError: true,
+    };
+  }
+}
+
+/**
+ * Build the persistent-context block from `contextText` + `contextFiles`.
+ * Files are resolved against `workingDir`, byte-capped per file and in
+ * total, and path-escape-protected so a consultant config can't read
+ * arbitrary paths outside the project by setting `"../../etc/passwd"`.
+ */
+function assemblePersistentContext(consultant: Consultant, workingDir: string): string {
+  const perFileCap = consultant.contextFileMaxBytes ?? 50_000;
+  const totalCap = consultant.contextTotalMaxBytes ?? 200_000;
+
+  const parts: string[] = [];
+  if (consultant.contextText && consultant.contextText.trim().length > 0) {
+    parts.push(consultant.contextText.trim());
+  }
+
+  if (consultant.contextFiles && consultant.contextFiles.length > 0) {
+    const base = resolve(workingDir);
+    let remaining = totalCap;
+    for (const relOrAbs of consultant.contextFiles) {
+      if (remaining <= 0) {
+        parts.push(`[context file skipped — total cap ${totalCap} bytes reached]`);
+        break;
+      }
+      const abs = isAbsolute(relOrAbs) ? resolve(relOrAbs) : resolve(base, relOrAbs);
+      if (!abs.startsWith(base)) {
+        parts.push(`[context file rejected — outside working dir: ${relOrAbs}]`);
+        continue;
+      }
+      try {
+        const stat = statSync(abs);
+        if (!stat.isFile()) {
+          parts.push(`[context file not a regular file: ${relOrAbs}]`);
+          continue;
+        }
+        const cap = Math.min(perFileCap, remaining);
+        const raw = readFileSync(abs, 'utf-8');
+        const clipped = raw.length > cap
+          ? raw.slice(0, cap) + `\n[...truncated from ${raw.length} to ${cap} bytes]`
+          : raw;
+        remaining -= clipped.length;
+        parts.push(`# ${relOrAbs}\n${clipped}`);
+      } catch (e) {
+        parts.push(`[context file load failed: ${relOrAbs} — ${(e as Error).message}]`);
+      }
+    }
+  }
+
+  return parts.join('\n\n');
+}
+
+function formatRoster(consultants: Consultant[]): string {
+  if (consultants.length === 0) {
+    return 'No consultants configured. Edit .kondi-chat/consultants.json to add some.';
+  }
+  const lines: string[] = ['Available consultants:', ''];
+  for (const c of consultants) {
+    lines.push(`  ${c.role}`);
+    lines.push(`    ${c.name} (${c.provider}/${c.model})`);
+    lines.push(`    ${c.description}`);
+    if (c.contextText) {
+      const preview = c.contextText.trim().replace(/\s+/g, ' ');
+      lines.push(`    baseline: ${preview.length > 120 ? preview.slice(0, 117) + '…' : preview}`);
+    }
+    if (c.contextFiles && c.contextFiles.length > 0) {
+      lines.push(`    attached files: ${c.contextFiles.join(', ')}`);
+    }
+    lines.push('');
+  }
+  lines.push(
+    'Call consult({role: "<role>", question: "<your question>", context?: "<optional file or design snippet>"}) to ask one.',
+  );
+  return lines.join('\n');
+}

package/src/engine/diff.ts

@@ -0,0 +1,171 @@
+/**
+ * Unified diff computation for file edits.
+ *
+ * Self-contained line-level LCS. Used by write_file / edit_file tools
+ * (Spec 03) and git_diff tool (Spec 02) — the latter imports from here.
+ */
+
+const CONTEXT_LINES = 3;
+const MAX_LINES = 200;
+const MAX_BYTES = 200 * 1024;
+const MAX_SOURCE_LINES = 5000;
+
+export interface DiffResult {
+  /** Unified diff string with ---/+++ headers, or '' if empty/binary/too-large. */
+  diff: string;
+  linesAdded: number;
+  linesRemoved: number;
+  /** True if output was capped at MAX_LINES. */
+  truncated: boolean;
+  /** True if input was skipped (too large or binary). */
+  skipped?: 'file-too-large' | 'binary' | 'empty';
+}
+
+function isBinary(s: string): boolean {
+  // Fast heuristic: NUL byte in first 8KiB
+  const limit = Math.min(s.length, 8192);
+  for (let i = 0; i < limit; i++) {
+    if (s.charCodeAt(i) === 0) return true;
+  }
+  return false;
+}
+
+/** Compute LCS-based line diff and emit unified-diff hunks. */
+export function computeUnifiedDiff(
+  filePath: string,
+  oldContent: string,
+  newContent: string,
+): DiffResult {
+  if (oldContent === newContent) {
+    return { diff: '', linesAdded: 0, linesRemoved: 0, truncated: false, skipped: 'empty' };
+  }
+  if (
+    oldContent.length > MAX_BYTES ||
+    newContent.length > MAX_BYTES ||
+    isBinary(oldContent) ||
+    isBinary(newContent)
+  ) {
+    const skipped = isBinary(oldContent) || isBinary(newContent) ? 'binary' : 'file-too-large';
+    return { diff: '', linesAdded: 0, linesRemoved: 0, truncated: true, skipped };
+  }
+
+  const a = oldContent === '' ? [] : oldContent.split('\n');
+  const b = newContent === '' ? [] : newContent.split('\n');
+  if (a.length > MAX_SOURCE_LINES || b.length > MAX_SOURCE_LINES) {
+    return { diff: '', linesAdded: 0, linesRemoved: 0, truncated: true, skipped: 'file-too-large' };
+  }
+
+  const ops = diffLines(a, b);
+  const hunks = buildHunks(a, b, ops, CONTEXT_LINES);
+
+  let linesAdded = 0;
+  let linesRemoved = 0;
+  const out: string[] = [];
+  out.push(`--- ${oldContent === '' ? '/dev/null' : `a/${filePath}`}`);
+  out.push(`+++ ${newContent === '' ? '/dev/null' : `b/${filePath}`}`);
+
+  let truncated = false;
+  for (const h of hunks) {
+    out.push(`@@ -${h.oldStart},${h.oldLen} +${h.newStart},${h.newLen} @@`);
+    for (const line of h.lines) {
+      if (line[0] === '+') linesAdded++;
+      else if (line[0] === '-') linesRemoved++;
+      if (out.length >= MAX_LINES + 2) { truncated = true; break; }
+      out.push(line);
+    }
+    if (truncated) break;
+  }
+  if (truncated) out.push(`... (diff truncated at ${MAX_LINES} lines)`);
+
+  return { diff: out.join('\n'), linesAdded, linesRemoved, truncated };
+}
+
+// ── LCS line diff ─────────────────────────────────────────────────────
+
+type Op = { kind: 'eq' | 'del' | 'add'; aIdx: number; bIdx: number };
+
+function diffLines(a: string[], b: string[]): Op[] {
+  const n = a.length, m = b.length;
+  // DP table of LCS lengths
+  const dp: Uint32Array[] = [];
+  for (let i = 0; i <= n; i++) dp.push(new Uint32Array(m + 1));
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+    }
+  }
+  const ops: Op[] = [];
+  let i = 0, j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) { ops.push({ kind: 'eq', aIdx: i, bIdx: j }); i++; j++; }
+    else if (dp[i + 1][j] >= dp[i][j + 1]) { ops.push({ kind: 'del', aIdx: i, bIdx: j }); i++; }
+    else { ops.push({ kind: 'add', aIdx: i, bIdx: j }); j++; }
+  }
+  while (i < n) { ops.push({ kind: 'del', aIdx: i, bIdx: j }); i++; }
+  while (j < m) { ops.push({ kind: 'add', aIdx: i, bIdx: j }); j++; }
+  return ops;
+}
+
+interface Hunk {
+  oldStart: number; oldLen: number;
+  newStart: number; newLen: number;
+  lines: string[];
+}
+
+function buildHunks(a: string[], b: string[], ops: Op[], context: number): Hunk[] {
+  // Find change regions and expand with context.
+  const hunks: Hunk[] = [];
+  let i = 0;
+  while (i < ops.length) {
+    if (ops[i].kind === 'eq') { i++; continue; }
+    // Start of a change — walk back for leading context.
+    let start = i;
+    let ctxBefore = 0;
+    while (start > 0 && ops[start - 1].kind === 'eq' && ctxBefore < context) {
+      start--; ctxBefore++;
+    }
+    // Walk forward through changes, allowing up to 2*context eq lines to merge adjacent hunks.
+    let end = i;
+    while (end < ops.length) {
+      if (ops[end].kind !== 'eq') { end++; continue; }
+      // Count eq run
+      let runEnd = end;
+      while (runEnd < ops.length && ops[runEnd].kind === 'eq') runEnd++;
+      const runLen = runEnd - end;
+      const isTail = runEnd === ops.length;
+      if (isTail || runLen > 2 * context) {
+        // Keep up to `context` trailing eq lines.
+        end = Math.min(end + context, runEnd);
+        break;
+      }
+      end = runEnd;
+    }
+
+    const lines: string[] = [];
+    const firstOp = ops[start];
+    const oldStartIdx = firstOp.aIdx;
+    const newStartIdx = firstOp.bIdx;
+    let oldLen = 0, newLen = 0;
+    for (let k = start; k < end; k++) {
+      const op = ops[k];
+      if (op.kind === 'eq') {
+        lines.push(' ' + a[op.aIdx]); oldLen++; newLen++;
+      } else if (op.kind === 'del') {
+        lines.push('-' + a[op.aIdx]); oldLen++;
+      } else {
+        lines.push('+' + b[op.bIdx]); newLen++;
+      }
+    }
+    // Unified diff: 1-based line numbers; if len==0 the "start" is the line BEFORE which
+    // content is added/removed, i.e. the 0-based index itself.
+    hunks.push({
+      oldStart: oldLen === 0 ? oldStartIdx : oldStartIdx + 1,
+      oldLen,
+      newStart: newLen === 0 ? newStartIdx : newStartIdx + 1,
+      newLen,
+      lines,
+    });
+    i = end;
+  }
+  return hunks;
+}

package/src/engine/errors.ts

@@ -0,0 +1,102 @@
+/**
+ * Structured error hierarchy for the agent engine.
+ *
+ * All domain-specific failure modes should inherit from `KondiError`
+ * rather than throw bare `Error` instances, so the backend and TUI can
+ * make informed decisions about how to surface a failure to the user
+ * (retry vs. give up vs. abort the turn).
+ *
+ * Design principles:
+ *   - Every error carries a `severity` so callers can distinguish
+ *     recoverable ("retry with different args") from fatal ("the
+ *     pipeline cannot continue").
+ *   - Every error carries a `stage` string so log messages and ledger
+ *     entries can attribute the failure to the specific step that broke.
+ *   - Errors are plain `Error` subclasses so they work with existing
+ *     stack-trace tooling and Node's `instanceof` checks.
+ *
+ * This file is deliberately tiny — the goal is to stop swallowing errors
+ * at the pipeline layer, not to refactor every throw site in the
+ * codebase in one pass.
+ */
+
+/** Coarse severity ladder for structured failures. */
+export type ErrorSeverity =
+  | 'info'          // informational — the caller can ignore this
+  | 'warning'       // worth logging but not worth aborting for
+  | 'recoverable'   // retry with different args may succeed
+  | 'fatal';        // the enclosing operation cannot continue
+
+/**
+ * Base class for every structured engine error. Plain Errors are still
+ * valid throws — they just get treated as 'fatal' when a PipelineError
+ * isn't thrown.
+ */
+export class KondiError extends Error {
+  readonly severity: ErrorSeverity;
+  readonly stage: string;
+  readonly cause?: unknown;
+
+  constructor(message: string, opts: { severity: ErrorSeverity; stage: string; cause?: unknown }) {
+    super(message);
+    this.name = this.constructor.name;
+    this.severity = opts.severity;
+    this.stage = opts.stage;
+    this.cause = opts.cause;
+  }
+}
+
+/**
+ * Thrown from within `runPipeline` when a stage cannot complete. Carries
+ * the stage name (`dispatch`/`execute`/`apply`/`verify`/`reflect`) so
+ * downstream error handlers can surface a meaningful location.
+ */
+export class PipelineError extends KondiError {
+  constructor(
+    message: string,
+    opts: { severity: ErrorSeverity; stage: 'dispatch' | 'execute' | 'apply' | 'verify' | 'reflect'; cause?: unknown },
+  ) {
+    super(message, opts);
+  }
+}
+
+/**
+ * Thrown from tool executors on structured tool failures (not every
+ * tool error — routine "file not found" still returns `{ isError: true }`).
+ * Reserved for failures that should surface as errors rather than as
+ * tool-result content the model can read and react to.
+ */
+export class ToolError extends KondiError {
+  readonly toolName: string;
+  constructor(message: string, opts: { severity: ErrorSeverity; toolName: string; cause?: unknown }) {
+    super(message, { severity: opts.severity, stage: `tool:${opts.toolName}`, cause: opts.cause });
+    this.toolName = opts.toolName;
+  }
+}
+
+/** Thrown by LLM provider calls when the request fails definitively. */
+export class LlmCallError extends KondiError {
+  readonly provider: string;
+  readonly model: string;
+  readonly status?: number;
+  constructor(
+    message: string,
+    opts: { severity: ErrorSeverity; provider: string; model: string; status?: number; cause?: unknown },
+  ) {
+    super(message, { severity: opts.severity, stage: `llm:${opts.provider}/${opts.model}`, cause: opts.cause });
+    this.provider = opts.provider;
+    this.model = opts.model;
+    this.status = opts.status;
+  }
+}
+
+/**
+ * Helper: turn an unknown thrown value into a KondiError. Use when
+ * wrapping code that may throw bare Errors — the result is always a
+ * KondiError subclass so downstream `instanceof` checks are reliable.
+ */
+export function asKondiError(e: unknown, fallbackStage: string): KondiError {
+  if (e instanceof KondiError) return e;
+  const message = e instanceof Error ? e.message : String(e);
+  return new KondiError(message, { severity: 'fatal', stage: fallbackStage, cause: e });
+}