@tiangong-lca/cli 0.0.1

package/dist/src/lib/llm.js

@@ -0,0 +1,383 @@
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { resolveEnv } from './env.js';
+import { CliError } from './errors.js';
+import { readJsonArtifact, writeJsonArtifact, writeJsonLinesArtifact } from './artifacts.js';
+export const LLM_ENV_KEYS = {
+    baseUrl: 'TIANGONG_LCA_REVIEW_LLM_BASE_URL',
+    apiKey: 'TIANGONG_LCA_REVIEW_LLM_API_KEY',
+    model: 'TIANGONG_LCA_REVIEW_LLM_MODEL',
+};
+export const LLM_ENV_SPECS = [
+    {
+        key: LLM_ENV_KEYS.baseUrl,
+        required: true,
+        description: 'Review LLM OpenAI-compatible Responses API base URL',
+    },
+    {
+        key: LLM_ENV_KEYS.apiKey,
+        required: true,
+        description: 'LLM API key',
+    },
+    {
+        key: LLM_ENV_KEYS.model,
+        required: true,
+        description: 'LLM model identifier',
+    },
+];
+function defaultSleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function requireLlmRuntime(env) {
+    if (!env.baseUrl) {
+        throw new CliError(`Missing LLM base URL. Set ${LLM_ENV_KEYS.baseUrl}.`, {
+            code: 'LLM_BASE_URL_REQUIRED',
+            exitCode: 2,
+        });
+    }
+    if (!env.apiKey) {
+        throw new CliError(`Missing LLM API key. Set ${LLM_ENV_KEYS.apiKey}.`, {
+            code: 'LLM_API_KEY_REQUIRED',
+            exitCode: 2,
+        });
+    }
+    if (!env.model) {
+        throw new CliError(`Missing LLM model. Set ${LLM_ENV_KEYS.model}.`, {
+            code: 'LLM_MODEL_REQUIRED',
+            exitCode: 2,
+        });
+    }
+    return {
+        baseUrl: env.baseUrl,
+        apiKey: env.apiKey,
+        model: env.model,
+    };
+}
+function buildLlmUrl(baseUrl) {
+    return `${baseUrl.replace(/\/+$/u, '')}/responses`;
+}
+function normalizeContext(context) {
+    if (context === undefined || context === null) {
+        return '';
+    }
+    if (typeof context === 'string') {
+        return context;
+    }
+    return JSON.stringify(context);
+}
+function buildTextOptions(input) {
+    const options = { ...(input.text ?? {}) };
+    if (input.responseFormat !== undefined) {
+        options.format = input.responseFormat;
+    }
+    return Object.keys(options).length ? options : undefined;
+}
+function buildRequestBody(model, input) {
+    const textOptions = buildTextOptions(input);
+    const body = {
+        model,
+        input: [
+            {
+                role: 'system',
+                content: [{ type: 'input_text', text: input.prompt }],
+            },
+            {
+                role: 'user',
+                content: [{ type: 'input_text', text: normalizeContext(input.context) }],
+            },
+        ],
+    };
+    if (textOptions) {
+        body.text = textOptions;
+    }
+    return body;
+}
+function hashRequest(baseUrl, body) {
+    return createHash('sha256').update(JSON.stringify({ baseUrl, body })).digest('hex');
+}
+function buildCachePath(cacheDir, promptHash) {
+    if (!cacheDir) {
+        return null;
+    }
+    return path.join(cacheDir, `${promptHash}.json`);
+}
+function getUsageValue(value, key) {
+    if (value && typeof value === 'object' && key in value) {
+        return value[key];
+    }
+    return undefined;
+}
+function coerceInteger(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return Math.trunc(value);
+    }
+    if (typeof value === 'string' && value.trim()) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed)) {
+            return Math.trunc(parsed);
+        }
+    }
+    return undefined;
+}
+export function extractLlmOutput(payload) {
+    if (payload && typeof payload === 'object') {
+        const directText = payload.output_text;
+        if (typeof directText === 'string' && directText) {
+            return directText;
+        }
+        const output = payload.output;
+        if (Array.isArray(output)) {
+            const parts = [];
+            output.forEach((item) => {
+                if (!item || typeof item !== 'object') {
+                    return;
+                }
+                if (item.type !== 'message') {
+                    return;
+                }
+                const content = item.content;
+                if (!Array.isArray(content)) {
+                    return;
+                }
+                content.forEach((entry) => {
+                    if (!entry || typeof entry !== 'object') {
+                        return;
+                    }
+                    if (entry.type !== 'output_text') {
+                        return;
+                    }
+                    const text = entry.text;
+                    if (typeof text === 'string' && text) {
+                        parts.push(text);
+                    }
+                });
+            });
+            return parts.join('\n');
+        }
+    }
+    return '';
+}
+export function extractLlmUsage(payload) {
+    if (!payload || typeof payload !== 'object') {
+        return null;
+    }
+    const usageObject = getUsageValue(payload, 'usage');
+    if (!usageObject || typeof usageObject !== 'object') {
+        return null;
+    }
+    const usage = {};
+    const inputTokens = coerceInteger(getUsageValue(usageObject, 'input_tokens'));
+    const outputTokens = coerceInteger(getUsageValue(usageObject, 'output_tokens'));
+    const totalTokens = coerceInteger(getUsageValue(usageObject, 'total_tokens'));
+    const inputDetails = getUsageValue(usageObject, 'input_tokens_details');
+    const outputDetails = getUsageValue(usageObject, 'output_tokens_details');
+    const cachedInputTokens = coerceInteger(getUsageValue(inputDetails, 'cached_tokens'));
+    const reasoningTokens = coerceInteger(getUsageValue(outputDetails, 'reasoning_tokens'));
+    if (inputTokens !== undefined) {
+        usage.inputTokens = inputTokens;
+    }
+    if (outputTokens !== undefined) {
+        usage.outputTokens = outputTokens;
+    }
+    if (totalTokens !== undefined) {
+        usage.totalTokens = totalTokens;
+    }
+    else if (inputTokens !== undefined && outputTokens !== undefined) {
+        usage.totalTokens = inputTokens + outputTokens;
+    }
+    if (cachedInputTokens !== undefined) {
+        usage.cachedInputTokens = cachedInputTokens;
+    }
+    if (reasoningTokens !== undefined) {
+        usage.reasoningTokens = reasoningTokens;
+    }
+    return Object.keys(usage).length ? usage : null;
+}
+function loadCachedResult(cachePath) {
+    const payload = readJsonArtifact(cachePath);
+    if (!payload || typeof payload !== 'object' || typeof payload.output !== 'string') {
+        throw new CliError(`LLM cache payload is invalid: ${cachePath}`, {
+            code: 'LLM_CACHE_INVALID',
+            exitCode: 2,
+        });
+    }
+    return {
+        output: payload.output,
+        usage: payload.usage ?? null,
+        cacheHit: true,
+        promptHash: path.basename(cachePath, '.json'),
+    };
+}
+function buildTraceRecord(options) {
+    const record = {
+        timestamp: options.now.toISOString(),
+        runId: options.runId?.trim() || 'unknown',
+        module: options.module?.trim() || 'unknown',
+        stage: options.stage?.trim() || 'unknown',
+        promptHash: options.promptHash,
+        model: options.model,
+        latencyMs: Math.round(options.latencyMs * 100) / 100,
+        cacheHit: options.cacheHit,
+        status: options.status,
+    };
+    if (options.usage) {
+        record.usage = options.usage;
+    }
+    if (options.error) {
+        record.error = options.error.slice(0, 500);
+    }
+    return record;
+}
+function writeTrace(tracePath, record) {
+    if (!tracePath) {
+        return;
+    }
+    writeJsonLinesArtifact(tracePath, record, { append: true });
+}
+function isRetryableStatus(status) {
+    return status === 408 || status === 429 || status >= 500;
+}
+function isJsonContentType(contentType) {
+    return (contentType ?? '').toLowerCase().includes('application/json');
+}
+async function requestLlm(url, body, options, apiKey) {
+    const response = await options.fetchImpl(url, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(options.timeoutMs),
+    });
+    const rawText = await response.text();
+    const contentType = response.headers.get('content-type');
+    if (!isJsonContentType(contentType)) {
+        throw new CliError(`LLM response was not valid JSON for ${url}`, {
+            code: 'LLM_INVALID_JSON',
+            exitCode: 1,
+            details: rawText,
+        });
+    }
+    let payload;
+    try {
+        payload = JSON.parse(rawText);
+    }
+    catch (error) {
+        throw new CliError(`LLM response was not valid JSON for ${url}`, {
+            code: 'LLM_INVALID_JSON',
+            exitCode: 1,
+            details: String(error),
+        });
+    }
+    if (!response.ok) {
+        const httpError = new CliError(`LLM request failed with HTTP ${response.status} from ${url}`, {
+            code: 'LLM_REQUEST_FAILED',
+            exitCode: 1,
+            details: payload,
+        });
+        httpError.retryable = isRetryableStatus(response.status);
+        throw httpError;
+    }
+    return {
+        output: extractLlmOutput(payload),
+        usage: extractLlmUsage(payload),
+    };
+}
+export function readLlmRuntimeEnv(env) {
+    return {
+        baseUrl: resolveEnv(LLM_ENV_SPECS[0], env).value,
+        apiKey: resolveEnv(LLM_ENV_SPECS[1], env).value,
+        model: resolveEnv(LLM_ENV_SPECS[2], env).value,
+    };
+}
+export async function invokeLlm(options) {
+    const runtime = requireLlmRuntime(options.env);
+    const url = buildLlmUrl(runtime.baseUrl);
+    const body = buildRequestBody(runtime.model, options.input);
+    const promptHash = hashRequest(runtime.baseUrl, body);
+    const cachePath = buildCachePath(options.cacheDir, promptHash);
+    const startedAt = process.hrtime.bigint();
+    const now = options.now ?? (() => new Date());
+    if (cachePath && existsSync(cachePath)) {
+        const cachedResult = loadCachedResult(cachePath);
+        writeTrace(options.tracePath, buildTraceRecord({
+            now: now(),
+            runId: options.runId,
+            module: options.module,
+            stage: options.stage,
+            promptHash,
+            model: runtime.model,
+            latencyMs: Number(process.hrtime.bigint() - startedAt) / 1_000_000,
+            cacheHit: true,
+            status: 'ok',
+            usage: cachedResult.usage,
+        }));
+        return cachedResult;
+    }
+    const maxAttempts = Math.max(options.maxAttempts ?? 3, 1);
+    const sleep = options.sleep ?? defaultSleep;
+    const retryDelayMs = Math.max(options.retryDelayMs ?? 1_000, 0);
+    let lastError = new CliError('LLM invocation failed without a terminal result.', {
+        code: 'LLM_INVOCATION_INCOMPLETE',
+        exitCode: 1,
+    });
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        try {
+            const result = await requestLlm(url, body, options, runtime.apiKey);
+            if (cachePath) {
+                writeJsonArtifact(cachePath, {
+                    output: result.output,
+                    usage: result.usage,
+                });
+            }
+            writeTrace(options.tracePath, buildTraceRecord({
+                now: now(),
+                runId: options.runId,
+                module: options.module,
+                stage: options.stage,
+                promptHash,
+                model: runtime.model,
+                latencyMs: Number(process.hrtime.bigint() - startedAt) / 1_000_000,
+                cacheHit: false,
+                status: 'ok',
+                usage: result.usage,
+            }));
+            return {
+                output: result.output,
+                usage: result.usage,
+                cacheHit: false,
+                promptHash,
+            };
+        }
+        catch (error) {
+            lastError = error;
+            const retryable = Boolean(error instanceof CliError &&
+                'retryable' in error &&
+                error.retryable);
+            if (attempt < maxAttempts - 1 && (!(error instanceof CliError) || retryable)) {
+                await sleep(retryDelayMs * (attempt + 1));
+                continue;
+            }
+            break;
+        }
+    }
+    writeTrace(options.tracePath, buildTraceRecord({
+        now: now(),
+        runId: options.runId,
+        module: options.module,
+        stage: options.stage,
+        promptHash,
+        model: runtime.model,
+        latencyMs: Number(process.hrtime.bigint() - startedAt) / 1_000_000,
+        cacheHit: false,
+        status: 'error',
+        usage: null,
+        error: String(lastError),
+    }));
+    throw lastError;
+}
+//# sourceMappingURL=llm.js.map

