onto-mcp 0.3.0

package/dist/core-runtime/learning/shared/llm-caller.js

@@ -0,0 +1,831 @@
+/**
+ * Background task (learn/govern/promote) LLM call wrapper.
+ *
+ * Canonical provider resolution:
+ *   1. Caller-explicit: callLlm(..., { provider }) — one provider only.
+ *   2. `llm.auth=oauth + llm.provider=openai` — Codex worker.
+ *   3. `llm.auth=api_key` — OpenAI / Anthropic / Grok API key from env.
+ *   4. `llm.auth=local + llm.provider=lmstudio` — local OpenAI-style endpoint.
+ *
+ *   Priority 0 (special): ONTO_LLM_MOCK=1 → in-process mock (test only)
+ *
+ * Mock provider:
+ *   When ONTO_LLM_MOCK=1 is set, callLlm() routes to an in-process mock that
+ *   pattern-matches the system prompt against known Phase 3 prompts (panel
+ *   review, judgment audit, insight reclassify, domain doc) and returns
+ *   deterministic JSON. This unblocks E2E tests that need to exercise the
+ *   full LLM call path without real API credentials. NEVER ship with this
+ *   env var set in production — there's no real reasoning happening.
+ *
+ * Runtime config must reach this module through the canonical `llm` switcher
+ * or an explicit call-site override. Missing provider/model/credentials fail
+ * immediately.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { loadCoreLensRegistry } from "../../discovery/lens-registry.js";
+import { DEFAULT_GROK_BASE_URL, DEFAULT_LMSTUDIO_BASE_URL, normalizeLlmModelSwitcher, } from "../../llm/model-switcher.js";
+/**
+ * Bridge: OntoConfig + CLI overrides → Partial<LlmCallConfig> that callLlm consumes.
+ *
+ * Callers (learning/promote panel-reviewer, promote-executor, judgment-auditor,
+ * insight-reclassifier, extractor, semantic-classifier) should:
+ *
+ *   const partial = resolveLearningProviderConfig({ config: ontoConfig, cliOverrides });
+ *   const result = await callLlm(system, user, { ...partial, max_tokens: 2048 });
+ *
+ * This replaces the pattern of callers building Partial<LlmCallConfig> ad-hoc, and is
+ * the canonical seat where OntoConfig translates to provider resolution input.
+ *
+ */
+export function resolveLearningProviderConfig(args) {
+    const config = args.config ?? {};
+    const cli = args.cliOverrides ?? {};
+    const selection = normalizeLlmModelSwitcher(config.llm);
+    const provider = cli.provider ?? selection?.provider;
+    const model_id = cli.model ?? selection?.model_id;
+    const envBaseUrl = provider === "grok"
+        ? process.env.GROK_BASE_URL ?? process.env.XAI_BASE_URL
+        : provider === "lmstudio"
+            ? process.env.LMSTUDIO_BASE_URL
+            : undefined;
+    const base_url = cli.base_url ?? envBaseUrl ?? selection?.base_url;
+    const reasoning_effort = cli.reasoning_effort ?? selection?.reasoning_effort;
+    const service_tier = selection?.provider === "codex" ? selection.service_tier : undefined;
+    const api_key_env = selection?.api_key_env;
+    const models_per_provider = {};
+    if (provider && model_id)
+        models_per_provider[provider] = model_id;
+    const out = {};
+    if (provider)
+        out.provider = provider;
+    if (model_id)
+        out.model_id = model_id;
+    if (base_url)
+        out.base_url = base_url;
+    if (reasoning_effort)
+        out.reasoning_effort = reasoning_effort;
+    if (service_tier)
+        out.service_tier = service_tier;
+    if (api_key_env)
+        out.api_key_env = api_key_env;
+    if (Object.keys(models_per_provider).length > 0) {
+        out.models_per_provider = models_per_provider;
+    }
+    return out;
+}
+// Phase 3 production found 30s too tight for large audit batches (37 items
+// could time out then SDK-retry for 90s total). 120s is generous
+// enough for ~50-item single-batch audits while still failing fast on real
+// network problems.
+const DEFAULT_TIMEOUT_MS = Number(process.env.ONTO_LLM_TIMEOUT_MS) || 120_000;
+// SDK auto-retry hides failures behind a long stall. We surface failures
+// faster (1 retry instead of the default 2) so operators see provider errors
+// within ~2× timeout instead of ~3×.
+const DEFAULT_MAX_RETRIES = 1;
+/**
+ * Model-call observability — emits STDERR logs for each LLM API call, covering
+ * (a) pre-call model_id + provider + max_tokens, (b) post-call usage on success,
+ * (c) full SDK error fields (status / error.type / error.message / request_id)
+ * on failure. Silent "Connection error." wrapping by review runner no longer
+ * hides model-not-found / auth / quota / network distinctions.
+ */
+function emitModelCallLog(line) {
+    process.stderr.write(`[model-call] ${line}\n`);
+}
+function readCodexAuthState() {
+    const codexAuthPath = path.join(os.homedir(), ".codex", "auth.json");
+    if (!fs.existsSync(codexAuthPath)) {
+        return { chatgptOAuth: false, openaiApiKey: null };
+    }
+    try {
+        const auth = JSON.parse(fs.readFileSync(codexAuthPath, "utf8"));
+        const oauth = auth.auth_mode === "chatgpt" ||
+            (auth.tokens && typeof auth.tokens.access_token === "string");
+        const openaiKey = typeof auth.OPENAI_API_KEY === "string" && auth.OPENAI_API_KEY.length > 0
+            ? auth.OPENAI_API_KEY
+            : null;
+        return { chatgptOAuth: Boolean(oauth), openaiApiKey: openaiKey };
+    }
+    catch {
+        return { chatgptOAuth: false, openaiApiKey: null };
+    }
+}
+function readEnvApiKey(envNames) {
+    for (const envName of envNames) {
+        const value = process.env[envName];
+        if (typeof value === "string" && value.length > 0)
+            return value;
+    }
+    return null;
+}
+function resolveProvider(preferred, configBaseUrl, apiKeyEnv) {
+    if (preferred === undefined) {
+        throw new Error(missingProviderSelectionError());
+    }
+    if (preferred === "anthropic") {
+        const apiKey = readEnvApiKey(apiKeyEnv ? [apiKeyEnv] : ["ANTHROPIC_API_KEY"]);
+        if (apiKey) {
+            return { provider: "anthropic", apiKey };
+        }
+        throw new Error(explicitProviderMissingCredentialError("anthropic"));
+    }
+    if (preferred === "openai") {
+        const envKey = readEnvApiKey(apiKeyEnv ? [apiKeyEnv] : ["OPENAI_API_KEY"]);
+        if (envKey) {
+            return { provider: "openai", apiKey: envKey };
+        }
+        const codexAuth = readCodexAuthState();
+        if (codexAuth.openaiApiKey) {
+            return { provider: "openai", apiKey: codexAuth.openaiApiKey };
+        }
+        throw new Error(explicitProviderMissingCredentialError("openai"));
+    }
+    if (preferred === "grok") {
+        const apiKey = readEnvApiKey(apiKeyEnv ? [apiKeyEnv] : ["XAI_API_KEY", "GROK_API_KEY"]);
+        if (apiKey) {
+            return {
+                provider: "grok",
+                apiKey,
+                baseUrl: configBaseUrl ?? DEFAULT_GROK_BASE_URL,
+            };
+        }
+        throw new Error(explicitProviderMissingCredentialError("grok"));
+    }
+    if (preferred === "lmstudio") {
+        return {
+            provider: "lmstudio",
+            apiKey: "lmstudio-local",
+            baseUrl: configBaseUrl ?? process.env.LMSTUDIO_BASE_URL ?? DEFAULT_LMSTUDIO_BASE_URL,
+        };
+    }
+    return {
+        provider: "codex",
+        apiKey: "codex-oauth",
+    };
+}
+function explicitProviderMissingCredentialError(provider) {
+    const envVar = provider === "anthropic"
+        ? "ANTHROPIC_API_KEY"
+        : provider === "openai"
+            ? "OPENAI_API_KEY"
+            : "XAI_API_KEY or GROK_API_KEY";
+    return [
+        `llm.provider=${provider} 명시적으로 선택되었으나 ${envVar}가 환경변수에 없습니다.`,
+        ...(provider === "openai"
+            ? ["(~/.codex/auth.json의 OPENAI_API_KEY 필드도 비어 있거나 없음)"]
+            : []),
+        `명시적 provider override를 사용하려면 ${envVar}를 export하세요.`,
+        "또는 .onto/settings.json 의 llm block 을 현재 credential에 맞게 수정하세요.",
+    ].join("\n");
+}
+function missingProviderSelectionError() {
+    return [
+        "LLM provider가 지정되지 않았습니다.",
+        "`.onto/settings.json`에 `llm` 블록을 추가하거나 호출부에서 provider를 명시하세요:",
+        "  llm:",
+        "    auth: oauth | api_key | local",
+        "    provider: openai | anthropic | grok | lmstudio",
+        "    model: <model-id>",
+    ].join("\n");
+}
+/**
+ * Construct a fail-fast error for api-key providers when no model is specified.
+ * Used by anthropic / openai / grok / lmstudio dispatch branches. codex is exempt because
+ * the codex CLI picks its own default when `-m` is omitted.
+ *
+ * Hardcoded DEFAULT_ANTHROPIC_MODEL / DEFAULT_OPENAI_MODEL constants were removed
+ * from this module (2026-04-15): model choice is a user decision (cost / quality /
+ * account constraints) and should not be hardcoded in library code where it can
+ * go stale or mismatch account permissions.
+ */
+function missingModelError(provider) {
+    const providerField = provider;
+    return new Error([
+        `provider=${provider} 경로는 model 지정이 필요합니다. 하드코딩된 기본 모델은 제거되었습니다.`,
+        "다음 중 한 가지로 설정하세요:",
+        "  1. .onto/settings.json 의 `llm.model: <model-id>`",
+        "  3. 호출부에서 LlmCallConfig.model_id 인자 전달 (런타임 override)",
+        "(codex provider는 model 미지정 시 codex CLI가 자체 기본값을 사용하므로 이 메시지의 대상이 아닙니다.)",
+    ].join("\n"));
+}
+// ---------------------------------------------------------------------------
+// Anthropic call
+// ---------------------------------------------------------------------------
+async function callAnthropic(systemPrompt, userPrompt, apiKey, modelId, maxTokens) {
+    const { default: Anthropic } = await import("@anthropic-ai/sdk");
+    const client = new Anthropic({
+        apiKey,
+        timeout: DEFAULT_TIMEOUT_MS,
+        maxRetries: DEFAULT_MAX_RETRIES,
+    });
+    emitModelCallLog(`anthropic call: model="${modelId}" max_tokens=${maxTokens}`);
+    let response;
+    try {
+        response = await client.messages.create({
+            model: modelId,
+            max_tokens: maxTokens,
+            system: systemPrompt,
+            messages: [{ role: "user", content: userPrompt }],
+        });
+    }
+    catch (err) {
+        const e = err;
+        emitModelCallLog(`anthropic call FAILED: model="${modelId}" status=${e.status ?? "?"} type=${e.error?.type ?? e.name ?? "?"} message="${e.error?.message ?? e.message ?? String(err)}" request_id=${e.request_id ?? "?"}`);
+        throw err;
+    }
+    emitModelCallLog(`anthropic success: model_id=${response.model ?? modelId} input_tokens=${response.usage.input_tokens} output_tokens=${response.usage.output_tokens}`);
+    const text = response.content
+        .filter((block) => block.type === "text")
+        .map((block) => ("text" in block ? block.text : ""))
+        .join("\n");
+    return {
+        text,
+        input_tokens: response.usage.input_tokens,
+        output_tokens: response.usage.output_tokens,
+        model_id: modelId,
+        effective_base_url: "https://api.anthropic.com",
+        declared_billing_mode: "per_token",
+    };
+}
+// ---------------------------------------------------------------------------
+// OpenAI call
+// ---------------------------------------------------------------------------
+async function callOpenAI(systemPrompt, userPrompt, apiKey, modelId, maxTokens, baseUrl, providerLabel = "openai") {
+    const { default: OpenAI } = await import("openai");
+    const client = new OpenAI({
+        apiKey,
+        baseURL: baseUrl,
+        timeout: DEFAULT_TIMEOUT_MS,
+        maxRetries: DEFAULT_MAX_RETRIES,
+    });
+    emitModelCallLog(`${providerLabel} call: model="${modelId}" max_tokens=${maxTokens}${baseUrl ? ` base_url=${baseUrl}` : ""}`);
+    let response;
+    try {
+        response = await client.chat.completions.create({
+            model: modelId,
+            max_tokens: maxTokens,
+            messages: [
+                { role: "system", content: systemPrompt },
+                { role: "user", content: userPrompt },
+            ],
+        });
+    }
+    catch (err) {
+        const e = err;
+        emitModelCallLog(`${providerLabel} call FAILED: model="${modelId}" status=${e.status ?? "?"} type=${e.error?.type ?? e.name ?? "?"} message="${e.error?.message ?? e.message ?? String(err)}" request_id=${e.request_id ?? "?"}`);
+        throw err;
+    }
+    emitModelCallLog(`${providerLabel} success: model_id=${response.model ?? modelId} input_tokens=${response.usage?.prompt_tokens ?? 0} output_tokens=${response.usage?.completion_tokens ?? 0}`);
+    const text = response.choices[0]?.message?.content ?? "";
+    const defaultBase = providerLabel === "grok"
+        ? DEFAULT_GROK_BASE_URL
+        : providerLabel === "lmstudio"
+            ? DEFAULT_LMSTUDIO_BASE_URL
+            : "https://api.openai.com/v1";
+    return {
+        text,
+        input_tokens: response.usage?.prompt_tokens ?? 0,
+        output_tokens: response.usage?.completion_tokens ?? 0,
+        model_id: modelId,
+        effective_base_url: baseUrl ?? defaultBase,
+        declared_billing_mode: providerLabel === "lmstudio" ? "local" : "per_token",
+    };
+}
+// ---------------------------------------------------------------------------
+// codex CLI call (OAuth subscription path)
+// ---------------------------------------------------------------------------
+/**
+ * Invoke `codex exec --ephemeral -` as a Codex worker for a single-turn
+ * prompt → text response. Uses the host's codex CLI authentication
+ * (chatgpt OAuth via ~/.codex/auth.json), which routes through chatgpt.com's
+ * backend — cannot be reached via the OpenAI SDK.
+ *
+ * --ephemeral keeps this learning call from persisting a session file
+ *   alongside review sessions. --skip-git-repo-check lets learning run
+ *   from non-repo cwd. No -C/-s/-o: this is single-turn, no agentic scaffold.
+ */
+async function callCodexCli(systemPrompt, userPrompt, modelId, reasoningEffort, serviceTier) {
+    const { spawn } = await import("node:child_process");
+    const args = ["exec", "--skip-git-repo-check", "--ephemeral"];
+    if (modelId)
+        args.push("-m", modelId);
+    if (reasoningEffort)
+        args.push("-c", `model_reasoning_effort="${reasoningEffort}"`);
+    if (serviceTier)
+        args.push("-c", `service_tier="${serviceTier}"`);
+    args.push("-");
+    const combinedPrompt = `${systemPrompt}\n\n---\n\n${userPrompt}`;
+    emitModelCallLog(`codex call: model="${modelId ?? "(codex default)"}" effort="${reasoningEffort ?? "(unset)"}" service_tier="${serviceTier ?? "(unset)"}" timeout_ms=${DEFAULT_TIMEOUT_MS}`);
+    const child = spawn("codex", args, {
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    child.stdout.on("data", (chunk) => {
+        stdout += String(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+        stderr += String(chunk);
+    });
+    child.stdin.write(combinedPrompt);
+    child.stdin.end();
+    const timeoutHandle = setTimeout(() => {
+        timedOut = true;
+        child.kill("SIGTERM");
+    }, DEFAULT_TIMEOUT_MS);
+    const exitCode = await new Promise((resolve, reject) => {
+        child.on("error", (err) => {
+            clearTimeout(timeoutHandle);
+            if (err.code === "ENOENT") {
+                reject(new Error("codex CLI not found on PATH. Install codex to use the OAuth subscription path: https://github.com/openai/codex"));
+            }
+            else {
+                reject(err);
+            }
+        });
+        child.on("close", (code) => {
+            clearTimeout(timeoutHandle);
+            resolve(code ?? 1);
+        });
+    });
+    if (timedOut) {
+        emitModelCallLog(`codex call FAILED: model="${modelId ?? "(codex default)"}" reason=timeout timeout_ms=${DEFAULT_TIMEOUT_MS}`);
+        throw new Error(`codex CLI call timed out after ${DEFAULT_TIMEOUT_MS}ms`);
+    }
+    if (exitCode !== 0) {
+        const combined = [stderr.trim(), stdout.trim()]
+            .filter((m) => m.length > 0)
+            .join("\n");
+        emitModelCallLog(`codex call FAILED: model="${modelId ?? "(codex default)"}" exit_code=${exitCode} message="${combined.slice(0, 200).replace(/\n/g, " ")}"`);
+        // A1: chatgpt account model allowlist rejection — augment with actionable hint.
+        // codex emits errors like:
+        //   "The 'gpt-4o-mini' model is not supported when using Codex with a ChatGPT account."
+        // Surface a fix path so users don't have to decode the upstream message.
+        if (combined.includes("is not supported when using Codex with a ChatGPT account") ||
+            combined.includes("not supported when using Codex")) {
+            const requested = modelId ?? "(codex default)";
+            throw new Error([
+                combined,
+                "",
+                `지정된 모델 "${requested}"이 현재 ChatGPT 계정의 codex allowlist에 없습니다.`,
+                "다음 중 한 가지로 해결하세요:",
+                "  1. .onto/settings.json 의 llm.model 값을 현재 계정에서 허용되는 모델로 변경",
+                "  2. 터미널에서 `codex` 를 직접 실행해 현재 계정에서 선택 가능한 모델 확인",
+                "  3. `codex login` 으로 API-key 모드로 전환 (per-token 과금, 더 넓은 모델 범위)",
+            ].join("\n"));
+        }
+        throw new Error(combined.length > 0 ? combined : `codex CLI exited with code ${exitCode}`);
+    }
+    const text = stdout.trim();
+    // codex exec does not return usage metadata in stdout; estimate by char count.
+    // LlmCallResult carries these as approximate; audit may flag via declared_billing_mode=subscription.
+    const estimateTokens = (s) => Math.max(1, Math.ceil(s.length / 4));
+    const in_tokens = estimateTokens(combinedPrompt);
+    const out_tokens = estimateTokens(text);
+    emitModelCallLog(`codex success: model_id=${modelId ?? "codex-default"} input_tokens~=${in_tokens} output_tokens~=${out_tokens}`);
+    return {
+        text,
+        input_tokens: in_tokens,
+        output_tokens: out_tokens,
+        model_id: modelId ?? "codex-default",
+        effective_base_url: "codex-cli://oauth",
+        declared_billing_mode: "subscription",
+    };
+}
+// ---------------------------------------------------------------------------
+// Plan-aware dispatch (Review Recovery PR-1)
+// ---------------------------------------------------------------------------
+/**
+ * Dispatch an LLM call using a pre-resolved ExecutionPlan shape. The plan
+ * carries `provider_identity`, `model_id`, and `base_url`; credentials are
+ * still read from env (ANTHROPIC_API_KEY / OPENAI_API_KEY / XAI_API_KEY)
+ * since secrets never enter the plan by design.
+ *
+ * Why credentials stay in env:
+ *   The plan is written to session artifacts (`execution-plan.yaml`) for
+ *   reproducibility and audit. Including API keys would leak them; env-sourced
+ *   credentials keep the plan portable while the runtime still has enough to
+ *   authenticate.
+ */
+async function dispatchByPlan(systemPrompt, userPrompt, config) {
+    const { plan } = config;
+    const maxTokens = config.max_tokens ?? 1024;
+    if (plan.provider_identity === "mock") {
+        return callMockProvider(systemPrompt, userPrompt);
+    }
+    if (plan.provider_identity === "claude-code") {
+        throw new Error("callLlm: ExecutionPlan.provider_identity=claude-code is orchestrator-only; background LLM calls cannot dispatch through the host nested spawn path.");
+    }
+    if (plan.provider_identity === "codex") {
+        const modelId = config.model_id ?? plan.model_id ?? config.models_per_provider?.codex;
+        return callCodexCli(systemPrompt, userPrompt, modelId, config.reasoning_effort, config.service_tier);
+    }
+    if (plan.provider_identity === "anthropic") {
+        const apiKey = readEnvApiKey(config.api_key_env ? [config.api_key_env] : ["ANTHROPIC_API_KEY"]);
+        if (!apiKey) {
+            throw new Error(explicitProviderMissingCredentialError("anthropic"));
+        }
+        const modelId = config.model_id ?? plan.model_id ?? config.models_per_provider?.anthropic;
+        if (!modelId)
+            throw missingModelError("anthropic");
+        return callAnthropic(systemPrompt, userPrompt, apiKey, modelId, maxTokens);
+    }
+    if (plan.provider_identity === "openai") {
+        const envKey = readEnvApiKey(config.api_key_env ? [config.api_key_env] : ["OPENAI_API_KEY"]);
+        const codexAuth = readCodexAuthState();
+        const apiKey = envKey ?? codexAuth.openaiApiKey ?? null;
+        if (!apiKey) {
+            throw new Error(explicitProviderMissingCredentialError("openai"));
+        }
+        const modelId = config.model_id ?? plan.model_id ?? config.models_per_provider?.openai;
+        if (!modelId)
+            throw missingModelError("openai");
+        return callOpenAI(systemPrompt, userPrompt, apiKey, modelId, maxTokens);
+    }
+    if (plan.provider_identity === "grok") {
+        const apiKey = readEnvApiKey(config.api_key_env ? [config.api_key_env] : ["XAI_API_KEY", "GROK_API_KEY"]);
+        if (!apiKey) {
+            throw new Error(explicitProviderMissingCredentialError("grok"));
+        }
+        const modelId = config.model_id ?? plan.model_id ?? config.models_per_provider?.grok;
+        if (!modelId)
+            throw missingModelError("grok");
+        return callOpenAI(systemPrompt, userPrompt, apiKey, modelId, maxTokens, plan.base_url ?? config.base_url ?? DEFAULT_GROK_BASE_URL, "grok");
+    }
+    if (plan.provider_identity === "lmstudio") {
+        const modelId = config.model_id ?? plan.model_id ?? config.models_per_provider?.lmstudio;
+        if (!modelId)
+            throw missingModelError("lmstudio");
+        return callOpenAI(systemPrompt, userPrompt, "lmstudio-local", modelId, maxTokens, plan.base_url ?? config.base_url ?? process.env.LMSTUDIO_BASE_URL ?? DEFAULT_LMSTUDIO_BASE_URL, "lmstudio");
+    }
+    throw new Error(`dispatchByPlan: unexpected provider_identity=${String(plan.provider_identity)}`);
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Call an LLM through the explicitly selected provider path. */
+export async function callLlm(systemPrompt, userPrompt, config) {
+    // Test-only mock provider — gated by ONTO_LLM_MOCK=1.
+    if (process.env.ONTO_LLM_MOCK === "1") {
+        return callMockProvider(systemPrompt, userPrompt);
+    }
+    if (config?.plan) {
+        return dispatchByPlan(systemPrompt, userPrompt, config);
+    }
+    if (config?.provider === "codex") {
+        return callCodexCli(systemPrompt, userPrompt, config.model_id ?? config.models_per_provider?.codex, config.reasoning_effort, config.service_tier);
+    }
+    if (config?.provider === "grok") {
+        const modelId = config.model_id ?? config.models_per_provider?.grok;
+        if (!modelId)
+            throw missingModelError("grok");
+        const apiKey = readEnvApiKey(config.api_key_env ? [config.api_key_env] : ["XAI_API_KEY", "GROK_API_KEY"]);
+        if (!apiKey)
+            throw new Error(explicitProviderMissingCredentialError("grok"));
+        const maxTokens = config.max_tokens ?? 1024;
+        return callOpenAI(systemPrompt, userPrompt, apiKey, modelId, maxTokens, config.base_url ?? DEFAULT_GROK_BASE_URL, "grok");
+    }
+    if (config?.provider === "lmstudio") {
+        const modelId = config.model_id ?? config.models_per_provider?.lmstudio;
+        if (!modelId)
+            throw missingModelError("lmstudio");
+        const maxTokens = config.max_tokens ?? 1024;
+        return callOpenAI(systemPrompt, userPrompt, "lmstudio-local", modelId, maxTokens, config.base_url ?? process.env.LMSTUDIO_BASE_URL ?? DEFAULT_LMSTUDIO_BASE_URL, "lmstudio");
+    }
+    const resolved = resolveProvider(config?.provider, config?.base_url, config?.api_key_env);
+    const maxTokens = config?.max_tokens ?? 1024;
+    const perProviderModel = config?.models_per_provider?.[resolved.provider];
+    switch (resolved.provider) {
+        case "codex": {
+            const modelId = config?.model_id ?? perProviderModel;
+            return callCodexCli(systemPrompt, userPrompt, modelId, config?.reasoning_effort, config?.service_tier);
+        }
+        case "anthropic": {
+            const modelId = config?.model_id ?? perProviderModel;
+            if (!modelId)
+                throw missingModelError("anthropic");
+            return callAnthropic(systemPrompt, userPrompt, resolved.apiKey, modelId, maxTokens);
+        }
+        case "openai": {
+            const modelId = config?.model_id ?? perProviderModel;
+            if (!modelId)
+                throw missingModelError("openai");
+            return callOpenAI(systemPrompt, userPrompt, resolved.apiKey, modelId, maxTokens);
+        }
+        case "grok": {
+            const modelId = config?.model_id ?? perProviderModel;
+            if (!modelId)
+                throw missingModelError("grok");
+            return callOpenAI(systemPrompt, userPrompt, resolved.apiKey, modelId, maxTokens, resolved.baseUrl ?? DEFAULT_GROK_BASE_URL, "grok");
+        }
+        case "lmstudio": {
+            const modelId = config?.model_id ?? perProviderModel;
+            if (!modelId)
+                throw missingModelError("lmstudio");
+            return callOpenAI(systemPrompt, userPrompt, resolved.apiKey, modelId, maxTokens, resolved.baseUrl ?? DEFAULT_LMSTUDIO_BASE_URL, "lmstudio");
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Mock provider — test only, gated by ONTO_LLM_MOCK=1
+// ---------------------------------------------------------------------------
+const MOCK_MODEL_ID = "mock-llm-deterministic";
+/**
+ * Pattern-match the system prompt against known Phase 3 prompt headers and
+ * return a deterministic JSON response shaped to satisfy each module's
+ * validator. The matching is intentionally string-prefix based — fragile by
+ * design so a prompt change forces a test update rather than silently
+ * accepting drift.
+ *
+ * Coverage:
+ *   - Panel reviewer (criteria 1~5)
+ *   - Judgment auditor (audit outcomes)
+ *   - Insight reclassifier (proposed_role)
+ *   - Domain doc proposer Phase B (reflection_form + content)
+ *   - Cross-agent dedup (criterion 6, same-principle test)
+ *   - Phase 2 semantic classifier (decision)
+ *
+ * N-1 fix: previously, unknown prompts fell through to a generic "ok" string,
+ * which made prompt drift a downstream parse failure instead of an immediate
+ * mock-dispatch failure. Now unknown prompts raise an error so test breakage
+ * surfaces at the mock layer with the actual prompt prefix in the message.
+ */
+function callMockProvider(systemPrompt, userPrompt) {
+    let text;
+    if (systemPrompt.startsWith("You are reviewing promotion candidates")) {
+        // Panel reviewer — extract candidate_ids from the user prompt and return
+        // one item per id with all-yes criteria + promote verdict.
+        const candidateIds = extractCandidateIds(userPrompt);
+        text = JSON.stringify({
+            items: candidateIds.map((id) => ({
+                candidate_id: id,
+                verdict: "promote",
+                criteria: [1, 2, 3, 4, 5].map((c) => ({
+                    criterion: c,
+                    judgment: "yes",
+                    reasoning: `mock reasoning for criterion ${c}`,
+                })),
+                axis_tag_recommendation: "retain",
+                axis_tag_note: "mock — keep current tags",
+                contradiction_resolution: "n/a",
+                reason: "mock — all criteria passed deterministically",
+            })),
+        });
+    }
+    else if (systemPrompt.startsWith("You are re-verifying previously promoted [judgment]-type learnings")) {
+        // Judgment auditor — extract item count and return retain for each.
+        const count = extractJudgmentItemCount(userPrompt);
+        text = JSON.stringify({
+            outcomes: Array.from({ length: count }, (_, i) => ({
+                item_index: i,
+                decision: "retain",
+                reason: "mock — judgment still valid",
+                modified_content: null,
+            })),
+        });
+    }
+    else if (systemPrompt.startsWith("You are reclassifying [insight]-tagged learnings")) {
+        // Insight reclassifier — return foundation as a safe default.
+        text = JSON.stringify({
+            proposed_role: "foundation",
+            reason: "mock — defaulted to foundation",
+        });
+    }
+    else if (systemPrompt.startsWith("You are updating a domain document")) {
+        // Domain doc proposer Phase B.
+        text = JSON.stringify({
+            reflection_form: "add_term",
+            content: "**Mock Term** — A mock entry produced by the deterministic LLM provider.",
+        });
+    }
+    else if (systemPrompt.startsWith("You are detecting cross-agent principle duplication")) {
+        // Cross-agent dedup (criterion 6) — extract the first agent from the
+        // user prompt as primary owner and fabricate a consolidated line. The
+        // mock happy path always confirms same_principle so tests can exercise
+        // the structural path.
+        //
+        // Negative-path hooks (CG3 + UF3):
+        //   ONTO_LLM_MOCK_DEDUP_BOGUS_OWNER=1
+        //     → return a primary_owner_agent that is NOT in the shortlist so the
+        //       C2 runtime guard in llmConfirmCluster rejects the cluster.
+        //   ONTO_LLM_MOCK_DEDUP_SAME_PRINCIPLE_FALSE=1
+        //     → return same_principle=false so the UF2 metric bucket bumps.
+        //   ONTO_LLM_MOCK_DEDUP_MALFORMED=1
+        //     → emit non-JSON so the malformed_json failure channel fires.
+        //
+        // These hooks are test-only and gated on the ONTO_LLM_MOCK=1 envelope
+        // already checked above; production runs never see them.
+        if (process.env.ONTO_LLM_MOCK_DEDUP_MALFORMED === "1") {
+            text = "{this is not valid json at all";
+        }
+        else if (process.env.ONTO_LLM_MOCK_DEDUP_SAME_PRINCIPLE_FALSE === "1") {
+            text = JSON.stringify({
+                same_principle: false,
+                primary_owner_agent: null,
+                primary_owner_reason: "mock — disagreement",
+                consolidated_principle: "",
+                representative_cases: [],
+                consolidated_line: "",
+            });
+        }
+        else {
+            const firstAgent = extractFirstDedupAgent(userPrompt);
+            const agentCount = countDedupAgents(userPrompt);
+            const bogusOwner = process.env.ONTO_LLM_MOCK_DEDUP_BOGUS_OWNER === "1"
+                ? "offshortlist_ghost_agent"
+                : firstAgent;
+            text = JSON.stringify({
+                same_principle: true,
+                primary_owner_agent: bogusOwner,
+                primary_owner_reason: "mock — first listed agent",
+                consolidated_principle: "Mock consolidated principle produced by the deterministic LLM provider.",
+                representative_cases: Array.from({ length: Math.min(agentCount, 3) }, (_, i) => `mock case ${i + 1}`),
+                consolidated_line: "- [fact] [methodology] [foundation] mock consolidated principle " +
+                    "(Representative cases: mock case 1; mock case 2) (source: consolidated from mock-mock-2026-04-09)",
+            });
+        }
+    }
+    else if (systemPrompt.startsWith("You are a semantic classifier")) {
+        text = JSON.stringify({
+            decision: "save",
+            conflict_kind: null,
+            matched_existing_line: null,
+            reason: "mock — no overlap detected",
+        });
+    }
+    else if (systemPrompt.startsWith("You are a review complexity assessor")) {
+        // Phase 3: Step 1.5 complexity assessment mock — defaults to full review
+        text = JSON.stringify({
+            q2_cross_verification_secondary: false,
+            q2_rationale: "mock — defaulting to full review (cross-verification critical)",
+            q3_miss_risk_acceptable: false,
+            q3_rationale: "mock — defaulting to full review (risk not acceptable)",
+            suggest_core_axis: false,
+        });
+    }
+    else if (systemPrompt.startsWith("You are a review lens selector")) {
+        // Phase 3: Step 1.5 lens selection mock — default core-axis set.
+        // SSOT: .onto/authority/core-lens-registry.yaml (v0.2.1: cost-constrained
+        // Pareto-optimal lenses). Imported at module init (see top of file).
+        text = JSON.stringify({
+            selected_lens_ids: loadCoreLensRegistry().core_axis_lens_ids,
+            rationale: "mock — default core-axis review lens set",
+        });
+    }
+    else if (systemPrompt.startsWith("You are executing a single bounded review unit")) {
+        // Phase 2 host-decoupling: ts_inline_http review unit executor (lens
+        // variant). The mock returns a minimal lens-output-shaped markdown so
+        // executor tests can verify the full call → write → JSON-print path
+        // without needing a real LLM endpoint. Real lens output comes from a real
+        // LLM; this mock only exercises the executor wiring.
+        text = [
+            "# Mock Lens Output (ts_inline_http executor mock)",
+            "",
+            "## Structural Inspection",
+            "- Mock checklist item: PASS",
+            "",
+            "## Findings",
+            "(none — mock executor)",
+            "",
+            "## Newly Learned",
+            "(none — mock executor)",
+            "",
+            "## Applied Learnings",
+            "(none — mock executor)",
+            "",
+            "## Domain Constraints Used",
+            "[]",
+            "",
+            "## Domain Context Assumptions",
+            '- "Mock executor returned this output for test purposes via ONTO_LLM_MOCK=1."',
+            "",
+        ].join("\n");
+    }
+    else if (systemPrompt.startsWith("You are the synthesize actor for a 9-lens review")) {
+        // Phase 3-3: synthesize-variant executor mock. Returns a minimal
+        // synthesize-shaped markdown with the 8 required sections + YAML
+        // frontmatter so downstream consumers can verify the structure.
+        //
+        // Phase 3-4 A2 negative-path hook: ONTO_LLM_MOCK_SYNTHESIZE_WRAP_FENCE=1
+        // makes the mock wrap its entire response in a ```yaml fence, simulating
+        // the 30B-A3B behavior that violates the "Do not wrap" prompt rule. This
+        // exercises the executor's stripWrappingCodeFence post-processor without
+        // needing a real LLM call.
+        //
+        // Phase 3-4 A5 negative-path hook: ONTO_LLM_MOCK_SYNTHESIZE_FABRICATE=1
+        // injects a fabricated quote (a phrase that won't appear in any lens
+        // pool content) into the Disagreement section, simulating the
+        // hallucination observed in the A3 benchmark. This exercises the
+        // citation audit layer. Both hooks are test-only and gated on the
+        // ONTO_LLM_MOCK=1 envelope already checked above.
+        const disagreementSection = process.env.ONTO_LLM_MOCK_SYNTHESIZE_FABRICATE === "1"
+            ? 'Axiology said "A fabricated quote that is definitely nowhere in the lens pool for this mock test run".'
+            : "(none — mock executor)";
+        const synthesizeBody = [
+            "---",
+            "deliberation_status: performed",
+            "---",
+            "",
+            "# Mock Synthesize Output (ts_inline_http executor mock, synthesize variant)",
+            "",
+            "## Consensus",
+            "(none — mock executor)",
+            "",
+            "## Conditional Consensus",
+            "(none — mock executor)",
+            "",
+            "## Disagreement",
+            disagreementSection,
+            "",
+            "## Deliberation Decision",
+            "Mock synthesize consumed the controlled deliberation artifact via ONTO_LLM_MOCK=1.",
+            "",
+            "## Unique Finding Tagging",
+            "(none — mock executor)",
+            "",
+            "## Axiology Integration",
+            "(none — mock executor)",
+            "",
+            "## Newly Learned",
+            "(none — mock executor)",
+            "",
+            "## Degraded Lens Failures",
+            "(none — mock executor)",
+            "",
+        ].join("\n");
+        text =
+            process.env.ONTO_LLM_MOCK_SYNTHESIZE_WRAP_FENCE === "1"
+                ? "```yaml\n" + synthesizeBody + "```"
+                : synthesizeBody;
+    }
+    else {
+        // Unknown prompt → throw with the prefix so tests point at the drifted prompt.
+        const prefix = systemPrompt.slice(0, 80).replace(/\n/g, " ");
+        return Promise.reject(new Error(`mock LLM provider: no pattern matched system prompt prefix "${prefix}". ` +
+            `If this is a new Phase 3 prompt, add a matching branch in callMockProvider. ` +
+            `If this is an old prompt that changed, update the matching prefix.`));
+    }
+    return Promise.resolve({
+        text,
+        input_tokens: estimateMockTokens(systemPrompt + userPrompt),
+        output_tokens: estimateMockTokens(text),
+        model_id: MOCK_MODEL_ID,
+        effective_base_url: "mock://deterministic",
+        declared_billing_mode: "per_token",
+    });
+}
+function extractCandidateIds(userPrompt) {
+    // Panel prompt format: `1. candidate_id=abc123 type=...`
+    const ids = [];
+    const re = /candidate_id=([A-Za-z0-9_-]+)/g;
+    let m;
+    while ((m = re.exec(userPrompt)) !== null) {
+        ids.push(m[1]);
+    }
+    return ids;
+}
+function extractJudgmentItemCount(userPrompt) {
+    const m = userPrompt.match(/Judgment items to re-verify:\s*(\d+)/);
+    return m ? Number(m[1]) : 0;
+}
+/**
+ * Cross-agent dedup user prompt lists items as:
+ *   1. agent_id=structure
+ *      ...
+ *   2. agent_id=coverage
+ *      ...
+ * Pick the first agent_id we see so the mock's primary_owner_agent matches
+ * the first listed shortlist member. Falls back to "structure" when no
+ * agent_id appears at all (shouldn't happen in practice).
+ */
+function extractFirstDedupAgent(userPrompt) {
+    const m = userPrompt.match(/agent_id=([A-Za-z0-9_-]+)/);
+    return m ? m[1] : "structure";
+}
+/**
+ * Count the distinct agent_id references in the cross-agent dedup user prompt
+ * so the mock can emit a plausible representative_cases list sized to the
+ * shortlist.
+ */
+function countDedupAgents(userPrompt) {
+    const ids = new Set();
+    const re = /agent_id=([A-Za-z0-9_-]+)/g;
+    let m;
+    while ((m = re.exec(userPrompt)) !== null) {
+        ids.add(m[1]);
+    }
+    return ids.size;
+}
+function estimateMockTokens(text) {
+    return Math.max(1, Math.ceil(text.length / 4));
+}
+/**
+ * Compute a stable hash of a prompt string for audit trail.
+ */
+export function hashPrompt(prompt) {
+    return crypto.createHash("sha256").update(prompt).digest("hex").slice(0, 12);
+}