@hypercli/gen 0.1.1

package/dist/ai/ai-variable-resolver.js

@@ -0,0 +1,219 @@
+/**
+ * AI Variable Resolver
+ *
+ * Resolves unresolved recipe variables by batching them into a single AI prompt.
+ * Uses the existing AiService/transport infrastructure for the actual LLM call.
+ */
+import createDebug from "debug";
+import { AiService } from "./ai-service.js";
+const debug = createDebug("hypergen:ai:variable-resolver");
+/**
+ * Batched AI variable resolution.
+ *
+ * Collects all unresolved variables, builds one prompt, calls the LLM,
+ * parses the JSON response, and validates each value.
+ */
+export class AiVariableResolver {
+    aiConfig;
+    constructor(aiConfig) {
+        this.aiConfig = aiConfig;
+    }
+    /**
+     * Resolve a batch of variables via a single AI call.
+     *
+     * @returns Record mapping variable names to AI-resolved values.
+     *          Variables the AI could not resolve are omitted.
+     */
+    async resolveBatch(unresolvedVars, resolvedVars, recipeMeta, projectContext) {
+        if (unresolvedVars.length === 0)
+            return {};
+        debug("Resolving %d variables via AI for recipe: %s", unresolvedVars.length, recipeMeta.name);
+        const prompt = this.buildPrompt(unresolvedVars, resolvedVars, recipeMeta, projectContext);
+        const systemPrompt = this.buildSystemPrompt(unresolvedVars);
+        const aiService = AiService.getInstance(this.aiConfig);
+        let result;
+        try {
+            result = await aiService.generate({
+                prompt,
+                system: systemPrompt,
+                temperature: this.aiConfig.temperature ?? 0.2,
+                maxTokens: this.aiConfig.maxTokens,
+                model: this.aiConfig.model,
+                provider: this.aiConfig.provider,
+                projectRoot: process.cwd(),
+                stepName: "ai-variable-resolver",
+            });
+        }
+        catch (error) {
+            debug("AI call failed: %s", error instanceof Error ? error.message : String(error));
+            // Return empty — caller decides what to do with still-unresolved vars
+            return {};
+        }
+        return this.parseResponse(result.output, unresolvedVars);
+    }
+    /**
+     * Build the user prompt that describes what variables need values.
+     */
+    buildPrompt(unresolvedVars, resolvedVars, recipeMeta, projectContext) {
+        const lines = [];
+        lines.push("# Variable Resolution Request");
+        lines.push("");
+        lines.push(`**Recipe:** ${recipeMeta.name}`);
+        if (recipeMeta.description) {
+            lines.push(`**Description:** ${recipeMeta.description}`);
+        }
+        lines.push("");
+        // Already-resolved variables as context
+        const resolvedKeys = Object.keys(resolvedVars);
+        if (resolvedKeys.length > 0) {
+            lines.push("## Already Known Variables");
+            lines.push("");
+            for (const [name, value] of Object.entries(resolvedVars)) {
+                lines.push(`- **${name}**: \`${JSON.stringify(value)}\``);
+            }
+            lines.push("");
+        }
+        // Project context
+        if (projectContext) {
+            lines.push("## Project Context");
+            lines.push("");
+            lines.push(projectContext);
+            lines.push("");
+        }
+        // Variables that need resolution
+        lines.push("## Variables to Resolve");
+        lines.push("");
+        lines.push("For each variable below, determine the best value based on the recipe context, already-known variables, and any constraints.");
+        lines.push("");
+        for (const { name, config, defaultValue } of unresolvedVars) {
+            lines.push(`### \`${name}\``);
+            lines.push(`- **Type:** ${config.type}`);
+            if (config.required)
+                lines.push("- **Required:** yes");
+            if (config.description)
+                lines.push(`- **Description:** ${config.description}`);
+            if (config.suggestion !== undefined)
+                lines.push(`- **Suggestion:** \`${JSON.stringify(config.suggestion)}\``);
+            if (defaultValue !== undefined)
+                lines.push(`- **Default (skipped):** \`${JSON.stringify(defaultValue)}\``);
+            if (config.values)
+                lines.push(`- **Allowed values:** ${config.values.map((v) => `\`${v}\``).join(", ")}`);
+            if (config.pattern)
+                lines.push(`- **Pattern:** \`${config.pattern}\``);
+            if (config.min !== undefined)
+                lines.push(`- **Min:** ${config.min}`);
+            if (config.max !== undefined)
+                lines.push(`- **Max:** ${config.max}`);
+            lines.push("");
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Build the system prompt instructing the AI to return JSON.
+     */
+    buildSystemPrompt(unresolvedVars) {
+        const keys = unresolvedVars.map((v) => `"${v.name}"`).join(", ");
+        return [
+            "You are a code generation configuration assistant.",
+            "You MUST respond with ONLY a valid JSON object — no markdown fences, no explanation, no text outside the JSON.",
+            `The JSON object must have exactly these keys: ${keys}.`,
+            "Each value must match the type and constraints described in the prompt.",
+            "For string values, provide the string directly. For numbers, provide a number. For booleans, provide true/false.",
+            "For enum values, pick from the allowed values list. For arrays, provide a JSON array. For objects, provide a JSON object.",
+            "Use the suggestion or skipped default as a strong hint when available.",
+        ].join("\n");
+    }
+    /**
+     * Parse the AI's JSON response and coerce values to expected types.
+     */
+    parseResponse(raw, unresolvedVars) {
+        let text = raw.trim();
+        // Strip markdown code fences
+        const fenceMatch = text.match(/^```(?:json)?\s*\n?([\s\S]*?)\n?\s*```$/m);
+        if (fenceMatch) {
+            text = fenceMatch[1].trim();
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (err) {
+            debug("Failed to parse AI response as JSON: %s", text.slice(0, 200));
+            return {};
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            debug("AI response is not a JSON object");
+            return {};
+        }
+        const result = {};
+        for (const { name, config } of unresolvedVars) {
+            if (!(name in parsed)) {
+                debug("AI response missing key: %s", name);
+                continue;
+            }
+            const value = parsed[name];
+            const coerced = this.coerceValue(value, config);
+            if (coerced !== undefined) {
+                result[name] = coerced;
+            }
+            else {
+                debug("AI value for %s failed coercion (type: %s, got: %s)", name, config.type, typeof value);
+            }
+        }
+        debug("Parsed %d/%d variables from AI response", Object.keys(result).length, unresolvedVars.length);
+        return result;
+    }
+    /**
+     * Coerce a raw AI value to the expected variable type.
+     * Returns undefined if coercion fails.
+     */
+    coerceValue(value, config) {
+        if (value === null || value === undefined)
+            return undefined;
+        switch (config.type) {
+            case "string":
+            case "file":
+            case "directory":
+                return typeof value === "string" ? value : String(value);
+            case "number": {
+                const num = typeof value === "number" ? value : Number(value);
+                return Number.isNaN(num) ? undefined : num;
+            }
+            case "boolean":
+                if (typeof value === "boolean")
+                    return value;
+                if (value === "true")
+                    return true;
+                if (value === "false")
+                    return false;
+                return undefined;
+            case "enum":
+                if (config.values?.includes(String(value))) {
+                    return String(value);
+                }
+                // For multi-select enums
+                if (Array.isArray(value) && config.values) {
+                    const filtered = value.map(String).filter((v) => config.values?.includes(v));
+                    return filtered.length > 0 ? filtered : undefined;
+                }
+                return undefined;
+            case "array":
+                if (Array.isArray(value))
+                    return value;
+                if (typeof value === "string") {
+                    return value
+                        .split(",")
+                        .map((s) => s.trim())
+                        .filter(Boolean);
+                }
+                return undefined;
+            case "object":
+                if (typeof value === "object" && !Array.isArray(value))
+                    return value;
+                return undefined;
+            default:
+                return value;
+        }
+    }
+}
+//# sourceMappingURL=ai-variable-resolver.js.map

package/dist/ai/ai-variable-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-variable-resolver.js","sourceRoot":"","sources":["../../src/ai/ai-variable-resolver.ts"],"names":[],"mappings":"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"}

package/dist/ai/context-collector.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Context Collector
+ *
+ * Reads files, config, and previous step results to build the context
+ * included in AI prompts. Enforces token budgets.
+ */
+import type { StepResult } from "#recipe-engine/types";
+import type { AIContextConfig } from "./ai-config.js";
+/**
+ * A collected context bundle ready for prompt assembly
+ */
+export interface ContextBundle {
+    /** Collected file contents keyed by path */
+    files: Map<string, string>;
+    /** Config file contents keyed by name */
+    configs: Map<string, string>;
+    /** Previous step outputs keyed by step name */
+    stepOutputs: Map<string, string>;
+    /** Total estimated token count */
+    estimatedTokens: number;
+    /** Whether truncation was applied */
+    truncated: boolean;
+}
+export declare class ContextCollector {
+    /**
+     * Collect context files, configs, and step results based on configuration
+     */
+    collect(config: AIContextConfig | undefined, projectRoot: string, stepResults: Map<string, StepResult>): Promise<ContextBundle>;
+}
+//# sourceMappingURL=context-collector.d.ts.map

package/dist/ai/context-collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-collector.d.ts","sourceRoot":"","sources":["../../src/ai/context-collector.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAItD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,4CAA4C;IAC5C,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,yCAAyC;IACzC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,+CAA+C;IAC/C,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,kCAAkC;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,SAAS,EAAE,OAAO,CAAC;CACnB;AA0BD,qBAAa,gBAAgB;IAC5B;;OAEG;IACG,OAAO,CACZ,MAAM,EAAE,eAAe,GAAG,SAAS,EACnC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAClC,OAAO,CAAC,aAAa,CAAC;CAqIzB"}

package/dist/ai/context-collector.js

@@ -0,0 +1,158 @@
+/**
+ * Context Collector
+ *
+ * Reads files, config, and previous step results to build the context
+ * included in AI prompts. Enforces token budgets.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import createDebug from "debug";
+import { glob } from "glob";
+const debug = createDebug("hypergen:ai:context-collector");
+/**
+ * Rough token estimation: ~4 characters per token (conservative).
+ * This is intentionally simple — real token counting requires the model's tokenizer.
+ */
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Known project config file names and their typical locations
+ */
+const CONFIG_FILE_MAP = {
+    tsconfig: ["tsconfig.json", "tsconfig.build.json"],
+    "package.json": ["package.json"],
+    eslint: [
+        ".eslintrc.json",
+        ".eslintrc.js",
+        ".eslintrc.cjs",
+        "eslint.config.js",
+        "eslint.config.mjs",
+    ],
+    ".editorconfig": [".editorconfig"],
+};
+export class ContextCollector {
+    /**
+     * Collect context files, configs, and step results based on configuration
+     */
+    async collect(config, projectRoot, stepResults) {
+        const bundle = {
+            files: new Map(),
+            configs: new Map(),
+            stepOutputs: new Map(),
+            estimatedTokens: 0,
+            truncated: false,
+        };
+        if (!config)
+            return bundle;
+        const maxTokens = config.maxContextTokens ?? Number.POSITIVE_INFINITY;
+        let currentTokens = 0;
+        // 1. Project config files (highest priority — smallest, most relevant)
+        if (config.projectConfig) {
+            const configNames = config.projectConfig === true ? ["tsconfig", "package.json"] : config.projectConfig;
+            for (const name of configNames) {
+                const candidates = CONFIG_FILE_MAP[name] || [name];
+                for (const candidate of candidates) {
+                    const filePath = path.resolve(projectRoot, candidate);
+                    if (fs.existsSync(filePath)) {
+                        const content = fs.readFileSync(filePath, "utf-8");
+                        const tokens = estimateTokens(content);
+                        if (currentTokens + tokens > maxTokens) {
+                            bundle.truncated = true;
+                            debug("Skipping config %s: would exceed token budget", name);
+                            break;
+                        }
+                        bundle.configs.set(name, content);
+                        currentTokens += tokens;
+                        debug("Collected config %s (%d tokens)", name, tokens);
+                        break; // use first found
+                    }
+                }
+            }
+        }
+        // 2. Previous step results
+        if (config.fromSteps) {
+            for (const stepName of config.fromSteps) {
+                const result = stepResults.get(stepName);
+                if (result?.toolResult) {
+                    // Serialize step result to include in context
+                    const content = JSON.stringify(result.toolResult, null, 2);
+                    const tokens = estimateTokens(content);
+                    if (currentTokens + tokens > maxTokens) {
+                        bundle.truncated = true;
+                        debug("Skipping step output %s: would exceed token budget", stepName);
+                        continue;
+                    }
+                    bundle.stepOutputs.set(stepName, content);
+                    currentTokens += tokens;
+                    debug("Collected step output %s (%d tokens)", stepName, tokens);
+                }
+            }
+        }
+        // 3. Explicit file paths
+        if (config.include) {
+            for (const filePath of config.include) {
+                const resolved = path.resolve(projectRoot, filePath);
+                if (fs.existsSync(resolved)) {
+                    const content = fs.readFileSync(resolved, "utf-8");
+                    const tokens = estimateTokens(content);
+                    if (currentTokens + tokens > maxTokens) {
+                        if (config.overflow === "truncate") {
+                            const remainingChars = (maxTokens - currentTokens) * 4;
+                            if (remainingChars > 100) {
+                                bundle.files.set(filePath, `${content.slice(0, remainingChars)}\n... [truncated]`);
+                                currentTokens = maxTokens;
+                                bundle.truncated = true;
+                                debug("Truncated file %s to fit budget", filePath);
+                            }
+                        }
+                        else if (config.overflow === "error") {
+                            throw new Error(`Context exceeds token budget (${currentTokens + tokens} > ${maxTokens}). File: ${filePath}`);
+                        }
+                        else {
+                            bundle.truncated = true;
+                            debug("Skipping file %s: would exceed token budget", filePath);
+                        }
+                        continue;
+                    }
+                    bundle.files.set(filePath, content);
+                    currentTokens += tokens;
+                    debug("Collected file %s (%d tokens)", filePath, tokens);
+                }
+                else {
+                    debug("Context file not found: %s", resolved);
+                }
+            }
+        }
+        // 4. Glob patterns
+        if (config.files) {
+            for (const pattern of config.files) {
+                const matches = await glob(pattern, {
+                    cwd: projectRoot,
+                    absolute: false,
+                });
+                for (const match of matches) {
+                    if (bundle.files.has(match))
+                        continue; // avoid duplicates
+                    const resolved = path.resolve(projectRoot, match);
+                    if (!fs.existsSync(resolved) || fs.statSync(resolved).isDirectory())
+                        continue;
+                    const content = fs.readFileSync(resolved, "utf-8");
+                    const tokens = estimateTokens(content);
+                    if (currentTokens + tokens > maxTokens) {
+                        bundle.truncated = true;
+                        debug("Skipping glob match %s: would exceed token budget", match);
+                        continue;
+                    }
+                    bundle.files.set(match, content);
+                    currentTokens += tokens;
+                    debug("Collected glob match %s (%d tokens)", match, tokens);
+                }
+            }
+        }
+        bundle.estimatedTokens = currentTokens;
+        debug("Context collection complete: %d files, %d configs, %d step outputs, ~%d tokens, truncated=%s", bundle.files.size, bundle.configs.size, bundle.stepOutputs.size, currentTokens, bundle.truncated);
+        return bundle;
+    }
+}
+//# sourceMappingURL=context-collector.js.map

package/dist/ai/context-collector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-collector.js","sourceRoot":"","sources":["../../src/ai/context-collector.ts"],"names":[],"mappings":"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"}

package/dist/ai/cost-tracker.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Cost Tracker
+ *
+ * Tracks token usage and estimated costs across AI steps within a recipe execution.
+ * Enforces budget limits and provides end-of-run summaries.
+ */
+import type { AIBudgetConfig, AICostSummary, AIModelPricing } from "./ai-config.js";
+export declare class CostTracker {
+    private readonly budget?;
+    private readonly costTable;
+    private steps;
+    private totalInputTokens;
+    private totalOutputTokens;
+    private totalCostUsd;
+    private budgetWarningTriggered;
+    private budgetLimitHit;
+    constructor(budget?: AIBudgetConfig | undefined, costTable?: Record<string, AIModelPricing>);
+    /**
+     * Calculate cost for a given token usage
+     */
+    calculateCost(model: string, inputTokens: number, outputTokens: number): number;
+    /**
+     * Record token usage from an AI step
+     */
+    record(stepName: string, model: string, inputTokens: number, outputTokens: number, retryAttempts?: number): void;
+    /**
+     * Check if budget allows another AI call.
+     * Returns null if OK, or throws if hard limit exceeded.
+     * Logs warning if warn threshold crossed.
+     */
+    checkBudget(): void;
+    /**
+     * Get cost summary for the entire execution
+     */
+    getSummary(): AICostSummary;
+    /**
+     * Format a human-readable cost report
+     */
+    formatReport(): string;
+}
+//# sourceMappingURL=cost-tracker.d.ts.map

package/dist/ai/cost-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-tracker.d.ts","sourceRoot":"","sources":["../../src/ai/cost-tracker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAuBpF,qBAAa,WAAW;IAStB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAT3B,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,sBAAsB,CAAS;IACvC,OAAO,CAAC,cAAc,CAAS;gBAGb,MAAM,CAAC,EAAE,cAAc,YAAA,EACvB,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAM;IAOhE;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAY/E;;OAEG;IACH,MAAM,CACL,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,aAAa,SAAI,GACf,IAAI;IAyBP;;;;OAIG;IACH,WAAW,IAAI,IAAI;IA4CnB;;OAEG;IACH,UAAU,IAAI,aAAa;IAa3B;;OAEG;IACH,YAAY,IAAI,MAAM;CA4BtB"}

package/dist/ai/cost-tracker.js

@@ -0,0 +1,131 @@
+/**
+ * Cost Tracker
+ *
+ * Tracks token usage and estimated costs across AI steps within a recipe execution.
+ * Enforces budget limits and provides end-of-run summaries.
+ */
+import { ErrorCode, ErrorHandler } from "@hypercli/core";
+import createDebug from "debug";
+const debug = createDebug("hypergen:ai:cost-tracker");
+/**
+ * Default cost table for common models (USD per 1M tokens)
+ */
+const DEFAULT_COST_TABLE = {
+    "claude-sonnet-4-5": { inputPer1M: 3, outputPer1M: 15 },
+    "claude-haiku-3-5": { inputPer1M: 0.8, outputPer1M: 4 },
+    "gpt-4o": { inputPer1M: 2.5, outputPer1M: 10 },
+    "gpt-4o-mini": { inputPer1M: 0.15, outputPer1M: 0.6 },
+};
+export class CostTracker {
+    budget;
+    costTable;
+    steps = [];
+    totalInputTokens = 0;
+    totalOutputTokens = 0;
+    totalCostUsd = 0;
+    budgetWarningTriggered = false;
+    budgetLimitHit = false;
+    constructor(budget, costTable = {}) {
+        this.budget = budget;
+        this.costTable = costTable;
+        // Merge user cost table with defaults
+        this.costTable = { ...DEFAULT_COST_TABLE, ...costTable };
+        debug("CostTracker initialized with budget: %o", budget);
+    }
+    /**
+     * Calculate cost for a given token usage
+     */
+    calculateCost(model, inputTokens, outputTokens) {
+        const pricing = this.costTable[model];
+        if (!pricing) {
+            debug("No pricing found for model %s, cost will be 0", model);
+            return 0;
+        }
+        return ((inputTokens * pricing.inputPer1M) / 1_000_000 +
+            (outputTokens * pricing.outputPer1M) / 1_000_000);
+    }
+    /**
+     * Record token usage from an AI step
+     */
+    record(stepName, model, inputTokens, outputTokens, retryAttempts = 0) {
+        const costUsd = this.calculateCost(model, inputTokens, outputTokens);
+        this.steps.push({
+            stepName,
+            model,
+            inputTokens,
+            outputTokens,
+            costUsd,
+            retryAttempts,
+        });
+        this.totalInputTokens += inputTokens;
+        this.totalOutputTokens += outputTokens;
+        this.totalCostUsd += costUsd;
+        debug('Recorded step "%s": %d in + %d out = $%.4f (total: $%.4f)', stepName, inputTokens, outputTokens, costUsd, this.totalCostUsd);
+    }
+    /**
+     * Check if budget allows another AI call.
+     * Returns null if OK, or throws if hard limit exceeded.
+     * Logs warning if warn threshold crossed.
+     */
+    checkBudget() {
+        if (!this.budget)
+            return;
+        // Check token limit
+        if (this.budget.maxTotalTokens &&
+            this.totalInputTokens + this.totalOutputTokens >= this.budget.maxTotalTokens) {
+            this.budgetLimitHit = true;
+            throw ErrorHandler.createError(ErrorCode.AI_BUDGET_EXCEEDED, `Token budget exceeded: ${this.totalInputTokens + this.totalOutputTokens} tokens used, limit is ${this.budget.maxTotalTokens}`, {});
+        }
+        // Check cost limit
+        if (this.budget.maxTotalCostUsd && this.totalCostUsd >= this.budget.maxTotalCostUsd) {
+            this.budgetLimitHit = true;
+            throw ErrorHandler.createError(ErrorCode.AI_BUDGET_EXCEEDED, `Cost budget exceeded: $${this.totalCostUsd.toFixed(4)} spent, limit is $${this.budget.maxTotalCostUsd.toFixed(2)}`, {});
+        }
+        // Check warning threshold
+        if (this.budget.warnAtCostUsd &&
+            this.totalCostUsd >= this.budget.warnAtCostUsd &&
+            !this.budgetWarningTriggered) {
+            this.budgetWarningTriggered = true;
+            debug("Budget warning: $%.4f spent (threshold: $%.2f)", this.totalCostUsd, this.budget.warnAtCostUsd);
+            console.warn(`[hypergen:ai] Budget warning: $${this.totalCostUsd.toFixed(4)} spent of $${this.budget.maxTotalCostUsd?.toFixed(2) ?? "?"} limit`);
+        }
+    }
+    /**
+     * Get cost summary for the entire execution
+     */
+    getSummary() {
+        return {
+            totalInputTokens: this.totalInputTokens,
+            totalOutputTokens: this.totalOutputTokens,
+            totalTokens: this.totalInputTokens + this.totalOutputTokens,
+            totalCostUsd: this.totalCostUsd,
+            stepCount: this.steps.length,
+            steps: [...this.steps],
+            budgetWarningTriggered: this.budgetWarningTriggered,
+            budgetLimitHit: this.budgetLimitHit,
+        };
+    }
+    /**
+     * Format a human-readable cost report
+     */
+    formatReport() {
+        const lines = ["AI Cost Summary:", ""];
+        if (this.steps.length === 0) {
+            lines.push("  No AI steps executed.");
+            return lines.join("\n");
+        }
+        for (const step of this.steps) {
+            lines.push(`  ${step.stepName} (${step.model}): ${step.inputTokens} in + ${step.outputTokens} out = $${step.costUsd.toFixed(4)}${step.retryAttempts > 0 ? ` (${step.retryAttempts} retries)` : ""}`);
+        }
+        lines.push("");
+        lines.push(`  Total: ${this.totalInputTokens} in + ${this.totalOutputTokens} out = $${this.totalCostUsd.toFixed(4)}`);
+        if (this.budgetWarningTriggered) {
+            lines.push("  Warning: Budget warning threshold was triggered");
+        }
+        if (this.budgetLimitHit) {
+            lines.push("  Error: Budget limit was exceeded");
+        }
+        return lines.join("\n");
+    }
+}
+//# sourceMappingURL=cost-tracker.js.map

package/dist/ai/cost-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-tracker.js","sourceRoot":"","sources":["../../src/ai/cost-tracker.ts"],"names":[],"mappings":"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"}

package/dist/ai/env.d.ts

@@ -0,0 +1,36 @@
+/**
+ * AI Environment Variable Resolution
+ *
+ * Centralizes API key resolution from environment variables.
+ * Loads .env files via dotenvx on first use.
+ */
+/**
+ * Well-known environment variable names for each AI provider's API key.
+ * These match the defaults used by the Vercel AI SDK provider packages.
+ */
+export declare const PROVIDER_API_KEY_ENV_VARS: Record<string, string>;
+/** All well-known env var names (for auto-detection scans) */
+export declare const ALL_KNOWN_API_KEY_VARS: string[];
+/**
+ * Ensure .env files are loaded into process.env.
+ * Called lazily on first API key resolution.
+ */
+export declare function loadDotenv(): void;
+/**
+ * Resolve an API key from the environment.
+ *
+ * @param envVarName Explicit env var name from config (e.g. 'ANTHROPIC_API_KEY')
+ * @param provider   Provider name, used to infer default env var when envVarName is omitted
+ * @returns The API key string, or undefined if not found
+ */
+export declare function resolveApiKey(envVarName: string | undefined, provider: string): string | undefined;
+/**
+ * Get the env var name that would be used for a provider (for error messages).
+ */
+export declare function getExpectedEnvVar(envVarName: string | undefined, provider: string): string;
+/**
+ * Check if any API key is available for the given config, without loading it.
+ * Used by auto-detection in resolveTransport.
+ */
+export declare function hasApiKeyAvailable(envVarName: string | undefined, provider: string | undefined): boolean;
+//# sourceMappingURL=env.d.ts.map