package/dist/src/lib/llm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.js","sourceRoot":"","sources":["../../../src/lib/llm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAE7F,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,OAAO,EAAE,kCAAkC;IAC3C,MAAM,EAAE,iCAAiC;IACzC,KAAK,EAAE,+BAA+B;CAC9B,CAAC;AAEX,MAAM,CAAC,MAAM,aAAa,GAAc;IACtC;QACE,GAAG,EAAE,YAAY,CAAC,OAAO;QACzB,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,qDAAqD;KACnE;IACD;QACE,GAAG,EAAE,YAAY,CAAC,MAAM;QACxB,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,aAAa;KAC3B;IACD;QACE,GAAG,EAAE,YAAY,CAAC,KAAK;QACvB,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,sBAAsB;KACpC;CACF,CAAC;AA4EF,SAAS,YAAY,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,iBAAiB,CAAC,GAAkB;IAC3C,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QACjB,MAAM,IAAI,QAAQ,CAAC,6BAA6B,YAAY,CAAC,OAAO,GAAG,EAAE;YACvE,IAAI,EAAE,uBAAuB;YAC7B,QAAQ,EAAE,CAAC;SACZ,CAAC,CAAC;IACL,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;QAChB,MAAM,IAAI,QAAQ,CAAC,4BAA4B,YAAY,CAAC,MAAM,GAAG,EAAE;YACrE,IAAI,EAAE,sBAAsB;YAC5B,QAAQ,EAAE,CAAC;SACZ,CAAC,CAAC;IACL,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,QAAQ,CAAC,0BAA0B,YAAY,CAAC,KAAK,GAAG,EAAE;YAClE,IAAI,EAAE,oBAAoB;YAC1B,QAAQ,EAAE,CAAC;SACZ,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,KAAK,EAAE,GAAG,CAAC,KAAK;KACjB,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,OAAe;IAClC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,YAAY,CAAC;AACrD,CAAC;AAED,SAAS,gBAAgB,CAAC,OAAgB;IACxC,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QAC9C,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;AACjC,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAyB;IACjD,MAAM,OAAO,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,CAAC;IAC1C,IAAI,KAAK,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QACvC,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC,cAAc,CAAC;IACxC,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3D,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAa,EAAE,KAAyB;IAChE,MAAM,WAAW,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC5C,MAAM,IAAI,GAA4B;QACpC,KAAK;QACL,KAAK,EAAE;YACL;gBACE,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;aACtD;YACD;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,gBAAgB,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;aACzE;SACF;KACF,CAAC;IAEF,IAAI,WAAW,EAAE,CAAC;QAChB,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,WAAW,CAAC,OAAe,EAAE,IAA6B;IACjE,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACtF,CAAC;AAED,SAAS,cAAc,CAAC,QAAmC,EAAE,UAAkB;IAC7E,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,UAAU,OAAO,CAAC,CAAC;AACnD,CAAC;AAED,SAAS,aAAa,CAAC,KAAc,EAAE,GAAW;IAChD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC;QACvD,OAAQ,KAAiC,CAAC,GAAG,CAAC,CAAC;IACjD,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACxD,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC9C,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7B,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,OAAgB;IAC/C,IAAI,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC3C,MAAM,UAAU,GAAI,OAAqC,CAAC,WAAW,CAAC;QACtE,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,EAAE,CAAC;YACjD,OAAO,UAAU,CAAC;QACpB,CAAC;QAED,MAAM,MAAM,GAAI,OAAgC,CAAC,MAAM,CAAC;QACxD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,MAAM,KAAK,GAAa,EAAE,CAAC;YAC3B,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;gBACtB,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;oBACtC,OAAO;gBACT,CAAC;gBAED,IAAK,IAA2B,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;oBACpD,OAAO;gBACT,CAAC;gBAED,MAAM,OAAO,GAAI,IAA8B,CAAC,OAAO,CAAC;gBACxD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;oBAC5B,OAAO;gBACT,CAAC;gBAED,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;oBACxB,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;wBACxC,OAAO;oBACT,CAAC;oBAED,IAAK,KAA4B,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;wBACzD,OAAO;oBACT,CAAC;oBAED,MAAM,IAAI,GAAI,KAA4B,CAAC,IAAI,CAAC;oBAChD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,EAAE,CAAC;wBACrC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBACnB,CAAC;gBACH,CAAC,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;YACH,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC5C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,WAAW,GAAG,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACpD,IAAI,CAAC,WAAW,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;QACpD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,WAAW,GAAG,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC,CAAC;IAC9E,MAAM,YAAY,GAAG,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC,CAAC;IAChF,MAAM,WAAW,GAAG,aAAa,CAAC,aAAa,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC,CAAC;IAC9E,MAAM,YAAY,GAAG,aAAa,CAAC,WAAW,EAAE,sBAAsB,CAAC,CAAC;IACxE,MAAM,aAAa,GAAG,aAAa,CAAC,WAAW,EAAE,uBAAuB,CAAC,CAAC;IAC1E,MAAM,iBAAiB,GAAG,aAAa,CAAC,aAAa,CAAC,YAAY,EAAE,eAAe,CAAC,CAAC,CAAC;IACtF,MAAM,eAAe,GAAG,aAAa,CAAC,aAAa,CAAC,aAAa,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAExF,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,KAAK,CAAC,WAAW,GAAG,WAAW,CAAC;IAClC,CAAC;IAED,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,KAAK,CAAC,YAAY,GAAG,YAAY,CAAC;IACpC,CAAC;IAED,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,KAAK,CAAC,WAAW,GAAG,WAAW,CAAC;IAClC,CAAC;SAAM,IAAI,WAAW,KAAK,SAAS,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QACnE,KAAK,CAAC,WAAW,GAAG,WAAW,GAAG,YAAY,CAAC;IACjD,CAAC;IAED,IAAI,iBAAiB,KAAK,SAAS,EAAE,CAAC;QACpC,KAAK,CAAC,iBAAiB,GAAG,iBAAiB,CAAC;IAC9C,CAAC;IAED,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;QAClC,KAAK,CAAC,eAAe,GAAG,eAAe,CAAC;IAC1C,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAClD,CAAC;AAED,SAAS,gBAAgB,CAAC,SAAiB;IACzC,MAAM,OAAO,GAAG,gBAAgB,CAAC,SAAS,CAAoB,CAAC;IAC/D,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,OAAO,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAClF,MAAM,IAAI,QAAQ,CAAC,iCAAiC,SAAS,EAAE,EAAE;YAC/D,IAAI,EAAE,mBAAmB;YACzB,QAAQ,EAAE,CAAC;SACZ,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,IAAI;QAC5B,QAAQ,EAAE,IAAI;QACd,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;KAC9C,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,OAYzB;IACC,MAAM,MAAM,GAAmB;QAC7B,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE;QACpC,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,SAAS;QACzC,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,SAAS;QAC3C,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,SAAS;QACzC,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,GAAG,GAAG,CAAC,GAAG,GAAG;QACpD,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC;IAEF,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,MAAM,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC/B,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,MAAM,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC7C,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,UAAU,CAAC,SAAoC,EAAE,MAAsB;IAC9E,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO;IACT,CAAC;IAED,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,iBAAiB,CAAC,MAAc;IACvC,OAAO,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,IAAI,GAAG,CAAC;AAC3D,CAAC;AAED,SAAS,iBAAiB,CAAC,WAA0B;IACnD,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC;AACxE,CAAC;AAED,KAAK,UAAU,UAAU,CACvB,GAAW,EACX,IAA6B,EAC7B,OAA0D,EAC1D,MAAc;IAEd,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,GAAG,EAAE;QAC5C,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,aAAa,EAAE,UAAU,MAAM,EAAE;YACjC,cAAc,EAAE,kBAAkB;SACnC;QACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;QAC1B,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC;KAC/C,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IACtC,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAEzD,IAAI,CAAC,iBAAiB,CAAC,WAAW,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,QAAQ,CAAC,uCAAuC,GAAG,EAAE,EAAE;YAC/D,IAAI,EAAE,kBAAkB;YACxB,QAAQ,EAAE,CAAC;YACX,OAAO,EAAE,OAAO;SACjB,CAAC,CAAC;IACL,CAAC;IAED,IAAI,OAAgB,CAAC;IACrB,IAAI,CAAC;QACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,QAAQ,CAAC,uCAAuC,GAAG,EAAE,EAAE;YAC/D,IAAI,EAAE,kBAAkB;YACxB,QAAQ,EAAE,CAAC;YACX,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC;SACvB,CAAC,CAAC;IACL,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,SAAS,GAAG,IAAI,QAAQ,CAAC,gCAAgC,QAAQ,CAAC,MAAM,SAAS,GAAG,EAAE,EAAE;YAC5F,IAAI,EAAE,oBAAoB;YAC1B,QAAQ,EAAE,CAAC;YACX,OAAO,EAAE,OAAO;SACjB,CAAC,CAAC;QACF,SAAgD,CAAC,SAAS,GAAG,iBAAiB,CAC7E,QAAQ,CAAC,MAAM,CAChB,CAAC;QACF,MAAM,SAAS,CAAC;IAClB,CAAC;IAED,OAAO;QACL,MAAM,EAAE,gBAAgB,CAAC,OAAO,CAAC;QACjC,KAAK,EAAE,eAAe,CAAC,OAAO,CAAC;KAChC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,GAAsB;IACtD,OAAO;QACL,OAAO,EAAE,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,KAAK;QAChD,MAAM,EAAE,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,KAAK;QAC/C,KAAK,EAAE,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,KAAK;KAC/C,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAyB;IACvD,MAAM,OAAO,GAAG,iBAAiB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/C,MAAM,GAAG,GAAG,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,gBAAgB,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC5D,MAAM,UAAU,GAAG,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACtD,MAAM,SAAS,GAAG,cAAc,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAC/D,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;IAC1C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IAE9C,IAAI,SAAS,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACvC,MAAM,YAAY,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;QACjD,UAAU,CACR,OAAO,CAAC,SAAS,EACjB,gBAAgB,CAAC;YACf,GAAG,EAAE,GAAG,EAAE;YACV,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,UAAU;YACV,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,SAAS;YAClE,QAAQ,EAAE,IAAI;YACd,MAAM,EAAE,IAAI;YACZ,KAAK,EAAE,YAAY,CAAC,KAAK;SAC1B,CAAC,CACH,CAAC;QACF,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,YAAY,CAAC;IAC5C,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,YAAY,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC;IAChE,IAAI,SAAS,GAAY,IAAI,QAAQ,CAAC,kDAAkD,EAAE;QACxF,IAAI,EAAE,2BAA2B;QACjC,QAAQ,EAAE,CAAC;KACZ,CAAC,CAAC;IAEH,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,WAAW,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC;QAC1D,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;YACpE,IAAI,SAAS,EAAE,CAAC;gBACd,iBAAiB,CAAC,SAAS,EAAE;oBAC3B,MAAM,EAAE,MAAM,CAAC,MAAM;oBACrB,KAAK,EAAE,MAAM,CAAC,KAAK;iBACpB,CAAC,CAAC;YACL,CAAC;YAED,UAAU,CACR,OAAO,CAAC,SAAS,EACjB,gBAAgB,CAAC;gBACf,GAAG,EAAE,GAAG,EAAE;gBACV,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,UAAU;gBACV,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,SAAS;gBAClE,QAAQ,EAAE,KAAK;gBACf,MAAM,EAAE,IAAI;gBACZ,KAAK,EAAE,MAAM,CAAC,KAAK;aACpB,CAAC,CACH,CAAC;YACF,OAAO;gBACL,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,QAAQ,EAAE,KAAK;gBACf,UAAU;aACX,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,SAAS,GAAG,KAAK,CAAC;YAClB,MAAM,SAAS,GAAG,OAAO,CACvB,KAAK,YAAY,QAAQ;gBACzB,WAAW,IAAI,KAAK;gBACnB,KAA4C,CAAC,SAAS,CACxD,CAAC;YAEF,IAAI,OAAO,GAAG,WAAW,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,YAAY,QAAQ,CAAC,IAAI,SAAS,CAAC,EAAE,CAAC;gBAC7E,MAAM,KAAK,CAAC,YAAY,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;gBAC1C,SAAS;YACX,CAAC;YACD,MAAM;QACR,CAAC;IACH,CAAC;IAED,UAAU,CACR,OAAO,CAAC,SAAS,EACjB,gBAAgB,CAAC;QACf,GAAG,EAAE,GAAG,EAAE;QACV,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,UAAU;QACV,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,SAAS;QAClE,QAAQ,EAAE,KAAK;QACf,MAAM,EAAE,OAAO;QACf,KAAK,EAAE,IAAI;QACX,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC;KACzB,CAAC,CACH,CAAC;IAEF,MAAM,SAAS,CAAC;AAClB,CAAC","sourcesContent":["import { createHash } from 'node:crypto';\nimport { existsSync } from 'node:fs';\nimport path from 'node:path';\nimport type { EnvSpec } from './env.js';\nimport { resolveEnv } from './env.js';\nimport { CliError } from './errors.js';\nimport type { FetchLike } from './http.js';\nimport { readJsonArtifact, writeJsonArtifact, writeJsonLinesArtifact } from './artifacts.js';\n\nexport const LLM_ENV_KEYS = {\n  baseUrl: 'TIANGONG_LCA_REVIEW_LLM_BASE_URL',\n  apiKey: 'TIANGONG_LCA_REVIEW_LLM_API_KEY',\n  model: 'TIANGONG_LCA_REVIEW_LLM_MODEL',\n} as const;\n\nexport const LLM_ENV_SPECS: EnvSpec[] = [\n  {\n    key: LLM_ENV_KEYS.baseUrl,\n    required: true,\n    description: 'Review LLM OpenAI-compatible Responses API base URL',\n  },\n  {\n    key: LLM_ENV_KEYS.apiKey,\n    required: true,\n    description: 'LLM API key',\n  },\n  {\n    key: LLM_ENV_KEYS.model,\n    required: true,\n    description: 'LLM model identifier',\n  },\n];\n\nexport type LlmRuntimeEnv = {\n  baseUrl: string | null;\n  apiKey: string | null;\n  model: string | null;\n};\n\nexport type LlmUsage = {\n  inputTokens?: number;\n  outputTokens?: number;\n  totalTokens?: number;\n  cachedInputTokens?: number;\n  reasoningTokens?: number;\n};\n\nexport type LlmInvocationInput = {\n  prompt: string;\n  context?: unknown;\n  responseFormat?: unknown;\n  text?: Record<string, unknown>;\n};\n\nexport type LlmInvocationResult = {\n  output: string;\n  usage: LlmUsage | null;\n  cacheHit: boolean;\n  promptHash: string;\n};\n\nexport type InvokeLlmOptions = {\n  env: LlmRuntimeEnv;\n  input: LlmInvocationInput;\n  fetchImpl: FetchLike;\n  timeoutMs: number;\n  maxAttempts?: number;\n  sleep?: (ms: number) => Promise<void>;\n  retryDelayMs?: number;\n  cacheDir?: string | null;\n  tracePath?: string | null;\n  runId?: string | null;\n  module?: string;\n  stage?: string;\n  now?: () => Date;\n};\n\ntype SuccessfulLlmResponse = {\n  output: string;\n  usage: LlmUsage | null;\n};\n\ntype CachedLlmResult = {\n  output: string;\n  usage?: LlmUsage | null;\n};\n\ntype RequiredLlmRuntimeEnv = {\n  baseUrl: string;\n  apiKey: string;\n  model: string;\n};\n\ntype LlmTraceRecord = {\n  timestamp: string;\n  runId: string;\n  module: string;\n  stage: string;\n  promptHash: string;\n  model: string;\n  latencyMs: number;\n  cacheHit: boolean;\n  status: 'ok' | 'error';\n  usage?: LlmUsage;\n  error?: string;\n};\n\nfunction defaultSleep(ms: number): Promise<void> {\n  return new Promise((resolve) => {\n    setTimeout(resolve, ms);\n  });\n}\n\nfunction requireLlmRuntime(env: LlmRuntimeEnv): RequiredLlmRuntimeEnv {\n  if (!env.baseUrl) {\n    throw new CliError(`Missing LLM base URL. Set ${LLM_ENV_KEYS.baseUrl}.`, {\n      code: 'LLM_BASE_URL_REQUIRED',\n      exitCode: 2,\n    });\n  }\n\n  if (!env.apiKey) {\n    throw new CliError(`Missing LLM API key. Set ${LLM_ENV_KEYS.apiKey}.`, {\n      code: 'LLM_API_KEY_REQUIRED',\n      exitCode: 2,\n    });\n  }\n\n  if (!env.model) {\n    throw new CliError(`Missing LLM model. Set ${LLM_ENV_KEYS.model}.`, {\n      code: 'LLM_MODEL_REQUIRED',\n      exitCode: 2,\n    });\n  }\n\n  return {\n    baseUrl: env.baseUrl,\n    apiKey: env.apiKey,\n    model: env.model,\n  };\n}\n\nfunction buildLlmUrl(baseUrl: string): string {\n  return `${baseUrl.replace(/\\/+$/u, '')}/responses`;\n}\n\nfunction normalizeContext(context: unknown): string {\n  if (context === undefined || context === null) {\n    return '';\n  }\n\n  if (typeof context === 'string') {\n    return context;\n  }\n\n  return JSON.stringify(context);\n}\n\nfunction buildTextOptions(input: LlmInvocationInput): Record<string, unknown> | undefined {\n  const options = { ...(input.text ?? {}) };\n  if (input.responseFormat !== undefined) {\n    options.format = input.responseFormat;\n  }\n\n  return Object.keys(options).length ? options : undefined;\n}\n\nfunction buildRequestBody(model: string, input: LlmInvocationInput): Record<string, unknown> {\n  const textOptions = buildTextOptions(input);\n  const body: Record<string, unknown> = {\n    model,\n    input: [\n      {\n        role: 'system',\n        content: [{ type: 'input_text', text: input.prompt }],\n      },\n      {\n        role: 'user',\n        content: [{ type: 'input_text', text: normalizeContext(input.context) }],\n      },\n    ],\n  };\n\n  if (textOptions) {\n    body.text = textOptions;\n  }\n\n  return body;\n}\n\nfunction hashRequest(baseUrl: string, body: Record<string, unknown>): string {\n  return createHash('sha256').update(JSON.stringify({ baseUrl, body })).digest('hex');\n}\n\nfunction buildCachePath(cacheDir: string | null | undefined, promptHash: string): string | null {\n  if (!cacheDir) {\n    return null;\n  }\n\n  return path.join(cacheDir, `${promptHash}.json`);\n}\n\nfunction getUsageValue(value: unknown, key: string): unknown {\n  if (value && typeof value === 'object' && key in value) {\n    return (value as Record<string, unknown>)[key];\n  }\n\n  return undefined;\n}\n\nfunction coerceInteger(value: unknown): number | undefined {\n  if (typeof value === 'number' && Number.isFinite(value)) {\n    return Math.trunc(value);\n  }\n\n  if (typeof value === 'string' && value.trim()) {\n    const parsed = Number(value);\n    if (Number.isFinite(parsed)) {\n      return Math.trunc(parsed);\n    }\n  }\n\n  return undefined;\n}\n\nexport function extractLlmOutput(payload: unknown): string {\n  if (payload && typeof payload === 'object') {\n    const directText = (payload as { output_text?: unknown }).output_text;\n    if (typeof directText === 'string' && directText) {\n      return directText;\n    }\n\n    const output = (payload as { output?: unknown }).output;\n    if (Array.isArray(output)) {\n      const parts: string[] = [];\n      output.forEach((item) => {\n        if (!item || typeof item !== 'object') {\n          return;\n        }\n\n        if ((item as { type?: unknown }).type !== 'message') {\n          return;\n        }\n\n        const content = (item as { content?: unknown }).content;\n        if (!Array.isArray(content)) {\n          return;\n        }\n\n        content.forEach((entry) => {\n          if (!entry || typeof entry !== 'object') {\n            return;\n          }\n\n          if ((entry as { type?: unknown }).type !== 'output_text') {\n            return;\n          }\n\n          const text = (entry as { text?: unknown }).text;\n          if (typeof text === 'string' && text) {\n            parts.push(text);\n          }\n        });\n      });\n      return parts.join('\\n');\n    }\n  }\n\n  return '';\n}\n\nexport function extractLlmUsage(payload: unknown): LlmUsage | null {\n  if (!payload || typeof payload !== 'object') {\n    return null;\n  }\n\n  const usageObject = getUsageValue(payload, 'usage');\n  if (!usageObject || typeof usageObject !== 'object') {\n    return null;\n  }\n\n  const usage: LlmUsage = {};\n  const inputTokens = coerceInteger(getUsageValue(usageObject, 'input_tokens'));\n  const outputTokens = coerceInteger(getUsageValue(usageObject, 'output_tokens'));\n  const totalTokens = coerceInteger(getUsageValue(usageObject, 'total_tokens'));\n  const inputDetails = getUsageValue(usageObject, 'input_tokens_details');\n  const outputDetails = getUsageValue(usageObject, 'output_tokens_details');\n  const cachedInputTokens = coerceInteger(getUsageValue(inputDetails, 'cached_tokens'));\n  const reasoningTokens = coerceInteger(getUsageValue(outputDetails, 'reasoning_tokens'));\n\n  if (inputTokens !== undefined) {\n    usage.inputTokens = inputTokens;\n  }\n\n  if (outputTokens !== undefined) {\n    usage.outputTokens = outputTokens;\n  }\n\n  if (totalTokens !== undefined) {\n    usage.totalTokens = totalTokens;\n  } else if (inputTokens !== undefined && outputTokens !== undefined) {\n    usage.totalTokens = inputTokens + outputTokens;\n  }\n\n  if (cachedInputTokens !== undefined) {\n    usage.cachedInputTokens = cachedInputTokens;\n  }\n\n  if (reasoningTokens !== undefined) {\n    usage.reasoningTokens = reasoningTokens;\n  }\n\n  return Object.keys(usage).length ? usage : null;\n}\n\nfunction loadCachedResult(cachePath: string): LlmInvocationResult {\n  const payload = readJsonArtifact(cachePath) as CachedLlmResult;\n  if (!payload || typeof payload !== 'object' || typeof payload.output !== 'string') {\n    throw new CliError(`LLM cache payload is invalid: ${cachePath}`, {\n      code: 'LLM_CACHE_INVALID',\n      exitCode: 2,\n    });\n  }\n\n  return {\n    output: payload.output,\n    usage: payload.usage ?? null,\n    cacheHit: true,\n    promptHash: path.basename(cachePath, '.json'),\n  };\n}\n\nfunction buildTraceRecord(options: {\n  now: Date;\n  runId: string | null | undefined;\n  module: string | undefined;\n  stage: string | undefined;\n  promptHash: string;\n  model: string;\n  latencyMs: number;\n  cacheHit: boolean;\n  status: 'ok' | 'error';\n  usage: LlmUsage | null;\n  error?: string;\n}): LlmTraceRecord {\n  const record: LlmTraceRecord = {\n    timestamp: options.now.toISOString(),\n    runId: options.runId?.trim() || 'unknown',\n    module: options.module?.trim() || 'unknown',\n    stage: options.stage?.trim() || 'unknown',\n    promptHash: options.promptHash,\n    model: options.model,\n    latencyMs: Math.round(options.latencyMs * 100) / 100,\n    cacheHit: options.cacheHit,\n    status: options.status,\n  };\n\n  if (options.usage) {\n    record.usage = options.usage;\n  }\n\n  if (options.error) {\n    record.error = options.error.slice(0, 500);\n  }\n\n  return record;\n}\n\nfunction writeTrace(tracePath: string | null | undefined, record: LlmTraceRecord): void {\n  if (!tracePath) {\n    return;\n  }\n\n  writeJsonLinesArtifact(tracePath, record, { append: true });\n}\n\nfunction isRetryableStatus(status: number): boolean {\n  return status === 408 || status === 429 || status >= 500;\n}\n\nfunction isJsonContentType(contentType: string | null): boolean {\n  return (contentType ?? '').toLowerCase().includes('application/json');\n}\n\nasync function requestLlm(\n  url: string,\n  body: Record<string, unknown>,\n  options: Pick<InvokeLlmOptions, 'fetchImpl' | 'timeoutMs'>,\n  apiKey: string,\n): Promise<SuccessfulLlmResponse> {\n  const response = await options.fetchImpl(url, {\n    method: 'POST',\n    headers: {\n      Authorization: `Bearer ${apiKey}`,\n      'Content-Type': 'application/json',\n    },\n    body: JSON.stringify(body),\n    signal: AbortSignal.timeout(options.timeoutMs),\n  });\n\n  const rawText = await response.text();\n  const contentType = response.headers.get('content-type');\n\n  if (!isJsonContentType(contentType)) {\n    throw new CliError(`LLM response was not valid JSON for ${url}`, {\n      code: 'LLM_INVALID_JSON',\n      exitCode: 1,\n      details: rawText,\n    });\n  }\n\n  let payload: unknown;\n  try {\n    payload = JSON.parse(rawText);\n  } catch (error) {\n    throw new CliError(`LLM response was not valid JSON for ${url}`, {\n      code: 'LLM_INVALID_JSON',\n      exitCode: 1,\n      details: String(error),\n    });\n  }\n\n  if (!response.ok) {\n    const httpError = new CliError(`LLM request failed with HTTP ${response.status} from ${url}`, {\n      code: 'LLM_REQUEST_FAILED',\n      exitCode: 1,\n      details: payload,\n    });\n    (httpError as CliError & { retryable?: boolean }).retryable = isRetryableStatus(\n      response.status,\n    );\n    throw httpError;\n  }\n\n  return {\n    output: extractLlmOutput(payload),\n    usage: extractLlmUsage(payload),\n  };\n}\n\nexport function readLlmRuntimeEnv(env: NodeJS.ProcessEnv): LlmRuntimeEnv {\n  return {\n    baseUrl: resolveEnv(LLM_ENV_SPECS[0], env).value,\n    apiKey: resolveEnv(LLM_ENV_SPECS[1], env).value,\n    model: resolveEnv(LLM_ENV_SPECS[2], env).value,\n  };\n}\n\nexport async function invokeLlm(options: InvokeLlmOptions): Promise<LlmInvocationResult> {\n  const runtime = requireLlmRuntime(options.env);\n  const url = buildLlmUrl(runtime.baseUrl);\n  const body = buildRequestBody(runtime.model, options.input);\n  const promptHash = hashRequest(runtime.baseUrl, body);\n  const cachePath = buildCachePath(options.cacheDir, promptHash);\n  const startedAt = process.hrtime.bigint();\n  const now = options.now ?? (() => new Date());\n\n  if (cachePath && existsSync(cachePath)) {\n    const cachedResult = loadCachedResult(cachePath);\n    writeTrace(\n      options.tracePath,\n      buildTraceRecord({\n        now: now(),\n        runId: options.runId,\n        module: options.module,\n        stage: options.stage,\n        promptHash,\n        model: runtime.model,\n        latencyMs: Number(process.hrtime.bigint() - startedAt) / 1_000_000,\n        cacheHit: true,\n        status: 'ok',\n        usage: cachedResult.usage,\n      }),\n    );\n    return cachedResult;\n  }\n\n  const maxAttempts = Math.max(options.maxAttempts ?? 3, 1);\n  const sleep = options.sleep ?? defaultSleep;\n  const retryDelayMs = Math.max(options.retryDelayMs ?? 1_000, 0);\n  let lastError: unknown = new CliError('LLM invocation failed without a terminal result.', {\n    code: 'LLM_INVOCATION_INCOMPLETE',\n    exitCode: 1,\n  });\n\n  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {\n    try {\n      const result = await requestLlm(url, body, options, runtime.apiKey);\n      if (cachePath) {\n        writeJsonArtifact(cachePath, {\n          output: result.output,\n          usage: result.usage,\n        });\n      }\n\n      writeTrace(\n        options.tracePath,\n        buildTraceRecord({\n          now: now(),\n          runId: options.runId,\n          module: options.module,\n          stage: options.stage,\n          promptHash,\n          model: runtime.model,\n          latencyMs: Number(process.hrtime.bigint() - startedAt) / 1_000_000,\n          cacheHit: false,\n          status: 'ok',\n          usage: result.usage,\n        }),\n      );\n      return {\n        output: result.output,\n        usage: result.usage,\n        cacheHit: false,\n        promptHash,\n      };\n    } catch (error) {\n      lastError = error;\n      const retryable = Boolean(\n        error instanceof CliError &&\n        'retryable' in error &&\n        (error as CliError & { retryable?: boolean }).retryable,\n      );\n\n      if (attempt < maxAttempts - 1 && (!(error instanceof CliError) || retryable)) {\n        await sleep(retryDelayMs * (attempt + 1));\n        continue;\n      }\n      break;\n    }\n  }\n\n  writeTrace(\n    options.tracePath,\n    buildTraceRecord({\n      now: now(),\n      runId: options.runId,\n      module: options.module,\n      stage: options.stage,\n      promptHash,\n      model: runtime.model,\n      latencyMs: Number(process.hrtime.bigint() - startedAt) / 1_000_000,\n      cacheHit: false,\n      status: 'error',\n      usage: null,\n      error: String(lastError),\n    }),\n  );\n\n  throw lastError;\n}\n"]}